diff --git a/docs/pt-BR/automation/tasks.md b/docs/pt-BR/automation/tasks.md index 64e644177..030a50f5a 100644 --- a/docs/pt-BR/automation/tasks.md +++ b/docs/pt-BR/automation/tasks.md @@ -1,16 +1,16 @@ --- read_when: - Inspecionando trabalhos em segundo plano em andamento ou concluídos recentemente - - Depuração de falhas de entrega em execuções de agente desanexadas - - Entendendo como as execuções em segundo plano se relacionam com sessões, Cron e Heartbeat + - Depuração de falhas de entrega em execuções de agentes desanexadas + - Entendendo como execuções em segundo plano se relacionam a sessões, Cron e Heartbeat sidebarTitle: Background tasks -summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, tarefas Cron isoladas e operações da CLI +summary: Rastreamento de tarefas em segundo plano para execuções de ACP, subagentes, trabalhos Cron isolados e operações da CLI title: Tarefas em segundo plano x-i18n: - generated_at: "2026-05-01T05:55:21Z" + generated_at: "2026-05-05T01:44:37Z" model: gpt-5.5 provider: openai - source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 + source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 source_path: automation/tasks.md workflow: 16 --- @@ -19,29 +19,29 @@ x-i18n: Procurando agendamento? Consulte [Automação e tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página é o registro de atividades do trabalho em segundo plano, não o agendador. -Tarefas em segundo plano rastreiam o trabalho executado **fora da sua sessão principal de conversa**: execuções ACP, criação de subagentes, execuções isoladas de tarefas Cron e operações iniciadas pela CLI. +Tarefas em segundo plano rastreiam trabalhos executados **fora da sua sessão principal de conversa**: execuções ACP, criação de subagentes, execuções isoladas de tarefas cron e operações iniciadas pela CLI. -Tarefas **não** substituem sessões, tarefas Cron nem Heartbeats — elas são o **registro de atividades** que registra qual trabalho destacado aconteceu, quando e se ele teve sucesso. +Tarefas **não** substituem sessões, tarefas cron ou heartbeats — elas são o **registro de atividades** que registra qual trabalho separado aconteceu, quando, e se foi bem-sucedido. -Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat interativo normal não criam. Todas as execuções Cron, criações ACP, criações de subagentes e comandos de agente pela CLI criam. +Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat interativo normal não criam. Todas as execuções cron, criações ACP, criações de subagentes e comandos de agente pela CLI criam. ## TL;DR -- Tarefas são **registros**, não agendadores — Cron e Heartbeat decidem _quando_ o trabalho é executado, tarefas rastreiam _o que aconteceu_. -- ACP, subagentes, todas as tarefas Cron e operações da CLI criam tarefas. Turnos de Heartbeat não criam. +- Tarefas são **registros**, não agendadores — cron e heartbeat decidem _quando_ o trabalho executa, tarefas rastreiam _o que aconteceu_. +- ACP, subagentes, todas as tarefas cron e operações da CLI criam tarefas. Turnos de Heartbeat não criam. - Cada tarefa passa por `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost). -- Tarefas Cron permanecem ativas enquanto o runtime Cron ainda controla o job; se o - estado do runtime em memória desapareceu, a manutenção de tarefas primeiro verifica o histórico durável de execuções Cron +- Tarefas cron permanecem ativas enquanto o runtime cron ainda é dono do job; se o + estado do runtime em memória se foi, a manutenção de tarefas primeiro verifica o histórico durável de execuções cron antes de marcar uma tarefa como perdida. -- A conclusão é orientada por push: trabalho destacado pode notificar diretamente ou acordar a - sessão/Heartbeat solicitante quando termina, então loops de sondagem de status +- A conclusão é orientada por push: trabalho separado pode notificar diretamente ou acordar a + sessão/heartbeat solicitante quando termina, então loops de consulta de status geralmente têm o formato errado. -- Execuções Cron isoladas e conclusões de subagentes fazem a melhor tentativa de limpar abas/processos de navegador rastreados para a sessão filha antes da escrituração final de limpeza. -- A entrega Cron isolada suprime respostas intermediárias obsoletas do pai enquanto trabalho de subagente descendente ainda está escoando, e prefere a saída final do descendente quando ela chega antes da entrega. -- Notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo Heartbeat. -- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` expõe problemas. +- Execuções cron isoladas e conclusões de subagentes tentam, em melhor esforço, limpar abas/processos de navegador rastreados para a sessão filha antes da escrituração final de limpeza. +- A entrega de cron isolado suprime respostas intermediárias obsoletas do pai enquanto o trabalho de subagentes descendentes ainda está sendo drenado, e prefere a saída final do descendente quando ela chega antes da entrega. +- Notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo heartbeat. +- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` destaca problemas. - Registros terminais são mantidos por 7 dias e depois removidos automaticamente. ## Início rápido @@ -97,28 +97,28 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera ## O que cria uma tarefa -| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política padrão de notificação | +| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| Execuções em segundo plano ACP | `acp` | Ao criar uma sessão ACP filha | `done_only` | +| Execuções ACP em segundo plano | `acp` | Ao criar uma sessão ACP filha | `done_only` | | Orquestração de subagentes | `subagent` | Ao criar um subagente via `sessions_spawn` | `done_only` | -| Tarefas Cron (todos os tipos) | `cron` | Toda execução Cron (sessão principal e isolada) | `silent` | -| Operações da CLI | `cli` | Comandos `openclaw agent` que executam pelo Gateway | `silent` | +| Tarefas cron (todos os tipos) | `cron` | A cada execução cron (sessão principal e isolada) | `silent` | +| Operações da CLI | `cli` | Comandos `openclaw agent` que executam pelo gateway | `silent` | | Jobs de mídia do agente | `cli` | Execuções `music_generate`/`video_generate` apoiadas por sessão | `silent` | - - 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. + + Tarefas cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam `silent` por padrão, mas são mais visíveis porque executam em sua própria sessão. - Execuções `music_generate` e `video_generate` apoiadas por sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um despertar interno para que o agente possa escrever a mensagem de acompanhamento e anexar a mídia finalizada por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `video_generate` podem tentar primeiro a entrega direta no canal; conclusões assíncronas de `music_generate` permanecem no caminho de despertar da sessão solicitante. + Execuções `music_generate` e `video_generate` apoiadas por sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um acionamento interno para que o agente possa escrever a mensagem de acompanhamento e anexar a mídia finalizada por conta própria. Conclusões em grupo/canal seguem a política normal de resposta visível, então o agente usa a ferramenta de mensagem quando a entrega de origem exige isso. - - 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. + + Enquanto uma tarefa `video_generate` apoiada por sessão ainda está ativa, a ferramenta também atua como uma proteção: chamadas repetidas a `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status pelo lado do agente. - Turnos de Heartbeat — sessão principal; consulte [Heartbeat](/pt-BR/gateway/heartbeat) - - Turnos de chat interativo normal - - Respostas diretas de `/command` + - Turnos normais de chat interativo + - Respostas diretas a `/command` @@ -137,55 +137,55 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| Status | O que significa | +| Status | O que significa | | ----------- | -------------------------------------------------------------------------- | -| `queued` | Criada, aguardando o agente iniciar | -| `running` | O turno do agente está executando ativamente | -| `succeeded` | Concluída com sucesso | +| `queued` | Criada, aguardando o agente iniciar | +| `running` | O turno do agente está executando ativamente | +| `succeeded` | Concluída com sucesso | | `failed` | Concluída com erro | -| `timed_out` | Excedeu o timeout configurado | -| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` | -| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de tolerância de 5 minutos | +| `timed_out` | Excedeu o tempo limite configurado | +| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` | +| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de carência de 5 minutos | As transições acontecem automaticamente — quando a execução de agente associada termina, o status da tarefa é atualizado para corresponder. -A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução destacada bem-sucedida finaliza como `succeeded`, erros comuns de execução finalizam como `failed`, e resultados de timeout ou abortamento finalizam como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como `failed`, `timed_out` ou `lost`, um sinal posterior de sucesso não rebaixa esse status terminal. +A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução separada bem-sucedida finaliza como `succeeded`, erros comuns de execução finalizam como `failed`, e resultados de timeout ou abortamento finalizam como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como `failed`, `timed_out` ou `lost`, um sinal posterior de sucesso não rebaixa esse status terminal. `lost` é ciente do runtime: - Tarefas ACP: os metadados da sessão ACP filha de apoio desapareceram. - Tarefas de subagente: a sessão filha de apoio desapareceu do armazenamento do agente de destino. -- Tarefas Cron: o runtime Cron não rastreia mais o job como ativo e o histórico durável de execuções Cron - não mostra um resultado terminal para essa execução. A auditoria offline da CLI - não trata seu próprio estado vazio de runtime Cron em processo como autoridade. -- Tarefas CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas CLI - apoiadas por chat usam o contexto de execução ao vivo, então linhas persistentes - de sessão de canal/grupo/direta não as mantêm vivas. Execuções - `openclaw agent` apoiadas pelo Gateway também finalizam pelo resultado da execução, então execuções concluídas - não ficam ativas até que o varredor as marque como `lost`. +- Tarefas cron: o runtime cron não rastreia mais o job como ativo e o histórico durável + de execuções cron não mostra um resultado terminal para essa execução. A auditoria offline da CLI + não trata seu próprio estado vazio de runtime cron em processo como autoridade. +- Tarefas da CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas da CLI + apoiadas por chat usam o contexto de execução ativo, então linhas persistentes de sessão + de canal/grupo/direta não as mantêm vivas. Execuções `openclaw agent` apoiadas pelo Gateway + também finalizam a partir do resultado da execução, então execuções concluídas + não ficam ativas até o varredor marcá-las como `lost`. ## Entrega e notificações -Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega: +Quando uma tarefa alcança um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega: -**Entrega direta** — se a tarefa tem um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai direto para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagente, o OpenClaw também preserva o roteamento de thread/tópico vinculado quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta. +**Entrega direta** — se a tarefa tem um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai diretamente para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagentes, o OpenClaw também preserva o roteamento de thread/tópico vinculado quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta. -**Entrega enfileirada na sessão** — se a entrega direta falha ou nenhuma origem está definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo Heartbeat. +**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo heartbeat. -A conclusão da tarefa aciona um despertar imediato do Heartbeat para que você veja o resultado rapidamente — você não precisa esperar pelo próximo tick de Heartbeat agendado. +A conclusão de tarefa aciona um acionamento imediato de heartbeat para que você veja o resultado rapidamente — você não precisa esperar o próximo tique de heartbeat agendado. -Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho destacado uma vez e depois deixe o runtime acordar ou notificar você na conclusão. Sonde o estado da tarefa somente quando precisar de depuração, intervenção ou uma auditoria explícita. +Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho separado uma vez e deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa somente quando precisar depurar, intervir ou fazer uma auditoria explícita. ### Políticas de notificação Controle quanto você ouve sobre cada tarefa: -| Política | O que é entregue | +| Política | O que é entregue | | --------------------- | ----------------------------------------------------------------------- | | `done_only` (padrão) | Somente estado terminal (succeeded, failed etc.) — **este é o padrão** | -| `state_changes` | Toda transição de estado e atualização de progresso | +| `state_changes` | Toda transição de estado e atualização de progresso | | `silent` | Nada | Altere a política enquanto uma tarefa está em execução: @@ -218,7 +218,7 @@ openclaw tasks notify 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á handle separado de runtime filho). O status transita para `cancelled` e uma notificação de entrega é enviada quando aplicável. + Para tarefas ACP e de subagente, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há identificador de runtime filho separado). O status transiciona para `cancelled` e uma notificação de entrega é enviada quando aplicável. @@ -231,16 +231,16 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - Expõe problemas operacionais. Constatações também aparecem em `openclaw status` quando problemas são detectados. + Destaca problemas operacionais. Achados também aparecem em `openclaw status` quando problemas são detectados. - | Constatação | Severidade | Acionador | - | ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- | - | `stale_queued` | warn | Em fila por mais de 10 minutos | - | `stale_running` | error | Em execução por mais de 30 minutos | - | `lost` | warn/error | A propriedade da tarefa respaldada por runtime desapareceu; tarefas perdidas retidas emitem aviso até `cleanupAfter`, depois viram erros | - | `delivery_failed` | warn | A entrega falhou e a política de notificação não é `silent` | - | `missing_cleanup` | warn | Tarefa terminal sem timestamp de limpeza | - | `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de começar) | + | Descoberta | Severidade | Gatilho | + | ------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | + | `stale_queued` | warn | Na fila há mais de 10 minutos | + | `stale_running` | error | Em execução há mais de 30 minutos | + | `lost` | warn/error | A propriedade da tarefa apoiada pelo runtime desapareceu; tarefas perdidas retidas avisam até `cleanupAfter`, depois viram erros | + | `delivery_failed` | warn | A entrega falhou e a política de notificação não é `silent` | + | `missing_cleanup` | warn | Tarefa terminal sem timestamp de limpeza | + | `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de começar) | @@ -249,21 +249,21 @@ openclaw tasks notify state_changes openclaw tasks maintenance --apply [--json] ``` - Use isto para visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e estado do TaskFlow. + Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e o estado do Task Flow. - A reconciliação é ciente de runtime: + A reconciliação é ciente do runtime: - - Tarefas ACP/subagente verificam sua sessão filha de apoio. + - Tarefas de ACP/subagente verificam sua sessão filha de apoio. - Tarefas de subagente cuja sessão filha tem uma lápide de recuperação de reinicialização são marcadas como perdidas em vez de serem tratadas como sessões de apoio recuperáveis. - - Tarefas Cron verificam se o runtime do cron ainda possui o job, depois recuperam o status terminal de logs de execução de cron/estado de job persistidos antes de recorrer a `lost`. Apenas o processo Gateway é autoritativo para o conjunto de jobs ativos de cron em memória; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa de cron como perdida somente porque esse Set local está vazio. - - Tarefas da CLI respaldadas por chat verificam o contexto de execução ao vivo proprietário, não apenas a linha da sessão de chat. + - Tarefas de Cron verificam se o runtime de cron ainda possui o trabalho, depois recuperam o status terminal de logs de execução cron/estado de trabalho persistidos antes de recorrer a `lost`. Somente o processo Gateway é autoritativo para o conjunto em memória de trabalhos ativos de cron; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa cron como perdida apenas porque esse Set local está vazio. + - Tarefas da CLI apoiadas por chat verificam o contexto de execução ao vivo proprietário, não apenas a linha da sessão de chat. - A limpeza de conclusão também é ciente de runtime: + A limpeza de conclusão também é ciente do runtime: - - A conclusão de subagente tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão filha antes que a limpeza de anúncio continue. - - A conclusão de cron isolado tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão de cron antes que a execução seja totalmente encerrada. - - A entrega de cron isolado aguarda acompanhamento de subagente descendente quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo. - - A entrega de conclusão de subagente prefere o texto de assistente visível mais recente; se ele estiver vazio, recorre ao texto sanitizado mais recente de tool/toolResult, e execuções de chamadas de ferramenta apenas por timeout podem ser reduzidas a um breve resumo de progresso parcial. Execuções terminais com falha anunciam o status de falha sem repetir o texto de resposta capturado. + - A conclusão de subagente fecha, por melhor esforço, abas/processos de navegador rastreados para a sessão filha antes de a limpeza de anúncio continuar. + - A conclusão de cron isolado fecha, por melhor esforço, abas/processos de navegador rastreados para a sessão cron antes de a execução ser totalmente desmontada. + - A entrega de cron isolado aguarda o acompanhamento de subagente descendente quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo. + - A entrega de conclusão de subagente prefere o texto de assistente visível mais recente; se estiver vazio, recorre ao texto mais recente higienizado de ferramenta/toolResult, e execuções de chamadas de ferramenta apenas por timeout podem ser reduzidas a um breve resumo de progresso parcial. Execuções terminais com falha anunciam o status de falha sem reproduzir o texto de resposta capturado. - Falhas de limpeza não mascaram o resultado real da tarefa. @@ -274,65 +274,65 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - Use estes quando o TaskFlow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano. + Use estes quando o Task Flow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano. ## Quadro de tarefas do chat (`/tasks`) -Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O quadro mostra tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro. +Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O quadro mostra tarefas ativas e concluídas recentemente com runtime, status, temporização e detalhes de progresso ou erro. -Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre às contagens de tarefas locais do agente, para que você ainda tenha uma visão geral sem vazar detalhes de outras sessões. +Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente, para que você ainda tenha uma visão geral sem vazar detalhes de outras sessões. -Para o livro-razão completo do operador, use a CLI: `openclaw tasks list`. +Para o registro completo do operador, use a CLI: `openclaw tasks list`. ## Integração de status (pressão de tarefas) -`openclaw status` inclui um resumo rápido de tarefas: +`openclaw status` inclui um resumo de tarefas em uma olhada: ``` Tasks: 3 queued · 2 running · 1 issues ``` -O resumo informa: +O resumo relata: - **active** — contagem de `queued` + `running` - **failures** — contagem de `failed` + `timed_out` + `lost` - **byRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli` -Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas ciente de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas são ocultadas e falhas recentes só aparecem quando nenhum trabalho ativo permanece. Isso mantém o cartão de status focado no que importa agora. +Tanto `/status` quanto a ferramenta `session_status` usam um instantâneo de tarefas ciente de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas ficam ocultas, e falhas recentes só aparecem quando não resta nenhum trabalho ativo. Isso mantém o cartão de status focado no que importa agora. ## Armazenamento e manutenção ### Onde as tarefas ficam -Registros de tarefas persistem no SQLite em: +Registros de tarefa persistem no SQLite em: ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -O registro é carregado na memória na inicialização do Gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações. -O Gateway mantém o log de gravação antecipada do SQLite limitado usando o limite padrão de +O registro é carregado na memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações. +O Gateway mantém o log write-ahead do SQLite limitado usando o limite padrão de autocheckpoint do SQLite mais checkpoints `TRUNCATE` periódicos e no desligamento. ### Manutenção automática -Um varredor é executado a cada **60 segundos** e cuida de quatro coisas: +Um varredor roda a cada **60 segundos** e cuida de quatro coisas: - Verifica se tarefas ativas ainda têm respaldo autoritativo de runtime. Tarefas ACP/subagente usam o estado da sessão filha, tarefas de cron usam a propriedade de jobs ativos, e tarefas da CLI respaldadas por chat usam o contexto de execução proprietário. Se esse estado de apoio desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`. + Verifica se tarefas ativas ainda têm apoio autoritativo de runtime. Tarefas de ACP/subagente usam o estado da sessão filha, tarefas de cron usam a propriedade do trabalho ativo, e tarefas da CLI apoiadas por chat usam o contexto de execução proprietário. Se esse estado de apoio desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`. - Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs somente quando não resta nenhum vínculo de conversa ativo. + Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs apenas quando não resta nenhuma vinculação de conversa ativa. 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`. + Exclui registros após a data `cleanupAfter`. @@ -343,36 +343,36 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas: ## Como as tarefas se relacionam com outros sistemas - - [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. + + [Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxo acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefa e `openclaw tasks flow` para inspecionar o fluxo orquestrador. - Consulte [TaskFlow](/pt-BR/automation/taskflow) para detalhes. + Consulte [Task Flow](/pt-BR/automation/taskflow) para obter detalhes. - Uma **definição** de job de cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução em runtime fica ao lado dela em `~/.openclaw/cron/jobs-state.json`. **Toda** execução de cron cria um registro de tarefa — tanto de sessão principal quanto isolada. Tarefas de cron de sessão principal usam por padrão a política de notificação `silent`, de modo que são rastreadas sem gerar notificações. + Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução do runtime fica ao lado dela em `~/.openclaw/cron/jobs-state.json`. **Toda** execução de cron cria um registro de tarefa — tanto de sessão principal quanto isolada. Tarefas cron de sessão principal usam a política de notificação `silent` por padrão, para que sejam rastreadas sem gerar notificações. - Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). + Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs). - - 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. + + Execuções de Heartbeat são turnos de sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode disparar um despertar de Heartbeat para que você veja o resultado prontamente. Consulte [Heartbeat](/pt-BR/gateway/heartbeat). - Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade sobre isso. + Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade por cima disso. - O `runId` de uma tarefa aponta para a execução do agente que realiza o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa — você não precisa gerenciar o ciclo de vida manualmente. + O `runId` de uma tarefa vincula à execução de agente que faz o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa — você não precisa gerenciar o ciclo de vida manualmente. -## Relacionados +## Relacionado -- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo +- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em uma olhada - [CLI: Tarefas](/pt-BR/cli/tasks) — referência de comandos da CLI - [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos de sessão principal - [Tarefas agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano -- [TaskFlow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas +- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas diff --git a/docs/pt-BR/channels/slack.md b/docs/pt-BR/channels/slack.md index b3df54ea8..36530303b 100644 --- a/docs/pt-BR/channels/slack.md +++ b/docs/pt-BR/channels/slack.md @@ -1,47 +1,204 @@ --- read_when: - Configurando o Slack ou depurando o modo socket/HTTP do Slack -summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de requisição HTTP) +summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de solicitação HTTP) title: Slack x-i18n: - generated_at: "2026-05-04T07:02:49Z" + generated_at: "2026-05-05T01:44:18Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 9a8e1cbfd3d99bfc24d79b56ee762d1ab399402391b241ff40698249b0828008 source_path: channels/slack.md workflow: 16 --- -Pronto para produção para DMs e canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de requisição HTTP também são compatíveis. +Pronto para produção em DMs e canais via integrações de app Slack. O modo padrão é Socket Mode; HTTP Request URLs também são compatíveis. - - DMs do Slack usam o modo de pareamento por padrão. + + DMs do Slack usam o modo de emparelhamento por padrão. - - Comportamento nativo de comandos e catálogo de comandos. + + Comportamento de comandos nativos e catálogo de comandos. Diagnósticos entre canais e playbooks de reparo. +## Escolhendo Socket Mode ou HTTP Request URLs + +Ambos os transportes estão prontos para produção e alcançam paridade de recursos para mensagens, comandos de barra, App Home e interatividade. Escolha pelo formato da implantação, não pelos recursos. + +| Preocupação | Socket Mode (padrão) | HTTP Request URLs | +| --------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| URL pública do Gateway | Não necessária | Necessária (DNS, TLS, proxy reverso ou túnel) | +| Rede de saída | WSS de saída para `wss-primary.slack.com` deve estar acessível | Sem WS de saída; apenas HTTPS de entrada | +| Tokens necessários | Token do bot (`xoxb-...`) + Token de Nível de App (`xapp-...`) com `connections:write` | Token do bot (`xoxb-...`) + Signing Secret | +| Notebook de dev / atrás de firewall | Funciona como está | Precisa de um túnel público (ngrok, Cloudflare Tunnel, Tailscale Funnel) ou Gateway de staging | +| Escalabilidade horizontal | Uma sessão Socket Mode por app por host; múltiplos Gateways precisam de apps Slack separados | Manipulador POST sem estado; várias réplicas do Gateway podem compartilhar um app atrás de um balanceador de carga | +| Múltiplas contas em um Gateway | Compatível; cada conta abre seu próprio WS | Compatível; cada conta precisa de um `webhookPath` único (padrão `/slack/events`) para que os registros não colidam | +| Transporte de comando de barra | Entregue pela conexão WS; `slash_commands[].url` é ignorado | Slack envia POST para `slash_commands[].url`; o campo é obrigatório para o comando ser despachado | +| Assinatura de requisições | Não usada (a autenticação é o Token de Nível de App) | Slack assina toda requisição; OpenClaw verifica com `signingSecret` | +| Recuperação em queda de conexão | Slack SDK reconecta automaticamente; o ajuste de transporte de pong-timeout do gateway se aplica | Nenhuma conexão persistente para cair; novas tentativas são por requisição a partir do Slack | + + + **Escolha Socket Mode** para hosts com um único Gateway, notebooks de dev e redes on-prem que conseguem alcançar `*.slack.com` como saída, mas não conseguem aceitar HTTPS de entrada. + +**Escolha HTTP Request URLs** ao executar várias réplicas do Gateway atrás de um balanceador de carga, quando WSS de saída está bloqueado, mas HTTPS de entrada é permitido, ou quando você já encerra webhooks do Slack em um proxy reverso. + + ## Configuração rápida - - Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: + + Abra [api.slack.com/apps](https://api.slack.com/apps/new) → **Criar Novo App** → **A partir de um manifesto** → selecione seu workspace → cole um dos manifestos abaixo → **Avançar** → **Criar**. - - escolha **from a manifest** e selecione um workspace para seu app - - cole o [manifesto de exemplo](#manifest-and-scope-checklist) abaixo e continue para criar - - gere um **Token em nível de app** (`xapp-...`) com `connections:write` - - instale o app e copie o **Token do bot** (`xoxb-...`) exibido + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **Recomendado** corresponde ao conjunto completo de recursos do plugin Slack incluído: App Home, comandos de barra, arquivos, reações, pins, DMs de grupo e leituras de emojis/grupos de usuários. Escolha **Mínimo** quando a política do workspace restringir escopos — ele cobre DMs, histórico de canais/grupos, menções e comandos de barra, mas remove arquivos, reações, pins, DMs de grupo (`mpim:*`), `emoji:read` e `usergroups:read`. Consulte a [Lista de verificação de manifesto e escopos](#manifest-and-scope-checklist) para a justificativa por escopo e opções aditivas, como comandos de barra extras. + + + Depois que o Slack criar o app: + + - **Informações Básicas → Tokens de Nível de App → Gerar Token e Escopos**: adicione `connections:write`, salve, copie o valor `xapp-...`. + - **Instalar App → Instalar no Workspace**: copie o Token OAuth de Usuário Bot `xoxb-...`. - + Configuração SecretRef recomendada: @@ -64,7 +221,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - Fallback de env (somente conta padrão): + Fallback de env (apenas conta padrão): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +230,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,21 +241,172 @@ openclaw gateway - + - - Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: + + Abra [api.slack.com/apps](https://api.slack.com/apps/new) → **Criar Novo App** → **A partir de um manifesto** → selecione seu workspace → cole um dos manifestos abaixo → substitua `https://gateway-host.example.com/slack/events` pela URL pública do seu Gateway → **Avançar** → **Criar**. - - escolha **from a manifest** e selecione um workspace para seu app - - cole o [manifesto de exemplo](#manifest-and-scope-checklist) e atualize as URLs antes de criar - - salve o **Segredo de assinatura** para verificação de requisições - - instale o app e copie o **Token do bot** (`xoxb-...`) exibido + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **Recomendado** corresponde ao conjunto completo de recursos do Plugin Slack incluído; **Mínimo** remove arquivos, reações, pins, DM de grupo (`mpim:*`), `emoji:read` e `usergroups:read` para workspaces restritivos. Veja o [Checklist de manifesto e escopos](#manifest-and-scope-checklist) para a justificativa por escopo. + + + + Os três campos de URL (`slash_commands[].url`, `event_subscriptions.request_url` e `interactivity.request_url` / `message_menu_options_url`) apontam todos para o mesmo endpoint do OpenClaw. O esquema de manifesto do Slack exige que eles tenham nomes separados, mas o OpenClaw roteia por tipo de payload, então um único `webhookPath` (padrão `/slack/events`) é suficiente. Comandos slash sem `slash_commands[].url` não farão nada silenciosamente no modo HTTP. + + + Depois que o Slack criar o app: + + - **Informações básicas → Credenciais do app**: copie o **Segredo de assinatura** para verificação de solicitações. + - **Instalar app → Instalar no workspace**: copie o Token OAuth de usuário bot `xoxb-...`. - + - Configuração SecretRef recomendada: + Configuração recomendada de SecretRef: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,14 +429,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Use caminhos de Webhook exclusivos para HTTP com várias contas + Use caminhos de Webhook únicos para HTTP com várias contas - Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito. + Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não colidam. - + ```bash openclaw gateway @@ -142,7 +450,7 @@ openclaw gateway ## Ajuste de transporte do Socket Mode -O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segundos por padrão para Socket Mode. Substitua as configurações de transporte somente quando precisar de ajuste específico para workspace ou host: +O OpenClaw define, por padrão, o timeout de pong do cliente do SDK do Slack como 15 segundos para Socket Mode. Sobrescreva as configurações de transporte somente quando precisar de ajustes específicos para workspace ou host: ```json5 { @@ -159,13 +467,13 @@ O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segu } ``` -Use isto somente para workspaces em Socket Mode que registrem timeouts de pong/websocket ou server-ping do Slack, ou que rodem em hosts com starvation conhecida do loop de eventos. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping do cliente; `serverPingTimeout` é a espera por pings do servidor do Slack. Mensagens e eventos do app continuam sendo estado da aplicação, não sinais de vivacidade do transporte. +Use isto apenas para workspaces em Socket Mode que registrem timeouts de pong/server-ping do websocket do Slack ou sejam executados em hosts com starvation conhecida do loop de eventos. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping de cliente; `serverPingTimeout` é a espera por pings do servidor Slack. Mensagens e eventos do app continuam sendo estado da aplicação, não sinais de vivacidade do transporte. ## Checklist de manifesto e escopos -O manifesto base do app do Slack é o mesmo para Socket Mode e URLs de requisição HTTP. Somente o bloco `settings` (e a `url` do comando slash) difere. +O manifesto base do app Slack é o mesmo para Socket Mode e URLs de solicitação HTTP. Somente o bloco `settings` (e o `url` do comando slash) é diferente. -Manifesto base (Socket Mode padrão): +Manifesto base (padrão do Socket Mode): ```json { @@ -240,7 +548,7 @@ Manifesto base (Socket Mode padrão): } ``` -Para o **modo de URLs de requisição HTTP**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória: +Para o **modo de URLs de solicitação HTTP**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória: ```json { @@ -284,19 +592,19 @@ Para o **modo de URLs de requisição HTTP**, substitua `settings` pela variante ### Configurações adicionais do manifesto -Exponha recursos diferentes que ampliam os padrões acima. +Exponha diferentes recursos que ampliam os padrões acima. -O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home_opened`. Quando um membro do workspace abre a aba Home, o OpenClaw publica uma visualização Home padrão segura com `views.publish`; nenhum payload de conversa nem configuração privada é incluído. A aba **Messages** continua habilitada para DMs do Slack. +O manifesto padrão habilita a guia **Início** do Slack App Home e assina `app_home_opened`. Quando um membro do workspace abre a guia Início, o OpenClaw publica uma visualização Início padrão segura com `views.publish`; nenhum payload de conversa nem configuração privada é incluído. A guia **Mensagens** permanece habilitada para mensagens diretas do Slack. - Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com nuances: + Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados no lugar de um único comando configurado, com algumas nuances: - Use `/agentstatus` em vez de `/status` porque o comando `/status` é reservado. - - Não mais que 25 comandos slash podem ser disponibilizados de uma vez. + - No máximo 25 comandos slash podem ser disponibilizados de uma vez. - Substitua sua seção `features.slash_commands` existente por um subconjunto dos [comandos disponíveis](/pt-BR/tools/slash-commands#command-list): + Substitua a seção `features.slash_commands` existente por um subconjunto de [comandos disponíveis](/pt-BR/tools/slash-commands#command-list): @@ -422,7 +730,7 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home ``` - + Use a mesma lista `slash_commands` do Socket Mode acima e adicione `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Exemplo: ```json @@ -449,10 +757,10 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home - + Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens enviadas usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app Slack. - Se você usar um ícone de emoji, o Slack espera a sintaxe `:emoji_name:`. + Se você usar um ícone de emoji, Slack espera a sintaxe `:emoji_name:`. @@ -472,33 +780,33 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home ## Modelo de token - `botToken` + `appToken` são obrigatórios para Socket Mode. -- O modo HTTP exige `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples +- O modo HTTP requer `botToken` + `signingSecret`. +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto claro ou objetos SecretRef. - Tokens de configuração substituem o fallback de env. - O fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão. -- `userToken` (`xoxp-...`) é apenas de configuração (sem fallback de env) e usa por padrão comportamento somente leitura (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) é somente configuração (sem fallback de env) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`). Comportamento do instantâneo de status: -- A inspeção de conta do Slack rastreia campos `*Source` e `*Status` +- A inspeção de contas do Slack rastreia campos `*Source` e `*Status` por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`). - O status é `available`, `configured_unavailable` ou `missing`. -- `configured_unavailable` significa que a conta está configurada por SecretRef - ou outra fonte de segredo não embutida, mas o comando/caminho de runtime atual +- `configured_unavailable` significa que a conta está configurada por meio de SecretRef + ou outra fonte de segredo não embutida, mas o caminho atual de comando/runtime não conseguiu resolver o valor real. -- No modo HTTP, `signingSecretStatus` é incluído; no Socket Mode, o - par obrigatório é `botTokenStatus` + `appTokenStatus`. +- No modo HTTP, `signingSecretStatus` é incluído; no Socket Mode, o par + obrigatório é `botTokenStatus` + `appTokenStatus`. -Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot está indisponível. +Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para gravações, o token de bot continua sendo preferido; gravações com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot está indisponível. ## Ações e gates As ações do Slack são controladas por `channels.slack.actions.*`. -Grupos de ações disponíveis nas ferramentas atuais do Slack: +Grupos de ações disponíveis no ferramental atual do Slack: | Grupo | Padrão | | ---------- | ------- | @@ -508,7 +816,7 @@ Grupos de ações disponíveis nas ferramentas atuais do Slack: | memberInfo | habilitado | | emojiList | habilitado | -As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo do Slack mostrados nos placeholders de arquivos recebidos e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo. +As ações de mensagem atuais do Slack incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo do Slack mostrados em placeholders de arquivos recebidos e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo. ## Controle de acesso e roteamento @@ -518,7 +826,7 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `pairing` (padrão) - `allowlist` - - `open` (exige que `channels.slack.allowFrom` inclua `"*"`) + - `open` (requer que `channels.slack.allowFrom` inclua `"*"`) - `disabled` Flags de DM: @@ -526,22 +834,22 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `dm.enabled` (padrão true) - `channels.slack.allowFrom` - `dm.allowFrom` (legado) - - `dm.groupEnabled` (DMs em grupo padrão false) + - `dm.groupEnabled` (DMs de grupo usam false por padrão) - `dm.groupChannels` (lista de permissões MPIM opcional) - Precedência de várias contas: + Precedência em várias contas: - `channels.slack.accounts.default.allowFrom` se aplica apenas à conta `default`. - Contas nomeadas herdam `channels.slack.allowFrom` quando seu próprio `allowFrom` não está definido. - Contas nomeadas não herdam `channels.slack.accounts.default.allowFrom`. - `channels.slack.dm.policy` e `channels.slack.dm.allowFrom` legados ainda são lidos por compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando consegue fazer isso sem alterar o acesso. + `channels.slack.dm.policy` e `channels.slack.dm.allowFrom` legados ainda são lidos para compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando consegue fazer isso sem alterar o acesso. - O emparelhamento em DMs usa `openclaw pairing approve slack `. + O pareamento em DMs usa `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` controla o tratamento de canais: - `open` @@ -550,18 +858,18 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- A lista de permissões de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal do Slack** (por exemplo, `C12345678`) como chaves de configuração. - Observação de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime faz fallback para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). + Observação de runtime: se `channels.slack` estiver completamente ausente (configuração apenas por env), o runtime usa como fallback `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). Resolução de nome/ID: - entradas da lista de permissões de canais e entradas da lista de permissões de DM são resolvidas na inicialização quando o acesso por token permite - entradas de nome de canal não resolvidas são mantidas como configuradas, mas ignoradas para roteamento por padrão - - autorização de entrada e roteamento de canal são ID-first por padrão; correspondência direta de nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` + - autorização de entrada e roteamento de canais usam ID primeiro por padrão; correspondência direta de nome de usuário/slug requer `channels.slack.dangerouslyAllowNameMatching: true` - Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem sob `groupPolicy: "allowlist"`. A busca de canal é ID-first por padrão, então uma chave baseada em nome nunca será roteada com sucesso e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave de canal não é obrigatória para roteamento e uma chave baseada em nome parece funcionar. + Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de canais usa ID primeiro por padrão, então uma chave baseada em nome nunca será roteada com sucesso e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave do canal não é obrigatória para roteamento e uma chave baseada em nome parece funcionar. - Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no final da URL. + Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no fim da URL. Correto: @@ -597,16 +905,16 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - Mensagens de canal são controladas por menções por padrão. + As mensagens de canal são controladas por menções por padrão. Fontes de menção: - menção explícita ao app (`<@botId>`) - menção a grupo de usuários do Slack (``) quando o usuário bot é membro desse grupo de usuários; requer `usergroups:read` - - padrões regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - comportamento implícito de resposta para thread do bot (desativado quando `thread.requireExplicitMention` é `true`) + - padrões de regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - comportamento implícito de thread em resposta ao bot (desativado quando `thread.requireExplicitMention` é `true`) - Controles por canal (`channels.slack.channels.`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`): + Controles por canal (`channels.slack.channels.`; nomes apenas via resolução na inicialização ou `dangerouslyAllowNameMatching`): - `requireMention` - `users` (lista de permissões) @@ -615,9 +923,9 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `systemPrompt` - `tools`, `toolsBySender` - formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, ou curinga `"*"` - (chaves legadas sem prefixo ainda mapeiam somente para `id:`) + (chaves legadas sem prefixo ainda mapeiam apenas para `id:`) - `allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bot são aceitas somente quando o bot remetente está listado explicitamente na lista de permissões `users` dessa sala, ou quando pelo menos um ID explícito de proprietário do Slack de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; certifique-se de que o app tenha o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a consulta de membros falhar, o OpenClaw descarta a mensagem de sala criada por bot. + `allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bot são aceitas apenas quando o bot remetente está explicitamente listado na lista de permissões `users` dessa sala, ou quando pelo menos um ID explícito de proprietário do Slack de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; certifique-se de que o app tenha o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a consulta de membros falhar, o OpenClaw descarta a mensagem de sala criada por bot. @@ -625,27 +933,27 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- ## Threads, sessões e tags de resposta - DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`. -- Associações de rota do Slack aceitam IDs brutos de par, além de formas de destino do Slack como `channel:C12345678`, `user:U12345678` e `<@U12345678>`. -- Com o padrão `session.dmScope=main`, DMs do Slack são agrupadas na sessão principal do agente. +- Vinculações de rota do Slack aceitam IDs brutos de pares mais formas de destino do Slack, como `channel:C12345678`, `user:U12345678` e `<@U12345678>`. +- Com `session.dmScope=main` padrão, DMs do Slack são agrupadas na sessão principal do agente. - Sessões de canal: `agent::slack:channel:`. -- Respostas em thread podem criar sufixos de sessão de thread (`:thread:`) quando aplicável. +- Respostas em threads podem criar sufixos de sessão de thread (`:thread:`) quando aplicável. - O padrão de `channels.slack.thread.historyScope` é `thread`; o padrão de `thread.inheritParent` é `false`. - `channels.slack.thread.initialHistoryLimit` controla quantas mensagens existentes da thread são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desativar). -- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda somente a menções explícitas `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot ignoram o controle de `requireMention`. +- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em threads para que o bot responda apenas a menções explícitas a `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot ignoram o controle de `requireMention`. -Controles de threading de resposta: +Controles de encadeamento de respostas: - `channels.slack.replyToMode`: `off|first|all|batched` (padrão `off`) - `channels.slack.replyToModeByChatType`: por `direct|group|channel` -- fallback legado para chats diretos: `channels.slack.dm.replyToMode` +- fallback legado para conversas diretas: `channels.slack.dm.replyToMode` -Tags manuais de resposta são compatíveis: +Tags de resposta manuais são compatíveis: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` desativa **todo** o threading de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis em linha. +`replyToMode="off"` desativa **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, onde tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram continuam visíveis em linha. ## Reações de confirmação @@ -657,7 +965,7 @@ Ordem de resolução: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") +- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`; caso contrário, "👀") Observações: @@ -668,14 +976,14 @@ Observações: `channels.slack.streaming` controla o comportamento de pré-visualização ao vivo: -- `off`: desativa streaming de pré-visualização ao vivo. +- `off`: desativa o streaming de pré-visualização ao vivo. - `partial` (padrão): substitui o texto de pré-visualização pela saída parcial mais recente. -- `block`: acrescenta atualizações de pré-visualização em blocos. +- `block`: acrescenta atualizações de pré-visualização em partes. - `progress`: mostra texto de status de progresso durante a geração e depois envia o texto final. -- `streaming.preview.toolProgress`: quando a pré-visualização de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de pré-visualização editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso. +- `streaming.preview.toolProgress`: quando a pré-visualização de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de pré-visualização editada (padrão: `true`). Defina como `false` para manter mensagens separadas de ferramenta/progresso. - `streaming.preview.commandText` / `streaming.progress.commandText`: defina como `status` para manter linhas compactas de progresso de ferramenta enquanto oculta texto bruto de comando/execução (padrão: `raw`). -Oculte texto bruto de comando/execução enquanto mantém linhas compactas de progresso: +Ocultar texto bruto de comando/execução enquanto mantém linhas compactas de progresso: ```json { @@ -695,14 +1003,14 @@ Oculte texto bruto de comando/execução enquanto mantém linhas compactas de pr `channels.slack.streaming.nativeTransport` controla o streaming de texto nativo do Slack quando `channels.slack.streaming.mode` é `partial` (padrão: `true`). -- Uma thread de resposta precisa estar disponível para que o streaming de texto nativo e o status de thread de assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`. -- Raízes de canal, chat em grupo e DM de nível superior ainda podem usar a pré-visualização normal de rascunho quando o streaming nativo está indisponível ou nenhuma thread de resposta existe. -- DMs de nível superior do Slack ficam fora de thread por padrão, então não exibem a pré-visualização de stream/status nativo em estilo de thread do Slack; em vez disso, o OpenClaw publica e edita uma pré-visualização de rascunho na DM. -- Mídia e payloads não textuais recorrem à entrega normal. -- Finais de mídia/erro cancelam edições pendentes de pré-visualização; finais de texto/bloco elegíveis são descarregados somente quando podem editar a pré-visualização no local. -- Se o streaming falhar no meio da resposta, o OpenClaw recorre à entrega normal para os payloads restantes. +- Uma thread de resposta deve estar disponível para que o streaming de texto nativo e o status de thread do assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`. +- Raízes de canal, conversa em grupo e DM de nível superior ainda podem usar a pré-visualização de rascunho normal quando o streaming nativo está indisponível ou nenhuma thread de resposta existe. +- DMs do Slack de nível superior permanecem fora de thread por padrão, portanto não mostram a pré-visualização nativa de stream/status em estilo de thread do Slack; o OpenClaw publica e edita uma pré-visualização de rascunho na DM. +- Mídia e cargas úteis que não sejam texto usam a entrega normal como fallback. +- Finais de mídia/erro cancelam edições de pré-visualização pendentes; finais de texto/bloco elegíveis são liberados apenas quando podem editar a pré-visualização no lugar. +- Se o streaming falhar no meio da resposta, o OpenClaw usa a entrega normal como fallback para as cargas úteis restantes. -Use pré-visualização de rascunho em vez de streaming de texto nativo do Slack: +Usar pré-visualização de rascunho em vez do streaming de texto nativo do Slack: ```json5 { @@ -719,13 +1027,13 @@ Use pré-visualização de rascunho em vez de streaming de texto nativo do Slack Chaves legadas: -- `channels.slack.streamMode` (`replace | status_final | append`) é migrada automaticamente para `channels.slack.streaming.mode`. -- booleano `channels.slack.streaming` é migrado automaticamente para `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`. -- `channels.slack.nativeStreaming` legado é migrado automaticamente para `channels.slack.streaming.nativeTransport`. +- `channels.slack.streamMode` (`replace | status_final | append`) é migrado automaticamente para `channels.slack.streaming.mode`. +- o booleano `channels.slack.streaming` é migrado automaticamente para `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`. +- o `channels.slack.nativeStreaming` legado é migrado automaticamente para `channels.slack.streaming.nativeTransport`. ## Fallback de reação de digitação -`typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto o OpenClaw processa uma resposta e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "está digitando...". +`typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto o OpenClaw está processando uma resposta, e a remove quando a execução termina. Isso é mais útil fora de respostas em threads, que usam um indicador de status padrão "está digitando...". Ordem de resolução: @@ -735,42 +1043,42 @@ Ordem de resolução: Observações: - O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`). -- A reação é de melhor esforço, e a limpeza é tentada automaticamente após a conclusão da resposta ou do caminho de falha. +- A reação é de melhor esforço, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído. ## Mídia, fragmentação e entrega - - Anexos de arquivos do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticada por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. Os placeholders de arquivo incluem o `fileId` do Slack para que os agentes possam buscar o arquivo original com `download-file`. + + Os anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticado por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. Os placeholders de arquivo incluem o `fileId` do Slack para que os agentes possam buscar o arquivo original com `download-file`. - Os downloads usam tempos limite delimitados de inatividade e totais. Se a recuperação de arquivos do Slack travar ou falhar, o OpenClaw continua processando a mensagem e recorre ao placeholder de arquivo. + Os downloads usam tempos limite ociosos e totais delimitados. Se a recuperação de arquivo do Slack travar ou falhar, o OpenClaw continua processando a mensagem e recorre ao placeholder de arquivo. - O limite de tamanho de entrada em runtime usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`. + O limite de tamanho de entrada em tempo de execução usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`. - - - fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000) + + - os fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000) - `channels.slack.chunkMode="newline"` habilita a divisão priorizando parágrafos - - envios de arquivos usam APIs de upload do Slack e podem incluir respostas em thread (`thread_ts`) - - o limite de mídia de saída segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, os envios do canal usam padrões por tipo MIME do pipeline de mídia + - os envios de arquivo usam APIs de upload do Slack e podem incluir respostas em threads (`thread_ts`) + - o limite de mídia de saída segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, envios de canal usam padrões por tipo MIME do pipeline de mídia - - Destinos explícitos preferidos: + + Alvos explícitos preferenciais: - `user:` para DMs - `channel:` para canais - DMs do Slack somente com texto/blocos podem postar diretamente em IDs de usuário; uploads de arquivo e envios em thread abrem a DM primeiro pelas APIs de conversa do Slack porque esses caminhos exigem um ID de conversa concreto. + DMs do Slack somente com texto/blocos podem publicar diretamente em IDs de usuário; uploads de arquivo e envios em thread abrem a DM primeiro pelas APIs de conversação do Slack, porque esses caminhos exigem um ID de conversa concreto. -## Comandos e comportamento de slash +## Comandos e comportamento de barra -Comandos slash aparecem no Slack como um único comando configurado ou como vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando: +Comandos de barra aparecem no Slack como um único comando configurado ou como vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando: - `enabled: false` - `name: "openclaw"` @@ -781,9 +1089,9 @@ Comandos slash aparecem no Slack como um único comando configurado ou como vár /openclaw /help ``` -Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu aplicativo Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais. +Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais. -- O modo automático de comandos nativos fica **desativado** para o Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. +- O modo automático de comandos nativos fica **desativado** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. ```txt /help @@ -800,11 +1108,11 @@ Menus de argumentos nativos usam uma estratégia de renderização adaptativa qu /think ``` -Sessões slash usam chaves isoladas como `agent::slack:slash:` e ainda roteiam execuções de comando para a sessão de conversa de destino usando `CommandTargetSessionKey`. +Sessões de barra usam chaves isoladas como `agent::slack:slash:` e ainda roteiam execuções de comando para a sessão da conversa de destino usando `CommandTargetSessionKey`. ## Respostas interativas -O Slack pode renderizar controles de resposta interativa criados por agentes, mas esse recurso fica desabilitado por padrão. +O Slack pode renderizar controles de resposta interativos criados por agentes, mas esse recurso é desabilitado por padrão. Habilite globalmente: @@ -820,7 +1128,7 @@ Habilite globalmente: } ``` -Ou habilite para apenas uma conta do Slack: +Ou habilite apenas para uma conta do Slack: ```json5 { @@ -838,30 +1146,30 @@ Ou habilite para apenas uma conta do Slack: } ``` -Quando habilitado, os agentes podem emitir diretivas de resposta exclusivas do Slack: +Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Essas diretivas são compiladas para Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho de evento de interação existente do Slack. +Essas diretivas são compiladas para o Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho de evento de interação existente do Slack. Observações: - Esta é uma UI específica do Slack. Outros canais não traduzem diretivas do Slack Block Kit para seus próprios sistemas de botões. -- Os valores de callback interativo são tokens opacos gerados pelo OpenClaw, não valores brutos criados pelo agente. -- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw recorre à resposta de texto original em vez de enviar uma carga útil de blocos inválida. +- Os valores de callback interativo são tokens opacos gerados pelo OpenClaw, não valores brutos criados por agentes. +- Se blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw recorre à resposta de texto original em vez de enviar um payload de blocos inválido. -## Aprovações de execução no Slack +## Aprovações de Exec no Slack O Slack pode atuar como um cliente de aprovação nativo com botões e interações interativos, em vez de recorrer à UI Web ou ao terminal. -- Aprovações de execução usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal. +- Aprovações de Exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal. - Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo de ID de aprovação é `plugin:`. -- A autorização do aprovador ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack. +- A autorização de aprovadores ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack. -Isso usa a mesma superfície compartilhada de botões de aprovação que outros canais. Quando `interactivity` está habilitado nas configurações do seu aplicativo Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa. -Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw -só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser que aprovações +Isso usa a mesma superfície compartilhada de botões de aprovação que outros canais. Quando `interactivity` está habilitada nas configurações do seu app Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa. +Quando esses botões estiverem presentes, eles são a UX de aprovação principal; o OpenClaw +só deve incluir um comando manual `/approve` quando o resultado da ferramenta indicar que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho. Caminho de configuração: @@ -871,11 +1179,11 @@ Caminho de configuração: - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter` -O Slack habilita automaticamente aprovações de execução nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um +O Slack habilita automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador é resolvido. Defina `enabled: false` para desabilitar explicitamente o Slack como cliente de aprovação nativo. Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos. -Comportamento padrão sem configuração explícita de aprovação de execução do Slack: +Comportamento padrão sem configuração explícita de aprovação de exec do Slack: ```json5 { @@ -885,7 +1193,7 @@ Comportamento padrão sem configuração explícita de aprovação de execução } ``` -A configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou +Configuração nativa do Slack explícita só é necessária quando você quer substituir aprovadores, adicionar filtros ou optar por entrega no chat de origem: ```json5 @@ -902,23 +1210,23 @@ optar por entrega no chat de origem: } ``` -O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de execução também precisarem -ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado de `approvals.plugin` também é +O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de exec também precisarem +ser roteados para outros chats ou alvos explícitos fora de banda. O encaminhamento compartilhado de `approvals.plugin` também é separado; botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegam ao Slack. -`/approve` no mesmo chat também funciona em canais e DMs do Slack que já dão suporte a comandos. Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovação. +`/approve` no mesmo chat também funciona em canais e DMs do Slack que já aceitam comandos. Consulte [Aprovações de Exec](/pt-BR/tools/exec-approvals) para o modelo completo de encaminhamento de aprovações. ## Eventos e comportamento operacional -- Edições/exclusões de mensagens são mapeadas para eventos do sistema. -- Transmissões de thread (respostas de thread "Também enviar para o canal") são processadas como mensagens normais de usuário. -- Eventos de adicionar/remover reação são mapeados para eventos do sistema. -- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover fixação são mapeados para eventos do sistema. +- Edições/exclusões de mensagens são mapeadas para eventos de sistema. +- Transmissões de thread (respostas em thread com "Também enviar para o canal") são processadas como mensagens normais de usuário. +- Eventos de adição/remoção de reação são mapeados para eventos de sistema. +- Eventos de entrada/saída de membro, canal criado/renomeado e adição/remoção de fixação são mapeados para eventos de sistema. - `channel_id_changed` pode migrar chaves de configuração de canal quando `configWrites` está habilitado. -- Metadados de tópico/finalidade do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento. -- A semente de contexto do iniciador da thread e do histórico inicial da thread é filtrada por allowlists de remetentes configuradas quando aplicável. -- Ações de bloco e interações modais emitem eventos de sistema estruturados `Slack interaction: ...` com campos de carga útil ricos: +- Metadados de tópico/propósito de canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento. +- O contexto inicial do iniciador da thread e do histórico da thread é filtrado por allowlists de remetentes configuradas quando aplicável. +- Ações de bloco e interações modais emitem eventos de sistema `Slack interaction: ...` estruturados com campos de payload ricos: - ações de bloco: valores selecionados, rótulos, valores de seletores e metadados `workflow_*` - eventos modais `view_submission` e `view_closed` com metadados de canal roteado e entradas de formulário @@ -926,28 +1234,28 @@ ao Slack. Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/config-channels#slack). - + - modo/autenticação: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - acesso a DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` -- alternância de compatibilidade: `dangerouslyAllowNameMatching` (uso emergencial; mantenha desativado a menos que necessário) -- acesso a canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` +- alternância de compatibilidade: `dangerouslyAllowNameMatching` (quebra-vidro; mantenha desativado a menos que seja necessário) +- acesso a canais: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - threads/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` -- ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` +- operações/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## Solução de problemas - - Verifique, na ordem: + + Verifique, em ordem: - `groupPolicy` - - allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente em `groupPolicy: "allowlist"` porque o roteamento de canal prioriza IDs por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copiar link** — o valor `C...` no fim da URL é o ID do canal. + - allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente sob `groupPolicy: "allowlist"` porque o roteamento de canal prioriza ID por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copy link** — o valor `C...` no fim da URL é o ID do canal. - `requireMention` - - allowlist de `users` por canal + - allowlist `users` por canal Comandos úteis: @@ -959,14 +1267,14 @@ openclaw doctor - + Verifique: - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (ou legado `channels.slack.dm.policy`) - aprovações de pareamento / entradas de allowlist - - eventos de DM do Slack Assistant: logs detalhados mencionando `drop message_changed` - geralmente significam que o Slack enviou um evento editado de thread do Assistant sem um + - eventos de DM do Slack Assistant: logs detalhados que mencionam `drop message_changed` + geralmente significam que o Slack enviou um evento de thread do Assistant editado sem um remetente humano recuperável nos metadados da mensagem ```bash @@ -975,70 +1283,70 @@ openclaw pairing list slack - - Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do aplicativo Slack. + + Valide os tokens de bot + app e a habilitação do Socket Mode nas configurações do app Slack. Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou `appTokenStatus: "configured_unavailable"`, a conta do Slack está - configurada, mas o runtime atual não conseguiu resolver o valor - respaldado por SecretRef. + configurada, mas o tempo de execução atual não conseguiu resolver o valor + baseado em SecretRef. - + Valide: - segredo de assinatura - - caminho de Webhook - - URLs de solicitação do Slack (Eventos + Interatividade + Comandos Slash) - - `webhookPath` exclusivo por conta HTTP + - caminho do Webhook + - URLs de solicitação do Slack (Eventos + Interatividade + Comandos de barra) + - `webhookPath` único por conta HTTP - Se `signingSecretStatus: "configured_unavailable"` aparecer em snapshots de conta, - a conta HTTP está configurada, mas o runtime atual não conseguiu - resolver o segredo de assinatura respaldado por SecretRef. + Se `signingSecretStatus: "configured_unavailable"` aparecer em snapshots + de conta, a conta HTTP está configurada, mas o tempo de execução atual não + conseguiu resolver o segredo de assinatura baseado em SecretRef. - + Verifique se você pretendia usar: - - modo de comando nativo (`channels.slack.commands.native: true`) com comandos slash correspondentes registrados no Slack - - ou modo de comando slash único (`channels.slack.slashCommand.enabled: true`) + - modo de comando nativo (`channels.slack.commands.native: true`) com comandos de barra correspondentes registrados no Slack + - ou modo de comando de barra único (`channels.slack.slashCommand.enabled: true`) - Verifique também `commands.useAccessGroups` e allowlists de canais/usuários. + Verifique também `commands.useAccessGroups` e allowlists de canal/usuário. -## Referência de visão de anexos +## Referência de visão para anexos -O Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivo do Slack são bem-sucedidos e os limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável, em vez de serem tratados como entrada de imagem. +O Slack pode anexar mídia baixada ao turno do agente quando os downloads de arquivo do Slack são bem-sucedidos e os limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável em vez de tratados como entrada de imagem. ### Tipos de mídia compatíveis -| Tipo de mídia | Origem | Comportamento atual | Observações | -| ------------------------------ | -------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| Imagens JPEG / PNG / GIF / WebP | URL de arquivo do Slack | Baixadas e anexadas ao turno para tratamento compatível com visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) | -| Arquivos PDF | URL de arquivo do Slack | Baixados e expostos como contexto de arquivo para ferramentas como `download-file` ou `pdf` | A entrada do Slack não converte PDFs automaticamente em entrada de visão por imagem | -| Outros arquivos | URL de arquivo do Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem | -| Respostas em thread | Arquivos do início da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Inícios somente com arquivo usam um placeholder de anexo | -| Mensagens com múltiplas imagens | Vários arquivos do Slack | Cada arquivo é avaliado de forma independente | O processamento do Slack é limitado a oito arquivos por mensagem | +| Tipo de mídia | Origem | Comportamento atual | Observações | +| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| Imagens JPEG / PNG / GIF / WebP | URL de arquivo Slack | Baixadas e anexadas ao turno para tratamento compatível com visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) | +| Arquivos PDF | URL de arquivo Slack | Baixados e expostos como contexto de arquivo para ferramentas como `download-file` ou `pdf` | A entrada do Slack não converte PDFs automaticamente em entrada de imagem para visão | +| Outros arquivos | URL de arquivo Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem | +| Respostas em thread | Arquivos da mensagem inicial da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Mensagens iniciais apenas com arquivo usam um placeholder de anexo | +| Mensagens com várias imagens | Vários arquivos Slack | Cada arquivo é avaliado independentemente | O processamento do Slack é limitado a oito arquivos por mensagem | ### Pipeline de entrada Quando uma mensagem do Slack com anexos de arquivo chega: -1. O OpenClaw baixa o arquivo da URL privada do Slack usando o token do bot (`xoxb-...`). -2. O arquivo é gravado no armazenamento de mídia em caso de sucesso. -3. Os caminhos de mídia baixados e os tipos de conteúdo são adicionados ao contexto de entrada. +1. OpenClaw baixa o arquivo da URL privada do Slack usando o token do bot (`xoxb-...`). +2. O arquivo é gravado no armazenamento de mídia com sucesso. +3. Caminhos de mídia baixada e tipos de conteúdo são adicionados ao contexto de entrada. 4. Caminhos de modelo/ferramenta compatíveis com imagem podem usar anexos de imagem desse contexto. -5. Arquivos que não são imagem permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que conseguem lidar com eles. +5. Arquivos que não são imagem continuam disponíveis como metadados de arquivo ou referências de mídia para ferramentas que podem lidar com eles. ### Herança de anexos da raiz da thread Quando uma mensagem chega em uma thread (tem um pai `thread_ts`): -- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos raiz como contexto de início da thread. +- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos raiz como contexto da mensagem inicial da thread. - Anexos diretos da resposta têm precedência sobre anexos da mensagem raiz. - Uma mensagem raiz que tem apenas arquivos e nenhum texto é representada com um placeholder de anexo para que o fallback ainda possa incluir seus arquivos. @@ -1046,54 +1354,54 @@ Quando uma mensagem chega em uma thread (tem um pai `thread_ts`): Quando uma única mensagem do Slack contém vários anexos de arquivo: -- Cada anexo é processado de forma independente pelo pipeline de mídia. +- Cada anexo é processado independentemente pelo pipeline de mídia. - Referências de mídia baixadas são agregadas ao contexto da mensagem. -- A ordem de processamento segue a ordem dos arquivos do Slack no payload do evento. +- A ordem de processamento segue a ordem dos arquivos do Slack na carga útil do evento. - Uma falha no download de um anexo não bloqueia os outros. ### Limites de tamanho, download e modelo - **Limite de tamanho**: padrão de 20 MB por arquivo. Configurável via `channels.slack.mediaMaxMb`. -- **Falhas de download**: arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos grandes demais e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos incompatíveis. +- **Falhas de download**: arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos acima do limite e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos incompatíveis. - **Modelo de visão**: a análise de imagem usa o modelo de resposta ativo quando ele oferece suporte a visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`. ### Limites conhecidos -| Cenário | Comportamento atual | Solução alternativa | +| Cenário | Comportamento atual | Solução alternativa | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| URL de arquivo do Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack | +| URL de arquivo Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack | | Modelo de visão não configurado | Anexos de imagem são armazenados como referências de mídia, mas não analisados como imagens | Configure `agents.defaults.imageModel` ou use um modelo de resposta compatível com visão | -| Imagens muito grandes (> 20 MB por padrão) | Ignoradas pelo limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir | -| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedada no Slack são tratados da melhor forma possível | Recompartilhe diretamente na thread do OpenClaw | -| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF | +| Imagens muito grandes (> 20 MB por padrão) | Ignoradas conforme o limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir | +| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedada no Slack são tratados em melhor esforço | Compartilhe novamente diretamente na thread do OpenClaw | +| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF | ### Documentação relacionada - [Pipeline de compreensão de mídia](/pt-BR/nodes/media-understanding) - [Ferramenta PDF](/pt-BR/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack +- Épico: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack - Testes de regressão: [#51353](https://github.com/openclaw/openclaw/issues/51353) - Verificação ao vivo: [#51354](https://github.com/openclaw/openclaw/issues/51354) -## Relacionados +## Relacionado - + Pareie um usuário do Slack ao Gateway. - + Comportamento de canal e DM em grupo. - - Roteie mensagens de entrada para agentes. + + Encaminhe mensagens de entrada para agentes. - - Modelo de ameaças e hardening. + + Modelo de ameaças e fortalecimento. - - Layout e precedência de configuração. + + Layout e precedência da configuração. - + Catálogo e comportamento de comandos. diff --git a/docs/pt-BR/ci.md b/docs/pt-BR/ci.md index 834597df1..e0a458056 100644 --- a/docs/pt-BR/ci.md +++ b/docs/pt-BR/ci.md @@ -1,71 +1,71 @@ --- read_when: - - Você precisa entender por que um job de CI foi executado ou não - - Você está depurando uma verificação do GitHub Actions que está falhando - - Você está coordenando uma execução ou reexecução da validação de lançamento + - Você precisa entender por que uma tarefa de CI foi ou não executada + - Você está depurando uma verificação com falha do GitHub Actions + - Você está coordenando uma execução ou reexecução de validação de lançamento - Você está alterando o acionamento do ClawSweeper ou o encaminhamento de atividades do GitHub -summary: Grafo de tarefas de CI, controles de escopo, guarda-chuvas de lançamento e equivalentes de comandos locais +summary: Grafo de tarefas de CI, critérios de escopo, abrangências de lançamento e equivalentes de comandos locais title: Pipeline de CI x-i18n: - generated_at: "2026-05-04T05:52:15Z" + generated_at: "2026-05-05T01:44:48Z" model: gpt-5.5 provider: openai - source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d + source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66 source_path: ci.md workflow: 16 --- -A CI do OpenClaw é executada em cada push para `main` e em cada pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais de `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android continuam opcionais por meio de `include_android`. A cobertura de Plugins somente de release fica no workflow separado [`Plugin Prerelease`](#plugin-prerelease) e só é executada a partir de [`Full Release Validation`](#full-release-validation) ou de um disparo manual explícito. +OpenClaw CI é executado em cada push para `main` e em cada pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais por `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android continuam opt-in por meio de `include_android`. A cobertura de plugins exclusiva de release fica no workflow separado [`Pré-lançamento de Plugin`](#plugin-prerelease) e só é executada a partir de [`Validação Completa de Release`](#full-release-validation) ou de um disparo manual explícito. ## Visão geral do pipeline -| Job | Finalidade | Quando é executado | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Detecta alterações somente de docs, escopos alterados, extensions alteradas e constrói o manifesto de CI | Sempre em pushes e PRs não rascunho | -| `security-scm-fast` | Detecção de chaves privadas e auditoria de workflow via `zizmor` | Sempre em pushes e PRs não rascunho | -| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs não rascunho | -| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não rascunho | -| `check-dependencies` | Passagem do Knip somente para dependências de produção mais a guarda da lista de permissões de arquivos não usados | Alterações relevantes para Node | -| `build-artifacts` | Compila `dist/`, Control UI, verificações de artefatos compilados e artefatos downstream reutilizáveis | Alterações relevantes para Node | -| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de Plugins empacotados/contratos de Plugin/protocolo | Alterações relevantes para Node | -| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canais com um resultado agregado estável | Alterações relevantes para Node | -| `checks-node-core-test` | Fragmentos de testes do Node principal, excluindo lanes de canais, Plugins empacotados, contratos e extensions | Alterações relevantes para Node | -| `check` | Equivalente fragmentado do gate local principal: tipos de produção, lint, guardas, tipos de teste e smoke estrito | Alterações relevantes para Node | -| `check-additional` | Arquitetura, drift fragmentado de limites/prompts, guardas de extensions, limite de pacote e Gateway watch | Alterações relevantes para Node | -| `build-smoke` | Testes smoke da CLI compilada e smoke de memória de inicialização | Alterações relevantes para Node | -| `checks` | Verificador para testes de canal de artefatos compilados | Alterações relevantes para Node | -| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para releases | -| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas | -| `skills-python` | Ruff + pytest para Skills apoiadas por Python | Alterações relevantes para Skills em Python | -| `checks-windows` | Testes específicos de processo/caminho no Windows mais regressões compartilhadas de especificadores de importação em runtime | Alterações relevantes para Windows | -| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS | -| `macos-swift` | Lint, build e testes Swift para o app macOS | Alterações relevantes para macOS | -| `android` | Testes unitários de Android para ambos os flavors mais um build de APK de debug | Alterações relevantes para Android | -| `test-performance-agent` | Otimização diária de testes lentos pelo Codex após atividade confiável | Sucesso da CI principal ou disparo manual | -| `openclaw-performance` | Relatórios diários/sob demanda de performance do runtime Kova com lanes de mock-provider, deep-profile e GPT 5.4 ao vivo | Disparo agendado e manual | +| Job | Finalidade | Quando é executado | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | +| `preflight` | Detecta mudanças apenas em docs, escopos alterados, extensões alteradas e cria o manifesto de CI | Sempre em pushes e PRs não rascunho | +| `security-scm-fast` | Detecção de chave privada e auditoria de workflows via `zizmor` | Sempre em pushes e PRs não rascunho | +| `security-dependency-audit` | Auditoria do lockfile de produção, sem dependências, contra avisos do npm | Sempre em pushes e PRs não rascunho | +| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não rascunho | +| `check-dependencies` | Passo Knip de produção apenas para dependências mais a guarda da allowlist de arquivos não usados | Mudanças relevantes para Node | +| `build-artifacts` | Cria `dist/`, Control UI, verificações de artefatos criados e artefatos reutilizáveis downstream | Mudanças relevantes para Node | +| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de bundled/contrato de plugin/protocolo | Mudanças relevantes para Node | +| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canais com um resultado de verificação agregado estável | Mudanças relevantes para Node | +| `checks-node-core-test` | Shards de testes principais de Node, excluindo lanes de canal, bundled, contrato e extensão | Mudanças relevantes para Node | +| `check` | Equivalente fragmentado do gate local principal: tipos de prod, lint, guardas, tipos de teste e smoke estrito | Mudanças relevantes para Node | +| `check-additional` | Arquitetura, drift fragmentado de boundary/prompt, guardas de extensão, package boundary e gateway watch | Mudanças relevantes para Node | +| `build-smoke` | Testes smoke da CLI criada e smoke de memória de inicialização | Mudanças relevantes para Node | +| `checks` | Verificador para testes de canais com artefatos criados | Mudanças relevantes para Node | +| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para releases | +| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas | +| `skills-python` | Ruff + pytest para skills baseadas em Python | Mudanças relevantes para skills Python | +| `checks-windows` | Testes específicos do Windows para processos/caminhos mais regressões compartilhadas de especificadores de importação em runtime | Mudanças relevantes para Windows | +| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos criados compartilhados | Mudanças relevantes para macOS | +| `macos-swift` | Lint, build e testes Swift para o app macOS | Mudanças relevantes para macOS | +| `android` | Testes unitários Android para ambos os flavors mais um build de APK debug | Mudanças relevantes para Android | +| `test-performance-agent` | Otimização diária de testes lentos do Codex após atividade confiável | Sucesso do CI principal ou disparo manual | +| `openclaw-performance` | Relatórios diários/sob demanda de performance do runtime Kova com mock-provider, deep-profile e lanes live GPT 5.4 | Disparo agendado e manual | -## Ordem de falha rápida +## Ordem de fail-fast -1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro deste job, não jobs independentes. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de matriz de artefatos e plataformas. +1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro desse job, não jobs independentes. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de artefatos e matriz de plataformas. 3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto. -4. Lanes mais pesadas de plataforma e runtime se expandem depois disso: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. +4. Depois disso, lanes mais pesadas de plataforma e runtime se expandem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`. -O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega ao mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais nova para a mesma ref também esteja falhando. Verificações agregadas de fragmentos usam `!cancelled() && always()` para que ainda relatem falhas normais de fragmentos, mas não entrem na fila depois que o workflow inteiro já tiver sido substituído. A chave de concorrência automática da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas da main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento. +O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais recente chega ao mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. Verificações agregadas de shards usam `!cancelled() && always()` para ainda relatar falhas normais de shard, mas não entrar na fila depois que o workflow inteiro já foi substituído. A chave automática de concorrência do CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas de main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento. ## Escopo e roteamento A lógica de escopo fica em `scripts/ci-changed-scope.mjs` e é coberta por testes unitários em `src/scripts/ci-changed-scope.test.ts`. O disparo manual pula a detecção de escopo alterado e faz o manifesto de preflight agir como se todas as áreas com escopo tivessem mudado. -- **Edições de workflow de CI** validam o grafo de CI do Node mais linting de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma permanecem escopadas a alterações de código-fonte de plataforma. -- **Edições apenas de roteamento de CI, edições selecionadas de fixtures baratas de testes do núcleo e edições estreitas de helpers/roteamento de testes de contrato de Plugin** usam um caminho rápido de manifesto somente Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canais, fragmentos completos do núcleo, fragmentos de Plugins empacotados e matrizes adicionais de guardas quando a alteração se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente. -- **Verificações de Node no Windows** são escopadas a wrappers específicos de processo/caminho do Windows, helpers de execução npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; alterações não relacionadas de código-fonte, Plugin, smoke de instalação e somente testes permanecem nas lanes de Node no Linux. +- **Edições no workflow de CI** validam o grafo de CI do Node mais o lint de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma continuam limitadas ao escopo de mudanças no código-fonte da plataforma. +- **Edições apenas de roteamento de CI, edições selecionadas baratas de fixtures de testes principais e edições estreitas de helpers/test-routing de contrato de plugin** usam um caminho rápido de manifesto apenas para Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canais, shards principais completos, shards de bundled-plugin e matrizes adicionais de guardas quando a mudança se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente. +- **Verificações de Node no Windows** têm escopo limitado a wrappers de processos/caminhos específicos do Windows, helpers de runner npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; mudanças não relacionadas em código-fonte, plugin, install-smoke e apenas testes ficam nas lanes de Node do Linux. -As famílias mais lentas de testes Node são divididas ou balanceadas para que cada job continue pequeno sem reservar runners em excesso: contratos de canais rodam como três fragmentos ponderados, lanes rápidas/de suporte de unidade do núcleo rodam separadamente, a infraestrutura de runtime do núcleo é dividida entre fragmentos de estado e processo/configuração, auto-reply roda como workers balanceados (com a subárvore de respostas dividida em fragmentos de agent-runner, dispatch e commands/state-routing), e configurações agentic de Gateway/servidor são divididas entre lanes de chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos compilados. Testes amplos de navegador, QA, mídia e Plugins diversos usam suas configurações Vitest dedicadas em vez do catch-all compartilhado de Plugins. Fragmentos com padrão de inclusão registram entradas de tempo usando o nome do fragmento de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma configuração inteira de um fragmento filtrado. `check-additional` mantém juntos o trabalho de compilação/canário de limite de pacote e separa a arquitetura de topologia de runtime da cobertura de Gateway watch; a lista de guardas de limite é distribuída em quatro fragmentos de matriz, cada um executando guardas independentes selecionadas em paralelo e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que drift de prompt do caminho feliz do runtime Codex fique preso ao PR que o causou. Gateway watch, testes de canais e o fragmento de limite de suporte do núcleo rodam em paralelo dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados. +As famílias de testes Node mais lentas são divididas ou balanceadas para que cada job permaneça pequeno sem reservar runners em excesso: contratos de canais rodam como três shards ponderados, lanes fast/support de unidades do core rodam separadamente, a infraestrutura de runtime do core é dividida entre shards de estado e processo/config, auto-reply roda como workers balanceados (com a subárvore de reply dividida em shards de agent-runner, dispatch e commands/state-routing), e configs agentic de gateway/server são divididas entre lanes de chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos criados. Testes amplos de navegador, QA, mídia e plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de plugins. Shards de include-pattern registram entradas de tempo usando o nome do shard de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma config inteira de um shard filtrado. `check-additional` mantém o trabalho de compile/canary de package-boundary junto e separa arquitetura de topologia de runtime da cobertura de gateway watch; a lista de guardas de boundary é distribuída em quatro shards de matriz, cada um executando guardas independentes selecionadas em paralelo e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que o drift de prompt do caminho feliz do runtime Codex fique fixado ao PR que o causou. Gateway watch, testes de canais e o shard de support-boundary do core rodam em paralelo dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram criados. -A CI de Android executa `testPlayDebugUnitTest` e `testThirdPartyDebugUnitTest` e depois compila o APK de debug Play. O flavor third-party não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo um job duplicado de empacotamento de APK de debug em cada push relevante para Android. +O CI de Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest` e depois cria o APK debug Play. O flavor third-party não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo um job duplicado de empacotamento de APK debug em todo push relevante para Android. -O fragmento `check-dependencies` executa `pnpm deadcode:dependencies` (uma passagem do Knip somente para dependências de produção fixada na versão mais recente do Knip, com a idade mínima de release do pnpm desativada para a instalação `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na lista de permissões, preservando superfícies intencionais de Plugins dinâmicos, geradas, de build, testes ao vivo e pontes de pacote que o Knip não consegue resolver estaticamente. +O shard `check-dependencies` executa `pnpm deadcode:dependencies` (um passo Knip de produção apenas para dependências, fixado na versão mais recente do Knip, com a idade mínima de release do pnpm desativada para a instalação `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na allowlist, preservando ao mesmo tempo superfícies intencionais de plugin dinâmico, geradas, de build, live-test e bridge de pacote que o Knip não consegue resolver estaticamente. ## Encaminhamento de atividade do ClawSweeper @@ -75,20 +75,20 @@ O workflow tem quatro lanes: - `clawsweeper_item` para solicitações exatas de revisão de issues e pull requests; - `clawsweeper_comment` para comandos explícitos do ClawSweeper em comentários de issues; -- `clawsweeper_commit_review` para solicitações de revisão no nível de commit em pushes para `main`; +- `clawsweeper_commit_review` para solicitações de revisão em nível de commit em pushes para `main`; - `github_activity` para atividade geral do GitHub que o agente ClawSweeper pode inspecionar. -A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos de comentários ou revisões quando presentes. Ela evita intencionalmente encaminhar o corpo completo do Webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper. +A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos para comentários ou reviews quando presentes. Ela evita intencionalmente encaminhar o corpo completo do webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper. -Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino do Discord no prompt e deve publicar em `#clawsweeper` somente quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, atividade repetitiva de bots, ruído de Webhook duplicado e tráfego normal de revisão devem resultar em `NO_REPLY`. +Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino Discord em seu prompt e deve publicar em `#clawsweeper` apenas quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, ruído de bots, ruído duplicado de webhook e tráfego normal de reviews devem resultar em `NO_REPLY`. -Trate títulos, comentários, corpos, texto de revisão, nomes de branches e mensagens de commit do GitHub como dados não confiáveis em todo este caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou o runtime do agente. +Trate títulos, comentários, corpos, texto de reviews, nomes de branches e mensagens de commit do GitHub como dados não confiáveis ao longo de todo esse caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou runtime do agente. ## Disparos manuais -Os dispatches manuais de CI executam o mesmo grafo de jobs que a CI normal, mas forçam a ativação de toda lane com escopo não Android: shards Linux Node, shards de plugins agrupados, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de documentação, Skills Python, Windows, macOS e i18n da Control UI. Dispatches manuais independentes de CI executam apenas Android com `include_android=true`; o guarda-chuva completo de release habilita Android passando `include_android=true`. Verificações estáticas de pré-release de Plugin, o shard exclusivo de release `agentic-plugins`, a varredura completa em lote de extensions e as lanes Docker de pré-release de Plugin ficam excluídos da CI. A suíte Docker de pré-release é executada somente quando `Full Release Validation` dispara o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado. +Os despachos manuais de CI executam o mesmo grafo de jobs da CI normal, mas forçam todos os lanes com escopo não Android: shards Linux Node, shards de plugins agrupados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS e i18n da Control UI. Despachos manuais independentes de CI executam apenas Android com `include_android=true`; o guarda-chuva de release completo habilita Android passando `include_android=true`. Verificações estáticas de pré-lançamento de Plugin, o shard exclusivo de release `agentic-plugins`, a varredura completa em lote de plugins e lanes Docker de pré-lançamento de Plugin são excluídos da CI. A suíte Docker de pré-lançamento é executada apenas quando `Full Release Validation` despacha o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado. -Execuções manuais usam um grupo de concorrência único para que uma suíte completa de candidato a release não seja cancelada por outra execução de push ou PR na mesma ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA completo de commit usando o arquivo de workflow da ref de dispatch selecionada. +Execuções manuais usam um grupo de concorrência exclusivo para que uma suíte completa de candidato a release não seja cancelada por outra execução de push ou PR no mesmo ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA de commit completo enquanto usa o arquivo de workflow do ref de despacho selecionado. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -96,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Executores +## Runners -| Executor | Jobs | -| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/plugins agrupados, verificações fragmentadas de contratos de canal, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de documentação, Skills Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensions mais leves, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de plugins agrupados, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU a ponto de 8 vCPU custar mais do que economizou); builds Docker de install-smoke (o tempo de fila de 32 vCPU custou mais do que economizou) | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks voltam para `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks voltam para `macos-latest` | +| Runner | Jobs | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, jobs e agregados de segurança rápidos (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/agrupados, verificações de contrato de canal em shards, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado no GitHub para que a matriz do Blacksmith possa entrar na fila mais cedo | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensão mais leves, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de Plugin agrupado, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU o bastante para que 8 vCPU custassem mais do que economizavam); builds Docker de install-smoke (o tempo de fila de 32 vCPU custou mais do que economizou) | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback | ## Equivalentes locais @@ -135,9 +135,9 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md ``` -## Desempenho do OpenClaw +## Performance do OpenClaw -`OpenClaw Performance` é o workflow de desempenho de produto/runtime. Ele é executado diariamente em `main` e pode ser disparado manualmente: +`OpenClaw Performance` é o workflow de performance do produto/runtime. Ele é executado diariamente em `main` e pode ser despachado manualmente: ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -145,25 +145,32 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -O dispatch manual normalmente mede a ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Os caminhos de relatórios publicados e ponteiros mais recentes são indexados pela ref testada, e cada `index.md` registra a ref/SHA testada, a ref/SHA do workflow, a ref do Kova, perfil, modo de autenticação da lane, modelo, contagem de repetições e filtros de cenário. +O despacho manual normalmente mede o ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Caminhos de relatórios publicados e ponteiros mais recentes são indexados pelo ref testado, e cada `index.md` registra o ref/SHA testado, ref/SHA do workflow, ref do Kova, perfil, modo de autenticação do lane, modelo, contagem de repetições e filtros de cenário. -O workflow instala OCM a partir de uma release fixada e Kova a partir de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes: +O workflow instala o OCM a partir de uma release fixada e o Kova a partir de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes: -- `mock-provider`: cenários diagnósticos do Kova contra um runtime de build local com autenticação fake determinística compatível com OpenAI. -- `mock-deep-profile`: profiling de CPU/heap/trace para pontos críticos de inicialização, Gateway e turnos de agente. +- `mock-provider`: cenários diagnósticos do Kova contra um runtime de build local com autenticação falsa determinística compatível com OpenAI. +- `mock-deep-profile`: profiling de CPU/heap/trace para hotspots de inicialização, Gateway e turno de agente. - `live-gpt54`: um turno real de agente OpenAI `openai/gpt-5.4`, ignorado quando `OPENAI_API_KEY` não está disponível. -A lane mock-provider também executa sondagens de origem nativas do OpenClaw após a passagem do Kova: tempo de inicialização e memória do Gateway nos casos de inicialização padrão, com hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock-OpenAI; e comandos de inicialização da CLI contra o Gateway iniciado. O resumo Markdown da sondagem de origem fica em `source/index.md` no pacote de relatório, com JSON bruto ao lado. +O lane mock-provider também executa sondagens de origem nativas do OpenClaw após a passagem do Kova: tempo de boot e memória do Gateway em casos de inicialização padrão, com hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock-OpenAI; e comandos de inicialização da CLI contra o Gateway inicializado. O resumo Markdown da sondagem de origem fica em `source/index.md` no pacote do relatório, com JSON bruto ao lado. -Cada lane envia artefatos do GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também faz commit de `report.json`, `report.md`, pacotes, `index.md` e artefatos de sondagem de origem em `openclaw/clawgrit-reports` sob `openclaw-performance//-//`. O ponteiro atual da ref testada é gravado como `openclaw-performance//latest-.json`. +Cada lane envia artefatos do GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também faz commit de `report.json`, `report.md`, pacotes, `index.md` e artefatos de sondagem de origem em `openclaw/clawgrit-reports` sob `openclaw-performance//-//`. O ponteiro atual do ref testado é escrito como `openclaw-performance//latest-.json`. -## Validação Completa de Release +## Full Release Validation -`Full Release Validation` é o workflow manual guarda-chuva para "executar tudo antes da release." Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para comprovação exclusiva de release de plugin/pacote/estática/Docker e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release Docker, live/E2E, OpenWebUI, paridade QA Lab, Matrix e lanes Telegram. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Depois da publicação, passe `npm_telegram_package_spec` para reexecutar a mesma lane de pacote Telegram contra o pacote npm publicado. +`Full Release Validation` é o workflow guarda-chuva manual para "executar tudo antes da release". Ele aceita uma branch, tag ou SHA de commit completo, despacha o workflow manual `CI` com esse alvo, despacha `Plugin Prerelease` para prova exclusiva de release de plugin/pacote/estática/Docker e despacha `OpenClaw Release Checks` para install smoke, aceitação de pacote, verificações de pacote entre sistemas operacionais, paridade do QA Lab, Matrix e lanes do Telegram. Execuções estáveis/padrão mantêm cobertura exaustiva live/E2E e de caminho de release Docker atrás de `run_release_soak=true`; `release_profile=full` força essa cobertura de soak para que validações amplas de advisory continuem amplas. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Após publicar, passe `npm_telegram_package_spec` para reexecutar o mesmo lane de pacote Telegram contra o pacote npm publicado. -Consulte [validação completa de release](/pt-BR/reference/full-release-validation) para a matriz de estágios, nomes exatos de jobs do workflow, diferenças de perfil, artefatos e identificadores de reexecução focada. +Consulte [Validação completa de release](/pt-BR/reference/full-release-validation) para a +matriz de estágios, nomes exatos dos jobs de workflow, diferenças de perfil, artefatos e +identificadores de reexecução focada. -`OpenClaw Release Publish` é o workflow manual mutável de release. Dispare-o de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o preflight npm do OpenClaw tiver sido concluído com sucesso. Ele verifica `pnpm plugins:sync:check`, dispara `Plugin NPM Release` para todos os pacotes de Plugin publicáveis, dispara `Plugin ClawHub Release` para o mesmo SHA de release e só então dispara `OpenClaw NPM Release` com o `preflight_run_id` salvo. +`OpenClaw Release Publish` é o workflow manual mutável de release. Despache-o +a partir de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o +preflight npm do OpenClaw tiver sido bem-sucedido. Ele verifica `pnpm plugins:sync:check`, +despacha `Plugin NPM Release` para todos os pacotes de Plugin publicáveis, despacha +`Plugin ClawHub Release` para o mesmo SHA de release e só então despacha +`OpenClaw NPM Release` com o `preflight_run_id` salvo. ```bash gh workflow run openclaw-release-publish.yml \ @@ -173,35 +180,45 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Para comprovação de commit fixado em uma branch que se move rápido, use o helper em vez de `gh workflow run ... --ref main -f ref=`: +Para prova de commit fixado em uma branch que muda rapidamente, use o helper em vez de +`gh workflow run ... --ref main -f ref=`: ```bash pnpm ci:full-release --sha ``` -Refs de dispatch de workflow do GitHub devem ser branches ou tags, não SHAs brutos de commit. O helper envia uma branch temporária `release-ci/-...` no SHA alvo, dispara `Full Release Validation` a partir dessa ref fixada, verifica se cada `headSha` de workflow filho corresponde ao alvo e exclui a branch temporária quando a execução termina. O verificador guarda-chuva também falha se qualquer workflow filho tiver executado em um SHA diferente. +Refs de despacho de workflow do GitHub devem ser branches ou tags, não SHAs de commit brutos. O +helper envia uma branch temporária `release-ci/-...` no SHA de destino, +despacha `Full Release Validation` a partir desse ref fixado, verifica se cada `headSha` +de workflow filho corresponde ao alvo e exclui a branch temporária quando a +execução termina. O verificador guarda-chuva também falha se qualquer workflow filho for executado em um +SHA diferente. -`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os fluxos de trabalho manuais de lançamento usam `stable` por padrão; use `full` somente quando você intencionalmente quiser a matriz ampla consultiva de provedores/mídia. +`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os fluxos de trabalho manuais de lançamento usam `stable` por padrão; use `full` apenas quando você intencionalmente quiser a ampla matriz consultiva de provedores/mídia. `run_release_soak` controla se as verificações de lançamento estáveis/padrão executam o soak exaustivo live/E2E e do caminho de lançamento do Docker; `full` força o soak. -- `minimum` mantém as linhas OpenAI/núcleo críticas para lançamento mais rápidas. +- `minimum` mantém as lanes críticas de lançamento mais rápidas de OpenAI/core. - `stable` adiciona o conjunto estável de provedores/backends. -- `full` executa a matriz ampla consultiva de provedores/mídia. +- `full` executa a ampla matriz consultiva de provedores/mídia. -O guarda-chuva registra os ids das execuções filhas disparadas, e o trabalho final `Verify full validation` verifica novamente as conclusões atuais das execuções filhas e acrescenta tabelas dos trabalhos mais lentos de cada execução filha. Se um fluxo de trabalho filho for reexecutado e ficar verde, reexecute apenas o trabalho verificador pai para atualizar o resultado guarda-chuva e o resumo de tempos. +O guarda-chuva registra os ids das execuções filhas despachadas, e o job final `Verify full validation` verifica novamente as conclusões atuais das execuções filhas e acrescenta tabelas dos jobs mais lentos para cada execução filha. Se um fluxo de trabalho filho for reexecutado e ficar verde, reexecute apenas o job verificador pai para atualizar o resultado do guarda-chuva e o resumo de tempos. -Para recuperação, tanto `Full Release Validation` quanto `OpenClaw Release Checks` aceitam `rerun_group`. Use `all` para um candidato a lançamento, `ci` apenas para o filho de CI completo normal, `plugin-prerelease` apenas para o filho de pré-lançamento de plugins, `release-checks` para todos os filhos de lançamento, ou um grupo mais estreito: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` no guarda-chuva. Isso mantém limitada a reexecução de uma caixa de lançamento com falha após uma correção focada. +Para recuperação, tanto `Full Release Validation` quanto `OpenClaw Release Checks` aceitam `rerun_group`. Use `all` para um candidato a lançamento, `ci` somente para o filho normal de CI completo, `plugin-prerelease` somente para o filho de pré-lançamento de plugin, `release-checks` para todos os filhos de lançamento, ou um grupo mais estreito: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` no guarda-chuva. Isso mantém limitada a reexecução de uma caixa de lançamento com falha após uma correção focada. Para uma lane cross-OS com falha, combine `rerun_group=cross-os` com `cross_os_suite_filter`, por exemplo `windows/packaged-upgrade`; comandos cross-OS longos emitem linhas de heartbeat, e resumos packaged-upgrade incluem tempos por fase. Lanes de verificação de lançamento de QA são consultivas, então falhas somente de QA avisam, mas não bloqueiam o verificador de release-check. -`OpenClaw Release Checks` usa a ref confiável do fluxo de trabalho para resolver a ref selecionada uma vez em um tarball `release-package-under-test`, depois passa esse artefato tanto para o fluxo de trabalho Docker live/E2E do caminho de lançamento quanto para o shard de aceitação de pacote. Isso mantém os bytes do pacote consistentes entre as caixas de lançamento e evita reempacotar o mesmo candidato em vários trabalhos filhos. +`OpenClaw Release Checks` usa a referência confiável do fluxo de trabalho para resolver a ref selecionada uma vez em um tarball `release-package-under-test`, depois passa esse artefato para verificações cross-OS e Package Acceptance, além do fluxo de trabalho Docker live/E2E do caminho de lançamento quando a cobertura de soak é executada. Isso mantém os bytes do pacote consistentes entre caixas de lançamento e evita reempacotar o mesmo candidato em vários jobs filhos. -Execuções duplicadas de `Full Release Validation` para `ref=main` e `rerun_group=all` substituem o guarda-chuva mais antigo. O monitor pai cancela qualquer fluxo de trabalho filho que já tenha disparado quando o pai é cancelado, então a validação mais nova da main não fica atrás de uma execução obsoleta de duas horas de verificações de lançamento. A validação de branch/tag de lançamento e grupos de reexecução focados mantêm `cancel-in-progress: false`. +Execuções duplicadas de `Full Release Validation` para `ref=main` e `rerun_group=all` +substituem o guarda-chuva mais antigo. O monitor pai cancela qualquer fluxo de trabalho filho que +já tenha despachado quando o pai é cancelado, então a validação mais nova de main +não fica atrás de uma execução obsoleta de duas horas de release-check. Validações de branch/tag +de lançamento e grupos de reexecução focada mantêm `cancel-in-progress: false`. -## Shards live e E2E +## Fragmentos live e E2E -O filho live/E2E de lançamento mantém cobertura ampla nativa de `pnpm test:live`, mas a executa como shards nomeados por meio de `scripts/test-live-shard.mjs` em vez de um trabalho serial: +O filho live/E2E de lançamento mantém ampla cobertura nativa de `pnpm test:live`, mas a executa como fragmentos nomeados por meio de `scripts/test-live-shard.mjs` em vez de um job serial: - `native-live-src-agents` - `native-live-src-gateway-core` -- trabalhos `native-live-src-gateway-profiles` filtrados por provedor +- jobs `native-live-src-gateway-profiles` filtrados por provedor - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -209,57 +226,59 @@ O filho live/E2E de lançamento mantém cobertura ampla nativa de `pnpm test:liv - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- shards de áudio/vídeo de mídia divididos e shards de música filtrados por provedor +- fragmentos separados de mídia de áudio/vídeo e fragmentos de música filtrados por provedor -Isso mantém a mesma cobertura de arquivos enquanto torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes de shard agregados `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` continuam válidos para reexecuções manuais únicas. +Isso mantém a mesma cobertura de arquivos e torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes agregados de fragmentos `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` continuam válidos para reexecuções manuais únicas. -Os shards nativos de mídia live executam em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo fluxo de trabalho `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; os trabalhos de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners Blacksmith normais — trabalhos em contêiner são o lugar errado para iniciar testes Docker aninhados. +Os fragmentos nativos de mídia live são executados em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo fluxo de trabalho `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; jobs de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners normais da Blacksmith — jobs em contêiner são o lugar errado para iniciar testes Docker aninhados. -Shards live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:` por commit selecionado. O fluxo de trabalho live de lançamento cria e envia essa imagem uma vez, depois os shards de modelo live Docker, Gateway divididos por provedor, backend CLI, vínculo ACP e harness Codex executam com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shards Docker do Gateway carregam limites explícitos de `timeout` em nível de script abaixo do timeout do trabalho do fluxo de trabalho, para que um contêiner travado ou caminho de limpeza falhe rápido em vez de consumir todo o orçamento das verificações de lançamento. Se esses shards recriarem o alvo Docker de código-fonte completo independentemente, a execução de lançamento está mal configurada e desperdiçará tempo de relógio com builds duplicados de imagem. +Fragmentos live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:` por commit selecionado. O fluxo de trabalho live de lançamento cria e envia essa imagem uma vez, depois os fragmentos de modelo live Docker, Gateway dividido por provedor, backend de CLI, vínculo ACP e harness Codex executam com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Fragmentos Docker de Gateway carregam limites explícitos de `timeout` no nível do script abaixo do timeout do job do fluxo de trabalho para que um contêiner travado ou caminho de limpeza falhe rápido em vez de consumir todo o orçamento de release-check. Se esses fragmentos reconstruírem independentemente o alvo Docker completo do código-fonte, a execução de lançamento está configurada incorretamente e desperdiçará tempo de relógio em builds duplicados de imagem. -## Aceitação de Pacote +## Package Acceptance -Use `Package Acceptance` quando a pergunta for "este pacote OpenClaw instalável funciona como produto?" Ela é diferente da CI normal: a CI normal valida a árvore de código-fonte, enquanto a aceitação de pacote valida um único tarball pelo mesmo harness Docker E2E que os usuários exercitam após instalar ou atualizar. +Use `Package Acceptance` quando a pergunta for “este pacote instalável do OpenClaw funciona como produto?”. Ele é diferente do CI normal: o CI normal valida a árvore de código-fonte, enquanto o package acceptance valida um único tarball pelo mesmo harness Docker E2E que usuários exercitam após instalar ou atualizar. -### Trabalhos +### Jobs -1. `resolve_package` faz checkout de `workflow_ref`, resolve um candidato de pacote, grava `.artifacts/docker-e2e-package/openclaw-current.tgz`, grava `.artifacts/docker-e2e-package/package-candidate.json`, envia ambos como o artefato `package-under-test` e imprime a origem, ref do fluxo de trabalho, ref do pacote, versão, SHA-256 e perfil no resumo da etapa do GitHub. -2. `docker_acceptance` chama `openclaw-live-and-e2e-checks-reusable.yml` com `ref=workflow_ref` e `package_artifact_name=package-under-test`. O fluxo de trabalho reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker de resumo de pacote quando necessário e executa as linhas Docker selecionadas contra esse pacote em vez de empacotar o checkout do fluxo de trabalho. Quando um perfil seleciona vários `docker_lanes` direcionados, o fluxo de trabalho reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas linhas como trabalhos Docker direcionados paralelos com artefatos únicos. -3. `package_telegram` opcionalmente chama `NPM Telegram Beta E2E`. Ele executa quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando Package Acceptance resolveu um; um disparo autônomo do Telegram ainda pode instalar uma especificação npm publicada. -4. `summary` falha o fluxo de trabalho se a resolução do pacote, a aceitação Docker ou a linha opcional do Telegram falhar. +1. `resolve_package` faz checkout de `workflow_ref`, resolve um candidato de pacote, escreve `.artifacts/docker-e2e-package/openclaw-current.tgz`, escreve `.artifacts/docker-e2e-package/package-candidate.json`, envia ambos como o artefato `package-under-test` e imprime a fonte, a ref do fluxo de trabalho, a ref do pacote, a versão, o SHA-256 e o perfil no resumo de etapa do GitHub. +2. `docker_acceptance` chama `openclaw-live-and-e2e-checks-reusable.yml` com `ref=workflow_ref` e `package_artifact_name=package-under-test`. O fluxo de trabalho reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker com digest do pacote quando necessário e executa as lanes Docker selecionadas contra esse pacote em vez de empacotar o checkout do fluxo de trabalho. Quando um perfil seleciona vários `docker_lanes` direcionados, o fluxo de trabalho reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas lanes como jobs Docker direcionados paralelos com artefatos únicos. +3. `package_telegram` opcionalmente chama `NPM Telegram Beta E2E`. Ele é executado quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando Package Acceptance resolveu um; um despacho autônomo do Telegram ainda pode instalar uma especificação npm publicada. +4. `summary` falha o fluxo de trabalho se a resolução do pacote, a aceitação Docker ou a lane opcional do Telegram falhar. -### Origens de candidatos +### Fontes de candidatos -- `source=npm` aceita somente `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isso para aceitação de pré-lançamento/estável publicado. -- `source=ref` empacota um branch, tag ou SHA completo de commit confiável em `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável pelo histórico de branches do repositório ou por uma tag de lançamento, instala dependências em uma árvore de trabalho destacada e o empacota com `scripts/package-openclaw-for-docker.mjs`. +- `source=npm` aceita apenas `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isto para aceitação de pré-lançamento/estável publicado. +- `source=ref` empacota uma branch, tag ou SHA completo de commit confiável de `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável pelo histórico de branches do repositório ou por uma tag de lançamento, instala dependências em uma worktree destacada e o empacota com `scripts/package-openclaw-for-docker.mjs`. - `source=url` baixa um `.tgz` HTTPS; `package_sha256` é obrigatório. - `source=artifact` baixa um `.tgz` de `artifact_run_id` e `artifact_name`; `package_sha256` é opcional, mas deve ser fornecido para artefatos compartilhados externamente. -Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código confiável de fluxo de trabalho/harness que executa o teste. `package_ref` é o commit de origem que é empacotado quando `source=ref`. Isso permite que o harness de teste atual valide commits de origem confiáveis mais antigos sem executar lógica antiga de fluxo de trabalho. +Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código confiável do fluxo de trabalho/harness que executa o teste. `package_ref` é o commit de origem que é empacotado quando `source=ref`. Isso permite que o harness de teste atual valide commits de origem confiáveis mais antigos sem executar lógica antiga de fluxo de trabalho. ### Perfis de suíte - `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update` - `product` — `package` mais `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full` — blocos completos Docker do caminho de lançamento com OpenWebUI +- `full` — blocos completos do caminho de lançamento Docker com OpenWebUI - `custom` — `docker_lanes` exatos; obrigatório quando `suite_profile=custom` -O perfil `package` usa cobertura offline de plugins para que a validação de pacote publicado não dependa da disponibilidade live do ClawHub. A linha opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho de especificação npm publicada para disparos autônomos. +O perfil `package` usa cobertura offline de plugins para que a validação de pacote publicado não dependa da disponibilidade live do ClawHub. A lane opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho de especificação npm publicada para despachos autônomos. -Para a política dedicada de testes de atualização e plugins, incluindo comandos locais, linhas Docker, entradas de Package Acceptance, padrões de lançamento e triagem de falhas, consulte [Testar atualizações e plugins](/pt-BR/help/testing-updates-plugins). +Para a política dedicada de testes de atualização e plugin, incluindo comandos locais, +lanes Docker, entradas de Package Acceptance, padrões de lançamento e triagem de falhas, +consulte [Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins). -As verificações de lançamento chamam Package Acceptance com `source=artifact`, o artefato de pacote de lançamento preparado, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` e `telegram_mode=mock-openai`. Isso mantém a prova de migração de pacote, atualização, limpeza de dependência obsoleta de plugin, reparo de instalação de plugin configurado, plugin offline, atualização de plugin e Telegram no mesmo tarball de pacote resolvido. Defina `package_acceptance_package_spec` em Full Release Validation ou OpenClaw Release Checks para executar essa mesma matriz contra um pacote npm enviado em vez do artefato criado a partir do SHA. As verificações de lançamento entre sistemas operacionais ainda cobrem integração inicial específica de SO, instalador e comportamento de plataforma; a validação de produto de pacote/atualização deve começar com Package Acceptance. A linha Docker `published-upgrade-survivor` valida uma linha de base de pacote publicado por execução. Em Package Acceptance, o tarball `package-under-test` resolvido é sempre o candidato, e `published_upgrade_survivor_baseline` seleciona a linha de base publicada de fallback, com padrão `openclaw@latest`; comandos de reexecução de linha com falha preservam essa linha de base. Defina `published_upgrade_survivor_baselines=all-since-2026.4.23` para expandir a CI de Full Release por todos os lançamentos npm estáveis de `2026.4.23` até `latest`; `release-history` continua disponível para amostragem manual mais ampla com a âncora pré-data mais antiga. Defina `published_upgrade_survivor_scenarios=reported-issues` para expandir as mesmas linhas de base por fixtures em formato de issues para configuração do Feishu, arquivos bootstrap/persona preservados, instalações configuradas de plugin OpenClaw, caminhos de log com til e raízes obsoletas de dependência de plugins legados. O fluxo de trabalho separado `Update Migration` usa a linha Docker `update-migration` com `all-since-2026.4.23` e `plugin-deps-cleanup` quando a pergunta é limpeza exaustiva de atualização publicada, não a amplitude normal da CI de Full Release. Execuções agregadas locais podem passar especificações exatas de pacote com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, manter uma única linha com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, como `openclaw@2026.4.15`, ou definir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` para a matriz de cenários. A linha publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, registra etapas da receita em `summary.json` e sonda `/healthz`, `/readyz`, além do status RPC após o início do Gateway. As linhas frescas empacotadas e de instalador do Windows também verificam que um pacote instalado consegue importar uma substituição de controle de navegador de um caminho Windows absoluto bruto. O smoke de turno de agente OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, `openai/gpt-5.4`, para que a prova de instalação e Gateway permaneça em um modelo de teste GPT-5 enquanto evita padrões GPT-4.x. +As verificações de lançamento chamam Package Acceptance com `source=artifact`, o artefato de pacote de lançamento preparado, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` e `telegram_mode=mock-openai`. Isso mantém a prova de migração de pacote, atualização, limpeza de dependência obsoleta de plugin, reparo de instalação de plugin configurado, plugin offline, atualização de plugin e Telegram no mesmo tarball de pacote resolvido. Defina `package_acceptance_package_spec` em Full Release Validation ou OpenClaw Release Checks para executar essa mesma matriz contra um pacote npm enviado em vez do artefato criado a partir do SHA. Verificações de lançamento cross-OS ainda cobrem onboarding, instalador e comportamento de plataforma específicos de SO; a validação de produto de pacote/atualização deve começar com Package Acceptance. A lane Docker `published-upgrade-survivor` valida uma linha de base de pacote publicado por execução no caminho de lançamento bloqueante. Em Package Acceptance, o tarball `package-under-test` resolvido é sempre o candidato, e `published_upgrade_survivor_baseline` seleciona a linha de base publicada alternativa, com padrão `openclaw@latest`; comandos de reexecução de lane com falha preservam essa linha de base. Full Release Validation com `run_release_soak=true` ou `release_profile=full` define `published_upgrade_survivor_baselines=all-since-2026.4.23` e `published_upgrade_survivor_scenarios=reported-issues` para expandir por todos os lançamentos npm estáveis de `2026.4.23` até `latest` e fixtures com formato de issues para configuração do Feishu, arquivos bootstrap/persona preservados, instalações configuradas de plugins OpenClaw, caminhos de log com til e raízes obsoletas de dependências legadas de plugins. O fluxo de trabalho separado `Update Migration` usa a lane Docker `update-migration` com `all-since-2026.4.23` e `plugin-deps-cleanup` quando a pergunta é limpeza exaustiva de atualização publicada, não a amplitude normal do Full Release CI. Execuções agregadas locais podem passar especificações exatas de pacote com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, manter uma única lane com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, como `openclaw@2026.4.15`, ou definir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` para a matriz de cenários. A lane publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, registra etapas da receita em `summary.json` e sonda `/healthz`, `/readyz`, além do status RPC após o início do Gateway. As lanes fresh empacotada e de instalador do Windows também verificam se um pacote instalado consegue importar uma substituição de controle de navegador de um caminho absoluto bruto do Windows. O smoke cross-OS de turno de agente OpenAI usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, `openai/gpt-5.4`, para que a prova de instalação e Gateway permaneça em um modelo de teste GPT-5 evitando padrões GPT-4.x. ### Janelas de compatibilidade legada Package Acceptance tem janelas limitadas de compatibilidade legada para pacotes já publicados. Pacotes até `2026.4.25`, incluindo `2026.4.25-beta.*`, podem usar o caminho de compatibilidade: -- entradas QA privadas conhecidas em `dist/postinstall-inventory.json` podem apontar para arquivos omitidos do tarball; -- `doctor-switch` pode pular o subcaso de persistência de `gateway install --wrapper` quando o pacote não expõe essa flag; -- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes da fixture git falsa derivada do tarball e pode registrar `update.channel` persistido ausente; +- entradas privadas de QA conhecidas em `dist/postinstall-inventory.json` podem apontar para arquivos omitidos do tarball; +- `doctor-switch` pode pular o subcaso de persistência `gateway install --wrapper` quando o pacote não expõe essa flag; +- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes do fixture git falso derivado do tarball e pode registrar `update.channel` persistido ausente; - smokes de plugin podem ler locais legados de registro de instalação ou aceitar persistência ausente de registro de instalação do marketplace; -- `plugin-update` pode permitir migração de metadados de configuração enquanto ainda exige que o registro de instalação e o comportamento de não reinstalação permaneçam inalterados. +- `plugin-update` pode permitir migração de metadados de configuração enquanto ainda exige que o registro de instalação e o comportamento de não reinstalar permaneçam inalterados. O pacote publicado `2026.4.26` também pode avisar sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores devem satisfazer os contratos modernos; as mesmas condições falham em vez de avisar ou pular. @@ -304,110 +323,110 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo de `resolve_package` para confirmar a origem do pacote, a versão e o SHA-256. Em seguida, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de reexecução. Prefira reexecutar o perfil de pacote com falha ou as lanes Docker exatas em vez de reexecutar a validação completa de lançamento. +Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo `resolve_package` para confirmar a origem, a versão e o SHA-256 do pacote. Em seguida, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de reexecução. Prefira reexecutar o perfil de pacote com falha ou as lanes Docker exatas em vez de reexecutar a validação completa de release. ## Smoke de instalação -O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio do próprio job `preflight`. Ele divide a cobertura smoke em `run_fast_install_smoke` e `run_full_install_smoke`. +O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio de seu próprio job `preflight`. Ele divide a cobertura de smoke em `run_fast_install_smoke` e `run_full_install_smoke`. -- **Caminho rápido** é executado para pull requests que tocam superfícies Docker/pacote, alterações em pacote/manifesto de Plugin empacotado ou superfícies centrais de Plugin/canal/Gateway/Plugin SDK exercitadas pelos jobs de smoke Docker. Alterações somente de código-fonte em Plugin empacotado, edições somente de teste e edições somente de documentação não reservam workers Docker. O caminho rápido cria a imagem do Dockerfile raiz uma vez, verifica a CLI, executa o smoke de CLI de exclusão de agentes em workspace compartilhado, executa o E2E de rede do Gateway em contêiner, verifica um argumento de build de extensão empacotada e executa o perfil Docker limitado de Plugin empacotado sob um timeout agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente). -- **Caminho completo** mantém a cobertura de instalação de pacote QR e Docker/atualização do instalador para execuções agendadas noturnas, disparos manuais, verificações de lançamento por chamada de workflow e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, o install-smoke prepara ou reutiliza uma imagem smoke GHCR do Dockerfile raiz para o SHA de destino e, então, executa a instalação de pacote QR, smokes do Dockerfile raiz/Gateway, smokes de instalador/atualização e o E2E Docker rápido de Plugin empacotado como jobs separados para que o trabalho de instalador não espere atrás dos smokes da imagem raiz. +- **Caminho rápido** é executado para pull requests que tocam superfícies Docker/pacote, alterações em pacote/manifesto de plugin incluído ou superfícies principais de plugin/canal/gateway/Plugin SDK que os jobs de smoke Docker exercitam. Alterações apenas em código-fonte de plugins incluídos, edições apenas de testes e edições apenas de documentação não reservam workers Docker. O caminho rápido compila a imagem do Dockerfile raiz uma vez, verifica a CLI, executa o smoke da CLI de exclusão de agents em workspace compartilhado, executa o e2e de gateway-network do contêiner, verifica um argumento de build de extensão incluída e executa o perfil Docker limitado de plugin incluído sob um timeout agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente). +- **Caminho completo** mantém a instalação de pacote QR e a cobertura Docker/de atualização do instalador para execuções noturnas agendadas, dispatches manuais, verificações de release por workflow-call e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, install-smoke prepara ou reutiliza uma imagem de smoke GHCR do Dockerfile raiz para o SHA de destino, depois executa instalação de pacote QR, smokes do Dockerfile raiz/gateway, smokes de instalador/atualização e o Docker E2E rápido de plugin incluído como jobs separados, para que o trabalho do instalador não espere atrás dos smokes da imagem raiz. -Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de alterações solicitaria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke completo de instalação para a validação noturna ou de lançamento. +Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de alterações pediria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke completo de instalação para a validação noturna ou de release. -O smoke lento de provedor de imagem com instalação global via Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele é executado na agenda noturna e a partir do workflow de verificações de lançamento, e disparos manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação. +O smoke lento do provedor de imagens com instalação global Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele é executado na agenda noturna e a partir do workflow de verificações de release, e dispatches manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação. -## E2E Docker local +## Docker E2E local -`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e cria duas imagens compartilhadas de `scripts/e2e/Dockerfile`: +`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e compila duas imagens compartilhadas de `scripts/e2e/Dockerfile`: -- um runner básico Node/Git para lanes de instalador/atualização/dependência de Plugin; -- uma imagem funcional que instala o mesmo tarball em `/app` para lanes de funcionalidade normal. +- um runner Node/Git básico para lanes de instalador/atualização/dependência de plugin; +- uma imagem funcional que instala o mesmo tarball em `/app` para lanes de funcionalidade normais. -As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois executa as lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`. +As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois executa lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`. -### Parâmetros ajustáveis +### Ajustes -| Variável | Padrão | Finalidade | -| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live concorrentes para que provedores não apliquem throttling. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes concorrentes de instalação npm. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes concorrentes com múltiplos serviços. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo escalonado entre inícios de lanes para evitar tempestades de criação no daemon Docker; defina `0` para sem escalonamento. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais estritos. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista separada por vírgulas de lanes exatas; pula o smoke de limpeza para que agentes possam reproduzir uma lane com falha. | +| Variável | Padrão | Finalidade | +| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live simultâneas para que os provedores não façam throttle. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes simultâneas de instalação npm. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes simultâneas com múltiplos serviços. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo entre inícios de lanes para evitar tempestades de criação no daemon Docker; defina `0` para não escalonar. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais rígidos. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista de lanes exatas separadas por vírgulas; pula o smoke de limpeza para que agents possam reproduzir uma lane com falha. | -Uma lane mais pesada que seu limite efetivo ainda pode começar de um pool vazio e, então, roda sozinha até liberar capacidade. Os preflights agregados locais verificam o Docker, removem contêineres E2E obsoletos do OpenClaw, emitem status de lanes ativas, persistem tempos de lanes para ordenação da mais longa para a mais curta e param de agendar novas lanes em pool após a primeira falha por padrão. +Uma lane mais pesada do que seu limite efetivo ainda pode iniciar a partir de um pool vazio, depois roda sozinha até liberar capacidade. Os preflights agregados locais verificam o Docker, removem contêineres OpenClaw E2E obsoletos, emitem status de lanes ativas, persistem tempos de lanes para ordenação pelas mais longas primeiro e, por padrão, param de agendar novas lanes em pool após a primeira falha. ### Workflow live/E2E reutilizável -O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual pacote, tipo de imagem, imagem live, lane e cobertura de credenciais são necessários. `scripts/docker-e2e.mjs` então converte esse plano em saídas e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; cria e envia imagens Docker E2E bare/funcionais GHCR marcadas com digest de pacote por meio do cache de camadas Docker do Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidas ou imagens existentes com digest de pacote em vez de reconstruir. Pulls de imagens Docker são repetidos com um timeout limitado de 180 segundos por tentativa para que um fluxo travado de registro/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico da CI. +O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual pacote, tipo de imagem, imagem live, lane e cobertura de credenciais são necessários. `scripts/docker-e2e.mjs` então converte esse plano em outputs e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; compila e envia imagens Docker E2E GHCR básicas/funcionais marcadas pelo digest do pacote por meio do cache de camadas Docker da Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidas ou imagens existentes por digest de pacote em vez de recompilar. Pulls de imagens Docker são repetidos com um timeout limitado de 180 segundos por tentativa, para que um stream preso de registry/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico da CI. -### Fragmentos do caminho de lançamento +### Chunks do caminho de release -A cobertura Docker de lançamento executa jobs menores em fragmentos com `OPENCLAW_SKIP_DOCKER_BUILD=1`, de modo que cada fragmento puxe apenas o tipo de imagem de que precisa e execute várias lanes pelo mesmo agendador ponderado: +A cobertura Docker de release executa jobs menores em chunks com `OPENCLAW_SKIP_DOCKER_BUILD=1`, para que cada chunk puxe apenas o tipo de imagem de que precisa e execute várias lanes pelo mesmo agendador ponderado: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -Os fragmentos Docker de lançamento atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` permanecem aliases agregados de Plugin/runtime. O alias de lane `install-e2e` permanece o alias agregado de reexecução manual para ambas as lanes de instalador de provedor. +Os chunks Docker de release atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` permanecem aliases agregados de plugin/runtime. O alias de lane `install-e2e` permanece o alias agregado de reexecução manual para ambas as lanes de instalador de provedor. -OpenWebUI é incorporado em `plugins-runtime-services` quando a cobertura completa de release-path o solicita, e mantém um fragmento independente `openwebui` apenas para disparos somente do OpenWebUI. Lanes de atualização de canais empacotados tentam novamente uma vez em caso de falhas transitórias de rede npm. +OpenWebUI é incorporado a `plugins-runtime-services` quando a cobertura completa do caminho de release o solicita, e mantém um chunk autônomo `openwebui` apenas para dispatches somente de OpenWebUI. Lanes de atualização de canais incluídos tentam novamente uma vez em caso de falhas transitórias de rede npm. -Cada fragmento faz upload de `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do workflow executa lanes selecionadas contra as imagens preparadas em vez dos jobs de fragmento, o que mantém a depuração de lane com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado cria a imagem de teste live localmente para essa reexecução. Comandos gerados de reexecução por lane no GitHub incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagem preparadas quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha. +Cada chunk envia `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do workflow executa lanes selecionadas contra as imagens preparadas em vez dos jobs de chunk, o que mantém a depuração de lanes com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado compila a imagem de teste live localmente para essa reexecução. Comandos de reexecução do GitHub gerados por lane incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagens preparadas quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha. ```bash pnpm test:docker:rerun # 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 de release-path. +O workflow live/E2E agendado executa diariamente a suíte Docker completa do caminho de release. -## Pré-lançamento de Plugin +## Pré-release de Plugin -`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, portanto é um workflow separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e disparos manuais independentes de CI mantêm essa suíte desativada. Ele balanceia testes de Plugins empacotados entre oito workers de extensão; esses jobs de shard de extensão executam até dois grupos de configuração de Plugin por vez, com um worker Vitest por grupo e um heap Node maior para que lotes de Plugins pesados em importação não criem jobs extras de CI. O caminho Docker de pré-lançamento exclusivo de lançamento agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos. +`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, portanto é um workflow separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e dispatches manuais autônomos de CI mantêm essa suíte desativada. Ele balanceia testes de plugins incluídos entre oito workers de extensão; esses jobs de shards de extensão executam até dois grupos de configuração de plugin por vez, com um worker Vitest por grupo e um heap Node maior, para que lotes de plugins pesados em imports não criem jobs extras de CI. O caminho Docker de pré-release somente para release agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos. ## QA Lab -O QA Lab tem lanes dedicadas de CI fora do workflow principal com escopo inteligente. A paridade agêntica fica aninhada sob os harnesses amplos de QA e lançamento, não como um workflow autônomo de PR. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação. +QA Lab tem lanes de CI dedicadas fora do workflow principal com escopo inteligente. A paridade agentic fica aninhada nos harnesses amplos de QA e release, não em um workflow autônomo de PR. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação. -- O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e por disparo manual; ele distribui a lane de paridade mock, a lane live Matrix e as lanes live Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases Convex. +- O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e em dispatch manual; ele distribui em leque a lane de paridade mock, a lane live Matrix e as lanes live Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases Convex. -As verificações de lançamento executam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`) para que o contrato do canal fique isolado da latência de modelos live e da inicialização normal de Plugin de provedor. O Gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker. +As verificações de release executam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`), para que o contrato de canal fique isolado da latência de modelo live e da inicialização normal de plugin de provedor. O gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker. -Matrix usa `--profile fast` para gates agendados e de lançamento, adicionando `--fail-fast` apenas quando a CLI em checkout oferece suporte a isso. O padrão da CLI e a entrada manual do workflow permanecem `all`; o disparo manual `matrix_profile=all` sempre fragmenta a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. +Matrix usa `--profile fast` para gates agendados e de release, adicionando `--fail-fast` apenas quando a CLI com checkout dá suporte a isso. O padrão da CLI e a entrada manual do workflow permanecem `all`; dispatch manual `matrix_profile=all` sempre fragmenta a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. -`OpenClaw Release Checks` também executa as lanes críticas de lançamento do QA Lab antes da aprovação de lançamento; seu gate de paridade de QA executa os pacotes candidato e baseline como jobs de lanes paralelos e, então, baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade. +`OpenClaw Release Checks` também executa as lanes críticas de release do QA Lab antes da aprovação de release; seu gate de paridade de QA executa os pacotes candidato e baseline como jobs de lane paralelos, depois baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade. -Para PRs normais, siga evidências de CI/verificações com escopo em vez de tratar a paridade como um status obrigatório. +Para PRs normais, siga evidências de CI/check com escopo em vez de tratar a paridade como um status obrigatório. ## CodeQL -O fluxo de trabalho `CodeQL` é intencionalmente um verificador de segurança inicial e estreito, não uma varredura completa do repositório. Execuções de proteção diárias, manuais e de solicitações de pull não rascunho verificam o código de fluxos de trabalho do Actions, além das superfícies JavaScript/TypeScript de maior risco, com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica. +O workflow `CodeQL` é intencionalmente um scanner de segurança inicial restrito, não uma varredura completa do repositório. Execuções diárias, manuais e de proteção de pull requests que não são rascunho escaneiam código de workflows do Actions e as superfícies JavaScript/TypeScript de maior risco com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica. -A proteção de solicitação de pull permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança do fluxo de trabalho agendado. CodeQL para Android e macOS fica fora dos padrões de PR. +A proteção de pull request permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança do workflow agendado. O CodeQL de Android e macOS fica fora dos padrões de PR. ### Categorias de segurança -| Categoria | Superfície | +| Categoria | Superfície | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, cron e Gateway | -| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do núcleo, além do runtime do plugin de canal, Gateway, Plugin SDK, segredos e pontos de auditoria | -| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do núcleo, análise de IP, proteção de rede, busca web e política de SSRF do Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, auxiliares de execução de processo, entrega de saída e proteções de execução de ferramentas de agentes | -| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, carregador, manifesto, registro, instalação do gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK | +| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, Cron e Gateway | +| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do core mais o runtime de Plugin de canal, Gateway, Plugin SDK, segredos e pontos de contato de auditoria | +| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do core, parsing de IP, proteção de rede, web-fetch e política de SSRF do Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, helpers de execução de processos, entrega de saída e gates de execução de ferramentas de agentes | +| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, loader, manifesto, registro, instalação por gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK | -### Shards de segurança específicos de plataforma +### Shards de segurança específicos por plataforma -- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o aplicativo Android manualmente para o CodeQL no menor executor Linux do Blacksmith aceito pela sanidade do fluxo de trabalho. Envia em `/codeql-critical-security/android`. -- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o aplicativo macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de compilação de dependências fora do SARIF enviado e envia em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque a compilação do macOS domina o tempo de execução mesmo quando está limpa. +- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o app Android manualmente para o CodeQL no menor runner Blacksmith Linux aceito pela sanidade do workflow. Faz upload em `/codeql-critical-security/android`. +- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o app macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de build de dependências do SARIF enviado e faz upload em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque o build do macOS domina o tempo de execução mesmo quando está limpo. ### Categorias de qualidade crítica -`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript sem segurança e com severidade de erro sobre superfícies estreitas de alto valor no executor Linux menor do Blacksmith. Sua proteção de solicitação de pull é intencionalmente menor que o perfil agendado: PRs não rascunho executam apenas os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de respostas, código de esquema/migração/IO de configuração, código de autenticação/segredos/sandbox/segurança, canal do núcleo e runtime de plugin de canal empacotado, protocolo/método de servidor do Gateway, cola de runtime/SDK de memória, MCP/processo/entrega de saída, catálogo de runtime/modelos de provedores, diagnósticos de sessão/filas de entrega, carregador de Plugin, contrato de Plugin SDK/pacote ou runtime de respostas do Plugin SDK. Alterações na configuração do CodeQL e no fluxo de trabalho de qualidade executam todos os doze shards de qualidade de PR. +`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript de severidade de erro e não relacionadas a segurança sobre superfícies restritas de alto valor no runner Blacksmith Linux menor. Sua proteção de pull request é intencionalmente menor que o perfil agendado: PRs que não são rascunho executam apenas os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de resposta, código de schema/migração/IO de config, código de autenticação/segredos/sandbox/segurança, runtime de canal do core e Plugin de canal incluído, protocolo/método de servidor do Gateway, runtime de memória/cola do SDK, MCP/processo/entrega de saída, catálogo de runtime/modelo de provedor, diagnósticos de sessão/filas de entrega, loader de Plugin, contrato de Plugin SDK/pacote ou runtime de resposta do Plugin SDK. Alterações de configuração do CodeQL e workflow de qualidade executam todos os doze shards de qualidade de PR. O despacho manual aceita: @@ -415,40 +434,40 @@ O despacho manual aceita: profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -Os perfis estreitos são ganchos de ensino/iteração para executar um shard de qualidade isoladamente. +Os perfis restritos são ganchos de ensino/iteração para executar um shard de qualidade isoladamente. -| Categoria | Superfície | +| Categoria | Superfície | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, cron e Gateway | -| `/codeql-critical-quality/config-boundary` | Contratos de esquema, migração, normalização e IO de configuração | -| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas do protocolo do Gateway e contratos de métodos de servidor | -| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do núcleo e de plugin de canal empacotado | -| `/codeql-critical-quality/agent-runtime-boundary` | Execução de comandos, despacho de modelo/provedor, despacho e filas de resposta automática e contratos de runtime do plano de controle ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e pontes de ferramentas, auxiliares de supervisão de processo e contratos de entrega de saída | -| `/codeql-critical-quality/memory-runtime-boundary` | SDK de host de memória, fachadas de runtime de memória, aliases de memória do Plugin SDK, cola de ativação de runtime de memória e comandos doctor de memória | -| `/codeql-critical-quality/session-diagnostics-boundary` | Internos de fila de resposta, filas de entrega de sessão, auxiliares de vinculação/entrega de sessão de saída, superfícies de evento diagnóstico/pacote de logs e contratos de CLI doctor de sessão | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do Plugin SDK, auxiliares de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e auxiliares de vinculação de sessão/thread | -| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de provedores, registro de runtime de provedores, padrões/catálogos de provedores e registros de web/pesquisa/busca/embedding | -| `/codeql-critical-quality/ui-control-plane` | Inicialização da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas | -| `/codeql-critical-quality/web-media-runtime-boundary` | Busca/pesquisa web do núcleo, IO de mídia, compreensão de mídia, geração de imagens e contratos de runtime de geração de mídia | -| `/codeql-critical-quality/plugin-boundary` | Contratos de carregador, registro, superfície pública e pontos de entrada do Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK do lado do pacote publicado e auxiliares de contrato de pacote de plugin | +| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, Cron e Gateway | +| `/codeql-critical-quality/config-boundary` | Schema de configuração, migração, normalização e contratos de IO | +| `/codeql-critical-quality/gateway-runtime-boundary` | Schemas de protocolo do Gateway e contratos de método de servidor | +| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do core e Plugin de canal incluído | +| `/codeql-critical-quality/agent-runtime-boundary` | Execução de comandos, despacho de modelo/provedor, despacho e filas de resposta automática, e contratos de runtime do plano de controle ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e bridges de ferramentas, helpers de supervisão de processos e contratos de entrega de saída | +| `/codeql-critical-quality/memory-runtime-boundary` | SDK do host de memória, facades de runtime de memória, aliases de Plugin SDK de memória, cola de ativação de runtime de memória e comandos doctor de memória | +| `/codeql-critical-quality/session-diagnostics-boundary` | Internos da fila de respostas, filas de entrega de sessão, helpers de vinculação/entrega de sessão de saída, superfícies de eventos diagnósticos/pacote de logs e contratos de CLI de doctor de sessão | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do Plugin SDK, helpers de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e helpers de vinculação de sessão/thread | +| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de provedores, registro de runtime de provedor, padrões/catálogos de provedor e registros de web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | Bootstrap da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas | +| `/codeql-critical-quality/web-media-runtime-boundary` | Fetch/search web do core, IO de mídia, entendimento de mídia, geração de imagens e contratos de runtime de geração de mídia | +| `/codeql-critical-quality/plugin-boundary` | Contratos de loader, registro, superfície pública e ponto de entrada do Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK do lado do pacote publicado e helpers de contrato de pacote de Plugin | -Qualidade fica separada de segurança para que achados de qualidade possam ser agendados, medidos, desativados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e plugins empacotados deve ser adicionada de volta como trabalho de acompanhamento com escopo ou sharding apenas depois que os perfis estreitos tiverem runtime e sinal estáveis. +A qualidade fica separada da segurança para que achados de qualidade possam ser agendados, medidos, desabilitados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e Plugins incluídos deve ser adicionada novamente como trabalho de acompanhamento escopado ou fragmentado apenas depois que os perfis restritos tiverem tempo de execução e sinal estáveis. -## Fluxos de trabalho de manutenção +## Workflows de manutenção ### Docs Agent -O fluxo de trabalho `Docs Agent` é uma via de manutenção do Codex orientada por eventos para manter a documentação existente alinhada com alterações recém-integradas. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` já avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando ele executa, revisa o intervalo de commits desde o SHA de origem anterior não ignorado do Docs Agent até o `main` atual, então uma execução horária pode cobrir todas as alterações em main acumuladas desde a última passagem de documentação. +O workflow `Docs Agent` é uma faixa de manutenção Codex orientada a eventos para manter a documentação existente alinhada com alterações aterrissadas recentemente. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` já avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando executado, ele revisa o intervalo de commits do SHA de origem anterior não ignorado do Docs Agent até o `main` atual, então uma execução horária pode cobrir todas as alterações em main acumuladas desde a última passada de documentação. ### Test Performance Agent -O fluxo de trabalho `Test Performance Agent` é uma via de manutenção do Codex orientada por eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, mas ele é ignorado se outra invocação por workflow-run já foi executada ou está em execução naquele dia UTC. O despacho manual ignora essa proteção de atividade diária. A via cria um relatório de desempenho agrupado de Vitest da suíte completa, permite que o Codex faça apenas pequenas correções de desempenho de testes que preservem a cobertura, em vez de refatorações amplas, depois reexecuta o relatório da suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias, e o relatório da suíte completa pós-agente deve passar antes de qualquer coisa ser commitada. Quando `main` avança antes que o push do bot seja integrado, a via faz rebase do patch validado, reexecuta `pnpm check:changed` e tenta o push novamente; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado no GitHub para que a ação do Codex possa manter a mesma postura de segurança drop-sudo do agente de documentação. +O workflow `Test Performance Agent` é uma faixa de manutenção Codex orientada a eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, mas ele ignora se outra invocação por workflow-run já executou ou está executando naquele dia UTC. O despacho manual contorna esse gate de atividade diária. A faixa gera um relatório agrupado de performance do Vitest para a suíte completa, permite que o Codex faça apenas pequenas correções de performance de testes que preservem cobertura em vez de refatorações amplas, depois reexecuta o relatório da suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias e o relatório da suíte completa após o agente deve passar antes que qualquer coisa seja commitada. Quando `main` avança antes do push do bot aterrissar, a faixa faz rebase do patch validado, reexecuta `pnpm check:changed` e tenta o push novamente; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado pelo GitHub para que a ação Codex possa manter a mesma postura de segurança sem sudo do agente de documentação. ### PRs duplicados após merge -O fluxo de trabalho `Duplicate PRs After Merge` é um fluxo de trabalho manual de mantenedor para limpeza de duplicatas pós-integração. Ele usa dry-run por padrão e só fecha PRs explicitamente listados quando `apply=true`. Antes de alterar o GitHub, ele verifica se o PR integrado foi mesclado e se cada duplicata tem um problema referenciado compartilhado ou hunks alterados sobrepostos. +O workflow `Duplicate PRs After Merge` é um workflow manual de mantenedor para limpeza de duplicatas pós-aterrissagem. Ele usa dry-run por padrão e só fecha PRs listados explicitamente quando `apply=true`. Antes de alterar o GitHub, ele verifica se o PR aterrissado foi mesclado e se cada duplicata tem uma issue referenciada compartilhada ou hunks alterados sobrepostos. ```bash gh workflow run duplicate-after-merge.yml \ @@ -457,29 +476,29 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Proteções de verificação local e roteamento de alterações +## Gates de verificação local e roteamento de alterações -A lógica local de changed-lane vive em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Essa proteção de verificação local é mais estrita sobre fronteiras de arquitetura do que o escopo amplo da plataforma de CI: +A lógica local de changed-lane vive em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate de verificação local é mais rigoroso sobre fronteiras de arquitetura do que o escopo amplo da plataforma de CI: -- alterações de produção do núcleo executam typecheck de produção do núcleo e de testes do núcleo, além de lint/proteções do núcleo; -- alterações apenas em testes do núcleo executam somente typecheck de testes do núcleo, além de lint do núcleo; -- alterações de produção de extensão executam typecheck de produção e de testes de extensão, além de lint de extensão; -- alterações apenas em testes de extensão executam typecheck de testes de extensão, além de lint de extensão; -- alterações no Plugin SDK público ou no contrato de plugins expandem para typecheck de extensões porque extensões dependem desses contratos do núcleo (varreduras de extensão do Vitest continuam sendo trabalho explícito de teste); -- bumps de versão somente de metadados de release executam verificações direcionadas de versão/configuração/dependência raiz; -- alterações desconhecidas de raiz/configuração falham de modo seguro para todas as vias de verificação. +- alterações de produção do core executam typecheck de core prod e core test mais lint/guards do core; +- alterações apenas de teste do core executam apenas typecheck de core test mais lint do core; +- alterações de produção de extensão executam typecheck de extension prod e extension test mais lint de extension; +- alterações apenas de teste de extensão executam typecheck de extension test mais lint de extension; +- alterações públicas do Plugin SDK ou contrato de Plugin expandem para typecheck de extension porque extensões dependem desses contratos do core (varreduras de extensão do Vitest continuam sendo trabalho de teste explícito); +- aumentos de versão apenas de metadados de release executam verificações direcionadas de versão/config/dependência raiz; +- alterações desconhecidas em root/config falham com segurança para todas as faixas de verificação. -O roteamento local de changed-test vive em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de testes executam a si mesmas, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de importação. A configuração compartilhada de entrega em salas de grupo é um dos mapeamentos explícitos: alterações na configuração de resposta visível de grupo, no modo de entrega de resposta de origem ou no prompt de sistema da ferramenta de mensagens passam pelos testes de resposta do núcleo, além de regressões de entrega do Discord e Slack, para que uma alteração de padrão compartilhado falhe antes do primeiro push de PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável. +O roteamento local de changed-test vive em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de teste executam os próprios testes, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de imports. A configuração de entrega de sala de grupo compartilhada é um dos mapeamentos explícitos: alterações na configuração de resposta visível de grupo, no modo de entrega de resposta de origem ou no prompt de sistema da ferramenta de mensagens passam pelos testes de resposta do core mais regressões de entrega do Discord e Slack para que uma alteração de padrão compartilhado falhe antes do primeiro push do PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável. ## Validação Testbox -Execute o Testbox a partir da raiz do repositório e prefira uma box recém-aquecida para comprovação ampla. Antes de gastar um gate lento em uma box que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da box primeiro. +Execute o Testbox a partir da raiz do repositório e prefira uma máquina recém-aquecida para comprovação ampla. Antes de gastar um gate lento em uma máquina que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da máquina primeiro. -A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desapareceram ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso normalmente significa que o estado da sincronização remota não é uma cópia confiável do PR; pare essa box e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs com grandes exclusões intencionais, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade. +A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desapareceram ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso geralmente significa que o estado de sincronização remoto não é uma cópia confiável do PR; pare essa máquina e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs intencionais com grandes exclusões, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade. -`pnpm testbox:run` também encerra uma invocação local da CLI do Blacksmith que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desativar essa proteção, ou use um valor maior em milissegundos para diffs locais incomumente grandes. +`pnpm testbox:run` também encerra uma invocação local da CLI do Blacksmith que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desabilitar essa proteção ou use um valor maior em milissegundos para diffs locais incomumente grandes. -Crabbox é o wrapper de box remota mantido pelo repositório para comprovação Linux de mantenedores. Use-o quando uma verificação for ampla demais para um ciclo local de edição, quando a paridade com CI for importante ou quando a comprovação precisar de segredos, Docker, lanes de pacote, boxes reutilizáveis ou logs remotos. O backend normal do OpenClaw é `blacksmith-testbox`; a capacidade própria em AWS/Hetzner é uma alternativa para indisponibilidades do Blacksmith, problemas de cota ou testes explícitos em capacidade própria. +Crabbox é o wrapper de máquina remota pertencente ao repositório para comprovação Linux de mantenedores. Use-o quando uma verificação for ampla demais para um ciclo local de edição, quando a paridade com CI importar ou quando a comprovação precisar de segredos, Docker, lanes de pacote, máquinas reutilizáveis ou logs remotos. O backend normal do OpenClaw é `blacksmith-testbox`; capacidade própria em AWS/Hetzner é um fallback para indisponibilidades do Blacksmith, problemas de cota ou testes explícitos de capacidade própria. Antes de uma primeira execução, verifique o wrapper a partir da raiz do repositório: @@ -487,7 +506,7 @@ Antes de uma primeira execução, verifique o wrapper a partir da raiz do reposi pnpm crabbox:run -- --help | sed -n '1,120p' ``` -O wrapper do repositório recusa um binário Crabbox obsoleto que não anuncia `blacksmith-testbox`. Passe o provider explicitamente, mesmo que `.crabbox.yaml` tenha padrões de nuvem própria. +O wrapper do repositório recusa um binário obsoleto do Crabbox que não anuncia `blacksmith-testbox`. Passe o provedor explicitamente, mesmo que `.crabbox.yaml` tenha padrões de nuvem própria. Gate de alterações: @@ -504,7 +523,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" ``` -Reexecução de teste focado: +Reexecução de teste focada: ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -534,21 +553,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` -Leia o resumo JSON final. Os campos úteis são `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` e `totalMs`. Execuções Crabbox únicas com suporte do Blacksmith devem parar o Testbox automaticamente; se uma execução for interrompida ou a limpeza não estiver clara, inspecione as boxes ativas e pare somente as boxes que você criou: +Leia o resumo JSON final. Os campos úteis são `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` e `totalMs`. Execuções únicas do Crabbox com suporte do Blacksmith devem parar o Testbox automaticamente; se uma execução for interrompida ou a limpeza não estiver clara, inspecione as máquinas ativas e pare apenas as máquinas que você criou: ```bash blacksmith testbox list blacksmith testbox stop --id ``` -Use reutilização somente quando você precisar intencionalmente de vários comandos na mesma box hidratada: +Use reutilização somente quando precisar intencionalmente de vários comandos na mesma máquina hidratada: ```bash pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " pnpm crabbox:stop -- ``` -Se o Crabbox for a camada quebrada, mas o próprio Blacksmith funcionar, use o Blacksmith direto como alternativa restrita: +Se o Crabbox for a camada quebrada, mas o próprio Blacksmith funcionar, use o Blacksmith direto como um fallback restrito: ```bash blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 @@ -556,7 +575,7 @@ blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --id ``` -Escalone para capacidade própria do Crabbox somente quando o Blacksmith estiver indisponível, limitado por cota, sem o ambiente necessário ou quando a capacidade própria for explicitamente o objetivo: +Escale para capacidade própria do Crabbox somente quando o Blacksmith estiver fora do ar, limitado por cota, sem o ambiente necessário ou quando a capacidade própria for explicitamente o objetivo: ```bash pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m @@ -565,9 +584,9 @@ pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.crabbox.yaml` controla os padrões de provider, sincronização e hidratação do GitHub Actions para lanes de nuvem própria. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados Git remotos em vez de sincronizar remotos e armazenamentos de objetos locais dos mantenedores, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla o checkout, a configuração do Node/pnpm, o fetch de `origin/main` e a transferência de ambiente sem segredos para comandos `crabbox run --id ` em nuvem própria. +`.crabbox.yaml` controla os padrões de provedor, sincronização e hidratação do GitHub Actions para lanes de nuvem própria. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados remotos do Git em vez de sincronizar remotos e armazenamentos de objetos locais do mantenedor, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla checkout, configuração de Node/pnpm, busca de `origin/main` e repasse de ambiente não secreto para comandos `crabbox run --id ` em nuvem própria. -## Relacionados +## Relacionado - [Visão geral da instalação](/pt-BR/install) - [Canais de desenvolvimento](/pt-BR/install/development-channels) diff --git a/docs/pt-BR/cli/dashboard.md b/docs/pt-BR/cli/dashboard.md index 5ff955ca5..43454eec6 100644 --- a/docs/pt-BR/cli/dashboard.md +++ b/docs/pt-BR/cli/dashboard.md @@ -1,21 +1,21 @@ --- read_when: - - Você quer abrir a Control UI com seu token atual - - Você quer exibir a URL sem abrir um navegador -summary: Referência de CLI para `openclaw dashboard` (abre a Control UI) + - Você quer abrir a UI de Controle com seu token atual + - Você quer imprimir a URL sem abrir um navegador +summary: Referência da CLI para `openclaw dashboard` (abrir a interface de controle) title: Painel x-i18n: - generated_at: "2026-04-25T13:43:35Z" - model: gpt-5.4 + generated_at: "2026-05-05T01:44:32Z" + model: gpt-5.5 provider: openai - source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c + source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f source_path: cli/dashboard.md - workflow: 15 + workflow: 16 --- # `openclaw dashboard` -Abre a Control UI usando sua autenticação atual. +Abra a UI de Controle usando sua autenticação atual. ```bash openclaw dashboard @@ -24,11 +24,14 @@ openclaw dashboard --no-open Observações: -- `dashboard` resolve SecretRefs configurados em `gateway.auth.token` quando possível. -- `dashboard` segue `gateway.tls.enabled`: Gateways com TLS habilitado exibem/abrem - URLs da Control UI com `https://` e se conectam via `wss://`. -- Para tokens gerenciados por SecretRef (resolvidos ou não resolvidos), `dashboard` exibe/copia/abre uma URL sem token para evitar expor segredos externos na saída do terminal, no histórico da área de transferência ou em argumentos de inicialização do navegador. -- Se `gateway.auth.token` for gerenciado por SecretRef, mas não estiver resolvido neste caminho de comando, o comando exibirá uma URL sem token e orientações explícitas de correção em vez de incorporar um placeholder de token inválido. +- `dashboard` resolve SecretRefs de `gateway.auth.token` configuradas quando possível. +- `dashboard` segue `gateway.tls.enabled`: instâncias de Gateway com TLS habilitado imprimem/abrem URLs da UI de Controle com + `https://` e se conectam por `wss://`. +- Se a entrega pela área de transferência/navegador falhar para uma URL do painel autenticada por token, + `dashboard` registra uma dica segura de autenticação manual nomeando `OPENCLAW_GATEWAY_TOKEN`, + `gateway.auth.token` e a chave de fragmento `token` sem imprimir o valor do token. +- Para tokens gerenciados por SecretRef (resolvidos ou não resolvidos), `dashboard` imprime/copia/abre uma URL sem token para evitar expor segredos externos na saída do terminal, no histórico da área de transferência ou nos argumentos de inicialização do navegador. +- Se `gateway.auth.token` for gerenciado por SecretRef, mas não for resolvido neste caminho de comando, o comando imprime uma URL sem token e orientações explícitas de correção em vez de incorporar um placeholder de token inválido. ## Relacionado diff --git a/docs/pt-BR/cli/doctor.md b/docs/pt-BR/cli/doctor.md index 725022942..2864154d1 100644 --- a/docs/pt-BR/cli/doctor.md +++ b/docs/pt-BR/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - Você tem problemas de conectividade/autenticação e deseja correções guiadas - - Você atualizou e quer uma verificação rápida + - Você está com problemas de conectividade/autenticação e quer correções guiadas + - Você atualizou e quer uma verificação de sanidade summary: Referência da CLI para `openclaw doctor` (verificações de integridade + reparos guiados) title: Diagnóstico x-i18n: - generated_at: "2026-05-04T02:22:18Z" + generated_at: "2026-05-05T01:44:26Z" model: gpt-5.5 provider: openai - source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 + source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Verificações de integridade + correções rápidas para o Gateway e canais. +Verificações de integridade + correções rápidas para o Gateway e os canais. Relacionado: @@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token ## Opções -- `--no-workspace-suggestions`: desativa sugestões de memória/pesquisa do workspace +- `--no-workspace-suggestions`: desabilita sugestões de memória/pesquisa do workspace - `--yes`: aceita os padrões sem solicitar confirmação -- `--repair`: aplica reparos recomendados que não envolvem serviço sem solicitar confirmação; instalações e reescritas do serviço do Gateway ainda exigem confirmação interativa ou comandos explícitos do Gateway +- `--repair`: aplica reparos recomendados que não sejam de serviço sem solicitar confirmação; instalações e regravações do serviço de Gateway ainda exigem confirmação interativa ou comandos explícitos de Gateway - `--fix`: alias para `--repair` - `--force`: aplica reparos agressivos, incluindo sobrescrever configuração personalizada de serviço quando necessário -- `--non-interactive`: executa sem prompts; apenas migrações seguras e reparos que não envolvem serviço -- `--generate-gateway-token`: gera e configura um token do Gateway -- `--deep`: verifica serviços do sistema em busca de instalações extras do Gateway +- `--non-interactive`: executa sem prompts; somente migrações seguras e reparos que não sejam de serviço +- `--generate-gateway-token`: gera e configura um token de Gateway +- `--deep`: examina os serviços do sistema em busca de instalações extras do Gateway Observações: -- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções sem interface (cron, Telegram, sem terminal) ignorarão prompts. -- Desempenho: execuções não interativas de `doctor` ignoram o carregamento antecipado de plugins para manter verificações de integridade sem interface rápidas. Sessões interativas ainda carregam plugins completamente quando uma verificação precisa da contribuição deles. +- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções headless (cron, Telegram, sem terminal) ignorarão os prompts. +- Desempenho: execuções não interativas de `doctor` ignoram o carregamento antecipado de Plugin para que as verificações de integridade headless permaneçam rápidas. Sessões interativas ainda carregam Plugins por completo quando uma verificação precisa da contribuição deles. - `--fix` (alias para `--repair`) grava um backup em `~/.openclaw/openclaw.json.bak` e remove chaves de configuração desconhecidas, listando cada remoção. -- `doctor --fix --non-interactive` relata definições de serviço do Gateway ausentes ou obsoletas, mas não as instala nem reescreve fora do modo de reparo de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher. -- As verificações de integridade de estado agora detectam arquivos de transcrição órfãos no diretório de sessões. Arquivá-los como `.deleted.` exige uma confirmação interativa; `--fix`, `--yes` e execuções sem interface os deixam no lugar. -- Doctor também verifica `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de tarefas cron e pode reescrevê-los no lugar antes que o agendador precise normalizá-los automaticamente em tempo de execução. -- No Linux, Doctor avisa quando o crontab do usuário ainda executa o legado `~/.openclaw/bin/ensure-whatsapp.sh`; esse script não é mais mantido e pode registrar falsas indisponibilidades do Gateway do WhatsApp quando o cron não tem o ambiente do barramento de usuário do systemd. -- Doctor limpa estado legado de preparação de dependências de plugins criado por versões antigas do OpenClaw. Ele também repara plugins baixáveis configurados ausentes quando o registro consegue resolvê-los, e a passagem de Doctor 2026.5.2 instala automaticamente plugins baixáveis que uma configuração antiga já usa antes de marcar a configuração como tocada para essa versão. Se o download falhar, Doctor relata o erro de instalação e preserva a entrada de plugin configurada para a próxima tentativa de reparo. -- Doctor repara configuração obsoleta de plugins removendo ids de plugins ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal pendente correspondente, alvos de Heartbeat e substituições de modelo de canal quando a descoberta de plugins está íntegra. -- Doctor coloca configuração inválida de plugins em quarentena desativando a entrada `plugins.entries.` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já ignora apenas esse plugin problemático, para que outros plugins e canais possam continuar em execução. -- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerencia o ciclo de vida do Gateway. Doctor ainda relata a integridade do Gateway/serviço e aplica reparos que não envolvem serviço, mas ignora instalação/início/reinício/bootstrap do serviço e limpeza de serviço legado. -- No Linux, Doctor ignora unidades systemd extras semelhantes ao Gateway que estejam inativas e não reescreve metadados de comando/entrypoint para um serviço systemd do Gateway em execução durante o reparo. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher ativo. -- Doctor migra automaticamente configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e relacionados) para `talk.provider` + `talk.providers.`. -- Execuções repetidas de `doctor --fix` não relatam/aplicam mais normalização do Talk quando a única diferença é a ordem das chaves do objeto. -- Doctor inclui uma verificação de prontidão de pesquisa de memória e pode recomendar `openclaw configure --section model` quando credenciais de embeddings estão ausentes. -- Doctor avisa quando nenhum proprietário de comandos está configurado. O proprietário de comandos é a conta do operador humano autorizada a executar comandos exclusivos de proprietário e aprovar ações perigosas. O pareamento por DM apenas permite que alguém fale com o bot; se você aprovou um remetente antes de existir o bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente. -- Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais do Codex CLI existem no diretório inicial Codex do operador. Inicializações locais do servidor de app do Codex usam diretórios iniciais isolados por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente. -- Doctor avisa quando Skills permitidas para o agente padrão estão indisponíveis no ambiente de execução atual porque bins, variáveis de ambiente, configuração ou requisitos de SO estão ausentes. `doctor --fix` pode desativar essas skills indisponíveis com `skills.entries..enabled=false`; instale/configure o requisito ausente em vez disso quando quiser manter a skill ativa. -- Se o modo sandbox estiver ativado mas o Docker estiver indisponível, Doctor relata um aviso de alto sinal com correção (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`). -- Se arquivos legados do registro do sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, Doctor os relata; `openclaw doctor --fix` migra entradas válidas para diretórios de registro particionados e coloca arquivos legados inválidos em quarentena. -- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho do comando atual, Doctor relata um aviso somente leitura e não grava credenciais fallback em texto simples. -- Se a inspeção de SecretRef do canal falhar em um caminho de correção, Doctor continua e relata um aviso em vez de sair antecipadamente. -- Após migrações de diretório de estado, Doctor avisa quando contas padrão ativadas do Telegram ou Discord dependem de fallback por env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo do Doctor. -- A resolução automática de nome de usuário `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho do comando atual. Se a inspeção do token estiver indisponível, Doctor relata um aviso e ignora a resolução automática nessa passagem. +- `doctor --fix --non-interactive` informa definições de serviço de Gateway ausentes ou obsoletas, mas não as instala nem regrava fora do modo de reparo de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador. +- As verificações de integridade de estado agora detectam arquivos órfãos de transcrição no diretório de sessões. Arquivá-los como `.deleted.` exige uma confirmação interativa; `--fix`, `--yes` e execuções headless os deixam no lugar. +- Doctor também examina `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de trabalhos Cron e pode regravá-los no local antes que o agendador precise normalizá-los automaticamente em tempo de execução. +- No Linux, doctor avisa quando o crontab do usuário ainda executa o legado `~/.openclaw/bin/ensure-whatsapp.sh`; esse script não é mais mantido e pode registrar falsas indisponibilidades do Gateway do WhatsApp quando Cron não tem o ambiente de barramento de usuário do systemd. +- Doctor limpa o estado legado de preparação de dependências de Plugin criado por versões antigas do OpenClaw. Ele também repara Plugins baixáveis ausentes que são referenciados pela configuração, como `plugins.entries`, canais configurados, configurações de provedor/pesquisa configuradas ou runtimes de agente configurados. Durante atualizações de pacote, doctor ignora o reparo de Plugin pelo gerenciador de pacotes até que a troca de pacote seja concluída; execute novamente `openclaw doctor --fix` depois se um Plugin configurado ainda precisar de recuperação. Se o download falhar, doctor relata o erro de instalação e preserva a entrada de Plugin configurada para a próxima tentativa de reparo. +- Doctor repara configuração obsoleta de Plugin removendo ids de Plugin ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal pendente correspondente, alvos de Heartbeat e substituições de modelo de canal quando a descoberta de Plugin está íntegra. +- Doctor coloca em quarentena configuração inválida de Plugin desabilitando a entrada `plugins.entries.` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já ignora apenas esse Plugin problemático para que outros Plugins e canais possam continuar em execução. +- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerenciar o ciclo de vida do Gateway. Doctor ainda relata a integridade do Gateway/serviço e aplica reparos que não sejam de serviço, mas ignora instalação/início/reinício/bootstrap de serviço e limpeza de serviço legado. +- No Linux, doctor ignora unidades systemd extras semelhantes a Gateway que estejam inativas e não regrava metadados de comando/entrypoint para um serviço systemd de Gateway em execução durante o reparo. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador ativo. +- Doctor migra automaticamente a configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e afins) para `talk.provider` + `talk.providers.`. +- Execuções repetidas de `doctor --fix` não relatam/aplicam mais a normalização do Talk quando a única diferença é a ordem das chaves do objeto. +- Doctor inclui uma verificação de prontidão de pesquisa em memória e pode recomendar `openclaw configure --section model` quando as credenciais de embedding estão ausentes. +- Doctor avisa quando nenhum proprietário de comandos está configurado. O proprietário de comandos é a conta de operador humano autorizada a executar comandos exclusivos do proprietário e aprovar ações perigosas. O pareamento por DM apenas permite que alguém fale com o bot; se você aprovou um remetente antes da existência do bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente. +- Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais da CLI do Codex existem na home Codex do operador. Inicializações locais do app-server do Codex usam homes isoladas por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente. +- Doctor avisa quando Skills permitidas para o agente padrão estão indisponíveis no ambiente de runtime atual porque bins, env vars, configuração ou requisitos de SO estão ausentes. `doctor --fix` pode desabilitar essas Skills indisponíveis com `skills.entries..enabled=false`; instale/configure o requisito ausente em vez disso quando quiser manter a skill ativa. +- Se o modo sandbox estiver habilitado, mas o Docker estiver indisponível, doctor relata um aviso de alto sinal com remediação (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`). +- Se arquivos legados de registro de sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, doctor os relata; `openclaw doctor --fix` migra entradas válidas para diretórios de registro fragmentados e coloca arquivos legados inválidos em quarentena. +- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho de comando atual, doctor relata um aviso somente leitura e não grava credenciais fallback em texto simples. +- Se a inspeção de SecretRef do canal falhar em um caminho de correção, doctor continua e relata um aviso em vez de sair antecipadamente. +- Após migrações do diretório de estado, doctor avisa quando contas padrão habilitadas do Telegram ou Discord dependem de fallback de env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo doctor. +- A resolução automática de nome de usuário `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho de comando atual. Se a inspeção do token estiver indisponível, doctor relata um aviso e ignora a resolução automática nessa passagem. ## macOS: substituições de env do `launchctl` -Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor sobrescreve seu arquivo de configuração e pode causar erros persistentes de “não autorizado”. +Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor substitui seu arquivo de configuração e pode causar erros persistentes de “não autorizado”. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN diff --git a/docs/pt-BR/cli/gateway.md b/docs/pt-BR/cli/gateway.md index 056e07203..8ec95cad8 100644 --- a/docs/pt-BR/cli/gateway.md +++ b/docs/pt-BR/cli/gateway.md @@ -1,16 +1,16 @@ --- read_when: - Executando o Gateway pela CLI (desenvolvimento ou servidores) - - Depuração de autenticação do Gateway, modos de vinculação e conectividade - - Descoberta de Gateways via Bonjour (DNS-SD local + de área ampla) + - Depuração da autenticação do Gateway, dos modos de bind e da conectividade + - Descobrindo Gateways via Bonjour (DNS-SD local + de área ampla) sidebarTitle: Gateway summary: OpenClaw Gateway CLI (`openclaw gateway`) — execute, consulte e descubra Gateways title: Gateway x-i18n: - generated_at: "2026-05-04T18:23:47Z" + generated_at: "2026-05-05T01:44:36Z" model: gpt-5.5 provider: openai - source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d + source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 source_path: cli/gateway.md workflow: 16 --- @@ -19,13 +19,13 @@ O Gateway é o servidor WebSocket do OpenClaw (canais, nós, sessões, hooks). O - Configuração de mDNS local + DNS-SD de área ampla. + Configuração local de mDNS + DNS-SD de área ampla. - + Como o OpenClaw anuncia e encontra gateways. - Chaves de configuração de nível superior do gateway. + Chaves de configuração de Gateway de nível superior. @@ -46,11 +46,11 @@ openclaw gateway run - Por padrão, o Gateway se recusa a iniciar a menos que `gateway.mode=local` esteja definido em `~/.openclaw/openclaw.json`. Use `--allow-unconfigured` para execuções ad-hoc/de desenvolvimento. - - Espera-se que `openclaw onboard --mode local` e `openclaw setup` gravem `gateway.mode=local`. Se o arquivo existir, mas `gateway.mode` estiver ausente, trate isso como uma configuração quebrada ou sobrescrita e repare-a em vez de assumir implicitamente o modo local. - - Se o arquivo existir e `gateway.mode` estiver ausente, o Gateway trata isso como dano suspeito na configuração e se recusa a "adivinhar local" para você. - - Vincular além do loopback sem autenticação é bloqueado (barreira de segurança). - - `SIGUSR1` aciona uma reinicialização dentro do processo quando autorizado (`commands.restart` é habilitado por padrão; defina `commands.restart: false` para bloquear a reinicialização manual, enquanto aplicação/atualização da ferramenta/configuração do gateway continuam permitidas). - - Os manipuladores de `SIGINT`/`SIGTERM` interrompem o processo do gateway, mas não restauram nenhum estado personalizado do terminal. Se você encapsular a CLI com uma TUI ou entrada em modo bruto, restaure o terminal antes de sair. + - Espera-se que `openclaw onboard --mode local` e `openclaw setup` gravem `gateway.mode=local`. Se o arquivo existir, mas `gateway.mode` estiver ausente, trate isso como uma configuração quebrada ou sobrescrita e repare-a em vez de presumir implicitamente o modo local. + - Se o arquivo existir e `gateway.mode` estiver ausente, o Gateway trata isso como dano suspeito à configuração e se recusa a "adivinhar local" por você. + - Vinculação além de loopback sem autenticação é bloqueada (barreira de segurança). + - `SIGUSR1` aciona uma reinicialização em processo quando autorizado (`commands.restart` é habilitado por padrão; defina `commands.restart: false` para bloquear reinicialização manual, enquanto aplicação/atualização de ferramenta/configuração do Gateway continuam permitidas). + - Manipuladores de `SIGINT`/`SIGTERM` param o processo do gateway, mas não restauram nenhum estado personalizado do terminal. Se você encapsular a CLI com uma TUI ou entrada em modo bruto, restaure o terminal antes de sair. @@ -58,19 +58,19 @@ openclaw gateway run ### Opções - Porta WebSocket (o padrão vem da configuração/env; geralmente `18789`). + Porta WebSocket (o padrão vem de config/env; geralmente `18789`). - Modo de bind do listener. + Modo de vinculação do listener. Substituição do modo de autenticação. - Substituição do token (também define `OPENCLAW_GATEWAY_TOKEN` para o processo). + Substituição de token (também define `OPENCLAW_GATEWAY_TOKEN` para o processo). - Substituição da senha. + Substituição de senha. Leia a senha do gateway de um arquivo. @@ -79,16 +79,16 @@ openclaw gateway run Exponha o Gateway via Tailscale. - Redefina a configuração serve/funnel do Tailscale ao encerrar. + Redefina a configuração de serve/funnel do Tailscale no encerramento. - Permita que o gateway inicie sem `gateway.mode=local` na configuração. Ignora a proteção de inicialização apenas para bootstrap ad-hoc/de desenvolvimento; não grava nem repara o arquivo de configuração. + Permite iniciar o gateway sem `gateway.mode=local` na configuração. Ignora a proteção de inicialização apenas para bootstrap ad-hoc/de desenvolvimento; não grava nem repara o arquivo de configuração. - Crie uma configuração de desenvolvimento + workspace se ausentes (ignora BOOTSTRAP.md). + Crie uma configuração de desenvolvimento + workspace se estiver ausente (ignora BOOTSTRAP.md). - Redefina configuração de desenvolvimento + credenciais + sessões + workspace (requer `--dev`). + Redefina a configuração de desenvolvimento + credenciais + sessões + workspace (requer `--dev`). Encerre qualquer listener existente na porta selecionada antes de iniciar. @@ -100,7 +100,7 @@ openclaw gateway run Mostre apenas logs do backend da CLI no console (e habilite stdout/stderr). - Estilo de log do WebSocket. + Estilo de log Websocket. Alias para `--ws-log compact`. @@ -109,7 +109,7 @@ openclaw gateway run Registre eventos brutos de stream do modelo em jsonl. - Caminho jsonl do stream bruto. + Caminho do jsonl de stream bruto. ## Reiniciar o Gateway @@ -120,21 +120,21 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` pede ao Gateway em execução que faça uma pré-verificação do trabalho ativo do OpenClaw antes de reiniciar. Se operações em fila, entrega de respostas, execuções incorporadas ou execuções de tarefas estiverem ativas, o Gateway relata os bloqueadores, agrupa solicitações duplicadas de reinicialização segura e reinicia quando o trabalho ativo é escoado. `restart` simples mantém o comportamento existente do gerenciador de serviço para compatibilidade. Use `--force` somente quando você quiser explicitamente o caminho de substituição imediata. +`openclaw gateway restart --safe` solicita ao Gateway em execução que faça um preflight do trabalho ativo do OpenClaw antes de reiniciar. Se operações enfileiradas, entrega de respostas, execuções incorporadas ou execuções de tarefas estiverem ativas, o Gateway relata os bloqueadores, consolida solicitações duplicadas de reinicialização segura e reinicia quando o trabalho ativo esvazia. `restart` simples mantém o comportamento existente do gerenciador de serviço por compatibilidade. Use `--force` apenas quando você quiser explicitamente o caminho de substituição imediata. `--password` inline pode ser exposto em listagens de processos locais. Prefira `--password-file`, env ou um `gateway.auth.password` baseado em SecretRef. -### Perfilamento da inicialização +### Perfil de inicialização -- Defina `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar tempos de fases durante a inicialização do Gateway, incluindo atraso `eventLoopMax` por fase e tempos de tabelas de consulta de plugins para índice instalado, registro de manifestos, planejamento de inicialização e trabalho de mapa de proprietários. -- Defina `OPENCLAW_DIAGNOSTICS=timeline` com `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` para gravar uma timeline de diagnósticos de inicialização JSONL de melhor esforço para harnesses externos de QA. Você também pode habilitar a flag com `diagnostics.flags: ["timeline"]` na configuração; o caminho ainda é fornecido por env. Adicione `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir amostras do loop de eventos. -- Execute `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir a inicialização do Gateway. O benchmark registra a primeira saída do processo, `/healthz`, `/readyz`, tempos do trace de inicialização, atraso do loop de eventos e detalhes de tempo das tabelas de consulta de plugins. +- Defina `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar tempos de fase durante a inicialização do Gateway, incluindo atraso `eventLoopMax` por fase e tempos de tabela de lookup de Plugin para índice instalado, registro de manifestos, planejamento de inicialização e trabalho de mapa de proprietários. +- Defina `OPENCLAW_DIAGNOSTICS=timeline` com `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` para gravar uma linha do tempo de diagnósticos de inicialização JSONL de melhor esforço para harnesses externos de QA. Você também pode habilitar a flag com `diagnostics.flags: ["timeline"]` na configuração; o caminho ainda é fornecido via env. Adicione `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir amostras do loop de eventos. +- Execute `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir o desempenho da inicialização do Gateway. O benchmark registra a primeira saída do processo, `/healthz`, `/readyz`, tempos de trace de inicialização, atraso do loop de eventos e detalhes de tempo da tabela de lookup de Plugin. ## Consultar um Gateway em execução -Todos os comandos de consulta usam RPC por WebSocket. +Todos os comandos de consulta usam RPC via WebSocket. @@ -154,7 +154,7 @@ Todos os comandos de consulta usam RPC por WebSocket. -Quando você define `--url`, a CLI não recorre a credenciais da configuração ou do ambiente. Passe `--token` ou `--password` explicitamente. Credenciais explícitas ausentes são um erro. +Quando você define `--url`, a CLI não faz fallback para credenciais de configuração ou ambiente. Passe `--token` ou `--password` explicitamente. A ausência de credenciais explícitas é um erro. ### `gateway health` @@ -163,11 +163,11 @@ Quando você define `--url`, a CLI não recorre a credenciais da configuração openclaw gateway health --url ws://127.0.0.1:18789 ``` -O endpoint HTTP `/healthz` é uma sonda de vitalidade: ele retorna quando o servidor consegue responder por HTTP. O endpoint HTTP `/readyz` é mais rigoroso e permanece vermelho enquanto sidecars de plugins de inicialização, canais ou hooks configurados ainda estão se acomodando. Respostas detalhadas de prontidão locais ou autenticadas incluem um bloco de diagnóstico `eventLoop` com atraso do loop de eventos, utilização do loop de eventos, proporção de núcleos de CPU e uma flag `degraded`. +O endpoint HTTP `/healthz` é uma sonda de atividade: ele retorna quando o servidor consegue responder HTTP. O endpoint HTTP `/readyz` é mais estrito e permanece vermelho enquanto sidecars de Plugin de inicialização, canais ou hooks configurados ainda estão se estabilizando. Respostas detalhadas de prontidão locais ou autenticadas incluem um bloco de diagnóstico `eventLoop` com atraso do loop de eventos, utilização do loop de eventos, razão de núcleos de CPU e uma flag `degraded`. ### `gateway usage-cost` -Busca resumos de custo de uso dos logs de sessão. +Busque resumos de custo de uso dos logs de sessão. ```bash openclaw gateway usage-cost @@ -181,7 +181,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Busca o gravador recente de estabilidade de diagnóstico de um Gateway em execução. +Busque o gravador recente de estabilidade de diagnóstico de um Gateway em execução. ```bash openclaw gateway stability @@ -201,10 +201,10 @@ openclaw gateway stability --json Inclua apenas eventos após um número de sequência de diagnóstico. - Leia um pacote de estabilidade persistido em vez de chamar o Gateway em execução. Use `--bundle latest` (ou apenas `--bundle`) para o pacote mais novo no diretório de estado, ou passe diretamente um caminho JSON do pacote. + Leia um pacote de estabilidade persistido em vez de chamar o Gateway em execução. Use `--bundle latest` (ou apenas `--bundle`) para o pacote mais novo no diretório de estado, ou passe diretamente um caminho JSON de pacote. - Grave um zip de diagnósticos de suporte compartilhável em vez de imprimir detalhes de estabilidade. + Grave um zip compartilhável de diagnósticos de suporte em vez de imprimir detalhes de estabilidade. Caminho de saída para `--export`. @@ -212,15 +212,15 @@ openclaw gateway stability --json - - Os registros mantêm metadados operacionais: nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de filas/sessões, nomes de canais/plugins e resumos de sessão redigidos. Eles não mantêm texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies, valores secretos, nomes de host ou ids brutos de sessão. Defina `diagnostics.enabled: false` para desabilitar o gravador totalmente. - - Em encerramentos fatais do Gateway, timeouts de desligamento e falhas de inicialização após reinicialização, o OpenClaw grava o mesmo snapshot de diagnóstico em `~/.openclaw/logs/stability/openclaw-stability-*.json` quando o gravador tem eventos. Inspecione o pacote mais novo com `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` também se aplicam à saída do pacote. + - Os registros mantêm metadados operacionais: nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de fila/sessão, nomes de canais/plugins e resumos de sessão redigidos. Eles não mantêm texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies, valores secretos, nomes de host ou ids brutos de sessão. Defina `diagnostics.enabled: false` para desabilitar completamente o gravador. + - Em saídas fatais do Gateway, timeouts de encerramento e falhas de inicialização de reinício, o OpenClaw grava o mesmo snapshot de diagnóstico em `~/.openclaw/logs/stability/openclaw-stability-*.json` quando o gravador tem eventos. Inspecione o pacote mais novo com `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` também se aplicam à saída do pacote. ### `gateway diagnostics export` -Grava um zip de diagnósticos local projetado para anexar a relatórios de bugs. Para o modelo de privacidade e o conteúdo do pacote, consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics). +Grave um zip local de diagnósticos projetado para anexar a relatórios de bugs. Para o modelo de privacidade e o conteúdo do pacote, consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -232,7 +232,7 @@ openclaw gateway diagnostics export --json Caminho do zip de saída. O padrão é uma exportação de suporte no diretório de estado. - Máximo de linhas de log sanitizadas a incluir. + Número máximo de linhas de log sanitizadas a incluir. Máximo de bytes de log a inspecionar. @@ -256,13 +256,13 @@ openclaw gateway diagnostics export --json Imprima o caminho gravado, o tamanho e o manifesto como JSON. -A exportação contém um manifesto, um resumo em Markdown, formato da configuração, detalhes sanitizados da configuração, resumos sanitizados de logs, snapshots sanitizados de status/integridade do Gateway e o pacote de estabilidade mais novo quando existir. +A exportação contém um manifesto, um resumo em Markdown, formato de configuração, detalhes de configuração sanitizados, resumos de log sanitizados, snapshots sanitizados de status/integridade do Gateway e o pacote de estabilidade mais novo quando houver um. -Ela foi feita para ser compartilhada. Mantém detalhes operacionais que ajudam na depuração, como campos seguros de log do OpenClaw, nomes de subsistemas, códigos de status, durações, modos configurados, portas, ids de plugins, ids de provedores, configurações de recursos não secretas e mensagens de log operacional redigidas. Omite ou redige texto de chat, corpos de webhook, saídas de ferramentas, credenciais, cookies, identificadores de contas/mensagens, texto de prompts/instruções, nomes de host e valores secretos. Quando uma mensagem no estilo LogTape parece texto de payload de usuário/chat/ferramenta, a exportação mantém apenas que uma mensagem foi omitida, além de sua contagem de bytes. +Ela foi feita para ser compartilhada. Mantém detalhes operacionais que ajudam na depuração, como campos seguros de log do OpenClaw, nomes de subsistemas, códigos de status, durações, modos configurados, portas, ids de Plugin, ids de provedores, configurações de recursos não secretas e mensagens de log operacional redigidas. Ela omite ou redige texto de chat, corpos de webhook, saídas de ferramentas, credenciais, cookies, identificadores de conta/mensagem, texto de prompt/instrução, nomes de host e valores secretos. Quando uma mensagem no estilo LogTape parece texto de payload de usuário/chat/ferramenta, a exportação mantém apenas que uma mensagem foi omitida e sua contagem de bytes. ### `gateway status` -`gateway status` mostra o serviço do Gateway (launchd/systemd/schtasks) mais uma sonda opcional de capacidade de conectividade/autenticação. +`gateway status` mostra o serviço do Gateway (launchd/systemd/schtasks) mais uma sonda opcional de conectividade/capacidade de autenticação. ```bash openclaw gateway status @@ -271,7 +271,7 @@ openclaw gateway status --require-rpc ``` - Adicione um destino de sondagem explícito. O remoto configurado + localhost ainda são sondados. + Adicione um alvo de sondagem explícito. O remoto configurado + localhost ainda são sondados. Autenticação por token para a sondagem. @@ -283,32 +283,32 @@ openclaw gateway status --require-rpc Tempo limite da sondagem. - Pule a sondagem de conectividade (visão apenas do serviço). + Ignore a sondagem de conectividade (visualização somente do serviço). - Examine também serviços em nível de sistema. + Verifique também serviços em nível de sistema. - Atualize a sondagem de conectividade padrão para uma sondagem de leitura e saia com código diferente de zero quando essa sondagem de leitura falhar. Não pode ser combinado com `--no-probe`. + Promova a sondagem de conectividade padrão para uma sondagem de leitura e saia com código diferente de zero quando essa sondagem de leitura falhar. Não pode ser combinado com `--no-probe`. - - `gateway status` permanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou é inválida. + - `gateway status` permanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou inválida. - O `gateway status` padrão comprova o estado do serviço, a conexão WebSocket e a capacidade de autenticação visível no momento do handshake. Ele não comprova operações de leitura/gravação/administração. - - As sondagens de diagnóstico não fazem mutações para autenticação de dispositivo de primeira vez: elas reutilizam um token de dispositivo existente em cache quando ele existe, mas não criam uma nova identidade de dispositivo da CLI nem um registro de pareamento de dispositivo somente leitura apenas para verificar o status. + - As sondagens de diagnóstico não fazem mutações na autenticação de dispositivos de primeiro uso: elas reutilizam um token de dispositivo em cache existente quando houver um, mas não criam uma nova identidade de dispositivo da CLI nem um registro de pareamento de dispositivo somente leitura apenas para verificar o status. - `gateway status` resolve SecretRefs de autenticação configurados para autenticação da sondagem quando possível. - - Se um SecretRef de autenticação obrigatório não for resolvido nesse caminho de comando, `gateway status --json` relatará `rpc.authWarning` quando a conectividade/autenticação da sondagem falhar; passe `--token`/`--password` explicitamente ou resolva a origem do segredo primeiro. - - Se a sondagem for bem-sucedida, avisos de referências de autenticação não resolvidas serão suprimidos para evitar falsos positivos. - - Use `--require-rpc` em scripts e automação quando um serviço em escuta não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam íntegras. - - `--deep` adiciona uma verificação de melhor esforço por instalações extras de launchd/systemd/schtasks. Quando vários serviços semelhantes ao Gateway são detectados, a saída humana imprime dicas de limpeza e avisa que a maioria das configurações deve executar um Gateway por máquina. - - A saída humana inclui o caminho resolvido do log em arquivo mais um instantâneo dos caminhos/validade da configuração CLI-vs-serviço para ajudar a diagnosticar desvios de perfil ou diretório de estado. + - Se uma SecretRef de autenticação obrigatória não for resolvida neste caminho de comando, `gateway status --json` relata `rpc.authWarning` quando a conectividade/autenticação da sondagem falha; passe `--token`/`--password` explicitamente ou resolva a origem do segredo primeiro. + - Se a sondagem for bem-sucedida, avisos de referência de autenticação não resolvida serão suprimidos para evitar falsos positivos. + - Use `--require-rpc` em scripts e automação quando um serviço escutando não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam íntegras. + - `--deep` adiciona uma verificação de melhor esforço por instalações launchd/systemd/schtasks extras. Quando vários serviços semelhantes ao Gateway são detectados, a saída humana mostra dicas de limpeza e avisa que a maioria das configurações deve executar um Gateway por máquina. + - A saída humana inclui o caminho resolvido do arquivo de log, além de um instantâneo dos caminhos/validade da configuração da CLI versus serviço para ajudar a diagnosticar desvio de perfil ou diretório de estado. - - Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores `Environment=` e `EnvironmentFile=` da unidade (incluindo `%h`, caminhos entre aspas, múltiplos arquivos e arquivos opcionais com `-`). - - As verificações de desvio resolvem SecretRefs de `gateway.auth.token` usando o ambiente de runtime mesclado (primeiro o ambiente do comando do serviço, depois fallback para o ambiente do processo). - - Se a autenticação por token não estiver efetivamente ativa (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, ou modo não definido em que a senha pode prevalecer e nenhum candidato a token pode prevalecer), as verificações de desvio de token pulam a resolução do token de configuração. + - Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores de `Environment=` e `EnvironmentFile=` da unidade (incluindo `%h`, caminhos entre aspas, vários arquivos e arquivos opcionais com `-`). + - As verificações de desvio resolvem SecretRefs de `gateway.auth.token` usando o ambiente de runtime mesclado (primeiro o ambiente do comando de serviço, depois o ambiente do processo como fallback). + - Se a autenticação por token não estiver efetivamente ativa (`gateway.auth.mode` explícito como `password`/`none`/`trusted-proxy`, ou modo não definido quando a senha pode prevalecer e nenhum candidato a token pode prevalecer), as verificações de desvio de token ignoram a resolução do token de configuração. @@ -317,17 +317,17 @@ openclaw gateway status --require-rpc `gateway probe` é o comando de "depurar tudo". Ele sempre sonda: -- seu Gateway remoto configurado (se definido), e -- localhost (loopback) **mesmo se o remoto estiver configurado**. +- seu gateway remoto configurado (se definido), e +- localhost (loopback) **mesmo que o remoto esteja configurado**. -Se você passar `--url`, esse destino explícito será adicionado antes de ambos. A saída humana rotula os destinos como: +Se você passar `--url`, esse alvo explícito será adicionado antes de ambos. A saída humana rotula os alvos como: - `URL (explicit)` - `Remote (configured)` ou `Remote (configured, inactive)` - `Local loopback` -Se vários Gateways estiverem acessíveis, ele imprime todos. Múltiplos Gateways têm suporte quando você usa perfis/portas isolados (por exemplo, um bot de resgate), mas a maioria das instalações ainda executa um único Gateway. +Se vários gateways estiverem acessíveis, ele mostra todos. Vários gateways têm suporte quando você usa perfis/portas isolados (por exemplo, um bot de resgate), mas a maioria das instalações ainda executa um único gateway. ```bash @@ -337,51 +337,51 @@ openclaw gateway probe --json - - `Reachable: yes` significa que pelo menos um destino aceitou uma conexão WebSocket. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` relata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da alcançabilidade. - - `Read probe: ok` significa que chamadas RPC detalhadas com escopo de leitura (`health`/`status`/`system-presence`/`config.get`) também foram bem-sucedidas. - - `Read probe: limited - missing scope: operator.read` significa que a conexão foi bem-sucedida, mas o RPC com escopo de leitura está limitado. Isso é relatado como alcançabilidade **degradada**, não falha total. - - `Read probe: failed` após `Connect: ok` significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura subsequentes atingiram o tempo limite ou falharam. Isso também é alcançabilidade **degradada**, não um Gateway inalcançável. - - Assim como `gateway status`, a sondagem reutiliza a autenticação de dispositivo em cache existente, mas não cria identidade de dispositivo de primeira vez nem estado de pareamento. - - O código de saída é diferente de zero apenas quando nenhum destino sondado está acessível. + - `Reachable: yes` significa que pelo menos um alvo aceitou uma conexão WebSocket. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` relata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da acessibilidade. + - `Read probe: ok` significa que chamadas RPC de detalhe com escopo de leitura (`health`/`status`/`system-presence`/`config.get`) também foram bem-sucedidas. + - `Read probe: limited - missing scope: operator.read` significa que a conexão foi bem-sucedida, mas o RPC com escopo de leitura está limitado. Isso é relatado como acessibilidade **degradada**, não falha total. + - `Read probe: failed` após `Connect: ok` significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura seguintes atingiram o tempo limite ou falharam. Isso também é acessibilidade **degradada**, não um Gateway inacessível. + - Como `gateway status`, a sondagem reutiliza a autenticação de dispositivo em cache existente, mas não cria identidade de dispositivo de primeiro uso nem estado de pareamento. + - O código de saída é diferente de zero somente quando nenhum alvo sondado está acessível. Nível superior: - - `ok`: pelo menos um destino está acessível. - - `degraded`: pelo menos um destino aceitou uma conexão, mas não concluiu todos os diagnósticos RPC detalhados. - - `capability`: melhor capacidade vista entre destinos acessíveis (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` ou `unknown`). - - `primaryTargetId`: melhor destino a tratar como vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e depois local loopback. + - `ok`: pelo menos um alvo está acessível. + - `degraded`: pelo menos um alvo aceitou uma conexão, mas não concluiu todos os diagnósticos RPC detalhados. + - `capability`: melhor capacidade observada entre alvos acessíveis (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` ou `unknown`). + - `primaryTargetId`: melhor alvo a tratar como vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e, depois, local loopback. - `warnings[]`: registros de aviso de melhor esforço com `code`, `message` e `targetIds` opcionais. - `network`: dicas de URL de local loopback/tailnet derivadas da configuração atual e da rede do host. - - `discovery.timeoutMs` e `discovery.count`: o orçamento/contagem de resultados de descoberta reais usados nesta passagem de sondagem. + - `discovery.timeoutMs` e `discovery.count`: o orçamento/contagem de resultados real de descoberta usado nesta passada de sondagem. - Por destino (`targets[].connect`): + Por alvo (`targets[].connect`): - - `ok`: alcançabilidade após conexão + classificação degradada. - - `rpcOk`: sucesso total do RPC detalhado. - - `scopeLimited`: RPC detalhado falhou devido à ausência de escopo de operador. + - `ok`: acessibilidade após conexão + classificação degradada. + - `rpcOk`: sucesso completo de RPC detalhado. + - `scopeLimited`: o RPC detalhado falhou devido à ausência de escopo de operador. - Por destino (`targets[].auth`): + Por alvo (`targets[].auth`): - `role`: função de autenticação relatada em `hello-ok` quando disponível. - `scopes`: escopos concedidos relatados em `hello-ok` quando disponíveis. - - `capability`: a classificação de capacidade de autenticação exposta para esse destino. + - `capability`: a classificação de capacidade de autenticação exibida para esse alvo. - - `ssh_tunnel_failed`: a configuração do túnel SSH falhou; o comando recorreu a sondagens diretas. - - `multiple_gateways`: mais de um destino estava acessível; isso é incomum, a menos que você execute intencionalmente perfis isolados, como um bot de resgate. - - `auth_secretref_unresolved`: um SecretRef de autenticação configurado não pôde ser resolvido para um destino com falha. + - `ssh_tunnel_failed`: a configuração do túnel SSH falhou; o comando voltou para sondagens diretas. + - `multiple_gateways`: mais de um alvo estava acessível; isso é incomum, a menos que você execute perfis isolados intencionalmente, como um bot de resgate. + - `auth_secretref_unresolved`: uma SecretRef de autenticação configurada não pôde ser resolvida para um alvo com falha. - `probe_scope_limited`: a conexão WebSocket foi bem-sucedida, mas a sondagem de leitura foi limitada pela ausência de `operator.read`. -#### Remoto via SSH (paridade com o app para Mac) +#### Remoto via SSH (paridade do app Mac) -O modo "Remote over SSH" do app macOS usa um encaminhamento de porta local para que o Gateway remoto (que pode estar vinculado apenas ao loopback) fique acessível em `ws://127.0.0.1:`. +O modo "Remote over SSH" do app macOS usa um encaminhamento de porta local para que o gateway remoto (que pode estar vinculado apenas ao loopback) fique acessível em `ws://127.0.0.1:`. Equivalente na CLI: @@ -396,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host Arquivo de identidade. - Escolha o primeiro host de Gateway descoberto como destino SSH a partir do endpoint de descoberta resolvido (`local.` mais o domínio de longa distância configurado, se houver). Dicas somente TXT são ignoradas. + Escolha o primeiro host de Gateway descoberto como alvo SSH a partir do endpoint de descoberta resolvido (`local.` mais o domínio de longa distância configurado, se houver). Dicas somente TXT são ignoradas. Configuração (opcional, usada como padrão): @@ -429,7 +429,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Orçamento de tempo limite. - Principalmente para RPCs no estilo agente que transmitem eventos intermediários antes de um payload final. + Principalmente para RPCs no estilo de agente que transmitem eventos intermediários antes de um payload final. Saída JSON legível por máquina. @@ -439,7 +439,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' `--params` deve ser JSON válido. -## Gerencie o serviço Gateway +## Gerenciar o serviço Gateway ```bash openclaw gateway install @@ -452,8 +452,8 @@ openclaw gateway uninstall ### Instalar com um wrapper Use `--wrapper` quando o serviço gerenciado precisar iniciar por meio de outro executável, por exemplo um -shim de gerenciador de segredos ou um auxiliar run-as. O wrapper recebe os argumentos normais do Gateway e é -responsável por eventualmente executar `openclaw` ou Node com esses argumentos via exec. +shim de gerenciador de segredos ou um auxiliar de execução como outro usuário. O wrapper recebe os argumentos normais do Gateway e é +responsável por eventualmente executar `openclaw` ou Node com esses argumentos. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -477,7 +477,7 @@ OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install -- openclaw doctor ``` -Para remover um wrapper persistido, limpe `OPENCLAW_WRAPPER` durante a reinstalação: +Para remover um wrapper persistido, limpe `OPENCLAW_WRAPPER` ao reinstalar: ```bash OPENCLAW_WRAPPER= openclaw gateway install --force @@ -488,43 +488,44 @@ openclaw gateway restart - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` - - `gateway restart`: `--force`, `--wait `, `--json` + - `gateway restart`: `--safe`, `--force`, `--wait `, `--json` - `gateway uninstall|start|stop`: `--json` - Use `gateway restart` para reiniciar um serviço gerenciado. Não encadeie `gateway stop` e `gateway start` como substituto de reinicialização; no macOS, `gateway stop` desativa intencionalmente o LaunchAgent antes de pará-lo. + - `gateway restart --safe` solicita ao Gateway em execução que faça uma pré-verificação do trabalho ativo do OpenClaw e adie a reinicialização até que a entrega de respostas, execuções incorporadas e execuções de tarefas sejam drenadas. `--safe` não pode ser combinado com `--force` ou `--wait`. - `gateway restart --wait 30s` substitui o orçamento configurado de drenagem de reinicialização para essa reinicialização. Números sem unidade são milissegundos; unidades como `s`, `m` e `h` são aceitas. `--wait 0` aguarda indefinidamente. - - `gateway restart --force` pula a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já tiver inspecionado os bloqueadores de tarefas listados e quiser o Gateway de volta agora. - - Comandos de ciclo de vida aceitam `--json` para scripts. + - `gateway restart --force` ignora a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já inspecionou os bloqueadores de tarefas listados e quer o gateway de volta agora. + - Os comandos de ciclo de vida aceitam `--json` para scripts. - - - Quando a autenticação por token requer um token e `gateway.auth.token` é gerenciado por SecretRef, `gateway install` valida que o SecretRef pode ser resolvido, mas não persiste o token resolvido nos metadados de ambiente do serviço. - - Se a autenticação por token requer um token e o SecretRef de token configurado não é resolvido, a instalação falha de forma fechada em vez de persistir fallback em texto claro. - - Para autenticação por senha em `gateway run`, prefira `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` ou um `gateway.auth.password` com suporte de SecretRef em vez de `--password` inline. - - No modo de autenticação inferido, `OPENCLAW_GATEWAY_PASSWORD` apenas no shell não relaxa os requisitos de token de instalação; use configuração durável (`gateway.auth.password` ou `env` de configuração) ao instalar um serviço gerenciado. + + - Quando a autenticação por token exige um token e `gateway.auth.token` é gerenciado por SecretRef, `gateway install` valida que o SecretRef pode ser resolvido, mas não persiste o token resolvido nos metadados de ambiente do serviço. + - Se a autenticação por token exige um token e o SecretRef do token configurado não é resolvido, a instalação falha de modo fechado em vez de persistir texto simples de fallback. + - Para autenticação por senha em `gateway run`, prefira `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` ou um `gateway.auth.password` apoiado por SecretRef em vez de `--password` inline. + - No modo de autenticação inferido, `OPENCLAW_GATEWAY_PASSWORD` disponível apenas no shell não flexibiliza os requisitos de token da instalação; use configuração durável (`gateway.auth.password` ou `env` de configuração) ao instalar um serviço gerenciado. - Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, a instalação será bloqueada até que o modo seja definido explicitamente. -## Descobrir Gateways (Bonjour) +## Descobrir gateways (Bonjour) -`gateway discover` verifica beacons do Gateway (`_openclaw-gw._tcp`). +`gateway discover` verifica beacons de Gateway (`_openclaw-gw._tcp`). -- Multicast DNS-SD: `local.` -- Unicast DNS-SD (Bonjour de área ampla): escolha um domínio (exemplo: `openclaw.internal.`) e configure DNS dividido + um servidor DNS; consulte [Bonjour](/pt-BR/gateway/bonjour). +- DNS-SD multicast: `local.` +- DNS-SD unicast (Bonjour de área ampla): escolha um domínio (exemplo: `openclaw.internal.`) e configure DNS dividido + um servidor DNS; consulte [Bonjour](/pt-BR/gateway/bonjour). -Somente gateways com descoberta Bonjour habilitada (padrão) anunciam o sinalizador. +Somente gateways com descoberta Bonjour habilitada (padrão) anunciam o beacon. Registros de descoberta de área ampla incluem (TXT): - `role` (dica de função do gateway) - `transport` (dica de transporte, por exemplo, `gateway`) - `gatewayPort` (porta WebSocket, geralmente `18789`) -- `sshPort` (opcional; clientes usam `22` como destino SSH padrão quando ausente) -- `tailnetDns` (nome de host MagicDNS, quando disponível) +- `sshPort` (opcional; clientes usam `22` como padrão para destinos SSH quando ausente) +- `tailnetDns` (nome do host MagicDNS, quando disponível) - `gatewayTls` / `gatewayTlsSha256` (TLS habilitado + impressão digital do certificado) - `cliPath` (dica de instalação remota gravada na zona de área ampla) @@ -535,10 +536,10 @@ openclaw gateway discover ``` - Tempo limite por comando (busca/resolução). + Tempo limite por comando (browse/resolve). - Saída legível por máquina (também desabilita estilo/spinner). + Saída legível por máquina (também desativa estilo/spinner). Exemplos: @@ -549,13 +550,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- A CLI examina `local.` mais o domínio de área ampla configurado quando um está habilitado. -- `wsUrl` na saída JSON é derivado do endpoint de serviço resolvido, não de dicas apenas em TXT, como `lanHost` ou `tailnetDns`. -- Em mDNS `local.`, `sshPort` e `cliPath` só são transmitidos quando `discovery.mdns.mode` é `full`. DNS-SD de área ampla ainda grava `cliPath`; `sshPort` também permanece opcional lá. +- A CLI verifica `local.` mais o domínio de área ampla configurado quando algum está habilitado. +- `wsUrl` na saída JSON é derivado do endpoint de serviço resolvido, não de dicas apenas de TXT, como `lanHost` ou `tailnetDns`. +- No mDNS `local.`, `sshPort` e `cliPath` só são transmitidos quando `discovery.mdns.mode` é `full`. DNS-SD de área ampla ainda grava `cliPath`; `sshPort` também continua opcional ali. -## Relacionados +## Relacionado - [Referência da CLI](/pt-BR/cli) - [Runbook do Gateway](/pt-BR/gateway) diff --git a/docs/pt-BR/cli/plugins.md b/docs/pt-BR/cli/plugins.md index 26b6b278b..9a6e01961 100644 --- a/docs/pt-BR/cli/plugins.md +++ b/docs/pt-BR/cli/plugins.md @@ -1,15 +1,15 @@ --- read_when: - - Você deseja instalar ou gerenciar plugins do Gateway ou pacotes compatíveis - - Você quer depurar falhas de carregamento de Plugin + - Você quer instalar ou gerenciar plugins do Gateway ou pacotes compatíveis + - Você quer depurar falhas no carregamento de Plugin sidebarTitle: Plugins -summary: Referência da CLI para `openclaw plugins` (listar, instalar, marketplace, desinstalar, habilitar/desabilitar, doctor) +summary: Referência da CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugins x-i18n: - generated_at: "2026-05-04T09:37:13Z" + generated_at: "2026-05-05T01:44:32Z" model: gpt-5.5 provider: openai - source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4 + source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a source_path: cli/plugins.md workflow: 16 --- @@ -63,15 +63,15 @@ openclaw plugins marketplace list --json ``` Para investigar instalações, inspeções, desinstalações ou atualizações de registro lentas, execute o -comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava os tempos das fases +comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava tempos das fases em stderr e mantém a saída JSON analisável. Consulte [Depuração](/pt-BR/help/debugging#plugin-lifecycle-trace). -Plugins empacotados são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelo empacotados, provedores de fala empacotados e o Plugin de navegador empacotado); outros exigem `plugins enable`. +Plugins incluídos são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelos incluídos, provedores de fala incluídos e o plugin de navegador incluído); outros exigem `plugins enable`. -Plugins nativos do OpenClaw devem incluir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle. +Plugins nativos do OpenClaw devem distribuir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle. -`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo do bundle (`codex`, `claude` ou `cursor`) além das capacidades de bundle detectadas. +`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo do bundle (`codex`, `claude` ou `cursor`) mais as capacidades de bundle detectadas. ### Instalar @@ -93,17 +93,17 @@ openclaw plugins install --marketplace https://github.com// -Nomes de pacote simples são instalados a partir do npm por padrão durante a transição de lançamento. Use `clawhub:` para o ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas. +Nomes de pacotes sem prefixo são instalados a partir do npm por padrão durante a transição de lançamento. Use `clawhub:` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas. `plugins search` consulta o ClawHub em busca de pacotes de plugins instaláveis e imprime -nomes de pacotes prontos para instalação. Ele pesquisa pacotes de Plugin de código e Plugin de bundle, -não Skills. Use `openclaw skills search` para Skills do ClawHub. +nomes de pacotes prontos para instalação. Ele pesquisa pacotes de plugins de código e de plugins de bundle, +não skills. Use `openclaw skills search` para Skills do ClawHub. -ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. O npm -continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de Plugin -`@openclaw/*` mantidos pelo OpenClaw foram publicados novamente no npm; veja a lista atual +ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. Npm +continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de plugins +`@openclaw/*` de propriedade do OpenClaw voltaram a ser publicados no npm; veja a lista atual em [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou no [inventário de plugins](/pt-BR/plugins/plugin-inventory). Instalações estáveis usam `latest`. Instalações e atualizações do canal beta preferem a dist-tag `beta` do npm quando essa tag @@ -112,50 +112,50 @@ está disponível, depois recorrem a `latest`. - Se sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de includes e includes com substituições irmãs falham de forma fechada em vez de serem achatados. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis. + Se a sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` gravam nesse arquivo incluído e deixam `openclaw.json` intocado. Includes raiz, arrays de include e includes com sobrescritas irmãs falham de forma fechada em vez de serem achatados. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis. - Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e orienta você a executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração de Plugin inválida falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar a entrada inválida do Plugin em quarentena. A única exceção documentada em tempo de instalação é um caminho estreito de recuperação de Plugin empacotado para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`. + Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e orienta você a executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração inválida de plugin falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar em quarentena a entrada inválida do plugin. A única exceção documentada no momento da instalação é um caminho restrito de recuperação de plugin incluído para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`. - - `--force` reutiliza o destino de instalação existente e sobrescreve um Plugin ou pacote de hooks já instalado no lugar. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para upgrades rotineiros de um Plugin npm já rastreado, prefira `openclaw plugins update `. + + `--force` reutiliza o destino de instalação existente e sobrescreve no local um plugin ou pacote de hooks já instalado. Use quando estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para upgrades rotineiros de um plugin npm já rastreado, prefira `openclaw plugins update `. - Se você executar `plugins install` para um id de Plugin que já está instalado, o OpenClaw interrompe e aponta para `plugins update ` para um upgrade normal, ou para `plugins install --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente. + Se você executar `plugins install` para um id de plugin que já está instalado, o OpenClaw para e aponta para `plugins update ` para um upgrade normal, ou para `plugins install --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente. - `--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de fonte do marketplace em vez de uma especificação npm. + `--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados da fonte do marketplace em vez de uma especificação npm. - `--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no verificador integrado de código perigoso. Ela permite que a instalação continue mesmo quando o verificador integrado relata achados `critical`, mas **não** ignora bloqueios de política de hook `before_install` do Plugin e **não** ignora falhas de varredura. + `--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no scanner integrado de código perigoso. Ela permite que a instalação continue mesmo quando o scanner integrado relata achados `critical`, mas **não** contorna bloqueios de política de hook `before_install` do plugin e **não** contorna falhas de varredura. - Essa flag da CLI se aplica a fluxos de instalação/atualização de Plugin. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub. + Essa flag de CLI se aplica a fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de requisição correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub. - Se um Plugin que você publicou no ClawHub for bloqueado por uma varredura de registro, use as etapas para publicadores em [ClawHub](/pt-BR/tools/clawhub). + Se um plugin que você publicou no ClawHub for bloqueado por uma varredura do registro, use as etapas de publicador em [ClawHub](/pt-BR/tools/clawhub). - `plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacote. + `plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacotes. - Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências rodam localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm. + Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências são executadas localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação do npm. - Use `npm:` quando quiser explicitar a resolução npm. Especificações de pacote simples também instalam diretamente do npm durante a transição de lançamento. + Use `npm:` quando quiser tornar a resolução npm explícita. Especificações de pacote sem prefixo também instalam diretamente do npm durante a transição de lançamento. - Especificações simples e `@latest` permanecem na faixa estável. Versões de correção datadas do OpenClaw, como `2026.5.3-1`, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você aceite explicitamente com uma tag de pré-versão, como `@beta`/`@rc`, ou uma versão de pré-lançamento exata, como `@1.2.3-beta.4`. + Especificações sem prefixo e `@latest` permanecem na trilha estável. Versões de correção do OpenClaw com carimbo de data, como `2026.5.3-1`, são lançamentos estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw para e pede que você opte explicitamente por uma tag de pré-versão, como `@beta`/`@rc`, ou por uma versão de pré-lançamento exata, como `@1.2.3-beta.4`. - Se uma especificação de instalação simples corresponder a um id oficial de Plugin (por exemplo, `diffs`), o OpenClaw instala a entrada do catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícito (por exemplo, `@scope/diffs`). + Se uma especificação de instalação sem prefixo corresponder a um id oficial de plugin (por exemplo, `diffs`), o OpenClaw instala a entrada do catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícito (por exemplo, `@scope/diffs`). - Use `git:` para instalar diretamente de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completas `https://`, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git` de clone. Adicione `@` ou `#` para fazer checkout de um branch, tag ou commit antes da instalação. + Use `git:` para instalar diretamente a partir de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completos `https://`, `ssh://`, `git://`, `file://` e URLs de clone `git@host:owner/repo.git`. Adicione `@` ou `#` para fazer checkout de uma branch, tag ou commit antes da instalação. - Instalações Git clonam para um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de Plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a fonte mais tarde. + Instalações Git clonam em um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a fonte depois. - Depois de instalar a partir de git, use `openclaw plugins inspect --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos da CLI. Se o Plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`. + Depois de instalar a partir de git, use `openclaw plugins inspect --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos de CLI. Se o plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`. - Arquivos compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos de Plugin nativo do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do Plugin; arquivos que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação. + Arquivos compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos de plugins nativos do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do plugin; arquivos que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação. Instalações do marketplace Claude também são compatíveis. @@ -169,25 +169,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Especificações de Plugin simples seguras para npm instalam a partir do npm por padrão durante a transição de lançamento: +Especificações de plugin seguras para npm sem prefixo são instaladas a partir do npm por padrão durante a transição de lançamento: ```bash openclaw plugins install openclaw-codex-app-server ``` -Use `npm:` para explicitar a resolução somente por npm: +Use `npm:` para tornar a resolução somente npm explícita: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -O OpenClaw verifica a API de Plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo. Versões antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações posteriores. -Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que `openclaw plugins update` possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor. +O OpenClaw verifica a API de plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo. Versões antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações futuras. +Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que `openclaw plugins update` possa acompanhar lançamentos mais novos do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados a esse seletor. -#### Atalho de marketplace +#### Abreviação de marketplace -Use o atalho `plugin@marketplace` quando o nome do marketplace existir no cache de registro local do Claude em `~/.claude/plugins/known_marketplaces.json`: +Use a abreviação `plugin@marketplace` quando o nome do marketplace existir no cache local de registro do Claude em `~/.claude/plugins/known_marketplaces.json`: ```bash openclaw plugins marketplace list @@ -204,28 +204,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - + - um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json` - - uma raiz de marketplace local ou um caminho `marketplace.json` - - um atalho de repositório do GitHub, como `owner/repo` - - uma URL de repositório do GitHub, como `https://github.com/owner/repo` + - uma raiz de marketplace local ou caminho de `marketplace.json` + - um atalho de repositório GitHub, como `owner/repo` + - uma URL de repositório GitHub, como `https://github.com/owner/repo` - uma URL git - - Para marketplaces remotos carregados do GitHub ou git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras fontes de Plugin que não sejam caminhos em manifests remotos. + + Para marketplaces remotos carregados do GitHub ou git, as entradas de plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras fontes de plugin que não sejam caminhos em manifestos remotos. -Para caminhos locais e arquivos compactados, o OpenClaw detecta automaticamente: +Para caminhos locais e arquivos, o OpenClaw detecta automaticamente: -- Plugins nativos do OpenClaw (`openclaw.plugin.json`) +- plugins nativos do OpenClaw (`openclaw.plugin.json`) - pacotes compatíveis com Codex (`.codex-plugin/plugin.json`) - pacotes compatíveis com Claude (`.claude-plugin/plugin.json` ou o layout padrão de componentes do Claude) - pacotes compatíveis com Cursor (`.cursor-plugin/plugin.json`) -Pacotes compatíveis são instalados na raiz normal de Plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifest, Skills de comando do Cursor e diretórios de hooks compatíveis do Codex; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime. +Pacotes compatíveis são instalados na raiz normal de plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifesto, Skills de comando do Cursor e diretórios de hooks Codex compatíveis; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime. ### Listar @@ -241,28 +241,29 @@ openclaw plugins search --json ``` - Mostra apenas Plugins habilitados. + Mostra apenas plugins habilitados. - Alterna da visualização em tabela para linhas detalhadas por Plugin com metadados de fonte/origem/versão/ativação. + Alterna da visualização em tabela para linhas de detalhes por plugin com metadados de fonte/origem/versão/ativação. - Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacote. + Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências do pacote. -`plugins list` lê primeiro o registro local persistido de Plugins, com um fallback derivado apenas de manifest quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime em tempo real de um processo Gateway já em execução. Depois de alterar código de Plugin, habilitação, política de hooks ou `plugins.load.paths`, reinicie o Gateway que atende o canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper. +`plugins list` lê primeiro o registro de plugins local persistido, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um plugin está instalado, habilitado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime ativa de um processo Gateway já em execução. Depois de alterar o código do plugin, a habilitação, a política de hooks ou `plugins.load.paths`, reinicie o Gateway que atende ao canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper. -`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` de `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de busca `node_modules` do Node do Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes. +`plugins list --json` inclui o `dependencyStatus` de cada plugin a partir de +`dependencies` e `optionalDependencies` em `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de consulta de `node_modules` do Node do plugin; ele não importa código de runtime do plugin, não executa um gerenciador de pacotes nem repara dependências ausentes. -`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados da busca incluem o nome do pacote no ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:`. +`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera a configuração, não instala pacotes nem carrega código de runtime de plugin. Os resultados da busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:`. -Para trabalho com Plugin incluído dentro de uma imagem Docker empacotada, monte o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, de modo que instalações empacotadas normais continuam usando o dist compilado. +Para trabalho com plugin incluído em uma imagem Docker empacotada, monte com bind o diretório de origem do plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, para que instalações empacotadas normais ainda usem o dist compilado. Para depuração de hooks em runtime: -- `openclaw plugins inspect --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou instalar Plugins baixáveis configurados que estejam ausentes. +- `openclaw plugins inspect --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou recuperar plugins baixáveis ausentes referenciados pela configuração. - `openclaw gateway status --deep --require-rpc` confirma o Gateway acessível, dicas de serviço/processo, caminho de configuração e integridade de RPC. - Hooks de conversa não incluídos (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigem `plugins.entries..hooks.allowConversationAccess=true`. @@ -275,14 +276,14 @@ openclaw plugins install -l ./my-plugin `--force` não é compatível com `--link` porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado. -Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de Plugins gerenciado, mantendo o comportamento padrão sem fixação. +Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de plugins gerenciado, mantendo o comportamento padrão sem fixação. -### Índice de Plugins +### Índice de plugins -Metadados de instalação de Plugin são estado gerenciado pela máquina, não configuração do usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros de manifests de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado de manifest. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e o registro frio de Plugins. +Metadados de instalação de plugins são estado gerenciado por máquina, não configuração de usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável dos metadados de instalação, incluindo registros de manifestos de plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado do manifesto. O arquivo inclui um aviso para não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e pelo registro frio de plugins. -Quando o OpenClaw vê registros legados enviados de `plugins.installs` na configuração, ele os move para o índice de Plugins e remove a chave de configuração; se qualquer uma das gravações falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos. +Quando o OpenClaw encontra registros legados enviados em `plugins.installs` na configuração, ele os move para o índice de plugins e remove a chave de configuração; se qualquer gravação falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos. ### Desinstalar @@ -292,10 +293,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de Plugins, de entradas de lista de permissão/negação de Plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de Plugins do OpenClaw. Para Plugins de Active Memory, o slot de memória é redefinido para `memory-core`. +`uninstall` remove registros de plugin de `plugins.entries`, do índice de plugins persistido, de entradas de lista de permissão/bloqueio de plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de plugins do OpenClaw. Para plugins de memória ativa, o slot de memória é redefinido para `memory-core`. -`--keep-config` é compatível como um alias obsoleto de `--keep-files`. +`--keep-config` é compatível como alias obsoleto de `--keep-files`. ### Atualizar @@ -308,29 +309,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Atualizações se aplicam a instalações de Plugin rastreadas no índice de Plugins gerenciado e a instalações de pacotes de hooks rastreadas em `hooks.internal.installs`. +Atualizações se aplicam a instalações de plugin rastreadas no índice de plugins gerenciado e a instalações de pacotes de hooks rastreadas em `hooks.internal.installs`. - - Quando você passa um id de Plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam sendo usadas em execuções posteriores de `update `. + + Quando você passa um id de plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam sendo usadas em execuções posteriores de `update `. - Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id. + Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de plugin rastreado, atualiza esse plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id. - Passar o nome do pacote npm sem versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin tiver sido fixado a uma versão exata e você quiser movê-lo de volta para a linha de lançamento padrão do registro. + Passar o nome do pacote npm sem uma versão ou tag também resolve de volta para o registro de plugin rastreado. Use isso quando um plugin foi fixado em uma versão exata e você quer movê-lo de volta para a linha de lançamento padrão do registro. - - `openclaw plugins update` reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e, em seguida, fazem fallback para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor. + + `openclaw plugins update` reutiliza a especificação de plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e depois retornam para a especificação padrão/latest registrada se não existir uma versão beta do plugin. Versões exatas e tags explícitas permanecem fixadas a esse seletor. - - Antes de uma atualização npm em tempo real, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`. + + Antes de uma atualização npm ativa, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já correspondem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`. - Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de continuar. Auxiliares de atualização não interativos falham em modo fechado, a menos que o chamador forneça uma política de continuação explícita. + Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e solicita confirmação antes de continuar. Auxiliares de atualização não interativos falham de forma fechada, a menos que o chamador forneça uma política explícita de continuação. - - `--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição de emergência para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não contorna bloqueios de política `before_install` do Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de pacotes de hooks. + + `--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição de emergência para falsos positivos da verificação integrada de código perigoso durante atualizações de plugins. Ele ainda não contorna bloqueios de política `before_install` de plugin nem bloqueios por falha de verificação, e se aplica apenas a atualizações de plugins, não a atualizações de pacotes de hooks. @@ -342,21 +343,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -A inspeção mostra identidade, estado de carregamento, fonte, recursos do manifest, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidores MCP ou LSP sem importar o runtime do Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção de runtime relata dependências ausentes do Plugin diretamente; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`. +Inspecionar mostra identidade, status de carregamento, fonte, capacidades do manifesto, sinalizadores de política, diagnósticos, metadados de instalação, capacidades de pacote e qualquer suporte detectado a servidor MCP ou LSP sem importar o runtime do plugin por padrão. Adicione `--runtime` para carregar o módulo do plugin e incluir hooks, ferramentas, comandos, serviços, métodos de gateway e rotas HTTP registrados. A inspeção de runtime relata dependências de plugin ausentes diretamente; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`. -Comandos de CLI pertencentes a Plugins são instalados como grupos de comandos raiz `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`. +Comandos de CLI pertencentes a plugins são instalados como grupos de comandos raiz de `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw ...`; por exemplo, um plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`. -Cada Plugin é classificado pelo que ele realmente registra em runtime: +Cada plugin é classificado pelo que ele realmente registra em runtime: -- **plain-capability** — um tipo de recurso (por exemplo, um Plugin apenas de provedor) -- **hybrid-capability** — vários tipos de recurso (por exemplo, texto + fala + imagens) -- **hook-only** — apenas hooks, sem recursos ou superfícies -- **non-capability** — ferramentas/comandos/serviços, mas sem recursos +- **plain-capability** — um tipo de capacidade (por exemplo, um plugin somente de provedor) +- **hybrid-capability** — vários tipos de capacidade (por exemplo, texto + fala + imagens) +- **hook-only** — apenas hooks, sem capacidades ou superfícies +- **non-capability** — ferramentas/comandos/serviços, mas sem capacidades -Consulte [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de recursos. +Consulte [Formatos de plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de capacidades. -A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de recurso, avisos de compatibilidade, recursos de pacote e resumo de hooks. `info` é um alias de `inspect`. +A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de capacidade, avisos de compatibilidade, capacidades de pacote e resumo de hooks. `info` é um alias de `inspect`. ### Doctor @@ -365,11 +366,11 @@ A flag `--json` gera um relatório legível por máquina adequado para scripts e openclaw plugins doctor ``` -`doctor` relata erros de carregamento de Plugin, diagnósticos de manifest/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.` +`doctor` relata erros de carregamento de plugins, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.` -Se um Plugin configurado estiver presente no disco, mas bloqueado pelas verificações de segurança de caminho do loader, a validação de configuração mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade de caminho ou permissões graváveis pelo mundo, em vez de remover a configuração `plugins.entries.` ou `plugins.allow`. +Se um plugin configurado está presente no disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação de configuração mantém a entrada do plugin e a relata como `present but blocked`. Corrija o diagnóstico de plugin bloqueado anterior, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a configuração `plugins.entries.` ou `plugins.allow`. -Para falhas de formato de módulo, como exports `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato dos exports na saída de diagnóstico. +Para falhas de formato de módulo, como exportações `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato de exportação na saída de diagnóstico. ### Registro @@ -379,14 +380,14 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -O registro local de Plugins é o modelo persistido de leitura fria do OpenClaw para identidade de Plugins instalados, habilitação, metadados de fonte e propriedade de contribuição. A inicialização normal, a busca de proprietário de provedor, a classificação de configuração de canal e o inventário de Plugins podem lê-lo sem importar módulos de runtime de Plugin. +O registro local de plugins é o modelo de leitura fria persistido do OpenClaw para identidade de plugins instalados, habilitação, metadados de fonte e propriedade de contribuições. Inicialização normal, consulta de proprietário de provedor, classificação de configuração de canal e inventário de plugins podem lê-lo sem importar módulos de runtime de plugins. -Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice persistido de Plugins, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução. +Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice de Plugin persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução. -`openclaw doctor --fix` também repara desvios de npm gerenciado adjacentes ao registro: se um pacote `@openclaw/*` órfão ou recuperado sob a raiz npm de Plugins gerenciados sombrear um Plugin incluído, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto incluído. +`openclaw doctor --fix` também repara desvios de npm gerenciado adjacentes ao registro: se um pacote `@openclaw/*` órfão ou recuperado sob a raiz npm de Plugin gerenciado sombrear um Plugin incluído, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto incluído. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma chave de compatibilidade emergencial obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por env é apenas para recuperação emergencial de inicialização enquanto a migração é distribuída. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma opção de compatibilidade emergencial obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por env é apenas para recuperação emergencial de inicialização enquanto a migração é implantada. ### Mercado @@ -396,10 +397,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -A listagem do mercado aceita um caminho local de mercado, um caminho `marketplace.json`, um atalho do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da fonte resolvida, além do manifesto de mercado analisado e das entradas de Plugin. +A listagem do mercado aceita um caminho de mercado local, um caminho `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório GitHub ou uma URL git. `--json` imprime o rótulo da fonte resolvida mais o manifesto de mercado analisado e as entradas de Plugin. ## Relacionado -- [Criando Plugins](/pt-BR/plugins/building-plugins) +- [Criação de Plugins](/pt-BR/plugins/building-plugins) - [Referência da CLI](/pt-BR/cli) - [Plugins da comunidade](/pt-BR/plugins/community) diff --git a/docs/pt-BR/cli/sessions.md b/docs/pt-BR/cli/sessions.md index 0b97985f6..8753258c5 100644 --- a/docs/pt-BR/cli/sessions.md +++ b/docs/pt-BR/cli/sessions.md @@ -1,30 +1,31 @@ --- read_when: - - Você quer listar as sessões armazenadas e ver a atividade recente + - Você quer listar sessões armazenadas e ver a atividade recente summary: Referência da CLI para `openclaw sessions` (listar sessões armazenadas + uso) title: Sessões x-i18n: - generated_at: "2026-05-04T07:02:44Z" + generated_at: "2026-05-05T01:44:15Z" model: gpt-5.5 provider: openai - source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e + source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7 source_path: cli/sessions.md workflow: 16 --- # `openclaw sessions` -Liste sessões de conversa armazenadas. +Liste as sessões de conversa armazenadas. -Listas de sessões não são verificações de disponibilidade de canal/provedor. Elas mostram linhas de conversa persistidas dos armazenamentos de sessões. Um Discord, Slack, Telegram ou outro canal silencioso pode se reconectar com sucesso sem criar uma nova linha de sessão até que uma mensagem seja processada. Use `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` quando precisar de conectividade de canal ao vivo. +Listas de sessões não são verificações de conectividade de canal/provedor. Elas mostram linhas de conversa persistidas dos armazenamentos de sessão. Um Discord, Slack, Telegram ou outro canal silencioso pode se reconectar com sucesso sem criar uma nova linha de sessão até que uma mensagem seja processada. Use `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` quando precisar de conectividade de canal ao vivo. -As respostas `sessions.list` do Gateway são limitadas por padrão para que armazenamentos grandes e de longa duração não monopolizem o loop de eventos do Gateway. Passe um `limit` positivo explícito de clientes RPC quando uma janela de resultados diferente for necessária; as respostas incluem `totalCount`, `limitApplied` e `hasMore` quando os chamadores precisam mostrar que existem mais linhas. +As respostas de `openclaw sessions` e Gateway `sessions.list` são limitadas por padrão para que armazenamentos grandes e de longa duração não monopolizem o processo da CLI ou o loop de eventos do Gateway. A CLI retorna as 100 sessões mais recentes por padrão; passe `--limit ` para uma janela menor/maior ou `--limit all` quando você precisar intencionalmente do armazenamento completo. Respostas JSON incluem `totalCount`, `limitApplied` e `hasMore` quando chamadores precisam mostrar que existem mais linhas. ```bash openclaw sessions openclaw sessions --agent work openclaw sessions --all-agents openclaw sessions --active 120 +openclaw sessions --limit 25 openclaw sessions --verbose openclaw sessions --json ``` @@ -35,7 +36,8 @@ Seleção de escopo: - `--verbose`: registro em log detalhado - `--agent `: um armazenamento de agente configurado - `--all-agents`: agrega todos os armazenamentos de agentes configurados -- `--store `: caminho explícito do armazenamento (não pode ser combinado com `--agent` ou `--all-agents`) +- `--store `: caminho de armazenamento explícito (não pode ser combinado com `--agent` ou `--all-agents`) +- `--limit `: máximo de linhas a gerar na saída (padrão `100`; `all` restaura a saída completa) Exporte um pacote de trajetória para uma sessão armazenada: @@ -44,9 +46,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de exec. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no workspace selecionado. +Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de execução. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no workspace selecionado. -`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` com modelo. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; symlinks e caminhos fora da raiz são ignorados. +`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` modelada. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; links simbólicos e caminhos fora da raiz são ignorados. Exemplos JSON: @@ -61,6 +63,9 @@ Exemplos JSON: ], "allAgents": true, "count": 2, + "totalCount": 2, + "limitApplied": 100, + "hasMore": false, "activeMinutes": null, "sessions": [ { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" }, @@ -82,21 +87,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` usa as configurações `session.maintenance` da configuração: +`openclaw sessions cleanup` usa as configurações de `session.maintenance` da configuração: -- Observação de escopo: `openclaw sessions cleanup` faz manutenção de armazenamentos de sessões, transcrições e sidecars de trajetória. Ele não remove logs de execução de Cron (`cron/runs/.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance). +- Observação de escopo: `openclaw sessions cleanup` mantém armazenamentos de sessão, transcrições e sidecars de trajetória. Ele não poda logs de execução de Cron (`cron/runs/.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance). -- `--dry-run`: visualiza quantas entradas seriam removidas/limitadas sem gravar. - - No modo de texto, dry-run imprime uma tabela de ações por sessão (`Action`, `Key`, `Age`, `Model`, `Flags`) para que você veja o que seria mantido ou removido. -- `--enforce`: aplica manutenção mesmo quando `session.maintenance.mode` é `warn`. +- `--dry-run`: visualize quantas entradas seriam podadas/limitadas sem gravar. + - No modo de texto, dry-run imprime uma tabela de ações por sessão (`Action`, `Key`, `Age`, `Model`, `Flags`) para que você possa ver o que seria mantido vs removido. +- `--enforce`: aplica a manutenção mesmo quando `session.maintenance.mode` é `warn`. - `--fix-missing`: remove entradas cujos arquivos de transcrição estão ausentes, mesmo que elas normalmente ainda não fossem removidas por idade/contagem. -- `--active-key `: protege uma chave ativa específica da remoção por orçamento de disco. Ponteiros duráveis de conversas externas, como sessões de grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção de idade/contagem/orçamento de disco. +- `--active-key `: protege uma chave ativa específica contra remoção por orçamento de disco. Ponteiros duráveis de conversas externas, como sessões de grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção por idade/contagem/orçamento de disco. - `--agent `: executa a limpeza para um armazenamento de agente configurado. - `--all-agents`: executa a limpeza para todos os armazenamentos de agentes configurados. - `--store `: executa contra um arquivo `sessions.json` específico. - `--json`: imprime um resumo JSON. Com `--all-agents`, a saída inclui um resumo por armazenamento. -Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada pelo Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões que o tráfego de runtime. Use `--store ` para reparo offline explícito de um arquivo de armazenamento. +Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada por meio do Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões do tráfego de runtime. Use `--store ` para reparo offline explícito de um arquivo de armazenamento. `openclaw sessions cleanup --all-agents --dry-run --json`: @@ -128,9 +133,9 @@ Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de Relacionado: -- Configuração de sessão: [Referência de configuração](/pt-BR/gateway/config-agents#session) +- Configuração de sessão: [referência de configuração](/pt-BR/gateway/config-agents#session) ## Relacionado -- [Referência da CLI](/pt-BR/cli) -- [Gerenciamento de sessões](/pt-BR/concepts/session) +- [referência da CLI](/pt-BR/cli) +- [gerenciamento de sessões](/pt-BR/concepts/session) diff --git a/docs/pt-BR/cli/update.md b/docs/pt-BR/cli/update.md index a7cd70cbc..f07dcca55 100644 --- a/docs/pt-BR/cli/update.md +++ b/docs/pt-BR/cli/update.md @@ -1,15 +1,15 @@ --- read_when: - - Você quer atualizar um checkout do código-fonte com segurança + - Você quer atualizar um checkout de código-fonte com segurança - Você está depurando a saída ou as opções de `openclaw update` - - Você precisa entender o comportamento da forma abreviada `--update` -summary: Referência da CLI para `openclaw update` (atualização do código-fonte relativamente segura + reinicialização automática do Gateway) + - Você precisa entender o comportamento abreviado de `--update` +summary: Referência da CLI para `openclaw update` (atualização de origem relativamente segura + reinício automático do Gateway) title: Atualizar x-i18n: - generated_at: "2026-05-03T21:29:30Z" + generated_at: "2026-05-05T01:45:10Z" model: gpt-5.5 provider: openai - source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8 + source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f source_path: cli/update.md workflow: 16 --- @@ -18,7 +18,7 @@ x-i18n: Atualize o OpenClaw com segurança e alterne entre os canais stable/beta/dev. -Se você instalou via **npm/pnpm/bun** (instalação global, sem metadados git), +Se você instalou via **npm/pnpm/bun** (instalação global, sem metadados do git), as atualizações acontecem pelo fluxo do gerenciador de pacotes em [Atualização](/pt-BR/install/updating). ## Uso @@ -40,23 +40,24 @@ openclaw --update ## Opções -- `--no-restart`: ignora a reinicialização do serviço Gateway após uma atualização bem-sucedida. Atualizações por gerenciador de pacotes que reiniciam o Gateway verificam se o serviço reiniciado informa a versão atualizada esperada antes de o comando ser concluído com sucesso. -- `--channel `: define o canal de atualização (git + npm; persistido na configuração). -- `--tag `: substitui o destino do pacote somente para esta atualização. Para instalações de pacote, `main` é mapeado para `github:openclaw/openclaw#main`. -- `--dry-run`: pré-visualiza as ações de atualização planejadas (fluxo de canal/tag/destino/reinicialização) sem gravar configuração, instalar, sincronizar plugins ou reiniciar. -- `--json`: imprime JSON `UpdateRunResult` legível por máquina, incluindo - `postUpdate.plugins.integrityDrifts` quando divergência de artefato de plugin npm é - detectada durante a sincronização de plugins pós-atualização. +- `--no-restart`: pule a reinicialização do serviço Gateway após uma atualização bem-sucedida. Atualizações por gerenciador de pacotes que reiniciam o Gateway verificam se o serviço reiniciado informa a versão atualizada esperada antes de o comando ser concluído com sucesso. +- `--channel `: defina o canal de atualização (git + npm; persistido na configuração). +- `--tag `: substitua o pacote de destino somente para esta atualização. Para instalações por pacote, `main` mapeia para `github:openclaw/openclaw#main`. +- `--dry-run`: visualize as ações de atualização planejadas (fluxo de canal/tag/destino/reinicialização) sem gravar configuração, instalar, sincronizar plugins ou reiniciar. +- `--json`: imprima JSON `UpdateRunResult` legível por máquina, incluindo + `postUpdate.plugins.integrityDrifts` quando desvio de artefato de Plugin npm for + detectado durante a sincronização de plugins pós-atualização. - `--timeout `: tempo limite por etapa (o padrão é 1800s). -- `--yes`: ignora prompts de confirmação (por exemplo, confirmação de downgrade). +- `--yes`: pule prompts de confirmação (por exemplo, confirmação de downgrade). -`openclaw update` não tem uma flag `--verbose`. Use `--dry-run` para pré-visualizar -as ações planejadas de canal/tag/instalação/reinicialização, `--json` para resultados -legíveis por máquina e `openclaw update status --json` quando você só precisar dos -detalhes de canal e disponibilidade. Se você estiver depurando logs do Gateway em torno de uma atualização, -a verbosidade do console e o nível de log em arquivo são separados: `--verbose` do Gateway afeta -a saída de terminal/WebSocket, enquanto logs em arquivo exigem `logging.level: "debug"` ou -`"trace"` na configuração. Veja [Logs do Gateway](/pt-BR/gateway/logging). +`openclaw update` não tem uma flag `--verbose`. Use `--dry-run` para visualizar +as ações planejadas de canal/tag/instalação/reinicialização, `--json` para +resultados legíveis por máquina, e `openclaw update status --json` quando você +só precisar de detalhes de canal e disponibilidade. Se você estiver depurando +logs do Gateway durante uma atualização, a verbosidade do console e o nível de +log em arquivo são separados: Gateway `--verbose` afeta a saída +terminal/WebSocket, enquanto logs em arquivo exigem `logging.level: "debug"` ou +`"trace"` na configuração. Consulte [logs do Gateway](/pt-BR/gateway/logging). Downgrades exigem confirmação porque versões mais antigas podem quebrar a configuração. @@ -64,7 +65,7 @@ Downgrades exigem confirmação porque versões mais antigas podem quebrar a con ## `update status` -Mostra o canal de atualização ativo + tag/branch/SHA do git (para checkouts de origem), além da disponibilidade de atualização. +Mostre o canal de atualização ativo + tag/branch/SHA do git (para checkouts de código-fonte), além da disponibilidade de atualização. ```bash openclaw update status @@ -74,13 +75,13 @@ openclaw update status --timeout 10 Opções: -- `--json`: imprime JSON de status legível por máquina. +- `--json`: imprima JSON de status legível por máquina. - `--timeout `: tempo limite para verificações (o padrão é 3s). ## `update wizard` -Fluxo interativo para escolher um canal de atualização e confirmar se o Gateway deve ser reiniciado -após a atualização (o padrão é reiniciar). Se você selecionar `dev` sem um checkout git, ele +Fluxo interativo para escolher um canal de atualização e confirmar se deve reiniciar o Gateway +após atualizar (o padrão é reiniciar). Se você selecionar `dev` sem um checkout git, ele oferece criar um. Opções: @@ -89,114 +90,115 @@ Opções: ## O que ele faz -Quando você troca de canal explicitamente (`--channel ...`), o OpenClaw também mantém o +Quando você alterna canais explicitamente (`--channel ...`), o OpenClaw também mantém o método de instalação alinhado: - `dev` → garante um checkout git (padrão: `~/openclaw`, substitua com `OPENCLAW_GIT_DIR`), atualiza-o e instala a CLI global a partir desse checkout. - `stable` → instala do npm usando `latest`. -- `beta` → prefere a dist-tag npm `beta`, mas recua para `latest` quando beta está +- `beta` → prefere a dist-tag npm `beta`, mas recorre a `latest` quando beta está ausente ou é mais antiga que a versão stable atual. O atualizador automático do núcleo do Gateway (quando habilitado via configuração) inicia o caminho de atualização da CLI -fora do manipulador de requisições ativo do Gateway. Atualizações de gerenciador de pacotes -`update.run` do plano de controle forçam uma reinicialização de atualização não adiada e sem cooldown após a troca do pacote, -porque o processo antigo do Gateway ainda pode ter partes em memória apontando para +fora do manipulador de requisições ativo do Gateway. Atualizações por gerenciador de pacotes +`update.run` do plano de controle forçam uma reinicialização de atualização sem adiamento e sem cooldown após a troca do pacote, +porque o processo antigo do Gateway ainda pode ter chunks em memória que apontam para arquivos removidos pelo novo pacote. Para instalações por gerenciador de pacotes, `openclaw update` resolve a versão -do pacote de destino antes de invocar o gerenciador de pacotes. Instalações globais npm usam uma instalação -em estágio: o OpenClaw instala o novo pacote em um prefixo npm temporário, verifica -o inventário `dist` empacotado ali e então troca essa árvore limpa de pacote para o -prefixo global real. Se a verificação falhar, o doctor pós-atualização, a sincronização de plugins e -o trabalho de reinicialização não rodam a partir da árvore suspeita. Mesmo quando a versão instalada -já corresponde ao destino, o comando atualiza a instalação global do pacote, -depois executa a sincronização de plugins, uma atualização de conclusão de comando principal e o trabalho de reinicialização. Isso -mantém sidecars empacotados e registros de plugins pertencentes ao canal alinhados com a -build instalada do OpenClaw, deixando reconstruções completas de conclusão de comandos de plugins para +do pacote de destino antes de invocar o gerenciador de pacotes. Instalações globais npm usam uma instalação em estágio: +o OpenClaw instala o novo pacote em um prefixo npm temporário, verifica +o inventário `dist` empacotado ali e então troca essa árvore de pacote limpa para o +prefixo global real. Se a verificação falhar, doctor pós-atualização, sincronização de plugins e +reinicialização não são executados a partir da árvore suspeita. Mesmo quando a versão instalada +já corresponde ao destino, o comando atualiza a instalação do pacote global, +depois executa sincronização de plugins, uma atualização de completions de comandos principais e a reinicialização. Isso +mantém sidecars empacotados e registros de Plugin pertencentes ao canal alinhados com a +build do OpenClaw instalada, deixando reconstruções completas de completions de comandos de Plugin para execuções explícitas de `openclaw completion --write-state`. Quando um serviço Gateway gerenciado local está instalado e a reinicialização está habilitada, atualizações por gerenciador de pacotes param o serviço em execução antes de substituir a árvore -do pacote, depois atualizam os metadados do serviço a partir da instalação atualizada, reiniciam o +do pacote, então atualizam os metadados do serviço a partir da instalação atualizada, reiniciam o serviço e verificam se o Gateway reiniciado informa a versão esperada antes de -relatar sucesso. No macOS, a verificação pós-atualização também verifica se o LaunchAgent -está carregado/em execução para o perfil ativo e se a porta de local loopback configurada está -saudável. Se o plist está instalado, mas o launchd não o supervisiona, o OpenClaw -reexecuta o bootstrap do LaunchAgent automaticamente, depois executa novamente as -verificações de prontidão de saúde/versão/canal. Um bootstrap novo carrega o job RunAtLoad +informar sucesso. No macOS, a verificação pós-atualização também verifica se o LaunchAgent +está carregado/em execução para o perfil ativo e se a porta de loopback configurada está +saudável. Se o plist estiver instalado, mas o launchd não estiver supervisionando-o, o OpenClaw +reinicializa o LaunchAgent automaticamente e então executa novamente as verificações de +saúde/versão/prontidão de canal. Um bootstrap novo carrega o job RunAtLoad diretamente, então a recuperação de atualização não executa imediatamente `kickstart -k` no Gateway -recém-iniciado. Se o Gateway ainda não ficar saudável, o comando sai -com código diferente de zero e imprime o caminho do log de reinicialização mais instruções explícitas de reinicialização, reinstalação e -rollback de pacote. Com `--no-restart`, +recém-criado. Se o Gateway ainda não ficar saudável, o comando sai +com código diferente de zero e imprime o caminho do log de reinicialização, além de instruções explícitas de reinicialização, reinstalação e +rollback do pacote. Com `--no-restart`, a substituição do pacote ainda é executada, mas o serviço gerenciado não é parado nem -reiniciado, então o Gateway em execução pode manter código antigo até que você o reinicie +reiniciado, então o Gateway em execução pode manter o código antigo até que você o reinicie manualmente. ## Fluxo de checkout git ### Seleção de canal -- `stable`: faz checkout da tag não beta mais recente, depois compila e executa o doctor. -- `beta`: prefere a tag `-beta` mais recente, mas recua para a tag stable mais recente quando beta está ausente ou é mais antiga. -- `dev`: faz checkout de `main`, depois busca e faz rebase. +- `stable`: faz checkout da tag não beta mais recente, depois faz build e executa doctor. +- `beta`: prefere a tag `-beta` mais recente, mas recorre à tag stable mais recente quando beta está ausente ou é mais antiga. +- `dev`: faz checkout de `main`, depois faz fetch e rebase. ### Etapas de atualização - Exige ausência de alterações não commitadas. + Exige nenhuma alteração não commitada. - - Troca para o canal selecionado (tag ou branch). + + Alterna para o canal selecionado (tag ou branch). Somente dev. - Executa lint e build TypeScript em uma worktree temporária. Se a ponta falhar, volta até 10 commits para encontrar a build limpa mais nova. + Executa lint e build TypeScript em uma worktree temporária. Se a ponta falhar, retrocede até 10 commits para encontrar a build limpa mais recente. - Faz rebase para o commit selecionado (somente dev). + Faz rebase no commit selecionado (somente dev). - Usa o gerenciador de pacotes do repo. Para checkouts pnpm, o atualizador inicializa `pnpm` sob demanda (via `corepack` primeiro, depois um fallback temporário `npm install pnpm@10`) em vez de executar `npm run build` dentro de um workspace pnpm. + Usa o gerenciador de pacotes do repositório. Para checkouts pnpm, o atualizador inicializa `pnpm` sob demanda (via `corepack` primeiro, depois um fallback temporário `npm install pnpm@10`) em vez de executar `npm run build` dentro de um workspace pnpm. - - Compila o gateway e a Control UI. + + Faz build do gateway e da Control UI. `openclaw doctor` é executado como a verificação final de atualização segura. - Sincroniza plugins com o canal ativo. Dev usa plugins empacotados; stable e beta usam npm. Atualiza instalações de plugins rastreadas. + Sincroniza plugins com o canal ativo. Dev usa plugins incluídos; stable e beta usam npm. Atualiza instalações de Plugin rastreadas. No canal de atualização beta, instalações rastreadas de plugins npm e ClawHub que seguem -a linha padrão/latest tentam primeiro uma versão `@beta` do plugin. Se o plugin não tiver -versão beta, o OpenClaw recua para a spec padrão/latest registrada. Versões -exatas e tags explícitas não são reescritas. +a linha padrão/latest tentam primeiro uma versão `@beta` do Plugin. Se o Plugin não tiver +versão beta, o OpenClaw recorre à spec padrão/latest registrada. Para +plugins npm, o OpenClaw também recorre quando o pacote beta existe, mas falha na +validação de instalação. Versões exatas e tags explícitas não são reescritas. -Se uma atualização de plugin npm fixada exata resolver para um artefato cuja integridade difere do registro de instalação armazenado, `openclaw update` aborta essa atualização de artefato de plugin em vez de instalá-la. Reinstale ou atualize o plugin explicitamente somente depois de verificar que você confia no novo artefato. +Se uma atualização de Plugin npm fixada exatamente resolver para um artefato cuja integridade difere do registro de instalação armazenado, `openclaw update` aborta essa atualização de artefato de Plugin em vez de instalá-lo. Reinstale ou atualize o Plugin explicitamente somente após verificar que você confia no novo artefato. -Falhas de sincronização de plugins pós-atualização fazem o resultado da atualização falhar e interrompem o trabalho subsequente de reinicialização. Corrija a instalação do plugin ou o erro de atualização, depois execute novamente `openclaw update`. +Falhas de sincronização de plugins pós-atualização fazem o resultado da atualização falhar e interrompem o trabalho de reinicialização subsequente. Corrija o erro de instalação ou atualização do Plugin e execute novamente `openclaw update`. -Quando o Gateway atualizado inicia, o carregamento de plugins é somente verificação: a inicialização não executa gerenciadores de pacotes nem altera árvores de dependências. Reinicializações `update.run` por gerenciador de pacotes ignoram o adiamento ocioso normal e o cooldown de reinicialização depois que a árvore do pacote foi trocada, para que o processo antigo não possa continuar carregando de forma preguiçosa partes removidas. +Quando o Gateway atualizado inicia, o carregamento de plugins é apenas de verificação: a inicialização não executa gerenciadores de pacotes nem altera árvores de dependências. Reinicializações `update.run` por gerenciador de pacotes ignoram o adiamento ocioso normal e o cooldown de reinicialização depois que a árvore de pacotes foi trocada, para que o processo antigo não possa continuar carregando lentamente chunks removidos. Se o bootstrap do pnpm ainda falhar, o atualizador para cedo com um erro específico do gerenciador de pacotes em vez de tentar `npm run build` dentro do checkout. -## Atalho `--update` +## Abreviação `--update` `openclaw --update` é reescrito para `openclaw update` (útil para shells e scripts de inicialização). -## Relacionado +## Relacionados -- `openclaw doctor` (oferece executar a atualização primeiro em checkouts git) +- `openclaw doctor` (oferece executar update primeiro em checkouts git) - [Canais de desenvolvimento](/pt-BR/install/development-channels) - [Atualização](/pt-BR/install/updating) - [Referência da CLI](/pt-BR/cli) diff --git a/docs/pt-BR/concepts/models.md b/docs/pt-BR/concepts/models.md index 9a2c14aea..5d12e292d 100644 --- a/docs/pt-BR/concepts/models.md +++ b/docs/pt-BR/concepts/models.md @@ -1,26 +1,26 @@ --- read_when: - - Adicionar ou modificar a CLI de modelos (models list/set/scan/aliases/fallbacks) - - Alteração do comportamento de fallback do modelo ou da UX de seleção + - Adicionando ou modificando a CLI de modelos (models list/set/scan/aliases/fallbacks) + - Alterando o comportamento alternativo do modelo ou a experiência do usuário na seleção - Atualizando sondas de varredura de modelos (ferramentas/imagens) sidebarTitle: Models CLI summary: 'CLI de modelos: listar, definir, aliases, fallbacks, verificar, status' -title: CLI de modelos +title: CLI de Modelos x-i18n: - generated_at: "2026-05-02T20:45:29Z" + generated_at: "2026-05-05T01:45:19Z" model: gpt-5.5 provider: openai - source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f + source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f source_path: concepts/models.md workflow: 16 --- - + Rotação de perfis de autenticação, cooldowns e como isso interage com fallbacks. - - Visão geral rápida de provedores e exemplos. + + Visão geral rápida dos provedores e exemplos. PI, Codex e outros runtimes de loop de agente. @@ -30,14 +30,14 @@ x-i18n: -Refs de modelo escolhem um provedor e um modelo. Normalmente, elas não escolhem o runtime de agente de baixo nível. Por exemplo, `openai/gpt-5.5` pode ser executado pelo caminho normal do provedor OpenAI ou pelo runtime do servidor de app do Codex, dependendo de `agents.defaults.agentRuntime.id`. No modo de runtime do Codex, a ref `openai/gpt-*` não implica cobrança por chave de API; a autenticação pode vir de uma conta Codex ou do perfil de autenticação `openai-codex`. Consulte [Runtimes de agentes](/pt-BR/concepts/agent-runtimes). +Refs de modelo escolhem um provedor e um modelo. Normalmente, eles não escolhem o runtime de agente de baixo nível. Por exemplo, `openai/gpt-5.5` pode executar pelo caminho normal do provedor OpenAI ou pelo runtime do app-server do Codex, dependendo de `agents.defaults.agentRuntime.id`. No modo de runtime Codex, a ref `openai/gpt-*` não implica cobrança por chave de API; a autenticação pode vir de uma conta Codex ou do perfil de autenticação `openai-codex`. Veja [Runtimes de agentes](/pt-BR/concepts/agent-runtimes). ## Como a seleção de modelo funciona -OpenClaw seleciona modelos nesta ordem: +O OpenClaw seleciona modelos nesta ordem: - + `agents.defaults.model.primary` (ou `agents.defaults.model`). @@ -50,33 +50,33 @@ OpenClaw seleciona modelos nesta ordem: - - `agents.defaults.models` é a allowlist/catálogo de modelos que o OpenClaw pode usar (além de aliases). - - `agents.defaults.imageModel` é usado **somente quando** o modelo principal não consegue aceitar imagens. - - `agents.defaults.pdfModel` é usado pela ferramenta `pdf`. Se omitido, a ferramenta faz fallback para `agents.defaults.imageModel` e depois para o modelo resolvido da sessão/padrão. - - `agents.defaults.imageGenerationModel` é usado pela capacidade compartilhada de geração de imagens. Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de imagens registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. - - `agents.defaults.musicGenerationModel` é usado pela capacidade compartilhada de geração de música. Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de música registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. - - `agents.defaults.videoGenerationModel` é usado pela capacidade compartilhada de geração de vídeo. Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de vídeo registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. - - Padrões por agente podem substituir `agents.defaults.model` via `agents.list[].model` mais associações (consulte [Roteamento multiagente](/pt-BR/concepts/multi-agent)). + - `agents.defaults.models` é a allowlist/catálogo de modelos que o OpenClaw pode usar (mais aliases). + - `agents.defaults.imageModel` é usado **somente quando** o modelo primário não aceita imagens. + - `agents.defaults.pdfModel` é usado pela ferramenta `pdf`. Se omitido, a ferramenta recorre a `agents.defaults.imageModel` e depois ao modelo resolvido da sessão/padrão. + - `agents.defaults.imageGenerationModel` é usado pela capacidade compartilhada de geração de imagens. Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagens em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. + - `agents.defaults.musicGenerationModel` é usado pela capacidade compartilhada de geração de música. Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. + - `agents.defaults.videoGenerationModel` é usado pela capacidade compartilhada de geração de vídeo. Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor. + - Padrões por agente podem substituir `agents.defaults.model` via `agents.list[].model` mais vinculações (veja [Roteamento multiagente](/pt-BR/concepts/multi-agent)). -## Origem da seleção e comportamento de fallback +## Fonte da seleção e comportamento de fallback O mesmo `provider/model` pode significar coisas diferentes dependendo de onde veio: -- Padrões configurados (`agents.defaults.model.primary` e modelos principais específicos do agente) são o ponto de partida normal e usam `agents.defaults.model.fallbacks`. -- Seleções automáticas de fallback são estado temporário de recuperação. Elas são armazenadas com `modelOverrideSource: "auto"` para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar primeiro um modelo principal sabidamente ruim. -- Seleções de sessão do usuário são exatas. `/model`, o seletor de modelos, `session_status(model=...)` e `sessions.patch` armazenam `modelOverrideSource: "user"`; se esse provedor/modelo selecionado estiver inacessível, o OpenClaw falha de forma visível em vez de passar para outro modelo configurado. -- `--model` de Cron / `model` do payload é um modelo principal por job. Ele ainda usa fallbacks configurados, a menos que o job forneça `fallbacks` explícitos no payload (use `fallbacks: []` para uma execução de cron estrita). -- Seletores de modelo padrão e de allowlist da CLI respeitam `models.mode: "replace"` listando `models.providers.*.models` explícitos em vez de carregar todo o catálogo integrado completo. -- O seletor de modelos da UI de Controle pede ao Gateway sua visão de modelos configurada: `agents.defaults.models` quando presente; caso contrário, `models.providers.*.models` explícitos mais provedores com autenticação utilizável. O catálogo integrado completo fica reservado para visualizações explícitas de navegação, como `models.list` com `view: "all"` ou `openclaw models list --all`. +- Padrões configurados (`agents.defaults.model.primary` e primários específicos de agente) são o ponto de partida normal e usam `agents.defaults.model.fallbacks`. +- Seleções de fallback automáticas são estado temporário de recuperação. Elas são armazenadas com `modelOverrideSource: "auto"` para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar primeiro um primário sabidamente ruim. +- Seleções de sessão do usuário são exatas. `/model`, o seletor de modelos, `session_status(model=...)` e `sessions.patch` armazenam `modelOverrideSource: "user"`; se esse provedor/modelo selecionado estiver inacessível, o OpenClaw falha de forma visível em vez de cair para outro modelo configurado. +- Cron `--model` / payload `model` é um primário por job. Ele ainda usa fallbacks configurados, a menos que o job forneça `fallbacks` explícitos no payload (use `fallbacks: []` para uma execução de cron estrita). +- Os seletores de modelo padrão e allowlist da CLI respeitam `models.mode: "replace"` listando `models.providers.*.models` explícitos em vez de carregar todo o catálogo integrado. +- O seletor de modelos da Control UI pede ao Gateway a visão configurada de modelos: `agents.defaults.models` quando presente; caso contrário, `models.providers.*.models` explícitos mais provedores com autenticação utilizável. O catálogo integrado completo é reservado para visões de navegação explícitas, como `models.list` com `view: "all"` ou `openclaw models list --all`. ## Política rápida de modelos -- Defina seu principal como o modelo de geração mais recente e mais forte disponível para você. -- Use fallbacks para tarefas sensíveis a custo/latência e chat de menor risco. -- Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelos mais antigas/mais fracas. +- Defina seu primário como o modelo de geração mais recente mais forte disponível para você. +- Use fallbacks para tarefas sensíveis a custo/latência e chats de menor risco. +- Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelo mais antigas/fracas. ## Onboarding (recomendado) @@ -99,7 +99,7 @@ Ele pode configurar modelo + autenticação para provedores comuns, incluindo ** - `models.providers` (provedores personalizados gravados em `models.json`) -Refs de modelo são normalizadas para minúsculas. Aliases de provedor como `z.ai/*` são normalizados para `zai/*`. +Refs de modelo são normalizadas para minúsculas. Aliases de provedor como `z.ai/*` normalizam para `zai/*`. Exemplos de configuração de provedor (incluindo OpenCode) ficam em [OpenCode](/pt-BR/providers/opencode). @@ -114,9 +114,9 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json - `openclaw config set` protege mapas de modelo/provedor contra sobrescritas acidentais. Uma atribuição de objeto simples a `agents.defaults.models`, `models.providers` ou `models.providers..models` é rejeitada quando removeria entradas existentes. Use `--merge` para alterações aditivas; use `--replace` somente quando o valor fornecido deve se tornar o valor alvo completo. + `openclaw config set` protege mapas de modelo/provedor contra sobrescritas acidentais. Uma atribuição simples de objeto para `agents.defaults.models`, `models.providers` ou `models.providers..models` é rejeitada quando removeria entradas existentes. Use `--merge` para alterações aditivas; use `--replace` somente quando o valor fornecido deve se tornar o valor completo do alvo. - A configuração interativa de provedor e `openclaw configure --section model` também mesclam seleções com escopo de provedor na allowlist existente, então adicionar Codex, Ollama ou outro provedor não remove entradas de modelo não relacionadas. Configure preserva um `agents.defaults.model.primary` existente quando a autenticação do provedor é reaplicada. Comandos explícitos de definição de padrão, como `openclaw models auth login --provider --set-default` e `openclaw models set `, ainda substituem `agents.defaults.model.primary`. + A configuração interativa de provedor e `openclaw configure --section model` também mesclam seleções no escopo do provedor à allowlist existente, então adicionar Codex, Ollama ou outro provedor não remove entradas de modelo não relacionadas. A configuração preserva um `agents.defaults.model.primary` existente quando a autenticação do provedor é reaplicada. Comandos explícitos de definição de padrão, como `openclaw models auth login --provider --set-default` e `openclaw models set `, ainda substituem `agents.defaults.model.primary`. @@ -126,11 +126,12 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json Se `agents.defaults.models` estiver definido, ele se torna a **allowlist** para `/model` e para substituições de sessão. Quando um usuário seleciona um modelo que não está nessa allowlist, o OpenClaw retorna: ``` -Model "provider/model" is not allowed. Use /model to list available models. +Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -Isso acontece **antes** que uma resposta normal seja gerada, então a mensagem pode parecer que "não respondeu". A correção é: +Isso acontece **antes** de uma resposta normal ser gerada, então a mensagem pode parecer que "não respondeu". A correção é: - Adicionar o modelo a `agents.defaults.models`, ou - Limpar a allowlist (remover `agents.defaults.models`), ou @@ -138,9 +139,11 @@ Isso acontece **antes** que uma resposta normal seja gerada, então a mensagem p -Para modelos locais/GGUF, armazene a ref completa com prefixo do provedor na allowlist, +Quando o comando rejeitado incluía uma substituição de runtime, como `/model openai/gpt-5.5 --runtime codex`, corrija primeiro a allowlist e depois tente novamente o mesmo comando `/model ... --runtime ...`. Para execução nativa do Codex, o modelo selecionado ainda é `openai/gpt-5.5`; o runtime `codex` seleciona o harness e usa a autenticação do Codex separadamente. + +Para modelos locais/GGUF, armazene a ref completa com prefixo de provedor na allowlist, por exemplo `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf` ou o -`provider/model` exato mostrado por `openclaw models list --provider `. +provedor/modelo exato mostrado por `openclaw models list --provider `. Nomes de arquivos locais simples ou nomes de exibição não são suficientes quando a allowlist está ativa. @@ -173,32 +176,32 @@ Você pode alternar modelos para a sessão atual sem reiniciar: - `/model` (e `/model list`) é um seletor compacto e numerado (família de modelo + provedores disponíveis). - - No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa Submit. - - No Telegram, as seleções do seletor `/models` têm escopo de sessão; elas não alteram o padrão persistente do agente em `openclaw.json`. - - `/models add` está obsoleto e agora retorna uma mensagem de obsolescência em vez de registrar modelos pelo chat. + - No Discord, `/model` e `/models` abrem um seletor interativo com dropdowns de provedor e modelo, além de uma etapa de envio. + - No Telegram, as seleções do seletor `/models` são no escopo da sessão; elas não alteram o padrão persistente do agente em `openclaw.json`. + - `/models add` está obsoleto e agora retorna uma mensagem de descontinuação em vez de registrar modelos pelo chat. - `/model <#>` seleciona a partir desse seletor. - - `/model` persiste imediatamente a nova seleção de sessão. + - `/model` persiste a nova seleção de sessão imediatamente. - Se o agente estiver ocioso, a próxima execução usa o novo modelo imediatamente. - - Se uma execução já estiver ativa, o OpenClaw marca uma alternância ao vivo como pendente e só reinicia no novo modelo em um ponto limpo de nova tentativa. - - Se a atividade de ferramenta ou a saída da resposta já tiver começado, a alternância pendente pode ficar na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário. - - Uma ref `/model` selecionada pelo usuário é estrita para essa sessão: se o provedor/modelo selecionado estiver inacessível, a resposta falha de forma visível em vez de responder silenciosamente a partir de `agents.defaults.model.fallbacks`. Isso é diferente de padrões configurados e modelos principais de jobs cron, que ainda podem usar cadeias de fallback. - - `/model status` é a visualização detalhada (candidatos de autenticação e, quando configurado, `baseUrl` do endpoint do provedor + modo `api`). + - Se uma execução já estiver ativa, o OpenClaw marca uma alternância ao vivo como pendente e só reinicia no novo modelo em um ponto de nova tentativa limpo. + - Se a atividade de ferramentas ou a saída da resposta já tiver começado, a alternância pendente pode ficar enfileirada até uma oportunidade de nova tentativa posterior ou o próximo turno do usuário. + - Uma ref `/model` selecionada pelo usuário é estrita para essa sessão: se o provedor/modelo selecionado estiver inacessível, a resposta falha de forma visível em vez de responder silenciosamente a partir de `agents.defaults.model.fallbacks`. Isso é diferente dos padrões configurados e dos primários de jobs cron, que ainda podem usar cadeias de fallback. + - `/model status` é a visão detalhada (candidatos de autenticação e, quando configurado, endpoint do provedor `baseUrl` + modo `api`). - + - Refs de modelo são analisadas dividindo na **primeira** `/`. Use `provider/model` ao digitar `/model `. - Se o próprio ID do modelo contiver `/` (estilo OpenRouter), você deve incluir o prefixo do provedor (exemplo: `/model openrouter/moonshotai/kimi-k2`). - Se você omitir o provedor, o OpenClaw resolve a entrada nesta ordem: 1. correspondência de alias 2. correspondência única de provedor configurado para esse ID de modelo exato sem prefixo - 3. fallback obsoleto para o provedor padrão configurado — se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw, em vez disso, faz fallback para o primeiro provedor/modelo configurado para evitar exibir um padrão obsoleto de provedor removido. + 3. fallback obsoleto para o provedor padrão configurado — se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado para evitar expor um padrão obsoleto de provedor removido. -Comportamento/configuração completa dos comandos: [Comandos de barra](/pt-BR/tools/slash-commands). +Comportamento/configuração completa do comando: [Comandos de barra](/pt-BR/tools/slash-commands). ## Comandos da CLI @@ -227,10 +230,10 @@ openclaw models image-fallbacks clear ### `models list` -Mostra modelos configurados/disponíveis por autenticação por padrão. Flags úteis: +Mostra modelos configurados/com autenticação disponível por padrão. Flags úteis: - Catálogo completo. Inclui linhas de catálogo estático agrupadas e pertencentes ao provedor antes da configuração da autenticação, para que visualizações apenas de descoberta possam mostrar modelos que ficam indisponíveis até você adicionar credenciais correspondentes do provedor. + Catálogo completo. Inclui linhas de catálogo estático pertencentes a provedores incluídos antes de a autenticação ser configurada, para que visualizações apenas de descoberta possam mostrar modelos indisponíveis até você adicionar credenciais de provedor correspondentes. Apenas provedores locais. @@ -247,21 +250,21 @@ Mostra modelos configurados/disponíveis por autenticação por padrão. Flags ### `models status` -Mostra o modelo primário resolvido, fallbacks, modelo de imagem e uma visão geral de autenticação dos provedores configurados. Também exibe o status de expiração OAuth para perfis encontrados no armazenamento de autenticação (avisa com 24h de antecedência por padrão). `--plain` imprime apenas o modelo primário resolvido. +Mostra o modelo primário resolvido, fallbacks, modelo de imagem e uma visão geral de autenticação dos provedores configurados. Também exibe o status de expiração OAuth para perfis encontrados no armazenamento de autenticação (avisa dentro de 24h por padrão). `--plain` imprime apenas o modelo primário resolvido. - - O status OAuth é sempre mostrado (e incluído na saída `--json`). Se um provedor configurado não tiver credenciais, `models status` imprime uma seção **Autenticação ausente**. - - JSON inclui `auth.oauth` (janela de aviso + perfis) e `auth.providers` (autenticação efetiva por provedor, incluindo credenciais baseadas em env). `auth.oauth` é apenas a integridade de perfis do armazenamento de autenticação; provedores somente por env não aparecem ali. - - Use `--check` para automação (sai com `1` quando ausente/expirado, `2` quando expirando). - - Use `--probe` para verificações de autenticação ao vivo; linhas de sondagem podem vir de perfis de autenticação, credenciais de env ou `models.json`. + - O status OAuth é sempre mostrado (e incluído na saída de `--json`). Se um provedor configurado não tiver credenciais, `models status` imprime uma seção **Autenticação ausente**. + - JSON inclui `auth.oauth` (janela de aviso + perfis) e `auth.providers` (autenticação efetiva por provedor, incluindo credenciais vindas do ambiente). `auth.oauth` é apenas a integridade de perfis do armazenamento de autenticação; provedores somente de ambiente não aparecem ali. + - Use `--check` para automação (saída `1` quando ausente/expirado, `2` quando estiver prestes a expirar). + - Use `--probe` para verificações de autenticação ao vivo; linhas de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`. - Se `auth.order.` explícito omitir um perfil armazenado, a sondagem relata `excluded_by_auth_order` em vez de tentar usá-lo. Se houver autenticação, mas nenhum modelo sondável puder ser resolvido para esse provedor, a sondagem relata `status: no_model`. -A escolha de autenticação depende do provedor/conta. Para hosts de gateway sempre ativos, chaves de API geralmente são as mais previsíveis; a reutilização do Claude CLI e perfis OAuth/token existentes da Anthropic também são compatíveis. +A escolha de autenticação depende do provedor/conta. Para hosts de Gateway sempre ativos, chaves de API costumam ser as mais previsíveis; reutilização da Claude CLI e perfis OAuth/token existentes da Anthropic também são compatíveis. Exemplo (Claude CLI): @@ -273,7 +276,7 @@ openclaw models status ## Varredura (modelos gratuitos do OpenRouter) -`openclaw models scan` inspeciona o **catálogo de modelos gratuitos** do OpenRouter e pode, opcionalmente, sondar modelos para suporte a ferramentas e imagens. +`openclaw models scan` inspeciona o **catálogo de modelos gratuitos** do OpenRouter e pode opcionalmente sondar modelos quanto a suporte a ferramentas e imagens. Pule sondagens ao vivo (somente metadados). @@ -285,66 +288,66 @@ openclaw models status Pule modelos mais antigos. - Filtro por prefixo do provedor. + Filtro por prefixo de provedor. Tamanho da lista de fallback. - Defina `agents.defaults.model.primary` como a primeira seleção. + Defina `agents.defaults.model.primary` para a primeira seleção. - Defina `agents.defaults.imageModel.primary` como a primeira seleção de imagem. + Defina `agents.defaults.imageModel.primary` para a primeira seleção de imagem. -O catálogo `/models` do OpenRouter é público, então varreduras somente de metadados podem listar candidatos gratuitos sem uma chave. Sondagem e inferência ainda exigem uma chave de API do OpenRouter (de perfis de autenticação ou `OPENROUTER_API_KEY`). Se nenhuma chave estiver disponível, `openclaw models scan` recorre à saída somente de metadados e deixa a configuração inalterada. Use `--no-probe` para solicitar explicitamente o modo somente de metadados. +O catálogo `/models` do OpenRouter é público, então varreduras somente de metadados podem listar candidatos gratuitos sem uma chave. Sondagem e inferência ainda exigem uma chave de API do OpenRouter (de perfis de autenticação ou `OPENROUTER_API_KEY`). Se nenhuma chave estiver disponível, `openclaw models scan` recorre à saída somente de metadados e deixa a configuração inalterada. Use `--no-probe` para solicitar explicitamente o modo somente metadados. Os resultados da varredura são classificados por: -1. Suporte a imagens -2. Latência de ferramentas -3. Tamanho de contexto +1. Suporte a imagem +2. Latência de ferramenta +3. Tamanho do contexto 4. Contagem de parâmetros Entrada: - Lista `/models` do OpenRouter (filtro `:free`) -- Sondagens ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou `OPENROUTER_API_KEY` (consulte [Variáveis de ambiente](/pt-BR/help/environment)) +- Sondagens ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou `OPENROUTER_API_KEY` (veja [Variáveis de ambiente](/pt-BR/help/environment)) - Filtros opcionais: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Controles de solicitação/sondagem: `--timeout`, `--concurrency` -Quando sondagens ao vivo são executadas em um TTY, você pode selecionar fallbacks interativamente. No modo não interativo, passe `--yes` para aceitar os padrões. Resultados somente de metadados são informativos; `--set-default` e `--set-image` exigem sondagens ao vivo para que o OpenClaw não configure um modelo OpenRouter sem chave e inutilizável. +Quando sondagens ao vivo são executadas em uma TUI, você pode selecionar fallbacks interativamente. No modo não interativo, passe `--yes` para aceitar os padrões. Resultados somente de metadados são informativos; `--set-default` e `--set-image` exigem sondagens ao vivo para que o OpenClaw não configure um modelo OpenRouter sem chave e inutilizável. ## Registro de modelos (`models.json`) -Provedores personalizados em `models.providers` são gravados em `models.json` no diretório do agente (padrão `~/.openclaw/agents//agent/models.json`). Esse arquivo é mesclado por padrão, a menos que `models.mode` esteja definido como `replace`. +Provedores personalizados em `models.providers` são gravados em `models.json` no diretório do agente (padrão `~/.openclaw/agents//agent/models.json`). Esse arquivo é mesclado por padrão, a menos que `models.mode` seja definido como `replace`. - Precedência do modo de mesclagem para IDs de provedores correspondentes: + Precedência do modo de mesclagem para IDs de provedor correspondentes: - `baseUrl` não vazio já presente no `models.json` do agente vence. - `apiKey` não vazio no `models.json` do agente vence apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. - - Valores `apiKey` de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para referências de env, `secretref-managed` para referências de arquivo/exec) em vez de persistir segredos resolvidos. - - Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para referências de env, `secretref-managed` para referências de arquivo/exec). - - `apiKey`/`baseUrl` vazios ou ausentes do agente recorrem a `models.providers` da configuração. - - Outros campos do provedor são atualizados a partir da configuração e de dados de catálogo normalizados. + - Valores de `apiKey` de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para referências de ambiente, `secretref-managed` para referências de arquivo/exec), em vez de persistir segredos resolvidos. + - Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para referências de ambiente, `secretref-managed` para referências de arquivo/exec). + - `apiKey`/`baseUrl` vazios ou ausentes no agente recorrem a `models.providers` da configuração. + - Outros campos de provedor são atualizados a partir da configuração e dos dados normalizados do catálogo. -A persistência de marcadores tem a origem como autoridade: o OpenClaw grava marcadores do snapshot da configuração de origem ativa (antes da resolução), não dos valores de segredo resolvidos em runtime. Isso se aplica sempre que o OpenClaw regenera `models.json`, incluindo caminhos acionados por comandos como `openclaw agent`. +A persistência de marcadores é autoritativa pela origem: o OpenClaw grava marcadores do snapshot de configuração de origem ativo (antes da resolução), não dos valores de segredo resolvidos em runtime. Isso se aplica sempre que o OpenClaw regenera `models.json`, incluindo caminhos acionados por comandos como `openclaw agent`. -## Relacionado +## Relacionados -- [Runtimes de agentes](/pt-BR/concepts/agent-runtimes) — PI, Codex e outros runtimes de loop de agentes -- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — chaves de configuração de modelos -- [Geração de imagens](/pt-BR/tools/image-generation) — configuração de modelo de imagem +- [Runtimes de agente](/pt-BR/concepts/agent-runtimes) — PI, Codex e outros runtimes de loop de agente +- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — chaves de configuração de modelo +- [Geração de imagem](/pt-BR/tools/image-generation) — configuração de modelo de imagem - [Failover de modelo](/pt-BR/concepts/model-failover) — cadeias de fallback -- [Provedores de modelos](/pt-BR/concepts/model-providers) — roteamento e autenticação de provedores +- [Provedores de modelo](/pt-BR/concepts/model-providers) — roteamento e autenticação de provedores - [Geração de música](/pt-BR/tools/music-generation) — configuração de modelo de música - [Geração de vídeo](/pt-BR/tools/video-generation) — configuração de modelo de vídeo diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md index 9587c7d43..3eef2b9a3 100644 --- a/docs/pt-BR/concepts/qa-e2e-automation.md +++ b/docs/pt-BR/concepts/qa-e2e-automation.md @@ -1,68 +1,68 @@ --- read_when: - - Entendendo como a pilha de QA se encaixa - - Estendendo o qa-lab, o qa-channel ou um adaptador de transporte - - Adicionar cenários de QA baseados no repositório - - Criando automação de QA de maior realismo em torno do dashboard do Gateway -summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e geração de relatórios.' + - Entendendo como a pilha de QA funciona em conjunto + - Estendendo qa-lab, qa-channel ou um adaptador de transporte + - Adicionando cenários de QA apoiados por repositório + - Criando automação de QA de maior realismo em torno do painel do Gateway +summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e relatórios.' title: Visão geral de QA x-i18n: - generated_at: "2026-05-04T05:52:10Z" + generated_at: "2026-05-05T01:45:29Z" model: gpt-5.5 provider: openai - source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 + source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -A stack privada de QA foi pensada para exercitar o OpenClaw de uma forma mais realista, -moldada por canais, do que um único teste unitário consegue. +A pilha privada de QA serve para exercitar o OpenClaw de uma forma mais realista, +com formato de canal, do que um único teste unitário conseguiria. -Componentes atuais: +Peças atuais: -- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, - canal, thread, reação, edição e exclusão. +- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, + reação, edição e exclusão. - `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, - injetar mensagens de entrada e exportar um relatório em Markdown. + injetar mensagens recebidas e exportar um relatório em Markdown. - `extensions/qa-matrix`, plugins executores futuros: adaptadores de transporte ao vivo que - controlam um canal real dentro de um Gateway de QA filho. -- `qa/`: ativos de semente respaldados pelo repositório para a tarefa inicial e cenários - de QA de linha de base. + conduzem um canal real dentro de um Gateway de QA filho. +- `qa/`: ativos iniciais versionados no repositório para a tarefa de kickoff e cenários + de QA de base. - [Mantis](/pt-BR/concepts/mantis): verificação ao vivo antes e depois para bugs que - precisam de transportes reais, capturas de tela do navegador, estado da VM e evidências de PR. + precisam de transportes reais, capturas de tela do navegador, estado de VM e evidências de PR. ## Superfície de comandos -Todo fluxo de QA é executado em `pnpm openclaw qa `. Muitos têm aliases de script `pnpm qa:*`; +Todo fluxo de QA roda em `pnpm openclaw qa `. Muitos têm aliases de script `pnpm qa:*`; ambas as formas são compatíveis. | Comando | Finalidade | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `qa run` | Autoverificação de QA incluída; grava um relatório em Markdown. | -| `qa suite` | Executa cenários respaldados pelo repositório contra a faixa do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. | -| `qa coverage` | Imprime o inventário markdown de cobertura de cenários (`--json` para saída de máquina). | -| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agêntica. | -| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Consulte [Relatórios](#reporting). | -| `qa manual` | Executa um prompt avulso contra a faixa de provedor/modelo selecionada. | -| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Compila a imagem Docker pré-preparada de QA. | -| `qa docker-scaffold` | Grava um scaffold docker-compose para o painel de QA + faixa do Gateway. | -| `qa up` | Compila o site de QA, inicia a stack apoiada por Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | -| `qa aimock` | Inicia apenas o servidor do provedor AIMock. | -| `qa mock-openai` | Inicia apenas o servidor do provedor `mock-openai` ciente de cenários. | -| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais do Convex. | -| `qa matrix` | Faixa de transporte ao vivo contra um homeserver Tuwunel descartável. Consulte [QA do Matrix](/pt-BR/concepts/qa-matrix). | -| `qa telegram` | Faixa de transporte ao vivo contra um grupo privado real do Telegram. | -| `qa discord` | Faixa de transporte ao vivo contra um canal real de guild privada do Discord. | -| `qa slack` | Faixa de transporte ao vivo contra um canal privado real do Slack. | -| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com evidências de reações de status no Discord, smoke de desktop/navegador Crabbox e smoke de Slack em VNC. Consulte [Mantis](/pt-BR/concepts/mantis). | +| `qa suite` | Executa cenários versionados no repositório contra a trilha do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. | +| `qa coverage` | Imprime o inventário de cobertura de cenários em markdown (`--json` para saída de máquina). | +| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agêntico. | +| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Consulte [Relatórios](#reporting). | +| `qa manual` | Executa um prompt avulso contra a trilha de provedor/modelo selecionada. | +| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Cria a imagem Docker de QA pré-preparada. | +| `qa docker-scaffold` | Grava um scaffold docker-compose para o painel de QA + trilha de Gateway. | +| `qa up` | Cria o site de QA, inicia a pilha apoiada por Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Inicia somente o servidor do provedor AIMock. | +| `qa mock-openai` | Inicia somente o servidor do provedor `mock-openai` ciente de cenários. | +| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais Convex. | +| `qa matrix` | Trilha de transporte ao vivo contra um homeserver Tuwunel descartável. Consulte [QA do Matrix](/pt-BR/concepts/qa-matrix). | +| `qa telegram` | Trilha de transporte ao vivo contra um grupo privado real do Telegram. | +| `qa discord` | Trilha de transporte ao vivo contra um canal de guilda privado real do Discord. | +| `qa slack` | Trilha de transporte ao vivo contra um canal privado real do Slack. | +| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com evidência de reações de status no Discord, smoke de desktop/navegador no Crabbox e smoke de Slack em VNC. Consulte [Mantis](/pt-BR/concepts/mantis). | ## Fluxo do operador O fluxo atual do operador de QA é um site de QA com dois painéis: - Esquerda: painel do Gateway (UI de Controle) com o agente. -- Direita: QA Lab, mostrando a transcrição estilo Slack e o plano do cenário. +- Direita: QA Lab, mostrando a transcrição no estilo Slack e o plano do cenário. Execute com: @@ -70,13 +70,13 @@ Execute com: pnpm qa:lab:up ``` -Isso compila o site de QA, inicia a faixa do Gateway apoiada por Docker e expõe a -página do QA Lab onde um operador ou loop de automação pode dar ao agente uma missão -de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou +Isso cria o site de QA, inicia a trilha de Gateway apoiada por Docker e expõe a +página do QA Lab onde um operador ou loop de automação pode dar ao agente uma +missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou permaneceu bloqueado. -Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker a cada vez, -inicie a stack com um pacote do QA Lab montado por bind: +Para uma iteração mais rápida da UI do QA Lab sem recriar a imagem Docker a cada vez, +inicie a pilha com um pacote do QA Lab montado por bind mount: ```bash pnpm openclaw qa docker-build-image @@ -85,40 +85,40 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e monta por bind +`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-criada e monta por bind mount `extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` -recompila esse pacote em mudanças, e o navegador recarrega automaticamente quando o hash -do ativo do QA Lab muda. +recria esse pacote a cada alteração, e o navegador recarrega automaticamente quando o hash de ativos do QA Lab +muda. -Para um smoke local de trace do OpenTelemetry, execute: +Para um smoke de trace local do OpenTelemetry, execute: ```bash pnpm qa:otel:smoke ``` Esse script inicia um receptor local de trace OTLP/HTTP, executa o cenário de QA -`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois decodifica os spans -protobuf exportados e verifica o formato crítico para release: +`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois +decodifica os spans protobuf exportados e valida o formato crítico de release: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` e `openclaw.message.delivery` devem estar presentes; chamadas de modelo não devem exportar `StreamAbandoned` em turnos bem-sucedidos; IDs diagnósticos brutos e -atributos `openclaw.content.*` devem permanecer fora do trace. Ele grava +atributos `openclaw.content.*` devem ficar fora do trace. Ele grava `otel-smoke-summary.json` ao lado dos artefatos da suíte de QA. -QA de observabilidade permanece restrito ao checkout do código-fonte. O tarball npm omite intencionalmente -o QA Lab, então as faixas de release Docker do pacote não executam comandos `qa`. Use -`pnpm qa:otel:smoke` a partir de um checkout de código-fonte compilado ao alterar a instrumentação +A QA de observabilidade permanece somente para checkout de código-fonte. O tarball npm omite intencionalmente +o QA Lab, então trilhas de release Docker de pacote não executam comandos `qa`. Use +`pnpm qa:otel:smoke` a partir de um checkout de código-fonte criado ao alterar a instrumentação de diagnósticos. -Para uma faixa de smoke do Matrix com transporte real, execute: +Para uma trilha de smoke do Matrix com transporte real, execute: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -A referência completa da CLI, catálogo de perfis/cenários, vars de env e layout de artefatos desta faixa ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável em Docker, registra usuários temporários de driver/SUT/observer, executa o plugin real do Matrix dentro de um Gateway de QA filho escopado para esse transporte (sem `qa-channel`), depois grava um relatório em Markdown, resumo JSON, artefato de eventos observados e log de saída combinado em `.artifacts/qa-e2e/matrix-/`. +A referência completa da CLI, o catálogo de perfis/cenários, variáveis de ambiente e layout de artefatos dessa trilha ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver/SUT/observador, executa o plugin Matrix real dentro de um Gateway de QA filho com escopo para esse transporte (sem `qa-channel`) e então grava um relatório em Markdown, um resumo JSON, um artefato de eventos observados e um log de saída combinado em `.artifacts/qa-e2e/matrix-/`. -Para faixas de smoke com transporte real de Telegram, Discord e Slack: +Para trilhas de smoke com transporte real do Telegram, Discord e Slack: ```bash pnpm openclaw qa telegram @@ -126,7 +126,7 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -Elas miram um canal real pré-existente com dois bots (driver + SUT). Vars de env obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais do Convex estão documentados na [referência de QA para Telegram, Discord e Slack](#telegram-discord-and-slack-qa-reference) abaixo. +Elas miram um canal real preexistente com dois bots (driver + SUT). Variáveis de ambiente obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais Convex estão documentados na [referência de QA do Telegram, Discord e Slack](#telegram-discord-and-slack-qa-reference) abaixo. Para uma execução completa de VM desktop do Slack com resgate por VNC, execute: @@ -137,13 +137,13 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Esse comando aluga uma máquina desktop/navegador Crabbox, executa a faixa ao vivo do Slack -dentro da VM, abre o Slack Web no navegador VNC, captura o desktop e copia -`slack-qa/` mais `slack-desktop-smoke.png` de volta para o diretório de artefatos do Mantis. -Reutilize `--lease-id ` depois de fazer login no Slack Web manualmente +Esse comando aluga uma máquina de desktop/navegador do Crabbox, executa a trilha ao vivo do Slack +dentro da VM, abre o Slack Web no navegador VNC, captura o desktop e +copia `slack-qa/` mais `slack-desktop-smoke.png` de volta para o diretório de artefatos +do Mantis. Reutilize `--lease-id ` depois de entrar no Slack Web manualmente pelo VNC. Com `--gateway-setup`, o Mantis deixa um Gateway Slack persistente do OpenClaw em execução dentro da VM na porta `38973`; sem isso, o comando executa a -faixa normal de QA Slack bot a bot e sai após a captura de artefatos. +trilha normal de QA do Slack bot-para-bot e sai após a captura dos artefatos. Antes de usar credenciais ao vivo em pool, execute: @@ -151,65 +151,65 @@ Antes de usar credenciais ao vivo em pool, execute: pnpm openclaw qa credentials doctor ``` -O doctor verifica o env do broker Convex, valida configurações de endpoint e verifica a acessibilidade de admin/list quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente dos segredos. +O doctor verifica o ambiente do broker Convex, valida as configurações de endpoint e verifica a alcançabilidade de admin/lista quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente dos segredos. ## Cobertura de transporte ao vivo -As faixas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a suíte ampla de comportamento de produto sintético e não faz parte da matriz de cobertura de transporte ao vivo. +As trilhas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a suíte ampla de comportamento sintético do produto e não faz parte da matriz de cobertura de transporte ao vivo. -| Faixa | Canary | Gating de menção | Bot a bot | Bloqueio por lista de permissões | Resposta de nível superior | Retomada após reinício | Continuação de thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo | -| -------- | ------ | ---------------- | --------- | -------------------------------- | -------------------------- | ---------------------- | --------------------- | -------------------- | -------------------- | ---------------- | -------------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | -| Slack | x | x | x | | | | | | | | | +| Trilha | Canary | Gate por menção | Bot-para-bot | Bloqueio por lista permitida | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo | +| -------- | ------ | --------------- | ------------ | ---------------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -------------------------- | +| Matrix | x | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | x | | | | | | | x | | +| Discord | x | x | x | | | | | | | | x | +| Slack | x | x | x | | | | | | | | | -Isso mantém `qa-channel` como a suíte ampla de comportamento de produto, enquanto Matrix, +Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, Telegram e transportes ao vivo futuros compartilham uma checklist explícita de contrato de transporte. -Para uma faixa de VM Linux descartável sem levar Docker para o caminho de QA, execute: +Para uma trilha de VM Linux descartável sem trazer Docker para o caminho de QA, execute: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Isso inicializa um guest Multipass novo, instala dependências, compila o OpenClaw -dentro do guest, executa `qa suite` e então copia o relatório de QA normal e o +Isso inicializa um convidado Multipass novo, instala dependências, compila o OpenClaw +dentro do convidado, executa `qa suite` e depois copia o relatório normal de QA e o resumo de volta para `.artifacts/qa-e2e/...` no host. Ele reutiliza o mesmo comportamento de seleção de cenários que `qa suite` no host. -As execuções das suítes no host e no Multipass executam vários cenários selecionados em paralelo +Execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo com workers de Gateway isolados por padrão. `qa-channel` usa concorrência -4 por padrão, limitada pela quantidade de cenários selecionados. Use `--concurrency ` para ajustar -a quantidade de workers, ou `--concurrency 1` para execução serial. +4 por padrão, limitada pela contagem de cenários selecionados. Use `--concurrency ` para ajustar +a contagem de workers, ou `--concurrency 1` para execução serial. O comando sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando -você quiser artefatos sem um código de saída com falha. +quiser artefatos sem um código de saída de falha. Execuções live encaminham as entradas de autenticação de QA compatíveis que são práticas para o -guest: chaves de provedores baseadas em env, o caminho da configuração do provedor live de QA e -`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest -possa escrever de volta pelo workspace montado. +convidado: chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e +`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o convidado +possa gravar de volta pelo workspace montado. -## Referência de QA do Telegram, Discord e Slack +## Referência de QA para Telegram, Discord e Slack -Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa da sua quantidade de cenários e do provisionamento de homeserver apoiado por Docker. Telegram, Discord e Slack são menores — alguns cenários cada, sem sistema de perfis, contra canais reais preexistentes — então a referência deles fica aqui. +Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa de sua contagem de cenários e do provisionamento de homeserver com suporte por Docker. Telegram, Discord e Slack são menores — alguns cenários cada, sem sistema de perfis, contra canais reais preexistentes — então sua referência fica aqui. -### Flags de CLI compartilhadas +### Flags compartilhadas da CLI -Essas lanes são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags: +Essas pistas são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags: | Flag | Padrão | Descrição | | ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Executa somente este cenário. Repetível. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Onde os relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. | +| `--scenario ` | — | Executa apenas este cenário. Repetível. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Onde relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. | | `--repo-root ` | `process.cwd()` | Raiz do repositório ao invocar a partir de um cwd neutro. | -| `--sut-account ` | `sut` | ID temporário da conta dentro da configuração do Gateway de QA. | +| `--sut-account ` | `sut` | ID de conta temporário dentro da configuração do Gateway de QA. | | `--provider-mode ` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` legado ainda funciona). | -| `--model ` / `--alt-model ` | padrão do provedor | Refs do modelo primário/alternativo. | -| `--fast` | desativado | Modo rápido do provedor quando compatível. | +| `--model ` / `--alt-model ` | padrão do provedor | Referências de modelo primário/alternativo. | +| `--fast` | desativado | Modo rápido do provedor onde compatível. | | `--credential-source ` | `env` | Consulte [pool de credenciais Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` em CI, `maintainer` caso contrário | Papel usado quando `--credential-source convex`. | +| `--credential-role ` | `ci` em CI, caso contrário `maintainer` | Função usada quando `--credential-source convex`. | -Cada lane sai com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída com falha. +Cada pista sai com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída de falha. ### QA do Telegram @@ -217,17 +217,17 @@ Cada lane sai com código diferente de zero em qualquer cenário com falha. `--a pnpm openclaw qa telegram ``` -Tem como alvo um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT deve ter um nome de usuário do Telegram; a observação bot-a-bot funciona melhor quando ambos os bots têm **Bot-to-Bot Communication Mode** habilitado no `@BotFather`. +Mira em um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT precisa ter um nome de usuário do Telegram; a observação bot-para-bot funciona melhor quando ambos os bots têm **Bot-to-Bot Communication Mode** habilitado em `@BotFather`. Env obrigatório quando `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — ID numérico do chat (string). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id numérico do chat (string). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` Opcional: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas (o padrão é redigir). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas (o padrão é redigir). Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -243,7 +243,7 @@ Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime Artefatos de saída: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta SUT observada), começando pelo canary. +- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta observada do SUT) começando pelo canary. - `telegram-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. ### QA do Discord @@ -252,7 +252,7 @@ Artefatos de saída: pnpm openclaw qa discord ``` -Tem como alvo um canal real de guilda privada do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Discord empacotado. Verifica o tratamento de menções de canal, que o bot SUT registrou o comando nativo `/help` com o Discord, e cenários de evidência Mantis opcionais. +Mira em um canal real privado de guilda do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway OpenClaw filho por meio do Plugin Discord incluído. Verifica o tratamento de menções no canal, se o bot SUT registrou o comando nativo `/help` no Discord e cenários de evidência Mantis opcionais. Env obrigatório quando `--credential-source env`: @@ -260,20 +260,20 @@ Env obrigatório quando `--credential-source env`: - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — deve corresponder ao ID de usuário do bot SUT retornado pelo Discord (caso contrário, a lane falha rapidamente). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — precisa corresponder ao id de usuário do bot SUT retornado pelo Discord (caso contrário, a pista falha rapidamente). Opcional: -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas. +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas. Cenários (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`): - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — cenário Mantis opcional. Executa sozinho porque muda o SUT para respostas de guilda sempre ativas e somente por ferramenta com `messages.statusReactions.enabled=true`, e então captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG. +- `discord-status-reactions-tool-only` — cenário Mantis opcional. Executa sozinho porque alterna o SUT para respostas de guilda sempre ativas e apenas com ferramentas com `messages.statusReactions.enabled=true`, depois captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG. -Execute explicitamente o cenário de reações de status do Mantis: +Execute explicitamente o cenário de reação de status Mantis: ```bash pnpm openclaw qa discord \ @@ -297,7 +297,7 @@ Artefatos de saída: pnpm openclaw qa slack ``` -Tem como alvo um canal privado real do Slack com dois bots distintos: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Slack empacotado. +Mira em um canal privado real do Slack com dois bots distintos: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway OpenClaw filho por meio do Plugin Slack incluído. Env obrigatório quando `--credential-source env`: @@ -308,7 +308,7 @@ Env obrigatório quando `--credential-source env`: Opcional: -- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas. +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas. Cenários (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`): @@ -321,55 +321,223 @@ Artefatos de saída: - `slack-qa-summary.json` - `slack-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. +#### Configurando o workspace do Slack + +A pista precisa de dois apps Slack distintos em um workspace, além de um canal do qual ambos os bots sejam membros: + +- `channelId` — o id `Cxxxxxxxxxx` de um canal para o qual ambos os bots foram convidados. Use um canal dedicado; a pista publica em cada execução. +- `driverBotToken` — token de bot (`xoxb-...`) do app **Driver**. +- `sutBotToken` — token de bot (`xoxb-...`) do app **SUT**, que deve ser um app Slack separado do driver para que seu id de usuário de bot seja distinto. +- `sutAppToken` — token de nível de app (`xapp-...`) do app SUT com `connections:write`, usado pelo Socket Mode para que o app SUT possa receber eventos. + +Prefira um workspace Slack dedicado a QA em vez de reutilizar um workspace de produção. + +O manifesto do SUT abaixo espelha a instalação de produção do Plugin Slack incluído (`extensions/slack/src/setup-shared.ts:10`). Para a configuração de canal de produção como os usuários a veem, consulte [configuração rápida de canal do Slack](/pt-BR/channels/slack#quick-setup); o par Driver/SUT de QA é intencionalmente separado porque a pista precisa de dois ids de usuário de bot distintos em um workspace. + +**1. Crie o app Driver** + +Acesse [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → escolha o workspace de QA, cole o manifesto a seguir e depois _Install to Workspace_: + +```json +{ + "display_information": { + "name": "OpenClaw QA Driver", + "description": "Test driver bot for OpenClaw QA Slack live lane" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA Driver", + "always_online": true + } + }, + "oauth_config": { + "scopes": { + "bot": ["chat:write", "channels:history", "groups:history", "users:read"] + } + }, + "settings": { + "socket_mode_enabled": false + } +} +``` + +Copie o _Bot User OAuth Token_ (`xoxb-...`) — isso se torna `driverBotToken`. O driver só precisa publicar mensagens e se identificar; sem eventos, sem Socket Mode. + +**2. Crie o app SUT** + +Repita _Create New App → From a manifest_ no mesmo workspace. O conjunto de escopos espelha a instalação de produção do Plugin Slack incluído (`extensions/slack/src/setup-shared.ts:10`): + +```json +{ + "display_information": { + "name": "OpenClaw QA SUT", + "description": "OpenClaw QA SUT connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA SUT", + "always_online": true + }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +Depois que o Slack criar o app, faça duas coisas na página de configurações dele: + +- _Install to Workspace_ → copie o _Bot User OAuth Token_ → isso se torna `sutBotToken`. +- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → adicione o escopo `connections:write` → salve → copie o valor `xapp-...` → isso se torna `sutAppToken`. + +Verifique se os dois bots têm IDs de usuário distintos chamando `auth.test` em cada token. O runtime diferencia driver e SUT pelo ID do usuário; reutilizar um app para ambos falhará imediatamente no gating de menções. + +**3. Crie o canal** + +No workspace de QA, crie um canal (por exemplo, `#openclaw-qa`) e convide ambos os bots de dentro do canal: + +``` +/invite @OpenClaw QA Driver +/invite @OpenClaw QA SUT +``` + +Copie o ID `Cxxxxxxxxxx` de _channel info → About → Channel ID_ — ele se torna `channelId`. Um canal público funciona; se você usar um canal privado, ambos os apps já têm `groups:history`, então as leituras de histórico do harness ainda terão sucesso. + +**4. Registre as credenciais** + +Duas opções. Use variáveis de ambiente para depuração em uma única máquina (defina as quatro variáveis `OPENCLAW_QA_SLACK_*` e passe `--credential-source env`) ou semeie o pool Convex compartilhado para que o CI e outros mantenedores possam alugá-las. + +Para o pool Convex, grave os quatro campos em um arquivo JSON: + +```json +{ + "channelId": "Cxxxxxxxxxx", + "driverBotToken": "xoxb-...", + "sutBotToken": "xoxb-...", + "sutAppToken": "xapp-..." +} +``` + +Com `OPENCLAW_QA_CONVEX_SITE_URL` e `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` exportados no seu shell, registre e verifique: + +```bash +pnpm openclaw qa credentials add \ + --kind slack \ + --payload-file slack-creds.json \ + --note "QA Slack pool seed" + +pnpm openclaw qa credentials list --kind slack --status all --json +``` + +Espere `count: 1`, `status: "active"`, sem campo `lease`. + +**5. Verifique de ponta a ponta** + +Execute a lane localmente para confirmar que ambos os bots conseguem conversar entre si por meio do broker: + +```bash +pnpm openclaw qa slack \ + --credential-source convex \ + --credential-role maintainer \ + --output-dir .artifacts/qa-e2e/slack-local +``` + +Uma execução verde é concluída em bem menos de 30 segundos, e `slack-qa-report.md` mostra tanto `slack-canary` quanto `slack-mention-gating` com status `pass`. Se a lane travar por cerca de 90 segundos e sair com `Convex credential pool exhausted for kind "slack"`, o pool está vazio ou todas as linhas estão alugadas — `qa credentials list --kind slack --status all --json` indicará qual é o caso. + ### Pool de credenciais Convex -As lanes do Telegram, Discord e Slack podem alugar credenciais de um pool Convex compartilhado em vez de ler as variáveis de env acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire uma locação exclusiva, envia heartbeats durante a execução e a libera no desligamento. Os tipos de pool são `"telegram"`, `"discord"` e `"slack"`. +As lanes Telegram, Discord e Slack podem alugar credenciais de um pool Convex compartilhado em vez de ler as variáveis de ambiente acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire um lease exclusivo, envia Heartbeats durante a execução e o libera no encerramento. Os tipos do pool são `"telegram"`, `"discord"` e `"slack"`. Formatos de payload que o broker valida em `admin/add`: -- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string de ID numérico de chat. +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string numérica de chat-id. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. +- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` deve corresponder a `^[A-Z][A-Z0-9]+$` (um ID do Slack como `Cxxxxxxxxxx`). Consulte [Configurando o workspace Slack](#setting-up-the-slack-workspace) para o provisionamento de app e escopos. -As variáveis de env operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais compartilhadas do Telegram via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos). +As variáveis de ambiente operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais Telegram compartilhadas via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos). -## Seeds apoiados pelo repositório +## Seeds baseados no repositório Os ativos de seed ficam em `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Eles ficam intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o -agente. +Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o agente. -`qa-lab` deve continuar sendo um executor genérico de markdown. Cada arquivo markdown de cenário é -a fonte da verdade para uma execução de teste e deve definir: +`qa-lab` deve permanecer um runner Markdown genérico. Cada arquivo Markdown de cenário é a fonte da verdade para uma execução de teste e deve definir: - metadados do cenário - metadados opcionais de categoria, capacidade, lane e risco -- refs de docs e código -- requisitos opcionais de Plugin +- referências de docs e código +- requisitos opcionais de plugin - patch opcional de configuração do Gateway - o `qa-flow` executável -A superfície de runtime reutilizável que sustenta `qa-flow` pode continuar genérica -e transversal. Por exemplo, cenários markdown podem combinar auxiliares do lado do transporte -com auxiliares do lado do navegador que conduzem a Control UI incorporada por meio da -seam `browser.request` do Gateway sem adicionar um runner especial. +A superfície reutilizável de runtime que sustenta `qa-flow` pode permanecer genérica e transversal. Por exemplo, cenários Markdown podem combinar helpers do lado do transporte com helpers do lado do navegador que controlam a Control UI incorporada por meio da costura `browser.request` do Gateway sem adicionar um runner especial para esse caso. -Os arquivos de cenário devem ser agrupados por capacidade de produto, em vez de pasta -da árvore de código-fonte. Mantenha os IDs de cenário estáveis quando arquivos forem movidos; use `docsRefs` e `codeRefs` -para rastreabilidade da implementação. +Os arquivos de cenário devem ser agrupados por capacidade do produto, não por pasta da árvore de origem. Mantenha os IDs de cenário estáveis quando os arquivos forem movidos; use `docsRefs` e `codeRefs` para rastreabilidade da implementação. A lista de base deve permanecer ampla o suficiente para cobrir: -- chat por DM e canal +- chat em DM e canal - comportamento de threads - ciclo de vida de ações de mensagem -- callbacks de cron -- recall de memória +- callbacks de Cron +- recuperação de memória - troca de modelo -- handoff para subagente +- handoff de subagente - leitura de repositório e leitura de docs - uma pequena tarefa de build, como Lobster Invaders @@ -377,78 +545,71 @@ A lista de base deve permanecer ampla o suficiente para cobrir: `qa suite` tem duas lanes locais de mock de provedor: -- `mock-openai` é o mock do OpenClaw ciente de cenários. Ele continua sendo a lane de mock determinística - padrão para QA apoiado pelo repositório e gates de paridade. -- `aimock` inicia um servidor de provedor apoiado pelo AIMock para cobertura experimental de protocolo, - fixture, gravação/reprodução e caos. Ele é aditivo e não - substitui o dispatcher de cenários `mock-openai`. +- `mock-openai` é o mock OpenClaw ciente de cenários. Ele permanece a lane de mock determinística padrão para QA baseado no repositório e gates de paridade. +- `aimock` inicia um servidor de provedor baseado em AIMock para cobertura experimental de protocolo, fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o dispatcher de cenários `mock-openai`. -A implementação de lanes de provedor fica em `extensions/qa-lab/src/providers/`. -Cada provedor possui seus padrões, inicialização de servidor local, configuração de modelo do Gateway, -necessidades de preparação de perfil de autenticação e flags de capacidade live/mock. O código compartilhado da suíte e do -Gateway deve rotear pelo registro de provedores em vez de ramificar por -nomes de provedores. +A implementação de lanes de provedor fica em `extensions/qa-lab/src/providers/`. Cada provedor possui seus próprios padrões, inicialização de servidor local, configuração de modelo do Gateway, necessidades de staging de auth-profile e flags de capacidade live/mock. O código compartilhado da suite e do Gateway deve rotear pelo registro de provedores em vez de ramificar por nomes de provedores. ## Adaptadores de transporte -`qa-lab` possui uma seam de transporte genérica para cenários de QA em markdown. `qa-channel` é o primeiro adaptador nessa seam, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suíte em vez de adicionar um runner de QA específico para transporte. +`qa-lab` possui uma costura de transporte genérica para cenários Markdown de QA. `qa-channel` é o primeiro adaptador nessa costura, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suite em vez de adicionar um runner de QA específico para transporte. No nível de arquitetura, a divisão é: -- `qa-lab` possui execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios. +- `qa-lab` possui execução genérica de cenários, concorrência de workers, escrita de artefatos e relatórios. - O adaptador de transporte possui configuração do Gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado. -- Arquivos de cenário markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa. +- Arquivos de cenário Markdown em `qa/scenarios/` definem a execução do teste; `qa-lab` fornece a superfície reutilizável de runtime que os executa. ### Adicionando um canal -Adicionar um canal ao sistema de QA em markdown exige exatamente duas coisas: +Adicionar um canal ao sistema de QA Markdown exige exatamente duas coisas: 1. Um adaptador de transporte para o canal. 2. Um pacote de cenários que exercite o contrato do canal. -Não adicione uma nova raiz de comando de QA de nível superior quando o host `qa-lab` compartilhado puder ser dono do fluxo. +Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder possuir o fluxo. -`qa-lab` é responsável pela mecânica compartilhada do host: +`qa-lab` possui a mecânica do host compartilhado: - a raiz do comando `openclaw qa` -- inicialização e encerramento da suíte +- inicialização e teardown da suite - concorrência de workers -- gravação de artefatos +- escrita de artefatos - geração de relatórios - execução de cenários - aliases de compatibilidade para cenários `qa-channel` mais antigos -Os plugins executores são responsáveis pelo contrato de transporte: +Plugins de runner possuem o contrato de transporte: -- como `openclaw qa ` é montado abaixo da raiz `qa` compartilhada -- como o gateway é configurado para esse transporte +- como `openclaw qa ` é montado abaixo da raiz compartilhada `qa` +- como o Gateway é configurado para esse transporte - como a prontidão é verificada - como eventos de entrada são injetados - como mensagens de saída são observadas -- como transcrições e o estado normalizado do transporte são expostos -- como ações respaldadas pelo transporte são executadas -- como redefinições ou limpezas específicas do transporte são tratadas +- como transcrições e estado de transporte normalizado são expostos +- como ações apoiadas por transporte são executadas +- como reset ou limpeza específicos do transporte são tratados -O nível mínimo de adoção para um novo canal: +O patamar mínimo de adoção para um novo canal: -1. Mantenha `qa-lab` como responsável pela raiz `qa` compartilhada. -2. Implemente o executor de transporte na interface compartilhada de host do `qa-lab`. -3. Mantenha a mecânica específica de transporte dentro do plugin executor ou do harness de canal. -4. Monte o executor como `openclaw qa ` em vez de registrar um comando raiz concorrente. Plugins executores devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; a CLI preguiçosa e a execução do executor devem ficar atrás de pontos de entrada separados. +1. Mantenha `qa-lab` como proprietário da raiz compartilhada `qa`. +2. Implemente o runner de transporte na costura do host compartilhado `qa-lab`. +3. Mantenha a mecânica específica do transporte dentro do plugin de runner ou harness do canal. +4. Monte o runner como `openclaw qa ` em vez de registrar um comando raiz concorrente. Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; a CLI lazy e a execução do runner devem permanecer atrás de entrypoints separados. 5. Crie ou adapte cenários Markdown nos diretórios temáticos `qa/scenarios/`. -6. Use os auxiliares genéricos de cenário para novos cenários. -7. Mantenha os aliases de compatibilidade existentes funcionando, a menos que o repo esteja fazendo uma migração intencional. +6. Use os helpers genéricos de cenário para novos cenários. +7. Mantenha os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional. A regra de decisão é estrita: - Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`. -- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin executor ou harness de plugin. -- Se um cenário precisar de um novo recurso que mais de um canal possa usar, adicione um auxiliar genérico em vez de uma ramificação específica de canal em `suite.ts`. -- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico de transporte e deixe isso explícito no contrato do cenário. +- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin de runner ou harness de plugin. +- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de uma ramificação específica de canal em `suite.ts`. +- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico de transporte e explicite isso no contrato do cenário. -### Nomes dos auxiliares de cenário +### Nomes de helpers de cenário -Auxiliares genéricos preferidos para novos cenários: +Helpers genéricos preferidos para novos cenários: - `waitForTransportReady` - `waitForChannelReady` @@ -463,11 +624,11 @@ Auxiliares genéricos preferidos para novos cenários: - `formatTransportTranscript` - `resetTransport` -Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a criação de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração completa de uma só vez, não como o modelo daqui em diante. +Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a autoria de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração flag-day, não como o modelo daqui para frente. ## Relatórios -`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do barramento. +`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado. O relatório deve responder: - O que funcionou @@ -477,8 +638,7 @@ O relatório deve responder: Para o inventário de cenários disponíveis — útil ao dimensionar trabalho de acompanhamento ou conectar um novo transporte — execute `pnpm openclaw qa coverage` (adicione `--json` para saída legível por máquina). -Para verificações de personagem e estilo, execute o mesmo cenário em várias refs de modelos ao vivo -e grave um relatório julgado em Markdown: +Para verificações de caráter e estilo, execute o mesmo cenário em múltiplas refs de modelo live e grave um relatório Markdown julgado: ```bash pnpm openclaw qa character-eval \ @@ -497,42 +657,23 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -O comando executa processos filhos locais do Gateway de QA, não Docker. Cenários de avaliação de personagem -devem definir a persona por meio de `SOUL.md` e depois executar turnos comuns de usuário, -como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato -não deve ser informado de que está sendo avaliado. O comando preserva cada -transcrição completa, registra estatísticas básicas de execução e depois pede aos modelos juízes em modo rápido com -raciocínio `xhigh`, quando houver suporte, para classificar as execuções por naturalidade, vibe e humor. -Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe -todas as transcrições e estados de execução, mas as refs candidatas são substituídas por -rótulos neutros como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após -a análise. -Execuções candidatas usam `high` thinking por padrão, com `medium` para GPT-5.5 e `xhigh` -para refs de avaliação OpenAI mais antigas que oferecem suporte. Substitua um candidato específico em linha com -`--model provider/model,thinking=`. `--thinking ` ainda define um -fallback global, e a forma mais antiga `--model-thinking ` é -mantida para compatibilidade. -Refs candidatas OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado onde -o provedor oferece suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` em linha quando um -único candidato ou juiz precisar de uma substituição. Passe `--fast` somente quando quiser -forçar o modo rápido para todos os modelos candidatos. As durações de candidatos e juízes são -registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente -para não classificar por velocidade. -Execuções dos modelos candidatos e juízes usam concorrência 16 por padrão. Reduza -`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão local do Gateway -tornarem uma execução ruidosa demais. -Quando nenhum candidato `--model` é passado, a avaliação de personagem usa por padrão +O comando executa processos filhos do Gateway de QA local, não Docker. Cenários de avaliação de personagem devem definir a persona por meio de `SOUL.md` e, depois, executar turnos comuns de usuário, como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição completa, registra estatísticas básicas da execução e, depois, pede aos modelos julgadores em modo rápido, com raciocínio `xhigh` quando houver suporte, que classifiquem as execuções por naturalidade, tom e humor. +Use `--blind-judge-models` ao comparar provedores: o prompt do julgador ainda recebe cada transcrição e status de execução, mas as refs dos candidatos são substituídas por rótulos neutros, como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após a análise. +Execuções de candidatos usam `high` como padrão de thinking, com `medium` para GPT-5.5 e `xhigh` para refs de avaliação mais antigas da OpenAI que oferecem suporte a isso. Sobrescreva um candidato específico inline com `--model provider/model,thinking=`. `--thinking ` ainda define um fallback global, e o formato antigo `--model-thinking ` é mantido por compatibilidade. +Refs de candidatos da OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um único candidato ou julgador precisar de uma substituição. Passe `--fast` apenas quando quiser forçar o modo rápido para todos os modelos candidatos. As durações de candidatos e julgadores são registradas no relatório para análise de benchmark, mas os prompts dos julgadores dizem explicitamente para não classificar por velocidade. +Execuções de modelos candidatos e julgadores usam concorrência 16 por padrão. Reduza `--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway local tornarem uma execução ruidosa demais. +Quando nenhum `--model` de candidato é passado, a avaliação de personagem usa como padrão `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e `google/gemini-3.1-pro-preview` quando nenhum `--model` é passado. -Quando nenhum `--judge-model` é passado, os juízes usam por padrão +Quando nenhum `--judge-model` é passado, os julgadores usam como padrão `openai/gpt-5.5,thinking=xhigh,fast` e `anthropic/claude-opus-4-6,thinking=high`. -## Documentos relacionados +## Documentação relacionada -- [QA de matriz](/pt-BR/concepts/qa-matrix) +- [Matriz de QA](/pt-BR/concepts/qa-matrix) - [Canal de QA](/pt-BR/channels/qa-channel) - [Testes](/pt-BR/help/testing) -- [Dashboard](/pt-BR/web/dashboard) +- [Painel](/pt-BR/web/dashboard) diff --git a/docs/pt-BR/gateway/config-tools.md b/docs/pt-BR/gateway/config-tools.md index 5980a326a..26709a0d0 100644 --- a/docs/pt-BR/gateway/config-tools.md +++ b/docs/pt-BR/gateway/config-tools.md @@ -1,35 +1,35 @@ --- read_when: - - Configurando a política `tools.*`, listas de permissões ou recursos experimentais + - Configurando a política de `tools.*`, listas de permissões ou recursos experimentais - Registrando provedores personalizados ou substituindo URLs base - Configurando endpoints auto-hospedados compatíveis com OpenAI sidebarTitle: Tools and custom providers -summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas com suporte de provedor) e configuração personalizada de provedor/base-URL +summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas apoiadas por provedor) e configuração personalizada de provedor/URL base title: Configuração — ferramentas e provedores personalizados x-i18n: - generated_at: "2026-05-03T21:31:35Z" + generated_at: "2026-05-05T01:45:57Z" model: gpt-5.5 provider: openai - source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da + source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883 source_path: gateway/config-tools.md workflow: 16 --- -`tools.*` chaves de configuração e configuração personalizada de provedor / URL base. Para agentes, canais e outras chaves de configuração de nível superior, consulte [Referência de configuração](/pt-BR/gateway/configuration-reference). +`tools.*` chaves de configuração e configuração de provedor personalizado / URL base. Para agentes, canais e outras chaves de configuração de nível superior, consulte [Referência de configuração](/pt-BR/gateway/configuration-reference). ## Ferramentas ### Perfis de ferramentas -`tools.profile` define uma lista de permissões base antes de `tools.allow`/`tools.deny`: +`tools.profile` define uma lista de permissão base antes de `tools.allow`/`tools.deny`: -A integração local define novas configurações locais como `tools.profile: "coding"` quando não estiver definido (perfis explícitos existentes são preservados). +O onboarding local define novas configurações locais como `tools.profile: "coding"` quando não estiver definido (perfis explícitos existentes são preservados). | Perfil | Inclui | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | somente `session_status` | +| `minimal` | apenas `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `full` | Sem restrição (igual a não definido) | @@ -49,11 +49,11 @@ A integração local define novas configurações locais como `tools.profile: "c | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas as ferramentas integradas (exclui Plugins de provedor) | +| `group:openclaw` | Todas as ferramentas integradas (exclui plugins de provedor) | ### `tools.allow` / `tools.deny` -Política global de permissão/negação de ferramentas (negação prevalece). Não diferencia maiúsculas de minúsculas, aceita curingas `*`. Aplicada mesmo quando o sandbox do Docker está desativado. +Política global de permissão/negação de ferramentas (`deny` prevalece). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. ```json5 { @@ -61,7 +61,7 @@ Política global de permissão/negação de ferramentas (negação prevalece). N } ``` -`write` e `apply_patch` são IDs de ferramentas separados. `allow: ["write"]` também habilita `apply_patch` para modelos compatíveis, mas `deny: ["write"]` não nega `apply_patch`. Para bloquear toda mutação de arquivos, negue `group:fs` ou liste explicitamente cada ferramenta de mutação: +`write` e `apply_patch` são ids de ferramenta separados. `allow: ["write"]` também habilita `apply_patch` para modelos compatíveis, mas `deny: ["write"]` não nega `apply_patch`. Para bloquear toda mutação de arquivos, negue `group:fs` ou liste explicitamente cada ferramenta de mutação: ```json5 { @@ -71,7 +71,7 @@ Política global de permissão/negação de ferramentas (negação prevalece). N ### `tools.byProvider` -Restrinja ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permissão/negação. +Restringe ainda mais as ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permissão/negação. ```json5 { @@ -87,7 +87,7 @@ Restrinja ainda mais ferramentas para provedores ou modelos específicos. Ordem: ### `tools.elevated` -Controla o acesso elevado de exec fora do sandbox: +Controla o acesso elevado de `exec` fora do sandbox: ```json5 { @@ -105,7 +105,7 @@ Controla o acesso elevado de exec fora do sandbox: - A substituição por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. - `/elevated on|off|ask|full` armazena o estado por sessão; diretivas inline se aplicam a uma única mensagem. -- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino de exec é `node`). +- `exec` elevado ignora o sandboxing e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o alvo de `exec` é `node`). ### `tools.exec` @@ -129,7 +129,7 @@ Controla o acesso elevado de exec fora do sandbox: ### `tools.loopDetection` -As verificações de segurança contra loops de ferramentas são **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`. +As verificações de segurança contra loops de ferramentas estão **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`. ```json5 { @@ -151,25 +151,25 @@ As verificações de segurança contra loops de ferramentas são **desativadas p ``` - Máximo de histórico de chamadas de ferramenta mantido para análise de loops. + Histórico máximo de chamadas de ferramenta retido para análise de loops. - Limite de padrões repetidos sem progresso para avisos. + Limite de padrão repetido sem progresso para avisos. Limite de repetição mais alto para bloquear loops críticos. - Limite de parada rígida para qualquer execução sem progresso. + Limite de parada forçada para qualquer execução sem progresso. - Avisa sobre chamadas repetidas com a mesma ferramenta/os mesmos argumentos. + Avisar sobre chamadas repetidas com a mesma ferramenta/os mesmos argumentos. - Avisa/bloqueia ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.). + Avisar/bloquear em ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.). - Avisa/bloqueia padrões alternados de pares sem progresso. + Avisar/bloquear em padrões alternados de pares sem progresso. @@ -208,7 +208,7 @@ Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircui ### `tools.media` -Configura a compreensão de mídia recebida (imagem/áudio/vídeo): +Configura o entendimento de mídia recebida (imagem/áudio/vídeo): ```json5 { @@ -216,7 +216,7 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async video directly to the channel + directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, @@ -246,30 +246,30 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo): ``` - + **Entrada de provedor** (`type: "provider"` ou omitido): - - `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) - - `model`: substituição do ID do modelo - - `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` + - `provider`: id do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) + - `model`: substituição do id do modelo + - `profile` / `preferredProfile`: seleção de perfil de `auth-profiles.json` **Entrada de CLI** (`type: "cli"`): - - `command`: executável a executar - - `args`: argumentos com modelo (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.; `openclaw doctor --fix` migra placeholders `{input}` obsoletos para `{{MediaPath}}`) + - `command`: executável a ser executado + - `args`: argumentos com modelo (aceita `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.; `openclaw doctor --fix` migra placeholders obsoletos `{input}` para `{{MediaPath}}`) **Campos comuns:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → imagem, `google` → imagem+áudio+vídeo, `groq` → áudio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada. - `tools.media.image.timeoutSeconds` e entradas correspondentes de `timeoutSeconds` do modelo de imagem também se aplicam quando o agente chama a ferramenta explícita `image`. - - As falhas recorrem à próxima entrada. + - Falhas recorrem à próxima entrada. A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`. **Campos de conclusão assíncrona:** - - `asyncCompletion.directSend`: quando `true`, tarefas de mídia assíncronas concluídas que são compatíveis com entrega direta de conclusão tentam primeiro a entrega direta ao canal. Padrão: `false` (caminho de despertar da sessão solicitante/entrega por modelo). Atualmente, isso se aplica a `video_generate` assíncrono; conclusões assíncronas de `music_generate` continuam mediadas pela sessão solicitante mesmo quando isso está ativado. + - `asyncCompletion.directSend`: sinalizador de compatibilidade obsoleto. Tarefas assíncronas de mídia concluídas permanecem mediadas pela sessão solicitante para que o agente receba o resultado, decida como informar o usuário e use a ferramenta de mensagem quando a entrega de origem exigir. @@ -305,12 +305,12 @@ Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). ``` - - - `self`: somente a chave da sessão atual. + + - `self`: apenas a chave da sessão atual. - `tree`: sessão atual + sessões geradas pela sessão atual (subagentes). - - `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente). - - `all`: qualquer sessão. O direcionamento entre agentes ainda requer `tools.agentToAgent`. - - Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`. + - `agent`: qualquer sessão pertencente ao id do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo id de agente). + - `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`. + - Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo que `tools.sessions.visibility="all"`. @@ -339,10 +339,10 @@ Controla o suporte a anexos inline para `sessions_spawn`. - Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita. - Os arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. - - O conteúdo dos anexos é automaticamente redigido da persistência da transcrição. - - Entradas Base64 são validadas com verificações estritas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação. + - O conteúdo dos anexos é automaticamente censurado da persistência da transcrição. + - Entradas Base64 são validadas com verificações rigorosas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação. - As permissões de arquivo são `0700` para diretórios e `0600` para arquivos. - - A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`. + - A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os mantém apenas quando `retainOnSessionKeep: true`. @@ -351,7 +351,7 @@ Controla o suporte a anexos inline para `sessions_spawn`. ### `tools.experimental` -Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos que uma regra de ativação automática strict-agentic do GPT-5 se aplique. +Flags experimentais de ferramentas integradas. Desativado por padrão, a menos que uma regra de ativação automática strict-agentic do GPT-5 se aplique. ```json5 { @@ -363,8 +363,8 @@ Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos } ``` -- `planTool`: habilita a ferramenta estruturada `update_plan` para rastreamento de trabalho não trivial em várias etapas. -- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 do OpenAI ou OpenAI Codex. Defina como `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções strict-agentic do GPT-5. +- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhar trabalhos não triviais de várias etapas. +- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 strict-agentic. - Quando habilitado, o prompt do sistema também adiciona orientações de uso para que o modelo a use apenas em trabalhos substanciais e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -385,16 +385,16 @@ Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos } ``` -- `model`: modelo padrão para subagentes gerados. Se omitido, os subagentes herdam o modelo do chamador. -- `allowAgents`: lista de permissões padrão de IDs de agentes de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). -- `runTimeoutSeconds`: tempo limite padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem tempo limite. -- Política de ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: modelo padrão para subagentes iniciados. Se omitido, os subagentes herdam o modelo do chamador. +- `allowAgents`: lista de permissões padrão de IDs de agentes de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: somente o mesmo agente). +- `runTimeoutSeconds`: timeout padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem timeout. +- Política de ferramentas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Provedores personalizados e URLs base -O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizados via `models.providers` na configuração ou em `~/.openclaw/agents//agent/models.json`. +OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizados via `models.providers` na configuração ou em `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -427,75 +427,75 @@ O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personaliza - Use `authHeader: true` + `headers` para necessidades de autenticação personalizada. - Substitua a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). - - Precedência de mesclagem para IDs de provedor correspondentes: - - Valores `baseUrl` não vazios de `models.json` do agente vencem. - - Valores `apiKey` não vazios do agente vencem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. - - Valores `apiKey` de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. - - Valores de cabeçalho de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec). - - `apiKey`/`baseUrl` vazios ou ausentes do agente recorrem a `models.providers` na configuração. - - `contextWindow`/`maxTokens` de modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. - - `contextTokens` de modelo correspondente preserva um limite de runtime explícito quando presente; use-o para limitar o contexto efetivo sem alterar metadados nativos do modelo. + - Precedência de mesclagem para IDs de provedores correspondentes: + - Valores `baseUrl` não vazios do `models.json` do agente vencem. + - Valores `apiKey` não vazios do agente vencem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação. + - Valores `apiKey` de provedor gerenciado por SecretRef são atualizados a partir dos marcadores de origem (`ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. + - Valores de cabeçalho de provedor gerenciado por SecretRef são atualizados a partir dos marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec). + - `apiKey`/`baseUrl` vazios ou ausentes do agente voltam para `models.providers` na configuração. + - `contextWindow`/`maxTokens` de modelos correspondentes usam o maior valor entre a configuração explícita e os valores implícitos do catálogo. + - `contextTokens` de modelos correspondentes preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo. - Use `models.mode: "replace"` quando quiser que a configuração reescreva completamente `models.json`. - - A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot de configuração de origem ativo (antes da resolução), não dos valores de segredo de runtime resolvidos. + - A persistência de marcadores tem a origem como autoridade: os marcadores são escritos a partir do snapshot da configuração de origem ativa (pré-resolução), não dos valores de segredo resolvidos em runtime. -### 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 por ID de provedor. + - `models.providers`: mapa de provedores personalizados indexado pelo ID do 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 requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). Para backends auto-hospedados de `/v1/chat/completions`, como MLX, vLLM, SGLang e a maioria dos servidores locais compatíveis com OpenAI, use `openai-completions`. Um provedor personalizado com `baseUrl` mas sem `api` usa `openai-completions` por padrão; defina `openai-responses` apenas quando o backend oferecer suporte a `/v1/responses`. - - `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por env). + - `models.providers.*.api`: adaptador de solicitação (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc). Para backends auto-hospedados `/v1/chat/completions`, como MLX, vLLM, SGLang e a maioria dos servidores locais compatíveis com OpenAI, use `openai-completions`. Um provedor personalizado com `baseUrl` mas sem `api` usa `openai-completions` como padrão; defina `openai-responses` apenas quando o backend for compatível com `/v1/responses`. + - `models.providers.*.apiKey`: credencial do provedor (prefira substituição por SecretRef/env). - `models.providers.*.auth`: estratégia de autenticação (`api-key`, `token`, `oauth`, `aws-sdk`). - - `models.providers.*.contextWindow`: janela de contexto nativa padrão para modelos neste provedor quando a entrada do modelo não define `contextWindow`. - - `models.providers.*.contextTokens`: limite efetivo padrão de contexto de runtime para modelos neste provedor quando a entrada do modelo não define `contextTokens`. - - `models.providers.*.maxTokens`: limite padrão de tokens de saída para modelos neste provedor quando a entrada do modelo não define `maxTokens`. - - `models.providers.*.timeoutSeconds`: tempo limite opcional por provedor para requisições HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de abortamento total da requisição. - - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas requisições (padrão: `true`). + - `models.providers.*.contextWindow`: janela de contexto nativa padrão para modelos desse provedor quando a entrada do modelo não define `contextWindow`. + - `models.providers.*.contextTokens`: limite efetivo padrão de contexto em runtime para modelos desse provedor quando a entrada do modelo não define `contextTokens`. + - `models.providers.*.maxTokens`: limite padrão de tokens de saída para modelos desse provedor quando a entrada do modelo não define `maxTokens`. + - `models.providers.*.timeoutSeconds`: timeout opcional por provedor para solicitações HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de aborto da solicitação total. + - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas solicitações (padrão: `true`). - `models.providers.*.authHeader`: força o transporte de credenciais no cabeçalho `Authorization` quando necessário. - `models.providers.*.baseUrl`: URL base da API upstream. - `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento de proxy/tenant. - - `models.providers.*.request`: substituições de transporte para requisições HTTP de provedores de modelo. + + `models.providers.*.request`: substituições de transporte para solicitações HTTP do provedor de modelos. - - `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Os valores aceitam SecretRef. - - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). + - `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Valores aceitam SecretRef. + - `request.auth`: substituição de estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional. - `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para faixas privadas, CGNAT ou semelhantes, via proteção de fetch HTTP do provedor (aceite explícito do operador para endpoints auto-hospedados compatíveis com OpenAI e confiáveis). URLs de stream de provedor de modelo em local loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isso seja definido explicitamente como `false`; hosts LAN, tailnet e DNS privado ainda exigem aceite explícito. WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não esse bloqueio SSRF de fetch. Padrão `false`. + - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou similares, por meio da proteção de fetch HTTP do provedor (adesão explícita do operador para endpoints auto-hospedados confiáveis compatíveis com OpenAI). URLs de stream de provedor de modelos em local loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isso seja explicitamente definido como `false`; hosts de LAN, tailnet e DNS privado ainda exigem adesão explícita. WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa barreira SSRF de fetch. Padrão `false`. - `models.providers.*.models`: entradas explícitas do catálogo de modelos do provedor. - - `models.providers.*.models.*.input`: modalidades de entrada do modelo. Use `["text"]` para modelos somente texto e `["text", "image"]` para modelos nativos de imagem/visão. Anexos de imagem são injetados em turnos do agente apenas quando o modelo selecionado está marcado como compatível com imagens. - - `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. Isso substitui `contextWindow` em nível de provedor para esse modelo. - - `models.providers.*.models.*.contextTokens`: limite opcional de contexto de runtime. Isso substitui `contextTokens` em nível de provedor; use quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo; `openclaw models list` mostra ambos os valores quando eles diferem. - - `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com um `baseUrl` não vazio e não nativo (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. - - `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas strings. Quando `true`, o OpenClaw achata arrays `messages[].content` de texto puro em strings simples antes de enviar a requisição. + - `models.providers.*.models.*.input`: modalidades de entrada do modelo. Use `["text"]` para modelos somente texto e `["text", "image"]` para modelos nativos de imagem/visão. Anexos de imagem só são injetados em turnos do agente quando o modelo selecionado está marcado como compatível com imagem. + - `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. Isso substitui o `contextWindow` em nível de provedor para esse modelo. + - `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Isso substitui o `contextTokens` em nível de provedor; use quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo; `openclaw models list` mostra ambos os valores quando diferem. + - `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com um `baseUrl` não nativo e não vazio (host diferente de `api.openai.com`), OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. + - `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam somente strings. Quando `true`, OpenClaw achata arrays de texto puro `messages[].content` em strings simples antes de enviar a solicitação. - `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de descoberta automática do Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa a descoberta implícita. - - `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para descoberta. + - `plugins.entries.amazon-bedrock.config.discovery.region`: região da AWS para descoberta. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional por ID de provedor para descoberta direcionada. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta. - - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto reserva para modelos descobertos. - - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída reserva para modelos descobertos. + - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto de fallback para modelos descobertos. + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos. -O onboarding interativo de provedores personalizados infere entrada de imagem para IDs comuns de modelos de visão, como GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V e GLM-4V, e ignora a pergunta extra para famílias conhecidas somente texto. IDs de modelo desconhecidos ainda solicitam suporte a imagem. O onboarding não interativo usa a mesma inferência; passe `--custom-image-input` para forçar metadados compatíveis com imagem ou `--custom-text-input` para forçar metadados somente texto. +A integração interativa de provedores personalizados infere entrada de imagem para IDs comuns de modelos de visão, como GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V e GLM-4V, e pula a pergunta extra para famílias conhecidas somente texto. IDs de modelos desconhecidos ainda perguntam sobre suporte a imagem. A integração não interativa usa a mesma inferência; passe `--custom-image-input` para forçar metadados compatíveis com imagem ou `--custom-text-input` para forçar metadados somente texto. ### Exemplos de provedores @@ -538,7 +538,7 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI direto. - + ```json5 { env: { KIMI_API_KEY: "sk-..." }, @@ -554,10 +554,10 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. - - Consulte [Modelos locais](/pt-BR/gateway/local-models). TL;DR: execute um modelo local grande pela API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados como fallback. + + Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um modelo local grande pela LM Studio Responses API em hardware robusto; mantenha os modelos hospedados mesclados para fallback. - + ```json5 { agents: { @@ -631,7 +631,7 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa Para o endpoint da China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. - Endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte `openai-completions` compartilhado, e o OpenClaw determina isso com base nas capacidades do endpoint, não apenas no id do provedor integrado. + Os endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado `openai-completions`, e o OpenClaw determina isso pelas capacidades do endpoint, não apenas pelo id do provedor integrado. @@ -646,10 +646,10 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa } ``` - Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencode/...` para o catálogo Zen ou referências `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. + Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use refs `opencode/...` para o catálogo Zen ou refs `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. - + ```json5 { env: { SYNTHETIC_API_KEY: "sk-..." }, @@ -709,9 +709,9 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa --- -## Relacionado +## Relacionados -- [Configuração — agentes](/pt-BR/gateway/config-agents) -- [Configuração — canais](/pt-BR/gateway/config-channels) +- [Configuração — agents](/pt-BR/gateway/config-agents) +- [Configuração — channels](/pt-BR/gateway/config-channels) - [Referência de configuração](/pt-BR/gateway/configuration-reference) — outras chaves de nível superior - [Ferramentas e plugins](/pt-BR/tools) diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index d32b5f6c6..e8da45b2f 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -1,40 +1,40 @@ --- read_when: - - Você precisa de semântica ou padrões exatos de configuração no nível dos campos + - Você precisa da semântica exata de configuração em nível de campo ou dos valores padrão - Você está validando blocos de configuração de canal, modelo, Gateway ou ferramenta -summary: Referência de configuração do Gateway para chaves centrais do OpenClaw, valores padrão e links para referências dedicadas de subsistemas +summary: Referência de configuração do Gateway para chaves centrais do OpenClaw, valores padrão e links para referências dedicadas de subsistema title: Referência de configuração x-i18n: - generated_at: "2026-05-03T21:31:42Z" + generated_at: "2026-05-05T01:45:59Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- -Referência da configuração principal para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuração](/pt-BR/gateway/configuration). +Referência de configuração principal para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuração](/pt-BR/gateway/configuration). -Abrange as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria referência mais aprofundada. Catálogos de comandos pertencentes a canais e plugins e ajustes avançados de memória/QMD ficam em suas próprias páginas, não nesta. +Abrange as principais superfícies de configuração do OpenClaw e aponta para outras páginas quando um subsistema tem sua própria referência mais aprofundada. Catálogos de comandos pertencentes a canais e Plugins, além de ajustes avançados de memória/QMD, ficam em suas próprias páginas, em vez desta. -Verdade do código: +Fonte da verdade no código: -- `openclaw config schema` imprime o JSON Schema ativo usado para validação e Control UI, com metadados de bundles/plugins/canais mesclados quando disponíveis -- `config.schema.lookup` retorna um nó de schema com escopo de caminho para ferramentas de detalhamento -- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de baseline da documentação de configuração em relação à superfície de schema atual +- `openclaw config schema` imprime o JSON Schema ativo usado para validação e Control UI, com metadados de pacotes/Plugins/canais mesclados quando disponíveis +- `config.schema.lookup` retorna um nó de esquema com escopo por caminho para ferramentas de inspeção detalhada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de base da documentação de configuração contra a superfície de esquema atual -Caminho de consulta do agente: use a ação de ferramenta `config.schema.lookup` do `gateway` para +Caminho de consulta do agente: use a ação de ferramenta `gateway` `config.schema.lookup` para documentação e restrições exatas em nível de campo antes de editar. Use [Configuração](/pt-BR/gateway/configuration) para orientação orientada a tarefas e esta página para o mapa de campos mais amplo, padrões e links para referências de subsistemas. Referências aprofundadas dedicadas: -- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de dreaming em `plugins.entries.memory-core.config.dreaming` -- [Comandos slash](/pt-BR/tools/slash-commands) para o catálogo atual de comandos integrados + em bundle -- páginas dos canais/plugins proprietários para superfícies de comandos específicas de canais +- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de Dreaming em `plugins.entries.memory-core.config.dreaming` +- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos integrados + empacotados +- páginas dos canais/Plugins proprietários para superfícies de comandos específicas de canal -O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. +O formato da configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando eles são omitidos. --- @@ -43,20 +43,20 @@ O formato de configuração é **JSON5** (comentários + vírgulas finais permit As chaves de configuração por canal foram movidas para uma página dedicada — consulte [Configuração — canais](/pt-BR/gateway/config-channels) para `channels.*`, incluindo Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e outros -canais em bundle (autenticação, controle de acesso, várias contas, controle de menções). +canais empacotados (autenticação, controle de acesso, várias contas, bloqueio por menções). ## Padrões de agente, multiagente, sessões e mensagens Movido para uma página dedicada — consulte [Configuração — agentes](/pt-BR/gateway/config-agents) para: -- `agents.defaults.*` (workspace, modelo, raciocínio, heartbeat, memória, mídia, skills, sandbox) -- `multiAgent.*` (roteamento e vinculações multiagente) -- `session.*` (ciclo de vida da sessão, compaction, poda) -- `messages.*` (entrega de mensagens, TTS, renderização markdown) +- `agents.defaults.*` (workspace, modelo, raciocínio, Heartbeat, memória, mídia, Skills, sandbox) +- `multiAgent.*` (roteamento e vínculos multiagente) +- `session.*` (ciclo de vida da sessão, Compaction, poda) +- `messages.*` (entrega de mensagens, TTS, renderização de markdown) - `talk.*` (modo Talk) - `talk.speechLocale`: id de localidade BCP 47 opcional para reconhecimento de fala do Talk no iOS/macOS - - `talk.silenceTimeoutMs`: quando não definido, o Talk mantém a janela de pausa padrão da plataforma antes de enviar a transcrição (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.silenceTimeoutMs`: quando não definido, o Talk mantém a janela de pausa padrão da plataforma antes de enviar a transcrição (`700 ms no macOS e Android, 900 ms no iOS`) ## Ferramentas e provedores personalizados @@ -66,7 +66,7 @@ provedor personalizado / URL base foram movidas para uma página dedicada — co ## Modelos -Definições de provedores, allowlists de modelos e configuração de provedor personalizado ficam em +Definições de provedores, listas de modelos permitidos e configuração de provedores personalizados ficam em [Configuração — ferramentas e provedores personalizados](/pt-BR/gateway/config-tools#custom-providers-and-base-urls). A raiz `models` também controla o comportamento global do catálogo de modelos. @@ -80,11 +80,11 @@ A raiz `models` também controla o comportamento global do catálogo de modelos. ``` - `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`). -- `models.providers`: mapa de provedores personalizados indexado por id de provedor. +- `models.providers`: mapa de provedores personalizados indexado por id do provedor. - `models.pricing.enabled`: controla a inicialização de preços em segundo plano que - começa depois que sidecars e canais chegam ao caminho pronto do Gateway. Quando `false`, + começa depois que sidecars e canais alcançam o caminho pronto do Gateway. Quando `false`, o Gateway ignora buscas de catálogo de preços do OpenRouter e LiteLLM; valores - `models.providers.*.models[].cost` configurados ainda funcionam para estimativas locais de custo. + `models.providers.*.models[].cost` configurados ainda funcionam para estimativas de custo locais. ## MCP @@ -120,15 +120,15 @@ servidor de destino durante edições de configuração. Entradas remotas usam `transport: "streamable-http"` ou `transport: "sse"`; `type: "http"` é um alias nativo da CLI que `openclaw mcp set` e `openclaw doctor --fix` normalizam para o campo canônico `transport`. -- `mcp.sessionIdleTtlMs`: TTL ocioso para runtimes MCP em bundle com escopo de sessão. - Execuções incorporadas pontuais solicitam limpeza ao fim da execução; este TTL é o recurso de segurança para - sessões de longa duração e futuros chamadores. -- Alterações em `mcp.*` são aplicadas a quente ao descartar runtimes MCP de sessão em cache. +- `mcp.sessionIdleTtlMs`: TTL ocioso para runtimes MCP empacotados com escopo de sessão. + Execuções incorporadas pontuais solicitam limpeza ao fim da execução; este TTL é a proteção para + sessões de longa duração e chamadores futuros. +- Alterações em `mcp.*` são aplicadas a quente descartando runtimes MCP de sessão em cache. A próxima descoberta/uso de ferramenta os recria a partir da nova configuração, então entradas `mcp.servers` removidas são coletadas imediatamente em vez de aguardar o TTL ocioso. Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e -[Backends de CLI](/pt-BR/gateway/cli-backends#bundle-mcp-overlays) para o comportamento em runtime. +[backends da CLI](/pt-BR/gateway/cli-backends#bundle-mcp-overlays) para o comportamento de runtime. ## Skills @@ -155,14 +155,14 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e } ``` -- `allowBundled`: allowlist opcional apenas para Skills em bundle (Skills gerenciadas/de workspace não são afetadas). -- `load.extraDirs`: raízes extras de Skills compartilhadas (menor precedência). -- `install.preferBrew`: quando verdadeiro, prefere instaladores Homebrew quando `brew` está +- `allowBundled`: allowlist opcional apenas para Skills empacotadas (Skills gerenciadas/de workspace não são afetadas). +- `load.extraDirs`: raízes adicionais compartilhadas de Skills (menor precedência). +- `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está disponível antes de recorrer a outros tipos de instalador. - `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desativa uma Skill mesmo que esteja em bundle/instalada. -- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string em texto puro ou objeto SecretRef). +- `entries..enabled: false` desativa uma Skill mesmo se ela estiver empacotada/instalada. +- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string de texto puro ou objeto SecretRef). --- @@ -173,6 +173,7 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -191,40 +192,44 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e ``` - Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions`, além de `plugins.load.paths`. -- A descoberta aceita Plugins nativos do OpenClaw mais bundles Codex compatíveis e bundles Claude, incluindo bundles Claude sem manifesto com layout padrão. -- **Alterações de configuração exigem reinicialização do gateway.** -- `allow`: allowlist opcional (apenas plugins listados são carregados). `deny` prevalece. -- `plugins.entries..apiKey`: campo de conveniência de chave de API em nível de Plugin (quando suportado pelo Plugin). +- A descoberta aceita Plugins nativos do OpenClaw, além de pacotes Codex compatíveis e pacotes Claude, incluindo pacotes Claude de layout padrão sem manifesto. +- **Alterações de configuração exigem reinício do Gateway.** +- `allow`: allowlist opcional (somente Plugins listados são carregados). `deny` prevalece. +- `bundledDiscovery`: o padrão é `"allowlist"` para novas configurações, então um + `plugins.allow` não vazio também bloqueia Plugins de provedores empacotados, incluindo provedores + de runtime de pesquisa na web. O Doctor grava `"compat"` para configurações + allowlist legadas migradas para preservar o comportamento existente de provedores empacotados até você optar pela nova política. +- `plugins.entries..apiKey`: campo de conveniência de chave de API em nível de Plugin (quando compatível com o Plugin). - `plugins.entries..env`: mapa de variáveis de ambiente com escopo de Plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompts de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de Plugin nativos e diretórios de hooks fornecidos por bundles compatíveis. -- `plugins.entries..hooks.allowConversationAccess`: quando `true`, Plugins não incluídos em bundle e confiáveis podem ler conteúdo bruto de conversas de hooks tipados como `llm_input`, `llm_output`, `before_agent_finalize` e `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: confie explicitamente neste Plugin para solicitar substituições de `provider` e `model` por execução em execuções de subagentes em segundo plano. -- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando você intencionalmente quiser permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo Plugin (validado pelo schema nativo de Plugin do OpenClaw quando disponível). +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que mutam prompts de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de Plugins nativos e diretórios de hooks fornecidos por pacotes compatíveis. +- `plugins.entries..hooks.allowConversationAccess`: quando `true`, Plugins confiáveis não empacotados podem ler conteúdo bruto de conversas de hooks tipados como `llm_input`, `llm_output`, `before_agent_finalize` e `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste Plugin para solicitar substituições de `provider` e `model` por execução em execuções de subagentes em segundo plano. +- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para substituições confiáveis de subagentes. Use `"*"` somente quando você quiser intencionalmente permitir qualquer modelo. +- `plugins.entries..config`: objeto de configuração definido pelo Plugin (validado pelo esquema de Plugin nativo do OpenClaw quando disponível). - Configurações de conta/runtime de Plugin de canal ficam em `channels.` e devem ser descritas pelos metadados `channelConfigs` do manifesto do Plugin proprietário, não por um registro central de opções do OpenClaw. - `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de busca web Firecrawl. - - `apiKey`: chave de API Firecrawl (aceita SecretRef). Usa como fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, o legado `tools.web.fetch.firecrawl.apiKey` ou a variável de ambiente `FIRECRAWL_API_KEY`. - - `baseUrl`: URL base da API Firecrawl (padrão: `https://api.firecrawl.dev`; substituições self-hosted devem apontar para endpoints privados/internos). - - `onlyMainContent`: extrair apenas o conteúdo principal das páginas (padrão: `true`). + - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Recorre a `plugins.entries.firecrawl.config.webSearch.apiKey`, ao legado `tools.web.fetch.firecrawl.apiKey` ou à variável de ambiente `FIRECRAWL_API_KEY`. + - `baseUrl`: URL base da API do Firecrawl (padrão: `https://api.firecrawl.dev`; substituições auto-hospedadas devem apontar para endpoints privados/internos). + - `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`). - `maxAgeMs`: idade máxima do cache em milissegundos (padrão: `172800000` / 2 dias). - - `timeoutSeconds`: tempo limite da solicitação de scrape em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (busca web Grok). - - `enabled`: habilita o provedor X Search. - - `model`: modelo Grok a usar para busca (por exemplo, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limiares. - - `enabled`: chave mestre de dreaming (padrão `false`). - - `frequency`: cadência cron para cada varredura completa de dreaming (`"0 3 * * *"` por padrão). - - `model`: substituição opcional de modelo do subagente Dream Diary. Requer `plugins.entries.memory-core.subagent.allowModelOverride: true`; combine com `allowedModels` para restringir destinos. Erros de modelo indisponível tentam novamente uma vez com o modelo padrão da sessão; falhas de confiança ou allowlist não fazem fallback silenciosamente. - - política de fases e limiares são detalhes de implementação (não chaves de configuração voltadas ao usuário). + - `timeoutSeconds`: timeout da solicitação de raspagem em segundos (padrão: `60`). +- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (pesquisa web Grok). + - `enabled`: ativa o provedor X Search. + - `model`: modelo Grok a usar para pesquisa (por exemplo, `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: configurações de Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. + - `enabled`: alternância principal de Dreaming (padrão `false`). + - `frequency`: cadência Cron para cada varredura completa de Dreaming (`"0 3 * * *"` por padrão). + - `model`: substituição opcional de modelo de subagente Dream Diary. Exige `plugins.entries.memory-core.subagent.allowModelOverride: true`; combine com `allowedModels` para restringir destinos. Erros de modelo indisponível tentam novamente uma vez com o modelo padrão da sessão; falhas de confiança ou allowlist não fazem fallback silenciosamente. + - política de fases e limites são detalhes de implementação (não chaves de configuração voltadas ao usuário). - A configuração completa de memória fica em [Referência de configuração de memória](/pt-BR/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugins de bundle Claude habilitados também podem contribuir padrões incorporados do Pi a partir de `settings.json`; o OpenClaw aplica isso como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. -- `plugins.slots.memory`: escolha o id do Plugin de memória ativo, ou `"none"` para desativar Plugins de memória. -- `plugins.slots.contextEngine`: escolha o id do Plugin de mecanismo de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo. +- Plugins de pacote Claude ativados também podem contribuir padrões incorporados do Pi a partir de `settings.json`; o OpenClaw aplica esses valores como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. +- `plugins.slots.memory`: escolhe o id do Plugin de memória ativo, ou `"none"` para desativar Plugins de memória. +- `plugins.slots.contextEngine`: escolhe o id do Plugin de mecanismo de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo. Consulte [Plugins](/pt-BR/tools/plugin). @@ -232,10 +237,10 @@ Consulte [Plugins](/pt-BR/tools/plugin). ## Compromissos -`commitments` controla memória de acompanhamento inferida: o OpenClaw pode detectar check-ins a partir de turnos de conversa e entregá-los por execuções de heartbeat. +`commitments` controla memória inferida de acompanhamento: o OpenClaw pode detectar check-ins a partir de turnos de conversa e entregá-los por meio de execuções de Heartbeat. -- `commitments.enabled`: habilita extração LLM oculta, armazenamento e entrega por heartbeat para compromissos de acompanhamento inferidos. Padrão: `false`. -- `commitments.maxPerDay`: máximo de compromissos de acompanhamento inferidos entregues por sessão de agente em um dia contínuo. Padrão: `3`. +- `commitments.enabled`: ativa extração LLM oculta, armazenamento e entrega por Heartbeat de compromissos de acompanhamento inferidos. Padrão: `false`. +- `commitments.maxPerDay`: número máximo de compromissos de acompanhamento inferidos entregues por sessão de agente em um dia móvel. Padrão: `3`. Consulte [Compromissos inferidos](/pt-BR/concepts/commitments). @@ -291,50 +296,50 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments). - `tabCleanup` recupera abas rastreadas do agente principal após tempo ocioso ou quando uma sessão excede seu limite. Defina `idleMinutes: 0` ou `maxTabsPerSession: 0` para desativar esses modos individuais de limpeza. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, então a navegação do navegador permanece restrita por padrão. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, então a navegação do navegador permanece estrita por padrão. - Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` somente quando você confiar intencionalmente na navegação do navegador em rede privada. -- No modo restrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de acessibilidade/descoberta. +- No modo estrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) ficam sujeitos ao mesmo bloqueio de rede privada durante verificações de acessibilidade/descoberta. - `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. -- No modo restrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. +- No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. - Perfis remotos são somente anexação (iniciar/parar/redefinir desativados). - `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`. Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S) - quando seu provedor fornecer uma URL WebSocket direta do DevTools. + quando seu provedor fornecer uma URL direta de DevTools WebSocket. - `remoteCdpTimeoutMs` e `remoteCdpHandshakeTimeoutMs` se aplicam à acessibilidade CDP remota e - `attachOnly`, além de solicitações de abertura de abas. Perfis local loopback - gerenciados mantêm os padrões locais de CDP. + `attachOnly`, além de solicitações de abertura de abas. Perfis gerenciados por loopback + mantêm os padrões locais de CDP. - Se um serviço CDP gerenciado externamente estiver acessível por loopback, defina - `attachOnly: true` nesse perfil; caso contrário, o OpenClaw trata a porta loopback como um + `attachOnly: true` nesse perfil; caso contrário, o OpenClaw trata a porta de loopback como um perfil de navegador local gerenciado e pode relatar erros de propriedade de porta local. -- Perfis `existing-session` usam Chrome MCP em vez de CDP e podem se anexar no +- Perfis `existing-session` usam Chrome MCP em vez de CDP e podem anexar no host selecionado ou por meio de um nó de navegador conectado. -- Perfis `existing-session` podem definir `userDataDir` para apontar para um perfil +- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil específico de navegador baseado em Chromium, como Brave ou Edge. - Perfis `existing-session` mantêm os limites atuais da rota Chrome MCP: - ações orientadas por snapshot/ref em vez de segmentação por seletor CSS, hooks de upload - de arquivo único, sem substituições de tempo limite de diálogo, sem `wait --load networkidle` e sem - `responsebody`, exportação PDF, interceptação de download ou ações em lote. -- Perfis `openclaw` locais gerenciados atribuem automaticamente `cdpPort` e `cdpUrl`; defina + ações orientadas por snapshot/ref em vez de direcionamento por seletor CSS, hooks de upload + de um arquivo, sem substituições de tempo limite de diálogo, sem `wait --load networkidle` e sem + `responsebody`, exportação de PDF, interceptação de downloads ou ações em lote. +- Perfis `openclaw` gerenciados localmente atribuem automaticamente `cdpPort` e `cdpUrl`; defina `cdpUrl` explicitamente somente para CDP remoto. -- Perfis locais gerenciados podem definir `executablePath` para substituir o - `browser.executablePath` global desse perfil. Use isso para executar um perfil no +- Perfis gerenciados localmente podem definir `executablePath` para substituir o + `browser.executablePath` global para esse perfil. Use isso para executar um perfil no Chrome e outro no Brave. -- Perfis locais gerenciados usam `browser.localLaunchTimeoutMs` para descoberta HTTP do Chrome CDP - após o início do processo e `browser.localCdpReadyTimeoutMs` para +- Perfis gerenciados localmente usam `browser.localLaunchTimeoutMs` para descoberta HTTP + CDP do Chrome após o início do processo e `browser.localCdpReadyTimeoutMs` para prontidão do websocket CDP pós-inicialização. Aumente-os em hosts mais lentos nos quais o Chrome inicia com sucesso, mas as verificações de prontidão disputam com a inicialização. Ambos os valores devem ser inteiros positivos até `120000` ms; valores de configuração inválidos são rejeitados. - Ordem de detecção automática: navegador padrão se baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` e `browser.profiles..executablePath` aceitam `~` e `~/...` para o diretório inicial do seu SO antes da inicialização do Chromium. - `userDataDir` por perfil em perfis `existing-session` também passa por expansão de til. + `userDataDir` por perfil em perfis `existing-session` também tem til expandidos. - Serviço de controle: somente loopback (porta derivada de `gateway.port`, padrão `18791`). -- `extraArgs` acrescenta flags extras de inicialização ao startup local do Chromium (por exemplo +- `extraArgs` acrescenta flags extras de inicialização à inicialização local do Chromium (por exemplo `--disable-gpu`, dimensionamento de janela ou flags de depuração). --- -## Interface de usuário +## UI ```json5 { @@ -348,8 +353,8 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments). } ``` -- `seamColor`: cor de destaque para a moldura da interface do usuário do app nativo (matiz do balão do Modo de conversa etc.). -- `assistant`: substituição da identidade da Interface de controle. Usa como fallback a identidade do agente ativo. +- `seamColor`: cor de destaque para o chrome da UI do app nativo (tom do balão do Talk Mode etc.). +- `assistant`: substituição de identidade da Control UI. Recua para a identidade do agente ativo. --- @@ -427,52 +432,53 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments). -- `mode`: `local` (executar o Gateway) ou `remote` (conectar-se ao Gateway remoto). O Gateway se recusa a iniciar a menos que seja `local`. +- `mode`: `local` (executar Gateway) ou `remote` (conectar a um Gateway remoto). O Gateway se recusa a iniciar a menos que seja `local`. - `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (somente IP do Tailscale) ou `custom`. -- **Aliases legados de bind**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o Gateway fica inacessível. Use `--network host` ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. -- **Auth**: exigida por padrão. Binds que não são loopback exigem autenticação do Gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade usando `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. -- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Os fluxos de inicialização e de instalação/reparo de serviço falham quando ambos estão configurados e o modo não foi definido. -- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações confiáveis de local loopback; isso não é oferecido intencionalmente pelos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega a autenticação do navegador/usuário a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não loopback** por padrão; proxies reversos de loopback no mesmo host exigem `gateway.auth.trustedProxy.allowLoopback = true` explicitamente. Chamadores internos no mesmo host podem usar `gateway.auth.password` como fallback direto local; `gateway.auth.token` permanece mutuamente exclusivo com o modo trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da UI de Controle/WebSocket (verificada via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação de cabeçalho do Tailscale; em vez disso, seguem o modo normal de autenticação HTTP do Gateway. Esse fluxo sem token assume que o host do Gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. +- **Aliases de bind legados**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Observação sobre Docker**: o bind `loopback` padrão escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o Gateway fica inacessível. Use `--network host`, ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. +- **Autenticação**: obrigatória por padrão. Binds que não sejam loopback exigem autenticação do Gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. +- Se tanto `gateway.auth.token` quanto `gateway.auth.password` estiverem configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Fluxos de inicialização e de instalação/reparo de serviço falham quando ambos estão configurados e o modo não está definido. +- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use somente para configurações confiáveis de local loopback; isso é intencionalmente não oferecido pelos prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega a autenticação de navegador/usuário a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não loopback** por padrão; proxies reversos loopback no mesmo host exigem `gateway.auth.trustedProxy.allowLoopback = true` explícito. Chamadores internos no mesmo host podem usar `gateway.auth.password` como fallback direto local; `gateway.auth.token` permanece mutuamente exclusivo com o modo trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificada via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; em vez disso, seguem o modo normal de autenticação HTTP do Gateway. Esse fluxo sem token pressupõe que o host do Gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. - `gateway.auth.rateLimit`: limitador opcional de falhas de autenticação. Aplica-se por IP de cliente e por escopo de autenticação (shared-secret e device-token são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. - - No caminho assíncrono da UI de Controle do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Tentativas incorretas simultâneas do mesmo cliente podem, portanto, acionar o limitador na segunda solicitação, em vez de ambas passarem em corrida como simples incompatibilidades. - - `gateway.auth.rateLimit.exemptLoopback` tem `true` como padrão; defina `false` quando você quiser intencionalmente limitar também o tráfego de localhost (para configurações de teste ou implantações estritas de proxy). -- Tentativas de autenticação WS com origem em navegador são sempre limitadas, com isenção de loopback desativada (defesa em profundidade contra força bruta em localhost baseada em navegador). -- Em loopback, esses bloqueios com origem em navegador são isolados por valor - normalizado de `Origin`, então falhas repetidas de uma origem localhost não - bloqueiam automaticamente uma origem diferente. -- `tailscale.mode`: `serve` (somente tailnet, bind de loopback) ou `funnel` (público, exige autenticação). -- `controlUi.allowedOrigins`: allowlist explícita de origens de navegador para conexões WebSocket do Gateway. Exigida quando clientes de navegador são esperados de origens não loopback. -- `controlUi.chatMessageMaxWidth`: largura máxima opcional para mensagens de chat agrupadas da UI de Controle. Aceita valores de largura CSS restritos, como `960px`, `82%`, `min(1280px, 82%)` e `calc(100% - 2rem)`. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente de política de origem por cabeçalho Host. + - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Portanto, tentativas inválidas simultâneas do mesmo cliente podem acionar o limitador na segunda solicitação, em vez de ambas passarem como simples incompatibilidades. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando você quiser intencionalmente que o tráfego localhost também tenha limite de taxa (para configurações de teste ou implantações de proxy estritas). +- Tentativas de autenticação WS com origem em navegador sempre são limitadas, com isenção de loopback desabilitada (defesa em profundidade contra força bruta de localhost baseada em navegador). +- Em loopback, esses bloqueios com origem em navegador são isolados por valor de `Origin` + normalizado, então falhas repetidas de uma origem localhost não bloqueiam automaticamente + uma origem diferente. +- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, exige autenticação). +- `controlUi.allowedOrigins`: allowlist explícita de origens de navegador para conexões WebSocket do Gateway. Obrigatória quando clientes de navegador são esperados de origens que não sejam loopback. +- `controlUi.chatMessageMaxWidth`: largura máxima opcional para mensagens de chat agrupadas da Control UI. Aceita valores de largura CSS restritos, como `960px`, `82%`, `min(1280px, 82%)` e `calc(100% - 2rem)`. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente da política de origem por cabeçalho Host. - `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição de emergência no ambiente do processo - do lado do cliente que permite `ws://` em texto claro para IPs confiáveis de rede privada; - o padrão continua sendo somente loopback para texto claro. Não há equivalente em - `openclaw.json`, e configurações de rede privada do navegador, como - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, não afetam clientes WebSocket do Gateway. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição emergencial do ambiente de processo + no lado do cliente que permite `ws://` em texto puro para IPs confiáveis de rede privada; + o padrão permanece somente loopback para texto puro. Não há equivalente em `openclaw.json`, + e configurações de rede privada do navegador, como + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, não afetam clientes WebSocket + do Gateway. - `gateway.remote.token` / `.password` são campos de credenciais de cliente remoto. Eles não configuram a autenticação do Gateway por si só. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay externo de APNs usado por builds oficiais/TestFlight de iOS depois que publicam registros apoiados por relay no Gateway. Essa URL deve corresponder à URL do relay compilada no build de iOS. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds iOS oficiais/TestFlight depois que elas publicam registros com suporte a relay no Gateway. Essa URL deve corresponder à URL do relay compilada na build iOS. - `gateway.push.apns.relay.timeoutMs`: timeout de envio do Gateway para o relay em milissegundos. O padrão é `10000`. -- Registros apoiados por relay são delegados a uma identidade específica do Gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha ao Gateway uma concessão de envio com escopo de registro. Outro Gateway não pode reutilizar esse registro armazenado. +- Registros com suporte a relay são delegados a uma identidade específica do Gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha ao Gateway uma concessão de envio com escopo de registro. Outro Gateway não pode reutilizar esse registro armazenado. - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias de env para a configuração de relay acima. - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch somente para desenvolvimento para URLs de relay HTTP em loopback. URLs de relay de produção devem permanecer em HTTPS. -- `gateway.handshakeTimeoutMs`: timeout de handshake WebSocket do Gateway antes da autenticação, em milissegundos. Padrão: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` tem precedência quando definido. Aumente isso em hosts carregados ou de baixa potência onde clientes locais conseguem conectar enquanto o aquecimento de inicialização ainda está estabilizando. -- `gateway.channelHealthCheckMinutes`: intervalo do monitor de integridade de canais em minutos. Defina `0` para desativar reinicializações do monitor de integridade globalmente. Padrão: `5`. +- `gateway.handshakeTimeoutMs`: timeout do handshake WebSocket pré-autenticação do Gateway em milissegundos. Padrão: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` tem precedência quando definido. Aumente isso em hosts carregados ou de baixa potência onde clientes locais conseguem conectar enquanto o aquecimento da inicialização ainda está estabilizando. +- `gateway.channelHealthCheckMinutes`: intervalo do monitor de integridade de canais em minutos. Defina `0` para desabilitar reinicializações do monitor de integridade globalmente. Padrão: `5`. - `gateway.channelStaleEventThresholdMinutes`: limite de socket obsoleto em minutos. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. - `gateway.channelMaxRestartsPerHour`: máximo de reinicializações do monitor de integridade por canal/conta em uma hora móvel. Padrão: `10`. - `channels..healthMonitor.enabled`: opt-out por canal para reinicializações do monitor de integridade, mantendo o monitor global habilitado. -- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definida, tem precedência sobre a substituição no nível do canal. -- Caminhos de chamadas do Gateway local podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não estiver definido. -- Se `gateway.auth.token` / `gateway.auth.password` for configurado explicitamente via SecretRef e não for resolvido, a resolução falha de forma fechada (sem mascaramento por fallback remoto). -- `trustedProxies`: IPs de proxy reverso que encerram TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies que você controla. Entradas de loopback ainda são válidas para configurações de proxy/detecção local no mesmo host (por exemplo, Tailscale Serve ou um proxy reverso local), mas elas **não** tornam solicitações de loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. +- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais multi-conta. Quando definido, tem precedência sobre a substituição em nível de canal. +- Caminhos de chamada do Gateway local podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não estiver definido. +- Se `gateway.auth.token` / `gateway.auth.password` for configurado explicitamente via SecretRef e não resolvido, a resolução falha fechada (sem mascaramento por fallback remoto). +- `trustedProxies`: IPs de proxy reverso que terminam TLS ou injetam cabeçalhos de cliente encaminhado. Liste somente proxies que você controla. Entradas loopback ainda são válidas para configurações de proxy/detecção local no mesmo host (por exemplo, Tailscale Serve ou um proxy reverso local), mas elas **não** tornam solicitações loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: quando `true`, o Gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: allowlist CIDR/IP opcional para aprovar automaticamente o pareamento inicial de dispositivo de Node sem escopos solicitados. Fica desativada quando não definida. Isso não aprova automaticamente o pareamento de operador/navegador/UI de Controle/WebChat, e não aprova automaticamente upgrades de função, escopo, metadados ou chave pública. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: modelagem global de allow/deny para comandos de Node declarados após o pareamento e a avaliação da allowlist da plataforma. Use `allowCommands` para optar por comandos de Node perigosos, como `camera.snap`, `camera.clip` e `screen.record`; `denyCommands` remove um comando mesmo que um padrão da plataforma ou uma permissão explícita o incluísse de outra forma. Depois que um Node altera sua lista de comandos declarados, rejeite e aprove novamente esse pareamento de dispositivo para que o Gateway armazene o snapshot de comandos atualizado. -- `gateway.tools.deny`: nomes extras de ferramentas bloqueadas para HTTP `POST /tools/invoke` (estende a lista deny padrão). +- `gateway.nodes.pairing.autoApproveCidrs`: allowlist opcional de CIDR/IP para aprovar automaticamente o pareamento inicial de dispositivo de Node sem escopos solicitados. Fica desabilitada quando não definida. Isso não aprova automaticamente pareamento de operador/navegador/Control UI/WebChat, e não aprova automaticamente upgrades de função, escopo, metadados ou chave pública. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: modelagem global de allow/deny para comandos de Node declarados após pareamento e avaliação da allowlist da plataforma. Use `allowCommands` para optar por comandos perigosos de Node, como `camera.snap`, `camera.clip` e `screen.record`; `denyCommands` remove um comando mesmo que um padrão da plataforma ou allow explícito o incluísse de outra forma. Depois que um Node altera sua lista de comandos declarados, rejeite e reaprove o pareamento desse dispositivo para que o Gateway armazene o snapshot de comandos atualizado. +- `gateway.tools.deny`: nomes de ferramentas extras bloqueados para HTTP `POST /tools/invoke` (estende a lista deny padrão). - `gateway.tools.allow`: remove nomes de ferramentas da lista deny HTTP padrão. @@ -481,16 +487,16 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments). - Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Endurecimento de entrada por URL de Responses: +- Endurecimento de entrada por URL em Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Allowlists vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` - e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desativar a busca por URL. -- Cabeçalho opcional de endurecimento de resposta: - - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS que você controla; veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar a busca de URLs. +- Cabeçalho opcional de endurecimento da resposta: + - `gateway.http.securityHeaders.strictTransportSecurity` (defina somente para origens HTTPS que você controla; consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento de várias instâncias +### Isolamento multi-instância Execute vários Gateways em um host com portas e diretórios de estado únicos: @@ -502,7 +508,7 @@ openclaw gateway --port 19001 Flags de conveniência: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). -Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways). +Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways). ### `gateway.tls` @@ -520,11 +526,11 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways). } ``` -- `enabled`: habilita terminação TLS no listener do Gateway (HTTPS/WSS) (padrão: `false`). -- `autoGenerate`: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; somente para uso local/dev. +- `enabled`: habilita a terminação TLS no listener do Gateway (HTTPS/WSS) (padrão: `false`). +- `autoGenerate`: gera automaticamente um par de cert/key local autoassinado quando arquivos explícitos não estão configurados; somente para uso local/dev. - `certPath`: caminho do sistema de arquivos para o arquivo de certificado TLS. - `keyPath`: caminho do sistema de arquivos para o arquivo de chave privada TLS; mantenha permissões restritas. -- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. +- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança customizadas. ### `gateway.reload` @@ -540,17 +546,17 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways). } ``` -- `mode`: controla como edições de configuração são aplicadas em tempo de execução. +- `mode`: controla como edições de configuração são aplicadas em runtime. - `"off"`: ignora edições ao vivo; alterações exigem uma reinicialização explícita. - `"restart"`: sempre reinicia o processo do Gateway em alterações de configuração. - - `"hot"`: aplica alterações dentro do processo sem reiniciar. - - `"hybrid"` (padrão): tenta hot reload primeiro; recorre a reinicialização se necessário. -- `debounceMs`: janela de debounce em ms antes de as alterações de configuração serem aplicadas (inteiro não negativo). -- `deferralTimeoutMs`: tempo máximo opcional em ms para aguardar operações em andamento antes de forçar uma reinicialização. Omita para usar a espera limitada padrão (`300000`); defina `0` para aguardar indefinidamente e registrar avisos periódicos de ainda pendente. + - `"hot"`: aplica alterações no processo sem reiniciar. + - `"hybrid"` (padrão): tenta hot reload primeiro; recorre à reinicialização se necessário. +- `debounceMs`: janela de debounce em ms antes que alterações de configuração sejam aplicadas (inteiro não negativo). +- `deferralTimeoutMs`: tempo máximo opcional em ms para aguardar operações em andamento antes de forçar uma reinicialização. Omita para usar a espera limitada padrão (`300000`); defina `0` para aguardar indefinidamente e registrar avisos periódicos de pendências ainda existentes. --- -## Hooks +## Ganchos ```json5 { @@ -584,15 +590,15 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways). ``` Autenticação: `Authorization: Bearer ` ou `x-openclaw-token: `. -Tokens de hook na string de consulta são rejeitados. +Tokens de hook em string de consulta são rejeitados. Notas de validação e segurança: - `hooks.enabled=true` exige um `hooks.token` não vazio. -- `hooks.token` deve ser **distinto** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. +- `hooks.token` deve ser **diferente** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. - `hooks.path` não pode ser `/`; use um subcaminho dedicado, como `/hooks`. - Se `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por exemplo, `["hook:"]`). -- Se um mapeamento ou preset usa um `sessionKey` com template, defina `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Chaves de mapeamento estáticas não exigem essa opção explícita. +- Se um mapeamento ou preset usar um `sessionKey` com template, defina `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Chaves de mapeamento estáticas não exigem essa adesão explícita. **Pontos de extremidade:** @@ -602,20 +608,20 @@ Notas de validação e segurança: - `POST /hooks/` → resolvido via `hooks.mappings` - Valores de `sessionKey` de mapeamento renderizados por template são tratados como fornecidos externamente e também exigem `hooks.allowRequestSessionKey=true`. - + - `match.path` corresponde ao subcaminho após `/hooks` (por exemplo, `/hooks/gmail` → `gmail`). - `match.source` corresponde a um campo do payload para caminhos genéricos. - Templates como `{{messages[0].subject}}` leem do payload. - `transform` pode apontar para um módulo JS/TS que retorna uma ação de hook. - `transform.module` deve ser um caminho relativo e permanece dentro de `hooks.transformsDir` (caminhos absolutos e travessia são rejeitados). - - Mantenha `hooks.transformsDir` em `~/.openclaw/hooks/transforms`; diretórios de Skills do workspace são rejeitados. Se `openclaw doctor` relatar esse caminho como inválido, mova o módulo de transformação para o diretório de transforms de hooks ou remova `hooks.transformsDir`. -- `agentId` roteia para um agente específico; IDs desconhecidos retornam ao padrão. + - Mantenha `hooks.transformsDir` em `~/.openclaw/hooks/transforms`; diretórios de Skills do workspace são rejeitados. Se `openclaw doctor` relatar esse caminho como inválido, mova o módulo de transformação para o diretório de transformações de hooks ou remova `hooks.transformsDir`. +- `agentId` roteia para um agente específico; IDs desconhecidos voltam para o padrão. - `allowedAgentIds`: restringe o roteamento explícito (`*` ou omitido = permitir todos, `[]` = negar todos). - `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente de hook sem `sessionKey` explícito. -- `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` e chaves de sessão de mapeamento baseadas em template definam `sessionKey` (padrão: `false`). -- `allowedSessionKeyPrefixes`: lista opcional de prefixos permitidos para valores explícitos de `sessionKey` (solicitação + mapeamento), por exemplo, `["hook:"]`. Ela se torna obrigatória quando qualquer mapeamento ou preset usa um `sessionKey` com template. -- `deliver: true` envia a resposta final para um canal; `channel` usa `last` por padrão. +- `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` e chaves de sessão de mapeamento orientadas por template definam `sessionKey` (padrão: `false`). +- `allowedSessionKeyPrefixes`: lista de permissões opcional de prefixos para valores explícitos de `sessionKey` (solicitação + mapeamento), por exemplo `["hook:"]`. Ela se torna obrigatória quando qualquer mapeamento ou preset usa um `sessionKey` com template. +- `deliver: true` envia a resposta final para um canal; `channel` usa `last` como padrão. - `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido). @@ -623,8 +629,8 @@ Notas de validação e segurança: ### Integração com Gmail - O preset integrado do Gmail usa `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Se você mantiver esse roteamento por mensagem, defina `hooks.allowRequestSessionKey: true` e restrinja `hooks.allowedSessionKeyPrefixes` para corresponder ao namespace do Gmail, por exemplo, `["hook:", "hook:gmail:"]`. -- Se precisar de `hooks.allowRequestSessionKey: false`, substitua o preset por um `sessionKey` estático em vez do padrão com template. +- Se você mantiver esse roteamento por mensagem, defina `hooks.allowRequestSessionKey: true` e restrinja `hooks.allowedSessionKeyPrefixes` para corresponder ao namespace do Gmail, por exemplo `["hook:", "hook:gmail:"]`. +- Se você precisar de `hooks.allowRequestSessionKey: false`, substitua o preset por um `sessionKey` estático em vez do padrão com template. ```json5 { @@ -652,7 +658,7 @@ Notas de validação e segurança: --- -## Host de canvas +## Host do canvas ```json5 { @@ -664,12 +670,12 @@ Notas de validação e segurança: } ``` -- Serve HTML/CSS/JS editáveis por agentes e A2UI via HTTP sob a porta do Gateway: +- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP na porta do Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Somente local: mantenha `gateway.bind: "loopback"` (padrão). -- Binds sem loopback: rotas de canvas exigem autenticação do Gateway (token/senha/proxy confiável), igual a outras superfícies HTTP do Gateway. -- WebViews do Node normalmente não enviam cabeçalhos de autenticação; depois que um nó é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo do nó para acesso a canvas/A2UI. +- Vínculos que não são loopback: rotas de canvas exigem autenticação do Gateway (token/senha/proxy confiável), igual a outras superfícies HTTP do Gateway. +- WebViews de Node normalmente não enviam cabeçalhos de autenticação; depois que um nó é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo de nó para acesso ao canvas/A2UI. - URLs de capacidade são vinculadas à sessão WS ativa do nó e expiram rapidamente. Fallback baseado em IP não é usado. - Injeta cliente de recarregamento ao vivo no HTML servido. - Cria automaticamente um `index.html` inicial quando vazio. @@ -693,11 +699,11 @@ Notas de validação e segurança: } ``` -- `minimal` (padrão quando o Plugin `bonjour` integrado está habilitado): omite `cliPath` + `sshPort` dos registros TXT. -- `full`: inclui `cliPath` + `sshPort`; a publicidade multicast em LAN ainda exige que o Plugin `bonjour` integrado esteja habilitado. -- `off`: suprime a publicidade multicast em LAN sem alterar a habilitação do Plugin. -- O Plugin `bonjour` integrado inicia automaticamente em hosts macOS e é opcional em implantações do Gateway em Linux, Windows e containers. -- O hostname usa por padrão o hostname do sistema quando ele é um rótulo DNS válido, com fallback para `openclaw`. Substitua com `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (padrão quando o Plugin `bonjour` empacotado está habilitado): omite `cliPath` + `sshPort` dos registros TXT. +- `full`: inclui `cliPath` + `sshPort`; a divulgação multicast em LAN ainda exige que o Plugin `bonjour` empacotado esteja habilitado. +- `off`: suprime a divulgação multicast em LAN sem alterar a habilitação do Plugin. +- O Plugin `bonjour` empacotado inicia automaticamente em hosts macOS e é opcional no Linux, Windows e em implantações de Gateway em contêiner. +- O nome do host usa como padrão o nome de host do sistema quando ele é um rótulo DNS válido, recorrendo a `openclaw` caso contrário. Substitua com `OPENCLAW_MDNS_HOSTNAME`. ### Área ampla (DNS-SD) @@ -734,8 +740,8 @@ Configuração: `openclaw dns setup --apply`. } ``` -- Variáveis de ambiente inline são aplicadas somente se a variável de ambiente do processo não tiver a chave. -- Arquivos `.env`: `.env` no CWD + `~/.openclaw/.env` (nenhum deles substitui variáveis existentes). +- Variáveis de ambiente inline só são aplicadas se a variável de ambiente do processo não tiver a chave. +- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes). - `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login. - Consulte [Ambiente](/pt-BR/help/environment) para a precedência completa. @@ -751,8 +757,8 @@ Referencie variáveis de ambiente em qualquer string de configuração com `${VA } ``` -- Somente nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*`. -- Variáveis ausentes/vazias geram um erro ao carregar a configuração. +- Apenas nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*`. +- Variáveis ausentes/vazias geram um erro no carregamento da configuração. - Escape com `$${VAR}` para um `${VAR}` literal. - Funciona com `$include`. @@ -760,7 +766,7 @@ Referencie variáveis de ambiente em qualquer string de configuração com `${VA ## Segredos -Referências de segredo são aditivas: valores em texto simples ainda funcionam. +Refs de segredo são aditivas: valores em texto claro ainda funcionam. ### `SecretRef` @@ -772,19 +778,19 @@ Use um formato de objeto: Validação: -- Padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- Padrão de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- id para `source: "file"`: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`) -- Padrão de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- ids de `source: "exec"` não devem conter segmentos de caminho delimitados por barras `.` ou `..` (por exemplo, `a/../b` é rejeitado) +- padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- padrão de id de `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id de `source: "file"`: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`) +- padrão de id de `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- ids de `source: "exec"` não podem conter segmentos de caminho delimitados por barras `.` ou `..` (por exemplo, `a/../b` é rejeitado) ### Superfície de credenciais compatível -- Matriz canônica: [Superfície de Credenciais SecretRef](/pt-BR/reference/secretref-credential-surface) -- `secrets apply` direciona caminhos de credenciais compatíveis em `openclaw.json`. -- Referências de `auth-profiles.json` são incluídas na resolução em tempo de execução e na cobertura de auditoria. +- Matriz canônica: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface) +- `secrets apply` mira caminhos de credenciais compatíveis em `openclaw.json`. +- Refs de `auth-profiles.json` são incluídas na resolução em tempo de execução e na cobertura de auditoria. -### Configuração de provedores de segredos +### Configuração de provedores de segredo ```json5 { @@ -814,14 +820,14 @@ Validação: Observações: -- O provedor `file` oferece suporte a `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). -- Caminhos dos provedores file e exec falham em modo fechado quando a verificação de ACL do Windows não está disponível. Defina `allowInsecurePath: true` somente para caminhos confiáveis que não possam ser verificados. +- O provedor `file` é compatível com `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). +- Caminhos de provedores file e exec falham fechados quando a verificação de ACL do Windows não está disponível. Defina `allowInsecurePath: true` apenas para caminhos confiáveis que não podem ser verificados. - O provedor `exec` exige um caminho absoluto de `command` e usa payloads de protocolo em stdin/stdout. -- Por padrão, caminhos de comando por symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos por symlink enquanto valida o caminho de destino resolvido. +- Por padrão, caminhos de comando com symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos com symlink enquanto valida o caminho de destino resolvido. - Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho de destino resolvido. -- O ambiente filho de `exec` é mínimo por padrão; passe variáveis necessárias explicitamente com `passEnv`. -- Referências de segredo são resolvidas no momento da ativação em um snapshot em memória; depois, os caminhos de solicitação leem somente o snapshot. -- A filtragem de superfície ativa se aplica durante a ativação: referências não resolvidas em superfícies habilitadas fazem a inicialização/recarga falhar, enquanto superfícies inativas são ignoradas com diagnósticos. +- O ambiente filho de `exec` é mínimo por padrão; passe as variáveis necessárias explicitamente com `passEnv`. +- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória; depois, os caminhos de requisição leem apenas o snapshot. +- A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/recarregamento falhar, enquanto superfícies inativas são ignoradas com diagnósticos. --- @@ -844,13 +850,13 @@ Observações: ``` - Perfis por agente são armazenados em `/auth-profiles.json`. -- `auth-profiles.json` oferece suporte a referências no nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciais estáticas. -- Mapas simples legados de `auth-profiles.json`, como `{ "provider": { "apiKey": "..." } }`, não são um formato de tempo de execução; `openclaw doctor --fix` os reescreve para perfis canônicos de chave de API `provider:default` com um backup `.legacy-flat.*.bak`. -- Perfis no modo OAuth (`auth.profiles..mode = "oauth"`) não oferecem suporte a credenciais de perfil de autenticação baseadas em SecretRef. -- Credenciais estáticas de tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando descobertas. +- `auth-profiles.json` é compatível com refs em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. +- Mapas planos legados de `auth-profiles.json`, como `{ "provider": { "apiKey": "..." } }`, não são um formato de tempo de execução; `openclaw doctor --fix` os reescreve para perfis de chave de API canônicos `provider:default` com um backup `.legacy-flat.*.bak`. +- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não são compatíveis com credenciais de perfil de autenticação baseadas em SecretRef. +- Credenciais estáticas em tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando descobertas. - Importações OAuth legadas vêm de `~/.openclaw/credentials/oauth.json`. - Consulte [OAuth](/pt-BR/concepts/oauth). -- Comportamento em tempo de execução de segredos e ferramentas `audit/configure/apply`: [Gerenciamento de Segredos](/pt-BR/gateway/secrets). +- Comportamento de segredos em tempo de execução e ferramentas `audit/configure/apply`: [Gerenciamento de segredos](/pt-BR/gateway/secrets). ### `auth.cooldowns` @@ -872,19 +878,19 @@ Observações: } ``` -- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a erros reais de cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode chegar aqui mesmo em respostas `401`/`403`, mas os correspondentes de texto específicos de provedor permanecem restritos ao provedor que os possui (por exemplo, OpenRouter `Key limit exceeded`). Mensagens retentáveis de HTTP `402` de janela de uso ou limite de gastos de organização/workspace permanecem no caminho `rate_limit`. -- `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de cobrança. -- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de cobrança (padrão: `24`). +- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a erros reais de faturamento/crédito insuficiente (padrão: `5`). Texto explícito de faturamento ainda pode cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto específicas do provedor permanecem limitadas ao provedor que as possui (por exemplo, OpenRouter `Key limit exceeded`). Mensagens HTTP `402` repetíveis de janela de uso ou limite de gastos de organização/workspace permanecem no caminho `rate_limit`. +- `billingBackoffHoursByProvider`: substituições opcionais por provedor para as horas de backoff de faturamento. +- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de faturamento (padrão: `24`). - `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`). -- `authPermanentMaxMinutes`: limite em minutos para o crescimento do backoff de `auth_permanent` (padrão: `60`). +- `authPermanentMaxMinutes`: limite em minutos para o crescimento do backoff `auth_permanent` (padrão: `60`). - `failureWindowHours`: janela móvel em horas usada para contadores de backoff (padrão: `24`). -- `overloadedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de sobrecarga antes de alternar para o fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, chegam aqui. -- `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`). -- `rateLimitedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de limite de taxa antes de alternar para o fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui textos no formato do provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `overloadedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de sobrecarga antes de alternar para o fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, caem aqui. +- `overloadedBackoffMs`: atraso fixo antes de repetir uma rotação de provedor/perfil sobrecarregado (padrão: `0`). +- `rateLimitedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de limite de taxa antes de alternar para o fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto no formato do provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- -## Registro em log +## Registro em logs ```json5 { @@ -902,8 +908,8 @@ Observações: - Arquivo de log padrão: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Defina `logging.file` para um caminho estável. - `consoleLevel` sobe para `debug` quando `--verbose`. -- `maxFileBytes`: tamanho máximo do arquivo de log ativo em bytes antes da rotação (inteiro positivo; padrão: `104857600` = 100 MB). O OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo. -- `redactSensitive` / `redactPatterns`: mascaramento de melhor esforço para saída do console, logs de arquivo, registros de log OTLP e texto persistido de transcrição da sessão. `redactSensitive: "off"` desativa apenas essa política geral de log/transcrição; superfícies de segurança de UI/ferramenta/diagnóstico ainda redigem segredos antes da emissão. +- `maxFileBytes`: tamanho máximo do arquivo de log ativo em bytes antes da rotação (inteiro positivo; padrão: `104857600` = 100 MB). OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo. +- `redactSensitive` / `redactPatterns`: mascaramento de melhor esforço para saída do console, logs de arquivo, registros de log OTLP e texto persistido de transcrição de sessão. `redactSensitive: "off"` desativa apenas esta política geral de logs/transcrições; superfícies de segurança de UI/ferramentas/diagnóstico ainda redigem segredos antes da emissão. --- @@ -952,22 +958,22 @@ Observações: ``` - `enabled`: alternância principal para saída de instrumentação (padrão: `true`). -- `flags`: array de strings de flags que habilitam saída de log direcionada (aceita curingas como `"telegram.*"` ou `"*"`). -- `stuckSessionWarnMs`: limite de idade sem progresso em ms para classificar sessões de processamento de longa duração como `session.long_running`, `session.stalled` ou `session.stuck`. Resposta, ferramenta, status, bloco e progresso de ACP reiniciam o temporizador; diagnósticos `session.stuck` repetidos recuam enquanto não houver alterações. -- `otel.enabled`: habilita o pipeline de exportação do OpenTelemetry (padrão: `false`). Para a configuração completa, catálogo de sinais e modelo de privacidade, consulte [exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry). +- `flags`: array de strings de flags que ativam saída de log direcionada (aceita curingas como `"telegram.*"` ou `"*"`). +- `stuckSessionWarnMs`: limite de idade sem progresso em ms para classificar sessões de processamento de longa duração como `session.long_running`, `session.stalled` ou `session.stuck`. Resposta, ferramenta, status, bloco e progresso ACP reiniciam o temporizador; diagnósticos `session.stuck` repetidos recuam enquanto não houver mudanças. +- `otel.enabled`: ativa o pipeline de exportação OpenTelemetry (padrão: `false`). Para a configuração completa, o catálogo de sinais e o modelo de privacidade, consulte [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry). - `otel.endpoint`: URL do coletor para exportação OTel. - `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: endpoints OTLP opcionais específicos por sinal. Quando definidos, substituem `otel.endpoint` apenas para esse sinal. - `otel.protocol`: `"http/protobuf"` (padrão) ou `"grpc"`. - `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com solicitações de exportação OTel. - `otel.serviceName`: nome do serviço para atributos de recurso. -- `otel.traces` / `otel.metrics` / `otel.logs`: habilitam exportação de traces, métricas ou logs. -- `otel.sampleRate`: taxa de amostragem de trace `0`–`1`. +- `otel.traces` / `otel.metrics` / `otel.logs`: ativa exportação de traces, métricas ou logs. +- `otel.sampleRate`: taxa de amostragem de traces de `0` a `1`. - `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms. -- `otel.captureContent`: captura opcional de conteúdo bruto para atributos de span OTEL. O padrão é desativado. O booleano `true` captura conteúdo de mensagem/ferramenta que não seja do sistema; o formato de objeto permite habilitar `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` e `systemPrompt` explicitamente. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: alternância de ambiente para os atributos experimentais mais recentes de provedor de span GenAI. Por padrão, spans mantêm o atributo legado `gen_ai.system` para compatibilidade; métricas GenAI usam atributos semânticos limitados. -- `OPENCLAW_OTEL_PRELOADED=1`: alternância de ambiente para hosts que já registraram um SDK global do OpenTelemetry. Então o OpenClaw ignora a inicialização/desligamento do SDK pertencente ao Plugin, mantendo os listeners de diagnóstico ativos. +- `otel.captureContent`: captura opcional explícita de conteúdo bruto para atributos de spans OTEL. O padrão é desativado. O booleano `true` captura conteúdo não sistêmico de mensagens/ferramentas; a forma de objeto permite ativar `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` e `systemPrompt` explicitamente. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: alternância de ambiente para os atributos experimentais mais recentes de provedor de spans GenAI. Por padrão, spans mantêm o atributo legado `gen_ai.system` para compatibilidade; métricas GenAI usam atributos semânticos limitados. +- `OPENCLAW_OTEL_PRELOADED=1`: alternância de ambiente para hosts que já registraram um SDK OpenTelemetry global. O OpenClaw então ignora a inicialização/desligamento do SDK pertencente ao Plugin, mantendo os listeners de diagnóstico ativos. - `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` e `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: variáveis de ambiente de endpoint específicas por sinal usadas quando a chave de configuração correspondente não está definida. -- `cacheTrace.enabled`: registra snapshots de trace de cache para execuções embutidas (padrão: `false`). +- `cacheTrace.enabled`: registra snapshots de trace de cache para execuções incorporadas (padrão: `false`). - `cacheTrace.filePath`: caminho de saída para JSONL de trace de cache (padrão: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de trace de cache (todos padrão: `true`). @@ -991,12 +997,12 @@ Observações: } ``` -- `channel`: canal de lançamento para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. -- `checkOnStart`: verifica atualizações npm quando o gateway inicia (padrão: `true`). -- `auto.enabled`: habilita atualização automática em segundo plano para instalações de pacote (padrão: `false`). +- `channel`: canal de release para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. +- `checkOnStart`: verifica atualizações do npm quando o gateway inicia (padrão: `true`). +- `auto.enabled`: ativa atualização automática em segundo plano para instalações de pacote (padrão: `false`). - `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máx.: `168`). -- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máx.: `168`). -- `auto.betaCheckIntervalHours`: frequência em horas das verificações do canal beta (padrão: `1`; máx.: `24`). +- `auto.stableJitterHours`: janela extra em horas para espalhamento de rollout no canal estável (padrão: `12`; máx.: `168`). +- `auto.betaCheckIntervalHours`: frequência, em horas, das verificações do canal beta (padrão: `1`; máx.: `24`). --- @@ -1029,23 +1035,23 @@ Observações: } ``` -- `enabled`: gate global do recurso ACP (padrão: `true`; defina `false` para ocultar envio ACP e affordances de spawn). -- `dispatch.enabled`: gate independente para envio de turnos de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. +- `enabled`: gate global do recurso ACP (padrão: `true`; defina como `false` para ocultar dispatch ACP e affordances de spawn). +- `dispatch.enabled`: gate independente para dispatch de turnos de sessão ACP (padrão: `true`). Defina como `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. - `backend`: id padrão do backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado). - Instale primeiro o Plugin de backend e, se `plugins.allow` estiver definido, inclua o id do Plugin de backend (por exemplo, `acpx`) ou o backend ACP não será carregado. -- `defaultAgent`: id do agente de destino ACP de fallback quando spawns não especificam um destino explícito. -- `allowedAgents`: lista de permissões de ids de agentes permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. + Instale o Plugin de backend primeiro e, se `plugins.allow` estiver definido, inclua o id do Plugin de backend (por exemplo, `acpx`) ou o backend ACP não será carregado. +- `defaultAgent`: id do agente ACP de fallback quando spawns não especificam um destino explícito. +- `allowedAgents`: allowlist de ids de agentes permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. - `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente. -- `stream.coalesceIdleMs`: janela de flush ociosa em ms para texto transmitido. -- `stream.maxChunkChars`: tamanho máximo do chunk antes de dividir a projeção de bloco transmitida. +- `stream.coalesceIdleMs`: janela de flush ocioso em ms para texto transmitido por stream. +- `stream.maxChunkChars`: tamanho máximo de chunk antes de dividir a projeção do bloco transmitido por stream. - `stream.repeatSuppression`: suprime linhas repetidas de status/ferramenta por turno (padrão: `true`). - `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` armazena em buffer até eventos terminais do turno. -- `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`). +- `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos de ferramenta ocultos (padrão: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de saída do assistente projetados por turno ACP. -- `stream.maxSessionUpdateChars`: máximo de caracteres para linhas projetadas de status/atualização ACP. -- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos. -- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de serem elegíveis para limpeza. -- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP. +- `stream.maxSessionUpdateChars`: máximo de caracteres para linhas de status/atualização ACP projetadas. +- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos por stream. +- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de se tornarem elegíveis para limpeza. +- `runtime.installCommand`: comando de instalação opcional a executar ao inicializar um ambiente de runtime ACP. --- @@ -1064,14 +1070,14 @@ Observações: - `cli.banner.taglineMode` controla o estilo da tagline do banner: - `"random"` (padrão): taglines engraçadas/sazonais rotativas. - `"default"`: tagline neutra fixa (`All your chats, one OpenClaw.`). - - `"off"`: sem texto de tagline (título/versão do banner ainda são exibidos). + - `"off"`: sem texto de tagline (título/versão do banner ainda exibidos). - Para ocultar o banner inteiro (não apenas as taglines), defina a env `OPENCLAW_HIDE_BANNER=1`. --- ## Assistente -Metadados gravados por fluxos de configuração guiada da CLI (`onboard`, `configure`, `doctor`): +Metadados escritos por fluxos de configuração guiada da CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -1089,15 +1095,15 @@ Metadados gravados por fluxos de configuração guiada da CLI (`onboard`, `confi ## Identidade -Consulte os campos de identidade de `agents.list` em [Padrões de agente](/pt-BR/gateway/config-agents#agent-defaults). +Consulte os campos de identidade `agents.list` em [Padrões de agente](/pt-BR/gateway/config-agents#agent-defaults). --- -## Bridge (legado, removido) +## Ponte (legada, removida) -As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. As chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até que sejam removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). +As builds atuais não incluem mais a ponte TCP. Nodes se conectam pelo WebSocket do Gateway. Chaves `bridge.*` não fazem mais parte do esquema de configuração (a validação falha até serem removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). - + ```json { @@ -1135,11 +1141,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições cron arquivadas e excluídas. Padrão: `24h`; defina `false` para desativar. +- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções Cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas de Cron excluídas. Padrão: `24h`; defina como `false` para desativar. - `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da remoção. Padrão: `2_000_000` bytes. -- `runLog.keepLines`: linhas mais recentes retidas quando a remoção de logs de execução é acionada. Padrão: `2000`. -- `webhookToken`: token bearer usado para entrega POST de webhook cron (`delivery.mode = "webhook"`), se omitido nenhum cabeçalho de autenticação é enviado. -- `webhook`: URL legada de fallback de Webhook (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. +- `runLog.keepLines`: linhas mais recentes retidas quando a remoção do log de execução é acionada. Padrão: `2000`. +- `webhookToken`: token bearer usado para entrega POST do Webhook do Cron (`delivery.mode = "webhook"`), se omitido nenhum cabeçalho de auth será enviado. +- `webhook`: URL legada obsoleta de Webhook de fallback (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. ### `cron.retry` @@ -1155,11 +1161,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `maxAttempts`: máximo de novas tentativas para tarefas de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`). -- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de repetição (padrão: `[30000, 60000, 300000]`; 1–10 entradas). -- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para repetir todos os tipos transitórios. +- `maxAttempts`: máximo de novas tentativas para trabalhos de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`). +- `backoffMs`: array de atrasos de recuo em ms para cada tentativa de repetição (padrão: `[30000, 60000, 300000]`; 1–10 entradas). +- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente todos os tipos transitórios. -Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam tratamento de falhas separado. +Aplica-se somente a trabalhos Cron de execução única. Trabalhos recorrentes usam tratamento de falhas separado. ### `cron.failureAlert` @@ -1178,12 +1184,12 @@ Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam } ``` -- `enabled`: habilita alertas de falha para tarefas Cron (padrão: `false`). +- `enabled`: habilita alertas de falha para trabalhos Cron (padrão: `false`). - `after`: falhas consecutivas antes de um alerta ser disparado (inteiro positivo, mín.: `1`). -- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para a mesma tarefa (inteiro não negativo). -- `includeSkipped`: contabiliza execuções ignoradas consecutivas para o limite de alerta (padrão: `false`). Execuções ignoradas são rastreadas separadamente e não afetam o backoff de erros de execução. -- `mode`: modo de entrega — `"announce"` envia por meio de uma mensagem de canal; `"webhook"` publica no Webhook configurado. -- `accountId`: ID opcional de conta ou canal para delimitar a entrega de alertas. +- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para o mesmo trabalho (inteiro não negativo). +- `includeSkipped`: conta execuções ignoradas consecutivas para o limite de alerta (padrão: `false`). Execuções ignoradas são rastreadas separadamente e não afetam o recuo de erros de execução. +- `mode`: modo de entrega — `"announce"` envia por uma mensagem de canal; `"webhook"` publica no Webhook configurado. +- `accountId`: conta ou ID de canal opcional para limitar o escopo da entrega do alerta. ### `cron.failureDestination` @@ -1200,22 +1206,22 @@ Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam } ``` -- Destino padrão para notificações de falha do Cron em todas as tarefas. +- Destino padrão para notificações de falha de Cron em todos os trabalhos. - `mode`: `"announce"` ou `"webhook"`; usa `"announce"` como padrão quando existem dados de destino suficientes. - `channel`: substituição de canal para entrega por anúncio. `"last"` reutiliza o último canal de entrega conhecido. -- `to`: destino de anúncio explícito ou URL de Webhook. Obrigatório no modo Webhook. +- `to`: destino explícito de anúncio ou URL de Webhook. Obrigatório para o modo Webhook. - `accountId`: substituição opcional de conta para entrega. -- `delivery.failureDestination` por tarefa substitui esse padrão global. -- Quando nem o destino de falha global nem o por tarefa está definido, tarefas que já entregam via `announce` recorrem a esse destino principal de anúncio em caso de falha. -- `delivery.failureDestination` só é compatível com tarefas `sessionTarget="isolated"`, a menos que o `delivery.mode` principal da tarefa seja `"webhook"`. +- `delivery.failureDestination` por trabalho substitui esse padrão global. +- Quando nenhum destino de falha global ou por trabalho está definido, trabalhos que já entregam via `announce` usam esse destino principal de anúncio como fallback em caso de falha. +- `delivery.failureDestination` só é compatível com trabalhos `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do trabalho seja `"webhook"`. -Veja [Tarefas Cron](/pt-BR/automation/cron-jobs). Execuções Cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). +Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs). Execuções Cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). --- -## Variáveis de modelo para template de mídia +## Variáveis de modelo de mídia -Espaços reservados de modelo expandidos em `tools.media.models[].args`: +Placeholders de modelo expandidos em `tools.media.models[].args`: | Variável | Descrição | | ------------------ | ------------------------------------------------- | @@ -1223,26 +1229,26 @@ Espaços reservados de modelo expandidos em `tools.media.models[].args`: | `{{RawBody}}` | Corpo bruto (sem wrappers de histórico/remetente) | | `{{BodyStripped}}` | Corpo com menções de grupo removidas | | `{{From}}` | Identificador do remetente | -| `{{To}}` | Identificador do destino | +| `{{To}}` | Identificador de destino | | `{{MessageSid}}` | ID da mensagem do canal | | `{{SessionId}}` | UUID da sessão atual | | `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | | `{{MediaUrl}}` | Pseudo-URL da mídia recebida | | `{{MediaPath}}` | Caminho local da mídia | | `{{MediaType}}` | Tipo de mídia (imagem/áudio/documento/…) | -| `{{Transcript}}` | Transcrição do áudio | +| `{{Transcript}}` | Transcrição de áudio | | `{{Prompt}}` | Prompt de mídia resolvido para entradas da CLI | -| `{{MaxChars}}` | Máximo resolvido de caracteres de saída para entradas da CLI | +| `{{MaxChars}}` | Máximo de caracteres de saída resolvido para entradas da CLI | | `{{ChatType}}` | `"direct"` ou `"group"` | | `{{GroupSubject}}` | Assunto do grupo (melhor esforço) | | `{{GroupMembers}}` | Prévia dos membros do grupo (melhor esforço) | | `{{SenderName}}` | Nome de exibição do remetente (melhor esforço) | | `{{SenderE164}}` | Número de telefone do remetente (melhor esforço) | -| `{{Provider}}` | Dica de provedor (whatsapp, telegram, discord, etc.) | +| `{{Provider}}` | Dica do provedor (whatsapp, telegram, discord, etc.) | --- -## Inclusões de configuração (`$include`) +## Includes de configuração (`$include`) Divida a configuração em vários arquivos: @@ -1260,17 +1266,17 @@ Divida a configuração em vários arquivos: **Comportamento de mesclagem:** - Arquivo único: substitui o objeto que o contém. -- Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores). -- Chaves irmãs: mescladas após as inclusões (substituem valores incluídos). -- Inclusões aninhadas: até 10 níveis de profundidade. -- Caminhos: resolvidos em relação ao arquivo que faz a inclusão, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda resolvem dentro desse limite. -- Gravações de propriedade do OpenClaw que alteram apenas uma seção de nível superior apoiada por uma inclusão de arquivo único gravam nesse arquivo incluído. Por exemplo, `plugins install` atualiza `plugins: { $include: "./plugins.json5" }` em `plugins.json5` e deixa `openclaw.json` intacto. -- Inclusões raiz, arrays de inclusão e inclusões com substituições por chaves irmãs são somente leitura para gravações de propriedade do OpenClaw; essas gravações falham de forma fechada em vez de achatar a configuração. -- Erros: mensagens claras para arquivos ausentes, erros de análise e inclusões circulares. +- Array de arquivos: mesclados profundamente em ordem (posteriores substituem anteriores). +- Chaves irmãs: mescladas após includes (substituem valores incluídos). +- Includes aninhados: até 10 níveis de profundidade. +- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas somente quando ainda resolvem dentro desse limite. +- Escritas de propriedade do OpenClaw que alteram apenas uma seção de nível superior respaldada por um include de arquivo único escrevem nesse arquivo incluído. Por exemplo, `plugins install` atualiza `plugins: { $include: "./plugins.json5" }` em `plugins.json5` e deixa `openclaw.json` intacto. +- Includes raiz, arrays de include e includes com substituições irmãs são somente leitura para escritas de propriedade do OpenClaw; essas escritas falham de forma fechada em vez de achatar a configuração. +- Erros: mensagens claras para arquivos ausentes, erros de análise e includes circulares. --- -_Relacionado: [Configuração](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ +_Relacionado: [Configuração](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Diagnóstico](/pt-BR/gateway/doctor)_ ## Relacionado diff --git a/docs/pt-BR/gateway/diagnostics.md b/docs/pt-BR/gateway/diagnostics.md index 75f4b7f7d..a4ba622c9 100644 --- a/docs/pt-BR/gateway/diagnostics.md +++ b/docs/pt-BR/gateway/diagnostics.md @@ -1,26 +1,26 @@ --- read_when: - - Preparando um relatório de bug ou solicitação de suporte - - Depuração de falhas, reinicializações, pressão de memória ou cargas úteis excessivamente grandes do Gateway - - Revisando quais dados de diagnóstico são registrados ou ocultados -summary: Criar pacotes de diagnóstico do Gateway compartilháveis para relatórios de bugs + - Preparando um relatório de bug ou uma solicitação de suporte + - Depuração de falhas do Gateway, reinicializações, pressão de memória ou cargas úteis superdimensionadas + - Analisando quais dados de diagnóstico são registrados ou ocultados +summary: Crie pacotes de diagnóstico do Gateway compartilháveis para relatórios de bugs title: Exportação de diagnósticos x-i18n: - generated_at: "2026-05-03T21:32:00Z" + generated_at: "2026-05-05T01:46:16Z" model: gpt-5.5 provider: openai - source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b + source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382 source_path: gateway/diagnostics.md workflow: 16 --- O OpenClaw pode criar um zip de diagnósticos local para relatórios de bugs. Ele combina -status, integridade, logs, formato de configuração e eventos recentes de estabilidade -sem payload do Gateway, com sanitização. +status, integridade, logs, formato da configuração e eventos recentes de estabilidade +sem payload do Gateway, todos sanitizados. -Trate pacotes de diagnósticos como segredos até revisá-los. Eles são -projetados para omitir ou redigir payloads e credenciais, mas ainda resumem -logs locais do Gateway e estado de runtime no nível do host. +Trate pacotes de diagnósticos como segredos até revisá-los. Eles são projetados +para omitir ou redigir payloads e credenciais, mas ainda resumem logs locais do +Gateway e o estado de runtime no nível do host. ## Início rápido @@ -42,94 +42,101 @@ openclaw gateway diagnostics export --json ## Comando de chat -Proprietários podem usar `/diagnostics [note]` no chat para solicitar uma exportação local do Gateway. -Use isso quando o bug aconteceu em uma conversa real e você quiser um relatório -copiável e colável para suporte: +Proprietários podem usar `/diagnostics [note]` no chat para solicitar uma exportação +local do Gateway. Use isso quando o bug aconteceu em uma conversa real e você quiser +um relatório copiável para o suporte: 1. Envie `/diagnostics` na conversa em que você percebeu o problema. Adicione uma - nota curta se ajudar, por exemplo `/diagnostics bad tool choice`. -2. O OpenClaw envia o preâmbulo de diagnósticos e pede uma aprovação explícita de exec. - A aprovação executa `openclaw gateway diagnostics export --json`. + observação curta se ajudar, por exemplo `/diagnostics bad tool choice`. +2. O OpenClaw envia o preâmbulo de diagnósticos e pede uma aprovação explícita + de exec. A aprovação executa `openclaw gateway diagnostics export --json`. Não aprove diagnósticos por meio de uma regra allow-all. 3. Após a aprovação, o OpenClaw responde com um relatório colável contendo o caminho - do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes. + do pacote local, o resumo do manifesto, observações de privacidade e ids de sessão relevantes. Em chats em grupo, um proprietário ainda pode executar `/diagnostics`, mas o OpenClaw não publica os detalhes de diagnóstico de volta no chat compartilhado. Ele envia o preâmbulo, -prompts de aprovação, resultado da exportação do Gateway e detalhamento de sessão/thread do Codex +os prompts de aprovação, o resultado da exportação do Gateway e a divisão de sessão/thread do Codex ao proprietário pela rota privada de aprovação. O grupo recebe apenas um aviso curto -de que o fluxo de diagnósticos foi enviado em particular. Se o OpenClaw não conseguir encontrar uma rota privada -para o proprietário, o comando falha de forma fechada e pede que o proprietário o execute a partir de uma DM. +de que o fluxo de diagnósticos foi enviado em particular. Se o OpenClaw não conseguir encontrar uma rota +privada para o proprietário, o comando falha de forma fechada e pede que o proprietário o execute por DM. Quando a sessão ativa do OpenClaw está usando o harness nativo do OpenAI Codex, -a mesma aprovação de exec também cobre um upload de feedback do OpenAI para as threads de runtime -do Codex que o OpenClaw conhece. Esse upload é separado do zip local do -Gateway e aparece apenas para sessões do harness do Codex. Antes da aprovação, o +a mesma aprovação de exec também cobre um upload de feedback para a OpenAI referente às threads +de runtime do Codex que o OpenClaw conhece. Esse upload é separado do zip local +do Gateway e aparece apenas para sessões do harness Codex. Antes da aprovação, o prompt explica que aprovar diagnósticos também enviará feedback do Codex, mas ele -não lista ids de sessão ou thread do Codex. Após a aprovação, a resposta do chat lista +não lista ids de sessão ou thread do Codex. Após a aprovação, a resposta no chat lista os canais, ids de sessão do OpenClaw, ids de thread do Codex e comandos locais de retomada para as threads que foram enviadas aos servidores da OpenAI. Se você negar ou ignorar a aprovação, o OpenClaw não executa a exportação, não envia feedback do Codex e não imprime os ids do Codex. -Isso torna curto o loop comum de depuração do Codex: perceba o mau comportamento no +Isso torna curto o loop comum de depuração do Codex: perceba o comportamento ruim no Telegram, Discord ou outro canal, execute `/diagnostics`, aprove uma vez, compartilhe -o relatório com o suporte e então execute localmente o comando `codex resume ` impresso -se quiser inspecionar você mesmo a thread nativa do Codex. Consulte -[Harness do Codex](/pt-BR/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) para +o relatório com o suporte e então execute localmente o comando `codex resume ` +impresso se quiser inspecionar você mesmo a thread nativa do Codex. Consulte +[harness Codex](/pt-BR/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) para esse fluxo de inspeção. ## O que a exportação contém O zip inclui: -- `summary.md`: visão geral legível por humanos para suporte. +- `summary.md`: visão geral legível por humanos para o suporte. - `diagnostics.json`: resumo legível por máquina de configuração, logs, status, integridade e dados de estabilidade. - `manifest.json`: metadados de exportação e lista de arquivos. -- Formato de configuração sanitizado e detalhes de configuração não secretos. +- Formato da configuração sanitizado e detalhes de configuração não secretos. - Resumos de logs sanitizados e linhas recentes de log redigidas. -- Snapshots de status e integridade do Gateway por melhor esforço. +- Snapshots de status e integridade do Gateway em melhor esforço. - `stability/latest.json`: pacote de estabilidade persistido mais recente, quando disponível. A exportação é útil mesmo quando o Gateway não está íntegro. Se o Gateway não conseguir -responder a solicitações de status ou integridade, os logs locais, o formato de configuração e o pacote de -estabilidade mais recente ainda serão coletados quando disponíveis. +responder a solicitações de status ou integridade, os logs locais, o formato da configuração e o pacote +de estabilidade mais recente ainda serão coletados quando disponíveis. ## Modelo de privacidade -Diagnósticos são projetados para serem compartilháveis. A exportação mantém dados operacionais +Os diagnósticos são projetados para serem compartilháveis. A exportação mantém dados operacionais que ajudam na depuração, como: -- nomes de subsistemas, ids de Plugin, ids de provedores, ids de canais e modos configurados -- códigos de status, durações, contagens de bytes, estado de fila e leituras de memória +- nomes de subsistemas, ids de plugins, ids de provedores, ids de canais e modos configurados +- códigos de status, durações, contagens de bytes, estado da fila e leituras de memória - metadados de log sanitizados e mensagens operacionais redigidas -- formato de configuração e configurações de recursos não secretas +- formato da configuração e configurações de recursos não secretas A exportação omite ou redige: -- texto de chat, prompts, instruções, corpos de Webhook e saídas de ferramentas +- texto de chat, prompts, instruções, corpos de webhook e saídas de ferramentas - credenciais, chaves de API, tokens, cookies e valores secretos - corpos brutos de solicitação ou resposta - ids de conta, ids de mensagem, ids brutos de sessão, nomes de host e nomes de usuário locais -Quando uma mensagem de log parece texto de usuário, chat, prompt ou payload de ferramenta, a -exportação mantém apenas o fato de que uma mensagem foi omitida e a contagem de bytes. +Quando uma mensagem de log parece texto de payload de usuário, chat, prompt ou ferramenta, a +exportação mantém apenas que uma mensagem foi omitida e a contagem de bytes. ## Gravador de estabilidade O Gateway registra por padrão um fluxo de estabilidade limitado e sem payload quando -diagnósticos estão habilitados. Ele é para fatos operacionais, não para conteúdo. +os diagnósticos estão habilitados. Ele é para fatos operacionais, não conteúdo. -O mesmo Heartbeat de diagnóstico registra amostras de vivacidade quando o Gateway continua -em execução, mas o loop de eventos do Node.js ou a CPU parece saturado. Esses eventos +O mesmo heartbeat de diagnóstico registra amostras de atividade quando o Gateway continua +em execução, mas o loop de eventos do Node.js ou a CPU parecem saturados. Esses eventos `diagnostic.liveness.warning` incluem atraso do loop de eventos, utilização do loop de eventos, -proporção de núcleos de CPU e contagens de sessões ativas/em espera/enfileiradas. Amostras ociosas -permanecem na telemetria no nível `info`. Amostras de vivacidade se tornam avisos do Gateway -apenas quando há trabalho em espera ou enfileirado, ou quando trabalho ativo se sobrepõe a -atraso sustentado do loop de eventos. Picos transitórios de atraso máximo durante trabalho em segundo plano -saudável permanecem nos logs de debug. Eles não reiniciam o Gateway por -si só. +proporção de núcleos de CPU, contagens de sessões ativas/em espera/enfileiradas, a fase atual +de inicialização/runtime quando conhecida, spans de fases recentes e rótulos limitados de trabalho +ativo/enfileirado. Amostras ociosas permanecem na telemetria no nível `info`. Amostras de atividade +se tornam avisos do Gateway apenas quando há trabalho aguardando ou enfileirado, ou quando trabalho ativo +se sobrepõe a atraso sustentado do loop de eventos. Picos transitórios de atraso máximo durante +trabalho em segundo plano saudável permanecem nos logs de debug. Eles não reiniciam o +Gateway por si só. + +As fases de inicialização também emitem eventos `diagnostic.phase.completed` com tempo de relógio de parede e +tempo de CPU. Diagnósticos de execução incorporada travados marcam `terminalProgressStale=true` +quando o último progresso da ponte parecia terminal, como um item bruto de resposta ou +evento de conclusão de resposta, mas o Gateway ainda considera a execução incorporada +ativa. Inspecione o gravador ao vivo: @@ -140,7 +147,7 @@ openclaw gateway stability --json ``` Inspecione o pacote de estabilidade persistido mais recente após uma saída fatal, timeout de desligamento -ou falha de inicialização após reinício: +ou falha de inicialização por reinício: ```bash openclaw gateway stability --bundle latest @@ -169,13 +176,13 @@ openclaw gateway diagnostics export \ - `--url `: URL WebSocket do Gateway para snapshots de status e integridade. - `--token `: token do Gateway para snapshots de status e integridade. - `--password `: senha do Gateway para snapshots de status e integridade. -- `--timeout `: timeout de snapshot de status e integridade. +- `--timeout `: timeout de snapshots de status e integridade. - `--no-stability-bundle`: ignora a busca por pacote de estabilidade persistido. - `--json`: imprime metadados de exportação legíveis por máquina. ## Desabilitar diagnósticos -Diagnósticos são habilitados por padrão. Para desabilitar o gravador de estabilidade e +Os diagnósticos são habilitados por padrão. Para desabilitar o gravador de estabilidade e a coleta de eventos de diagnóstico: ```json5 @@ -186,7 +193,7 @@ a coleta de eventos de diagnóstico: } ``` -Desabilitar diagnósticos reduz os detalhes do relatório de bugs. Isso não afeta o logging +Desabilitar diagnósticos reduz os detalhes do relatório de bug. Isso não afeta o registro normal do Gateway. ## Relacionado diff --git a/docs/pt-BR/gateway/doctor.md b/docs/pt-BR/gateway/doctor.md index 67fd03ed6..08f24fbad 100644 --- a/docs/pt-BR/gateway/doctor.md +++ b/docs/pt-BR/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Adicionando ou modificando migrações do doctor - - Introduzindo alterações de configuração incompatíveis + - Adição ou modificação de migrações de diagnóstico + - Introduzindo alterações incompatíveis na configuração sidebarTitle: Doctor summary: 'Comando doctor: verificações de integridade, migrações de configuração e etapas de reparo' title: Diagnóstico x-i18n: - generated_at: "2026-05-04T09:36:57Z" + generated_at: "2026-05-05T01:46:22Z" model: gpt-5.5 provider: openai - source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798 + source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis. +`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configuração/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis. ## Início rápido @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Aplica também reparos agressivos (sobrescreve configurações personalizadas de supervisor). + Também aplica reparos agressivos (sobrescreve configurações personalizadas do supervisor). @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - Verifica serviços do sistema em busca de instalações extras do gateway (launchd/systemd/schtasks). + Verifica serviços do sistema em busca de instalações extras do Gateway (launchd/systemd/schtasks). -Se quiser revisar as mudanças antes de gravar, abra o arquivo de configuração primeiro: +Se você quiser revisar as alterações antes de gravar, abra o arquivo de configuração primeiro: ```bash cat ~/.openclaw/openclaw.json @@ -76,106 +76,109 @@ cat ~/.openclaw/openclaw.json ## O que ele faz (resumo) - - - Atualização prévia opcional para instalações via git (somente interativo). - - Verificação de atualização do protocolo da UI (recompila a Control UI quando o schema do protocolo é mais recente). + + - Atualização opcional de pré-verificação para instalações via git (somente interativo). + - Verificação de atualização do protocolo da interface (recompila a Interface de Controle quando o esquema do protocolo é mais recente). - Verificação de integridade + prompt de reinicialização. - - Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de Plugin. + - Resumo de status de Skills (qualificadas/ausentes/bloqueadas) e status de plugins. - 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 do navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP. - - Avisos de substituição do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). + - Migração da configuração de Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.`. + - Verificações de migração do navegador para configurações legadas da extensão do Chrome e prontidão do MCP do Chrome. + - Avisos de sobrescrita do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Avisos de sombreamento do OAuth do Codex (`models.providers.openai-codex`). - - Verificação de pré-requisitos de TLS do OAuth para perfis OAuth do OpenAI Codex. - - Avisos de lista de permissões de plugins/ferramentas quando `plugins.allow` é restritiva, mas a política de ferramentas ainda pede curingas ou ferramentas pertencentes a plugins. - - Migração de estado legado em disco (sessions/agent dir/autenticação do WhatsApp). - - Migração de chaves legadas de contrato de manifesto de plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Migração de armazenamento Cron legado (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, tarefas simples de fallback de Webhook `notify: true`). - - Migração de política de runtime de agentes legada para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`. - - Limpeza de configuração obsoleta de Plugin quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como configuração inerte de contenção e são preservadas. + - Verificação de pré-requisitos de TLS do OAuth para perfis de OAuth do OpenAI Codex. + - Avisos de lista de permissões de Plugin/ferramenta quando `plugins.allow` é restritiva, mas a política de ferramentas ainda solicita curingas ou ferramentas pertencentes a plugins. + - Migração de estado legado em disco (sessões/diretório de agentes/autenticação do WhatsApp). + - Migração de chaves legadas de contrato do manifesto do plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Migração do armazenamento legado de Cron (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, jobs fallback simples de Webhook `notify: true`). + - Migração legada da política de runtime do agente para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`. + - Limpeza de configurações obsoletas de plugins quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de plugins são tratadas como configuração inerte de contenção e são preservadas. - Inspeção de arquivos de bloqueio de sessão e limpeza de bloqueios obsoletos. - - Reparo de transcrições de sessão para branches duplicados de reescrita de prompt criados por builds 2026.4.24 afetadas. - - Detecção de tombstone de recuperação de reinicialização de subagentes travados, com suporte a `--fix` para limpar flags obsoletas de recuperação abortada para que a inicialização não continue tratando o filho como abortado na reinicialização. + - Reparo de transcrições de sessão para branches duplicados de reescrita de prompt criados por builds 2026.4.24 afetados. + - Detecção de tombstone de recuperação por reinicialização de subagente travado, com suporte a `--fix` para limpar flags obsoletos de recuperação abortada, para que a inicialização não continue tratando o filho como abortado por reinicialização. - Verificações de integridade de estado e permissões (sessões, transcrições, diretório de estado). - - Verificações de permissões do arquivo de configuração (chmod 600) ao executar localmente. - - Integridade da autenticação de modelos: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e informa estados de cooldown/desabilitado de perfis de autenticação. + - Verificações de permissão do arquivo de configuração (chmod 600) ao executar localmente. + - Integridade de autenticação do modelo: verifica expiração do OAuth, pode atualizar tokens prestes a expirar e relata estados de cooldown/desabilitado de perfis de autenticação. - Detecção de diretório extra de workspace (`~/openclaw`). - - Reparo da imagem de sandbox quando o sandboxing está habilitado. - - Migração de serviço legado e detecção de gateways extras. + - Reparo de imagem de sandbox quando o sandboxing está habilitado. + - Migração de serviço legado e detecção de Gateways extras. - Migração de estado legado do canal Matrix (no modo `--fix` / `--repair`). - Verificações de runtime do Gateway (serviço instalado, mas não em execução; rótulo launchd em cache). - - Avisos de status de canais (sondados a partir do gateway em execução). - - Auditoria de configuração de supervisor (launchd/systemd/schtasks) com reparo opcional. - - Limpeza do ambiente de proxy embutido para serviços de Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização. + - Avisos de status de canal (sondados a partir do Gateway em execução). + - Auditoria de configuração do supervisor (launchd/systemd/schtasks) com reparo opcional. + - Limpeza do ambiente de proxy embutido para serviços do Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante instalação ou atualização. - Verificações de boas práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciadores de versão). - Diagnósticos de colisão de porta do Gateway (padrão `18789`). - - Avisos de segurança para políticas de DM abertas. - - Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando não existe fonte de token; não sobrescreve configurações de SecretRef de token). - - Detecção de problemas de pareamento de dispositivos (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, divergência obsoleta do cache local de token de dispositivo e divergência de autenticação de registro pareado). + - Avisos de segurança para políticas de DM aberto. + - Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando nenhuma fonte de token existe; não sobrescreve configurações de SecretRef de token). + - Detecção de problemas de pareamento de dispositivo (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, desvio de cache obsoleto de token de dispositivo local e desvio de autenticação de registros pareados). - Verificação de linger do systemd no Linux. - - Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/próximo do limite para arquivos de contexto). - - Verificação de prontidão de Skills para o agente padrão; informa skills permitidas com bins, env, configuração ou requisitos de SO ausentes, e `--fix` pode desabilitar skills indisponíveis em `skills.entries`. - - Verificação de status de conclusão do shell e instalação/upgrade automático. - - Verificação de prontidão do provedor de embeddings de busca de memória (modelo local, chave de API remota ou binário QMD). - - Verificações de instalação a partir do código-fonte (incompatibilidade do workspace pnpm, assets de UI ausentes, binário tsx ausente). + - Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/próximo ao limite para arquivos de contexto). + - Verificação de prontidão de Skills para o agente padrão; relata Skills permitidas com bins, env, config ou requisitos de SO ausentes, e `--fix` pode desabilitar Skills indisponíveis em `skills.entries`. + - Verificação de status de completação do shell e instalação/upgrade automáticos. + - Verificação de prontidão do provedor de embeddings da busca de memória (modelo local, chave de API remota ou binário QMD). + - Verificações de instalação a partir do código-fonte (incompatibilidade de workspace pnpm, assets de UI ausentes, binário tsx ausente). - Grava configuração atualizada + metadados do assistente. -## Backfill e reset da UI Dreams +## Backfill e redefinição da interface Dreams -A cena Dreams da Control UI inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de dreaming ancorado. Essas ações usam métodos RPC no estilo doctor do gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`. +A cena Dreams da Interface de Controle inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de Dreaming fundamentado. Essas ações usam métodos RPC no estilo do doctor do Gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`. O que elas fazem: -- **Backfill** verifica arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM ancorado e grava entradas reversíveis de backfill em `DREAMS.md`. +- **Backfill** verifica arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem do diário REM fundamentado e grava entradas reversíveis de backfill em `DREAMS.md`. - **Reset** remove apenas essas entradas marcadas de diário de backfill de `DREAMS.md`. -- **Clear Grounded** remove apenas entradas encenadas de curto prazo, somente ancoradas, que vieram de replay histórico e ainda não acumularam recordação ao vivo ou suporte diário. +- **Clear Grounded** remove apenas entradas de curto prazo preparadas e somente fundamentadas que vieram de replay histórico e ainda não acumularam recall ao vivo ou suporte diário. O que elas **não** fazem por si só: - elas não editam `MEMORY.md` - elas não executam migrações completas do doctor -- elas não encenam automaticamente candidatos ancorados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho encenado da CLI primeiro +- elas não preparam automaticamente candidatos fundamentados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho preparado da CLI primeiro -Se quiser que o replay histórico ancorado influencie a faixa normal de promoção profunda, use o fluxo da CLI em vez disso: +Se você quiser que o replay histórico fundamentado influencie a trilha normal de promoção profunda, use o fluxo da CLI em vez disso: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão. +Isso prepara candidatos duráveis fundamentados no armazenamento de Dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão. ## Comportamento detalhado e justificativa - Se este for um checkout git e o doctor estiver sendo executado de forma interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor. + Se este for um checkout do git e o doctor estiver em execução interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor. - Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição específica de canal), o doctor os normaliza para o schema atual. + Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma sobrescrita específica de canal), o doctor os normaliza para o esquema atual. - Isso inclui campos planos legados do Talk. A configuração pública atual do Talk é `talk.provider` + `talk.providers.`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` para o mapa de provedores. + Isso inclui campos planos legados de Talk. A configuração pública atual de Talk é `talk.provider` + `talk.providers.`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` no mapa de provedores. O doctor também avisa quando `plugins.allow` não está vazio e a política de ferramentas usa - curingas ou entradas de ferramentas pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas - de plugins que realmente carregam; ele não ignora a lista de permissões exclusiva de plugins. + entradas de ferramenta curingas ou pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas + de plugins que realmente carregam; ele não contorna a lista exclusiva de permissões de plugins. + O doctor grava `plugins.bundledDiscovery: "compat"` para configurações legadas migradas + de lista de permissões para preservar o comportamento existente de provedores empacotados e + então aponta para a configuração mais rígida `"allowlist"`. @@ -184,10 +187,10 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto O doctor irá: - Explicar quais chaves legadas foram encontradas. - - Mostrar a migração que ele aplicou. - - Reescrever `~/.openclaw/openclaw.json` com o schema atualizado. + - Mostrar a migração aplicada. + - Reescrever `~/.openclaw/openclaw.json` com o esquema atualizado. - O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações de armazenamento de tarefas Cron são tratadas por `openclaw doctor --fix`. + O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações do armazenamento de jobs de Cron são tratadas por `openclaw doctor --fix`. Migrações atuais: @@ -195,11 +198,12 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` + - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` - configurações de canais configurados sem política de resposta visível → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - `routing.bindings` → `bindings` de nível superior - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - - `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` legados → `talk.provider` + `talk.providers.` + - legado `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -213,70 +217,76 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Para canais com `accounts` nomeadas, mas valores de canal de nível superior de conta única remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente) + - Para canais com `accounts` nomeadas, mas com valores de canal de nível superior de conta única ainda remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - remova `agents.defaults.llm`; use `models.providers..timeoutSeconds` para tempos limite de provedores/modelos lentos + - remova `agents.defaults.llm`; use `models.providers..timeoutSeconds` para tempos limite lentos de provedor/modelo - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - remova `browser.relayBindHost` (configuração legada de retransmissão da extensão) - - `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como um valor enum futuro ou desconhecido, em vez de falhar fechado) + - legado `models.providers.*.api: "openai"` → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como um valor de enum futuro ou desconhecido, em vez de falhar de forma fechada) - Os avisos do doctor também incluem orientação de conta padrão para canais com várias contas: + Os avisos do Doctor também incluem orientação de conta padrão para canais com várias contas: - Se duas ou mais entradas `channels..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 por modelo + custos. - Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação do Chrome MCP local ao host: + Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação Chrome MCP local ao host: - `browser.profiles.*.driver: "extension"` se torna `"existing-session"` - `browser.relayBindHost` é removido - O doctor também audita o caminho do Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado: + O Doctor também audita o caminho Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado: - verifica se o Google Chrome está instalado no mesmo host para perfis padrão de conexão automática - - verifica a versão detectada do Chrome e avisa quando ela está abaixo do Chrome 144 - - lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`) + - verifica a versão detectada do Chrome e avisa quando ela é inferior ao Chrome 144 + - lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`) - O doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige: + O Doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige: - um navegador baseado em Chromium 144+ no host do gateway/node - o navegador em execução localmente - depuração remota habilitada nesse navegador - aprovação do primeiro prompt de consentimento de anexação no navegador - A prontidão aqui diz respeito apenas aos pré-requisitos de anexação local. `Existing-session` mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto. + A prontidão aqui se refere apenas aos pré-requisitos de anexação local. Existing-session mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou um perfil CDP bruto. - Esta verificação **não** se aplica a Docker, sandbox, navegador remoto ou outros fluxos headless. Eles continuam usando CDP bruto. + Esta verificação **não** se aplica a Docker, sandbox, remote-browser ou outros fluxos headless. Eles continuam usando CDP bruto. - - Quando um perfil OAuth do OpenAI Codex está configurado, o doctor consulta o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a consulta falhar com um erro de certificado (por exemplo, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientação de correção específica para a plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a consulta é executada mesmo se o gateway estiver saudável. + + Quando um perfil OAuth do OpenAI Codex está configurado, o doctor sonda o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a sondagem falhar com um erro de certificado (por exemplo `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientações de correção específicas da plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a sondagem é executada mesmo se o gateway estiver saudável. - - Se você adicionou anteriormente configurações legadas de transporte da OpenAI em `models.providers.openai-codex`, elas podem sombrear o caminho integrado do provedor OAuth do Codex que versões mais novas usam automaticamente. O doctor avisa quando vê essas configurações antigas de transporte junto com o OAuth do Codex para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam este aviso. + + Se você adicionou anteriormente configurações legadas de transporte OpenAI em `models.providers.openai-codex`, elas podem mascarar o caminho do provedor OAuth do Codex integrado que versões mais recentes usam automaticamente. O Doctor avisa quando detecta essas configurações antigas de transporte junto com Codex OAuth, para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições somente de cabeçalhos ainda são compatíveis e não acionam este aviso. - Quando o Plugin Codex incluído está habilitado, o doctor também verifica se referências de modelo primário `openai-codex/*` ainda são resolvidas pelo executor padrão do PI. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex pelo PI, mas é fácil confundi-la com o harness nativo do app-server do Codex. O doctor avisa e aponta para o formato explícito do app-server: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`. + Quando o Plugin Codex incluído está habilitado, o doctor também verifica se refs de modelo primário `openai-codex/*` ainda resolvem pelo executor PI padrão. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex por meio do PI, mas é fácil confundi-la com o harness nativo do servidor de aplicativo do Codex. O Doctor avisa e aponta para o formato explícito do servidor de aplicativo: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`. - O doctor não repara isso automaticamente porque ambas as rotas são válidas: + O Doctor não repara isso automaticamente porque ambas as rotas são válidas: - - `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo executor normal do OpenClaw." - - `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado pelo app-server nativo do Codex." - - `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex pelo chat." + - `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex por meio do executor normal do OpenClaw." + - `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado por meio do servidor de aplicativo nativo do Codex." + - `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex a partir do chat." - `/acp ...` ou `runtime: "acp"` significa "usar o adaptador externo ACP/acpx." - Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando o OAuth do Codex via PI for intencional. + Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando o PI Codex OAuth for intencional. + + + + O Doctor também verifica o armazenamento de sessões ativas em busca de estado de rota obsoleto criado automaticamente depois que você move o modelo ou runtime padrão/fallback configurado para longe de uma rota pertencente a um Plugin, como Codex. + + `openclaw doctor --fix` pode limpar estado obsoleto criado automaticamente, como pins de modelo `modelOverrideSource: "auto"`, metadados de modelo de runtime, IDs de harness fixados, vinculações de sessão da CLI e substituições automáticas de perfil de autenticação quando a rota proprietária deles não está mais configurada. Escolhas explícitas de usuário ou modelos de sessão legados são relatadas para revisão manual e deixadas intactas; troque-as com `/model ...`, `/new` ou redefina a sessão quando essa rota não for mais pretendida. - O doctor pode migrar layouts mais antigos em disco para a estrutura atual: + O Doctor pode migrar layouts em disco mais antigos para a estrutura atual: - Armazenamento de sessões + transcrições: - de `~/.openclaw/sessions/` para `~/.openclaw/agents//sessions/` @@ -286,14 +296,14 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto - de `~/.openclaw/credentials/*.json` legado (exceto `oauth.json`) - para `~/.openclaw/credentials/whatsapp//...` (ID da conta padrão: `default`) - Essas migrações são por melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento legado de sessões + diretório do agente na inicialização para que histórico/autenticação/modelos cheguem ao caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diferenças apenas na ordem das chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`. + Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento de sessões legado + diretório do agente na inicialização, para que histórico/autenticação/modelos entrem no caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de Talk agora compara por igualdade estrutural, portanto diferenças apenas na ordem das chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`. - - O doctor verifica todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada é removida sem duplicar os dados. + + 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 também verifica o armazenamento de trabalhos cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de trabalhos que o agendador ainda aceita por compatibilidade. + O Doctor também verifica o armazenamento de jobs Cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de job que o agendador ainda aceita por compatibilidade. As limpezas atuais de cron incluem: @@ -302,160 +312,160 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto - campos de payload de nível superior (`message`, `model`, `thinking`, ...) → `payload` - campos de entrega de nível superior (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - aliases de entrega `provider` do payload → `delivery.channel` explícito - - trabalhos simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook` + - jobs simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook` - O doctor só migra automaticamente trabalhos `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um trabalho combina fallback legado de notificação com um modo de entrega não webhook existente, o doctor avisa e deixa esse trabalho para revisão manual. + O Doctor só migra automaticamente jobs `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um job combinar fallback de notificação legado com um modo de entrega não webhook existente, o doctor avisa e deixa esse job para revisão manual. - No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o `~/.openclaw/bin/ensure-whatsapp.sh` legado. Esse script local ao host não é mantido pelo OpenClaw atual e pode gravar mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para verificações de integridade atuais. + No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o legado `~/.openclaw/bin/ensure-whatsapp.sh`. Esse script local do host não é mantido pelo OpenClaw atual e pode gravar mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para as verificações de integridade atuais. - - O doctor verifica cada diretório de sessão de agente em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele relata: o caminho, PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID inativo ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`. + + O Doctor verifica todos os diretórios de sessão de agentes em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele informa: o caminho, PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID morto ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`. - O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicada criado pelo bug de reescrita de transcrição de prompt de 2026.4.24: uma interação de usuário abandonada com contexto de runtime interno do OpenClaw mais uma ramificação irmã ativa contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais interações duplicadas. + O Doctor verifica arquivos JSONL de sessão de agentes em busca do formato de ramificação duplicada criado pelo bug de reescrita da transcrição de prompt de 2026.4.24: uma rodada abandonada do usuário com contexto de runtime interno do OpenClaw, além de uma ramificação irmã ativa contendo o mesmo prompt visível do usuário. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais rodadas duplicadas. - O diretório de estado é o tronco encefálico operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar). + O diretório de estado é o tronco cerebral operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar). - O doctor verifica: + O Doctor verifica: - - **Diretório de estado ausente**: alerta sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não consegue recuperar dados ausentes. - - **Permissões do diretório de estado**: verifica a permissão de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma incompatibilidade de proprietário/grupo é detectada). - - **Diretório de estado sincronizado com nuvem no macOS**: alerta quando o estado é resolvido sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização. - - **Diretório de estado em SD ou eMMC no Linux**: alerta quando o estado é resolvido para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rapidamente com escritas de sessão e credenciais. - - **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são necessários para persistir histórico e evitar falhas `ENOENT`. - - **Incompatibilidade de transcrição**: alerta quando entradas recentes de sessão têm arquivos de transcrição ausentes. - - **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está acumulando). - - **Múltiplos diretórios de estado**: alerta quando existem várias pastas `~/.openclaw` entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações). + - **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não pode recuperar dados ausentes. + - **Permissões do diretório de estado**: verifica a possibilidade de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma divergência de proprietário/grupo é detectada). + - **Diretório de estado sincronizado com nuvem no macOS**: avisa quando o estado resolve sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização. + - **Diretório de estado em SD ou eMMC no Linux**: avisa quando o estado resolve para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rapidamente com escritas de sessões e credenciais. + - **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são obrigatórios para persistir histórico e evitar falhas `ENOENT`. + - **Incompatibilidade de transcrição**: avisa quando entradas de sessão recentes têm arquivos de transcrição ausentes. + - **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está se acumulando). + - **Múltiplos diretórios de estado**: avisa quando múltiplas pastas `~/.openclaw` existem entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode ser dividido entre instalações). - **Lembrete de modo remoto**: se `gateway.mode=remote`, o doctor lembra você de executá-lo no host remoto (o estado fica lá). - - **Permissões do arquivo de configuração**: alerta se `~/.openclaw/openclaw.json` pode ser lido por grupo/todos e oferece restringir para `600`. + - **Permissões do arquivo de configuração**: avisa se `~/.openclaw/openclaw.json` é legível por grupo/mundo e oferece restringir para `600`. - - O doctor inspeciona perfis OAuth no armazenamento de autenticação, alerta quando tokens estão expirando/expirados e pode renová-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Solicitações de renovação só aparecem ao executar interativamente (TTY); `--non-interactive` ignora tentativas de renovação. + + O Doctor inspeciona perfis OAuth no armazenamento de autenticação, avisa quando tokens estão expirando/expirados e pode atualizá-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Prompts de atualização aparecem apenas ao executar interativamente (TTY); `--non-interactive` ignora tentativas de atualização. - Quando uma renovação OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado. + Quando uma atualização OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor solicitando que você entre novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado. - O doctor também relata perfis de autenticação temporariamente inutilizáveis devido a: + O Doctor também informa perfis de autenticação que estão temporariamente inutilizáveis devido a: - - períodos curtos de espera (limites de taxa/timeouts/falhas de autenticação) - - desativações mais longas (falhas de cobrança/crédito) + - cooldowns curtos (limites de taxa/timeouts/falhas de autenticação) + - desativações mais longas (falhas de faturamento/crédito) - Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo contra o catálogo e a allowlist e alerta quando ela não puder ser resolvida ou não for permitida. + Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo contra o catálogo e a lista de permissões e avisa quando ela não resolve ou não é permitida. - Quando o sandboxing está ativado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente. + Quando sandboxing está habilitado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente. - O doctor remove estado legado de preparação de dependências de Plugin gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes obsoletas de dependências geradas, diretórios antigos de etapa de instalação, resíduos locais de pacote de código anterior de reparo de dependências de Plugin empacotado e cópias npm gerenciadas órfãs ou recuperadas de Plugins `@openclaw/*` empacotados que podem sombrear o manifesto empacotado atual. + O Doctor remove o estado legado de preparação de dependências de Plugin gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes de dependências geradas obsoletas, diretórios antigos de estágio de instalação, resíduos locais de pacote de código anterior de reparo de dependências de plugins incluídos e cópias npm gerenciadas órfãs ou recuperadas de plugins `@openclaw/*` incluídos que podem sombrear o manifesto incluído atual. - O doctor também pode reinstalar Plugins baixáveis configurados quando a configuração os referencia, mas o registro local de Plugins não consegue encontrá-los. Para a externalização de Plugins empacotados de 2026.5.2, o doctor instala automaticamente Plugins baixáveis que a configuração existente já usa e então depende de `meta.lastTouchedVersion` para executar essa passagem de versão apenas uma vez. A inicialização do Gateway e o recarregamento de configuração não executam gerenciadores de pacotes; instalações de Plugin continuam sendo trabalho explícito de doctor/instalação/atualização. + O Doctor também pode reinstalar plugins baixáveis ausentes quando a configuração os referencia, mas o registro local de plugins não consegue encontrá-los. Exemplos incluem `plugins.entries` materiais, configurações de canal/provedor/busca configuradas e runtimes de agentes configurados. Durante atualizações de pacote, o doctor evita executar reparo de plugins pelo gerenciador de pacotes enquanto o pacote principal está sendo trocado; execute `openclaw doctor --fix` novamente após a atualização se um Plugin configurado ainda precisar de recuperação. A inicialização do Gateway e a recarga de configuração não executam gerenciadores de pacotes; instalações de plugins continuam sendo trabalho explícito de doctor/instalação/atualização. - O doctor detecta serviços legados do Gateway (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do Gateway. Ele também pode procurar serviços extras semelhantes ao Gateway e imprimir dicas de limpeza. Serviços do Gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras". + O Doctor detecta serviços de gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do Gateway. Ele também pode verificar serviços extras semelhantes a gateway e imprimir dicas de limpeza. Serviços de gateway OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras". - No Linux, se o serviço de Gateway em nível de usuário estiver ausente, mas existir um serviço de Gateway do OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep` e, em seguida, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor de sistema for responsável pelo ciclo de vida do Gateway. + No Linux, se o serviço de Gateway no nível do usuário estiver ausente, mas existir um serviço de Gateway OpenClaw no nível do sistema, o doctor não instala automaticamente um segundo serviço no nível do usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep`; depois, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor do sistema for responsável pelo ciclo de vida do Gateway. - - Quando uma conta de canal Matrix tem uma migração de estado legado pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e então executa as etapas de migração de melhor esforço: migração de estado legado do Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é totalmente ignorada. + + Quando uma conta de canal Matrix tem uma migração de estado legada pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e então executa as etapas de migração de melhor esforço: migração de estado legada da Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), esta verificação é ignorada inteiramente. - O doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de saúde. + O Doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de integridade. - O que ele relata: + O que ele informa: - - solicitações de pareamento inicial pendentes + - solicitações pendentes de primeiro pareamento - upgrades de função pendentes para dispositivos já pareados - upgrades de escopo pendentes para dispositivos já pareados - - reparos de incompatibilidade de chave pública em que o ID do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado + - reparos de incompatibilidade de chave pública em que o id do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado - registros pareados sem um token ativo para uma função aprovada - - tokens pareados cujos escopos se desviaram da linha de base de pareamento aprovada - - entradas locais em cache de token de dispositivo para a máquina atual que são anteriores a uma rotação de token no lado do Gateway ou carregam metadados de escopo obsoletos + - tokens pareados cujos escopos se desviam da linha de base de pareamento aprovada + - entradas locais em cache de token de dispositivo para a máquina atual que antecedem uma rotação de token no lado do Gateway ou carregam metadados de escopo obsoletos - O doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas: + O Doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas: - inspecione solicitações pendentes com `openclaw devices list` - aprove a solicitação exata com `openclaw devices approve ` - rotacione um token novo com `openclaw devices rotate --device --role ` - - remova e reaprove um registro obsoleto com `openclaw devices remove ` + - remova e reprove um registro obsoleto com `openclaw devices remove ` - Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento necessário": agora o doctor distingue pareamento inicial de upgrades pendentes de função/escopo e de desvio de token/identidade do dispositivo obsoleto. + Isso fecha a lacuna comum de "já pareado, mas ainda recebendo exigência de pareamento": o doctor agora diferencia o primeiro pareamento de upgrades pendentes de função/escopo e de desvios de token/identidade de dispositivo obsoletos. - O doctor emite avisos quando um provedor está aberto a DMs sem uma lista de permissão, ou quando uma política está configurada de forma perigosa. + O Doctor emite avisos quando um provedor está aberto a DMs sem uma lista de permissões ou quando uma política está configurada de forma perigosa. - - Se estiver em execução como um serviço de usuário do systemd, o doctor garante que o linger esteja habilitado para que o Gateway permaneça ativo após o logout. + + Se estiver executando como um serviço de usuário systemd, o doctor garante que o linger esteja habilitado para que o gateway permaneça ativo após o logout. - - 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 das Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas pela lista de permissão. - - **Diretórios legados do workspace**: avisa quando `~/openclaw` ou outros diretórios legados do workspace existem junto ao workspace atual. - - **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de plugins para quaisquer erros; relata capacidades de plugins de pacote. + - **Status de Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas por lista de permissões. + - **Diretórios legados de workspace**: avisa quando `~/openclaw` ou outros diretórios legados de workspace existem junto ao workspace atual. + - **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de Plugin para quaisquer erros; informa capacidades de plugins incluídos. - **Avisos de compatibilidade de Plugin**: sinaliza plugins que têm problemas de compatibilidade com o runtime atual. - - **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros em tempo de carregamento emitidos pelo registro de plugins. + - **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros de tempo de carregamento emitidos pelo registro de plugins. - O doctor verifica se os arquivos de bootstrap do workspace (por exemplo, `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele relata, por arquivo, contagens de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e o total de caracteres injetados como uma fração do orçamento total. Quando os arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`. + O Doctor verifica se os arquivos de bootstrap do workspace (por exemplo `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele informa, por arquivo, contagens de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e total de caracteres injetados como fração do orçamento total. Quando arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`. - 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 de `agents.*.models["/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal desapareceu, mas a configuração ainda solicita que o Gateway se vincule a ele. + Quando `openclaw doctor --fix` remove um Plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse Plugin: entradas `channels.`, 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 desapareceu, mas a configuração ainda pede que o gateway se vincule a ele. - - O doctor verifica se a completaçã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 completação dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache. + - Se o perfil do shell usa um padrão lento de completação dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida com arquivo em cache. - Se a completação está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente. - - Se nenhuma completação está configurada, o doctor solicita a instalação (somente modo interativo; ignorado com `--non-interactive`). + - Se nenhuma completação estiver configurada, o doctor solicita instalá-la (somente modo interativo; ignorado com `--non-interactive`). Execute `openclaw completion --write-state` para regenerar o cache manualmente. - O doctor verifica a prontidão da autenticação por token do gateway local. + O Doctor verifica a prontidão da autenticação por token do Gateway local. - - Se o modo de token precisa de um token e nenhuma fonte de token existe, o doctor oferece gerar um. - - Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o substitui por texto simples. - - `openclaw doctor --generate-gateway-token` força a geração somente quando nenhum SecretRef de token está configurado. + - Se o modo de token precisar de um token e não existir nenhuma fonte de token, o doctor oferece gerar um. + - Se `gateway.auth.token` for gerenciado por SecretRef, mas estiver indisponível, o doctor avisa e não o sobrescreve com texto simples. + - `openclaw doctor --generate-gateway-token` força a geração apenas quando nenhum SecretRef de token está configurado. - Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento fail-fast do runtime. + Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento de falha rápida do runtime. - - `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura dos comandos da família de status para reparos de configuração direcionados. - - Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar credenciais de bot configuradas quando disponíveis. - - Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho de comando atual, o doctor relata que a credencial está configurada, mas indisponível, e ignora a resolução automática em vez de travar ou relatar incorretamente o token como ausente. + - `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura que os comandos da família de status para reparos direcionados de configuração. + - Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar as credenciais configuradas do bot quando disponíveis. + - Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho do comando atual, o doctor informa que a credencial está configurada, mas indisponível, e pula a resolução automática em vez de travar ou informar incorretamente que o token está ausente. - O Doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar saudável. + O doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar íntegro. - - 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 configurado de embeddings da pesquisa de memória está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados: - - **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção incluindo o pacote npm e uma opção de caminho manual para o binário. - - **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL de modelo remoto/baixável reconhecida. Se estiver ausente, sugere mudar para um provedor remoto. - - **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se uma chave de API está presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente. + - **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção, incluindo o pacote npm e uma opção de caminho manual para o binário. + - **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL reconhecida de modelo remoto/baixável. Se estiver ausente, sugere mudar para um provedor remoto. + - **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se há uma chave de API presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente. - **Provedor automático**: verifica primeiro a disponibilidade do modelo local e depois tenta cada provedor remoto na ordem de seleção automática. - Quando há um resultado de sondagem do Gateway em cache disponível (o Gateway estava íntegro no momento da verificação), o Doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O Doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ao vivo do provedor. + Quando um resultado de sondagem do Gateway em cache está disponível (o Gateway estava íntegro no momento da verificação), o doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ao vivo do provedor. - Use `openclaw memory status --deep` para verificar a prontidão de embeddings em tempo de execução. + Use `openclaw memory status --deep` para verificar a prontidão de embeddings em runtime. - Se o Gateway estiver íntegro, o Doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas. + Se o Gateway estiver íntegro, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas. - O Doctor verifica a configuração do supervisor instalada (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinicialização). Quando encontra uma incompatibilidade, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais. + O doctor verifica a configuração instalada do supervisor (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinício). Quando encontra uma divergência, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais. Observações: @@ -463,39 +473,39 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto - `openclaw doctor --yes` aceita as solicitações de reparo padrão. - `openclaw doctor --repair` aplica as correções recomendadas sem solicitações. - `openclaw doctor --repair --force` sobrescreve configurações personalizadas do supervisor. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o Doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não são de serviço, mas ignora instalação/início/reinício/bootstrap do serviço, reescritas da configuração do supervisor e limpeza de serviço legado porque um supervisor externo é dono desse ciclo de vida. - - No Linux, o Doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd correspondente do Gateway estiver ativa. Ele também ignora unidades extras inativas semelhantes ao Gateway que não sejam legadas durante a varredura de serviços duplicados, para que arquivos de serviço auxiliares não gerem ruído de limpeza. - - Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo Doctor valida o SecretRef, mas não persiste valores de token em texto simples resolvidos nos metadados de ambiente do serviço do supervisor. - - O Doctor detecta valores de ambiente de serviço gerenciados com suporte em `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Tarefa Agendada do Windows incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da origem de tempo de execução em vez da definição do supervisor. - - O Doctor detecta quando o comando de serviço ainda fixa uma `--port` antiga após alterações em `gateway.port` e reescreve os metadados do serviço para a porta atual. - - Se a autenticação por token exigir um token e o SecretRef de token configurado não puder ser resolvido, o Doctor bloqueia o caminho de instalação/reparo com orientação acionável. - - Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o Doctor bloqueia instalação/reparo até que o modo seja definido explicitamente. - - Para unidades user-systemd no Linux, as verificações de divergência de token do Doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço. - - Reparos de serviço pelo Doctor se recusam a reescrever, interromper ou reiniciar um serviço de Gateway de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não envolvem serviço, mas pula instalação/início/reinício/bootstrap de serviço, reescritas da configuração do supervisor e limpeza de serviços legados porque um supervisor externo controla esse ciclo de vida. + - No Linux, o doctor não reescreve metadados de comando/ponto de entrada enquanto a unidade systemd correspondente do Gateway está ativa. Ele também ignora unidades extras inativas e não legadas semelhantes ao Gateway durante a varredura de serviços duplicados, para que arquivos de serviço complementares não gerem ruído de limpeza. + - Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo doctor valida o SecretRef, mas não persiste valores de token em texto claro resolvidos nos metadados de ambiente do serviço do supervisor. + - O doctor detecta valores de ambiente de serviço gerenciados por `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Windows Scheduled Task incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da origem em runtime em vez da definição do supervisor. + - O doctor detecta quando o comando do serviço ainda fixa um `--port` antigo após alterações em `gateway.port` e reescreve os metadados do serviço para a porta atual. + - Se a autenticação por token exigir um token e o SecretRef de token configurado não for resolvido, o doctor bloqueia o caminho de instalação/reparo com orientações acionáveis. + - Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o doctor bloqueia a instalação/reparo até que o modo seja definido explicitamente. + - Para unidades user-systemd do Linux, as verificações de divergência de token do doctor agora incluem origens `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço. + - Os reparos de serviço do doctor se recusam a reescrever, parar ou reiniciar um serviço do Gateway a partir de um binário antigo do OpenClaw quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Você sempre pode forçar uma reescrita completa via `openclaw gateway install --force`. - - O Doctor inspeciona o tempo de execução do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH). + + 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 do Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega a inicialização do seu shell. O Doctor oferece migrar para uma instalação do Node do sistema quando disponível (Homebrew/apt/choco). + + O doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho do Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega a inicialização do seu shell. O doctor oferece migrar para uma instalação de sistema do Node quando disponível (Homebrew/apt/choco). - LaunchAgents do macOS recém-instalados ou reparados usam um PATH canônico do sistema (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, de modo que Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alterem qual Node os processos filhos resolvem. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios fallback presumidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco. + LaunchAgents do macOS recém-instalados ou reparados usam um PATH de sistema canônico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, portanto Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alteram qual Node é resolvido por processos filhos. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios de fallback inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco. - - O Doctor persiste quaisquer alterações de configuração e carimba metadados do assistente para registrar a execução do Doctor. + + O doctor persiste quaisquer alterações de configuração e marca os metadados do assistente para registrar a execução do doctor. - O Doctor sugere um sistema de memória do workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git. + O doctor sugere um sistema de memória de workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git. - Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre a estrutura do workspace e backup com git (GitHub ou GitLab privado recomendado). + Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para ver um guia completo sobre estrutura de workspace e backup com git (recomendado GitHub ou GitLab privado). -## Relacionado +## Relacionados - [Runbook do Gateway](/pt-BR/gateway) - [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting) diff --git a/docs/pt-BR/gateway/logging.md b/docs/pt-BR/gateway/logging.md index ee2f145bc..8b80dd900 100644 --- a/docs/pt-BR/gateway/logging.md +++ b/docs/pt-BR/gateway/logging.md @@ -1,32 +1,43 @@ --- read_when: - - Alteração da saída ou dos formatos de logs + - Alterando a saída ou os formatos de log - Depuração da saída da CLI ou do Gateway -summary: Superfícies de log, logs de arquivo, estilos de log WS e formatação do console -title: Logs do Gateway +summary: Superfícies de registro, registros em arquivo, estilos de registro WS e formatação do console +title: Registro do Gateway x-i18n: - generated_at: "2026-05-02T05:47:08Z" + generated_at: "2026-05-05T01:46:33Z" model: gpt-5.5 provider: openai - source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13 + source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246 source_path: gateway/logging.md workflow: 16 --- -# Logs +# Logging -Para uma visão geral voltada ao usuário (CLI + UI de Controle + configuração), consulte [/logging](/pt-BR/logging). +Para uma visão geral voltada ao usuário (CLI + interface de controle + configuração), consulte [/logging](/pt-BR/logging). -OpenClaw tem duas “superfícies” de log: +O OpenClaw tem duas “superfícies” de log: -- **Saída do console** (o que você vê no terminal / UI de Depuração). -- **Logs em arquivo** (linhas JSON) gravados pelo logger do Gateway. +- **Saída do console** (o que você vê no terminal / interface de depuração). +- **Logs de arquivo** (linhas JSON) gravados pelo registrador do Gateway. -## Logger baseado em arquivo +Na inicialização, o Gateway registra o modelo de agente padrão resolvido junto com os +padrões de modo que afetam novas sessões, por exemplo: + +```text +agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on) +``` + +`thinking` vem do agente padrão, dos parâmetros do modelo ou do padrão global do agente; +quando não está definido, o resumo de inicialização mostra `medium`. `fast` vem do +agente padrão ou dos parâmetros `fastMode` do modelo. + +## Registrador baseado em arquivo - O arquivo de log rotativo padrão fica em `/tmp/openclaw/` (um arquivo por dia): `openclaw-YYYY-MM-DD.log` - A data usa o fuso horário local do host do Gateway. -- Arquivos de log ativos rotacionam em `logging.maxFileBytes` (padrão: 100 MB), mantendo +- Arquivos de log ativos são rotacionados em `logging.maxFileBytes` (padrão: 100 MB), mantendo até cinco arquivos numerados e continuando a gravar em um novo arquivo ativo. - O caminho e o nível do arquivo de log podem ser configurados via `~/.openclaw/openclaw.json`: - `logging.file` @@ -34,7 +45,7 @@ OpenClaw tem duas “superfícies” de log: O formato do arquivo é um objeto JSON por linha. -A aba Logs da UI de Controle acompanha esse arquivo via Gateway (`logs.tail`). +A aba Logs da interface de controle acompanha esse arquivo via Gateway (`logs.tail`). A CLI pode fazer o mesmo: ```bash @@ -43,18 +54,18 @@ openclaw logs --follow **Detalhado vs. níveis de log** -- **Logs em arquivo** são controlados exclusivamente por `logging.level`. +- **Logs de arquivo** são controlados exclusivamente por `logging.level`. - `--verbose` afeta apenas a **verbosidade do console** (e o estilo de log WS); ele **não** - aumenta o nível dos logs em arquivo. -- Para capturar detalhes exclusivos do modo detalhado nos logs em arquivo, defina `logging.level` como `debug` ou + aumenta o nível de log do arquivo. +- Para capturar detalhes exclusivos do modo detalhado nos logs de arquivo, defina `logging.level` como `debug` ou `trace`. -- O registro em log de rastreamento também inclui resumos de tempos de diagnóstico para caminhos críticos selecionados, - como a preparação de fábricas de ferramentas de Plugin. Consulte +- O registro em nível trace também inclui resumos de tempo de diagnóstico para caminhos críticos selecionados, + como a preparação de fábricas de ferramentas de Plugins. Consulte [/tools/plugin#slow-plugin-tool-setup](/pt-BR/tools/plugin#slow-plugin-tool-setup). ## Captura do console -A CLI captura `console.log/info/warn/error/debug/trace` e os grava nos logs em arquivo, +A CLI captura `console.log/info/warn/error/debug/trace` e os grava nos logs de arquivo, enquanto ainda imprime em stdout/stderr. Você pode ajustar a verbosidade do console de forma independente via: @@ -64,20 +75,20 @@ Você pode ajustar a verbosidade do console de forma independente via: ## Redação -O OpenClaw pode mascarar tokens sensíveis antes que a saída de log ou transcrição saia do -processo. Essa política de redação de logs é aplicada nos destinos de texto de console, log em arquivo, -registro de log OTLP e transcrição de sessão, portanto valores de segredo correspondentes são +O OpenClaw pode mascarar tokens sensíveis antes que a saída de log ou de transcrição saia do +processo. Essa política de redação de logs é aplicada aos destinos de texto do console, +log de arquivo, registro de log OTLP e transcrição de sessão, para que valores secretos correspondentes sejam mascarados antes que linhas JSONL ou mensagens sejam gravadas em disco. - `logging.redactSensitive`: `off` | `tools` (padrão: `tools`) -- `logging.redactPatterns`: array de strings regex (substitui os padrões) - - Use strings regex brutas (auto `gi`), ou `/pattern/flags` se precisar de flags personalizadas. +- `logging.redactPatterns`: matriz de strings regex (substitui os padrões) + - Use strings regex brutas (`gi` automático), ou `/pattern/flags` se precisar de flags personalizadas. - Correspondências são mascaradas mantendo os primeiros 6 + últimos 4 caracteres (comprimento >= 18), caso contrário `***`. - - Os padrões cobrem atribuições de chaves comuns, flags de CLI, campos JSON, cabeçalhos bearer, blocos PEM, prefixos populares de token e nomes de campos de credenciais de pagamento, como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento. + - Os padrões cobrem atribuições comuns de chaves, flags de CLI, campos JSON, cabeçalhos bearer, blocos PEM, prefixos populares de tokens e nomes de campos de credenciais de pagamento, como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento. -Alguns limites de segurança sempre fazem a redação, independentemente de `logging.redactSensitive`. -Isso inclui eventos de chamada de ferramenta da UI de Controle, saída da ferramenta `sessions_history`, -exportações de suporte de diagnóstico, observações de erro de provedores, exibição de comandos de aprovação exec +Alguns limites de segurança sempre fazem redação, independentemente de `logging.redactSensitive`. +Isso inclui eventos de chamadas de ferramentas da interface de controle, saída da ferramenta `sessions_history`, +exportações de suporte a diagnósticos, observações de erros de provedores, exibição de comandos de aprovação de exec e logs do protocolo WebSocket do Gateway. Essas superfícies ainda podem usar `logging.redactPatterns` como padrões adicionais, mas `redactSensitive: "off"` não faz com que elas emitam segredos brutos. @@ -88,7 +99,7 @@ O Gateway imprime logs do protocolo WebSocket em dois modos: - **Modo normal (sem `--verbose`)**: apenas resultados RPC “interessantes” são impressos: - erros (`ok=false`) - - chamadas lentas (limite padrão: `>= 50ms`) + - chamadas lentas (limiar padrão: `>= 50ms`) - erros de análise - **Modo detalhado (`--verbose`)**: imprime todo o tráfego de solicitação/resposta WS. @@ -114,27 +125,27 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## Formatação do console (log de subsistema) +## Formatação do console (registro por subsistema) -O formatador de console é **consciente de TTY** e imprime linhas consistentes e prefixadas. -Loggers de subsistema mantêm a saída agrupada e fácil de examinar. +O formatador do console é **compatível com TTY** e imprime linhas consistentes, com prefixos. +Registradores de subsistema mantêm a saída agrupada e fácil de examinar. Comportamento: -- **Prefixos de subsistema** em todas as linhas (por exemplo, `[gateway]`, `[canvas]`, `[tailscale]`) +- **Prefixos de subsistema** em cada linha (por exemplo, `[gateway]`, `[canvas]`, `[tailscale]`) - **Cores de subsistema** (estáveis por subsistema), além de coloração por nível -- **Cor quando a saída é um TTY ou o ambiente parece um terminal rico** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respeita `NO_COLOR` -- **Prefixos de subsistema encurtados**: descarta `gateway/` + `channels/` iniciais, mantém os últimos 2 segmentos (por exemplo, `whatsapp/outbound`) -- **Sub-loggers por subsistema** (prefixo automático + campo estruturado `{ subsystem }`) +- **Cor quando a saída é um TTY ou o ambiente parece um terminal avançado** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respeita `NO_COLOR` +- **Prefixos de subsistema encurtados**: remove `gateway/` + `channels/` iniciais, mantém os últimos 2 segmentos (por exemplo, `whatsapp/outbound`) +- **Sub-registradores por subsistema** (prefixo automático + campo estruturado `{ subsystem }`) - **`logRaw()`** para saída de QR/UX (sem prefixo, sem formatação) - **Estilos de console** (por exemplo, `pretty | compact | json`) -- **Nível de log do console** separado do nível de log em arquivo (o arquivo mantém todos os detalhes quando `logging.level` está definido como `debug`/`trace`) +- **Nível de log do console** separado do nível de log do arquivo (o arquivo mantém detalhes completos quando `logging.level` está definido como `debug`/`trace`) - **Corpos de mensagens do WhatsApp** são registrados em `debug` (use `--verbose` para vê-los) -Isso mantém os logs em arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar. +Isso mantém os logs de arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar. -## Relacionados +## Relacionado -- [Logs](/pt-BR/logging) +- [Logging](/pt-BR/logging) - [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry) -- [Exportação de diagnóstico](/pt-BR/gateway/diagnostics) +- [Exportação de diagnósticos](/pt-BR/gateway/diagnostics) diff --git a/docs/pt-BR/help/debugging.md b/docs/pt-BR/help/debugging.md index e6d572a7d..ddf3a0442 100644 --- a/docs/pt-BR/help/debugging.md +++ b/docs/pt-BR/help/debugging.md @@ -1,20 +1,20 @@ --- read_when: - - Você precisa inspecionar a saída bruta do modelo em busca de vazamento de raciocínio - - Você quer executar o Gateway em modo watch enquanto itera + - Você precisa inspecionar a saída bruta do modelo para detectar vazamento de raciocínio + - Você quer executar o Gateway em modo de observação enquanto itera - Você precisa de um fluxo de trabalho de depuração repetível -summary: 'Ferramentas de depuração: modo de monitoramento, streams brutos do modelo e rastreamento de vazamento de raciocínio' +summary: 'Ferramentas de depuração: modo de observação, fluxos brutos do modelo e rastreamento de vazamento de raciocínio' title: Depuração x-i18n: - generated_at: "2026-05-03T21:33:55Z" + generated_at: "2026-05-05T01:47:14Z" model: gpt-5.5 provider: openai - source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc + source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec source_path: help/debugging.md workflow: 16 --- -Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio no texto normal. +Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio ao texto normal. ## Substituições de depuração em runtime @@ -36,7 +36,7 @@ Exemplos: ## Saída de rastreamento da sessão Use `/trace` quando quiser ver linhas de rastreamento/depuração pertencentes ao Plugin em uma sessão -sem ativar o modo verboso completo. +sem ativar o modo detalhado completo. Exemplos: @@ -46,16 +46,16 @@ Exemplos: /trace off ``` -Use `/trace` para diagnósticos de Plugin, como resumos de depuração do Active Memory. -Continue usando `/verbose` para saída verbosa normal de status/ferramentas, e continue usando +Use `/trace` para diagnósticos de Plugin, como resumos de depuração de Active Memory. +Continue usando `/verbose` para saída detalhada normal de status/ferramentas, e continue usando `/debug` para substituições de configuração somente em runtime. ## Rastreamento do ciclo de vida do Plugin -Use `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` quando comandos de ciclo de vida de Plugin parecerem lentos +Use `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` quando os comandos de ciclo de vida do Plugin parecerem lentos e você precisar de uma decomposição de fases integrada para metadados, descoberta, registro, -espelho de runtime, mutação de configuração e trabalho de atualização de plugins. O rastreamento é opcional e escreve -em stderr, então a saída JSON do comando continua analisável. +espelho de runtime, mutação de configuração e trabalho de atualização do Plugin. O rastreamento é opcional e escreve +em stderr, então a saída JSON do comando permanece analisável. Exemplo: @@ -63,7 +63,7 @@ Exemplo: OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force ``` -Exemplo de saída: +Saída de exemplo: ```text [plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install" @@ -71,12 +71,12 @@ Exemplo de saída: [plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed" ``` -Use isto para investigação de ciclo de vida de Plugin antes de recorrer a um profiler de CPU. -Se o comando estiver sendo executado a partir de um checkout do código-fonte, prefira medir o runtime +Use isso para investigação do ciclo de vida do Plugin antes de recorrer a um criador de perfil de CPU. +Se o comando estiver sendo executado a partir de um checkout de código-fonte, prefira medir o runtime compilado com `node dist/entry.js ...` após `pnpm build`; `pnpm openclaw ...` também mede a sobrecarga do executor de código-fonte. -## Inicialização da CLI e profiling de comandos +## Inicialização da CLI e criação de perfil de comandos Use o benchmark de inicialização versionado quando um comando parecer lento: @@ -86,7 +86,7 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3 pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu ``` -Para profiling avulso pelo executor de código-fonte normal, defina +Para criação de perfil pontual pelo executor de código-fonte normal, defina `OPENCLAW_RUN_NODE_CPU_PROF_DIR`: ```bash @@ -94,11 +94,21 @@ OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status ``` O executor de código-fonte adiciona flags de perfil de CPU do Node e grava um `.cpuprofile` para o -comando. Use isto antes de adicionar instrumentação temporária ao código do comando. +comando. Use isso antes de adicionar instrumentação temporária ao código do comando. -## Modo watch do Gateway +Para travamentos de inicialização que parecem trabalho síncrono de sistema de arquivos ou carregador de módulos, +adicione a flag de rastreamento de E/S síncrona do Node pelo executor de código-fonte: -Para iteração rápida, execute o gateway sob o observador de arquivos: +```bash +OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force +``` + +`pnpm gateway:watch` habilita essa flag por padrão para o filho Gateway observado. +Defina `OPENCLAW_TRACE_SYNC_IO=0` para suprimir a saída de rastreamento de E/S síncrona do Node no modo de observação. + +## Modo de observação do Gateway + +Para iteração rápida, execute o Gateway sob o observador de arquivos: ```bash pnpm gateway:watch @@ -107,14 +117,14 @@ pnpm gateway:watch Por padrão, isso inicia ou reinicia uma sessão tmux chamada `openclaw-gateway-watch-main` (ou uma variante específica de perfil/porta, como `openclaw-gateway-watch-dev-19001`) e anexa automaticamente a partir de terminais interativos. -Shells não interativos, CI e chamadas de execução de agentes permanecem desanexados e imprimem -instruções de anexação em vez disso. Anexe manualmente quando necessário: +Shells não interativos, CI e chamadas exec de agente permanecem desanexados e imprimem instruções +de anexação. Anexe manualmente quando necessário: ```bash tmux attach -t openclaw-gateway-watch-main ``` -O painel do tmux executa o observador bruto: +O painel tmux executa o observador bruto: ```bash node scripts/watch-node.mjs gateway --force @@ -124,68 +134,73 @@ Use o modo em primeiro plano quando tmux não for desejado: ```bash pnpm gateway:watch:raw -# or +# ou OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch ``` -Desative a anexação automática mantendo o gerenciamento por tmux: +Desative a anexação automática mantendo o gerenciamento do tmux: ```bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` -Faça profiling do tempo de CPU do Gateway observado ao depurar hotspots de inicialização/runtime: +Crie perfil do tempo de CPU do Gateway observado ao depurar pontos críticos de inicialização/runtime: ```bash pnpm gateway:watch --benchmark ``` -O wrapper de watch consome `--benchmark` antes de invocar o Gateway e grava -um `.cpuprofile` V8 por saída de filho do Gateway em +O wrapper de observação consome `--benchmark` antes de invocar o Gateway e grava +um `.cpuprofile` V8 por saída de filho Gateway em `.artifacts/gateway-watch-profiles/`. Pare ou reinicie o gateway observado para -descarregar o perfil atual, então abra-o com Chrome DevTools ou Speedscope: +descarregar o perfil atual, depois abra-o com Chrome DevTools ou Speedscope: ```bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ``` Use `--benchmark-dir ` quando quiser perfis em outro lugar. -Use `--benchmark-no-force` quando quiser que o filho com benchmark pule a limpeza de porta -`--force` padrão e falhe rapidamente se a porta do Gateway já estiver em +Use `--benchmark-no-force` quando quiser que o filho sob benchmark ignore a +limpeza de porta padrão `--force` e falhe rapidamente se a porta do Gateway já estiver em uso. +O modo benchmark suprime por padrão o excesso de rastreamento de E/S síncrona. Defina +`OPENCLAW_TRACE_SYNC_IO=1` com `--benchmark` quando quiser explicitamente perfis de CPU +e rastreamentos de pilha de E/S síncrona do Node. No modo benchmark, esses blocos de rastreamento +são gravados em `gateway-watch-output.log` no diretório do benchmark e +filtrados do painel do terminal; os logs normais do Gateway continuam visíveis. -O wrapper tmux leva seletores comuns de runtime não secretos, como +O wrapper tmux carrega seletores comuns de runtime não secretos, como `OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`, `OPENCLAW_GATEWAY_PORT` e `OPENCLAW_SKIP_CHANNELS`, para dentro do painel. Coloque credenciais de provedor no seu perfil/configuração normal, ou use o modo bruto em primeiro plano -para segredos efêmeros avulsos. +para segredos efêmeros pontuais. Se o Gateway observado sair durante a inicialização, o observador executa -`openclaw doctor --fix --non-interactive` uma vez e reinicia o filho do Gateway. -Use `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` quando quiser a falha de inicialização -original sem a etapa de reparo apenas de desenvolvimento. -O painel tmux gerenciado também usa logs coloridos do Gateway por padrão para legibilidade; +`openclaw doctor --fix --non-interactive` uma vez e reinicia o filho Gateway. +Use `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` quando quiser a falha original de inicialização +sem a passagem de reparo exclusiva de desenvolvimento. +O painel tmux gerenciado também usa por padrão logs coloridos do Gateway para legibilidade; defina `FORCE_COLOR=0` ao iniciar `pnpm gateway:watch` para desativar a saída ANSI. -O observador reinicia em arquivos relevantes para build sob `src/`, arquivos-fonte de extensão, +O observador reinicia em arquivos relevantes para build em `src/`, arquivos de código-fonte de extensão, metadados `package.json` e `openclaw.plugin.json` de extensão, `tsconfig.json`, -`package.json` e `tsdown.config.ts`. Alterações de metadados de extensão reiniciam o -gateway sem forçar uma rebuild de `tsdown`; alterações de código-fonte e configuração ainda +`package.json` e `tsdown.config.ts`. Alterações em metadados de extensão reiniciam o +gateway sem forçar uma recompilação `tsdown`; alterações de código-fonte e configuração ainda recompilam `dist` primeiro. -Adicione quaisquer flags da CLI do gateway após `gateway:watch` e elas serão repassadas em -cada reinicialização. Executar novamente o mesmo comando de watch recria o painel tmux nomeado, e -o observador bruto ainda mantém seu bloqueio de observador único, de modo que pais observadores duplicados +Adicione quaisquer flags de CLI do gateway após `gateway:watch` e elas serão repassadas em +cada reinicialização. Reexecutar o mesmo comando de observação recria o painel tmux nomeado, e +o observador bruto ainda mantém seu bloqueio de observador único para que pais observadores duplicados sejam substituídos em vez de se acumularem. ## Perfil de desenvolvimento + gateway de desenvolvimento (--dev) -Use o perfil de desenvolvimento para isolar o estado e iniciar uma configuração segura e descartável para -depuração. Existem **duas** flags `--dev`: +Use o perfil de desenvolvimento para isolar estado e iniciar uma configuração segura e descartável para +depuração. Há **duas** flags `--dev`: - **`--dev` global (perfil):** isola o estado em `~/.openclaw-dev` e - define a porta padrão do gateway como `19001` (portas derivadas se deslocam junto com ela). -- **`gateway --dev`: diz ao Gateway para criar automaticamente uma configuração padrão + - workspace** quando ausentes (e pular BOOTSTRAP.md). + define a porta padrão do gateway como `19001` (portas derivadas mudam junto). +- **`gateway --dev`: informa ao Gateway para criar automaticamente uma configuração padrão + + workspace** quando ausentes (e ignorar BOOTSTRAP.md). Fluxo recomendado (perfil de desenvolvimento + bootstrap de desenvolvimento): @@ -196,31 +211,31 @@ OPENCLAW_PROFILE=dev openclaw tui Se você ainda não tiver uma instalação global, execute a CLI via `pnpm openclaw ...`. -O que isto faz: +O que isso faz: 1. **Isolamento de perfil** (`--dev` global) - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas se deslocam de acordo) + - `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas mudam de acordo) 2. **Bootstrap de desenvolvimento** (`gateway --dev`) - Grava uma configuração mínima se ausente (`gateway.mode=local`, vincula a loopback). - - Define `agent.workspace` para o workspace de desenvolvimento. + - Define `agent.workspace` como o workspace de desenvolvimento. - Define `agent.skipBootstrap=true` (sem BOOTSTRAP.md). - - Inicializa os arquivos do workspace se ausentes: + - Semeia os arquivos do workspace se ausentes: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. - Identidade padrão: **C3‑PO** (droide de protocolo). - - Pula provedores de canal no modo de desenvolvimento (`OPENCLAW_SKIP_CHANNELS=1`). + - Ignora provedores de canal no modo de desenvolvimento (`OPENCLAW_SKIP_CHANNELS=1`). -Fluxo de reset (início limpo): +Fluxo de redefinição (começo limpo): ```bash pnpm gateway:dev:reset ``` -`--dev` é uma flag de perfil **global** e é consumida por alguns executores. Se precisar escrevê-la explicitamente, use o formato de variável de ambiente: +`--dev` é uma flag de perfil **global** e é consumida por alguns executores. Se precisar escrevê-la explicitamente, use a forma de variável de ambiente: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset @@ -229,10 +244,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset `--reset` apaga configuração, credenciais, sessões e o workspace de desenvolvimento (usando -`trash`, não `rm`), então recria a configuração de desenvolvimento padrão. +`trash`, não `rm`), depois recria a configuração padrão de desenvolvimento. -Se um gateway que não seja de desenvolvimento já estiver em execução (launchd ou systemd), pare-o primeiro: +Se um gateway que não é de desenvolvimento já estiver em execução (launchd ou systemd), pare-o primeiro: ```bash openclaw gateway stop @@ -243,16 +258,16 @@ openclaw gateway stop ## Registro de stream bruto (OpenClaw) OpenClaw pode registrar o **stream bruto do assistente** antes de qualquer filtragem/formatação. -Esta é a melhor maneira de ver se o raciocínio está chegando como deltas de texto simples +Esta é a melhor forma de ver se o raciocínio está chegando como deltas de texto simples (ou como blocos de pensamento separados). -Ative via CLI: +Habilite pela CLI: ```bash pnpm gateway:watch --raw-stream ``` -Substituição de caminho opcional: +Substituição opcional de caminho: ```bash pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl @@ -269,9 +284,9 @@ Arquivo padrão: `~/.openclaw/logs/raw-stream.jsonl` -## Registro de chunk bruto (pi-mono) +## Registro de fragmentos brutos (pi-mono) -Para capturar **chunks brutos compatíveis com OpenAI** antes de serem analisados em blocos, +Para capturar **fragmentos brutos compatíveis com OpenAI** antes que sejam analisados em blocos, pi-mono expõe um logger separado: ```bash @@ -288,16 +303,16 @@ Arquivo padrão: `~/.pi-mono/logs/raw-openai-completions.jsonl` -> Observação: isto é emitido apenas por processos que usam o provedor +> Observação: isso é emitido somente por processos que usam o provedor > `openai-completions` do pi-mono. ## Notas de segurança -- Logs de stream bruto podem incluir prompts completos, saída de ferramentas e dados de usuário. +- Logs de stream bruto podem incluir prompts completos, saída de ferramentas e dados de usuários. - Mantenha os logs locais e exclua-os após a depuração. - Se você compartilhar logs, remova segredos e PII primeiro. -## Relacionado +## Relacionados - [Solução de problemas](/pt-BR/help/troubleshooting) -- [FAQ](/pt-BR/help/faq) +- [Perguntas frequentes](/pt-BR/help/faq) diff --git a/docs/pt-BR/help/faq-models.md b/docs/pt-BR/help/faq-models.md index 3e21d185d..5668dccc5 100644 --- a/docs/pt-BR/help/faq-models.md +++ b/docs/pt-BR/help/faq-models.md @@ -1,59 +1,59 @@ --- read_when: - - Escolher ou alternar modelos, configurar apelidos - - Depuração do failover de modelo / "Todos os modelos falharam" - - Entendendo os perfis de autenticação e como gerenciá-los + - Escolha ou troca de modelos, configuração de aliases + - Depuração da alternância de modelo em caso de falha / "Todos os modelos falharam" + - Entendendo perfis de autenticação e como gerenciá-los sidebarTitle: Models FAQ summary: 'Perguntas frequentes: padrões de modelo, seleção, apelidos, troca, alternância em caso de falha e perfis de autenticação' title: 'Perguntas frequentes: modelos e autenticação' x-i18n: - generated_at: "2026-05-02T05:49:13Z" + generated_at: "2026-05-05T01:47:30Z" model: gpt-5.5 provider: openai - source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884 + source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54 source_path: help/faq-models.md workflow: 16 --- - Perguntas e respostas sobre modelos e perfis de autenticação. Para configuração, sessões, gateway, canais e - solução de problemas, consulte o [FAQ](/pt-BR/help/faq) principal. + P&R sobre modelos e perfis de autenticação. Para configuração, sessões, gateway, canais e + solução de problemas, consulte a [FAQ](/pt-BR/help/faq) principal. ## Modelos: padrões, seleção, aliases, troca - + O modelo padrão do OpenClaw é o que você definir como: ``` agents.defaults.model.primary ``` - Modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.5` ou `openai-codex/gpt-5.5`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato, e só então recorre ao provedor padrão configurado como um caminho de compatibilidade obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Ainda assim, você deve definir `provider/model` **explicitamente**. + Modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.5` ou `openai-codex/gpt-5.5`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para esse ID exato de modelo e só então recorre ao provedor padrão configurado como um caminho de compatibilidade obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Mesmo assim, você deve definir `provider/model` **explicitamente**. - - **Padrão recomendado:** use o modelo mais forte de última geração disponível na sua pilha de provedores. - **Para agentes com ferramentas habilitadas ou entrada não confiável:** priorize a capacidade do modelo em vez do custo. - **Para chat rotineiro/de baixo risco:** use modelos de fallback mais baratos e roteie por função do agente. + + **Padrão recomendado:** use o modelo de geração mais recente e mais forte disponível na sua pilha de provedores. + **Para agentes com ferramentas habilitadas ou entrada não confiável:** priorize a força do modelo em vez do custo. + **Para conversas rotineiras/de baixo risco:** use modelos de fallback mais baratos e roteie por função do agente. - MiniMax tem sua própria documentação: [MiniMax](/pt-BR/providers/minimax) e + O MiniMax tem sua própria documentação: [MiniMax](/pt-BR/providers/minimax) e [Modelos locais](/pt-BR/gateway/local-models). - Regra prática: use o **melhor modelo que você puder pagar** para trabalho de alto risco e um modelo mais barato - para chat rotineiro ou resumos. Você pode rotear modelos por agente e usar subagentes para + Regra prática: use o **melhor modelo que você puder pagar** para trabalho de alto risco, e um modelo mais barato + para conversas rotineiras ou resumos. Você pode rotear modelos por agente e usar subagentes para paralelizar tarefas longas (cada subagente consome tokens). Consulte [Modelos](/pt-BR/concepts/models) e [Subagentes](/pt-BR/tools/subagents). - Aviso importante: modelos mais fracos ou excessivamente quantizados são mais vulneráveis a injeção de prompt + Aviso forte: modelos mais fracos/com quantização excessiva são mais vulneráveis a injeção de prompt e comportamento inseguro. Consulte [Segurança](/pt-BR/gateway/security). Mais contexto: [Modelos](/pt-BR/concepts/models). - - Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituições completas da configuração. + + Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituições completas de configuração. Opções seguras: @@ -63,20 +63,20 @@ x-i18n: - edite `agents.defaults.model` em `~/.openclaw/openclaw.json` Evite `config.apply` com um objeto parcial, a menos que você pretenda substituir toda a configuração. - Para edições por RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload de lookup fornece o caminho normalizado, documentação/restrições superficiais do schema e resumos dos filhos imediatos. + Para edições por RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload de lookup fornece o caminho normalizado, documentos/restrições rasos do esquema e resumos imediatos dos filhos. para atualizações parciais. - Se você sobrescreveu a configuração, restaure a partir do backup ou execute novamente `openclaw doctor` para reparar. + Se você sobrescreveu a configuração, restaure a partir de um backup ou execute novamente `openclaw doctor` para reparar. Documentação: [Modelos](/pt-BR/concepts/models), [Configurar](/pt-BR/cli/configure), [Configuração](/pt-BR/cli/config), [Doctor](/pt-BR/gateway/doctor). - + Sim. Ollama é o caminho mais fácil para modelos locais. Configuração mais rápida: - 1. Instale o Ollama de `https://ollama.com/download` + 1. Instale o Ollama a partir de `https://ollama.com/download` 2. Baixe um modelo local, como `ollama pull gemma4` 3. Se também quiser modelos em nuvem, execute `ollama signin` 4. Execute `openclaw onboard` e escolha `Ollama` @@ -84,13 +84,13 @@ x-i18n: Observações: - - `Cloud + Local` fornece modelos em nuvem mais seus modelos Ollama locais - - modelos em nuvem como `kimi-k2.5:cloud` não precisam de download local + - `Cloud + Local` oferece modelos em nuvem mais seus modelos Ollama locais + - modelos em nuvem como `kimi-k2.5:cloud` não precisam de um download local - para troca manual, use `openclaw models list` e `openclaw models set ollama/` - Observação de segurança: modelos menores ou muito quantizados são mais vulneráveis a injeção de prompt. + Observação de segurança: modelos menores ou fortemente quantizados são mais vulneráveis a injeção de prompt. Recomendamos fortemente **modelos grandes** para qualquer bot que possa usar ferramentas. - Se ainda quiser modelos pequenos, habilite sandboxing e allowlists rigorosas de ferramentas. + Se ainda quiser modelos pequenos, habilite sandboxing e allowlists estritas de ferramentas. Documentação: [Ollama](/pt-BR/providers/ollama), [Modelos locais](/pt-BR/gateway/local-models), [Provedores de modelo](/pt-BR/concepts/model-providers), [Segurança](/pt-BR/gateway/security), @@ -98,14 +98,14 @@ x-i18n: - - - Essas implantações podem diferir e mudar ao longo do tempo; não há uma recomendação fixa de provedor. - - Verifique a configuração atual de runtime em cada gateway com `openclaw models status`. - - Para agentes sensíveis à segurança/com ferramentas habilitadas, use o modelo mais forte de última geração disponível. + + - Essas implantações podem diferir e mudar com o tempo; não há recomendação fixa de provedor. + - Verifique a configuração atual em tempo de execução em cada Gateway com `openclaw models status`. + - Para agentes sensíveis à segurança/com ferramentas habilitadas, use o modelo de geração mais recente e mais forte disponível. - + Use o comando `/model` como uma mensagem independente: ``` @@ -118,9 +118,9 @@ x-i18n: /model gemini-flash-lite ``` - Esses são os aliases integrados. Aliases personalizados podem ser adicionados por meio de `agents.defaults.models`. + Estes são os aliases integrados. Aliases personalizados podem ser adicionados via `agents.defaults.models`. - Você pode listar os modelos disponíveis com `/model`, `/model list` ou `/model status`. + Você pode listar modelos disponíveis com `/model`, `/model list` ou `/model status`. `/model` (e `/model list`) mostra um seletor compacto e numerado. Selecione por número: @@ -146,27 +146,27 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - Se quiser voltar ao padrão, selecione-o em `/model` (ou envie `/model `). + Se quiser voltar ao padrão, escolha-o em `/model` (ou envie `/model `). Use `/model status` para confirmar qual perfil de autenticação está ativo. - + Sim. Trate a escolha do modelo e a escolha do runtime separadamente: - - **Agente de programação Codex nativo:** defina `agents.defaults.model.primary` como `openai/gpt-5.5` e `agents.defaults.agentRuntime.id` como `"codex"`. Faça login com `openclaw models auth login --provider openai-codex` quando quiser autenticação por assinatura ChatGPT/Codex. - - **Tarefas diretas da API da OpenAI por meio do PI:** use `/model openai/gpt-5.5` sem uma substituição de runtime Codex e configure `OPENAI_API_KEY`. - - **OAuth do Codex por meio do PI:** use `/model openai-codex/gpt-5.5` apenas quando você quiser intencionalmente o executor normal do PI com OAuth do Codex. - - **Subagentes:** roteie tarefas de programação para um agente exclusivo de Codex com seu próprio modelo e padrão de `agentRuntime`. + - **Agente de codificação Codex nativo:** defina `agents.defaults.model.primary` como `openai/gpt-5.5` e `agents.defaults.agentRuntime.id` como `"codex"`. Faça login com `openclaw models auth login --provider openai-codex` quando quiser autenticação de assinatura ChatGPT/Codex. + - **Tarefas diretas da API da OpenAI por meio do PI:** use `/model openai/gpt-5.5` sem substituição de runtime Codex e configure `OPENAI_API_KEY`. + - **OAuth do Codex por meio do PI:** use `/model openai-codex/gpt-5.5` apenas quando quiser intencionalmente o executor PI normal com OAuth do Codex. + - **Subagentes:** roteie tarefas de codificação para um agente exclusivo do Codex com seu próprio modelo e padrão de `agentRuntime`. Consulte [Modelos](/pt-BR/concepts/models) e [Comandos de barra](/pt-BR/tools/slash-commands). - + Use uma alternância de sessão ou um padrão de configuração: - - **Por sessão:** envie `/fast on` enquanto a sessão estiver usando `openai/gpt-5.5` ou `openai-codex/gpt-5.5`. + - **Por sessão:** envie `/fast on` enquanto a sessão está usando `openai/gpt-5.5` ou `openai-codex/gpt-5.5`. - **Padrão por modelo:** defina `agents.defaults.models["openai/gpt-5.5"].params.fastMode` ou `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` como `true`. Exemplo: @@ -187,39 +187,42 @@ x-i18n: } ``` - Para OpenAI, o modo rápido mapeia para `service_tier = "priority"` em solicitações nativas Responses compatíveis. Substituições de sessão `/fast` têm precedência sobre padrões de configuração. + Para OpenAI, o modo rápido mapeia para `service_tier = "priority"` em solicitações Responses nativas compatíveis. Substituições de sessão `/fast` prevalecem sobre padrões de configuração. Consulte [Pensamento e modo rápido](/pt-BR/tools/thinking) e [Modo rápido da OpenAI](/pt-BR/providers/openai#fast-mode). - + Se `agents.defaults.models` estiver definido, ele se torna a **allowlist** para `/model` e quaisquer substituições de sessão. Escolher um modelo que não esteja nessa lista retorna: ``` - Model "provider/model" is not allowed. Use /model to list available models. + Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. + Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` Esse erro é retornado **em vez de** uma resposta normal. Correção: adicione o modelo a `agents.defaults.models`, remova a allowlist ou escolha um modelo em `/model list`. + Se o comando também incluiu `--runtime codex`, adicione o modelo primeiro e tente novamente + o mesmo comando `/model provider/model --runtime codex`. - + Isso significa que o **provedor não está configurado** (nenhuma configuração de provedor MiniMax ou perfil de autenticação foi encontrado), então o modelo não pode ser resolvido. Checklist de correção: - 1. Atualize para uma versão atual do OpenClaw (ou execute a partir de `main` no código-fonte) e reinicie o gateway. - 2. Certifique-se de que o MiniMax esteja configurado (assistente ou JSON), ou que a autenticação do MiniMax - exista no env/perfis de autenticação para que o provedor correspondente possa ser injetado - (`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` ou OAuth do MiniMax armazenado + 1. Atualize para uma versão atual do OpenClaw (ou execute a partir do `main` do código-fonte) e reinicie o Gateway. + 2. Certifique-se de que o MiniMax está configurado (assistente ou JSON), ou que a autenticação do MiniMax + existe em env/perfis de autenticação para que o provedor correspondente possa ser injetado + (`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` ou OAuth MiniMax armazenado para `minimax-portal`). - 3. Use o ID de modelo exato (diferencia maiúsculas de minúsculas) para seu caminho de autenticação: - `minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração com chave de API, - ou `minimax-portal/MiniMax-M2.7` / + 3. Use o ID exato do modelo (diferencia maiúsculas de minúsculas) para o seu caminho de autenticação: + `minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração + com chave de API, ou `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed` para configuração com OAuth. 4. Execute: @@ -227,13 +230,13 @@ x-i18n: openclaw models list ``` - e escolha na lista (ou `/model list` no chat). + e escolha a partir da lista (ou `/model list` no chat). Consulte [MiniMax](/pt-BR/providers/minimax) e [Modelos](/pt-BR/concepts/models). - + Sim. Use **MiniMax como padrão** e troque de modelo **por sessão** quando necessário. Fallbacks são para **erros**, não para "tarefas difíceis", então use `/model` ou um agente separado. @@ -270,7 +273,7 @@ x-i18n: - + Sim. O OpenClaw inclui alguns atalhos padrão (aplicados apenas quando o modelo existe em `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` @@ -282,11 +285,11 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Se você definir seu próprio alias com o mesmo nome, o seu valor prevalece. + Se você definir seu próprio alias com o mesmo nome, seu valor prevalece. - + Aliases vêm de `agents.defaults.models..alias`. Exemplo: ```json5 @@ -308,8 +311,8 @@ x-i18n: - - OpenRouter (pagamento por token; muitos modelos): + + OpenRouter (pague por token; muitos modelos): ```json5 { @@ -337,12 +340,12 @@ x-i18n: } ``` - Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`). + Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, você receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`). **Nenhuma chave de API encontrada para o provedor após adicionar um novo agente** Isso geralmente significa que o **novo agente** tem um armazenamento de autenticação vazio. A autenticação é por agente e - fica armazenada em: + armazenada em: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -351,57 +354,57 @@ x-i18n: Opções de correção: - Execute `openclaw agents add ` e configure a autenticação durante o assistente. - - Ou copie apenas perfis portáveis estáticos de `api_key` / `token` do armazenamento de autenticação do agente principal para o armazenamento de autenticação do novo agente. - - Para perfis OAuth, entre a partir do novo agente quando ele precisar da própria conta; caso contrário, o OpenClaw pode ler o agente padrão/principal sem clonar tokens de atualização. + - Ou copie apenas perfis estáticos portáteis de `api_key` / `token` do armazenamento de autenticação do agente principal para o armazenamento de autenticação do novo agente. + - Para perfis OAuth, faça login a partir do novo agente quando ele precisar da própria conta; caso contrário, o OpenClaw pode ler o agente padrão/principal sem clonar tokens de atualização. **Não** reutilize `agentDir` entre agentes; isso causa colisões de autenticação/sessão. -## Failover de modelo e "Todos os modelos falharam" +## Failover de modelos e "Todos os modelos falharam" - + O failover acontece em duas etapas: - 1. **Rotação de perfil de autenticação** dentro do mesmo provedor. + 1. **Rotação de perfis de autenticação** dentro do mesmo provedor. 2. **Fallback de modelo** para o próximo modelo em `agents.defaults.model.fallbacks`. - Cooldowns se aplicam a perfis com falha (backoff exponencial), então o OpenClaw pode continuar respondendo mesmo quando um provedor está com limite de taxa ou falhando temporariamente. + Cooldowns se aplicam aos perfis com falha (backoff exponencial), então o OpenClaw pode continuar respondendo mesmo quando um provedor está limitado por taxa ou falhando temporariamente. O bucket de limite de taxa inclui mais do que respostas `429` simples. O OpenClaw também trata mensagens como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` e limites periódicos - de janela de uso (`weekly/monthly limit reached`) como limites de taxa - que justificam failover. + de janelas de uso (`weekly/monthly limit reached`) como limites de taxa + elegíveis para failover. - Algumas respostas que parecem cobrança não são `402`, e algumas respostas HTTP `402` + Algumas respostas que parecem de cobrança não são `402`, e algumas respostas HTTP `402` também permanecem nesse bucket transitório. Se um provedor retornar - texto explícito de cobrança em `401` ou `403`, o OpenClaw ainda pode mantê-lo - na faixa de cobrança, mas correspondências de texto específicas de provedor permanecem limitadas ao - provedor que as possui (por exemplo, OpenRouter `Key limit exceeded`). Se uma mensagem `402` - parecer, em vez disso, uma janela de uso retentável ou + texto explícito de cobrança em `401` ou `403`, o OpenClaw ainda poderá manter isso na + faixa de cobrança, mas os correspondentes de texto específicos de provedor permanecem no escopo do + provedor ao qual pertencem (por exemplo, OpenRouter `Key limit exceeded`). Se uma mensagem `402` + parecer, em vez disso, uma janela de uso repetível ou limite de gastos de organização/workspace (`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`), o OpenClaw a trata como + `organization spending limit exceeded`), o OpenClaw a tratará como `rate_limit`, não como uma desativação longa por cobrança. Erros de estouro de contexto são diferentes: assinaturas como `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` ou `ollama error: context length - exceeded` permanecem no caminho de Compaction/nova tentativa em vez de avançar o + exceeded` permanecem no caminho de Compaction/tentativa novamente em vez de avançar o fallback de modelo. - Texto genérico de erro de servidor é intencionalmente mais restrito do que "qualquer coisa com - unknown/error nele". O OpenClaw trata formas transitórias com escopo de provedor - como Anthropic puro `An unknown error occurred`, OpenRouter puro - `Provider returned error`, erros de motivo de parada como `Unhandled stop reason: + Texto genérico de erro do servidor é intencionalmente mais restrito do que "qualquer coisa com + unknown/error nele". O OpenClaw trata formatos transitórios com escopo de provedor + como o `An unknown error occurred` simples da Anthropic, o + `Provider returned error` simples do OpenRouter, erros de motivo de parada como `Unhandled stop reason: error`, payloads JSON `api_error` com texto transitório de servidor (`internal server error`, `unknown error, 520`, `upstream error`, `backend error`) e erros de provedor ocupado como `ModelNotReadyException` como - sinais de timeout/sobrecarga que justificam failover quando o contexto do provedor + sinais de timeout/sobrecarga elegíveis para failover quando o contexto do provedor corresponde. Texto genérico de fallback interno como `LLM request failed with an unknown error.` permanece conservador e não aciona fallback de modelo por si só. @@ -425,35 +428,35 @@ x-i18n: **Checklist de correção para "No credentials found for profile anthropic"** - Isso significa que a execução está fixada em um perfil de autenticação Anthropic, mas o Gateway + Isso significa que a execução está fixada em um perfil de autenticação da Anthropic, mas o Gateway não consegue encontrá-lo em seu armazenamento de autenticação. - - **Use Claude CLI** - - Execute `openclaw models auth login --provider anthropic --method cli --set-default` no host do Gateway. + - **Use a Claude CLI** + - Execute `openclaw models auth login --provider anthropic --method cli --set-default` no host do gateway. - **Se você quiser usar uma chave de API em vez disso** - - Coloque `ANTHROPIC_API_KEY` em `~/.openclaw/.env` no **host do Gateway**. + - Coloque `ANTHROPIC_API_KEY` em `~/.openclaw/.env` no **host do gateway**. - Limpe qualquer ordem fixada que force um perfil ausente: ```bash openclaw models auth order clear --provider anthropic ``` - - **Confirme que você está executando comandos no host do Gateway** - - No modo remoto, os perfis de autenticação ficam na máquina do Gateway, não no seu laptop. + - **Confirme que você está executando comandos no host do gateway** + - No modo remoto, perfis de autenticação ficam na máquina do gateway, não no seu laptop. - Se sua configuração de modelo incluir Google Gemini como fallback (ou se você mudou para um atalho do Gemini), o OpenClaw o tentará durante o fallback de modelo. Se você não configurou credenciais do Google, verá `No API key found for provider "google"`. + Se sua configuração de modelo incluir Google Gemini como fallback (ou se você tiver mudado para uma forma abreviada do Gemini), o OpenClaw tentará usá-lo durante o fallback de modelo. Se você não tiver configurado credenciais do Google, verá `No API key found for provider "google"`. - Correção: forneça autenticação do Google ou remova/evite modelos do Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não seja roteado para lá. + Correção: forneça autenticação do Google ou remova/evite modelos do Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não direcione para lá. - **Solicitação LLM rejeitada: assinatura de thinking obrigatória (Google Antigravity)** + **Solicitação de LLM rejeitada: assinatura de pensamento necessária (Google Antigravity)** - Causa: o histórico da sessão contém **blocos de thinking sem assinaturas** (muitas vezes de - um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos de thinking. + Causa: o histórico da sessão contém **blocos de pensamento sem assinaturas** (muitas vezes de + um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos de pensamento. - Correção: o OpenClaw agora remove blocos de thinking não assinados para Google Antigravity Claude. Se ainda aparecer, inicie uma **nova sessão** ou defina `/thinking off` para esse agente. + Correção: o OpenClaw agora remove blocos de pensamento não assinados para o Google Antigravity Claude. Se ainda aparecer, inicie uma **nova sessão** ou defina `/thinking off` para esse agente. @@ -463,78 +466,80 @@ x-i18n: Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamento de tokens, padrões de várias contas) - + Um perfil de autenticação é um registro de credencial nomeado (OAuth ou chave de API) vinculado a um provedor. Os perfis ficam em: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` + Para inspecionar perfis salvos sem expor segredos, execute `openclaw models auth list` (opcionalmente `--provider ` ou `--json`). Consulte [CLI de modelos](/pt-BR/cli/models#openclaw-models-auth-list) para obter detalhes. + - + O OpenClaw usa IDs prefixados por provedor, como: - - `anthropic:default` (comum quando não existe identidade de e-mail) + - `anthropic:default` (comum quando não existe identidade de email) - `anthropic:` para identidades OAuth - IDs personalizados que você escolhe (por exemplo, `anthropic:work`) - + Sim. A configuração aceita metadados opcionais para perfis e uma ordenação por provedor (`auth.order.`). Isso **não** armazena segredos; mapeia IDs para provedor/modo e define a ordem de rotação. O OpenClaw pode ignorar temporariamente um perfil se ele estiver em um **cooldown** curto (limites de taxa/timeouts/falhas de autenticação) ou em um estado **desativado** mais longo (cobrança/créditos insuficientes). Para inspecionar isso, execute `openclaw models status --json` e verifique `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`. - Cooldowns de limite de taxa podem ter escopo de modelo. Um perfil em cooldown + Cooldowns de limite de taxa podem ter escopo por modelo. Um perfil que está em cooldown para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor, enquanto janelas de cobrança/desativação ainda bloqueiam o perfil inteiro. - Você também pode definir uma substituição de ordem **por agente** (armazenada no `auth-state.json` desse agente) via CLI: + Você também pode definir uma substituição de ordem **por agente** (armazenada no `auth-state.json` desse agente) pela CLI: ```bash - # Defaults to the configured default agent (omit --agent) + # Usa como padrão o agente padrão configurado (omita --agent) openclaw models auth order get --provider anthropic - # Lock rotation to a single profile (only try this one) + # Bloquear a rotação em um único perfil (tentar apenas este) openclaw models auth order set --provider anthropic anthropic:default - # Or set an explicit order (fallback within provider) + # Ou definir uma ordem explícita (fallback dentro do provedor) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Clear override (fall back to config auth.order / round-robin) + # Limpar substituição (voltar para config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` - Para direcionar a um agente específico: + Para apontar para um agente específico: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Para verificar o que realmente será tentado, use: + Para verificar o que será realmente tentado, use: ```bash openclaw models status --probe ``` - Se um perfil armazenado for omitido da ordem explícita, o probe reportará - `excluded_by_auth_order` para esse perfil em vez de tentá-lo silenciosamente. + Se um perfil armazenado for omitido da ordem explícita, a sondagem relata + `excluded_by_auth_order` para esse perfil em vez de tentar silenciosamente. - + O OpenClaw aceita ambos: - - **OAuth** geralmente aproveita acesso por assinatura (quando aplicável). + - **OAuth** muitas vezes aproveita o acesso por assinatura (quando aplicável). - **Chaves de API** usam cobrança por token. - O assistente oferece suporte explicitamente ao Anthropic Claude CLI, OpenAI Codex OAuth e chaves de API. + O assistente oferece suporte explicitamente à Anthropic Claude CLI, ao OpenAI Codex OAuth e a chaves de API. -## Relacionado +## Relacionados - [FAQ](/pt-BR/help/faq) — a FAQ principal - [FAQ — início rápido e configuração da primeira execução](/pt-BR/help/faq-first-run) diff --git a/docs/pt-BR/help/testing-updates-plugins.md b/docs/pt-BR/help/testing-updates-plugins.md index 988f1330e..cad9a0114 100644 --- a/docs/pt-BR/help/testing-updates-plugins.md +++ b/docs/pt-BR/help/testing-updates-plugins.md @@ -1,44 +1,44 @@ --- read_when: - Alterar o comportamento de atualização, doctor, aceitação de pacote ou instalação de Plugin do OpenClaw - - Preparando ou aprovando uma versão candidata a lançamento - - Depuração de regressões de atualização de pacote, limpeza de dependências de Plugin ou instalação de Plugin + - Preparar ou aprovar uma versão candidata a lançamento + - Depuração de regressões em atualizações de pacote, limpeza de dependências de Plugin ou instalação de Plugin sidebarTitle: Update and plugin tests summary: Como o OpenClaw valida caminhos de atualização, migrações de pacotes e o comportamento de instalação/atualização de Plugin title: 'Testes: atualizações e plugins' x-i18n: - generated_at: "2026-05-03T21:34:18Z" + generated_at: "2026-05-05T01:47:46Z" model: gpt-5.5 provider: openai - source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd + source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286 source_path: help/testing-updates-plugins.md workflow: 16 --- Esta é a checklist dedicada para validação de atualização e Plugin. O objetivo é -simples: provar que o pacote instalável consegue atualizar o estado real do usuário, reparar estado -legado obsoleto por meio de `doctor` e ainda instalar, carregar, atualizar e desinstalar -Plugins das fontes compatíveis. +simples: provar que o pacote instalável consegue atualizar o estado real do +usuário, reparar estado legado obsoleto por meio de `doctor` e ainda instalar, +carregar, atualizar e desinstalar Plugins a partir das fontes compatíveis. Para o mapa mais amplo do executor de testes, consulte [Testes](/pt-BR/help/testing). Para chaves de provedores -ao vivo e suítes que acessam a rede, consulte [Testes ao vivo](/pt-BR/help/testing-live). +ao vivo e suítes que tocam a rede, consulte [Testes ao vivo](/pt-BR/help/testing-live). ## O que protegemos Os testes de atualização e Plugin protegem estes contratos: -- Um tarball de pacote está completo, tem um `dist/postinstall-inventory.json` válido - e não depende de arquivos de repositório não empacotados. +- Um tarball de pacote está completo, tem um `dist/postinstall-inventory.json` + válido e não depende de arquivos descompactados do repositório. - Um usuário pode migrar de um pacote publicado mais antigo para o pacote candidato sem perder configuração, agentes, sessões, workspaces, allowlists de Plugin ou configuração de canal. - `openclaw doctor --fix --non-interactive` é responsável pelos caminhos de limpeza e reparo - legados. A inicialização não deve acumular migrações ocultas de compatibilidade para estado + legados. A inicialização não deve ganhar migrações de compatibilidade ocultas para estado obsoleto de Plugin. -- Instalações de Plugin funcionam a partir de diretórios locais, repositórios git, pacotes npm e do +- Instalações de Plugin funcionam a partir de diretórios locais, repositórios git, pacotes npm e o caminho de registro do ClawHub. - Dependências npm de Plugin são instaladas na raiz npm gerenciada, verificadas antes - da confiança e removidas por meio do npm durante a desinstalação para que dependências içadas não + da confiança e removidas pelo npm durante a desinstalação para que dependências içadas não permaneçam. - A atualização de Plugin é estável quando nada mudou: registros de instalação, fonte resolvida, layout de dependências instaladas e estado habilitado permanecem intactos. @@ -54,30 +54,30 @@ pnpm test:changed ``` Para alterações de instalação, desinstalação, dependência ou inventário de pacote de Plugin, também -execute os testes focados que cobrem o ponto editado: +execute os testes focados que cobrem a interface editada: ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -Antes que qualquer lane Docker de pacote consuma um tarball, prove o artefato do pacote: +Antes que qualquer pista Docker de pacote consuma um tarball, prove o artefato do pacote: ```bash pnpm release:check ``` -`release:check` executa verificações de drift de configuração/docs/API, grava o inventário de distribuição +`release:check` executa verificações de divergência de configuração/docs/API, grava o inventário de dist do pacote, executa `npm pack --dry-run`, rejeita arquivos empacotados proibidos, instala -o tarball em um prefixo temporário, executa postinstall e testa superficialmente os entrypoints de canais +o tarball em um prefixo temporário, executa postinstall e faz smoke de entrypoints de canais incluídos. -## Lanes Docker +## Pistas Docker -As lanes Docker são a prova em nível de produto. Elas instalam ou atualizam um pacote real -dentro de contêineres Linux e verificam o comportamento por meio de comandos CLI, -inicialização do Gateway, probes HTTP, status RPC e estado do sistema de arquivos. +As pistas Docker são a prova em nível de produto. Elas instalam ou atualizam um pacote real +dentro de contêineres Linux e verificam o comportamento por meio de comandos da CLI, +inicialização do Gateway, sondas HTTP, status RPC e estado do sistema de arquivos. -Use lanes focadas durante a iteração: +Use pistas focadas durante a iteração: ```bash pnpm test:docker:plugins @@ -88,36 +88,36 @@ pnpm test:docker:published-upgrade-survivor pnpm test:docker:update-migration ``` -Lanes importantes: +Pistas importantes: - `test:docker:plugins` valida smoke de instalação de Plugin, instalações de pasta local, - comportamento de ignorar atualização de pasta local, pastas locais com - dependências pré-instaladas, instalações de pacote `file:`, instalações git com execução de CLI, atualizações de - referência móvel git, instalações de registro npm com dependências transitivas - içadas, no-ops de atualização npm, instalações de fixture local do ClawHub e no-ops de atualização, - comportamento de atualização do marketplace e habilitação/inspeção do pacote Claude. Defina + comportamento de ignorar atualização de pasta local, pastas locais com dependências + pré-instaladas, instalações de pacote `file:`, instalações git com execução via CLI, atualizações + de referência móvel git, instalações de registro npm com dependências transitivas + içadas, no-ops de atualização npm, instalações de fixture local do ClawHub e no-ops de + atualização, comportamento de atualização do marketplace e habilitação/inspeção de pacote Claude. Defina `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` para manter o bloco do ClawHub hermético/offline. - `test:docker:plugin-lifecycle-matrix` instala o pacote candidato em um contêiner vazio, executa um Plugin npm por instalação, inspeção, desabilitação, habilitação, upgrade explícito, downgrade explícito e desinstalação após excluir o código do Plugin. Ele registra métricas de RSS e CPU para cada fase. -- `test:docker:plugin-update` valida que um Plugin instalado sem alterações não - reinstala nem perde metadados de instalação durante `openclaw plugins update`. -- `test:docker:upgrade-survivor` instala o tarball candidato sobre uma fixture de usuário antigo - suja, executa atualização de pacote mais doctor não interativo, depois inicia +- `test:docker:plugin-update` valida que um Plugin instalado inalterado não + é reinstalado nem perde metadados de instalação durante `openclaw plugins update`. +- `test:docker:upgrade-survivor` instala o tarball candidato sobre uma fixture + suja de usuário antigo, executa atualização de pacote mais doctor não interativo e então inicia um Gateway de loopback e verifica a preservação de estado. - `test:docker:published-upgrade-survivor` primeiro instala uma baseline publicada, configura-a por meio de uma receita `openclaw config set` embutida, atualiza-a para o - tarball candidato, executa doctor, verifica a limpeza legada, inicia o Gateway e - testa `/healthz`, `/readyz` e status RPC. -- `test:docker:update-migration` é a lane de atualização publicada com muita limpeza. Ela - começa a partir de um estado de usuário configurado no estilo Discord/Telegram, executa o - doctor da baseline para que dependências de Plugin configuradas tenham a chance de se materializar, semeia - detritos legados de dependências de Plugin para um Plugin empacotado configurado, atualiza para + tarball candidato, executa doctor, verifica limpeza legada, inicia o Gateway e + sonda `/healthz`, `/readyz` e status RPC. +- `test:docker:update-migration` é a pista de atualização publicada com forte foco em limpeza. Ela + começa com um estado de usuário configurado no estilo Discord/Telegram, executa doctor + da baseline para que dependências de Plugin configurado tenham chance de se materializar, semeia + resíduos legados de dependências de Plugin para um Plugin empacotado configurado, atualiza para o tarball candidato e exige que o doctor pós-atualização remova as raízes legadas - de dependência. + de dependências. -Variantes úteis do survivor de upgrade publicado: +Variantes úteis de published-upgrade survivor: ```bash OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \ @@ -130,15 +130,15 @@ pnpm test:docker:published-upgrade-survivor ``` Os cenários disponíveis são `base`, `feishu-channel`, `bootstrap-persona`, -`plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path` e -`versioned-runtime-deps`. Em execuções agregadas, +`plugin-deps-cleanup`, `configured-plugin-installs`, +`stale-source-plugin-shadow`, `tilde-log-path` e `versioned-runtime-deps`. Em execuções agregadas, `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` expande para todos os cenários -com formato de issues reportadas, incluindo a migração de instalação de Plugin configurado. +com formato de problemas relatados, incluindo a migração de instalação de Plugin configurado. -A migração completa de atualização é intencionalmente separada da CI de Release Completa. Use o -workflow manual `Update Migration` quando a pergunta de release for "cada -release estável publicado desde 2026.4.23 em diante consegue atualizar para este candidato e -limpar detritos de dependências de Plugin?": +A migração completa de atualização é intencionalmente separada da CI de Full Release. Use o +workflow manual `Update Migration` quando a pergunta de release for "toda +release estável publicada a partir de 2026.4.23 consegue atualizar para este candidato e +limpar resíduos de dependências de Plugin?": ```bash gh workflow run update-migration.yml \ @@ -152,24 +152,24 @@ gh workflow run update-migration.yml \ ## Package Acceptance Package Acceptance é o gate de pacote nativo do GitHub. Ele resolve um pacote -candidato em um tarball `package-under-test`, registra versão e SHA-256, depois -executa lanes Docker E2E reutilizáveis contra esse tarball exato. A ref do harness de workflow -é separada da ref de origem do pacote, então a lógica de teste atual pode validar -releases confiáveis mais antigos. +candidato em um tarball `package-under-test`, registra versão e SHA-256 e então +executa pistas Docker E2E reutilizáveis contra esse tarball exato. O ref do harness +do workflow é separado do ref de origem do pacote, para que a lógica de teste atual possa validar +releases confiáveis mais antigas. Fontes candidatas: -- `source=npm`: validar `openclaw@beta`, `openclaw@latest` ou uma versão - publicada exata. -- `source=ref`: empacotar um branch, tag ou commit confiável com o harness atual +- `source=npm`: valida `openclaw@beta`, `openclaw@latest` ou uma versão publicada + exata. +- `source=ref`: empacota uma branch, tag ou commit confiável com o harness atual selecionado. -- `source=url`: validar um tarball HTTPS com `package_sha256` obrigatório. -- `source=artifact`: reutilizar um tarball enviado por outra execução do Actions. +- `source=url`: valida um tarball HTTPS com `package_sha256` obrigatório. +- `source=artifact`: reutiliza um tarball enviado por outra execução do Actions. Full Release Validation usa `source=artifact` por padrão, criado a partir do SHA de release resolvido. Para prova pós-publicação, passe `package_acceptance_package_spec=openclaw@YYYY.M.D` para que a mesma matriz de upgrade -tenha como alvo o pacote npm entregue. +mire o pacote npm entregue. As verificações de release chamam Package Acceptance com o conjunto de pacote/atualização/Plugin: @@ -187,15 +187,14 @@ telegram_mode=mock-openai Isso mantém migração de pacote, troca de canal de atualização, limpeza de dependências obsoletas de Plugin, cobertura offline de Plugin, comportamento de atualização de Plugin e QA de pacote -do Telegram no mesmo artefato resolvido. +Telegram no mesmo artefato resolvido. -`all-since-2026.4.23` é a amostra de upgrade da CI de Release Completa: todo release estável publicado no npm de `2026.4.23` até `latest`. Para cobertura exaustiva de migração de atualização -publicada, use `all-since-2026.4.23` no workflow Update -Migration separado em vez da CI de Release Completa. `release-history` permanece -disponível para amostragem manual mais ampla quando você também quiser a âncora -legada anterior à data. +`all-since-2026.4.23` é a amostra de upgrade da CI de Full Release: todas as releases estáveis publicadas no npm de `2026.4.23` até `latest`. Para cobertura exaustiva de migração de +atualização publicada, use `all-since-2026.4.23` no workflow separado Update +Migration em vez da CI de Full Release. `release-history` permanece +disponível para amostragem manual mais ampla quando você também quiser a âncora legada anterior à data. -Execute um perfil de pacote manualmente ao validar um candidato antes do release: +Execute um perfil de pacote manualmente ao validar um candidato antes da release: ```bash gh workflow run package-acceptance.yml \ @@ -210,58 +209,56 @@ gh workflow run package-acceptance.yml \ ``` Use `suite_profile=product` quando a pergunta de release incluir canais MCP, -limpeza de cron/subagente, pesquisa web da OpenAI ou OpenWebUI. Use `suite_profile=full` -somente quando precisar de cobertura completa do caminho de release Docker. +limpeza de cron/subagente, busca web da OpenAI ou OpenWebUI. Use `suite_profile=full` +somente quando precisar de cobertura completa de caminho de release Docker. ## Padrão de release -Para candidatos a release, a pilha de prova padrão é: +Para candidatas a release, a pilha de prova padrão é: 1. `pnpm check:changed` e `pnpm test:changed` para regressões em nível de código-fonte. 2. `pnpm release:check` para integridade do artefato de pacote. -3. Perfil Package Acceptance `package` ou as lanes customizadas de pacote +3. Perfil `package` do Package Acceptance ou as pistas customizadas de pacote de release-check para contratos de instalação/atualização/Plugin. -4. Verificações de release entre sistemas operacionais para instalador, onboarding e comportamento - de plataforma específicos de OS. -5. Suítes ao vivo somente quando a superfície alterada toca comportamento de provedor ou serviço - hospedado. +4. Verificações de release entre sistemas operacionais para comportamento específico de instalador, onboarding e plataforma. +5. Suítes ao vivo somente quando a superfície alterada toca comportamento de provedor ou serviço hospedado. -Em máquinas de mantenedores, gates amplos e prova de produto Docker/pacote devem executar -no Testbox, a menos que a prova local esteja sendo feita explicitamente. +Em máquinas de mantenedores, gates amplos e prova de produto Docker/pacote devem ser executados +no Testbox, salvo prova local explícita. ## Compatibilidade legada -A leniência de compatibilidade é restrita e temporária: +A tolerância de compatibilidade é restrita e com prazo definido: - Pacotes até `2026.4.25`, incluindo `2026.4.25-beta.*`, podem tolerar lacunas de metadados de pacote já entregues no Package Acceptance. -- O pacote `2026.4.26` publicado pode emitir avisos para arquivos de carimbo de metadados +- O pacote publicado `2026.4.26` pode alertar sobre arquivos de carimbo de metadados de build local já entregues. - Pacotes posteriores devem satisfazer contratos modernos. As mesmas lacunas falham em vez de - avisar ou pular. + gerar alerta ou serem ignoradas. Não adicione novas migrações de inicialização para esses formatos antigos. Adicione ou estenda um reparo -de doctor, depois prove-o com `upgrade-survivor` ou `published-upgrade-survivor`. +de doctor e então prove com `upgrade-survivor` ou `published-upgrade-survivor`. ## Adicionando cobertura Ao alterar comportamento de atualização ou Plugin, adicione cobertura na camada mais baixa que -possa falhar pelo motivo correto: +possa falhar pelo motivo certo: - Lógica pura de caminho ou metadados: teste unitário ao lado do código-fonte. -- Comportamento de inventário de pacote ou arquivo empacotado: teste `package-dist-inventory` ou do verificador - de tarball. -- Comportamento de instalação/atualização da CLI: asserção ou fixture de lane Docker. -- Comportamento de migração de release publicado: cenário `published-upgrade-survivor`. -- Comportamento de registro/fonte de pacote: fixture `test:docker:plugins` ou servidor de fixture - do ClawHub. +- Inventário de pacote ou comportamento de arquivos empacotados: `package-dist-inventory` ou teste + de verificador de tarball. +- Comportamento de instalação/atualização da CLI: asserção ou fixture de pista Docker. +- Comportamento de migração de release publicada: cenário `published-upgrade-survivor`. +- Comportamento de fonte de registro/pacote: fixture `test:docker:plugins` ou servidor + de fixture do ClawHub. - Comportamento de layout ou limpeza de dependências: verifique tanto a execução em runtime quanto a - fronteira do sistema de arquivos. Dependências npm podem ser içadas sob a raiz npm gerenciada, - então os testes devem provar que a raiz é verificada/limpa em vez de assumir uma árvore + fronteira do sistema de arquivos. Dependências npm podem ser içadas sob a raiz npm + gerenciada, então os testes devem provar que a raiz é verificada/limpa em vez de assumir uma árvore `node_modules` local ao pacote. -Mantenha novas fixtures Docker herméticas por padrão. Use registros de fixture locais e -pacotes falsos, a menos que o ponto do teste seja o comportamento de registro ao vivo. +Mantenha novas fixtures Docker herméticas por padrão. Use registros de fixtures locais e +pacotes falsos, a menos que o objetivo do teste seja comportamento de registro ao vivo. ## Triagem de falhas @@ -270,10 +267,10 @@ Comece pela identidade do artefato: - Resumo `resolve_package` do Package Acceptance: fonte, versão, SHA-256 e nome do artefato. - Artefatos Docker: `.artifacts/docker-tests/**/summary.json`, - `failures.json`, logs de lane e comandos de nova execução. -- Resumo do upgrade survivor: `.artifacts/upgrade-survivor/summary.json`, - incluindo versão da baseline, versão candidata, cenário, tempos de fase e + `failures.json`, logs de pista e comandos de nova execução. +- Resumo de upgrade survivor: `.artifacts/upgrade-survivor/summary.json`, + incluindo versão baseline, versão candidata, cenário, tempos de fase e etapas da receita. -Prefira executar novamente a lane exata que falhou com o mesmo artefato de pacote em vez de +Prefira executar novamente a pista exata com falha com o mesmo artefato de pacote em vez de executar novamente todo o guarda-chuva de release. diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index fe35fc175..60be43809 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -2,32 +2,32 @@ read_when: - Executando testes localmente ou na CI - Adicionando testes de regressão para bugs de modelo/provedor - - Depuração do comportamento do Gateway + agente + - Depuração do comportamento do Gateway + do agente summary: 'Kit de testes: suítes unitárias/e2e/ao vivo, executores Docker e o que cada teste cobre' title: Testes x-i18n: - generated_at: "2026-05-04T07:03:04Z" + generated_at: "2026-05-05T01:47:49Z" model: gpt-5.5 provider: openai - source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 + source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 source_path: help/testing.md workflow: 16 --- -O OpenClaw tem três suítes Vitest (unitária/integração, e2e, live) e um pequeno conjunto +OpenClaw tem três suítes Vitest (unitária/integração, e2e, live) e um pequeno conjunto 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, pré-push, depuração). - Como os testes live descobrem credenciais e selecionam modelos/provedores. -- Como adicionar regressões para problemas reais de modelo/provedor. +- Como adicionar regressões para problemas reais de modelos/provedores. -**Stack de QA (qa-lab, qa-channel, lanes de transporte live)** é documentada separadamente: +**A pilha de QA (qa-lab, qa-channel, lanes de transporte live)** é documentada separadamente: -- [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) — arquitetura, superfície de comandos, criação de cenários. +- [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 baseados no repositório. +- [Canal de QA](/pt-BR/channels/qa-channel) — o Plugin de transporte sintético usado por cenários respaldados 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. @@ -38,183 +38,192 @@ 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 direto do Vitest em modo observação: `pnpm test:watch` -- O direcionamento direto de arquivo 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 arquivos agora também roteia caminhos de extensão/canal: `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 baseado em Docker: `pnpm qa:lab:up` -- Lane de QA baseada em VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Site de QA com suporte do Docker: `pnpm qa:lab:up` +- Lane de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você toca em testes ou quer confiança extra: +Quando você altera testes ou quer confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` Ao depurar provedores/modelos reais (exige credenciais reais): -- Suíte live (modelos + sondagens de ferramenta/imagem do Gateway): `pnpm test:live` -- Direcione um arquivo live silenciosamente: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Relatórios de desempenho em tempo de execução: dispare `OpenClaw Performance` com - `live_gpt54=true` para uma rodada real de agente `openai/gpt-5.4` ou +- Suíte live (modelos + sondas de ferramenta/imagem do Gateway): `pnpm test:live` +- Direcione um arquivo live de forma silenciosa: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Relatórios de desempenho em runtime: dispare `OpenClaw Performance` com + `live_gpt54=true` para uma interação real de agente `openai/gpt-5.4` ou `deep_profile=true` para artefatos de CPU/heap/trace do Kova. Execuções diárias agendadas - publicam artefatos das lanes de provedor simulado, perfil profundo e GPT 5.4 em + publicam artefatos das lanes mock-provider, deep-profile e GPT 5.4 em `openclaw/clawgrit-reports` quando `CLAWGRIT_REPORTS_TOKEN` está configurado. O - relatório de provedor simulado também inclui números em nível de código-fonte para inicialização do Gateway, - memória, pressão de plugins, loop hello repetido com modelo falso e inicialização da CLI. -- Varredura live de modelos em Docker: `pnpm test:docker:live-models` - - Cada modelo selecionado agora executa uma rodada de texto mais uma pequena sondagem no estilo leitura de arquivo. - Modelos cujos metadados anunciam entrada `image` também executam uma pequena rodada de imagem. - Desative as sondagens extras com `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou + relatório mock-provider também inclui números em nível de código-fonte de inicialização do gateway, memória, + pressão de plugins, loop hello repetido de modelo falso e inicialização da CLI. +- Varredura de modelos live no Docker: `pnpm test:docker:live-models` + - Cada modelo selecionado agora executa uma interação de texto mais uma pequena sonda no estilo de leitura de arquivo. + Modelos cujos metadados anunciam entrada `image` também executam uma pequena interação com imagem. + Desative as sondas extras com `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` ao isolar falhas de provedor. - - Cobertura de CI: `OpenClaw Scheduled Live And E2E Checks` diário e - `OpenClaw Release Checks` manual chamam o fluxo reutilizável live/E2E com - `include_live_suites: true`, que inclui jobs separados da matriz live de modelos em Docker + - Cobertura de CI: `OpenClaw Scheduled Live And E2E Checks` diária e + `OpenClaw Release Checks` manual chamam o fluxo de trabalho live/E2E reutilizável com + `include_live_suites: true`, que inclui jobs separados de matriz de modelos live no Docker divididos por provedor. - - Para reexecuções focadas em CI, dispare `OpenClaw Live And E2E Checks (Reusable)` + - Para reexecuções de CI focadas, dispare `OpenClaw Live And E2E Checks (Reusable)` com `include_live_suites: true` e `live_models_only: true`. - Adicione novos segredos de provedor 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 lane live em Docker contra o caminho do servidor de app 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 pelo vínculo nativo do Plugin em vez do ACP. -- Smoke do harness do servidor de app do Codex: `pnpm test:docker:live-codex-harness` - - Executa rodadas de agente do Gateway pelo harness do servidor de app 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 app do Codex. Para uma verificação focada de subagente, desative as outras sondagens: + - Executa uma lane live do Docker contra o caminho do app-server 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 uma rota de anexo de imagem + pela vinculação nativa do Plugin em vez de ACP. +- Smoke do harness do app-server do Codex: `pnpm test:docker:live-codex-harness` + - Executa interações de agente do gateway pelo harness do app-server do Codex de propriedade do Plugin, + verifica `/codex status` e `/codex models`, e por padrão exercita sondas de imagem, + MCP de Cron, subagente e Guardian. Desative a sonda de subagente com + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` ao isolar outras falhas do app-server do 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 + Isto sai 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 opcional com redundância extra para a superfície do comando de resgate de canal de mensagens. - Ela exercita `/crestodian status`, enfileira uma mudança persistente de modelo, + - Verificação opcional de reforço 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 escrita de auditoria/configuração. - Smoke Docker do planejador do 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 se traduz em uma escrita tipada - de configuração auditada. + e verifica se o fallback do planejador fuzzy se traduz em uma escrita de configuração tipada auditada. - Smoke Docker da primeira execução do Crestodian: `pnpm test:docker:crestodian-first-run` - - Começa a partir de um diretório de estado vazio do OpenClaw, roteia `openclaw` puro para - o Crestodian, aplica escritas de setup/modelo/agente/Plugin Discord + SecretRef, + - Começa de um diretório de estado vazio do OpenClaw, roteia `openclaw` puro para + o Crestodian, aplica setup/modelo/agente/Plugin do Discord + escritas SecretRef, valida a configuração e verifica entradas de auditoria. O mesmo caminho de setup 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 models list --provider moonshot --json`, então 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 se o JSON reporta Moonshot/K2.6 e se a transcrição do assistente armazena `usage.cost` normalizado. -Quando você só precisa de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. +Quando você só precisa de um caso com falha, prefira restringir testes live pelas variáveis de ambiente de allowlist descritas abaixo. ## Executores específicos de QA -Estes comandos ficam ao lado das suítes de teste principais quando você precisa do realismo do QA-lab: +Estes comandos ficam ao lado das principais suítes de teste quando você precisa de realismo do QA-lab: -A CI executa o QA Lab em fluxos dedicados. A paridade agêntica fica aninhada em -`QA-Lab - All Lanes` e validação de release, não em um fluxo de PR autônomo. +A CI executa o QA Lab em fluxos de trabalho dedicados. A paridade agentic fica aninhada em +`QA-Lab - All Lanes` e validação de release, não em um fluxo de trabalho de PR independente. A validação ampla deve usar `Full Release Validation` com -`rerun_group=qa-parity` ou o grupo de QA dos checks de release. `QA-Lab - All Lanes` -é executado todas as noites em `main` e por despacho manual com a lane de paridade simulada, a lane live -Matrix, a lane live Telegram gerenciada pelo Convex e a lane live Discord -gerenciada pelo Convex como jobs paralelos. QA agendado e checks de release passam Matrix -`--profile fast` explicitamente, enquanto a CLI Matrix e a entrada do fluxo manual -permanecem com padrão `all`; o despacho manual pode dividir `all` em jobs `transport`, -`media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. `OpenClaw Release -Checks` executa paridade mais as lanes rápidas de Matrix e Telegram antes da aprovação -de release, usando `mock-openai/gpt-5.5` para checks de transporte de release para que eles permaneçam -determinísticos e evitem a inicialização normal do Plugin de provedor. Esses Gateways de transporte live -desativam busca de memória; o comportamento de memória permanece coberto pelas suítes de paridade de QA. +`rerun_group=qa-parity` ou o grupo de QA de release-checks. As verificações de release estáveis/padrão +mantêm o soak live/Docker exaustivo atrás de `run_release_soak=true`; o +perfil `full` força o soak. `QA-Lab - All Lanes` +executa todas as noites em `main` e por despacho manual com a lane de paridade mock, lane live +Matrix, lane live Telegram gerenciada pelo Convex e lane live Discord +gerenciada pelo Convex como jobs paralelos. QA agendado e verificações de release passam Matrix +`--profile fast` explicitamente, enquanto a CLI Matrix e a entrada manual do fluxo de trabalho +permanecem por padrão como `all`; o despacho manual pode fragmentar `all` em jobs +`transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. `OpenClaw Release +Checks` executa paridade mais 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 live +desativam a busca de memória; o comportamento de memória permanece coberto pelas suítes de paridade de QA. -Os shards live de mídia de release completo usam +Shards de mídia live de release completo usam `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, que já tem -`ffmpeg` e `ffprobe`. Shards Docker live de modelo/backend usam a imagem compartilhada -`ghcr.io/openclaw/openclaw-live-test:` construída uma vez por commit selecionado, -então a baixam com `OPENCLAW_SKIP_DOCKER_BUILD=1` em vez de reconstruir +`ffmpeg` e `ffprobe`. Shards Docker de modelo/backend live usam a imagem compartilhada +`ghcr.io/openclaw/openclaw-live-test:` criada uma vez por commit selecionado, +então 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 cenários de QA apoiados pelo repositório diretamente no host. - Executa vários cenários selecionados em paralelo por padrão com workers de 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 lane serial mais antiga. + contagem de cenários selecionados). Use `--concurrency ` para ajustar + a contagem de workers, ou `--concurrency 1` para a lane serial mais 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. - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. - `aimock` inicia um servidor de provedor local baseado em AIMock para cobertura - experimental de fixtures e mocks de protocolo sem substituir a lane - `mock-openai` ciente de cenários. + `aimock` inicia um servidor de provedor local apoiado por AIMock para cobertura + experimental de fixtures e simulação de protocolo sem substituir a lane + `mock-openai` com reconhecimento de cenário. +- `pnpm test:plugins:kitchen-sink-live` + - Executa a prova completa do Plugin OpenAI Kitchen Sink ao vivo pelo QA Lab. Ele + instala o pacote externo Kitchen Sink, verifica o inventário da superfície do SDK de Plugin, + testa `/healthz` e `/readyz`, registra evidências de CPU/RSS do Gateway, + executa uma interação OpenAI ao vivo e verifica diagnósticos adversariais. + Requer autenticação OpenAI ao vivo, como `OPENAI_API_KEY`. Em sessões Testbox + hidratadas, ele carrega automaticamente o perfil de autenticação ao vivo do Testbox quando o + helper `openclaw-testbox-env` está presente. - `pnpm test:gateway:cpu-scenarios` - - Executa o bench de inicialização do Gateway mais um pequeno pacote de cenários mock do QA Lab + - Executa o benchmark de inicialização do Gateway mais um pequeno pacote de cenários simulados 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 alta (`--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 travado por minutos. + - Sinaliza apenas observações sustentadas de CPU alta por padrão (`--cpu-core-warn` + 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 travado por minutos. - Usa artefatos `dist` compilados; 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 Multipass descartável. - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host. - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`. - - Execuções live encaminham as entradas de autenticação de QA suportadas que são práticas para o guest: - chaves de provedor baseadas em env, o caminho de configuração de provedor live 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 convidado: + chaves de provedor 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 + - Diretórios de saída devem permanecer sob a raiz do repositório para que o convidado 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 baseado em Docker para trabalho de QA no estilo de operador. + - Inicia o site de QA apoiado por Docker para trabalho de QA no estilo de operador. - `pnpm test:docker:npm-onboard-channel-agent` - Cria 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 que o runtime do plugin empacotado carrega sem reparo de - dependências na inicialização, executa doctor e executa uma rodada de agente local contra um - endpoint OpenAI mockado. + Docker, executa onboarding não interativo com chave de API da OpenAI, configura Telegram + por padrão, verifica que o runtime do Plugin empacotado carrega sem reparo de dependências + na inicialização, executa doctor e executa uma interação de agente local contra um + endpoint OpenAI 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 determinístico em Docker do app compilado para transcrições de contexto de runtime - incorporado. Ele verifica que o contexto de runtime oculto do OpenClaw é persistido como uma - mensagem customizada sem exibição em vez de vazar para a rodada visível do usuário, - depois semeia um JSONL de sessão quebrada afetada e verifica que - `openclaw doctor --fix` o reescreve para o branch ativo com backup. + - Executa um smoke determinístico no Docker do aplicativo compilado para transcrições de contexto de runtime + incorporado. Ele verifica que o contexto oculto de runtime do OpenClaw é persistido como uma + mensagem personalizada sem exibição, em vez de vazar para a interação visível do usuário, + então semeia um JSONL de sessão quebrada afetada e verifica que + `openclaw doctor --fix` o reescreve para a branch ativa com um backup. - `pnpm test:docker:npm-telegram-live` - - Instala um candidato de pacote OpenClaw no Docker, executa onboarding de pacote instalado, - configura Telegram pela CLI instalada, depois reutiliza a lane de QA live do Telegram - com esse pacote instalado como o Gateway SUT. - - Usa `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` por padrão; defina + - Instala uma candidata 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. + instalar a partir do registro. - Usa as mesmas credenciais 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 da 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 de função. Se + `OPENCLAW_QA_CONVEX_SITE_URL` e um segredo de função Convex estiverem presentes em CI, o wrapper Docker seleciona Convex automaticamente. - O wrapper valida o env de credenciais Telegram ou Convex no host antes do - trabalho de build/install do Docker. Defina `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` - apenas ao depurar deliberadamente a configuração pré-credenciais. + trabalho de build/instalação do Docker. Defina `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` + somente ao depurar deliberadamente a configuração pré-credenciais. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` substitui o - `OPENCLAW_QA_CREDENTIAL_ROLE` compartilhado apenas para esta lane. - - O GitHub Actions expõe esta lane como o workflow manual de mantenedor - `NPM Telegram Beta E2E`. Ele não executa em merge. O workflow usa o - ambiente `qa-live-shared` e leases de credenciais de CI do Convex. -- O 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, spec npm publicada, + `OPENCLAW_QA_CREDENTIAL_ROLE` compartilhado somente para esta lane. + - GitHub Actions expõe esta lane como o workflow manual de maintainer + `NPM Telegram Beta E2E`. Ela não é executada no merge. O workflow usa o ambiente + `qa-live-shared` e leases de credenciais 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, faz upload - do `openclaw-current.tgz` normalizado como `package-under-test`, depois executa o + do `openclaw-current.tgz` normalizado como `package-under-test`, então executa o agendador Docker E2E existente com perfis de lane smoke, package, product, full ou custom. - Defina `telegram_mode=mock-openai` ou `live-frontier` para executar o - workflow de QA do Telegram contra o mesmo artefato `package-under-test`. + Defina `telegram_mode=mock-openai` ou `live-frontier` para executar o workflow de QA + Telegram contra o mesmo artefato `package-under-test`. - Prova de produto da beta mais recente: ```bash @@ -225,7 +234,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Prova de URL exata de tarball exige um digest: +- Prova por URL exata de tarball requer um digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -235,7 +244,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Prova de artefato baixa um artefato de tarball de outra execução do Actions: +- Prova por artefato baixa um artefato de tarball de outra execução do Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -247,26 +256,26 @@ gh workflow run package-acceptance.yml --ref main \ - `pnpm test:docker:plugins` - Empacota e instala a build atual do OpenClaw no Docker, inicia o Gateway - com OpenAI configurada e então habilita canais/plugins incluídos por meio de edições + com OpenAI configurado, então habilita canais/plugins incluídos por meio de edições de configuração. - - Verifica que a descoberta de setup mantém plugins baixáveis não configurados ausentes, - que o primeiro reparo configurado pelo doctor instala explicitamente cada - plugin baixável ausente e que uma segunda reinicialização não executa reparo - oculto de dependências. - - Também instala uma baseline npm antiga conhecida, habilita Telegram antes de executar - `openclaw update --tag ` e verifica que o doctor pós-update do candidato - limpa detritos de dependências de plugins legados sem um reparo de postinstall - pelo lado do harness. + - Verifica que a descoberta de setup deixa plugins baixáveis não configurados ausentes, + que o primeiro reparo configurado do doctor instala explicitamente cada Plugin + baixável ausente e que uma segunda reinicialização não executa reparo oculto + de dependências. + - Também instala uma linha de base npm mais antiga conhecida, habilita Telegram antes de executar + `openclaw update --tag ` e verifica que o doctor pós-atualização + da candidata limpa detritos de dependências legadas de Plugin sem um + reparo postinstall no lado do harness. - `pnpm test:parallels:npm-update` - - Executa o smoke nativo de update de instalação empacotada em guests Parallels. Cada - plataforma selecionada primeiro instala o pacote baseline solicitado, depois executa - o comando `openclaw update` instalado no mesmo guest e verifica a versão instalada, - o status do update, a prontidão do Gateway e uma rodada de agente local. - - Use `--platform macos`, `--platform windows` ou `--platform linux` ao - iterar em um guest. Use `--json` para o caminho do artefato de resumo e - o status por lane. - - A lane OpenAI usa `openai/gpt-5.5` por padrão para a prova live de rodada de agente. - Passe `--model ` ou defina + - Executa o smoke nativo de atualização de instalação empacotada em convidados Parallels. Cada + plataforma selecionada primeiro instala o pacote de linha de base solicitado, então executa + o comando `openclaw update` instalado no mesmo convidado e verifica a + versão instalada, status de atualização, prontidão do Gateway e uma interação de agente local. + - Use `--platform macos`, `--platform windows` ou `--platform linux` enquanto + itera em um convidado. Use `--json` para o caminho do artefato de resumo e + status por lane. + - A lane 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 @@ -277,48 +286,48 @@ gh workflow run package-acceptance.yml --ref main \ timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - O script grava logs de lanes aninhadas em `/tmp/openclaw-parallels-npm-update.*`. + - O script grava logs de lane aninhados 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. - - O update do Windows pode passar 10 a 15 minutos no doctor pós-update e no trabalho de - atualização de pacotes em um guest frio; isso ainda está saudável quando o log de debug npm + - A atualização do Windows pode passar de 10 a 15 minutos em trabalho de doctor pós-atualização e atualização de pacote + em um convidado frio; isso ainda está 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 guest. - - A prova pós-update executa a superfície normal de plugins incluídos porque - facades de capacidade como fala, geração de imagem e compreensão de mídia - são carregadas por APIs de runtime incluídas mesmo quando a rodada do agente + - Não execute este wrapper agregado em paralelo com lanes individuais de smoke do Parallels + no macOS, Windows ou Linux. Elas compartilham estado da VM e podem colidir na + restauração de snapshot, serviço de pacotes ou estado do Gateway do convidado. + - A prova pós-atualização executa a superfície normal de Plugin incluído porque + fachadas de capacidade, como fala, geração de imagens e entendimento de mídia, + são carregadas por APIs de runtime incluídas, mesmo quando a interação do agente em si verifica apenas uma resposta de texto simples. - `pnpm openclaw qa aimock` - - Inicia apenas o servidor de provedor AIMock local para testes smoke diretos de protocolo. + - Inicia somente o servidor local de provedor AIMock para testes smoke diretos de protocolo. - `pnpm openclaw qa matrix` - - Executa a lane de QA live do Matrix contra um homeserver Tuwunel descartável baseado em Docker. Somente checkout do código-fonte — instalações empacotadas não incluem `qa-lab`. - - CLI completa, catálogo de perfis/cenários, env vars e layout de artefatos: [QA do Matrix](/pt-BR/concepts/qa-matrix). + - Executa a lane de QA Matrix ao vivo contra um servidor doméstico Tuwunel descartável apoiado por Docker. Somente checkout de fonte — instalações empacotadas não distribuem `qa-lab`. + - CLI completa, catálogo de perfis/cenários, variáveis env e layout de artefatos: [QA Matrix](/pt-BR/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Executa a lane de QA live do Telegram contra um grupo privado real usando os tokens dos bots driver e SUT do env. - - Exige `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 Telegram. + - Executa a lane de QA Telegram ao vivo contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. + - 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. - Oferece suporte a `--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 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. - - Exige dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário Telegram. - - Para observação bot-para-bot estável, habilite o Bot-to-Bot Communication Mode em `@BotFather` para ambos os bots e garanta que o bot driver consiga observar 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. + - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário Telegram. + - Para observação estável de bot para bot, habilite Bot-to-Bot Communication Mode em `@BotFather` para ambos os bots e garanta que o bot driver possa observar o tráfego de bots do grupo. + - Grava um relatório de QA Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. Cenários com resposta incluem RTT da 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 se desviem; 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. +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) +### Credenciais Telegram compartilhadas via Convex (v1) Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está 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. +`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool apoiado por Convex, envia Heartbeat +desse lease enquanto a lane está em execução e libera o lease no encerramento. Scaffold de projeto Convex de referência: - `qa/convex-credential-broker/` -Env vars obrigatórias: +Variáveis env obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) - Um segredo para a função selecionada: @@ -326,9 +335,9 @@ Env vars obrigatórias: - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` - Seleção de função de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão de env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa `ci` por padrão no CI, `maintainer` caso contrário) + - Padrão env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `ci` em CI, `maintainer` caso contrário) -Env vars opcionais: +Variáveis env opcionais: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (padrão `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (padrão `30000`) @@ -336,14 +345,14 @@ Env vars 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 de loopback `http://` apenas para desenvolvimento local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento somente local. -`OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. +`OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` na operação normal. -Comandos de admin de mantenedor (adicionar/remover/listar pool) exigem -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. +Comandos administrativos de mantenedor (pool add/remove/list) exigem especificamente +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Helpers de CLI para mantenedores: +Auxiliares da CLI para mantenedores: ```bash pnpm openclaw qa credentials doctor @@ -352,11 +361,11 @@ 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 do endpoint, tempo limite HTTP e acessibilidade de admin/list sem imprimir +Use `doctor` antes de execuções ao vivo para verificar a URL do site Convex, segredos do broker, +prefixo do endpoint, tempo limite de HTTP e alcançabilidade 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 padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato de endpoint padrão (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -368,181 +377,180 @@ Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v - `POST /release` - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (apenas segredo de mantenedor) +- `POST /admin/add` (somente segredo de mantenedor) - Requisição: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (apenas segredo de mantenedor) +- `POST /admin/remove` (somente segredo de mantenedor) - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - Proteção de concessão ativa: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (apenas segredo de mantenedor) +- `POST /admin/list` (somente segredo de mantenedor) - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` -Formato do payload para o tipo Telegram: +Formato de payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` deve ser uma string numérica de id de chat do Telegram. - `admin/add` valida esse formato para `kind: "telegram"` e rejeita payloads malformados. -### Como adicionar um canal à QA +### Adicionar um canal ao QA -A arquitetura e os nomes dos auxiliares de cenário para novos adaptadores de canal ficam em [visão geral da QA → Como adicionar um canal](/pt-BR/concepts/qa-e2e-automation#adding-a-channel). O requisito mínimo: implementar o executor de transporte na interface de host `qa-lab` compartilhada, declarar `qaRunners` no manifesto do plugin, montar como `openclaw qa ` e criar cenários em `qa/scenarios/`. +A arquitetura e os nomes de auxiliares de cenário para novos adaptadores de canal ficam em [Visão geral do QA → Adicionar um canal](/pt-BR/concepts/qa-e2e-automation#adding-a-channel). O mínimo necessário: implementar o transport runner no seam compartilhado 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 roda onde) -Pense nas suítes como “realismo crescente” (e instabilidade/custo crescentes): +Pense nas suítes como “realismo crescente” (e flakiness/custo crescentes): -### Unitários / integração (padrão) +### Unitário / 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 rodam no shard dedicado `unit-ui` - Escopo: - Testes unitários puros - - Testes de integração em processo (autenticação do Gateway, roteamento, ferramentas, análise, configuração) + - Testes de integração em processo (autenticação do Gateway, roteamento, tooling, parsing, configuração) - Regressões determinísticas para bugs conhecidos - Expectativas: - Roda em CI - Não exige chaves reais - Deve ser rápido e estável - Testes de resolvedor e carregador de superfície pública devem comprovar o comportamento amplo de fallback de `api.js` e - `runtime-api.js` com fixtures de plugin minúsculas geradas, não - APIs de origem de plugins reais incluídos. Carregamentos de API de plugins reais pertencem às - suítes de contrato/integração pertencentes ao plugin. + `runtime-api.js` com pequenas fixtures de Plugin geradas, não com + APIs reais de código-fonte de Plugins empacotados. Carregamentos reais de API de Plugin pertencem a + suítes de contrato/integração pertencentes ao Plugin. - + - - `pnpm test` sem alvo executa doze configurações de shard 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 único processo gigante de projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que trabalhos de auto-reply/extensão deixem 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 multishard não é prático. + - `pnpm test` sem alvo roda doze configurações de shard 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 nativo de projeto raiz. Isso reduz o pico de RSS em máquinas carregadas e evita que trabalho de auto-reply/extensões deixe suítes não relacionadas sem recursos. + - `pnpm test --watch` ainda usa o grafo de projetos nativo raiz `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático. - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam alvos explícitos de arquivo/diretório primeiro por 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 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/package não executam testes amplamente, 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 de core, extensões, testes de extensão, apps, docs, metadados de release, ferramentas Docker live e tooling, depois 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 comprovação de teste. Incrementos de versão apenas de metadados de release executam verificações direcionadas de versão/config/dependência raiz, com um guard que rejeita alterações de package fora do campo de versão de nível superior. - - Edições do harness Docker ACP live executam verificações focadas: sintaxe shell para os scripts de autenticação Docker live e uma simulação do agendador Docker live. Alterações em `package.json` são incluídas apenas quando o diff se limita a `scripts["test:docker:live-*"]`; edições de dependência, export, versão e outras superfícies de package ainda usam os guards mais amplos. - - Testes unitários leves de import de agentes, comandos, plugins, auxiliares de auto-reply, `plugin-sdk` e áreas semelhantes de utilitários puros são roteados pela lane `unit-fast`, que pula `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, para que edições de auxiliares evitem reexecutar toda a suíte pesada desse diretório. - - `auto-reply` tem buckets dedicados para auxiliares core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. A CI também divide a subárvore de reply em shards de agent-runner, dispatch e commands/state-routing para que um bucket pesado de import não ocupe toda a cauda do Node. - - A CI normal de PR/main intencionalmente pula 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 `Plugin Prerelease` separado para essas suítes pesadas de plugins/extensões em candidatas a release. + - `pnpm test:changed` expande caminhos git alterados para lanes baratas com escopo por padrão: edições diretas em testes, arquivos irmãos `*.test.ts`, mapeamentos explícitos de código-fonte e dependentes do grafo de importação local. Edições de config/setup/package não disparam 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 estreito. Ele classifica o diff em core, testes de core, extensões, testes de extensão, apps, docs, metadados de release, tooling Docker ao vivo e tooling, depois roda os comandos correspondentes de typecheck, lint e guard. Ele não roda testes Vitest; chame `pnpm test:changed` ou `pnpm test ` explícito para comprovação por teste. Bumps de versão somente de metadados de release rodam verificações direcionadas de versão/configuração/dependências raiz, com um guard que rejeita alterações de package fora do campo de versão de nível superior. + - Edições do harness Docker ACP ao vivo rodam verificações focadas: sintaxe shell para os scripts de autenticação Docker ao vivo e um dry-run do scheduler 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, exportação, versão e outras superfícies de package ainda usam os guards mais amplos. + - Testes unitários leves de importação de agentes, comandos, Plugins, auxiliares de auto-reply, `plugin-sdk` e áreas puras semelhantes de utilitários roteiam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos stateful/pesados em runtime permanecem nas lanes existentes. + - Arquivos-fonte selecionados de auxiliares de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas lanes leves, então edições de auxiliares evitam rerodar a suíte pesada completa daquele diretório. + - `auto-reply` tem buckets dedicados para auxiliares 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 reply em shards de agent-runner, dispatch e commands/state-routing para que um bucket pesado em importação não fique dono de toda a cauda do Node. + - CI normal de PR/main intencionalmente ignora 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 suítes pesadas em Plugins/extensões em candidatos a release. - + - - Quando você altera entradas de descoberta de ferramenta de mensagem ou contexto de runtime de Compaction, + - Quando você alterar entradas de descoberta de message-tool ou contexto de runtime de compaction, mantenha os dois níveis de cobertura. - Adicione regressões focadas de auxiliares para limites puros de roteamento e normalização. - - Mantenha saudáveis as suítes de integração do executor embutido: + - Mantenha saudáveis as suítes 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 comportamento de Compaction ainda fluem - pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de auxiliares + - Essas suítes verificam que ids com escopo e comportamento de compaction ainda fluem + pelos caminhos reais `run.ts` / `compact.ts`; testes somente de auxiliares 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 - executor não isolado nos projetos raiz, e2e e configurações live. - - A lane de UI raiz mantém sua configuração `jsdom` e otimizador, mas também roda no - executor compartilhado não isolado. + runner não isolado nos projetos raiz, configurações e2e e ao vivo. + - A lane raiz de UI mantém sua configuração `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` para processos Node filhos do Vitest - por padrão para reduzir churn de compilação do V8 durante grandes execuções locais. + - `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 V8 padrão. - + - `pnpm changed:lanes` mostra quais lanes arquiteturais um diff aciona. - - O hook de pre-commit apenas formata. Ele recoloca em stage os arquivos formatados e - não executa lint, typecheck ou testes. - - Execute `pnpm check:changed` explicitamente antes do handoff ou push quando você + - O hook de pre-commit é somente de formatação. Ele reestagia arquivos formatados e + não roda lint, typecheck nem testes. + - Rode `pnpm check:changed` explicitamente antes de handoff ou push quando você precisar do gate de verificação local inteligente. - `pnpm test:changed` roteia por lanes baratas com escopo por padrão. Use - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando o agente - decidir que uma edição de harness, config, package ou contrato realmente precisa de cobertura - Vitest mais ampla. + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando o agente + decidir que uma edição de harness, configuração, package 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 local de workers é 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. + - O autoescalonamento de workers locais é 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 configuração base do Vitest marca os projetos/arquivos de configuração como - `forceRerunTriggers` para que reexecuções em modo alterado permaneçam corretas quando a - fiação de teste muda. + `forceRerunTriggers` para que reexecuções em modo changed continuem corretas quando a + fiação de testes mudar. - 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 você quiser + defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito 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 aos + - `pnpm test:perf:imports` habilita o relatório de duração de importações do Vitest mais + saída de detalhamento de importações. + - `pnpm test:perf:imports:changed` limita a mesma visão de profiling a arquivos alterados desde `origin/main`. - - Dados de tempo de shard são escritos 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 + - Dados de tempo de shard 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 rastreados separadamente. - - Quando um teste quente ainda passa a maior parte do tempo em imports de inicialização, - mantenha dependências pesadas atrás de uma interface local estreita `*.runtime.ts` e - faça mock direto dessa interface em vez de fazer deep import de auxiliares de runtime apenas - para passá-los por `vi.mock(...)`. + - Quando um teste quente ainda passa a maior parte do tempo em importações de inicialização, + mantenha dependências pesadas atrás de um seam local estreito `*.runtime.ts` e + faça mock desse seam diretamente em vez de importar helpers de runtime profundamente só + para repassá-los por `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` compara o - `test:changed` roteado com o caminho nativo de projeto raiz para esse diff comitado - e imprime o tempo de parede mais o RSS máximo no macOS. - - `pnpm test:perf:changed:bench -- --worktree` mede a árvore atual - suja roteando a lista de arquivos alterados por + `test:changed` roteado com o caminho nativo de projeto raiz para aquele diff commitado + e imprime tempo de relógio mais RSS máximo no 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. - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite. - - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a + - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a suíte unitária com paralelismo de arquivos desabilitado. -### Estabilidade (Gateway) +### Estabilidade (gateway) - Comando: `pnpm test:stability:gateway` -- Configuração: `vitest.gateway.config.ts`, forçada para um worker +- Configuração: `vitest.gateway.config.ts`, forçada a um worker - Escopo: - - Inicia um Gateway loopback real com diagnósticos habilitados por padrão - - Conduz churn sintético de mensagens do Gateway, memória e payloads grandes pelo caminho de eventos de diagnóstico + - Inicia um Gateway local loopback real com diagnósticos habilitados por padrão + - Conduz churn sintético de mensagem de gateway, memória e payload grande pelo caminho de evento diagnóstico - Consulta `diagnostics.stability` pelo RPC WS do Gateway - - Cobre auxiliares de persistência do pacote de estabilidade de diagnóstico - - Verifica 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 voltam a zero + - Cobre auxiliares de persistência do pacote de estabilidade diagnóstica + - Afirma 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 - Expectativas: - Seguro para CI e sem chaves - - Lane estreita para acompanhamento de regressões de estabilidade, não um substituto para a suíte completa do Gateway + - Lane estreita para acompanhamento de regressão de estabilidade, não um substituto para a suíte completa do Gateway -### E2E (smoke do Gateway) +### E2E (smoke de gateway) - Comando: `pnpm test:e2e` - Configuração: `vitest.e2e.config.ts` -- Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e testes E2E de Plugin integrado em `extensions/` -- Padrões de tempo de execução: - - Usa `threads` do Vitest com `isolate: false`, alinhado ao restante do repositório. +- Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e testes E2E de Plugins agrupados em `extensions/` +- Padrões de runtime: + - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repositório. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - Executa em modo silencioso por padrão para reduzir a sobrecarga de E/S do console. -- Sobrescritas úteis: +- Substituições úteis: - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada do console. - Escopo: - - Comportamento ponta a ponta de Gateway multi-instância - - Superfícies WebSocket/HTTP, pareamento de Node e rede mais pesada + - Comportamento end-to-end de Gateway multi-instância + - Superfícies WebSocket/HTTP, emparelhamento de nós e redes mais pesadas - Expectativas: - Executa em CI (quando habilitado no pipeline) - - Não exige chaves reais - - Mais partes móveis do que testes unitários (pode ser mais lento) + - Não requer chaves reais + - Mais partes móveis do que testes de unidade (pode ser mais lento) ### E2E: smoke do backend OpenShell @@ -551,37 +559,37 @@ Pense nas suítes como “realismo crescente” (e instabilidade/custo crescente - Escopo: - Inicia um Gateway OpenShell isolado no host via Docker - Cria uma sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell do OpenClaw por meio de `sandbox ssh-config` real + execução SSH - - Verifica o comportamento de sistema de arquivos canônico-remoto pela ponte fs da sandbox + - Exercita o backend OpenShell do OpenClaw por `sandbox ssh-config` real + execução SSH + - Verifica o comportamento do sistema de arquivos canônico remoto por meio da ponte fs da sandbox - Expectativas: - Apenas opt-in; não faz parte da execução padrão de `pnpm test:e2e` - - Exige uma CLI `openshell` local, além de um daemon Docker funcional + - Requer uma CLI `openshell` local mais um daemon Docker funcional - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o Gateway e a sandbox de teste -- Sobrescritas úteis: +- Substituições úteis: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário de CLI ou script wrapper não padrão -### Ao vivo (provedores reais + modelos reais) +### Live (provedores reais + modelos reais) - Comando: `pnpm test:live` - Configuração: `vitest.live.config.ts` -- Arquivos: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e testes ao vivo de Plugin integrado em `extensions/` +- Arquivos: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e testes live de Plugins agrupados 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, peculiaridades de chamadas de ferramentas, problemas de autenticação e comportamento de limite de taxa + - Capturar mudanças de formato de provedores, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de limites de taxa - 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 reduzidos em vez de “tudo” -- Execuções ao vivo carregam `~/.profile` para obter chaves de API ausentes. -- Por padrão, execuções ao vivo ainda isolam `HOME` e copiam material de configuração/autenticação para uma home temporária de teste, para que fixtures unitárias não possam alterar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` somente quando você precisar intencionalmente que testes ao vivo 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/conversa 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 do 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 sobrescrita por execução ao vivo via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. + - Prefira executar subconjuntos restritos 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 configuração/autenticação para um home temporário de teste para que fixtures de unidade não possam modificar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas 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: ele 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 do provedor): defina `*_API_KEYS` com formato de 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 substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. - Saída de progresso/Heartbeat: - - Suítes ao vivo agora emitem linhas de progresso para stderr, de modo que chamadas longas a provedores 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 ao vivo. + - Suítes live agora emitem linhas de progresso para stderr, para que chamadas longas de provedores 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`. @@ -590,193 +598,198 @@ Pense nas suítes como “realismo crescente” (e instabilidade/custo crescente Use esta tabela de decisão: - Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) -- Tocando rede do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot está fora do ar” / falhas específicas de provedor / chamadas de ferramentas: execute um `pnpm test:live` reduzido +- Tocando rede do Gateway / protocolo WS / emparelhamento: adicione `pnpm test:e2e` +- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramentas: execute um `pnpm test:live` restrito -## Testes ao vivo (com acesso à rede) +## Testes live (que tocam a rede) -Para a matriz de modelos ao vivo, smokes de backend CLI, smokes ACP, harness de servidor de app Codex e todos os testes ao vivo 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 ao vivo, consulte [Testando suítes ao vivo](/pt-BR/help/testing-live). Para a lista de verificação dedicada de atualização e validação de Plugin, consulte [Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins). +Para a matriz live de modelos, smokes de backend de CLI, smokes de ACP, harness de 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 manuseio de credenciais para execuções live — veja +[Testando suítes live](/pt-BR/help/testing-live). Para a checklist dedicada de atualização e +validação de Plugin, veja +[Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins). ## Runners Docker (verificações opcionais de "funciona no Linux") -Esses runners Docker se dividem em dois grupos: +Estes runners Docker se dividem em dois grupos: -- Runners de modelos ao vivo: `test:docker:live-models` e `test:docker:live-gateway` executam somente seu arquivo ao vivo correspondente de chave de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório de configuração local e workspace (e carregando `~/.profile` se montado). Os pontos de entrada locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Runners Docker ao vivo usam por padrão um limite de smoke menor para que uma varredura Docker completa continue prática: +- 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 de configuração local e workspace (e carregando `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Runners Docker live usam por padrão um limite de smoke menor para manter uma varredura Docker completa 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`. Sobrescreva essas variáveis de ambiente quando você - quiser explicitamente a varredura exaustiva maior. -- `test:docker:all` constrói a imagem Docker ao vivo 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`, depois constrói/reutiliza duas imagens `scripts/e2e/Dockerfile`. A imagem bare é apenas o runner Node/Git para lanes de instalação/atualização/dependências de Plugin; essas lanes montam o tarball pré-construído. A imagem funcional instala o mesmo tarball em `/app` para lanes de funcionalidade do app construído. Definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`; a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executa o plano selecionado. O agregado usa um escalonador local ponderado: `OPENCLAW_DOCKER_ALL_PARALLELISM` controla slots de processo, enquanto limites de recursos impedem que lanes pesadas ao vivo, de instalação npm e multisserviço comecem todas ao mesmo tempo. Se uma única lane 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é 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` somente quando o host Docker tiver mais folga. O runner faz uma pré-verificação Docker por padrão, remove contêineres E2E OpenClaw obsoletos, imprime status a cada 30 segundos, armazena tempos de lanes bem-sucedidas em `.artifacts/docker-tests/lane-timings.json` e usa esses tempos para iniciar lanes mais longas primeiro em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto ponderado de lanes sem construir ou executar Docker, ou `node scripts/test-docker-all.mjs --plan-json` para imprimir o plano de CI para lanes 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 de `source=npm`, `source=ref`, `source=url` ou `source=artifact`, faz upload dele como `package-under-test` e então executa as lanes E2E Docker reutilizáveis contra esse tarball exato em vez de reempacotar a ref selecionada. Os perfis são ordenados por abrangência: `smoke`, `package`, `product` e `full`. Consulte [Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins) para o contrato de pacote/atualização/Plugin, matriz de sobrevivência de upgrade publicado, padrões de release e triagem de falhas. -- Verificações de build e release executam `scripts/check-cli-bootstrap-imports.mjs` depois do tsdown. A guarda percorre o grafo estático construído a partir de `dist/entry.js` e `dist/cli/run-main.js` e falha se importações de inicialização pré-dispatch carregarem dependências de pacote, como Commander, UI de prompt, undici ou logging antes do dispatch do comando; ela também mantém o chunk de execução do Gateway integrado 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 de doctor, status, esquema 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 pacotes já lançados: entradas omitidas de inventário QA privado, 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 em 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: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`, `test:docker:plugin-lifecycle-matrix` e `test:docker:config-reload` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando você + explicitamente quiser a varredura exaustiva maior. +- `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 `scripts/package-openclaw-for-docker.mjs` e então constrói/reutiliza duas imagens `scripts/e2e/Dockerfile`. A imagem básica é apenas o runner Node/Git para lanes de instalação/atualização/dependência de Plugin; essas lanes montam o tarball pré-construído. A imagem funcional instala o mesmo tarball em `/app` para lanes de funcionalidade do app construído. As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`; a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executa o plano selecionado. O agregado usa um agendador local ponderado: `OPENCLAW_DOCKER_ALL_PARALLELISM` controla slots de processos, enquanto limites de recursos impedem que lanes pesadas live, npm-install e multisserviço iniciem todas de uma vez. Se uma única lane for mais pesada do que os limites ativos, o agendador ainda poderá iniciá-la quando o pool estiver vazio e então a manterá executando sozinha até que a capacidade fique 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 runner executa um preflight Docker por padrão, remove contêineres E2E OpenClaw obsoletos, imprime status a cada 30 segundos, armazena tempos de lanes bem-sucedidas em `.artifacts/docker-tests/lane-timings.json` e usa esses tempos para iniciar lanes mais longas primeiro em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto ponderado de lanes sem construir nem executar Docker, ou `node scripts/test-docker-all.mjs --plan-json` para imprimir o plano de CI para lanes selecionadas, necessidades de pacote/imagem e credenciais. +- `Package Acceptance` é o gate de pacote nativo do GitHub para "este tarball instalável funciona como um 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 lanes reutilizáveis Docker E2E contra esse tarball exato em vez de reempacotar a ref selecionada. Os perfis são ordenados por abrangência: `smoke`, `package`, `product` e `full`. Veja [Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins) para o contrato de pacote/atualização/Plugin, matriz de sobrevivência de atualização publicada, padrões de release e triagem de falhas. +- Verificações de build e release executam `scripts/check-cli-bootstrap-imports.mjs` após tsdown. A proteção percorre o grafo estático construído a partir de `dist/entry.js` e `dist/cli/run-main.js` e falha se importações de inicialização pré-dispatch carregarem dependências de pacote como Commander, UI de prompt, undici ou logging antes do dispatch de comando; ela também mantém o chunk de execução do Gateway agrupado 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 de doctor, status, esquema 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 limite, o harness tolera apenas lacunas de metadados de pacotes já publicados: entradas privadas omitidas do inventário de QA, ausência de `gateway install --wrapper`, 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 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: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`, `test:docker:plugin-lifecycle-matrix` e `test:docker:config-reload` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto. -Os runners Docker de modelos ao vivo também montam via bind somente as homes de autenticação CLI necessárias (ou todas as suportadas quando a execução não é reduzida) e então as copiam para a home do contêiner antes da execução, para que o OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de autenticação do host: +Os runners Docker de modelos live também fazem bind-mount apenas dos homes de autenticação de CLI necessários (ou todos os compatíveis quando a execução não é restrita) e depois 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: - 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 de backend da CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke do harness do servidor de app Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Smoke do harness do servidor de aplicativo do 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 QA em checkout de código-fonte. Ela intencionalmente não faz parte das lanes de lançamento Docker de pacote porque o tarball npm omite o QA Lab. - Smoke 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 com 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, executa doctor e executa um turno de agente OpenAI simulado. 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 troque 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 do pacote `stable` para o git `dev`, verifica se o canal persistido e o pós-atualização do Plugin funcionam, depois volta para o pacote `stable` e verifica o status de atualização. -- Smoke de sobrevivência de 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 Plugin e arquivos existentes de workspace/sessão. Ele executa atualização de 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. -- Smoke de sobrevivência de 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 embutida, valida a configuração resultante, atualiza essa instalação publicada para o tarball candidato, executa doctor não interativo, grava `.artifacts/upgrade-survivor/summary.json`, depois inicia um Gateway de loopback e verifica intents configuradas, preservação de estado, inicialização, `/healthz`, `/readyz` e orçamentos de status RPC. Sobrescreva uma linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, peça ao agendador agregado para expandir linhas de base exatas com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, como `all-since-2026.4.23`, e expanda fixtures no formato de issue com `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, como `reported-issues`; o conjunto reported-issues inclui `configured-plugin-installs` para reparo automático de instalação de Plugins externos do OpenClaw. Package Acceptance expõe isso como `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` e `published_upgrade_survivor_scenarios`. -- Smoke de contexto de runtime de sessão: `pnpm test:docker:session-runtime-context` verifica a persistência de transcript de contexto de runtime oculto 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-a com `bun install -g` em uma home isolada e verifica que `openclaw infer image providers --json` retorna provedores de imagem agrupados em vez de travar. Reutilize um tarball pré-compilado com `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, pule o 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 cache npm entre seus contêineres root, update e direct-npm. O smoke de atualização usa npm `latest` por padrão como linha de base estável antes de atualizar para o tarball candidato. Sobrescreva 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 de 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 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 for necessária cobertura direta de `npm install -g`. -- 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 uma home de contêiner isolada, executa `agents delete --json` e verifica JSON válido mais o 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`) -- Smoke de snapshot CDP do navegador: `pnpm test:docker:browser-cdp-snapshot` (script: `scripts/e2e/browser-cdp-snapshot-docker.sh`) compila a imagem E2E do código-fonte mais uma camada Chromium, inicia Chromium com CDP bruto, executa `browser doctor --deep` e verifica que os 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 web_search do OpenAI Responses: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI simulado pelo Gateway, verifica que `web_search` eleva `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema do provedor e verifica que o detalhe bruto aparece nos logs do Gateway. -- Ponte de canal 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 permitir/negar 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 + desmontagem de filho MCP stdio após execuções isoladas de cron e subagente avulso): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke de instalação/atualização para caminho local, `file:`, registro npm com dependências hoisted, refs móveis de git, conjunto completo do ClawHub, atualizações de marketplace e habilitar/inspecionar 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 de pacote/runtime completo com `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` e `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sem `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, o teste usa um servidor hermético de fixture ClawHub local. +- Smoke de onboarding/canal/agente do tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala o tarball OpenClaw empacotado globalmente no Docker, configura OpenAI via onboarding com referência de env mais Telegram por padrão, executa doctor e executa uma rodada de agente OpenAI simulada. Reutilize um tarball pré-construído com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore a recompilação do host com `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` ou troque o canal com `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` ou `OPENCLAW_NPM_ONBOARD_CHANNEL=slack`. +- Smoke de troca de canal de atualização: `pnpm test:docker:update-channel-switch` instala o tarball OpenClaw empacotado globalmente no Docker, troca de pacote `stable` para git `dev`, verifica o canal persistido e o funcionamento pós-atualização do plugin, depois volta para o pacote `stable` e verifica o status de atualização. +- Smoke de sobrevivência de upgrade: `pnpm test:docker:upgrade-survivor` instala o tarball OpenClaw empacotado sobre uma fixture de usuário antigo suja com agentes, configuração de canal, allowlists de plugins, estado obsoleto de dependência de plugin e arquivos existentes de workspace/sessão. Ele executa atualização de pacote mais doctor não interativo sem provedor ao vivo ou chaves de canal, depois inicia um Gateway loopback e verifica a preservação de configuração/estado mais os orçamentos de inicialização/status. +- Smoke de sobrevivência de 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 doctor não interativo, grava `.artifacts/upgrade-survivor/summary.json`, depois inicia um Gateway loopback e verifica intents configurados, preservação de estado, inicialização, `/healthz`, `/readyz` e orçamentos de status RPC. Substitua uma linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, peça ao agendador agregado para expandir linhas de base exatas com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, como `all-since-2026.4.23`, e expanda fixtures no formato de issues com `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, como `reported-issues`; o conjunto reported-issues inclui `configured-plugin-installs` para reparo automático de instalação de plugin OpenClaw externo. Package Acceptance expõe isso como `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` e `published_upgrade_survivor_scenarios`; Full Release Validation usa a linha de base latest padrão no caminho bloqueante e expande para all-since/reported-issues apenas para `run_release_soak=true` ou `release_profile=full`. +- Smoke de contexto de runtime da sessão: `pnpm test:docker:session-runtime-context` verifica a persistência oculta da transcrição de contexto de runtime mais o reparo pelo doctor de branches afetadas duplicadas 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 uma home isolada e verifica que `openclaw infer image providers --json` retorna provedores de imagem agrupados em vez de travar. Reutilize um tarball pré-construído com `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore a build do 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`. +- Smoke Docker do instalador: `bash scripts/test-install-sh-docker.sh` compartilha um cache npm entre seus contêineres root, update e direct-npm. O smoke de update usa por padrão npm `latest` como linha de base estável antes de atualizar 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 de instalador não root mantêm um cache npm isolado para que entradas de cache pertencentes a 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 entre reexecuções locais. +- O Install Smoke CI ignora a atualização global direct-npm duplicada com `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; execute o script localmente sem esse env quando a cobertura direta de `npm install -g` for necessária. +- Smoke da CLI de 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 de contêiner isolada, 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 + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Smoke 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 Chromium, inicia o Chromium com CDP bruto, executa `browser doctor --deep` e verifica que snapshots de papel CDP cobrem URLs de links, elementos clicáveis promovidos por cursor, refs de iframe e metadados de frame. +- Regressão de raciocínio mínimo de OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI simulado através do Gateway, verifica que `web_search` eleva `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema do provedor e verifica que o detalhe bruto aparece nos logs do Gateway. +- Ponte de canal MCP (Gateway semeado + ponte stdio + smoke de frame de notificação Claude bruto): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Ferramentas MCP do bundle Pi (servidor MCP stdio real + smoke allow/deny de perfil Pi incorporado): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Limpeza MCP de Cron/subagente (Gateway real + teardown 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 (smoke de instalação/atualização para caminho local, `file:`, registro npm com dependências içadas, refs móveis de git, ClawHub kitchen-sink, atualizações de marketplace e habilitação/inspeção de bundle 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 ClawHub. - Smoke de atualização inalterada de Plugin: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke da matriz de ciclo de vida de Plugin: `pnpm test:docker:plugin-lifecycle-matrix` instala o tarball empacotado do OpenClaw em um contêiner básico, instala um Plugin npm, alterna habilitar/desabilitar, faz upgrade e downgrade dele por meio de um registro npm local, exclui o código instalado e então verifica que a desinstalação ainda remove estado obsoleto enquanto registra métricas de RSS/CPU para cada fase do ciclo de vida. +- Smoke de matriz de ciclo de vida de Plugin: `pnpm test:docker:plugin-lifecycle-matrix` instala o tarball OpenClaw empacotado em um contêiner vazio, instala um plugin npm, alterna habilitar/desabilitar, faz upgrade e downgrade dele por meio de um registro npm local, exclui o código instalado e então verifica que a desinstalação ainda remove estado obsoleto enquanto registra métricas de RSS/CPU para cada fase do ciclo de vida. - Smoke de metadados de recarregamento de configuração: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` cobre smoke de instalação/atualização para caminho local, `file:`, registro npm com dependências hoisted, refs móveis de git, fixtures ClawHub, atualizações de marketplace e habilitar/inspecionar pacote Claude. `pnpm test:docker:plugin-update` cobre comportamento de atualização inalterada para Plugins instalados. `pnpm test:docker:plugin-lifecycle-matrix` cobre instalação de Plugin npm com rastreamento de recursos, habilitar, desabilitar, upgrade, downgrade e desinstalação com código ausente. +- Plugins: `pnpm test:docker:plugins` cobre smoke de instalação/atualização para caminho local, `file:`, registro npm com dependências içadas, refs móveis de git, fixtures ClawHub, atualizações de marketplace e habilitação/inspeção de bundle Claude. `pnpm test:docker:plugin-update` cobre comportamento de atualização inalterada para plugins instalados. `pnpm test:docker:plugin-lifecycle-matrix` cobre instalação, habilitação, desabilitação, upgrade, downgrade e desinstalação com código ausente de plugin npm com rastreamento de recursos. -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 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 app compilado compartilhado. +Substituições de imagem específicas de 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 remota compartilhada, 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 compartilhado do aplicativo construído. -Os runners Docker de modelos ao vivo 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 enquanto ainda executa o Vitest contra seu código-fonte/configuração local exato. +Os executores Docker com modelo ao vivo também montam a checkout atual como somente leitura e +a preparam em um diretório de trabalho temporário dentro do contêiner. Isso mantém a imagem de runtime +enxuta enquanto ainda executa o Vitest contra seu código-fonte/config local exato. 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 do app ou -Gradle, para que execuções ao vivo no Docker não passem minutos copiando +do Gradle, para que execuções Docker ao vivo não passem minutos copiando artefatos específicos da máquina. Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondagens ao vivo do Gateway não iniciem workers de canais 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 cobertura ao vivo do Gateway -dessa lane Docker. -`test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um -contêiner do Gateway do OpenClaw com os endpoints HTTP compatíveis com OpenAI ativados, +`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura ao vivo do Gateway +dessa faixa Docker. +`test:docker:openwebui` é uma verificação de compatibilidade de nível mais alto: ela inicia um +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 -requisição real de chat pelo proxy `/api/chat/completions` do Open WebUI. -A primeira execução pode ser notavelmente 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 ao vivo utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. +solicitação de chat real 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 a frio. +Essa faixa espera uma chave de modelo ao vivo utilizável, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções conteinerizadas com Docker. 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 -semeado, inicia um segundo contêiner que executa `openclaw mcp serve` e então -verifica descoberta de conversas roteadas, leituras de transcrição, metadados de anexos, +semeado, inicia um segundo contêiner que dispara `openclaw mcp serve` e então +verifica descoberta de conversas roteadas, leituras de transcrições, metadados de anexos, comportamento da fila de eventos ao vivo, roteamento de envio de saída e notificações de canal + permissão no estilo Claude pela ponte stdio MCP real. A verificação de notificação -inspeciona diretamente os frames MCP stdio brutos para que o smoke valide o que a +inspeciona diretamente os quadros MCP stdio brutos, para que a verificação valide o que a 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 ao vivo. Ele cria a imagem Docker do repositório, inicia um servidor de sondagem MCP stdio real -dentro do contêiner, materializa esse servidor pelo runtime MCP do pacote Pi embutido, -executa a ferramenta e então verifica se `coding` e `messaging` mantêm +modelo ao vivo. Ele compila a imagem Docker do repositório, inicia um servidor de sondagem MCP stdio real +dentro do contêiner, materializa esse servidor pelo runtime MCP do pacote Pi +incorporado, 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 -ao vivo. Ele inicia um Gateway semeado com um servidor de sondagem MCP stdio real, executa uma -rodada cron isolada e uma rodada filha 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 ao vivo. +Ele inicia um Gateway semeado com um servidor de sondagem MCP stdio real, executa uma +rodada Cron isolada e uma rodada filha avulsa de `/subagents spawn`, e então verifica +que o processo filho MCP sai após cada execução. -Smoke manual de thread ACP em linguagem simples (não CI): +Verificação manual de thread ACP em linguagem simples (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de regressão/debug. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. +- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. 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 nenhuma montagem externa de autenticação da 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 config/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 então copiados para `/home/node/...` antes do início dos testes +- 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 padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Execuções restritas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner -- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em novas execuções que não precisam de rebuild +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em novas execuções que não precisam de recompilação - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as 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 substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI -- `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI +- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo Gateway para a verificação do Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pela verificação do Open WebUI +- `OPENWEBUI_IMAGE=...` para substituir 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 do Mintlify quando também precisar de verificações de cabeçalhos dentro da página: `pnpm docs:check-links:anchors`. +Execute verificações de documentação após edições em documentos: `pnpm check:docs`. +Execute a validação completa de âncoras do Mintlify quando também precisar de verificações de cabeçalhos na página: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramenta do Gateway (OpenAI mock, 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`, escreve 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 (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 config + autenticação aplicada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evals de confiabilidade de agentes (skills) +## Avaliações de confiabilidade de agentes (Skills) -Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade de agentes”: +Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade de agentes”: -- Chamada de ferramenta mock pelo Gateway real + loop de agente (`src/gateway/gateway.test.ts`). -- Fluxos de assistente de ponta a ponta que validam a fiação de sessão e os efeitos de configuração (`src/gateway/gateway.test.ts`). +- Chamada de ferramenta simulada pelo Gateway real + loop de agente (`src/gateway/gateway.test.ts`). +- Fluxos de assistente de ponta a ponta que validam a fiação da 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)): +O que ainda falta para Skills (consulte [Skills](/pt-BR/tools/skills)): -- **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 do uso e segue as etapas/argumentos obrigatórios? -- **Contratos de workflow:** cenários multi-turno que validam ordem de ferramentas, persistência de histórico de sessão e limites de sandbox. +- **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 do uso e segue as etapas/argumentos exigidos? +- **Contratos de fluxo de trabalho:** cenários de múltiplas rodadas que verificam ordem de ferramentas, preservação do histórico da sessão e limites do sandbox. -Evals futuros devem permanecer determinísticos primeiro: +Avaliações futuras devem permanecer determinísticas primeiro: -- Um executor de cenários usando provedores mock para validar chamadas de ferramenta + ordem, leituras de arquivos de skill e fiação de sessão. -- Uma pequena suíte de cenários focados em skills (usar vs evitar, gating, injeção de prompt). -- Evals ao vivo 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 verificar chamadas de ferramentas + ordem, leituras de arquivos de Skill e fiação da sessão. +- Uma pequena suíte de cenários focados em Skills (usar vs evitar, bloqueios, injeção de prompt). +- Avaliações ao vivo opcionais (opt-in, protegidas 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 todo Plugin e canal registrado está em conformidade com seu +Testes de contrato verificam que cada 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 seams e smoke; execute os comandos de contrato explicitamente +asserções de formato e comportamento. A faixa unitária padrão de `pnpm test` intencionalmente +ignora esses arquivos compartilhados de verificação e smoke; execute os comandos de contrato explicitamente quando tocar em superfícies compartilhadas de canal ou provedor. ### Comandos - Todos os contratos: `pnpm test:contracts` -- Somente contratos de canal: `pnpm test:contracts:channels` -- Somente 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, capabilities) +- **plugin** - Formato básico do Plugin (id, nome, capacidades) - **setup** - Contrato do assistente de configuração -- **session-binding** - Comportamento de vínculo de sessão -- **outbound-payload** - Estrutura de payload de mensagem +- **session-binding** - Comportamento de vinculação de sessão +- **outbound-payload** - Estrutura da carga de mensagem - **inbound** - Tratamento de mensagens de entrada -- **actions** - Handlers de ações de canal +- **actions** - Manipuladores de ações de canal - **threading** - Tratamento de ID de thread - **directory** - API de diretório/lista - **group-policy** - Aplicação de política de grupo @@ -788,42 +801,42 @@ Localizados em `src/plugins/contracts/*.contract.test.ts`. - **status** - Sondagens de status de canal - **registry** - Formato do registro de Plugin -### Contratos de provedor +### Contratos de provedores Localizados em `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de fluxo de autenticação +- **auth** - Contrato do fluxo de autenticação - **auth-choice** - Escolha/seleção de autenticação - **catalog** - API de catálogo de modelos - **discovery** - Descoberta de Plugin - **loader** - Carregamento de Plugin -- **runtime** - Runtime de provedor +- **runtime** - Runtime do provedor - **shape** - Formato/interface do Plugin - **wizard** - Assistente de configuração ### Quando executar -- Depois de alterar exports ou subpaths de plugin-sdk -- Depois de adicionar ou modificar um canal ou Plugin de provedor +- Depois de alterar exportações ou subcaminhos 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 em CI e não exigem chaves reais de API. +Testes de contrato são executados no CI e não exigem chaves de API reais. -## Adicionando regressões (orientação) +## Adicionar regressões (orientação) -Quando você corrige um problema de provedor/modelo descoberto ao vivo: +Quando você corrigir um problema de provedor/modelo descoberto ao vivo: -- 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 ao vivo (limites de taxa, políticas de autenticação), mantenha o teste ao vivo restrito e opt-in via variáveis de ambiente +- Adicione uma regressão segura para CI se possível (provedor mock/stub, ou capture a transformação exata do formato da solicitação) +- Se for inerentemente apenas ao vivo (limites de taxa, políticas de autenticação), mantenha o teste ao vivo restrito e opt-in por variáveis de ambiente - Prefira mirar na menor camada que captura o bug: - - 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 ao vivo do Gateway ou teste mock seguro para CI do Gateway + - bug de conversão/reprodução de solicitação do provedor → teste direto de modelos + - bug de sessão/histórico/pipeline de ferramentas do Gateway → smoke ao vivo do Gateway ou teste mock do Gateway seguro para CI - Guardrail de travessia de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`) e então afirma que ids de execução com segmento 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. + - `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 verifica que ids de execução com segmentos de travessia são rejeitados. + - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. ## Relacionado -- [Testes ao vivo](/pt-BR/help/testing-live) -- [Testes de atualizações e plugins](/pt-BR/help/testing-updates-plugins) +- [Teste ao vivo](/pt-BR/help/testing-live) +- [Teste de atualizações e plugins](/pt-BR/help/testing-updates-plugins) - [CI](/pt-BR/ci) diff --git a/docs/pt-BR/plugins/bundles.md b/docs/pt-BR/plugins/bundles.md index 8058e3677..535c00670 100644 --- a/docs/pt-BR/plugins/bundles.md +++ b/docs/pt-BR/plugins/bundles.md @@ -6,36 +6,36 @@ read_when: summary: Instale e use pacotes do Codex, Claude e Cursor como plugins do OpenClaw title: Pacotes de Plugin x-i18n: - generated_at: "2026-05-02T05:51:39Z" + generated_at: "2026-05-05T01:47:57Z" model: gpt-5.5 provider: openai - source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4 + source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157 source_path: plugins/bundles.md workflow: 16 --- -OpenClaw pode instalar plugins de três ecossistemas externos: **Codex**, **Claude** -e **Cursor**. Eles são chamados de **bundles** — pacotes de conteúdo e metadados que +OpenClaw pode instalar plugins de três ecossistemas externos: **Codex**, **Claude**, +e **Cursor**. Eles são chamados de **pacotes** — pacotes de conteúdo e metadados que o OpenClaw mapeia para recursos nativos como Skills, hooks e ferramentas MCP. - Bundles **não** são o mesmo que plugins nativos do OpenClaw. Plugins nativos são executados - no processo e podem registrar qualquer capacidade. Bundles são pacotes de conteúdo com + Pacotes **não** são a mesma coisa que plugins nativos do OpenClaw. Plugins nativos rodam + no processo e podem registrar qualquer capacidade. Pacotes são conjuntos de conteúdo com mapeamento seletivo de recursos e um limite de confiança mais restrito. -## Por que bundles existem +## Por que os pacotes existem Muitos plugins úteis são publicados no formato Codex, Claude ou Cursor. Em vez de exigir que autores os reescrevam como plugins nativos do OpenClaw, o OpenClaw -detecta esses formatos e mapeia o conteúdo compatível deles para o conjunto de -recursos nativo. Isso significa que você pode instalar um pacote de comandos Claude ou um bundle de Skills Codex +detecta esses formatos e mapeia o conteúdo compatível para o conjunto de recursos +nativo. Isso significa que você pode instalar um pacote de comandos Claude ou um pacote de Skills do Codex e usá-lo imediatamente. -## Instalar um bundle +## Instalar um pacote - + ```bash # Local directory openclaw plugins install ./my-bundle @@ -50,17 +50,17 @@ e usá-lo imediatamente. - + ```bash openclaw plugins list openclaw plugins inspect ``` - Bundles aparecem como `Format: bundle` com um subtipo `codex`, `claude` ou `cursor`. + Pacotes aparecem como `Format: bundle` com um subtipo `codex`, `claude` ou `cursor`. - + ```bash openclaw gateway restart ``` @@ -70,51 +70,51 @@ e usá-lo imediatamente. -## O que o OpenClaw mapeia de bundles +## O que o OpenClaw mapeia de pacotes -Nem todo recurso de bundle é executado no OpenClaw hoje. Veja o que funciona e o que +Nem todos os recursos de pacote rodam no OpenClaw hoje. Veja o que funciona e o que é detectado, mas ainda não está conectado. -### Compatível agora +### Com suporte agora | Recurso | Como é mapeado | Aplica-se a | | ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| Conteúdo de Skills | Raízes de Skills do bundle são carregadas como Skills normais do OpenClaw | Todos os formatos | +| Conteúdo de Skill | Raízes de Skills do pacote carregam como Skills normais do OpenClaw | Todos os formatos | | Comandos | `commands/` e `.cursor/commands/` tratados como raízes de Skills | Claude, Cursor | | Pacotes de hooks | Layouts no estilo OpenClaw com `HOOK.md` + `handler.ts` | Codex | -| Ferramentas MCP | Configuração MCP do bundle mesclada às configurações incorporadas do Pi; servidores stdio e HTTP compatíveis carregados | Todos os formatos | -| Servidores LSP | `.lsp.json` do Claude e `lspServers` declarados no manifesto mesclados aos padrões LSP incorporados do Pi | Claude | -| Configurações | `settings.json` do Claude importado como padrões incorporados do Pi | Claude | +| Ferramentas MCP | Configuração MCP do pacote mesclada nas configurações embarcadas do Pi; servidores stdio e HTTP compatíveis carregados | Todos os formatos | +| Servidores LSP | `.lsp.json` do Claude e `lspServers` declarados no manifesto mesclados aos padrões LSP embarcados do Pi | Claude | +| Configurações | `settings.json` do Claude importado como padrões embarcados do Pi | Claude | -#### Conteúdo de Skills +#### Conteúdo de Skill -- raízes de Skills do bundle são carregadas como raízes normais de Skills do OpenClaw -- raízes `commands` do Claude são tratadas como raízes adicionais de Skills -- raízes `.cursor/commands` do Cursor são tratadas como raízes adicionais de Skills +- raízes de Skills do pacote carregam como raízes de Skills normais do OpenClaw +- raízes `commands` do Claude são tratadas como raízes de Skills adicionais +- raízes `.cursor/commands` do Cursor são tratadas como raízes de Skills adicionais -Isso significa que arquivos de comando markdown do Claude funcionam pelo carregador +Isso significa que arquivos de comando Markdown do Claude funcionam pelo carregador normal de Skills do OpenClaw. Markdown de comandos do Cursor funciona pelo mesmo caminho. #### Pacotes de hooks -- raízes de hooks do bundle funcionam **somente** quando usam o layout normal - de pacote de hooks do OpenClaw. Hoje, esse é principalmente o caso compatível com Codex: +- raízes de hooks de pacote funcionam **somente** quando usam o layout normal de pacote de hooks + do OpenClaw. Hoje, esse é principalmente o caso compatível com Codex: - `HOOK.md` - `handler.ts` ou `handler.js` #### MCP para Pi -- bundles habilitados podem contribuir com configuração de servidor MCP -- o OpenClaw mescla a configuração MCP do bundle às configurações incorporadas efetivas do Pi como +- pacotes habilitados podem contribuir configuração de servidor MCP +- o OpenClaw mescla a configuração MCP do pacote nas configurações embarcadas efetivas do Pi como `mcpServers` -- o OpenClaw expõe ferramentas MCP compatíveis do bundle durante turnos do agente Pi incorporado - iniciando servidores stdio ou conectando-se a servidores HTTP -- os perfis de ferramentas `coding` e `messaging` incluem ferramentas MCP de bundle por - padrão; use `tools.deny: ["bundle-mcp"]` para desativar para um agente ou Gateway -- configurações locais de projeto do Pi ainda se aplicam depois dos padrões do bundle, então configurações - de workspace podem sobrescrever entradas MCP do bundle quando necessário -- catálogos de ferramentas MCP de bundle são ordenados deterministicamente antes do registro, para que - mudanças na ordem de `listTools()` upstream não recriem blocos de ferramentas do cache de prompts +- o OpenClaw expõe ferramentas MCP de pacote compatíveis durante turnos do agente Pi embarcado ao + iniciar servidores stdio ou conectar a servidores HTTP +- os perfis de ferramenta `coding` e `messaging` incluem ferramentas MCP de pacote por + padrão; use `tools.deny: ["bundle-mcp"]` para optar por não usar em um agente ou Gateway +- configurações locais de projeto do Pi ainda se aplicam depois dos padrões do pacote, então as + configurações do workspace podem substituir entradas MCP do pacote quando necessário +- catálogos de ferramentas MCP de pacote são ordenados deterministamente antes do registro, para que + alterações na ordem upstream de `listTools()` não agitem blocos de ferramentas do cache de prompt ##### Transportes @@ -136,7 +136,7 @@ Servidores MCP podem usar transporte stdio ou HTTP: } ``` -**HTTP** conecta-se a um servidor MCP em execução por `sse` por padrão, ou `streamable-http` quando solicitado: +**HTTP** conecta a um servidor MCP em execução por `sse` por padrão, ou `streamable-http` quando solicitado: ```json { @@ -160,15 +160,15 @@ Servidores MCP podem usar transporte stdio ou HTTP: - somente esquemas de URL `http:` e `https:` são permitidos - valores de `headers` aceitam interpolação `${ENV_VAR}` - uma entrada de servidor com `command` e `url` é rejeitada -- credenciais de URL (userinfo e parâmetros de consulta) são redigidas de descrições - de ferramentas e logs -- `connectionTimeoutMs` substitui o tempo limite padrão de conexão de 30 segundos para +- credenciais de URL (userinfo e parâmetros de consulta) são redigidas de descrições de ferramentas + e logs +- `connectionTimeoutMs` substitui o tempo limite de conexão padrão de 30 segundos para transportes stdio e HTTP -##### Nomenclatura de ferramentas +##### Nomeação de ferramentas -O OpenClaw registra ferramentas MCP de bundle com nomes seguros para provedores no formato -`serverName__toolName`. Por exemplo, um servidor com a chave `"vigil-harbor"` que expõe uma ferramenta +O OpenClaw registra ferramentas MCP de pacote com nomes seguros para provedores no formato +`serverName__toolName`. Por exemplo, um servidor com chave `"vigil-harbor"` que expõe uma ferramenta `memory_search` é registrado como `vigil-harbor__memory_search`. - caracteres fora de `A-Za-z0-9_-` são substituídos por `-` @@ -176,16 +176,16 @@ O OpenClaw registra ferramentas MCP de bundle com nomes seguros para provedores - nomes completos de ferramentas são limitados a 64 caracteres - nomes de servidor vazios usam `mcp` como fallback - nomes sanitizados conflitantes são desambiguados com sufixos numéricos -- a ordem final de ferramentas expostas é determinística por nome seguro para manter turnos - repetidos do Pi estáveis para cache -- a filtragem de perfis trata todas as ferramentas de um servidor MCP de bundle como pertencentes ao plugin - `bundle-mcp`, então allowlists e deny lists de perfil podem incluir nomes - individuais de ferramentas expostas ou a chave de plugin `bundle-mcp` +- a ordem final de ferramentas expostas é determinística por nome seguro para manter turnos repetidos do Pi + estáveis em cache +- a filtragem de perfis trata todas as ferramentas de um servidor MCP de pacote como pertencentes ao plugin + `bundle-mcp`, então listas de permissão e negação de perfil podem incluir tanto + nomes individuais de ferramentas expostas quanto a chave de plugin `bundle-mcp` -#### Configurações incorporadas do Pi +#### Configurações embarcadas do Pi -- `settings.json` do Claude é importado como configurações incorporadas padrão do Pi quando o - bundle está habilitado +- `settings.json` do Claude é importado como configurações embarcadas padrão do Pi quando o + pacote está habilitado - o OpenClaw sanitiza chaves de substituição de shell antes de aplicá-las Chaves sanitizadas: @@ -193,13 +193,13 @@ Chaves sanitizadas: - `shellPath` - `shellCommandPrefix` -#### LSP incorporado do Pi +#### LSP embarcado do Pi -- bundles Claude habilitados podem contribuir com configuração de servidor LSP +- pacotes Claude habilitados podem contribuir configuração de servidor LSP - o OpenClaw carrega `.lsp.json` mais quaisquer caminhos `lspServers` declarados no manifesto -- a configuração LSP do bundle é mesclada aos padrões LSP incorporados efetivos do Pi -- somente servidores LSP compatíveis baseados em stdio são executáveis hoje; transportes - incompatíveis ainda aparecem em `openclaw plugins inspect ` +- a configuração LSP do pacote é mesclada aos padrões LSP embarcados efetivos do Pi +- somente servidores LSP com suporte baseados em stdio podem ser executados hoje; transportes + sem suporte ainda aparecem em `openclaw plugins inspect ` ### Detectado, mas não executado @@ -209,20 +209,20 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec - `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` do Cursor - metadados inline/de app do Codex além do relatório de capacidades -## Formatos de bundle +## Formatos de pacote - + Marcadores: `.codex-plugin/plugin.json` Conteúdo opcional: `skills/`, `hooks/`, `.mcp.json`, `.app.json` - Bundles Codex se encaixam melhor no OpenClaw quando usam raízes de Skills e diretórios - de pacotes de hooks no estilo OpenClaw (`HOOK.md` + `handler.ts`). + Pacotes Codex se encaixam melhor no OpenClaw quando usam raízes de Skills e diretórios + de pacote de hooks no estilo OpenClaw (`HOOK.md` + `handler.ts`). - + Dois modos de detecção: - **Baseado em manifesto:** `.claude-plugin/plugin.json` @@ -230,22 +230,22 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec Comportamento específico do Claude: - - `commands/` é tratado como conteúdo de Skills - - `settings.json` é importado para configurações incorporadas do Pi (chaves de substituição de shell são sanitizadas) - - `.mcp.json` expõe ferramentas stdio compatíveis para o Pi incorporado - - `.lsp.json` mais caminhos `lspServers` declarados no manifesto são carregados nos padrões LSP incorporados do Pi + - `commands/` é tratado como conteúdo de Skill + - `settings.json` é importado para as configurações embarcadas do Pi (chaves de substituição de shell são sanitizadas) + - `.mcp.json` expõe ferramentas stdio compatíveis ao Pi embarcado + - `.lsp.json` mais caminhos `lspServers` declarados no manifesto carregam nos padrões LSP embarcados do Pi - `hooks/hooks.json` é detectado, mas não executado - - Caminhos de componentes personalizados no manifesto são aditivos (eles estendem os padrões, não os substituem) + - caminhos de componentes personalizados no manifesto são aditivos (estendem os padrões, não os substituem) - + Marcadores: `.cursor-plugin/plugin.json` Conteúdo opcional: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json` - - `.cursor/commands/` é tratado como conteúdo de Skills - - `.cursor/rules/`, `.cursor/agents/` e `.cursor/hooks.json` são somente detectados + - `.cursor/commands/` é tratado como conteúdo de Skill + - `.cursor/rules/`, `.cursor/agents/` e `.cursor/hooks.json` são somente detecção @@ -255,55 +255,55 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec O OpenClaw verifica primeiro o formato de plugin nativo: 1. `openclaw.plugin.json` ou `package.json` válido com `openclaw.extensions` — tratado como **plugin nativo** -2. Marcadores de bundle (`.codex-plugin/`, `.claude-plugin/` ou layout padrão Claude/Cursor) — tratados como **bundle** +2. Marcadores de pacote (`.codex-plugin/`, `.claude-plugin/` ou layout padrão do Claude/Cursor) — tratados como **pacote** -Se um diretório contiver ambos, o OpenClaw usa o caminho nativo. Isso impede que -pacotes de formato duplo sejam instalados parcialmente como bundles. +Se um diretório contiver ambos, o OpenClaw usa o caminho nativo. Isso evita +que pacotes de formato duplo sejam parcialmente instalados como pacotes. ## Dependências de runtime e limpeza -- Bundles compatíveis de terceiros não recebem reparo `npm install` na inicialização. Eles - devem ser instalados por `openclaw plugins install` e incluir tudo +- Pacotes compatíveis de terceiros não recebem reparo de `npm install` na inicialização. Eles + devem ser instalados por meio de `openclaw plugins install` e incluir tudo de que precisam no diretório de plugin instalado. -- Plugins empacotados pertencentes ao OpenClaw são enviados de forma leve no core ou +- Plugins empacotados pertencentes ao OpenClaw são enviados de forma leve no núcleo ou baixáveis pelo instalador de plugins. A inicialização do Gateway nunca executa um gerenciador de pacotes para eles. - `openclaw doctor --fix` remove diretórios legados de dependências preparadas e pode - instalar plugins baixáveis configurados que estão ausentes do índice local - de plugins. + recuperar plugins baixáveis ausentes do índice local de plugins quando + a configuração os referencia. ## Segurança -Bundles têm um limite de confiança mais restrito que plugins nativos: +Pacotes têm um limite de confiança mais restrito que plugins nativos: -- o OpenClaw **não** carrega módulos arbitrários de runtime do bundle no processo -- caminhos de Skills e pacotes de hooks devem permanecer dentro da raiz do plugin (verificados por limite) -- arquivos de configurações são lidos com as mesmas verificações de limite +- o OpenClaw **não** carrega módulos arbitrários de runtime de pacote no processo +- caminhos de Skills e de pacotes de hooks devem permanecer dentro da raiz do plugin (com verificação de limite) +- arquivos de configuração são lidos com as mesmas verificações de limite - servidores MCP stdio compatíveis podem ser iniciados como subprocessos -Isso torna bundles mais seguros por padrão, mas você ainda deve tratar bundles -de terceiros como conteúdo confiável para os recursos que eles expõem. +Isso torna pacotes mais seguros por padrão, mas você ainda deve tratar pacotes de terceiros +como conteúdo confiável para os recursos que eles expõem. ## Solução de problemas - + Execute `openclaw plugins inspect `. Se uma capacidade estiver listada, mas marcada como - não conectada, isso é uma limitação do produto — não uma instalação quebrada. + não conectada, isso é um limite do produto — não uma instalação quebrada. - Verifique se o bundle está habilitado e se os arquivos markdown estão dentro de uma raiz + Verifique se o pacote está habilitado e se os arquivos Markdown estão dentro de uma raiz `commands/` ou `skills/` detectada. - - Somente configurações incorporadas do Pi de `settings.json` são compatíveis. O OpenClaw não - trata configurações de bundle como patches de configuração bruta. + + Somente configurações embarcadas do Pi de `settings.json` têm suporte. O OpenClaw não + trata configurações de pacote como patches de configuração bruta. - - `hooks/hooks.json` é somente detectado. Se você precisa de hooks executáveis, use o + + `hooks/hooks.json` é somente detecção. Se você precisa de hooks executáveis, use o layout de pacote de hooks do OpenClaw ou envie um plugin nativo. diff --git a/docs/pt-BR/plugins/codex-harness.md b/docs/pt-BR/plugins/codex-harness.md index c16a623f7..9f2df8fbd 100644 --- a/docs/pt-BR/plugins/codex-harness.md +++ b/docs/pt-BR/plugins/codex-harness.md @@ -1,21 +1,21 @@ --- read_when: - - Você quer usar a estrutura de app-server do Codex incluída + - Você quer usar o harness 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 apenas com Codex falhem em vez de recorrer ao PI -summary: Execute os turnos de agente incorporado do OpenClaw por meio da estrutura de execução app-server do Codex incluída -title: Ambiente de execução do Codex + - Você quer que implantações apenas com Codex falhem em vez de recorrerem ao Pi +summary: Execute turnos de agente embutido do OpenClaw pela estrutura de execução app-server incluída no Codex +title: Estrutura de execução do Codex x-i18n: - generated_at: "2026-05-03T21:35:37Z" + generated_at: "2026-05-05T01:48:12Z" model: gpt-5.5 provider: openai - source_hash: f5187e54e2dc94e511c0243227f741d3486669f595c2b15cf239b1c03ea466c8 + source_hash: 76302351e7e162e858dd6e3cffca84b3fd54497dd060104da9f90fe4c1a33f9b 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 de PI integrado. +O Plugin `codex` incluído permite que o OpenClaw execute turnos de agente incorporados pelo +app-server do Codex em vez do harness PI integrado. Use isso quando 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. @@ -29,35 +29,35 @@ ele só publica no canal quando chama `message(action="send")`. Defina `messages.visibleReplies: "automatic"` para manter as respostas finais de chat direto no caminho legado de entrega automática. -Turnos de Heartbeat do Codex também recebem a ferramenta `heartbeat_respond` por padrão, para que o +Turnos de heartbeat do Codex também recebem a ferramenta `heartbeat_respond` por padrão, para que o agente possa registrar se o despertar deve permanecer silencioso ou notificar sem codificar esse fluxo de controle no texto final. -A orientação de iniciativa específica de Heartbeat é enviada como uma instrução de desenvolvedor -do modo de colaboração do Codex no próprio turno de heartbeat. Turnos comuns de chat restauram -o modo Default do Codex em vez de carregar a filosofia de heartbeat no prompt normal +A orientação de iniciativa específica de Heartbeat é enviada como uma instrução de desenvolvedor em +modo de colaboração do Codex no próprio turno de heartbeat. Turnos de chat comuns restauram +o modo padrão do Codex em vez de carregar a filosofia de heartbeat no prompt normal de runtime. Se você está tentando se orientar, comece com [Runtimes de agente](/pt-BR/concepts/agent-runtimes). A versão curta é: -`openai/gpt-5.5` é a referência do modelo, `codex` é o runtime, e Telegram, +`openai/gpt-5.5` é a referência de modelo, `codex` é o runtime, e Telegram, Discord, Slack ou outro canal continua sendo a superfície de comunicação. ## Configuração rápida A maioria dos usuários que quer "Codex no OpenClaw" quer esta rota: entrar com uma -assinatura ChatGPT/Codex e, em seguida, executar turnos de agente incorporados pelo runtime nativo -do app-server do Codex. A referência do modelo ainda permanece canônica como -`openai/gpt-*`; a autenticação por assinatura vem da conta/perfil Codex, não +assinatura ChatGPT/Codex e então executar turnos de agente incorporados pelo runtime nativo +do app-server do Codex. A referência de modelo ainda permanece canônica como +`openai/gpt-*`; a autenticação por assinatura vem da conta/perfil do Codex, não de um prefixo de modelo `openai-codex/*`. -Primeiro, entre com o OAuth do Codex se ainda não tiver feito isso: +Primeiro entre com OAuth do Codex, se ainda não tiver feito isso: ```bash openclaw models auth login --provider openai-codex ``` -Depois habilite o Plugin `codex` incluído e force o runtime do Codex: +Então habilite o Plugin `codex` incluído e force o runtime do Codex: ```json5 { @@ -94,36 +94,36 @@ Se sua configuração usa `plugins.allow`, inclua `codex` ali também: } ``` -Não use `openai-codex/gpt-*` quando quiser dizer runtime nativo do Codex. Esse prefixo -é a rota explícita "OAuth do Codex por PI". Alterações de configuração se aplicam a sessões novas ou -reiniciadas; sessões existentes mantêm o runtime registrado. +Não use `openai-codex/gpt-*` quando você quer dizer runtime nativo do Codex. Esse prefixo +é a rota explícita "OAuth do Codex pelo PI". Alterações de configuração se aplicam a sessões novas ou +redefinidas; sessões existentes mantêm o runtime registrado delas. ## O que este Plugin altera O Plugin `codex` incluído contribui com várias capacidades separadas: -| Capacidade | Como usar | O que faz | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime nativo incorporado | `agentRuntime.id: "codex"` | Executa turnos de agente incorporados do OpenClaw pelo 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 pelo 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 limitados do app-server do Codex para modelos compatíveis de compreensão de imagem. | -| Relay de hook nativo | Hooks de Plugin em torno de eventos nativos do Codex | Permite que o OpenClaw observe/bloqueie eventos nativos compatíveis de ferramenta/finalização do Codex. | +| Capacidade | Como você a usa | O que ela faz | +| ---------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Runtime incorporado nativo | `agentRuntime.id: "codex"` | Executa turnos de agente incorporados do OpenClaw pelo 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 pelo harness | Permite que o runtime descubra e valide modelos do app-server. | +| Caminho de entendimento de mídia do Codex | Caminhos de compatibilidade de modelos de imagem `codex/*` | Executa turnos limitados do app-server do Codex para modelos compatíveis de entendimento de imagem. | +| Relay de hooks nativos | Hooks de Plugin ao redor 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 +- começa a usar o Codex para todo modelo OpenAI - converte referências de modelo `openai-codex/*` no runtime nativo -- torna ACP/acpx o caminho Codex padrão -- troca a quente sessões existentes que já registraram um runtime de PI -- substitui a entrega de canais do OpenClaw, arquivos de sessão, armazenamento de perfil de autenticação ou - roteamento de mensagens +- torna ACP/acpx o caminho padrão do Codex +- troca em tempo real sessões existentes que já registraram um runtime PI +- substitui entrega por canal, arquivos de sessão, armazenamento de perfil de autenticação ou + roteamento de mensagens do OpenClaw 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. +o Plugin está habilitado e o usuário pede para vincular, retomar, direcionar, parar ou inspecionar +threads do Codex pelo chat, 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 Codex +do ACP. Turnos nativos do Codex mantêm os 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: @@ -133,13 +133,13 @@ Estes são hooks em processo do OpenClaw, não hooks de comando `hooks.json` do - `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 +- `before_agent_finalize` pelo 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 de Plugin público -`tool_result_persist`, que transforma gravações de resultado de ferramenta em transcrições pertencentes ao OpenClaw. +Plugins também podem registrar middleware de resultado de ferramenta neutro quanto ao 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 escritas de resultado de ferramenta na transcrição pertencentes ao OpenClaw. Para a semântica dos próprios hooks de Plugin, consulte [Hooks de Plugin](/pt-BR/plugins/hooks) e [Comportamento de guarda de Plugin](/pt-BR/tools/plugin). @@ -147,157 +147,156 @@ 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 legadas de modelo `codex/*` ainda selecionam automaticamente -o harness por compatibilidade, mas prefixos legados de provedor apoiados por runtime +execução nativa no app-server. Referências de modelo legadas `codex/*` ainda selecionam automaticamente +o harness por compatibilidade, mas prefixos de provedor legados com suporte de runtime não são exibidos 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 OAuth/assinatura do Codex por PI, e -a execução nativa no app-server permanece uma escolha explícita de runtime. +intencional: `openai-codex/*` continua sendo 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 | Rota de autenticação/perfil | Rótulo de status esperado | -| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | -| Assinatura ChatGPT/Codex com runtime nativo do Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | OAuth do Codex ou conta Codex | `Runtime: OpenAI Codex` | -| API OpenAI pelo runner normal do OpenClaw | `openai/gpt-*` | omitido ou `runtime: "pi"` | Chave de API OpenAI | `Runtime: OpenClaw Pi Default` | -| Assinatura ChatGPT/Codex por PI | `openai-codex/gpt-*` | omitido ou `runtime: "pi"` | Provedor OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Provedores mistos com modo automático conservador | referências específicas de provedor | `agentRuntime.id: "auto"` | Por provedor selecionado | Depende do runtime selecionado | -| Sessão explícita do adaptador ACP do Codex | Depende do prompt/modelo ACP | `sessions_spawn` com `runtime: "acp"` | Autenticação do backend ACP | Status de tarefa/sessão ACP | +| Comportamento desejado | Referência de modelo | Configuração de runtime | Rota de autenticação/perfil | Rótulo de status esperado | +| --------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| Assinatura ChatGPT/Codex com runtime nativo do Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | OAuth do Codex ou conta do Codex | `Runtime: OpenAI Codex` | +| API da OpenAI pelo executor normal do OpenClaw | `openai/gpt-*` | omitido ou `runtime: "pi"` | Chave de API da OpenAI | `Runtime: OpenClaw Pi Default` | +| Assinatura ChatGPT/Codex pelo PI | `openai-codex/gpt-*` | omitido ou `runtime: "pi"` | Provedor OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | +| Provedores mistos com modo automático conservador | referências específicas do provedor | `agentRuntime.id: "auto"` | Por provedor selecionado | Depende do runtime selecionado | +| Sessão explícita do adaptador Codex ACP | depende de prompt/modelo ACP | `sessions_spawn` com `runtime: "acp"` | Autenticação do backend ACP | 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 +- `/codex ...` responde "a qual conversa nativa do Codex este chat deve se vincular ou controlar?" -- ACP responde "qual processo externo de harness o acpx deve iniciar?" +- 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. Para a configuração comum de assinatura mais runtime nativo do Codex, use `openai/*` com `agentRuntime.id: "codex"`. -Use `openai-codex/*` somente quando você quiser intencionalmente OAuth do Codex por PI: +Use `openai-codex/*` apenas quando você quiser intencionalmente OAuth do Codex pelo PI: -| Referência do modelo | Caminho de runtime | Use quando | -| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Provedor OpenAI pela infraestrutura OpenClaw/PI | Você quer acesso atual direto à API OpenAI Platform com `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex pelo OpenClaw/PI | Você quer autenticação por assinatura ChatGPT/Codex com o runner padrão de PI. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness do app-server do Codex | Você quer autenticação por assinatura ChatGPT/Codex com execução nativa do Codex. | +| Referência de modelo | Caminho de runtime | Use quando | +| -------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Provedor OpenAI pelo encanamento OpenClaw/PI | Você quer acesso atual direto à API da OpenAI Platform com `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OAuth OpenAI Codex pelo OpenClaw/PI | Você quer autenticação por assinatura ChatGPT/Codex com o executor PI padrão. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness do app-server do Codex | Você quer autenticação por assinatura ChatGPT/Codex com execução nativa do Codex. | -GPT-5.5 pode aparecer tanto em rotas diretas com chave de API OpenAI quanto em rotas de assinatura Codex -quando sua conta as expõe. Use `openai/gpt-5.5` com o harness do app-server do Codex -para runtime nativo do Codex, `openai-codex/gpt-5.5` para OAuth por PI, ou +GPT-5.5 pode aparecer em rotas de chave de API direta da OpenAI e de assinatura do Codex +quando sua conta as expõe. Use `openai/gpt-5.5` com o harness do app-server +do Codex para runtime nativo do Codex, `openai-codex/gpt-5.5` para OAuth pelo PI, ou `openai/gpt-5.5` sem uma substituição de runtime do Codex para tráfego direto por chave de API. -Referências legadas `codex/gpt-*` continuam sendo 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 usadas apenas como fallback -são deixadas inalteradas porque o runtime é configurado para todo o contêiner do agente. -Novas configurações OAuth do Codex por PI devem usar `openai-codex/gpt-*`; novas configurações do harness -nativo do app-server devem usar `openai/gpt-*` mais +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 +ficam inalteradas porque o runtime é configurado para todo o contêiner do agente. +Novas configurações de OAuth PI do Codex devem usar `openai-codex/gpt-*`; novas configurações nativas +do 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 ser executada pelo caminho do provedor OAuth -OpenAI Codex. Use `codex/gpt-*` quando a compreensão de imagem deve ser executada +`openai-codex/gpt-*` quando o entendimento de imagem deve ser executado pelo caminho de provedor OAuth +OpenAI Codex. Use `codex/gpt-*` quando o entendimento de imagem deve ser executado por um turno limitado 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. +anunciar suporte a entrada de imagem; modelos Codex somente 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 surpreender, habilite logs de depuração para o subsistema `agents/harness` +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, +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 os avisos do doctor significam -`openclaw doctor` avisa quando tudo isso é verdadeiro: +`openclaw doctor` avisa quando todos estes itens são verdadeiros: - 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 os usuários muitas vezes esperam que "Plugin Codex habilitado" implique +Esse aviso existe porque usuários costumam esperar que "Plugin do 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 PI. +- **Nenhuma alteração é necessária** se você pretendia usar OAuth ChatGPT/Codex pelo 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 os pins de runtime da sessão são persistentes. +- Sessões existentes ainda precisam de `/new` ou `/reset` depois de 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 +o OpenClaw registra o id do harness selecionado nessa sessão e continua a usá-lo 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 mesma transcrição por -dois sistemas incompatíveis de sessão nativa. +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 dois sistemas de sessão nativa +incompatíveis. -Sessões legadas criadas antes das fixações de harness são tratadas como fixadas em PI assim que -têm histórico de transcrição. Use `/new` ou `/reset` para fazer essa conversa optar pelo -Codex depois de alterar a configuração. +As sessões legadas criadas antes das fixações do ambiente de execução são tratadas como fixadas ao Pi assim que +tiverem histórico de transcrição. Use `/new` ou `/reset` para optar por incluir essa conversa no +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 Codex aparece como +`/status` mostra o runtime efetivo do modelo. O ambiente de execução padrão do Pi aparece como +`Runtime: OpenClaw Pi Default`, e o ambiente de execução do servidor de aplicativo do Codex aparece como `Runtime: OpenAI Codex`. ## Requisitos - OpenClaw com o Plugin `codex` incluído disponível. -- App-server Codex `0.125.0` ou mais recente. O Plugin incluído gerencia um binário - app-server Codex compatível por padrão, então comandos `codex` locais no `PATH` não - afetam a inicialização normal do harness. -- Autenticação Codex disponível para o processo app-server ou para a ponte de autenticação - Codex do OpenClaw. Inicializações locais do app-server usam uma home Codex gerenciada - pelo OpenClaw para cada agente e uma `HOME` filha isolada, então elas não leem sua conta - pessoal `~/.codex`, Skills, plugins, configuração, estado de threads ou - `$HOME/.agents/skills` nativos por padrão. +- Servidor de aplicativo do Codex `0.125.0` ou mais recente. O Plugin incluído gerencia um binário + compatível do servidor de aplicativo do Codex por padrão, portanto comandos `codex` locais no `PATH` não + afetam a inicialização normal do ambiente de execução. +- Autenticação do Codex disponível para o processo do servidor de aplicativo ou para a ponte de autenticação Codex + do OpenClaw. Inicializações locais do servidor de aplicativo usam uma home do Codex gerenciada pelo OpenClaw para cada + agente e um `HOME` filho isolado, portanto, por padrão, elas não leem sua conta pessoal + `~/.codex`, Skills, plugins, configuração, estado de threads ou + `$HOME/.agents/skills` nativo. -O Plugin bloqueia handshakes de app-server mais antigos ou sem versão. Isso mantém o +O Plugin bloqueia handshakes de servidor de aplicativo mais antigos ou sem versão. Isso mantém o OpenClaw na superfície de protocolo contra a qual ele 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. +Para testes smoke 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 servidor de aplicativo via stdio +também podem recorrer a `CODEX_API_KEY` / `OPENAI_API_KEY` quando nenhuma conta estiver presente. ## Arquivos de bootstrap do workspace -O Codex lida com `AGENTS.md` por conta própria por meio da descoberta nativa de docs de projeto. O OpenClaw -não escreve arquivos sintéticos de docs de projeto Codex nem depende de nomes de arquivo fallback do Codex +O Codex lida com `AGENTS.md` por conta própria por meio da descoberta nativa de documentação de projeto. O OpenClaw +não grava arquivos sintéticos de documentação de projeto do Codex nem depende de nomes de arquivo de fallback do Codex para arquivos de persona, porque os fallbacks do Codex só se aplicam quando `AGENTS.md` está ausente. -Para paridade do workspace OpenClaw, o harness Codex resolve os outros arquivos de bootstrap +Para paridade de workspace do OpenClaw, o ambiente de execução do Codex resolve os outros arquivos de bootstrap (`SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, -`BOOTSTRAP.md` e `MEMORY.md` quando presentes) e os encaminha por meio das instruções de configuração do Codex +`BOOTSTRAP.md` e `MEMORY.md`, quando presentes) e os encaminha pelas instruções de configuração do Codex em `thread/start` e `thread/resume`. Isso mantém `SOUL.md` e o contexto relacionado de persona/perfil do workspace visíveis sem duplicar `AGENTS.md`. -## Adicionar Codex junto de outros modelos +## Adicionar Codex ao lado de outros modelos Não defina `agentRuntime.id: "codex"` globalmente se o mesmo agente deve alternar livremente -entre Codex e modelos de provedores não Codex. Um runtime forçado se aplica a cada -turno incorporado para esse agente ou sessão. Se você selecionar um modelo Anthropic enquanto -esse runtime estiver forçado, o OpenClaw ainda tenta o harness Codex e falha fechado -em vez de rotear silenciosamente esse turno pelo PI. +entre o Codex e modelos de provedores nã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á usar o ambiente de execução do Codex e falhará de modo fechado +em vez de encaminhar silenciosamente esse turno pelo Pi. -Use uma destas formas: +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 PI para uso misto normal +- Mantenha o agente padrão em `agentRuntime.id: "auto"` e o fallback do Pi para uso normal misto de provedores. -- Use refs legadas `codex/*` apenas para compatibilidade. Novas configurações devem preferir - `openai/*` mais uma política explícita de runtime Codex. +- 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 adiciona um agente Codex separado: @@ -336,38 +335,39 @@ adiciona um agente Codex separado: } ``` -Com esta forma: +Com este formato: -- O agente `main` padrão usa o caminho normal de provedor e o fallback de compatibilidade PI. -- O agente `codex` usa o harness do app-server Codex. +- O agente padrão `main` usa o caminho normal do provedor e o fallback de compatibilidade do Pi. +- O agente `codex` usa o ambiente de execução do servidor de aplicativo 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. + em vez de usar o Pi silenciosamente. ## Roteamento de comandos de agente -Agentes devem rotear solicitações do usuário por intenção, não apenas pela palavra "Codex": +Os agentes devem rotear solicitações de usuário por intenção, não apenas pela palavra "Codex": -| O usuário pede... | O agente deve usar... | +| Usuário pede para... | Agente deve usar... | | ------------------------------------------------------ | ------------------------------------------------ | -| "Vincule este chat ao Codex" | `/codex bind` | -| "Retome a thread Codex `` aqui" | `/codex resume ` | -| "Mostre as threads Codex" | `/codex threads` | -| "Abra 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 minha assinatura ChatGPT/Codex com runtime Codex" | `openai/*` mais `agentRuntime.id: "codex"` | -| "Use minha assinatura ChatGPT/Codex por meio do PI" | refs de modelo `openai-codex/*` | -| "Execute Codex por 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 | +| "Vincular este chat ao Codex" | `/codex bind` | +| "Retomar thread do Codex `` aqui" | `/codex resume ` | +| "Mostrar threads do Codex" | `/codex threads` | +| "Registrar um relatório de suporte para uma execução ruim do Codex" | `/diagnostics [note]` | +| "Enviar feedback do Codex apenas para esta thread anexada" | `/codex diagnostics [note]` | +| "Usar minha assinatura do ChatGPT/Codex com runtime do Codex" | `openai/*` mais `agentRuntime.id: "codex"` | +| "Usar minha assinatura do ChatGPT/Codex pelo Pi" | referências de modelo `openai-codex/*` | +| "Executar Codex por ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Iniciar Claude Code/Gemini/OpenCode/Cursor em uma 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, -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 ACP. +O OpenClaw só anuncia orientação de spawn do ACP para agentes quando o ACP está habilitado, +pode ser despachado e é apoiado por um backend de runtime carregado. Se o ACP não estiver disponível, +o prompt do sistema e as Skills de Plugin não devem ensinar o agente sobre roteamento +do ACP. -## Implantações somente Codex +## Implantações somente com Codex -Force o harness Codex quando precisar provar que todo turno de agente incorporado -usa Codex. Runtimes explícitos de Plugin falham fechados e nunca são tentados de novo -silenciosamente por meio do PI: +Force o ambiente de execução do Codex quando precisar provar que cada turno de agente incorporado +usa Codex. Runtimes explícitos de Plugin falham de modo fechado e nunca são repetidos silenciosamente +pelo Pi: ```json5 { @@ -388,13 +388,13 @@ Sobrescrita de ambiente: 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 puder iniciar. +Com Codex forçado, o OpenClaw falha cedo se o Plugin Codex estiver desativado, o +servidor de aplicativo for antigo demais ou o servidor de aplicativo não conseguir iniciar. ## Codex por agente -Você pode tornar um agente somente Codex enquanto o agente padrão mantém -a seleção automática normal: +Você pode tornar um agente exclusivo para Codex enquanto o agente padrão mantém a +seleção automática normal: ```json5 { @@ -423,15 +423,15 @@ a seleção automática normal: } ``` -Use comandos normais de sessão para alternar agentes e modelos. `/new` cria uma sessão -OpenClaw nova, e o harness Codex cria ou retoma sua thread sidecar do app-server -conforme necessário. `/reset` limpa a vinculação da sessão OpenClaw para essa thread -e permite que o próximo turno resolva o harness a partir da configuração atual novamente. +Use comandos normais de sessão para alternar agentes e modelos. `/new` cria uma nova +sessão do OpenClaw, e o ambiente de execução do Codex cria ou retoma sua thread +auxiliar de servidor de aplicativo conforme necessário. `/reset` limpa a vinculação da sessão do OpenClaw para essa thread +e permite que o próximo turno resolva o ambiente de execução a partir da configuração atual novamente. ## Descoberta de modelos -Por padrão, o Plugin Codex pergunta ao app-server pelos modelos disponíveis. Se -a descoberta falhar ou atingir timeout, ele usa um catálogo fallback incluído para: +Por padrão, o Plugin Codex pede ao servidor de aplicativo os modelos disponíveis. Se a +descoberta falhar ou atingir o tempo limite, ele usa um catálogo de fallback incluído para: - GPT-5.5 - GPT-5.4 mini @@ -457,8 +457,8 @@ Você pode ajustar a descoberta em `plugins.entries.codex.config.discovery`: } ``` -Desabilite a descoberta quando quiser que a inicialização evite sondar o Codex e fique com o -catálogo fallback: +Desative a descoberta quando quiser que a inicialização evite sondar o Codex e fique no +catálogo de fallback: ```json5 { @@ -477,24 +477,24 @@ catálogo fallback: } ``` -## Conexão e política do app-server +## Conexão e política do servidor de aplicativo -Por padrão, o Plugin inicia localmente o binário Codex gerenciado pelo OpenClaw com: +Por padrão, o Plugin inicia localmente o binário gerenciado do Codex do OpenClaw com: ```bash codex app-server --listen stdio:// ``` O binário gerenciado é enviado com o pacote do Plugin `codex`. Isso mantém a -versão do app-server vinculada ao Plugin incluído em vez de qualquer CLI Codex separada -que por acaso esteja instalada localmente. Defina `appServer.command` apenas quando +versão do servidor de aplicativo vinculada ao Plugin incluído em vez de qualquer CLI +Codex separada que por acaso esteja instalada localmente. Defina `appServer.command` apenas 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 ambiente de execução do Codex no modo YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` e `sandbox: "danger-full-access"`. Esta é a postura confiável de operador local 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á presente para responder. +parar em prompts de aprovação nativos que ninguém está por perto para responder. Para optar por aprovações revisadas pelo guardião do Codex, defina `appServer.mode: "guardian"`: @@ -517,21 +517,21 @@ Para optar por aprovações revisadas pelo guardião do Codex, defina `appServer } ``` -O modo Guardian usa o caminho de aprovação com revisão automática nativa 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 -prompt humano. O revisor aplica a estrutura de risco do Codex e aprova ou nega -a solicitação específica. Use Guardian quando quiser mais proteções do que no modo YOLO -mas ainda precisar que agentes desacompanhados avancem. +O modo guardião usa o caminho de aprovação com revisão automática nativo do Codex. Quando o Codex pede para +sair da sandbox, gravar fora do workspace ou adicionar permissões como acesso à rede, +o Codex encaminha 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 que o modo YOLO, +mas ainda precisar que agentes não supervisionados avancem. -O preset `guardian` se expande para `approvalPolicy: "on-request"`, +A predefinição `guardian` se expande para `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` e `sandbox: "workspace-write"`. -Campos de política individuais ainda sobrescrevem `mode`, então implantações avançadas podem misturar -o preset com escolhas explícitas. O valor antigo de revisor `guardian_subagent` ainda é -aceito como alias de compatibilidade, mas novas configurações devem usar +Campos de política individuais ainda sobrescrevem `mode`, portanto implantações avançadas podem combinar +a predefinição 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`. -Para um app-server já em execução, use transporte WebSocket: +Para um servidor de aplicativo já em execução, use transporte WebSocket: ```json5 { @@ -553,46 +553,46 @@ 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, -mas o OpenClaw é dono da ponte de conta do app-server Codex e define tanto -`CODEX_HOME` quanto `HOME` para diretórios por agente sob o estado OpenClaw +Inicializações do servidor de aplicativo via stdio herdam o ambiente de processo do OpenClaw por padrão, +mas o OpenClaw possui a ponte de conta do servidor de aplicativo do Codex e define tanto +`CODEX_HOME` quanto `HOME` para diretórios por agente sob o estado do 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 -escopados ao agente OpenClaw em vez de vazarem da home pessoal da CLI Codex +`$HOME/.agents/skills`, portanto ambos os valores são isolados para inicializações locais do servidor de aplicativo. +Isso mantém Skills, plugins, configuração, contas e estado de threads nativos do Codex +escopados ao agente OpenClaw em vez de vazarem da home pessoal da CLI do Codex do operador. -Plugins OpenClaw e snapshots de Skills OpenClaw ainda fluem pelo próprio -registro de plugins e carregador de Skills do OpenClaw. Ativos pessoais da CLI Codex não. Se você tiver -Skills ou plugins úteis da CLI Codex que devem se tornar parte de um agente OpenClaw, -inventarie-os explicitamente: +Plugins do OpenClaw e snapshots de Skills do OpenClaw ainda fluem pelo próprio +registro de Plugins e carregador de Skills do OpenClaw. Ativos pessoais da CLI do Codex não. Se você tiver +Skills ou plugins úteis da CLI do Codex que devam se tornar parte de um agente OpenClaw, +faça um inventário deles explicitamente: ```bash openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -O provedor de migração Codex copia Skills para o workspace atual do agente OpenClaw. +O provedor de migração do Codex copia Skills para o workspace atual do agente OpenClaw. Plugins, hooks e arquivos de configuração nativos do Codex são relatados ou arquivados -para revisão manual em vez de serem ativados automaticamente, porque eles podem +para revisão manual em vez de serem ativados automaticamente, porque podem executar comandos, expor servidores MCP ou carregar credenciais. A autenticação é selecionada nesta ordem: 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 é necessária. +2. A conta existente do servidor de aplicativo na home do Codex desse agente. +3. Apenas para inicializações locais do servidor de aplicativo via stdio, `CODEX_API_KEY`, depois + `OPENAI_API_KEY`, quando nenhuma conta de servidor de aplicativo estiver presente e a autenticação da OpenAI + ainda for necessária. -Quando o OpenClaw vê um perfil de autenticação Codex em estilo de assinatura ChatGPT, ele remove -`CODEX_API_KEY` e `OPENAI_API_KEY` do processo filho Codex gerado. 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 cobrarem pela API por acidente. -Perfis explícitos de chave de API Codex e fallback local de chave de env por stdio usam login do app-server -em vez de env herdado do processo filho. Conexões WebSocket do app-server -não recebem fallback de chave de API env do Gateway; use um perfil explícito de autenticação ou a -conta própria do app-server remoto. +Quando o OpenClaw vê um perfil de autenticação Codex no estilo de assinatura do ChatGPT, ele remove +`CODEX_API_KEY` e `OPENAI_API_KEY` do processo filho do Codex gerado. Isso +mantém chaves de API no nível do Gateway disponíveis para embeddings ou modelos OpenAI diretos +sem fazer com que turnos nativos do servidor de aplicativo do Codex sejam cobrados pela API por acidente. +Perfis explícitos de chave de API do Codex e fallback de chave de ambiente via stdio local usam login do servidor de aplicativo +em vez de ambiente herdado do processo filho. Conexões WebSocket ao servidor de aplicativo +não recebem fallback de chave de API de ambiente do Gateway; use um perfil de autenticação explícito ou a +conta própria do servidor de aplicativo remoto. Se uma implantação precisar de isolamento adicional de ambiente, adicione essas variáveis a `appServer.clearEnv`: @@ -614,54 +614,53 @@ Se uma implantação precisar de isolamento adicional de ambiente, adicione essa } ``` -`appServer.clearEnv` afeta apenas o processo filho app-server do Codex gerado. +`appServer.clearEnv` afeta apenas o processo filho do app-server do Codex gerado. As ferramentas dinâmicas do Codex usam por padrão o perfil `native-first`. Nesse modo, -o OpenClaw não expõe ferramentas dinâmicas que duplicam operações nativas do Codex no workspace: -`read`, `write`, `edit`, `apply_patch`, `exec`, `process` e +o OpenClaw não expõe ferramentas dinâmicas que duplicam operações nativas de workspace +do Codex: `read`, `write`, `edit`, `apply_patch`, `exec`, `process` e `update_plan`. Ferramentas de integração do OpenClaw, como mensagens, sessões, mídia, -cron, navegador, nós, gateway, `heartbeat_respond` e `web_search` permanecem +cron, navegador, nós, gateway, `heartbeat_respond` e `web_search`, continuam disponíveis. -Campos de nível superior compatíveis do Plugin Codex: +Campos de nível superior do Plugin Codex com suporte: | Campo | Padrão | Significado | -| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | Use `"openclaw-compat"` para expor ao app-server do Codex o conjunto completo de ferramentas dinâmicas do OpenClaw. | +| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------- | +| `codexDynamicToolsProfile` | `"native-first"` | Use `"openclaw-compat"` para expor o conjunto completo de ferramentas dinâmicas do OpenClaw ao app-server do Codex. | | `codexDynamicToolsExclude` | `[]` | Nomes adicionais de ferramentas dinâmicas do OpenClaw a omitir dos turnos do app-server do Codex. | -Campos `appServer` compatíveis: +Campos de `appServer` com suporte: | Campo | Padrão | Significado | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` inicia o Codex; `"websocket"` conecta a `url`. | -| `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. | +| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` inicia o Codex; `"websocket"` se conecta a `url`. | +| `command` | binário gerenciado do Codex | Executável para transporte stdio. Deixe indefinido 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 WebSocket do app-server. | -| `authToken` | não definido | Token Bearer para transporte WebSocket. | -| `headers` | `{}` | Cabeçalhos WebSocket extras. | +| `url` | indefinido | URL WebSocket do app-server. | +| `authToken` | indefinido | Token Bearer para transporte WebSocket. | +| `headers` | `{}` | Cabeçalhos WebSocket extras. | | `clearEnv` | `[]` | Nomes extras de variáveis de ambiente removidos do processo app-server stdio gerado 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 do plano de controle do app-server. | -| `mode` | `"yolo"` | Predefinição para execução YOLO ou revisada por guardião. | -| `approvalPolicy` | `"never"` | Política nativa de aprovação do Codex enviada para início/retomada/turno de thread. | -| `sandbox` | `"danger-full-access"` | Modo nativo de sandbox do Codex enviado para início/retomada de thread. | -| `approvalsReviewer` | `"user"` | Use `"auto_review"` para permitir que o Codex revise prompts nativos de aprovação. `guardian_subagent` permanece como alias legado. | -| `serviceTier` | não definido | Camada de serviço opcional do app-server do Codex: `"fast"`, `"flex"` ou `null`. Valores legados inválidos são ignorados. | +| `requestTimeoutMs` | `60000` | Tempo limite para chamadas do 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 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` continua sendo um alias legado. | +| `serviceTier` | indefinido | Camada de serviço opcional do app-server do Codex: `"fast"`, `"flex"` ou `null`. Valores legados inválidos são ignorados. | -As chamadas de ferramentas dinâmicas pertencentes ao OpenClaw são limitadas independentemente de -`appServer.requestTimeoutMs`: cada solicitação Codex `item/tool/call` deve receber +Chamadas de ferramentas dinâmicas de propriedade do OpenClaw são limitadas independentemente de +`appServer.requestTimeoutMs`: cada solicitação `item/tool/call` do Codex deve receber uma resposta do OpenClaw em até 30 segundos. Em caso de tempo limite, o OpenClaw aborta o sinal da ferramenta -quando compatível e retorna ao Codex uma resposta de ferramenta dinâmica com falha para que -o turno possa continuar, em vez de deixar a sessão em `processing`. +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 +Depois que o OpenClaw responde a uma solicitação do 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 em silêncio por 60 segundos após essa resposta, o OpenClaw tenta -interromper 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 posteriores não fiquem enfileiradas atrás de um -turno nativo obsoleto. +app-server ficar sem responder por 60 segundos após essa resposta, o OpenClaw tenta, em melhor esforço, +interromper o turno do Codex, registra um tempo limite de diagnóstico e libera a raia da sessão do +OpenClaw para que mensagens de chat seguintes não fiquem enfileiradas atrás de um turno nativo obsoleto. -Substituições de ambiente permanecem disponíveis para testes locais: +Substituições de ambiente continuam disponíveis para testes locais: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -670,28 +669,28 @@ Substituições de ambiente permanecem disponíveis para testes locais: - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` `OPENCLAW_CODEX_APP_SERVER_BIN` ignora o binário gerenciado quando -`appServer.command` não está definido. +`appServer.command` está indefinido. `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 Codex. +mesmo arquivo revisado que o restante da configuração do harness do Codex. ## Uso do computador -O Computer Use é abordado em seu próprio guia de configuração: -[Codex Computer Use](/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 resumida: o OpenClaw não inclui o aplicativo de controle de desktop nem executa +A versão curta: o OpenClaw não inclui como vendored o aplicativo de controle de desktop nem executa ações de desktop 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 ferramenta MCP durante turnos em modo Codex. +servidor MCP `computer-use` está disponível e então permite que o Codex lide com as chamadas nativas de ferramentas +MCP durante turnos em modo Codex. -Para acesso direto ao driver TryCua fora do fluxo de marketplace do Codex, registre +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 [Codex Computer Use](/pt-BR/plugins/codex-computer-use) para ver a distinção -entre o Computer Use pertencente ao Codex e o registro MCP direto. +Veja [Uso do computador do Codex](/pt-BR/plugins/codex-computer-use) para a distinção +entre Uso do computador pertencente ao Codex e registro MCP direto. Configuração mínima: @@ -720,26 +719,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 ` -Computer Use é específico do macOS e pode exigir permissões locais do sistema operacional antes que o -servidor MCP do Codex consiga controlar aplicativos. Se `computerUse.enabled` for true e o servidor MCP -não estiver disponível, turnos em modo Codex falham antes de a thread iniciar, em vez de -executarem silenciosamente sem as ferramentas nativas de Computer Use. Consulte -[Codex Computer Use](/pt-BR/plugins/codex-computer-use) para opções de marketplace, -limites de 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 aplicativos. Se `computerUse.enabled` for true e o servidor MCP +estiver indisponível, turnos em modo Codex falham antes que a thread seja iniciada, em vez de +executar silenciosamente sem as ferramentas nativas de Uso do computador. Veja +[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. -Quando `computerUse.autoInstall` é true, o OpenClaw pode registrar o marketplace -padrão incluído do Codex Desktop a partir de +Quando `computerUse.autoInstall` é true, o OpenClaw pode registrar o marketplace padrão +incluído do Codex Desktop a partir 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 Computer Use para que sessões existentes não mantenham uma associação antiga de -PI ou thread do Codex. +alterar a configuração de runtime ou de Uso do computador para que sessões existentes não mantenham uma vinculação antiga +de PI ou thread do Codex. ## Receitas comuns @@ -757,7 +756,7 @@ Codex local com transporte stdio padrão: } ``` -Validação do harness somente Codex: +Validação do harness somente com Codex: ```json5 { @@ -779,7 +778,7 @@ Validação do harness somente Codex: } ``` -Aprovações Codex revisadas por guardião: +Aprovações do Codex revisadas pelo guardian: ```json5 { @@ -824,87 +823,91 @@ App-server remoto com cabeçalhos explícitos: } ``` -A troca de modelos permanece controlada pelo OpenClaw. Quando uma sessão do OpenClaw está anexada +A troca de modelo permanece controlada pelo OpenClaw. Quando uma sessão do OpenClaw está anexada a uma thread existente do Codex, o próximo turno envia novamente ao -app-server o modelo OpenAI, o provedor, a política de aprovação, o sandbox e a camada de serviço -selecionados no momento. Trocar de `openai/gpt-5.5` para `openai/gpt-5.2` mantém a -associação da thread, mas solicita que o Codex continue com o modelo recém-selecionado. +app-server o modelo OpenAI, provedor, política de aprovação, sandbox e camada de serviço +atualmente selecionados. 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 modelo recém-selecionado. ## Comando Codex O Plugin incluído 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. +genérico e funciona em qualquer canal que dê suporte a comandos de texto do OpenClaw. Formas comuns: -- `/codex status` mostra conectividade ativa do servidor de aplicativo, modelos, conta, limites de taxa, servidores MCP e Skills. -- `/codex models` lista os modelos ativos do servidor de aplicativo Codex. +- `/codex status` mostra conectividade ativa com o servidor de aplicativo, modelos, conta, limites de taxa, servidores MCP e Skills. +- `/codex models` lista os modelos ativos do servidor de aplicativo do Codex. - `/codex threads [filter]` lista threads recentes do Codex. -- `/codex resume ` anexa a sessão OpenClaw atual a uma thread existente do Codex. -- `/codex compact` pede ao servidor de aplicativo Codex para compactar a thread anexada. +- `/codex resume ` anexa a sessão atual do OpenClaw a uma thread existente do Codex. +- `/codex compact` pede ao servidor de aplicativo do Codex para compactar a thread anexada. - `/codex review` inicia a revisão nativa do Codex para a thread anexada. -- `/codex diagnostics [note]` pede confirmação antes de enviar feedback de diagnóstico do Codex para a thread anexada. -- `/codex computer-use status` verifica o Plugin Computer Use configurado e o servidor MCP. -- `/codex computer-use install` instala o Plugin Computer Use configurado e recarrega os servidores MCP. +- `/codex diagnostics [note]` solicita confirmação antes de enviar feedback de diagnóstico do Codex para a thread anexada. +- `/codex computer-use status` verifica o plugin Computer Use configurado e o servidor MCP. +- `/codex computer-use install` instala o plugin Computer Use configurado e recarrega os servidores MCP. - `/codex account` mostra o status da conta e dos limites de taxa. -- `/codex mcp` lista o status dos servidores MCP do servidor de aplicativo Codex. -- `/codex skills` lista as Skills do servidor de aplicativo Codex. +- `/codex mcp` lista o status dos servidores MCP do servidor de aplicativo do Codex. +- `/codex skills` lista as Skills do servidor de aplicativo do Codex. -### Fluxo de depuração comum +Quando o Codex relata uma falha de limite de uso, o OpenClaw inclui o próximo +horário de redefinição do servidor de aplicativo quando o Codex fornece um. Use `/codex account` na mesma +conversa para inspecionar a conta atual e as janelas de limite de taxa. -Quando um agente baseado em Codex faz algo inesperado no Telegram, Discord, Slack, -ou em outro canal, comece pela conversa em que o problema aconteceu: +### Fluxo comum de depuração -1. Execute `/diagnostics bad tool choice after image upload` ou outra observação curta +Quando um agente baseado no Codex faz algo inesperado no Telegram, Discord, Slack, +ou outro canal, comece pela conversa onde 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 ambiente de execução do Codex, - também envia o pacote relevante de feedback do Codex para os servidores da OpenAI. + diagnóstico do Gateway e, como a sessão está usando o harness do Codex, também + envia o pacote de feedback relevante do Codex 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 do OpenClaw, ids de thread do Codex e uma linha `Inspect locally` para cada thread do Codex. -4. Se quiser depurar a execução por conta própria, execute o comando `Inspect locally` +4. Se você 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, + 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 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) +Use `/codex diagnostics [note]` somente quando você quiser especificamente o upload de +feedback do Codex para a thread atualmente anexada 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 o modelo completo de privacidade e o comportamento em chats de grupo. -O núcleo do OpenClaw também expõe `/diagnostics [note]`, somente para proprietários, como o comando geral de -diagnósticos do Gateway. O prompt de aprovação mostra o preâmbulo de dados sensíveis, -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 OpenClaw ativa está usando o ambiente de execução do Codex, essa -mesma aprovação também autoriza o envio dos pacotes relevantes de feedback do Codex para +O núcleo do OpenClaw também expõe `/diagnostics [note]`, somente para proprietários, como o comando geral +de diagnósticos do Gateway. O prompt de aprovação mostra o preâmbulo de dados sensíveis, +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 exec +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 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 diz 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 de 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 +preâmbulo de diagnóstico, 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 rota privada para o proprietário, -o OpenClaw recusa a solicitação do grupo e pede que o proprietário a execute em uma DM. +o OpenClaw recusa a solicitação do grupo e pede que o proprietário a execute por DM. -O envio aprovado do Codex chama `feedback/upload` do servidor de aplicativo Codex e pede -ao servidor de aplicativo que inclua logs para cada thread listada e subthreads Codex geradas -quando disponíveis. O envio passa pelo caminho normal de feedback do Codex para os servidores da OpenAI; +O upload aprovado do Codex chama `feedback/upload` no servidor de aplicativo do Codex e pede +ao servidor de aplicativo para incluir 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 servidor de aplicativo, o comando retorna o erro do servidor de aplicativo. A resposta de diagnóstico 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 envio não substitui a exportação local +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 auxiliar de vínculo que o ambiente de execução usa para +`/codex resume` grava o mesmo arquivo de associação auxiliar que o harness usa para turnos normais. Na próxima mensagem, o OpenClaw retoma essa thread do Codex, passa o -modelo OpenClaw selecionado no momento para o servidor de aplicativo, e mantém o histórico estendido +modelo OpenClaw selecionado no momento para o servidor de aplicativo e mantém o histórico estendido ativado. ### Inspecionar uma thread do Codex pela CLI @@ -917,134 +920,134 @@ codex resume ``` Use isso quando notar 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 +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ê aprovar, o relatório concluído lista +`/diagnostics [note]` primeiro: depois que você o aprova, o relatório concluído lista cada thread do Codex e imprime um comando `Inspect locally`, por exemplo `codex resume `. Você pode copiar esse comando diretamente para um terminal. Você também pode obter um id de thread em `/codex binding` para o chat atual ou -`/codex threads [filter]` para threads recentes do servidor de aplicativo Codex, e então executar o mesmo +`/codex threads [filter]` para threads recentes do servidor de aplicativo do Codex e, em seguida, executar o mesmo comando `codex resume` no seu shell. -A superfície de comandos exige o servidor de aplicativo Codex `0.125.0` ou mais recente. Métodos +A superfície de comandos exige o servidor de aplicativo do Codex `0.125.0` ou mais recente. Métodos individuais de controle são relatados como `unsupported by this Codex app-server` se um servidor de aplicativo futuro ou personalizado não expuser esse método JSON-RPC. ## Limites de hooks -O ambiente de execução do Codex tem três camadas de hook: +O harness do Codex tem três camadas de hook: -| Camada | Proprietário | Finalidade | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Hooks de Plugin do OpenClaw | OpenClaw | Compatibilidade de produto/Plugin entre ambientes de execução PI e Codex. | -| Middleware de extensão do servidor de aplicativo Codex | Plugins incluídos no OpenClaw | Comportamento do adaptador por turno em torno de ferramentas dinâmicas do OpenClaw. | -| Hooks nativos do Codex | Codex | Ciclo de vida Codex de baixo nível e política nativa de ferramentas da configuração do Codex. | +| Camada | Proprietário | Finalidade | +| ------------------------------------- | ------------------------- | ------------------------------------------------------------------- | +| Hooks de plugins do OpenClaw | OpenClaw | Compatibilidade de produto/plugin entre harnesses de PI e Codex. | +| Middleware de extensão do servidor de aplicativo do Codex | Plugins incluídos do OpenClaw | Comportamento de 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 pela configuração do Codex. | O OpenClaw não usa arquivos `hooks.json` globais ou de projeto do Codex para rotear -comportamento de Plugins do OpenClaw. Para a ponte compatível de ferramenta nativa e permissões, -o OpenClaw injeta configuração Codex por thread para `PreToolUse`, `PostToolUse`, +comportamento de plugins 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. +`UserPromptSubmit`, continuam sendo controles em nível do Codex; eles não são expostos como +hooks de plugins do OpenClaw no contrato v1. -Para ferramentas dinâmicas do OpenClaw, o OpenClaw executa a ferramenta depois que o Codex pede a -chamada, então o OpenClaw dispara o comportamento de Plugin e middleware que ele possui no -adaptador do ambiente de execução. Para ferramentas nativas do Codex, o Codex possui o registro canônico da ferramenta. +Para ferramentas dinâmicas do OpenClaw, o OpenClaw executa a ferramenta depois que o Codex solicita a +chamada, então o OpenClaw aciona o comportamento de plugin e middleware que ele possui no +adaptador de 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 servidor de aplicativo ou callbacks de hook nativo. +a menos que o Codex exponha essa operação pelo servidor de aplicativo ou por callbacks de hook nativo. -Projeções de Compaction e ciclo de vida de LLM vêm de notificações do servidor de aplicativo Codex -e do estado do adaptador OpenClaw, não de comandos de hook nativo do Codex. +Projeções de Compaction e ciclo de vida de LLM vêm de notificações do servidor de aplicativo do Codex +e do estado do adaptador do OpenClaw, não de comandos de hook 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 +`llm_output` do OpenClaw são observações em nível de 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 pelo servidor de aplicativo são +As notificações `hook/started` e `hook/completed` nativas do Codex no servidor de aplicativo 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. +Elas não invocam hooks de plugins do OpenClaw. -## Contrato de suporte v1 +## Contrato de suporte V1 -O modo Codex não é PI com uma chamada de modelo diferente por baixo. O Codex controla mais do -loop nativo do modelo, e o OpenClaw adapta suas superfícies de Plugin e sessão +O modo Codex não é PI com uma chamada de modelo diferente por baixo. O Codex possui mais do +loop de modelo nativo, e o OpenClaw adapta suas superfícies de plugin e sessão em torno desse limite. -Compatível no tempo de execução Codex v1: +Compatível no runtime Codex v1: -| Superfície | Suporte | Por quê | -| --------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Loop de modelo OpenAI por meio do Codex | Compatível | O servidor de aplicativo Codex controla o turno OpenAI, retomada de thread nativa e 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 tempo de execução do modelo. | -| Ferramentas dinâmicas do OpenClaw | Compatível | O Codex pede ao OpenClaw para executar 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 rodam para turnos Codex. | -| Hooks de ferramentas dinâmicas | Compatível | `before_tool_call`, `after_tool_call` e middleware de resultado de ferramenta rodam em torno de ferramentas dinâmicas pertencentes ao OpenClaw. | -| Hooks de ciclo de vida | Compatíveis 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 de resposta final | Compatível por meio do relé de hook nativo | `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 nativo, patch e MCP | Compatível por meio do relé de hook nativo | `PreToolUse` e `PostToolUse` do Codex são retransmitidos para superfícies confirmadas de ferramentas nativas, incluindo payloads MCP no servidor de aplicativo Codex `0.125.0` ou mais recente. Bloqueio é compatível; reescrita de argumentos não. | -| Política de permissão nativa | Compatível por meio do relé de hook nativo | `PermissionRequest` do Codex pode ser roteado pela política do OpenClaw onde o tempo de execução a expõe. Se o OpenClaw não retornar decisão, o Codex continua por seu caminho normal de guardião ou aprovação do usuário. | -| Captura de trajetória do servidor de aplicativo | Compatível | O OpenClaw registra a solicitação que enviou ao servidor de aplicativo e as notificações do servidor de aplicativo que recebe. | +| Superfície | Suporte | Por quê | +| --------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Loop de modelo da OpenAI pelo Codex | Compatível | O servidor de aplicativo 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 ao OpenClaw para executar 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 motor de contexto | Compatível | Montagem, ingestão ou manutenção pós-turno e coordenação de Compaction do motor 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 pertencentes ao OpenClaw. | +| Hooks de ciclo de vida | Compatíveis 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 de resposta final | Compatível por meio do relay de hook nativo | `Stop` do Codex é repassado 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 repassados para superfícies de ferramentas nativas confirmadas, incluindo payloads MCP no servidor de aplicativo do Codex `0.125.0` ou mais recente. Bloqueio é compatível; 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 guardião ou aprovação do usuário. | +| Captura de trajetória do servidor de aplicativo | Compatível | O OpenClaw registra a solicitação que enviou ao servidor de aplicativo e as notificações do servidor de aplicativo que recebe. | -Não compatível no tempo de execução Codex v1: +Não compatível no runtime Codex v1: -| Superfície | Limite 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/esquema 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 do thread nativo. O OpenClaw possui um espelho e pode projetar contexto futuro, mas não deve mutar internos sem suporte. | Adicionar APIs explícitas do app-server do Codex se for necessária cirurgia no thread nativo. | -| `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 itens mantidos/removidos, delta de tokens ou payload de resumo. | Precisa de eventos de Compaction do Codex mais ricos. | -| Intervenção de Compaction | Os hooks atuais de Compaction do OpenClaw são em 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 de solicitação da API do 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 API de depuração. | +| Superfície | Limite da V1 | Caminho futuro | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Mutação de argumentos de ferramenta nativa | Hooks nativos pré-ferramenta do Codex podem bloquear, mas o OpenClaw não reescreve argumentos de ferramentas nativas do Codex. | Requer suporte de hook/esquema do Codex para substituir a entrada da ferramenta. | +| Histórico editável de transcrição nativa do Codex | O Codex é dono do histórico canônico da thread nativa. O OpenClaw possui um espelho e pode projetar contexto futuro, mas não deve mutar internos sem suporte. | Adicionar APIs explícitas do app-server do Codex se for necessária cirurgia na thread nativa. | +| `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 itens 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 ficam no nível de notificação no modo Codex. | Adicionar hooks pré/pós-Compaction do Codex se os plugins precisarem vetar ou reescrever a Compaction nativa. | +| Captura byte a byte de solicitação à API do 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 à 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 -O harness do Codex altera apenas o executor de agente embarcado de baixo nível. +O harness do Codex altera apenas o executor de agente incorporado de baixo nível. -O OpenClaw ainda constrói a lista de ferramentas e recebe resultados dinâmicos de ferramentas do -harness. Texto, imagens, vídeo, música, TTS, aprovações e saída de ferramenta de mensagens +O OpenClaw ainda monta 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 hook nativo é intencionalmente genérico, mas o contrato de suporte v1 é -limitado aos caminhos de ferramenta nativa do Codex e de permissão que o OpenClaw testa. No +O relay de hooks nativos é intencionalmente genérico, mas o contrato de suporte da v1 é +limitado aos caminhos de ferramentas e permissões nativos 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 seja uma superfície de Plugin do OpenClaw até que o contrato de runtime o nomeie. +`PostToolUse` e `PermissionRequest`. Não presuma que todo evento de hook futuro do +Codex seja uma superfície de Plugin do OpenClaw até que o contrato do runtime o nomeie. -Para `PermissionRequest`, o OpenClaw só retorna 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 sem -decisão de hook e continua para seu próprio guardião ou caminho de aprovação do usuário. +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 caminho de guardião ou 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 -`"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 enfileirada responde a essa solicitação -nativa do servidor em vez de ser direcionada como contexto extra. Outras solicitações de elicitação -MCP ainda falham fechadas. +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 enfileirada responde a essa solicitação do +servidor nativo em vez de ser direcionada como contexto extra. Outras solicitações de elicitação +MCP ainda falham de forma fechada. -O direcionamento da fila de execução ativa mapeia para `turn/steer` do app-server do Codex. Com o +O direcionamento da fila de execução ativa é mapeado 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 +revisão e Compaction manual do Codex podem rejeitar direcionamento no mesmo turno, caso em que +o OpenClaw usa a fila de acompanhamento quando o modo selecionado permite fallback. Veja [Fila de direcionamento](/pt-BR/concepts/queue-steering). -Quando o modelo selecionado usa o harness do Codex, a Compaction do thread nativo é +Quando o modelo selecionado usa o harness do Codex, a Compaction da thread nativa é delegada ao app-server do Codex. O OpenClaw mantém um espelho de transcrição para histórico -do canal, busca, `/new`, `/reset` e troca futura de modelo ou harness. O +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 app-server os emite. Hoje, o OpenClaw registra apenas -sinais de início e conclusão de Compaction nativa. Ele ainda não expõe um resumo de +sinais de início e conclusão da 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 o thread nativo canônico, `tool_result_persist` atualmente não -reescreve registros de resultado de ferramenta nativa do Codex. Ele só se aplica quando +Como o Codex é dono da thread nativa canônica, `tool_result_persist` atualmente não +reescreve registros de resultados 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`. @@ -1056,10 +1059,10 @@ novas configurações. Selecione um modelo `openai/gpt-*` com `plugins.entries.codex.enabled` e verifique se `plugins.allow` exclui `codex`. -**O OpenClaw usa PI em vez do Codex:** `agentRuntime.id: "auto"` ainda pode usar PI como -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 os testes. Um -runtime Codex forçado falha em vez de recorrer a PI. Depois que o app-server do Codex +**O OpenClaw usa PI em vez de Codex:** `agentRuntime.id: "auto"` ainda pode usar PI como o +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 testes. Um +runtime Codex forçado falha em vez de fazer fallback para PI. Depois que o app-server do Codex é selecionado, suas falhas aparecem diretamente. **O app-server é rejeitado:** atualize o Codex para que o handshake do app-server @@ -1071,19 +1074,19 @@ piso estável de protocolo `0.125.0` é o que o OpenClaw testa. ou desabilite a descoberta. **O transporte WebSocket falha imediatamente:** verifique `appServer.url`, `authToken` -e se o app-server remoto fala a mesma versão do protocolo app-server 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 em seu caminho -normal de provedor no modo `auto`. Se você forçar `agentRuntime.id: "codex"`, todo turno -embarcado desse agente deve ser um modelo OpenAI compatível com Codex. +`codex/*`. Referências simples `openai/gpt-*` e de outros provedores permanecem no caminho +normal do provedor no modo `auto`. Se você forçar `agentRuntime.id: "codex"`, todo turno incorporado +desse agente deve ser um modelo OpenAI compatível com Codex. -**Computer Use está instalado, mas as ferramentas não executam:** verifique -`/codex computer-use status` a partir de uma sessão nova. Se uma ferramenta reportar +**O Computer Use está instalado, mas as ferramentas não executam:** verifique +`/codex computer-use status` em uma sessão nova. Se uma ferramenta reportar `Native hook relay unavailable`, use `/new` ou `/reset`; se persistir, reinicie -o Gateway para limpar registros de hook nativo obsoletos. Se `computer-use.list_apps` -atingir timeout, 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` +expirar, reinicie o Codex Computer Use ou o Codex Desktop e tente novamente. ## Relacionados diff --git a/docs/pt-BR/plugins/dependency-resolution.md b/docs/pt-BR/plugins/dependency-resolution.md index 6c7dfffc1..cf125b831 100644 --- a/docs/pt-BR/plugins/dependency-resolution.md +++ b/docs/pt-BR/plugins/dependency-resolution.md @@ -1,50 +1,51 @@ --- read_when: - Você está depurando instalações de pacotes de Plugin - - Você está alterando o comportamento de inicialização de Plugin, do doctor ou de instalação do gerenciador de pacotes - - Você está mantendo instalações empacotadas do OpenClaw ou manifestos de Plugin incluídos + - Você está alterando o comportamento de inicialização do Plugin, do doctor ou de instalação do gerenciador de pacotes + - Você está mantendo instalações empacotadas do OpenClaw ou manifestos de plugins incluídos sidebarTitle: Dependencies summary: Como o OpenClaw instala pacotes de Plugin e resolve dependências de Plugin title: Resolução de dependências de Plugin x-i18n: - generated_at: "2026-05-03T21:35:46Z" + generated_at: "2026-05-05T01:48:22Z" model: gpt-5.5 provider: openai - source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d + source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20 source_path: plugins/dependency-resolution.md workflow: 16 --- # Resolução de dependências de Plugin -O OpenClaw mantém o trabalho de dependências de plugin no momento de instalação/atualização. O carregamento em runtime -não executa gerenciadores de pacotes, repara árvores de dependências nem modifica o diretório de pacote do OpenClaw. +OpenClaw mantém o trabalho de dependências de plugins no momento da instalação/atualização. O carregamento em runtime +não executa gerenciadores de pacotes, repara árvores de dependências nem modifica o diretório do pacote +OpenClaw. ## Divisão de responsabilidades -Os pacotes de plugin são responsáveis pelo próprio grafo de dependências: +Pacotes de Plugin são responsáveis pelo próprio grafo de dependências: - dependências de runtime ficam em `dependencies` ou - `optionalDependencies` do pacote de plugin -- importações do SDK/core são peers ou importações fornecidas pelo OpenClaw + `optionalDependencies` do pacote de Plugin +- importações de SDK/core são pares ou importações fornecidas pelo OpenClaw - plugins de desenvolvimento local trazem suas próprias dependências já instaladas - plugins npm e git são instalados em raízes de pacote pertencentes ao OpenClaw -O OpenClaw é responsável apenas pelo ciclo de vida do plugin: +OpenClaw é responsável apenas pelo ciclo de vida do Plugin: -- descobrir a origem do plugin +- descobrir a origem do Plugin - instalar ou atualizar o pacote quando solicitado explicitamente - registrar os metadados de instalação -- carregar o entrypoint do plugin -- falhar com um erro acionável quando faltarem dependências +- carregar o ponto de entrada do Plugin +- falhar com um erro acionável quando dependências estiverem ausentes ## Raízes de instalação -O OpenClaw usa raízes estáveis por origem: +OpenClaw usa raízes estáveis por origem: - pacotes npm são instalados em `~/.openclaw/npm` - pacotes git são clonados em `~/.openclaw/git` -- instalações locais/por caminho/arquivo são copiadas ou referenciadas sem reparo de dependências +- instalações locais/de caminho/de arquivo são copiadas ou referenciadas sem reparo de dependências Instalações npm são executadas na raiz npm com: @@ -52,38 +53,38 @@ Instalações npm são executadas na raiz npm com: npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -O npm pode içar dependências transitivas para `~/.openclaw/npm/node_modules` ao lado -do pacote de plugin. O OpenClaw examina a raiz npm gerenciada antes de confiar na -instalação e usa npm para remover pacotes gerenciados por npm durante a desinstalação, então dependências -de runtime içadas permanecem dentro do limite de limpeza gerenciado. +O npm pode elevar dependências transitivas para `~/.openclaw/npm/node_modules` ao lado +do pacote de Plugin. OpenClaw verifica a raiz npm gerenciada antes de confiar na +instalação e usa npm para remover pacotes gerenciados por npm durante a desinstalação, para que dependências +de runtime elevadas permaneçam dentro do limite de limpeza gerenciado. -Instalações git clonam ou atualizam o repositório e depois executam: +Instalações git clonam ou atualizam o repositório e então executam: ```bash npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` -O plugin instalado então é carregado a partir desse diretório de pacote, então a resolução -em `node_modules` local ao pacote e pai funciona da mesma forma que em um pacote +O Plugin instalado então carrega a partir desse diretório de pacote, então a resolução +de `node_modules` local ao pacote e pai funciona da mesma forma que em um pacote Node normal. ## Plugins locais -Plugins locais são tratados como diretórios controlados pelo desenvolvedor. O OpenClaw não +Plugins locais são tratados como diretórios controlados pelo desenvolvedor. OpenClaw não executa `npm install`, `pnpm install` nem reparo de dependências para eles. Se um -plugin local tiver dependências, instale-as nesse plugin antes de carregá-lo. +Plugin local tiver dependências, instale-as nesse Plugin antes de carregá-lo. Plugins locais TypeScript de terceiros podem usar o caminho emergencial Jiti. Plugins -JavaScript empacotados e plugins internos incluídos carregam por import/require -nativo em vez de Jiti. +JavaScript empacotados e plugins internos incluídos carregam por +import/require nativo em vez de Jiti. ## Inicialização e recarregamento -A inicialização do Gateway e o recarregamento de configuração nunca instalam dependências de plugin. Eles leem -os registros de instalação do plugin, calculam o entrypoint e o carregam. +A inicialização do Gateway e o recarregamento de configuração nunca instalam dependências de Plugin. Eles leem +os registros de instalação de Plugin, calculam o ponto de entrada e o carregam. -Se uma dependência estiver ausente em runtime, o plugin falha ao carregar e o erro -deve apontar o operador para uma correção explícita: +Se uma dependência estiver ausente em runtime, o Plugin falha ao carregar e o erro +deve indicar ao operador uma correção explícita: ```bash openclaw plugins update @@ -91,44 +92,44 @@ openclaw plugins install openclaw doctor --fix ``` -`doctor --fix` pode limpar estado legado de dependências gerado pelo OpenClaw e instalar -plugins baixáveis configurados que estejam ausentes dos registros de instalação locais. -Ele não repara dependências de um plugin local já instalado. +`doctor --fix` pode limpar estado de dependências legado gerado pelo OpenClaw e recuperar +plugins baixáveis que estão ausentes dos registros de instalação locais quando a configuração +os referencia. Doctor não repara dependências de um Plugin local já instalado. ## Plugins incluídos -Plugins incluídos leves e críticos para o core são enviados como parte do OpenClaw. +Plugins incluídos leves e críticos para o core são distribuídos como parte do OpenClaw. Eles devem não ter uma árvore pesada de dependências de runtime ou ser movidos para um pacote baixável no ClawHub/npm. -Para a lista gerada atual de plugins enviados no pacote core, instalados -externamente ou mantidos apenas como fonte, consulte [Inventário de plugins](/pt-BR/plugins/plugin-inventory). +Para a lista gerada atual de plugins que são distribuídos no pacote core, instalados +externamente ou permanecem apenas como código-fonte, consulte [Inventário de Plugin](/pt-BR/plugins/plugin-inventory). -Manifestos de plugins incluídos não devem solicitar staging de dependências. Funcionalidade grande ou opcional -de plugin deve ser empacotada como um plugin normal e instalada pelo +Manifestos de Plugin incluídos não devem solicitar preparação de dependências. Funcionalidade +de Plugin grande ou opcional deve ser empacotada como um Plugin normal e instalada pelo mesmo caminho npm/git/ClawHub que plugins de terceiros. -Em checkouts de código-fonte, o OpenClaw trata o repositório como um monorepo pnpm. Depois de -`pnpm install`, plugins incluídos carregam de `extensions/`, então dependências -workspace locais ao pacote ficam disponíveis e edições são aplicadas diretamente. O desenvolvimento em -checkout de código-fonte é somente pnpm; `npm install` simples na raiz do repositório não é -uma forma compatível de preparar dependências de plugins incluídos. +Em checkouts de código-fonte, OpenClaw trata o repositório como um monorepo pnpm. Após +`pnpm install`, plugins incluídos carregam a partir de `extensions/`, para que dependências +de workspace locais ao pacote fiquem disponíveis e edições sejam capturadas diretamente. O desenvolvimento +em checkout de código-fonte é somente pnpm; `npm install` simples na raiz do repositório +não é uma forma compatível de preparar dependências de Plugin incluído. -| Forma de instalação | Local do plugin incluído | Responsável pelas dependências | +| Formato de instalação | Local do Plugin incluído | Responsável pela dependência | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | Árvore de runtime construída dentro do pacote | Pacote OpenClaw e fluxos explícitos de instalação/atualização/doctor de plugins | -| Checkout git mais `pnpm install` | Pacotes workspace em `extensions/` | O workspace pnpm, incluindo as dependências próprias de cada pacote de plugin | -| `openclaw plugins install ...` | Raiz gerenciada de plugin npm/git/ClawHub | O fluxo de instalação/atualização de plugin | +| `npm install -g openclaw` | Árvore de runtime criada dentro do pacote | Pacote OpenClaw e fluxos explícitos de instalação/atualização/doctor de Plugin | +| Checkout git mais `pnpm install` | Pacotes de workspace `extensions/` | O workspace pnpm, incluindo as dependências próprias de cada pacote de Plugin | +| `openclaw plugins install ...` | Raiz gerenciada de Plugin npm/git/ClawHub | O fluxo de instalação/atualização de Plugin | ## Limpeza legada -Versões antigas do OpenClaw geravam raízes de dependências de plugins incluídos na inicialização ou -durante reparo do doctor. A limpeza atual do doctor remove esses diretórios obsoletos e -symlinks quando `--fix` é usado, incluindo antigas raízes `plugin-runtime-deps`, symlinks de pacote -do prefixo global do Node que apontam para destinos `plugin-runtime-deps` podados, -manifestos `.openclaw-runtime-deps*`, `node_modules` de plugin gerados, diretórios de estágio +Versões antigas do OpenClaw geravam raízes de dependências de Plugin incluído na inicialização ou +durante o reparo do doctor. A limpeza atual do doctor remove esses diretórios e +symlinks obsoletos quando `--fix` é usado, incluindo raízes antigas `plugin-runtime-deps`, symlinks +de pacotes de prefixo global do Node que apontam para destinos `plugin-runtime-deps` removidos, +manifestos `.openclaw-runtime-deps*`, `node_modules` de Plugin gerado, diretórios de estágio de instalação e stores pnpm locais ao pacote. O postinstall empacotado também -remove esses symlinks globais antes de podar as raízes de destino legadas para que upgrades -não deixem importações de pacotes ESM pendentes. +remove esses symlinks globais antes de remover as raízes de destino legadas para que atualizações +não deixem importações pendentes de pacotes ESM. Esses caminhos são apenas resíduos legados. Novas instalações não devem criá-los. diff --git a/docs/pt-BR/plugins/manage-plugins.md b/docs/pt-BR/plugins/manage-plugins.md index 3bfe175c2..66c72afb9 100644 --- a/docs/pt-BR/plugins/manage-plugins.md +++ b/docs/pt-BR/plugins/manage-plugins.md @@ -1,22 +1,21 @@ --- read_when: - - Você quer exemplos rápidos para instalar, listar, atualizar ou desinstalar Plugin - - Você quer escolher entre a distribuição de plugins pelo ClawHub e pelo npm + - Você quer exemplos rápidos de instalação, listagem, atualização ou desinstalação de Plugin + - Você quer escolher entre o ClawHub e a distribuição de Plugin via npm - Você está publicando um pacote de Plugin sidebarTitle: Manage plugins -summary: Exemplos rápidos de instalação, listagem, desinstalação, atualização e publicação de plugins do OpenClaw +summary: Exemplos rápidos para instalar, listar, desinstalar, atualizar e publicar plugins do OpenClaw title: Gerenciar plugins x-i18n: - generated_at: "2026-05-02T22:19:53Z" + generated_at: "2026-05-05T01:48:46Z" model: gpt-5.5 provider: openai - source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320 + source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c source_path: plugins/manage-plugins.md workflow: 16 --- -A maioria dos fluxos de trabalho de plugins envolve alguns comandos: pesquisar, instalar, reiniciar o Gateway, -verificar e desinstalar quando você não precisar mais do plugin. +A maioria dos fluxos de trabalho de plugin envolve alguns comandos: pesquisar, instalar, reiniciar o Gateway, verificar e desinstalar quando você não precisar mais do plugin. ## Listar plugins @@ -27,39 +26,35 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -Use `--json` em scripts. Ele inclui diagnósticos do registro e o -`dependencyStatus` estático de cada plugin quando o pacote do plugin declara `dependencies` ou -`optionalDependencies`. +Use `--json` para scripts. Ele inclui diagnósticos de registro e o `dependencyStatus` estático de cada plugin quando o pacote do plugin declara `dependencies` ou `optionalDependencies`. ```bash openclaw plugins list --json \ | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}' ``` -`plugins list` é uma verificação de inventário a frio. Ele mostra o que o OpenClaw consegue descobrir -a partir da configuração, dos manifestos e do registro de plugins; ele não prova que um -processo do Gateway já em execução importou o runtime do plugin. +`plugins list` é uma verificação fria de inventário. Ele mostra o que o OpenClaw consegue descobrir a partir da configuração, dos manifestos e do registro de plugins; ele não prova que um processo do Gateway já em execução importou o runtime do plugin. ## Instalar plugins ```bash -# Search ClawHub for plugin packages. +# Pesquise pacotes de plugin no ClawHub. openclaw plugins search "calendar" -# Bare package specs try ClawHub first, then npm fallback. +# Especificações de pacote simples tentam o ClawHub primeiro, depois fallback para npm. openclaw plugins install -# Force one source. +# Force uma origem. openclaw plugins install clawhub: openclaw plugins install npm: -# Install a specific version or dist-tag. +# Instale uma versão específica ou dist-tag. openclaw plugins install clawhub:@1.2.3 openclaw plugins install clawhub:@beta openclaw plugins install npm:@scope/openclaw-plugin@1.2.3 openclaw plugins install npm:@openclaw/codex -# Install from git or a local development checkout. +# Instale a partir do git ou de um checkout de desenvolvimento local. openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0 openclaw plugins install ./my-plugin openclaw plugins install --link ./my-plugin @@ -72,9 +67,7 @@ openclaw gateway restart openclaw plugins inspect --runtime --json ``` -Use `inspect --runtime` quando precisar de prova de que o plugin registrou superfícies de runtime -como ferramentas, hooks, serviços, métodos do Gateway ou comandos de CLI -pertencentes ao plugin. +Use `inspect --runtime` quando precisar de prova de que o plugin registrou superfícies de runtime, como ferramentas, hooks, serviços, métodos do Gateway ou comandos de CLI pertencentes ao plugin. ## Atualizar plugins @@ -84,22 +77,16 @@ openclaw plugins update openclaw plugins update --all ``` -Se um plugin foi instalado a partir de uma dist-tag do npm, como `@beta`, chamadas posteriores a -`update ` reutilizam essa tag registrada. Passar uma especificação explícita do npm -altera a instalação rastreada para essa especificação em atualizações futuras. +Se um plugin foi instalado a partir de uma dist-tag do npm, como `@beta`, chamadas posteriores de `update ` reutilizam essa tag registrada. Passar uma especificação npm explícita troca a instalação rastreada para essa especificação em atualizações futuras. ```bash openclaw plugins update @scope/openclaw-plugin@beta openclaw plugins update @scope/openclaw-plugin ``` -O segundo comando move um plugin de volta para a linha de lançamento padrão do registro -quando ele estava anteriormente fixado em uma versão exata ou tag. +O segundo comando move um plugin de volta para a linha de lançamento padrão do registro quando ele estava anteriormente fixado em uma versão exata ou tag. -Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub -da linha padrão tentam primeiro o lançamento `@beta` correspondente do plugin. Se esse lançamento -beta não existir, o OpenClaw volta para a especificação padrão/mais recente registrada. -Versões exatas e tags explícitas, como `@rc` ou `@beta`, são preservadas. +Quando `openclaw update` é executado no canal beta, registros de plugin npm e ClawHub da linha padrão tentam primeiro a versão `@beta` correspondente do plugin. Se essa versão beta não existir, o OpenClaw faz fallback para a especificação padrão/latest registrada. Para plugins npm, o OpenClaw também faz fallback quando o pacote beta existe, mas falha na validação de instalação. Versões exatas e tags explícitas, como `@rc` ou `@beta`, são preservadas. ## Desinstalar plugins @@ -110,20 +97,15 @@ openclaw plugins uninstall --keep-files openclaw gateway restart ``` -A desinstalação remove a entrada de configuração do plugin, o registro de índice do plugin, entradas -de lista de permissão/negação e caminhos de carregamento vinculados quando aplicável. Diretórios de instalação -gerenciados são removidos, a menos que você passe `--keep-files`. +A desinstalação remove a entrada de configuração do plugin, o registro de índice do plugin, entradas de lista de permissão/negação e caminhos de carregamento vinculados quando aplicável. Diretórios de instalação gerenciados são removidos, a menos que você passe `--keep-files`. ## Publicar plugins -Você pode publicar plugins externos no [ClawHub](https://clawhub.ai), npmjs.com ou -ambos. +Você pode publicar plugins externos no [ClawHub](https://clawhub.ai), no npmjs.com ou em ambos. ### Publicar no ClawHub -O ClawHub é a principal superfície pública de descoberta para plugins do OpenClaw. Ele oferece -aos usuários metadados pesquisáveis, histórico de versões e resultados de varredura do registro antes -da instalação. +O ClawHub é a principal superfície pública de descoberta para plugins do OpenClaw. Ele oferece aos usuários metadados pesquisáveis, histórico de versões e resultados de varredura do registro antes da instalação. ```bash npm i -g clawhub @@ -144,8 +126,7 @@ A forma simples ainda verifica o ClawHub primeiro. ### Publicar no npmjs.com -Plugins npm nativos devem incluir um manifesto de plugin e metadados de ponto de entrada -do OpenClaw no `package.json`. +Plugins npm nativos devem incluir um manifesto de plugin e metadados de ponto de entrada do OpenClaw no `package.json`. ```json package.json { @@ -162,7 +143,7 @@ do OpenClaw no `package.json`. npm publish --access public ``` -Os usuários instalam apenas pelo npm com: +Os usuários instalam apenas via npm com: ```bash openclaw plugins install npm:@acme/openclaw-plugin @@ -170,20 +151,16 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta openclaw plugins install npm:@acme/openclaw-plugin@1.0.0 ``` -Se o mesmo pacote também estiver disponível no ClawHub, `npm:` ignora a consulta ao ClawHub e -força a resolução pelo npm. +Se o mesmo pacote também estiver disponível no ClawHub, `npm:` ignora a consulta ao ClawHub e força a resolução via npm. -## Escolha da origem +## Escolha de origem -- **ClawHub**: use quando quiser descoberta nativa do OpenClaw, resumos de varredura, - versões e dicas de instalação. -- **npmjs.com**: use quando você já distribui pacotes JavaScript ou precisa de fluxos de trabalho de - dist-tags do npm/registro privado. -- **Git**: use quando quiser instalar diretamente de uma branch, tag ou commit. -- **Caminho local**: use quando estiver desenvolvendo ou testando um plugin na mesma - máquina. +- **ClawHub**: use quando quiser descoberta nativa do OpenClaw, resumos de varredura, versões e dicas de instalação. +- **npmjs.com**: use quando você já distribui pacotes JavaScript ou precisa de fluxos de trabalho de dist-tags/registro privado do npm. +- **Git**: use quando quiser instalar diretamente a partir de um branch, tag ou commit. +- **Caminho local**: use quando você estiver desenvolvendo ou testando um plugin na mesma máquina. -## Relacionados +## Relacionado - [Plugins](/pt-BR/tools/plugin) - visão geral e solução de problemas - [`openclaw plugins`](/pt-BR/cli/plugins) - referência completa da CLI diff --git a/docs/pt-BR/providers/openrouter.md b/docs/pt-BR/providers/openrouter.md index 43dd9754d..e4f5e93f3 100644 --- a/docs/pt-BR/providers/openrouter.md +++ b/docs/pt-BR/providers/openrouter.md @@ -1,34 +1,35 @@ --- read_when: - - Você quer uma única chave de API para vários LLMs - - Você quer executar modelos via OpenRouter no OpenClaw + - Você quer uma única chave de API para muitos LLMs + - Você quer executar modelos por meio do OpenRouter no OpenClaw - Você quer usar o OpenRouter para geração de imagens - - Você quer usar o OpenRouter para geração de vídeo -summary: Use a API unificada da OpenRouter para acessar vários modelos no OpenClaw + - Você quer usar o OpenRouter para geração de vídeos +summary: Use a API unificada do OpenRouter para acessar muitos modelos no OpenClaw title: OpenRouter x-i18n: - generated_at: "2026-05-04T05:54:34Z" + generated_at: "2026-05-05T01:48:53Z" model: gpt-5.5 provider: openai - source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc + source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244 source_path: providers/openrouter.md workflow: 16 --- -OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único endpoint e uma única chave de API. Ela é compatível com a OpenAI, então a maioria dos SDKs da OpenAI funciona ao trocar a URL base. +OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único +endpoint e chave de API. Ela é compatível com OpenAI, portanto a maioria dos SDKs da OpenAI funciona ao trocar a URL base. ## Primeiros passos - + Crie uma chave de API em [openrouter.ai/keys](https://openrouter.ai/keys). - + ```bash openclaw onboard --auth-choice openrouter-api-key ``` - + O onboarding usa `openrouter/auto` por padrão. Escolha um modelo concreto depois: ```bash @@ -51,16 +52,16 @@ OpenRouter fornece uma **API unificada** que roteia solicitações para muitos m } ``` -## Referências de modelos +## Referências de modelo -Refs de modelo seguem o padrão `openrouter//`. Para a lista completa de +As refs de modelo seguem o padrão `openrouter//`. Para ver a lista completa de provedores e modelos disponíveis, consulte [/concepts/model-providers](/pt-BR/concepts/model-providers). Exemplos de fallback incluídos: -| Ref. do modelo | Observações | +| Ref de modelo | Observações | | --------------------------------- | ---------------------------- | | `openrouter/auto` | Roteamento automático do OpenRouter | | `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI | @@ -83,7 +84,7 @@ OpenRouter também pode respaldar a ferramenta `image_generate`. Use um modelo d } ``` -O OpenClaw envia solicitações de imagem para a API de imagens de conclusões de chat do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas compatíveis de `aspectRatio` e `resolution` por meio do `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem mais lentos do OpenRouter; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda tem precedência. +OpenClaw envia solicitações de imagem para a API de imagens de chat completions do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas de `aspectRatio` e `resolution` compatíveis por meio de `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem do OpenRouter mais lentos; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda prevalece. ## Geração de vídeo @@ -102,20 +103,20 @@ OpenRouter também pode respaldar a ferramenta `video_generate` por meio de sua } ``` -O OpenClaw envia trabalhos de texto para vídeo e imagem para vídeo ao OpenRouter, consulta -a `polling_url` retornada e baixa o vídeo concluído de +OpenClaw envia trabalhos de texto para vídeo e imagem para vídeo para o OpenRouter, faz polling +da `polling_url` retornada e baixa o vídeo concluído a partir de `unsigned_urls` do OpenRouter ou do endpoint documentado de conteúdo do trabalho. -Imagens de referência são enviadas como imagens do primeiro/último quadro por padrão; imagens +Imagens de referência são enviadas por padrão como imagens do primeiro/último quadro; imagens marcadas com `reference_image` são enviadas como referências de entrada do OpenRouter. O padrão incluído `google/veo-3.1-fast` anuncia as durações atualmente compatíveis de 4/6/8 segundos, resoluções `720P`/`1080P` e proporções de aspecto `16:9`/`9:16`. -Vídeo para vídeo não é registrado para o OpenRouter porque a API upstream -de geração de vídeo atualmente aceita texto e referências de imagem. +Vídeo para vídeo não é registrado para o OpenRouter porque a API upstream de +geração de vídeo atualmente aceita texto e referências de imagem. ## Texto para fala OpenRouter também pode ser usado como provedor de TTS por meio de seu endpoint -`/audio/speech` compatível com a OpenAI. +`/audio/speech` compatível com OpenAI. ```json5 { @@ -135,14 +136,14 @@ OpenRouter também pode ser usado como provedor de TTS por meio de seu endpoint } ``` -Se `messages.tts.providers.openrouter.apiKey` for omitido, o TTS reutiliza +Se `messages.tts.providers.openrouter.apiKey` for omitido, TTS reutiliza `models.providers.openrouter.apiKey` e depois `OPENROUTER_API_KEY`. ## Autenticação e cabeçalhos -OpenRouter usa um token Bearer com sua chave de API internamente. +OpenRouter usa um token Bearer com sua chave de API por baixo dos panos. -Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), o OpenClaw também adiciona +Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), OpenClaw também adiciona os cabeçalhos documentados de atribuição de app do OpenRouter: | Cabeçalho | Valor | @@ -152,14 +153,14 @@ os cabeçalhos documentados de atribuição de app do OpenRouter: | `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | -Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, o OpenClaw -**não** injeta esses cabeçalhos específicos do OpenRouter nem marcadores de cache da Anthropic. +Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, OpenClaw +**não** injetará esses cabeçalhos específicos do OpenRouter nem marcadores de cache da Anthropic. ## Configuração avançada - + O cache de respostas do OpenRouter é opcional. Habilite-o por modelo do OpenRouter com parâmetros de modelo: @@ -180,60 +181,62 @@ Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, } ``` - O OpenClaw envia `X-OpenRouter-Cache: true` e, quando configurado, + OpenClaw envia `X-OpenRouter-Cache: true` e, quando configurado, `X-OpenRouter-Cache-TTL`. `responseCacheClear: true` força uma atualização para a solicitação atual e armazena a resposta substituta. Aliases em snake_case (`response_cache`, `response_cache_ttl_seconds` e `response_cache_clear`) também são aceitos. Isso é separado do cache de prompt do provedor e dos marcadores - Anthropic `cache_control` do OpenRouter. Ele é aplicado apenas em rotas + Anthropic `cache_control` do OpenRouter. Ele só é aplicado em rotas `openrouter.ai` verificadas, não em URLs base de proxy personalizadas. - + Em rotas verificadas do OpenRouter, refs de modelo Anthropic mantêm os marcadores Anthropic `cache_control` específicos do OpenRouter que o OpenClaw usa para melhor reutilização do cache de prompt em blocos de prompt de sistema/desenvolvedor. - + Em rotas verificadas do OpenRouter, refs de modelo Anthropic com raciocínio habilitado - removem turnos finais de preenchimento prévio do assistente antes que a solicitação chegue ao OpenRouter, - correspondendo à exigência da Anthropic de que conversas de raciocínio terminem com um - turno do usuário. + removem turnos finais de pré-preenchimento do assistente antes que a solicitação chegue ao OpenRouter, + correspondendo ao requisito da Anthropic de que conversas com raciocínio terminem com um turno + de usuário. - - Em rotas não `auto` compatíveis, o OpenClaw mapeia o nível de pensamento selecionado para - payloads de raciocínio do proxy OpenRouter. Dicas de modelo não compatíveis e + + Em rotas não `auto` compatíveis, OpenClaw mapeia o nível de pensamento selecionado para + payloads de raciocínio de proxy do OpenRouter. Dicas de modelo não compatíveis e `openrouter/auto` ignoram essa injeção de raciocínio. Hunter Alpha também ignora - o raciocínio de proxy para refs de modelo configuradas obsoletas porque o OpenRouter poderia - retornar texto de resposta final em campos de raciocínio para essa rota descontinuada. + raciocínio de proxy para refs de modelo configuradas obsoletas porque o OpenRouter poderia + retornar texto de resposta final em campos de raciocínio para essa rota aposentada. - + Em rotas verificadas do OpenRouter, `openrouter/deepseek/deepseek-v4-flash` e `openrouter/deepseek/deepseek-v4-pro` preenchem `reasoning_content` ausente em - turnos de assistente reproduzidos para que conversas com pensamento/ferramentas mantenham o formato - de acompanhamento exigido pelo DeepSeek V4. + turnos de assistente reproduzidos para que conversas de pensamento/ferramenta mantenham o + formato de acompanhamento exigido pelo DeepSeek V4. OpenClaw envia valores de + `reasoning_effort` compatíveis com o OpenRouter para essas rotas; `xhigh` é o nível mais alto anunciado, + e substituições `max` obsoletas são mapeadas para `xhigh`. - - OpenRouter ainda passa pelo caminho compatível com OpenAI no estilo proxy, então - a modelagem de solicitação nativa apenas da OpenAI, como `serviceTier`, `store` de Responses, - payloads compatíveis com raciocínio da OpenAI e dicas de cache de prompt, não é encaminhada. + + OpenRouter ainda passa pelo caminho em estilo proxy compatível com OpenAI, portanto + formatações de solicitação nativas apenas da OpenAI, como `serviceTier`, Responses `store`, + payloads de compatibilidade com raciocínio da OpenAI e dicas de cache de prompt não são encaminhadas. - - Refs do OpenRouter respaldadas por Gemini permanecem no caminho proxy-Gemini: o OpenClaw mantém - a sanitização de assinatura de pensamento Gemini lá, mas não habilita a validação nativa de reprodução - Gemini nem reescritas de bootstrap. + + Refs do OpenRouter com backend Gemini permanecem no caminho proxy-Gemini: OpenClaw mantém + a higienização de assinatura de pensamento do Gemini ali, mas não habilita a validação de replay + nativa do Gemini nem reescritas de bootstrap. - - Se você passar roteamento de provedor do OpenRouter em parâmetros de modelo, o OpenClaw o encaminha + + Se você passar roteamento de provedor do OpenRouter nos parâmetros de modelo, OpenClaw o encaminha como metadados de roteamento do OpenRouter antes que os wrappers de stream compartilhados sejam executados. @@ -241,10 +244,10 @@ Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, ## Relacionado - + Escolha de provedores, refs de modelo e comportamento de failover. - + Referência completa de configuração para agentes, modelos e provedores. diff --git a/docs/pt-BR/reference/RELEASING.md b/docs/pt-BR/reference/RELEASING.md index 6d7b3ec0e..cae39bb18 100644 --- a/docs/pt-BR/reference/RELEASING.md +++ b/docs/pt-BR/reference/RELEASING.md @@ -1,188 +1,172 @@ --- read_when: - - Procurando definições de canais de lançamento públicos - - Executando a validação de release ou a aceitação de pacote - - Buscando nomenclatura e cadência de versões -summary: Faixas de lançamento, lista de verificação do operador, caixas de validação, nomenclatura de versões e cadência + - Procurando definições de canais públicos de lançamento + - Executando validação de release ou aceitação de pacote + - Procurando nomenclatura e cadência de versões +summary: Faixas de lançamento, checklist do operador, caixas de validação, nomenclatura de versões e cadência title: Política de lançamento x-i18n: - generated_at: "2026-05-04T07:03:56Z" + generated_at: "2026-05-05T01:49:02Z" model: gpt-5.5 provider: openai - source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 + source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw tem três canais públicos de release: +OpenClaw tem três canais públicos de lançamento: -- estável: releases marcadas que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente -- beta: tags de pré-release que publicam no npm `beta` -- dev: o head móvel de `main` +- stable: lançamentos com tag que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente +- beta: tags de pré-lançamento que publicam no npm `beta` +- dev: o ponto mais recente em movimento de `main` ## Nomenclatura de versões -- Versão de release estável: `YYYY.M.D` - - Tag Git: `vYYYY.M.D` -- Versão de release de correção estável: `YYYY.M.D-N` - - Tag Git: `vYYYY.M.D-N` -- Versão de pré-release beta: `YYYY.M.D-beta.N` - - Tag Git: `vYYYY.M.D-beta.N` -- Não preencha mês ou dia com zero à esquerda -- `latest` significa o release npm estável promovido atual +- Versão de lançamento estável: `YYYY.M.D` + - Tag do Git: `vYYYY.M.D` +- Versão de lançamento estável de correção: `YYYY.M.D-N` + - Tag do Git: `vYYYY.M.D-N` +- Versão beta de pré-lançamento: `YYYY.M.D-beta.N` + - Tag do Git: `vYYYY.M.D-beta.N` +- Não adicione zeros à esquerda ao mês ou ao dia +- `latest` significa a versão estável atual promovida no npm - `beta` significa o destino atual de instalação beta -- Releases estáveis e releases de correção estáveis publicam no npm `beta` por padrão; operadores de release podem direcionar para `latest` explicitamente, ou promover uma build beta validada posteriormente -- Todo release estável do OpenClaw entrega o pacote npm e o app macOS juntos; - releases beta normalmente validam e publicam primeiro o caminho npm/pacote, com - build/assinatura/notarização do app Mac reservados para estável, salvo solicitação explícita +- Lançamentos estáveis e lançamentos estáveis de correção publicam no npm `beta` por padrão; operadores de lançamento podem direcionar explicitamente para `latest` ou promover uma compilação beta validada posteriormente +- Todo lançamento estável do OpenClaw entrega o pacote npm e o app para macOS juntos; + lançamentos beta normalmente validam e publicam primeiro o caminho npm/pacote, com + compilação/assinatura/notarização do app para Mac reservadas para stable, salvo solicitação explícita -## Cadência de release +## Cadência de lançamentos -- Releases avançam primeiro para beta -- Estável vem somente depois que a beta mais recente é validada -- Mantenedores normalmente criam releases a partir de uma branch `release/YYYY.M.D` criada - a partir da `main` atual, para que validação e correções de release não bloqueiem novo - desenvolvimento na `main` -- Se uma tag beta tiver sido enviada ou publicada e precisar de correção, mantenedores criam +- Lançamentos seguem primeiro para beta +- Stable vem somente depois que o beta mais recente é validado +- Mantenedores normalmente criam lançamentos a partir de uma branch `release/YYYY.M.D` criada + a partir da `main` atual, para que a validação e as correções de lançamento não bloqueiem novos + desenvolvimentos em `main` +- Se uma tag beta tiver sido enviada ou publicada e precisar de correção, os mantenedores criam a próxima tag `-beta.N` em vez de excluir ou recriar a tag beta antiga -- Procedimento detalhado de release, aprovações, credenciais e notas de recuperação são - apenas para mantenedores +- O procedimento detalhado de lançamento, aprovações, credenciais e notas de recuperação são + exclusivos para mantenedores -## Checklist do operador de release +## Lista de verificação do operador de lançamento -Este checklist é o formato público do fluxo de release. Credenciais privadas, +Esta lista de verificação é o formato público do fluxo de lançamento. Credenciais privadas, assinatura, notarização, recuperação de dist-tag e detalhes de rollback de emergência ficam no -runbook de release restrito a mantenedores. +runbook de lançamento exclusivo para mantenedores. -1. Comece pela `main` atual: puxe a versão mais recente, confirme que o commit de destino foi enviado, - e confirme que o CI da `main` atual está verde o suficiente para criar uma branch a partir dele. +1. Comece pela `main` atual: baixe as alterações mais recentes, confirme que o commit de destino foi enviado + e confirme que o CI atual da `main` está verde o suficiente para criar uma branch a partir dela. 2. Reescreva a seção superior de `CHANGELOG.md` a partir do histórico real de commits com `/changelog`, mantenha as entradas voltadas ao usuário, faça commit, envie, e faça rebase/pull mais uma vez antes de criar a branch. -3. Revise os registros de compatibilidade de release em +3. Revise os registros de compatibilidade de lançamento em `src/plugins/compat/registry.ts` e `src/commands/doctor/shared/deprecation-compat.ts`. Remova compatibilidade expirada - somente quando o caminho de upgrade continuar coberto, ou registre por que ela está + somente quando o caminho de atualização continuar coberto, ou registre por que ela está sendo mantida intencionalmente. -4. Crie `release/YYYY.M.D` a partir da `main` atual; não faça trabalho normal de release - diretamente na `main`. -5. Atualize todas as localizações de versão exigidas para a tag pretendida, execute - `pnpm plugins:sync` para que os pacotes de Plugin publicáveis compartilhem a versão - de release e os metadados de compatibilidade, depois execute o preflight determinístico local: +4. Crie `release/YYYY.M.D` a partir da `main` atual; não faça o trabalho normal de lançamento + diretamente em `main`. +5. Atualize todos os locais de versão necessários para a tag pretendida, execute + `pnpm plugins:sync` para que os pacotes de Plugin publicáveis compartilhem a versão de lançamento + e os metadados de compatibilidade, depois execute o preflight determinístico local: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` e `pnpm release:check`. -6. Execute `OpenClaw NPM Release` com `preflight_only=true`. Antes de existir uma tag, - um SHA completo de 40 caracteres da branch de release é permitido para preflight +6. Execute `OpenClaw NPM Release` com `preflight_only=true`. Antes de uma tag existir, + um SHA completo de 40 caracteres da branch de lançamento é permitido para preflight apenas de validação. Salve o `preflight_run_id` bem-sucedido. -7. Inicie todos os testes de pré-release com `Full Release Validation` para a - branch de release, tag ou SHA completo do commit. Este é o único ponto de entrada manual - para as quatro grandes caixas de teste de release: Vitest, Docker, QA Lab e Package. -8. Se a validação falhar, corrija na branch de release e reexecute o menor +7. Inicie todos os testes de pré-lançamento com `Full Release Validation` para a + branch de lançamento, tag ou SHA de commit completo. Este é o único ponto de entrada manual + para as quatro grandes caixas de teste de lançamento: Vitest, Docker, QA Lab e Package. +8. Se a validação falhar, corrija na branch de lançamento e execute novamente o menor arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo com falha que - comprove a correção. Reexecute o guarda-chuva completo somente quando a superfície alterada tornar + comprove a correção. Execute novamente o guarda-chuva completo somente quando a superfície alterada tornar as evidências anteriores obsoletas. -9. Para beta, marque `vYYYY.M.D-beta.N`, depois execute `OpenClaw Release Publish` a partir +9. Para beta, crie a tag `vYYYY.M.D-beta.N` e execute `OpenClaw Release Publish` a partir da branch `release/YYYY.M.D` correspondente. Ele verifica `pnpm plugins:sync:check`, publica primeiro todos os pacotes de Plugin publicáveis no npm, publica o mesmo - conjunto no ClawHub em segundo lugar como tarballs ClawPack npm-pack, e então promove o + conjunto no ClawHub em seguida como tarballs ClawPack npm-pack e então promove o artefato de preflight npm preparado do OpenClaw com a dist-tag correspondente. Após - publicar, execute a aceitação de pacote pós-publicação - contra o pacote publicado `openclaw@YYYY.M.D-beta.N` ou - `openclaw@beta`. Se uma pré-release enviada ou publicada precisar de correção, - crie o próximo número de pré-release correspondente; não exclua nem reescreva a pré-release - antiga. -10. Para estável, continue somente depois que a beta validada ou o release candidate tiver as - evidências de validação exigidas. A publicação npm estável também passa por + publicar, execute a aceitação de pacote pós-publicação contra o pacote + `openclaw@YYYY.M.D-beta.N` ou `openclaw@beta` publicado. Se um pré-lançamento enviado ou publicado precisar de correção, + crie o próximo número de pré-lançamento correspondente; não exclua nem reescreva o pré-lançamento antigo. +10. Para stable, continue somente depois que o beta validado ou candidato a lançamento tiver as + evidências de validação exigidas. A publicação npm stable também passa por `OpenClaw Release Publish`, reutilizando o artefato de preflight bem-sucedido via - `preflight_run_id`; a prontidão do release macOS estável também exige os - `.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado na `main`. + `preflight_run_id`; a prontidão do lançamento stable para macOS também exige o + `.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado em `main`. 11. Após publicar, execute o verificador npm pós-publicação, o E2E opcional do Telegram - usando npm publicado independente quando precisar de prova de canal pós-publicação, - promoção de dist-tag quando necessário, notas de release/pré-release do GitHub a partir da - seção completa correspondente de `CHANGELOG.md`, e as etapas de anúncio de release. + standalone publicado no npm quando você precisar de comprovação de canal pós-publicação, + a promoção de dist-tag quando necessário, notas de release/pré-release do GitHub a partir da + seção completa correspondente de `CHANGELOG.md` e as etapas de anúncio do lançamento. -## Preflight de release +## Preflight de lançamento -- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript de teste continue coberto fora do gate local mais rápido `pnpm check` +- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript de teste permaneça coberto fora do gate local mais rápido `pnpm check` - Execute `pnpm check:architecture` antes do preflight de release para que as verificações mais amplas de ciclos de importação e limites de arquitetura fiquem verdes fora do gate local mais rápido -- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados em `dist/*` e o bundle da Control UI existam para a etapa de validação do pack -- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de criar a tag. Ele atualiza versões de pacotes de plugins publicáveis, metadados de compatibilidade de peer/API do OpenClaw, metadados de build e stubs de changelog dos plugins para corresponder à versão de release do core. `pnpm plugins:sync:check` é o guardião de release não mutável; o workflow de publicação falha antes de qualquer mutação no registry se esta etapa tiver sido esquecida. -- Execute o workflow manual `Full Release Validation` antes da aprovação de release para iniciar todas as caixas de teste pré-release a partir de um único ponto de entrada. Ele aceita uma branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release do Docker, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e faixas do Telegram. Com `release_profile=full` e `rerun_group=all`, ele também executa o E2E de pacote do Telegram contra o artefato `release-package-under-test` das verificações de release. Forneça `npm_telegram_package_spec` depois da publicação quando o mesmo E2E do Telegram também precisar comprovar o pacote npm publicado. Forneça `package_acceptance_package_spec` depois da publicação quando Package Acceptance precisar executar sua matriz de pacote/atualização contra o pacote npm entregue em vez do artefato criado a partir do SHA. Forneça `evidence_package_spec` quando o relatório privado de evidências precisar comprovar que a validação corresponde a um pacote npm publicado sem forçar E2E do Telegram. Exemplo: - `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Execute o workflow manual `Package Acceptance` quando quiser prova por canal lateral para um candidato de pacote enquanto o trabalho de release continua. Use `source=npm` para `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` para empacotar uma branch/tag/SHA `package_ref` confiável com o harness `workflow_ref` atual; `source=url` para um tarball HTTPS com SHA-256 obrigatório; ou `source=artifact` para um tarball enviado por outra execução do GitHub Actions. O workflow resolve o candidato para `package-under-test`, reutiliza o agendador de release Docker E2E contra esse tarball e pode executar QA do Telegram contra o mesmo tarball com `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as faixas Docker selecionadas incluem `published-upgrade-survivor`, o artefato do pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a linha de base publicada. +- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados em `dist/*` e o bundle da Control UI existam para a etapa de validação do pacote +- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de criar a tag. Ele atualiza as versões de pacotes de plugins publicáveis, os metadados de compatibilidade de peer/API do OpenClaw, os metadados de build e os stubs de changelog dos plugins para corresponder à versão de release do núcleo. `pnpm plugins:sync:check` é a proteção de release não mutável; o workflow de publicação falha antes de qualquer mutação de registry se essa etapa tiver sido esquecida. +- Execute o workflow manual `Full Release Validation` antes da aprovação do release para iniciar todas as caixas de teste pré-release a partir de um único ponto de entrada. Ele aceita um branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para install smoke, aceitação de pacote, verificações de pacote entre sistemas operacionais, paridade do QA Lab, Matrix e lanes do Telegram. Execuções estáveis/padrão mantêm o soak exaustivo live/E2E e do caminho de release do Docker atrás de `run_release_soak=true`; `release_profile=full` força o soak. Com `release_profile=full` e `rerun_group=all`, ele também executa E2E de pacote do Telegram contra o artefato `release-package-under-test` das verificações de release. Forneça `npm_telegram_package_spec` após a publicação quando o mesmo E2E do Telegram também deve provar o pacote npm publicado. Forneça `package_acceptance_package_spec` após a publicação quando Package Acceptance deve executar sua matriz de pacote/atualização contra o pacote npm enviado em vez do artefato criado a partir do SHA. Forneça `evidence_package_spec` quando o relatório de evidências privado deve provar que a validação corresponde a um pacote npm publicado sem forçar o E2E do Telegram. Exemplo: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` +- Execute o workflow manual `Package Acceptance` quando quiser uma prova por canal lateral para um candidato de pacote enquanto o trabalho de release continua. Use `source=npm` para `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` para empacotar um branch/tag/SHA confiável de `package_ref` com o harness atual de `workflow_ref`; `source=url` para um tarball HTTPS com SHA-256 obrigatório; ou `source=artifact` para um tarball enviado por outra execução do GitHub Actions. O workflow resolve o candidato para `package-under-test`, reutiliza o agendador de release Docker E2E contra esse tarball e pode executar QA do Telegram contra o mesmo tarball com `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as lanes Docker selecionadas incluem `published-upgrade-survivor`, o artefato de pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a baseline publicada. Exemplo: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` Perfis comuns: - - `smoke`: faixas de instalação/canal/agente, rede do Gateway e recarregamento de configuração - - `package`: faixas nativas de artefato para pacote/atualização/plugin sem OpenWebUI ou ClawHub live - - `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente, - busca web da OpenAI e OpenWebUI + - `smoke`: lanes de instalação/canal/agente, rede do Gateway e recarregamento de configuração + - `package`: lanes nativas de artefato para pacote/atualização/plugin sem OpenWebUI ou ClawHub live + - `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente, busca na web da OpenAI e OpenWebUI - `full`: partes do caminho de release Docker com OpenWebUI - `custom`: seleção exata de `docker_lanes` para uma reexecução focada -- Execute o workflow manual `CI` diretamente quando você só precisar da cobertura completa normal de CI para o candidato de release. Disparos manuais de CI ignoram o escopo por alterações e forçam as shards Linux Node, shards de plugins agrupados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills em Python, Windows, macOS, Android e faixas de i18n da Control UI. +- Execute o workflow manual `CI` diretamente quando precisar apenas da cobertura completa normal de CI para o candidato de release. Disparos manuais de CI ignoram o escopo por alterações e forçam as shards Linux Node, shards de plugins empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e lanes de i18n da Control UI. Exemplo: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Execute `pnpm qa:otel:smoke` ao validar telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans de trace exportados, atributos limitados e redação de conteúdo/identificadores sem exigir Opik, Langfuse ou outro coletor externo. -- Execute `pnpm release:check` antes de toda release com tag -- Execute `OpenClaw Release Publish` para a sequência de publicação mutável depois que a tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma tag alcançável por main), passe a tag de release e o `preflight_run_id` npm do OpenClaw bem-sucedido, e mantenha o escopo padrão de publicação de plugins `all-publishable`, a menos que você esteja executando deliberadamente um reparo focado. O workflow serializa a publicação npm de plugins, a publicação ClawHub de plugins e a publicação npm do OpenClaw para que o pacote core não seja publicado antes dos seus plugins externalizados. -- As verificações de release agora são executadas em um workflow manual separado: - `OpenClaw Release Checks` -- `OpenClaw Release Checks` também executa a faixa de paridade mock do QA Lab mais o perfil Matrix live rápido e a faixa QA do Telegram antes da aprovação de release. As faixas live usam o ambiente `qa-live-shared`; o Telegram também usa concessões de credenciais CI do Convex. Execute o workflow manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte Matrix, mídia e E2EE em paralelo. -- A validação de runtime de instalação e atualização entre sistemas operacionais faz parte dos workflows públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o workflow reutilizável `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Essa divisão é intencional: manter o caminho real de release npm curto, determinístico e focado em artefatos, enquanto verificações live mais lentas permanecem na própria faixa para não atrasarem nem bloquearem a publicação -- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release Validation` ou a partir do ref de workflow `main`/release para que a lógica do workflow e os segredos permaneçam controlados -- `OpenClaw Release Checks` aceita uma branch, tag ou SHA completo de commit desde que o commit resolvido seja alcançável a partir de uma branch OpenClaw ou tag de release -- O preflight apenas de validação de `OpenClaw NPM Release` também aceita o SHA completo de 40 caracteres do commit atual da branch do workflow sem exigir uma tag enviada -- Esse caminho por SHA é apenas de validação e não pode ser promovido para uma publicação real +- Execute `pnpm qa:otel:smoke` ao validar telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans de trace exportados, atributos limitados e redação de conteúdo/identificador sem exigir Opik, Langfuse ou outro coletor externo. +- Execute `pnpm release:check` antes de cada release com tag +- Execute `OpenClaw Release Publish` para a sequência mutável de publicação depois que a tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma tag alcançável por main), passe a tag de release e o `preflight_run_id` bem-sucedido do npm do OpenClaw, e mantenha o escopo padrão de publicação de plugins `all-publishable`, a menos que esteja executando deliberadamente um reparo focado. O workflow serializa a publicação npm de plugins, a publicação de plugins no ClawHub e a publicação npm do OpenClaw para que o pacote central não seja publicado antes de seus plugins externalizados. +- As verificações de release agora são executadas em um workflow manual separado: `OpenClaw Release Checks` +- `OpenClaw Release Checks` também executa a lane de paridade mock do QA Lab, além do perfil rápido live do Matrix e da lane de QA do Telegram antes da aprovação do release. As lanes live usam o ambiente `qa-live-shared`; o Telegram também usa leases de credenciais de CI do Convex. Execute o workflow manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte, mídia e E2EE do Matrix em paralelo. +- A validação de runtime de instalação e upgrade entre sistemas operacionais faz parte dos workflows públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o workflow reutilizável `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- Essa divisão é intencional: manter o caminho real de release npm curto, determinístico e focado em artefatos, enquanto verificações live mais lentas permanecem em sua própria lane para que não atrasem nem bloqueiem a publicação +- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release Validation` ou a partir da ref de workflow `main`/release para que a lógica do workflow e os segredos permaneçam controlados +- `OpenClaw Release Checks` aceita um branch, tag ou SHA completo de commit desde que o commit resolvido seja alcançável a partir de um branch do OpenClaw ou tag de release +- O preflight somente de validação de `OpenClaw NPM Release` também aceita o SHA completo atual de 40 caracteres do commit do branch de workflow sem exigir uma tag enviada +- Esse caminho de SHA é somente de validação e não pode ser promovido para uma publicação real - No modo SHA, o workflow sintetiza `v` apenas para a verificação de metadados do pacote; a publicação real ainda exige uma tag de release real -- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação não mutável pode usar os runners Linux maiores do Blacksmith -- Esse workflow executa - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - usando os segredos de workflow `OPENAI_API_KEY` e `ANTHROPIC_API_KEY` -- O preflight de release npm não espera mais pela faixa separada de verificações de release -- Execute `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (ou a tag beta/correção correspondente) antes da aprovação -- Depois da publicação npm, execute - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - (ou a versão beta/correção correspondente) para verificar o caminho de instalação pelo registry publicado em um prefixo temporário novo -- Depois de uma publicação beta, execute `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - para verificar onboarding do pacote instalado, configuração do Telegram e E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais alugadas do Telegram. Execuções pontuais locais de mantenedores podem omitir as vars do Convex e passar diretamente as três credenciais de env `OPENCLAW_QA_TELEGRAM_*`. -- Para executar o smoke beta pós-publicação completo a partir de uma máquina de mantenedor, use `pnpm release:beta-smoke -- --beta betaN`. O helper executa validação de atualização npm/fresh-target do Parallels, dispara `NPM Telegram Beta E2E`, consulta a execução exata do workflow, baixa o artefato e imprime o relatório do Telegram. -- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions por meio do workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não roda em todo merge. -- A automação de release de mantenedores agora usa preflight-depois-promote: - - a publicação npm real deve passar um `preflight_run_id` npm bem-sucedido - - a publicação npm real deve ser disparada a partir da mesma branch `main` ou - `release/YYYY.M.D` da execução de preflight bem-sucedida +- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação não mutável pode usar os runners Linux maiores da Blacksmith +- Esse workflow executa `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` usando os segredos de workflow `OPENAI_API_KEY` e `ANTHROPIC_API_KEY` +- O preflight de release npm não espera mais pela lane separada de verificações de release +- Execute `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (ou a tag beta/correção correspondente) antes da aprovação +- Após a publicação npm, execute `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (ou a versão beta/correção correspondente) para verificar o caminho de instalação no registry publicado em um prefixo temporário novo +- Após uma publicação beta, execute `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` para verificar onboarding do pacote instalado, configuração do Telegram e E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais alugadas do Telegram. Execuções pontuais locais de mantenedores podem omitir as vars do Convex e passar diretamente as três credenciais de env `OPENCLAW_QA_TELEGRAM_*`. +- Para executar o smoke beta completo pós-publicação a partir da máquina de um mantenedor, use `pnpm release:beta-smoke -- --beta betaN`. O helper executa validação de atualização npm/fresh-target no Parallels, dispara `NPM Telegram Beta E2E`, faz polling da execução exata do workflow, baixa o artefato e imprime o relatório do Telegram. +- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions por meio do workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não executa a cada merge. +- A automação de release dos mantenedores agora usa preflight-then-promote: + - a publicação npm real deve passar por um `preflight_run_id` npm bem-sucedido + - a publicação npm real deve ser disparada a partir do mesmo branch `main` ou `release/YYYY.M.D` da execução de preflight bem-sucedida - releases npm estáveis usam `beta` por padrão - - a publicação npm estável pode mirar `latest` explicitamente via input do workflow - - a mutação de dist-tag npm baseada em token agora vive em - `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN`, enquanto o repo público mantém publicação somente com OIDC - - `macOS Release` público é apenas validação; quando uma tag existe apenas em uma - branch de release, mas o workflow é disparado a partir de `main`, defina - `public_release_branch=release/YYYY.M.D` - - a publicação privada real do mac deve passar por `preflight_run_id` e `validate_run_id` privados de mac bem-sucedidos + - a publicação npm estável pode mirar explicitamente `latest` via input do workflow + - a mutação de dist-tag npm baseada em token agora fica em `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN`, enquanto o repositório público mantém publicação somente por OIDC + - `macOS Release` público é somente de validação; quando uma tag existe apenas em um branch de release, mas o workflow é disparado a partir de `main`, defina `public_release_branch=release/YYYY.M.D` + - a publicação privada real para mac deve passar por `preflight_run_id` e `validate_run_id` privados de mac bem-sucedidos - os caminhos reais de publicação promovem artefatos preparados em vez de reconstruí-los novamente -- Para releases de correção estáveis como `YYYY.M.D-N`, o verificador pós-publicação também checa o mesmo caminho de atualização com prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, para que correções de release não deixem silenciosamente instalações globais antigas no payload estável base -- O preflight de release npm falha fechado, a menos que o tarball inclua tanto `dist/control-ui/index.html` quanto um payload não vazio em `dist/control-ui/assets/`, para que não entreguemos novamente um dashboard de navegador vazio -- A verificação pós-publicação também checa se os entrypoints de plugins publicados e os metadados de pacote estão presentes no layout instalado do registry. Uma release que entrega payloads de runtime de plugins ausentes falha no verificador postpublish e não pode ser promovida para `latest`. -- `pnpm test:install:smoke` também impõe o orçamento de `unpackedSize` do pack npm no tarball candidato de atualização, para que o e2e do instalador detecte crescimento acidental do pack antes do caminho de publicação de release -- Se o trabalho de release tocou planejamento de CI, manifests de timing de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard`, de propriedade do planejador, a partir de `.github/workflows/plugin-prerelease.yml` antes da aprovação para que as notas de release não descrevam um layout de CI obsoleto -- A prontidão de release estável do macOS também inclui as superfícies do atualizador: - - a release do GitHub deve acabar com os `.zip`, `.dmg` e `.dSYM.zip` empacotados - - `appcast.xml` em `main` deve apontar para o novo zip estável depois da publicação +- Para releases estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação também verifica o mesmo caminho de upgrade em prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, para que correções de release não deixem silenciosamente instalações globais antigas no payload estável base +- O preflight de release npm falha fechado a menos que o tarball inclua tanto `dist/control-ui/index.html` quanto um payload não vazio em `dist/control-ui/assets/`, para que não enviemos novamente um dashboard de navegador vazio +- A verificação pós-publicação também verifica que entrypoints de plugins publicados e metadados de pacote estão presentes no layout instalado do registry. Um release que envia payloads de runtime de plugins ausentes falha no verificador pós-publicação e não pode ser promovido para `latest`. +- `pnpm test:install:smoke` também impõe o orçamento de `unpackedSize` do pacote npm no tarball candidato de atualização, para que o e2e do instalador capture bloat acidental de pacote antes do caminho de publicação do release +- Se o trabalho de release tocou planejamento de CI, manifests de timing de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard` pertencentes ao planner em `.github/workflows/plugin-prerelease.yml` antes da aprovação, para que as notas de release não descrevam um layout de CI obsoleto +- A prontidão de release estável para macOS também inclui as superfícies de atualizador: + - o release do GitHub deve terminar com os pacotes `.zip`, `.dmg` e `.dSYM.zip` + - `appcast.xml` em `main` deve apontar para o novo zip estável após a publicação - o app empacotado deve manter um bundle id não debug, uma URL de feed Sparkle não vazia e um `CFBundleVersion` igual ou superior ao piso canônico de build do Sparkle para essa versão de release ## Caixas de teste de release -`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Para uma prova de commit fixado em uma branch de movimentação rápida, use o helper para que todo workflow filho rode a partir de uma branch temporária fixada no SHA de destino: +`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Para uma prova de commit fixado em um branch que se move rapidamente, use o helper para que cada workflow filho execute a partir de um branch temporário fixado no SHA alvo: ```bash pnpm ci:full-release --sha ``` -O helper envia `release-ci/-...`, dispara `Full Release Validation` a partir dessa branch com `ref=`, verifica se todo `headSha` de workflow filho corresponde ao alvo e então exclui a branch temporária. Isso evita comprovar por acidente uma execução filha de `main` mais nova. +O helper envia `release-ci/-...`, dispara `Full Release Validation` a partir desse branch com `ref=`, verifica que cada `headSha` de workflow filho corresponde ao alvo e então exclui o branch temporário. Isso evita provar acidentalmente uma execução filha de `main` mais nova. -Para validação de branch ou tag de release, execute a partir do ref de workflow confiável `main` e passe a branch ou tag de release como `ref`: +Para validação de branch de release ou tag, execute-a a partir da ref confiável de workflow `main` e passe o branch de release ou tag como `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -194,52 +178,52 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -O fluxo de trabalho resolve a ref de destino, despacha o `CI` manual com -`target_ref=`, despacha `OpenClaw Release Checks`, prepara um -artefato pai `release-package-under-test` para verificações voltadas a pacotes e -despacha o E2E independente do pacote Telegram quando `release_profile=full` com -`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. Em -seguida, `OpenClaw Release Checks` distribui smoke de instalação, verificações de -lançamento entre sistemas operacionais, cobertura do caminho de lançamento -live/E2E em Docker, Package Acceptance com QA do pacote Telegram, paridade do QA -Lab, Matrix live e Telegram live. Uma execução completa só é aceitável quando o -resumo de `Full Release Validation` mostra `normal_ci` e `release_checks` como -bem-sucedidos. No modo full/all, o filho `npm_telegram` também deve ser -bem-sucedido; fora de full/all, ele é ignorado, a menos que um -`npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final do -verificador inclui tabelas dos jobs mais lentos para cada execução filha, para -que o gerente de lançamento possa ver o caminho crítico atual sem baixar logs. -Consulte [Validação completa de lançamento](/pt-BR/reference/full-release-validation) -para ver a matriz de estágios completa, os nomes exatos dos jobs de workflow, as -diferenças entre os perfis stable e full, artefatos e identificadores de nova -execução focada. -Os workflows filhos são despachados a partir da ref confiável que executa -`Full Release Validation`, normalmente `--ref main`, mesmo quando a `ref` de -destino aponta para um branch ou tag de lançamento mais antigo. Não há uma -entrada separada de ref do workflow Full Release Validation; escolha o harness -confiável escolhendo a ref da execução do workflow. Não use `--ref main -f -ref=` para prova de commit exata em uma `main` móvel; SHAs brutos de commit -não podem ser refs de despacho de workflow, então use `pnpm ci:full-release ---sha ` para criar o branch temporário fixado. +O workflow resolve a ref de destino, dispara o `CI` manual com +`target_ref=`, dispara `OpenClaw Release Checks`, prepara um +artefato pai `release-package-under-test` para verificações voltadas a pacote e +dispara o E2E autônomo do pacote Telegram quando `release_profile=full` com +`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. `OpenClaw Release +Checks` então distribui para install smoke, verificações de release entre SOs, cobertura live/E2E Docker +do caminho de release quando o soak está habilitado, Package Acceptance com QA do pacote Telegram, paridade QA Lab, Matrix live e Telegram live. Uma execução completa só é aceitável quando o +resumo de `Full Release Validation` +mostra `normal_ci` e `release_checks` como bem-sucedidos. No modo full/all, +o filho `npm_telegram` também deve ser bem-sucedido; fora de full/all, ele é ignorado +a menos que um `npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final do +verificador inclui tabelas dos jobs mais lentos para cada execução filha, para que o gerente de release +possa ver o caminho crítico atual sem baixar logs. +Consulte [Validação completa de release](/pt-BR/reference/full-release-validation) para a +matriz completa de etapas, os nomes exatos dos jobs do workflow, diferenças entre perfis stable e full, +artefatos e identificadores de reexecução focada. +Workflows filhos são disparados a partir da ref confiável que executa `Full Release +Validation`, normalmente `--ref main`, mesmo quando a `ref` de destino aponta para uma +branch ou tag de release mais antiga. Não há uma entrada separada de ref do workflow Full Release Validation; +escolha o harness confiável escolhendo a ref da execução do workflow. +Não use `--ref main -f ref=` para prova de commit exato em `main` móvel; +SHAs brutos de commit não podem ser refs de dispatch de workflow, então use +`pnpm ci:full-release --sha ` para criar a branch temporária fixada. -Use `release_profile` para selecionar a amplitude live/de provedor: +Use `release_profile` para selecionar a abrangência live/provedor: -- `minimum`: caminho live e Docker mais rápido, crítico para lançamento, de OpenAI/core -- `stable`: minimum mais cobertura estável de provedor/backend para aprovação de lançamento -- `full`: stable mais cobertura ampla de provedores/mídia consultiva +- `minimum`: caminho Docker e live OpenAI/core crítico de release mais rápido +- `stable`: minimum mais cobertura estável de provedor/backend para aprovação de release +- `full`: stable mais cobertura ampla de provedor/mídia consultiva -`OpenClaw Release Checks` usa a ref confiável do workflow para resolver a ref de -destino uma vez como `release-package-under-test` e reutiliza esse artefato tanto -nas verificações Docker do caminho de lançamento quanto no Package Acceptance. -Isso mantém todas as caixas voltadas a pacotes nos mesmos bytes e evita builds de -pacote repetidos. O smoke de instalação OpenAI entre sistemas operacionais usa -`OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a variável de repo/org está definida; -caso contrário, usa `openai/gpt-5.4`, porque esta lane prova a instalação do -pacote, onboarding, inicialização do Gateway e uma interação live de agente, em -vez de fazer benchmark do modelo padrão mais lento. A matriz live mais ampla de -provedores continua sendo o lugar para cobertura específica por modelo. +Use `run_release_soak=true` com `stable` quando as lanes bloqueantes de release estiverem +verdes e você quiser a varredura exaustiva live/E2E, do caminho de release Docker e +upgrade-survivor all-since-2026.4.23 antes da promoção. `full` implica +`run_release_soak=true`. -Use estas variantes dependendo do estágio de lançamento: +`OpenClaw Release Checks` usa a ref confiável do workflow para resolver a ref de destino +uma vez como `release-package-under-test` e reutiliza esse artefato em verificações entre SOs, +Package Acceptance e verificações Docker do caminho de release quando o soak executa. Isso mantém +todas as máquinas voltadas a pacote nos mesmos bytes e evita builds de pacote repetidos. +O install smoke OpenAI entre SOs usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a +variável de repo/org está definida; caso contrário, `openai/gpt-5.4`, porque esta lane está +provando instalação do pacote, onboarding, inicialização do Gateway e uma rodada de agente live, +em vez de comparar o modelo padrão mais lento. A matriz live de provedores mais ampla +continua sendo o lugar para cobertura específica de modelo. + +Use estas variantes dependendo da etapa de release: ```bash # Validate an unpublished release candidate branch. @@ -269,47 +253,43 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Não use o guarda-chuva completo como a primeira nova execução após uma correção -focada. Se uma caixa falhar, use o workflow filho, job, lane Docker, perfil de -pacote, provedor de modelo ou lane de QA que falhou para a próxima prova. -Execute o guarda-chuva completo novamente somente quando a correção tiver -alterado a orquestração compartilhada de lançamento ou tornado obsoleta a -evidência anterior de todas as caixas. O verificador final do guarda-chuva -reverifica os ids registrados das execuções de workflows filhos; portanto, depois -que um workflow filho for reexecutado com sucesso, reexecute apenas o job pai +Não use o guarda-chuva completo como a primeira reexecução após uma correção focada. Se uma máquina +falhar, use o workflow filho, job, lane Docker, perfil de pacote, provedor de modelo +ou lane QA que falhou para a próxima prova. Execute o guarda-chuva completo novamente somente quando +a correção alterou a orquestração de release compartilhada ou tornou obsoleta a evidência anterior +de todas as máquinas. O verificador final do guarda-chuva verifica novamente os ids registrados das execuções de workflow +filhas, então, depois que um workflow filho for reexecutado com sucesso, reexecute somente o job pai `Verify full validation` que falhou. -Para recuperação limitada, passe `rerun_group` ao guarda-chuva. `all` é a -execução real do candidato a lançamento, `ci` executa apenas o filho de CI normal, -`plugin-prerelease` executa apenas o filho de plugin exclusivo de lançamento, -`release-checks` executa todas as caixas de lançamento, e os grupos de lançamento -mais estreitos são `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, -`qa-parity`, `qa-live` e `npm-telegram`. Novas execuções focadas de -`npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all com -`release_profile=full` usam o artefato de pacote de release-checks. +Para recuperação delimitada, passe `rerun_group` ao guarda-chuva. `all` é a execução real +do candidato a release, `ci` executa somente o filho de CI normal, `plugin-prerelease` +executa somente o filho de Plugin exclusivo de release, `release-checks` executa todas as máquinas de release, +e os grupos de release mais estreitos são `install-smoke`, `cross-os`, +`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` e `npm-telegram`. +Reexecuções focadas de `npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all +com `release_profile=full` usam o artefato de pacote de release-checks. Reexecuções focadas +entre SOs podem adicionar `cross_os_suite_filter=windows/packaged-upgrade` ou +outro filtro de SO/suíte. Falhas QA de release-checks são consultivas; uma falha somente em QA +não bloqueia a validação de release. ### Vitest -A caixa Vitest é o workflow filho `CI` manual. O CI manual ignora -intencionalmente o escopo por mudanças e força o grafo de testes normal para o -candidato a lançamento: shards Linux Node, shards de plugins agrupados, -contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, -smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e -i18n da Control UI. +A máquina Vitest é o workflow filho `CI` manual. O CI manual intencionalmente +ignora o escopo de alterações e força o grafo de testes normal para o candidato a release: +shards Linux Node, shards de Plugins empacotados, contratos de canal, compatibilidade Node 22, +`check`, `check-additional`, build smoke, verificações de docs, Skills Python, Windows, macOS, Android e i18n da Control UI. -Use esta caixa para responder "a árvore de código-fonte passou na suíte completa -normal de testes?" Ela não é a mesma coisa que validação de produto no caminho de -lançamento. Evidências a manter: +Use esta máquina para responder "a árvore de código-fonte passou na suíte normal completa de testes?" +Ela não é o mesmo que validação de produto no caminho de release. Evidências a manter: -- resumo de `Full Release Validation` mostrando a URL da execução `CI` despachada -- execução `CI` verde no SHA de destino exato +- resumo de `Full Release Validation` mostrando a URL da execução de `CI` disparada +- execução de `CI` verde no SHA de destino exato - nomes de shards com falha ou lentos dos jobs de CI ao investigar regressões - artefatos de temporização do Vitest, como `.artifacts/vitest-shard-timings.json`, quando uma execução precisa de análise de desempenho -Execute o CI manual diretamente somente quando o lançamento precisar de CI normal -determinístico, mas não das caixas Docker, QA Lab, live, entre sistemas -operacionais ou de pacote: +Execute o CI manual diretamente somente quando o release precisar de CI normal determinístico, mas +não das máquinas Docker, QA Lab, live, entre SOs ou de pacote: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -317,18 +297,18 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -A caixa Docker fica em `OpenClaw Release Checks` por meio de -`openclaw-live-and-e2e-checks-reusable.yml`, além do workflow `install-smoke` em -modo de lançamento. Ela valida o candidato a lançamento por meio de ambientes -Docker empacotados, em vez de apenas testes em nível de código-fonte. +A máquina Docker vive em `OpenClaw Release Checks` por meio de +`openclaw-live-and-e2e-checks-reusable.yml`, além do workflow `install-smoke` +em modo release. Ela valida o candidato a release por meio de ambientes Docker +empacotados, em vez de apenas testes em nível de código-fonte. -A cobertura Docker de lançamento inclui: +A cobertura Docker de release inclui: -- smoke completo de instalação com o smoke lento de instalação global Bun habilitado -- preparação/reutilização da imagem smoke do Dockerfile raiz por SHA de destino, com QR, - raiz/Gateway e jobs de smoke de instalador/Bun executando como shards separados de install-smoke -- lanes E2E do repositório -- chunks Docker do caminho de lançamento: `core`, `package-update-openai`, +- install smoke completo com o smoke de instalação global Bun lento habilitado +- preparação/reutilização de imagem smoke do Dockerfile raiz por SHA de destino, com jobs de QR, + root/gateway e installer/Bun smoke executando como shards install-smoke separados +- lanes E2E de repositório +- chunks Docker de caminho de release: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, @@ -336,98 +316,91 @@ A cobertura Docker de lançamento inclui: `plugins-runtime-install-e`, `plugins-runtime-install-f`, `plugins-runtime-install-g` e `plugins-runtime-install-h` - cobertura OpenWebUI dentro do chunk `plugins-runtime-services` quando solicitada -- lanes divididas de instalação/desinstalação de plugin agrupado, - de `bundled-plugin-install-uninstall-0` até +- lanes divididas de instalação/desinstalação de Plugin empacotado + `bundled-plugin-install-uninstall-0` até `bundled-plugin-install-uninstall-23` -- suítes live/E2E de provedores e cobertura de modelo live em Docker quando as verificações - de lançamento incluem suítes live +- suítes live/E2E de provedores e cobertura de modelo Docker live quando release checks + incluem suítes live -Use os artefatos Docker antes de reexecutar. O agendador do caminho de lançamento -envia `.artifacts/docker-tests/` com logs de lanes, `summary.json`, -`failures.json`, temporizações de fases, JSON do plano do agendador e comandos de -nova execução. Para recuperação focada, use `docker_lanes=` no -workflow reutilizável live/E2E em vez de reexecutar todos os chunks de -lançamento. Comandos gerados de nova execução incluem o -`package_artifact_run_id` anterior e entradas preparadas de imagem Docker quando -disponíveis, para que uma lane com falha possa reutilizar o mesmo tarball e as -mesmas imagens GHCR. +Use artefatos Docker antes de reexecutar. O agendador de caminho de release envia +`.artifacts/docker-tests/` com logs de lane, `summary.json`, `failures.json`, +temporizações de fase, JSON do plano do agendador e comandos de reexecução. Para recuperação focada, +use `docker_lanes=` no workflow live/E2E reutilizável em vez de +reexecutar todos os chunks de release. Comandos de reexecução gerados incluem +`package_artifact_run_id` anterior e entradas de imagem Docker preparadas quando disponíveis, para que uma +lane com falha possa reutilizar o mesmo tarball e as imagens GHCR. ### QA Lab -A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de -lançamento de comportamento agentivo e em nível de canal, separado do Vitest e -dos mecanismos de pacote do Docker. +A máquina QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de release de +comportamento agêntico e em nível de canal, separado da mecânica de pacote Vitest e Docker. -A cobertura QA Lab de lançamento inclui: +A cobertura QA Lab de release inclui: -- lane de paridade mock comparando a lane candidata OpenAI com a baseline Opus 4.6 - usando o pacote de paridade agentiva -- perfil rápido de QA Matrix live usando o ambiente `qa-live-shared` -- lane de QA Telegram live usando locações de credenciais CI do Convex -- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de prova local explícita +- lane de paridade mock comparando a lane candidata OpenAI contra a linha de base Opus 4.6 + usando o pacote de paridade agêntica +- perfil QA Matrix live rápido usando o ambiente `qa-live-shared` +- lane QA Telegram live usando leases de credenciais CI do Convex +- `pnpm qa:otel:smoke` quando a telemetria de release precisa de prova local explícita -Use esta caixa para responder "o lançamento se comporta corretamente em cenários -de QA e fluxos live de canal?" Mantenha as URLs de artefatos para as lanes de -paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura Matrix completa -continua disponível como uma execução QA-Lab manual em shards, em vez da lane -padrão crítica para lançamento. +Use esta máquina para responder "o release se comporta corretamente em cenários QA e +fluxos de canais live?" Mantenha as URLs de artefatos das lanes de paridade, Matrix e Telegram +ao aprovar o release. A cobertura Matrix completa continua disponível como uma execução QA-Lab +manual em shards, em vez da lane padrão crítica de release. ### Pacote -A caixa Pacote é o gate do produto instalável. Ela é apoiada por +A máquina Package é o gate do produto instalável. Ela é respaldada por `Package Acceptance` e pelo resolvedor `scripts/resolve-openclaw-package-candidate.mjs`. O resolvedor normaliza um -candidato no tarball `package-under-test` consumido pelo Docker E2E, valida o -inventário do pacote, registra a versão do pacote e o SHA-256, e mantém a ref do -harness do workflow separada da ref do código-fonte do pacote. +candidato no tarball `package-under-test` consumido pelo Docker E2E, valida +o inventário do pacote, registra a versão do pacote e SHA-256 e mantém a +ref do harness do workflow separada da ref de origem do pacote. Fontes de candidato compatíveis: -- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw -- `source=ref`: empacota um branch, tag ou SHA completo de commit de `package_ref` confiável +- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de release do OpenClaw +- `source=ref`: empacotar uma branch, tag ou SHA completo de commit `package_ref` confiável com o harness `workflow_ref` selecionado -- `source=url`: baixa um `.tgz` HTTPS com `package_sha256` obrigatório -- `source=artifact`: reutiliza um `.tgz` enviado por outra execução do GitHub Actions +- `source=url`: baixar um `.tgz` HTTPS com `package_sha256` obrigatório +- `source=artifact`: reutilizar um `.tgz` enviado por outra execução do GitHub Actions `OpenClaw Release Checks` executa Package Acceptance com `source=artifact`, o -artefato de pacote de lançamento preparado, `suite_profile=custom`, +artefato de pacote de release preparado, `suite_profile=custom`, `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, -`published_upgrade_survivor_baselines=all-since-2026.4.23`, -`published_upgrade_survivor_scenarios=reported-issues` e -`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização, -limpeza de dependências obsoletas de plugin, fixtures de plugin offline, -atualização de plugin e QA de pacote Telegram contra o mesmo tarball resolvido. A -matriz de upgrade cobre todas as baselines estáveis publicadas no npm de -`2026.4.23` até `latest`; use Package Acceptance com `source=npm` para um -candidato já enviado, ou `source=ref`/`source=artifact` para um tarball npm local -com base em SHA antes da publicação. Ele é o substituto nativo do GitHub para a -maior parte da cobertura de pacote/atualização que antes exigia Parallels. As -verificações de lançamento entre sistemas operacionais ainda importam para -onboarding, instalador e comportamento de plataforma específicos de SO, mas a -validação de produto de pacote/atualização deve preferir Package Acceptance. +`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização, limpeza de +dependências obsoletas de Plugin, fixtures de Plugin offline, atualização de Plugin e QA de pacote +Telegram contra o mesmo tarball resolvido. Verificações bloqueantes de release usam a +linha de base padrão do pacote publicado latest; `run_release_soak=true` ou +`release_profile=full` expande para todas as linhas de base estáveis publicadas no npm de +`2026.4.23` até `latest`, além de fixtures de problemas reportados. Use +Package Acceptance com `source=npm` para um candidato já enviado, ou +`source=ref`/`source=artifact` para um tarball npm local respaldado por SHA antes da +publicação. Ele é a substituição nativa do GitHub para a maior parte da cobertura de +pacote/atualização que anteriormente exigia Parallels. Verificações de release entre SOs ainda importam +para onboarding, instalador e comportamento de plataforma específicos de SO, mas a validação de produto +de pacote/atualização deve preferir Package Acceptance. -A checklist canônica para validação de atualização e plugin é -[Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins). Use-a ao -decidir qual lane local, Docker, Package Acceptance ou de release-check prova uma -instalação/atualização de plugin, limpeza pelo doctor ou mudança de migração de -pacote publicado. A migração exaustiva de atualização publicada a partir de cada -pacote estável `2026.4.23+` é um workflow manual separado `Update Migration`, não -parte do Full Release CI. +O checklist canônico para atualização e validação de Plugin é +[Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins). Use-o ao +decidir qual lane local, Docker, Package Acceptance ou release-check prova uma +instalação/atualização de Plugin, limpeza do doctor ou alteração de migração de pacote publicado. +A migração exaustiva de atualização publicada de todo pacote estável `2026.4.23+` é +um workflow manual `Update Migration` separado, não parte do Full Release CI. -A leniência legada de package-acceptance é intencionalmente limitada no tempo. -Pacotes até `2026.4.25` podem usar o caminho de compatibilidade para lacunas de -metadados já publicadas no npm: entradas privadas de inventário de QA ausentes no -tarball, `gateway install --wrapper` ausente, arquivos de patch ausentes no -fixture git derivado do tarball, `update.channel` persistido ausente, locais -legados de registro de instalação de plugin, persistência ausente de registro de -instalação do marketplace e migração de metadados de configuração durante -`plugins update`. O pacote `2026.4.26` publicado pode avisar sobre arquivos de -carimbo de metadados de build local que já foram enviados. Pacotes posteriores -devem satisfazer os contratos modernos de pacote; essas mesmas lacunas fazem a -validação de lançamento falhar. +A tolerância legada de package-acceptance é intencionalmente limitada no tempo. Pacotes até +`2026.4.25` podem usar o caminho de compatibilidade para lacunas de metadados já publicadas +no npm: entradas privadas de inventário QA ausentes do tarball, ausência de +`gateway install --wrapper`, arquivos de patch ausentes na fixture git derivada do tarball, +ausência de `update.channel` persistido, locais legados de registros de instalação de Plugin, +ausência de persistência de registro de instalação do marketplace e migração de metadados +de configuração durante `plugins update`. O pacote `2026.4.26` publicado pode avisar +sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores +devem satisfazer os contratos modernos de pacote; essas mesmas lacunas falham na validação +de release. -Use perfis Package Acceptance mais amplos quando a pergunta de lançamento for -sobre um pacote instalável real: +Use perfis Package Acceptance mais amplos quando a pergunta de release for sobre um +pacote instalável real: ```bash gh workflow run package-acceptance.yml \ @@ -441,33 +414,33 @@ gh workflow run package-acceptance.yml \ Perfis comuns de pacote: -- `smoke`: faixas rápidas de instalação de pacote/canal/agente, rede do Gateway e +- `smoke`: lanes rápidas de instalação de pacote/canal/agente, rede do Gateway e recarregamento de configuração -- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o - padrão de verificação de lançamento -- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa web da OpenAI - e OpenWebUI -- `full`: partes do caminho de lançamento Docker com OpenWebUI +- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o padrão + da verificação de release +- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa + web da OpenAI e OpenWebUI +- `full`: partes do caminho de release do Docker com OpenWebUI - `custom`: lista exata de `docker_lanes` para reexecuções focadas -Para prova do Telegram com pacote candidato, habilite `telegram_mode=mock-openai` ou -`telegram_mode=live-frontier` em Package Acceptance. O workflow passa o tarball -resolvido de `package-under-test` para a faixa do Telegram; o workflow avulso do -Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação. +Para prova de Telegram de candidato a pacote, habilite `telegram_mode=mock-openai` ou +`telegram_mode=live-frontier` no Package Acceptance. O workflow passa o tarball +`package-under-test` resolvido para a lane do Telegram; o workflow independente +do Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação. -## Automação de publicação de lançamento +## Automação de publicação de release `OpenClaw Release Publish` é o ponto de entrada mutável normal de publicação. Ele -orquestra os workflows de publicador confiável na ordem exigida pelo lançamento: +orquestra os workflows de publicador confiável na ordem que o release exige: -1. Fazer checkout da tag de lançamento e resolver seu SHA de commit. +1. Fazer checkout da tag de release e resolver seu SHA de commit. 2. Verificar se a tag é alcançável a partir de `main` ou `release/*`. 3. Executar `pnpm plugins:sync:check`. 4. Disparar `Plugin NPM Release` com `publish_scope=all-publishable` e `ref=`. 5. Disparar `Plugin ClawHub Release` com o mesmo escopo e SHA. -6. Disparar `OpenClaw NPM Release` com a tag de lançamento, a dist-tag npm e o - `preflight_run_id` salvo. +6. Disparar `OpenClaw NPM Release` com a tag de release, a dist-tag npm e + o `preflight_run_id` salvo. Exemplo de publicação beta: @@ -500,19 +473,19 @@ gh workflow run openclaw-release-publish.yml \ ``` Use os workflows de nível mais baixo `Plugin NPM Release` e `Plugin ClawHub Release` -apenas para trabalhos focados de reparo ou republicação. Para um reparo de Plugin -selecionado, passe `plugin_publish_scope=selected` e `plugins=@openclaw/name` para -`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o pacote -OpenClaw não deve ser publicado. +somente para trabalho focado de reparo ou republicação. Para um reparo de Plugin selecionado, passe +`plugin_publish_scope=selected` e `plugins=@openclaw/name` para +`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o +pacote OpenClaw não deve ser publicado. ## Entradas do workflow NPM `OpenClaw NPM Release` aceita estas entradas controladas pelo operador: -- `tag`: tag de lançamento obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou +- `tag`: tag de release obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou `v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA de commit - completo de 40 caracteres do branch do workflow atual para preflight apenas de validação -- `preflight_only`: `true` apenas para validação/build/pacote, `false` para o + completo de 40 caracteres da branch de workflow atual para preflight somente de validação +- `preflight_only`: `true` somente para validação/build/pacote, `false` para o caminho real de publicação - `preflight_run_id`: obrigatório no caminho real de publicação para que o workflow reutilize o tarball preparado da execução de preflight bem-sucedida @@ -520,70 +493,73 @@ OpenClaw não deve ser publicado. `OpenClaw Release Publish` aceita estas entradas controladas pelo operador: -- `tag`: tag de lançamento obrigatória; já deve existir -- `preflight_run_id`: id da execução de preflight bem-sucedida de `OpenClaw NPM Release`; +- `tag`: tag de release obrigatória; já deve existir +- `preflight_run_id`: id de execução de preflight bem-sucedida de `OpenClaw NPM Release`; obrigatório quando `publish_openclaw_npm=true` - `npm_dist_tag`: tag npm de destino para o pacote OpenClaw -- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` apenas +- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` somente para trabalho focado de reparo - `plugins`: nomes de pacotes `@openclaw/*` separados por vírgula quando `plugin_publish_scope=selected` -- `publish_openclaw_npm`: o padrão é `true`; defina como `false` apenas ao usar o - workflow como orquestrador de reparo somente de Plugins +- `publish_openclaw_npm`: o padrão é `true`; defina como `false` somente ao usar o + workflow como orquestrador de reparo somente de Plugin `OpenClaw Release Checks` aceita estas entradas controladas pelo operador: -- `ref`: branch, tag ou SHA de commit completo a validar. Verificações que carregam segredos - exigem que o commit resolvido seja alcançável a partir de um branch do OpenClaw ou - tag de lançamento. +- `ref`: branch, tag ou SHA de commit completo a validar. Verificações com segredos + exigem que o commit resolvido seja alcançável a partir de uma branch OpenClaw ou + tag de release. +- `run_release_soak`: opta por soak exaustivo ao vivo/E2E, caminho de release do Docker e + soak de sobrevivente de upgrade all-since em verificações de release estável/padrão. Ele é forçado + por `release_profile=full`. Regras: - Tags estáveis e de correção podem publicar em `beta` ou `latest` -- Tags beta de pré-lançamento podem publicar apenas em `beta` -- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida apenas quando +- Tags beta de pré-release podem publicar somente em `beta` +- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida somente quando `preflight_only=true` - `OpenClaw Release Checks` e `Full Release Validation` são sempre - apenas de validação + somente de validação - O caminho real de publicação deve usar o mesmo `npm_dist_tag` usado durante o preflight; o workflow verifica esses metadados antes de a publicação continuar -## Sequência de lançamento npm estável +## Sequência de release npm estável -Ao preparar um lançamento npm estável: +Ao cortar um release npm estável: 1. Execute `OpenClaw NPM Release` com `preflight_only=true` - - Antes de uma tag existir, você pode usar o SHA de commit completo do branch do workflow atual - para uma execução simulada apenas de validação do workflow de preflight -2. Escolha `npm_dist_tag=beta` para o fluxo normal beta primeiro, ou `latest` apenas - quando você quiser intencionalmente uma publicação estável direta -3. Execute `Full Release Validation` no branch de lançamento, tag de lançamento ou SHA de - commit completo quando quiser CI normal mais cobertura de cache de prompt ao vivo, - Docker, QA Lab, Matrix e Telegram em um único workflow manual -4. Se você intencionalmente precisar apenas do grafo de testes normal determinístico, execute o - workflow manual `CI` na ref de lançamento + - Antes de existir uma tag, você pode usar o SHA de commit completo da branch de workflow atual + para um ensaio somente de validação do workflow de preflight +2. Escolha `npm_dist_tag=beta` para o fluxo normal beta-primeiro, ou `latest` somente + quando você intencionalmente quiser uma publicação estável direta +3. Execute `Full Release Validation` na branch de release, tag de release ou SHA de + commit completo quando quiser CI normal mais cobertura de cache de prompt ao vivo, Docker, QA Lab, + Matrix e Telegram a partir de um único workflow manual +4. Se você intencionalmente só precisar do grafo normal determinístico de testes, execute o + workflow manual `CI` na ref de release em vez disso 5. Salve o `preflight_run_id` bem-sucedido 6. Execute `OpenClaw Release Publish` com a mesma `tag`, o mesmo `npm_dist_tag` e o `preflight_run_id` salvo; ele publica Plugins externalizados no npm - e no ClawHub antes de promover o pacote npm do OpenClaw -7. Se o lançamento chegou a `beta`, use o workflow privado + e no ClawHub antes de promover o pacote npm OpenClaw +7. Se o release foi lançado em `beta`, use o workflow privado `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` para promover essa versão estável de `beta` para `latest` -8. Se o lançamento foi publicado intencionalmente diretamente em `latest` e `beta` +8. Se o release foi publicado intencionalmente diretamente em `latest` e `beta` deve seguir a mesma build estável imediatamente, use esse mesmo workflow privado para apontar ambas as dist-tags para a versão estável, ou deixe a sincronização - autorreparadora agendada mover `beta` depois + auto-reparadora agendada dele mover `beta` depois -A mutação de dist-tag fica no repositório privado por segurança, porque ainda -exige `NPM_TOKEN`, enquanto o repositório público mantém publicação apenas com OIDC. +A mutação de dist-tag fica no repo privado por segurança porque ela ainda +exige `NPM_TOKEN`, enquanto o repo público mantém publicação somente por OIDC. -Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção beta primeiro +Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção beta-primeiro documentados e visíveis ao operador. -Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos da CLI -do 1Password (`op`) apenas dentro de uma sessão tmux dedicada. Não chame `op` -diretamente do shell principal do agente; mantê-lo dentro do tmux torna prompts, -alertas e o manuseio de OTP observáveis e evita alertas repetidos no host. +Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos +da CLI (`op`) do 1Password somente dentro de uma sessão tmux dedicada. Não chame `op` +diretamente a partir do shell principal do agente; mantê-lo dentro do tmux torna prompts, +alertas e tratamento de OTP observáveis e evita alertas repetidos do host. ## Referências públicas @@ -597,10 +573,10 @@ alertas e o manuseio de OTP observáveis e evita alertas repetidos no host. - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Mantenedores usam os documentos privados de lançamento em +Mantenedores usam a documentação privada de release em [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) para o runbook real. ## Relacionado -- [Canais de lançamento](/pt-BR/install/development-channels) +- [Canais de release](/pt-BR/install/development-channels) diff --git a/docs/pt-BR/reference/full-release-validation.md b/docs/pt-BR/reference/full-release-validation.md index d33558dc2..a7b039a9d 100644 --- a/docs/pt-BR/reference/full-release-validation.md +++ b/docs/pt-BR/reference/full-release-validation.md @@ -2,25 +2,25 @@ read_when: - Executando ou reexecutando a validação completa de lançamento - Comparando os perfis de validação de lançamento estável e completo - - Depurando falhas na etapa de validação de lançamento -summary: Estágios de Validação Completa de Lançamento, fluxos de trabalho filhos, perfis de lançamento, identificadores de reexecução e evidências -title: Validação completa de lançamento + - Depuração de falhas no estágio de validação de lançamento +summary: Etapas, fluxos de trabalho filhos, perfis de lançamento, identificadores de reexecução e evidências da Validação completa de lançamento +title: Validação completa do lançamento x-i18n: - generated_at: "2026-05-03T21:37:22Z" + generated_at: "2026-05-05T01:49:17Z" model: gpt-5.5 provider: openai - source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7 + source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d source_path: reference/full-release-validation.md workflow: 16 --- -`Full Release Validation` é o guarda-chuva da release. Ele é o único ponto de entrada -manual para prova pré-release, mas a maior parte do trabalho acontece em workflows -filhos para que uma caixa com falha possa ser executada novamente sem reiniciar a -release inteira. +`Full Release Validation` é o guarda-chuva de validação de lançamento. Ele é o único +ponto de entrada manual para a comprovação de pré-lançamento, mas a maior parte do +trabalho acontece em fluxos de trabalho filhos, para que uma caixa com falha possa +ser executada novamente sem reiniciar todo o lançamento. -Execute-o a partir de uma ref de workflow confiável, normalmente `main`, e passe a branch -de release, a tag ou o SHA completo do commit como `ref`: +Execute-o a partir de uma referência de fluxo de trabalho confiável, normalmente `main`, e passe a branch de lançamento, +tag ou SHA completo do commit como `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -31,103 +31,108 @@ gh workflow run full-release-validation.yml \ -f release_profile=stable ``` -Os workflows filhos usam a ref de workflow confiável para o harness e o `ref` -de entrada para o candidato em teste. Isso mantém a nova lógica de validação -disponível ao validar uma branch ou tag de release mais antiga. +Os fluxos de trabalho filhos usam a referência de fluxo de trabalho confiável para o harness e a entrada +`ref` para o candidato em teste. Isso mantém a nova lógica de validação disponível +ao validar uma branch ou tag de lançamento mais antiga. -A Aceitação de Pacote normalmente cria o tarball candidato a partir do `ref` -resolvido, incluindo execuções com SHA completo disparadas com `pnpm ci:full-release`. -Após a publicação, passe `package_acceptance_package_spec=openclaw@YYYY.M.D` (ou -`openclaw@beta`/`openclaw@latest`) para executar a mesma matriz de pacote/atualização -contra o pacote npm entregue. +Por padrão, `release_profile=stable` executa as faixas bloqueadoras de lançamento e ignora +o soak live/Docker exaustivo. Passe `run_release_soak=true` para incluir as +faixas de soak em uma execução estável. `release_profile=full` sempre habilita as faixas de soak, para que +o perfil consultivo amplo nunca perca cobertura silenciosamente. + +Package Acceptance normalmente compila o tarball candidato a partir do +`ref` resolvido, incluindo execuções com SHA completo disparadas com `pnpm ci:full-release`. Após +a publicação, passe `package_acceptance_package_spec=openclaw@YYYY.M.D` (ou +`openclaw@beta`/`openclaw@latest`) para executar a mesma matriz de pacote/atualização contra +o pacote npm publicado. ## Estágios de nível superior -| Estágio | Detalhes | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Resolução do alvo | **Job:** `Resolve target ref`
**Workflow filho:** nenhum
**Comprova:** resolve a branch de release, a tag ou o SHA completo do commit e registra as entradas selecionadas.
**Nova execução:** execute novamente o guarda-chuva se isso falhar. | -| Vitest e CI normal | **Job:** `Run normal full CI`
**Workflow filho:** `CI`
**Comprova:** grafo de CI completo manual contra a ref alvo, incluindo lanes Linux Node, shards de Plugin empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, i18n da Control UI e Android pelo guarda-chuva.
**Nova execução:** `rerun_group=ci`. | -| Pré-release de Plugin | **Job:** `Run plugin prerelease validation`
**Workflow filho:** `Plugin Prerelease`
**Comprova:** verificações estáticas de Plugin exclusivas de release, cobertura agêntica de Plugin, shards do lote completo de extensões e lanes Docker de pré-release de Plugin.
**Nova execução:** `rerun_group=plugin-prerelease`. | -| Verificações de release | **Job:** `Run release/live/Docker/QA validation`
**Workflow filho:** `OpenClaw Release Checks`
**Comprova:** smoke de instalação, verificações de pacote entre sistemas operacionais, suítes live/E2E, chunks do caminho de release Docker, Aceitação de Pacote, paridade do QA Lab, Matrix live e Telegram live.
**Nova execução:** `rerun_group=release-checks` ou um handle mais restrito de release-checks. | -| Artefato de pacote | **Job:** `Prepare release package artifact`
**Workflow filho:** nenhum
**Comprova:** cria o tarball pai `release-package-under-test` cedo o suficiente para verificações voltadas a pacote que não precisam esperar por `OpenClaw Release Checks`.
**Nova execução:** execute novamente o guarda-chuva ou forneça `npm_telegram_package_spec` para `rerun_group=npm-telegram`. | -| Pacote Telegram | **Job:** `Run package Telegram E2E`
**Workflow filho:** `NPM Telegram Beta E2E`
**Comprova:** prova de pacote Telegram baseada no artefato pai para `rerun_group=all` com `release_profile=full`, ou prova de Telegram com pacote publicado quando `npm_telegram_package_spec` está definido.
**Nova execução:** `rerun_group=npm-telegram` com `npm_telegram_package_spec`. | -| Verificador do guarda-chuva | **Job:** `Verify full validation`
**Workflow filho:** nenhum
**Comprova:** verifica novamente as conclusões registradas das execuções filhas e anexa tabelas dos jobs mais lentos dos workflows filhos.
**Nova execução:** execute novamente apenas este job depois de reexecutar um filho com falha até ficar verde. | +| Estágio | Detalhes | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resolução do alvo | **Job:** `Resolve target ref`
**Fluxo de trabalho filho:** nenhum
**Comprova:** resolve a branch de lançamento, tag ou SHA completo do commit e registra as entradas selecionadas.
**Executar novamente:** execute o guarda-chuva novamente se isso falhar. | +| Vitest e CI normal | **Job:** `Run normal full CI`
**Fluxo de trabalho filho:** `CI`
**Comprova:** grafo manual completo de CI contra o ref alvo, incluindo faixas Linux Node, shards de Plugin agrupados, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, i18n da Control UI e Android via guarda-chuva.
**Executar novamente:** `rerun_group=ci`. | +| Pré-lançamento de Plugin | **Job:** `Run plugin prerelease validation`
**Fluxo de trabalho filho:** `Plugin Prerelease`
**Comprova:** verificações estáticas de Plugin somente de lançamento, cobertura agentic de Plugin, shards completos de lote de extensão e faixas Docker de pré-lançamento de Plugin.
**Executar novamente:** `rerun_group=plugin-prerelease`. | +| Verificações de lançamento | **Job:** `Run release/live/Docker/QA validation`
**Fluxo de trabalho filho:** `OpenClaw Release Checks`
**Comprova:** smoke de instalação, verificações de pacote entre OSs, Package Acceptance, paridade do QA Lab, Matrix live e Telegram live. Com `run_release_soak=true` ou `release_profile=full`, também executa suítes live/E2E exaustivas e chunks de caminho de lançamento Docker.
**Executar novamente:** `rerun_group=release-checks` ou um identificador release-checks mais restrito. | +| Artefato de pacote | **Job:** `Prepare release package artifact`
**Fluxo de trabalho filho:** nenhum
**Comprova:** cria o tarball pai `release-package-under-test` cedo o suficiente para verificações voltadas a pacote que não precisam aguardar `OpenClaw Release Checks`.
**Executar novamente:** execute o guarda-chuva novamente ou forneça `npm_telegram_package_spec` para `rerun_group=npm-telegram`. | +| Package Telegram | **Job:** `Run package Telegram E2E`
**Fluxo de trabalho filho:** `NPM Telegram Beta E2E`
**Comprova:** comprovação de pacote Telegram baseada em artefato pai para `rerun_group=all` com `release_profile=full`, ou comprovação de Telegram de pacote publicado quando `npm_telegram_package_spec` está definido.
**Executar novamente:** `rerun_group=npm-telegram` com `npm_telegram_package_spec`. | +| Verificador do guarda-chuva | **Job:** `Verify full validation`
**Fluxo de trabalho filho:** nenhum
**Comprova:** verifica novamente as conclusões registradas das execuções filhas e anexa tabelas dos jobs mais lentos dos fluxos de trabalho filhos.
**Executar novamente:** execute novamente apenas este job depois de reexecutar um filho com falha até ficar verde. | Para `ref=main` e `rerun_group=all`, um guarda-chuva mais novo substitui um mais antigo. -Quando o pai é cancelado, seu monitor cancela qualquer workflow filho que ele já -tenha disparado. Execuções de validação de branch e tag de release não se cancelam +Quando o pai é cancelado, seu monitor cancela qualquer fluxo de trabalho filho que ele já +tenha disparado. Execuções de validação de branch e tag de lançamento não se cancelam por padrão. -## Estágios das verificações de release +## Estágios de verificações de lançamento -`OpenClaw Release Checks` é o maior workflow filho. Ele resolve o alvo uma vez -e prepara um artefato compartilhado `release-package-under-test` quando estágios +`OpenClaw Release Checks` é o maior fluxo de trabalho filho. Ele resolve o alvo +uma vez e prepara um artefato compartilhado `release-package-under-test` quando estágios voltados a pacote ou Docker precisam dele. -| Estágio | Detalhes | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alvo da release | **Job:** `Resolve target ref`
**Workflow de apoio:** nenhum
**Testa:** ref selecionada, SHA esperado opcional, perfil, grupo de nova execução e filtro focado da suíte live.
**Nova execução:** `rerun_group=release-checks`. | -| Artefato de pacote | **Job:** `Prepare release package artifact`
**Workflow de apoio:** nenhum
**Testa:** empacota ou resolve um tarball candidato e envia `release-package-under-test` para verificações downstream voltadas a pacote.
**Nova execução:** o grupo de pacote, cross-OS ou live/E2E afetado. | -| Smoke de instalação | **Job:** `Run install smoke`
**Workflow de apoio:** `Install Smoke`
**Testa:** caminho completo de instalação com reutilização da imagem smoke do Dockerfile raiz, instalação de pacote QR, smokes Docker de raiz e Gateway, testes Docker do instalador, smoke de provider de imagem com instalação global Bun e E2E rápido de instalação/desinstalação de Plugin empacotado.
**Nova execução:** `rerun_group=install-smoke`. | -| Cross-OS | **Job:** `cross_os_release_checks`
**Workflow de apoio:** `OpenClaw Cross-OS Release Checks (Reusable)`
**Testa:** lanes novas e de upgrade em Linux, Windows e macOS para o provider e modo selecionados, usando o tarball candidato mais um pacote de baseline.
**Nova execução:** `rerun_group=cross-os`. | -| Repo e E2E live | **Job:** `Run repo/live E2E validation`
**Workflow de apoio:** `OpenClaw Live And E2E Checks (Reusable)`
**Testa:** E2E do repositório, cache live, streaming websocket da OpenAI, provider live nativo e shards de Plugin, e harnesses live com Docker para modelo/backend/Gateway selecionados por `release_profile`.
**Nova execução:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. | -| Caminho de release Docker | **Job:** `Run Docker release-path validation`
**Workflow de apoio:** `OpenClaw Live And E2E Checks (Reusable)`
**Testa:** chunks Docker do caminho de release contra o artefato de pacote compartilhado.
**Nova execução:** `rerun_group=live-e2e`. | -| Aceitação de Pacote | **Job:** `Run package acceptance`
**Workflow de apoio:** `Package Acceptance`
**Testa:** fixtures offline de pacote de Plugin, atualização de Plugin, aceitação de pacote Telegram com mock da OpenAI e verificações de sobrevivência de upgrade publicado a partir de toda release npm estável em ou após `2026.4.23` contra o mesmo tarball.
**Nova execução:** `rerun_group=package`. | -| Paridade de QA | **Job:** `Run QA Lab parity lane` e `Run QA Lab parity report`
**Workflow de apoio:** jobs diretos
**Testa:** pacotes de paridade agêntica do candidato e do baseline, depois o relatório de paridade.
**Nova execução:** `rerun_group=qa-parity` ou `rerun_group=qa`. | -| Matrix live de QA | **Job:** `Run QA Lab live Matrix lane`
**Workflow de apoio:** job direto
**Testa:** perfil rápido de QA live Matrix no ambiente `qa-live-shared`.
**Nova execução:** `rerun_group=qa-live` ou `rerun_group=qa`. | -| Telegram live de QA | **Job:** `Run QA Lab live Telegram lane`
**Workflow de apoio:** job direto
**Testa:** QA live do Telegram com leases de credenciais Convex CI.
**Nova execução:** `rerun_group=qa-live` ou `rerun_group=qa`. | -| Verificador de release | **Job:** `Verify release checks`
**Workflow de apoio:** nenhum
**Testa:** jobs de release-check obrigatórios para o grupo de nova execução selecionado.
**Nova execução:** execute novamente depois que os jobs filhos focados passarem. | +| Etapa | Detalhes | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alvo de release | **Job:** `Resolve target ref`
**Workflow de suporte:** nenhum
**Testes:** ref selecionada, SHA esperado opcional, perfil, grupo de reexecução e filtro de suíte live focada.
**Reexecução:** `rerun_group=release-checks`. | +| Artefato de pacote | **Job:** `Prepare release package artifact`
**Workflow de suporte:** nenhum
**Testes:** empacota ou resolve um tarball candidato e faz upload de `release-package-under-test` para verificações downstream voltadas a pacotes.
**Reexecução:** o pacote afetado, grupo cross-OS ou live/E2E. | +| 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 Bun e E2E rápido de instalação/desinstalação de Plugin empacotado.
**Reexecução:** `rerun_group=install-smoke`. | +| Cross-OS | **Job:** `cross_os_release_checks`
**Workflow de suporte:** `OpenClaw Cross-OS Release Checks (Reusable)`
**Testes:** lanes novas e de upgrade no Linux, Windows e macOS para o provedor e modo selecionados, usando o tarball candidato mais um pacote de linha de base.
**Reexecução:** `rerun_group=cross-os`. | +| Repo e E2E live | **Job:** `Run repo/live E2E validation`
**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`
**Testes:** E2E do repositório, cache live, streaming websocket OpenAI, provedor live nativo e shards de Plugin, além de harnesses de modelo/backend/Gateway live com Docker selecionados por `release_profile`.
**Execuções:** `run_release_soak=true`, `release_profile=full` ou `rerun_group=live-e2e` focado.
**Reexecução:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. | +| Caminho de release Docker | **Job:** `Run Docker release-path validation`
**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`
**Testes:** chunks Docker do caminho de release contra o artefato de pacote compartilhado.
**Execuções:** `run_release_soak=true`, `release_profile=full` ou `rerun_group=live-e2e` focado.
**Reexecução:** `rerun_group=live-e2e`. | +| Aceitação de pacote | **Job:** `Run package acceptance`
**Workflow de suporte:** `Package Acceptance`
**Testes:** fixtures offline de pacote de Plugin, atualização de Plugin, aceitação de pacote Telegram com OpenAI simulada e verificações de sobrevivência de upgrade publicado contra o mesmo tarball. Verificações de release bloqueantes usam a linha de base publicada mais recente padrão; verificações soak expandem para cada release npm estável em ou após `2026.4.23` mais fixtures de problemas reportados.
**Reexecução:** `rerun_group=package`. | +| Paridade de 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 da linha de base, depois o relatório de paridade.
**Reexecução:** `rerun_group=qa-parity` ou `rerun_group=qa`. | +| Matriz live de QA | **Job:** `Run QA Lab live Matrix lane`
**Workflow de suporte:** job direto
**Testes:** perfil rápido de QA live Matrix no ambiente `qa-live-shared`.
**Reexecução:** `rerun_group=qa-live` ou `rerun_group=qa`. | +| Telegram live de QA | **Job:** `Run QA Lab live Telegram lane`
**Workflow de suporte:** job direto
**Testes:** QA live Telegram com concessões de credenciais do Convex CI.
**Reexecução:** `rerun_group=qa-live` ou `rerun_group=qa`. | +| Verificador de release | **Job:** `Verify release checks`
**Workflow de suporte:** nenhum
**Testes:** jobs obrigatórios de verificação de release para o grupo de reexecução selecionado.
**Reexecução:** reexecute depois que os jobs filhos focados passarem. | ## Chunks do caminho de release Docker -O estágio do caminho de release Docker executa estes chunks quando `live_suite_filter` está +A etapa do caminho de release Docker executa estes chunks quando `live_suite_filter` está vazio: -| Chunk | Cobertura | -| --------------------------------------------------------------- | ---------------------------------------------------------------------- | -| `core` | Lanes smoke do caminho de release Docker do Core. | -| `package-update-openai` | Comportamento de instalação e atualização do pacote OpenAI. | -| `package-update-anthropic` | Comportamento de instalação e atualização do pacote Anthropic. | -| `package-update-core` | Comportamento de pacote e atualização neutro em relação a provider. | -| `plugins-runtime-plugins` | Lanes de runtime de Plugin que exercitam comportamento de Plugin. | -| `plugins-runtime-services` | Lanes de runtime de Plugin apoiadas por serviço; inclui OpenWebUI quando solicitado. | -| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Lotes de instalação/runtime de Plugin divididos para validação de release paralela. | +| Chunk | Cobertura | +| --------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `core` | Lanes smoke centrais do caminho de release Docker. | +| `package-update-openai` | Comportamento de instalação e atualização de pacote OpenAI. | +| `package-update-anthropic` | Comportamento de instalação e atualização de pacote Anthropic. | +| `package-update-core` | Comportamento de pacote e atualização neutro em relação a provedor. | +| `plugins-runtime-plugins` | Lanes de runtime de Plugin que exercitam o comportamento de Plugin. | +| `plugins-runtime-services` | Lanes de runtime de Plugin com suporte por serviço; inclui OpenWebUI quando solicitado. | +| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Lotes de instalação/runtime de Plugin divididos para validação paralela de release. | -Use `docker_lanes=` direcionado no workflow reutilizável live/E2E quando -apenas uma lane do Docker falhar. Os artefatos de release incluem comandos de -reexecução por lane com entradas de reutilização de artefato de pacote e imagem -quando disponíveis. +Use `docker_lanes=` direcionado no workflow live/E2E reutilizável quando +apenas uma lane Docker falhar. Os artefatos de release incluem comandos de +reexecução por lane com entradas de artefato de pacote e reutilização de imagem quando disponíveis. ## Perfis de release -`release_profile` controla principalmente a abrangência live/provedor dentro das verificações de release. -Ele não remove a CI completa normal, Pré-lançamento de Plugin, smoke de instalação, aceitação de -pacote, QA Lab nem blocos do caminho de release do Docker. `full` também faz a -execução agregadora rodar o E2E do Telegram do pacote contra o artefato de pacote de release pai quando -`rerun_group=all`, então um candidato completo de pré-publicação não pula silenciosamente essa -lane de pacote do Telegram. +`release_profile` controla principalmente a amplitude live/provedor dentro das verificações de release. +Ele não remove CI completa normal, pré-lançamento de Plugin, smoke de instalação, aceitação de +pacote ou QA Lab. Para `stable`, E2E repo/live exaustivo e chunks de +caminho de release Docker são cobertura soak e são executados quando `run_release_soak=true`. +`full` força a cobertura soak e também faz a execução guarda-chuva executar o E2E Telegram de pacote +contra o artefato de pacote de release pai quando `rerun_group=all`, para que um candidato completo +de pré-publicação não pule silenciosamente essa lane de pacote Telegram. -| Perfil | Uso pretendido | Cobertura live/provedor incluída | +| Perfil | Uso pretendido | Cobertura live/provedor incluída | | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `minimum` | Smoke crítico de release mais rápido. | Caminho live OpenAI/core, modelos live do Docker para OpenAI, núcleo do gateway nativo, perfil de gateway OpenAI nativo, plugin OpenAI nativo e gateway live OpenAI do Docker. | -| `stable` | Perfil padrão de aprovação de release. | `minimum` mais smoke do Anthropic, Google, MiniMax, backend, harness de teste live nativo, backend de CLI live do Docker, bind ACP do Docker, harness Codex do Docker e um shard de smoke OpenCode Go. | -| `full` | Varredura consultiva ampla. | `stable` mais provedores consultivos, shards live de plugins e shards live de mídia. | +| `minimum` | Smoke mais rápido crítico para release. | Caminho live OpenAI/core, modelos live Docker para OpenAI, core do Gateway nativo, perfil de Gateway OpenAI nativo, Plugin OpenAI nativo e Gateway live Docker OpenAI. | +| `stable` | Perfil padrão de aprovação de release. | `minimum` mais smoke Anthropic, Google, MiniMax, backend, harness de teste live nativo, backend de CLI live Docker, bind ACP Docker, harness Codex Docker e um shard smoke OpenCode Go. | +| `full` | Varredura consultiva ampla. | `stable` mais provedores consultivos, shards live de Plugin e shards live de mídia. | -## Adições apenas de full +## Adições apenas do full -Estas suítes são puladas por `stable` e incluídas por `full`: +Estas suítes são ignoradas por `stable` e incluídas por `full`: -| Área | Cobertura apenas de full | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| Modelos live do Docker | OpenCode Go, OpenRouter, xAI, Z.ai e Fireworks. | -| Gateway live do Docker | Provedores consultivos divididos em shards DeepSeek/Fireworks, OpenCode Go/OpenRouter e xAI/Z.ai. | -| Perfis de provedor do gateway nativo | Shards completos Anthropic Opus e Sonnet/Haiku, Fireworks, DeepSeek, shards completos de modelos OpenCode Go, OpenRouter, xAI e Z.ai. | -| Shards live de plugins nativos | Plugins A-K, L-N, O-Z outros, Moonshot e xAI. | -| Shards live de mídia nativos | Áudio, música do Google, música do MiniMax e grupos de vídeo A-D. | +| Área | Cobertura apenas do full | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| Modelos live Docker | OpenCode Go, OpenRouter, xAI, Z.ai e Fireworks. | +| Gateway live Docker | Provedores consultivos divididos em shards DeepSeek/Fireworks, OpenCode Go/OpenRouter e xAI/Z.ai. | +| Perfis de provedor do Gateway nativo | Shards Anthropic completos Opus e Sonnet/Haiku, Fireworks, DeepSeek, shards completos de modelo OpenCode Go, OpenRouter, xAI e Z.ai. | +| Shards live de Plugin nativo | Plugins A-K, L-N, O-Z outros, Moonshot e xAI. | +| Shards live de mídia nativa | Áudio, música Google, música MiniMax e grupos de vídeo A-D. | `stable` inclui `native-live-src-gateway-profiles-anthropic-smoke` e -`native-live-src-gateway-profiles-opencode-go-smoke`; `full` usa os shards mais amplos -de modelos Anthropic e OpenCode Go em vez disso. Reexecuções focadas ainda podem usar os +`native-live-src-gateway-profiles-opencode-go-smoke`; `full` usa os shards +mais amplos de modelos Anthropic e OpenCode Go em vez disso. Reexecuções focadas ainda podem usar os identificadores agregados `native-live-src-gateway-profiles-anthropic` ou `native-live-src-gateway-profiles-opencode-go`. @@ -137,42 +142,53 @@ Use `rerun_group` para evitar repetir caixas de release não relacionadas: | Identificador | Escopo | | ------------------- | --------------------------------------------------------------------- | -| `all` | Todos os estágios de Validação Completa de Release. | -| `ci` | Apenas filho de CI completa manual. | -| `plugin-prerelease` | Apenas filho de Pré-lançamento de Plugin. | -| `release-checks` | Todos os estágios de Verificações de Release do OpenClaw. | -| `install-smoke` | Smoke de instalação por meio das verificações de release. | -| `cross-os` | Verificações de release entre sistemas operacionais. | -| `live-e2e` | Validação E2E do repo/live e do caminho de release do Docker. | -| `package` | Aceitação de Pacote. | -| `qa` | Paridade de QA mais lanes live de QA. | +| `all` | Todos os estágios da Validação Completa de Lançamento. | +| `ci` | Apenas o filho manual de CI completa. | +| `plugin-prerelease` | Apenas o filho de pré-lançamento de Plugin. | +| `release-checks` | Todos os estágios das Verificações de Lançamento do OpenClaw. | +| `install-smoke` | Smoke de instalação até as verificações de lançamento. | +| `cross-os` | Verificações de lançamento entre sistemas operacionais. | +| `live-e2e` | Validação de E2E ao vivo do repositório e do caminho de lançamento do Docker. | +| `package` | Aceitação do pacote. | +| `qa` | Paridade de QA mais lanes de QA ao vivo. | | `qa-parity` | Apenas lanes e relatório de paridade de QA. | -| `qa-live` | Apenas Matrix live de QA e Telegram. | -| `npm-telegram` | E2E do Telegram de pacote publicado; exige `npm_telegram_package_spec`. | +| `qa-live` | Apenas Matrix e Telegram de QA ao vivo. | +| `npm-telegram` | E2E do Telegram com pacote publicado; requer `npm_telegram_package_spec`. | -Use `live_suite_filter` com `rerun_group=live-e2e` quando uma suíte live falhar. -IDs de filtro válidos são definidos no workflow reutilizável live/E2E, incluindo +Use `live_suite_filter` com `rerun_group=live-e2e` quando uma suíte ao vivo falhar. +Os ids de filtro válidos são definidos no workflow reutilizável ao vivo/E2E, incluindo `docker-live-models`, `live-gateway-docker`, `live-gateway-anthropic-docker`, `live-gateway-google-docker`, `live-gateway-minimax-docker`, `live-gateway-advisory-docker`, `live-cli-backend-docker`, `live-acp-bind-docker` e `live-codex-harness-docker`. -O identificador `live-gateway-advisory-docker` é um identificador de reexecução agregada para seus -três shards de provedor, então ele ainda se expande para todos os jobs consultivos de gateway Docker. +O identificador `live-gateway-advisory-docker` é um identificador agregado de reexecução para seus +três shards de provedor, então ele ainda se espalha para todos os jobs de Gateway Docker de advisories. -## Evidências a manter +Use `cross_os_suite_filter` com `rerun_group=cross-os` quando uma lane entre sistemas operacionais +falhar. O filtro aceita um id de sistema operacional, um id de suíte ou um par sistema operacional/suíte, por +exemplo `windows/packaged-upgrade`, `windows` ou `packaged-fresh`. Os +resumos entre sistemas operacionais incluem tempos por fase para lanes de upgrade empacotado, e comandos +de longa duração imprimem linhas de Heartbeat para que uma atualização do Windows travada fique visível antes do +tempo limite do job. -Mantenha o resumo de `Full Release Validation` como o índice em nível de release. Ele vincula -IDs de execuções filhas e inclui tabelas dos jobs mais lentos. Para falhas, inspecione primeiro o workflow filho -e depois reexecute o menor identificador correspondente acima. +As lanes de verificações de lançamento de QA são consultivas. Uma falha apenas de QA é relatada como aviso +e não bloqueia o verificador de verificações de lançamento; reexecute `rerun_group=qa`, +`qa-parity` ou `qa-live` quando precisar de evidência de QA atualizada. + +## Evidência a manter + +Mantenha o resumo de `Full Release Validation` como o índice no nível do lançamento. Ele vincula +ids de execução filhos e inclui tabelas dos jobs mais lentos. Para falhas, inspecione primeiro o workflow +filho e depois reexecute o menor identificador correspondente acima. Artefatos úteis: -- `release-package-under-test` do pai de Validação Completa de Release e `OpenClaw Release Checks` -- Artefatos do caminho de release do Docker em `.artifacts/docker-tests/` -- `package-under-test` da Aceitação de Pacote e artefatos de aceitação do Docker -- Artefatos de verificação de release entre sistemas operacionais para cada SO e suíte +- `release-package-under-test` do pai da Validação Completa de Lançamento e `OpenClaw Release Checks` +- Artefatos do caminho de lançamento do Docker em `.artifacts/docker-tests/` +- `package-under-test` da Aceitação do Pacote e artefatos de aceitação do Docker +- Artefatos de verificação de lançamento entre sistemas operacionais para cada sistema operacional e suíte - Artefatos de paridade de QA, Matrix e Telegram ## Arquivos de workflow diff --git a/docs/pt-BR/reference/test.md b/docs/pt-BR/reference/test.md index 8c1479ce8..2d7d1fe3d 100644 --- a/docs/pt-BR/reference/test.md +++ b/docs/pt-BR/reference/test.md @@ -1,63 +1,63 @@ --- read_when: - - Executar ou corrigir testes + - Executando ou corrigindo testes summary: Como executar testes localmente (vitest) e quando usar os modos force/coverage title: Testes x-i18n: - generated_at: "2026-05-02T21:04:13Z" + generated_at: "2026-05-05T01:49:14Z" model: gpt-5.5 provider: openai - source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f + source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605 source_path: reference/test.md workflow: 16 --- - Kit completo de testes (suítes, ao vivo, Docker): [Testes](/pt-BR/help/testing) -- Validação de atualizações e pacote de plugin: [Testes de atualizações e plugins](/pt-BR/help/testing-updates-plugins) +- Validação de atualizações e pacotes de Plugin: [Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins) -- `pnpm test:force`: Encerra qualquer processo Gateway remanescente que esteja ocupando a porta de controle padrão e, em seguida, executa a suíte Vitest completa com uma porta Gateway isolada para que os testes de servidor não entrem em conflito com uma instância em execução. Use isto quando uma execução anterior do Gateway deixou a porta 18789 ocupada. -- `pnpm test:coverage`: Executa a suíte unitária com cobertura V8 (via `vitest.unit.config.ts`). Este é um gate de cobertura unitária de arquivos carregados, não uma cobertura de todos os arquivos do repositório inteiro. Os limites são 70% para linhas/funções/instruções e 55% para branches. Como `coverage.all` é falso, o gate mede os arquivos carregados pela suíte de cobertura unitária em vez de tratar cada arquivo-fonte de lane dividida como descoberto. -- `pnpm test:coverage:changed`: Executa cobertura unitária apenas para arquivos alterados desde `origin/main`. -- `pnpm test:changed`: execução barata e inteligente de testes alterados. Ela executa alvos precisos de edições diretas em testes, arquivos `*.test.ts` irmãos, mapeamentos explícitos de código-fonte e o grafo de importação local. Alterações amplas de configuração/pacote são ignoradas, a menos que sejam mapeadas para testes precisos. -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: execução ampla explícita de testes alterados. Use quando uma edição de harness/configuração/pacote de teste deve recorrer ao comportamento mais amplo de testes alterados do Vitest. +- `pnpm test:force`: Encerra qualquer processo Gateway remanescente que esteja ocupando a porta de controle padrão e, em seguida, executa a suíte Vitest completa com uma porta de Gateway isolada para que os testes de servidor não colidam com uma instância em execução. Use isto quando uma execução anterior do Gateway deixou a porta 18789 ocupada. +- `pnpm test:coverage`: Executa a suíte de unidade com cobertura V8 (via `vitest.unit.config.ts`). Este é um gate de cobertura de unidade por arquivos carregados, não cobertura de todos os arquivos do repositório inteiro. Os limites são 70% para linhas/funções/instruções e 55% para branches. Como `coverage.all` é false, o gate mede os arquivos carregados pela suíte de cobertura de unidade em vez de tratar cada arquivo-fonte de lane dividida como não coberto. +- `pnpm test:coverage:changed`: Executa cobertura de unidade apenas para arquivos alterados desde `origin/main`. +- `pnpm test:changed`: execução barata de testes alterados inteligentes. Ela executa alvos precisos a partir de edições diretas de teste, arquivos irmãos `*.test.ts`, mapeamentos explícitos de código-fonte e o grafo de imports local. Alterações amplas de configuração/pacote são ignoradas, a menos que mapeiem para testes precisos. +- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: execução explícita ampla de testes alterados. Use quando uma edição de harness/configuração/pacote de teste deve recorrer ao comportamento mais amplo de testes alterados do Vitest. - `pnpm changed:lanes`: mostra as lanes arquiteturais acionadas pelo diff contra `origin/main`. -- `pnpm check:changed`: executa o gate inteligente de verificação de alterações para o diff contra `origin/main`. Ele executa typecheck, lint e comandos de guarda para as lanes arquiteturais afetadas, mas não executa testes Vitest. Use `pnpm test:changed` ou `pnpm test ` explícito para comprovação de testes. -- `pnpm test`: roteia alvos explícitos de arquivo/diretório por lanes Vitest com escopo. Execuções sem alvo usam grupos de shards fixos e se expandem para configurações folha para execução paralela local; o grupo de extensões sempre se expande para as configurações de shard por extensão em vez de um processo gigante de projeto raiz. -- Execuções do wrapper de teste terminam com um resumo curto `[test] passed|failed|skipped ... in ...`. A própria linha de duração do Vitest continua sendo o detalhe por shard. -- Estado de teste compartilhado do OpenClaw: use `src/test-utils/openclaw-test-state.ts` a partir do Vitest quando um teste precisar de `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture de configuração, workspace, diretório de agente ou armazenamento de perfis de autenticação isolados. -- Helpers de E2E de processo: use `test/helpers/openclaw-test-instance.ts` quando um teste E2E em nível de processo do Vitest precisar de um Gateway em execução, ambiente de CLI, captura de logs e limpeza em um só lugar. -- Helpers de E2E Docker/Bash: lanes que usam `scripts/lib/docker-e2e-image.sh` como fonte podem passar `docker_e2e_test_state_shell_b64 - Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT de streaming do Voice Call, - voz em tempo real de backend e embeddings de memória. + Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT de streaming para Voice Call, voz em tempo real de backend + e embeddings de memória. - Superfícies de chat/roteamento de modelo, geração/edição de imagens, texto para vídeo, - TTS em lote, STT em lote, compreensão de mídia de imagem e embeddings de memória. + Roteamento de chat/modelo, geração/edição de imagens, texto para vídeo, TTS em lote, + STT em lote, compreensão de mídia de imagem e superfícies de embeddings de memória. Modelos nativos da DeepInfra de rerank/classificação/detecção de objetos não são registrados até que o OpenClaw tenha contratos de provedor dedicados para essas categorias. - Imagem, vídeo, pesquisa, execução de código, TTS em lote, STT em lote e STT de streaming do Voice - Call. Voz em tempo real da xAI é uma capacidade upstream, mas não é registrada no OpenClaw até - que o contrato compartilhado de voz em tempo real possa representá-la. + Imagem, vídeo, busca, execução de código, TTS em lote, STT em lote e STT de streaming para Voice + Call. A voz em tempo real da xAI é um recurso upstream, mas não é + registrada no OpenClaw até que o contrato compartilhado de voz em tempo real consiga + representá-la. -## Relacionado +## Relacionados - [Geração de imagens](/pt-BR/tools/image-generation) -- [Geração de vídeos](/pt-BR/tools/video-generation) +- [Geração de vídeo](/pt-BR/tools/video-generation) - [Geração de música](/pt-BR/tools/music-generation) - [Texto para fala](/pt-BR/tools/tts) - [Compreensão de mídia](/pt-BR/nodes/media-understanding) diff --git a/docs/pt-BR/tools/music-generation.md b/docs/pt-BR/tools/music-generation.md index 32cb0bbde..79a6433d3 100644 --- a/docs/pt-BR/tools/music-generation.md +++ b/docs/pt-BR/tools/music-generation.md @@ -4,43 +4,44 @@ read_when: - Configuração de provedores e modelos de geração de música - Entendendo os parâmetros da ferramenta music_generate sidebarTitle: Music generation -summary: Gere música por meio de music_generate em fluxos de trabalho do Google Lyria, MiniMax e ComfyUI +summary: Gere música com music_generate em fluxos de trabalho do Google Lyria, MiniMax e ComfyUI title: Geração de música x-i18n: - generated_at: "2026-05-02T21:06:00Z" + generated_at: "2026-05-05T01:50:41Z" model: gpt-5.5 provider: openai - source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26 + source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650 source_path: tools/music-generation.md workflow: 16 --- A ferramenta `music_generate` permite que o agente crie música ou áudio por meio da capacidade compartilhada de geração de música com provedores configurados — Google, -MiniMax e ComfyUI configurado por workflow atualmente. +MiniMax e ComfyUI configurado por fluxo de trabalho atualmente. -Para execuções de agente com suporte de sessão, o OpenClaw inicia a geração de música como uma -tarefa em segundo plano, a rastreia no livro-razão de tarefas e depois desperta o agente novamente -quando a faixa está pronta, para que o agente possa publicar o áudio finalizado de volta no -canal original. +Para execuções de agente com sessão, o OpenClaw inicia a geração de música como uma +tarefa em segundo plano, rastreia-a no registro de tarefas e então desperta o agente novamente +quando a faixa estiver pronta, para que o agente possa avisar o usuário e anexar o +áudio finalizado. Em chats de grupo/canal que usam entrega visível apenas por ferramenta +de mensagem, o agente retransmite o resultado pela ferramenta de mensagem. A ferramenta compartilhada integrada só aparece quando pelo menos um provedor de geração de música está disponível. Se você não vir `music_generate` nas ferramentas do seu agente, -configure `agents.defaults.musicGenerationModel` ou configure uma chave de API de -provedor. +configure `agents.defaults.musicGenerationModel` ou configure uma +chave de API de provedor. ## Início rápido - + - + Defina uma chave de API para pelo menos um provedor — por exemplo `GEMINI_API_KEY` ou `MINIMAX_API_KEY`. - + ```json5 { agents: { @@ -53,30 +54,30 @@ provedor. } ``` - - _"Generate an upbeat synthpop track about a night drive through a - neon city."_ + + _"Gere uma faixa synthpop animada sobre um passeio noturno de carro por uma + cidade neon."_ - O agente chama `music_generate` automaticamente. Nenhuma lista de - permissão de ferramentas é necessária. + O agente chama `music_generate` automaticamente. Não é necessário + colocar a ferramenta em uma lista de permissões. - Para contextos síncronos diretos sem uma execução de agente com suporte de sessão, + Para contextos síncronos diretos sem uma execução de agente com sessão, a ferramenta integrada ainda recorre à geração inline e retorna - o caminho da mídia final no resultado da ferramenta. + o caminho final da mídia no resultado da ferramenta. - + - - Configure `plugins.entries.comfy.config.music` com um workflow + + Configure `plugins.entries.comfy.config.music` com um fluxo de trabalho JSON e nós de prompt/saída. - - Para o Comfy Cloud, defina `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`. + + Para Comfy Cloud, defina `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`. - + ```text /tool music_generate prompt="Warm ambient synth loop with soft tape texture" ``` @@ -97,18 +98,18 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## Provedores compatíveis -| Provedor | Modelo padrão | Entradas de referência | Controles compatíveis | Autenticação | -| -------- | ---------------------- | ---------------------- | -------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | Até 1 imagem | Música ou áudio definido pelo workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | -| Google | `lyria-3-clip-preview` | Até 10 imagens | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.6` | Nenhuma | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` ou OAuth do MiniMax | +| Provedor | Modelo padrão | Entradas de referência | Controles compatíveis | Autenticação | +| -------- | ---------------------- | ---------------------- | ---------------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | Até 1 imagem | Música ou áudio definido pelo fluxo de trabalho | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| Google | `lyria-3-clip-preview` | Até 10 imagens | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `music-2.6` | Nenhuma | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` ou OAuth do MiniMax | ### Matriz de capacidades -O contrato de modo explícito usado por `music_generate`, testes de contrato e pela -varredura ao vivo compartilhada: +O contrato de modo explícito usado por `music_generate`, testes de contrato e a +varredura live compartilhada: -| Provedor | `generate` | `edit` | Limite de edição | Faixas ao vivo compartilhadas | +| Provedor | `generate` | `edit` | Limite de edição | Lanes live compartilhadas | | -------- | :--------: | :----: | ---------------- | --------------------------------------------------------------------------- | | ComfyUI | ✓ | ✓ | 1 imagem | Não está na varredura compartilhada; coberto por `extensions/comfy/comfy.live.test.ts` | | Google | ✓ | ✓ | 10 imagens | `generate`, `edit` | @@ -121,7 +122,7 @@ tempo de execução: /tool music_generate action=list ``` -Use `action: "status"` para inspecionar a tarefa de música ativa com suporte de sessão: +Use `action: "status"` para inspecionar a tarefa de música ativa com sessão: ```text /tool music_generate action=status @@ -146,10 +147,10 @@ Exemplo de geração direta: `comfy/workflow`). - Letras opcionais quando o provedor dá suporte a entrada explícita de letra. + Letras opcionais quando o provedor oferece suporte a entrada explícita de letras. - Solicita saída apenas instrumental quando o provedor dá suporte a isso. + Solicita saída apenas instrumental quando o provedor oferece suporte. Caminho ou URL de uma única imagem de referência. @@ -158,53 +159,53 @@ Exemplo de geração direta: Várias imagens de referência (até 10 em provedores compatíveis). - Duração-alvo em segundos quando o provedor dá suporte a dicas de duração. + Duração-alvo em segundos quando o provedor oferece suporte a dicas de duração. - Dica de formato de saída quando o provedor dá suporte a isso. + Dica de formato de saída quando o provedor oferece suporte. Dica de nome de arquivo de saída. -Tempo limite opcional de solicitação ao provedor em milissegundos. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta. +Timeout opcional da requisição ao provedor em milissegundos. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta. -Nem todos os provedores dão suporte a todos os parâmetros. O OpenClaw ainda valida limites -rígidos, como contagens de entrada, antes do envio. Quando um provedor dá suporte a +Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw ainda valida limites +rígidos, como contagens de entrada, antes do envio. Quando um provedor oferece suporte a duração, mas usa um máximo menor que o valor solicitado, o OpenClaw -limita à duração compatível mais próxima. Dicas opcionais realmente incompatíveis -são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue honrá-las. +limita para a duração compatível mais próxima. Dicas opcionais realmente sem suporte +são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue atendê-las. Os resultados da ferramenta informam as configurações aplicadas; `details.normalization` captura qualquer mapeamento de solicitado para aplicado. ## Comportamento assíncrono -A geração de música com suporte de sessão é executada como uma tarefa em segundo plano: +A geração de música com sessão é executada como uma tarefa em segundo plano: - **Tarefa em segundo plano:** `music_generate` cria uma tarefa em segundo plano, retorna uma - resposta de iniciada/tarefa imediatamente e publica a faixa finalizada depois em + resposta iniciada/de tarefa imediatamente e publica a faixa finalizada depois em uma mensagem de acompanhamento do agente. - **Prevenção de duplicatas:** enquanto uma tarefa está `queued` ou `running`, chamadas posteriores de `music_generate` na mesma sessão retornam o status da tarefa em vez de iniciar outra geração. Use `action: "status"` para verificar explicitamente. - **Consulta de status:** `openclaw tasks list` ou `openclaw tasks show ` - inspeciona status em fila, em execução e terminal. -- **Despertar na conclusão:** o OpenClaw injeta um evento interno de conclusão de volta - na mesma sessão para que o modelo possa escrever por conta própria o acompanhamento + inspeciona status em fila, em execução e terminais. +- **Despertar de conclusão:** o OpenClaw injeta um evento interno de conclusão de volta + na mesma sessão para que o modelo possa escrever ele mesmo o acompanhamento voltado ao usuário. - **Dica de prompt:** turnos posteriores de usuário/manuais na mesma sessão recebem uma pequena dica de runtime quando uma tarefa de música já está em andamento, para que o modelo - não chame `music_generate` novamente às cegas. + não chame `music_generate` novamente sem critério. - **Fallback sem sessão:** contextos diretos/locais sem uma sessão real de agente executam inline e retornam o resultado final de áudio no mesmo turno. ### Ciclo de vida da tarefa -| Estado | Significado | -| ----------- | ---------------------------------------------------------------------------------------------- | -| `queued` | Tarefa criada, aguardando o provedor aceitá-la. | -| `running` | O provedor está processando (normalmente 30 segundos a 3 minutos, dependendo do provedor e da duração). | -| `succeeded` | Faixa pronta; o agente desperta e a publica na conversa. | -| `failed` | Erro ou tempo limite do provedor; o agente desperta com detalhes do erro. | +| Estado | Significado | +| ----------- | ----------------------------------------------------------------------------------------------- | +| `queued` | Tarefa criada, aguardando o provedor aceitá-la. | +| `running` | O provedor está processando (normalmente de 30 segundos a 3 minutos, dependendo do provedor e da duração). | +| `succeeded` | Faixa pronta; o agente desperta e a publica na conversa. | +| `failed` | Erro ou timeout do provedor; o agente desperta com detalhes do erro. | Verifique o status pela CLI: @@ -238,9 +239,9 @@ O OpenClaw tenta provedores nesta ordem: 1. Parâmetro `model` da chamada da ferramenta (se o agente especificar um). 2. `musicGenerationModel.primary` da configuração. 3. `musicGenerationModel.fallbacks` em ordem. -4. Detecção automática usando apenas padrões de provedor com autenticação: +4. Detecção automática usando apenas padrões de provedores com autenticação: - provedor padrão atual primeiro; - - provedores restantes de geração de música registrados em ordem de ID de provedor. + - demais provedores registrados de geração de música em ordem de id de provedor. Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos falharem, o erro inclui detalhes de cada tentativa. @@ -252,40 +253,40 @@ entradas explícitas de `model`, `primary` e `fallbacks`. - Orientado por workflow e depende do grafo configurado mais o mapeamento de nós - para campos de prompt/saída. O plugin `comfy` incluído se conecta à + Orientado por fluxo de trabalho e depende do grafo configurado mais o mapeamento de nós + para campos de prompt/saída. O Plugin `comfy` integrado se conecta à ferramenta compartilhada `music_generate` por meio do registro de provedores de geração de música. - Usa geração em lote do Lyria 3. O fluxo incluído atual oferece suporte a + Usa geração em lote do Lyria 3. O fluxo integrado atual oferece suporte a prompt, texto opcional de letras e imagens de referência opcionais. Usa o endpoint em lote `music_generation`. Oferece suporte a prompt, letras - opcionais, modo instrumental, direcionamento de duração e saída mp3 por meio - de autenticação por chave de API `minimax` ou OAuth `minimax-portal`. + opcionais, modo instrumental, direcionamento de duração e saída mp3 por meio de + autenticação por chave de API `minimax` ou OAuth `minimax-portal`. ## Escolhendo o caminho certo -- **Com suporte de provedor compartilhado** quando você quer seleção de modelo, failover de - provedor e o fluxo integrado assíncrono de tarefa/status. -- **Caminho de plugin (ComfyUI)** quando você precisa de um grafo de workflow personalizado ou de um - provedor que não faz parte da capacidade musical compartilhada incluída. +- **Com provedor compartilhado** quando você quer seleção de modelo, failover de provedor + e o fluxo assíncrono integrado de tarefa/status. +- **Caminho de Plugin (ComfyUI)** quando você precisa de um grafo de fluxo de trabalho personalizado ou de um + provedor que não faz parte da capacidade compartilhada integrada de música. Se você estiver depurando comportamento específico do ComfyUI, consulte [ComfyUI](/pt-BR/providers/comfy). Se você estiver depurando comportamento de provedor -compartilhado, comece com [Google (Gemini)](/pt-BR/providers/google) ou +compartilhado, comece por [Google (Gemini)](/pt-BR/providers/google) ou [MiniMax](/pt-BR/providers/minimax). ## Modos de capacidade do provedor O contrato compartilhado de geração de música oferece suporte a declarações explícitas de modo: -- `generate` para geração apenas por prompt. -- `edit` quando a solicitação inclui uma ou mais imagens de referência. +- `generate` para geração somente por prompt. +- `edit` quando a requisição inclui uma ou mais imagens de referência. Novas implementações de provedor devem preferir blocos de modo explícitos: @@ -306,14 +307,14 @@ capabilities: { ``` Campos planos legados, como `maxInputImages`, `supportsLyrics` e -`supportsFormat`, **não** bastam para anunciar suporte a edição. Provedores -devem declarar `generate` e `edit` explicitamente para que testes ao vivo, testes de contrato -e a ferramenta compartilhada `music_generate` possam validar o suporte a modos -de forma determinística. +`supportsFormat`, **não** são suficientes para anunciar suporte a edição. Provedores +devem declarar `generate` e `edit` explicitamente para que testes live, testes de contrato +e a ferramenta compartilhada `music_generate` possam validar suporte de modo +deterministicamente. -## Testes ao vivo +## Testes live -Cobertura ao vivo opcional para os provedores compartilhados incluídos: +Cobertura live opcional para os provedores compartilhados integrados: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts @@ -325,29 +326,30 @@ Wrapper do repositório: pnpm test:live:media music ``` -Este arquivo ao vivo carrega variáveis de ambiente de provedor ausentes de `~/.profile`, prefere -chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa tanto -a cobertura de `generate` quanto a de `edit` declarado quando o provedor habilita o modo -de edição. Cobertura hoje: +Este arquivo live carrega variáveis de ambiente de provedor ausentes de `~/.profile`, prefere +chaves de API live/env antes de perfis de autenticação armazenados por padrão e executa tanto +a cobertura de `generate` quanto a de `edit` declarada quando o provedor habilita o modo +de edição. Cobertura atual: - `google`: `generate` mais `edit` - `minimax`: apenas `generate` -- `comfy`: cobertura ao vivo separada do Comfy, não a varredura compartilhada de provedores +- `comfy`: cobertura live separada do Comfy, não a varredura de provedores compartilhados -Cobertura ao vivo opcional para o caminho de música ComfyUI incluído: +Cobertura live opcional para o caminho de música ComfyUI integrado: ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -O arquivo live do Comfy também cobre fluxos de trabalho de imagem e vídeo do Comfy quando essas seções estão configuradas. +O arquivo live do Comfy também cobre fluxos de trabalho de imagem e vídeo do Comfy quando essas +seções estão configuradas. -## Relacionados +## Relacionado -- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para execuções destacadas de `music_generate` +- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para execuções `music_generate` desanexadas - [ComfyUI](/pt-BR/providers/comfy) - [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — configuração `musicGenerationModel` - [Google (Gemini)](/pt-BR/providers/google) - [MiniMax](/pt-BR/providers/minimax) -- [Modelos](/pt-BR/concepts/models) — configuração de modelos e tolerância a falhas +- [Modelos](/pt-BR/concepts/models) — configuração de modelos e alternância em caso de falha - [Visão geral das ferramentas](/pt-BR/tools) diff --git a/docs/pt-BR/tools/plugin.md b/docs/pt-BR/tools/plugin.md index 954c52abb..ffec2e9da 100644 --- a/docs/pt-BR/tools/plugin.md +++ b/docs/pt-BR/tools/plugin.md @@ -1,31 +1,31 @@ --- read_when: - Instalando ou configurando plugins - - Entendendo a descoberta de Plugins e as regras de carregamento + - Entendendo as regras de descoberta e carregamento de Plugin - Trabalhando com pacotes de Plugin compatíveis com Codex/Claude sidebarTitle: Install and Configure -summary: Instale, configure e gerencie os plugins do OpenClaw +summary: Instale, configure e gerencie plugins do OpenClaw title: Plugins x-i18n: - generated_at: "2026-05-03T21:39:20Z" + generated_at: "2026-05-05T01:50:56Z" model: gpt-5.5 provider: openai - source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0 + source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004 source_path: tools/plugin.md workflow: 16 --- -Plugins estendem o OpenClaw com novos recursos: canais, provedores de modelo, +Plugins estendem o OpenClaw com novas capacidades: canais, provedores de modelo, arneses de agente, ferramentas, Skills, fala, transcrição em tempo real, voz em -tempo real, compreensão de mídia, geração de imagem, geração de vídeo, busca na -web, pesquisa na web e muito mais. Alguns plugins são **core** (incluídos no OpenClaw), outros +tempo real, compreensão de mídia, geração de imagens, geração de vídeo, busca na web, +pesquisa na web e muito mais. Alguns plugins são **core** (incluídos com o OpenClaw), outros são **externos**. A maioria dos plugins externos é publicada e descoberta por meio do -[ClawHub](/pt-BR/tools/clawhub). O npm continua com suporte para instalações diretas e para um +[ClawHub](/pt-BR/tools/clawhub). O npm continua compatível para instalações diretas e para um conjunto temporário de pacotes de plugin pertencentes ao OpenClaw enquanto essa migração é concluída. ## Início rápido -Para exemplos de instalação, listagem, desinstalação, atualização e publicação para copiar e colar, consulte +Para exemplos de copiar e colar de instalação, listagem, desinstalação, atualização e publicação, consulte [Gerenciar plugins](/pt-BR/plugins/manage-plugins). @@ -61,15 +61,15 @@ Para exemplos de instalação, listagem, desinstalação, atualização e public openclaw gateway restart ``` - Em seguida, configure em `plugins.entries.\.config` no seu arquivo de configuração. + Depois configure em `plugins.entries.\.config` no seu arquivo de configuração. - Em um Gateway em execução, `/plugins enable` e `/plugins disable`, exclusivos do proprietário, + Em um Gateway em execução, `/plugins enable` e `/plugins disable` exclusivos do proprietário acionam o recarregador de configuração do Gateway. O Gateway recarrega as superfícies de runtime - do plugin no processo, e novas rodadas de agente reconstroem sua lista de ferramentas a partir do - registro atualizado. `/plugins install` altera o código-fonte do plugin, portanto o + do plugin no processo, e novas rodadas do agente reconstroem sua lista de ferramentas a partir do + registro atualizado. `/plugins install` altera o código-fonte do plugin, então o Gateway solicita uma reinicialização em vez de fingir que o processo atual pode recarregar com segurança módulos já importados. @@ -84,8 +84,8 @@ Para exemplos de instalação, listagem, desinstalação, atualização e public ``` Use `--runtime` quando precisar comprovar ferramentas registradas, serviços, métodos de gateway, - hooks ou comandos de CLI pertencentes ao plugin. `inspect` simples é uma verificação fria - de manifesto/registro e evita intencionalmente importar o runtime do plugin. + hooks ou comandos de CLI pertencentes ao plugin. O `inspect` simples é uma verificação fria de + manifesto/registro e evita intencionalmente importar o runtime do plugin. @@ -98,85 +98,85 @@ Se você preferir controle nativo do chat, habilite `commands.plugins: true` e u /plugin enable ``` -O caminho de instalação usa o mesmo resolvedor da CLI: caminho/arquivo local, `clawhub:` -explícito, `npm:` explícito, `git:` explícito ou especificação de pacote simples -por meio do npm. +O caminho de instalação usa o mesmo resolvedor que a CLI: caminho/arquivo local, `clawhub:` explícito, +`npm:` explícito, `git:` explícito ou especificação de pacote simples +via npm. -Se a configuração for inválida, a instalação normalmente falha fechada e direciona você para +Se a configuração for inválida, a instalação normalmente falha em modo fechado e direciona você para `openclaw doctor --fix`. A única exceção de recuperação é um caminho estreito de reinstalação de plugin incluído para plugins que optam por `openclaw.install.allowInvalidConfigRecovery`. -Durante a inicialização do Gateway, configuração de plugin inválida falha fechada como qualquer outra configuração inválida. -Execute `openclaw doctor --fix` para colocar em quarentena a configuração incorreta do plugin, -desabilitando essa entrada de plugin e removendo sua carga de configuração inválida; o backup -normal da configuração mantém os valores anteriores. -Quando uma configuração de canal referencia um plugin que não é mais descobrível, mas o -mesmo id de plugin obsoleto permanece na configuração do plugin ou nos registros de instalação, a inicialização do Gateway +Durante a inicialização do Gateway, configuração inválida de plugin falha em modo fechado como qualquer outra configuração inválida. +Execute `openclaw doctor --fix` para colocar em quarentena a configuração incorreta do plugin +desabilitando essa entrada de plugin e removendo sua carga de configuração inválida; o backup normal +da configuração mantém os valores anteriores. +Quando uma configuração de canal referencia um plugin que não é mais detectável, mas o +mesmo id de plugin obsoleto permanece na configuração de plugin ou nos registros de instalação, a inicialização do Gateway registra avisos e ignora esse canal em vez de bloquear todos os outros canais. Execute `openclaw doctor --fix` para remover as entradas obsoletas de canal/plugin; chaves de canal desconhecidas sem evidência de plugin obsoleto ainda falham na validação para que erros de digitação permaneçam visíveis. -Se `plugins.enabled: false` estiver definido, referências obsoletas a plugins serão tratadas como inertes: -a inicialização do Gateway ignora o trabalho de descoberta/carregamento de plugins e `openclaw doctor` preserva -a configuração desabilitada do plugin em vez de removê-la automaticamente. Reabilite plugins antes de -executar a limpeza do doctor se quiser que ids de plugin obsoletos sejam removidos. +Se `plugins.enabled: false` estiver definido, referências obsoletas de plugin serão tratadas como inertes: +a inicialização do Gateway ignora o trabalho de descoberta/carregamento de plugin e `openclaw doctor` preserva +a configuração de plugin desabilitada em vez de removê-la automaticamente. Reabilite plugins antes de +executar a limpeza do doctor se quiser remover ids de plugin obsoletos. -A instalação de dependências de plugin acontece somente durante fluxos explícitos de instalação/atualização ou -reparo do doctor. A inicialização do Gateway, o recarregamento de configuração e a inspeção de runtime -não executam gerenciadores de pacotes nem reparam árvores de dependências. Plugins locais já devem +A instalação de dependências de plugin acontece apenas durante fluxos explícitos de instalação/atualização ou +reparo do doctor. Inicialização do Gateway, recarregamento de configuração e inspeção de runtime não +executam gerenciadores de pacote nem reparam árvores de dependências. Plugins locais já devem ter suas dependências instaladas, enquanto plugins npm, git e ClawHub são -instalados nas raízes de plugins gerenciadas pelo OpenClaw. Dependências npm podem ser içadas -dentro da raiz npm gerenciada do OpenClaw; instalação/atualização verifica essa raiz gerenciada antes da -confiança, e a desinstalação remove pacotes gerenciados por npm por meio do npm. Plugins externos +instalados nas raízes de plugin gerenciadas pelo OpenClaw. Dependências npm podem ser içadas +dentro da raiz npm gerenciada pelo OpenClaw; install/update verifica essa raiz gerenciada antes +da confiança, e uninstall remove pacotes gerenciados por npm por meio do npm. Plugins externos e caminhos de carregamento personalizados ainda devem ser instalados por meio de `openclaw plugins install`. Use `openclaw plugins list --json` para ver o `dependencyStatus` estático de cada plugin visível sem importar código de runtime nem reparar dependências. Consulte [Resolução de dependências de Plugin](/pt-BR/plugins/dependency-resolution) para o -ciclo de vida em tempo de instalação. +ciclo de vida no momento da instalação. Para instalações npm, seletores mutáveis como `latest` ou uma dist-tag são resolvidos antes da instalação e então fixados na versão exata verificada na raiz npm -gerenciada do OpenClaw. Depois que o npm termina, o OpenClaw verifica se a entrada -`package-lock.json` instalada ainda corresponde à versão e à integridade resolvidas. Se -o npm gravar metadados de pacote diferentes, a instalação falhará e o pacote gerenciado -será revertido em vez de aceitar um artefato de plugin diferente. +gerenciada pelo OpenClaw. Depois que o npm termina, o OpenClaw verifica se a entrada instalada de +`package-lock.json` ainda corresponde à versão resolvida e à integridade. Se +o npm gravar metadados de pacote diferentes, a instalação falha e o pacote gerenciado +é revertido em vez de aceitar um artefato de plugin diferente. -Checkouts de código-fonte são workspaces pnpm. Se você clonar o OpenClaw para trabalhar em plugins incluídos, -execute `pnpm install`; então o OpenClaw carrega plugins incluídos de -`extensions/` para que edições e dependências locais do pacote sejam usadas diretamente. -Instalações simples na raiz via npm são para o OpenClaw empacotado, não para desenvolvimento -em checkout de código-fonte. +Checkouts de código-fonte são workspaces pnpm. Se você clonar o OpenClaw para trabalhar em plugins +incluídos, execute `pnpm install`; então o OpenClaw carrega plugins incluídos a partir de +`extensions/` para que edições e dependências locais ao pacote sejam usadas diretamente. +Instalações npm simples na raiz são para OpenClaw empacotado, não para desenvolvimento em checkout +de código-fonte. ## Tipos de Plugin O OpenClaw reconhece dois formatos de plugin: -| Formato | Como funciona | Exemplos | +| Formato | Como funciona | Exemplos | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade | +| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade | | **Pacote** | Layout compatível com Codex/Claude/Cursor; mapeado para recursos do OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Ambos aparecem em `openclaw plugins list`. Consulte [Pacotes de Plugin](/pt-BR/plugins/bundles) para detalhes sobre pacotes. +Ambos aparecem em `openclaw plugins list`. Consulte [Pacotes de Plugin](/pt-BR/plugins/bundles) para detalhes de pacote. -Se você estiver escrevendo um plugin nativo, comece com [Criar Plugins](/pt-BR/plugins/building-plugins) +Se você está escrevendo um plugin nativo, comece com [Criação de Plugins](/pt-BR/plugins/building-plugins) e a [Visão geral do SDK de Plugin](/pt-BR/plugins/sdk-overview). ## Pontos de entrada de pacote Pacotes npm de plugin nativo devem declarar `openclaw.extensions` em `package.json`. Cada entrada deve permanecer dentro do diretório do pacote e resolver para um arquivo de -runtime legível, ou para um arquivo-fonte TypeScript com um par JavaScript compilado inferido, +runtime legível, ou para um arquivo de origem TypeScript com um par JavaScript compilado inferido, como `src/index.ts` para `dist/index.js`. -Instalações empacotadas devem incluir essa saída de runtime JavaScript. O fallback de -código-fonte TypeScript é para checkouts de código-fonte e caminhos de desenvolvimento local, não para -pacotes npm instalados na raiz de plugins gerenciada do OpenClaw. +Instalações empacotadas devem incluir essa saída JavaScript de runtime. O fallback de +origem TypeScript é para checkouts de código-fonte e caminhos de desenvolvimento local, não para +pacotes npm instalados na raiz de plugin gerenciada pelo OpenClaw. -Use `openclaw.runtimeExtensions` quando os arquivos de runtime publicados não estiverem nos -mesmos caminhos das entradas de código-fonte. Quando presente, `runtimeExtensions` deve conter +Use `openclaw.runtimeExtensions` quando arquivos de runtime publicados não estiverem nos +mesmos caminhos das entradas de origem. Quando presente, `runtimeExtensions` deve conter exatamente uma entrada para cada entrada de `extensions`. Listas incompatíveis fazem a instalação e -a descoberta de plugins falharem em vez de voltar silenciosamente para caminhos de código-fonte. Se você também -publicar `openclaw.setupEntry`, use `openclaw.runtimeSetupEntry` para seu par -JavaScript compilado; esse arquivo é obrigatório quando declarado. +a descoberta de plugin falharem em vez de recorrer silenciosamente aos caminhos de origem. Se você também +publicar `openclaw.setupEntry`, use `openclaw.runtimeSetupEntry` para seu par JavaScript +compilado; esse arquivo é obrigatório quando declarado. ```json { @@ -192,17 +192,17 @@ JavaScript compilado; esse arquivo é obrigatório quando declarado. ### Pacotes npm pertencentes ao OpenClaw durante a migração -ClawHub é o caminho principal de distribuição para a maioria dos plugins. Versões empacotadas atuais -do OpenClaw já incluem muitos plugins oficiais, portanto eles não precisam de +ClawHub é o caminho principal de distribuição para a maioria dos plugins. As versões empacotadas +atuais do OpenClaw já incluem muitos plugins oficiais, então eles não precisam de instalações npm separadas em configurações normais. Até que todos os plugins pertencentes ao OpenClaw -tenham migrado para o ClawHub, o OpenClaw ainda distribui alguns pacotes de plugin `@openclaw/*` no +tenham migrado para o ClawHub, o OpenClaw ainda publica alguns pacotes de plugin `@openclaw/*` no npm para instalações mais antigas/personalizadas e fluxos de trabalho npm diretos. -Se o npm relatar um pacote de plugin `@openclaw/*` como descontinuado, essa versão do pacote -vem de uma linha mais antiga de pacotes externos. Use o plugin incluído do +Se o npm relatar um pacote de plugin `@openclaw/*` como obsoleto, essa versão do pacote +vem de uma linha antiga de pacotes externos. Use o plugin incluído do OpenClaw atual ou um checkout local até que um pacote npm mais novo seja publicado. -| Plugin | Pacote | Documentação | +| Plugin | Pacote | Documentação | | --------------- | -------------------------- | ------------------------------------------ | | BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/pt-BR/channels/bluebubbles) | | Discord | `@openclaw/discord` | [Discord](/pt-BR/channels/discord) | @@ -218,7 +218,7 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public | Zalo | `@openclaw/zalo` | [Zalo](/pt-BR/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/pt-BR/plugins/zalouser) | -### Core (incluído no OpenClaw) +### Core (incluídos com o OpenClaw) @@ -230,11 +230,11 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public - - `memory-core` — busca de memória incluída (padrão via `plugins.slots.memory`) - - `memory-lancedb` — memória de longo prazo baseada em LanceDB com recuperação/captura automática (defina `plugins.slots.memory = "memory-lancedb"`) + - `memory-core` — pesquisa de memória incluída (padrão via `plugins.slots.memory`) + - `memory-lancedb` — memória de longo prazo baseada em LanceDB com rechamada/captura automática (defina `plugins.slots.memory = "memory-lancedb"`) Consulte [Memory LanceDB](/pt-BR/plugins/memory-lancedb) para configuração de - embeddings compatíveis com OpenAI, exemplos do Ollama, limites de recuperação e solução de problemas. + embeddings compatível com OpenAI, exemplos de Ollama, limites de rechamada e solução de problemas. @@ -243,7 +243,7 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public - - `browser` — plugin de navegador incluído para a ferramenta de navegador, CLI `openclaw browser`, método de gateway `browser.request`, runtime de navegador e serviço padrão de controle de navegador (habilitado por padrão; desabilite antes de substituí-lo) + - `browser` — plugin de navegador incluído para a ferramenta de navegador, CLI `openclaw browser`, método de gateway `browser.request`, runtime de navegador e serviço padrão de controle do navegador (habilitado por padrão; desabilite antes de substituí-lo) - `copilot-proxy` — ponte do VS Code Copilot Proxy (desabilitada por padrão) @@ -267,39 +267,47 @@ Procurando plugins de terceiros? Consulte [Plugins da comunidade](/pt-BR/plugins } ``` -| Campo | Descrição | -| ---------------- | --------------------------------------------------------- | -| `enabled` | Alternância principal (padrão: `true`) | -| `allow` | Lista de permissões de Plugin (opcional) | -| `deny` | Lista de bloqueio de Plugin (opcional; bloqueio vence) | -| `load.paths` | Arquivos/diretórios extras de plugin | -| `slots` | Seletores de slot exclusivos (por exemplo, `memory`, `contextEngine`) | -| `entries.\` | Alternâncias + configuração por plugin | +| Campo | Descrição | +| ------------------ | --------------------------------------------------------- | +| `enabled` | Alternância principal (padrão: `true`) | +| `allow` | Allowlist de plugins (opcional) | +| `bundledDiscovery` | Modo de descoberta de plugins empacotados (`allowlist` por padrão) | +| `deny` | Denylist de plugins (opcional; deny vence) | +| `load.paths` | Arquivos/diretórios extras de plugins | +| `slots` | Seletores de slots exclusivos (ex.: `memory`, `contextEngine`) | +| `entries.\` | Alternâncias + configuração por plugin | `plugins.allow` é exclusivo. Quando não está vazio, somente os plugins listados podem carregar -ou expor ferramentas, mesmo que `tools.allow` contenha `"*"` ou um nome específico de ferramenta -pertencente a um plugin. Se uma lista de permissões de ferramentas referenciar ferramentas de plugin, adicione os ids dos plugins proprietários -a `plugins.allow` ou remova `plugins.allow`; `openclaw doctor` alerta sobre esse +ou expor ferramentas, mesmo que `tools.allow` contenha `"*"` ou o nome específico +de uma ferramenta pertencente a um plugin. Se uma allowlist de ferramentas referenciar ferramentas de plugin, adicione os ids dos plugins proprietários +a `plugins.allow` ou remova `plugins.allow`; `openclaw doctor` avisa sobre esse formato. -Alterações de configuração feitas por meio de `/plugins enable` ou `/plugins disable` acionam um -recarregamento de plugin do Gateway no processo. Novos turnos de agente reconstroem sua lista de ferramentas a partir -do registro de plugins atualizado. Operações que alteram a origem, como instalar, -atualizar e desinstalar, ainda reiniciam o processo do Gateway porque módulos de plugin já importados -não podem ser substituídos com segurança no local. +`plugins.bundledDiscovery` usa `"allowlist"` como padrão para novas configurações, então um +inventário restritivo em `plugins.allow` também bloqueia plugins provedores empacotados +omitidos, incluindo a descoberta em runtime de provedores de pesquisa na web. O Doctor marca configurações antigas +de allowlist restritiva com `"compat"` durante a migração para que upgrades mantenham +o comportamento legado de provedores empacotados até que o operador opte pelo modo mais rigoroso. +Um `plugins.allow` vazio ainda é tratado como não definido/aberto. + +Alterações de configuração feitas por `/plugins enable` ou `/plugins disable` acionam um +recarregamento de plugins do Gateway dentro do processo. Novos turnos de agente recompõem sua lista de ferramentas a partir +do registro de plugins atualizado. Operações que alteram a fonte, como instalar, +atualizar e desinstalar, ainda reiniciam o processo do Gateway porque módulos de +plugin já importados não podem ser substituídos com segurança no lugar. `openclaw plugins list` é um snapshot local do registro/configuração de plugins. Um plugin `enabled` ali significa que o registro persistido e a configuração atual permitem que o -plugin participe. Isso não prova que um Gateway remoto já em execução -tenha recarregado ou reiniciado com o mesmo código de plugin. Em configurações de VPS/contêiner -com processos wrapper, envie reinicializações ou escritas que acionam recarregamento para o processo real +plugin participe. Isso não prova que um Gateway remoto já em execução tenha recarregado +ou reiniciado para o mesmo código de plugin. Em configurações VPS/contêiner +com processos wrapper, envie reinícios ou gravações que acionem recarregamento ao processo real `openclaw gateway run`, ou use `openclaw gateway restart` contra o -Gateway em execução quando o recarregamento relatar uma falha. +Gateway em execução quando o recarregamento reportar uma falha. - + - **Desativado**: o plugin existe, mas as regras de ativação o desligaram. A configuração é preservada. - **Ausente**: a configuração referencia um id de plugin que a descoberta não encontrou. - - **Inválido**: o plugin existe, mas sua configuração não corresponde ao esquema declarado. A inicialização do Gateway ignora somente esse plugin; `openclaw doctor --fix` pode colocar a entrada inválida em quarentena desativando-a e removendo sua carga útil de configuração. + - **Inválido**: o plugin existe, mas sua configuração não corresponde ao esquema declarado. A inicialização do Gateway ignora apenas esse plugin; `openclaw doctor --fix` pode colocar a entrada inválida em quarentena, desativando-a e removendo seu payload de configuração. @@ -308,79 +316,79 @@ Gateway em execução quando o recarregamento relatar uma falha. O OpenClaw procura plugins nesta ordem (a primeira correspondência vence): - + `plugins.load.paths` — caminhos explícitos de arquivo ou diretório. Caminhos que apontam - de volta para os próprios diretórios de plugins agrupados empacotados do OpenClaw são ignorados; + de volta para os próprios diretórios de plugins empacotados do OpenClaw são ignorados; execute `openclaw doctor --fix` para remover esses aliases obsoletos. - + `\/.openclaw//*.ts` e `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` e `~/.openclaw//*/index.ts`. - + Distribuídos com o OpenClaw. Muitos são ativados por padrão (provedores de modelo, fala). Outros exigem ativação explícita. -Instalações empacotadas e imagens Docker normalmente resolvem plugins agrupados a partir da -árvore compilada `dist/extensions`. Se um diretório de origem de plugin agrupado for -montado por bind sobre o caminho de origem empacotado correspondente, por exemplo -`/app/extensions/synology-chat`, o OpenClaw trata esse diretório de origem montado -como uma sobreposição de origem agrupada e o descobre antes do pacote -`/app/dist/extensions/synology-chat` empacotado. Isso mantém os loops de contêiner de mantenedores -funcionando sem mudar todos os plugins agrupados de volta para a origem TypeScript. +Instalações empacotadas e imagens Docker normalmente resolvem plugins empacotados a partir da +árvore compilada `dist/extensions`. Se um diretório-fonte de plugin empacotado for +montado por bind sobre o caminho-fonte empacotado correspondente, por exemplo +`/app/extensions/synology-chat`, o OpenClaw trata esse diretório-fonte montado +como uma sobreposição de fonte empacotada e o descobre antes do pacote +`/app/dist/extensions/synology-chat`. Isso mantém loops de contêiner de mantenedores +funcionando sem alternar todos os plugins empacotados de volta para código-fonte TypeScript. Defina `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` para forçar pacotes dist empacotados -mesmo quando montagens de sobreposição de origem estiverem presentes. +mesmo quando montagens de sobreposição de fonte estiverem presentes. ### Regras de ativação -- `plugins.enabled: false` desativa todos os plugins e ignora o trabalho de descoberta/carregamento de plugins -- `plugins.deny` sempre vence sobre allow +- `plugins.enabled: false` desativa todos os plugins e pula o trabalho de descoberta/carregamento de plugins +- `plugins.deny` sempre vence allow - `plugins.entries.\.enabled: false` desativa esse plugin -- Plugins originados do workspace são **desativados por padrão** (devem ser ativados explicitamente) -- Plugins agrupados seguem o conjunto integrado ativado por padrão, salvo substituição +- Plugins originados no workspace são **desativados por padrão** (devem ser ativados explicitamente) +- Plugins empacotados seguem o conjunto embutido ativado por padrão, a menos que sejam sobrescritos - Slots exclusivos podem forçar a ativação do plugin selecionado para esse slot -- Alguns plugins agrupados opt-in são ativados automaticamente quando a configuração nomeia uma - superfície pertencente ao plugin, como uma referência de modelo de provedor, configuração de canal ou runtime +- Alguns plugins empacotados opt-in são ativados automaticamente quando a configuração nomeia uma + superfície pertencente ao plugin, como uma ref de modelo de provedor, configuração de canal ou runtime de harness - Configuração obsoleta de plugin é preservada enquanto `plugins.enabled: false` está ativo; - reative os plugins antes de executar a limpeza do doctor se quiser que ids obsoletos sejam removidos + reative os plugins antes de executar a limpeza do doctor se quiser remover ids obsoletos - Rotas Codex da família OpenAI mantêm limites de plugin separados: - `openai-codex/*` pertence ao plugin OpenAI, enquanto o plugin agrupado do servidor de app Codex - é selecionado por `agentRuntime.id: "codex"` ou referências legadas de modelo + `openai-codex/*` pertence ao plugin OpenAI, enquanto o plugin empacotado de + app-server do Codex é selecionado por `agentRuntime.id: "codex"` ou refs de modelo legadas `codex/*` -## Solução de problemas de hooks de runtime +## Solução de problemas de hooks em runtime -Se um plugin aparece em `plugins list`, mas efeitos colaterais ou hooks de `register(api)` -não são executados em tráfego de chat ao vivo, verifique isto primeiro: +Se um plugin aparecer em `plugins list`, mas efeitos colaterais ou hooks de `register(api)` +não forem executados no tráfego de chat ao vivo, verifique estes pontos primeiro: -- Execute `openclaw gateway status --deep --require-rpc` e confirme se a URL ativa do - Gateway, o perfil, o caminho da configuração e o processo são os que você está editando. -- Reinicie o Gateway ao vivo após alterações de instalação/configuração/código do plugin. Em contêineres +- Execute `openclaw gateway status --deep --require-rpc` e confirme que a URL, o perfil, + o caminho de configuração e o processo do Gateway ativo são os que você está editando. +- Reinicie o Gateway ao vivo após alterações de instalação/configuração/código de plugins. Em contêineres wrapper, o PID 1 pode ser apenas um supervisor; reinicie ou sinalize o processo filho `openclaw gateway run`. - Use `openclaw plugins inspect --runtime --json` para confirmar registros de hooks e - diagnósticos. Hooks de conversa não agrupados, como `llm_input`, + diagnósticos. Hooks de conversa não empacotados, como `llm_input`, `llm_output`, `before_agent_finalize` e `agent_end`, precisam de `plugins.entries..hooks.allowConversationAccess=true`. -- Para troca de modelo, prefira `before_model_resolve`. Ele é executado antes da resolução de modelo - para turnos de agente; `llm_output` só é executado depois que uma tentativa de modelo +- Para troca de modelo, prefira `before_model_resolve`. Ele é executado antes da resolução + de modelo para turnos de agente; `llm_output` só é executado depois que uma tentativa de modelo produz saída do assistente. -- Para prova do modelo efetivo da sessão, use `openclaw sessions` ou as superfícies - de sessão/status do Gateway e, ao depurar payloads de provedor, inicie +- Para prova do modelo efetivo da sessão, use `openclaw sessions` ou as superfícies de + sessão/status do Gateway e, ao depurar payloads de provedores, inicie o Gateway com `--raw-stream --raw-stream-path `. ### Configuração lenta de ferramentas de plugin -Se turnos de agente parecem travar durante a preparação de ferramentas, ative logs de rastreamento e -verifique linhas de tempo de fábrica de ferramentas de plugin: +Se turnos de agente parecerem travar ao preparar ferramentas, ative logs de trace e +verifique linhas de temporização da factory de ferramentas de plugin: ```bash openclaw config set logging.level trace @@ -393,26 +401,26 @@ Procure por: [trace:plugin-tools] factory timings ... ``` -O resumo lista o tempo total de fábrica e as fábricas de ferramentas de plugin mais lentas, +O resumo lista o tempo total de factory e as factories de ferramentas de plugin mais lentas, incluindo id do plugin, nomes de ferramentas declarados, formato do resultado e se a ferramenta é -opcional. Linhas lentas são promovidas a avisos quando uma única fábrica leva -pelo menos 1s ou a preparação total de fábricas de ferramentas de plugin leva pelo menos 5s. +opcional. Linhas lentas são promovidas a avisos quando uma única factory leva pelo menos +1s ou a preparação total das factories de ferramentas de plugin leva pelo menos 5s. -O OpenClaw armazena em cache resultados bem-sucedidos de fábricas de ferramentas de plugin para resoluções repetidas -com o mesmo contexto efetivo da requisição. A chave de cache inclui a configuração -efetiva de runtime, workspace, ids de agente/sessão, política de sandbox, configurações do navegador, -contexto de entrega, identidade do solicitante e estado de propriedade, então fábricas que +O OpenClaw armazena em cache resultados bem-sucedidos de factories de ferramentas de plugin para resoluções repetidas +com o mesmo contexto efetivo de requisição. A chave de cache inclui a configuração efetiva +de runtime, workspace, ids de agente/sessão, política de sandbox, configurações do navegador, +contexto de entrega, identidade do solicitante e estado de propriedade, então factories que dependem desses campos confiáveis são executadas novamente quando o contexto muda. -Se um plugin domina o tempo, inspecione seus registros de runtime: +Se um plugin dominar a temporização, inspecione seus registros de runtime: ```bash openclaw plugins inspect --runtime --json ``` -Depois atualize, reinstale ou desative esse plugin. Autores de Plugin devem mover +Depois atualize, reinstale ou desative esse plugin. Autores de plugins devem mover carregamento caro de dependências para trás do caminho de execução da ferramenta, em vez de fazê-lo -dentro da fábrica de ferramentas. +dentro da factory da ferramenta. ### Propriedade duplicada de canal ou ferramenta @@ -422,9 +430,9 @@ Sintomas: - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Isso significa que mais de um plugin ativado está tentando ser proprietário do mesmo canal, -fluxo de configuração ou nome de ferramenta. A causa mais comum é um plugin de canal externo -instalado ao lado de um plugin agrupado que agora fornece o mesmo id de canal. +Isso significa que mais de um plugin ativado está tentando possuir o mesmo canal, +fluxo de configuração ou nome de ferramenta. A causa mais comum é um plugin externo de canal +instalado ao lado de um plugin empacotado que agora fornece o mesmo id de canal. Etapas de depuração: @@ -432,25 +440,25 @@ Etapas de depuração: e sua origem. - Execute `openclaw plugins inspect --runtime --json` para cada plugin suspeito e compare `channels`, `channelConfigs`, `tools` e diagnósticos. -- Execute `openclaw plugins registry --refresh` após instalar ou remover - pacotes de plugin para que metadados persistidos reflitam a instalação atual. +- Execute `openclaw plugins registry --refresh` depois de instalar ou remover + pacotes de plugin para que os metadados persistidos reflitam a instalação atual. - Reinicie o Gateway após alterações de instalação, registro ou configuração. Opções de correção: - Se um plugin substitui intencionalmente outro para o mesmo id de canal, o plugin preferido deve declarar `channelConfigs..preferOver` com - o id do plugin de prioridade mais baixa. Consulte [/plugins/manifest#replacing-another-channel-plugin](/pt-BR/plugins/manifest#replacing-another-channel-plugin). -- Se a duplicação for acidental, desative um lado com - `plugins.entries..enabled: false` ou remova a instalação obsoleta do - plugin. + o id do plugin de prioridade mais baixa. Veja [/plugins/manifest#replacing-another-channel-plugin](/pt-BR/plugins/manifest#replacing-another-channel-plugin). +- Se a duplicação for acidental, desative um dos lados com + `plugins.entries..enabled: false` ou remova a instalação obsoleta + do plugin. - Se você ativou explicitamente ambos os plugins, o OpenClaw mantém essa solicitação e - relata o conflito. Escolha um proprietário para o canal ou renomeie ferramentas pertencentes a plugin + reporta o conflito. Escolha um proprietário para o canal ou renomeie as ferramentas pertencentes ao plugin para que a superfície de runtime seja inequívoca. -## Slots de Plugin (categorias exclusivas) +## Slots de plugin (categorias exclusivas) -Algumas categorias são exclusivas (somente uma ativa por vez): +Algumas categorias são exclusivas (apenas uma ativa por vez): ```json5 { @@ -465,8 +473,8 @@ Algumas categorias são exclusivas (somente uma ativa por vez): | Slot | O que controla | Padrão | | --------------- | --------------------- | ------------------- | -| `memory` | Plugin de memória ativa | `memory-core` | -| `contextEngine` | Motor de contexto ativo | `legacy` (integrado) | +| `memory` | Plugin de Active Memory | `memory-core` | +| `contextEngine` | Mecanismo de contexto ativo | `legacy` (embutido) | ## Referência da CLI @@ -516,84 +524,33 @@ openclaw plugins enable openclaw plugins disable ``` -Plugins incluídos são distribuídos com o OpenClaw. Muitos são habilitados por padrão (por exemplo -provedores de modelo incluídos, provedores de fala incluídos e o plugin de navegador -incluído). Outros plugins incluídos ainda precisam de `openclaw plugins enable `. +Plugins incluídos são distribuídos com o OpenClaw. Muitos são ativados por padrão (por exemplo, provedores de modelos incluídos, provedores de fala incluídos e o plugin de navegador incluído). Outros plugins incluídos ainda precisam de `openclaw plugins enable `. -`--force` sobrescreve no local um plugin instalado ou pacote de hooks existente. Use -`openclaw plugins update ` para atualizações rotineiras de plugins npm -rastreados. Ele não é compatível com `--link`, que reutiliza o caminho de origem em vez -de copiar sobre um destino de instalação gerenciada. +`--force` sobrescreve no lugar um plugin instalado existente ou pacote de hooks. Use `openclaw plugins update ` para atualizações rotineiras de plugins npm rastreados. Ele não é compatível com `--link`, que reutiliza o caminho de origem em vez de copiar sobre um destino de instalação gerenciado. -Quando `plugins.allow` já está definido, `openclaw plugins install` adiciona o -id do plugin instalado a essa allowlist antes de habilitá-lo. Se o mesmo id de plugin -estiver presente em `plugins.deny`, a instalação remove essa entrada deny obsoleta para que a -instalação explícita possa ser carregada imediatamente após a reinicialização. +Quando `plugins.allow` já está definido, `openclaw plugins install` adiciona o id do plugin instalado a essa lista de permissões antes de ativá-lo. Se o mesmo id de plugin estiver presente em `plugins.deny`, a instalação remove essa entrada de negação obsoleta para que a instalação explícita possa ser carregada imediatamente após a reinicialização. -O OpenClaw mantém um registro local persistido de plugins como modelo de leitura frio para -inventário de plugins, propriedade de contribuições e planejamento de inicialização. Os fluxos de instalação, atualização, -desinstalação, habilitação e desabilitação atualizam esse registro depois de alterar o -estado do plugin. O mesmo arquivo `plugins/installs.json` mantém metadados duráveis de instalação em -`installRecords` de nível superior e metadados reconstruíveis de manifesto em `plugins`. Se -o registro estiver ausente, obsoleto ou inválido, `openclaw plugins registry ---refresh` reconstrói sua visão de manifesto a partir dos registros de instalação, política de configuração e -metadados de manifesto/pacote sem carregar módulos de runtime de plugin. -`openclaw plugins update ` se aplica a instalações rastreadas. Passar -uma especificação de pacote npm com uma dist-tag ou versão exata resolve o nome do pacote -de volta para o registro de plugin rastreado e registra a nova especificação para futuras atualizações. -Passar o nome do pacote sem uma versão move uma instalação com pin exato de volta para -a linha de lançamento padrão do registro. Se o plugin npm instalado já corresponder -à versão resolvida e à identidade de artefato registrada, o OpenClaw pula a atualização -sem baixar, reinstalar ou reescrever a configuração. -Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub -na linha padrão tentam `@beta` primeiro e voltam para default/latest quando não existe -lançamento beta do plugin. Versões exatas e tags explícitas permanecem fixadas. +O OpenClaw mantém um registro local persistente de plugins como modelo de leitura fria para inventário de plugins, propriedade de contribuições e planejamento de inicialização. Fluxos de instalação, atualização, desinstalação, ativação e desativação atualizam esse registro depois de alterar o estado do plugin. O mesmo arquivo `plugins/installs.json` mantém metadados de instalação duráveis em `installRecords` no nível superior e metadados de manifesto reconstruíveis em `plugins`. Se o registro estiver ausente, obsoleto ou inválido, `openclaw plugins registry --refresh` reconstrói sua visão de manifesto a partir dos registros de instalação, da política de configuração e dos metadados de manifesto/pacote sem carregar módulos de runtime de plugins. `openclaw plugins update ` se aplica a instalações rastreadas. Passar uma especificação de pacote npm com uma dist-tag ou versão exata resolve o nome do pacote de volta para o registro do plugin rastreado e registra a nova especificação para atualizações futuras. Passar o nome do pacote sem uma versão move uma instalação fixada exata de volta para a linha de lançamento padrão do registro. Se o plugin npm instalado já corresponder à versão resolvida e à identidade de artefato registrada, o OpenClaw ignora a atualização sem baixar, reinstalar ou reescrever a configuração. Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub da linha padrão tentam `@beta` primeiro e retornam para padrão/latest quando não existe lançamento beta do plugin. Versões exatas e tags explícitas permanecem fixadas. -`--pin` é somente para npm. Ele não é compatível com `--marketplace`, porque -instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm. +`--pin` é somente para npm. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm. -`--dangerously-force-unsafe-install` é uma substituição de emergência para falsos -positivos do scanner de código perigoso integrado. Ela permite que instalações de plugins -e atualizações de plugins continuem após achados `critical` integrados, mas ainda -não contorna bloqueios de política `before_install` de plugins nem bloqueio por falha de varredura. -Varreduras de instalação ignoram arquivos e diretórios comuns de teste, como `tests/`, -`__tests__/`, `*.test.*` e `*.spec.*`, para evitar bloquear mocks de teste empacotados; -entrypoints de runtime declarados pelo plugin ainda são verificados mesmo que usem um desses -nomes. +`--dangerously-force-unsafe-install` é uma substituição de emergência para falsos positivos do scanner de código perigoso integrado. Ele permite que instalações e atualizações de plugins continuem após descobertas `critical` integradas, mas ainda não contorna bloqueios de política `before_install` de plugins nem bloqueios por falha de varredura. Varreduras de instalação ignoram arquivos e diretórios de teste comuns, como `tests/`, `__tests__/`, `*.test.*` e `*.spec.*`, para evitar bloquear mocks de teste empacotados; pontos de entrada de runtime declarados do plugin ainda são verificados mesmo que usem um desses nomes. -Essa flag de CLI se aplica apenas aos fluxos de instalação/atualização de plugins. Instalações de dependências de Skills -com suporte do Gateway usam a substituição de solicitação `dangerouslyForceUnsafeInstall` -correspondente, enquanto `openclaw skills install` continua sendo o fluxo separado de -download/instalação de Skills do ClawHub. +Esta flag da CLI se aplica apenas aos fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` permanece o fluxo separado de download/instalação de Skills do ClawHub. -Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma varredura, abra o -painel do ClawHub ou execute `clawhub package rescan ` para pedir ao ClawHub que o verifique -novamente. `--dangerously-force-unsafe-install` afeta apenas instalações na sua própria -máquina; ele não pede ao ClawHub para verificar o plugin novamente nem torna público um lançamento -bloqueado. +Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma varredura, abra o painel do ClawHub ou execute `clawhub package rescan ` para pedir que o ClawHub o verifique novamente. `--dangerously-force-unsafe-install` afeta apenas instalações na sua própria máquina; ele não pede ao ClawHub para verificar novamente o plugin nem torna público um lançamento bloqueado. -Bundles compatíveis participam do mesmo fluxo de listar/inspecionar/habilitar/desabilitar -plugins. O suporte de runtime atual inclui Skills de bundle, command-skills do Claude, -padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude e de -`lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks -compatíveis do Codex. +Bundles compatíveis participam do mesmo fluxo de listar/inspecionar/ativar/desativar plugins. O suporte de runtime atual inclui Skills de bundle, command-skills do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude e `lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks compatíveis do Codex. -`openclaw plugins inspect ` também relata capacidades detectadas do bundle, além de -entradas de servidor MCP e LSP compatíveis ou incompatíveis para plugins baseados em bundle. +`openclaw plugins inspect ` também relata capacidades de bundle detectadas, além de entradas de servidor MCP e LSP compatíveis ou incompatíveis para plugins apoiados por bundle. -Origens de marketplace podem ser um nome de marketplace conhecido do Claude em -`~/.claude/plugins/known_marketplaces.json`, uma raiz de marketplace local ou -caminho de `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório do GitHub -ou uma URL git. Para marketplaces remotos, as entradas de plugins devem permanecer dentro do -repositório de marketplace clonado e usar apenas origens de caminho relativo. +Origens de marketplace podem ser um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json`, uma raiz de marketplace local ou caminho `marketplace.json`, um atalho do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. Para marketplaces remotos, as entradas de plugin devem permanecer dentro do repositório de marketplace clonado e usar somente origens de caminho relativas. -Veja a [referência de CLI de `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos. +Consulte a [referência da CLI `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos. ## Visão geral da API de Plugin -Plugins nativos exportam um objeto de entrada que expõe `register(api)`. Plugins mais antigos -ainda podem usar `activate(api)` como alias legado, mas novos plugins devem -usar `register`. +Plugins nativos exportam um objeto de entrada que expõe `register(api)`. Plugins mais antigos ainda podem usar `activate(api)` como alias legado, mas novos plugins devem usar `register`. ```typescript export default definePluginEntry({ @@ -613,75 +570,60 @@ export default definePluginEntry({ }); ``` -O OpenClaw carrega o objeto de entrada e chama `register(api)` durante a -ativação do plugin. O loader ainda recorre a `activate(api)` para plugins mais antigos, -mas plugins incluídos e novos plugins externos devem tratar `register` como o -contrato público. +O OpenClaw carrega o objeto de entrada e chama `register(api)` durante a ativação do plugin. O carregador ainda recorre a `activate(api)` para plugins mais antigos, mas plugins incluídos e novos plugins externos devem tratar `register` como o contrato público. `api.registrationMode` informa a um plugin por que sua entrada está sendo carregada: -| Modo | Significado | -| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Ativação de runtime. Registre ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ao vivo. | -| `discovery` | Descoberta de capacidades somente leitura. Registre provedores e metadados; código de entrada de plugin confiável pode carregar, mas pule efeitos colaterais ao vivo. | -| `setup-only` | Carregamento de metadados de configuração de canal por meio de uma entrada de configuração leve. | -| `setup-runtime` | Carregamento de configuração de canal que também precisa da entrada de runtime. | -| `cli-metadata` | Apenas coleta de metadados de comando da CLI. | +| Modo | Significado | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `full` | Ativação de runtime. Registre ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ativos. | +| `discovery` | Descoberta de capacidades somente leitura. Registre provedores e metadados; código de entrada confiável do plugin pode carregar, mas pule efeitos colaterais ativos. | +| `setup-only` | Carregamento de metadados de configuração de canal por meio de uma entrada de configuração leve. | +| `setup-runtime` | Carregamento de configuração de canal que também precisa da entrada de runtime. | +| `cli-metadata` | Apenas coleta de metadados de comandos da CLI. | -Entradas de plugin que abrem sockets, bancos de dados, workers em segundo plano ou clientes -de longa duração devem proteger esses efeitos colaterais com `api.registrationMode === "full"`. -Cargas de descoberta são armazenadas em cache separadamente das cargas de ativação e não substituem -o registro do Gateway em execução. A descoberta é não ativadora, não livre de imports: -o OpenClaw pode avaliar a entrada confiável do plugin ou o módulo de plugin de canal para criar -o snapshot. Mantenha os níveis superiores dos módulos leves e sem efeitos colaterais, e mova -clientes de rede, subprocessos, listeners, leituras de credenciais e inicialização de serviços -para trás de caminhos de runtime completo. +Entradas de plugin que abrem sockets, bancos de dados, workers em segundo plano ou clientes de longa duração devem proteger esses efeitos colaterais com `api.registrationMode === "full"`. Cargas de descoberta são armazenadas em cache separadamente das cargas de ativação e não substituem o registro em execução do Gateway. A descoberta é não ativadora, não livre de imports: o OpenClaw pode avaliar a entrada confiável do plugin ou o módulo de plugin de canal para criar o snapshot. Mantenha os níveis superiores de módulo leves e sem efeitos colaterais, e mova clientes de rede, subprocessos, listeners, leituras de credenciais e inicialização de serviços para trás de caminhos de runtime completo. -Métodos comuns de registro: +Métodos de registro comuns: -| Método | O que registra | -| --------------------------------------- | --------------------------------------- | -| `registerProvider` | Provedor de modelo (LLM) | -| `registerChannel` | Canal de chat | -| `registerTool` | Ferramenta de agente | -| `registerHook` / `on(...)` | Hooks de ciclo de vida | -| `registerSpeechProvider` | Texto para fala / STT | -| `registerRealtimeTranscriptionProvider` | STT em streaming | -| `registerRealtimeVoiceProvider` | Voz em tempo real duplex | -| `registerMediaUnderstandingProvider` | Análise de imagem/áudio | -| `registerImageGenerationProvider` | Geração de imagem | -| `registerMusicGenerationProvider` | Geração de música | -| `registerVideoGenerationProvider` | Geração de vídeo | -| `registerWebFetchProvider` | Provedor de busca/coleta na web | -| `registerWebSearchProvider` | Busca na web | -| `registerHttpRoute` | Endpoint HTTP | -| `registerCommand` / `registerCli` | Comandos de CLI | -| `registerContextEngine` | Motor de contexto | -| `registerService` | Serviço em segundo plano | +| Método | O que registra | +| --------------------------------------- | -------------------------------- | +| `registerProvider` | Provedor de modelo (LLM) | +| `registerChannel` | Canal de chat | +| `registerTool` | Ferramenta de agente | +| `registerHook` / `on(...)` | Hooks de ciclo de vida | +| `registerSpeechProvider` | Texto para fala / STT | +| `registerRealtimeTranscriptionProvider` | STT em streaming | +| `registerRealtimeVoiceProvider` | Voz em tempo real duplex | +| `registerMediaUnderstandingProvider` | Análise de imagem/áudio | +| `registerImageGenerationProvider` | Geração de imagens | +| `registerMusicGenerationProvider` | Geração de música | +| `registerVideoGenerationProvider` | Geração de vídeo | +| `registerWebFetchProvider` | Provedor de busca/coleta Web | +| `registerWebSearchProvider` | Pesquisa Web | +| `registerHttpRoute` | Endpoint HTTP | +| `registerCommand` / `registerCli` | Comandos da CLI | +| `registerContextEngine` | Mecanismo de contexto | +| `registerService` | Serviço em segundo plano | -Comportamento de guard para hooks tipados de ciclo de vida: +Comportamento de guarda de hooks para hooks de ciclo de vida tipados: -- `before_tool_call`: `{ block: true }` é terminal; handlers de prioridade mais baixa são pulados. +- `before_tool_call`: `{ block: true }` é terminal; manipuladores de prioridade mais baixa são ignorados. - `before_tool_call`: `{ block: false }` é um no-op e não limpa um bloqueio anterior. -- `before_install`: `{ block: true }` é terminal; handlers de prioridade mais baixa são pulados. +- `before_install`: `{ block: true }` é terminal; manipuladores de prioridade mais baixa são ignorados. - `before_install`: `{ block: false }` é um no-op e não limpa um bloqueio anterior. -- `message_sending`: `{ cancel: true }` é terminal; handlers de prioridade mais baixa são pulados. +- `message_sending`: `{ cancel: true }` é terminal; manipuladores de prioridade mais baixa são ignorados. - `message_sending`: `{ cancel: false }` é um no-op e não limpa um cancelamento anterior. -O app-server nativo do Codex faz a ponte de eventos de ferramentas nativas do Codex de volta para esta -superfície de hooks. Plugins podem bloquear ferramentas nativas do Codex por meio de `before_tool_call`, -observar resultados por meio de `after_tool_call` e participar de aprovações de -`PermissionRequest` do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do Codex. -O limite exato de suporte ao runtime do Codex está no -[contrato de suporte v1 do harness do Codex](/pt-BR/plugins/codex-harness#v1-support-contract). +O app-server nativo do Codex faz a ponte de eventos de ferramentas nativas do Codex de volta para esta superfície de hooks. Plugins podem bloquear ferramentas nativas do Codex por meio de `before_tool_call`, observar resultados por meio de `after_tool_call` e participar de aprovações `PermissionRequest` do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do Codex. O limite exato de suporte de runtime do Codex está no [contrato de suporte do harness Codex v1](/pt-BR/plugins/codex-harness#v1-support-contract). -Para o comportamento completo de hooks tipados, veja a [visão geral do SDK](/pt-BR/plugins/sdk-overview#hook-decision-semantics). +Para o comportamento completo de hooks tipados, consulte a [visão geral do SDK](/pt-BR/plugins/sdk-overview#hook-decision-semantics). -## Relacionados +## Relacionado - [Criando plugins](/pt-BR/plugins/building-plugins) — crie seu próprio plugin -- [Bundles de Plugin](/pt-BR/plugins/bundles) — compatibilidade de bundles Codex/Claude/Cursor -- [Manifesto de Plugin](/pt-BR/plugins/manifest) — esquema de manifesto +- [Pacotes de plugins](/pt-BR/plugins/bundles) — compatibilidade de pacotes do Codex/Claude/Cursor +- [Manifesto do plugin](/pt-BR/plugins/manifest) — esquema do manifesto - [Registrando ferramentas](/pt-BR/plugins/building-plugins#registering-agent-tools) — adicione ferramentas de agente em um plugin -- [Internos de Plugin](/pt-BR/plugins/architecture) — modelo de capacidade e pipeline de carregamento +- [Aspectos internos do plugin](/pt-BR/plugins/architecture) — modelo de capacidades e pipeline de carregamento - [Plugins da comunidade](/pt-BR/plugins/community) — listagens de terceiros diff --git a/docs/pt-BR/tools/thinking.md b/docs/pt-BR/tools/thinking.md index 2d1d7985f..51aac36fc 100644 --- a/docs/pt-BR/tools/thinking.md +++ b/docs/pt-BR/tools/thinking.md @@ -1,97 +1,98 @@ --- read_when: - - Ajuste da análise de diretivas ou padrões de raciocínio, modo rápido ou verbosidade + - Ajustar a análise sintática ou os padrões das diretivas thinking, fast-mode ou verbose summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio title: Níveis de raciocínio x-i18n: - generated_at: "2026-05-04T18:24:30Z" + generated_at: "2026-05-05T01:50:47Z" model: gpt-5.5 provider: openai - source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811 + source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012 source_path: tools/thinking.md workflow: 16 --- -## O que ele faz +## O que faz - Diretiva inline em qualquer corpo recebido: `/t `, `/think:` ou `/thinking `. - Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “think” - - low → “think hard” - - medium → “think harder” + - minimal → “pensar” + - low → “pensar muito” + - medium → “pensar ainda mais” - high → “ultrathink” (orçamento máximo) - xhigh → “ultrathink+” (modelos GPT-5.2+ e Codex, além do esforço do Anthropic Claude Opus 4.7) - - adaptive → pensamento adaptativo gerenciado pelo provedor (com suporte para Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini) - - max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; o Ollama mapeia isso para seu maior esforço `think` nativo) + - adaptive → pensamento adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini) + - max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; Ollama mapeia isso para seu maior esforço nativo de `think`) - `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` mapeiam para `xhigh`. - `highest` mapeia para `high`. - Observações sobre provedores: - - Menus e seletores de pensamento são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como `on` binário. - - `adaptive`, `xhigh` e `max` só são anunciados para perfis de provedor/modelo que os suportam. Diretivas digitadas para níveis sem suporte são rejeitadas com as opções válidas desse modelo. - - Níveis sem suporte armazenados anteriormente são remapeados pela classificação do perfil do provedor. `adaptive` volta para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` voltam para o maior nível não `off` com suporte para o modelo selecionado. - - Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento é definido. + - Menus e seletores de pensamento são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como o binário `on`. + - `adaptive`, `xhigh` e `max` só são anunciados para perfis de provedor/modelo compatíveis. Diretivas digitadas para níveis não compatíveis são rejeitadas com as opções válidas desse modelo. + - Níveis armazenados existentes que não são compatíveis são remapeados pela classificação do perfil do provedor. `adaptive` volta para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` voltam para o maior nível não `off` compatível com o modelo selecionado. + - Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento está definido. - Anthropic Claude Opus 4.7 não usa pensamento adaptativo por padrão. O padrão de esforço da API continua pertencendo ao provedor, a menos que você defina explicitamente um nível de pensamento. - Anthropic Claude Opus 4.7 mapeia `/think xhigh` para pensamento adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de pensamento e `xhigh` é a configuração de esforço do Opus 4.7. - Anthropic Claude Opus 4.7 também expõe `/think max`; ele mapeia para o mesmo caminho de esforço máximo pertencente ao provedor. - - Modelos DeepSeek V4 expõem `/think xhigh|max`; ambos mapeiam para `reasoning_effort: "max"` do DeepSeek, enquanto níveis menores não `off` mapeiam para `high`. - - Modelos Ollama com capacidade de pensamento expõem `/think low|medium|high|max`; `max` mapeia para `think: "high"` nativo porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`. - - Modelos OpenAI GPT mapeiam `/think` pelo suporte de esforço da Responses API específico do modelo. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino oferece suporte; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte. - - Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers..models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI de agente e `llm-task` concordam com o comportamento de transporte. - - Refs configuradas obsoletas do OpenRouter Hunter Alpha pulam a injeção de raciocínio por proxy porque essa rota aposentada poderia retornar o texto da resposta final por campos de raciocínio. - - Google Gemini mapeia `/think adaptive` para o pensamento dinâmico pertencente ao provedor do Gemini. Requisições Gemini 3 omitem um `thinkingLevel` fixo, enquanto requisições Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos. - - MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou da requisição. Isso evita deltas `reasoning_content` vazados do formato de stream Anthropic não nativo da MiniMax. - - Z.AI (`zai/*`) oferece suporte apenas a pensamento binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`). - - Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`. + - Modelos diretos DeepSeek V4 expõem `/think xhigh|max`; ambos mapeiam para `reasoning_effort: "max"` do DeepSeek, enquanto níveis não `off` menores mapeiam para `high`. + - Modelos DeepSeek V4 roteados pelo OpenRouter expõem `/think xhigh` e enviam valores de `reasoning_effort` compatíveis com o OpenRouter. Sobrescritas `max` armazenadas voltam para `xhigh`. + - Modelos Ollama com capacidade de pensamento expõem `/think low|medium|high|max`; `max` mapeia para o `think: "high"` nativo, porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`. + - Modelos OpenAI GPT mapeiam `/think` pelo suporte a esforço da Responses API específico do modelo. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino é compatível; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte. + - Entradas de catálogo personalizadas compatíveis com OpenAI podem aderir a `/think xhigh` definindo `models.providers..models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI de agente e `llm-task` concordam com o comportamento de transporte. + - Referências configuradas obsoletas do OpenRouter Hunter Alpha ignoram a injeção de raciocínio por proxy porque essa rota descontinuada podia retornar texto de resposta final por campos de raciocínio. + - Google Gemini mapeia `/think adaptive` para o pensamento dinâmico pertencente ao provedor do Gemini. Solicitações do Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações do Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos. + - MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou da solicitação. Isso evita deltas de `reasoning_content` vazados pelo formato de stream Anthropic não nativo do MiniMax. + - Z.AI (`zai/*`) só oferece suporte a pensamento binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`). + - Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, Moonshot só aceita `tool_choice` `auto|none`; OpenClaw normaliza valores incompatíveis para `auto`. ## Ordem de resolução 1. Diretiva inline na mensagem (aplica-se somente a essa mensagem). -2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas a diretiva). +2. Sobrescrita de sessão (definida pelo envio de uma mensagem contendo apenas a diretiva). 3. Padrão por agente (`agents.list[].thinkingDefault` na configuração). 4. Padrão global (`agents.defaults.thinkingDefault` na configuração). -5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou para o nível não `off` com suporte mais próximo para esse modelo, e modelos sem raciocínio permanecem `off`. +5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou o nível não `off` compatível mais próximo para esse modelo, e modelos sem raciocínio permanecem `off`. -## Definir um padrão de sessão +## Definindo um padrão de sessão - Envie uma mensagem que seja **somente** a diretiva (espaços em branco permitidos), por exemplo, `/think:medium` ou `/t high`. -- Isso permanece para a sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição de sessão ociosa. -- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão ficará inalterado. -- Envie `/think` (ou `/think:`) sem argumento para ver o nível atual de pensamento. +- Isso fica fixo para a sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição de ociosidade da sessão. +- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão permanecerá inalterado. +- Envie `/think` (ou `/think:`) sem argumento para ver o nível de pensamento atual. ## Aplicação por agente -- **Pi embutido**: o nível resolvido é passado para o runtime do agente Pi em processo. -- **Backend Claude CLI**: níveis diferentes de off são passados para Claude Code como `--effort` ao usar `claude-cli`; consulte [backends CLI](/pt-BR/gateway/cli-backends). +- **Pi incorporado**: o nível resolvido é passado para o runtime do agente Pi em processo. +- **backend Claude CLI**: níveis diferentes de off são passados para Claude Code como `--effort` ao usar `claude-cli`; consulte [backends CLI](/pt-BR/gateway/cli-backends). ## Modo rápido (/fast) - Níveis: `on|off`. -- Mensagem contendo apenas a diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`. +- Mensagem contendo apenas a diretiva alterna uma sobrescrita de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`. - Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido. -- O OpenClaw resolve o modo rápido nesta ordem: - 1. `/fast on|off` inline/contendo apenas a diretiva - 2. Substituição da sessão +- OpenClaw resolve o modo rápido nesta ordem: + 1. `/fast on|off` inline/contendo apenas diretiva + 2. Sobrescrita de sessão 3. Padrão por agente (`agents.list[].fastModeDefault`) 4. Configuração por modelo: `agents.defaults.models["/"].params.fastMode` 5. Fallback: `off` -- Para `openai/*`, o modo rápido mapeia para processamento prioritário da OpenAI enviando `service_tier=priority` em requisições Responses com suporte. -- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Responses do Codex. O OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação. -- Para requisições públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para camadas de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`. +- Para `openai/*`, o modo rápido mapeia para processamento prioritário da OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis. +- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Codex Responses. OpenClaw mantém uma única alternância `/fast` compartilhada entre os dois caminhos de autenticação. +- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`. - Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. -- Parâmetros de modelo Anthropic explícitos `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. O OpenClaw ainda pula a injeção de camada de serviço Anthropic para URLs base de proxy não Anthropic. +- Parâmetros explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão de modo rápido quando ambos estão definidos. OpenClaw ainda ignora a injeção de nível de serviço Anthropic para URLs base de proxy não Anthropic. - `/status` mostra `Fast` somente quando o modo rápido está ativado. -## Diretivas detalhadas (/verbose ou /v) +## Diretivas verbosas (/verbose ou /v) - Níveis: `on` (mínimo) | `full` | `off` (padrão). -- Mensagem contendo apenas a diretiva alterna o detalhamento da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado. -- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessões escolhendo `inherit`. +- Mensagem contendo apenas a diretiva alterna o verbose da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado. +- `/verbose off` armazena uma sobrescrita explícita de sessão; limpe-a pela UI de Sessões escolhendo `inherit`. - Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam caso contrário. -- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual. -- Quando o modo detalhado está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem apenas de metadados, prefixada com ` : ` quando disponível. Esses resumos de ferramentas são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming. -- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos com detalhes brutos de erro ficam ocultos, a menos que o detalhamento seja `on` ou `full`. -- Quando o detalhamento é `full`, saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução está em andamento, bolhas de ferramentas posteriores respeitarão a nova configuração. -- `agents.defaults.toolProgressDetail` controla o formato dos resumos de ferramentas de `/verbose` e das linhas de ferramenta de rascunho de progresso. Use `"explain"` (padrão) para rótulos humanos compactos como `🛠️ Exec: checking JS syntax`; use `"raw"` quando também quiser o comando/detalhe bruto anexado para depuração. `agents.list[].toolProgressDetail` por agente substitui o padrão. +- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível verbose atual. +- Quando verbose está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com ` : ` quando disponível. Esses resumos de ferramenta são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming. +- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos de detalhes brutos de erro ficam ocultos, a menos que verbose seja `on` ou `full`. +- Quando verbose é `full`, as saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um comprimento seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração. +- `agents.defaults.toolProgressDetail` controla o formato dos resumos de ferramenta de `/verbose` e das linhas de ferramenta de rascunho de progresso. Use `"explain"` (padrão) para rótulos humanos compactos, como `🛠️ Exec: checking JS syntax`; use `"raw"` quando também quiser o comando/detalhe bruto anexado para depuração. `agents.list[].toolProgressDetail` por agente substitui o padrão. - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js` - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` @@ -100,21 +101,21 @@ x-i18n: - Níveis: `on` | `off` (padrão). - Mensagem contendo apenas a diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`. - Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam caso contrário. -- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível atual de rastreamento. +- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual. - `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de rastreamento/depuração pertencentes ao Plugin, como resumos de depuração da Active Memory. -- Linhas de rastreamento podem aparecer em `/status` e como mensagem diagnóstica de acompanhamento após a resposta normal do assistente. +- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente. -## Visibilidade do raciocínio (/reasoning) +## Visibilidade de raciocínio (/reasoning) - Níveis: `on|off|stream`. -- Mensagem contendo apenas a diretiva alterna se blocos de pensamento são mostrados nas respostas. +- Mensagem contendo apenas a diretiva alterna se blocos de pensamento são exibidos nas respostas. - Quando ativado, o raciocínio é enviado como uma **mensagem separada** prefixada com `Reasoning:`. -- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta está sendo gerada, depois envia a resposta final sem raciocínio. +- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta está sendo gerada e depois envia a resposta final sem raciocínio. - Alias: `/reason`. -- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível atual de raciocínio. -- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`). +- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível de raciocínio atual. +- Ordem de resolução: diretiva inline, depois sobrescrita de sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`). -Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos `...` fechados permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, de outra forma, seria entregue como texto vazio, o OpenClaw remove a tag de abertura malformada e entrega o texto restante. +Tags de raciocínio malformadas de modelo local são tratadas de forma conservadora. Blocos fechados `...` permanecem ocultos em respostas normais, e raciocínio não fechado depois de texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e de outra forma seria entregue como texto vazio, OpenClaw remove a tag de abertura malformada e entrega o texto restante. ## Relacionado @@ -122,23 +123,23 @@ Tags de raciocínio de modelo local malformadas são tratadas de forma conservad ## Heartbeats -- O corpo da sondagem de Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats). -- A entrega de Heartbeat usa somente o payload final por padrão. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente. +- O corpo da sonda Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats). +- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente. ## UI de chat web -- O seletor de pensamento do chat web reflete o nível armazenado da sessão a partir do armazenamento/configuração da sessão recebida quando a página carrega. -- Escolher outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição `thinkingOnce` de uso único. -- A primeira opção é sempre `Default ()`, em que o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback que `/status` e `session_status` usam. -- O seletor usa `thinkingLevels` retornado pela linha/padrões de sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedores; Plugins possuem os conjuntos de níveis específicos de modelo. -- `/think:` ainda funciona e atualiza o mesmo nível armazenado da sessão, então diretivas de chat e o seletor permanecem sincronizados. +- O seletor de pensamento do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão recebida quando a página carrega. +- Escolher outro nível grava a sobrescrita de sessão imediatamente via `sessions.patch`; ele não espera pelo próximo envio e não é uma sobrescrita `thinkingOnce` de uso único. +- A primeira opção é sempre `Default ()`, em que o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback usada por `/status` e `session_status`. +- O seletor usa `thinkingLevels` retornado pela linha/padrões de sessão do Gateway, com `thinkingOptions` mantido como uma lista de rótulos legada. A UI do navegador não mantém sua própria lista de regex de provedor; os Plugins são donos dos conjuntos de níveis específicos de modelo. +- `/think:` ainda funciona e atualiza o mesmo nível de sessão armazenado, então as diretivas de chat e o seletor permanecem sincronizados. ## Perfis de provedor -- Plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão. -- Plugins de provedor que atuam como proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e de proxy permaneçam alinhados. -- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir um `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`. -- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` mais `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis de provedor/modelo. -- Plugins de ferramenta com acesso aos metadados configurados de modelo personalizado podem passar `catalog` para `resolveThinkingPolicy` para que adesões de `compat.supportedReasoningEfforts` sejam refletidas na validação no lado do Plugin. +- Os plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão. +- Os plugins de provedor que intermedeiam modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos Anthropic diretos e de proxy permaneçam alinhados. +- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir uma `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`. +- Plugins de ferramenta que precisam validar uma substituição explícita de pensamento devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto com `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis por provedor/modelo. +- Plugins de ferramenta com acesso aos metadados configurados de modelos personalizados podem passar `catalog` para `resolveThinkingPolicy` para que adesões por `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do plugin. - Hooks legados publicados (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) permanecem como adaptadores de compatibilidade, mas novos conjuntos de níveis personalizados devem usar `resolveThinkingProfile`. -- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos ids e rótulos de perfil que a validação em tempo de execução usa. +- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos IDs e rótulos de perfil que a validação de runtime usa. diff --git a/docs/pt-BR/tools/video-generation.md b/docs/pt-BR/tools/video-generation.md index b54173fa2..016ad4b0a 100644 --- a/docs/pt-BR/tools/video-generation.md +++ b/docs/pt-BR/tools/video-generation.md @@ -1,21 +1,21 @@ --- read_when: - - Gerando vídeos por meio do agente + - Geração de vídeos por meio do agente - Configuração de provedores e modelos de geração de vídeo - Entendendo os parâmetros da ferramenta video_generate sidebarTitle: Video generation -summary: Gere vídeos via video_generate a partir de referências de texto, imagem ou vídeo em 16 backends de provedores +summary: Gere vídeos via video_generate a partir de referências de texto, imagem ou vídeo em 16 mecanismos de provedores title: Geração de vídeo x-i18n: - generated_at: "2026-04-30T10:13:16Z" + generated_at: "2026-05-05T01:51:02Z" model: gpt-5.5 provider: openai - source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf + source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83 source_path: tools/video-generation.md workflow: 16 --- -Os agentes do OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou +Os agentes OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou vídeos existentes. Dezesseis backends de provedores são compatíveis, cada um com diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe o provedor certo automaticamente com base na sua configuração e nas chaves de API @@ -24,10 +24,10 @@ disponíveis. A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo está disponível. Se você não a vir nas ferramentas do seu agente, defina uma -chave de API de provedor ou configure `agents.defaults.videoGenerationModel`. +chave de API do provedor ou configure `agents.defaults.videoGenerationModel`. -O OpenClaw trata a geração de vídeo como três modos de tempo de execução: +O OpenClaw trata a geração de vídeo como três modos de runtime: - `generate` — solicitações de texto para vídeo sem mídia de referência. - `imageToVideo` — a solicitação inclui uma ou mais imagens de referência. @@ -39,7 +39,7 @@ modo ativo antes do envio e relata os modos compatíveis em `action=list`. ## Início rápido - + Defina uma chave de API para qualquer provedor compatível: ```bash @@ -47,15 +47,15 @@ modo ativo antes do envio e relata os modos compatíveis em `action=list`. ``` - + ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` - + > Gere um vídeo cinematográfico de 5 segundos de uma lagosta simpática surfando ao pôr do sol. - O agente chama `video_generate` automaticamente. Nenhuma lista de permissões de ferramentas + O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramentas é necessária. @@ -68,33 +68,35 @@ sessão: 1. O OpenClaw envia a solicitação ao provedor e retorna imediatamente um id de tarefa. 2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). -3. Quando o vídeo fica pronto, o OpenClaw desperta a mesma sessão com um evento interno de conclusão. -4. O agente publica o vídeo finalizado de volta na conversa original. +3. Quando o vídeo está pronto, o OpenClaw desperta a mesma sessão com um evento interno de conclusão. +4. O agente informa o usuário e anexa o vídeo finalizado. Em conversas de grupo/canal + que usam entrega visível somente por ferramenta de mensagem, o agente retransmite o + resultado pela ferramenta de mensagem em vez de o OpenClaw publicá-lo diretamente. Enquanto um trabalho está em andamento, chamadas duplicadas de `video_generate` na mesma -sessão retornam o status da tarefa atual em vez de iniciar outra +sessão retornam o status atual da tarefa em vez de iniciar outra geração. Use `openclaw tasks list` ou `openclaw tasks show ` para verificar o progresso pela CLI. -Fora de execuções de agente com sessão de apoio (por exemplo, invocações diretas de ferramentas), -a ferramenta recorre à geração em linha e retorna o caminho da mídia final +Fora de execuções de agente com sessão (por exemplo, invocações diretas de ferramenta), +a ferramenta recorre à geração inline e retorna o caminho final da mídia no mesmo turno. Arquivos de vídeo gerados são salvos no armazenamento de mídia gerenciado pelo OpenClaw quando o provedor retorna bytes. O limite padrão de salvamento de vídeos gerados segue o limite de mídia de vídeo, e `agents.defaults.mediaMaxMb` o aumenta para renderizações maiores. Quando um provedor também retorna uma URL de saída hospedada, o OpenClaw -pode entregar essa URL em vez de falhar a tarefa se a persistência local -rejeitar um arquivo grande demais. +pode entregar essa URL em vez de falhar a tarefa caso a persistência local +rejeite um arquivo grande demais. ### Ciclo de vida da tarefa -| Estado | Significado | -| ----------- | ------------------------------------------------------------------------------------------------ | -| `queued` | Tarefa criada, aguardando o provedor aceitá-la. | +| Estado | Significado | +| ----------- | ---------------------------------------------------------------------------------------------------- | +| `queued` | Tarefa criada, aguardando o provedor aceitá-la. | | `running` | O provedor está processando (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). | -| `succeeded` | Vídeo pronto; o agente desperta e o publica na conversa. | -| `failed` | Erro ou tempo limite do provedor; o agente desperta com detalhes do erro. | +| `succeeded` | Vídeo pronto; o agente desperta e o publica na conversa. | +| `failed` | Erro ou timeout do provedor; o agente desperta com detalhes do erro. | Verifique o status pela CLI: @@ -105,55 +107,55 @@ openclaw tasks cancel ``` Se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual, -`video_generate` retorna o status da tarefa existente em vez de iniciar uma nova +`video_generate` retornará o status da tarefa existente em vez de iniciar uma nova tarefa. Use `action: "status"` para verificar explicitamente sem acionar uma nova geração. ## Provedores compatíveis -| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação | -| --------------------- | ------------------------------ | :---: | -------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` | -| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via função) | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | -| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance de referência para vídeo | Até 3 vídeos com Seedance de referência para vídeo | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou MiniMax OAuth | -| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` | -| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` | -| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` | -| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` | -| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` | +| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação | +| --------------------- | ------------------------------ | :---: | --------------------------------------------------- | -------------------------------------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via papel) | — | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | +| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance de referência para vídeo | Até 3 vídeos com Seedance de referência para vídeo | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou MiniMax OAuth | +| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` | +| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` | +| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` | +| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` | +| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` | Alguns provedores aceitam variáveis de ambiente de chave de API adicionais ou alternativas. Consulte -as [páginas de provedores](#related) individuais para obter detalhes. +as [páginas dos provedores](#related) individuais para obter detalhes. Execute `video_generate action=list` para inspecionar provedores, modelos e -modos de tempo de execução disponíveis em tempo de execução. +modos de runtime disponíveis em tempo de execução. ### Matriz de capacidades O contrato de modo explícito usado por `video_generate`, testes de contrato e -a varredura compartilhada ao vivo: +a varredura ao vivo compartilhada: -| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Trilhas compartilhadas ao vivo hoje | +| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Trilhas ao vivo compartilhadas hoje | | ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- | | Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas | | BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` | | ComfyUI | ✓ | ✓ | — | Não está na varredura compartilhada; a cobertura específica de workflow fica com os testes do Comfy | | DeepInfra | ✓ | — | — | `generate`; os esquemas de vídeo nativos do DeepInfra são de texto para vídeo no contrato incluído | | fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` somente ao usar Seedance de referência para vídeo | -| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura atual Gemini/Veo baseada em buffer não aceita essa entrada | +| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura Gemini/Veo atual baseada em buffer não aceita essa entrada | | MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` | -| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente precisa de acesso de inpaint/remix do lado do provedor | +| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente precisa de acesso a inpaint/remix no lado do provedor | | OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` | | Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas | -| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` roda somente quando o modelo selecionado é `runway/gen4_aleph` | +| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` executa somente quando o modelo selecionado é `runway/gen4_aleph` | | Together | ✓ | ✓ | — | `generate`, `imageToVideo` | | Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` incluído é somente texto e o `kling` incluído exige uma URL de imagem remota | | xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota | @@ -186,19 +188,19 @@ referência de voz quando o provedor oferece suporte a entradas de áudio. Vários áudios de referência (até 3). -Dicas opcionais de função por posição, paralelas à lista combinada de áudio. +Dicas opcionais de função por posição, paralelas à lista combinada de áudios. Valor canônico: `reference_audio`. As dicas de função são encaminhadas ao provedor como estão. Os valores canônicos vêm da união `VideoGenerationAssetRole`, mas os provedores podem -aceitar strings de função adicionais. Arrays `*Roles` não devem ter mais -entradas do que a lista de referência correspondente; erros de deslocamento -de uma posição falham com uma mensagem clara. Use uma string vazia para -deixar uma posição sem definição. Para xAI, defina toda função de imagem como +aceitar strings de função adicionais. Os arrays `*Roles` não devem ter mais +entradas que a lista de referência correspondente; erros de deslocamento de +uma posição falham com uma mensagem clara. Use uma string vazia para deixar +um slot sem definição. Para xAI, defina todas as funções de imagem como `reference_image` para usar seu modo de geração `reference_images`; omita a -função ou use `first_frame` para imagem-para-vídeo com uma única imagem. +função ou use `first_frame` para imagem para vídeo com uma única imagem. ### Controles de estilo @@ -208,19 +210,19 @@ função ou use `first_frame` para imagem-para-vídeo com uma única imagem. `480P`, `720P`, `768P` ou `1080P`. - Duração alvo em segundos (arredondada para o valor compatível mais próximo do provedor). + Duração-alvo em segundos (arredondada para o valor mais próximo aceito pelo provedor). Dica de tamanho quando o provedor oferece suporte. Habilita áudio gerado na saída quando houver suporte. Diferente de `audioRef*` (entradas). -Alterna a marca d'água do provedor quando houver suporte. +Alterna a marca-d'água do provedor quando houver suporte. -`adaptive` é um sentinela específico do provedor: ele é encaminhado como -está para provedores que declaram `adaptive` em seus recursos (por exemplo, -o BytePlus Seedance o usa para detectar automaticamente a proporção a partir +`adaptive` é um sentinela específico do provedor: ele é encaminhado como está +para provedores que declaram `adaptive` em suas capacidades (por exemplo, o +BytePlus Seedance o usa para detectar automaticamente a proporção a partir das dimensões da imagem de entrada). Provedores que não o declaram expõem o -valor via `details.ignoredOverrides` no resultado da ferramenta para que o +valor via `details.ignoredOverrides` no resultado da ferramenta, para que o descarte fique visível. ### Avançado @@ -230,70 +232,68 @@ descarte fique visível. Substituição de provedor/modelo (por exemplo, `runway/gen4.5`). Dica de nome de arquivo de saída. -Tempo limite opcional da solicitação ao provedor em milissegundos. +Tempo limite opcional da solicitação ao provedor, em milissegundos. - Opções específicas do provedor como objeto JSON (por exemplo, `{"seed": 42, "draft": true}`). + Opções específicas do provedor como um objeto JSON (por exemplo, `{"seed": 42, "draft": true}`). Provedores que declaram um esquema tipado validam as chaves e os tipos; chaves - desconhecidas ou incompatibilidades ignoram o candidato durante o fallback. - Provedores sem um esquema declarado recebem as opções como estão. Execute - `video_generate action=list` para ver o que cada provedor aceita. + desconhecidas ou incompatibilidades pulam o candidato durante o fallback. Provedores sem um + esquema declarado recebem as opções como estão. Execute `video_generate action=list` + para ver o que cada provedor aceita. -Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw -normaliza a duração para o valor compatível mais próximo do provedor e -remapeia dicas de geometria traduzidas, como tamanho-para-proporção, quando -um provedor de fallback expõe uma superfície de controle diferente. -Substituições realmente sem suporte são ignoradas com base no melhor esforço -e relatadas como avisos no resultado da ferramenta. Limites rígidos de -recurso (como excesso de entradas de referência) falham antes do envio. Os -resultados da ferramenta relatam as configurações aplicadas; -`details.normalization` captura qualquer tradução de solicitado-para-aplicado. +Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw normaliza a duração para +o valor mais próximo aceito pelo provedor e remapeia dicas de geometria traduzidas, +como tamanho para proporção, quando um provedor de fallback expõe uma +superfície de controle diferente. Substituições realmente sem suporte são ignoradas em regime de melhor esforço +e relatadas como avisos no resultado da ferramenta. Limites rígidos de capacidade +(como excesso de entradas de referência) falham antes do envio. Os resultados da ferramenta +relatam as configurações aplicadas; `details.normalization` captura qualquer +tradução de solicitado para aplicado. -Entradas de referência selecionam o modo de runtime: +As entradas de referência selecionam o modo de runtime: - Nenhuma mídia de referência → `generate` - Qualquer referência de imagem → `imageToVideo` - Qualquer referência de vídeo → `videoToVideo` -- Entradas de áudio de referência **não** alteram o modo resolvido; elas são - aplicadas sobre qualquer modo selecionado pelas referências de imagem/vídeo - e funcionam apenas com provedores que declaram `maxInputAudios`. +- Entradas de áudio de referência **não** alteram o modo resolvido; elas se aplicam sobre + qualquer modo selecionado pelas referências de imagem/vídeo e só funcionam + com provedores que declaram `maxInputAudios`. -Referências mistas de imagem e vídeo não são uma superfície de recurso -compartilhada estável. Prefira um tipo de referência por solicitação. +Referências mistas de imagem e vídeo não são uma superfície de capacidade compartilhada estável. +Prefira um tipo de referência por solicitação. #### Fallback e opções tipadas -Algumas verificações de recurso são aplicadas na camada de fallback em vez -de no limite da ferramenta, portanto uma solicitação que excede os limites -do provedor primário ainda pode ser executada em um fallback capaz: +Algumas verificações de capacidade são aplicadas na camada de fallback, em vez de na +fronteira da ferramenta, portanto uma solicitação que excede os limites do provedor primário ainda pode +ser executada em um fallback capaz: -- Candidato ativo que não declara `maxInputAudios` (ou declara `0`) é ignorado - quando a solicitação contém referências de áudio; o próximo candidato é tentado. -- `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds` - solicitado sem uma lista `supportedDurationSeconds` declarada → ignorado. -- A solicitação contém `providerOptions` e o candidato ativo declara - explicitamente um esquema tipado `providerOptions` → ignorado se as chaves - fornecidas não estiverem no esquema ou se os tipos de valor não corresponderem. - Provedores sem um esquema declarado recebem as opções como estão - (repasse compatível com versões anteriores). Um provedor pode recusar todas - as opções de provedor declarando um esquema vazio (`capabilities.providerOptions: {}`), - o que causa o mesmo salto de uma incompatibilidade de tipo. +- O candidato ativo que não declara `maxInputAudios` (ou declara `0`) é pulado quando + a solicitação contém referências de áudio; o próximo candidato é tentado. +- O `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds` solicitado + sem uma lista `supportedDurationSeconds` declarada → pulado. +- A solicitação contém `providerOptions` e o candidato ativo declara explicitamente + um esquema tipado de `providerOptions` → pulado se as chaves fornecidas + não estiverem no esquema ou se os tipos dos valores não corresponderem. Provedores sem um + esquema declarado recebem as opções como estão (passagem direta compatível + com versões anteriores). Um provedor pode optar por não aceitar nenhuma opção de provedor + declarando um esquema vazio (`capabilities.providerOptions: {}`), o que + causa o mesmo pulo que uma incompatibilidade de tipo. -O primeiro motivo de salto em uma solicitação é registrado em `warn` para -que operadores vejam quando o provedor primário foi preterido; saltos -subsequentes são registrados em `debug` para manter cadeias longas de -fallback silenciosas. Se todos os candidatos forem ignorados, o erro agregado -inclui o motivo do salto de cada um. +O primeiro motivo de pulo em uma solicitação é registrado em `warn` para que operadores vejam quando +seu provedor primário foi preterido; pulos subsequentes são registrados em `debug` para +manter cadeias longas de fallback silenciosas. Se todos os candidatos forem pulados, o +erro agregado incluirá o motivo de pulo de cada um. ## Ações -| Ação | O que faz | -| ---------- | ---------------------------------------------------------------------------------------------------------- | -| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. | -| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. | -| `list` | Mostra provedores, modelos e seus recursos disponíveis. | +| Ação | O que faz | +| ---------- | -------------------------------------------------------------------------------------------------------- | +| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. | +| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. | +| `list` | Mostra provedores, modelos e suas capacidades disponíveis. | ## Seleção de modelo @@ -303,13 +303,14 @@ O OpenClaw resolve o modelo nesta ordem: 2. **`videoGenerationModel.primary`** da configuração. 3. **`videoGenerationModel.fallbacks`** em ordem. 4. **Detecção automática** — provedores que têm autenticação válida, começando pelo - provedor padrão atual e depois pelos provedores restantes em ordem alfabética. + provedor padrão atual e depois os provedores restantes em ordem + alfabética. -Se um provedor falhar, o próximo candidato é tentado automaticamente. Se -todos os candidatos falharem, o erro inclui detalhes de cada tentativa. +Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos +os candidatos falharem, o erro incluirá detalhes de cada tentativa. Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` para usar -apenas as entradas explícitas `model`, `primary` e `fallbacks`. +apenas as entradas explícitas de `model`, `primary` e `fallbacks`. ```json5 { @@ -324,12 +325,12 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`. } ``` -## Notas de provedores +## Observações dos provedores - Usa o endpoint assíncrono do DashScope / Model Studio. Imagens e - vídeos de referência devem ser URLs `http(s)` remotas. + Usa o endpoint assíncrono DashScope / Model Studio. Imagens e + vídeos de referência devem ser URLs remotas `http(s)`. ID do provedor: `byteplus`. @@ -339,12 +340,12 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`. `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Modelos T2V (`*-t2v-*`) não aceitam entradas de imagem; modelos I2V e - modelos gerais `*-pro-*` oferecem suporte a uma única imagem de - referência (primeiro quadro). Passe a imagem posicionalmente ou defina - `role: "first_frame"`. IDs de modelo T2V são alternados automaticamente - para a variante I2V correspondente quando uma imagem é fornecida. + modelos gerais `*-pro-*` oferecem suporte a uma única imagem de referência (primeiro + frame). Passe a imagem posicionalmente ou defina `role: "first_frame"`. + IDs de modelo T2V são trocados automaticamente para a variante I2V + correspondente quando uma imagem é fornecida. - Chaves `providerOptions` compatíveis: `seed` (número), `draft` (booleano — + Chaves de `providerOptions` compatíveis: `seed` (número), `draft` (booleano — força 480p), `camera_fixed` (booleano). @@ -353,14 +354,14 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`. ID do provedor: `byteplus-seedance15`. Modelo: `seedance-1-5-pro-251215`. - Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens - de entrada (`first_frame` + `last_frame`). Todas as entradas devem ser - URLs `https://` remotas. Defina `role: "first_frame"` / `"last_frame"` - em cada imagem, ou passe imagens posicionalmente. + Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens de entrada + (`first_frame` + `last_frame`). Todas as entradas devem ser URLs remotas `https://`. + Defina `role: "first_frame"` / `"last_frame"` em cada imagem, ou + passe as imagens posicionalmente. - `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir - da imagem de entrada. `audio: true` é mapeado para `generate_audio`. - `providerOptions.seed` (número) é encaminhado. + `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. + `audio: true` mapeia para `generate_audio`. `providerOptions.seed` + (número) é encaminhado. @@ -369,32 +370,32 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`. `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. - Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de - referência, 3 vídeos de referência e 3 áudios de referência. Todas as - entradas devem ser URLs `https://` remotas. Defina `role` em cada ativo — - valores compatíveis: `"first_frame"`, `"last_frame"`, `"reference_image"`, + Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de referência, + 3 vídeos de referência e 3 áudios de referência. Todas as entradas devem ser URLs remotas + `https://`. Defina `role` em cada ativo — valores compatíveis: + `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. - `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir - da imagem de entrada. `audio: true` é mapeado para `generate_audio`. - `providerOptions.seed` (número) é encaminhado. + `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. + `audio: true` mapeia para `generate_audio`. `providerOptions.seed` + (número) é encaminhado. - Execução local ou em nuvem orientada por workflow. Oferece suporte a - texto-para-vídeo e imagem-para-vídeo pelo grafo configurado. + Execução local ou em nuvem orientada por workflow. Oferece suporte a texto para vídeo e + imagem para vídeo por meio do grafo configurado. - Usa um fluxo com fila para tarefas de longa duração. A maioria dos - modelos de vídeo da fal aceita uma única referência de imagem. Modelos - Seedance 2.0 de referência-para-vídeo aceitam até 9 imagens, 3 vídeos e - 3 referências de áudio, com no máximo 12 arquivos de referência no total. + Usa um fluxo baseado em fila para jobs de longa duração. A maioria dos modelos de vídeo da fal + aceita uma única referência de imagem. Modelos de referência para vídeo do Seedance 2.0 + aceitam até 9 imagens, 3 vídeos e 3 referências de áudio, com + no máximo 12 arquivos de referência no total. Oferece suporte a uma referência de imagem ou uma referência de vídeo. - Apenas referência de imagem única. + Apenas uma única referência de imagem. Apenas a substituição `size` é encaminhada. Outras substituições de estilo @@ -402,39 +403,41 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`. um aviso. - Usa a API assíncrona `/videos` do OpenRouter. O OpenClaw envia a tarefa, - consulta `polling_url` e baixa `unsigned_urls` ou o endpoint documentado - de conteúdo da tarefa. O padrão incluído `google/veo-3.1-fast` anuncia - durações de 4/6/8 segundos, resoluções `720P`/`1080P` e proporções - `16:9`/`9:16`. + Usa a API assíncrona `/videos` do OpenRouter. O OpenClaw envia o + job, consulta `polling_url` e baixa `unsigned_urls` ou o + endpoint de conteúdo de job documentado. O padrão incluído `google/veo-3.1-fast` + anuncia durações de 4/6/8 segundos, resoluções `720P`/`1080P` e + proporções `16:9`/`9:16`. - Mesmo backend DashScope da Alibaba. Entradas de referência devem ser - URLs `http(s)` remotas; arquivos locais são rejeitados antecipadamente. + Mesmo backend DashScope que o Alibaba. Entradas de referência devem ser URLs remotas + `http(s)`; arquivos locais são rejeitados antecipadamente. - Oferece suporte a arquivos locais via URIs de dados. Vídeo-para-vídeo - requer `runway/gen4_aleph`. Execuções somente texto expõem proporções + Oferece suporte a arquivos locais via URIs de dados. Vídeo para vídeo requer + `runway/gen4_aleph`. Execuções somente texto expõem proporções `16:9` e `9:16`. - Apenas referência de imagem única. + Apenas uma única referência de imagem. Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos - que descartam autenticação. `veo3` é incluído apenas como texto-para-vídeo; - `kling` requer uma URL de imagem remota. + que descartam autenticação. `veo3` é incluído apenas como texto para vídeo; `kling` requer + uma URL de imagem remota. - Oferece suporte a texto-para-vídeo, imagem-para-vídeo com um único primeiro - quadro, até 7 entradas `reference_image` por meio de `reference_images` - da xAI, e fluxos remotos de edição/extensão de vídeo. + Oferece suporte a texto para vídeo, imagem para vídeo com uma única imagem de primeiro frame, até 7 + entradas `reference_image` por meio de `reference_images` da xAI e fluxos remotos + de edição/extensão de vídeo. -## Modos de recursos do provedor +## Modos de capacidade dos provedores -O contrato compartilhado de geração de vídeo oferece suporte a recursos específicos por modo em vez de apenas limites agregados planos. Novas implementações de provedor devem preferir blocos de modo explícitos: +O contrato compartilhado de geração de vídeo oferece suporte a recursos específicos por modo +em vez de apenas limites agregados planos. Novas implementações de provedores +devem preferir blocos de modo explícitos: ```typescript capabilities: { @@ -459,42 +462,55 @@ capabilities: { } ``` -Campos agregados planos como `maxInputImages` e `maxInputVideos` **não** são suficientes para anunciar suporte ao modo de transformação. Os provedores devem declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes ao vivo, testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte a modos de forma determinística. +Campos agregados planos como `maxInputImages` e `maxInputVideos` +**não** são suficientes para anunciar suporte a modos de transformação. Provedores devem +declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes +ao vivo, testes de contrato e a ferramenta compartilhada `video_generate` possam validar +o suporte a modos de forma determinística. -Quando um modelo em um provedor tiver suporte mais amplo a entradas de referência do que os demais, use `maxInputImagesByModel`, `maxInputVideosByModel` ou `maxInputAudiosByModel` em vez de aumentar o limite de todo o modo. +Quando um modelo em um provedor tiver suporte mais amplo a entradas de referência do que o +restante, use `maxInputImagesByModel`, `maxInputVideosByModel` ou +`maxInputAudiosByModel` em vez de aumentar o limite de todo o modo. ## Testes ao vivo -Cobertura ao vivo opcional para os provedores compartilhados incluídos: +Cobertura ao vivo opcional para os provedores agrupados compartilhados: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts ``` -Encapsulador do repositório: +Wrapper do repositório: ```bash pnpm test:live:media video ``` -Este arquivo ao vivo carrega variáveis de ambiente de provedor ausentes de `~/.profile`, por padrão prefere chaves de API ao vivo/de ambiente antes de perfis de autenticação armazenados e executa um smoke seguro para release por padrão: +Este arquivo ao vivo carrega variáveis de ambiente ausentes de provedores a partir de `~/.profile`, prefere +chaves de API ao vivo/do ambiente antes de perfis de autenticação armazenados por padrão e executa um +smoke test seguro para lançamento por padrão: -- `generate` para cada provedor não FAL na varredura. +- `generate` para todos os provedores não FAL na varredura. - Prompt de lagosta de um segundo. -- Limite de operação por provedor de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão). +- Limite de operação por provedor a partir de + `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão). -FAL é opcional porque a latência da fila do lado do provedor pode dominar o tempo de release: +FAL é opcional porque a latência da fila do lado do provedor pode dominar o tempo de lançamento: ```bash pnpm test:live:media video --video-providers fal ``` -Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados que a varredura compartilhada pode exercitar com segurança com mídia local: +Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de +transformação declarados que a varredura compartilhada pode exercitar com segurança com mídia local: - `imageToVideo` quando `capabilities.imageToVideo.enabled`. -- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo aceita entrada de vídeo local baseada em buffer na varredura compartilhada. +- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o + provedor/modelo aceita entrada de vídeo local baseada em buffer na varredura + compartilhada. -Hoje, a faixa ao vivo compartilhada de `videoToVideo` cobre `runway` somente quando você seleciona `runway/gen4_aleph`. +Hoje, a faixa ao vivo compartilhada de `videoToVideo` cobre apenas `runway` quando você +seleciona `runway/gen4_aleph`. ## Configuração @@ -513,7 +529,7 @@ Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw } ``` -Ou pela CLI: +Ou via CLI: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" @@ -522,7 +538,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Relacionados - [Alibaba Model Studio](/pt-BR/providers/alibaba) -- [Tarefas em segundo plano](/pt-BR/automation/tasks) — acompanhamento de tarefas para geração assíncrona de vídeo +- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para geração de vídeo assíncrona - [BytePlus](/pt-BR/concepts/model-providers#byteplus-international) - [ComfyUI](/pt-BR/providers/comfy) - [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) diff --git a/docs/pt-BR/web/dashboard.md b/docs/pt-BR/web/dashboard.md index e7aef7d35..bfa426ef4 100644 --- a/docs/pt-BR/web/dashboard.md +++ b/docs/pt-BR/web/dashboard.md @@ -1,18 +1,18 @@ --- read_when: - - Alterando modos de autenticação ou exposição do painel -summary: Acesso e autenticação do painel do Gateway (Control UI) + - Alteração da autenticação ou dos modos de exposição do painel +summary: Acesso e autenticação do painel do Gateway (interface de controle) title: Painel x-i18n: - generated_at: "2026-04-25T13:58:52Z" - model: gpt-5.4 + generated_at: "2026-05-05T01:50:50Z" + model: gpt-5.5 provider: openai - source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a + source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1 source_path: web/dashboard.md - workflow: 15 + workflow: 16 --- -O painel do Gateway é o Control UI no navegador servido em `/` por padrão +O painel do Gateway é a Interface de Controle no navegador servida em `/` por padrão (substitua com `gateway.controlUi.basePath`). Abertura rápida (Gateway local): @@ -23,87 +23,91 @@ Abertura rápida (Gateway local): Referências principais: -- [Control UI](/pt-BR/web/control-ui) para uso e recursos da UI. +- [Interface de Controle](/pt-BR/web/control-ui) para uso e recursos da UI. - [Tailscale](/pt-BR/gateway/tailscale) para automação de Serve/Funnel. -- [Superfícies web](/pt-BR/web) para modos de bind e observações de segurança. +- [Superfícies Web](/pt-BR/web) para modos de bind e notas de segurança. -A autenticação é aplicada no handshake do WebSocket pelo caminho de autenticação -configurado do gateway: +A autenticação é aplicada no handshake WebSocket pelo caminho de autenticação do gateway +configurado: - `connect.params.auth.token` - `connect.params.auth.password` -- Cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true` -- Cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"` +- cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true` +- cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"` -Consulte `gateway.auth` em [Configuração do Gateway](/pt-BR/gateway/configuration). +Veja `gateway.auth` em [Configuração do Gateway](/pt-BR/gateway/configuration). -Observação de segurança: o Control UI é uma **superfície administrativa** (chat, configuração, aprovações de exec). -Não o exponha publicamente. A UI mantém tokens de URL do painel em `sessionStorage` +Nota de segurança: a Interface de Controle é uma **superfície de administração** (chat, configuração, aprovações de execução). +Não a exponha publicamente. A UI mantém tokens de URL do painel em sessionStorage para a sessão atual da aba do navegador e a URL do gateway selecionada, e os remove da URL após o carregamento. Prefira localhost, Tailscale Serve ou um túnel SSH. ## Caminho rápido (recomendado) -- Após o onboarding, a CLI abre automaticamente o painel e imprime um link limpo (sem token). -- Reabra a qualquer momento: `openclaw dashboard` (copia o link, abre o navegador se possível, mostra dica de SSH se estiver em modo headless). +- Após a integração inicial, a CLI abre automaticamente o painel e imprime um link limpo (sem token). +- Reabra a qualquer momento: `openclaw dashboard` (copia o link, abre o navegador se possível, mostra dica de SSH se estiver sem interface gráfica). +- Se a entrega por área de transferência e navegador falhar, `openclaw dashboard` ainda imprime a + URL limpa e informa para usar o token de `OPENCLAW_GATEWAY_TOKEN` ou + `gateway.auth.token` como a chave de fragmento de URL `token`; ele não imprime valores de token + nos logs. - Se a UI solicitar autenticação por segredo compartilhado, cole o token ou - a senha configurados nas configurações do Control UI. + a senha configurados nas configurações da Interface de Controle. ## Noções básicas de autenticação (local vs remoto) - **Localhost**: abra `http://127.0.0.1:18789/`. - **TLS do Gateway**: quando `gateway.tls.enabled: true`, links de painel/status usam - `https://` e links WebSocket do Control UI usam `wss://`. + `https://` e links WebSocket da Interface de Controle usam `wss://`. - **Origem do token de segredo compartilhado**: `gateway.auth.token` (ou - `OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` pode passá-lo por fragmento de URL - para bootstrap único, e o Control UI o mantém em `sessionStorage` para a - sessão atual da aba do navegador e a URL do gateway selecionada, em vez de `localStorage`. + `OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` pode passá-lo via fragmento de URL + para bootstrap único, e a Interface de Controle o mantém em sessionStorage para a + sessão atual da aba do navegador e a URL do gateway selecionada em vez de localStorage. - Se `gateway.auth.token` for gerenciado por SecretRef, `openclaw dashboard` imprime/copia/abre uma URL sem token por design. Isso evita expor - tokens gerenciados externamente em logs do shell, histórico da área de transferência ou argumentos - de inicialização do navegador. -- Se `gateway.auth.token` estiver configurado como um SecretRef e não for resolvido no seu + tokens gerenciados externamente em logs do shell, histórico da área de transferência ou argumentos de + inicialização do navegador. +- Se `gateway.auth.token` estiver configurado como SecretRef e não for resolvido no seu shell atual, `openclaw dashboard` ainda imprime uma URL sem token mais - orientações práticas de configuração de autenticação. -- **Senha de segredo compartilhado**: use a `gateway.auth.password` configurada (ou + orientações acionáveis de configuração de autenticação. +- **Senha de segredo compartilhado**: use o `gateway.auth.password` configurado (ou `OPENCLAW_GATEWAY_PASSWORD`). O painel não persiste senhas entre recarregamentos. -- **Modos com identidade**: o Tailscale Serve pode satisfazer a autenticação do Control UI/WebSocket - por cabeçalhos de identidade quando `gateway.auth.allowTailscale: true`, e um - proxy reverso com reconhecimento de identidade fora de loopback pode satisfazer +- **Modos com identidade**: Tailscale Serve pode satisfazer a autenticação da Interface de Controle/WebSocket + via cabeçalhos de identidade quando `gateway.auth.allowTailscale: true`, e um + proxy reverso com reconhecimento de identidade que não seja loopback pode satisfazer `gateway.auth.mode: "trusted-proxy"`. Nesses modos, o painel não precisa de um segredo compartilhado colado para o WebSocket. -- **Não localhost**: use Tailscale Serve, um bind fora de loopback com segredo compartilhado, um - proxy reverso fora de loopback com reconhecimento de identidade e - `gateway.auth.mode: "trusted-proxy"`, ou um túnel SSH. As APIs HTTP ainda usam - autenticação por segredo compartilhado, a menos que você execute intencionalmente um ingresso privado com - `gateway.auth.mode: "none"` ou autenticação HTTP trusted-proxy. Consulte - [Superfícies web](/pt-BR/web). +- **Não localhost**: use Tailscale Serve, um bind de segredo compartilhado que não seja loopback, um + proxy reverso com reconhecimento de identidade que não seja loopback com + `gateway.auth.mode: "trusted-proxy"` ou um túnel SSH. APIs HTTP ainda usam + autenticação por segredo compartilhado, a menos que você execute intencionalmente + `gateway.auth.mode: "none"` com private-ingress ou autenticação HTTP por proxy confiável. Veja + [Superfícies Web](/pt-BR/web). ## Se você vir "unauthorized" / 1008 -- Verifique se o gateway está acessível (local: `openclaw status`; remoto: túnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` e depois abra `http://127.0.0.1:18789/`). -- Para `AUTH_TOKEN_MISMATCH`, os clientes podem fazer uma nova tentativa confiável com um token de dispositivo em cache quando o gateway retorna dicas de nova tentativa. Essa nova tentativa com token em cache reutiliza os escopos aprovados em cache do token; chamadores com `deviceToken` explícito / `scopes` explícitos mantêm seu conjunto de escopos solicitado. Se a autenticação ainda falhar após essa nova tentativa, resolva manualmente a divergência de token. -- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é token/senha compartilhados explícitos primeiro, depois `deviceToken` explícito, depois token de dispositivo armazenado e, por fim, token de bootstrap. -- No caminho assíncrono do Control UI via Tailscale Serve, tentativas com falha para o mesmo - `{scope, ip}` são serializadas antes de o limitador de autenticação com falha registrá-las, então - a segunda nova tentativa ruim concorrente já pode mostrar `retry later`. -- Para etapas de reparo de divergência de token, siga a [Checklist de recuperação de divergência de token](/pt-BR/cli/devices#token-drift-recovery-checklist). +- Garanta que o gateway esteja acessível (local: `openclaw status`; remoto: túnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` e então abra `http://127.0.0.1:18789/`). +- Para `AUTH_TOKEN_MISMATCH`, clientes podem fazer uma nova tentativa confiável com um token de dispositivo em cache quando o gateway retorna dicas de nova tentativa. Essa nova tentativa com token em cache reutiliza os escopos aprovados em cache do token; chamadores com `deviceToken` explícito / `scopes` explícitos mantêm o conjunto de escopos solicitado. Se a autenticação ainda falhar após essa nova tentativa, resolva a divergência de token manualmente. +- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é primeiro token/senha compartilhados explícitos, depois `deviceToken` explícito, depois token de dispositivo armazenado, depois token de bootstrap. +- No caminho assíncrono da Interface de Controle via Tailscale Serve, tentativas com falha para o mesmo + `{scope, ip}` são serializadas antes que o limitador de autenticação com falha as registre, então + a segunda nova tentativa incorreta simultânea já pode mostrar `retry later`. +- Para etapas de reparo de divergência de token, siga a [lista de verificação de recuperação de divergência de token](/pt-BR/cli/devices#token-drift-recovery-checklist). - Recupere ou forneça o segredo compartilhado a partir do host do gateway: - Token: `openclaw config get gateway.auth.token` - - Senha: resolva a `gateway.auth.password` configurada ou + - Senha: resolva o `gateway.auth.password` configurado ou `OPENCLAW_GATEWAY_PASSWORD` - Token gerenciado por SecretRef: resolva o provedor de segredo externo ou exporte - `OPENCLAW_GATEWAY_TOKEN` neste shell e depois execute `openclaw dashboard` novamente + `OPENCLAW_GATEWAY_TOKEN` neste shell, então execute novamente `openclaw dashboard` - Nenhum segredo compartilhado configurado: `openclaw doctor --generate-gateway-token` -- Nas configurações do painel, cole o token ou a senha no campo de autenticação - e depois conecte. -- O seletor de idioma da UI está em **Overview -> Gateway Access -> Language**. - Ele faz parte do cartão de acesso, não da seção Appearance. +- Nas configurações do painel, cole o token ou a senha no campo de autenticação, + então conecte. +- O seletor de idioma da UI fica em **Visão geral -> Acesso ao Gateway -> Idioma**. + Ele faz parte do cartão de acesso, não da seção Aparência. -## Relacionado +## Relacionados -- [Control UI](/pt-BR/web/control-ui) +- [Interface de Controle](/pt-BR/web/control-ui) - [WebChat](/pt-BR/web/webchat)