From dfd84aba5a52712aad1df5774838467b70636fd0 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 4 May 2026 07:06:03 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/channels/discord.md | 455 +++++++------- docs/pt-BR/channels/slack.md | 419 +++++++------ docs/pt-BR/channels/telegram.md | 455 +++++++------- docs/pt-BR/cli/sessions.md | 32 +- docs/pt-BR/concepts/messages.md | 132 ++-- docs/pt-BR/concepts/streaming.md | 202 +++--- docs/pt-BR/help/testing.md | 742 +++++++++++----------- docs/pt-BR/plugins/google-meet.md | 968 ++++++++++++++--------------- docs/pt-BR/providers/elevenlabs.md | 78 +-- docs/pt-BR/reference/RELEASING.md | 670 +++++++++----------- docs/pt-BR/web/control-ui.md | 274 ++++---- 11 files changed, 2222 insertions(+), 2205 deletions(-) diff --git a/docs/pt-BR/channels/discord.md b/docs/pt-BR/channels/discord.md index 311507b1e..90da36f1c 100644 --- a/docs/pt-BR/channels/discord.md +++ b/docs/pt-BR/channels/discord.md @@ -1,44 +1,44 @@ --- read_when: - Trabalhando em recursos de canais do Discord -summary: Status do suporte a robôs do Discord, capacidades e configuração +summary: Status de suporte, capacidades e configuração do bot do Discord title: Discord x-i18n: - generated_at: "2026-05-04T02:21:22Z" + generated_at: "2026-05-04T07:02:45Z" model: gpt-5.5 provider: openai - source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 + source_hash: 1e00f9d9b134296ac1ca52bb4058fc62ea7a95c4d46d9478648b2ecdd448652a source_path: channels/discord.md workflow: 16 --- -Pronto para DMs e canais de guild via o Gateway oficial do Discord. +Pronto para DMs e canais de guild pelo Gateway oficial do Discord. - As DMs do Discord usam o modo de pareamento por padrão. + DMs do Discord usam o modo de pareamento por padrão. - Comportamento nativo dos comandos e catálogo de comandos. + Comportamento nativo de comandos e catálogo de comandos. - Diagnóstico entre canais e fluxo de reparo. + Diagnósticos entre canais e fluxo de reparo. ## Configuração rápida -Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu servidor e pareá-lo com o OpenClaw. Recomendamos adicionar seu bot ao seu próprio servidor privado. Se você ainda não tiver um, [crie um primeiro](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (escolha **Create My Own > For me and my friends**). +Você precisará criar uma nova aplicação com um bot, adicionar o bot ao seu servidor e pareá-lo com o OpenClaw. Recomendamos adicionar seu bot ao seu próprio servidor privado. Se você ainda não tiver um, [crie um primeiro](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (escolha **Create My Own > For me and my friends**). - - Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e clique em **New Application**. Dê a ele um nome como "OpenClaw". + + Acesse o [Discord Developer Portal](https://discord.com/developers/applications) e clique em **New Application**. Dê a ela um nome como "OpenClaw". - Clique em **Bot** na barra lateral. Defina o **Username** como o nome que você dá ao seu agente OpenClaw. + Clique em **Bot** na barra lateral. Defina o **Username** como o nome que você usa para seu agente OpenClaw. - + Ainda na página **Bot**, role para baixo até **Privileged Gateway Intents** e ative: - **Message Content Intent** (obrigatório) @@ -47,18 +47,18 @@ Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu ser - + Role de volta para cima na página **Bot** e clique em **Reset Token**. Apesar do nome, isso gera seu primeiro token — nada está sendo "redefinido". - Copie o token e salve-o em algum lugar. Este é o seu **Bot Token** e você precisará dele em breve. + Copie o token e salve-o em algum lugar. Este é seu **Bot Token** e você precisará dele em breve. - + Clique em **OAuth2** na barra lateral. Você gerará uma URL de convite com as permissões corretas para adicionar o bot ao seu servidor. Role para baixo até **OAuth2 URL Generator** e ative: @@ -77,31 +77,31 @@ Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu ser - Attach Files - Add Reactions (opcional) - Este é o conjunto básico para canais de texto normais. Se você pretende postar em threads do Discord, incluindo fluxos de canais de fórum ou mídia que criam ou continuam uma thread, ative também **Send Messages in Threads**. + Esse é o conjunto básico para canais de texto normais. Se você planeja publicar em threads do Discord, incluindo fluxos de trabalho de canais de fórum ou mídia que criam ou continuam uma thread, ative também **Send Messages in Threads**. Copie a URL gerada na parte inferior, cole-a no seu navegador, selecione seu servidor e clique em **Continue** para conectar. Agora você deve ver seu bot no servidor Discord. - - De volta ao aplicativo Discord, você precisa ativar o Modo de Desenvolvedor para poder copiar IDs internos. + + De volta ao aplicativo Discord, você precisa ativar o Developer Mode para poder copiar IDs internos. 1. Clique em **User Settings** (ícone de engrenagem ao lado do seu avatar) → **Advanced** → ative **Developer Mode** 2. Clique com o botão direito no **ícone do servidor** na barra lateral → **Copy Server ID** 3. Clique com o botão direito no **seu próprio avatar** → **Copy User ID** - Salve seu **Server ID** e **User ID** junto com seu Bot Token — você enviará os três para o OpenClaw na próxima etapa. + Salve seu **Server ID** e **User ID** junto com seu Bot Token — você enviará os três ao OpenClaw na próxima etapa. - - Para que o pareamento funcione, o Discord precisa permitir que seu bot envie DM para você. Clique com o botão direito no **ícone do servidor** → **Privacy Settings** → ative **Direct Messages**. + + Para o pareamento funcionar, o Discord precisa permitir que seu bot envie DM para você. Clique com o botão direito no **ícone do servidor** → **Privacy Settings** → ative **Direct Messages**. - Isso permite que membros do servidor (incluindo bots) enviem DMs para você. Mantenha isso ativado se quiser usar DMs do Discord com o OpenClaw. Se você pretende usar apenas canais de guild, pode desativar DMs após o pareamento. + Isso permite que membros do servidor (incluindo bots) enviem DMs para você. Mantenha isso ativado se quiser usar DMs do Discord com o OpenClaw. Se você planeja usar apenas canais de guild, pode desativar DMs depois do pareamento. - - Seu token de bot do Discord é um segredo (como uma senha). Defina-o na máquina que executa o OpenClaw antes de enviar mensagens ao seu agente. + + Seu token de bot do Discord é um segredo (como uma senha). Defina-o na máquina que executa o OpenClaw antes de enviar mensagem ao seu agente. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,22 +120,22 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - Se o OpenClaw já estiver em execução como um serviço em segundo plano, reinicie-o pelo aplicativo OpenClaw para Mac ou parando e reiniciando o processo `openclaw gateway run`. - Para instalações de serviço gerenciado, execute `openclaw gateway install` a partir de um shell onde `DISCORD_BOT_TOKEN` esteja presente, ou armazene a variável em `~/.openclaw/.env`, para que o serviço possa resolver o env SecretRef após a reinicialização. - Se seu host estiver bloqueado ou com limite de taxa pela consulta de aplicativo na inicialização do Discord, defina o ID do aplicativo/cliente Discord no Portal de Desenvolvedores para que a inicialização possa pular essa chamada REST. Use `channels.discord.applicationId` para a conta padrão, ou `channels.discord.accounts..applicationId` quando você executar vários bots Discord. + Se o OpenClaw já estiver em execução como serviço em segundo plano, reinicie-o pelo app OpenClaw para Mac ou parando e reiniciando o processo `openclaw gateway run`. + Para instalações de serviço gerenciado, execute `openclaw gateway install` em um shell onde `DISCORD_BOT_TOKEN` esteja presente, ou armazene a variável em `~/.openclaw/.env`, para que o serviço possa resolver o SecretRef de env após a reinicialização. + Se seu host estiver bloqueado ou com limite de taxa pela consulta de aplicação de inicialização do Discord, defina o ID da aplicação/cliente do Discord pelo Developer Portal para que a inicialização possa pular essa chamada REST. Use `channels.discord.applicationId` para a conta padrão, ou `channels.discord.accounts..applicationId` quando você executa vários bots do Discord. - + - Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e informe-o. Se Discord for seu primeiro canal, use a aba CLI / config em vez disso. + Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e informe-o. Se o Discord for seu primeiro canal, use a aba CLI / config. > "Já defini meu token de bot do Discord na configuração. Conclua a configuração do Discord com User ID `` e Server ID ``." - Se você preferir configuração baseada em arquivo, defina: + Se você prefere configuração baseada em arquivo, defina: ```json5 { @@ -158,9 +158,9 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Para configuração via script ou remota, escreva o mesmo bloco JSON5 com `openclaw config patch --file ./discord.patch.json5 --dry-run` e depois execute novamente sem `--dry-run`. Valores `token` em texto simples são compatíveis. Valores SecretRef também são compatíveis para `channels.discord.token` entre provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). + Para configuração por script ou remota, grave o mesmo bloco JSON5 com `openclaw config patch --file ./discord.patch.json5 --dry-run` e depois execute novamente sem `--dry-run`. Valores `token` em texto puro são aceitos. Valores SecretRef também são aceitos para `channels.discord.token` em provedores env/file/exec. Veja [Gerenciamento de segredos](/pt-BR/gateway/secrets). - Para vários bots Discord, mantenha cada token de bot e ID de aplicativo sob sua conta. Um `channels.discord.applicationId` de nível superior é herdado pelas contas, então só o defina ali quando todas as contas devem usar o mesmo ID de aplicativo. + Para vários bots do Discord, mantenha cada token de bot e ID de aplicação em sua conta. Um `channels.discord.applicationId` de nível superior é herdado pelas contas, então só o defina ali quando todas as contas devem usar o mesmo ID de aplicação. ```json5 { @@ -187,12 +187,12 @@ DISCORD_BOT_TOKEN=... - - Aguarde até que o gateway esteja em execução e, em seguida, envie uma DM ao seu bot no Discord. Ele responderá com um código de pareamento. + + Aguarde até que o gateway esteja em execução e então envie uma DM para seu bot no Discord. Ele responderá com um código de pareamento. - Envie o código de pareamento ao seu agente no seu canal existente: + Envie o código de pareamento ao seu agente no canal existente: > "Aprove este código de pareamento do Discord: ``" @@ -214,24 +214,24 @@ openclaw pairing approve discord -A resolução de tokens reconhece contas. Valores de token na configuração têm precedência sobre fallback de env. `DISCORD_BOT_TOKEN` é usado apenas para a conta padrão. -Se duas contas Discord ativadas resolverem para o mesmo token de bot, o OpenClaw inicia apenas um monitor de Gateway para esse token. Um token vindo da configuração tem precedência sobre o fallback de env padrão; caso contrário, a primeira conta ativada tem precedência e a conta duplicada é relatada como desativada. -Para chamadas de saída avançadas (ferramenta de mensagem/ações de canal), um `token` explícito por chamada é usado para essa chamada. Isso se aplica a ações de envio e leitura/sondagem (por exemplo, read/search/fetch/thread/pins/permissions). As configurações de política/tentativa da conta ainda vêm da conta selecionada no snapshot de runtime ativo. +A resolução de token considera a conta. Valores de token na configuração têm prioridade sobre o fallback de env. `DISCORD_BOT_TOKEN` é usado apenas para a conta padrão. +Se duas contas do Discord ativadas resolverem para o mesmo token de bot, o OpenClaw inicia apenas um monitor de gateway para esse token. Um token vindo da configuração tem prioridade sobre o fallback de env padrão; caso contrário, a primeira conta ativada vence e a conta duplicada é relatada como desativada. +Para chamadas outbound avançadas (ferramenta de mensagem/ações de canal), um `token` explícito por chamada é usado nessa chamada. Isso se aplica a ações de envio e leitura/sondagem (por exemplo, read/search/fetch/thread/pins/permissions). As configurações de política de conta/retry ainda vêm da conta selecionada no snapshot de runtime ativo. -## Recomendado: configure um workspace de guild +## Recomendado: configurar um workspace de guild -Depois que as DMs estiverem funcionando, você pode configurar seu servidor Discord como um workspace completo em que cada canal recebe sua própria sessão de agente com seu próprio contexto. Isso é recomendado para servidores privados em que é apenas você e seu bot. +Quando as DMs estiverem funcionando, você poderá configurar seu servidor Discord como um workspace completo, onde cada canal recebe sua própria sessão de agente com seu próprio contexto. Isso é recomendado para servidores privados onde há apenas você e seu bot. - - Isso permite que seu agente responda em qualquer canal do seu servidor, não apenas em DMs. + + Isso permite que seu agente responda em qualquer canal no seu servidor, não apenas em DMs. - > "Adicione meu Server ID do Discord `` à lista de permissões de guild" + > "Adicione meu Discord Server ID `` à lista de permissões de guild" - + ```json5 { @@ -254,18 +254,18 @@ Depois que as DMs estiverem funcionando, você pode configurar seu servidor Disc - + Por padrão, seu agente só responde em canais de guild quando recebe @mention. Para um servidor privado, você provavelmente quer que ele responda a todas as mensagens. - Em canais de guild, respostas finais normais do assistente permanecem privadas por padrão. A saída visível no Discord deve ser enviada explicitamente com a ferramenta `message`, para que o agente possa observar por padrão e só postar quando decidir que uma resposta no canal é útil. + Em canais de guild, respostas finais normais do assistente permanecem privadas por padrão. A saída visível no Discord deve ser enviada explicitamente com a ferramenta `message`, para que o agente possa observar por padrão e publicar apenas quando decidir que uma resposta no canal é útil. - Isso significa que o modelo selecionado deve chamar ferramentas de forma confiável. Se o Discord mostrar digitação e os logs mostrarem uso de tokens, mas nenhuma mensagem publicada, verifique o log da sessão para texto do assistente com `didSendViaMessagingTool: false`. Isso significa que o modelo produziu uma resposta final privada em vez de chamar `message(action=send)`. Troque para um modelo mais forte em chamadas de ferramenta ou use a configuração abaixo para restaurar respostas finais automáticas legadas. + Isso significa que o modelo selecionado deve chamar ferramentas de forma confiável. Se o Discord mostrar digitação e os logs mostrarem uso de tokens, mas nenhuma mensagem publicada, verifique o log da sessão em busca de texto do assistente com `didSendViaMessagingTool: false`. Isso significa que o modelo produziu uma resposta final privada em vez de chamar `message(action=send)`. Troque para um modelo mais forte em chamadas de ferramenta, ou use a configuração abaixo para restaurar respostas finais automáticas legadas. > "Permita que meu agente responda neste servidor sem precisar receber @mention" - + Defina `requireMention: false` na sua configuração de guild: ```json5 @@ -289,42 +289,42 @@ Depois que as DMs estiverem funcionando, você pode configurar seu servidor Disc - - Por padrão, a memória de longo prazo (MEMORY.md) carrega apenas em sessões de DM. Canais de guild não carregam MEMORY.md automaticamente. + + Por padrão, a memória de longo prazo (MEMORY.md) só é carregada em sessões de DM. Canais de guild não carregam MEMORY.md automaticamente. > "Quando eu fizer perguntas em canais do Discord, use memory_search ou memory_get se precisar de contexto de longo prazo de MEMORY.md." - Se você precisar de contexto compartilhado em todos os canais, coloque as instruções estáveis em `AGENTS.md` ou `USER.md` (elas são injetadas em todas as sessões). Mantenha notas de longo prazo em `MEMORY.md` e acesse-as sob demanda com ferramentas de memória. + Se você precisa de contexto compartilhado em todos os canais, coloque as instruções estáveis em `AGENTS.md` ou `USER.md` (elas são injetadas em todas as sessões). Mantenha notas de longo prazo em `MEMORY.md` e acesse-as sob demanda com ferramentas de memória. -Agora crie alguns canais no seu servidor Discord e comece a conversar. Seu agente consegue ver o nome do canal, e cada canal recebe sua própria sessão isolada — então você pode configurar `#coding`, `#home`, `#research` ou o que se encaixar no seu fluxo de trabalho. +Agora crie alguns canais no seu servidor Discord e comece a conversar. Seu agente pode ver o nome do canal, e cada canal recebe sua própria sessão isolada — então você pode configurar `#coding`, `#home`, `#research` ou o que se ajustar ao seu fluxo de trabalho. ## Modelo de runtime -- O Gateway controla a conexão com o Discord. -- O roteamento de respostas é determinístico: respostas recebidas do Discord retornam ao Discord. -- Metadados de guild/canal do Discord são adicionados ao prompt do modelo como contexto não confiável, não como prefixo de resposta visível ao usuário. Se um modelo copiar esse envelope de volta, o OpenClaw remove os metadados copiados das respostas de saída e do contexto de replay futuro. +- O Gateway é responsável pela conexão do Discord. +- O roteamento de respostas é determinístico: respostas de entrada do Discord voltam para o Discord. +- Metadados de guilda/canal do Discord são adicionados ao prompt do modelo como contexto não confiável, não como um prefixo de resposta visível ao usuário. Se um modelo copiar esse envelope de volta, o OpenClaw remove os metadados copiados das respostas de saída e do contexto de reprodução futuro. - Por padrão (`session.dmScope=main`), conversas diretas compartilham a sessão principal do agente (`agent:main:main`). -- Canais de guild são chaves de sessão isoladas (`agent::discord:channel:`). -- DMs de grupo são ignoradas por padrão (`channels.discord.dm.groupEnabled=false`). +- Canais de guilda são chaves de sessão isoladas (`agent::discord:channel:`). +- DMs em grupo são ignoradas por padrão (`channels.discord.dm.groupEnabled=false`). - Comandos de barra nativos são executados em sessões de comando isoladas (`agent::discord:slash:`), enquanto ainda carregam `CommandTargetSessionKey` para a sessão de conversa roteada. -- A entrega de anúncios de cron/heartbeat somente texto ao Discord usa a resposta final visível ao assistente uma vez. Payloads de mídia e componentes estruturados permanecem como múltiplas mensagens quando o agente emite vários payloads entregáveis. +- A entrega de anúncios de Cron/Heartbeat somente em texto para o Discord usa a resposta final visível ao assistente uma vez. Payloads de mídia e componentes estruturados permanecem em várias mensagens quando o agente emite vários payloads entregáveis. ## Canais de fórum -Canais de fórum e mídia do Discord aceitam apenas posts em threads. O OpenClaw oferece suporte a duas formas de criá-los: +Canais de fórum e mídia do Discord aceitam apenas publicações em threads. O OpenClaw oferece suporte a duas formas de criá-las: -- Envie uma mensagem para o fórum pai (`channel:`) para criar uma thread automaticamente. O título da thread usa a primeira linha não vazia da sua mensagem. +- Envie uma mensagem ao fórum pai (`channel:`) para criar uma thread automaticamente. O título da thread usa a primeira linha não vazia da sua mensagem. - Use `openclaw message thread create` para criar uma thread diretamente. Não passe `--message-id` para canais de fórum. -Exemplo: enviar para o fórum pai para criar uma thread +Exemplo: enviar ao fórum pai para criar uma thread ```bash openclaw message send --channel discord --target channel: \ @@ -338,11 +338,11 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Fóruns pais não aceitam componentes do Discord. Se precisar de componentes, envie para a própria thread (`channel:`). +Fóruns pai não aceitam componentes do Discord. Se você precisar de componentes, envie para a própria thread (`channel:`). ## Componentes interativos -O OpenClaw oferece suporte a contêineres de componentes v2 do Discord para mensagens de agentes. Use a ferramenta de mensagem com um payload `components`. Os resultados de interação são roteados de volta para o agente como mensagens recebidas normais e seguem as configurações existentes de `replyToMode` do Discord. +O OpenClaw oferece suporte a contêineres de componentes v2 do Discord para mensagens de agentes. Use a ferramenta de mensagem com um payload `components`. Resultados de interação são roteados de volta ao agente como mensagens de entrada normais e seguem as configurações existentes de `replyToMode` do Discord. Blocos compatíveis: @@ -354,19 +354,19 @@ Por padrão, componentes são de uso único. Defina `components.reusable=true` p Para restringir quem pode clicar em um botão, defina `allowedUsers` nesse botão (IDs de usuário do Discord, tags ou `*`). Quando configurado, usuários sem correspondência recebem uma negação efêmera. -Os comandos de barra `/model` e `/models` abrem um seletor interativo de modelo com menus suspensos de provedor, modelo e runtime compatível, além de uma etapa Enviar. `/models add` foi descontinuado e agora retorna uma mensagem de descontinuação em vez de registrar modelos pelo chat. A resposta do seletor é efêmera e somente o usuário que a invocou pode usá-la. +Os comandos de barra `/model` e `/models` abrem um seletor interativo de modelo com menus suspensos de provedor, modelo e runtime compatível, além de uma etapa de envio. `/models add` está obsoleto e agora retorna uma mensagem de obsolescência em vez de registrar modelos pelo chat. A resposta do seletor é efêmera e somente o usuário que o invocou pode usá-lo. Anexos de arquivo: - Blocos `file` devem apontar para uma referência de anexo (`attachment://`) -- Forneça o anexo via `media`/`path`/`filePath` (arquivo único); use `media-gallery` para múltiplos arquivos +- Forneça o anexo via `media`/`path`/`filePath` (arquivo único); use `media-gallery` para vários arquivos - Use `filename` para substituir o nome do upload quando ele deve corresponder à referência do anexo Formulários modais: - Adicione `components.modal` com até 5 campos - Tipos de campo: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- O OpenClaw adiciona um botão de disparo automaticamente +- O OpenClaw adiciona um botão de acionamento automaticamente Exemplo: @@ -426,34 +426,34 @@ Exemplo: - `channels.discord.dmPolicy` controla o acesso a DMs. `channels.discord.allowFrom` é a lista de permissões canônica para DMs. + `channels.discord.dmPolicy` controla o acesso por DM. `channels.discord.allowFrom` é a allowlist canônica de DMs. - `pairing` (padrão) - `allowlist` - `open` (exige que `channels.discord.allowFrom` inclua `"*"`) - `disabled` - Se a política de DM não estiver aberta, usuários desconhecidos são bloqueados (ou recebem solicitação de pareamento no modo `pairing`). + Se a política de DM não estiver aberta, usuários desconhecidos são bloqueados (ou solicitados a parear no modo `pairing`). - Precedência de múltiplas contas: + Precedência de várias contas: - - `channels.discord.accounts.default.allowFrom` se aplica somente à conta `default`. - - Para uma conta, `allowFrom` tem precedência sobre o `dm.allowFrom` legado. - - Contas nomeadas herdam `channels.discord.allowFrom` quando seu próprio `allowFrom` e o `dm.allowFrom` legado não estão definidos. + - `channels.discord.accounts.default.allowFrom` se aplica apenas à conta `default`. + - Para uma conta, `allowFrom` tem precedência sobre o legado `dm.allowFrom`. + - Contas nomeadas herdam `channels.discord.allowFrom` quando seu próprio `allowFrom` e o legado `dm.allowFrom` não estão definidos. - Contas nomeadas não herdam `channels.discord.accounts.default.allowFrom`. - `channels.discord.dm.policy` e `channels.discord.dm.allowFrom` legados ainda são lidos para compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando pode fazer isso sem alterar o acesso. + `channels.discord.dm.policy` e `channels.discord.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. Formato de destino de DM para entrega: - `user:` - menção `<@id>` - IDs numéricos simples normalmente são resolvidos como IDs de canal quando um padrão de canal está ativo, mas IDs listados no `allowFrom` efetivo de DM da conta são tratados como destinos de DM de usuário para compatibilidade. + IDs numéricos simples normalmente são resolvidos como IDs de canal quando um padrão de canal está ativo, mas IDs listados no `allowFrom` de DM efetivo da conta são tratados como destinos de DM de usuário para compatibilidade. - + DMs do Discord podem usar entradas dinâmicas `accessGroup:` em `channels.discord.allowFrom`. Nomes de grupos de acesso são compartilhados entre canais de mensagem. Use `type: "message.senders"` para um grupo estático cujos membros são expressos na sintaxe normal de `allowFrom` de cada canal, ou `type: "discord.channelAudience"` quando o público atual de `ViewChannel` de um canal do Discord deve definir a associação dinamicamente. O comportamento compartilhado de grupos de acesso está documentado aqui: [Grupos de acesso](/pt-BR/channels/access-groups). @@ -479,9 +479,9 @@ Exemplo: } ``` - Um canal de texto do Discord não tem uma lista de membros separada. `type: "discord.channelAudience"` modela a associação assim: o remetente da DM é membro da guild configurada e atualmente tem permissão efetiva de `ViewChannel` no canal configurado após a aplicação de substituições de função e canal. + Um canal de texto do Discord não tem uma lista separada de membros. `type: "discord.channelAudience"` modela a associação assim: o remetente da DM é membro da guilda configurada e atualmente tem permissão efetiva `ViewChannel` no canal configurado depois que sobrescritas de função e canal são aplicadas. - Exemplo: permitir que qualquer pessoa que possa ver `#maintainers` envie DM ao bot, mantendo as DMs fechadas para todos os demais. + Exemplo: permitir que qualquer pessoa que possa ver `#maintainers` envie DM ao bot, mantendo DMs fechadas para todos os demais. ```json5 { @@ -522,14 +522,14 @@ Exemplo: } ``` - As consultas falham fechadas. Se o Discord retornar `Missing Access`, a consulta de membro falhar ou o canal pertencer a uma guild diferente, o remetente da DM será tratado como não autorizado. + Consultas falham de forma fechada. Se o Discord retornar `Missing Access`, a consulta de membro falhar ou o canal pertencer a uma guilda diferente, o remetente da DM será tratado como não autorizado. - Ative a **Server Members Intent** do Portal de Desenvolvedor do Discord para o bot ao usar grupos de acesso baseados em público de canal. DMs não incluem estado de membro da guild, então o OpenClaw resolve o membro via REST do Discord no momento da autorização. + Habilite a **Server Members Intent** no Discord Developer Portal para o bot ao usar grupos de acesso por público de canal. DMs não incluem estado de membro de guilda, então o OpenClaw resolve o membro pelo REST do Discord no momento da autorização. - - O tratamento de guilds é controlado por `channels.discord.groupPolicy`: + + O tratamento de guildas é controlado por `channels.discord.groupPolicy`: - `open` - `allowlist` @@ -539,12 +539,12 @@ Exemplo: Comportamento de `allowlist`: - - a guild deve corresponder a `channels.discord.guilds` (`id` preferido, slug aceito) - - listas de permissões opcionais de remetentes: `users` (IDs estáveis recomendados) e `roles` (somente IDs de função); se qualquer uma for configurada, remetentes são permitidos quando correspondem a `users` OU `roles` + - a guilda deve corresponder a `channels.discord.guilds` (`id` preferido, slug aceito) + - allowlists opcionais de remetentes: `users` (IDs estáveis recomendados) e `roles` (somente IDs de função); se qualquer uma for configurada, remetentes são permitidos quando corresponderem a `users` OU `roles` - correspondência direta por nome/tag é desabilitada por padrão; habilite `channels.discord.dangerouslyAllowNameMatching: true` somente como modo de compatibilidade emergencial - - nomes/tags são compatíveis para `users`, mas IDs são mais seguros; `openclaw security audit` alerta quando entradas de nome/tag são usadas - - se uma guild tiver `channels` configurado, canais não listados serão negados - - se uma guild não tiver bloco `channels`, todos os canais dessa guild na lista de permissões serão permitidos + - nomes/tags têm suporte para `users`, mas IDs são mais seguros; `openclaw security audit` avisa quando entradas de nome/tag são usadas + - se uma guilda tiver `channels` configurado, canais não listados são negados + - se uma guilda não tiver bloco `channels`, todos os canais nessa guilda na allowlist são permitidos Exemplo: @@ -570,12 +570,12 @@ Exemplo: } ``` - Se você definir apenas `DISCORD_BOT_TOKEN` e não criar um bloco `channels.discord`, o fallback em runtime será `groupPolicy="allowlist"` (com um aviso nos logs), mesmo se `channels.defaults.groupPolicy` for `open`. + Se você definir apenas `DISCORD_BOT_TOKEN` e não criar um bloco `channels.discord`, o fallback de runtime será `groupPolicy="allowlist"` (com um aviso nos logs), mesmo que `channels.defaults.groupPolicy` seja `open`. - - Mensagens de guild exigem menção por padrão. + + Mensagens de guilda exigem menção por padrão. A detecção de menção inclui: @@ -583,22 +583,22 @@ Exemplo: - padrões de menção configurados (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - comportamento implícito de resposta ao bot em casos compatíveis - Ao escrever mensagens de saída do Discord, use a sintaxe canônica de menção: `<@USER_ID>` para usuários, `<#CHANNEL_ID>` para canais e `<@&ROLE_ID>` para funções. Não use a forma legada de menção por apelido `<@!USER_ID>`. + Ao escrever mensagens de saída do Discord, use a sintaxe canônica de menção: `<@USER_ID>` para usuários, `<#CHANNEL_ID>` para canais e `<@&ROLE_ID>` para funções. Não use o formato legado de menção por apelido `<@!USER_ID>`. - `requireMention` é configurado por guild/canal (`channels.discord.guilds...`). + `requireMention` é configurado por guilda/canal (`channels.discord.guilds...`). `ignoreOtherMentions` opcionalmente descarta mensagens que mencionam outro usuário/função, mas não o bot (excluindo @everyone/@here). - DMs de grupo: + DMs em grupo: - padrão: ignoradas (`dm.groupEnabled=false`) - - lista de permissões opcional via `dm.groupChannels` (IDs ou slugs de canal) + - allowlist opcional via `dm.groupChannels` (IDs de canal ou slugs) -### Roteamento de agente baseado em função +### Roteamento de agentes baseado em função -Use `bindings[].match.roles` para rotear membros de guild do Discord para diferentes agentes por ID de função. Bindings baseados em função aceitam somente IDs de função e são avaliados após bindings de peer ou parent-peer e antes de bindings somente de guild. Se um binding também definir outros campos de correspondência (por exemplo, `peer` + `guildId` + `roles`), todos os campos configurados devem corresponder. +Use `bindings[].match.roles` para rotear membros de guilda do Discord para diferentes agentes por ID de função. Bindings baseados em função aceitam apenas IDs de função e são avaliados depois de bindings de peer ou parent-peer e antes de bindings somente de guilda. Se um binding também definir outros campos de correspondência (por exemplo `peer` + `guildId` + `roles`), todos os campos configurados devem corresponder. ```json5 { @@ -622,17 +622,17 @@ Use `bindings[].match.roles` para rotear membros de guild do Discord para difere } ``` -## Comandos nativos e autenticação de comando +## Comandos nativos e autenticação de comandos -- `commands.native` tem como padrão `"auto"` e é habilitado para Discord. +- `commands.native` usa `"auto"` por padrão e é habilitado para Discord. - Substituição por canal: `channels.discord.commands.native`. -- `commands.native=false` ignora o registro e a limpeza de comandos de barra do Discord durante a inicialização. Comandos registrados anteriormente podem continuar visíveis no Discord até que você os remova do aplicativo do Discord. +- `commands.native=false` ignora o registro e a limpeza de comandos slash do Discord durante a inicialização. Comandos registrados anteriormente podem continuar visíveis no Discord até que você os remova do aplicativo do Discord. - A autenticação de comandos nativos usa as mesmas listas de permissões/políticas do Discord que o tratamento normal de mensagens. -- Os comandos ainda podem ficar visíveis na IU do Discord para usuários que não estão autorizados; a execução ainda aplica a autenticação do OpenClaw e retorna "não autorizado". +- Os comandos ainda podem ficar visíveis na interface do Discord para usuários que não estão autorizados; a execução ainda aplica a autenticação do OpenClaw e retorna "não autorizado". -Veja [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo e o comportamento dos comandos. +Consulte [Comandos slash](/pt-BR/tools/slash-commands) para ver o catálogo e o comportamento dos comandos. -Configurações padrão de comandos de barra: +Configurações padrão de comandos slash: - `ephemeral: true` @@ -652,18 +652,18 @@ Configurações padrão de comandos de barra: - `all` - `batched` - Observação: `off` desabilita o encadeamento implícito de respostas. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. - `first` sempre anexa a referência implícita de resposta nativa à primeira mensagem enviada do Discord no turno. + Observação: `off` desativa o encadeamento implícito de respostas. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. + `first` sempre anexa a referência implícita de resposta nativa à primeira mensagem de saída do Discord no turno. `batched` só anexa a referência implícita de resposta nativa do Discord quando o turno de entrada foi um lote com debounce de várias mensagens. Isso é útil quando você quer respostas nativas principalmente para conversas ambíguas em rajadas, não para cada turno de mensagem única. - IDs de mensagem são expostos no contexto/histórico para que os agentes possam direcionar mensagens específicas. + IDs de mensagem são expostos no contexto/histórico para que agentes possam direcionar mensagens específicas. - + O OpenClaw pode transmitir respostas em rascunho enviando uma mensagem temporária e editando-a conforme o texto chega. `channels.discord.streaming` aceita `off` (padrão) | `partial` | `block` | `progress`. `progress` mantém um rascunho de status editável e o atualiza com o progresso da ferramenta até a entrega final; `streamMode` é um alias legado e é migrado automaticamente. O padrão continua sendo `off` porque edições de prévia do Discord atingem limites de taxa rapidamente quando vários bots ou gateways compartilham uma conta. @@ -684,47 +684,66 @@ Configurações padrão de comandos de barra: ``` - `partial` edita uma única mensagem de prévia conforme os tokens chegam. - - `block` emite blocos do tamanho de rascunho (use `draftChunk` para ajustar tamanho e pontos de quebra, limitado a `textChunkLimit`). + - `block` emite blocos do tamanho de rascunho (use `draftChunk` para ajustar tamanho e pontos de quebra, limitado por `textChunkLimit`). - Finais com mídia, erro e resposta explícita cancelam edições de prévia pendentes. - `streaming.preview.toolProgress` (padrão `true`) controla se atualizações de ferramenta/progresso reutilizam a mensagem de prévia. + - `streaming.preview.commandText` / `streaming.progress.commandText` controla detalhes de comando/execução em linhas compactas de progresso: `raw` (padrão) ou `status` (apenas o rótulo da ferramenta). - A transmissão de prévia é somente texto; respostas com mídia voltam para a entrega normal. Quando a transmissão `block` é habilitada explicitamente, o OpenClaw ignora o fluxo de prévia para evitar transmissão duplicada. + Oculte texto bruto de comando/execução mantendo linhas compactas de progresso: + + ```json + { + "channels": { + "discord": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + O streaming de prévia é somente texto; respostas com mídia voltam para a entrega normal. Quando o streaming `block` é habilitado explicitamente, o OpenClaw pula o stream de prévia para evitar streaming duplicado. - + Contexto de histórico de guilda: - - `channels.discord.historyLimit` padrão `20` + - padrão de `channels.discord.historyLimit`: `20` - fallback: `messages.groupChat.historyLimit` - - `0` desabilita + - `0` desativa Controles de histórico de DM: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Comportamento de thread: + Comportamento de threads: - - Threads do Discord são roteadas como sessões de canal e herdam a configuração do canal pai, a menos que sejam substituídas. - - Sessões de thread herdam a seleção `/model` em nível de sessão do canal pai como fallback apenas de modelo; seleções `/model` locais da thread ainda têm precedência e o histórico da transcrição pai não é copiado, a menos que a herança de transcrição esteja habilitada. - - `channels.discord.thread.inheritParent` (padrão `false`) opta novas auto-threads por propagação a partir da transcrição pai. Substituições por conta ficam em `channels.discord.accounts..thread.inheritParent`. - - Reações da ferramenta de mensagem podem resolver destinos de DM `user:`. + - Threads do Discord são roteadas como sessões de canal e herdam a configuração do canal pai, a menos que haja substituição. + - Sessões de thread herdam a seleção `/model` em nível de sessão do canal pai como fallback apenas de modelo; seleções `/model` locais da thread ainda têm precedência, e o histórico da transcrição pai não é copiado, a menos que a herança de transcrição esteja habilitada. + - `channels.discord.thread.inheritParent` (padrão `false`) faz novas auto-threads iniciarem com dados da transcrição pai. Substituições por conta ficam em `channels.discord.accounts..thread.inheritParent`. + - Reações da ferramenta de mensagens podem resolver alvos de DM `user:`. - `guilds..channels..requireMention: false` é preservado durante o fallback de ativação no estágio de resposta. - Tópicos de canal são injetados como contexto **não confiável**. Listas de permissões controlam quem pode acionar o agente, não são uma fronteira completa de redação de contexto suplementar. + Tópicos de canal são injetados como contexto **não confiável**. Listas de permissões controlam quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar. - O Discord pode vincular uma thread a um destino de sessão para que mensagens subsequentes nessa thread continuem sendo roteadas para a mesma sessão (incluindo sessões de subagente). + O Discord pode vincular uma thread a um alvo de sessão para que mensagens de acompanhamento nessa thread continuem sendo roteadas para a mesma sessão (incluindo sessões de subagente). Comandos: - - `/focus ` vincula a thread atual/nova a um destino de subagente/sessão + - `/focus ` vincula a thread atual/nova a um alvo de subagente/sessão - `/unfocus` remove o vínculo da thread atual - - `/agents` mostra execuções ativas e estado de vínculo - - `/session idle ` inspeciona/atualiza o auto-desfoque por inatividade para vínculos focados + - `/agents` mostra execuções ativas e o estado de vínculo + - `/session idle ` inspeciona/atualiza o desfoco automático por inatividade para vínculos focados - `/session max-age ` inspeciona/atualiza a idade máxima rígida para vínculos focados Configuração: @@ -756,16 +775,16 @@ Configurações padrão de comandos de barra: - `session.threadBindings.*` define padrões globais. - `channels.discord.threadBindings.*` substitui o comportamento do Discord. - - `spawnSessions` controla a criação/vinculação automática de threads para `sessions_spawn({ thread: true })` e criações de thread do ACP. Padrão: `true`. - - `defaultSpawnContext` controla o contexto nativo de subagente para criações vinculadas a thread. Padrão: `"fork"`. - - Chaves obsoletas `spawnSubagentSessions`/`spawnAcpSessions` são migradas por `openclaw doctor --fix`. - - Se vínculos de thread estiverem desabilitados para uma conta, `/focus` e operações relacionadas de vínculo de thread não estarão disponíveis. + - `spawnSessions` controla a criação/vinculação automática de threads para `sessions_spawn({ thread: true })` e gerações de thread ACP. Padrão: `true`. + - `defaultSpawnContext` controla o contexto nativo de subagente para gerações vinculadas a threads. Padrão: `"fork"`. + - As chaves obsoletas `spawnSubagentSessions`/`spawnAcpSessions` são migradas por `openclaw doctor --fix`. + - Se vínculos de thread estiverem desativados para uma conta, `/focus` e operações relacionadas de vínculo de thread ficam indisponíveis. - Veja [Subagentes](/pt-BR/tools/subagents), [Agentes ACP](/pt-BR/tools/acp-agents) e [Referência de configuração](/pt-BR/gateway/configuration-reference). + Consulte [Subagentes](/pt-BR/tools/subagents), [Agentes ACP](/pt-BR/tools/acp-agents) e [Referência de configuração](/pt-BR/gateway/configuration-reference). - + Para workspaces ACP estáveis e "sempre ativos", configure vínculos ACP tipados de nível superior direcionados a conversas do Discord. Caminho de configuração: @@ -823,10 +842,10 @@ Configurações padrão de comandos de barra: Observações: - `/acp spawn codex --bind here` vincula o canal ou a thread atual no local e mantém mensagens futuras na mesma sessão ACP. Mensagens de thread herdam o vínculo do canal pai. - - Em um canal ou thread vinculado, `/new` e `/reset` redefinem a mesma sessão ACP no local. Vínculos temporários de thread podem substituir a resolução de destino enquanto estiverem ativos. - - `spawnSessions` controla a criação/vinculação de threads filhas via `--thread auto|here`. + - Em um canal ou thread vinculado, `/new` e `/reset` redefinem a mesma sessão ACP no local. Vínculos temporários de thread podem substituir a resolução de destino enquanto ativos. + - `spawnSessions` controla a criação/vinculação de threads filhas por meio de `--thread auto|here`. - Veja [Agentes ACP](/pt-BR/tools/acp-agents) para detalhes do comportamento de vínculo. + Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para detalhes do comportamento de vínculo. @@ -850,21 +869,21 @@ Configurações padrão de comandos de barra: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, senão "👀") + - fallback de emoji de identidade do agente (`agents.list[].identity.emoji`, senão "👀") Observações: - O Discord aceita emoji unicode ou nomes de emoji personalizados. - - Use `""` para desabilitar a reação para um canal ou conta. + - Use `""` para desativar a reação para um canal ou conta. - Gravações de configuração iniciadas por canal são habilitadas por padrão. + Gravações de configuração iniciadas pelo canal são habilitadas por padrão. Isso afeta fluxos `/config set|unset` (quando recursos de comando estão habilitados). - Desabilitar: + Desativar: ```json5 { @@ -879,7 +898,7 @@ Configurações padrão de comandos de barra: - Roteie o tráfego WebSocket do Gateway do Discord e buscas REST de inicialização (ID do aplicativo + resolução de lista de permissões) por meio de um proxy HTTP(S) com `channels.discord.proxy`. + Roteie o tráfego WebSocket do gateway do Discord e consultas REST de inicialização (ID do aplicativo + resolução de lista de permissões) por meio de um proxy HTTP(S) com `channels.discord.proxy`. ```json5 { @@ -909,8 +928,8 @@ Configurações padrão de comandos de barra: - - Habilite a resolução do PluralKit para mapear mensagens com proxy para a identidade de membro do sistema: + + Habilite a resolução do PluralKit para mapear mensagens em proxy para a identidade de membro do sistema: ```json5 { @@ -928,14 +947,14 @@ Configurações padrão de comandos de barra: Observações: - listas de permissões podem usar `pk:` - - nomes de exibição de membros são correspondidos por nome/slug somente quando `channels.discord.dangerouslyAllowNameMatching: true` - - buscas usam o ID da mensagem original e são restritas por janela de tempo - - se a busca falhar, mensagens com proxy são tratadas como mensagens de bot e descartadas, a menos que `allowBots=true` + - nomes de exibição de membros são correspondidos por nome/slug apenas quando `channels.discord.dangerouslyAllowNameMatching: true` + - consultas usam o ID da mensagem original e são restritas por janela de tempo + - se a consulta falhar, mensagens em proxy são tratadas como mensagens de bot e descartadas, a menos que `allowBots=true` - Use `mentionAliases` quando agentes precisarem de menções de saída determinísticas para usuários conhecidos do Discord. As chaves são identificadores sem o `@` inicial; os valores são IDs de usuário do Discord. Identificadores desconhecidos, `@everyone`, `@here` e menções dentro de spans de código Markdown são deixados inalterados. + Use `mentionAliases` quando agentes precisarem de menções de saída determinísticas para usuários conhecidos do Discord. Chaves são identificadores sem o `@` inicial; valores são IDs de usuário do Discord. Identificadores desconhecidos, `@everyone`, `@here` e menções dentro de spans de código Markdown permanecem inalterados. ```json5 { @@ -961,7 +980,7 @@ Configurações padrão de comandos de barra: Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando habilita presença automática. - Exemplo somente de status: + Exemplo apenas de status: ```json5 { @@ -986,7 +1005,7 @@ Configurações padrão de comandos de barra: } ``` - Exemplo de transmissão: + Exemplo de streaming: ```json5 { @@ -1009,7 +1028,7 @@ Configurações padrão de comandos de barra: - 4: Personalizado (usa o texto da atividade como o estado do status; emoji é opcional) - 5: Competindo - Exemplo de presença automática (sinal de integridade em tempo de execução): + Exemplo de presença automática (sinal de integridade em runtime): ```json5 { @@ -1026,16 +1045,16 @@ Configurações padrão de comandos de barra: } ``` - Presença automática mapeia disponibilidade em tempo de execução para status do Discord: saudável => online, degradada ou desconhecida => ocioso, esgotada ou indisponível => dnd. Substituições opcionais de texto: + Presença automática mapeia a disponibilidade em tempo de execução para o status do Discord: saudável => online, degradado ou desconhecido => idle, esgotado ou indisponível => dnd. Substituições opcionais de texto: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (oferece suporte ao placeholder `{reason}`) + - `autoPresence.exhaustedText` (aceita o placeholder `{reason}`) - O Discord oferece suporte ao tratamento de aprovação baseado em botões em DMs e pode opcionalmente publicar prompts de aprovação no canal de origem. + Discord oferece suporte ao tratamento de aprovações por botões em DMs e pode, opcionalmente, publicar prompts de aprovação no canal de origem. Caminho de configuração: @@ -1044,30 +1063,30 @@ Configurações padrão de comandos de barra: - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - O Discord ativa automaticamente as aprovações de execução nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou de `commands.ownerAllowFrom`. O Discord não infere aprovadores de execução a partir de `allowFrom` do canal, do `dm.allowFrom` legado ou de `defaultTo` de mensagem direta. Defina `enabled: false` para desativar explicitamente o Discord como cliente de aprovação nativo. + Discord ativa automaticamente aprovações nativas de execução quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja por `execApprovals.approvers` ou por `commands.ownerAllowFrom`. Discord não infere aprovadores de execução a partir de `allowFrom` do canal, `dm.allowFrom` legado ou `defaultTo` de mensagem direta. Defina `enabled: false` para desabilitar explicitamente o Discord como cliente nativo de aprovação. - Para comandos de grupo sensíveis e exclusivos do proprietário, como `/diagnostics` e `/export-trajectory`, o OpenClaw envia solicitações de aprovação e resultados finais em privado. Ele tenta primeiro a DM do Discord quando o proprietário que invocou o comando tem uma rota de proprietário do Discord; se isso não estiver disponível, recorre à primeira rota de proprietário disponível em `commands.ownerAllowFrom`, como Telegram. + Para comandos de grupo sensíveis exclusivos do proprietário, como `/diagnostics` e `/export-trajectory`, OpenClaw envia prompts de aprovação e resultados finais de forma privada. Ele tenta primeiro a DM do Discord quando o proprietário que invocou o comando tem uma rota de proprietário do Discord; se isso não estiver disponível, recorre à primeira rota de proprietário disponível em `commands.ownerAllowFrom`, como Telegram. - Quando `target` é `channel` ou `both`, a solicitação de aprovação fica visível no canal. Somente aprovadores resolvidos podem usar os botões; outros usuários recebem uma negativa efêmera. As solicitações de aprovação incluem o texto do comando, portanto habilite a entrega em canal apenas em canais confiáveis. Se o ID do canal não puder ser derivado da chave de sessão, o OpenClaw recorre à entrega por DM. + Quando `target` é `channel` ou `both`, o prompt de aprovação fica visível no canal. Somente aprovadores resolvidos podem usar os botões; outros usuários recebem uma negação efêmera. Prompts de aprovação incluem o texto do comando, então habilite entrega no canal apenas em canais confiáveis. Se o ID do canal não puder ser derivado da chave de sessão, OpenClaw recorre à entrega por DM. - O Discord também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Discord adiciona principalmente roteamento de DM para aprovadores e distribuição para canais. - Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw - deve incluir um comando `/approve` manual somente quando o resultado da ferramenta indicar que + Discord também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Discord adiciona principalmente roteamento de DM para aprovadores e fanout de canal. + Quando esses botões estão presentes, eles são a UX principal de aprovação; OpenClaw + só deve incluir um comando manual `/approve` quando o resultado da ferramenta diz que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho. - Se o runtime de aprovação nativa do Discord não estiver ativo, o OpenClaw mantém a - solicitação determinística local `/approve ` visível. Se o + Se o runtime de aprovação nativa do Discord não estiver ativo, OpenClaw mantém o + prompt determinístico local `/approve ` visível. Se o runtime estiver ativo, mas um cartão nativo não puder ser entregue a nenhum destino, - o OpenClaw envia um aviso de fallback no mesmo chat com o comando `/approve` + OpenClaw envia um aviso de fallback no mesmo chat com o comando `/approve` exato da aprovação pendente. - A autenticação do Gateway e a resolução de aprovação seguem o contrato compartilhado do cliente Gateway (IDs `plugin:` são resolvidos por `plugin.approval.resolve`; outros IDs por `exec.approval.resolve`). Aprovações expiram após 30 minutos por padrão. + A autenticação do Gateway e a resolução de aprovações seguem o contrato compartilhado do cliente Gateway (IDs `plugin:` são resolvidos por `plugin.approval.resolve`; outros IDs por `exec.approval.resolve`). Aprovações expiram após 30 minutos por padrão. Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals). -## Ferramentas e portões de ação +## Ferramentas e gates de ação As ações de mensagem do Discord incluem ações de mensagens, administração de canais, moderação, presença e metadados. @@ -1080,9 +1099,9 @@ Exemplos principais: A ação `event-create` aceita um parâmetro opcional `image` (URL ou caminho de arquivo local) para definir a imagem de capa do evento agendado. -Os portões de ação ficam em `channels.discord.actions.*`. +Gates de ação ficam em `channels.discord.actions.*`. -Comportamento padrão dos portões: +Comportamento padrão dos gates: | Grupo de ações | Padrão | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | @@ -1091,11 +1110,11 @@ Comportamento padrão dos portões: | moderation | desabilitado | | presence | desabilitado | -## UI Components v2 +## UI de componentes v2 -O OpenClaw usa componentes v2 do Discord para aprovações de execução e marcadores entre contextos. As ações de mensagem do Discord também podem aceitar `components` para UI personalizada (avançado; requer construir um payload de componente pela ferramenta discord), enquanto `embeds` legados continuam disponíveis, mas não são recomendados. +OpenClaw usa componentes v2 do Discord para aprovações de execução e marcadores entre contextos. Ações de mensagem do Discord também podem aceitar `components` para UI personalizada (avançado; exige construir um payload de componente via ferramenta do discord), enquanto `embeds` legados continuam disponíveis, mas não são recomendados. -- `channels.discord.ui.components.accentColor` define a cor de destaque usada pelos contêineres de componentes do Discord (hex). +- `channels.discord.ui.components.accentColor` define a cor de destaque usada por contêineres de componentes do Discord (hex). - Defina por conta com `channels.discord.accounts..ui.components.accentColor`. - `embeds` são ignorados quando componentes v2 estão presentes. @@ -1117,14 +1136,14 @@ Exemplo: ## Voz -O Discord tem duas superfícies de voz distintas: **canais de voz** em tempo real (conversas contínuas) e **anexos de mensagem de voz** (o formato de prévia com forma de onda). O Gateway oferece suporte a ambos. +Discord tem duas superfícies de voz distintas: **canais de voz** em tempo real (conversas contínuas) e **anexos de mensagens de voz** (o formato de prévia com forma de onda). O gateway oferece suporte a ambos. ### Canais de voz Checklist de configuração: 1. Habilite Message Content Intent no Discord Developer Portal. -2. Habilite Server Members Intent quando allowlists de funções/usuários forem usadas. +2. Habilite Server Members Intent quando allowlists de função/usuário forem usadas. 3. Convide o bot com os escopos `bot` e `applications.commands`. 4. Conceda Connect, Speak, Send Messages e Read Message History no canal de voz de destino. 5. Habilite comandos nativos (`commands.native` ou `channels.discord.commands.native`). @@ -1172,34 +1191,34 @@ Observações: - `voice.tts` substitui `messages.tts` apenas para reprodução de voz. - `voice.model` substitui o LLM usado apenas para respostas em canais de voz do Discord. Deixe sem definir para herdar o modelo do agente roteado. - STT usa `tools.media.audio`; `voice.model` não afeta a transcrição. -- Substituições de `systemPrompt` do Discord por canal se aplicam aos turnos de transcrição de voz desse canal de voz. +- Substituições de `systemPrompt` por canal do Discord se aplicam a turnos de transcrição de voz desse canal de voz. - Turnos de transcrição de voz derivam o status de proprietário de `allowFrom` do Discord (ou `dm.allowFrom`); falantes que não são proprietários não podem acessar ferramentas exclusivas do proprietário (por exemplo, `gateway` e `cron`). -- A voz do Discord é opcional para configurações somente de texto; defina `channels.discord.voice.enabled=true` (ou mantenha um bloco `channels.discord.voice` existente) para habilitar comandos `/vc`, o runtime de voz e a intenção Gateway `GuildVoiceStates`. +- Voz do Discord é opt-in para configurações somente texto; defina `channels.discord.voice.enabled=true` (ou mantenha um bloco `channels.discord.voice` existente) para habilitar comandos `/vc`, o runtime de voz e a intenção de gateway `GuildVoiceStates`. - `channels.discord.intents.voiceStates` pode substituir explicitamente a assinatura de intenção de estado de voz. Deixe sem definir para que a intenção siga a habilitação efetiva de voz. -- `voice.daveEncryption` e `voice.decryptionFailureTolerance` são repassados às opções de entrada de `@discordjs/voice`. -- Os padrões de `@discordjs/voice` são `daveEncryption=true` e `decryptionFailureTolerance=24` se não forem definidos. -- `voice.connectTimeoutMs` controla a espera inicial por Ready de `@discordjs/voice` para `/vc join` e tentativas de entrada automática. Padrão: `30000`. -- `voice.reconnectGraceMs` controla por quanto tempo o OpenClaw aguarda que uma sessão de voz desconectada comece a se reconectar antes de destruí-la. Padrão: `15000`. -- O OpenClaw também observa falhas de descriptografia no recebimento e se recupera automaticamente saindo e entrando novamente no canal de voz após falhas repetidas em uma janela curta. -- Se os logs de recebimento mostrarem repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` após a atualização, colete um relatório de dependências e logs. A linha `@discordjs/voice` incluída contém a correção upstream de preenchimento do PR #11449 do discord.js, que fechou a issue #11419 do discord.js. +- `voice.daveEncryption` e `voice.decryptionFailureTolerance` são repassados para as opções de entrada do `@discordjs/voice`. +- Os padrões do `@discordjs/voice` são `daveEncryption=true` e `decryptionFailureTolerance=24` se não definidos. +- `voice.connectTimeoutMs` controla a espera inicial por Ready do `@discordjs/voice` para tentativas de `/vc join` e entrada automática. Padrão: `30000`. +- `voice.reconnectGraceMs` controla por quanto tempo o OpenClaw espera que uma sessão de voz desconectada comece a reconectar antes de destruí-la. Padrão: `15000`. +- OpenClaw também monitora falhas de descriptografia de recebimento e se recupera automaticamente saindo e entrando novamente no canal de voz após falhas repetidas em uma janela curta. +- Se os logs de recebimento mostrarem repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` após a atualização, colete um relatório de dependências e logs. A linha `@discordjs/voice` incluída contém a correção upstream de padding do PR #11449 do discord.js, que encerrou a issue #11419 do discord.js. Pipeline de canal de voz: -- A captura PCM do Discord é convertida em um arquivo temporário WAV. +- A captura PCM do Discord é convertida para um arquivo temporário WAV. - `tools.media.audio` lida com STT, por exemplo `openai/gpt-4o-mini-transcribe`. - A transcrição é enviada pelo ingresso e roteamento do Discord enquanto o LLM de resposta roda com uma política de saída de voz que oculta a ferramenta `tts` do agente e solicita texto retornado, porque a voz do Discord controla a reprodução TTS final. -- `voice.model`, quando definido, substitui apenas o LLM de resposta para esse turno de canal de voz. -- `voice.tts` é mesclado sobre `messages.tts`; o áudio resultante é reproduzido no canal conectado. +- `voice.model`, quando definido, substitui apenas o LLM de resposta para este turno de canal de voz. +- `voice.tts` é mesclado sobre `messages.tts`; o áudio resultante é reproduzido no canal ingressado. -As credenciais são resolvidas por componente: autenticação da rota LLM para `voice.model`, autenticação STT para `tools.media.audio` e autenticação TTS para `messages.tts`/`voice.tts`. +Credenciais são resolvidas por componente: autenticação de rota de LLM para `voice.model`, autenticação de STT para `tools.media.audio` e autenticação de TTS para `messages.tts`/`voice.tts`. ### Mensagens de voz -Mensagens de voz do Discord mostram uma prévia com forma de onda e exigem áudio OGG/Opus. O OpenClaw gera a forma de onda automaticamente, mas precisa de `ffmpeg` e `ffprobe` no host do Gateway para inspecionar e converter. +Mensagens de voz do Discord exibem uma prévia com forma de onda e exigem áudio OGG/Opus. OpenClaw gera a forma de onda automaticamente, mas precisa de `ffmpeg` e `ffprobe` no host do gateway para inspecionar e converter. - Forneça um **caminho de arquivo local** (URLs são rejeitadas). -- Omita o conteúdo de texto (o Discord rejeita texto + mensagem de voz no mesmo payload). -- Qualquer formato de áudio é aceito; o OpenClaw converte para OGG/Opus conforme necessário. +- Omita conteúdo de texto (Discord rejeita texto + mensagem de voz no mesmo payload). +- Qualquer formato de áudio é aceito; OpenClaw converte para OGG/Opus conforme necessário. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1211,16 +1230,16 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - habilite Message Content Intent - - habilite Server Members Intent quando depender da resolução de usuário/membro - - reinicie o Gateway após alterar intents + - habilite Server Members Intent quando você depende de resolução de usuário/membro + - reinicie o gateway após alterar intents - verifique `groupPolicy` - - verifique a allowlist de guilda em `channels.discord.guilds` - - se o mapa `channels` da guilda existir, somente canais listados serão permitidos + - verifique a allowlist da guilda em `channels.discord.guilds` + - se o mapa `channels` da guilda existir, somente os canais listados serão permitidos - verifique o comportamento de `requireMention` e os padrões de menção Verificações úteis: @@ -1233,12 +1252,12 @@ openclaw logs --follow - + Causas comuns: - - `groupPolicy="allowlist"` sem allowlist de guilda/canal correspondente - - `requireMention` configurado no lugar errado (deve estar em `channels.discord.guilds` ou na entrada do canal) - - remetente bloqueado pela allowlist `users` da guilda/canal + - `groupPolicy="allowlist"` sem allowlist correspondente de guilda/canal + - `requireMention` configurado no lugar errado (deve ficar em `channels.discord.guilds` ou na entrada do canal) + - remetente bloqueado pela allowlist `users` de guilda/canal @@ -1249,13 +1268,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Ajustes da fila do Gateway do Discord: + Ajustes da fila do gateway do Discord: - conta única: `channels.discord.eventQueue.listenerTimeout` - várias contas: `channels.discord.accounts..eventQueue.listenerTimeout` - - isso controla apenas o trabalho do listener do Gateway do Discord, não a duração do turno do agente + - isso controla apenas o trabalho do listener do gateway do Discord, não a duração do turno do agente - O Discord não aplica um timeout controlado pelo canal a turnos de agente enfileirados. Listeners de mensagem fazem a transferência imediatamente, e execuções do Discord enfileiradas preservam a ordenação por sessão até que o ciclo de vida da sessão/ferramenta/runtime conclua ou aborte o trabalho. + Discord não aplica um timeout pertencente ao canal a turnos de agente enfileirados. Listeners de mensagem repassam imediatamente, e execuções do Discord enfileiradas preservam a ordenação por sessão até que o ciclo de vida da sessão/ferramenta/runtime conclua ou aborte o trabalho. ```json5 { @@ -1275,10 +1294,10 @@ openclaw logs --follow - - O OpenClaw busca metadados `/gateway/bot` do Discord antes de conectar. Falhas transitórias recorrem à URL padrão de Gateway do Discord e têm taxa limitada nos logs. + + O OpenClaw busca os metadados `/gateway/bot` do Discord antes de se conectar. Falhas transitórias usam como fallback a URL padrão de gateway do Discord e têm limitação de taxa nos logs. - Ajustes de timeout de metadados: + Controles de tempo limite de metadados: - conta única: `channels.discord.gatewayInfoTimeoutMs` - várias contas: `channels.discord.accounts..gatewayInfoTimeoutMs` @@ -1287,26 +1306,26 @@ openclaw logs --follow - - O OpenClaw aguarda o evento `READY` do Gateway do Discord durante a inicialização e após reconexões em tempo de execução. Configurações com várias contas e escalonamento de inicialização podem precisar de uma janela de READY de inicialização maior que o padrão. + + O OpenClaw aguarda o evento `READY` do gateway do Discord durante a inicialização e após reconexões em tempo de execução. Configurações com várias contas e escalonamento de inicialização podem precisar de uma janela READY de inicialização maior que a padrão. - Controles de timeout de READY: + Controles de tempo limite de READY: - - conta única na inicialização: `channels.discord.gatewayReadyTimeoutMs` - - várias contas na inicialização: `channels.discord.accounts..gatewayReadyTimeoutMs` - - fallback de env na inicialização quando a configuração não está definida: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - - padrão de inicialização: `15000` (15 segundos), máx.: `120000` - - conta única em tempo de execução: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - várias contas em tempo de execução: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - fallback de env em tempo de execução quando a configuração não está definida: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - - padrão em tempo de execução: `30000` (30 segundos), máx.: `120000` + - inicialização com conta única: `channels.discord.gatewayReadyTimeoutMs` + - inicialização com várias contas: `channels.discord.accounts..gatewayReadyTimeoutMs` + - fallback de env de inicialização quando a configuração não está definida: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - padrão de inicialização: `15000` (15 segundos), máximo: `120000` + - tempo de execução com conta única: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - tempo de execução com várias contas: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - fallback de env de tempo de execução quando a configuração não está definida: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - padrão de tempo de execução: `30000` (30 segundos), máximo: `120000` As verificações de permissão de `channels status --probe` funcionam apenas para IDs numéricos de canais. - Se você usa chaves de slug, a correspondência em tempo de execução ainda pode funcionar, mas o probe não consegue verificar permissões completamente. + Se você usar chaves de slug, a correspondência em tempo de execução ainda pode funcionar, mas a sondagem não consegue verificar permissões por completo. @@ -1321,7 +1340,7 @@ openclaw logs --follow Por padrão, mensagens criadas por bots são ignoradas. - Se você definir `channels.discord.allowBots=true`, use regras estritas de menção e lista de permissões para evitar comportamento de loop. + Se você definir `channels.discord.allowBots=true`, use regras rígidas de menção e lista de permissão para evitar comportamento de loop. Prefira `channels.discord.allowBots="mentions"` para aceitar apenas mensagens de bots que mencionem o bot. ```json5 @@ -1353,11 +1372,11 @@ openclaw logs --follow - mantenha o OpenClaw atualizado (`openclaw update`) para que a lógica de recuperação de recebimento de voz do Discord esteja presente - confirme `channels.discord.voice.daveEncryption=true` (padrão) - - comece com `channels.discord.voice.decryptionFailureTolerance=24` (padrão upstream) e ajuste apenas se necessário - - monitore os logs para: + - comece com `channels.discord.voice.decryptionFailureTolerance=24` (padrão do projeto de origem) e ajuste somente se necessário + - observe os logs em busca de: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - se as falhas continuarem após a reentrada automática, colete os logs e compare com o histórico upstream de recebimento do DAVE em [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) e [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) + - se as falhas continuarem após a reentrada automática, colete logs e compare com o histórico de recebimento DAVE do projeto de origem em [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) e [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) @@ -1366,17 +1385,17 @@ openclaw logs --follow Referência principal: [Referência de configuração - Discord](/pt-BR/gateway/config-channels#discord). - + - inicialização/autenticação: `enabled`, `token`, `accounts.*`, `allowBots` - política: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - comando: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - fila de eventos: `eventQueue.listenerTimeout` (orçamento do listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- Gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` +- gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` - resposta/histórico: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - entrega: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` - streaming: `streaming` (alias legado: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- mídia/tentativa: `mediaMaxMb` (limita uploads de saída do Discord, padrão `100MB`), `retry` +- mídia/tentativa: `mediaMaxMb` (limita uploads enviados ao Discord, padrão `100MB`), `retry` - ações: `actions.*` - presença: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` @@ -1388,27 +1407,27 @@ Referência principal: [Referência de configuração - Discord](/pt-BR/gateway/ - Trate tokens de bot como segredos (`DISCORD_BOT_TOKEN` é preferível em ambientes supervisionados). - Conceda permissões do Discord com privilégio mínimo. -- Se a implantação/estado de comandos estiver obsoleto, reinicie o Gateway e verifique novamente com `openclaw channels status --probe`. +- Se a implantação/estado dos comandos estiver desatualizada, reinicie o gateway e verifique novamente com `openclaw channels status --probe`. ## Relacionados - Pareie um usuário do Discord ao Gateway. + Pareie um usuário do Discord ao gateway. - Comportamento de chat em grupo e lista de permissões. + Comportamento de chat em grupo e lista de permissão. - Roteie mensagens de entrada para agentes. + Encaminhe mensagens recebidas para agentes. - Modelo de ameaça e endurecimento. + Modelo de ameaças e hardening. Mapeie guildas e canais para agentes. - Comportamento de comando nativo. + Comportamento de comandos nativos. diff --git a/docs/pt-BR/channels/slack.md b/docs/pt-BR/channels/slack.md index 9a62c3962..b3df54ea8 100644 --- a/docs/pt-BR/channels/slack.md +++ b/docs/pt-BR/channels/slack.md @@ -1,27 +1,27 @@ --- read_when: - - Configuração do Slack ou depuração do modo de soquete/HTTP do Slack -summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de solicitação HTTP) + - 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) title: Slack x-i18n: - generated_at: "2026-05-04T02:22:07Z" + generated_at: "2026-05-04T07:02:49Z" model: gpt-5.5 provider: openai - source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b + source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 source_path: channels/slack.md workflow: 16 --- -Pronto para produção para DMs e canais por meio de integrações do app Slack. O modo padrão é Socket Mode; HTTP Request URLs também são compatíveis. +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. - + DMs do Slack usam o modo de pareamento por padrão. - - Comportamento de comando nativo e catálogo de comandos. + + Comportamento nativo de comandos e catálogo de comandos. - + Diagnósticos entre canais e playbooks de reparo. @@ -29,19 +29,19 @@ Pronto para produção para DMs e canais por meio de integrações do app Slack. ## Configuração rápida - + - - Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: + + Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: - 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 **App-Level Token** (`xapp-...`) com `connections:write` - - instale o app e copie o **Bot Token** (`xoxb-...`) exibido + - gere um **Token em nível de app** (`xapp-...`) com `connections:write` + - instale o app e copie o **Token do bot** (`xoxb-...`) exibido - + Configuração SecretRef recomendada: @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - Fallback por env (somente conta padrão): + Fallback de env (somente conta padrão): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,19 +84,19 @@ openclaw gateway - + - - Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: + + Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: - 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 **Signing Secret** para verificação de solicitações - - instale o app e copie o **Bot Token** (`xoxb-...`) exibido + - salve o **Segredo de assinatura** para verificação de requisições + - instale o app e copie o **Token do bot** (`xoxb-...`) exibido - + Configuração SecretRef recomendada: @@ -128,7 +128,7 @@ openclaw config patch --file ./slack.http.patch.json5 - + ```bash openclaw gateway @@ -140,9 +140,9 @@ openclaw gateway -## Ajuste do transporte Socket Mode +## 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 ajustes específicos para o workspace ou o host: +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: ```json5 { @@ -159,11 +159,11 @@ O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segu } ``` -Use isso somente para workspaces em Socket Mode que registram tempos limite de pong/server-ping do websocket do Slack ou executam em hosts com starvation conhecido do loop de eventos. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping do cliente; `serverPingTimeout` é a espera pelos pings do servidor do Slack. Mensagens e eventos do app permanecem como estado da aplicação, não como sinais de vivacidade do transporte. +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. ## Checklist de manifesto e escopos -O manifesto base do app Slack é o mesmo para Socket Mode e HTTP Request URLs. Apenas o bloco `settings` (e a `url` do comando slash) difere. +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. Manifesto base (Socket Mode padrão): @@ -240,7 +240,7 @@ Manifesto base (Socket Mode padrão): } ``` -Para o **modo HTTP Request URLs**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória: +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: ```json { @@ -284,22 +284,22 @@ Para o **modo HTTP Request URLs**, substitua `settings` pela variante HTTP e adi ### Configurações adicionais do manifesto -Exiba recursos diferentes que estendem os padrões acima. +Exponha recursos diferentes 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 ou configuração privada é incluído. A aba **Messages** permanece habilitada para DMs do Slack. +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. - + - Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com uma nuance: + Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com nuances: - Use `/agentstatus` em vez de `/status` porque o comando `/status` é reservado. - - No máximo 25 comandos slash podem ficar disponíveis ao mesmo tempo. + - Não mais que 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): - + ```json { @@ -422,7 +422,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 @@ -450,7 +450,7 @@ 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 de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app Slack. + 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:`. @@ -464,57 +464,57 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (se você depender de leituras da busca do Slack) + - `search:read` (se você depende de leituras de busca do Slack) -## Modelo de tokens +## 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 claro +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples 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-...`) é somente por configuração (sem fallback de env) e o padrão é comportamento somente leitura (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) é apenas de configuração (sem fallback de env) e usa por padrão comportamento somente leitura (`userTokenReadOnly: true`). -Comportamento do snapshot de status: +Comportamento do instantâneo de status: -- A inspeção da conta Slack rastreia campos `*Source` e `*Status` +- A inspeção de conta 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 origem de segredo não inline, mas o caminho de comando/runtime atual + ou outra fonte de segredo não embutida, mas o comando/caminho de runtime atual não conseguiu resolver o valor real. -- No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o +- 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 sendo 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 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. ## Ações e gates As ações do Slack são controladas por `channels.slack.actions.*`. -Grupos de ação disponíveis nas ferramentas Slack atuais: +Grupos de ações disponíveis nas ferramentas atuais do Slack: | Grupo | Padrão | | ---------- | ------- | -| messages | ativado | -| reactions | ativado | -| pins | ativado | -| memberInfo | ativado | -| emojiList | ativado | +| messages | habilitado | +| reactions | habilitado | +| pins | habilitado | +| memberInfo | habilitado | +| emojiList | habilitado | -As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo 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 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. ## Controle de acesso e roteamento - `channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a allowlist canônica de DM. + `channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a lista de permissões canônica de DM. - `pairing` (padrão) - `allowlist` @@ -527,9 +527,9 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil - `channels.slack.allowFrom` - `dm.allowFrom` (legado) - `dm.groupEnabled` (DMs em grupo padrão false) - - `dm.groupChannels` (allowlist opcional de MPIM) + - `dm.groupChannels` (lista de permissões MPIM opcional) - Precedência em várias contas: + Precedência de 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. @@ -537,31 +537,31 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil `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. - O pareamento em DMs usa `openclaw pairing approve slack `. + O emparelhamento em DMs usa `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` controla o tratamento de canais: - `open` - `allowlist` - `disabled` - A allowlist de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal Slack** (por exemplo, `C12345678`) como chaves de configuração. + 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. - Nota de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime volta para `groupPolicy="allowlist"` e registra um aviso (mesmo se `channels.defaults.groupPolicy` estiver definido). + 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). Resolução de nome/ID: - - entradas da allowlist de canais e entradas da allowlist de DM são resolvidas na inicialização quando o acesso por token permite - - entradas não resolvidas por nome de canal 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 por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` + - 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` - Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de canal é ID-first por padrão, portanto uma chave baseada em nome nunca roteará 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 é exigida para roteamento e uma chave baseada em nome parece funcionar. + 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. - Sempre use o ID do canal Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copy link** — o ID (`C...`) aparece no fim 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 final da URL. Correto: @@ -578,7 +578,7 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil } ``` - Incorreto (bloqueado silenciosamente em `groupPolicy: "allowlist"`): + Incorreto (bloqueado silenciosamente sob `groupPolicy: "allowlist"`): ```json5 { @@ -596,28 +596,28 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil - - Mensagens de canal exigem menção por padrão. + + Mensagens de canal são controladas por menções por padrão. - Origens de mençã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; exige `usergroups:read` + - 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 ao bot em thread (desativado quando `thread.requireExplicitMention` é `true`) + - comportamento implícito de resposta para thread do bot (desativado quando `thread.requireExplicitMention` é `true`) - Controles por canal (`channels.slack.channels.`; nomes apenas por resolução na inicialização ou `dangerouslyAllowNameMatching`): + Controles por canal (`channels.slack.channels.`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`): - `requireMention` - - `users` (allowlist) + - `users` (lista de permissões) - `allowBots` - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"` - (chaves legadas sem prefixo ainda mapeiam apenas para `id:`) + - formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, ou curinga `"*"` + (chaves legadas sem prefixo ainda mapeiam somente para `id:`) - `allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bots são aceitas apenas quando o bot remetente está explicitamente listado na allowlist `users` dessa sala, ou quando pelo menos um ID explícito de proprietário 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; verifique se o app tem o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a busca 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 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. @@ -625,13 +625,13 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil ## Threads, sessões e tags de resposta - DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`. -- Vinculações de rota do Slack aceitam IDs brutos de pares e formas de destino Slack, como `channel:C12345678`, `user:U12345678` e `<@U12345678>`. -- Com o padrão `session.dmScope=main`, DMs do Slack são colapsadas para a sessão principal do agente. +- 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. - Sessões de canal: `agent::slack:channel:`. - Respostas em thread 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 de thread existentes 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 threads para que o bot só responda 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 contornam o gate de `requireMention`. +- `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`. Controles de threading de resposta: @@ -639,51 +639,70 @@ Controles de threading de resposta: - `channels.slack.replyToModeByChatType`: por `direct|group|channel` - fallback legado para chats diretos: `channels.slack.dm.replyToMode` -Tags manuais de resposta têm suporte: +Tags manuais de resposta são compatíveis: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` desativa **todo** threading de resposta 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 inline. +`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. ## Reações de confirmação -`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. +`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. Ordem de resolução: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀") +- fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") -Notas: +Observações: - O Slack espera shortcodes (por exemplo, `"eyes"`). -- Use `""` para desativar a reação para a conta Slack ou globalmente. +- Use `""` para desativar a reação para a conta do Slack ou globalmente. ## Streaming de texto -`channels.slack.streaming` controla o comportamento de prévia ao vivo: +`channels.slack.streaming` controla o comportamento de pré-visualização ao vivo: -- `off`: desativa streaming de prévia ao vivo. -- `partial` (padrão): substitui o texto da prévia pela saída parcial mais recente. -- `block`: acrescenta atualizações de prévia em chunks. -- `progress`: mostra texto de status de progresso durante a geração e, depois, envia o texto final. -- `streaming.preview.toolProgress`: quando a prévia de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de prévia editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso. +- `off`: desativa 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. +- `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.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: + +```json +{ + "channels": { + "slack": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` `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`. -- Canais, chats em grupo e raízes de DM de nível superior ainda podem usar a prévia de rascunho normal quando o streaming nativo está indisponível ou não existe thread de resposta. -- DMs Slack de nível superior ficam fora de thread por padrão, então não mostram a prévia de stream/status nativo no estilo de thread do Slack; o OpenClaw publica e edita uma prévia de rascunho na DM em vez disso. -- Payloads de mídia e não texto fazem fallback para a entrega normal. -- Finais de mídia/erro cancelam edições de prévia pendentes; finais elegíveis de texto/bloco só são descarregados quando conseguem editar a prévia no local. -- Se o streaming falhar no meio da resposta, o OpenClaw faz fallback para a entrega normal para os payloads restantes. +- 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. -Use prévia de rascunho em vez de streaming de texto nativo do Slack: +Use pré-visualização de rascunho em vez de streaming de texto nativo do Slack: ```json5 { @@ -700,58 +719,58 @@ Use prévia de rascunho em vez de streaming de texto nativo do Slack: Chaves legadas: -- `channels.slack.streamMode` (`replace | status_final | append`) é migrado automaticamente para `channels.slack.streaming.mode`. +- `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`. ## Fallback de reação de digitação -`typingReaction` adiciona uma reação temporária à mensagem Slack recebida 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 "is typing...". +`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...". Ordem de resolução: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -Notas: +Observações: -- O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`). -- A reação é best-effort, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído. +- 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. ## Mídia, fragmentação e entrega - - 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 tem sucesso 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`. + + 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 downloads usam tempos limite ociosos e totais delimitados. 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 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. - 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`. + O limite de tamanho de entrada em runtime 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) - `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 threads (`thread_ts`) + - 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 - - Destinos explícitos preferenciais: + + Destinos explícitos preferidos: - `user:` para DMs - `channel:` para canais - DMs do Slack somente com texto/blocos podem publicar diretamente em IDs de usuário; uploads de arquivos e envios em threads abrem a DM primeiro por meio das APIs de conversa do Slack porque esses caminhos exigem um ID de conversa concreto. + 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. ## Comandos e comportamento de slash -Comandos slash aparecem no Slack como um único comando configurado ou vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando: +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: - `enabled: false` - `name: "openclaw"` @@ -762,30 +781,30 @@ Comandos slash aparecem no Slack como um único comando configurado ou vários c /openclaw /help ``` -Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app do 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 aplicativo 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 Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. +- O modo automático de comandos nativos fica **desativado** para o Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. ```txt /help ``` -Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar o valor da opção selecionada: +Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar um valor de opção selecionado: -- até 5 opções: blocos de botão -- 6-100 opções: menu de seleção estática -- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando handlers de opções de interatividade estão disponíveis +- até 5 opções: blocos de botões +- 6-100 opções: menu de seleção estático +- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando manipuladores de opções de interatividade estiverem disponíveis - limites do Slack excedidos: valores de opção codificados recorrem a botões ```txt /think ``` -Sessões slash usam chaves isoladas como `agent::slack:slash:` e ainda roteiam execuções de comandos para a sessão da conversa de destino usando `CommandTargetSessionKey`. +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`. ## Respostas interativas -O Slack pode renderizar controles de resposta interativos criados por agentes, mas esse recurso é desabilitado por padrão. +O Slack pode renderizar controles de resposta interativa criados por agentes, mas esse recurso fica desabilitado por padrão. Habilite globalmente: @@ -801,7 +820,7 @@ Habilite globalmente: } ``` -Ou habilite somente para uma conta do Slack: +Ou habilite para apenas uma conta do Slack: ```json5 { @@ -819,30 +838,30 @@ Ou habilite somente para uma conta do Slack: } ``` -Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slack: +Quando habilitado, os 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 eventos de interação existente do Slack. +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. 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 de blocos inválida. +- 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. -## Aprovações de exec no Slack +## Aprovações de execução no Slack -O Slack pode atuar como um cliente de aprovação nativo com botões e interações interativas, em vez de recorrer à UI Web ou ao terminal. +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 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 do ID de aprovação é `plugin:`. -- A autorização de aprovadores continua sendo aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack. +- Aprovações de execução 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. -Isso usa a mesma superfície compartilhada de botões de aprovação de outros canais. Quando `interactivity` está habilitado nas configurações do seu app do Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa. +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 diz que aprovações +só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho. Caminho de configuração: @@ -852,11 +871,11 @@ Caminho de configuração: - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter` -O Slack habilita automaticamente aprovações de exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um +O Slack habilita automaticamente aprovações de execução nativas 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 exec do Slack: +Comportamento padrão sem configuração explícita de aprovação de execução do Slack: ```json5 { @@ -883,37 +902,37 @@ optar por entrega no chat de origem: } ``` -O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de exec também precisarem +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 é 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á aceitam comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovações. +`/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. ## Eventos e comportamento operacional - Edições/exclusões de mensagens são mapeadas para eventos do sistema. -- Transmissões de threads (respostas de thread com "Também enviar ao canal") são processadas como mensagens normais de usuário. -- Eventos de adição/remoção de reação são mapeados para eventos do sistema. -- Eventos de entrada/saída de membro, canal criado/renomeado e adição/remoção de pin são mapeados 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. - `channel_id_changed` pode migrar chaves de configuração de canal quando `configWrites` está habilitado. -- Metadados de tópico/propósito do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento. -- O iniciador da thread e a semeadura inicial de contexto de histórico da thread são filtrados por allowlists de remetentes configuradas quando aplicável. -- Ações de bloco e interações modais emitem eventos do sistema estruturados `Slack interaction: ...` com campos de carga ricos: +- 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: - 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 roteados e entradas de formulário + - eventos modais `view_submission` e `view_closed` com metadados de canal roteado e entradas de formulário ## Referência de configuração Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/config-channels#slack). - + -- modo/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- 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` (quebra-vidro; mantenha desativado, a menos que necessário) -- acesso a canais: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- threading/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- alternância de compatibilidade: `dangerouslyAllowNameMatching` (uso emergencial; mantenha desativado a menos que necessário) +- acesso a canal: `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` @@ -922,13 +941,13 @@ Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/co ## Solução de problemas - + Verifique, na ordem: - `groupPolicy` - - allowlist de canal (`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 canais 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 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. - `requireMention` - - allowlist `users` por canal + - allowlist de `users` por canal Comandos úteis: @@ -940,14 +959,14 @@ openclaw doctor - + Verifique: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (ou o legado `channels.slack.dm.policy`) + - `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 de thread do Assistant editado sem um + - 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 remetente humano recuperável nos metadados da mensagem ```bash @@ -956,54 +975,54 @@ openclaw pairing list slack - - Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do app do Slack. + + Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do aplicativo 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 baseado em - SecretRef. + configurada, mas o runtime atual não conseguiu resolver o valor + respaldado por SecretRef. - + Valide: - segredo de assinatura - caminho de Webhook - - URLs de solicitação do Slack (Eventos + Interatividade + Comandos slash) - - `webhookPath` único por conta HTTP + - URLs de solicitação do Slack (Eventos + Interatividade + Comandos Slash) + - `webhookPath` exclusivo 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 baseado em SecretRef. + resolver o segredo de assinatura respaldado por 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`) - Também verifique `commands.useAccessGroups` e allowlists de canal/usuário. + Verifique também `commands.useAccessGroups` e allowlists de canais/usuários. ## Referência de visão de anexos -O Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivos do Slack têm sucesso e os limites de tamanho permitem. Arquivos de imagem podem ser passados pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta compatível com visão; outros arquivos são retidos como contexto de arquivo baixável em vez de tratados como entrada de imagem. +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. ### 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 com suporte a visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) | +| 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 iniciador da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Iniciadores apenas com arquivo usam um placeholder de anexo | -| Mensagens com várias imagens | Vários arquivos do Slack | Cada arquivo é avaliado independentemente | O processamento do Slack é limitado a oito arquivos por mensagem | +| 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 | ### Pipeline de entrada @@ -1011,70 +1030,70 @@ 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. Caminhos de mídia baixada e tipos de conteúdo são adicionados ao contexto de entrada. -4. Caminhos de modelo/ferramenta com suporte a imagem podem usar anexos de imagem desse contexto. -5. Arquivos que não são imagens permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que conseguem processá-los. +3. Os caminhos de mídia baixados e os 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. ### 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 da raiz como contexto do iniciador 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 de início 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. -### Tratamento de vários anexos +### Tratamento de múltiplos anexos Quando uma única mensagem do Slack contém vários anexos de arquivo: -- Cada anexo é processado independentemente pelo pipeline de mídia. -- Referências de mídia baixada são agregadas ao contexto da mensagem. +- Cada anexo é processado de forma independente 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. -- Uma falha no download de um anexo não bloqueia os demais. +- 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 não compatíveis. -- **Modelo de visão**: A análise de imagem usa o modelo de resposta ativo quando ele tem suporte a visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`. +- **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. +- **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 | -| 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 com suporte a 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 em modo best-effort | 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 | +| URL de arquivo do 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 | ### Documentação relacionada - [Pipeline de compreensão de mídia](/pt-BR/nodes/media-understanding) - [Ferramenta PDF](/pt-BR/tools/pdf) -- Épico: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack +- Epic: [#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) -## Relacionado +## Relacionados - - Emparelhe um usuário do Slack ao Gateway. + + Pareie um usuário do Slack ao Gateway. - - Comportamento de canais e DMs de grupo. + + Comportamento de canal e DM em grupo. - + Roteie mensagens de entrada para agentes. - + Modelo de ameaças e hardening. - - Layout e precedência da configuração. + + Layout e precedência de configuração. - + Catálogo e comportamento de comandos. diff --git a/docs/pt-BR/channels/telegram.md b/docs/pt-BR/channels/telegram.md index 68fc73fd2..b0fd4dbbd 100644 --- a/docs/pt-BR/channels/telegram.md +++ b/docs/pt-BR/channels/telegram.md @@ -4,24 +4,24 @@ read_when: summary: Status de suporte, recursos e configuração do bot do Telegram title: Telegram x-i18n: - generated_at: "2026-05-03T21:27:12Z" + generated_at: "2026-05-04T07:02:43Z" model: gpt-5.5 provider: openai - source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0 + source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6 source_path: channels/telegram.md workflow: 16 --- -Pronto para produção para DMs e grupos de bot via grammY. Long polling é o modo padrão; o modo webhook é opcional. +Pronto para produção para DMs e grupos de bots via grammY. O long polling é o modo padrão; o modo Webhook é opcional. - - A política padrão de DM para Telegram é pairing. + + A política padrão de DM para Telegram é emparelhamento. - + Diagnósticos entre canais e playbooks de reparo. - + Padrões e exemplos completos de configuração de canal. @@ -29,14 +29,14 @@ Pronto para produção para DMs e grupos de bot via grammY. Long polling é o mo ## Configuração rápida - + Abra o Telegram e converse com **@BotFather** (confirme que o identificador é exatamente `@BotFather`). Execute `/newbot`, siga as instruções e salve o token. - + ```json5 { @@ -52,11 +52,11 @@ Pronto para produção para DMs e grupos de bot via grammY. Long polling é o mo ``` Fallback de env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão). - Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e então inicie o gateway. + Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/env e depois inicie o Gateway. - + ```bash openclaw gateway @@ -64,42 +64,42 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Códigos de pairing expiram após 1 hora. + Os códigos de emparelhamento expiram após 1 hora. - - Adicione o bot ao seu grupo e então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. + + Adicione o bot ao seu grupo e, em seguida, defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. -A ordem de resolução de tokens considera a conta. Na prática, valores de configuração prevalecem sobre o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão. +A ordem de resolução de token considera a conta. Na prática, valores de configuração têm precedência sobre o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão. -## Configurações no lado do Telegram +## Configurações do lado do Telegram - - Bots do Telegram usam **Privacy Mode** por padrão, o que limita quais mensagens de grupo eles recebem. + + Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem. - Se o bot precisar ver todas as mensagens de grupo: + Se o bot precisar ver todas as mensagens de grupo, faça uma destas opções: - desative o modo de privacidade via `/setprivacy`, ou - - torne o bot um administrador do grupo. + - torne o bot administrador do grupo. Ao alternar o modo de privacidade, remova e adicione novamente o bot em cada grupo para que o Telegram aplique a alteração. - - O status de administrador é controlado nas configurações do grupo do Telegram. + + O status de administrador é controlado nas configurações de grupo do Telegram. Bots administradores recebem todas as mensagens de grupo, o que é útil para comportamento de grupo sempre ativo. - + - `/setjoingroups` para permitir/negar adições a grupos - `/setprivacy` para comportamento de visibilidade em grupos @@ -110,7 +110,7 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf ## Controle de acesso e ativação - + `channels.telegram.dmPolicy` controla o acesso por mensagem direta: - `pairing` (padrão) @@ -118,23 +118,23 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf - `open` (exige que `allowFrom` inclua `"*"`) - `disabled` - `dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use isso apenas para bots intencionalmente públicos com ferramentas estritamente restritas; bots de um único proprietário devem usar `allowlist` com IDs numéricos de usuário. + `dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use isso somente para bots intencionalmente públicos com ferramentas rigidamente restritas; bots de um único proprietário devem usar `allowlist` com IDs numéricos de usuário. `channels.telegram.allowFrom` aceita IDs numéricos de usuário do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados. - Em configurações de múltiplas contas, um `channels.telegram.allowFrom` restritivo no nível superior é tratado como um limite de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a allowlist efetiva da conta ainda contenha um curinga explícito após a mesclagem. - `dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação da configuração. - A configuração inicial solicita apenas IDs numéricos de usuário. - Se você atualizou e sua configuração contém entradas de allowlist `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram). - Se você dependia anteriormente de arquivos de allowlist do armazenamento de pairing, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). + Em configurações de várias contas, um `channels.telegram.allowFrom` restritivo no nível superior é tratado como um limite de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a lista de permissões efetiva da conta ainda contenha um curinga explícito após a mesclagem. + `dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração. + A configuração inicial pede somente IDs numéricos de usuário. + Se você atualizou e sua configuração contém entradas de lista de permissões `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram). + Se você anteriormente dependia de arquivos de lista de permissões do armazenamento de emparelhamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de lista de permissões (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). - Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pairing anteriores). + Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de emparelhamento anteriores). - Confusão comum: aprovação de pairing por DM não significa "este remetente está autorizado em todos os lugares". - O pairing concede acesso por DM. Se ainda não existir proprietário de comandos, o primeiro pairing aprovado também define `commands.ownerAllowFrom` para que comandos somente de proprietário e aprovações de execução tenham uma conta de operador explícita. - A autorização de remetente em grupo ainda vem de allowlists explícitas na configuração. - Se você quer "eu sou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos somente de proprietário, verifique se `commands.ownerAllowFrom` contém `telegram:`. + Confusão comum: aprovação de emparelhamento por DM não significa "este remetente está autorizado em todos os lugares". + O emparelhamento concede acesso por DM. Se ainda não houver proprietário de comandos, o primeiro emparelhamento aprovado também define `commands.ownerAllowFrom` para que comandos exclusivos do proprietário e aprovações de execução tenham uma conta de operador explícita. + A autorização de remetentes em grupo ainda vem de listas de permissões explícitas na configuração. + Se você quer "estou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos exclusivos do proprietário, garanta que `commands.ownerAllowFrom` contenha `telegram:`. - ### Encontrar seu ID de usuário do Telegram + ### Encontrando seu ID de usuário do Telegram Mais seguro (sem bot de terceiros): @@ -152,14 +152,14 @@ curl "https://api.telegram.org/bot/getUpdates" - + Dois controles se aplicam em conjunto: 1. **Quais grupos são permitidos** (`channels.telegram.groups`) - sem configuração `groups`: - com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo - - com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`) - - `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`) + - com `groupPolicy: "allowlist"` (padrão): grupos ficam bloqueados até você adicionar entradas em `groups` (ou `"*"`) + - `groups` configurado: atua como lista de permissões (IDs explícitos ou `"*"`) 2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`) - `open` @@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` é usado para filtragem de remetentes em grupo. Se não definido, Telegram recorre a `allowFrom`. Entradas `groupAllowFrom` devem ser IDs numéricos de usuário do Telegram (prefixos `telegram:` / `tg:` são normalizados). - Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`. + Não coloque IDs de chat de grupos ou supergrupos do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`. Entradas não numéricas são ignoradas para autorização de remetente. - Limite de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações do armazenamento de pairing de DM. - Pairing continua sendo somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico. - Se `groupAllowFrom` não estiver definido, Telegram recorre ao `allowFrom` da configuração, não ao armazenamento de pairing. - Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos de destino em `channels.telegram.groups`. - Nota de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão fail-closed `groupPolicy="allowlist"`, a menos que `channels.defaults.groupPolicy` esteja explicitamente definido. + Limite de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações de armazenamento de emparelhamento por DM. + O emparelhamento permanece somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico. + Se `groupAllowFrom` não estiver definido, Telegram recorre a `allowFrom` da configuração, não ao armazenamento de emparelhamento. + Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos-alvo em `channels.telegram.groups`. + Nota de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão `groupPolicy="allowlist"` com falha fechada, a menos que `channels.defaults.groupPolicy` esteja explicitamente definido. Exemplo: permitir qualquer membro em um grupo específico: @@ -211,17 +211,17 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram. + Erro comum: `groupAllowFrom` não é uma lista de permissões de grupos do Telegram. - - Coloque IDs de chat negativos de grupo ou supergrupo do Telegram, como `-1001234567890`, em `channels.telegram.groups`. + - Coloque IDs de chat negativos de grupos ou supergrupos do Telegram, como `-1001234567890`, em `channels.telegram.groups`. - Coloque IDs de usuário do Telegram, como `8734062810`, em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot. - - Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot. + - Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido consiga falar com o bot. - + Respostas em grupo exigem menção por padrão. A menção pode vir de: @@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - Elas atualizam apenas o estado da sessão. Use configuração para persistência. + Elas atualizam somente o estado da sessão. Use configuração para persistência. Exemplo de configuração persistente: @@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Obter o ID do chat de grupo: + Obtendo o ID do chat do grupo: - encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot` - ou leia `chat.id` em `openclaw logs --follow` @@ -263,20 +263,20 @@ curl "https://api.telegram.org/bot/getUpdates" ## Comportamento de runtime -- Telegram é propriedade do processo do gateway. -- O roteamento é determinístico: entradas do Telegram respondem de volta ao Telegram (o modelo não escolhe canais). -- Mensagens de entrada são normalizadas para o envelope de canal compartilhado com metadados de resposta e placeholders de mídia. +- Telegram é de propriedade do processo do Gateway. +- O roteamento é determinístico: entradas do Telegram respondem de volta no Telegram (o modelo não escolhe canais). +- Mensagens de entrada são normalizadas no envelope de canal compartilhado com metadados de resposta e placeholders de mídia. - Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum acrescentam `:topic:` para manter os tópicos isolados. -- Mensagens de DM podem carregar `message_thread_id`; OpenClaw preserva o ID da thread para respostas, mas mantém DMs na sessão plana por padrão. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` ou uma configuração de tópico correspondente quando você quiser intencionalmente isolamento de sessão por tópico de DM. -- Long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`. -- Long polling é protegido dentro de cada processo do gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, outro gateway OpenClaw, script ou poller externo provavelmente está usando o mesmo token. -- Reinícios do watchdog de long polling são acionados após 120 segundos sem liveness de `getUpdates` concluído por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se sua implantação ainda vir reinícios falsos por polling paralisado durante trabalho de longa duração. O valor é em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis. -- A Telegram Bot API não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica). +- Mensagens de DM podem carregar `message_thread_id`; OpenClaw preserva o ID da conversa para respostas, mas mantém DMs na sessão plana por padrão. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` ou uma configuração de tópico correspondente quando você intencionalmente quiser isolamento de sessão por tópico de DM. +- Long polling usa o runner do grammY com sequenciamento por chat/por conversa. A concorrência geral do coletor do runner usa `agents.defaults.maxConcurrent`. +- Long polling é protegido dentro de cada processo do Gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, outro Gateway do OpenClaw, script ou poller externo provavelmente está usando o mesmo token. +- Reinicializações do watchdog de long polling são acionadas após 120 segundos sem vivacidade de `getUpdates` concluída por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se sua implantação ainda vir reinicializações falsas por travamento de polling durante trabalhos de longa duração. O valor está em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis. +- A Telegram Bot API não oferece suporte a recibos de leitura (`sendReadReceipts` não se aplica). ## Referência de recursos - + OpenClaw pode transmitir respostas parciais em tempo real: - chats diretos: mensagem de prévia + `editMessageText` @@ -286,10 +286,11 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`) - `progress` mantém um rascunho de status editável e o atualiza com progresso de ferramentas até a entrega final - - `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando streaming de prévia está ativo) + - `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando a transmissão de prévia está ativa) + - `streaming.preview.commandText` controla detalhes de comando/execução dentro dessas linhas de progresso de ferramenta: `raw` (padrão, preserva o comportamento lançado) ou `status` (somente rótulo da ferramenta) - `channels.telegram.streamMode` legado e valores booleanos de `streaming` são detectados; execute `openclaw doctor --fix` para migrá-los para `channels.telegram.streaming.mode` - Atualizações de prévia de progresso de ferramentas são as linhas curtas de status mostradas enquanto ferramentas executam, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. Telegram mantém essas atualizações ativadas por padrão para corresponder ao comportamento lançado do OpenClaw a partir de `v2026.4.22`. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramentas, defina: + Atualizações de prévia de progresso de ferramenta são as linhas curtas de status mostradas enquanto ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patch. Telegram as mantém ativadas por padrão para corresponder ao comportamento lançado do OpenClaw a partir de `v2026.4.22`. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramenta, defina: ```json { @@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Use `streaming.mode: "off"` somente quando você quiser entrega apenas final: as edições de prévia do Telegram são desativadas e a conversa genérica de ferramentas/progresso é suprimida em vez de ser enviada como mensagens de status independentes. Prompts de aprovação, cargas de mídia e erros ainda são roteados pela entrega final normal. Use `streaming.preview.toolProgress: false` quando você quiser apenas manter as edições de prévia da resposta enquanto oculta as linhas de status de progresso da ferramenta. + Para manter o progresso de ferramenta visível, mas ocultar texto de comando/execução, defina: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "partial", + "preview": { + "commandText": "status" + } + } + } + } + } + ``` + + Para o modo de rascunho de progresso, coloque a mesma política de texto de comando em `streaming.progress`: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + Use `streaming.mode: "off"` somente quando quiser entrega apenas final: as edições de pré-visualização do Telegram são desativadas e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens de status independentes. Prompts de aprovação, cargas de mídia e erros ainda passam pela entrega final normal. Use `streaming.preview.toolProgress: false` quando quiser manter apenas as edições de pré-visualização da resposta enquanto oculta as linhas de status de progresso da ferramenta. - Respostas com citação selecionada do Telegram são a exceção. Quando `replyToMode` é `"first"`, `"all"` ou `"batched"` e a mensagem recebida inclui texto de citação selecionado, o OpenClaw envia a resposta final pelo caminho nativo de resposta com citação do Telegram em vez de editar a prévia da resposta, portanto `streaming.preview.toolProgress` não consegue mostrar as linhas curtas de status nesse turno. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de prévia. Defina `replyToMode: "off"` quando a visibilidade do progresso da ferramenta for mais importante do que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer a troca. + As respostas a citações selecionadas do Telegram são a exceção. Quando `replyToMode` é `"first"`, `"all"` ou `"batched"` e a mensagem recebida inclui texto de citação selecionado, o OpenClaw envia a resposta final pelo caminho nativo de resposta com citação do Telegram em vez de editar a pré-visualização da resposta, portanto `streaming.preview.toolProgress` não pode mostrar as linhas curtas de status para essa interação. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de pré-visualização. Defina `replyToMode: "off"` quando a visibilidade do progresso da ferramenta for mais importante do que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer essa troca. - Para respostas somente de texto: + Para respostas somente em texto: - - prévias curtas em DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no lugar, a menos que uma mensagem visível que não seja de prévia tenha sido enviada depois que a prévia apareceu - - prévias seguidas por saída visível que não seja de prévia: o OpenClaw envia a resposta concluída como uma nova mensagem final e limpa a prévia mais antiga, para que a resposta final apareça depois da saída intermediária - - prévias com mais de cerca de um minuto: o OpenClaw envia a resposta concluída como uma nova mensagem final e então limpa a prévia, para que o timestamp visível do Telegram reflita o horário de conclusão em vez do horário de criação da prévia + - pré-visualizações curtas em DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar, a menos que uma mensagem visível que não seja de pré-visualização tenha sido enviada depois que a pré-visualização apareceu + - pré-visualizações seguidas por saída visível que não seja de pré-visualização: o OpenClaw envia a resposta concluída como uma nova mensagem final e limpa a pré-visualização antiga, para que a resposta final apareça depois da saída intermediária + - pré-visualizações com mais de cerca de um minuto: o OpenClaw envia a resposta concluída como uma nova mensagem final e depois limpa a pré-visualização, para que o carimbo de data/hora visível do Telegram reflita o horário de conclusão em vez do horário de criação da pré-visualização - Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw recorre à entrega final normal e então limpa a mensagem de prévia. + Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw recorre à entrega final normal e depois limpa a mensagem de pré-visualização. - Streaming de prévia é separado de streaming de blocos. Quando o streaming de blocos é explicitamente habilitado para Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplicado. + O streaming de pré-visualização é separado do streaming de blocos. Quando o streaming de blocos é explicitamente ativado para o Telegram, o OpenClaw ignora o stream de pré-visualização para evitar streaming duplicado. - Stream de raciocínio exclusivo do Telegram: + Stream de raciocínio somente no Telegram: - - `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração + - `/reasoning stream` envia o raciocínio para a pré-visualização ao vivo durante a geração + - a pré-visualização do raciocínio é excluída após a entrega final; use `/reasoning on` quando o raciocínio deve permanecer visível - a resposta final é enviada sem texto de raciocínio @@ -332,20 +369,20 @@ curl "https://api.telegram.org/bot/getUpdates" O texto de saída usa `parse_mode: "HTML"` do Telegram. - - Texto no estilo Markdown é renderizado como HTML seguro para Telegram. + - Texto no estilo Markdown é renderizado como HTML seguro para o Telegram. - HTML bruto do modelo é escapado para reduzir falhas de análise do Telegram. - Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples. - Prévias de link são habilitadas por padrão e podem ser desabilitadas com `channels.telegram.linkPreview: false`. + Pré-visualizações de links são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`. O registro do menu de comandos do Telegram é tratado na inicialização com `setMyCommands`. - Padrões de comandos nativos: + Padrões de comando nativo: - - `commands.native: "auto"` habilita comandos nativos para Telegram + - `commands.native: "auto"` ativa comandos nativos para o Telegram Adicione entradas personalizadas ao menu de comandos: @@ -367,37 +404,37 @@ curl "https://api.telegram.org/bot/getUpdates" - nomes são normalizados (remove `/` inicial, minúsculas) - padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32` - comandos personalizados não podem substituir comandos nativos - - conflitos/duplicatas são ignorados e registrados + - conflitos/duplicatas são ignorados e registrados em log Observações: - comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente - - comandos de plugin/skill ainda podem funcionar quando digitados, mesmo se não forem mostrados no menu do Telegram + - comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram - Se comandos nativos estiverem desabilitados, os integrados são removidos. Comandos personalizados/de plugin ainda podem ser registrados se configurados. + Se comandos nativos estiverem desativados, os integrados serão removidos. Comandos personalizados/de Plugin ainda podem ser registrados se configurados. Falhas comuns de configuração: - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos de plugin/skill/personalizados ou desabilite `channels.telegram.commands.native`. - - falha em `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos curl diretos da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove uma terminação acidental `/bot`. - - `getMe returned 401` significa que o Telegram rejeitou o token de bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, portanto isso não é relatado como falha de limpeza de webhook. + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após a redução; reduza comandos de Plugin/Skills/personalizados ou desative `channels.telegram.commands.native`. + - Falha em `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos curl diretos da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot` final acidental. + - `getMe returned 401` significa que o Telegram rejeitou o token do bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como uma falha de limpeza de Webhook. - `setMyCommands failed` com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado. - ### Comandos de pareamento de dispositivo (plugin `device-pair`) + ### Comandos de pareamento de dispositivo (Plugin `device-pair`) - Quando o plugin `device-pair` estiver instalado: + Quando o Plugin `device-pair` está instalado: - 1. `/pair` gera código de configuração + 1. `/pair` gera o código de configuração 2. cole o código no app iOS 3. `/pair pending` lista solicitações pendentes (incluindo função/escopos) 4. aprove a solicitação: - `/pair approve ` para aprovação explícita - - `/pair approve` quando houver apenas uma solicitação pendente + - `/pair approve` quando há apenas uma solicitação pendente - `/pair approve latest` para a mais recente - O código de configuração carrega um token de bootstrap de curta duração. O handoff de bootstrap integrado mantém o token do node primário em `scopes: []`; qualquer token de operador repassado permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap têm prefixo de função, então essa lista de permissões de operador só satisfaz solicitações de operador; funções que não são de operador ainda precisam de escopos sob seu próprio prefixo de função. + O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap integrada mantém o token do nó principal em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap são prefixadas por função, portanto essa allowlist de operador só satisfaz solicitações de operador; funções que não sejam de operador ainda precisam de escopos sob seu próprio prefixo de função. - Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute novamente `/pair pending` antes de aprovar. + Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar. Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -444,7 +481,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (padrão) - `capabilities: ["inlineButtons"]` legado mapeia para `inlineButtons: "all"`. + `capabilities: ["inlineButtons"]` legado é mapeado para `inlineButtons: "all"`. Exemplo de ação de mensagem: @@ -469,36 +506,36 @@ curl "https://api.telegram.org/bot/getUpdates" - + As ações de ferramenta do Telegram incluem: - - `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`) - Ações de mensagens de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Controles de restrição: + Controles de bloqueio: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - - `channels.telegram.actions.sticker` (padrão: desabilitado) + - `channels.telegram.actions.sticker` (padrão: desativado) - Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm toggles `channels.telegram.actions.*` separados. - Envios em runtime usam o snapshot ativo de configuração/segredos (inicialização/reload), portanto caminhos de ação não executam nova resolução ad hoc de SecretRef por envio. + Observação: `edit` e `topic-create` atualmente são ativados por padrão e não têm alternâncias separadas em `channels.telegram.actions.*`. + Envios em tempo de execução usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), então caminhos de ação não fazem nova resolução ad hoc de SecretRef a cada envio. Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions) - - O Telegram oferece suporte a tags explícitas de encadeamento de respostas na saída gerada: + + O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada: - - `[[reply_to_current]]` responde à mensagem disparadora - - `[[reply_to:]]` responde a um ID de mensagem específico do Telegram + - `[[reply_to_current]]` responde à mensagem acionadora + - `[[reply_to:]]` responde a um ID específico de mensagem do Telegram `channels.telegram.replyToMode` controla o tratamento: @@ -506,9 +543,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Quando o encadeamento de respostas está habilitado e o texto ou legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas desde o início e recorrem a uma resposta simples se o Telegram rejeitar a citação. + Quando o encadeamento de resposta está ativado e o texto ou a legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas a partir do início e recorrem a uma resposta simples se o Telegram rejeitar a citação. - Observação: `off` desabilita o encadeamento de respostas implícito. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. + Observação: `off` desativa o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. @@ -516,8 +553,8 @@ curl "https://api.telegram.org/bot/getUpdates" Supergrupos de fórum: - chaves de sessão de tópico acrescentam `:topic:` - - respostas e digitação miram a thread do tópico - - caminho de configuração do tópico: + - respostas e indicação de digitação miram a thread do tópico + - caminho de configuração de tópico: `channels.telegram.groups..topics.` Caso especial do tópico geral (`threadId=1`): @@ -525,8 +562,8 @@ curl "https://api.telegram.org/bot/getUpdates" - envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`) - ações de digitação ainda incluem `message_thread_id` - Herança de tópico: entradas de tópico herdam configurações de grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` é exclusivo do tópico e não herda dos padrões do grupo. + Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` é exclusivo do tópico e não herda os padrões do grupo. **Roteamento de agente por tópico**: Cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo: @@ -550,24 +587,24 @@ curl "https://api.telegram.org/bot/getUpdates" Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3` - **Vinculação persistente de tópico ACP**: Tópicos de fórum podem fixar sessões de harness ACP por meio de vinculações ACP tipadas de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e um id qualificado por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents). + **Vínculo persistente de tópico ACP**: Tópicos de fórum podem fixar sessões de harness ACP por meio de vínculos ACP tipados de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e um id qualificado por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents). - **Spawn ACP vinculado a thread a partir do chat**: `/acp spawn --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de spawn no tópico. Requer que `channels.telegram.threadBindings.spawnSessions` permaneça habilitado (padrão: `true`). + **Spawn de ACP vinculado à thread a partir do chat**: `/acp spawn --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de spawn no tópico. Exige que `channels.telegram.threadBindings.spawnSessions` permaneça ativado (padrão: `true`). - O contexto do template expõe `MessageThreadId` e `IsForum`. Chats de DM com `message_thread_id` mantêm roteamento de DM e metadados de resposta em sessões planas por padrão; eles só usam chaves de sessão com reconhecimento de thread quando configurados com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` de nível superior para o padrão da conta, ou `direct..threadReplies` para uma DM. + O contexto do template expõe `MessageThreadId` e `IsForum`. Conversas diretas com `message_thread_id` mantêm roteamento de mensagem direta e metadados de resposta em sessões planas por padrão; elas só usam chaves de sessão com reconhecimento de encadeamento quando configuradas com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` no nível superior para o padrão da conta, ou `direct..threadReplies` para uma conversa direta. - + ### Mensagens de áudio O Telegram distingue notas de voz de arquivos de áudio. - padrão: comportamento de arquivo de áudio - - tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz - - transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina, - não confiável no contexto do agente; a detecção de menção ainda usa a transcrição - bruta, então mensagens de voz restritas por menção continuam funcionando. + - tag `[[audio_as_voice]]` na resposta do agente para forçar o envio como nota de voz + - transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina + e não confiável no contexto do agente; a detecção de menção ainda usa a transcrição + bruta para que mensagens de voz controladas por menção continuem funcionando. Exemplo de ação de mensagem: @@ -583,7 +620,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Mensagens de vídeo - Telegram distingue arquivos de vídeo de notas de vídeo. + O Telegram distingue arquivos de vídeo de notas de vídeo. Exemplo de ação de mensagem: @@ -597,7 +634,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Notas de vídeo não oferecem suporte a legendas; o texto de mensagem fornecido é enviado separadamente. + Notas de vídeo não aceitam legendas; o texto de mensagem fornecido é enviado separadamente. ### Figurinhas @@ -607,7 +644,7 @@ curl "https://api.telegram.org/bot/getUpdates" - TGS animado: ignorado - WEBM de vídeo: ignorado - Campos de contexto da figurinha: + Campos de contexto de figurinha: - `Sticker.emoji` - `Sticker.setName` @@ -619,7 +656,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - As figurinhas são descritas uma vez (quando possível) e armazenadas em cache para reduzir chamadas repetidas de visão. + Figurinhas são descritas uma vez (quando possível) e armazenadas em cache para reduzir chamadas de visão repetidas. Habilitar ações de figurinha: @@ -635,7 +672,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Ação de enviar figurinha: + Ação para enviar figurinha: ```json5 { @@ -660,9 +697,9 @@ curl "https://api.telegram.org/bot/getUpdates" - As reações do Telegram chegam como atualizações `message_reaction` (separadas dos payloads de mensagem). + As reações do Telegram chegam como atualizações `message_reaction` (separadas dos conteúdos das mensagens). - Quando habilitado, o OpenClaw enfileira eventos do sistema como: + Quando habilitado, o OpenClaw enfileira eventos de sistema como: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -673,40 +710,40 @@ curl "https://api.telegram.org/bot/getUpdates" Observações: - - `own` significa reações do usuário apenas a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). + - `own` significa apenas reações de usuários a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). - Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados. - - O Telegram não fornece IDs de thread em atualizações de reação. - - grupos que não são fórum são roteados para a sessão de chat do grupo - - grupos de fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem + - O Telegram não fornece IDs de encadeamento em atualizações de reação. + - grupos que não são fóruns roteiam para a sessão do chat em grupo + - grupos de fórum roteiam para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem - `allowed_updates` para polling/webhook inclui `message_reaction` automaticamente. + `allowed_updates` para sondagem/Webhook inclui `message_reaction` automaticamente. - `ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. + `ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. Ordem de resolução: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") + - alternativa de emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀") Observações: - - O Telegram espera emoji unicode (por exemplo, "👀"). - - Use `""` para desabilitar a reação para um canal ou conta. + - O Telegram espera emoji Unicode (por exemplo, "👀"). + - Use `""` para desabilitar a reação para um canal ou uma conta. - + Gravações de configuração de canal são habilitadas por padrão (`configWrites !== false`). - Gravações acionadas pelo Telegram incluem: + Gravações disparadas pelo Telegram incluem: - eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups` - - `/config set` e `/config unset` (requer habilitação de comandos) + - `/config set` e `/config unset` (requer habilitação de comando) Desabilitar: @@ -722,39 +759,39 @@ curl "https://api.telegram.org/bot/getUpdates" - - O padrão é long polling. Para o modo webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionalmente `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`). + + O padrão é sondagem longa. Para o modo Webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionais: `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`). - O listener local se vincula a `127.0.0.1:8787`. Para ingresso público, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente. + O ouvinte local se vincula a `127.0.0.1:8787`. Para entrada pública, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente. - O modo webhook valida proteções de requisição, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram. - Em seguida, o OpenClaw processa a atualização de forma assíncrona pelas mesmas lanes de bot por chat/por tópico usadas pelo long polling, então turnos lentos do agente não seguram o ACK de entrega do Telegram. + O modo Webhook valida proteções de requisição, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram. + O OpenClaw então processa a atualização de forma assíncrona pelas mesmas filas do bot por chat/por tópico usadas pela sondagem longa, então turnos lentos do agente não seguram a confirmação de entrega do Telegram. - - - `channels.telegram.textChunkLimit` padrão é 4000. + + - O padrão de `channels.telegram.textChunkLimit` é 4000. - `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho. - - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia do Telegram recebida e enviada. - - `channels.telegram.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são armazenados em buffer antes de o OpenClaw despachá-los como uma única mensagem recebida. Aumente se as partes do álbum chegarem atrasadas; diminua para reduzir a latência de resposta do álbum. - - `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). Clientes de bot limitam valores configurados abaixo da proteção de 60 segundos para requisições de texto/typing de saída, para que o grammY não aborte a entrega de resposta visível antes que a proteção de transporte e o fallback do OpenClaw possam executar. Long polling ainda usa uma proteção de requisição `getUpdates` de 45 segundos para que polls ociosos não sejam abandonados indefinidamente. - - `channels.telegram.pollingStallThresholdMs` usa `120000` por padrão; ajuste entre `30000` e `600000` apenas para reinicializações de polling-stall falso-positivas. - - o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita. - - contexto suplementar de resposta/citação/encaminhamento atualmente é passado como recebido. - - allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar. - - Controles de histórico de DM: + - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada pelo Telegram. + - `channels.telegram.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são mantidos em buffer antes que o OpenClaw os despache como uma única mensagem recebida. Aumente esse valor se partes do álbum chegarem tarde; reduza-o para diminuir a latência de resposta do álbum. + - `channels.telegram.timeoutSeconds` substitui o tempo limite do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). Clientes de bot limitam valores configurados abaixo da proteção de requisição de texto/digitação de saída de 60 segundos para que o grammY não aborte a entrega da resposta visível antes que a proteção de transporte e a alternativa do OpenClaw possam executar. A sondagem longa ainda usa uma proteção de requisição `getUpdates` de 45 segundos para que sondagens ociosas não sejam abandonadas indefinidamente. + - O padrão de `channels.telegram.pollingStallThresholdMs` é `120000`; ajuste entre `30000` e `600000` apenas para reinícios de sondagem travada por falso positivo. + - O histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita. + - Contexto suplementar de resposta/citação/encaminhamento é atualmente passado como recebido. + - Listas de permissão do Telegram controlam principalmente quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar. + - Controles de histórico de mensagens diretas: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - A configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final de entrada também usa uma repetição safe-send limitada para falhas de pré-conexão do Telegram, mas não repete envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis. + - A configuração `channels.telegram.retry` se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final a mensagens recebidas também usa uma nova tentativa limitada de envio seguro para falhas pré-conexão do Telegram, mas não repete envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis. - O alvo de envio da CLI pode ser ID numérico de chat ou nome de usuário: + O destino de envio da CLI pode ser um ID numérico de chat ou um nome de usuário: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Polls do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum: + Enquetes do Telegram usam `openclaw message poll` e aceitam tópicos de fórum: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -764,57 +801,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Flags de poll exclusivas do Telegram: + Opções de enquete exclusivas do Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`) + - `--thread-id` para tópicos de fórum (ou use um destino `:topic:`) - Envio pelo Telegram também oferece suporte a: + O envio pelo Telegram também aceita: - - `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite + - `--presentation` com blocos `buttons` para teclados em linha quando `channels.telegram.capabilities.inlineButtons` permite - `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot puder fixar nesse chat - - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads de foto comprimida ou mídia animada + - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads de foto compactada ou mídia animada Controle de ações: - - `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo polls - - `channels.telegram.actions.poll=false` desabilita a criação de polls do Telegram enquanto mantém envios regulares habilitados + - `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo enquetes + - `channels.telegram.actions.poll=false` desabilita a criação de enquetes do Telegram enquanto mantém envios regulares habilitados - - O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram. + + O Telegram oferece suporte a aprovações de execução em mensagens diretas de aprovadores e pode, opcionalmente, publicar solicitações no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram. Caminho de configuração: - `channels.telegram.execApprovals.enabled` (habilita automaticamente quando pelo menos um aprovador é resolvível) - - `channels.telegram.execApprovals.approvers` (faz fallback para IDs numéricos de proprietários de `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.approvers` (recorre aos IDs numéricos dos proprietários em `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (padrão) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de exec. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração de um único proprietário continua funcionando sem duplicar IDs em `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de execução. O primeiro pareamento de mensagem direta aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração com um único proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`. - A entrega no canal mostra o texto do comando no chat; habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega a um tópico de fórum, o OpenClaw preserva o tópico para o prompt de aprovação e o acompanhamento. Aprovações de exec expiram após 30 minutos por padrão. + A entrega no canal mostra o texto do comando no chat; habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando a solicitação chega em um tópico de fórum, o OpenClaw preserva o tópico para a solicitação de aprovação e o acompanhamento. Aprovações de execução expiram após 30 minutos por padrão. - Botões de aprovação inline também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície alvo (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de Plugin; os demais são resolvidos primeiro por aprovações de exec. + Botões de aprovação em linha também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de Plugin; os demais são resolvidos primeiro por aprovações de execução. - Consulte [aprovações de exec](/pt-BR/tools/exec-approvals). + Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals). ## Controles de resposta de erro -Quando o agente encontra um erro de entrega ou provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: +Quando o agente encontra um erro de entrega ou de provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: -| Chave | Valores | Padrão | Descrição | -| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável ao chat. `silent` suprime respostas de erro totalmente. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erro durante indisponibilidades. | +| Chave | Valores | Padrão | Descrição | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável ao chat. `silent` suprime totalmente respostas de erro. | +| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. | -Substituições por conta, por grupo e por tópico são aceitas (mesma herança que outras chaves de configuração do Telegram). +Sobrescritas por conta, grupo e tópico são aceitas (mesma herança de outras chaves de configuração do Telegram). ```json5 { @@ -839,52 +876,52 @@ Substituições por conta, por grupo e por tópico são aceitas (mesma herança - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total. - BotFather: `/setprivacy` -> Desabilitar - - depois remova e adicione novamente o bot ao grupo + - em seguida, remova + adicione o bot novamente ao grupo - `openclaw channels status` avisa quando a configuração espera mensagens de grupo sem menção. - - `openclaw channels status --probe` pode verificar IDs numéricos de grupo explícitos; o curinga `"*"` não pode ter associação verificada por probe. + - `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter a associação verificada. - teste rápido de sessão: `/activation always`. - + - quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`) - - verifique a associação do bot no grupo - - revise logs: `openclaw logs --follow` para motivos de salto + - verifique a associação do bot ao grupo + - revise os logs: `openclaw logs --follow` para motivos de ignorar - + - autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico) - - a autorização de comando ainda se aplica mesmo quando a política de grupo é `open` - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desabilite menus nativos - - chamadas de inicialização `deleteMyCommands` / `setMyCommands` e chamadas de typing `sendChatAction` são limitadas e repetem uma vez pelo fallback de transporte do Telegram em caso de timeout de requisição. Erros persistentes de rede/fetch geralmente indicam problemas de alcançabilidade DNS/HTTPS para `api.telegram.org` + - a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open` + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desative menus nativos + - as chamadas de inicialização `deleteMyCommands` / `setMyCommands` e as chamadas de digitação `sendChatAction` são limitadas e tentam novamente uma vez por meio do fallback de transporte do Telegram em caso de timeout da solicitação. Erros persistentes de rede/fetch geralmente indicam problemas de acessibilidade DNS/HTTPS para `api.telegram.org` - + - `getMe returned 401` é uma falha de autenticação do Telegram para o token de bot configurado. - - Copie novamente ou regenere o token do bot no BotFather e atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão. - - `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-lo como "nenhum Webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores. + - Copie novamente ou regenere o token de bot no BotFather e, em seguida, atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão. + - `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-la como "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores. - - Node 22+ + fetch/proxy personalizado pode acionar comportamento de aborto imediato se os tipos de AbortSignal não corresponderem. - - Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; egresso IPv6 com problemas pode causar falhas intermitentes da API do Telegram. - - Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis. + - Node 22+ + fetch/proxy personalizado pode acionar comportamento de abort imediato se os tipos de AbortSignal forem incompatíveis. + - Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 quebrada pode causar falhas intermitentes da API do Telegram. + - Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses erros como erros de rede recuperáveis. - Durante a inicialização do polling, o OpenClaw reutiliza a sondagem `getMe` bem-sucedida da inicialização para o grammY, para que o executor não precise de um segundo `getMe` antes do primeiro `getUpdates`. - Se `deleteWebhook` falhar com um erro de rede transitório durante a inicialização do polling, o OpenClaw continua para long polling em vez de fazer outra chamada de plano de controle antes do polling. Um Webhook ainda ativo aparece como um conflito de `getUpdates`; então o OpenClaw reconstrói o transporte do Telegram e tenta novamente a limpeza do Webhook. - - Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se `channels.telegram.timeoutSeconds` está baixo; os clientes de bot limitam valores configurados abaixo das proteções de solicitação de saída e `getUpdates`, mas versões mais antigas podiam abortar cada polling ou resposta quando isso era definido abaixo dessas proteções. - - Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness de long-poll concluído por padrão. - - `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após o período de tolerância da inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após o período de tolerância da inicialização ou quando a última atividade bem-sucedida do transporte de polling está obsoleta. - - Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinicializações falsas por travamento de polling. Travamentos persistentes geralmente indicam problemas de proxy, DNS, IPv6 ou egresso TLS entre o host e `api.telegram.org`. - - O Telegram também respeita variáveis de ambiente de proxy do processo para o transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda podem ignorar `api.telegram.org`. - - Se o proxy gerenciado do OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhuma variável de ambiente de proxy padrão estiver presente, o Telegram também usa essa URL para o transporte da Bot API. - - Em hosts VPS com egresso direto/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`: + - Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se `channels.telegram.timeoutSeconds` está baixo; clientes de bot limitam valores configurados abaixo dos limites de solicitações de saída e `getUpdates`, mas versões mais antigas podiam abortar cada polling ou resposta quando isso era definido abaixo desses limites. + - Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness concluída de long polling por padrão. + - `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após a tolerância de inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após a tolerância de inicialização, ou quando a última atividade de transporte de polling bem-sucedida está obsoleta. + - Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinicializações falsas por polling travado. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`. + - O Telegram também respeita env de proxy do processo para transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda pode contornar `api.telegram.org`. + - Se o proxy gerenciado do OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usa essa URL para o transporte da Bot API. + - Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por meio de `channels.telegram.proxy`: ```yaml channels: @@ -892,8 +929,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ usa `autoSelectFamily=true` por padrão (exceto WSL2). A ordem de resultados DNS do Telegram respeita `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, depois `channels.telegram.network.dnsResultOrder`, depois o padrão do processo, como `NODE_OPTIONS=--dns-result-order=ipv4first`; se nada se aplicar, Node 22+ volta para `ipv4first`. - - Se o seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família: + - Node 22+ usa `autoSelectFamily=true` por padrão (exceto WSL2). A ordem dos resultados DNS do Telegram respeita `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, depois `channels.telegram.network.dnsResultOrder`, depois o padrão do processo, como `NODE_OPTIONS=--dns-result-order=ipv4first`; se nada se aplicar, Node 22+ volta para `ipv4first`. + - Se seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família: ```yaml channels: @@ -903,8 +940,8 @@ channels: ``` - Respostas de intervalo de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas - por padrão para downloads de mídia do Telegram. Se um proxy fake-IP ou - transparente confiável reescrever `api.telegram.org` para algum outro + para downloads de mídia do Telegram por padrão. Se um fake-IP confiável ou + proxy transparente reescrever `api.telegram.org` para algum outro endereço privado/interno/de uso especial durante downloads de mídia, você pode optar pelo bypass exclusivo do Telegram: @@ -917,19 +954,19 @@ channels: - A mesma opção está disponível por conta em `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Se o seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a + - Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a flag perigosa desativada primeiro. A mídia do Telegram já permite o intervalo de benchmark RFC 2544 por padrão. `channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as proteções - SSRF de mídia do Telegram. Use isso somente em ambientes de proxy confiáveis - controlados pelo operador, como roteamento fake-IP de Clash, Mihomo ou Surge, quando eles - sintetizam respostas privadas ou de uso especial fora do intervalo de benchmark - RFC 2544. Deixe desativado para acesso normal ao Telegram pela internet pública. + SSRF de mídia do Telegram. Use-a somente em ambientes de proxy confiáveis + controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge quando eles + sintetizarem respostas privadas ou de uso especial fora do intervalo de benchmark + RFC 2544. Deixe-a desativada para acesso normal do Telegram pela internet pública. - - Sobrescritas de ambiente (temporárias): + - Substituições de ambiente (temporárias): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -953,9 +990,9 @@ Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway - inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados) - controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`) -- aprovações de execução: `execApprovals`, `accounts.*.execApprovals` +- aprovações de exec: `execApprovals`, `accounts.*.execApprovals` - comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands` -- encadeamento/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` +- threads/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming` - formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - mídia/rede: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` @@ -969,7 +1006,7 @@ Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway -Precedência de várias contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw volta para o primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`. +Precedência de várias contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`. ## Relacionados @@ -981,11 +1018,11 @@ Precedência de várias contas: quando dois ou mais IDs de conta estiverem confi Comportamento de lista de permissões de grupos e tópicos. - + Roteie mensagens recebidas para agentes. - Modelo de ameaças e hardening. + Modelo de ameaças e fortalecimento. Mapeie grupos e tópicos para agentes. diff --git a/docs/pt-BR/cli/sessions.md b/docs/pt-BR/cli/sessions.md index 2f7cb7ba6..0b97985f6 100644 --- a/docs/pt-BR/cli/sessions.md +++ b/docs/pt-BR/cli/sessions.md @@ -1,13 +1,13 @@ --- read_when: - - Você quer listar sessões armazenadas e ver a atividade recente + - Você quer listar as 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-02T20:44:05Z" + generated_at: "2026-05-04T07:02:44Z" model: gpt-5.5 provider: openai - source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f + source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e source_path: cli/sessions.md workflow: 16 --- @@ -18,6 +18,8 @@ Liste 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. +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. + ```bash openclaw sessions openclaw sessions --agent work @@ -30,10 +32,10 @@ openclaw sessions --json Seleção de escopo: - padrão: armazenamento do agente padrão configurado -- `--verbose`: registro detalhado +- `--verbose`: registro em log detalhado - `--agent `: um armazenamento de agente configurado - `--all-agents`: agrega todos os armazenamentos de agentes configurados -- `--store `: caminho de armazenamento explícito (não pode ser combinado com `--agent` ou `--all-agents`) +- `--store `: caminho explícito do armazenamento (não pode ser combinado com `--agent` ou `--all-agents`) Exporte um pacote de trajetória para uma sessão armazenada: @@ -42,9 +44,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 execução. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no espaço de trabalho selecionado. +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. -`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` baseada em modelo. 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. +`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. Exemplos JSON: @@ -69,7 +71,7 @@ Exemplos JSON: ## Manutenção de limpeza -Execute a manutenção agora (em vez de aguardar o próximo ciclo de gravação): +Execute a manutenção agora (em vez de esperar pelo próximo ciclo de gravação): ```bash openclaw sessions cleanup --dry-run @@ -80,21 +82,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` usa as configurações de `session.maintenance` da configuração: +`openclaw sessions cleanup` usa as configurações `session.maintenance` da configuração: -- Observação de escopo: `openclaw sessions cleanup` mantém armazenamentos de sessões, transcrições e arquivos auxiliares de trajetória. Ele não limpa 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` 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). -- `--dry-run`: pré-visualiza quantas entradas seriam removidas/limitadas sem gravar. +- `--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 a manutenção mesmo quando `session.maintenance.mode` é `warn`. -- `--fix-missing`: remove entradas cujos arquivos de transcrição estão ausentes, mesmo que normalmente elas ainda não fossem removidas por idade/contagem. -- `--active-key `: protege uma chave ativa específica contra remoção por orçamento de disco. Ponteiros duráveis para conversas externas, como sessões em 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. +- `--enforce`: aplica 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. - `--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 do tráfego em tempo de execução. Use `--store ` para o 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 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. `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/pt-BR/concepts/messages.md b/docs/pt-BR/concepts/messages.md index ede5961b9..2fb751de6 100644 --- a/docs/pt-BR/concepts/messages.md +++ b/docs/pt-BR/concepts/messages.md @@ -6,15 +6,15 @@ read_when: summary: Fluxo de mensagens, sessões, enfileiramento e visibilidade do raciocínio title: Mensagens x-i18n: - generated_at: "2026-04-30T16:27:50Z" + generated_at: "2026-05-04T07:03:01Z" model: gpt-5.5 provider: openai - source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 + source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f source_path: concepts/messages.md workflow: 16 --- -OpenClaw lida com mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade de raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta. +OpenClaw lida com mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade do raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta. ## Fluxo de mensagens (alto nível) @@ -29,24 +29,24 @@ Inbound message Os principais controles ficam na configuração: - `messages.*` para prefixos, enfileiramento e comportamento de grupos. -- `agents.defaults.*` para padrões de streaming em blocos e fragmentação. -- Sobrescritas de canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming. +- `agents.defaults.*` para padrões de streaming em blocos e divisão em partes. +- Substituições por canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming. -Consulte [Configuração](/pt-BR/gateway/configuration) para ver o esquema completo. +Consulte [Configuração](/pt-BR/gateway/configuration) para o esquema completo. -## Deduplicação de recebimento +## Desduplicação de recebimento -Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um -cache de curta duração indexado por canal/conta/par/sessão/id da mensagem para que entregas -duplicadas não acionem outra execução do agente. +Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um cache +de curta duração indexado por canal/conta/par/sessão/ID da mensagem para que entregas +duplicadas não disparem outra execução do agente. ## Debounce de recebimento Mensagens consecutivas rápidas do **mesmo remetente** podem ser agrupadas em um único -turno do agente por meio de `messages.inbound`. O debounce tem escopo por canal + conversa -e usa a mensagem mais recente para encadeamento/IDs de resposta. +turno do agente via `messages.inbound`. O debounce é limitado por canal + conversa +e usa a mensagem mais recente para encadeamento/IDs da resposta. -Configuração (padrão global + sobrescritas por canal): +Configuração (padrão global + substituições por canal): ```json5 { @@ -65,69 +65,69 @@ Configuração (padrão global + sobrescritas por canal): Observações: -- O debounce se aplica a mensagens **somente de texto**; mídia/anexos são liberados imediatamente. -- Comandos de controle ignoram o debounce para permanecerem autônomos — **exceto** quando um canal opta explicitamente por coalescência de DM do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga útil enviada em partes possa entrar no mesmo turno do agente. +- O debounce se aplica a mensagens **somente de texto**; mídia/anexos são descarregados imediatamente. +- Comandos de controle ignoram o debounce para permanecerem independentes — **exceto** quando um canal opta explicitamente pela coalescência de DMs do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga enviada em partes possa entrar no mesmo turno do agente. ## Sessões e dispositivos -As sessões pertencem ao gateway, não aos clientes. +As sessões pertencem ao Gateway, não aos clientes. -- Conversas diretas são consolidadas na chave de sessão principal do agente. +- Conversas diretas convergem para a chave da sessão principal do agente. - Grupos/canais recebem suas próprias chaves de sessão. - O armazenamento de sessões e as transcrições ficam no host do Gateway. Vários dispositivos/canais podem mapear para a mesma sessão, mas o histórico não é totalmente sincronizado de volta para todos os clientes. Recomendação: use um dispositivo principal para conversas -longas a fim de evitar contexto divergente. A Control UI e a TUI sempre mostram a -transcrição da sessão respaldada pelo Gateway, portanto são a fonte da verdade. +longas a fim de evitar contexto divergente. A Interface de Controle e a TUI sempre mostram a +transcrição da sessão mantida pelo Gateway, portanto elas são a fonte da verdade. Detalhes: [Gerenciamento de sessões](/pt-BR/concepts/session). ## Metadados de resultado de ferramenta -`content` do resultado da ferramenta é o resultado visível para o modelo. `details` do resultado da ferramenta é -metadado de runtime para renderização de UI, diagnósticos, entrega de mídia e plugins. +O `content` do resultado da ferramenta é o resultado visível para o modelo. O `details` do resultado da ferramenta são +metadados de runtime para renderização de UI, diagnósticos, entrega de mídia e plugins. O OpenClaw mantém esse limite explícito: -- `toolResult.details` é removido antes de repetição pelo provedor e entrada de Compaction. -- Transcrições de sessão persistidas mantêm apenas `details` limitados; metadados grandes demais - são substituídos por um resumo compacto marcado como `persistedDetailsTruncated: true`. -- Plugins e ferramentas devem colocar o texto que o modelo precisa ler em `content`, não apenas +- `toolResult.details` é removido antes do replay do provedor e da entrada de Compaction. +- Transcrições de sessão persistidas mantêm apenas `details` limitados; metadados + grandes demais são substituídos por um resumo compacto marcado como `persistedDetailsTruncated: true`. +- Plugins e ferramentas devem colocar texto que o modelo precisa ler em `content`, não apenas em `details`. ## Corpos recebidos e contexto de histórico O OpenClaw separa o **corpo do prompt** do **corpo do comando**: -- `BodyForAgent`: texto primário voltado ao modelo para a mensagem atual. Plugins de canal - devem mantê-lo focado no texto atual do remetente que contém o prompt. -- `Body`: fallback legado de prompt. Ele pode incluir envelopes do canal e - wrappers opcionais de histórico, mas canais atuais não devem depender dele como - entrada primária do modelo quando `BodyForAgent` estiver disponível. +- `BodyForAgent`: texto principal voltado ao modelo para a mensagem atual. Plugins de canal + devem manter isto focado no texto atual do remetente que contém o prompt. +- `Body`: fallback de prompt legado. Isto pode incluir envelopes de canal e + wrappers opcionais de histórico, mas canais atuais não devem depender dele como a + entrada principal do modelo quando `BodyForAgent` estiver disponível. - `CommandBody`: texto bruto do usuário para análise de diretivas/comandos. -- `RawBody`: alias legado de `CommandBody` (mantido por compatibilidade). +- `RawBody`: alias legado para `CommandBody` (mantido para compatibilidade). Quando um canal fornece histórico, ele usa um wrapper compartilhado: -- `[Chat messages since your last reply - for context]` -- `[Current message - respond to this]` +- `[Mensagens de chat desde sua última resposta - para contexto]` +- `[Mensagem atual - responda a isto]` -Para **conversas não diretas** (grupos/canais/salas), o **corpo da mensagem atual** recebe como prefixo o -rótulo do remetente (o mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e mensagens enfileiradas/de histórico +Para **chats não diretos** (grupos/canais/salas), o **corpo da mensagem atual** recebe como prefixo o +rótulo do remetente (mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e enfileiradas/de histórico consistentes no prompt do agente. -Buffers de histórico são **somente pendentes**: incluem mensagens de grupo que _não_ -acionaram uma execução (por exemplo, mensagens controladas por menção) e **excluem** mensagens +Buffers de histórico são **somente pendentes**: eles incluem mensagens de grupo que _não_ +dispararam uma execução (por exemplo, mensagens filtradas por menção) e **excluem** mensagens já presentes na transcrição da sessão. A remoção de diretivas se aplica apenas à seção da **mensagem atual**, para que o histórico permaneça intacto. Canais que encapsulam histórico devem definir `CommandBody` (ou `RawBody`) como o texto original da mensagem e manter `Body` como o prompt combinado. Histórico estruturado, resposta, encaminhamento e metadados de canal são renderizados como -blocos de contexto não confiável no papel de usuário durante a montagem do prompt. +blocos de contexto não confiável com papel de usuário durante a montagem do prompt. Buffers de histórico são configuráveis via `messages.groupChat.historyLimit` (padrão -global) e sobrescritas por canal como `channels.slack.historyLimit` ou +global) e substituições por canal, como `channels.slack.historyLimit` ou `channels.telegram.accounts..historyLimit` (defina `0` para desativar). ## Enfileiramento e acompanhamentos @@ -138,82 +138,82 @@ execução atual ou coletadas para um turno de acompanhamento. - Configure via `messages.queue` (e `messages.queue.byChannel`). - O modo padrão é `steer`, com um debounce de acompanhamento de 500 ms quando o direcionamento recai para entrega de acompanhamento enfileirada. -- Modos: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` e o - modo legado um-por-vez `queue`. +- Modos: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` e o modo legado + `queue`, de um por vez. Detalhes: [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering). -## Propriedade da execução do canal +## Propriedade de execução do canal -Plugins de canal podem preservar a ordenação, aplicar debounce à entrada e aplicar contrapressão -de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um +Plugins de canal podem preservar ordenação, aplicar debounce à entrada e aplicar +backpressure de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um timeout separado em torno do próprio turno do agente. Depois que uma mensagem é roteada para uma -sessão, trabalhos de longa duração são regidos pelo ciclo de vida da sessão, da ferramenta e do runtime, -para que todos os canais relatem e se recuperem de turnos lentos de forma consistente. +sessão, trabalhos de longa duração são governados pelo ciclo de vida da sessão, da ferramenta e do +runtime para que todos os canais relatem e se recuperem de turnos lentos de forma consistente. -## Streaming, fragmentação e agrupamento +## Streaming, divisão em partes e agrupamento -Streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto. -A fragmentação respeita os limites de texto do canal e evita dividir blocos de código cercados. +O streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto. +A divisão em partes respeita limites de texto do canal e evita dividir código cercado. Configurações principais: -- `agents.defaults.blockStreamingDefault` (`on|off`, padrão desativado) +- `agents.defaults.blockStreamingDefault` (`on|off`, desativado por padrão) - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) - `agents.defaults.blockStreamingCoalesce` (agrupamento baseado em ociosidade) -- `agents.defaults.humanDelay` (pausa semelhante à humana entre respostas em blocos) -- Sobrescritas de canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais que não sejam Telegram exigem `*.blockStreaming: true` explícito) +- `agents.defaults.humanDelay` (pausa semelhante à humana entre respostas em bloco) +- Substituições por canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais não Telegram exigem `*.blockStreaming: true` explícito) -Detalhes: [Streaming + fragmentação](/pt-BR/concepts/streaming). +Detalhes: [Streaming + divisão em partes](/pt-BR/concepts/streaming). -## Visibilidade de raciocínio e tokens +## Visibilidade do raciocínio e tokens O OpenClaw pode expor ou ocultar o raciocínio do modelo: - `/reasoning on|off|stream` controla a visibilidade. - O conteúdo de raciocínio ainda conta para o uso de tokens quando produzido pelo modelo. -- O Telegram oferece suporte a streaming de raciocínio no balão de rascunho. +- O Telegram oferece suporte a streaming de raciocínio em um balão de rascunho transitório que é excluído após a entrega final; use `/reasoning on` para saída de raciocínio persistente. Detalhes: [Diretivas de pensamento + raciocínio](/pt-BR/tools/thinking) e [Uso de tokens](/pt-BR/reference/token-use). ## Prefixos, encadeamento e respostas -A formatação de mensagens de saída é centralizada em `messages`: +A formatação de mensagens enviadas é centralizada em `messages`: -- `messages.responsePrefix`, `channels..responsePrefix` e `channels..accounts..responsePrefix` (cascata de prefixo de saída), além de `channels.whatsapp.messagePrefix` (prefixo de entrada do WhatsApp) +- `messages.responsePrefix`, `channels..responsePrefix` e `channels..accounts..responsePrefix` (cascata de prefixo de saída), mais `channels.whatsapp.messagePrefix` (prefixo de entrada do WhatsApp) - Encadeamento de respostas via `replyToMode` e padrões por canal Detalhes: [Configuração](/pt-BR/gateway/config-agents#messages) e documentação dos canais. ## Respostas silenciosas -O token silencioso exato `NO_REPLY` / `no_reply` significa “não entregar uma resposta visível ao usuário”. +O token silencioso exato `NO_REPLY` / `no_reply` significa “não entregue uma resposta visível ao usuário”. Quando um turno também tem mídia de ferramenta pendente, como áudio TTS gerado, o OpenClaw remove o texto silencioso, mas ainda entrega o anexo de mídia. O OpenClaw resolve esse comportamento por tipo de conversa: - Conversas diretas não permitem silêncio por padrão e reescrevem uma resposta - silenciosa pura para um fallback curto e visível. + silenciosa isolada para um fallback curto visível. - Grupos/canais permitem silêncio por padrão. - Orquestração interna permite silêncio por padrão. O OpenClaw também usa respostas silenciosas para falhas internas do executor que acontecem -antes de qualquer resposta do assistente em conversas não diretas, para que grupos/canais não vejam -texto boilerplate de erro do gateway. Conversas diretas mostram texto compacto de falha por padrão; -detalhes brutos do executor são mostrados somente quando `/verbose` está `on` ou `full`. +antes de qualquer resposta do assistente em chats não diretos, para que grupos/canais não vejam +texto padrão de erro do Gateway. Conversas diretas mostram uma cópia compacta da falha por padrão; +detalhes brutos do executor são mostrados apenas quando `/verbose` está `on` ou `full`. Os padrões ficam em `agents.defaults.silentReply` e `agents.defaults.silentReplyRewrite`; `surfaces..silentReply` e -`surfaces..silentReplyRewrite` podem sobrescrevê-los por superfície. +`surfaces..silentReplyRewrite` podem substituí-los por superfície. -Quando a sessão pai tem uma ou mais execuções de subagente geradas pendentes, respostas -silenciosas puras são descartadas em todas as superfícies em vez de serem reescritas, para que o +Quando a sessão pai tem uma ou mais execuções pendentes de subagentes gerados, respostas +silenciosas isoladas são descartadas em todas as superfícies em vez de serem reescritas, para que o pai permaneça quieto até que o evento de conclusão do filho entregue a resposta real. ## Relacionados - [Streaming](/pt-BR/concepts/streaming) — entrega de mensagens em tempo real -- [Tentativa novamente](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens +- [Nova tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens - [Fila](/pt-BR/concepts/queue) — fila de processamento de mensagens - [Canais](/pt-BR/channels) — integrações com plataformas de mensagens diff --git a/docs/pt-BR/concepts/streaming.md b/docs/pt-BR/concepts/streaming.md index 73e9bd35d..29c53a7c4 100644 --- a/docs/pt-BR/concepts/streaming.md +++ b/docs/pt-BR/concepts/streaming.md @@ -1,15 +1,15 @@ --- read_when: - - Explicando como a transmissão contínua ou a divisão em partes funciona nos canais - - Alterando o comportamento de streaming de blocos ou fragmentação de canal - - Depuração de respostas de bloco duplicadas/antecipadas ou do streaming de pré-visualização do canal -summary: Comportamento de transmissão contínua + fragmentação (respostas em bloco, transmissão contínua de pré-visualização do canal, mapeamento de modos) -title: Transmissão contínua e fragmentação + - Explicando como a transmissão contínua ou a divisão em partes funcionam nos canais + - Alterando o comportamento de streaming de blocos ou de fragmentação de canais + - Depuração de respostas de bloco duplicadas/antecipadas ou do streaming de prévia do canal +summary: Comportamento de transmissão + fragmentação (respostas em bloco, transmissão da prévia do canal, mapeamento de modos) +title: Transmissão em fluxo e fragmentação x-i18n: - generated_at: "2026-05-03T21:30:57Z" + generated_at: "2026-05-04T07:03:07Z" model: gpt-5.5 provider: openai - source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50 + source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1 source_path: concepts/streaming.md workflow: 16 --- @@ -17,13 +17,13 @@ x-i18n: OpenClaw tem duas camadas de streaming separadas: - **Streaming de blocos (canais):** emite **blocos** concluídos enquanto o assistente escreve. Essas são mensagens normais de canal (não deltas de tokens). -- **Streaming de pré-visualização (Telegram/Discord/Slack):** atualiza uma **mensagem de pré-visualização** temporária durante a geração. +- **Streaming de prévia (Telegram/Discord/Slack):** atualiza uma **mensagem de prévia** temporária durante a geração. -Atualmente, **não há streaming real de deltas de tokens** para mensagens de canal. O streaming de pré-visualização é baseado em mensagens (envio + edições/anexos). +Atualmente, **não há streaming real de delta de tokens** para mensagens de canal. O streaming de prévia é baseado em mensagens (envio + edições/acréscimos). ## Streaming de blocos (mensagens de canal) -O streaming de blocos envia a saída do assistente em partes maiores conforme ela fica disponível. +O streaming de blocos envia a saída do assistente em partes maiores à medida que ela fica disponível. ``` Model output @@ -38,173 +38,162 @@ Model output Legenda: - `text_delta/events`: eventos de stream do modelo (podem ser esparsos para modelos sem streaming). -- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimo/máximo + preferência de quebra. -- `channel send`: mensagens de saída reais (respostas em blocos). +- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimos/máximos + preferência de quebra. +- `channel send`: mensagens de saída reais (respostas em bloco). **Controles:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (desativado por padrão). -- Substituições de canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal. +- Sobrescritas de canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal. - `agents.defaults.blockStreamingBreak`: `"text_end"` ou `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. - `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (mescla blocos transmitidos antes do envio). - Limite rígido do canal: `*.textChunkLimit` (por exemplo, `channels.whatsapp.textChunkLimit`). -- Modo de divisão do canal: `*.chunkMode` (`length` padrão, `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho). -- Limite flexível do Discord: `channels.discord.maxLinesPerMessage` (padrão 17) divide respostas altas para evitar cortes na UI. +- Modo de divisão do canal: `*.chunkMode` (`length` é o padrão, `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho). +- Limite flexível do Discord: `channels.discord.maxLinesPerMessage` (padrão 17) divide respostas altas para evitar corte na UI. -**Semântica de limites:** +**Semântica de limite:** -- `text_end`: transmite blocos assim que o chunker emite; descarrega a cada `text_end`. -- `message_end`: espera a mensagem do assistente terminar e então descarrega a saída em buffer. +- `text_end`: transmite blocos assim que o divisor emite; descarrega em cada `text_end`. +- `message_end`: aguarda até que a mensagem do assistente termine e então descarrega a saída em buffer. -`message_end` ainda usa o chunker se o texto em buffer exceder `maxChars`, portanto pode emitir vários blocos no final. +`message_end` ainda usa o divisor se o texto em buffer exceder `maxChars`, então ele pode emitir várias partes ao final. ### Entrega de mídia com streaming de blocos -Diretivas `MEDIA:` são metadados normais de entrega. Quando o streaming de blocos envia um bloco de mídia antecipadamente, o OpenClaw se lembra dessa entrega no turno. Se a carga final do assistente repetir a mesma URL de mídia, a entrega final remove a mídia duplicada em vez de enviar o anexo novamente. +Diretivas `MEDIA:` são metadados normais de entrega. Quando o streaming de blocos envia um bloco de mídia antecipadamente, o OpenClaw lembra dessa entrega para o turno. Se a carga final do assistente repetir a mesma URL de mídia, a entrega final remove a mídia duplicada em vez de enviar o anexo novamente. -Cargas finais exatamente duplicadas são suprimidas. Se a carga final adicionar texto distinto ao redor de mídia que já foi transmitida, o OpenClaw ainda envia o novo texto mantendo a mídia com entrega única. Isso evita notas de voz ou arquivos duplicados em canais como Telegram quando um agente emite `MEDIA:` durante o streaming e o provedor também a inclui na resposta concluída. +Cargas finais exatamente duplicadas são suprimidas. Se a carga final adicionar texto distinto ao redor de mídia que já foi transmitida, o OpenClaw ainda envia o novo texto mantendo a mídia com entrega única. Isso evita notas de voz ou arquivos duplicados em canais como Telegram quando um agente emite `MEDIA:` durante o streaming e o provedor também o inclui na resposta concluída. ## Algoritmo de divisão (limites baixo/alto) -A divisão de blocos é implementada por `EmbeddedBlockChunker`: +A divisão em blocos é implementada por `EmbeddedBlockChunker`: -- **Limite baixo:** não emite até o buffer >= `minChars` (a menos que seja forçado). +- **Limite baixo:** não emite até que o buffer >= `minChars` (a menos que seja forçado). - **Limite alto:** prefere divisões antes de `maxChars`; se forçado, divide em `maxChars`. - **Preferência de quebra:** `paragraph` → `newline` → `sentence` → `whitespace` → quebra rígida. -- **Cercas de código:** nunca divide dentro de cercas; quando forçado em `maxChars`, fecha + reabre a cerca para manter o Markdown válido. +- **Blocos de código:** nunca divide dentro de blocos; quando forçado em `maxChars`, fecha + reabre o bloco para manter o Markdown válido. -`maxChars` é limitado ao `textChunkLimit` do canal, então você não pode exceder os limites por canal. +`maxChars` é limitado ao `textChunkLimit` do canal, então você não consegue exceder os limites por canal. ## Coalescência (mesclar blocos transmitidos) -Quando o streaming de blocos está ativado, o OpenClaw pode **mesclar blocos consecutivos** -antes de enviá-los. Isso reduz “spam de linha única” enquanto ainda fornece -saída progressiva. +Quando o streaming de blocos está ativado, o OpenClaw pode **mesclar partes de blocos consecutivas** antes de enviá-las. Isso reduz “spam de uma linha” enquanto ainda fornece saída progressiva. -- A coalescência espera **intervalos ociosos** (`idleMs`) antes de descarregar. -- Buffers são limitados por `maxChars` e serão descarregados se excederem esse valor. -- `minChars` impede que fragmentos minúsculos sejam enviados até que texto suficiente se acumule - (a descarga final sempre envia o texto restante). -- O juntador é derivado de `blockStreamingChunk.breakPreference` - (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espaço). -- Substituições de canal estão disponíveis via `*.blockStreamingCoalesce` (incluindo configurações por conta). -- O `minChars` padrão de coalescência é aumentado para 1500 para Signal/Slack/Discord, a menos que seja substituído. +- A coalescência aguarda **intervalos ociosos** (`idleMs`) antes de descarregar. +- Buffers são limitados por `maxChars` e serão descarregados se o excederem. +- `minChars` impede o envio de fragmentos pequenos até que texto suficiente se acumule (o descarregamento final sempre envia o texto restante). +- O conector é derivado de `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espaço). +- Sobrescritas de canal estão disponíveis via `*.blockStreamingCoalesce` (incluindo configurações por conta). +- O `minChars` padrão da coalescência é aumentado para 1500 para Signal/Slack/Discord, a menos que seja sobrescrito. ## Ritmo semelhante ao humano entre blocos -Quando o streaming de blocos está ativado, você pode adicionar uma **pausa aleatória** entre -respostas em blocos (após o primeiro bloco). Isso faz respostas com várias bolhas parecerem -mais naturais. +Quando o streaming de blocos está ativado, você pode adicionar uma **pausa aleatória** entre respostas em bloco (após o primeiro bloco). Isso faz respostas em múltiplos balões parecerem mais naturais. -- Configuração: `agents.defaults.humanDelay` (substitua por agente via `agents.list[].humanDelay`). +- Configuração: `agents.defaults.humanDelay` (sobrescreva por agente via `agents.list[].humanDelay`). - Modos: `off` (padrão), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`). -- Aplica-se apenas a **respostas em blocos**, não a respostas finais ou resumos de ferramentas. +- Aplica-se apenas a **respostas em bloco**, não a respostas finais ou resumos de ferramentas. ## "Transmitir partes ou tudo" Isso corresponde a: - **Transmitir partes:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emite conforme avança). Canais que não sejam Telegram também precisam de `*.blockStreaming: true`. -- **Transmitir tudo no final:** `blockStreamingBreak: "message_end"` (descarrega uma vez, possivelmente em vários blocos se for muito longo). +- **Transmitir tudo ao final:** `blockStreamingBreak: "message_end"` (descarrega uma vez, possivelmente em várias partes se for muito longo). - **Sem streaming de blocos:** `blockStreamingDefault: "off"` (apenas resposta final). -**Observação sobre canais:** O streaming de blocos fica **desativado a menos que** -`*.blockStreaming` seja definido explicitamente como `true`. Os canais podem transmitir uma pré-visualização ao vivo -(`channels..streaming`) sem respostas em blocos. +**Observação de canal:** O streaming de blocos fica **desativado a menos que** +`*.blockStreaming` esteja explicitamente definido como `true`. Canais podem transmitir uma prévia ao vivo +(`channels..streaming`) sem respostas em bloco. Lembrete de localização da configuração: os padrões `blockStreaming*` ficam em `agents.defaults`, não na configuração raiz. -## Modos de streaming de pré-visualização +## Modos de streaming de prévia Chave canônica: `channels..streaming` Modos: -- `off`: desativa o streaming de pré-visualização. -- `partial`: pré-visualização única que é substituída pelo texto mais recente. -- `block`: pré-visualização atualizada em etapas divididas/anexadas. -- `progress`: pré-visualização de progresso/status durante a geração, resposta final ao concluir. +- `off`: desativa o streaming de prévia. +- `partial`: prévia única que é substituída pelo texto mais recente. +- `block`: atualizações de prévia em etapas divididas/acrescentadas. +- `progress`: prévia de progresso/status durante a geração, resposta final ao concluir. -`streaming.mode: "block"` é um modo de streaming de pré-visualização para canais com suporte a edição -como Discord e Telegram. Ele não habilita a entrega de blocos de canal ali. -Use `streaming.block.enabled` ou a chave legada de canal `blockStreaming` quando -quiser respostas normais em blocos. Microsoft Teams é a exceção: ele não tem -transporte de bloco de pré-visualização de rascunho, então `streaming.mode: "block"` é mapeado para entrega de blocos do Teams -em vez de streaming parcial/progresso nativo. +`streaming.mode: "block"` é um modo de streaming de prévia para canais com suporte a edição, como Discord e Telegram. Ele não habilita a entrega de blocos do canal nesses casos. Use `streaming.block.enabled` ou a chave de canal legada `blockStreaming` quando quiser respostas normais em bloco. Microsoft Teams é a exceção: ele não tem transporte de blocos de prévia de rascunho, então `streaming.mode: "block"` mapeia para a entrega de blocos do Teams em vez de streaming parcial/progresso nativo. ### Mapeamento de canais -| Canal | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | -------------------------- | +| Canal | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ----------------------- | | Telegram | ✅ | ✅ | ✅ | rascunho de progresso editável | | Discord | ✅ | ✅ | ✅ | rascunho de progresso editável | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | -| MS Teams | ✅ | ✅ | ✅ | stream de progresso nativo | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | +| MS Teams | ✅ | ✅ | ✅ | stream de progresso nativo | Somente Slack: - `channels.slack.streaming.nativeTransport` alterna chamadas à API de streaming nativa do Slack quando `channels.slack.streaming.mode="partial"` (padrão: `true`). -- O streaming nativo do Slack e o status de thread de assistente do Slack exigem um destino de thread de resposta. DMs no nível superior não mostram essa pré-visualização em estilo de thread, mas ainda podem usar publicações e edições de pré-visualização de rascunho do Slack. +- O streaming nativo do Slack e o status de thread do assistente do Slack exigem um destino de thread de resposta. DMs de nível superior não mostram essa prévia no estilo thread, mas ainda podem usar publicações e edições de prévia de rascunho do Slack. -Migração de chaves legadas: +Migração de chave legada: -- Telegram: valores legados `streamMode` e valores escalares/booleanos de `streaming` são detectados e migrados pelos caminhos de compatibilidade de doctor/config para `streaming.mode`. -- Discord: `streamMode` + `streaming` booleano migram automaticamente para o enum `streaming`. -- Slack: `streamMode` migra automaticamente para `streaming.mode`; `streaming` booleano migra automaticamente para `streaming.mode` mais `streaming.nativeTransport`; `nativeStreaming` legado migra automaticamente para `streaming.nativeTransport`. +- Telegram: valores legados de `streamMode` e valores escalares/booleanos de `streaming` são detectados e migrados pelos caminhos de compatibilidade de doctor/config para `streaming.mode`. +- Discord: `streamMode` + booleano `streaming` migram automaticamente para o enum `streaming`. +- Slack: `streamMode` migra automaticamente para `streaming.mode`; booleano `streaming` migra automaticamente para `streaming.mode` mais `streaming.nativeTransport`; `nativeStreaming` legado migra automaticamente para `streaming.nativeTransport`. -### Comportamento em tempo de execução +### Comportamento em runtime Telegram: -- Usa `sendMessage` + atualizações de pré-visualização `editMessageText` em DMs e grupos/tópicos. -- Envia uma nova mensagem final em vez de editar no mesmo lugar quando uma pré-visualização ficou visível por cerca de um minuto, depois limpa a pré-visualização para que o carimbo de data/hora do Telegram reflita a conclusão da resposta. -- O streaming de pré-visualização é ignorado quando o streaming de blocos do Telegram está explicitamente ativado (para evitar streaming duplo). -- `/reasoning stream` pode escrever o raciocínio na pré-visualização. +- Usa `sendMessage` + atualizações de prévia com `editMessageText` em DMs e grupos/tópicos. +- Envia uma nova mensagem final em vez de editar no local quando uma prévia ficou visível por cerca de um minuto, então limpa a prévia para que o timestamp do Telegram reflita a conclusão da resposta. +- O streaming de prévia é ignorado quando o streaming de blocos do Telegram está explicitamente habilitado (para evitar streaming duplo). +- `/reasoning stream` pode escrever o raciocínio em uma prévia transitória que é excluída após a entrega final. Discord: -- Usa envio + edição de mensagens de pré-visualização. +- Usa mensagens de prévia com envio + edição. - O modo `block` usa divisão de rascunho (`draftChunk`). -- O streaming de pré-visualização é ignorado quando o streaming de blocos do Discord está explicitamente ativado. -- Mídia final, erro e cargas de resposta explícita cancelam pré-visualizações pendentes sem descarregar um novo rascunho e então usam a entrega normal. +- O streaming de prévia é ignorado quando o streaming de blocos do Discord está explicitamente habilitado. +- Mídia final, erro e cargas de resposta explícita cancelam prévias pendentes sem descarregar um novo rascunho, então usam a entrega normal. Slack: -- `partial` pode usar streaming nativo do Slack (`chat.startStream`/`append`/`stop`) quando disponível. -- `block` usa pré-visualizações de rascunho em estilo de anexo. -- `progress` usa texto de pré-visualização de status e depois a resposta final. -- DMs no nível superior sem uma thread de resposta usam publicações e edições de pré-visualização de rascunho em vez de streaming nativo do Slack. -- Streaming de pré-visualização nativo e de rascunho suprime respostas em blocos para esse turno, então uma resposta do Slack é transmitida por apenas um caminho de entrega. -- Cargas finais de mídia/erro e finais de progresso não criam mensagens de rascunho descartáveis; apenas finais de texto/bloco que podem editar a pré-visualização descarregam texto de rascunho pendente. +- `partial` pode usar o streaming nativo do Slack (`chat.startStream`/`append`/`stop`) quando disponível. +- `block` usa prévias de rascunho no estilo acréscimo. +- `progress` usa texto de prévia de status, então a resposta final. +- DMs de nível superior sem uma thread de resposta usam publicações e edições de prévia de rascunho em vez do streaming nativo do Slack. +- O streaming de prévia nativo e de rascunho suprime respostas em bloco para esse turno, então uma resposta do Slack é transmitida por apenas um caminho de entrega. +- Cargas finais de mídia/erro e finais de progresso não criam mensagens de rascunho descartáveis; apenas finais de texto/bloco que podem editar a prévia descarregam o texto de rascunho pendente. Mattermost: -- Transmite pensamento, atividade de ferramentas e texto parcial de resposta em uma única publicação de pré-visualização de rascunho que finaliza no mesmo lugar quando a resposta final é segura para enviar. -- Recai para o envio de uma nova publicação final se a publicação de pré-visualização foi excluída ou está indisponível no momento da finalização. -- Cargas finais de mídia/erro cancelam atualizações de pré-visualização pendentes antes da entrega normal em vez de descarregar uma publicação temporária de pré-visualização. +- Transmite pensamento, atividade de ferramentas e texto parcial de resposta em uma única publicação de prévia de rascunho que é finalizada no local quando a resposta final pode ser enviada com segurança. +- Recorre ao envio de uma nova publicação final se a publicação de prévia tiver sido excluída ou estiver indisponível no momento da finalização. +- Cargas finais de mídia/erro cancelam atualizações de prévia pendentes antes da entrega normal em vez de descarregar uma publicação de prévia temporária. Matrix: -- Pré-visualizações de rascunho finalizam no mesmo lugar quando o texto final pode reutilizar o evento de pré-visualização. -- Finais apenas com mídia, erro e incompatibilidade de destino de resposta cancelam atualizações de pré-visualização pendentes antes da entrega normal; uma pré-visualização obsoleta já visível é redigida. +- Prévias de rascunho são finalizadas no local quando o texto final pode reutilizar o evento de prévia. +- Finais somente com mídia, erro e incompatibilidade de destino de resposta cancelam atualizações de prévia pendentes antes da entrega normal; uma prévia obsoleta já visível é redigida. -### Atualizações de pré-visualização de progresso de ferramentas +### Atualizações de prévia de progresso de ferramentas -O streaming de pré-visualização também pode incluir atualizações de **progresso de ferramentas** — linhas curtas de status como "pesquisando na web", "lendo arquivo" ou "chamando ferramenta" — que aparecem na mesma mensagem de pré-visualização enquanto as ferramentas estão em execução, antes da resposta final. Isso mantém turnos de ferramenta em várias etapas visualmente ativos em vez de silenciosos entre a primeira pré-visualização de pensamento e a resposta final. +O streaming de prévia também pode incluir atualizações de **progresso de ferramentas** — linhas curtas de status como "pesquisando na web", "lendo arquivo" ou "chamando ferramenta" — que aparecem na mesma mensagem de prévia enquanto as ferramentas estão em execução, antes da resposta final. Isso mantém turnos de ferramentas com várias etapas visualmente ativos em vez de silenciosos entre a primeira prévia de pensamento e a resposta final. Superfícies compatíveis: -- **Discord**, **Slack**, **Telegram** e **Matrix** transmitem progresso de ferramentas para a edição de pré-visualização ao vivo por padrão quando o streaming de pré-visualização está ativo. Microsoft Teams usa seu stream de progresso nativo em conversas pessoais. -- Telegram foi lançado com atualizações de pré-visualização de progresso de ferramentas ativadas desde `v2026.4.22`; mantê-las ativadas preserva esse comportamento lançado. -- **Mattermost** já incorpora atividade de ferramentas em sua única publicação de pré-visualização de rascunho (veja acima). -- Edições de progresso de ferramentas seguem o modo ativo de streaming de pré-visualização; elas são ignoradas quando o streaming de pré-visualização está `off` ou quando o streaming de blocos assumiu a mensagem. No Telegram, `streaming.mode: "off"` é somente final: conversas genéricas de progresso também são suprimidas em vez de serem entregues como mensagens de status independentes, enquanto solicitações de aprovação, cargas de mídia e erros ainda são roteados normalmente. -- Para manter o streaming de pré-visualização mas ocultar linhas de progresso de ferramentas, defina `streaming.preview.toolProgress` como `false` para esse canal. Para desativar totalmente edições de pré-visualização, defina `streaming.mode` como `off`. -- Respostas a citações selecionadas do Telegram são uma exceção: quando `replyToMode` não está `"off"` e há texto de citação selecionada, o OpenClaw ignora o stream de pré-visualização da resposta para esse turno, então linhas de pré-visualização de progresso de ferramentas não podem ser renderizadas. Respostas à mensagem atual sem texto de citação selecionada ainda mantêm o streaming de pré-visualização. Veja [documentação do canal Telegram](/pt-BR/channels/telegram) para detalhes. +- **Discord**, **Slack**, **Telegram** e **Matrix** transmitem progresso de ferramentas na edição da prévia ao vivo por padrão quando o streaming de prévia está ativo. Microsoft Teams usa seu stream de progresso nativo em conversas pessoais. +- Telegram foi lançado com atualizações de prévia de progresso de ferramentas habilitadas desde `v2026.4.22`; mantê-las habilitadas preserva esse comportamento lançado. +- **Mattermost** já incorpora a atividade de ferramentas em sua única publicação de prévia de rascunho (veja acima). +- Edições de progresso de ferramentas seguem o modo de streaming de prévia ativo; elas são ignoradas quando o streaming de prévia está `off` ou quando o streaming de blocos assumiu a mensagem. No Telegram, `streaming.mode: "off"` é apenas final: conversa genérica de progresso também é suprimida em vez de ser entregue como mensagens de status independentes, enquanto prompts de aprovação, cargas de mídia e erros ainda são roteados normalmente. +- Para manter o streaming de prévia, mas ocultar linhas de progresso de ferramentas, defina `streaming.preview.toolProgress` como `false` para esse canal. Para manter linhas de progresso de ferramentas visíveis enquanto oculta texto de comando/execução, defina `streaming.preview.commandText` como `"status"` ou `streaming.progress.commandText` como `"status"`; o padrão é `"raw"` para preservar o comportamento lançado. Essa política é compartilhada por canais de rascunho/progresso que usam o renderizador de progresso compacto do OpenClaw, incluindo Discord, Matrix, Microsoft Teams, Mattermost, prévias de rascunho do Slack e Telegram. Para desativar edições de prévia completamente, defina `streaming.mode` como `off`. +- Respostas a citações selecionadas no Telegram são uma exceção: quando `replyToMode` não é `"off"` e texto de citação selecionado está presente, o OpenClaw ignora o stream de prévia da resposta para esse turno, então linhas de prévia de progresso de ferramentas não podem ser renderizadas. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de prévia. Consulte a [documentação do canal Telegram](/pt-BR/channels/telegram) para detalhes. -Exemplo: +Mantenha as linhas de progresso visíveis, mas oculte o texto bruto de comando/execução: ```json { @@ -213,7 +202,8 @@ Exemplo: "streaming": { "mode": "partial", "preview": { - "toolProgress": false + "toolProgress": true, + "commandText": "status" } } } @@ -221,9 +211,27 @@ Exemplo: } ``` -## Relacionados +Use a mesma forma sob outra chave compacta de canal de progresso, por exemplo `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost` ou pré-visualizações de rascunhos do Slack. Para o modo de rascunho de progresso, coloque a mesma política sob `streaming.progress`: + +```json +{ + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` + +## Relacionado - [Rascunhos de progresso](/pt-BR/concepts/progress-drafts) — mensagens visíveis de trabalho em andamento que são atualizadas durante turnos longos - [Mensagens](/pt-BR/concepts/messages) — ciclo de vida e entrega de mensagens -- [Tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa em falha de entrega +- [Nova tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa em caso de falha na entrega - [Canais](/pt-BR/channels) — suporte a streaming por canal diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index 6ef2fc91e..fe35fc175 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -1,20 +1,20 @@ --- read_when: - Executando testes localmente ou na CI - - Adicionando testes de regressão para erros de modelo/provedor - - Depuração do Gateway + comportamento do agente -summary: 'Kit de testes: suítes unitárias/e2e/live, executores Docker e o que cada teste cobre' + - Adicionando testes de regressão para bugs de modelo/provedor + - Depuração do comportamento do Gateway + agente +summary: 'Kit de testes: suítes unitárias/e2e/ao vivo, executores Docker e o que cada teste cobre' title: Testes x-i18n: - generated_at: "2026-05-03T21:34:22Z" + generated_at: "2026-05-04T07:03:04Z" model: gpt-5.5 provider: openai - source_hash: e7fb57bee958c4e6243f02193a657d7b19ca633c7a27f70eac6b590931390671 + source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 source_path: help/testing.md workflow: 16 --- -OpenClaw tem três suítes Vitest (unitária/integração, e2e, live) e um pequeno conjunto +O 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). @@ -23,13 +23,13 @@ de executores Docker. Este documento é um guia de "como testamos": - Como adicionar regressões para problemas reais de modelo/provedor. -**A pilha de QA (qa-lab, qa-channel, lanes de transporte live)** é documentada separadamente: +**Stack 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, autoria de cenários. -- [QA de matriz](/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 respaldados pelo repositório. +- [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) — arquitetura, superfície de comandos, criação 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. -Esta página cobre a execução das suítes de testes regulares e dos executores Docker/Parallels. A seção de executores específicos de QA abaixo ([Executores específicos de QA](#qa-specific-runners)) lista as invocações `qa` concretas e aponta de volta para as referências acima. +Esta página cobre a execução das suítes de teste regulares e dos executores Docker/Parallels. A seção de executores específicos de QA abaixo ([executores específicos de QA](#qa-specific-runners)) lista as invocações `qa` concretas e aponta de volta para as referências acima. ## Início rápido @@ -38,73 +38,73 @@ Na maioria dos dias: - Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Execução local mais rápida da suíte completa em uma máquina espaçosa: `pnpm test:max` -- Loop de observação direto do Vitest: `pnpm test:watch` -- O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefira execuções direcionadas primeiro quando estiver iterando sobre uma única falha. -- Site de QA respaldado por Docker: `pnpm qa:lab:up` -- Lane de QA respaldada por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- 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` +- 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` Quando você toca em testes ou quer confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` -Ao depurar provedores/modelos reais (requer credenciais reais): +Ao depurar provedores/modelos reais (exige credenciais reais): - Suíte 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 um turno de agente real `openai/gpt-5.4` ou + `live_gpt54=true` para uma rodada 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 de lanes mock-provider, deep-profile e GPT 5.4 em + publicam artefatos das lanes de provedor simulado, perfil profundo e GPT 5.4 em `openclaw/clawgrit-reports` quando `CLAWGRIT_REPORTS_TOKEN` está configurado. O - relatório mock-provider também inclui números de inicialização do Gateway no nível de código-fonte, memória, - pressão de Plugin, loop hello repetido de modelo falso e inicialização da CLI. -- Varredura live de modelos com Docker: `pnpm test:docker:live-models` - - Cada modelo selecionado agora executa um turno de texto mais uma pequena sondagem no estilo leitura de arquivo. - Modelos cujos metadados anunciam entrada `image` também executam um pequeno turno de imagem. + 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 `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 de trabalho live/E2E reutilizável com - `include_live_suites: true`, que inclui jobs separados de matriz live de modelos Docker - fragmentados por provedor. + `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 + divididos por provedor. - Para reexecuções focadas em CI, 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 Docker contra o caminho do app-server do Codex, vincula uma DM sintética + - 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`, depois verifica uma resposta simples e um anexo de imagem - roteados 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 turnos do agente do Gateway pelo harness do app-server do Codex de propriedade do Plugin, + `/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, - cron MCP, subagente e Guardian. Desative a sondagem 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 sondagens: + 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: `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 `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 de cinto e suspensórios para a superfície de comando de resgate do canal de mensagens. - Ela exercita `/crestodian status`, enfileira uma alteração persistente de modelo, - responde `/crestodian yes` e verifica o caminho de gravação de auditoria/configuração. + - 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, + 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 que o fallback do planejador fuzzy se traduz em uma gravação de configuração tipada auditada. + e verifica se o fallback do planejador aproximado se traduz em uma escrita tipada + de configuração 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 gravações de configuração/modelo/agente/Plugin do Discord + SecretRef, - valida a configuração e verifica entradas de auditoria. O mesmo caminho de configuração Ring 0 também é - coberto no QA Lab por + o Crestodian, aplica escritas de setup/modelo/agente/Plugin Discord + 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 agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - isolado contra `moonshot/kimi-k2.6`. Verifique que o JSON relata Moonshot/K2.6 e que a + isolado contra `moonshot/kimi-k2.6`. Verifique se o JSON relata Moonshot/K2.6 e se a transcrição do assistente armazena `usage.cost` normalizado. @@ -113,102 +113,105 @@ Quando você só precisa de um caso com falha, prefira restringir os testes live ## 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 suítes de teste principais quando você precisa do realismo do QA-lab: -O CI executa o QA Lab em fluxos de trabalho dedicados. A paridade agentic fica aninhada sob -`QA-Lab - All Lanes` e validação de release, não em um fluxo de trabalho de PR independente. +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 validação ampla deve usar `Full Release Validation` com -`rerun_group=qa-parity` ou o grupo de QA de release-checks. `QA-Lab - All Lanes` -executa todas as noites em `main` e por disparo 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 -`--profile fast` da Matrix explicitamente, enquanto a CLI Matrix e a entrada manual do fluxo de trabalho -permanecem por padrão como `all`; o disparo manual pode fragmentar `all` em jobs -`transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. `OpenClaw Release -Checks` executa paridade mais as 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 de 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. +`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. -Os fragmentos live media de release completo usam +Os shards live de mídia de release completo usam `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, que já tem -`ffmpeg` e `ffprobe`. Fragmentos Docker live de modelo/backend usam a imagem compartilhada -`ghcr.io/openclaw/openclaw-live-test:` criada uma vez por commit selecionado, -depois a puxam com `OPENCLAW_SKIP_DOCKER_BUILD=1` em vez de reconstruir -dentro de cada fragmento. +`ffmpeg` e `ffprobe`. Shards Docker 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 +dentro de cada shard. - `pnpm openclaw qa suite` - - Executa cenários de QA apoiados pelo repositório diretamente no host. + - Executa cenários de QA baseados no repositório diretamente no host. - Executa vários cenários selecionados em paralelo por padrão com workers de - 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. + 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. - 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. - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. - `aimock` inicia um servidor de provedor local apoiado por AIMock para cobertura - experimental de fixture e mock de protocolo sem substituir a lane + `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. - `pnpm test:gateway:cpu-scenarios` - - Executa o benchmark de inicialização do Gateway mais um pequeno pacote de cenários mock do QA Lab + - Executa o bench de inicialização do Gateway mais um pequeno pacote de cenários mock do QA Lab (`channel-chat-baseline`, `memory-failure-fallback`, `gateway-restart-inflight-run`) e grava um resumo combinado de observação de CPU em `.artifacts/gateway-cpu-scenarios/`. - - Sinaliza 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 vários minutos. + - 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. - 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 descartável do Multipass. + - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host. - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`. - - Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o convidado: - chaves de provedor baseadas em env, o caminho da configuração de provedor ao vivo de QA e `CODEX_HOME` + - 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` quando presente. - - Diretórios de saída devem permanecer sob a raiz do repositório para que o convidado possa gravar de volta pelo + - Diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado. - Grava o relatório + resumo normais de QA mais logs do Multipass em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA apoiado por Docker para trabalho de QA no estilo de operador. + - Inicia o site de QA baseado em 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 globalmente no + - 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ência - na inicialização, executa doctor e executa uma rodada de agente local contra um + 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. - 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 - embutido. Ele verifica que o contexto oculto de runtime do OpenClaw é persistido como uma + 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, - então semeia uma sessão JSONL quebrada afetada e verifica que - `openclaw doctor --fix` a reescreve para a branch ativa com um backup. + depois semeia um JSONL de sessão quebrada afetada e verifica que + `openclaw doctor --fix` o reescreve para o branch ativo com backup. - `pnpm test:docker:npm-telegram-live` - - Instala um pacote candidato do OpenClaw no Docker, executa onboarding de pacote instalado, - configura Telegram pela CLI instalada e então reutiliza a lane de QA ao vivo do Telegram + - 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 `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 pelo registro. + instalar 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, 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. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` substitui o `OPENCLAW_QA_CREDENTIAL_ROLE` compartilhado apenas para esta lane. - - GitHub Actions expõe esta lane como o workflow manual de mantenedor - `NPM Telegram Beta E2E`. Ele não roda 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 executada em paralelo - contra um pacote candidato. Ele aceita um ref confiável, especificação npm publicada, + - 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, 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`, então executa o + do `openclaw-current.tgz` normalizado como `package-under-test`, depois 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`. @@ -244,23 +247,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 configurado e então habilita channels/plugins empacotados por edições de config. - - 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ência. - - Também instala uma baseline npm mais antiga conhecida, habilita Telegram antes de executar - `openclaw update --tag ` e verifica que o doctor pós-atualização do candidato - limpa detritos de dependência de Plugin legado sem um reparo postinstall do lado do harness. + com OpenAI configurada e 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. - `pnpm test:parallels:npm-update` - - Executa o smoke nativo de atualização de instalação empacotada em convidados Parallels. Cada - plataforma selecionada primeiro instala o pacote baseline solicitado, então executa - o comando `openclaw update` instalado no mesmo convidado e verifica a - versão instalada, o status de atualização, a prontidão do Gateway e uma rodada 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 + - 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` para a prova de rodada de agente ao vivo por - padrão. Passe `--model ` ou defina + - A lane OpenAI usa `openai/gpt-5.5` por padrão para a prova live de rodada de agente. + 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 @@ -271,58 +277,58 @@ gh workflow run package-acceptance.yml --ref main \ timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - O script grava logs de lane aninhados em `/tmp/openclaw-parallels-npm-update.*`. + - O script grava logs de lanes aninhadas em `/tmp/openclaw-parallels-npm-update.*`. Inspecione `windows-update.log`, `macos-update.log` ou `linux-update.log` antes de presumir que o wrapper externo travou. - - A atualização do Windows pode passar 10 a 15 minutos no doctor pós-atualização e no trabalho de - atualização de pacote em um convidado frio; isso ainda é saudável quando o log de debug npm + - 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 aninhado está avançando. - - Não execute este wrapper agregado em paralelo com lanes individuais de smoke do Parallels - macOS, Windows ou Linux. Elas compartilham estado de VM e podem colidir na - restauração de snapshot, serviço de pacote ou estado do Gateway convidado. - - A prova pós-atualização executa a superfície normal de Plugins empacotados porque - facades de capacidade como fala, geração de imagem e entendimento de mídia - são carregadas por APIs de runtime empacotadas mesmo quando a própria rodada do agente - verifica apenas uma resposta de texto simples. + - 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 + 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. - `pnpm openclaw qa matrix` - - Executa a lane de QA ao vivo do Matrix contra um homeserver Tuwunel descartável apoiado por Docker. Apenas checkout de origem — instalações empacotadas não incluem `qa-lab`. - - CLI completa, catálogo de perfis/cenários, vars de env e layout de artefatos: [QA do Matrix](/pt-BR/concepts/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). - `pnpm openclaw qa telegram` - - Executa a lane de QA ao vivo do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do 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 do 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. - 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 com falha. - - Exige dois bots distintos no mesmo grupo privado, com o bot SUT expondo um username do Telegram. - - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot em `@BotFather` para ambos os bots e garanta que o bot driver consiga observar tráfego de bots no 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 requisição de envio do driver até a resposta observada do SUT. + 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. -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. +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. ### Credenciais compartilhadas do Telegram 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 apoiado por Convex, envia heartbeats -desse 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 baseado em Convex, envia heartbeats +para esse lease enquanto a lane está em execução e libera o lease no desligamento. Scaffold de projeto Convex de referência: - `qa/convex-credential-broker/` -Vars de env obrigatórias: +Env vars obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) - Um segredo para a função selecionada: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` -- Seleção da função de credencial: +- Seleção de função de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa `ci` por padrão no CI, `maintainer` caso contrário) + - Padrão de env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa `ci` por padrão no CI, `maintainer` caso contrário) -Vars de env opcionais: +Env vars opcionais: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (padrão `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (padrão `30000`) @@ -330,11 +336,11 @@ Vars de env opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento apenas local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex de loopback `http://` apenas para desenvolvimento local. `OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem +Comandos de admin de mantenedor (adicionar/remover/listar pool) exigem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. Helpers de CLI para mantenedores: @@ -346,32 +352,31 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Use `doctor` antes de execuções ao vivo para verificar a URL do site Convex, segredos do broker, -prefixo de endpoint, timeout HTTP e alcance de admin/list sem imprimir -valores secretos. Use `--json` para saída legível por máquina em scripts e -utilitários de CI. +Use `doctor` antes de execuções live para verificar a URL do site Convex, segredos do broker, +prefixo do endpoint, tempo limite HTTP e acessibilidade de admin/list sem imprimir +valores secretos. Use `--json` para saída legível por máquina em scripts e utilitários de CI. -Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - - Solicitação: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Sucesso: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Esgotado/com nova tentativa: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Esgotado/repetível: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) - `POST /release` - - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Requisição: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (somente segredo de mantenedor) - - Solicitação: `{ kind, actorId, payload, note?, status? }` +- `POST /admin/add` (apenas segredo de mantenedor) + - Requisição: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (somente segredo de mantenedor) - - Solicitação: `{ credentialId, actorId }` +- `POST /admin/remove` (apenas segredo de mantenedor) + - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (somente segredo de mantenedor) - - Solicitação: `{ kind?, status?, includePayload?, limit? }` + - Proteção de concessão ativa: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (apenas segredo de mantenedor) + - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` Formato do payload para o tipo Telegram: @@ -380,60 +385,60 @@ Formato do payload para o tipo Telegram: - `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. -### Adicionando um canal ao QA +### Como adicionar um canal à QA -A arquitetura e os nomes de helpers de cenário para novos adaptadores de canal ficam em [Visão geral de QA → Adicionando um canal](/pt-BR/concepts/qa-e2e-automation#adding-a-channel). O requisito mínimo: implemente o runner de transporte no seam de host compartilhado `qa-lab`, declare `qaRunners` no manifesto do plugin, monte como `openclaw qa ` e crie cenários em `qa/scenarios/`. +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/`. -## Suites de teste (o que roda onde) +## Suítes de teste (o que roda onde) -Pense nas suites como “realismo crescente” (e também instabilidade/custo crescentes): +Pense nas suítes como “realismo crescente” (e instabilidade/custo crescentes): -### Unitário / integração (padrão) +### Unitários / integração (padrão) - Comando: `pnpm test` -- Configuração: execuções sem alvo específico usam o conjunto de shards `vitest.full-*.config.ts` e podem expandir shards multiprojeto em configurações por projeto para agendamento paralelo +- 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 no mesmo processo (autenticação do Gateway, roteamento, ferramentas, parsing, configuração) + - Testes de integração em processo (autenticação do Gateway, roteamento, ferramentas, análise, 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 do resolvedor e do loader de superfície pública devem provar o comportamento amplo de fallback de `api.js` e - `runtime-api.js` com pequenas fixtures de plugin geradas, não - APIs de fonte reais de plugins incluídos. Carregamentos reais de API de plugin pertencem a - suites de contrato/integração de responsabilidade do plugin. + - 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. - - `pnpm test` sem alvo específico 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 nativo gigante do projeto raiz. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensões deixe suites não relacionadas sem recursos. - - `pnpm test --watch` ainda usa o grafo de projeto raiz nativo `vitest.config.ts`, porque um loop de watch com vários shards não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham alvos explícitos de arquivo/diretório primeiro por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo de inicialização completo do projeto raiz. - - `pnpm test:changed` expande caminhos git alterados em lanes baratas com escopo por padrão: alterações diretas em testes, arquivos `*.test.ts` irmãos, mapeamentos explícitos de fonte e dependentes locais do grafo de importação. Alterações de configuração/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 inteligente normal de checagem local para trabalho estreito. Ele classifica o diff em core, testes de core, extensões, testes de extensão, apps, docs, metadados de release, ferramentas de 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 prova de teste. Bumps de versão somente de metadados de release executam checagens 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. - - Alterações no harness de Docker live do ACP executam checagens focadas: sintaxe de shell para os scripts de autenticação Docker live e um dry-run do agendador Docker live. Alterações em `package.json` são incluídas somente quando o diff está limitado a `scripts["test:docker:live-*"]`; alterações de dependência, exportação, versão e outra superfície de package ainda usam os guards mais amplos. - - Testes unitários leves em importações de agents, comandos, plugins, helpers de auto-reply, `plugin-sdk` e áreas semelhantes de utilitários puros passam pela lane `unit-fast`, que pula `test/setup-openclaw-runtime.ts`; arquivos com estado/pesados em runtime permanecem nas lanes existentes. - - Arquivos-fonte selecionados de helpers de `plugin-sdk` e `commands` também mapeiam execuções em modo alterado para testes irmãos explícitos nessas lanes leves, então alterações em helpers evitam reexecutar a suite pesada completa desse diretório. - - `auto-reply` tem buckets dedicados para helpers de core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. O CI divide ainda mais a subárvore de reply em shards de agent-runner, dispatch e commands/state-routing para que um bucket pesado em importações não concentre toda a cauda de execução do Node. - - O CI normal de PR/main pula intencionalmente a varredura em lote de extensões e o shard somente de release `agentic-plugins`. A Validação Completa de Release dispara o workflow filho separado de Pré-release de Plugin para essas suites pesadas em plugins/extensões em candidatos a release. + - `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`, `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. - + - - Quando você alterar entradas de descoberta de ferramenta de mensagem ou contexto de runtime de Compaction, - mantenha ambos os níveis de cobertura. - - Adicione regressões focadas de helpers para limites puros de roteamento e normalização. - - Mantenha saudáveis as suites de integração do runner embarcado: + - Quando você altera entradas de descoberta de ferramenta de mensagem 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: `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 suites verificam que ids com escopo e comportamento de Compaction ainda fluem - pelos caminhos reais `run.ts` / `compact.ts`; testes somente de helpers - não são substituto suficiente para esses caminhos de integração. + - 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 + não são um substituto suficiente para esses caminhos de integração. @@ -441,66 +446,66 @@ Pense nas suites como “realismo crescente” (e também instabilidade/custo cr - A configuração base do Vitest usa `threads` por padrão. - A configuração compartilhada do Vitest fixa `isolate: false` e usa o - runner não isolado nos projetos raiz, configurações e2e e live. - - A lane raiz de UI mantém seu setup `jsdom` e otimizador, mas também roda no - runner compartilhado não isolado. + 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. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest. - - `scripts/run-vitest.mjs` adiciona `--no-maglev` por padrão aos processos Node - filhos do Vitest para reduzir retrabalho de compilação do V8 durante execuções locais grandes. - Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` para comparar com o comportamento padrão do V8. + - `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. + Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` para comparar com o comportamento V8 padrão. - `pnpm changed:lanes` mostra quais lanes arquiteturais um diff aciona. - - O hook de pre-commit é somente de formatação. Ele recoloca arquivos formatados no stage e - não executa lint, typecheck nem testes. - - Execute `pnpm check:changed` explicitamente antes da entrega ou push quando você - precisar do gate inteligente de checagem local. - - `pnpm test:changed` passa por lanes baratas com escopo por padrão. Use - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando o agente - decidir que uma alteração de harness, configuração, package ou contrato realmente precisa de cobertura + - 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ê + 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. - `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 recua - quando a média de carga do host já está alta, então várias execuções - Vitest concorrentes causam menos impacto por padrão. + - 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. - 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 - configuração dos testes muda. - - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` ativado em hosts compatíveis; + fiação de teste muda. + - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se você quiser um local de cache explícito para profiling direto. - + - - `pnpm test:perf:imports` ativa relatórios de duração de importação do Vitest, além de - saída de detalhamento de importações. - - `pnpm test:perf:imports:changed` limita a mesma visão de profiling aos + - `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 arquivos alterados desde `origin/main`. - - Dados de tempo dos shards são gravados em `.artifacts/vitest-shard-timings.json`. - Execuções de configuração inteira usam o caminho da configuração como chave; shards de CI - por padrão de inclusão acrescentam o nome do shard para que shards filtrados possam ser acompanhados + - 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 separadamente. - - Quando um teste de alto custo 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 - simule esse seam diretamente, em vez de fazer importação profunda de helpers de runtime apenas - para repassá-los por `vi.mock(...)`. + - 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(...)`. - `pnpm test:perf:changed:bench -- --ref ` compara o - `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado - e imprime tempo de parede mais RSS máximo no macOS. - - `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore - suja atual encaminhando a lista de arquivos alterados por + `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 `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 - startup do Vitest/Vite e overhead de transform. - - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a - suite unitária com paralelismo de arquivos desativado. + overhead de inicialização e transformação do Vitest/Vite. + - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a + suíte unitária com paralelismo de arquivos desabilitado. @@ -508,77 +513,77 @@ Pense nas suites como “realismo crescente” (e também instabilidade/custo cr ### Estabilidade (Gateway) - Comando: `pnpm test:stability:gateway` -- Configuração: `vitest.gateway.config.ts`, forçada a um worker +- Configuração: `vitest.gateway.config.ts`, forçada para um worker - Escopo: - - Inicia um Gateway de loopback real com diagnósticos ativados por padrão - - Simula carga sintética de mensagens do Gateway, memória e payloads grandes pelo caminho de eventos de diagnóstico - - Consulta `diagnostics.stability` via RPC WS do Gateway - - Cobre helpers de persistência do pacote de estabilidade de diagnóstico - - Confirma que o gravador permanece limitado, amostras sintéticas de RSS ficam abaixo do orçamento de pressão e profundidades de fila por sessão drenam de volta para zero + - Inicia um Gateway 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 + - 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 - Expectativas: - Seguro para CI e sem chaves - - Lane estreita para acompanhamento de regressão de estabilidade, não substituto para a suite completa do Gateway + - Lane estreita para acompanhamento de regressões de estabilidade, não um substituto para a suíte completa do Gateway ### E2E (smoke do Gateway) - Comando: `pnpm test:e2e` - Configuração: `vitest.e2e.config.ts` -- Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e testes E2E de plugins incluídos em `extensions/` -- Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repo. +- 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. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Roda em modo silencioso por padrão para reduzir overhead de I/O do console. -- Overrides úteis: + - Executa em modo silencioso por padrão para reduzir a sobrecarga de E/S do console. +- Sobrescritas úteis: - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reativar saída verbose do console. + - `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada do console. - Escopo: - - Comportamento end-to-end de Gateway multi-instância - - Superfícies WebSocket/HTTP, pareamento de Node e networking mais pesado + - Comportamento ponta a ponta de Gateway multi-instância + - Superfícies WebSocket/HTTP, pareamento de Node e rede mais pesada - Expectativas: - - Roda em CI (quando habilitado no pipeline) + - 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) -### E2E: smoke do back-end OpenShell +### E2E: smoke do backend OpenShell - Comando: `pnpm test:e2e:openshell` - Arquivo: `extensions/openshell/src/backend.e2e.test.ts` - 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 sobre `sandbox ssh-config` real + execução SSH - - Verifica o comportamento de sistema de arquivos canônico remoto por meio da ponte fs da sandbox + - 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 - Expectativas: - - Somente opt-in; não faz parte da execução padrão de `pnpm test:e2e` - - Requer uma CLI local `openshell` mais um daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o Gateway de teste e a sandbox -- Substituições úteis: + - 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 + - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o Gateway e a sandbox de teste +- Sobrescritas úteis: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário de CLI não padrão ou um script wrapper + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper ### Ao vivo (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 Plugins incluídos em `extensions/` +- Arquivos: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e testes ao vivo de Plugin integrado 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 ferramenta, problemas de autenticação e comportamento de limite de taxa + - Capturar mudanças de formato de provedor, peculiaridades de chamadas de ferramentas, problemas de autenticação e comportamento de limite 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 um diretório home temporário de teste para que fixtures unitárias não possam modificar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` somente quando você precisar intencionalmente que os 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/ruído do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar todos os logs de inicialização. -- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por execução ao vivo via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. +- 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. - Saída de progresso/Heartbeat: - - As suítes ao vivo agora emitem linhas de progresso para stderr para que chamadas longas a provedores fiquem visivelmente ativas mesmo quando a captura de console do Vitest estiver silenciosa. - - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso do provedor/Gateway sejam transmitidas imediatamente durante execuções ao vivo. + - 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. - Ajuste Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajuste Heartbeats de Gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajuste Heartbeats de Gateway/probe com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Qual suíte devo executar? @@ -586,66 +591,61 @@ 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 caiu” / falhas específicas de provedor / chamada de ferramentas: execute um `pnpm test:live` reduzido +- Depurando “meu bot está fora do ar” / falhas específicas de provedor / chamadas de ferramentas: execute um `pnpm test:live` reduzido -## Testes ao vivo (que tocam a rede) +## Testes ao vivo (com acesso à rede) -Para a matriz de modelos ao vivo, smokes de backend da 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 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). -## Executores Docker (verificações opcionais de "funciona no Linux") +## Runners Docker (verificações opcionais de "funciona no Linux") -Esses executores Docker se dividem em dois grupos: +Esses runners Docker se dividem em dois grupos: -- Executores de modelos ao vivo: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o 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`. -- Executores Docker ao vivo usam por padrão um limite de smoke menor para que uma varredura Docker completa permaneça prática: +- 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: `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando você + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sobrescreva essas variáveis de ambiente quando você quiser explicitamente a varredura exaustiva maior. -- `test:docker:all` cria a imagem Docker 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` e depois cria/reutiliza duas imagens `scripts/e2e/Dockerfile`. A imagem base é apenas o executor Node/Git para faixas de instalação/atualização/dependências de Plugin; essas faixas montam o tarball pré-criado. A imagem funcional instala o mesmo tarball em `/app` para faixas de funcionalidade do app criado. As definições de faixas Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`; a lógica de planejamento fica em `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executa o plano selecionado. O agregado usa um agendador local ponderado: `OPENCLAW_DOCKER_ALL_PARALLELISM` controla slots de processo, enquanto limites de recursos impedem que faixas pesadas ao vivo, de instalação npm e de múltiplos serviços iniciem todas de uma vez. Se uma única faixa for mais pesada que os limites ativos, o agendador ainda poderá iniciá-la quando o pool estiver vazio e então a manterá 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 executor realiza uma pré-verificação Docker por padrão, remove contêineres OpenClaw E2E obsoletos, imprime status a cada 30 segundos, armazena tempos de faixas bem-sucedidas em `.artifacts/docker-tests/lane-timings.json` e usa esses tempos para iniciar primeiro faixas mais longas em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto ponderado de faixas sem criar ou executar Docker, ou `node scripts/test-docker-all.mjs --plan-json` para imprimir o plano de CI para faixas selecionadas, necessidades de pacote/imagem e credenciais. -- `Package Acceptance` é o gate de pacote nativo do GitHub para "este tarball instalável funciona como 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 faixas Docker E2E 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, a matriz de sobrevivência de upgrade publicado, os padrões de lançamento e a triagem de falhas. -- Verificações de build e release executam `scripts/check-cli-bootstrap-imports.mjs` depois do tsdown. A proteção percorre o grafo estático criado a partir de `dist/entry.js` e `dist/cli/run-main.js` e falha se a inicialização pré-despacho importar dependências de pacote como Commander, interface de prompt, undici ou logging antes do despacho do comando; ela também mantém o chunk de execução do Gateway incluído no pacote 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 corte, o harness tolera apenas lacunas de metadados de pacotes já lançados: entradas omitidas de inventário privado 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 Plugin, 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. -- Executores 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. +- `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. -Os executores Docker de modelos ao vivo também fazem bind mount apenas dos diretórios home de autenticação da CLI necessários (ou todos os suportados quando a execução não é reduzida) e depois os copiam para o diretório home do contêiner antes da execução para que o OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host: +Os 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: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) - Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`; cobre Claude, Codex e Gemini por padrão, com cobertura estrita de Droid/OpenCode via `pnpm test:docker:live-acp-bind:droid` e `pnpm test:docker:live-acp-bind:opencode`) -- Smoke do backend da CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke do harness do servidor do app Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- 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`) - Gateway + agente de desenvolvimento: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Smoke de observabilidade: `pnpm qa:otel:smoke` é uma lane privada de checkout de código-fonte de QA. Ela intencionalmente não faz parte das lanes de lançamento Docker do pacote porque o tarball npm omite o QA Lab. +- 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 do tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala o tarball empacotado do OpenClaw globalmente no Docker, configura a OpenAI via onboarding com referência de env mais Telegram por padrão, executa o doctor e executa uma rodada de agente OpenAI mockada. Reutilize um tarball pré-compilado com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, pule o rebuild do 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 Plugin pós-atualização funcionam, depois troca de 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 chaves de provedor ou canal ao vivo, depois inicia um Gateway local 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 baseline com uma receita de comando embutida, valida a configuração resultante, atualiza essa instalação publicada para o tarball candidato, executa o doctor não interativo, grava `.artifacts/upgrade-survivor/summary.json`, depois inicia um Gateway local loopback e verifica intents configurados, preservação de estado, inicialização, `/healthz`, `/readyz` e orçamentos de status RPC. Sobrescreva uma baseline com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, peça ao agendador agregado para expandir baselines exatas com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, como `all-since-2026.4.23`, e expanda fixtures em 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 Plugin externo 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 oculta de transcritos de contexto de runtime mais o reparo pelo doctor de branches duplicados afetados de reescrita de prompt. -- Smoke de instalação global com Bun: `bash scripts/e2e/bun-global-install-smoke.sh` empacota a árvore atual, instala-a com `bun install -g` em uma home isolada e verifica que `openclaw infer image providers --json` retorna provedores de imagem empacotados em vez de travar. Reutilize um tarball pré-compilado com `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, pule o build do 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 por padrão npm `latest` como baseline stable 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 novas execuções locais. -- O CI Install Smoke pula a atualização global direct-npm duplicada com `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; execute o script localmente sem essa env quando a cobertura direta de `npm install -g` for necessária. -- Smoke da CLI de exclusão de workspace compartilhado por agentes: `pnpm test:docker:agents-delete-shared-workspace` (script: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) compila a imagem Dockerfile raiz por padrão, semeia dois agentes com um workspace em uma home isolada no contêiner, 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 + saúde): `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 de código-fonte mais uma camada Chromium, inicia o Chromium com CDP bruto, executa `browser doctor --deep` e verifica que snapshots de função CDP cobrem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame. -- Regressão de raciocínio mínimo em OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI mockado por meio do Gateway, verifica que `web_search` eleva `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema pelo provedor e verifica que o detalhe bruto aparece nos logs do Gateway. -- Ponte de canal MCP (Gateway semeado + ponte stdio + smoke bruto de notification-frame do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Ferramentas MCP do pacote Pi (servidor MCP stdio real + smoke allow/deny do perfil Pi embutido): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Limpeza MCP de Cron/subagente (Gateway real + 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 hoisted, refs móveis de git, kitchen-sink do ClawHub, atualizações de marketplace e habilitação/inspeção de 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 pacote/runtime kitchen-sink padrão com `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` e `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sem `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, o teste usa um servidor fixture ClawHub local hermético. +- 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 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 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 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 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 habilitação/inspeção de 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, habilitação, desabilitação, upgrade, downgrade e desinstalação com código ausente de Plugin npm com rastreamento de recursos. +- 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. Para pré-compilar e reutilizar manualmente a imagem funcional compartilhada: @@ -654,50 +654,50 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: 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 prevalecem quando definidas. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` aponta para uma imagem compartilhada remota, os scripts fazem pull dela se ela ainda não estiver local. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação em vez do runtime de app compilado compartilhado. +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. -Os executores 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 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. A etapa de preparação ignora caches grandes apenas locais e saídas de build de apps, como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios de saída `.build` locais de apps ou -do Gradle, para que as execuções live no Docker não passem minutos copiando +`.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 artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondagens live do Gateway não iniciem -workers reais de canais Telegram/Discord/etc. dentro do contêiner. -`test:docker:live-models` ainda executa `pnpm test:live`, então encaminhe também -`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura live do Gateway -dessa trilha Docker. -`test:docker:openwebui` é um teste de fumaça de compatibilidade de nível mais alto: ele inicia um -contêiner do Gateway OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, -inicia um contêiner Open WebUI fixado contra esse Gateway, entra pelo -Open WebUI, verifica que `/api/models` expõe `openclaw/default` e então envia uma -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 partida a frio. -Essa trilha espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções Dockerizadas. +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, +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. 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`, depois +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, -comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + -permissão no estilo Claude sobre a ponte MCP stdio real. A verificação de notificação -inspeciona diretamente os quadros MCP stdio brutos, para que o teste de fumaça valide o que a +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 ponte realmente emite, não apenas o que um SDK de cliente específico por acaso expõe. -`test:docker:pi-bundle-mcp-tools` é determinístico e não precisa de uma chave de modelo live. -Ele constrói 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 que `coding` e `messaging` mantêm +`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 ferramentas `bundle-mcp`, enquanto `minimal` e `tools.deny: ["bundle-mcp"]` as filtram. -`test:docker:cron-mcp-cleanup` é determinístico e não precisa de uma chave de modelo live. -Ele inicia um Gateway semeado com um servidor de sondagem MCP stdio real, executa uma -rodada cron isolada e uma rodada filha única de `/subagents spawn`, depois verifica -que 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 one-shot de `/subagents spawn`, e então verifica +se o processo filho MCP encerra após cada execução. -Teste de fumaça manual de thread ACP em linguagem simples (não CI): +Smoke manual de thread ACP em linguagem simples (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` - Mantenha este script para fluxos de regressão/debug. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. @@ -706,80 +706,80 @@ 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 os testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de configuração/workspace e sem montagens externas de autenticação da CLI +- `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_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 da CLI em `$HOME` são montados como somente leitura em `/host-auth...` e então copiados para `/home/node/...` antes do início dos testes +- Diretórios/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 padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Execuções restringidas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Sobrescreva 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` + - 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 reexecuções que não precisam de rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do repositório de perfis (não do ambiente) -- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo Gateway para o teste de fumaça Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para sobrescrever o prompt de verificação de nonce usado pelo teste de fumaça Open WebUI -- `OPENWEBUI_IMAGE=...` para sobrescrever a tag fixada da imagem Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em novas execuções que não precisam de rebuild +- `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 ## Sanidade da documentação -Execute verificações de documentação após edições na documentação: `pnpm check:docs`. -Execute a validação completa de âncoras Mintlify quando também precisar de verificações de títulos dentro da página: `pnpm docs:check-links:anchors`. +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`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramentas do Gateway (OpenAI mockado, 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 de configuração do Gateway (WS `wizard.start`/`wizard.next`, grava configuração + autenticação imposta): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- 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") -## Evals de confiabilidade de agente (skills) +## Evals de confiabilidade de agentes (skills) -Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade de agente”: +Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade de agentes”: -- Chamada de ferramentas mockada pelo Gateway real + loop de agente (`src/gateway/gateway.test.ts`). -- Fluxos de assistente de configuração de ponta a ponta que validam o encadeamento de sessão e os efeitos de configuração (`src/gateway/gateway.test.ts`). +- 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`). O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)): -- **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 vários turnos que validam ordem de ferramentas, preservação do histórico da sessão e limites de sandbox. +- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a skill 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. -Evals futuras devem permanecer determinísticas primeiro: +Evals futuros devem permanecer determinísticos primeiro: -- Um executor de cenários usando provedores mockados para validar chamadas de ferramentas + ordem, leituras de arquivos de Skill e encadeamento de sessão. -- Uma pequena suíte de cenários focados em Skills (usar versus evitar, bloqueios, injeção de prompt). -- Evals live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta. +- 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. ## Testes de contrato (formato de Plugin e canal) Testes de contrato verificam que todo Plugin e canal registrado está em conformidade com seu contrato de interface. Eles iteram por todos os plugins descobertos e executam uma suíte de -asserções de formato e comportamento. A trilha unitária padrão de `pnpm test` ignora intencionalmente -esses arquivos compartilhados de fronteira e fumaça; execute os comandos de contrato explicitamente -quando tocar superfícies compartilhadas de canal ou provedor. +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 +quando tocar em superfícies compartilhadas de canal ou provedor. ### Comandos - Todos os contratos: `pnpm test:contracts` -- Apenas contratos de canal: `pnpm test:contracts:channels` -- Apenas contratos de provedor: `pnpm test:contracts:plugins` +- Somente contratos de canal: `pnpm test:contracts:channels` +- Somente contratos de provedor: `pnpm test:contracts:plugins` ### Contratos de canal Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Formato básico do Plugin (id, nome, capacidades) +- **plugin** - Formato básico do Plugin (id, nome, capabilities) - **setup** - Contrato do assistente de configuração -- **session-binding** - Comportamento de vinculação de sessão -- **outbound-payload** - Estrutura da carga da mensagem +- **session-binding** - Comportamento de vínculo de sessão +- **outbound-payload** - Estrutura de payload de mensagem - **inbound** - Tratamento de mensagens de entrada -- **actions** - Handlers de ação de canal +- **actions** - Handlers de ações de canal - **threading** - Tratamento de ID de thread - **directory** - API de diretório/lista -- **group-policy** - Imposição de política de grupo +- **group-policy** - Aplicação de política de grupo ### Contratos de status de provedor @@ -798,7 +798,7 @@ Localizados em `src/plugins/contracts/*.contract.test.ts`: - **discovery** - Descoberta de Plugin - **loader** - Carregamento de Plugin - **runtime** - Runtime de provedor -- **shape** - Formato/interface de Plugin +- **shape** - Formato/interface do Plugin - **wizard** - Assistente de configuração ### Quando executar @@ -807,23 +807,23 @@ Localizados em `src/plugins/contracts/*.contract.test.ts`: - Depois de adicionar ou modificar um canal ou Plugin de provedor - Depois de refatorar registro ou descoberta de plugins -Testes de contrato executam em CI e não exigem chaves de API reais. +Testes de contrato executam em CI e não exigem chaves reais de API. ## Adicionando regressões (orientação) -Quando você corrige um problema de provedor/modelo descoberto em live: +Quando você corrige 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 solicitação) -- Se for inerentemente apenas live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in por variáveis de ambiente -- Prefira mirar a menor camada que captura o bug: - - bug de conversão/replay de solicitação do provedor → teste direto de modelos - - bug de sessão/histórico/pipeline de ferramentas do Gateway → teste de fumaça live do Gateway ou teste mock do Gateway seguro para CI -- Proteção de travessia SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um destino amostrado por classe SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`) e então afirma que IDs de exec com segmento de travessia são rejeitados. - - Se você adicionar uma nova família de destinos SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em IDs de destino não classificados para que novas classes não possam ser ignoradas silenciosamente. +- 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 +- 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 +- 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. -## Relacionados +## Relacionado -- [Testes live](/pt-BR/help/testing-live) +- [Testes ao vivo](/pt-BR/help/testing-live) - [Testes de atualizações e plugins](/pt-BR/help/testing-updates-plugins) - [CI](/pt-BR/ci) diff --git a/docs/pt-BR/plugins/google-meet.md b/docs/pt-BR/plugins/google-meet.md index 0927bd30c..4e136ec84 100644 --- a/docs/pt-BR/plugins/google-meet.md +++ b/docs/pt-BR/plugins/google-meet.md @@ -1,44 +1,44 @@ --- read_when: - - Você quer que um agente do OpenClaw participe de uma chamada do Google Meet - - Você quer que um agente OpenClaw crie uma nova chamada do Google Meet - - Você está configurando Chrome, nó do Chrome ou Twilio como transporte do Google Meet -summary: 'Plugin do Google Meet: entre em URLs explícitas do Meet via Chrome ou Twilio com padrões de retorno de fala do agente' + - Você quer que um agente do OpenClaw entre em uma chamada do Google Meet + - Você quer que um agente do OpenClaw crie uma nova chamada do Google Meet + - Você está configurando Chrome, Chrome node ou Twilio como transporte do Google Meet +summary: 'Plugin do Google Meet: entrar em URLs explícitas do Meet via Chrome ou Twilio com padrões de resposta por voz do agente' title: Plugin do Google Meet x-i18n: - generated_at: "2026-05-04T05:54:03Z" + generated_at: "2026-05-04T07:03:04Z" model: gpt-5.5 provider: openai - source_hash: ad2117a42a91f9b494e8c48cc4cfd7439c8bd7b32fd8b97a139fb9b8bbde40a1 + source_hash: 4268ad895bbf83d649b9571c0888c27eb982ad9710dfb408f22f7818cdc5dbcb source_path: plugins/google-meet.md workflow: 16 --- -O suporte a participantes do Google Meet para o OpenClaw é explícito por design: +Suporte a participantes do Google Meet para o OpenClaw — o Plugin é explícito por design: - Ele entra apenas em uma URL explícita `https://meet.google.com/...`. -- Ele pode criar um novo espaço do Meet por meio da API do Google Meet e então entrar na +- Ele pode criar um novo espaço do Meet pela API do Google Meet e então entrar na URL retornada. -- `agent` é o modo padrão de resposta por voz: a transcrição em tempo real escuta, o - agente configurado do OpenClaw responde, e o TTS normal do OpenClaw fala no Meet. -- `bidi` continua disponível como modo alternativo direto do modelo de voz em tempo real. -- Os agentes escolhem o comportamento de entrada com `mode`: use `agent` para escuta/resposta por voz - ao vivo, `bidi` para a alternativa direta de voz em tempo real, ou `transcribe` - para entrar/controlar o navegador sem a ponte de resposta por voz. +- `agent` é o modo padrão de retorno por fala: a transcrição em tempo real escuta, o + agente OpenClaw configurado responde, e o TTS regular do OpenClaw fala no Meet. +- `bidi` continua disponível como modo alternativo de modelo de voz direto em tempo real. +- Os agentes escolhem o comportamento de entrada com `mode`: use `agent` para + escuta/retorno por fala ao vivo, `bidi` para fallback direto de voz em tempo real, ou `transcribe` + para entrar/controlar o navegador sem a ponte de retorno por fala. - A autenticação começa como OAuth pessoal do Google ou um perfil do Chrome já conectado. - Não há anúncio automático de consentimento. - O backend de áudio padrão do Chrome é `BlackHole 2ch`. -- O Chrome pode rodar localmente ou em um host de nó pareado. -- O Twilio aceita um número de discagem mais um PIN ou sequência DTMF opcional; ele - não consegue discar diretamente para uma URL do Meet. +- O Chrome pode ser executado localmente ou em um host de nó pareado. +- A Twilio aceita um número de discagem mais um PIN ou sequência DTMF opcional; ela + não consegue discar uma URL do Meet diretamente. - O comando da CLI é `googlemeet`; `meet` é reservado para fluxos mais amplos de teleconferência de agentes. ## Início rápido Instale as dependências locais de áudio e configure um provedor de transcrição em tempo real -mais o TTS normal do OpenClaw. OpenAI é o provedor padrão de transcrição; -Google Gemini Live também funciona como uma alternativa separada de voz `bidi` com +mais o TTS regular do OpenClaw. A OpenAI é o provedor de transcrição padrão; +o Google Gemini Live também funciona como um fallback de voz `bidi` separado com `realtime.voiceProvider: "google"`: ```bash @@ -48,21 +48,21 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` instala o dispositivo de áudio virtual `BlackHole 2ch`. O instalador -do Homebrew exige uma reinicialização antes que o macOS exponha o dispositivo: +`blackhole-2ch` instala o dispositivo de áudio virtual `BlackHole 2ch`. O instalador do +Homebrew exige uma reinicialização antes que o macOS exponha o dispositivo: ```bash sudo reboot ``` -Após reiniciar, verifique as duas partes: +Após a reinicialização, verifique os dois componentes: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Ative o Plugin: +Habilite o Plugin: ```json5 { @@ -83,32 +83,32 @@ Verifique a configuração: openclaw googlemeet setup ``` -A saída de configuração foi pensada para ser legível por agentes e ciente do modo. Ela relata o perfil do Chrome, -a fixação de nó e, para entradas no Chrome em tempo real, a ponte de áudio -BlackHole/SoX e as verificações atrasadas de introdução em tempo real. Para entradas somente observação, verifique o mesmo -transporte com `--mode transcribe`; esse modo ignora os pré-requisitos de áudio em tempo real +A saída da configuração foi feita para ser legível por agentes e ciente do modo. Ela informa o perfil do Chrome, +a fixação de nó e, para entradas em tempo real pelo Chrome, a ponte de áudio +BlackHole/SoX e as verificações de introdução em tempo real atrasada. Para entradas apenas de observação, verifique o mesmo +transporte com `--mode transcribe`; esse modo ignora pré-requisitos de áudio em tempo real porque não escuta nem fala pela ponte: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -Quando a delegação pelo Twilio está configurada, a configuração também relata se o Plugin -`voice-call`, as credenciais do Twilio e a exposição pública de Webhook estão prontos. -Trate qualquer verificação `ok: false` como um bloqueador para o transporte e modo verificados +Quando a delegação da Twilio está configurada, a configuração também informa se o +Plugin `voice-call`, as credenciais da Twilio e a exposição pública de Webhook estão prontos. +Trate qualquer verificação `ok: false` como um bloqueio para o transporte e modo verificados antes de pedir que um agente entre. Use `openclaw googlemeet setup --json` para scripts ou saída legível por máquina. Use `--transport chrome`, -`--transport chrome-node` ou `--transport twilio` para fazer a pré-verificação de um +`--transport chrome-node` ou `--transport twilio` para fazer uma verificação prévia de um transporte específico antes que um agente tente usá-lo. -Para o Twilio, sempre faça a pré-verificação explícita do transporte quando o transporte padrão +Para a Twilio, sempre faça a verificação prévia do transporte explicitamente quando o transporte padrão for Chrome: ```bash openclaw googlemeet setup --transport twilio ``` -Isso detecta fiação ausente do `voice-call`, credenciais do Twilio ou exposição +Isso detecta integração ausente com `voice-call`, credenciais da Twilio ou exposição de Webhook inacessível antes que o agente tente discar para a reunião. Entre em uma reunião: @@ -117,7 +117,7 @@ Entre em uma reunião: openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -Ou deixe um agente entrar por meio da ferramenta `google_meet`: +Ou deixe um agente entrar pela ferramenta `google_meet`: ```json { @@ -128,12 +128,12 @@ Ou deixe um agente entrar por meio da ferramenta `google_meet`: } ``` -A ferramenta `google_meet` voltada ao agente continua disponível em hosts que não são macOS para -fluxos de artefatos, calendário, configuração, transcrição, Twilio e `chrome-node`. As ações locais -de resposta por voz do Chrome são bloqueadas nesses hosts porque o caminho de áudio do Chrome incluído +A ferramenta `google_meet` voltada para agentes permanece disponível em hosts que não são macOS para +fluxos de artefatos, calendário, configuração, transcrição, Twilio e `chrome-node`. Ações locais +de retorno por fala pelo Chrome são bloqueadas nesses hosts porque o caminho de áudio empacotado do Chrome atualmente depende do `BlackHole 2ch` do macOS. No Linux, use `mode: "transcribe"`, -discagem pelo Twilio ou um host macOS `chrome-node` para participação com resposta por voz -do Chrome. +discagem da Twilio ou um host macOS `chrome-node` para participação com retorno por fala +pelo Chrome. Crie uma nova reunião e entre nela: @@ -141,19 +141,19 @@ Crie uma nova reunião e entre nela: openclaw googlemeet create --transport chrome-node --mode agent ``` -Para salas criadas pela API, use Google Meet `SpaceConfig.accessType` quando quiser -que a política sem solicitação de entrada da sala seja explícita, em vez de herdada dos padrões da -conta Google: +Para salas criadas por API, use `SpaceConfig.accessType` do Google Meet quando quiser +que a política sem solicitação de entrada da sala seja explícita em vez de herdada dos padrões da conta +Google: ```bash openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` permite que qualquer pessoa com a URL do Meet entre sem pedir entrada. `TRUSTED` permite que -usuários confiáveis da organização do host, usuários externos convidados e usuários por discagem -entrem sem pedir entrada. `RESTRICTED` limita a entrada sem solicitação a convidados. Essas -configurações se aplicam apenas ao caminho oficial de criação da API do Google Meet, portanto as -credenciais OAuth precisam estar configuradas. +`OPEN` permite que qualquer pessoa com a URL do Meet entre sem solicitar entrada. `TRUSTED` permite que os +usuários confiáveis da organização anfitriã, usuários externos convidados e usuários por discagem +entrem sem solicitar entrada. `RESTRICTED` limita a entrada sem solicitação a convidados. Essas +configurações só se aplicam ao caminho oficial de criação pela API do Google Meet, portanto as credenciais +OAuth precisam estar configuradas. Se você autenticou o Google Meet antes de esta opção estar disponível, execute novamente `openclaw googlemeet auth login --json` depois de adicionar o escopo @@ -167,16 +167,16 @@ openclaw googlemeet create --no-join `googlemeet create` tem dois caminhos: -- Criação pela API: usada quando as credenciais OAuth do Google Meet estão configuradas. Este é +- Criação por API: usada quando credenciais OAuth do Google Meet estão configuradas. Este é o caminho mais determinístico e não depende do estado da interface do navegador. -- Alternativa pelo navegador: usada quando as credenciais OAuth estão ausentes. O OpenClaw usa o - nó fixado do Chrome, abre `https://meet.google.com/new`, espera o Google +- Fallback pelo navegador: usado quando credenciais OAuth estão ausentes. O OpenClaw usa o + nó Chrome fixado, abre `https://meet.google.com/new`, espera o Google redirecionar para uma URL real com código de reunião e então retorna essa URL. Este caminho exige que o perfil do Chrome do OpenClaw no nó já esteja conectado ao Google. - A automação do navegador lida com o prompt inicial de microfone do próprio Meet; esse prompt + A automação do navegador lida com o próprio prompt inicial de microfone do Meet; esse prompt não é tratado como falha de login do Google. - Os fluxos de entrada e criação também tentam reutilizar uma aba existente do Meet antes de abrir uma - nova. A correspondência ignora strings de consulta inofensivas da URL, como `authuser`, então uma + Fluxos de entrada e criação também tentam reutilizar uma aba existente do Meet antes de abrir uma + nova. A correspondência ignora strings de consulta inofensivas na URL, como `authuser`, então uma nova tentativa do agente deve focar a reunião já aberta em vez de criar uma segunda aba do Chrome. @@ -185,7 +185,7 @@ possam explicar qual caminho foi usado. `create` entra na nova reunião por padr retorna `joined: true` mais a sessão de entrada. Para apenas gerar a URL, use `create --no-join` na CLI ou passe `"join": false` para a ferramenta. -Ou diga a um agente: "Crie um Google Meet, entre nele com o modo de resposta por voz do agente +Ou diga a um agente: "Crie um Google Meet, entre nele com o modo de retorno por fala do agente, e me envie o link." O agente deve chamar `google_meet` com `action: "create"` e então compartilhar o `meetingUri` retornado. @@ -197,53 +197,53 @@ e me envie o link." O agente deve chamar `google_meet` com } ``` -Para uma entrada somente observação/controle do navegador, defina `"mode": "transcribe"`. Isso -não inicia a ponte duplex de voz em tempo real, não exige BlackHole nem SoX, -e não responderá por voz na reunião. Entradas do Chrome nesse modo também evitam +Para uma entrada apenas de observação/controle do navegador, defina `"mode": "transcribe"`. Isso não +inicia a ponte duplex de voz em tempo real, não exige BlackHole nem SoX, +e não responderá por fala na reunião. Entradas pelo Chrome neste modo também evitam a concessão de permissão de microfone/câmera do OpenClaw e evitam o caminho **Usar -microfone** do Meet. Se o Meet mostrar uma tela intermediária de escolha de áudio, a automação tenta -o caminho sem microfone e, caso contrário, relata uma ação manual em vez de abrir +microfone** do Meet. Se o Meet mostrar um intersticial de escolha de áudio, a automação tenta +o caminho sem microfone e, caso contrário, informa uma ação manual em vez de abrir o microfone local. No modo de transcrição, transportes gerenciados do Chrome também instalam um observador de legendas do Meet em melhor esforço. `googlemeet status --json` e -`googlemeet doctor` exibem `captioning`, `captionsEnabledAttempted`, -`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText` +`googlemeet doctor` expõem `captioning`, `captionsEnabledAttempted`, +`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText`, e uma cauda curta de `recentTranscript` para que operadores possam saber se o navegador entrou na chamada e se as legendas do Meet estão produzindo texto. Use `openclaw googlemeet test-listen --transport chrome-node` quando -precisar de uma sondagem sim/não: ele entra no modo de transcrição, espera por movimento recente de legenda ou -transcrição e retorna `listenVerified`, `listenTimedOut`, campos de ação manual -e a saúde mais recente das legendas. +precisar de uma sondagem sim/não: ele entra no modo de transcrição, espera por legenda recente ou +movimento de transcrição, e retorna `listenVerified`, `listenTimedOut`, campos de +ação manual e o status de legenda mais recente. -Durante sessões em tempo real, o status de `google_meet` inclui a saúde do navegador e da ponte -de áudio, como `inCall`, `manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`, carimbos de data/hora da última entrada/saída, -contadores de bytes e estado fechado da ponte. Se um prompt seguro da página do Meet -aparecer, a automação do navegador lida com ele quando consegue. Login, admissão pelo host e -prompts de permissão do navegador/SO são relatados como ação manual com motivo e +Durante sessões em tempo real, o status de `google_meet` inclui a saúde do navegador e da ponte de áudio, +como `inCall`, `manualActionRequired`, `providerConnected`, +`realtimeReady`, `audioInputActive`, `audioOutputActive`, últimos carimbos de data/hora +de entrada/saída, contadores de bytes e estado fechado da ponte. Se um prompt seguro da página do Meet +aparecer, a automação do navegador lida com ele quando consegue. Login, admissão pelo anfitrião e +prompts de permissão do navegador/SO são informados como ação manual com um motivo e mensagem para o agente retransmitir. Sessões gerenciadas do Chrome só emitem a introdução ou -frase de teste depois que a saúde do navegador relata `inCall: true`; caso contrário, o status relata -`speechReady: false` e a tentativa de fala é bloqueada em vez de fingir que o -agente falou na reunião. +frase de teste depois que a saúde do navegador informa `inCall: true`; caso contrário, o status informa +`speechReady: false` e a tentativa de fala é bloqueada em vez de fingir que +o agente falou na reunião. -Entradas locais do Chrome usam o perfil de navegador conectado do OpenClaw. O modo em tempo real +Entradas locais pelo Chrome usam o perfil de navegador do OpenClaw conectado. O modo em tempo real exige `BlackHole 2ch` para o caminho de microfone/alto-falante usado pelo OpenClaw. Para áudio duplex limpo, use dispositivos virtuais separados ou um grafo no estilo Loopback; um único dispositivo BlackHole é suficiente para um primeiro teste rápido, mas pode gerar eco. ### Gateway local + Chrome no Parallels -Você **não** precisa de um Gateway completo do OpenClaw nem de uma chave de API de modelo dentro de uma VM macOS -apenas para fazer a VM ser dona do Chrome. Rode o Gateway e o agente localmente e então rode um -host de nó na VM. Ative o Plugin incluído na VM uma vez para que o nó +Você **não** precisa de um Gateway OpenClaw completo ou chave de API de modelo dentro de uma VM macOS +apenas para fazer a VM controlar o Chrome. Execute o Gateway e o agente localmente e, em seguida, execute um +host de nó na VM. Habilite o Plugin empacotado na VM uma vez para que o nó anuncie o comando do Chrome: O que roda onde: -- Host do Gateway: OpenClaw Gateway, workspace do agente, chaves de modelo/API, provedor em tempo real +- Host do Gateway: Gateway OpenClaw, workspace do agente, chaves de modelo/API, provedor em tempo real e a configuração do Plugin do Google Meet. -- VM macOS do Parallels: CLI/host de nó do OpenClaw, Google Chrome, SoX, BlackHole 2ch +- VM macOS no Parallels: CLI/host de nó do OpenClaw, Google Chrome, SoX, BlackHole 2ch, e um perfil do Chrome conectado ao Google. -- Não é necessário na VM: serviço Gateway, configuração de agente, chave OpenAI/GPT ou configuração +- Não necessário na VM: serviço Gateway, configuração de agente, chave OpenAI/GPT ou configuração de provedor de modelo. Instale as dependências da VM: @@ -252,20 +252,20 @@ Instale as dependências da VM: brew install blackhole-2ch sox ``` -Reinicie a VM após instalar o BlackHole para que o macOS exponha `BlackHole 2ch`: +Reinicie a VM depois de instalar o BlackHole para que o macOS exponha `BlackHole 2ch`: ```bash sudo reboot ``` -Após reiniciar, verifique se a VM consegue ver o dispositivo de áudio e os comandos SoX: +Após a reinicialização, verifique se a VM consegue ver o dispositivo de áudio e os comandos do SoX: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Instale ou atualize o OpenClaw na VM e então ative o Plugin incluído nela: +Instale ou atualize o OpenClaw na VM e então habilite o Plugin empacotado nela: ```bash openclaw plugins enable google-meet @@ -294,10 +294,10 @@ openclaw node restart ``` `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` é ambiente de processo, não uma configuração -de `openclaw.json`. `openclaw node install` a armazena no ambiente do LaunchAgent +`openclaw.json`. `openclaw node install` a armazena no ambiente do LaunchAgent quando ela está presente no comando de instalação. -Aprove o nó pelo host do Gateway: +Aprove o nó a partir do host do Gateway: ```bash openclaw devices list @@ -305,7 +305,7 @@ openclaw devices approve ``` Confirme que o Gateway vê o nó e que ele anuncia tanto `googlemeet.chrome` -quanto a capacidade do navegador/`browser.proxy`: +quanto a capacidade de navegador/`browser.proxy`: ```bash openclaw nodes status @@ -341,13 +341,13 @@ Roteie o Meet por esse nó no host do Gateway: } ``` -Agora entre normalmente pelo host do Gateway: +Agora entre normalmente a partir do host do Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -ou peça que o agente use a ferramenta `google_meet` com `transport: "chrome-node"`. +ou peça ao agente para usar a ferramenta `google_meet` com `transport: "chrome-node"`. Para um teste rápido de um comando que cria ou reutiliza uma sessão, fala uma frase conhecida e imprime a saúde da sessão: @@ -357,47 +357,47 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` Durante a entrada em tempo real, a automação de navegador do OpenClaw preenche o nome do convidado, clica em -Join/Ask to join e aceita a opção inicial do Meet "Use microphone" quando esse +Entrar/Pedir para entrar e aceita a opção "Usar microfone" da primeira execução do Meet quando esse prompt aparece. Durante a entrada apenas para observação ou a criação de reunião somente pelo navegador, ela -continua além do mesmo prompt sem microfone quando essa opção está disponível. +continua após o mesmo prompt sem microfone quando essa opção está disponível. Se o perfil do navegador não estiver conectado, o Meet estiver aguardando admissão pelo anfitrião, o Chrome precisar de permissão de microfone/câmera para uma entrada em tempo real, ou o Meet estiver travado em um prompt que a automação não conseguiu resolver, o resultado de join/test-speech informa `manualActionRequired: true` com `manualActionReason` e -`manualActionMessage`. Os agentes devem parar de tentar novamente a entrada, relatar essa mensagem exata -mais o `browserUrl`/`browserTitle` atual, e tentar novamente somente depois que a -ação manual no navegador for concluída. +`manualActionMessage`. Os agentes devem parar de tentar entrar novamente, relatar essa mensagem exata +mais o `browserUrl`/`browserTitle` atual, e tentar novamente somente depois que a ação manual +no navegador estiver concluída. Se `chromeNode.node` for omitido, o OpenClaw seleciona automaticamente somente quando exatamente um -Node conectado anuncia tanto `googlemeet.chrome` quanto controle de navegador. Se -vários Nodes compatíveis estiverem conectados, defina `chromeNode.node` como o id do Node, +nó conectado anuncia tanto `googlemeet.chrome` quanto controle de navegador. Se +vários nós capazes estiverem conectados, defina `chromeNode.node` como o id do nó, nome de exibição ou IP remoto. -Verificações comuns de falhas: +Verificações comuns de falha: -- `Configured Google Meet node ... is not usable: offline`: o Node fixado é - conhecido pelo Gateway, mas está indisponível. Os agentes devem tratar esse Node como - estado de diagnóstico, não como um host Chrome utilizável, e relatar o bloqueio de configuração - em vez de alternar para outro transporte, a menos que o usuário tenha pedido isso. +- `Configured Google Meet node ... is not usable: offline`: o nó fixado é + conhecido pelo Gateway, mas está indisponível. Os agentes devem tratar esse nó como + estado de diagnóstico, não como um host Chrome utilizável, e relatar o bloqueador de configuração + em vez de recorrer a outro transporte, a menos que o usuário tenha pedido isso. - `No connected Google Meet-capable node`: inicie `openclaw node run` na VM, - aprove o pareamento e garanta que `openclaw plugins enable google-meet` e - `openclaw plugins enable browser` tenham sido executados na VM. Confirme também que o - host do Gateway permite ambos os comandos do Node com + aprove o pareamento e confirme que `openclaw plugins enable google-meet` e + `openclaw plugins enable browser` foram executados na VM. Confirme também que o + host Gateway permite ambos os comandos de nó com `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. - `BlackHole 2ch audio device not found`: instale `blackhole-2ch` no host que está sendo verificado e reinicie antes de usar áudio local do Chrome. - `BlackHole 2ch audio device not found on the node`: instale `blackhole-2ch` na VM e reinicie a VM. - O Chrome abre, mas não consegue entrar: faça login no perfil do navegador dentro da VM, ou - mantenha `chrome.guestName` definido para entrada como convidado. A entrada automática como convidado usa a - automação de navegador do OpenClaw por meio do proxy de navegador do Node; garanta que a configuração do navegador - do Node aponte para o perfil desejado, por exemplo - `browser.defaultProfile: "user"` ou um perfil nomeado de sessão existente. -- Abas duplicadas do Meet: deixe `chrome.reuseExistingTab: true` habilitado. O OpenClaw - ativa uma aba existente para a mesma URL do Meet antes de abrir uma nova, e a - criação de reunião pelo navegador reutiliza uma aba em andamento de `https://meet.google.com/new` - ou de prompt de conta Google antes de abrir outra. -- Sem áudio: no Meet, direcione o áudio do microfone/alto-falante pelo caminho de dispositivo de áudio virtual + mantenha `chrome.guestName` definido para entrada como convidado. A entrada automática como convidado usa a automação de navegador do OpenClaw + por meio do proxy de navegador do nó; confirme que a configuração de navegador do nó + aponta para o perfil que você quer, por exemplo + `browser.defaultProfile: "user"` ou um perfil de sessão existente nomeado. +- Abas duplicadas do Meet: mantenha `chrome.reuseExistingTab: true` habilitado. O OpenClaw + ativa uma aba existente para a mesma URL do Meet antes de abrir uma nova, e + a criação de reunião pelo navegador reutiliza uma aba em andamento de `https://meet.google.com/new` + ou de prompt de conta do Google antes de abrir outra. +- Sem áudio: no Meet, roteie o áudio de microfone/alto-falante pelo caminho do dispositivo de áudio virtual usado pelo OpenClaw; use dispositivos virtuais separados ou roteamento no estilo Loopback para áudio duplex limpo. @@ -405,27 +405,27 @@ Verificações comuns de falhas: O padrão de retorno de fala do Chrome usa duas ferramentas externas: -- `sox`: utilitário de áudio de linha de comando. O Plugin usa comandos CoreAudio - explícitos de dispositivo para a ponte de áudio PCM16 padrão de 24 kHz. -- `blackhole-2ch`: driver de áudio virtual do macOS. Ele cria o dispositivo de áudio - `BlackHole 2ch` pelo qual o Chrome/Meet pode rotear. +- `sox`: utilitário de áudio de linha de comando. O Plugin usa comandos explícitos de dispositivo CoreAudio + para a ponte de áudio PCM16 padrão de 24 kHz. +- `blackhole-2ch`: driver de áudio virtual do macOS. Ele cria o dispositivo de áudio `BlackHole 2ch` + pelo qual Chrome/Meet podem rotear. -O OpenClaw não empacota nem redistribui nenhum dos dois pacotes. A documentação pede que os usuários -os instalem como dependências do host via Homebrew. O SoX é licenciado como -`LGPL-2.0-only AND GPL-2.0-only`; o BlackHole é GPL-3.0. Se você criar um -instalador ou appliance que empacote o BlackHole com o OpenClaw, revise os +O OpenClaw não empacota nem redistribui nenhum dos pacotes. A documentação pede que os usuários +os instalem como dependências de host pelo Homebrew. SoX é licenciado como +`LGPL-2.0-only AND GPL-2.0-only`; BlackHole é GPL-3.0. Se você criar um +instalador ou appliance que empacota o BlackHole com o OpenClaw, revise os termos de licenciamento upstream do BlackHole ou obtenha uma licença separada da Existential Audio. ## Transportes ### Chrome -O transporte Chrome abre a URL do Meet por meio do controle de navegador do OpenClaw e entra +O transporte Chrome abre a URL do Meet pelo controle de navegador do OpenClaw e entra como o perfil de navegador do OpenClaw conectado. No macOS, o Plugin verifica a presença de `BlackHole 2ch` antes da inicialização. Se configurado, ele também executa um comando de integridade da ponte de áudio e um comando de inicialização antes de abrir o Chrome. Use `chrome` quando -o Chrome/áudio estiverem no host do Gateway; use `chrome-node` quando o Chrome/áudio estiverem -em um Node pareado, como uma VM macOS do Parallels. Para Chrome local, escolha o +Chrome/áudio estiverem no host Gateway; use `chrome-node` quando Chrome/áudio estiverem +em um nó pareado, como uma VM Parallels macOS. Para Chrome local, escolha o perfil com `browser.defaultProfile`; `chrome.browserProfile` é passado para hosts `chrome-node`. @@ -434,7 +434,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Direcione o áudio do microfone e alto-falante do Chrome pela ponte de áudio local do OpenClaw. +Roteie o áudio de microfone e alto-falante do Chrome pela ponte de áudio local do OpenClaw. Se `BlackHole 2ch` não estiver instalado, a entrada falha com um erro de configuração em vez de entrar silenciosamente sem um caminho de áudio. @@ -443,11 +443,11 @@ em vez de entrar silenciosamente sem um caminho de áudio. O transporte Twilio é um plano de discagem estrito delegado ao Plugin Voice Call. Ele não analisa páginas do Meet em busca de números de telefone. -Use isso quando a participação pelo Chrome não estiver disponível ou quando você quiser uma alternativa de discagem -por telefone. O Google Meet deve expor um número de discagem por telefone e PIN para a -reunião; o OpenClaw não os descobre a partir da página do Meet. +Use isso quando a participação pelo Chrome não estiver disponível ou quando você quiser uma alternativa de discagem telefônica. +O Google Meet deve expor um número de discagem telefônica e PIN para a +reunião; o OpenClaw não descobre esses dados a partir da página do Meet. -Habilite o Plugin Voice Call no host do Gateway, não no Node do Chrome: +Habilite o Plugin Voice Call no host Gateway, não no nó Chrome: ```json5 { @@ -488,7 +488,7 @@ Habilite o Plugin Voice Call no host do Gateway, não no Node do Chrome: } ``` -Forneça credenciais da Twilio por ambiente ou configuração. Variáveis de ambiente mantêm +Forneça credenciais da Twilio por ambiente ou configuração. O ambiente mantém segredos fora de `openclaw.json`: ```bash @@ -498,13 +498,13 @@ export TWILIO_FROM_NUMBER=+15550001234 export GEMINI_API_KEY=... ``` -Use `realtime.provider: "openai"` com o Plugin provedor OpenAI e +Use `realtime.provider: "openai"` com o Plugin do provedor OpenAI e `OPENAI_API_KEY` se esse for seu provedor de voz em tempo real. Reinicie ou recarregue o Gateway depois de habilitar `voice-call`; alterações na configuração do Plugin -não aparecem em um processo do Gateway já em execução até que ele recarregue. +não aparecem em um processo Gateway já em execução até que ele seja recarregado. -Então verifique: +Em seguida, verifique: ```bash openclaw config validate @@ -512,8 +512,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Quando a delegação Twilio estiver conectada, `googlemeet setup` inclui verificações bem-sucedidas de -`twilio-voice-call-plugin`, `twilio-voice-call-credentials` e +Quando a delegação Twilio estiver conectada, `googlemeet setup` inclui verificações bem-sucedidas +de `twilio-voice-call-plugin`, `twilio-voice-call-credentials` e `twilio-voice-call-webhook`. ```bash @@ -538,15 +538,15 @@ OAuth é opcional para criar um link do Meet porque `googlemeet create` pode rec à automação de navegador. Configure OAuth quando você quiser criação pela API oficial, resolução de espaços ou verificações de pré-verificação da Meet Media API. -O acesso à API do Google Meet usa OAuth de usuário: crie um cliente OAuth no Google Cloud, -solicite os escopos necessários, autorize uma conta Google e então armazene o -token de atualização resultante na configuração do Plugin Google Meet ou forneça as variáveis -de ambiente `OPENCLAW_GOOGLE_MEET_*`. +O acesso à Google Meet API usa OAuth de usuário: crie um cliente OAuth do Google Cloud, +solicite os escopos necessários, autorize uma conta Google e, em seguida, armazene o +token de atualização resultante na configuração do Plugin Google Meet ou forneça as +variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*`. OAuth não substitui o caminho de entrada pelo Chrome. Os transportes Chrome e Chrome-node -ainda entram por meio de um perfil do Chrome conectado, BlackHole/SoX e um Node conectado -quando você usa participação pelo navegador. OAuth serve apenas para o caminho oficial da API do Google -Meet: criar espaços de reunião, resolver espaços e executar verificações de pré-verificação da Meet Media API. +ainda entram por um perfil Chrome conectado, BlackHole/SoX e um nó conectado +quando você usa participação pelo navegador. OAuth serve apenas para o caminho oficial da Google +Meet API: criar espaços de reunião, resolver espaços e executar verificações de pré-verificação da Meet Media API. ### Criar credenciais do Google @@ -555,8 +555,8 @@ No Google Cloud Console: 1. Crie ou selecione um projeto do Google Cloud. 2. Habilite a **Google Meet REST API** para esse projeto. 3. Configure a tela de consentimento OAuth. - - **Internal** é o mais simples para uma organização Google Workspace. - - **External** funciona para configurações pessoais/de teste; enquanto o app estiver em Testing, + - **Interno** é o mais simples para uma organização Google Workspace. + - **Externo** funciona para configurações pessoais/de teste; enquanto o app estiver em Testes, adicione cada conta Google que autorizará o app como usuário de teste. 4. Adicione os escopos que o OpenClaw solicita: - `https://www.googleapis.com/auth/meetings.space.created` @@ -564,7 +564,7 @@ No Google Cloud Console: - `https://www.googleapis.com/auth/meetings.space.settings` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. Crie um ID de cliente OAuth. - - Tipo de aplicativo: **Web application**. + - Tipo de aplicativo: **Aplicativo web**. - URI de redirecionamento autorizado: ```text @@ -576,15 +576,15 @@ No Google Cloud Console: `meetings.space.created` é exigido por `spaces.create` do Google Meet. `meetings.space.readonly` permite que o OpenClaw resolva URLs/códigos do Meet para espaços. `meetings.space.settings` permite que o OpenClaw passe configurações de `SpaceConfig`, como -`accessType`, durante a criação de sala pela API. -`meetings.conference.media.readonly` é para pré-verificação da Meet Media API e trabalho -de mídia; o Google pode exigir inscrição no Developer Preview para uso real da Media API. +`accessType`, durante a criação de salas pela API. +`meetings.conference.media.readonly` é para pré-verificação da Meet Media API e trabalho de mídia; +o Google pode exigir inscrição no Developer Preview para uso real da Media API. Se você só precisa de entradas pelo Chrome baseadas em navegador, ignore OAuth completamente. ### Emitir o token de atualização -Configure `oauth.clientId` e, opcionalmente, `oauth.clientSecret`, ou passe-os como -variáveis de ambiente, então execute: +Configure `oauth.clientId` e opcionalmente `oauth.clientSecret`, ou passe-os como +variáveis de ambiente, depois execute: ```bash openclaw googlemeet auth login --json @@ -602,7 +602,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -Use o modo manual quando o navegador não puder acessar o callback local: +Use o modo manual quando o navegador não conseguir acessar o callback local: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -650,20 +650,20 @@ Prefira variáveis de ambiente quando você não quiser o token de atualização Se valores de configuração e de ambiente estiverem presentes, o Plugin resolve primeiro a configuração e depois usa o ambiente como fallback. -O consentimento OAuth inclui criação de espaço do Meet, acesso de leitura a espaço do Meet e acesso -de leitura à mídia de conferência do Meet. Se você se autenticou antes de o suporte à criação -de reunião existir, execute novamente `openclaw googlemeet auth login --json` para que o token de atualização +O consentimento OAuth inclui criação de espaço do Meet, acesso de leitura a espaço do Meet e acesso de leitura +a mídia de conferência do Meet. Se você autenticou antes de existir suporte à criação de reuniões, +execute novamente `openclaw googlemeet auth login --json` para que o token de atualização tenha o escopo `meetings.space.created`. ### Verificar OAuth com doctor -Execute o doctor OAuth quando quiser uma verificação de integridade rápida e sem segredos: +Execute o doctor de OAuth quando quiser uma verificação de integridade rápida e sem segredos: ```bash openclaw googlemeet doctor --oauth --json ``` -Isso não carrega o runtime do Chrome nem exige um Node Chrome conectado. Ele +Isso não carrega o runtime do Chrome nem exige um nó Chrome conectado. Ele verifica se a configuração OAuth existe e se o token de atualização consegue emitir um token de acesso. O relatório JSON inclui apenas campos de status como `ok`, `configured`, `tokenSource`, `expiresAt` e mensagens de verificação; ele não imprime o token de acesso, @@ -671,14 +671,14 @@ token de atualização ou segredo do cliente. Resultados comuns: -| Verificação | Significado | +| Verificação | Significado | | -------------------- | --------------------------------------------------------------------------------------- | | `oauth-config` | `oauth.clientId` mais `oauth.refreshToken`, ou um token de acesso em cache, está presente. | | `oauth-token` | O token de acesso em cache ainda é válido, ou o token de atualização emitiu um novo token de acesso. | -| `meet-spaces-get` | A verificação opcional `--meeting` resolveu um espaço do Meet existente. | -| `meet-spaces-create` | A verificação opcional `--create-space` criou um novo espaço do Meet. | +| `meet-spaces-get` | A verificação opcional `--meeting` resolveu um espaço Meet existente. | +| `meet-spaces-create` | A verificação opcional `--create-space` criou um novo espaço Meet. | -Para comprovar também a habilitação da API do Google Meet e o escopo `spaces.create`, execute a +Para comprovar também a ativação da API do Google Meet e o escopo `spaces.create`, execute a verificação de criação com efeito colateral: ```bash @@ -686,8 +686,8 @@ openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` cria uma URL descartável do Meet. Use isso quando precisar confirmar -que o projeto do Google Cloud tem a API do Meet habilitada e que a conta autorizada +`--create-space` cria uma URL Meet descartável. Use isso quando precisar confirmar +que o projeto do Google Cloud tem a API Meet ativada e que a conta autorizada tem o escopo `meetings.space.created`. Para comprovar acesso de leitura a um espaço de reunião existente: @@ -697,15 +697,16 @@ openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hi openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` e `resolve-space` comprovam acesso de leitura a um espaço existente -que a conta Google autorizada pode acessar. Um `403` dessas verificações -geralmente significa que a API REST do Google Meet está desabilitada, que o token de atualização -consentido não tem o escopo necessário ou que a conta Google não pode acessar esse espaço do Meet. Um erro de token de atualização significa executar novamente `openclaw googlemeet auth login +`doctor --oauth --meeting` e `resolve-space` comprovam acesso de leitura a um +espaço existente que a conta Google autorizada pode acessar. Um `403` nessas verificações +geralmente significa que a API REST do Google Meet está desativada, o token de atualização consentido +não tem o escopo necessário, ou a conta Google não pode acessar esse espaço Meet. +Um erro de token de atualização significa executar novamente `openclaw googlemeet auth login --json` e armazenar o novo bloco `oauth`. -Nenhuma credencial OAuth é necessária para o fallback do navegador. Nesse modo, a autenticação do Google -vem do perfil do Chrome conectado no Node selecionado, não da -configuração do OpenClaw. +Nenhuma credencial OAuth é necessária para o fallback do navegador. Nesse modo, a autenticação Google +vem do perfil do Chrome conectado no Node selecionado, não da configuração do +OpenClaw. Estas variáveis de ambiente são aceitas como fallbacks: @@ -718,19 +719,19 @@ Estas variáveis de ambiente são aceitas como fallbacks: - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` ou `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` ou `GOOGLE_MEET_PREVIEW_ACK` -Resolva uma URL do Meet, código ou `spaces/{id}` por meio de `spaces.get`: +Resolva uma URL Meet, código ou `spaces/{id}` por meio de `spaces.get`: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Execute a pré-verificação antes do trabalho com mídia: +Execute a pré-verificação antes do trabalho de mídia: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Liste artefatos de reunião e presença depois que o Meet tiver criado registros de conferência: +Liste artefatos da reunião e presença depois que o Meet criar registros de conferência: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -739,10 +740,10 @@ openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --outp ``` Com `--meeting`, `artifacts` e `attendance` usam o registro de conferência mais recente -por padrão. Passe `--all-conference-records` quando quiser todos os registros retidos +por padrão. Passe `--all-conference-records` quando quiser todos os registros mantidos para essa reunião. -A consulta ao Calendar pode resolver a URL da reunião no Google Calendar antes de ler +A busca no Calendar pode resolver a URL da reunião no Google Calendar antes de ler artefatos do Meet: ```bash @@ -752,14 +753,14 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` pesquisa o calendário `primary` de hoje por um evento do Calendar com um -link do Google Meet. Use `--event ` para pesquisar texto de evento correspondente, e -`--calendar ` para um calendário não primário. A consulta ao Calendar requer um novo +`--today` pesquisa no calendário `primary` de hoje um evento do Calendar com um +link do Google Meet. Use `--event ` para pesquisar texto correspondente do evento, e +`--calendar ` para um calendário não primário. A busca no Calendar exige um novo login OAuth que inclua o escopo somente leitura de eventos do Calendar. -`calendar-events` pré-visualiza os eventos do Meet correspondentes e marca o evento que +`calendar-events` pré-visualiza os eventos Meet correspondentes e marca o evento que `latest`, `artifacts`, `attendance` ou `export` escolherá. -Se você já souber o id do registro de conferência, enderece-o diretamente: +Se você já sabe o id do registro de conferência, enderece-o diretamente: ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -774,9 +775,9 @@ sala após a chamada: openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -Isso chama `spaces.endActiveConference` do Google Meet e requer OAuth com o +Isso chama `spaces.endActiveConference` do Google Meet e exige OAuth com o escopo `meetings.space.created` para um espaço que a conta autorizada pode gerenciar. -O OpenClaw aceita uma URL do Meet, código de reunião ou entrada `spaces/{id}` e a resolve +O OpenClaw aceita uma URL Meet, código de reunião ou entrada `spaces/{id}` e a resolve para o recurso de espaço da API antes de encerrar a conferência ativa. Isso é separado de `googlemeet leave`: `leave` interrompe a participação local/de sessão do OpenClaw, enquanto `end-active-conference` pede ao Google Meet para encerrar a conferência ativa @@ -799,29 +800,29 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ `artifacts` retorna metadados do registro de conferência mais metadados de recursos de participante, gravação, transcrição, entrada de transcrição estruturada e notas inteligentes quando -o Google os expõe para a reunião. Use `--no-transcript-entries` para ignorar -a consulta de entradas em reuniões grandes. `attendance` expande participantes em +o Google os expõe para a reunião. Use `--no-transcript-entries` para pular +a busca de entradas em reuniões grandes. `attendance` expande participantes em linhas de sessão de participante com horários de primeira/última visualização, duração total da sessão, -sinalizadores de atraso/saída antecipada e recursos de participante duplicados mesclados por usuário conectado -ou nome de exibição. Passe `--no-merge-duplicates` para manter recursos brutos de participante -separados, `--late-after-minutes` para ajustar a detecção de atraso e +sinalizadores de atraso/saída antecipada, e recursos de participante duplicados mesclados por usuário +conectado ou nome de exibição. Passe `--no-merge-duplicates` para manter recursos brutos de participante +separados, `--late-after-minutes` para ajustar a detecção de atraso, e `--early-before-minutes` para ajustar a detecção de saída antecipada. `export` grava uma pasta contendo `summary.md`, `attendance.csv`, `transcript.md`, `artifacts.json`, `attendance.json` e `manifest.json`. `manifest.json` registra a entrada escolhida, opções de exportação, registros de conferência, -arquivos de saída, contagens, origem do token, evento do Calendar quando um foi usado e quaisquer +arquivos de saída, contagens, origem do token, evento do Calendar quando algum foi usado, e quaisquer avisos de recuperação parcial. Passe `--zip` para também gravar um arquivo portátil ao lado -da pasta. Passe `--include-doc-bodies` para exportar texto de Google Docs de transcrição vinculada e -notas inteligentes por meio de `files.export` do Google Drive; isso requer um -novo login OAuth que inclua o escopo somente leitura do Drive Meet. Sem -`--include-doc-bodies`, as exportações incluem apenas metadados do Meet e entradas de transcrição -estruturadas. Se o Google retornar uma falha parcial de artefato, como um erro de listagem de -notas inteligentes, entrada de transcrição ou corpo de documento do Drive, o resumo e o -manifesto mantêm o aviso em vez de falhar a exportação inteira. -Use `--dry-run` para buscar os mesmos dados de artefato/presença e imprimir o +da pasta. Passe `--include-doc-bodies` para exportar o texto de Google Docs vinculados de transcrição e +notas inteligentes por meio de `files.export` do Google Drive; isso exige um +novo login OAuth que inclua o escopo somente leitura Drive Meet. Sem +`--include-doc-bodies`, as exportações incluem apenas metadados do Meet e entradas estruturadas de transcrição. +Se o Google retornar uma falha parcial de artefato, como uma listagem de notas inteligentes, +entrada de transcrição ou erro de corpo de documento do Drive, o resumo e o +manifesto mantêm o aviso em vez de falhar toda a exportação. +Use `--dry-run` para buscar os mesmos dados de artefatos/presença e imprimir o JSON do manifesto sem criar a pasta ou o ZIP. Isso é útil antes de gravar -uma exportação grande ou quando um agente só precisa de contagens, registros selecionados e +uma exportação grande ou quando um agente precisa apenas de contagens, registros selecionados e avisos. Agentes também podem criar o mesmo pacote por meio da ferramenta `google_meet`: @@ -836,7 +837,7 @@ Agentes também podem criar o mesmo pacote por meio da ferramenta `google_meet`: } ``` -Defina `"dryRun": true` para retornar apenas o manifesto de exportação e ignorar gravações de arquivos. +Defina `"dryRun": true` para retornar apenas o manifesto de exportação e pular gravações de arquivos. Agentes também podem criar uma sala apoiada por API com uma política de acesso explícita: @@ -849,7 +850,7 @@ Agentes também podem criar uma sala apoiada por API com uma política de acesso } ``` -E eles podem encerrar a conferência ativa de uma sala conhecida: +E podem encerrar a conferência ativa de uma sala conhecida: ```json { @@ -858,7 +859,7 @@ E eles podem encerrar a conferência ativa de uma sala conhecida: } ``` -Para validação priorizando escuta, agentes devem usar `test_listen` antes de afirmar que a +Para validação ouvindo primeiro, os agentes devem usar `test_listen` antes de afirmar que a reunião é útil: ```json @@ -870,7 +871,7 @@ reunião é útil: } ``` -Execute o smoke live protegido contra uma reunião real retida: +Execute o smoke live protegido contra uma reunião real mantida: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -878,7 +879,7 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Execute a sondagem live no navegador priorizando escuta contra uma reunião em que alguém vai +Execute a sondagem live do navegador ouvindo primeiro contra uma reunião em que alguém irá falar com legendas do Meet disponíveis: ```bash @@ -886,12 +887,13 @@ openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -Ambiente do smoke live: +Ambiente de smoke live: -- `OPENCLAW_LIVE_TEST=1` habilita testes live protegidos. -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` aponta para uma URL do Meet, código ou - `spaces/{id}` retido. -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` ou `GOOGLE_MEET_CLIENT_ID` fornece o id do cliente OAuth. +- `OPENCLAW_LIVE_TEST=1` ativa testes live protegidos. +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` aponta para uma URL Meet, código ou + `spaces/{id}` mantido. +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` ou `GOOGLE_MEET_CLIENT_ID` fornece o id do cliente + OAuth. - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` ou `GOOGLE_MEET_REFRESH_TOKEN` fornece o token de atualização. - Opcional: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`, @@ -899,24 +901,24 @@ Ambiente do smoke live: `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` usam os mesmos nomes de fallback sem o prefixo `OPENCLAW_`. -O smoke live base de artefato/presença precisa de +O smoke live base de artefatos/presença precisa de `https://www.googleapis.com/auth/meetings.space.readonly` e -`https://www.googleapis.com/auth/meetings.conference.media.readonly`. A consulta ao Calendar +`https://www.googleapis.com/auth/meetings.conference.media.readonly`. A busca no Calendar precisa de `https://www.googleapis.com/auth/calendar.events.readonly`. A exportação de corpo de documento do Drive precisa de `https://www.googleapis.com/auth/drive.meet.readonly`. -Crie um novo espaço do Meet: +Crie um novo espaço Meet: ```bash openclaw googlemeet create ``` -O comando imprime o novo `meeting uri`, a origem e a sessão de entrada. Com credenciais OAuth -ele usa a API oficial do Google Meet. Sem credenciais OAuth, ele -usa o perfil de navegador conectado do Node do Chrome fixado como fallback. Agentes podem -usar a ferramenta `google_meet` com `action: "create"` para criar e entrar em uma -etapa. Para criação apenas de URL, passe `"join": false`. +O comando imprime o novo `meeting uri`, origem e sessão de entrada. Com credenciais +OAuth, ele usa a API oficial do Google Meet. Sem credenciais OAuth, ele +usa como fallback o perfil de navegador conectado do Node Chrome fixado. Agentes podem +usar a ferramenta `google_meet` com `action: "create"` para criar e entrar em uma única +etapa. Para criação somente de URL, passe `"join": false`. Exemplo de saída JSON do fallback do navegador: @@ -938,8 +940,8 @@ Exemplo de saída JSON do fallback do navegador: } ``` -Se o fallback do navegador encontrar login do Google ou um bloqueio de permissão do Meet antes de -conseguir criar a URL, o método do Gateway retorna uma resposta com falha e a +Se o fallback do navegador encontrar login do Google ou um bloqueio de permissão do Meet antes que ele +consiga criar a URL, o método Gateway retorna uma resposta com falha e a ferramenta `google_meet` retorna detalhes estruturados em vez de uma string simples: ```json @@ -960,7 +962,7 @@ ferramenta `google_meet` retorna detalhes estruturados em vez de uma string simp Quando um agente vê `manualActionRequired: true`, ele deve relatar a `manualActionMessage` mais o contexto de Node/aba do navegador e parar de abrir novas -abas do Meet até que o operador conclua a etapa no navegador. +abas Meet até que o operador conclua a etapa no navegador. Exemplo de saída JSON da criação por API: @@ -983,25 +985,23 @@ Exemplo de saída JSON da criação por API: } ``` -Criar uma Meet entra por padrão. O transporte Chrome ou Chrome-node ainda +Criar um Meet entra na reunião por padrão. O transporte Chrome ou Chrome-node ainda precisa de um perfil do Google Chrome conectado para entrar pelo navegador. Se o -perfil estiver desconectado, o OpenClaw relata `manualActionRequired: true` ou -um erro de fallback do navegador e pede ao operador para concluir o login do -Google antes de tentar novamente. +perfil estiver desconectado, o OpenClaw relata `manualActionRequired: true` ou um +erro de fallback do navegador e pede que o operador conclua o login do Google antes +de tentar novamente. -Defina `preview.enrollmentAcknowledged: true` somente após confirmar que seu -projeto Cloud, principal OAuth e participantes da reunião estão inscritos no -Programa de Preview para Desenvolvedores do Google Workspace para APIs de mídia -do Meet. +Defina `preview.enrollmentAcknowledged: true` somente depois de confirmar que seu +projeto do Cloud, principal OAuth e participantes da reunião estão inscritos no +Google Workspace Developer Preview Program para APIs de mídia do Meet. ## Configuração -O caminho comum do agente Chrome precisa apenas do Plugin habilitado, BlackHole, -SoX, uma chave de provedor de transcrição em tempo real e um provedor de TTS do -OpenClaw configurado. OpenAI é o provedor de transcrição padrão; defina -`realtime.voiceProvider` como `"google"` e `realtime.model` para usar Google -Gemini Live no modo `bidi` sem alterar o provedor de transcrição padrão do modo -de agente: +O caminho comum do agente Chrome precisa apenas do Plugin habilitado, BlackHole, SoX, uma +chave de provedor de transcrição em tempo real e um provedor de TTS do OpenClaw configurado. +OpenAI é o provedor de transcrição padrão; defina `realtime.voiceProvider` como +`"google"` e `realtime.model` para usar o Google Gemini Live no modo `bidi` +sem alterar o provedor de transcrição padrão do modo agente: ```bash brew install blackhole-2ch sox @@ -1029,61 +1029,58 @@ Padrões: - `defaultTransport: "chrome"` - `defaultMode: "agent"` (`"realtime"` é aceito apenas como um alias legado de - compatibilidade para `"agent"`; novas chamadas de ferramentas devem usar - `"agent"`) -- `chromeNode.node`: id/nome/IP opcional do Node para `chrome-node` + compatibilidade para `"agent"`; novas chamadas de ferramenta devem dizer `"agent"`) +- `chromeNode.node`: id/nome/IP opcional do nó para `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: nome usado na tela de convidado - desconectado do Meet -- `chrome.autoJoin: true`: preenchimento de nome de convidado e clique em Join - Now por melhor esforço via automação de navegador do OpenClaw em `chrome-node` +- `chrome.guestName: "OpenClaw Agent"`: nome usado na tela de convidado desconectado + do Meet +- `chrome.autoJoin: true`: preenchimento de nome de convidado e clique em Entrar agora + por automação de navegador do OpenClaw em `chrome-node`, com melhor esforço - `chrome.reuseExistingTab: true`: ativa uma aba existente do Meet em vez de abrir duplicatas -- `chrome.waitForInCallMs: 20000`: espera a aba do Meet relatar que está na - chamada antes de acionar a introdução de resposta por voz +- `chrome.waitForInCallMs: 20000`: aguarda a aba do Meet relatar que está na chamada + antes que a introdução de resposta falada seja acionada - `chrome.audioFormat: "pcm16-24khz"`: formato de áudio do par de comandos. Use - `"g711-ulaw-8khz"` somente para pares de comandos legados/personalizados que - ainda emitem áudio de telefonia. -- `chrome.audioBufferBytes: 4096`: buffer de processamento do SoX para comandos - de áudio gerados do par de comandos do Chrome. Isso é metade do buffer padrão - de 8192 bytes do SoX, reduzindo a latência padrão do pipe enquanto deixa - margem para aumentá-lo em hosts ocupados. Valores abaixo do mínimo do SoX são - limitados a 17 bytes. -- `chrome.audioInputCommand`: comando SoX que lê de CoreAudio `BlackHole 2ch` e - grava áudio em `chrome.audioFormat` + `"g711-ulaw-8khz"` apenas para pares de comandos legados/personalizados que ainda emitem + áudio de telefonia. +- `chrome.audioBufferBytes: 4096`: buffer de processamento do SoX para comandos de áudio + de par de comandos gerados para Chrome. Isso é metade do buffer padrão de 8192 bytes do SoX, + reduzindo a latência padrão do pipe e deixando espaço para aumentá-lo em hosts ocupados. + Valores abaixo do mínimo do SoX são limitados a 17 bytes. +- `chrome.audioInputCommand`: comando SoX que lê de CoreAudio `BlackHole 2ch` + e grava áudio em `chrome.audioFormat` - `chrome.audioOutputCommand`: comando SoX que lê áudio em `chrome.audioFormat` - e grava em CoreAudio `BlackHole 2ch` -- `chrome.bargeInInputCommand`: comando opcional de microfone local que grava - PCM mono little-endian com sinal de 16 bits para detecção de interrupção - humana enquanto a reprodução do assistente está ativa. Atualmente, isso se - aplica à ponte de par de comandos `chrome` hospedada pelo Gateway. -- `chrome.bargeInRmsThreshold: 650`: nível RMS que conta como interrupção - humana em `chrome.bargeInInputCommand` -- `chrome.bargeInPeakThreshold: 2500`: nível de pico que conta como interrupção - humana em `chrome.bargeInInputCommand` + e grava no CoreAudio `BlackHole 2ch` +- `chrome.bargeInInputCommand`: comando opcional de microfone local que grava PCM mono + little-endian assinado de 16 bits para detecção de interrupção humana enquanto + a reprodução do assistente está ativa. Atualmente, isso se aplica à ponte de par de comandos + `chrome` hospedada pelo Gateway. +- `chrome.bargeInRmsThreshold: 650`: nível RMS que conta como uma interrupção humana + em `chrome.bargeInInputCommand` +- `chrome.bargeInPeakThreshold: 2500`: nível de pico que conta como uma interrupção humana + em `chrome.bargeInInputCommand` - `chrome.bargeInCooldownMs: 900`: atraso mínimo entre limpezas repetidas de interrupção humana -- `mode: "agent"`: modo padrão de resposta por voz. A fala dos participantes é - transcrita pelo provedor de transcrição em tempo real configurado, enviada ao - agente OpenClaw configurado em uma sessão de subagente por reunião e falada de - volta pelo runtime de TTS normal do OpenClaw. -- `mode: "bidi"`: modo de fallback de modelo em tempo real bidirecional direto. - O provedor de voz em tempo real responde diretamente à fala dos participantes - e pode chamar `openclaw_agent_consult` para respostas mais profundas/com apoio - de ferramentas. -- `mode: "transcribe"`: modo somente observação, sem a ponte de resposta por voz. -- `realtime.provider: "openai"`: fallback de compatibilidade usado quando os - campos de provedor com escopo abaixo não estão definidos. -- `realtime.transcriptionProvider: "openai"`: id do provedor usado pelo modo - `agent` para transcrição em tempo real. -- `realtime.voiceProvider`: id do provedor usado pelo modo `bidi` para voz em - tempo real direta. Defina isto como `"google"` para usar Gemini Live mantendo a - transcrição do modo de agente na OpenAI. +- `mode: "agent"`: modo padrão de resposta falada. A fala dos participantes é transcrita pelo + provedor de transcrição em tempo real configurado, enviada ao agente OpenClaw configurado + em uma sessão de subagente por reunião e falada de volta pelo runtime normal de TTS + do OpenClaw. +- `mode: "bidi"`: modo alternativo direto de modelo bidirecional em tempo real. O + provedor de voz em tempo real responde diretamente à fala dos participantes e pode chamar + `openclaw_agent_consult` para respostas mais profundas/com suporte de ferramentas. +- `mode: "transcribe"`: modo somente observação sem a ponte de resposta falada. +- `realtime.provider: "openai"`: fallback de compatibilidade usado quando os campos de + provedor com escopo abaixo não estão definidos. +- `realtime.transcriptionProvider: "openai"`: id do provedor usado pelo modo `agent` + para transcrição em tempo real. +- `realtime.voiceProvider`: id do provedor usado pelo modo `bidi` para voz direta + em tempo real. Defina isto como `"google"` para usar Gemini Live mantendo a + transcrição do modo agente na OpenAI. - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: respostas faladas breves, com `openclaw_agent_consult` para respostas mais profundas -- `realtime.introMessage`: breve verificação de prontidão falada quando a ponte - em tempo real se conecta; defina como `""` para entrar silenciosamente +- `realtime.introMessage`: verificação curta de prontidão falada quando a ponte em tempo real + se conecta; defina como `""` para entrar silenciosamente - `realtime.agentId`: id opcional do agente OpenClaw para `openclaw_agent_consult`; o padrão é `main` @@ -1140,6 +1137,50 @@ Substituições opcionais: } ``` +ElevenLabs tanto para escuta quanto para fala no modo agente: + +```json5 +{ + messages: { + tts: { + provider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "eleven_v3", + voiceId: "pMsXgVXv3BLzUgSXRplE", + }, + }, + }, + }, + plugins: { + entries: { + "google-meet": { + config: { + realtime: { + transcriptionProvider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "scribe_v2_realtime", + audioFormat: "ulaw_8000", + sampleRate: 8000, + commitStrategy: "vad", + }, + }, + }, + }, + }, + }, + }, +} +``` + +A voz persistente do Meet vem de +`messages.tts.providers.elevenlabs.voiceId`. Respostas do agente também podem usar +diretivas por resposta `[[tts:voiceId=... model=eleven_v3]]` quando substituições +de modelo TTS estão habilitadas, mas a configuração é o padrão determinístico para reuniões. +Ao entrar, os logs devem mostrar `transcriptionProvider=elevenlabs` e cada +resposta falada deve registrar `provider=elevenlabs model=eleven_v3 voice=`. + Configuração somente para Twilio: ```json5 @@ -1156,11 +1197,11 @@ Configuração somente para Twilio: ``` `voiceCall.enabled` tem `true` como padrão; com o transporte Twilio, ele delega a -chamada PSTN real, DTMF e saudação de introdução ao Plugin Voice Call. O Voice -Call reproduz a sequência DTMF antes de abrir o stream de mídia em tempo real e, -em seguida, usa o texto de introdução salvo como a saudação inicial em tempo -real. Se `voice-call` não estiver habilitado, o Google Meet ainda poderá validar -e registrar o plano de discagem, mas não poderá fazer a chamada Twilio. +chamada PSTN real, DTMF e saudação inicial ao Plugin Voice Call. O Voice Call +reproduz a sequência DTMF antes de abrir o fluxo de mídia em tempo real e então usa o +texto de introdução salvo como a saudação inicial em tempo real. Se `voice-call` não estiver +habilitado, o Google Meet ainda pode validar e registrar o plano de discagem, mas não pode +fazer a chamada Twilio. ## Ferramenta @@ -1176,48 +1217,45 @@ Agentes podem usar a ferramenta `google_meet`: ``` Use `transport: "chrome"` quando o Chrome for executado no host do Gateway. Use -`transport: "chrome-node"` quando o Chrome for executado em um Node pareado, -como uma VM Parallels. Em ambos os casos, os provedores de modelo e -`openclaw_agent_consult` são executados no host do Gateway, então as credenciais -do modelo permanecem lá. Com o `mode: "agent"` padrão, o provedor de transcrição -em tempo real cuida da escuta, o agente OpenClaw configurado produz a resposta e -o TTS regular do OpenClaw a fala no Meet. Use `mode: "bidi"` quando quiser que o -modelo de voz em tempo real responda diretamente. O `mode: "realtime"` bruto -continua sendo aceito como alias legado de compatibilidade para `mode: "agent"`, -mas não é mais anunciado no esquema da ferramenta do agente. Logs do modo de -agente incluem o provedor/modelo de transcrição resolvido na inicialização da -ponte e o provedor, modelo, voz, formato de saída e taxa de amostragem de TTS -após cada resposta sintetizada. +`transport: "chrome-node"` quando o Chrome for executado em um nó pareado, como uma VM Parallels. +Em ambos os casos, os provedores de modelo e `openclaw_agent_consult` são executados no +host do Gateway, então as credenciais de modelo permanecem lá. Com o `mode: "agent"` padrão, +o provedor de transcrição em tempo real lida com a escuta, o agente OpenClaw configurado +produz a resposta, e o TTS regular do OpenClaw a fala no Meet. Use +`mode: "bidi"` quando quiser que o modelo de voz em tempo real responda diretamente. +`mode: "realtime"` bruto continua aceito como um alias legado de compatibilidade para +`mode: "agent"`, mas não é mais anunciado no esquema da ferramenta de agente. +Logs do modo agente incluem o provedor/modelo de transcrição resolvido na inicialização +da ponte e o provedor de TTS, modelo, voz, formato de saída e taxa de amostragem depois +de cada resposta sintetizada. -Use `action: "status"` para listar sessões ativas ou inspecionar um ID de -sessão. Use `action: "speak"` com `sessionId` e `message` para fazer o agente em -tempo real falar imediatamente. Use `action: "test_speech"` para criar ou -reutilizar a sessão, acionar uma frase conhecida e retornar a integridade -`inCall` quando o host Chrome puder relatá-la. `test_speech` sempre força -`mode: "agent"` e falha se solicitado a executar em `mode: "transcribe"`, porque -sessões somente observação intencionalmente não podem emitir fala. Seu resultado -`speechOutputVerified` é baseado no aumento de bytes de saída de áudio em tempo -real durante esta chamada de teste, então uma sessão reutilizada com áudio antigo -não conta como uma nova verificação de fala bem-sucedida. Use `action: "leave"` -para marcar uma sessão como encerrada. +Use `action: "status"` para listar sessões ativas ou inspecionar um ID de sessão. Use +`action: "speak"` com `sessionId` e `message` para fazer o agente em tempo real +falar imediatamente. Use `action: "test_speech"` para criar ou reutilizar a sessão, +acionar uma frase conhecida e retornar a integridade `inCall` quando o host Chrome puder +relatá-la. `test_speech` sempre força `mode: "agent"` e falha se solicitado a +executar em `mode: "transcribe"` porque sessões somente observação intencionalmente não podem +emitir fala. Seu resultado `speechOutputVerified` se baseia no aumento de bytes de saída de áudio +em tempo real durante esta chamada de teste, então uma sessão reutilizada com áudio antigo +não conta como uma nova verificação de fala bem-sucedida. Use `action: "leave"` para marcar +uma sessão como encerrada. `status` inclui a integridade do Chrome quando disponível: - `inCall`: o Chrome parece estar dentro da chamada do Meet -- `micMuted`: estado do microfone do Meet por melhor esforço +- `micMuted`: estado do microfone do Meet com melhor esforço - `manualActionRequired` / `manualActionReason` / `manualActionMessage`: o - perfil do navegador precisa de login manual, admissão pelo anfitrião do Meet, - permissões ou reparo do controle do navegador antes que a fala funcione -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: se a fala - gerenciada do Chrome é permitida agora. `speechReady: false` significa que o - OpenClaw não enviou a introdução/frase de teste para a ponte de áudio. + perfil do navegador precisa de login manual, admissão pelo anfitrião do Meet, permissões ou + reparo de controle do navegador antes que a fala possa funcionar +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: se + a fala gerenciada do Chrome está permitida agora. `speechReady: false` significa que o OpenClaw + não enviou a frase de introdução/teste para a ponte de áudio. - `providerConnected` / `realtimeReady`: estado da ponte de voz em tempo real -- `lastInputAt` / `lastOutputAt`: último áudio visto a partir da ponte ou - enviado para ela -- `audioOutputRouted` / `audioOutputDeviceLabel`: se a saída de mídia da aba do - Meet foi roteada ativamente para o dispositivo BlackHole usado pela ponte -- `lastSuppressedInputAt` / `suppressedInputBytes`: entrada de local loopback - ignorada enquanto a reprodução do assistente está ativa +- `lastInputAt` / `lastOutputAt`: último áudio visto vindo da ponte ou enviado a ela +- `audioOutputRouted` / `audioOutputDeviceLabel`: se a saída de mídia da aba do Meet + foi roteada ativamente para o dispositivo BlackHole usado pela ponte +- `lastSuppressedInputAt` / `suppressedInputBytes`: entrada de local loopback ignorada enquanto + a reprodução do assistente está ativa ```json { @@ -1227,56 +1265,40 @@ para marcar uma sessão como encerrada. } ``` -## Modos Agent e Bidi +## Modos agente e bidi -O modo `agent` do Chrome é otimizado para o comportamento de "meu agente está na -reunião". O provedor de transcrição em tempo real ouve o áudio da reunião, as -transcrições finais dos participantes são roteadas pelo agente OpenClaw -configurado e a resposta é falada pelo runtime de TTS normal do OpenClaw. Defina -`mode: "bidi"` quando quiser que o modelo de voz em tempo real responda -diretamente. Fragmentos próximos da transcrição final são combinados antes da -consulta para que uma fala não produza várias respostas parciais obsoletas. A -entrada em tempo real também é suprimida enquanto o áudio enfileirado do -assistente ainda estiver sendo reproduzido, e ecos recentes de transcrição -semelhantes ao assistente são ignorados antes da consulta ao agente para que o -local loopback do BlackHole não faça o agente responder à própria fala. +O modo `agent` do Chrome é otimizado para o comportamento de "meu agente está na reunião". O +provedor de transcrição em tempo real ouve o áudio da reunião, transcrições finais dos participantes +são roteadas pelo agente OpenClaw configurado, e a resposta é +falada pelo runtime normal de TTS do OpenClaw. Defina `mode: "bidi"` quando quiser +que o modelo de voz em tempo real responda diretamente. +Fragmentos próximos de transcrição final são combinados antes da consulta para que um turno +falado não produza várias respostas parciais obsoletas. A entrada em tempo real também é +suprimida enquanto áudio do assistente em fila ainda está sendo reproduzido, +e ecos recentes de transcrições semelhantes ao assistente são ignorados antes da consulta ao agente +para que o local loopback do BlackHole não faça o agente responder à própria fala. -| Modo | Quem decide a resposta | Caminho de saída de fala | Use quando | +| Modo | Quem decide a resposta | Caminho de saída de fala | Use quando | | ------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------- | -| `agent` | O agente OpenClaw configurado | Runtime de TTS normal do OpenClaw | Você quer o comportamento de "meu agente está na reunião" | -| `bidi` | O modelo de voz em tempo real | Resposta de áudio do provedor de voz em tempo real | Você quer o loop de voz conversacional de menor latência | +| `agent` | O agente OpenClaw configurado | Runtime normal de TTS do OpenClaw | Você quer o comportamento de "meu agente está na reunião" | +| `bidi` | O modelo de voz em tempo real | Resposta de áudio do provedor de voz em tempo real | Você quer o loop de voz conversacional de menor latência | -No modo `bidi`, quando o modelo em tempo real precisa de raciocínio mais -profundo, informações atuais ou ferramentas normais do OpenClaw, ele pode chamar -`openclaw_agent_consult`. +No modo `bidi`, quando o modelo em tempo real precisa de raciocínio mais profundo, informações +atuais ou ferramentas normais do OpenClaw, ele pode chamar `openclaw_agent_consult`. -A ferramenta de consulta executa o agente OpenClaw regular nos bastidores com o -contexto recente da transcrição da reunião e retorna uma resposta falada concisa. -No modo `agent`, o OpenClaw envia essa resposta diretamente ao runtime de TTS; no -modo `bidi`, o modelo de voz em tempo real pode falar o resultado da consulta de -volta na reunião. Ela usa a mesma infraestrutura compartilhada de consulta do -Voice Call. +A ferramenta de consulta executa o agente OpenClaw regular nos bastidores com o contexto recente da transcrição da reunião e retorna uma resposta falada concisa. No modo `agent`, o OpenClaw envia essa resposta diretamente para o runtime de TTS; no modo `bidi`, o modelo de voz em tempo real pode falar o resultado da consulta de volta na reunião. Ela usa o mesmo mecanismo de consulta compartilhado da Chamada de Voz. -Por padrão, consultas são executadas no agente `main`. Defina `realtime.agentId` -quando uma rota do Meet deve consultar um workspace de agente OpenClaw dedicado, -padrões de modelo, política de ferramentas, memória e histórico de sessão. +Por padrão, as consultas são executadas no agente `main`. Defina `realtime.agentId` quando uma faixa do Meet deve consultar um workspace dedicado de agente OpenClaw, padrões de modelo, política de ferramentas, memória e histórico de sessão. -Consultas do modo de agente usam uma chave de sessão -`agent::subagent:google-meet:` por reunião, para que perguntas de -acompanhamento mantenham o contexto da reunião enquanto herdam a política normal -de agente do agente configurado. +Consultas no modo agente usam uma chave de sessão por reunião `agent::subagent:google-meet:`, para que perguntas de acompanhamento mantenham o contexto da reunião enquanto herdam a política normal do agente configurado. `realtime.toolPolicy` controla a execução da consulta: -- `safe-read-only`: expõe a ferramenta de consulta e limita o agente regular a - `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` e - `memory_get`. -- `owner`: expõe a ferramenta de consulta e permite que o agente regular use a - política normal de ferramentas do agente. +- `safe-read-only`: expõe a ferramenta de consulta e limita o agente regular a `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` e `memory_get`. +- `owner`: expõe a ferramenta de consulta e permite que o agente regular use a política normal de ferramentas do agente. - `none`: não expõe a ferramenta de consulta ao modelo de voz em tempo real. -A chave da sessão de consulta tem escopo por sessão do Meet, então chamadas de consulta de acompanhamento -podem reutilizar o contexto de consulta anterior durante a mesma reunião. +A chave de sessão da consulta é delimitada por sessão do Meet, então chamadas de consulta de acompanhamento podem reutilizar o contexto de consulta anterior durante a mesma reunião. Para forçar uma verificação falada de prontidão depois que o Chrome tiver entrado completamente na chamada: @@ -1284,7 +1306,7 @@ Para forçar uma verificação falada de prontidão depois que o Chrome tiver en openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Para o teste smoke completo de entrar e falar: +Para o smoke completo de entrar e falar: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1294,7 +1316,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## Lista de verificação de teste ao vivo -Use esta sequência antes de entregar uma reunião a um agente não assistido: +Use esta sequência antes de entregar uma reunião a um agente sem supervisão: ```bash openclaw googlemeet setup @@ -1307,15 +1329,12 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ Estado esperado do Chrome-node: - `googlemeet setup` está todo verde. -- `googlemeet setup` inclui `chrome-node-connected` quando Chrome-node é o - transporte padrão ou um nó está fixado. +- `googlemeet setup` inclui `chrome-node-connected` quando Chrome-node é o transporte padrão ou um nó está fixado. - `nodes status` mostra o nó selecionado conectado. -- O nó selecionado anuncia tanto `googlemeet.chrome` quanto `browser.proxy`. -- A aba do Meet entra na chamada e `test-speech` retorna a integridade do Chrome com - `inCall: true`. +- O nó selecionado anuncia `googlemeet.chrome` e `browser.proxy`. +- A aba do Meet entra na chamada e `test-speech` retorna a integridade do Chrome com `inCall: true`. -Para um host Chrome remoto, como uma VM macOS Parallels, esta é a verificação -segura mais curta depois de atualizar o Gateway ou a VM: +Para um host remoto do Chrome, como uma VM macOS do Parallels, esta é a verificação segura mais curta após atualizar o Gateway ou a VM: ```bash openclaw googlemeet setup @@ -1326,11 +1345,9 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Isso comprova que o Plugin do Gateway está carregado, que o nó da VM está conectado com o -token atual e que a ponte de áudio do Meet está disponível antes que um agente abra uma -aba de reunião real. +Isso prova que o Plugin do Gateway foi carregado, o nó da VM está conectado com o token atual e a ponte de áudio do Meet está disponível antes de um agente abrir uma aba de reunião real. -Para um teste smoke do Twilio, use uma reunião que exponha detalhes de discagem por telefone: +Para um smoke do Twilio, use uma reunião que exponha detalhes de discagem por telefone: ```bash openclaw googlemeet setup @@ -1342,12 +1359,10 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Estado esperado do Twilio: -- `googlemeet setup` inclui verificações verdes de `twilio-voice-call-plugin`, - `twilio-voice-call-credentials` e `twilio-voice-call-webhook`. -- `voicecall` está disponível na CLI depois que o Gateway for recarregado. +- `googlemeet setup` inclui verificações verdes de `twilio-voice-call-plugin`, `twilio-voice-call-credentials` e `twilio-voice-call-webhook`. +- `voicecall` está disponível na CLI após o recarregamento do Gateway. - A sessão retornada tem `transport: "twilio"` e um `twilio.voiceCallId`. -- `openclaw logs --follow` mostra DTMF TwiML servido antes de TwiML em tempo real, depois uma - ponte em tempo real com a saudação inicial enfileirada. +- `openclaw logs --follow` mostra DTMF TwiML servido antes do TwiML em tempo real, depois uma ponte em tempo real com a saudação inicial enfileirada. - `googlemeet leave ` encerra a chamada de voz delegada. ## Solução de problemas @@ -1361,14 +1376,9 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -Se você acabou de editar `plugins.entries.google-meet`, reinicie ou recarregue o Gateway. -O agente em execução só vê ferramentas de Plugin registradas pelo processo atual do Gateway. +Se você acabou de editar `plugins.entries.google-meet`, reinicie ou recarregue o Gateway. O agente em execução só vê ferramentas de Plugin registradas pelo processo atual do Gateway. -Em hosts de Gateway que não são macOS, a ferramenta `google_meet` voltada ao agente continua visível, -mas ações locais de retorno de fala do Chrome são bloqueadas antes de chegarem à ponte de áudio. -O áudio local de retorno de fala do Chrome atualmente depende de `BlackHole 2ch` do macOS, então -agentes Linux devem usar `mode: "transcribe"`, discagem do Twilio ou um host -`chrome-node` macOS em vez do caminho padrão de agente local do Chrome. +Em hosts de Gateway que não são macOS, a ferramenta `google_meet` voltada ao agente continua visível, mas ações locais de resposta por áudio do Chrome são bloqueadas antes de chegarem à ponte de áudio. O áudio local de resposta por áudio do Chrome atualmente depende do macOS `BlackHole 2ch`, então agentes Linux devem usar `mode: "transcribe"`, discagem do Twilio ou um host macOS `chrome-node` em vez do caminho padrão de agente com Chrome local. ### Nenhum nó compatível com Google Meet conectado @@ -1389,8 +1399,7 @@ openclaw devices approve openclaw nodes status ``` -O nó deve estar conectado e listar `googlemeet.chrome` mais `browser.proxy`. -A configuração do Gateway deve permitir esses comandos de nó: +O nó deve estar conectado e listar `googlemeet.chrome` além de `browser.proxy`. A configuração do Gateway deve permitir esses comandos de nó: ```json5 { @@ -1402,9 +1411,7 @@ A configuração do Gateway deve permitir esses comandos de nó: } ``` -Se `googlemeet setup` falhar em `chrome-node-connected` ou o log do Gateway relatar -`gateway token mismatch`, reinstale ou reinicie o nó com o token atual do Gateway. -Para um Gateway em LAN, isso geralmente significa: +Se `googlemeet setup` falhar em `chrome-node-connected` ou o log do Gateway relatar `gateway token mismatch`, reinstale ou reinicie o nó com o token atual do Gateway. Para um Gateway em LAN, isso geralmente significa: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1424,54 +1431,28 @@ openclaw nodes status --connected ### O navegador abre, mas o agente não consegue entrar -Execute `googlemeet test-listen` para entradas somente de observação ou `googlemeet test-speech` -para entradas em tempo real, depois inspecione a integridade do Chrome retornada. Se qualquer uma das sondagens -relatar `manualActionRequired: true`, mostre `manualActionMessage` ao operador -e pare de tentar novamente até que a ação no navegador esteja concluída. +Execute `googlemeet test-listen` para entradas apenas de observação ou `googlemeet test-speech` para entradas em tempo real, depois inspecione a integridade do Chrome retornada. Se qualquer uma das sondagens relatar `manualActionRequired: true`, mostre `manualActionMessage` ao operador e pare de tentar novamente até que a ação no navegador esteja concluída. Ações manuais comuns: -- Entrar no perfil do Chrome. -- Admitir o convidado a partir da conta host do Meet. -- Conceder permissões de microfone/câmera ao Chrome quando o prompt nativo de permissão - do Chrome aparecer. -- Fechar ou reparar uma caixa de diálogo travada de permissão do Meet. +- Faça login no perfil do Chrome. +- Admita o convidado pela conta anfitriã do Meet. +- Conceda permissões de microfone/câmera ao Chrome quando o prompt nativo de permissão do Chrome aparecer. +- Feche ou repare uma caixa de diálogo de permissão do Meet travada. -Não relate "não conectado" só porque o Meet mostra "Do you want people to -hear you in the meeting?" Esse é o intersticial de escolha de áudio do Meet; o OpenClaw -clica em **Use microphone** por meio de automação de navegador quando disponível e continua -aguardando o estado real da reunião. Para fallback de navegador somente para criação, o OpenClaw -pode clicar em **Continue without microphone** porque criar a URL não precisa -do caminho de áudio em tempo real. +Não relate "not signed in" apenas porque o Meet mostra "Do you want people to hear you in the meeting?" Esse é o intersticial de escolha de áudio do Meet; o OpenClaw clica em **Use microphone** por meio da automação do navegador quando disponível e continua aguardando o estado real da reunião. Para fallback de navegador apenas para criação, o OpenClaw pode clicar em **Continue without microphone** porque criar a URL não precisa do caminho de áudio em tempo real. -### Falha na criação da reunião +### A criação da reunião falha -`googlemeet create` primeiro usa o endpoint `spaces.create` da API do Google Meet -quando credenciais OAuth estão configuradas. Sem credenciais OAuth, ele faz fallback -para o navegador do nó Chrome fixado. Confirme: +`googlemeet create` primeiro usa o endpoint `spaces.create` da API do Google Meet quando as credenciais OAuth estão configuradas. Sem credenciais OAuth, ele recorre ao navegador do nó Chrome fixado. Confirme: -- Para criação via API: `oauth.clientId` e `oauth.refreshToken` estão configurados, - ou variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*` correspondentes estão presentes. -- Para criação via API: o token de atualização foi emitido depois que o suporte à criação foi - adicionado. Tokens mais antigos podem não ter o escopo `meetings.space.created`; execute novamente - `openclaw googlemeet auth login --json` e atualize a configuração do Plugin. -- Para fallback de navegador: `defaultTransport: "chrome-node"` e - `chromeNode.node` apontam para um nó conectado com `browser.proxy` e - `googlemeet.chrome`. -- Para fallback de navegador: o perfil do Chrome do OpenClaw nesse nó está conectado - ao Google e consegue abrir `https://meet.google.com/new`. -- Para fallback de navegador: novas tentativas reutilizam uma aba existente de - `https://meet.google.com/new` ou de prompt da conta Google antes de abrir uma nova aba. Se um agente exceder o tempo, - tente novamente a chamada da ferramenta em vez de abrir manualmente outra aba do Meet. -- Para fallback de navegador: se a ferramenta retornar `manualActionRequired: true`, use - `browser.nodeId`, `browser.targetId`, `browserUrl` e - `manualActionMessage` retornados para orientar o operador. Não tente novamente em loop até que essa - ação esteja concluída. -- Para fallback de navegador: se o Meet mostrar "Do you want people to hear you in the - meeting?", deixe a aba aberta. O OpenClaw deve clicar em **Use microphone** ou, para - fallback somente de criação, **Continue without microphone** por meio de automação de navegador - e continuar aguardando a URL do Meet gerada. Se não conseguir, o - erro deve mencionar `meet-audio-choice-required`, não `google-login-required`. +- Para criação via API: `oauth.clientId` e `oauth.refreshToken` estão configurados, ou variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*` correspondentes estão presentes. +- Para criação via API: o token de atualização foi emitido depois que o suporte à criação foi adicionado. Tokens mais antigos podem não ter o escopo `meetings.space.created`; execute novamente `openclaw googlemeet auth login --json` e atualize a configuração do Plugin. +- Para fallback de navegador: `defaultTransport: "chrome-node"` e `chromeNode.node` apontam para um nó conectado com `browser.proxy` e `googlemeet.chrome`. +- Para fallback de navegador: o perfil do Chrome do OpenClaw nesse nó está conectado ao Google e consegue abrir `https://meet.google.com/new`. +- Para fallback de navegador: novas tentativas reutilizam uma aba existente de `https://meet.google.com/new` ou de prompt de conta do Google antes de abrir uma nova aba. Se um agente atingir o tempo limite, repita a chamada da ferramenta em vez de abrir manualmente outra aba do Meet. +- Para fallback de navegador: se a ferramenta retornar `manualActionRequired: true`, use os valores retornados `browser.nodeId`, `browser.targetId`, `browserUrl` e `manualActionMessage` para orientar o operador. Não tente novamente em loop até que essa ação esteja concluída. +- Para fallback de navegador: se o Meet mostrar "Do you want people to hear you in the meeting?", deixe a aba aberta. O OpenClaw deve clicar em **Use microphone** ou, para fallback apenas de criação, **Continue without microphone** por meio da automação do navegador e continuar aguardando a URL do Meet gerada. Se não conseguir, o erro deve mencionar `meet-audio-choice-required`, não `google-login-required`. ### O agente entra, mas não fala @@ -1482,63 +1463,33 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -Use `mode: "agent"` para o caminho normal STT -> agente OpenClaw -> retorno de fala TTS, -ou `mode: "bidi"` para o fallback direto de voz em tempo real. `mode: "transcribe"` -intencionalmente não inicia a ponte de retorno de fala. Para depuração somente de observação, -execute `openclaw googlemeet status --json ` depois que os participantes falarem -e verifique `captioning`, `transcriptLines` e `lastCaptionText`. Se `inCall` estiver -true, mas `transcriptLines` permanecer em `0`, as legendas do Meet podem estar desativadas, ninguém -falou desde que o observador foi instalado, a interface do Meet mudou ou legendas ao vivo -não estão disponíveis para o idioma/conta da reunião. +Use `mode: "agent"` para o caminho normal de resposta por áudio STT -> agente OpenClaw -> TTS, ou `mode: "bidi"` para o fallback direto de voz em tempo real. `mode: "transcribe"` intencionalmente não inicia a ponte de resposta por áudio. Para depuração apenas de observação, execute `openclaw googlemeet status --json ` depois que os participantes falarem e verifique `captioning`, `transcriptLines` e `lastCaptionText`. Se `inCall` for true mas `transcriptLines` permanecer em `0`, as legendas do Meet podem estar desativadas, ninguém falou desde que o observador foi instalado, a interface do Meet mudou ou legendas ao vivo estão indisponíveis para o idioma/conta da reunião. -`googlemeet test-speech` sempre verifica o caminho em tempo real e relata se -bytes de saída da ponte foram observados nessa invocação. Se `speechOutputVerified` for false e -`speechOutputTimedOut` for true, o provedor em tempo real pode ter aceitado a -fala, mas o OpenClaw não viu novos bytes de saída chegarem à ponte de áudio -do Chrome. +`googlemeet test-speech` sempre verifica o caminho em tempo real e relata se bytes de saída da ponte foram observados para aquela invocação. Se `speechOutputVerified` for false e `speechOutputTimedOut` for true, o provedor em tempo real pode ter aceitado a fala, mas o OpenClaw não viu novos bytes de saída chegarem à ponte de áudio do Chrome. Verifique também: -- Uma chave de provedor em tempo real está disponível no host do Gateway, como - `OPENAI_API_KEY` ou `GEMINI_API_KEY`. +- Uma chave de provedor em tempo real está disponível no host do Gateway, como `OPENAI_API_KEY` ou `GEMINI_API_KEY`. - `BlackHole 2ch` está visível no host do Chrome. - `sox` existe no host do Chrome. -- O microfone e o alto-falante do Meet estão roteados pelo caminho de áudio virtual usado pelo - OpenClaw. `doctor` deve mostrar `meet output routed: yes` para entradas em tempo real - no Chrome local. +- O microfone e o alto-falante do Meet estão roteados pelo caminho de áudio virtual usado pelo OpenClaw. `doctor` deve mostrar `meet output routed: yes` para entradas em tempo real com Chrome local. -`googlemeet doctor [session-id]` imprime a sessão, o nó, o estado em chamada, -o motivo da ação manual, a conexão do provedor em tempo real, `realtimeReady`, atividade de -entrada/saída de áudio, últimos timestamps de áudio, contadores de bytes e URL do navegador. -Use `googlemeet status [session-id] --json` quando precisar do JSON bruto. Use -`googlemeet doctor --oauth` quando precisar verificar a atualização OAuth do Google Meet -sem expor tokens; adicione `--meeting` ou `--create-space` quando também precisar de uma -prova da API do Google Meet. +`googlemeet doctor [session-id]` imprime a sessão, o nó, o estado na chamada, o motivo da ação manual, a conexão do provedor em tempo real, `realtimeReady`, atividade de entrada/saída de áudio, últimos carimbos de data/hora de áudio, contadores de bytes e URL do navegador. Use `googlemeet status [session-id] --json` quando precisar do JSON bruto. Use `googlemeet doctor --oauth` quando precisar verificar a atualização OAuth do Google Meet sem expor tokens; adicione `--meeting` ou `--create-space` quando também precisar de uma prova da API do Google Meet. -Se um agente excedeu o tempo e você consegue ver uma aba do Meet já aberta, inspecione essa aba -sem abrir outra: +Se um agente atingiu o tempo limite e você consegue ver uma aba do Meet já aberta, inspecione essa aba sem abrir outra: ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -A ação de ferramenta equivalente é `recover_current_tab`. Ela foca e inspeciona uma -aba existente do Meet para o transporte selecionado. Com `chrome`, usa controle local -do navegador por meio do Gateway; com `chrome-node`, usa o nó Chrome configurado. -Ela não abre uma nova aba nem cria uma nova sessão; relata o -bloqueador atual, como login, admissão, permissões ou estado de escolha de áudio. -O comando da CLI fala com o Gateway configurado, então o Gateway deve estar em execução; -`chrome-node` também exige que o nó Chrome esteja conectado. +A ação de ferramenta equivalente é `recover_current_tab`. Ela focaliza e inspeciona uma aba existente do Meet para o transporte selecionado. Com `chrome`, usa controle local do navegador por meio do Gateway; com `chrome-node`, usa o nó Chrome configurado. Ela não abre uma nova aba nem cria uma nova sessão; relata o bloqueador atual, como login, admissão, permissões ou estado de escolha de áudio. O comando CLI conversa com o Gateway configurado, então o Gateway deve estar em execução; `chrome-node` também exige que o nó Chrome esteja conectado. -### Falha nas verificações de configuração do Twilio +### As verificações de configuração do Twilio falham -`twilio-voice-call-plugin` falha quando `voice-call` não é permitido ou não está habilitado. -Adicione-o a `plugins.allow`, habilite `plugins.entries.voice-call` e recarregue o -Gateway. +`twilio-voice-call-plugin` falha quando `voice-call` não é permitido ou não está habilitado. Adicione-o a `plugins.allow`, habilite `plugins.entries.voice-call` e recarregue o Gateway. -`twilio-voice-call-credentials` falha quando o backend Twilio não tem SID da conta, -token de autenticação ou número chamador. Defina estes no host do Gateway: +`twilio-voice-call-credentials` falha quando o backend do Twilio não tem SID da conta, token de autenticação ou número chamador. Defina estes no host do Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1546,14 +1497,9 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`twilio-voice-call-webhook` falha quando `voice-call` não tem exposição pública de Webhook, -ou quando `publicUrl` aponta para local loopback ou espaço de rede privada. -Defina `plugins.entries.voice-call.config.publicUrl` para a URL pública do provedor ou -configure uma exposição de túnel/Tailscale de `voice-call`. +`twilio-voice-call-webhook` falha quando `voice-call` não tem exposição pública de Webhook, ou quando `publicUrl` aponta para local loopback ou espaço de rede privada. Defina `plugins.entries.voice-call.config.publicUrl` como a URL pública do provedor ou configure uma exposição de túnel/Tailscale para `voice-call`. -URLs de loopback e privadas não são válidas para callbacks de operadora. Não use -`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, -`192.168.x`, `169.254.x`, `fc00::/7` ou `fd00::/8` como `publicUrl`. +URLs de loopback e privadas não são válidas para callbacks de operadora. Não use `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` ou `fd00::/8` como `publicUrl`. Para uma URL pública estável: @@ -1574,7 +1520,8 @@ Para uma URL pública estável: } ``` -Para desenvolvimento local, use um túnel ou exposição Tailscale em vez de uma URL de host privada: +Para desenvolvimento local, use um túnel ou exposição Tailscale em vez de uma URL +de host privada: ```json5 { @@ -1592,7 +1539,7 @@ Para desenvolvimento local, use um túnel ou exposição Tailscale em vez de uma } ``` -Depois reinicie ou recarregue o Gateway e execute: +Em seguida, reinicie ou recarregue o Gateway e execute: ```bash openclaw googlemeet setup --transport twilio @@ -1600,14 +1547,14 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` é somente prontidão por padrão. Para simular um número específico: +`voicecall smoke` verifica apenas prontidão por padrão. Para simular com um número específico: ```bash openclaw voicecall smoke --to "+15555550123" ``` -Só adicione `--yes` quando você intencionalmente quiser fazer uma chamada de notificação -de saída ao vivo: +Adicione `--yes` somente quando você quiser intencionalmente fazer uma chamada +real de notificação de saída: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -1615,7 +1562,8 @@ openclaw voicecall smoke --to "+15555550123" --yes ### A chamada Twilio inicia, mas nunca entra na reunião -Confirme se o evento do Meet expõe detalhes de discagem telefônica. Passe o número de discagem e o PIN exatos ou uma sequência DTMF personalizada: +Confirme se o evento do Meet expõe os detalhes de discagem por telefone. Passe o +número exato de discagem e o PIN, ou uma sequência DTMF personalizada: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1624,38 +1572,66 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -Use `w` inicial ou vírgulas em `--dtmf-sequence` se o provedor precisar de uma pausa antes de inserir o PIN. +Use `w` inicial ou vírgulas em `--dtmf-sequence` se o provedor precisar de uma +pausa antes de inserir o PIN. -Se a chamada telefônica for criada, mas a lista de participantes do Meet nunca mostrar o participante por discagem: +Se a chamada telefônica for criada, mas a lista do Meet nunca mostrar o +participante por discagem: -- Execute `openclaw googlemeet doctor ` para confirmar o ID da chamada Twilio delegada, se DTMF foi enfileirado e se a saudação introdutória foi solicitada. +- Execute `openclaw googlemeet doctor ` para confirmar o ID da chamada Twilio delegada, se o DTMF foi enfileirado e se a saudação de introdução foi solicitada. - Execute `openclaw voicecall status --call-id ` e confirme se a chamada ainda está ativa. -- Execute `openclaw voicecall tail` e verifique se os Webhooks da Twilio estão chegando ao Gateway. -- Execute `openclaw logs --follow` e procure a sequência Twilio Meet: o Google Meet delega a entrada, o Voice Call inicia o trecho telefônico, o Google Meet aguarda `voiceCall.dtmfDelayMs`, envia DTMF com `voicecall.dtmf`, aguarda `voiceCall.postDtmfSpeechDelayMs` e então solicita fala introdutória com `voicecall.speak`. -- Execute novamente `openclaw googlemeet setup --transport twilio`; uma verificação de configuração verde é necessária, mas não prova que a sequência de PIN da reunião está correta. -- Confirme se o número de discagem pertence ao mesmo convite e região do Meet que o PIN. -- Aumente `voiceCall.dtmfDelayMs` se o Meet atender lentamente ou se a transcrição da chamada ainda mostrar o prompt solicitando um PIN após o envio de DTMF. -- Se o participante entrar, mas você não ouvir a saudação, verifique `openclaw logs --follow` para a solicitação `voicecall.speak` pós-DTMF e a reprodução TTS por fluxo de mídia ou o fallback `` da Twilio. Se a transcrição da chamada ainda contiver "enter the meeting PIN", o trecho telefônico ainda não entrou na sala do Meet, portanto os participantes da reunião não ouvirão a fala. +- Execute `openclaw voicecall tail` e verifique se os webhooks da Twilio estão chegando ao Gateway. +- Execute `openclaw logs --follow` e procure a sequência do Twilio Meet: o Google Meet delega a entrada, o Voice Call inicia a perna telefônica, o Google Meet aguarda `voiceCall.dtmfDelayMs`, envia DTMF com `voicecall.dtmf`, aguarda `voiceCall.postDtmfSpeechDelayMs` e então solicita a fala de introdução com `voicecall.speak`. +- Execute novamente `openclaw googlemeet setup --transport twilio`; uma verificação de configuração verde é obrigatória, mas não comprova que a sequência do PIN da reunião está correta. +- Confirme se o número de discagem pertence ao mesmo convite do Meet e à mesma região que o PIN. +- Aumente `voiceCall.dtmfDelayMs` se o Meet responder lentamente ou se a transcrição da chamada ainda mostrar a solicitação de PIN após o envio do DTMF. +- Se o participante entrar, mas você não ouvir a saudação, verifique `openclaw logs --follow` para a solicitação `voicecall.speak` pós-DTMF e a reprodução de TTS por fluxo de mídia ou o fallback `` da Twilio. Se a transcrição da chamada ainda contiver "enter the meeting PIN", a perna telefônica ainda não entrou na sala do Meet, portanto os participantes da reunião não ouvirão a fala. -Se os Webhooks não chegarem, depure primeiro o Plugin Voice Call: o provedor deve alcançar `plugins.entries.voice-call.config.publicUrl` ou o túnel configurado. Consulte [Solução de problemas de chamada de voz](/pt-BR/plugins/voice-call#troubleshooting). +Se os webhooks não chegarem, depure primeiro o Plugin Voice Call: o provedor deve +alcançar `plugins.entries.voice-call.config.publicUrl` ou o túnel configurado. +Consulte [Solução de problemas de chamadas de voz](/pt-BR/plugins/voice-call#troubleshooting). ## Observações -A API oficial de mídia do Google Meet é orientada a recebimento, portanto falar em uma chamada do Meet ainda precisa de um caminho de participante. Este Plugin mantém esse limite visível: o Chrome lida com a participação pelo navegador e o roteamento de áudio local; a Twilio lida com a participação por discagem telefônica. +A API oficial de mídia do Google Meet é orientada a recebimento, então falar em +uma chamada do Meet ainda precisa de um caminho de participante. Este plugin +mantém esse limite visível: o Chrome lida com a participação no navegador e o +roteamento de áudio local; a Twilio lida com a participação por discagem +telefônica. -Os modos de resposta de voz do Chrome precisam de `BlackHole 2ch` mais um dos seguintes: +Os modos de resposta por fala do Chrome precisam de `BlackHole 2ch` mais um dos seguintes: - `chrome.audioInputCommand` mais `chrome.audioOutputCommand`: o OpenClaw controla a ponte e canaliza áudio em `chrome.audioFormat` entre esses comandos e o provedor selecionado. O modo de agente usa transcrição em tempo real mais TTS regular; o modo bidi usa o provedor de voz em tempo real. O caminho padrão do Chrome é PCM16 de 24 kHz com `chrome.audioBufferBytes: 4096`; G.711 mu-law de 8 kHz continua disponível para pares de comandos legados. -- `chrome.audioBridgeCommand`: um comando de ponte externo controla todo o caminho de áudio local e deve sair após iniciar ou validar seu daemon. Isso só é válido para `bidi` porque o modo `agent` precisa de acesso direto ao par de comandos para TTS. +- `chrome.audioBridgeCommand`: um comando de ponte externo controla todo o caminho de áudio local e deve sair após iniciar ou validar seu daemon. Isso é válido apenas para `bidi`, porque o modo `agent` precisa de acesso direto ao par de comandos para TTS. -Para áudio duplex limpo, roteie a saída do Meet e o microfone do Meet por dispositivos virtuais separados ou por um grafo de dispositivos virtuais no estilo Loopback. Um único dispositivo BlackHole compartilhado pode devolver o áudio de outros participantes para a chamada. +Quando um agente chama a ferramenta `google_meet` no modo de agente, a sessão de +consultor da reunião bifurca a transcrição atual do chamador antes de responder +à fala dos participantes. A sessão do Meet ainda permanece separada +(`agent::subagent:google-meet:`), para que acompanhamentos da +reunião não alterem diretamente a transcrição do chamador. -Com a ponte Chrome por par de comandos, `chrome.bargeInInputCommand` pode ouvir um microfone local separado e limpar a reprodução do assistente quando a pessoa começa a falar. Isso mantém a fala humana à frente da saída do assistente mesmo quando a entrada de local loopback compartilhada do BlackHole é temporariamente suprimida durante a reprodução do assistente. Assim como `chrome.audioInputCommand` e `chrome.audioOutputCommand`, ele é um comando local configurado pelo operador. Use um caminho de comando confiável explícito ou uma lista de argumentos, e não aponte para scripts de locais não confiáveis. +Para áudio duplex limpo, roteie a saída do Meet e o microfone do Meet por +dispositivos virtuais separados ou por um grafo de dispositivos virtuais no estilo +Loopback. Um único dispositivo BlackHole compartilhado pode ecoar outros +participantes de volta para a chamada. -`googlemeet speak` aciona a ponte de áudio de resposta de voz ativa para uma sessão do Chrome. `googlemeet leave` interrompe essa ponte. Para sessões Twilio delegadas por meio do Plugin Voice Call, `leave` também encerra a chamada de voz subjacente. Use `googlemeet end-active-conference` quando você também quiser fechar a conferência ativa do Google Meet para um espaço gerenciado por API. +Com a ponte Chrome por par de comandos, `chrome.bargeInInputCommand` pode ouvir +um microfone local separado e limpar a reprodução do assistente quando o humano +começar a falar. Isso mantém a fala humana à frente da saída do assistente mesmo +quando a entrada compartilhada de local loopback do BlackHole é temporariamente +suprimida durante a reprodução do assistente. Assim como `chrome.audioInputCommand` +e `chrome.audioOutputCommand`, ele é um comando local configurado pelo operador. +Use um caminho de comando confiável explícito ou uma lista de argumentos e não o +aponte para scripts de locais não confiáveis. + +`googlemeet speak` aciona a ponte de áudio ativa de resposta por fala para uma +sessão do Chrome. `googlemeet leave` interrompe essa ponte. Para sessões Twilio +delegadas pelo Plugin Voice Call, `leave` também encerra a chamada de voz +subjacente. Use `googlemeet end-active-conference` quando você também quiser +fechar a conferência ativa do Google Meet para um espaço gerenciado por API. ## Relacionados -- [Plugin Voice Call](/pt-BR/plugins/voice-call) -- [Modo de fala](/pt-BR/nodes/talk) -- [Criando Plugins](/pt-BR/plugins/building-plugins) +- [Plugin de chamada de voz](/pt-BR/plugins/voice-call) +- [Modo de conversa](/pt-BR/nodes/talk) +- [Criando plugins](/pt-BR/plugins/building-plugins) diff --git a/docs/pt-BR/providers/elevenlabs.md b/docs/pt-BR/providers/elevenlabs.md index 6253d09fb..68e0599bb 100644 --- a/docs/pt-BR/providers/elevenlabs.md +++ b/docs/pt-BR/providers/elevenlabs.md @@ -1,38 +1,38 @@ --- read_when: - - Você quer usar text-to-speech do ElevenLabs no OpenClaw - - Você quer usar speech-to-text Scribe do ElevenLabs para anexos de áudio - - Você quer transcrição em tempo real do ElevenLabs para Voice Call -summary: Use fala do ElevenLabs, STT Scribe e transcrição em tempo real com OpenClaw + - Você quer usar a conversão de texto em fala da ElevenLabs no OpenClaw + - Você quer a conversão de fala em texto do ElevenLabs Scribe para anexos de áudio + - Você quer transcrição em tempo real do ElevenLabs para Chamada de voz ou Google Meet +summary: Use a síntese de fala da ElevenLabs, o Scribe STT e a transcrição em tempo real com o OpenClaw title: ElevenLabs x-i18n: - generated_at: "2026-04-25T13:54:19Z" - model: gpt-5.4 + generated_at: "2026-05-04T07:03:31Z" + model: gpt-5.5 provider: openai - source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a + source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b source_path: providers/elevenlabs.md - workflow: 15 + workflow: 16 --- -O OpenClaw usa ElevenLabs para text-to-speech, speech-to-text em lote com Scribe -v2 e STT de streaming do Voice Call com Scribe v2 Realtime. +OpenClaw usa ElevenLabs para texto para fala, fala para texto em lote com Scribe +v2 e STT por streaming com Scribe v2 Realtime. -| Capacidade | Superfície do OpenClaw | Padrão | -| ----------------------- | --------------------------------------------- | ------------------------ | -| Text-to-speech | `messages.tts` / `talk` | `eleven_multilingual_v2` | -| Speech-to-text em lote | `tools.media.audio` | `scribe_v2` | -| Speech-to-text em streaming | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` | +| Recurso | Superfície do OpenClaw | Padrão | +| ------------------------ | -------------------------------------------------------------------- | ------------------------ | +| Texto para fala | `messages.tts` / `talk` | `eleven_multilingual_v2` | +| Fala para texto em lote | `tools.media.audio` | `scribe_v2` | +| Fala para texto por streaming | streaming de chamada de voz ou Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` | ## Autenticação -Defina `ELEVENLABS_API_KEY` no ambiente. `XI_API_KEY` também é aceito por -compatibilidade com ferramentas existentes do ElevenLabs. +Defina `ELEVENLABS_API_KEY` no ambiente. `XI_API_KEY` também é aceito para +compatibilidade com ferramentas existentes da ElevenLabs. ```bash export ELEVENLABS_API_KEY="..." ``` -## Text-to-speech +## Texto para fala ```json5 { @@ -50,10 +50,10 @@ export ELEVENLABS_API_KEY="..." } ``` -Defina `modelId` como `eleven_v3` para usar TTS v3 do ElevenLabs. O OpenClaw mantém +Defina `modelId` como `eleven_v3` para usar TTS v3 da ElevenLabs. OpenClaw mantém `eleven_multilingual_v2` como padrão para instalações existentes. -## Speech-to-text +## Fala para texto Use Scribe v2 para anexos de áudio recebidos e segmentos curtos de voz gravada: @@ -70,22 +70,22 @@ Use Scribe v2 para anexos de áudio recebidos e segmentos curtos de voz gravada: } ``` -O OpenClaw envia áudio multipart para `/v1/speech-to-text` do ElevenLabs com -`model_id: "scribe_v2"`. Dicas de idioma são mapeadas para `language_code` quando presentes. +OpenClaw envia áudio multipart para ElevenLabs `/v1/speech-to-text` com +`model_id: "scribe_v2"`. As dicas de idioma são mapeadas para `language_code` quando presentes. -## STT de streaming para Voice Call +## STT por streaming -O Plugin integrado `elevenlabs` registra Scribe v2 Realtime para -transcrição em streaming do Voice Call. +O Plugin `elevenlabs` incluído registra o Scribe v2 Realtime para transcrição por streaming +em modo agente de chamada de voz e Google Meet. -| Configuração | Caminho de configuração | Padrão | -| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------- | -| Chave de API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Usa `ELEVENLABS_API_KEY` / `XI_API_KEY` como fallback | -| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` | -| Formato de áudio | `...elevenlabs.audioFormat` | `ulaw_8000` | -| Sample rate | `...elevenlabs.sampleRate` | `8000` | -| Estratégia de commit | `...elevenlabs.commitStrategy` | `vad` | -| Idioma | `...elevenlabs.languageCode` | (não definido) | +| Configuração | Caminho de configuração | Padrão | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | +| Chave de API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Recorre a `ELEVENLABS_API_KEY` / `XI_API_KEY` | +| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` | +| Formato de áudio | `...elevenlabs.audioFormat` | `ulaw_8000` | +| Taxa de amostragem | `...elevenlabs.sampleRate` | `8000` | +| Estratégia de commit | `...elevenlabs.commitStrategy` | `vad` | +| Idioma | `...elevenlabs.languageCode` | (não definido) | ```json5 { @@ -113,12 +113,18 @@ transcrição em streaming do Voice Call. ``` -O Voice Call recebe mídia do Twilio como G.711 u-law a 8 kHz. O provider -realtime do ElevenLabs usa `ulaw_8000` por padrão, então quadros de telefonia podem ser encaminhados sem +A chamada de voz recebe mídia da Twilio como G.711 u-law a 8 kHz. O provedor em tempo real +da ElevenLabs usa `ulaw_8000` como padrão, então quadros de telefonia podem ser encaminhados sem transcodificação. +Para o modo agente do Google Meet, defina +`plugins.entries.google-meet.config.realtime.transcriptionProvider` como +`"elevenlabs"` e configure o mesmo bloco de provedor em +`plugins.entries.google-meet.config.realtime.providers.elevenlabs`. + ## Relacionados -- [Text-to-speech](/pt-BR/tools/tts) +- [Texto para fala](/pt-BR/tools/tts) +- [Google Meet](/pt-BR/plugins/google-meet) - [Seleção de modelo](/pt-BR/concepts/model-providers) diff --git a/docs/pt-BR/reference/RELEASING.md b/docs/pt-BR/reference/RELEASING.md index 6087fbc8b..6d7b3ec0e 100644 --- a/docs/pt-BR/reference/RELEASING.md +++ b/docs/pt-BR/reference/RELEASING.md @@ -1,284 +1,188 @@ --- read_when: - - Procurando definições públicas de canais de lançamento - - Executando validação de lançamento ou aceitação de pacote - - Procurando nomenclatura e cadência de versões -summary: Canais de lançamento, checklist do operador, caixas de validação, nomenclatura de versões e cadência + - 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 title: Política de lançamento x-i18n: - generated_at: "2026-05-03T21:36:44Z" + generated_at: "2026-05-04T07:03:56Z" model: gpt-5.5 provider: openai - source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba + source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw tem três canais públicos de lançamento: +OpenClaw tem três canais públicos de release: -- estável: versões marcadas 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` +- 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` ## Nomenclatura de versões -- Versão de lançamento estável: `YYYY.M.D` +- Versão de release estável: `YYYY.M.D` - Tag Git: `vYYYY.M.D` -- Versão de correção estável: `YYYY.M.D-N` +- Versão de release de correção estável: `YYYY.M.D-N` - Tag Git: `vYYYY.M.D-N` -- Versão beta de pré-lançamento: `YYYY.M.D-beta.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 zeros à esquerda -- `latest` significa a versão npm estável promovida atual -- `beta` significa o alvo atual de instalação beta -- Lançamentos estáveis e de correção estável publicam no npm `beta` por padrão; operadores de release podem mirar `latest` explicitamente, ou promover uma build beta validada posteriormente -- Todo lançamento estável do OpenClaw entrega o pacote npm e o app macOS juntos; - lançamentos beta normalmente validam e publicam primeiro o caminho npm/pacote, com +- Não preencha mês ou dia com zero à esquerda +- `latest` significa o release npm estável promovido atual +- `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 -## Cadência de lançamento +## Cadência de release -- Lançamentos seguem primeiro para beta -- Estável vem somente depois que o beta mais recente é validado -- Mantenedores normalmente criam lançamentos a partir de uma branch `release/YYYY.M.D` criada - a partir do `main` atual, para que validação e correções de release não bloqueiem novo - desenvolvimento no `main` +- 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 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 - exclusivos para mantenedores + apenas para mantenedores ## Checklist do operador de release -Este checklist é a forma pública do fluxo de release. Credenciais privadas, +Este checklist é o formato público do fluxo de release. Credenciais privadas, assinatura, notarização, recuperação de dist-tag e detalhes de rollback de emergência ficam no -runbook de release exclusivo para mantenedores. +runbook de release restrito a mantenedores. -1. Comece do `main` atual: baixe a versão mais recente, confirme que o commit alvo foi enviado, - e confirme que o CI atual do `main` está verde o suficiente para criar uma branch a partir dele. -2. Reescreva a seção superior do `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 +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. +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 registros de compatibilidade de release em +3. Revise os registros de compatibilidade de release 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á sendo mantida intencionalmente. -4. Crie `release/YYYY.M.D` a partir do `main` atual; não faça trabalho normal de release - diretamente no `main`. -5. Atualize todos os locais de versão obrigatórios para a tag pretendida, execute - `pnpm plugins:sync` para que pacotes de Plugin publicáveis compartilhem a versão de release - e os metadados de compatibilidade, então execute o preflight determinístico local: +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: `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 somente para validação - preflight. Salve o `preflight_run_id` bem-sucedido. + um SHA completo de 40 caracteres da branch de release é 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 execute novamente o menor - arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo que - comprove a correção. Execute novamente o guarda-chuva completo somente quando a superfície - alterada tornar evidências anteriores obsoletas. -9. Para beta, marque `vYYYY.M.D-beta.N`, então execute `OpenClaw Release Publish` a partir +8. Se a validação falhar, corrija na branch de release e reexecute o menor + arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo com falha que + comprove a correção. Reexecute o guarda-chuva completo somente quando a superfície alterada tornar + as evidências anteriores obsoletas. +9. Para beta, marque `vYYYY.M.D-beta.N`, depois execute `OpenClaw Release Publish` a partir da branch `release/YYYY.M.D` correspondente. Ele verifica `pnpm plugins:sync:check`, - publica todos os pacotes de Plugin publicáveis no npm primeiro, publica o mesmo - conjunto no ClawHub em seguida como tarballs npm-pack ClawPack e então promove o - artefato 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 - `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 estável, continue somente depois que o beta validado ou candidato a release tiver a - evidência de validação necessária. A publicação npm estável também passa por - `OpenClaw Release Publish`, reutilizando o artefato preflight bem-sucedido via - `preflight_run_id`; a prontidão para release estável do macOS também exige os - `.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado no `main`. + 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 + 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 + `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`. 11. Após publicar, execute o verificador npm pós-publicação, o E2E opcional do Telegram - publicado via npm independente quando você precisar de prova de canal pós-publicação, + 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 do `CHANGELOG.md` e as etapas de anúncio de release. + seção completa correspondente de `CHANGELOG.md`, e as etapas de anúncio de release. ## Preflight de release -- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript dos testes continue - coberto fora do gate local mais rápido `pnpm check` -- Execute `pnpm check:architecture` antes do preflight de release para que as verificações mais amplas de ciclo de importação - e limites de arquitetura estejam verdes fora do gate local mais rápido -- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados - `dist/*` e o pacote 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 marcar a tag. Ele - atualiza as versões dos pacotes de Plugin 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 core. `pnpm plugins:sync:check` é a proteção de release sem mutação; - o workflow de publicação falha antes de qualquer mutação no registro 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 de 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 Docker, - live/E2E, OpenWebUI, paridade do QA Lab, Matrix e faixas Telegram. Com - `release_profile=full` e `rerun_group=all`, ele também executa o E2E de pacote - Telegram contra o artefato `release-package-under-test` dos checks de release. Forneça - `npm_telegram_package_spec` após a publicação quando o mesmo E2E Telegram também deve comprovar 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 entregue em vez - do artefato construído a partir do SHA. Forneça - `evidence_package_spec` quando o relatório privado de evidências deve comprovar que a - validação corresponde a um pacote npm publicado sem forçar o E2E Telegram. - Exemplo: +- 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: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 uma comprovação paralela - para um candidato a pacote enquanto o trabalho de release continua. Use `source=npm` para - `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` - para empacotar uma branch/tag/SHA confiável de `package_ref` com o harness atual - `workflow_ref`; `source=url` para um tarball HTTPS com um SHA-256 obrigatório; - ou `source=artifact` para um tarball enviado por outro run 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 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 baseline publicada. +- 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. 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 config - - `package`: faixas nativas de artefato para pacote/atualização/Plugin sem OpenWebUI ou ClawHub live + - `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 - - `full`: blocos de caminho de release Docker com OpenWebUI - - `custom`: seleção exata de `docker_lanes` para uma nova execução focada -- Execute o workflow manual `CI` diretamente quando precisar apenas da cobertura completa normal de CI - para o candidato a release. Disparos manuais de CI ignoram o escopo por mudanças - e forçam os shards Linux Node, shards de plugins incluídos, contratos de canal, - compatibilidade com Node 22, `check`, `check-additional`, smoke de build, - checks de documentação, Skills Python, Windows, macOS, Android e faixas de i18n - da Control UI. + - `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. Exemplo: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Execute `pnpm qa:otel:smoke` ao validar a telemetria de release. Ele exercita - o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes 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 todo release com tag -- Execute `OpenClaw Release Publish` para a sequência de publicação com mutaçã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 Plugin - `all-publishable`, a menos que você esteja executando deliberadamente um reparo focado. O - workflow serializa a publicação npm de Plugin, a publicação de Plugin no ClawHub e a publicação npm - do OpenClaw para que o pacote core não seja publicado antes de seus - plugins externalizados. -- Os checks de release agora rodam em um workflow manual separado: +- 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 rápido - live Matrix e a faixa QA Telegram antes da aprovação de release. As faixas live - usam o ambiente `qa-live-shared`; Telegram também usa concessões de credenciais Convex CI. - Execute o workflow manual `QA-Lab - All Lanes` com - `matrix_profile=all` e `matrix_shards=true` quando quiser 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 - `OpenClaw Release Checks` e `Full Release Validation` públicos, que chamam diretamente - o workflow reutilizável - `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Essa separação é intencional: manter o caminho real de release npm curto, - determinístico e focado em artefatos, enquanto checks live mais lentos ficam em sua - própria faixa para não atrasarem nem bloquearem a publicação -- Checks de release com segredos devem ser disparados 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 uma branch, tag ou SHA completo de commit desde que - o commit resolvido seja alcançável a partir de uma 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 da branch do workflow sem exigir uma tag enviada -- Esse caminho por SHA é somente de validação e não pode ser promovido para uma publicação real -- No modo SHA, o workflow sintetiza `v` apenas para a - verificação de metadados do pacote; a publicação real ainda exige uma tag real de release -- 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 sem mutação pode usar os runners Linux maiores - da Blacksmith +- `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 +- 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 checks de release +- 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 - do registro publicado em um prefixo temporário novo + (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 o onboarding do pacote instalado, a configuração do Telegram e o E2E real do Telegram - contra o pacote npm publicado usando o pool compartilhado de credenciais Telegram concedidas. - Execuções locais pontuais de mantenedores podem omitir as vars Convex e passar diretamente as três - credenciais de env `OPENCLAW_QA_TELEGRAM_*`. -- Mantenedores podem executar o mesmo check pós-publicação pelo GitHub Actions por meio do - workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e - não roda a cada merge. -- A automação de release de mantenedores agora usa preflight-depois-promover: - - a publicação npm real deve passar por um `preflight_run_id` npm bem-sucedido + 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` que o run de preflight bem-sucedido + `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 fica em + - 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 - 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 uma + 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 para mac deve passar por `preflight_run_id` e `validate_run_id` - privados de mac bem-sucedidos - - os caminhos reais de publicação promovem artefatos preparados em vez de reconstruí-los - novamente -- Para releases estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação - também verifica o mesmo caminho de upgrade com prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, - para que correções de release não deixem silenciosamente instalações globais mais antigas no - payload estável base -- O preflight de release npm falha fechado a menos que o tarball inclua tanto - `dist/control-ui/index.html` quanto um payload não vazio de `dist/control-ui/assets/` - para que não publiquemos novamente um painel de navegador vazio -- A verificação pós-publicação também confere que os entrypoints de Plugin publicados e - os metadados de pacote estão presentes no layout instalado do registro. Um release que - entrega payloads de runtime de Plugin ausentes falha no verificador pós-publicação e - não pode ser promovido para `latest`. -- `pnpm test:install:smoke` também aplica o orçamento de `unpackedSize` do pacote npm no - tarball candidato de atualização, para que o e2e do instalador capture crescimento acidental do pacote - antes do caminho de publicação de release -- Se o trabalho de release tocou o planejamento de CI, manifests de timing de extensions ou - matrizes de teste de extensions, regenere e revise as saídas de matriz - `plugin-prerelease-extension-shard` pertencentes ao planejador 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 para macOS também inclui as superfícies do atualizador: - - o release no GitHub deve terminar com os arquivos `.zip`, `.dmg` e `.dSYM.zip` empacotados + - a publicação privada real do 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 - - o app empacotado deve manter um bundle id que não seja de debug, uma URL de feed Sparkle - não vazia e um `CFBundleVersion` no piso canônico de build Sparkle - ou acima dele para essa versão de release + - 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 de pré-release a partir de -um único ponto de entrada. Para uma comprovação de commit fixado em uma branch que muda rapidamente, use o -helper para que todo workflow filho rode a partir de uma branch temporária fixada no SHA -alvo: +`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: ```bash pnpm ci:full-release --sha ``` -O auxiliar faz push de `release-ci/-...`, dispara `Full Release Validation` -a partir dessa branch com `ref=`, verifica se cada workflow filho `headSha` -corresponde ao alvo e então exclui a branch temporária. Isso evita validar por -acidente uma execução filha de um `main` mais recente. +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. -Para validação de branch ou tag de lançamento, execute-o a partir da ref -confiável de workflow `main` e passe a branch ou tag de lançamento como `ref`: +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`: ```bash gh workflow run full-release-validation.yml \ @@ -290,39 +194,50 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -O fluxo de trabalho resolve o 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 independente do pacote Telegram quando `release_profile=full` com -`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. `OpenClaw Release -Checks` então expande para smoke de instalação, verificações de lançamento entre sistemas operacionais, cobertura live/E2E do caminho de lançamento do Docker, Package Acceptance com QA do pacote Telegram, paridade do QA Lab, Matrix ao vivo e Telegram ao vivo. 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 a -matriz completa de estágios, nomes exatos dos jobs do fluxo de trabalho, diferenças entre perfis estável e completo, artefatos e identificadores de reexecução focada. -Fluxos de trabalho filhos são disparados a partir do ref confiável que executa `Full Release -Validation`, normalmente `--ref main`, mesmo quando o `ref` de destino aponta para um -branch ou tag de lançamento mais antigo. Não há uma entrada separada de ref de fluxo de trabalho para Full Release Validation; escolha o harness confiável escolhendo o ref da execução do fluxo de trabalho. -Não use `--ref main -f ref=` para comprovação exata de commit em `main` móvel; -SHAs de commit brutos não podem ser refs de despacho de fluxo de trabalho, então use -`pnpm ci:full-release --sha ` para criar o branch temporário fixado. +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. -Use `release_profile` para selecionar a abrangência live/provedor: +Use `release_profile` para selecionar a amplitude live/de provedor: -- `minimum`: caminho mais rápido crítico para lançamento de OpenAI/core live e Docker -- `stable`: mínimo mais cobertura estável de provedor/backend para aprovação de lançamento -- `full`: estável mais cobertura ampla de provedor/mídia consultiva +- `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 -`OpenClaw Release Checks` usa o ref confiável do fluxo de trabalho para resolver o ref de destino -uma vez como `release-package-under-test` e reutiliza esse artefato tanto nas verificações Docker de caminho de lançamento quanto no Package Acceptance. Isso mantém todas as caixas voltadas a pacote nos mesmos bytes e evita builds repetidos de pacote. -O smoke de instalação OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a -variável de repositório/org está definida, caso contrário `openai/gpt-5.4`, porque essa lane está -comprovando instalação do pacote, onboarding, inicialização do gateway e uma rodada de agente ao vivo -em vez de medir o desempenho do modelo padrão mais lento. A matriz live de provedores mais ampla -continua sendo o local para cobertura específica de modelo. +`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 estas variantes dependendo do estágio de lançamento: @@ -354,35 +269,47 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Não use o guarda-chuva completo como a primeira reexecução após uma correção focada. Se uma caixa -falhar, use o fluxo de trabalho filho, job, lane Docker, perfil de pacote, provedor de modelo -ou lane de QA que falhou para a próxima comprovação. Execute o guarda-chuva completo novamente apenas quando -a correção alterou a orquestração compartilhada de lançamento ou tornou obsoleta a evidência anterior de todas as caixas. O verificador final do guarda-chuva verifica novamente os ids registrados das execuções dos fluxos de trabalho filhos, então, depois que um fluxo de trabalho filho for reexecutado com sucesso, reexecute apenas o job pai +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 `Verify full validation` que falhou. -Para recuperação delimitada, passe `rerun_group` para o guarda-chuva. `all` é a execução real -de candidato a lançamento, `ci` executa apenas o filho normal de CI, `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`. -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. +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. ### Vitest -A caixa Vitest é o fluxo de trabalho filho `CI` manual. O CI manual intencionalmente -contorna o escopo por alterações e força o grafo normal de testes para o candidato a lançamento: shards Linux Node, shards de plugins empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e i18n da Control UI. +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. -Use esta caixa para responder "a árvore de código-fonte passou pela suíte normal completa de testes?" -Ela não é o mesmo que validação de produto no caminho de lançamento. Evidências a manter: +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: -- resumo de `Full Release Validation` mostrando a URL da execução de `CI` disparada -- execução de `CI` verde no SHA exato de destino +- resumo de `Full Release Validation` mostrando a URL da execução `CI` despachada +- execução `CI` verde no SHA de destino exato - nomes de shards com falha ou lentos dos jobs de CI ao investigar regressões -- artefatos de tempo do Vitest, como `.artifacts/vitest-shard-timings.json`, quando - uma execução precisar de análise de desempenho +- artefatos de 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 apenas 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 lançamento precisar de CI normal +determinístico, mas não das caixas Docker, QA Lab, live, entre sistemas +operacionais ou de pacote: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -390,18 +317,18 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -A caixa Docker vive em `OpenClaw Release Checks` por meio de -`openclaw-live-and-e2e-checks-reusable.yml`, além do fluxo de trabalho `install-smoke` -em modo de lançamento. Ela valida o candidato a lançamento por ambientes Docker empacotados -em vez de apenas testes em nível de código-fonte. +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 cobertura Docker de lançamento inclui: - smoke completo de instalação com o smoke lento de instalação global Bun habilitado -- preparação/reutilização da imagem de smoke do Dockerfile raiz por SHA de destino, com QR, - root/gateway e jobs de smoke de instalador/Bun executando como shards separados de install-smoke +- 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 de caminho de lançamento: `core`, `package-update-openai`, +- chunks Docker do caminho de lançamento: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, @@ -409,85 +336,98 @@ 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 plugins empacotados - `bundled-plugin-install-uninstall-0` até +- lanes divididas de instalação/desinstalação de plugin agrupado, + de `bundled-plugin-install-uninstall-0` até `bundled-plugin-install-uninstall-23` -- suítes de provedores live/E2E e cobertura de modelo Docker live quando as verificações de lançamento - incluem suítes live +- suítes live/E2E de provedores e cobertura de modelo live em Docker quando as verificações + de lançamento incluem suítes live -Use artefatos Docker antes de reexecutar. O agendador de caminho de lançamento envia -`.artifacts/docker-tests/` com logs de lanes, `summary.json`, `failures.json`, -tempos de fases, JSON do plano do agendador e comandos de reexecução. Para recuperação focada, -use `docker_lanes=` no fluxo de trabalho live/E2E reutilizável em vez de -reexecutar todos os chunks de lançamento. 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 imagens GHCR. +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. ### QA Lab -A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de lançamento de comportamento agêntico e de nível de canal, separada da mecânica de pacote do Vitest e do Docker. +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 cobertura QA Lab de lançamento inclui: - lane de paridade mock comparando a lane candidata OpenAI com a baseline Opus 4.6 - usando o pacote de paridade agêntica + usando o pacote de paridade agentiva - perfil rápido de QA Matrix live usando o ambiente `qa-live-shared` -- lane de QA Telegram live usando leases de credenciais Convex CI -- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de comprovação local explícita +- 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 -Use esta caixa para responder "o lançamento se comporta corretamente em cenários de QA e -fluxos de canais live?" Mantenha as URLs de artefatos para as lanes de paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura completa de Matrix continua disponível como uma -execução manual shardada do QA-Lab, em vez da lane crítica padrão de lançamento. +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. ### Pacote -A caixa Package é o gate de produto instalável. Ela é apoiada por +A caixa Pacote é o gate do produto instalável. Ela é apoiada 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 o -ref do harness do fluxo de trabalho separado do ref de origem 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 o SHA-256, e mantém a ref do +harness do workflow separada da ref do código-fonte 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`: empacote um branch, tag ou SHA completo de commit de `package_ref` confiável +- `source=ref`: empacota um branch, tag ou SHA completo de commit de `package_ref` confiável com o harness `workflow_ref` selecionado -- `source=url`: baixe um `.tgz` HTTPS com `package_sha256` obrigatório -- `source=artifact`: reutilize um `.tgz` enviado por outra execução do GitHub Actions +- `source=url`: baixa um `.tgz` HTTPS com `package_sha256` obrigatório +- `source=artifact`: reutiliza um `.tgz` enviado por outra execução do GitHub Actions `OpenClaw Release Checks` executa Package Acceptance com `source=artifact`, o -artefato preparado do pacote de lançamento, `suite_profile=custom`, +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`. Package Acceptance mantém migração, atualização, limpeza de dependências obsoletas de plugins, fixtures de plugins offline, atualização de plugins e QA de pacote Telegram contra o mesmo tarball resolvido. A matriz de upgrade cobre toda baseline estável publicada no npm de `2026.4.23` até `latest`; use -Package Acceptance com `source=npm` para um candidato já lançado, ou -`source=ref`/`source=artifact` para um tarball npm local respaldado por SHA antes da -publicação. Ela é a substituição nativa do GitHub -para a maior parte da cobertura de pacote/atualização que antes exigia -Parallels. Verificações de lançamento entre sistemas operacionais ainda importam para onboarding, -instalador e comportamento 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. 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. 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 release-check comprova 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 fluxo de trabalho manual `Update Migration` separado, não parte do Full Release CI. +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. -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, ausência de -`gateway install --wrapper`, arquivos de patch ausentes na fixture git derivada do tarball, -ausência de `update.channel` persistido, locais legados de registro de instalação de plugins, -ausência de persistência de registro de instalação do marketplace e migração de metadados de configuração durante `plugins update`. O pacote publicado `2026.4.26` pode avisar -sobre arquivos locais de carimbo de metadados de build que já foram lançados. Pacotes posteriores -devem satisfazer os contratos modernos de pacote; essas mesmas lacunas falham na validação de lançamento. +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. -Use perfis mais amplos de Package Acceptance quando a pergunta de lançamento for sobre um -pacote realmente instalável: +Use perfis Package Acceptance mais amplos quando a pergunta de lançamento for +sobre um pacote instalável real: ```bash gh workflow run package-acceptance.yml \ @@ -501,33 +441,33 @@ gh workflow run package-acceptance.yml \ Perfis comuns de pacote: -- `smoke`: lanes rápidas de instalação de pacote/canal/agente, rede do Gateway e +- `smoke`: faixas 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 release -- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa na web da OpenAI +- `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 release do Docker com OpenWebUI +- `full`: partes do caminho de lançamento Docker com OpenWebUI - `custom`: lista exata de `docker_lanes` para reexecuções focadas -Para comprovação de Telegram de pacote candidato, habilite `telegram_mode=mock-openai` ou -`telegram_mode=live-frontier` em 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. +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. -## Automação de publicação de release +## Automação de publicação de lançamento -`OpenClaw Release Publish` é o ponto de entrada normal de publicação mutante. Ele -orquestra os workflows de publicador confiável na ordem necessária para a 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: -1. Fazer checkout da tag da release e resolver seu SHA de commit. -2. Verificar se a tag é acessível a partir de `main` ou `release/*`. +1. Fazer checkout da tag de lançamento 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 da release, a dist-tag npm e - o `preflight_run_id` salvo. +6. Disparar `OpenClaw NPM Release` com a tag de lançamento, a dist-tag npm e o + `preflight_run_id` salvo. Exemplo de publicação beta: @@ -549,7 +489,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Promoção estável diretamente para `latest` é explícita: +A promoção estável diretamente para `latest` é explícita: ```bash gh workflow run openclaw-release-publish.yml \ @@ -560,18 +500,18 @@ gh workflow run openclaw-release-publish.yml \ ``` Use os workflows de nível mais baixo `Plugin NPM Release` e `Plugin ClawHub Release` -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. +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. ## Entradas do workflow NPM `OpenClaw NPM Release` aceita estas entradas controladas pelo operador: -- `tag`: tag de release obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou - `v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA de commit completo - atual de 40 caracteres da branch do workflow para preflight somente de validação +- `tag`: tag de lançamento obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou + `v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA 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 caminho real de publicação - `preflight_run_id`: obrigatório no caminho real de publicação para que o workflow reutilize @@ -580,70 +520,70 @@ pacote OpenClaw não deve ser publicado. `OpenClaw Release Publish` aceita estas entradas controladas pelo operador: -- `tag`: tag de release obrigatória; já deve existir +- `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`; 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` somente +- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` apenas 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` somente ao usar o - workflow como orquestrador de reparo somente de Plugin +- `publish_openclaw_npm`: o padrão é `true`; defina como `false` apenas ao usar o + workflow como orquestrador de reparo somente de Plugins `OpenClaw Release Checks` aceita estas entradas controladas pelo operador: -- `ref`: branch, tag ou SHA de commit completo a validar. Verificações com segredos - exigem que o commit resolvido seja acessível a partir de uma branch do OpenClaw ou - tag de release. +- `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. Regras: - Tags estáveis e de correção podem publicar em `beta` ou `latest` -- Tags de pré-release beta podem publicar somente em `beta` -- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida somente quando +- 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 `preflight_only=true` - `OpenClaw Release Checks` e `Full Release Validation` são sempre - somente validação + apenas de validação - O caminho real de publicação deve usar o mesmo `npm_dist_tag` usado durante o preflight; - o workflow verifica esses metadados antes que a publicação continue + o workflow verifica esses metadados antes de a publicação continuar -## Sequência de release npm estável +## Sequência de lançamento npm estável -Ao preparar uma release npm estável: +Ao preparar um lançamento npm estável: 1. Execute `OpenClaw NPM Release` com `preflight_only=true` - - Antes de existir uma tag, você pode usar o SHA de commit completo atual da branch do workflow - para uma simulação somente de validação do workflow de preflight -2. Escolha `npm_dist_tag=beta` para o fluxo normal beta primeiro, ou `latest` somente + - 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` na branch da release, tag da release ou SHA de commit completo - quando quiser CI normal mais cache de prompt ao vivo, Docker, QA Lab, - Matrix e cobertura de Telegram a partir de um workflow manual -4. Se você intencionalmente só precisa do grafo de testes normal determinístico, execute o - workflow manual `CI` na ref da release em vez disso +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 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 a release caiu em `beta`, use o workflow privado +7. Se o lançamento chegou a `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 a release foi publicada intencionalmente diretamente em `latest` e `beta` - deve seguir a mesma build estável imediatamente, use o mesmo workflow privado +8. Se o lançamento 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 - agendada de autocorreção mover `beta` depois + autorreparadora agendada mover `beta` depois -A mutação de dist-tag fica no repositório privado por segurança, porque ela ainda -exige `NPM_TOKEN`, enquanto o repositório público mantém publicação somente com OIDC. +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. -Isso mantém o caminho de publicação direta e 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`) 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. +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. ## Referências públicas @@ -657,10 +597,10 @@ alertas e tratamento de OTP observáveis e evita alertas repetidos do 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 a documentação privada de release em +Mantenedores usam os documentos privados de lançamento em [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) para o runbook real. ## Relacionado -- [Canais de release](/pt-BR/install/development-channels) +- [Canais de lançamento](/pt-BR/install/development-channels) diff --git a/docs/pt-BR/web/control-ui.md b/docs/pt-BR/web/control-ui.md index 9fe7342d1..575371292 100644 --- a/docs/pt-BR/web/control-ui.md +++ b/docs/pt-BR/web/control-ui.md @@ -1,20 +1,20 @@ --- read_when: - - Você quer operar o Gateway a partir de um navegador + - Você deseja operar o Gateway a partir de um navegador - Você quer acesso à Tailnet sem túneis SSH sidebarTitle: Control UI -summary: UI de controle baseada no navegador para o Gateway (chat, nós, configuração) +summary: Interface de controle baseada no navegador para o Gateway (chat, nós, configuração) title: Interface de controle x-i18n: - generated_at: "2026-05-04T05:56:07Z" + generated_at: "2026-05-04T07:04:08Z" model: gpt-5.5 provider: openai - source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644 + source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5 source_path: web/control-ui.md workflow: 16 --- -A Interface de Controle é um pequeno aplicativo de página única **Vite + Lit** servido pelo Gateway: +A UI de Controle é um pequeno app de página única **Vite + Lit** servido pelo Gateway: - padrão: `http://:18789/` - prefixo opcional: defina `gateway.controlUi.basePath` (por exemplo, `/openclaw`) @@ -36,117 +36,117 @@ A autenticação é fornecida durante o handshake do WebSocket por meio de: - 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"` -O painel de configurações do dashboard mantém um token para a sessão atual da aba do navegador e a URL do gateway selecionada; senhas não são persistidas. A integração inicial normalmente gera um token de gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`. +O painel de configurações do dashboard mantém um token para a sessão da aba atual do navegador e para a URL do gateway selecionada; senhas não são persistidas. O onboarding geralmente gera um token do gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`. ## Pareamento de dispositivo (primeira conexão) -Quando você se conecta à Interface de Controle a partir de um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Esta é uma medida de segurança para impedir acesso não autorizado. +Quando você se conecta à UI de Controle por um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Esta é uma medida de segurança para impedir acesso não autorizado. -**O que você verá:** "desconectado (1008): pareamento necessário" +**O que você verá:** "desconectado (1008): pareamento obrigatório" - + ```bash openclaw devices list ``` - + ```bash openclaw devices approve ``` -Se o navegador tentar novamente o pareamento com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute `openclaw devices list` novamente antes da aprovação. +Se o navegador tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute `openclaw devices list` novamente antes da aprovação. -Se o navegador já estiver pareado e você alterá-lo de acesso de leitura para acesso de escrita/administrador, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e solicita que você aprove explicitamente o novo conjunto de escopos. +Se o navegador já estiver pareado e você o alterar de acesso de leitura para acesso de escrita/admin, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e solicita que você aprove explicitamente o novo conjunto de escopos. Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com `openclaw devices revoke --device --role `. Consulte [CLI de Dispositivos](/pt-BR/cli/devices) para rotação e revogação de tokens. - Conexões diretas de navegador por local loopback (`127.0.0.1` / `localhost`) são aprovadas automaticamente. -- O Tailscale Serve pode pular a etapa de pareamento para sessões de operador da Interface de Controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo. -- Vinculações diretas à Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita. -- Cada perfil de navegador gera um ID de dispositivo único, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento. +- O Tailscale Serve pode pular a rodada de pareamento para sessões de operador da UI de Controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo. +- Vínculos diretos de Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita. +- Cada perfil de navegador gera um ID de dispositivo exclusivo, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento. ## Identidade pessoal (local do navegador) -A Interface de Controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada às mensagens enviadas para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, é limitada ao perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria da transcrição nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador redefine essa identidade para vazia. +A UI de Controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada às mensagens de saída para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, tem escopo no perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria do transcript nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador redefine isso para vazio. -O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca passam por ida e volta via `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes não UI que escrevem o campo diretamente (como gateways com scripts ou dashboards personalizados). +O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca fazem ida e volta por `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes que não sejam de UI gravarem o campo diretamente (como gateways roteirizados ou dashboards personalizados). -## Endpoint de configuração de runtime +## Endpoint de configuração em runtime -A Interface de Controle busca suas configurações de runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável. +A UI de Controle busca suas configurações em runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável. ## Suporte a idiomas -A Interface de Controle pode se localizar automaticamente no primeiro carregamento com base na localidade do seu navegador. Para substituí-la depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência. +A UI de Controle pode se localizar no primeiro carregamento com base no idioma do seu navegador. Para substituí-lo depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência. - Localidades compatíveis: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- Traduções para idiomas não ingleses são carregadas sob demanda no navegador. +- Traduções para idiomas diferentes do inglês são carregadas sob demanda no navegador. - A localidade selecionada é salva no armazenamento do navegador e reutilizada em visitas futuras. -- Chaves de tradução ausentes recorrem ao inglês. +- Chaves de tradução ausentes usam inglês como fallback. -As traduções da documentação são geradas para o mesmo conjunto de localidades não inglesas, mas o seletor de idioma integrado do site de docs do Mintlify é limitado aos códigos de localidade aceitos pelo Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos. +As traduções da documentação são geradas para o mesmo conjunto de localidades diferentes do inglês, mas o seletor de idiomas integrado do site de documentação do Mintlify é limitado aos códigos de localidade aceitos pelo Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos. ## Temas de aparência -O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o [editor tweakcn](https://tweakcn.com/editor/theme), escolha ou crie um tema, clique em **Compartilhar** e cole o link de tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/`, IDs de tema brutos e nomes de tema padrão como `amethyst-haze`. +O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o [editor tweakcn](https://tweakcn.com/editor/theme), escolha ou crie um tema, clique em **Compartilhar** e cole o link do tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/`, IDs brutos de tema e nomes de tema padrão como `amethyst-haze`. -Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo muda o tema ativo de volta para Claw se o tema importado estava selecionado. +Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo troca o tema ativo de volta para Claw se o tema importado estava selecionado. -## O que ele pode fazer (hoje) +## O que ela consegue fazer (hoje) - - - Converse por chat com o modelo via WS do Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Converse por sessões realtime do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador limitado a um único uso via WebSocket, e plugins de voz realtime somente de backend usam o transporte de relay do Gateway. O relay mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo OpenClaw maior configurado. - - Transmita chamadas de ferramentas + cartões de saída de ferramenta ao vivo no Chat (eventos de agente). + + - Converse com o modelo via WS do Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). + - Converse por meio de sessões em tempo real do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador restrito e de uso único por WebSocket, e plugins de voz em tempo real somente de backend usam o transporte de retransmissão do Gateway. A retransmissão mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo OpenClaw maior configurado. + - Transmita chamadas de ferramenta + cartões de saída de ferramenta ao vivo no Chat (eventos do agente). - - Canais: status de canais integrados e de canais de plugins incluídos/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`). + - Canais: status de canais integrados e de canais de plugins empacotados/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`). - Instâncias: lista de presença + atualização (`system-presence`). - - Sessões: lista + substituições por sessão de modelo/thinking/rápido/detalhado/rastreamento/raciocínio (`sessions.list`, `sessions.patch`). - - Dreams: status de dreaming, alternância de ativar/desativar e leitor do Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + - Sessões: lista + substituições por sessão de modelo/thinking/rápido/verboso/trace/reasoning (`sessions.list`, `sessions.patch`). + - Dreams: status de dreaming, alternância para ativar/desativar e leitor do Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - - Tarefas Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (`cron.*`). + + - Jobs de Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execuções (`cron.*`). - Skills: status, ativar/desativar, instalar, atualizações de chave de API (`skills.*`). - Nodes: lista + capacidades (`node.list`). - - Aprovações de exec: editar allowlists de gateway ou node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`). + - Aprovações de exec: editar allowlists do gateway ou node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`). - Visualize/edite `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - - Aplique + reinicie com validação (`config.apply`) e desperte a última sessão ativa. + - Aplique + reinicie com validação (`config.apply`) e acorde a última sessão ativa. - Gravações incluem uma proteção por hash base para evitar sobrescrever edições concorrentes. - - Gravações (`config.set`/`config.apply`/`config.patch`) fazem uma pré-verificação da resolução de SecretRef ativa para refs no payload de configuração enviado; refs enviadas ativas não resolvidas são rejeitadas antes da gravação. - - Esquema + renderização de formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de docs em nós aninhados de objeto/curinga/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto fica disponível apenas quando o snapshot tem uma ida e volta bruta segura. - - Se um snapshot não conseguir fazer ida e volta segura do texto bruto, a Interface de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot. - - O editor JSON bruto "Redefinir para salvo" preserva a forma escrita em bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, para que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança. - - Valores estruturados de objeto SecretRef são renderizados como somente leitura em entradas de texto de formulário para evitar corrupção acidental de objeto para string. + - Gravações (`config.set`/`config.apply`/`config.patch`) fazem pré-validação da resolução de SecretRef ativa para refs no payload de configuração enviado; refs enviadas ativas não resolvidas são rejeitadas antes da gravação. + - Renderização de esquema + formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de documentação em nodes aninhados de objeto/wildcard/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto só fica disponível quando o snapshot tem uma ida e volta bruta segura. + - Se um snapshot não puder fazer ida e volta de texto bruto com segurança, a UI de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot. + - "Redefinir para salvo" no editor JSON bruto preserva o formato autorado em bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, de modo que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança. + - Valores de objeto SecretRef estruturados são renderizados como somente leitura em entradas de texto do formulário para evitar corrupção acidental de objeto para string. - - Depuração: snapshots de status/health/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`). - - Logs: tail ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`). - - Atualização: execute uma atualização de pacote/git + reinício (`update.run`) com um relatório de reinício e, em seguida, consulte `update.status` após a reconexão para verificar a versão do gateway em execução. + - Depuração: snapshots de status/saúde/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`). + - Logs: acompanhamento ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`). + - Atualização: execute uma atualização de pacote/git + reinicie (`update.run`) com um relatório de reinicialização e, depois, consulte `update.status` após reconectar para verificar a versão do gateway em execução. - - - Para tarefas isoladas, a entrega usa anúncio de resumo por padrão. Você pode mudar para nenhuma se quiser execuções apenas internas. - - Campos de canal/destino aparecem quando anúncio é selecionado. + + - Para jobs isolados, a entrega usa resumo de anúncio como padrão. Você pode mudar para nenhuma se quiser execuções apenas internas. + - Os campos de canal/destino aparecem quando anúncio é selecionado. - O modo Webhook usa `delivery.mode = "webhook"` com `delivery.to` definido como uma URL de webhook HTTP(S) válida. - - Para tarefas da sessão principal, os modos de entrega webhook e nenhuma ficam disponíveis. - - Controles avançados de edição incluem excluir após execução, limpar substituição de agente, opções cron exato/escalonado, substituições de modelo/thinking do agente e alternâncias de entrega por melhor esforço. - - A validação de formulário é inline com erros por campo; valores inválidos desativam o botão de salvar até serem corrigidos. + - Para jobs de sessão principal, os modos de entrega Webhook e nenhuma estão disponíveis. + - Controles de edição avançada incluem excluir após execução, limpar substituição de agente, opções exatas/escalonadas de cron, substituições de modelo/thinking do agente e alternâncias de entrega por melhor esforço. + - A validação do formulário é inline com erros por campo; valores inválidos desativam o botão de salvar até serem corrigidos. - Defina `cron.webhookToken` para enviar um token bearer dedicado; se omitido, o webhook é enviado sem cabeçalho de autenticação. - - Fallback obsoleto: tarefas legadas armazenadas com `notify: true` ainda podem usar `cron.webhook` até serem migradas. + - Fallback obsoleto: jobs legados armazenados com `notify: true` ainda podem usar `cron.webhook` até serem migrados. @@ -155,62 +155,62 @@ Temas importados são armazenados apenas no perfil atual do navegador. Eles não - - `chat.send` é **não bloqueante**: confirma imediatamente com `{ runId, status: "started" }` e a resposta é transmitida por eventos `chat`. - - Uploads de chat aceitam imagens e arquivos que não sejam vídeo. Imagens mantêm o caminho nativo da imagem; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo. + - `chat.send` é **não bloqueante**: confirma imediatamente com `{ runId, status: "started" }` e a resposta é transmitida via eventos `chat`. + - Uploads de chat aceitam imagens e arquivos que não sejam vídeos. Imagens mantêm o caminho de imagem nativo; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo. - Reenviar com o mesmo `idempotencyKey` retorna `{ status: "in_flight" }` enquanto estiver em execução, e `{ status: "ok" }` após a conclusão. - - As respostas de `chat.history` têm limite de tamanho para segurança da UI. Quando as entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder (`[chat.history omitted: message too large]`). - - Imagens geradas/pelo assistente são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, então recarregamentos não dependem de payloads brutos de imagem em base64 permanecerem na resposta do histórico do chat. - - `chat.history` também remove tags de diretivas inline somente de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamadas de ferramenta em texto simples (incluindo `...`, `...`, `...`, `...` e blocos truncados de chamadas de ferramenta), e tokens de controle de modelo ASCII/largura total vazados, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`. - - Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém mensagens locais otimistas do usuário/assistente visíveis se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway alcança o estado atual. - - Eventos `chat` ao vivo representam estado de entrega, enquanto `chat.history` é reconstruído a partir da transcrição durável da sessão. Após eventos finais de ferramenta, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição está documentado em [WebChat](/pt-BR/web/webchat). - - `chat.inject` anexa uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações somente da UI (sem execução do agente, sem entrega de canal). - - Os seletores de modelo e pensamento do cabeçalho do chat aplicam patches imediatamente na sessão ativa por meio de `sessions.patch`; eles são sobrescritas persistentes de sessão, não opções de envio válidas apenas para uma rodada. - - Digitar `/new` na Control UI cria e alterna para a mesma sessão nova de dashboard que Novo Chat. Digitar `/reset` mantém a redefinição explícita in-place do Gateway para a sessão atual. - - O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa lista de permissões orienta o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` e provedores com autenticação utilizável. O catálogo completo permanece disponível pelo RPC de depuração `models.list` com `view: "all"`. - - Quando relatórios novos de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat mostra um aviso de contexto e, em níveis recomendados de compaction, um botão compacto que executa o caminho normal de compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até o Gateway relatar uso novo novamente. + - As respostas de `chat.history` têm limite de tamanho para segurança da UI. Quando entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder (`[chat.history omitted: message too large]`). + - Imagens do assistente/geradas são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, para que recarregamentos não dependam de payloads brutos de imagem em base64 permanecerem na resposta do histórico de chat. + - `chat.history` também remove tags de diretivas inline apenas de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamadas de ferramenta em texto puro (incluindo `...`, `...`, `...`, `...` e blocos truncados de chamadas de ferramenta), além de tokens de controle do modelo ASCII/de largura cheia vazados, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`. + - Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém visíveis as mensagens locais otimistas do usuário/assistente se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway se atualiza. + - Eventos `chat` ao vivo são estado de entrega, enquanto `chat.history` é reconstruído a partir da transcrição durável da sessão. Após eventos finais de ferramenta, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição está documentado em [WebChat](/pt-BR/web/webchat). + - `chat.inject` anexa uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações apenas da UI (sem execução de agente, sem entrega por canal). + - Os seletores de modelo e de raciocínio no cabeçalho do chat aplicam patch à sessão ativa imediatamente por `sessions.patch`; eles são substituições persistentes de sessão, não opções de envio válidas apenas para uma interação. + - Digitar `/new` na Control UI cria e alterna para a mesma nova sessão do painel que New Chat. Digitar `/reset` mantém a redefinição explícita in-place do Gateway para a sessão atual. + - O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa lista de permissões orienta o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` e provedores com autenticação utilizável. O catálogo completo continua disponível pelo RPC de depuração `models.list` com `view: "all"`. + - Quando relatórios recentes de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat exibe um aviso de contexto e, nos níveis recomendados de Compaction, um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até que o Gateway relate uso recente novamente. - O modo de conversa usa um provedor de voz em tempo real registrado. Configure a OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure o Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração do provedor em tempo real de Chamada de Voz ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API padrão do provedor. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação Live API restrito de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramentas travadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, então credenciais e sockets de fornecedores ficam no lado do servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita sobrescritas de instrução fornecidas pelo chamador. + O modo de conversa usa um provedor de voz em tempo real registrado. Configure a OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure o Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração do provedor em tempo real de Voice Call ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API padrão do provedor. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação Live API restrito e de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramentas bloqueadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, de modo que credenciais e sockets de fornecedor permaneçam no servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita substituições de instruções fornecidas pelo chamador. - No compositor de Chat, o controle de Conversa é o botão de ondas ao lado do botão de ditado por microfone. Quando a Conversa inicia, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por meio de `chat.send`. + No compositor de Chat, o controle Talk é o botão de ondas ao lado do botão de ditado por microfone. Quando Talk inicia, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por `chat.send`. - Smoke ao vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca de SDP WebRTC do navegador da OpenAI, a configuração WebSocket do navegador com token restrito do Google Live e o adaptador de navegador de retransmissão do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos. + Smoke ao vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca SDP do WebRTC de navegador da OpenAI, a configuração do WebSocket de navegador com token restrito do Google Live e o adaptador de navegador de retransmissão do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos. - Clique em **Parar** (chama `chat.abort`). - - Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Orientar** em uma mensagem na fila para injetar esse acompanhamento na rodada em execução. - - Digite `/stop` (ou frases independentes de aborto como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora de banda. - - `chat.abort` oferece suporte a `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão. + - Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Direcionar** em uma mensagem enfileirada para injetar esse acompanhamento na interação em execução. + - Digite `/stop` (ou frases autônomas de abortar como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora da banda. + - `chat.abort` aceita `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão. - - - Quando uma execução é abortada, o texto parcial do assistente ainda pode ser mostrado na UI. + + - Quando uma execução é abortada, texto parcial do assistente ainda pode ser mostrado na UI. - O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer. - - Entradas persistidas incluem metadados de aborto para que consumidores da transcrição consigam distinguir parciais de aborto da saída de conclusão normal. + - Entradas persistidas incluem metadados de abortamento para que consumidores da transcrição consigam distinguir parciais abortadas de saída de conclusão normal. -## Instalação PWA e push web +## Instalação PWA e web push -A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA independente. Web Push permite que o Gateway acorde a PWA instalada com notificações mesmo quando a aba ou a janela do navegador não está aberta. +A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA independente. Web Push permite que o Gateway acorde a PWA instalada com notificações mesmo quando a aba ou janela do navegador não está aberta. -| Superfície | O que faz | +| Superfície | O que faz | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | Manifesto PWA. Navegadores oferecem "Instalar app" quando ele fica acessível. | -| `ui/public/sw.js` | Service worker que trata eventos `push` e cliques em notificações. | -| `push/vapid-keys.json` (sob o diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads Web Push. | -| `push/web-push-subscriptions.json` | Endpoints persistidos de assinatura do navegador. | +| `ui/public/manifest.webmanifest` | Manifesto PWA. Navegadores oferecem "Instalar app" quando ele está acessível. | +| `ui/public/sw.js` | Service worker que lida com eventos `push` e cliques em notificações. | +| `push/vapid-keys.json` (no diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads de Web Push. | +| `push/web-push-subscriptions.json` | Endpoints de assinatura de navegador persistidos. | -Sobrescreva o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes): +Substitua o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` -- `OPENCLAW_VAPID_SUBJECT` (padrão: `mailto:openclaw@localhost`) +- `OPENCLAW_VAPID_SUBJECT` (o padrão é `mailto:openclaw@localhost`) -A Control UI usa estes métodos do Gateway com escopo limitado para registrar e testar assinaturas do navegador: +A Control UI usa estes métodos do Gateway com escopo restrito para registrar e testar assinaturas do navegador: - `push.web.vapidPublicKey` — busca a chave pública VAPID ativa. - `push.web.subscribe` — registra um `endpoint` mais `keys.p256dh`/`keys.auth`. @@ -218,7 +218,7 @@ A Control UI usa estes métodos do Gateway com escopo limitado para registrar e - `push.web.test` — envia uma notificação de teste para a assinatura do chamador. -Web Push é independente do caminho de retransmissão APNS do iOS (veja [Configuração](/pt-BR/gateway/configuration) para push apoiado por retransmissão) e do método `push.test` existente, que mira o pareamento móvel nativo. +Web Push é independente do caminho de retransmissão APNS do iOS (veja [Configuração](/pt-BR/gateway/configuration) para push com retransmissão) e do método `push.test` existente, que miram o pareamento móvel nativo. ## Embeds hospedados @@ -227,13 +227,13 @@ Mensagens do assistente podem renderizar conteúdo web hospedado inline com o sh - Desabilita a execução de scripts dentro de embeds hospedados. + Desativa a execução de scripts dentro de embeds hospedados. - - Permite embeds interativos enquanto mantém isolamento de origem; este é o padrão e geralmente é suficiente para jogos/widgets de navegador autossuficientes. + + Permite embeds interativos mantendo o isolamento de origem; esse é o padrão e normalmente é suficiente para jogos/widgets de navegador autossuficientes. - Adiciona `allow-same-origin` além de `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes. + Adiciona `allow-same-origin` sobre `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes. @@ -250,14 +250,14 @@ Exemplo: ``` -Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos gerados por agente e canvases interativos, `scripts` é a escolha mais segura. +Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos e canvases interativos gerados por agente, `scripts` é a escolha mais segura. -URLs externas absolutas de embed `http(s)` permanecem bloqueadas por padrão. Se você intencionalmente quiser que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`. +URLs absolutas externas de embed `http(s)` permanecem bloqueadas por padrão. Se você quiser intencionalmente que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`. ## Largura da mensagem de chat -Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem sobrescrevê-la sem corrigir o CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`: +Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem substituí-la sem aplicar patch ao CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`: ```json5 { @@ -269,13 +269,13 @@ Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implanta } ``` -O valor é validado antes de chegar ao navegador. Valores com suporte incluem comprimentos simples e porcentagens como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`. +O valor é validado antes de chegar ao navegador. Valores compatíveis incluem comprimentos e porcentagens simples, como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`. -## Acesso à tailnet (recomendado) +## Acesso pela tailnet (recomendado) - - Mantenha o Gateway no loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS: + + Mantenha o Gateway em local loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS: ```bash openclaw gateway --tailscale serve @@ -285,12 +285,12 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co - `https:///` (ou seu `gateway.controlUi.basePath` configurado) - Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar por cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e comparando-o ao cabeçalho, e só aceita essas solicitações quando elas chegam ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo do navegador, esse caminho Serve verificado também pula a rodada de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Então use `gateway.auth.mode: "token"` ou `"password"`. + Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar via cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e correspondendo-o ao cabeçalho, e aceita esses cabeçalhos apenas quando a solicitação chega ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo no navegador, esse caminho Serve verificado também pula a ida e volta de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Depois use `gateway.auth.mode: "token"` ou `"password"`. - Para esse caminho assíncrono de identidade Serve, tentativas de autenticação com falha para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Novas tentativas ruins concorrentes do mesmo navegador podem, portanto, mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo. + Para esse caminho assíncrono de identidade Serve, tentativas de autenticação malsucedidas para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Retentativas ruins concorrentes do mesmo navegador podem, portanto, mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo. - Autenticação Serve sem token pressupõe que o host do gateway é confiável. Se código local não confiável puder ser executado nesse host, exija autenticação por token/senha. + Autenticação Serve sem token pressupõe que o host do Gateway é confiável. Se código local não confiável puder ser executado nesse host, exija autenticação por token/senha. @@ -299,7 +299,7 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` - Então abra: + Depois abra: - `http://:18789/` (ou seu `gateway.controlUi.basePath` configurado) @@ -310,13 +310,13 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co ## HTTP inseguro -Se você abrir o dashboard por HTTP simples (`http://` ou `http://`), o navegador executa em um **contexto não seguro** e bloqueia WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo. +Se você abrir o painel por HTTP simples (`http://` ou `http://`), o navegador roda em um **contexto não seguro** e bloqueia WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo. Exceções documentadas: -- compatibilidade HTTP insegura somente para localhost com `gateway.controlUi.allowInsecureAuth=true` -- autenticação bem-sucedida da Control UI de operador por `gateway.auth.mode: "trusted-proxy"` -- exceção de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- compatibilidade com HTTP inseguro apenas em localhost com `gateway.controlUi.allowInsecureAuth=true` +- autenticação bem-sucedida de operador da Control UI por `gateway.auth.mode: "trusted-proxy"` +- opção de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **Correção recomendada:** use HTTPS (Tailscale Serve) ou abra a UI localmente: @@ -335,11 +335,11 @@ Exceções documentadas: } ``` - `allowInsecureAuth` é apenas uma alternância de compatibilidade local: + `allowInsecureAuth` é apenas uma opção local de compatibilidade: - - Ela permite que sessões da Control UI no localhost prossigam sem identidade do dispositivo em contextos HTTP não seguros. + - Ela permite que sessões localhost da Control UI continuem sem identidade do dispositivo em contextos HTTP não seguros. - Ela não ignora verificações de pareamento. - - Ela não relaxa os requisitos de identidade do dispositivo remoto (não localhost). + - Ela não relaxa os requisitos de identidade de dispositivo remoto (não localhost). @@ -354,14 +354,14 @@ Exceções documentadas: ``` - `dangerouslyDisableDeviceAuth` desativa as verificações de identidade do dispositivo da Control UI e é um rebaixamento grave de segurança. Reverta rapidamente após o uso emergencial. + `dangerouslyDisableDeviceAuth` desativa as verificações de identidade de dispositivo da Control UI e é uma redução grave de segurança. Reverta rapidamente após o uso emergencial. - - Uma autenticação bem-sucedida de proxy confiável pode admitir sessões **operator** da Control UI sem identidade do dispositivo. - - Isso **não** se estende a sessões da Control UI com função de nó. - - Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth). + - A autenticação trusted-proxy bem-sucedida pode admitir sessões **operator** da Control UI sem identidade do dispositivo. + - Isso **não** se estende a sessões da Control UI com função de node. + - Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação trusted-proxy; consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth). @@ -370,26 +370,36 @@ Consulte [Tailscale](/pt-BR/gateway/tailscale) para orientações de configuraç ## Política de segurança de conteúdo -A Control UI é fornecida com uma política `img-src` restrita: somente ativos de **mesma origem**, URLs `data:` e URLs `blob:` geradas localmente são permitidos. URLs de imagem remotas `http(s)` e relativas ao protocolo são rejeitadas pelo navegador e não emitem buscas de rede. +A Control UI é fornecida com uma política `img-src` restrita: somente ativos de **mesma origem**, URLs `data:` e URLs `blob:` geradas localmente são permitidas. URLs de imagem remotas `http(s)` e relativas a protocolo são rejeitadas pelo navegador e não emitem buscas de rede. O que isso significa na prática: - Avatares e imagens servidos em caminhos relativos (por exemplo, `/avatars/`) ainda são renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs `blob:` locais. -- URLs inline `data:image/...` ainda são renderizadas (úteis para payloads no protocolo). +- URLs `data:image/...` embutidas ainda são renderizadas (úteis para cargas dentro do protocolo). - URLs `blob:` locais criadas pela Control UI ainda são renderizadas. -- URLs de avatar remotas emitidas por metadados de canais são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/distintivo integrado, para que um canal comprometido ou malicioso não consiga forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador. +- URLs remotas de avatar emitidas pelos metadados do canal são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/selo integrado, para que um canal comprometido ou malicioso não possa forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador. -Você não precisa alterar nada para obter esse comportamento — ele está sempre ativo e não é configurável. +Você não precisa alterar nada para obter esse comportamento — ele está sempre ativado e não é configurável. ## Autenticação da rota de avatar Quando a autenticação do gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do gateway que o restante da API: -- `GET /avatar/` retorna a imagem do avatar somente para chamadores autenticados. `GET /avatar/?meta=1` retorna os metadados do avatar sob a mesma regra. -- Solicitações não autenticadas para qualquer uma das rotas são rejeitadas (correspondendo à rota irmã de mídia do assistente). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos. -- A própria Control UI encaminha o token do gateway como um cabeçalho bearer ao buscar avatares e usa URLs de blob autenticadas para que a imagem ainda seja renderizada em painéis. +- `GET /avatar/` retorna a imagem do avatar apenas para chamadores autenticados. `GET /avatar/?meta=1` retorna os metadados do avatar sob a mesma regra. +- Solicitações não autenticadas a qualquer uma das rotas são rejeitadas (correspondendo à rota irmã assistant-media). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos. +- A própria Control UI encaminha o token do gateway como um cabeçalho bearer ao buscar avatares e usa URLs blob autenticadas para que a imagem ainda seja renderizada em dashboards. -Se você desativar a autenticação do gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, em linha com o restante do gateway. +Se você desativar a autenticação do gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, alinhada ao restante do gateway. + +## Autenticação da rota de mídia do assistente + +Quando a autenticação do gateway está configurada, pré-visualizações de mídia local do assistente usam uma rota em duas etapas: + +- `GET /__openclaw__/assistant-media?meta=1&source=` exige a autenticação normal de operador da Control UI. O navegador envia o token do gateway como um cabeçalho bearer ao verificar a disponibilidade. +- Respostas de metadados bem-sucedidas incluem um `mediaTicket` de curta duração, com escopo limitado ao caminho exato da origem. +- URLs de imagem, áudio, vídeo e documento renderizadas pelo navegador usam `mediaTicket=` em vez do token ou da senha ativa do gateway. O tíquete expira rapidamente e não pode autorizar uma origem diferente. + +Isso mantém a renderização normal de mídia compatível com elementos de mídia nativos do navegador sem colocar credenciais reutilizáveis do gateway em URLs de mídia visíveis. ## Compilando a UI @@ -399,7 +409,7 @@ O Gateway serve arquivos estáticos de `dist/control-ui`. Compile-os com: pnpm ui:build ``` -Base absoluta opcional (quando você quiser URLs de ativos fixas): +Base absoluta opcional (quando você quiser URLs fixas de ativos): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -411,11 +421,11 @@ Para desenvolvimento local (servidor de desenvolvimento separado): pnpm ui:dev ``` -Depois aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`). +Em seguida, aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`). ## Depuração/testes: servidor de desenvolvimento + Gateway remoto -A Control UI é composta por arquivos estáticos; o destino do WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway é executado em outro lugar. +A Control UI consiste em arquivos estáticos; o destino WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway executa em outro lugar. @@ -439,17 +449,17 @@ A Control UI é composta por arquivos estáticos; o destino do WebSocket é conf - - `gatewayUrl` é armazenado no localStorage após o carregamento e removido da URL. - - Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique o valor de `gatewayUrl` para URL para que o navegador analise a string de consulta corretamente. - - `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez por compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap. - - `password` é mantido apenas na memória. - - Quando `gatewayUrl` está definido, a UI não faz fallback para credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. A falta de credenciais explícitas é um erro. + - `gatewayUrl` é armazenado em localStorage após o carregamento e removido da URL. + - Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique em URL o valor de `gatewayUrl` para que o navegador analise a string de consulta corretamente. + - `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e no Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez para compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap. + - `password` é mantido apenas em memória. + - Quando `gatewayUrl` está definido, a UI não recorre a credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. Credenciais explícitas ausentes são um erro. - Use `wss://` quando o Gateway estiver atrás de TLS (Tailscale Serve, proxy HTTPS etc.). - `gatewayUrl` só é aceito em uma janela de nível superior (não incorporada) para evitar clickjacking. - - Implantações da Control UI que não sejam de loopback devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações de desenvolvimento remotas. - - A inicialização do Gateway pode semear origens locais como `http://localhost:` e `http://127.0.0.1:` a partir do bind e da porta efetivos em tempo de execução, mas origens de navegadores remotos ainda precisam de entradas explícitas. - - Não use `gateway.controlUi.allowedOrigins: ["*"]` exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder ao host que eu estiver usando." - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem pelo cabeçalho Host, mas é um modo de segurança perigoso. + - Implantações não loopback da Control UI devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações remotas de desenvolvimento. + - A inicialização do Gateway pode semear origens locais como `http://localhost:` e `http://127.0.0.1:` a partir do bind e da porta efetivos em tempo de execução, mas origens remotas de navegador ainda precisam de entradas explícitas. + - Não use `gateway.controlUi.allowedOrigins: ["*"]` exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder a qualquer host que eu esteja usando". + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem por cabeçalho Host, mas é um modo de segurança perigoso. @@ -470,7 +480,7 @@ Detalhes de configuração de acesso remoto: [Acesso remoto](/pt-BR/gateway/remo ## Relacionados -- [Painel](/pt-BR/web/dashboard) — painel do gateway -- [Verificações de integridade](/pt-BR/gateway/health) — monitoramento de integridade do gateway +- [Dashboard](/pt-BR/web/dashboard) — dashboard do gateway +- [Health Checks](/pt-BR/gateway/health) — monitoramento de integridade do gateway - [TUI](/pt-BR/web/tui) — interface de usuário de terminal - [WebChat](/pt-BR/web/webchat) — interface de chat baseada em navegador