diff --git a/docs/pt-BR/channels/bluebubbles.md b/docs/pt-BR/channels/bluebubbles.md index de6d2598f..21edb4ff4 100644 --- a/docs/pt-BR/channels/bluebubbles.md +++ b/docs/pt-BR/channels/bluebubbles.md @@ -2,47 +2,47 @@ read_when: - Configurando o canal BlueBubbles - Solução de problemas de pareamento de Webhook - - Configurando iMessage no macOS + - Configurando o iMessage no macOS sidebarTitle: BlueBubbles -summary: iMessage via servidor macOS do BlueBubbles (envio/recebimento REST, digitação, reações, pareamento, ações avançadas). +summary: iMessage via servidor macOS do BlueBubbles (envio/recebimento por REST, digitação, reações, pareamento, ações avançadas). title: BlueBubbles x-i18n: - generated_at: "2026-05-01T05:55:15Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145 + source_hash: 78a054da0c7c32b161997acd05914896259dd1a050e736a4c9e438a452ab6a51 source_path: channels/bluebubbles.md workflow: 16 --- -Status: Plugin empacotado que se comunica com o servidor macOS BlueBubbles por HTTP. **Recomendado para integração com iMessage** devido à sua API mais rica e configuração mais fácil em comparação com o canal imsg legado. +Status: Plugin incluído que se comunica com o servidor macOS BlueBubbles por HTTP. **Recomendado para integração com iMessage** devido à sua API mais rica e à configuração mais fácil em comparação com o canal imsg legado. -As versões atuais do OpenClaw incluem o BlueBubbles, portanto builds empacotados normais não precisam de uma etapa separada de `openclaw plugins install`. +As versões atuais do OpenClaw incluem o BlueBubbles, portanto compilações empacotadas normais não precisam de uma etapa separada de `openclaw plugins install`. ## Visão geral -- Executa no macOS por meio do app auxiliar BlueBubbles ([bluebubbles.app](https://bluebubbles.app)). -- Recomendado/testado: macOS Sequoia (15). macOS Tahoe (26) funciona; a edição está atualmente quebrada no Tahoe, e atualizações de ícone de grupo podem relatar sucesso, mas não sincronizar. -- O OpenClaw se comunica com ele por meio da API REST (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). +- Executa no macOS por meio do aplicativo auxiliar BlueBubbles ([bluebubbles.app](https://bluebubbles.app)). +- Recomendado/testado: macOS Sequoia (15). macOS Tahoe (26) funciona; a edição está atualmente quebrada no Tahoe, e atualizações de ícones de grupo podem informar sucesso, mas não sincronizar. +- O OpenClaw se comunica com ele por meio da sua API REST (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). - Mensagens recebidas chegam por webhooks; respostas enviadas, indicadores de digitação, confirmações de leitura e tapbacks são chamadas REST. - Anexos e stickers são ingeridos como mídia de entrada (e expostos ao agente quando possível). - Respostas Auto-TTS que sintetizam áudio MP3 ou CAF são entregues como bolhas de memorando de voz do iMessage em vez de anexos de arquivo simples. -- O pareamento/lista de permissões funciona da mesma forma que outros canais (`/channels/pairing` etc.) com `channels.bluebubbles.allowFrom` + códigos de pareamento. -- Reações são expostas como eventos do sistema, assim como Slack/Telegram, para que agentes possam "mencioná-las" antes de responder. -- Recursos avançados: editar, desfazer envio, encadeamento de respostas, efeitos de mensagem, gerenciamento de grupos. +- O pareamento/lista de permissões funciona da mesma forma que em outros canais (`/channels/pairing` etc.) com `channels.bluebubbles.allowFrom` + códigos de pareamento. +- Reações são expostas como eventos do sistema, assim como no Slack/Telegram, para que os agentes possam "mencioná-las" antes de responder. +- Recursos avançados: edição, cancelamento de envio, encadeamento de respostas, efeitos de mensagem, gerenciamento de grupos. ## Início rápido - + Instale o servidor BlueBubbles no seu Mac (siga as instruções em [bluebubbles.app/install](https://bluebubbles.app/install)). - - Na configuração do BlueBubbles, habilite a API web e defina uma senha. + + Na configuração do BlueBubbles, ative a API web e defina uma senha. - + Execute `openclaw onboard` e selecione BlueBubbles, ou configure manualmente: ```json5 @@ -59,29 +59,29 @@ As versões atuais do OpenClaw incluem o BlueBubbles, portanto builds empacotado ``` - + Aponte os webhooks do BlueBubbles para o seu gateway (exemplo: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). - - Inicie o Gateway; ele registrará o manipulador de Webhook e começará o pareamento. + + Inicie o gateway; ele registrará o manipulador de webhook e iniciará o pareamento. **Segurança** -- Sempre defina uma senha de Webhook. -- A autenticação de Webhook é sempre obrigatória. O OpenClaw rejeita solicitações de Webhook do BlueBubbles a menos que incluam uma senha/guid que corresponda a `channels.bluebubbles.password` (por exemplo, `?password=` ou `x-password`), independentemente da topologia de loopback/proxy. -- A autenticação por senha é verificada antes da leitura/análise dos corpos completos de Webhook. +- Sempre defina uma senha de webhook. +- A autenticação de webhook é sempre obrigatória. O OpenClaw rejeita solicitações de webhook do BlueBubbles, a menos que elas incluam uma senha/guid que corresponda a `channels.bluebubbles.password` (por exemplo, `?password=` ou `x-password`), independentemente da topologia de loopback/proxy. +- A autenticação por senha é verificada antes da leitura/análise dos corpos completos de webhook. ## Mantendo o Messages.app ativo (VM / configurações headless) -Algumas configurações de VM macOS / sempre ativas podem acabar com o Messages.app ficando "ocioso" (eventos recebidos param até que o app seja aberto/trazido para primeiro plano). Uma solução simples é **cutucar o Messages a cada 5 minutos** usando um AppleScript + LaunchAgent. +Algumas VMs macOS / configurações sempre ativas podem acabar com o Messages.app ficando "ocioso" (eventos recebidos param até que o aplicativo seja aberto/colocado em primeiro plano). Uma solução simples é **acionar o Messages a cada 5 minutos** usando um AppleScript + LaunchAgent. - + Salve isto como `~/Scripts/poke-messages.scpt`: ```applescript @@ -100,7 +100,7 @@ Algumas configurações de VM macOS / sempre ativas podem acabar com o Messages. ``` - + Salve isto como `~/Library/LaunchAgents/com.user.poke-messages.plist`: ```xml @@ -135,7 +135,7 @@ Algumas configurações de VM macOS / sempre ativas podem acabar com o Messages. Isso executa **a cada 300 segundos** e **no login**. A primeira execução pode acionar prompts de **Automação** do macOS (`osascript` → Messages). Aprove-os na mesma sessão de usuário que executa o LaunchAgent. - + ```bash launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist @@ -160,13 +160,13 @@ O assistente solicita: Senha da API das configurações do BlueBubbles Server. - Caminho do endpoint de Webhook. + Caminho do endpoint de webhook. `pairing`, `allowlist`, `open` ou `disabled`. - Números de telefone, emails ou destinos de chat. + Números de telefone, emails ou alvos de chat. Você também pode adicionar BlueBubbles via CLI: @@ -180,26 +180,26 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor - Padrão: `channels.bluebubbles.dmPolicy = "pairing"`. - - Remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até a aprovação (os códigos expiram após 1 hora). + - Remetentes desconhecidos recebem um código de pareamento; mensagens são ignoradas até serem aprovadas (os códigos expiram após 1 hora). - Aprove via: - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` - - O pareamento é a troca de tokens padrão. Detalhes: [Pareamento](/pt-BR/channels/pairing) + - O pareamento é a troca de token padrão. Detalhes: [Pareamento](/pt-BR/channels/pairing) - + - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (padrão: `allowlist`). - `channels.bluebubbles.groupAllowFrom` controla quem pode acionar em grupos quando `allowlist` está definido. -### Enriquecimento de nome de contato (macOS, opcional) +### Enriquecimento de nomes de contatos (macOS, opcional) -Webhooks de grupo do BlueBubbles muitas vezes incluem apenas endereços brutos dos participantes. Se você quiser que o contexto `GroupMembers` mostre nomes de contatos locais em vez disso, pode optar pelo enriquecimento local de Contatos no macOS: +Webhooks de grupo do BlueBubbles frequentemente incluem apenas endereços brutos dos participantes. Se você quiser que o contexto `GroupMembers` mostre nomes de contatos locais em vez disso, pode optar por ativar o enriquecimento local de Contatos no macOS: -- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` habilita a consulta. Padrão: `false`. -- As consultas são executadas somente depois que o acesso ao grupo, a autorização de comando e o gating de menção permitirem a passagem da mensagem. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` ativa a busca. Padrão: `false`. +- As buscas são executadas somente depois que o acesso ao grupo, a autorização de comando e o controle por menção permitirem a passagem da mensagem. - Somente participantes de telefone sem nome são enriquecidos. - Números de telefone brutos permanecem como fallback quando nenhuma correspondência local é encontrada. @@ -213,13 +213,13 @@ Webhooks de grupo do BlueBubbles muitas vezes incluem apenas endereços brutos d } ``` -### Gating de menção (grupos) +### Controle por menção (grupos) -BlueBubbles oferece suporte a gating de menção para chats em grupo, correspondendo ao comportamento do iMessage/WhatsApp: +BlueBubbles oferece suporte a controle por menção em chats de grupo, acompanhando o comportamento do iMessage/WhatsApp: - Usa `agents.list[].groupChat.mentionPatterns` (ou `messages.groupChat.mentionPatterns`) para detectar menções. -- Quando `requireMention` está habilitado para um grupo, o agente responde somente quando mencionado. -- Comandos de controle de remetentes autorizados ignoram o gating de menção. +- Quando `requireMention` está ativado para um grupo, o agente só responde quando mencionado. +- Comandos de controle de remetentes autorizados ignoram o controle por menção. Configuração por grupo: @@ -238,15 +238,15 @@ Configuração por grupo: } ``` -### Gating de comandos +### Controle por comando - Comandos de controle (por exemplo, `/config`, `/model`) exigem autorização. - Usa `allowFrom` e `groupAllowFrom` para determinar a autorização de comando. - Remetentes autorizados podem executar comandos de controle mesmo sem mencionar em grupos. -### Prompt de sistema por grupo +### Prompt do sistema por grupo -Cada entrada em `channels.bluebubbles.groups.*` aceita uma string opcional `systemPrompt`. O valor é injetado no prompt de sistema do agente em cada turno que processa uma mensagem nesse grupo, para que você possa definir persona ou regras comportamentais por grupo sem editar prompts do agente: +Cada entrada em `channels.bluebubbles.groups.*` aceita uma string opcional `systemPrompt`. O valor é injetado no prompt do sistema do agente em cada turno que processa uma mensagem nesse grupo, para que você possa definir persona ou regras de comportamento por grupo sem editar prompts do agente: ```json5 { @@ -262,11 +262,11 @@ Cada entrada em `channels.bluebubbles.groups.*` aceita uma string opcional `syst } ``` -A chave corresponde a qualquer valor que o BlueBubbles relate como `chatGuid` / `chatIdentifier` / `chatId` numérico para o grupo, e uma entrada curinga `"*"` fornece um padrão para todos os grupos sem uma correspondência exata (o mesmo padrão usado por `requireMention` e políticas de ferramentas por grupo). Correspondências exatas sempre vencem o curinga. DMs ignoram esse campo; use personalização de prompt no nível do agente ou da conta em vez disso. +A chave corresponde ao que o BlueBubbles informar como `chatGuid` / `chatIdentifier` / `chatId` numérico para o grupo, e uma entrada curinga `"*"` fornece um padrão para todos os grupos sem correspondência exata (o mesmo padrão usado por `requireMention` e políticas de ferramentas por grupo). Correspondências exatas sempre prevalecem sobre o curinga. DMs ignoram este campo; use personalização de prompt em nível de agente ou conta em vez disso. #### Exemplo prático: respostas encadeadas e reações tapback (API privada) -Com a API privada do BlueBubbles habilitada, mensagens de entrada chegam com IDs curtos de mensagem (por exemplo, `[[reply_to:5]]`) e o agente pode chamar `action=reply` para encadear em uma mensagem específica ou `action=react` para enviar um tapback. Um `systemPrompt` por grupo é uma forma confiável de manter o agente escolhendo a ferramenta certa: +Com a API privada do BlueBubbles ativada, mensagens recebidas chegam com IDs curtos de mensagem (por exemplo, `[[reply_to:5]]`) e o agente pode chamar `action=reply` para encadear em uma mensagem específica ou `action=react` para enviar um tapback. Um `systemPrompt` por grupo é uma forma confiável de manter o agente escolhendo a ferramenta certa: ```json5 { @@ -274,15 +274,7 @@ Com a API privada do BlueBubbles habilitada, mensagens de entrada chegam com IDs bluebubbles: { groups: { "iMessage;+;chat-family": { - systemPrompt: [ - "When replying in this group, always call action=reply with the", - "[[reply_to:N]] messageId from context so your response threads", - "under the triggering message. Never send a new unlinked message.", - "", - "For short acknowledgements ('ok', 'got it', 'on it'), use", - "action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓)", - "instead of sending a text reply.", - ].join(" "), + systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.", }, }, }, @@ -292,27 +284,27 @@ Com a API privada do BlueBubbles habilitada, mensagens de entrada chegam com IDs Reações tapback e respostas encadeadas exigem a API privada do BlueBubbles; consulte [Ações avançadas](#advanced-actions) e [IDs de mensagem](#message-ids-short-vs-full) para a mecânica subjacente. -## Associações de conversas ACP +## Vínculos de conversa ACP Chats do BlueBubbles podem ser transformados em workspaces ACP duráveis sem alterar a camada de transporte. Fluxo rápido do operador: -- Execute `/acp spawn codex --bind here` dentro da DM ou chat em grupo permitido. -- Mensagens futuras nessa mesma conversa do BlueBubbles são roteadas para a sessão ACP gerada. -- `/new` e `/reset` redefinem a mesma sessão ACP associada no lugar. -- `/acp close` fecha a sessão ACP e remove a associação. +- Execute `/acp spawn codex --bind here` dentro da DM ou do chat de grupo permitido. +- Mensagens futuras nessa mesma conversa do BlueBubbles são roteadas para a sessão ACP criada. +- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no lugar. +- `/acp close` fecha a sessão ACP e remove o vínculo. -Associações persistentes configuradas também são compatíveis por meio de entradas `bindings[]` de nível superior com `type: "acp"` e `match.channel: "bluebubbles"`. +Vínculos persistentes configurados também são compatíveis por meio de entradas `bindings[]` de nível superior com `type: "acp"` e `match.channel: "bluebubbles"`. -`match.peer.id` pode usar qualquer forma de destino BlueBubbles compatível: +`match.peer.id` pode usar qualquer formato de alvo BlueBubbles compatível: -- identificador de DM normalizado, como `+15555550123` ou `user@example.com` +- identificador normalizado de DM, como `+15555550123` ou `user@example.com` - `chat_id:` - `chat_guid:` - `chat_identifier:` -Para associações estáveis de grupo, prefira `chat_id:*` ou `chat_identifier:*`. +Para vínculos de grupo estáveis, prefira `chat_id:*` ou `chat_identifier:*`. Exemplo: @@ -344,13 +336,13 @@ Exemplo: } ``` -Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para o comportamento compartilhado de associação ACP. +Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para o comportamento compartilhado de vínculos ACP. ## Digitação + confirmações de leitura -- **Indicadores de digitação**: Enviados automaticamente antes e durante a geração da resposta. -- **Confirmações de leitura**: Controladas por `channels.bluebubbles.sendReadReceipts` (padrão: `true`). -- **Indicadores de digitação**: O OpenClaw envia eventos de início de digitação; o BlueBubbles limpa a digitação automaticamente ao enviar ou ao atingir o tempo limite (a parada manual via DELETE não é confiável). +- **Indicadores de digitação**: enviados automaticamente antes e durante a geração de resposta. +- **Confirmações de leitura**: controladas por `channels.bluebubbles.sendReadReceipts` (padrão: `true`). +- **Indicadores de digitação**: o OpenClaw envia eventos de início de digitação; o BlueBubbles limpa a digitação automaticamente ao enviar ou por timeout (parada manual via DELETE não é confiável). ```json5 { @@ -364,7 +356,7 @@ Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para o comportamento compartilha ## Ações avançadas -O BlueBubbles oferece suporte a ações avançadas de mensagem quando habilitadas na configuração: +BlueBubbles oferece suporte a ações avançadas de mensagem quando habilitadas na configuração: ```json5 { @@ -389,68 +381,68 @@ O BlueBubbles oferece suporte a ações avançadas de mensagem quando habilitada ``` - - - **react**: Adicionar/remover reações tapback (`messageId`, `emoji`, `remove`). O conjunto nativo de tapbacks do iMessage é `love`, `like`, `dislike`, `laugh`, `emphasize` e `question`. Quando um agente escolhe um emoji fora desse conjunto (por exemplo, `👀`), a ferramenta de reação recorre a `love` para que o tapback ainda seja renderizado em vez de falhar a solicitação inteira. Reações de confirmação configuradas ainda são validadas estritamente e geram erro em valores desconhecidos. - - **edit**: Editar uma mensagem enviada (`messageId`, `text`). - - **unsend**: Desfazer o envio de uma mensagem (`messageId`). - - **reply**: Responder a uma mensagem específica (`messageId`, `text`, `to`). - - **sendWithEffect**: Enviar com efeito do iMessage (`text`, `to`, `effectId`). - - **renameGroup**: Renomear uma conversa em grupo (`chatGuid`, `displayName`). - - **setGroupIcon**: Definir o ícone/foto de uma conversa em grupo (`chatGuid`, `media`) — instável no macOS 26 Tahoe (a API pode retornar sucesso, mas o ícone não sincroniza). - - **addParticipant**: Adicionar alguém a um grupo (`chatGuid`, `address`). - - **removeParticipant**: Remover alguém de um grupo (`chatGuid`, `address`). - - **leaveGroup**: Sair de uma conversa em grupo (`chatGuid`). - - **upload-file**: Enviar mídia/arquivos (`to`, `buffer`, `filename`, `asVoice`). - - Memos de voz: defina `asVoice: true` com áudio **MP3** ou **CAF** para enviar como uma mensagem de voz do iMessage. O BlueBubbles converte MP3 → CAF ao enviar memos de voz. + + - **react**: Adiciona/remove reações de tapback (`messageId`, `emoji`, `remove`). O conjunto nativo de tapbacks do iMessage é `love`, `like`, `dislike`, `laugh`, `emphasize` e `question`. Quando um agente escolhe um emoji fora desse conjunto (por exemplo, `👀`), a ferramenta de reação recorre a `love`, para que o tapback ainda seja renderizado em vez de falhar a solicitação inteira. Reações de confirmação configuradas ainda são validadas estritamente e geram erro em valores desconhecidos. + - **edit**: Edita uma mensagem enviada (`messageId`, `text`). + - **unsend**: Cancela o envio de uma mensagem (`messageId`). + - **reply**: Responde a uma mensagem específica (`messageId`, `text`, `to`). + - **sendWithEffect**: Envia com efeito do iMessage (`text`, `to`, `effectId`). + - **renameGroup**: Renomeia um chat em grupo (`chatGuid`, `displayName`). + - **setGroupIcon**: Define o ícone/foto de um chat em grupo (`chatGuid`, `media`) — instável no macOS 26 Tahoe (a API pode retornar sucesso, mas o ícone não sincroniza). + - **addParticipant**: Adiciona alguém a um grupo (`chatGuid`, `address`). + - **removeParticipant**: Remove alguém de um grupo (`chatGuid`, `address`). + - **leaveGroup**: Sai de um chat em grupo (`chatGuid`). + - **upload-file**: Envia mídia/arquivos (`to`, `buffer`, `filename`, `asVoice`). + - Memorandos de voz: defina `asVoice: true` com áudio **MP3** ou **CAF** para enviar como mensagem de voz do iMessage. BlueBubbles converte MP3 → CAF ao enviar memorandos de voz. - Alias legado: `sendAttachment` ainda funciona, mas `upload-file` é o nome canônico da ação. -### IDs de mensagem (curtos vs. completos) +### IDs de mensagem (curto vs completo) -O OpenClaw pode expor IDs de mensagem _curtos_ (por exemplo, `1`, `2`) para economizar tokens. +OpenClaw pode expor IDs de mensagem _curtos_ (por exemplo, `1`, `2`) para economizar tokens. - `MessageSid` / `ReplyToId` podem ser IDs curtos. - `MessageSidFull` / `ReplyToIdFull` contêm os IDs completos do provedor. -- IDs curtos ficam em memória; podem expirar ao reiniciar ou com a remoção do cache. +- IDs curtos ficam na memória; podem expirar ao reiniciar ou por remoção do cache. - Ações aceitam `messageId` curto ou completo, mas IDs curtos gerarão erro se não estiverem mais disponíveis. Use IDs completos para automações e armazenamento duráveis: -- Modelos: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` -- Contexto: `MessageSidFull` / `ReplyToIdFull` em payloads de entrada +- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` +- Contexto: `MessageSidFull` / `ReplyToIdFull` em cargas de entrada -Consulte [Configuração](/pt-BR/gateway/configuration) para variáveis de modelo. +Consulte [Configuração](/pt-BR/gateway/configuration) para variáveis de template. -## Mesclagem de DMs com envio dividido (comando + URL em uma composição) +## Coalescência de DMs com envio dividido (comando + URL em uma composição) Quando um usuário digita um comando e uma URL juntos no iMessage — por exemplo, `Dump https://example.com/article` — a Apple divide o envio em **duas entregas de webhook separadas**: 1. Uma mensagem de texto (`"Dump"`). -2. Um balão de pré-visualização de URL (`"https://..."`) com imagens de pré-visualização OG como anexos. +2. Um balão de prévia de URL (`"https://..."`) com imagens de prévia OG como anexos. -Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem mesclagem, o agente recebe apenas o comando no turno 1, responde (geralmente "envie a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido. +Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem coalescência, o agente recebe apenas o comando no turno 1, responde (muitas vezes "envie-me a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido. -`channels.bluebubbles.coalesceSameSenderDms` opta por mesclar webhooks consecutivos do mesmo remetente em uma DM em um único turno do agente. Conversas em grupo continuam a usar chave por mensagem para preservar a estrutura de turnos de vários usuários. +`channels.bluebubbles.coalesceSameSenderDms` opta uma DM por mesclar webhooks consecutivos do mesmo remetente em um único turno do agente. Chats em grupo continuam usando chave por mensagem, preservando a estrutura de turnos com múltiplos usuários. - + Habilite quando: - - Você entrega skills que esperam `command + payload` em uma mensagem (dump, colar, salvar, enfileirar etc.). + - Você distribui Skills que esperam `command + payload` em uma mensagem (dump, paste, save, queue etc.). - Seus usuários colam URLs, imagens ou conteúdo longo junto com comandos. - - Você pode aceitar a latência adicional no turno de DM (veja abaixo). + - Você aceita a latência adicional de turno em DM (veja abaixo). Deixe desabilitado quando: - - Você precisa de latência mínima de comando para gatilhos de DM de uma única palavra. - - Todos os seus fluxos são comandos únicos sem payloads subsequentes. + - Você precisa de latência mínima de comando para gatilhos de DM de uma só palavra. + - Todos os seus fluxos são comandos únicos sem acompanhamentos de carga útil. - + ```json5 { channels: { @@ -461,9 +453,9 @@ Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das } ``` - Com a flag ativada e sem `messages.inbound.byChannel.bluebubbles` explícito, a janela de debounce aumenta para **2500 ms** (o padrão sem mesclagem é 500 ms). A janela maior é necessária — a cadência de envio dividido da Apple, de 0,8-2,0 s, não cabe no padrão mais estreito. + Com a flag ativada e sem `messages.inbound.byChannel.bluebubbles` explícito, a janela de debounce aumenta para **2500 ms** (o padrão sem coalescência é 500 ms). A janela mais ampla é necessária — a cadência de envio dividido da Apple de 0,8-2,0 s não cabe no padrão mais curto. - Para ajustar a janela por conta própria: + Para ajustar a janela você mesmo: ```json5 { @@ -480,39 +472,39 @@ Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das ``` - - - **Latência adicional para comandos de controle de DM.** Com a flag ativada, mensagens de comando de controle em DM (como `Dump`, `Save` etc.) agora aguardam até a janela de debounce antes do despacho, caso um webhook de payload esteja chegando. Comandos em conversas de grupo mantêm despacho instantâneo. - - **A saída mesclada é limitada** — o texto mesclado tem limite de 4000 caracteres com um marcador explícito `…[truncated]`; anexos têm limite de 20; entradas de origem têm limite de 10 (a primeira e a mais recente são mantidas além disso). Cada `messageId` de origem ainda chega à desduplicação de entrada, então uma reprodução posterior do MessagePoller de qualquer evento individual é reconhecida como duplicada. - - **Opcional, por canal.** Outros canais (Telegram, WhatsApp, Slack, …) não são afetados. + + - **Latência adicional para comandos de controle em DM.** Com a flag ativada, mensagens de comando de controle em DM (como `Dump`, `Save` etc.) agora aguardam até a janela de debounce antes do despacho, caso um webhook de carga útil esteja chegando. Comandos em chats de grupo mantêm despacho instantâneo. + - **A saída mesclada é limitada** — o texto mesclado é limitado a 4000 caracteres com um marcador explícito `…[truncated]`; anexos são limitados a 20; entradas de origem são limitadas a 10 (primeira-mais-recente retidas além disso). Cada `messageId` de origem ainda chega à desduplicação de entrada, então uma repetição posterior do MessagePoller de qualquer evento individual é reconhecida como duplicata. + - **Opt-in, por canal.** Outros canais (Telegram, WhatsApp, Slack, …) não são afetados. ### Cenários e o que o agente vê -| Usuário compõe | Apple entrega | Flag desativada (padrão) | Flag ativada + janela de 2500 ms | -| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- | -| `Dump https://example.com` (um envio) | 2 webhooks com ~1 s entre eles | Dois turnos do agente: "Dump" sozinho, depois URL | Um turno: texto mesclado `Dump https://example.com` | -| `Save this 📎image.jpg caption` (anexo + texto) | 2 webhooks | Dois turnos | Um turno: texto + imagem | -| `/status` (comando independente) | 1 webhook | Despacho instantâneo | **Aguarda até a janela e então despacha** | -| URL colada sozinha | 1 webhook | Despacho instantâneo | Despacho instantâneo (apenas uma entrada no bucket) | -| Texto + URL enviados como duas mensagens separadas deliberadas, com minutos de diferença | 2 webhooks fora da janela | Dois turnos | Dois turnos (a janela expira entre eles) | -| Enxurrada rápida (>10 DMs pequenas dentro da janela) | N webhooks | N turnos | Um turno, saída limitada (primeira + mais recente, limites de texto/anexo aplicados) | +| Usuário compõe | Apple entrega | Flag desativada (padrão) | Flag ativada + janela de 2500 ms | +| ------------------------------------------------------------------ | ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ | +| `Dump https://example.com` (um envio) | 2 webhooks com ~1 s de intervalo | Dois turnos do agente: "Dump" sozinho, depois URL | Um turno: texto mesclado `Dump https://example.com` | +| `Save this 📎image.jpg caption` (anexo + texto) | 2 webhooks | Dois turnos | Um turno: texto + imagem | +| `/status` (comando independente) | 1 webhook | Despacho instantâneo | **Aguarda até a janela e então despacha** | +| URL colada sozinha | 1 webhook | Despacho instantâneo | Despacho instantâneo (apenas uma entrada no bucket) | +| Texto + URL enviados como duas mensagens separadas deliberadas, com minutos de intervalo | 2 webhooks fora da janela | Dois turnos | Dois turnos (a janela expira entre eles) | +| Enxurrada rápida (>10 DMs pequenas dentro da janela) | N webhooks | N turnos | Um turno, saída limitada (primeira + mais recente, limites de texto/anexo aplicados) | -### Solução de problemas da mesclagem de envio dividido +### Solução de problemas de coalescência de envio dividido Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, verifique cada camada: - + ``` grep coalesceSameSenderDms ~/.openclaw/openclaw.json ``` - Em seguida, `openclaw gateway restart` — a flag é lida na criação do registro do debouncer. + Em seguida, `openclaw gateway restart` — a flag é lida na criação do registro de debouncers. - + Consulte o log do servidor BlueBubbles em `~/Library/Logs/bluebubbles-server/main.log`: ``` @@ -522,14 +514,14 @@ Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, ve Meça o intervalo entre o despacho de texto no estilo `"Dump"` e o despacho seguinte de `"https://..."; Attachments:`. Aumente `messages.inbound.byChannel.bluebubbles` para cobrir esse intervalo com folga. - - Os carimbos de data/hora de eventos de sessão (`~/.openclaw/agents//sessions/*.jsonl`) refletem quando o gateway entrega uma mensagem ao agente, **não** quando o webhook chegou. Uma segunda mensagem enfileirada marcada como `[Queued messages while agent was busy]` significa que o primeiro turno ainda estava em execução quando o segundo webhook chegou — o bucket de mesclagem já tinha sido esvaziado. Ajuste a janela com base no log do servidor BB, não no log de sessão. + + Timestamps de eventos de sessão (`~/.openclaw/agents//sessions/*.jsonl`) refletem quando o Gateway entrega uma mensagem ao agente, **não** quando o webhook chegou. Uma segunda mensagem enfileirada marcada como `[Queued messages while agent was busy]` significa que o primeiro turno ainda estava em execução quando o segundo webhook chegou — o bucket de coalescência já havia sido descarregado. Ajuste a janela com base no log do servidor BB, não no log da sessão. - - Em máquinas menores (8 GB), turnos do agente podem demorar o suficiente para que o bucket de mesclagem seja esvaziado antes de a resposta ser concluída, e a URL chegue como um segundo turno enfileirado. Verifique `memory_pressure` e `ps -o rss -p $(pgrep openclaw-gateway)`; se o gateway estiver acima de ~500 MB RSS e o compressor estiver ativo, feche outros processos pesados ou migre para um host maior. + + Em máquinas menores (8 GB), turnos do agente podem levar tempo suficiente para que o bucket de coalescência seja descarregado antes de a resposta ser concluída, e a URL entra como um segundo turno enfileirado. Verifique `memory_pressure` e `ps -o rss -p $(pgrep openclaw-gateway)`; se o Gateway estiver acima de ~500 MB de RSS e o compressor estiver ativo, feche outros processos pesados ou migre para um host maior. - - Se o usuário tocou em `Dump` como uma **resposta** a um balão de URL existente (o iMessage mostra um selo "1 Reply" no balão Dump), a URL fica em `replyToBody`, não em um segundo webhook. A mesclagem não se aplica — isso é uma questão de skill/prompt, não do debouncer. + + Se o usuário tocou em `Dump` como uma **resposta** a um balão de URL existente (o iMessage mostra um selo "1 Reply" no balão de Dump), a URL fica em `replyToBody`, não em um segundo webhook. A coalescência não se aplica — isso é uma questão de Skill/prompt, não de debouncer. @@ -551,48 +543,48 @@ Controle se as respostas são enviadas como uma única mensagem ou transmitidas - Anexos de entrada são baixados e armazenados no cache de mídia. - Limite de mídia via `channels.bluebubbles.mediaMaxMb` para mídia de entrada e saída (padrão: 8 MB). -- Texto de saída é dividido em blocos até `channels.bluebubbles.textChunkLimit` (padrão: 4000 caracteres). +- Texto de saída é dividido em partes conforme `channels.bluebubbles.textChunkLimit` (padrão: 4000 caracteres). ## Referência de configuração Configuração completa: [Configuração](/pt-BR/gateway/configuration) - - - `channels.bluebubbles.enabled`: Habilitar/desabilitar o canal. + + - `channels.bluebubbles.enabled`: Habilita/desabilita o canal. - `channels.bluebubbles.serverUrl`: URL base da API REST do BlueBubbles. - `channels.bluebubbles.password`: Senha da API. - - `channels.bluebubbles.webhookPath`: Caminho do endpoint de Webhook (padrão: `/bluebubbles-webhook`). + - `channels.bluebubbles.webhookPath`: Caminho do endpoint Webhook (padrão: `/bluebubbles-webhook`). - + - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: `pairing`). - `channels.bluebubbles.allowFrom`: Lista de permissões de DM (identificadores, e-mails, números E.164, `chat_id:*`, `chat_guid:*`). - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (padrão: `allowlist`). - `channels.bluebubbles.groupAllowFrom`: Lista de permissões de remetentes de grupo. - - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: No macOS, opcionalmente enriquecer participantes de grupo sem nome a partir dos Contatos locais depois que as verificações de acesso passarem. Padrão: `false`. + - `channels.bluebubbles.enrichGroupParticipantsFromContacts`: No macOS, opcionalmente enriquece participantes de grupo sem nome a partir dos Contatos locais após a aprovação das barreiras de acesso. Padrão: `false`. - `channels.bluebubbles.groups`: Configuração por grupo (`requireMention` etc.). - `channels.bluebubbles.sendReadReceipts`: Enviar confirmações de leitura (padrão: `true`). - - `channels.bluebubbles.blockStreaming`: Habilitar streaming em blocos (padrão: `false`; obrigatório para respostas em streaming). - - `channels.bluebubbles.textChunkLimit`: Tamanho dos fragmentos de saída em caracteres (padrão: 4000). - - `channels.bluebubbles.sendTimeoutMs`: Tempo limite por solicitação, em ms, para envios de texto de saída via `/api/v1/message/text` (padrão: 30000). Aumente em configurações do macOS 26 nas quais envios do iMessage pela Private API podem travar por mais de 60 segundos dentro do framework do iMessage; por exemplo, `45000` ou `60000`. Probes, buscas de chat, reações, edições e verificações de integridade atualmente mantêm o padrão mais curto de 10 s; ampliar a cobertura para reações e edições está planejado como continuidade. Substituição por conta: `channels.bluebubbles.accounts..sendTimeoutMs`. + - `channels.bluebubbles.blockStreaming`: Ativar streaming em bloco (padrão: `false`; obrigatório para respostas em streaming). + - `channels.bluebubbles.textChunkLimit`: Tamanho do fragmento de saída em caracteres (padrão: 4000). + - `channels.bluebubbles.sendTimeoutMs`: Timeout por solicitação em ms para envios de texto de saída via `/api/v1/message/text` (padrão: 30000). Aumente em configurações do macOS 26 em que envios do iMessage pela API privada podem travar por mais de 60 segundos dentro do framework do iMessage; por exemplo, `45000` ou `60000`. Sondagens, consultas de chats, reações, edições e verificações de integridade atualmente mantêm o padrão mais curto de 10s; ampliar a cobertura para reações e edições está planejado como continuação. Substituição por conta: `channels.bluebubbles.accounts..sendTimeoutMs`. - `channels.bluebubbles.chunkMode`: `length` (padrão) divide somente ao exceder `textChunkLimit`; `newline` divide em linhas em branco (limites de parágrafo) antes da fragmentação por tamanho. - `channels.bluebubbles.mediaMaxMb`: Limite de mídia de entrada/saída em MB (padrão: 8). - - `channels.bluebubbles.mediaLocalRoots`: Lista de permissões explícita de diretórios locais absolutos permitidos para caminhos de mídia local de saída. Envios por caminho local são negados por padrão, a menos que isto esteja configurado. Substituição por conta: `channels.bluebubbles.accounts..mediaLocalRoots`. - - `channels.bluebubbles.coalesceSameSenderDms`: Mesclar webhooks de DM consecutivos do mesmo remetente em um único turno do agente para que o envio dividido de texto+URL da Apple chegue como uma única mensagem (padrão: `false`). Consulte [Agrupando DMs enviadas em partes](#coalescing-split-send-dms-command--url-in-one-composition) para cenários, ajuste de janela e compensações. Amplia a janela padrão de debounce de entrada de 500 ms para 2500 ms quando habilitado sem um `messages.inbound.byChannel.bluebubbles` explícito. - - `channels.bluebubbles.historyLimit`: Máximo de mensagens de grupo para contexto (0 desabilita). - - `channels.bluebubbles.dmHistoryLimit`: Limite de histórico de DM. - - `channels.bluebubbles.replyContextApiFallback`: Quando uma resposta de entrada chega sem `replyToBody`/`replyToSender` e o cache em memória de contexto de resposta falha, buscar a mensagem original na API HTTP do BlueBubbles como fallback de melhor esforço (padrão: `false`). Útil para implantações com várias instâncias compartilhando uma conta do BlueBubbles, após reinicializações do processo ou após remoção por cache TTL/LRU de longa duração. A busca é protegida contra SSRF pela mesma política de todas as outras solicitações do cliente BlueBubbles, nunca lança erro e popula o cache para que respostas subsequentes sejam amortizadas. Substituição por conta: `channels.bluebubbles.accounts..replyContextApiFallback`. Uma configuração no nível do canal se propaga para contas que omitem a flag. + - `channels.bluebubbles.mediaLocalRoots`: Lista de permissões explícita de diretórios locais absolutos permitidos para caminhos de mídia local de saída. Envios de caminhos locais são negados por padrão, a menos que isto esteja configurado. Substituição por conta: `channels.bluebubbles.accounts..mediaLocalRoots`. + - `channels.bluebubbles.coalesceSameSenderDms`: Mesclar webhooks consecutivos de DM do mesmo remetente em um turno do agente para que o envio dividido de texto+URL da Apple chegue como uma única mensagem (padrão: `false`). Veja [Coalescer DMs de envio dividido](#coalescing-split-send-dms-command--url-in-one-composition) para cenários, ajuste de janela e compensações. Amplia a janela padrão de debounce de entrada de 500 ms para 2500 ms quando ativado sem um `messages.inbound.byChannel.bluebubbles` explícito. + - `channels.bluebubbles.historyLimit`: Máximo de mensagens de grupo para contexto (0 desativa). + - `channels.bluebubbles.dmHistoryLimit`: Limite do histórico de DM. + - `channels.bluebubbles.replyContextApiFallback`: Quando uma resposta de entrada chega sem `replyToBody`/`replyToSender` e o cache de contexto de resposta em memória não encontra correspondência, busca a mensagem original na API HTTP do BlueBubbles como fallback de melhor esforço (padrão: `false`). Útil para implantações com várias instâncias compartilhando uma conta BlueBubbles, após reinicializações de processo ou após expulsão de cache TTL/LRU de longa duração. A busca é protegida contra SSRF pela mesma política de todas as outras solicitações do cliente BlueBubbles, nunca lança erro e preenche o cache para amortizar respostas subsequentes. Substituição por conta: `channels.bluebubbles.accounts..replyContextApiFallback`. Uma configuração em nível de canal se propaga para contas que omitem a flag. - - `channels.bluebubbles.actions`: Habilitar/desabilitar ações específicas. + - `channels.bluebubbles.actions`: Ativar/desativar ações específicas. - `channels.bluebubbles.accounts`: Configuração de várias contas. @@ -611,36 +603,36 @@ Prefira `chat_guid` para roteamento estável: - `chat_id:123` - `chat_identifier:...` - Identificadores diretos: `+15555550123`, `user@example.com` - - Se um identificador direto não tiver um chat de DM existente, o OpenClaw criará um via `POST /api/v1/chat/new`. Isso exige que a Private API do BlueBubbles esteja habilitada. + - Se um identificador direto não tiver um chat de DM existente, o OpenClaw criará um via `POST /api/v1/chat/new`. Isso exige que a API privada do BlueBubbles esteja ativada. ### Roteamento iMessage vs SMS -Quando o mesmo identificador tem tanto um chat iMessage quanto um chat SMS no Mac (por exemplo, um número de telefone registrado no iMessage que também recebeu fallbacks de bolha verde), o OpenClaw prefere o chat iMessage e nunca rebaixa silenciosamente para SMS. Para forçar o chat SMS, use um prefixo de destino `sms:` explícito (por exemplo, `sms:+15555550123`). Identificadores sem um chat iMessage correspondente ainda enviam por qualquer chat que o BlueBubbles reportar. +Quando o mesmo identificador tem tanto um chat do iMessage quanto um chat de SMS no Mac (por exemplo, um número de telefone registrado no iMessage que também recebeu fallbacks de balão verde), o OpenClaw prefere o chat do iMessage e nunca rebaixa silenciosamente para SMS. Para forçar o chat de SMS, use um prefixo de destino `sms:` explícito (por exemplo, `sms:+15555550123`). Identificadores sem um chat do iMessage correspondente ainda enviam por qualquer chat que o BlueBubbles informar. ## Segurança -- Solicitações de Webhook são autenticadas comparando parâmetros de consulta ou cabeçalhos `guid`/`password` com `channels.bluebubbles.password`. -- Mantenha a senha da API e o endpoint de Webhook secretos (trate-os como credenciais). -- Não há bypass de localhost para autenticação de Webhook do BlueBubbles. Se você encaminhar tráfego de Webhook por proxy, mantenha a senha do BlueBubbles na solicitação de ponta a ponta. `gateway.trustedProxies` não substitui `channels.bluebubbles.password` aqui. Consulte [segurança do Gateway](/pt-BR/gateway/security#reverse-proxy-configuration). -- Habilite HTTPS + regras de firewall no servidor BlueBubbles se o expuser fora da sua LAN. +- Solicitações de Webhook são autenticadas comparando os parâmetros de consulta ou cabeçalhos `guid`/`password` com `channels.bluebubbles.password`. +- Mantenha a senha da API e o endpoint de Webhook em segredo (trate-os como credenciais). +- Não há bypass de localhost para autenticação de Webhook do BlueBubbles. Se você fizer proxy do tráfego de Webhook, mantenha a senha do BlueBubbles na solicitação de ponta a ponta. `gateway.trustedProxies` não substitui `channels.bluebubbles.password` aqui. Veja [Segurança do Gateway](/pt-BR/gateway/security#reverse-proxy-configuration). +- Ative HTTPS + regras de firewall no servidor BlueBubbles se expô-lo fora da sua LAN. ## Solução de problemas - Se eventos de digitação/leitura pararem de funcionar, verifique os logs de Webhook do BlueBubbles e confirme se o caminho do Gateway corresponde a `channels.bluebubbles.webhookPath`. - Códigos de pareamento expiram após uma hora; use `openclaw pairing list bluebubbles` e `openclaw pairing approve bluebubbles `. -- Reações exigem a API privada do BlueBubbles (`POST /api/v1/message/react`); certifique-se de que a versão do servidor a expõe. -- Editar/desfazer envio exige macOS 13+ e uma versão compatível do servidor BlueBubbles. No macOS 26 (Tahoe), a edição está atualmente quebrada devido a alterações na API privada. -- Atualizações de ícone de grupo podem ser instáveis no macOS 26 (Tahoe): a API pode retornar sucesso, mas o novo ícone não sincroniza. -- O OpenClaw oculta automaticamente ações sabidamente quebradas com base na versão do macOS do servidor BlueBubbles. Se a edição ainda aparecer no macOS 26 (Tahoe), desabilite-a manualmente com `channels.bluebubbles.actions.edit=false`. -- `coalesceSameSenderDms` habilitado, mas envios divididos (por exemplo, `Dump` + URL) ainda chegam como dois turnos: consulte a lista de verificação de [solução de problemas de agrupamento de envios divididos](#split-send-coalescing-troubleshooting) — causas comuns são janela de debounce apertada demais, timestamps do log de sessão interpretados incorretamente como chegada do Webhook ou um envio com citação de resposta (que usa `replyToBody`, não um segundo Webhook). +- Reações exigem a API privada do BlueBubbles (`POST /api/v1/message/react`); confirme se a versão do servidor a expõe. +- Editar/cancelar envio exige macOS 13+ e uma versão compatível do servidor BlueBubbles. No macOS 26 (Tahoe), a edição está atualmente quebrada devido a alterações da API privada. +- Atualizações de ícones de grupo podem ser instáveis no macOS 26 (Tahoe): a API pode retornar sucesso, mas o novo ícone não sincroniza. +- O OpenClaw oculta automaticamente ações sabidamente quebradas com base na versão do macOS do servidor BlueBubbles. Se a edição ainda aparecer no macOS 26 (Tahoe), desative-a manualmente com `channels.bluebubbles.actions.edit=false`. +- `coalesceSameSenderDms` ativado, mas envios divididos (por exemplo, `Dump` + URL) ainda chegam como dois turnos: veja a lista de verificação de [solução de problemas de coalescência de envios divididos](#split-send-coalescing-troubleshooting) — causas comuns são uma janela de debounce curta demais, timestamps de log de sessão lidos incorretamente como chegada do Webhook ou um envio com citação de resposta (que usa `replyToBody`, não um segundo Webhook). - Para informações de status/integridade: `openclaw status --all` ou `openclaw status --deep`. -Para referência geral do fluxo de trabalho de canais, consulte [Canais](/pt-BR/channels) e o guia de [Plugins](/pt-BR/tools/plugin). +Para referência geral do fluxo de trabalho de canais, veja [Canais](/pt-BR/channels) e o guia de [Plugins](/pt-BR/tools/plugin). ## Relacionados - [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens - [Visão geral de canais](/pt-BR/channels) — todos os canais compatíveis -- [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e controle por menções +- [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e controle por menção - [Pareamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de pareamento -- [Segurança](/pt-BR/gateway/security) — modelo de acesso e endurecimento +- [Segurança](/pt-BR/gateway/security) — modelo de acesso e fortalecimento diff --git a/docs/pt-BR/channels/broadcast-groups.md b/docs/pt-BR/channels/broadcast-groups.md index 0e807bf01..9033955db 100644 --- a/docs/pt-BR/channels/broadcast-groups.md +++ b/docs/pt-BR/channels/broadcast-groups.md @@ -1,16 +1,16 @@ --- read_when: - - Configuração de grupos de transmissão + - Configurando grupos de transmissão - Depuração de respostas multiagente no WhatsApp sidebarTitle: Broadcast groups status: experimental summary: Envie uma mensagem do WhatsApp para vários agentes title: Grupos de transmissão x-i18n: - generated_at: "2026-04-30T09:35:18Z" + generated_at: "2026-05-04T02:21:29Z" model: gpt-5.5 provider: openai - source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec + source_hash: eab43d3c3ffddb360340469433d74a380fbab98e662b2463a54f62eafc375b55 source_path: channels/broadcast-groups.md workflow: 16 --- @@ -21,11 +21,11 @@ x-i18n: ## Visão geral -Os grupos de transmissão permitem que vários agentes processem e respondam à mesma mensagem simultaneamente. Isso permite criar equipes de agentes especializados que trabalham juntas em um único grupo ou DM do WhatsApp — tudo usando um único número de telefone. +Broadcast Groups permitem que vários agentes processem e respondam à mesma mensagem simultaneamente. Isso permite criar equipes de agentes especializados que trabalham juntas em um único grupo ou DM do WhatsApp — tudo usando um único número de telefone. Escopo atual: **somente WhatsApp** (canal web). -Os grupos de transmissão são avaliados após as allowlists de canal e as regras de ativação de grupo. Em grupos do WhatsApp, isso significa que as transmissões acontecem quando o OpenClaw normalmente responderia (por exemplo: em menções, dependendo das configurações do seu grupo). +Broadcast groups são avaliados após allowlists de canais e regras de ativação de grupos. Em grupos do WhatsApp, isso significa que broadcasts acontecem quando o OpenClaw normalmente responderia (por exemplo: em uma menção, dependendo das configurações do seu grupo). ## Casos de uso @@ -77,7 +77,7 @@ Os grupos de transmissão são avaliados após as allowlists de canal e as regra ### Configuração básica -Adicione uma seção `broadcast` de nível superior (ao lado de `bindings`). As chaves são IDs de pares do WhatsApp: +Adicione uma seção `broadcast` de nível superior (ao lado de `bindings`). As chaves são ids de pares do WhatsApp: - conversas em grupo: JID do grupo (por exemplo, `120363403215116621@g.us`) - DMs: número de telefone E.164 (por exemplo, `+15551234567`) @@ -90,7 +90,7 @@ Adicione uma seção `broadcast` de nível superior (ao lado de `bindings`). As } ``` -**Resultado:** Quando o OpenClaw responderia nessa conversa, ele executará os três agentes. +**Resultado:** Quando o OpenClaw responderia nesta conversa, ele executará todos os três agentes. ### Estratégia de processamento @@ -165,48 +165,48 @@ Controle como os agentes processam mensagens: ### Fluxo de mensagens - + Uma mensagem de grupo ou DM do WhatsApp chega. - + O sistema verifica se o ID do par está em `broadcast`. - + - Todos os agentes listados processam a mensagem. - Cada agente tem sua própria chave de sessão e contexto isolado. - Os agentes processam em paralelo (padrão) ou sequencialmente. - - O roteamento normal se aplica (primeiro vínculo correspondente). + + O roteamento normal se aplica (primeiro binding correspondente). -Grupos de transmissão não ignoram allowlists de canal nem regras de ativação de grupo (menções/comandos/etc.). Eles apenas alteram _quais agentes são executados_ quando uma mensagem está qualificada para processamento. +Broadcast groups não ignoram allowlists de canais nem regras de ativação de grupos (menções/comandos/etc.). Eles apenas alteram _quais agentes são executados_ quando uma mensagem está qualificada para processamento. ### Isolamento de sessão -Cada agente em um grupo de transmissão mantém completamente separados: +Cada agente em um broadcast group mantém completamente separados: - **Chaves de sessão** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`) -- **Histórico de conversa** (o agente não vê as mensagens de outros agentes) +- **Histórico de conversa** (o agente não vê as mensagens dos outros agentes) - **Workspace** (sandboxes separados, se configurados) -- **Acesso a ferramentas** (listas de permitir/negar diferentes) -- **Memória/contexto** (IDENTITY.md, SOUL.md etc. separados) -- **Buffer de contexto do grupo** (mensagens recentes do grupo usadas para contexto) é compartilhado por par, então todos os agentes de transmissão veem o mesmo contexto quando acionados +- **Acesso a ferramentas** (listas de permissão/negação diferentes) +- **Memória/contexto** (IDENTITY.md, SOUL.md, etc. separados) +- **Buffer de contexto do grupo** (mensagens recentes do grupo usadas como contexto) é compartilhado por par, então todos os agentes de broadcast veem o mesmo contexto quando acionados Isso permite que cada agente tenha: - Personalidades diferentes -- Acesso diferente a ferramentas (por exemplo, somente leitura vs. leitura e escrita) +- Acesso a ferramentas diferente (por exemplo, somente leitura vs. leitura e escrita) - Modelos diferentes (por exemplo, opus vs. sonnet) - Skills diferentes instaladas ### Exemplo: sessões isoladas -No grupo `120363403215116621@g.us` com os agentes `["alfred", "baerbel"]`: +No grupo `120363403215116621@g.us` com agentes `["alfred", "baerbel"]`: @@ -227,7 +227,7 @@ No grupo `120363403215116621@g.us` com os agentes `["alfred", "baerbel"]`: -## Melhores práticas +## Práticas recomendadas @@ -258,32 +258,34 @@ No grupo `120363403215116621@g.us` com os agentes `["alfred", "baerbel"]`: ``` - + Dê aos agentes apenas as ferramentas de que precisam: ```json { "agents": { "reviewer": { - "tools": { "allow": ["read", "exec"] } // Read-only + "tools": { "allow": ["read", "exec"] } }, "fixer": { - "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write + "tools": { "allow": ["read", "write", "edit", "exec"] } } } } ``` + `reviewer` é somente leitura. `fixer` pode ler e escrever. + Com muitos agentes, considere: - Usar `"strategy": "parallel"` (padrão) para velocidade - - Limitar grupos de transmissão a 5-10 agentes + - Limitar broadcast groups a 5-10 agentes - Usar modelos mais rápidos para agentes mais simples - + Agentes falham de forma independente. O erro de um agente não bloqueia os outros: ``` @@ -296,9 +298,9 @@ No grupo `120363403215116621@g.us` com os agentes `["alfred", "baerbel"]`: ## Compatibilidade -### Provedores +### Providers -Grupos de transmissão funcionam atualmente com: +Broadcast groups atualmente funcionam com: - ✅ WhatsApp (implementado) - 🚧 Telegram (planejado) @@ -307,7 +309,7 @@ Grupos de transmissão funcionam atualmente com: ### Roteamento -Grupos de transmissão funcionam junto com o roteamento existente: +Broadcast groups funcionam junto com o roteamento existente: ```json { @@ -324,7 +326,7 @@ Grupos de transmissão funcionam junto com o roteamento existente: ``` - `GROUP_A`: Somente alfred responde (roteamento normal). -- `GROUP_B`: agent1 E agent2 respondem (transmissão). +- `GROUP_B`: agent1 E agent2 respondem (broadcast). **Precedência:** `broadcast` tem prioridade sobre `bindings`. @@ -350,11 +352,11 @@ Grupos de transmissão funcionam junto com o roteamento existente: **Causa:** O ID do par pode estar em `bindings`, mas não em `broadcast`. - **Correção:** Adicione à configuração de transmissão ou remova de bindings. + **Correção:** Adicione à configuração de broadcast ou remova de bindings. - Se estiver lento com muitos agentes: + Se ficar lento com muitos agentes: - Reduza o número de agentes por grupo. - Use modelos mais leves (sonnet em vez de opus). @@ -405,7 +407,7 @@ Grupos de transmissão funcionam junto com o roteamento existente: **Respostas:** - - code-formatter: "Indentação corrigida e dicas de tipo adicionadas" + - code-formatter: "Corrigi a indentação e adicionei dicas de tipo" - security-scanner: "⚠️ Vulnerabilidade de injeção de SQL na linha 12" - test-coverage: "A cobertura é de 45%, faltam testes para casos de erro" - docs-checker: "Docstring ausente para a função `process_data`" @@ -449,14 +451,14 @@ interface OpenClawConfig { Como processar agentes. `parallel` executa todos os agentes simultaneamente; `sequential` os executa na ordem do array. - JID do grupo do WhatsApp, número E.164 ou outro ID de par. O valor é o array de IDs de agentes que devem processar mensagens. + JID de grupo do WhatsApp, número E.164 ou outro ID de par. O valor é o array de IDs de agentes que devem processar mensagens. ## Limitações -1. **Máximo de agentes:** Sem limite rígido, mas mais de 10 agentes podem ser lentos. +1. **Máximo de agentes:** Sem limite rígido, mas 10+ agentes podem ser lentos. 2. **Contexto compartilhado:** Os agentes não veem as respostas uns dos outros (por design). -3. **Ordenação de mensagens:** Respostas paralelas podem chegar em qualquer ordem. +3. **Ordem das mensagens:** Respostas paralelas podem chegar em qualquer ordem. 4. **Limites de taxa:** Todos os agentes contam para os limites de taxa do WhatsApp. ## Melhorias futuras @@ -468,10 +470,10 @@ Recursos planejados: - [ ] Seleção dinâmica de agentes (escolher agentes com base no conteúdo da mensagem) - [ ] Prioridades de agentes (alguns agentes respondem antes de outros) -## Relacionados +## Relacionado - [Roteamento de canais](/pt-BR/channels/channel-routing) - [Grupos](/pt-BR/channels/groups) - [Ferramentas de sandbox multiagente](/pt-BR/tools/multi-agent-sandbox-tools) -- [Pareamento](/pt-BR/channels/pairing) +- [Emparelhamento](/pt-BR/channels/pairing) - [Gerenciamento de sessões](/pt-BR/concepts/session) diff --git a/docs/pt-BR/channels/discord.md b/docs/pt-BR/channels/discord.md index ad6019a7d..311507b1e 100644 --- a/docs/pt-BR/channels/discord.md +++ b/docs/pt-BR/channels/discord.md @@ -1,49 +1,49 @@ --- read_when: - - Trabalhando em recursos do canal Discord -summary: Status de suporte, recursos e configuração do bot do Discord + - Trabalhando em recursos de canais do Discord +summary: Status do suporte a robôs do Discord, capacidades e configuração title: Discord x-i18n: - generated_at: "2026-05-03T21:27:16Z" + generated_at: "2026-05-04T02:21:22Z" model: gpt-5.5 provider: openai - source_hash: 3a38cb3c8e25c1f3d6b7ddfc35a0445dc264be74d74b08d0051528b462b743a3 + source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 source_path: channels/discord.md workflow: 16 --- -Pronto para DMs e canais de servidor via o Gateway oficial do Discord. +Pronto para DMs e canais de guild via o Gateway oficial do Discord. - DMs do Discord usam o modo de pareamento por padrão. + As DMs do Discord usam o modo de pareamento por padrão. - Comportamento nativo de comandos e catálogo de comandos. + Comportamento nativo dos comandos e catálogo de comandos. - Diagnósticos entre canais e fluxo de reparo. + Diagnóstico entre canais e fluxo de reparo. ## Configuração rápida -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**). +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**). - - Acesse o [Discord Developer Portal](https://discord.com/developers/applications) e clique em **New Application**. Dê a ela um nome como "OpenClaw". + + Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e clique em **New Application**. Dê a ele um nome como "OpenClaw". Clique em **Bot** na barra lateral. Defina o **Username** como o nome que você dá ao seu agente OpenClaw. - + Ainda na página **Bot**, role para baixo até **Privileged Gateway Intents** e ative: - - **Message Content Intent** (obrigatória) - - **Server Members Intent** (recomendada; obrigatória para allowlists de funções e correspondência de nome para ID) - - **Presence Intent** (opcional; necessária apenas para atualizações de presença) + - **Message Content Intent** (obrigatório) + - **Server Members Intent** (recomendado; obrigatório para listas de permissões de funções e correspondência de nome para ID) + - **Presence Intent** (opcional; necessário apenas para atualizações de presença) @@ -77,8 +77,8 @@ Você precisará criar uma nova aplicação com um bot, adicionar o bot ao seu s - Attach Files - Add Reactions (opcional) - Este é o conjunto base 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 navegador, selecione seu servidor e clique em **Continue** para conectar. Agora você deve ver seu bot no servidor Discord. + 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**. + 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. @@ -96,12 +96,12 @@ Você precisará criar uma nova aplicação com um bot, adicionar o bot ao seu s 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**. - 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 servidor, 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ê pretende usar apenas canais de guild, pode desativar DMs após o pareamento. - 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. + 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. ```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 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` em um shell onde `DISCORD_BOT_TOKEN` esteja presente, ou armazene a variável em `~/.openclaw/.env`, para que o serviço consiga resolver o SecretRef de env após a reinicialização. - Se seu host estiver bloqueado ou limitado por taxa pela consulta de aplicação de inicialização do Discord, defina o ID da aplicação/cliente do Discord no 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ê executar vários bots do Discord. + 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. - + - Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e informe isso a ele. Se Discord for seu primeiro canal, use a aba CLI / config. + 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. - > "Já defini o token do meu bot do Discord na configuração. Conclua a configuração do Discord com User ID `` e Server ID ``." + > "Já defini meu token de bot do Discord na configuração. Conclua a configuração do Discord com User ID `` e Server ID ``." - Se preferir configuração baseada em arquivo, defina: + Se você preferir configuração baseada em arquivo, defina: ```json5 { @@ -158,9 +158,9 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Para configuração com 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 de `token` em texto puro são compatíveis. Valores SecretRef também são compatíveis para `channels.discord.token` em provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). + 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 vários bots do Discord, mantenha cada token de bot e ID de aplicação em sua respectiva conta. Um `channels.discord.applicationId` de nível superior é herdado pelas contas, então defina-o ali apenas quando todas as contas devem usar o mesmo ID de aplicação. + 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. ```json5 { @@ -188,7 +188,7 @@ DISCORD_BOT_TOKEN=... - 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. + 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. @@ -214,24 +214,24 @@ openclaw pairing approve discord -A resolução de token é ciente da conta. Valores de token na configuração prevalecem sobre o 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 prevalece sobre o fallback de env padrão; caso contrário, a primeira conta ativada prevalece e a conta duplicada é relatada como desativada. +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. -## Recomendado: configure um workspace de servidor +## Recomendado: configure um workspace de guild -Depois que as DMs estiverem funcionando, você pode 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 é apenas você e seu bot. +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. - + Isso permite que seu agente responda em qualquer canal do seu servidor, não apenas em DMs. - > "Adicione meu Server ID do Discord `` à allowlist de servidores" + > "Adicione meu Server ID do Discord `` à lista de permissões de guild" - + ```json5 { @@ -255,16 +255,18 @@ Depois que as DMs estiverem funcionando, você pode configurar seu servidor Disc - Por padrão, seu agente só responde em canais de servidor quando recebe @mention. Para um servidor privado, você provavelmente quer que ele responda a todas as mensagens. + 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 servidor, 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ó publicar 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 só postar 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. > "Permita que meu agente responda neste servidor sem precisar receber @mention" - - Defina `requireMention: false` na configuração do seu servidor: + + Defina `requireMention: false` na sua configuração de guild: ```json5 { @@ -287,37 +289,37 @@ Depois que as DMs estiverem funcionando, você pode configurar seu servidor Disc - - Por padrão, a memória de longo prazo (MEMORY.md) só é carregada em sessões de DM. Canais de servidor não carregam MEMORY.md automaticamente. + + 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. - > "Quando eu fizer perguntas em canais do Discord, use memory_search ou memory_get se precisar de contexto de longo prazo do MEMORY.md." + > "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 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ê 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. -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 — assim você pode configurar `#coding`, `#home`, `#research` ou o que se ajustar ao seu fluxo de trabalho. +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. ## Modelo de runtime -- Gateway controla a conexão com o Discord. -- O roteamento de respostas é determinístico: respostas recebidas pelo Discord voltam para o 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 repetição futura. +- 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. - 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 em grupo são ignoradas por padrão (`channels.discord.dm.groupEnabled=false`). +- DMs de 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úncio de Cron/Heartbeat somente texto para o Discord usa a resposta final visível ao assistente uma vez. Payloads de mídia e componentes estruturados continuam com várias mensagens quando o agente emite vários payloads entregáveis. +- 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. ## Canais de fórum -Canais de fórum e mídia do Discord aceitam apenas publicações em threads. O OpenClaw oferece suporte a duas maneiras de criá-las: +Canais de fórum e mídia do Discord aceitam apenas posts em threads. O OpenClaw oferece suporte a duas formas de criá-los: - 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. - Use `openclaw message thread create` para criar uma thread diretamente. Não passe `--message-id` para canais de fórum. @@ -336,11 +338,11 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Fóruns pai não aceitam componentes do Discord. Se você precisar de componentes, envie para a própria thread (`channel:`). +Fóruns pais não aceitam componentes do Discord. Se 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`. 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`. 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. Blocos compatíveis: @@ -357,14 +359,14 @@ Os comandos de barra `/model` e `/models` abrem um seletor interativo de modelo 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 vários arquivos -- Use `filename` para substituir o nome do upload quando ele precisar corresponder à referência do anexo +- Forneça o anexo via `media`/`path`/`filePath` (arquivo único); use `media-gallery` para múltiplos 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 acionamento automaticamente +- O OpenClaw adiciona um botão de disparo automaticamente Exemplo: @@ -424,37 +426,37 @@ Exemplo: - `channels.discord.dmPolicy` controla o acesso por DM. `channels.discord.allowFrom` é a lista de permissões canônica de DM. + `channels.discord.dmPolicy` controla o acesso a DMs. `channels.discord.allowFrom` é a lista de permissões canônica para DMs. - `pairing` (padrão) - `allowlist` - - `open` (requer que `channels.discord.allowFrom` inclua `"*"`) + - `open` (exige que `channels.discord.allowFrom` inclua `"*"`) - `disabled` - Se a política de DM não for aberta, usuários desconhecidos serão bloqueados (ou solicitados a fazer pareamento no modo `pairing`). + 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`). - Precedência de várias contas: + Precedência de múltiplas contas: - - `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. + - `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. - Contas nomeadas não herdam `channels.discord.accounts.default.allowFrom`. - `channels.discord.dm.policy` e `channels.discord.dm.allowFrom` legados ainda são lidos por compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando consegue fazer isso sem alterar o acesso. + `channels.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. 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` de DM efetivo da conta são tratados como destinos de DM de usuário por 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` efetivo de DM 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 `allowFrom` normal 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 de grupos de acesso compartilhados está documentado aqui: [Grupos de acesso](/pt-BR/channels/access-groups). + 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). ```json5 { @@ -477,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 como: o remetente da DM é membro da guild configurada e atualmente tem permissão efetiva de `ViewChannel` no canal configurado depois que substituições de cargo e canal são aplicadas. + 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. - Exemplo: permitir que qualquer pessoa que possa ver `#maintainers` envie DM para o bot, mantendo DMs fechadas para todos os demais. + Exemplo: permitir que qualquer pessoa que possa ver `#maintainers` envie DM ao bot, mantendo as DMs fechadas para todos os demais. ```json5 { @@ -520,14 +522,14 @@ Exemplo: } ``` - Consultas falham de forma fechada. 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. + 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. - Habilite a **Server Members Intent** do Portal de Desenvolvedores do Discord para o bot ao usar grupos de acesso por público do canal. DMs não incluem estado de membro de guild, então o OpenClaw resolve o membro via REST do Discord no momento da autorização. + 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. - O tratamento de guild é controlado por `channels.discord.groupPolicy`: + O tratamento de guilds é controlado por `channels.discord.groupPolicy`: - `open` - `allowlist` @@ -538,11 +540,11 @@ 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` (apenas IDs de cargo); se qualquer um estiver configurado, remetentes são permitidos quando corresponderem a `users` OU `roles` - - correspondência direta de nome/tag fica desabilitada por padrão; habilite `channels.discord.dangerouslyAllowNameMatching: true` apenas como modo de compatibilidade de emergência - - nomes/tags têm suporte para `users`, mas IDs são mais seguros; `openclaw security audit` alerta quando entradas de nome/tag são usadas + - 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` + - 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 nessa guild permitida serão permitidos + - se uma guild não tiver bloco `channels`, todos os canais dessa guild na lista de permissões serão permitidos Exemplo: @@ -568,12 +570,12 @@ Exemplo: } ``` - 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`. + 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`. - - Mensagens de guild são bloqueadas por menção por padrão. + + Mensagens de guild exigem menção por padrão. A detecção de menção inclui: @@ -581,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 cargos. Não use o formulário legado 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 a forma legada de menção por apelido `<@!USER_ID>`. `requireMention` é configurado por guild/canal (`channels.discord.guilds...`). - `ignoreOtherMentions` opcionalmente descarta mensagens que mencionam outro usuário/cargo, mas não o bot (excluindo @everyone/@here). + `ignoreOtherMentions` opcionalmente descarta mensagens que mencionam outro usuário/função, mas não o bot (excluindo @everyone/@here). - DMs em grupo: + DMs de grupo: - padrão: ignoradas (`dm.groupEnabled=false`) - - lista de permissões opcional via `dm.groupChannels` (IDs de canal ou slugs) + - lista de permissões opcional via `dm.groupChannels` (IDs ou slugs de canal) -### Roteamento de agentes baseado em cargos +### Roteamento de agente baseado em função -Use `bindings[].match.roles` para rotear membros de guild do Discord para agentes diferentes por ID de cargo. Bindings baseados em cargo aceitam apenas IDs de cargo e são avaliados após bindings de par ou par-pai 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 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. ```json5 { @@ -622,15 +624,15 @@ Use `bindings[].match.roles` para rotear membros de guild do Discord para agente ## Comandos nativos e autenticação de comando -- `commands.native` usa `"auto"` por padrão e é habilitado para Discord. +- `commands.native` tem como padrão `"auto"` e é habilitado para Discord. - Substituição por canal: `channels.discord.commands.native`. -- `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ão/políticas do Discord que o processamento normal de mensagens. -- Os comandos ainda podem ficar visíveis na interface do Discord para usuários não autorizados; a execução ainda impõe a autenticação do OpenClaw e retorna "not authorized". +- `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. +- 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". -Consulte [Comandos slash](/pt-BR/tools/slash-commands) para ver o catálogo e o comportamento dos comandos. +Veja [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo e o comportamento dos comandos. -Configurações padrão de comandos slash: +Configurações padrão de comandos de barra: - `ephemeral: true` @@ -651,20 +653,20 @@ Configurações padrão de comandos slash: - `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 de saída do Discord no turno. + `first` sempre anexa a referência implícita de resposta nativa à primeira mensagem enviada 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 agentes possam direcionar mensagens específicas. + IDs de mensagem são expostos no contexto/histórico para que os agentes possam direcionar mensagens específicas. - O OpenClaw pode transmitir rascunhos de respostas 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 de ferramentas até a entrega final; `streamMode` é um alias legado e é migrado automaticamente. + 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 permanece `off` porque edições de prévia no Discord atingem limites de taxa rapidamente quando vários bots ou gateways compartilham uma conta. + 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. ```json5 { @@ -682,16 +684,16 @@ Configurações padrão de comandos slash: ``` - `partial` edita uma única mensagem de prévia conforme os tokens chegam. - - `block` emite blocos do tamanho de rascunho (use `draftChunk` para ajustar o tamanho e os pontos de quebra, limitado a `textChunkLimit`). - - Mídia, erro e finais com resposta explícita cancelam edições de prévia pendentes. + - `block` emite blocos do tamanho de rascunho (use `draftChunk` para ajustar tamanho e pontos de quebra, limitado a `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. - 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 a transmissão de prévia para evitar transmissão dupla. + 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. - - Contexto de histórico de servidor: + + Contexto de histórico de guilda: - `channels.discord.historyLimit` padrão `20` - fallback: `messages.groupChat.historyLimit` @@ -702,28 +704,28 @@ Configurações padrão de comandos slash: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Comportamento de threads: + Comportamento de thread: - - Threads do Discord são roteadas como sessões de canal e herdam a configuração do canal pai, salvo 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 à thread ainda têm precedência, e o histórico de transcrição do pai não é copiado, salvo quando a herança de transcrição está habilitada. - - `channels.discord.thread.inheritParent` (padrão `false`) faz novas auto-threads receberem dados iniciais da transcrição pai. Substituições por conta ficam em `channels.discord.accounts..thread.inheritParent`. - - Reações da ferramenta de mensagens 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 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:`. - `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ão controlam quem pode acionar o agente, não um limite completo 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 sã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 de acompanhamento nessa thread continuem sendo roteadas para a mesma sessão (incluindo sessões de subagentes). + 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). Comandos: - `/focus ` vincula a thread atual/nova a um destino de subagente/sessão - - `/unfocus` remove a vinculação da thread atual - - `/agents` mostra execuções ativas e estado de vinculação - - `/session idle ` inspeciona/atualiza o auto-unfocus por inatividade para vinculações focadas - - `/session max-age ` inspeciona/atualiza a idade máxima rígida para vinculações focadas + - `/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 + - `/session max-age ` inspeciona/atualiza a idade máxima rígida para vínculos focados Configuração: @@ -754,17 +756,17 @@ Configurações padrão de comandos slash: - `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 ACP. Padrão: `true`. - - `defaultSpawnContext` controla o contexto nativo de subagente para criações vinculadas a threads. Padrão: `"fork"`. + - `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 as vinculações de thread estiverem desabilitadas para uma conta, `/focus` e operações relacionadas de vinculação de thread ficam indisponíveis. + - 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. - Consulte [Subagentes](/pt-BR/tools/subagents), [Agentes ACP](/pt-BR/tools/acp-agents) e [Referência de configuração](/pt-BR/gateway/configuration-reference). + Veja [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 vinculações ACP tipadas de nível superior que apontam para conversas do Discord. + + 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: @@ -820,23 +822,23 @@ Configurações padrão de comandos slash: 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 a vinculação do canal pai. - - Em um canal ou thread vinculado, `/new` e `/reset` redefinem a mesma sessão ACP no local. Vinculações temporárias de thread podem substituir a resolução de destino enquanto estiverem ativas. + - `/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`. - Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para detalhes do comportamento de vinculação. + Veja [Agentes ACP](/pt-BR/tools/acp-agents) para detalhes do comportamento de vínculo. - Modo de notificação de reação por servidor: + Modo de notificação de reação por guilda: - `off` - `own` (padrão) - `all` - `allowlist` (usa `guilds..users`) - Eventos de reação são transformados em eventos de sistema e anexados à sessão roteada do Discord. + Eventos de reação são transformados em eventos do sistema e anexados à sessão roteada do Discord. @@ -852,7 +854,7 @@ Configurações padrão de comandos slash: Observações: - - O Discord aceita emojis unicode ou nomes de emojis personalizados. + - O Discord aceita emoji unicode ou nomes de emoji personalizados. - Use `""` para desabilitar a reação para um canal ou conta. @@ -860,7 +862,7 @@ Configurações padrão de comandos slash: Gravações de configuração iniciadas por canal são habilitadas por padrão. - Isso afeta fluxos `/config set|unset` (quando os recursos de comando estão habilitados). + Isso afeta fluxos `/config set|unset` (quando recursos de comando estão habilitados). Desabilitar: @@ -877,7 +879,7 @@ Configurações padrão de comandos slash: - Roteie o tráfego WebSocket do Gateway do Discord e consultas REST de inicialização (ID do aplicativo + resolução de lista de permissão) por um proxy HTTP(S) com `channels.discord.proxy`. + 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`. ```json5 { @@ -908,7 +910,7 @@ Configurações padrão de comandos slash: - Habilite a resolução do PluralKit para mapear mensagens intermediadas para a identidade de membro do sistema: + Habilite a resolução do PluralKit para mapear mensagens com proxy para a identidade de membro do sistema: ```json5 { @@ -925,15 +927,15 @@ Configurações padrão de comandos slash: Observações: - - listas de permissão podem usar `pk:` + - 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` - - consultas usam o ID da mensagem original e são limitadas por janela de tempo - - se a consulta falhar, mensagens intermediadas são tratadas como mensagens de bot e descartadas, salvo se `allowBots=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` - - 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 permanecem inalterados. + + 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. ```json5 { @@ -957,7 +959,7 @@ Configurações padrão de comandos slash: - Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando habilita a presença automática. + 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: @@ -1004,10 +1006,10 @@ Configurações padrão de comandos slash: - 1: Transmitindo (requer `activityUrl`) - 2: Ouvindo - 3: Assistindo - - 4: Personalizado (usa o texto da atividade como estado do status; emoji é opcional) + - 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 runtime): + Exemplo de presença automática (sinal de integridade em tempo de execução): ```json5 { @@ -1024,7 +1026,7 @@ Configurações padrão de comandos slash: } ``` - A presença automática mapeia a disponibilidade em runtime para o status do Discord: saudável => online, degradado ou desconhecido => idle, esgotado ou indisponível => dnd. Substituições opcionais de texto: + 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: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1033,39 +1035,39 @@ Configurações padrão de comandos slash: - O Discord oferece suporte ao processamento de aprovações por botões em DMs e pode, opcionalmente, publicar prompts de aprovação no canal de origem. + 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. Caminho de configuração: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como fallback quando possível) + - `channels.discord.execApprovals.approvers` (opcional; recorre a `commands.ownerAllowFrom` quando possível) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord habilita automaticamente aprovações nativas de execução quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou de `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 um cliente de aprovação nativo. + 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. - Para comandos sensíveis de grupo restritos ao proprietário, como `/diagnostics` e `/export-trajectory`, o 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 tem uma rota de proprietário no Discord; se isso não estiver disponível, ele usa como fallback a primeira rota de proprietário disponível em `commands.ownerAllowFrom`, como Telegram. + 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. - Quando `target` é `channel` ou `both`, o prompt de aprovação fica visível no canal. Apenas 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 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 usa entrega por DM como fallback. + 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. - 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 para canais. - Quando esses botões estão presentes, eles são a UX de aprovação principal; o OpenClaw - 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. - Se o runtime de aprovação nativa do Discord não estiver ativo, o OpenClaw mantém o - prompt determinístico local `/approve ` visível. Se o + 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 + 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 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` exato da aprovação pendente. - A autenticação do Gateway e a resolução de aprovações seguem o contrato compartilhado do cliente Gateway (IDs `plugin:` resolvem por `plugin.approval.resolve`; outros IDs por `exec.approval.resolve`). As aprovações expiram após 30 minutos por padrão. + 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. Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals). -## Ferramentas e gates de ação +## Ferramentas e portões 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. @@ -1078,22 +1080,22 @@ 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 gates de ação ficam em `channels.discord.actions.*`. +Os portões de ação ficam em `channels.discord.actions.*`. -Comportamento padrão dos gates: +Comportamento padrão dos portões: -| Grupo de ações | Padrão | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | habilitado | +| Grupo de ações | Padrão | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | habilitado | | roles | desabilitado | | moderation | desabilitado | | presence | desabilitado | -## UI de componentes v2 +## UI Components 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. -- `channels.discord.ui.components.accentColor` define a cor de destaque usada por contêineres de componentes do Discord (hex). +- `channels.discord.ui.components.accentColor` define a cor de destaque usada pelos 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. @@ -1115,20 +1117,20 @@ Exemplo: ## Voz -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. +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. ### 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ção/usuário forem usadas. +2. Habilite Server Members Intent quando allowlists de funções/usuários 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`). 6. Configure `channels.discord.voice`. -Use `/vc join|leave|status` para controlar sessões. O comando usa o agente padrão da conta e segue as mesmas regras de allowlist e política de grupo de outros comandos do Discord. +Use `/vc join|leave|status` para controlar sessões. O comando usa o agente padrão da conta e segue as mesmas regras de allowlist e política de grupo que outros comandos do Discord. ```bash /vc join channel: @@ -1168,35 +1170,35 @@ Exemplo de entrada automática: 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 indefinido para herdar o modelo do agente roteado. +- `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` por canal do Discord se aplicam aos 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 não proprietários não podem acessar ferramentas restritas ao proprietário (por exemplo, `gateway` e `cron`). -- Voz do Discord é opcional para configs 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 o intent de Gateway `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` pode substituir explicitamente a assinatura do intent de estado de voz. Deixe indefinido para que o intent acompanhe a habilitação efetiva de voz. -- `voice.daveEncryption` e `voice.decryptionFailureTolerance` são repassados para as opções de entrada de `@discordjs/voice`. -- Os padrões de `@discordjs/voice` são `daveEncryption=true` e `decryptionFailureTolerance=24` se indefinidos. -- `voice.connectTimeoutMs` controla a espera inicial de Ready do `@discordjs/voice` para `/vc join` e tentativas de entrada automática. Padrão: `30000`. -- `voice.reconnectGraceMs` controla por quanto tempo o OpenClaw espera uma sessão de voz desconectada começar a reconectar antes de destruí-la. Padrão: `15000`. -- O 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 empacotada de `@discordjs/voice` inclui a correção upstream de padding do PR #11449 do discord.js, que fechou a issue #11419 do discord.js. +- Substituições de `systemPrompt` do Discord por canal se aplicam aos 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`. +- `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. Pipeline de canal de voz: - A captura PCM do Discord é convertida em 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 pede texto retornado, porque a voz do Discord é responsável pela reprodução final de TTS. -- `voice.model`, quando definido, substitui apenas o LLM de resposta para este turno de canal de voz. +- 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. -As credenciais são resolvidas por componente: autenticação de rota LLM para `voice.model`, autenticação STT para `tools.media.audio` e autenticação TTS para `messages.tts`/`voice.tts`. +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`. ### 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. - Forneça um **caminho de arquivo local** (URLs são rejeitadas). -- Omita conteúdo de texto (Discord rejeita texto + mensagem de voz no mesmo payload). +- 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. ```bash @@ -1206,10 +1208,10 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Solução de problemas - + - habilite Message Content Intent - - habilite Server Members Intent quando você depender de resolução de usuário/membro + - habilite Server Members Intent quando depender da resolução de usuário/membro - reinicie o Gateway após alterar intents @@ -1218,7 +1220,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - verifique `groupPolicy` - verifique a allowlist de guilda em `channels.discord.guilds` - - se o mapa `channels` da guilda existir, apenas os canais listados são permitidos + - se o mapa `channels` da guilda existir, somente canais listados serão permitidos - verifique o comportamento de `requireMention` e os padrões de menção Verificações úteis: @@ -1250,10 +1252,10 @@ openclaw logs --follow Ajustes da fila do Gateway do Discord: - conta única: `channels.discord.eventQueue.listenerTimeout` - - múltiplas contas: `channels.discord.accounts..eventQueue.listenerTimeout` - - isto controla apenas o trabalho do listener do Gateway do Discord, não a duração do turno do agente + - 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 - 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. + 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. ```json5 { @@ -1274,37 +1276,37 @@ openclaw logs --follow - O OpenClaw busca metadados `/gateway/bot` do Discord antes de conectar. Falhas transitórias usam como fallback a URL padrão de Gateway do Discord e são limitadas por taxa nos logs. + 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. Ajustes de timeout de metadados: - conta única: `channels.discord.gatewayInfoTimeoutMs` - - múltiplas contas: `channels.discord.accounts..gatewayInfoTimeoutMs` - - fallback de env quando a config está indefinida: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - padrão: `30000` (30 segundos), máx.: `120000` + - várias contas: `channels.discord.accounts..gatewayInfoTimeoutMs` + - fallback de env quando a configuração não está definida: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - padrão: `30000` (30 segundos), máximo: `120000` - 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 mais longa 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 de READY de inicialização maior que o padrão. Controles de timeout 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áximo: `120000` + - 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áximo: `120000` + - padrão em tempo de execução: `30000` (30 segundos), máx.: `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 a sondagem não consegue verificar permissões totalmente. + 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. @@ -1319,7 +1321,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 allowlist para evitar comportamento de loop. + Se você definir `channels.discord.allowBots=true`, use regras estritas de menção e lista de permissões para evitar comportamento de loop. Prefira `channels.discord.allowBots="mentions"` para aceitar apenas mensagens de bots que mencionem o bot. ```json5 @@ -1328,14 +1330,14 @@ openclaw logs --follow discord: { accounts: { mantis: { - // Mantis escuta outros bots apenas quando eles a mencionam. + // Mantis listens to other bots only when they mention her. allowBots: "mentions", }, molty: { - // Molty escuta todas as mensagens do Discord criadas por bots. + // Molty listens to all bot-authored Discord messages. allowBots: true, mentionAliases: { - // Permite que Molty escreva "@Mantis" e envie uma menção real do Discord. + // Lets Molty write "@Mantis" and send a real Discord mention. Mantis: "MANTIS_DISCORD_USER_ID", }, }, @@ -1351,11 +1353,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 por `channels.discord.voice.decryptionFailureTolerance=24` (padrão upstream) e ajuste apenas se necessário - - monitore os logs por: + - comece com `channels.discord.voice.decryptionFailureTolerance=24` (padrão upstream) e ajuste apenas se necessário + - monitore os logs para: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - se as falhas continuarem após a reconexão 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 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) @@ -1364,17 +1366,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/repetição: `mediaMaxMb` (limita uploads de saída do Discord, padrão `100MB`), `retry` +- mídia/tentativa: `mediaMaxMb` (limita uploads de saída do Discord, padrão `100MB`), `retry` - ações: `actions.*` - presença: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` @@ -1384,29 +1386,29 @@ Referência principal: [Referência de configuração - Discord](/pt-BR/gateway/ ## Segurança e operações -- Trate tokens de bot como segredos (`DISCORD_BOT_TOKEN` preferido em ambientes supervisionados). +- 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 obsoleta, reinicie o Gateway e verifique novamente com `openclaw channels status --probe`. +- Se a implantação/estado de comandos estiver obsoleto, 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 allowlist. + Comportamento de chat em grupo e lista de permissões. - Encaminhe mensagens de entrada para agentes. + Roteie mensagens de entrada para agentes. - Modelo de ameaças e hardening. + Modelo de ameaça e endurecimento. Mapeie guildas e canais para agentes. - + Comportamento de comando nativo. diff --git a/docs/pt-BR/channels/googlechat.md b/docs/pt-BR/channels/googlechat.md index b503ab9ff..19f359a94 100644 --- a/docs/pt-BR/channels/googlechat.md +++ b/docs/pt-BR/channels/googlechat.md @@ -1,20 +1,20 @@ --- read_when: - - Trabalhando nos recursos do canal do Google Chat -summary: Status de suporte, recursos e configuração do app do Google Chat + - Trabalhando nos recursos do canal Google Chat +summary: Status de suporte, recursos e configuração do app Google Chat title: Google Chat x-i18n: - generated_at: "2026-05-02T20:41:31Z" + generated_at: "2026-05-04T02:21:19Z" model: gpt-5.5 provider: openai - source_hash: fdb8dcf651602e92801d7107646d853871ea6cef188a8733a831695a1243740e + source_hash: afa2ca4d9673396aa24a55ca5855a34ad26a4640c3a1f6928dbf7246e403cb04 source_path: channels/googlechat.md workflow: 16 --- -Status: Plugin baixável para DMs + espaços via webhooks da API do Google Chat (somente HTTP). +Status: Plugin baixável para DMs + espaços via webhooks da Google Chat API (somente HTTP). -## Instalar +## Instalação Instale o Google Chat antes de configurar o canal: @@ -30,63 +30,63 @@ openclaw plugins install ./path/to/local/googlechat-plugin ## Configuração rápida (iniciante) -1. Crie um projeto do Google Cloud e habilite a **API do Google Chat**. - - Acesse: [Credenciais da API do Google Chat](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) +1. Crie um projeto do Google Cloud e habilite a **Google Chat API**. + - Acesse: [Credenciais da Google Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) - Habilite a API se ela ainda não estiver habilitada. -2. Crie uma **conta de serviço**: - - Pressione **Criar credenciais** > **Conta de serviço**. +2. Crie uma **Conta de serviço**: + - Pressione **Create Credentials** > **Service Account**. - Dê o nome que quiser (por exemplo, `openclaw-chat`). - - Deixe as permissões em branco (pressione **Continuar**). - - Deixe os principais com acesso em branco (pressione **Concluído**). -3. Crie e baixe a **chave JSON**: - - Na lista de contas de serviço, clique na que você acabou de criar. - - Acesse a aba **Chaves**. - - Clique em **Adicionar chave** > **Criar nova chave**. - - Selecione **JSON** e pressione **Criar**. -4. Armazene o arquivo JSON baixado no host do Gateway (por exemplo, `~/.openclaw/googlechat-service-account.json`). -5. Crie um app do Google Chat na [Configuração do Chat no Console do Google Cloud](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): - - Preencha as **informações do aplicativo**: + - Deixe as permissões em branco (pressione **Continue**). + - Deixe os principais com acesso em branco (pressione **Done**). +3. Crie e baixe a **Chave JSON**: + - Na lista de contas de serviço, clique naquela que você acabou de criar. + - Acesse a aba **Keys**. + - Clique em **Add Key** > **Create new key**. + - Selecione **JSON** e pressione **Create**. +4. Armazene o arquivo JSON baixado no host do seu Gateway (por exemplo, `~/.openclaw/googlechat-service-account.json`). +5. Crie um app do Google Chat na [Configuração do Chat no Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): + - Preencha as **Informações do aplicativo**: - **Nome do app**: (por exemplo, `OpenClaw`) - **URL do avatar**: (por exemplo, `https://openclaw.ai/logo.png`) - **Descrição**: (por exemplo, `Assistente pessoal de IA`) - Habilite **Recursos interativos**. - Em **Funcionalidade**, marque **Participar de espaços e conversas em grupo**. - - Em **Configurações de conexão**, selecione **URL do endpoint HTTP**. - - Em **Acionadores**, selecione **Usar uma URL de endpoint HTTP comum para todos os acionadores** e defina-a como a URL pública do seu Gateway seguida de `/googlechat`. + - Em **Configurações de conexão**, selecione **URL de endpoint HTTP**. + - Em **Gatilhos**, selecione **Usar uma URL de endpoint HTTP comum para todos os gatilhos** e defina-a como a URL pública do seu Gateway seguida de `/googlechat`. - _Dica: execute `openclaw status` para encontrar a URL pública do seu Gateway._ - - Em **Visibilidade**, marque **Disponibilizar este app do Chat para pessoas e grupos específicos em ``**. - - Insira seu endereço de e-mail (por exemplo, `user@example.com`) na caixa de texto. - - Clique em **Salvar** na parte inferior. + - Em **Visibilidade**, marque **Tornar este app do Chat disponível para pessoas e grupos específicos em ``**. + - Insira seu endereço de email (por exemplo, `user@example.com`) na caixa de texto. + - Clique em **Save** na parte inferior. 6. **Habilite o status do app**: - Depois de salvar, **atualize a página**. - - Procure a seção **Status do app** (geralmente perto do topo ou da parte inferior após salvar). - - Altere o status para **Ativo - disponível para usuários**. - - Clique em **Salvar** novamente. -7. Configure o OpenClaw com o caminho da conta de serviço + público do webhook: + - Procure a seção **Status do app** (geralmente perto do topo ou da parte inferior depois de salvar). + - Altere o status para **Live - available to users**. + - Clique em **Save** novamente. +7. Configure o OpenClaw com o caminho da conta de serviço + público do Webhook: - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` - Ou config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`. -8. Defina o tipo + valor do público do webhook (corresponde à configuração do seu app do Chat). -9. Inicie o Gateway. O Google Chat fará POST para o caminho do seu webhook. +8. Defina o tipo + valor do público do Webhook (corresponde à configuração do seu app do Chat). +9. Inicie o Gateway. O Google Chat enviará POST para o caminho do seu Webhook. ## Adicionar ao Google Chat -Depois que o Gateway estiver em execução e seu e-mail tiver sido adicionado à lista de visibilidade: +Depois que o Gateway estiver em execução e seu email for adicionado à lista de visibilidade: 1. Acesse [Google Chat](https://chat.google.com/). 2. Clique no ícone **+** (mais) ao lado de **Mensagens diretas**. -3. Na barra de pesquisa (onde você normalmente adiciona pessoas), digite o **nome do app** que você configurou no Console do Google Cloud. - - **Observação**: o bot _não_ aparecerá na lista de navegação do "Marketplace" porque é um app privado. Você precisa procurá-lo pelo nome. +3. Na barra de pesquisa (onde você geralmente adiciona pessoas), digite o **Nome do app** que você configurou no Google Cloud Console. + - **Observação**: o bot _não_ aparecerá na lista de navegação do "Marketplace" porque é um app privado. Você deve pesquisá-lo pelo nome. 4. Selecione seu bot nos resultados. 5. Clique em **Adicionar** ou **Chat** para iniciar uma conversa 1:1. 6. Envie "Olá" para acionar o assistente! ## URL pública (somente Webhook) -Webhooks do Google Chat exigem um endpoint HTTPS público. Por segurança, **exponha somente o caminho `/googlechat`** à internet. Mantenha o painel do OpenClaw e outros endpoints sensíveis na sua rede privada. +Webhooks do Google Chat exigem um endpoint HTTPS público. Por segurança, **exponha somente o caminho `/googlechat`** para a internet. Mantenha o painel do OpenClaw e outros endpoints sensíveis na sua rede privada. ### Opção A: Tailscale Funnel (recomendado) -Use Tailscale Serve para o painel privado e Funnel para o caminho público do webhook. Isso mantém `/` privado enquanto expõe somente `/googlechat`. +Use o Tailscale Serve para o painel privado e o Funnel para o caminho público do Webhook. Isso mantém `/` privado enquanto expõe somente `/googlechat`. 1. **Verifique a qual endereço seu Gateway está vinculado:** @@ -94,30 +94,30 @@ Use Tailscale Serve para o painel privado e Funnel para o caminho público do we ss -tlnp | grep 18789 ``` - Anote o endereço IP (por exemplo, `127.0.0.1`, `0.0.0.0` ou seu IP do Tailscale, como `100.x.x.x`). + Observe o endereço IP (por exemplo, `127.0.0.1`, `0.0.0.0` ou seu IP do Tailscale, como `100.x.x.x`). -2. **Exponha o painel somente à tailnet (porta 8443):** +2. **Exponha o painel apenas para a tailnet (porta 8443):** ```bash - # Se estiver vinculado ao localhost (127.0.0.1 ou 0.0.0.0): + # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale serve --bg --https 8443 http://127.0.0.1:18789 - # Se estiver vinculado somente ao IP do Tailscale (por exemplo, 100.106.161.80): + # If bound to Tailscale IP only (e.g., 100.106.161.80): tailscale serve --bg --https 8443 http://100.106.161.80:18789 ``` -3. **Exponha publicamente somente o caminho do webhook:** +3. **Exponha publicamente somente o caminho do Webhook:** ```bash - # Se estiver vinculado ao localhost (127.0.0.1 ou 0.0.0.0): + # If bound to localhost (127.0.0.1 or 0.0.0.0): tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat - # Se estiver vinculado somente ao IP do Tailscale (por exemplo, 100.106.161.80): + # If bound to Tailscale IP only (e.g., 100.106.161.80): tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat ``` -4. **Autorize o Node para acesso ao Funnel:** - Se solicitado, visite a URL de autorização mostrada na saída para habilitar o Funnel para este Node na política da sua tailnet. +4. **Autorize o nó para acesso ao Funnel:** + Se solicitado, acesse a URL de autorização exibida na saída para habilitar o Funnel para este nó na política da sua tailnet. 5. **Verifique a configuração:** @@ -126,19 +126,19 @@ Use Tailscale Serve para o painel privado e Funnel para o caminho público do we tailscale funnel status ``` -Sua URL pública do webhook será: +Sua URL pública do Webhook será: `https://..ts.net/googlechat` -Seu painel privado permanece somente na tailnet: +Seu painel privado permanece acessível apenas pela tailnet: `https://..ts.net:8443/` Use a URL pública (sem `:8443`) na configuração do app do Google Chat. > Observação: esta configuração persiste entre reinicializações. Para removê-la depois, execute `tailscale funnel reset` e `tailscale serve reset`. -### Opção B: Proxy reverso (Caddy) +### Opção B: proxy reverso (Caddy) -Se você usa um proxy reverso como o Caddy, faça proxy somente do caminho específico: +Se você usa um proxy reverso como o Caddy, encaminhe somente o caminho específico: ```caddy your-domain.com { @@ -150,33 +150,33 @@ Com esta configuração, qualquer solicitação para `your-domain.com/` será ig ### Opção C: Cloudflare Tunnel -Configure as regras de ingresso do seu túnel para rotear somente o caminho do webhook: +Configure as regras de ingresso do seu túnel para rotear somente o caminho do Webhook: - **Caminho**: `/googlechat` -> `http://localhost:18789/googlechat` - **Regra padrão**: HTTP 404 (Não encontrado) ## Como funciona -1. O Google Chat envia POSTs de webhook para o Gateway. Cada solicitação inclui um cabeçalho `Authorization: Bearer `. - - O OpenClaw verifica a autenticação bearer antes de ler/analisar corpos completos de webhook quando o cabeçalho está presente. - - Solicitações de Complementos do Google Workspace que carregam `authorizationEventObject.systemIdToken` no corpo têm suporte por meio de um orçamento de corpo de pré-autenticação mais rigoroso. -2. O OpenClaw verifica o token em relação ao `audienceType` + `audience` configurado: - - `audienceType: "app-url"` → o público é a URL HTTPS do seu webhook. +1. O Google Chat envia POSTs de Webhook para o Gateway. Cada solicitação inclui um cabeçalho `Authorization: Bearer `. + - O OpenClaw verifica a autenticação bearer antes de ler/analisar corpos completos de Webhook quando o cabeçalho está presente. + - Solicitações do Google Workspace Add-on que carregam `authorizationEventObject.systemIdToken` no corpo são compatíveis por meio de um orçamento de corpo pré-autenticação mais rigoroso. +2. O OpenClaw verifica o token em relação ao `audienceType` + `audience` configurados: + - `audienceType: "app-url"` → o público é a URL HTTPS do seu Webhook. - `audienceType: "project-number"` → o público é o número do projeto Cloud. 3. As mensagens são roteadas por espaço: - DMs usam a chave de sessão `agent::googlechat:direct:`. - Espaços usam a chave de sessão `agent::googlechat:group:`. -4. O acesso por DM usa pareamento por padrão. Remetentes desconhecidos recebem um código de pareamento; aprove com: +4. O acesso por DM usa emparelhamento por padrão. Remetentes desconhecidos recebem um código de emparelhamento; aprove com: - `openclaw pairing approve googlechat ` -5. Espaços de grupo exigem @menção por padrão. Use `botUser` se a detecção de menção precisar do nome de usuário do app. +5. Espaços de grupo exigem @-menção por padrão. Use `botUser` se a detecção de menção precisar do nome de usuário do app. ## Destinos -Use estes identificadores para entrega e listas de permissão: +Use estes identificadores para entrega e listas de permissões: - Mensagens diretas: `users/` (recomendado). -- E-mail bruto `name@example.com` é mutável e usado somente para correspondência de lista de permissão direta quando `channels.googlechat.dangerouslyAllowNameMatching: true`. -- Obsoleto: `users/` é tratado como um ID de usuário, não como uma lista de permissão de e-mail. +- Email bruto `name@example.com` é mutável e usado somente para correspondência direta de lista de permissões quando `channels.googlechat.dangerouslyAllowNameMatching: true`. +- Obsoleto: `users/` é tratado como um id de usuário, não como uma lista de permissões de email. - Espaços: `spaces/`. ## Destaques de configuração @@ -199,7 +199,7 @@ Use estes identificadores para entrega e listas de permissão: groupPolicy: "allowlist", groups: { "spaces/AAAA": { - allow: true, + enabled: true, requireMention: true, users: ["users/1234567890"], systemPrompt: "Short answers only.", @@ -215,14 +215,14 @@ Use estes identificadores para entrega e listas de permissão: Observações: -- As credenciais da conta de serviço também podem ser passadas inline com `serviceAccount` (string JSON). -- `serviceAccountRef` também tem suporte (env/file SecretRef), incluindo refs por conta em `channels.googlechat.accounts..serviceAccountRef`. -- O caminho padrão do webhook é `/googlechat` se `webhookPath` não estiver definido. -- `dangerouslyAllowNameMatching` reabilita a correspondência de principal de e-mail mutável para listas de permissão (modo de compatibilidade de emergência). -- Reações estão disponíveis pela ferramenta `reactions` e por `channels action` quando `actions.reactions` está habilitado. -- Ações de mensagem expõem `send` para texto e `upload-file` para envios explícitos de anexo. `upload-file` aceita `media` / `filePath` / `path` mais `message`, `filename` e direcionamento de thread opcionais. -- `typingIndicator` dá suporte a `none`, `message` (padrão) e `reaction` (reação exige OAuth de usuário). -- Anexos são baixados pela API do Chat e armazenados no pipeline de mídia (tamanho limitado por `mediaMaxMb`). +- Credenciais de conta de serviço também podem ser passadas inline com `serviceAccount` (string JSON). +- `serviceAccountRef` também é compatível (env/file SecretRef), incluindo refs por conta em `channels.googlechat.accounts..serviceAccountRef`. +- O caminho padrão do Webhook é `/googlechat` se `webhookPath` não estiver definido. +- `dangerouslyAllowNameMatching` reabilita a correspondência mutável de principal por email para listas de permissões (modo de compatibilidade de emergência). +- Reações estão disponíveis por meio da ferramenta `reactions` e de `channels action` quando `actions.reactions` está habilitado. +- Ações de mensagem expõem `send` para texto e `upload-file` para envios explícitos de anexos. `upload-file` aceita `media` / `filePath` / `path`, além de `message`, `filename` e direcionamento de thread opcionais. +- `typingIndicator` aceita `none`, `message` (padrão) e `reaction` (`reaction` exige OAuth de usuário). +- Anexos são baixados por meio da Chat API e armazenados no pipeline de mídia (tamanho limitado por `mediaMaxMb`). Detalhes de referência de segredos: [Gerenciamento de segredos](/pt-BR/gateway/secrets). @@ -236,7 +236,7 @@ Se o Google Cloud Logs Explorer mostrar erros como: status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed ``` -Isso significa que o manipulador do webhook não está registrado. Causas comuns: +Isso significa que o manipulador do Webhook não está registrado. Causas comuns: 1. **Canal não configurado**: a seção `channels.googlechat` está ausente da sua configuração. Verifique com: @@ -244,7 +244,7 @@ Isso significa que o manipulador do webhook não está registrado. Causas comuns openclaw config get channels.googlechat ``` - Se retornar "Config path not found", adicione a configuração (consulte [Destaques de configuração](#config-highlights)). + Se retornar "Caminho de configuração não encontrado", adicione a configuração (consulte [Destaques de configuração](#config-highlights)). 2. **Plugin não habilitado**: verifique o status do Plugin: @@ -252,7 +252,7 @@ Isso significa que o manipulador do webhook não está registrado. Causas comuns openclaw plugins list | grep googlechat ``` - Se mostrar "disabled", adicione `plugins.entries.googlechat.enabled: true` à sua configuração. + Se mostrar "desabilitado", adicione `plugins.entries.googlechat.enabled: true` à sua configuração. 3. **Gateway não reiniciado**: depois de adicionar a configuração, reinicie o Gateway: @@ -270,20 +270,20 @@ openclaw channels status ### Outros problemas - Verifique `openclaw channels status --probe` para erros de autenticação ou configuração de público ausente. -- Se nenhuma mensagem chegar, confirme a URL do webhook do app do Chat + assinaturas de eventos. -- Se o controle por menção bloquear respostas, defina `botUser` como o nome do recurso de usuário do app e verifique `requireMention`. -- Use `openclaw logs --follow` enquanto envia uma mensagem de teste para ver se as solicitações chegam ao Gateway. +- Se nenhuma mensagem chegar, confirme a URL do Webhook do app do Chat + assinaturas de evento. +- Se o bloqueio por menção impedir respostas, defina `botUser` como o nome do recurso de usuário do app e verifique `requireMention`. +- Use `openclaw logs --follow` ao enviar uma mensagem de teste para ver se as solicitações chegam ao Gateway. -Documentação relacionada: +Documentos relacionados: - [Configuração do Gateway](/pt-BR/gateway/configuration) - [Segurança](/pt-BR/gateway/security) - [Reações](/pt-BR/tools/reactions) -## Relacionado +## Relacionados - [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis -- [Pareamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de pareamento -- [Grupos](/pt-BR/channels/groups) — comportamento de chats em grupo e controle por menção -- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens -- [Segurança](/pt-BR/gateway/security) — modelo de acesso e fortalecimento +- [Emparelhamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de emparelhamento +- [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e bloqueio por menção +- [Roteamento de canal](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens +- [Segurança](/pt-BR/gateway/security) — modelo de acesso e proteção diff --git a/docs/pt-BR/channels/groups.md b/docs/pt-BR/channels/groups.md index e8b347f1c..8dd746c61 100644 --- a/docs/pt-BR/channels/groups.md +++ b/docs/pt-BR/channels/groups.md @@ -2,37 +2,37 @@ read_when: - Alteração do comportamento de chats em grupo ou do controle por menções sidebarTitle: Groups -summary: Comportamento de conversas em grupo em diferentes superfícies (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) +summary: Comportamento de chats em grupo em diferentes superfícies (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: Grupos x-i18n: - generated_at: "2026-05-03T21:27:19Z" + generated_at: "2026-05-04T02:21:20Z" model: gpt-5.5 provider: openai - source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116 + source_hash: dea506c011a5d8f6155b2f56aacb236482cb8c5b7457001cb2171fd45932443d source_path: channels/groups.md workflow: 16 --- -OpenClaw trata chats em grupo de forma consistente em todas as superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo. +OpenClaw trata chats em grupo de forma consistente entre superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo. ## Introdução para iniciantes (2 minutos) -OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário bot separado do WhatsApp. Se **você** está em um grupo, o OpenClaw pode ver esse grupo e responder ali. +OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário de bot separado no WhatsApp. Se **você** está em um grupo, OpenClaw pode ver esse grupo e responder nele. Comportamento padrão: - Grupos são restritos (`groupPolicy: "allowlist"`). -- Respostas exigem uma menção, a menos que você desative explicitamente o controle por menção. +- Respostas exigem uma menção, a menos que você desative explicitamente o bloqueio por menção. - Respostas finais normais em grupos/canais são privadas por padrão. Saída visível na sala usa a ferramenta `message`. -Em outras palavras: remetentes na lista de permissões podem acionar o OpenClaw mencionando-o. +Tradução: remetentes na lista de permissões podem acionar o OpenClaw mencionando-o. -**Resumo** +**TL;DR** -- **Acesso por mensagem direta** é controlado por `*.allowFrom`. -- **Acesso por grupo** é controlado por `*.groupPolicy` + listas de permissões (`*.groups`, `*.groupAllowFrom`). -- **Acionamento de resposta** é controlado pelo controle por menção (`requireMention`, `/activation`). +- **Acesso por DM** é controlado por `*.allowFrom`. +- **Acesso a grupos** é controlado por `*.groupPolicy` + listas de permissões (`*.groups`, `*.groupAllowFrom`). +- **Acionamento de resposta** é controlado pelo bloqueio por menção (`requireMention`, `/activation`). @@ -47,18 +47,27 @@ otherwise -> reply ## Respostas visíveis -Para salas de grupo/canal, o padrão do OpenClaw é `messages.groupChat.visibleReplies: "message_tool"`. +Para salas de grupo/canal, OpenClaw usa por padrão `messages.groupChat.visibleReplies: "message_tool"`. `openclaw doctor --fix` grava esse padrão nas configurações de canais configurados que o omitem. Isso significa que o agente ainda processa o turno e pode atualizar o estado de memória/sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar de forma visível, o agente usa `message(action=send)`. -Se a ferramenta de mensagens estiver indisponível sob a política de ferramentas ativa, o OpenClaw recorre a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. -`openclaw doctor` alerta sobre essa incompatibilidade. +Esse padrão depende de um modelo/runtime que chama ferramentas de forma confiável. Se os logs mostrarem +texto do assistente mas `didSendViaMessagingTool: false`, o modelo respondeu +privadamente em vez de chamar a ferramenta de mensagem. Isso não é uma falha de envio do +Discord/Slack/Telegram. Use um modelo confiável para chamadas de ferramenta em +sessões de grupo/canal, ou defina +`messages.groupChat.visibleReplies: "automatic"` para restaurar as respostas finais +visíveis legadas. -Para conversas diretas e qualquer outro turno de origem, use `messages.visibleReplies: "message_tool"` para aplicar globalmente o mesmo comportamento de resposta visível somente por ferramenta. Arneses também podem escolher isso como seu padrão não definido; o arnês do Codex faz isso para chats diretos no modo Codex. `messages.groupChat.visibleReplies` continua sendo a substituição mais específica para salas de grupo/canal. +Se a ferramenta de mensagem estiver indisponível sob a política de ferramentas ativa, OpenClaw volta +a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. +`openclaw doctor` avisa sobre essa incompatibilidade. -Isso substitui o padrão antigo de forçar o modelo a responder `NO_REPLY` para a maioria dos turnos em modo de observação. No modo somente ferramenta, não fazer nada visível significa simplesmente não chamar a ferramenta de mensagens. +Para chats diretos e qualquer outro turno de origem, use `messages.visibleReplies: "message_tool"` para aplicar globalmente o mesmo comportamento de resposta visível apenas por ferramenta. Harnesses também podem escolher isso como seu padrão não definido; o harness do Codex faz isso para chats diretos em modo Codex. `messages.groupChat.visibleReplies` continua sendo a substituição mais específica para salas de grupo/canal. -Indicadores de digitação ainda são enviados enquanto o agente trabalha no modo somente ferramenta. O modo padrão de digitação em grupo é atualizado de "message" para "instant" nesses turnos porque pode nunca haver texto normal de mensagem do assistente antes de o agente decidir se chama a ferramenta de mensagens. A configuração explícita de modo de digitação ainda prevalece. +Isso substitui o antigo padrão de forçar o modelo a responder `NO_REPLY` na maioria dos turnos em modo de observação. No modo somente ferramenta, não fazer nada visível significa simplesmente não chamar a ferramenta de mensagem. + +Indicadores de digitação ainda são enviados enquanto o agente trabalha em modo somente ferramenta. O modo padrão de digitação em grupo é elevado de "message" para "instant" nesses turnos porque pode nunca haver texto normal de mensagem do assistente antes que o agente decida chamar ou não a ferramenta de mensagem. A configuração explícita do modo de digitação ainda prevalece. Para restaurar respostas finais automáticas legadas para salas de grupo/canal: @@ -72,9 +81,10 @@ Para restaurar respostas finais automáticas legadas para salas de grupo/canal: } ``` -O Gateway recarrega a configuração `messages` a quente depois que o arquivo é salvo. Reinicie somente quando a observação de arquivos ou o recarregamento de configuração estiver desativado na implantação. +O Gateway recarrega a configuração de `messages` a quente depois que o arquivo é salvo. Reinicie somente +quando a observação de arquivos ou o recarregamento de configuração estiver desativado na implantação. -Para exigir que a saída visível passe pela ferramenta de mensagens em todos os chats de origem: +Para exigir que a saída visível passe pela ferramenta de mensagem em todo chat de origem: ```json5 { @@ -84,7 +94,7 @@ Para exigir que a saída visível passe pela ferramenta de mensagens em todos os } ``` -Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte a comandos nativos) ignoram `visibleReplies: "message_tool"` e sempre respondem de forma visível para que a interface nativa de comandos do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos `/...` digitados como texto e turnos comuns de chat ainda seguem o padrão de grupo configurado. +Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte nativo a comandos) ignoram `visibleReplies: "message_tool"` e sempre respondem de forma visível para que a UI de comando nativa do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos `/...` digitados como texto e turnos de chat comuns ainda seguem o padrão de grupo configurado. ## Visibilidade de contexto e listas de permissões @@ -93,15 +103,15 @@ Dois controles diferentes estão envolvidos na segurança de grupos: - **Autorização de acionamento**: quem pode acionar o agente (`groupPolicy`, `groups`, `groupAllowFrom`, listas de permissões específicas do canal). - **Visibilidade de contexto**: qual contexto suplementar é injetado no modelo (texto de resposta, citações, histórico de thread, metadados encaminhados). -Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o contexto quase como recebido. Isso significa que listas de permissões decidem principalmente quem pode acionar ações, não um limite universal de redação para cada trecho citado ou histórico. +Por padrão, OpenClaw prioriza o comportamento normal de chat e mantém o contexto principalmente como recebido. Isso significa que listas de permissões decidem principalmente quem pode acionar ações, não um limite universal de redação para cada trecho citado ou histórico. - - - Alguns canais já aplicam filtragem baseada em remetente para contexto suplementar em caminhos específicos (por exemplo, semeadura de threads no Slack, buscas de resposta/thread no Matrix). + + - Alguns canais já aplicam filtragem baseada no remetente para contexto suplementar em caminhos específicos (por exemplo, inicialização de thread no Slack, buscas de resposta/thread no Matrix). - Outros canais ainda passam contexto de citação/resposta/encaminhamento como recebido. - + - `contextVisibility: "all"` (padrão) mantém o comportamento atual como recebido. - `contextVisibility: "allowlist"` filtra contexto suplementar para remetentes na lista de permissões. - `contextVisibility: "allowlist_quote"` é `allowlist` mais uma exceção explícita de citação/resposta. @@ -111,24 +121,24 @@ Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o cont -![Fluxo de mensagens de grupo](/images/groups-flow.svg) +![Fluxo de mensagem de grupo](/images/groups-flow.svg) Se você quer... -| Objetivo | O que configurar | +| Objetivo | O que definir | | -------------------------------------------- | ---------------------------------------------------------- | -| Permitir todos os grupos, mas responder apenas a @menções | `groups: { "*": { requireMention: true } }` | -| Desativar todas as respostas em grupo | `groupPolicy: "disabled"` | -| Apenas grupos específicos | `groups: { "": { ... } }` (sem chave `"*"` ) | -| Apenas você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | -| Reutilizar um conjunto de remetentes confiáveis entre canais | `groupAllowFrom: ["accessGroup:operators"]` | +| Permitir todos os grupos, mas responder apenas em @menções | `groups: { "*": { requireMention: true } }` | +| Desativar todas as respostas de grupo | `groupPolicy: "disabled"` | +| Apenas grupos específicos | `groups: { "": { ... } }` (sem chave `"*"` ) | +| Apenas você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| Reutilizar um conjunto confiável de remetentes entre canais | `groupAllowFrom: ["accessGroup:operators"]` | -Para listas reutilizáveis de remetentes permitidos, veja [Grupos de acesso](/pt-BR/channels/access-groups). +Para listas de permissões reutilizáveis de remetentes, consulte [Grupos de acesso](/pt-BR/channels/access-groups). ## Chaves de sessão - Sessões de grupo usam chaves de sessão `agent:::group:` (salas/canais usam `agent:::channel:`). -- Tópicos de fórum do Telegram adicionam `:topic:` ao ID do grupo para que cada tópico tenha sua própria sessão. +- Tópicos de fórum do Telegram adicionam `:topic:` ao id do grupo para que cada tópico tenha sua própria sessão. - Chats diretos usam a sessão principal (ou por remetente, se configurado). - Heartbeats são ignorados para sessões de grupo. @@ -136,21 +146,21 @@ Para listas reutilizáveis de remetentes permitidos, veja [Grupos de acesso](/pt ## Padrão: DMs pessoais + grupos públicos (agente único) -Sim — isso funciona bem se o seu tráfego "pessoal" for **DMs** e o seu tráfego "público" for **grupos**. +Sim — isso funciona bem se o seu tráfego "pessoal" são **DMs** e o seu tráfego "público" são **grupos**. -Por quê: no modo de agente único, DMs normalmente chegam na chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main::group:`). Se você ativar sandboxing com `mode: "non-main"`, essas sessões de grupo rodam no backend de sandbox configurado enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um. +Motivo: no modo de agente único, DMs normalmente chegam na chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main::group:`). Se você ativar sandboxing com `mode: "non-main"`, essas sessões de grupo serão executadas no backend de sandbox configurado, enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um. -Isso dá a você um "cérebro" de agente (espaço de trabalho + memória compartilhados), mas duas posturas de execução: +Isso dá a você um "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução: - **DMs**: ferramentas completas (host) - **Grupos**: sandbox + ferramentas restritas -Se você precisa de espaços de trabalho/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + vinculações. Veja [Roteamento Multiagente](/pt-BR/concepts/multi-agent). +Se você precisa de workspaces/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + vinculações. Consulte [Roteamento multiagente](/pt-BR/concepts/multi-agent). - + ```json5 { agents: { @@ -174,8 +184,8 @@ Se você precisa de espaços de trabalho/personas realmente separados ("pessoal" } ``` - - Quer "grupos só podem ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte apenas caminhos na lista de permissões dentro do sandbox: + + Quer que "grupos só possam ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte apenas caminhos na lista de permissões dentro do sandbox: ```json5 { @@ -203,12 +213,12 @@ Se você precisa de espaços de trabalho/personas realmente separados ("pessoal" Relacionado: - Chaves de configuração e padrões: [Configuração do Gateway](/pt-BR/gateway/config-agents#agentsdefaultssandbox) -- Depurar por que uma ferramenta está bloqueada: [Sandbox vs Política de Ferramentas vs Elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated) -- Detalhes de montagens bind: [Sandboxing](/pt-BR/gateway/sandboxing#custom-bind-mounts) +- Depuração de por que uma ferramenta está bloqueada: [Sandbox vs Política de ferramentas vs Elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated) +- Detalhes de montagens de vinculação: [Sandboxing](/pt-BR/gateway/sandboxing#custom-bind-mounts) ## Rótulos de exibição -- Rótulos da interface usam `displayName` quando disponível, formatado como `:`. +- Rótulos da UI usam `displayName` quando disponível, formatado como `:`. - `#room` é reservado para salas/canais; chats em grupo usam `g-` (minúsculas, espaços -> `-`, manter `#@+._-`). ## Política de grupo @@ -260,25 +270,25 @@ Controle como mensagens de grupo/sala são tratadas por canal: } ``` -| Política | Comportamento | +| Política | Comportamento | | ------------- | ------------------------------------------------------------ | -| `"open"` | Grupos ignoram listas de permissões; controle por menção ainda se aplica. | -| `"disabled"` | Bloqueia todas as mensagens de grupo completamente. | +| `"open"` | Grupos ignoram listas de permissões; o bloqueio por menção ainda se aplica. | +| `"disabled"` | Bloqueia completamente todas as mensagens de grupo. | | `"allowlist"` | Permite apenas grupos/salas que correspondem à lista de permissões configurada. | - + - `groupPolicy` é separado do controle por menção (que exige @menções). - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use `groupAllowFrom` (fallback: `allowFrom` explícito). - - Signal: `groupAllowFrom` pode corresponder ao ID de grupo Signal de entrada ou ao telefone/UUID do remetente. - - Aprovações de pareamento de DM (entradas de armazenamento `*-allowFrom`) se aplicam apenas ao acesso por DM; a autorização de remetente em grupo permanece explícita nas listas de permissões de grupo. - - Discord: a lista de permissões usa `channels.discord.guilds..channels`. - - Slack: a lista de permissões usa `channels.slack.channels`. - - Matrix: a lista de permissões usa `channels.matrix.groups`. Prefira IDs ou aliases de sala; a busca por nome de sala ingressada é de melhor esforço, e nomes não resolvidos são ignorados em tempo de execução. Use `channels.matrix.groupAllowFrom` para restringir remetentes; listas de permissões `users` por sala também têm suporte. - - DMs de grupo são controladas separadamente (`channels.discord.dm.*`, `channels.slack.dm.*`). - - A lista de permissões do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas. - - O padrão é `groupPolicy: "allowlist"`; se sua lista de permissões de grupo estiver vazia, mensagens de grupo são bloqueadas. - - Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (`channels.` ausente), a política de grupo recorre a um modo fechado por padrão (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`. + - Signal: `groupAllowFrom` pode corresponder ao id do grupo Signal de entrada ou ao telefone/UUID do remetente. + - Aprovações de pareamento por DM (entradas de armazenamento `*-allowFrom`) se aplicam apenas ao acesso por DM; a autorização de remetente em grupo permanece explícita para allowlists de grupo. + - Discord: a allowlist usa `channels.discord.guilds..channels`. + - Slack: a allowlist usa `channels.slack.channels`. + - Matrix: a allowlist usa `channels.matrix.groups`. Prefira IDs ou aliases de sala; a busca por nome em salas ingressadas é feita por melhor esforço, e nomes não resolvidos são ignorados em tempo de execução. Use `channels.matrix.groupAllowFrom` para restringir remetentes; allowlists `users` por sala também são compatíveis. + - DMs em grupo são controladas separadamente (`channels.discord.dm.*`, `channels.slack.dm.*`). + - A allowlist do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas. + - O padrão é `groupPolicy: "allowlist"`; se a allowlist do seu grupo estiver vazia, mensagens de grupo serão bloqueadas. + - Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (`channels.` ausente), a política de grupo volta para um modo de falha fechada (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`. @@ -289,19 +299,19 @@ Modelo mental rápido (ordem de avaliação para mensagens de grupo): `groupPolicy` (open/disabled/allowlist). - - Listas de permissão de grupo (`*.groups`, `*.groupAllowFrom`, lista de permissão específica do canal). + + Allowlists de grupo (`*.groups`, `*.groupAllowFrom`, allowlist específica do canal). - + Controle por menção (`requireMention`, `/activation`). ## Controle por menção (padrão) -Mensagens de grupo exigem uma menção, a menos que isso seja sobrescrito por grupo. Os padrões ficam por subsistema em `*.groups."*"`. +Mensagens de grupo exigem uma menção, salvo substituição por grupo. Os padrões ficam por subsistema em `*.groups."*"`. -Responder a uma mensagem de bot conta como uma menção implícita quando o canal oferece suporte a metadados de resposta. Citar uma mensagem de bot também pode contar como uma menção implícita em canais que expõem metadados de citação. Os casos integrados atuais incluem Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser. +Responder a uma mensagem do bot conta como uma menção implícita quando o canal oferece suporte a metadados de resposta. Citar uma mensagem do bot também pode contar como uma menção implícita em canais que expõem metadados de citação. Os casos integrados atuais incluem Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser. ```json5 { @@ -340,40 +350,40 @@ Responder a uma mensagem de bot conta como uma menção implícita quando o cana ``` - - - `mentionPatterns` são padrões regex seguros e sem diferenciação entre maiúsculas e minúsculas; padrões inválidos e formas inseguras com repetição aninhada são ignorados. + + - `mentionPatterns` são padrões regex seguros e sem diferenciação entre maiúsculas e minúsculas; padrões inválidos e formas inseguras de repetição aninhada são ignorados. - Superfícies que fornecem menções explícitas ainda passam; os padrões são um fallback. - - Sobrescrita por agente: `agents.list[].groupChat.mentionPatterns` (útil quando vários agentes compartilham um grupo). - - O controle por menção só é aplicado quando a detecção de menção é possível (menções nativas ou `mentionPatterns` configurados). - - Colocar um grupo ou remetente na lista de permissão não desativa o controle por menção; defina `requireMention` desse grupo como `false` quando todas as mensagens devem acionar. - - O contexto de prompt de chat em grupo carrega a instrução de resposta silenciosa resolvida em cada turno; os arquivos do workspace não devem duplicar a mecânica de `NO_REPLY`. - - Grupos em que respostas silenciosas são permitidas tratam turnos de modelo limpos vazios ou apenas de raciocínio como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo somente quando respostas silenciosas diretas são explicitamente permitidas; caso contrário, respostas vazias continuam sendo turnos de agente com falha. - - Os padrões do Discord ficam em `channels.discord.guilds."*"` (sobrescritíveis por guild/canal). - - O contexto de histórico de grupo é encapsulado uniformemente entre canais e é **somente pendente** (mensagens ignoradas devido ao controle por menção); use `messages.groupChat.historyLimit` para o padrão global e `channels..historyLimit` (ou `channels..accounts.*.historyLimit`) para sobrescritas. Defina `0` para desativar. + - Substituição por agente: `agents.list[].groupChat.mentionPatterns` (útil quando vários agentes compartilham um grupo). + - O controle por menção só é aplicado quando a detecção de menção é possível (menções nativas ou `mentionPatterns` estão configurados). + - Colocar um grupo ou remetente na allowlist não desativa o controle por menção; defina `requireMention` desse grupo como `false` quando todas as mensagens devem acionar. + - O contexto de prompt de chat em grupo carrega a instrução resolvida de resposta silenciosa a cada turno; arquivos do workspace não devem duplicar a mecânica de `NO_REPLY`. + - Grupos em que respostas silenciosas são permitidas tratam turnos do modelo limpos, vazios ou apenas de raciocínio como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo apenas quando respostas silenciosas diretas são permitidas explicitamente; caso contrário, respostas vazias continuam sendo turnos de agente com falha. + - Os padrões do Discord ficam em `channels.discord.guilds."*"` (substituíveis por guilda/canal). + - O contexto de histórico de grupo é encapsulado de forma uniforme entre canais e é **apenas pendente** (mensagens ignoradas devido ao controle por menção); use `messages.groupChat.historyLimit` para o padrão global e `channels..historyLimit` (ou `channels..accounts.*.historyLimit`) para substituições. Defina `0` para desativar. -## Restrições de ferramentas por grupo/canal (opcional) +## Restrições de ferramentas de grupo/canal (opcional) -Algumas configurações de canal oferecem suporte a restringir quais ferramentas ficam disponíveis **dentro de um grupo/sala/canal específico**. +Algumas configurações de canal oferecem suporte à restrição de quais ferramentas estão disponíveis **dentro de um grupo/sala/canal específico**. - `tools`: permite/nega ferramentas para o grupo inteiro. -- `toolsBySender`: sobrescritas por remetente dentro do grupo. Use prefixos de chave explícitos: `id:`, `e164:`, `username:`, `name:` e o curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondidas apenas como `id:`. +- `toolsBySender`: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: `id:`, `e164:`, `username:`, `name:` e o curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondidas apenas como `id:`. Ordem de resolução (o mais específico vence): - + Correspondência de `toolsBySender` de grupo/canal. - + `tools` de grupo/canal. - + Correspondência de `toolsBySender` padrão (`"*"`). - + `tools` padrão (`"*"`). @@ -399,28 +409,28 @@ Exemplo (Telegram): ``` -Restrições de ferramentas por grupo/canal são aplicadas além da política global/de agente para ferramentas (negação ainda vence). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). +Restrições de ferramentas de grupo/canal são aplicadas além da política global/de agente para ferramentas (negação ainda vence). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). -## Listas de permissão de grupo +## Allowlists de grupo -Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` é configurado, as chaves atuam como uma lista de permissão de grupo. Use `"*"` para permitir todos os grupos e ainda definir o comportamento padrão de menção. +Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` está configurado, as chaves atuam como uma allowlist de grupo. Use `"*"` para permitir todos os grupos e ainda definir o comportamento padrão de menção. -Confusão comum: aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento desbloqueia apenas DMs. Comandos de grupo ainda exigem autorização explícita do remetente do grupo por listas de permissão de configuração, como `groupAllowFrom`, ou pelo fallback de configuração documentado para esse canal. +Confusão comum: aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento libera apenas DMs. Comandos de grupo ainda exigem autorização explícita de remetente de grupo por allowlists de configuração, como `groupAllowFrom`, ou pelo fallback de configuração documentado para esse canal. Intenções comuns (copiar/colar): - + ```json5 { channels: { whatsapp: { groupPolicy: "disabled" } }, } ``` - + ```json5 { channels: { @@ -434,7 +444,7 @@ Intenções comuns (copiar/colar): } ``` - + ```json5 { channels: { @@ -445,7 +455,7 @@ Intenções comuns (copiar/colar): } ``` - + ```json5 { channels: { @@ -462,7 +472,7 @@ Intenções comuns (copiar/colar): ## Ativação (somente proprietário) -Proprietários de grupo podem alternar a ativação por grupo: +Proprietários de grupos podem alternar a ativação por grupo: - `/activation mention` - `/activation always` @@ -479,29 +489,29 @@ Payloads de entrada de grupo definem: - `WasMentioned` (resultado do controle por menção) - Tópicos de fórum do Telegram também incluem `MessageThreadId` e `IsForum`. -Observações específicas do canal: +Notas específicas por canal: -- BlueBubbles pode opcionalmente enriquecer participantes de grupos do macOS sem nome a partir do banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa. +- BlueBubbles pode, opcionalmente, enriquecer participantes de grupos macOS sem nome a partir do banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa. -O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como uma pessoa, evitar tabelas em Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupos e rótulos de participantes vindos do canal são renderizados como metadados não confiáveis em bloco cercado, não como instruções de sistema inline. +O prompt do sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como uma pessoa, evitar tabelas Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupos e rótulos de participantes vindos do canal são renderizados como metadados não confiáveis em bloco cercado, não como instruções de sistema inline. ## Especificidades do iMessage -- Prefira `chat_id:` ao rotear ou colocar em lista de permissão. +- Prefira `chat_id:` ao rotear ou colocar na allowlist. - Listar chats: `imsg chats --limit 20`. - Respostas de grupo sempre voltam para o mesmo `chat_id`. ## Prompts de sistema do WhatsApp -Consulte [WhatsApp](/pt-BR/channels/whatsapp#system-prompts) para as regras canônicas de prompt de sistema do WhatsApp, incluindo resolução de prompts de grupo e diretos, comportamento de curinga e semântica de sobrescrita por conta. +Consulte [WhatsApp](/pt-BR/channels/whatsapp#system-prompts) para as regras canônicas de prompt de sistema do WhatsApp, incluindo resolução de prompt de grupo e direto, comportamento de curinga e semântica de substituição de conta. ## Especificidades do WhatsApp -Consulte [Mensagens de grupo](/pt-BR/channels/group-messages) para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menções). +Consulte [Mensagens de grupo](/pt-BR/channels/group-messages) para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menção). ## Relacionado - [Grupos de transmissão](/pt-BR/channels/broadcast-groups) -- [Roteamento de canal](/pt-BR/channels/channel-routing) +- [Roteamento de canais](/pt-BR/channels/channel-routing) - [Mensagens de grupo](/pt-BR/channels/group-messages) - [Pareamento](/pt-BR/channels/pairing) diff --git a/docs/pt-BR/channels/irc.md b/docs/pt-BR/channels/irc.md index 3e628b49d..cd670b6b8 100644 --- a/docs/pt-BR/channels/irc.md +++ b/docs/pt-BR/channels/irc.md @@ -1,24 +1,24 @@ --- read_when: - - Você quer conectar o OpenClaw a canais ou DMs de IRC - - Você está configurando allowlists, política de grupo ou exigência de menção para IRC -summary: Configuração do Plugin de IRC, controles de acesso e solução de problemas + - Você quer conectar o OpenClaw a canais de IRC ou mensagens diretas + - Você está configurando listas de permissões de IRC, política de grupos ou controle de menções +summary: Configuração do Plugin IRC, controles de acesso e solução de problemas title: IRC x-i18n: - generated_at: "2026-04-24T05:41:39Z" - model: gpt-5.4 + generated_at: "2026-05-04T02:21:29Z" + model: gpt-5.5 provider: openai - source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69 + source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555 source_path: channels/irc.md - workflow: 15 + workflow: 16 --- -Use IRC quando você quiser o OpenClaw em canais clássicos (`#room`) e mensagens diretas. -O IRC é fornecido como um Plugin incluído, mas é configurado na configuração principal em `channels.irc`. +Use IRC quando quiser usar OpenClaw em canais clássicos (`#room`) e mensagens diretas. +O IRC é fornecido como um Plugin agrupado, mas é configurado na configuração principal em `channels.irc`. ## Início rápido -1. Habilite a configuração de IRC em `~/.openclaw/openclaw.json`. +1. Habilite a configuração do IRC em `~/.openclaw/openclaw.json`. 2. Defina pelo menos: ```json5 @@ -36,7 +36,7 @@ O IRC é fornecido como um Plugin incluído, mas é configurado na configuraçã } ``` -Prefira um servidor IRC privado para coordenação do bot. Se você usar intencionalmente uma rede IRC pública, escolhas comuns incluem Libera.Chat, OFTC e Snoonet. Evite canais públicos previsíveis para tráfego de backchannel de bots ou swarm. +Prefira um servidor IRC privado para coordenação de bots. Se você usar intencionalmente uma rede IRC pública, opções comuns incluem Libera.Chat, OFTC e Snoonet. Evite canais públicos previsíveis para tráfego de backchannel de bots ou enxames. 3. Inicie/reinicie o gateway: @@ -46,38 +46,39 @@ openclaw gateway run ## Padrões de segurança +- O IRC usa soquetes TCP/TLS brutos fora do roteamento de proxy de encaminhamento gerenciado pelo operador do OpenClaw. Em implantações que exigem que todo o tráfego de saída passe por esse proxy de encaminhamento, defina `channels.irc.enabled=false`, a menos que o tráfego de saída direto de IRC seja explicitamente aprovado. - `channels.irc.dmPolicy` usa `"pairing"` por padrão. - `channels.irc.groupPolicy` usa `"allowlist"` por padrão. -- Com `groupPolicy="allowlist"`, defina `channels.irc.groups` para definir os canais permitidos. -- Use TLS (`channels.irc.tls=true`) a menos que você aceite intencionalmente transporte em texto simples. +- Com `groupPolicy="allowlist"`, defina `channels.irc.groups` para declarar os canais permitidos. +- Use TLS (`channels.irc.tls=true`), a menos que você aceite intencionalmente transporte em texto simples. ## Controle de acesso Há dois “portões” separados para canais IRC: 1. **Acesso ao canal** (`groupPolicy` + `groups`): se o bot aceita mensagens de um canal. -2. **Acesso do remetente** (`groupAllowFrom` / por canal `groups["#channel"].allowFrom`): quem tem permissão para acionar o bot dentro desse canal. +2. **Acesso do remetente** (`groupAllowFrom` / `groups["#channel"].allowFrom` por canal): quem tem permissão para acionar o bot dentro desse canal. Chaves de configuração: -- allowlist de DM (acesso do remetente em DM): `channels.irc.allowFrom` -- allowlist de remetentes em grupo (acesso do remetente no canal): `channels.irc.groupAllowFrom` -- Controles por canal (canal + remetente + regras de menção): `channels.irc.groups["#channel"]` -- `channels.irc.groupPolicy="open"` permite canais não configurados (**ainda exigindo menção por padrão**) +- Lista de permissões de DM (acesso do remetente de DM): `channels.irc.allowFrom` +- Lista de permissões de remetentes de grupo (acesso do remetente no canal): `channels.irc.groupAllowFrom` +- Controles por canal (regras de canal + remetente + menção): `channels.irc.groups["#channel"]` +- `channels.irc.groupPolicy="open"` permite canais não configurados (**ainda com exigência de menção por padrão**) -Entradas de allowlist devem usar identidades estáveis de remetente (`nick!user@host`). +Entradas de lista de permissões devem usar identidades de remetente estáveis (`nick!user@host`). A correspondência apenas por nick é mutável e só é habilitada quando `channels.irc.dangerouslyAllowNameMatching: true`. -### Pegadinha comum: `allowFrom` é para DMs, não para canais +### Pegadinha comum: `allowFrom` é para DMs, não canais Se você vir logs como: - `irc: drop group sender alice!ident@host (policy=allowlist)` -…isso significa que o remetente não foi permitido para mensagens de **grupo/canal**. Corrija isso de uma destas formas: +...isso significa que o remetente não tinha permissão para mensagens de **grupo/canal**. Corrija isso de uma destas formas: - definindo `channels.irc.groupAllowFrom` (global para todos os canais), ou -- definindo allowlists de remetente por canal: `channels.irc.groups["#channel"].allowFrom` +- definindo listas de permissões de remetentes por canal: `channels.irc.groups["#channel"].allowFrom` Exemplo (permitir que qualquer pessoa em `#tuirc-dev` fale com o bot): @@ -94,13 +95,13 @@ Exemplo (permitir que qualquer pessoa em `#tuirc-dev` fale com o bot): } ``` -## Acionamento de resposta (menções) +## Acionamento de respostas (menções) Mesmo que um canal seja permitido (via `groupPolicy` + `groups`) e o remetente seja permitido, o OpenClaw usa por padrão **exigência de menção** em contextos de grupo. -Isso significa que você pode ver logs como `drop channel … (missing-mention)` a menos que a mensagem inclua um padrão de menção que corresponda ao bot. +Isso significa que você pode ver logs como `drop channel … (missing-mention)`, a menos que a mensagem inclua um padrão de menção que corresponda ao bot. -Para fazer o bot responder em um canal IRC **sem precisar de menção**, desative a exigência de menção para esse canal: +Para fazer o bot responder em um canal IRC **sem precisar de uma menção**, desabilite a exigência de menção para esse canal: ```json5 { @@ -118,7 +119,7 @@ Para fazer o bot responder em um canal IRC **sem precisar de menção**, desativ } ``` -Ou, para permitir **todos** os canais IRC (sem allowlist por canal) e ainda responder sem menções: +Ou, para permitir **todos** os canais IRC (sem lista de permissões por canal) e ainda responder sem menções: ```json5 { @@ -135,10 +136,10 @@ Ou, para permitir **todos** os canais IRC (sem allowlist por canal) e ainda resp ## Observação de segurança (recomendada para canais públicos) -Se você permitir `allowFrom: ["*"]` em um canal público, qualquer pessoa poderá dar prompts ao bot. -Para reduzir o risco, restrinja as ferramentas desse canal. +Se você permitir `allowFrom: ["*"]` em um canal público, qualquer pessoa poderá enviar prompts ao bot. +Para reduzir o risco, restrinja as ferramentas para esse canal. -### As mesmas ferramentas para todos no canal +### Mesmas ferramentas para todos no canal ```json5 { @@ -159,7 +160,7 @@ Para reduzir o risco, restrinja as ferramentas desse canal. ### Ferramentas diferentes por remetente (o proprietário recebe mais poder) -Use `toolsBySender` para aplicar uma política mais restrita a `"*"` e uma política mais flexível ao seu nick: +Use `toolsBySender` para aplicar uma política mais restrita a `"*"` e uma mais permissiva ao seu nick: ```json5 { @@ -186,15 +187,15 @@ Use `toolsBySender` para aplicar uma política mais restrita a `"*"` e uma polí Observações: - As chaves de `toolsBySender` devem usar `id:` para valores de identidade de remetente IRC: - `id:eigen` ou `id:eigen!~eigen@174.127.248.171` para uma correspondência mais forte. + `id:eigen` ou `id:eigen!~eigen@174.127.248.171` para correspondência mais forte. - Chaves legadas sem prefixo ainda são aceitas e correspondem apenas como `id:`. - A primeira política de remetente correspondente vence; `"*"` é o fallback curinga. -Para saber mais sobre acesso a grupos vs. exigência de menção (e como eles interagem), consulte: [/channels/groups](/pt-BR/channels/groups). +Para saber mais sobre acesso de grupo versus exigência de menção (e como eles interagem), consulte: [/channels/groups](/pt-BR/channels/groups). ## NickServ -Para se identificar com NickServ após a conexão: +Para se identificar com o NickServ após a conexão: ```json5 { @@ -210,7 +211,7 @@ Para se identificar com NickServ após a conexão: } ``` -Registro opcional único na conexão: +Registro único opcional na conexão: ```json5 { @@ -225,11 +226,11 @@ Registro opcional único na conexão: } ``` -Desative `register` após o nick ser registrado para evitar tentativas repetidas de REGISTER. +Desabilite `register` depois que o nick for registrado para evitar tentativas repetidas de REGISTER. ## Variáveis de ambiente -A conta padrão oferece suporte a: +A conta padrão aceita: - `IRC_HOST` - `IRC_PORT` @@ -238,22 +239,22 @@ A conta padrão oferece suporte a: - `IRC_USERNAME` - `IRC_REALNAME` - `IRC_PASSWORD` -- `IRC_CHANNELS` (separados por vírgula) +- `IRC_CHANNELS` (separado por vírgulas) - `IRC_NICKSERV_PASSWORD` - `IRC_NICKSERV_REGISTER_EMAIL` -`IRC_HOST` não pode ser definido a partir de um `.env` do workspace; consulte [Arquivos `.env` do workspace](/pt-BR/gateway/security). +`IRC_HOST` não pode ser definido a partir de um `.env` de workspace; consulte [Arquivos `.env` de workspace](/pt-BR/gateway/security). ## Solução de problemas -- Se o bot se conecta, mas nunca responde em canais, verifique `channels.irc.groups` **e** se a exigência de menção está descartando mensagens (`missing-mention`). Se você quiser que ele responda sem pings, defina `requireMention:false` para o canal. +- Se o bot conectar, mas nunca responder em canais, verifique `channels.irc.groups` **e** se a exigência de menção está descartando mensagens (`missing-mention`). Se quiser que ele responda sem pings, defina `requireMention:false` para o canal. - Se o login falhar, verifique a disponibilidade do nick e a senha do servidor. - Se o TLS falhar em uma rede personalizada, verifique host/porta e a configuração do certificado. -## Relacionado +## Relacionados -- [Visão geral de canais](/pt-BR/channels) — todos os canais compatíveis -- [Pairing](/pt-BR/channels/pairing) — autenticação de DM e fluxo de pairing +- [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis +- [Pairing](/pt-BR/channels/pairing) — autenticação por DM e fluxo de pairing - [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e exigência de menção -- [Roteamento de canal](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens -- [Segurança](/pt-BR/gateway/security) — modelo de acesso e endurecimento +- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens +- [Segurança](/pt-BR/gateway/security) — modelo de acesso e reforço de segurança diff --git a/docs/pt-BR/channels/pairing.md b/docs/pt-BR/channels/pairing.md index e779d4b5c..ede94821d 100644 --- a/docs/pt-BR/channels/pairing.md +++ b/docs/pt-BR/channels/pairing.md @@ -1,43 +1,43 @@ --- read_when: - - Configurando o controle de acesso a mensagens diretas - - Pareando um novo Node iOS/Android + - Configurando o controle de acesso a DMs + - Emparelhamento de um novo Node iOS/Android - Revisando a postura de segurança do OpenClaw -summary: 'Visão geral do pareamento: aprove quem pode enviar mensagens diretas para você + quais Node podem entrar' -title: Emparelhamento +summary: 'Visão geral do pareamento: aprove quem pode enviar mensagens diretas para você + quais nós podem participar' +title: Pareamento x-i18n: - generated_at: "2026-05-02T05:41:31Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4 + source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874 source_path: channels/pairing.md workflow: 16 --- -“Emparelhamento” é a etapa explícita de aprovação de acesso do OpenClaw. -Ele é usado em dois lugares: +“Pareamento” é a etapa explícita de aprovação de acesso do OpenClaw. +Ela é usada em dois lugares: -1. **Emparelhamento por DM** (quem tem permissão para falar com o bot) -2. **Emparelhamento de Node** (quais dispositivos/nós têm permissão para entrar na rede do Gateway) +1. **Pareamento de DM** (quem tem permissão para falar com o bot) +2. **Pareamento de Node** (quais dispositivos/nós têm permissão para entrar na rede do Gateway) Contexto de segurança: [Segurança](/pt-BR/gateway/security) -## 1) Emparelhamento por DM (acesso de chat de entrada) +## 1) Pareamento de DM (acesso de chat de entrada) Quando um canal é configurado com a política de DM `pairing`, remetentes desconhecidos recebem um código curto e a mensagem deles **não é processada** até você aprovar. -As políticas de DM padrão estão documentadas em: [Segurança](/pt-BR/gateway/security) +As políticas padrão de DM estão documentadas em: [Segurança](/pt-BR/gateway/security) -`dmPolicy: "open"` só é público quando a lista de permissões de DM efetiva inclui `"*"`. -A configuração e a validação exigem esse curinga para configurações públicas abertas. Se o estado existente -contiver `open` com entradas concretas de `allowFrom`, o runtime ainda admitirá -somente esses remetentes, e aprovações do armazenamento de emparelhamento não ampliam o acesso `open`. +`dmPolicy: "open"` é público somente quando a lista de permissões efetiva de DM inclui `"*"`. +A configuração e a validação exigem esse curinga para configurações público-abertas. Se o estado existente +contiver `open` com entradas concretas em `allowFrom`, o runtime ainda admite +somente esses remetentes, e aprovações no armazenamento de pareamento não ampliam o acesso `open`. -Códigos de emparelhamento: +Códigos de pareamento: - 8 caracteres, maiúsculos, sem caracteres ambíguos (`0O1I`). -- **Expiram após 1 hora**. O bot só envia a mensagem de emparelhamento quando uma nova solicitação é criada (aproximadamente uma vez por hora por remetente). -- Solicitações pendentes de emparelhamento por DM são limitadas a **3 por canal** por padrão; solicitações adicionais são ignoradas até que uma expire ou seja aprovada. +- **Expiram após 1 hora**. O bot só envia a mensagem de pareamento quando uma nova solicitação é criada (aproximadamente uma vez por hora por remetente). +- Solicitações pendentes de pareamento de DM são limitadas a **3 por canal** por padrão; solicitações adicionais são ignoradas até que uma expire ou seja aprovada. ### Aprovar um remetente @@ -46,18 +46,18 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` -Se nenhum proprietário de comandos estiver configurado ainda, aprovar um código de emparelhamento por DM também inicializa -`commands.ownerAllowFrom` com o remetente aprovado, como `telegram:123456789`. -Isso dá às configurações iniciais um proprietário explícito para comandos privilegiados e solicitações de aprovação de execução. -Depois que um proprietário existir, aprovações de emparelhamento posteriores concedem apenas acesso por DM; +Se nenhum proprietário de comando estiver configurado ainda, aprovar um código de pareamento de DM também inicializa +`commands.ownerAllowFrom` para o remetente aprovado, como `telegram:123456789`. +Isso dá às configurações de primeira execução um proprietário explícito para comandos privilegiados e prompts de aprovação de exec. +Depois que um proprietário existe, aprovações de pareamento posteriores concedem apenas acesso de DM; elas não adicionam mais proprietários. Canais compatíveis: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. ### Grupos de remetentes reutilizáveis -Use `accessGroups` no nível superior quando o mesmo conjunto de remetentes confiáveis deve se aplicar a -vários canais de mensagem ou tanto a listas de permissões de DM quanto de grupos. +Use `accessGroups` de nível superior quando o mesmo conjunto de remetentes confiáveis deve ser aplicado a +vários canais de mensagem ou tanto a listas de permissões de DM quanto de grupo. Grupos estáticos usam `type: "message.senders"` e são referenciados com `accessGroup:` nas listas de permissões de canais: @@ -92,54 +92,54 @@ Armazenado em `~/.openclaw/credentials/`: - Conta padrão: `-allowFrom.json` - Conta não padrão: `--allowFrom.json` -Comportamento de escopo de conta: +Comportamento de escopo por conta: -- Contas não padrão leem/gravam somente seu arquivo de lista de permissões com escopo. -- A conta padrão usa o arquivo de lista de permissões sem escopo do canal. +- Contas não padrão leem/gravam somente o arquivo de lista de permissões com escopo delas. +- A conta padrão usa o arquivo de lista de permissões sem escopo, com escopo do canal. -Trate-os como sensíveis (eles controlam o acesso ao seu assistente). +Trate esses arquivos como sensíveis (eles controlam o acesso ao seu assistente). -O armazenamento da lista de permissões de emparelhamento é para acesso por DM. A autorização em grupo é separada. -Aprovar um código de emparelhamento por DM não permite automaticamente que esse remetente execute comandos de grupo +O armazenamento da lista de permissões de pareamento é para acesso de DM. A autorização de grupo é separada. +Aprovar um código de pareamento de DM não permite automaticamente que esse remetente execute comandos de grupo ou controle o bot em grupos. A inicialização do primeiro proprietário é um estado de configuração separado -em `commands.ownerAllowFrom`, e a entrega em chats de grupo ainda segue as listas de permissões de grupo do -canal (por exemplo `groupAllowFrom`, `groups` ou substituições por grupo +em `commands.ownerAllowFrom`, e a entrega em chats de grupo ainda segue as listas de permissões de grupo +do canal (por exemplo, `groupAllowFrom`, `groups` ou substituições por grupo ou por tópico, dependendo do canal). -## 2) Emparelhamento de dispositivo Node (nós iOS/Android/macOS/headless) +## 2) Pareamento de dispositivo Node (nós iOS/Android/macOS/headless) Nós se conectam ao Gateway como **dispositivos** com `role: node`. O Gateway -cria uma solicitação de emparelhamento de dispositivo que precisa ser aprovada. +cria uma solicitação de pareamento de dispositivo que precisa ser aprovada. -### Emparelhar via Telegram (recomendado para iOS) +### Parear via Telegram (recomendado para iOS) -Se você usa o Plugin `device-pair`, pode fazer o emparelhamento inicial do dispositivo inteiramente pelo Telegram: +Se você usa o Plugin `device-pair`, pode fazer o pareamento inicial do dispositivo inteiramente pelo Telegram: -1. No Telegram, envie uma mensagem ao seu bot: `/pair` +1. No Telegram, envie uma mensagem para seu bot: `/pair` 2. O bot responde com duas mensagens: uma mensagem de instruções e uma mensagem separada com o **código de configuração** (fácil de copiar/colar no Telegram). -3. No seu telefone, abra o aplicativo OpenClaw para iOS → Configurações → Gateway. +3. No telefone, abra o app iOS do OpenClaw → Settings → Gateway. 4. Cole o código de configuração e conecte. -5. De volta ao Telegram: `/pair pending` (revise IDs de solicitação, função e escopos), depois aprove. +5. De volta ao Telegram: `/pair pending` (revise IDs de solicitação, função e escopos) e então aprove. O código de configuração é uma carga JSON codificada em base64 que contém: - `url`: a URL WebSocket do Gateway (`ws://...` ou `wss://...`) -- `bootstrapToken`: um token de inicialização de dispositivo único e curta duração usado para o handshake inicial de emparelhamento +- `bootstrapToken`: um token de bootstrap de curta duração para um único dispositivo, usado no handshake inicial de pareamento -Esse token de inicialização carrega o perfil interno de inicialização de emparelhamento: +Esse token de bootstrap carrega o perfil integrado de bootstrap de pareamento: -- o token `node` primário repassado permanece com `scopes: []` -- qualquer token `operator` repassado permanece limitado à lista de permissões de inicialização: +- o token `node` principal transferido permanece com `scopes: []` +- qualquer token `operator` transferido permanece limitado à lista de permissões de bootstrap: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` -- verificações de escopo de inicialização têm prefixo de função, não um único conjunto plano de escopos: +- verificações de escopo de bootstrap são prefixadas por função, não um único conjunto plano de escopos: entradas de escopo de operador só satisfazem solicitações de operador, e funções não operadoras - ainda precisam solicitar escopos sob seu próprio prefixo de função -- rotação/revogação posterior de tokens permanece limitada tanto pelo contrato de função aprovado do dispositivo - quanto pelos escopos de operador da sessão chamadora + ainda devem solicitar escopos sob o próprio prefixo de função +- rotação/revogação posterior de token permanece limitada tanto pelo contrato de função aprovado + do dispositivo quanto pelos escopos de operador da sessão chamadora -Trate o código de configuração como uma senha enquanto ele for válido. +Trate o código de configuração como uma senha enquanto ele estiver válido. ### Aprovar um dispositivo Node @@ -149,17 +149,24 @@ openclaw devices approve openclaw devices reject ``` -Se o mesmo dispositivo tentar novamente com detalhes de autenticação diferentes (por exemplo, função/escopos/chave pública diferentes), a solicitação pendente anterior será substituída e um novo -`requestId` será criado. +Quando uma aprovação explícita é negada porque a sessão de dispositivo pareado aprovadora +foi aberta com escopo apenas de pareamento, a CLI tenta novamente a mesma solicitação com +`operator.admin`. Isso permite que um dispositivo pareado existente com capacidade de administrador recupere um novo +pareamento da Control UI/navegador sem editar `devices/paired.json` manualmente. O +Gateway ainda valida a conexão repetida; tokens que não conseguem se autenticar +com `operator.admin` permanecem bloqueados. + +Se o mesmo dispositivo tentar novamente com detalhes de autenticação diferentes (por exemplo, função/escopos/chave pública diferentes), +a solicitação pendente anterior é substituída e um novo `requestId` é criado. -Um dispositivo já emparelhado não recebe acesso mais amplo silenciosamente. Se ele se reconectar pedindo mais escopos ou uma função mais ampla, o OpenClaw mantém a aprovação existente como está e cria uma nova solicitação pendente de upgrade. Use `openclaw devices list` para comparar o acesso atualmente aprovado com o acesso recém-solicitado antes de aprovar. +Um dispositivo já pareado não recebe acesso mais amplo silenciosamente. Se ele reconectar solicitando mais escopos ou uma função mais ampla, o OpenClaw mantém a aprovação existente como está e cria uma nova solicitação pendente de upgrade. Use `openclaw devices list` para comparar o acesso aprovado atualmente com o novo acesso solicitado antes de aprovar. ### Aprovação automática opcional de Node por CIDR confiável -O emparelhamento de dispositivos continua manual por padrão. Para redes de nós rigidamente controladas, -você pode optar pela aprovação automática de Node inicial com CIDRs explícitos ou IPs exatos: +O pareamento de dispositivo permanece manual por padrão. Para redes de Node estritamente controladas, +você pode optar pela aprovação automática de Node na primeira execução com CIDRs explícitos ou IPs exatos: ```json5 { @@ -173,29 +180,29 @@ você pode optar pela aprovação automática de Node inicial com CIDRs explíci } ``` -Isso se aplica somente a novas solicitações de emparelhamento com `role: node` sem -escopos solicitados. Clientes Operator, navegador, Control UI e WebChat ainda exigem aprovação manual. +Isso se aplica somente a novas solicitações de pareamento com `role: node` sem escopos solicitados. +Clientes de operador, navegador, Control UI e WebChat ainda exigem aprovação manual. Alterações de função, escopo, metadados e chave pública ainda exigem aprovação manual. -### Armazenamento de estado de emparelhamento de Node +### Armazenamento do estado de pareamento de Node Armazenado em `~/.openclaw/devices/`: - `pending.json` (curta duração; solicitações pendentes expiram) -- `paired.json` (dispositivos emparelhados + tokens) +- `paired.json` (dispositivos pareados + tokens) ### Observações - A API legada `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) é um - armazenamento de emparelhamento separado e pertencente ao gateway. Nós WS ainda exigem emparelhamento de dispositivo. -- O registro de emparelhamento é a fonte durável da verdade para funções aprovadas. Tokens de dispositivo ativos - permanecem limitados a esse conjunto de funções aprovado; uma entrada de token solta + armazenamento de pareamento separado, de propriedade do gateway. Nós WS ainda exigem pareamento de dispositivo. +- O registro de pareamento é a fonte durável da verdade para funções aprovadas. Tokens de dispositivo ativos + permanecem limitados a esse conjunto de funções aprovado; uma entrada de token avulsa fora das funções aprovadas não cria novo acesso. -## Documentos relacionados +## Documentação relacionada - Modelo de segurança + injeção de prompt: [Segurança](/pt-BR/gateway/security) -- Atualização segura (executar doctor): [Atualização](/pt-BR/install/updating) +- Atualizar com segurança (executar doctor): [Atualização](/pt-BR/install/updating) - Configurações de canal: - Telegram: [Telegram](/pt-BR/channels/telegram) - WhatsApp: [WhatsApp](/pt-BR/channels/whatsapp) diff --git a/docs/pt-BR/channels/qqbot.md b/docs/pt-BR/channels/qqbot.md index 05bc495a6..1af0961a5 100644 --- a/docs/pt-BR/channels/qqbot.md +++ b/docs/pt-BR/channels/qqbot.md @@ -2,24 +2,24 @@ read_when: - Você quer conectar o OpenClaw ao QQ - Você precisa configurar as credenciais do QQ Bot - - Você quer suporte a grupos ou conversas privadas do QQ Bot -summary: Instalação, configuração e uso do QQ Bot + - Você quer suporte a chats em grupo ou privados do QQ Bot +summary: Configuração inicial, configuração e uso do QQ Bot title: bot do QQ x-i18n: - generated_at: "2026-05-03T21:27:29Z" + generated_at: "2026-05-04T02:21:31Z" model: gpt-5.5 provider: openai - source_hash: 471c24110bf0ab8896d22f5bb5932ac4e03ff5169560c99ba6b9d1ca4025d9a8 + source_hash: e17fa0da2f6939ed28cac5f13b3e37e6c63b87a10250ff213f7a86685a6141d6 source_path: channels/qqbot.md workflow: 16 --- -O QQ Bot se conecta ao OpenClaw pela API oficial do QQ Bot (Gateway WebSocket). O -plugin oferece suporte a chat privado C2C, @mensagens em grupo e mensagens de canal -de guilda com mídia rica (imagens, voz, vídeo, arquivos). +QQ Bot se conecta ao OpenClaw pela API oficial do QQ Bot (Gateway WebSocket). O +plugin oferece suporte a chat privado C2C, mensagens de grupo com @menções e mensagens +em canais de guilda com mídia avançada (imagens, voz, vídeo, arquivos). Status: plugin baixável. Mensagens diretas, chats em grupo, canais de guilda e -mídia são compatíveis. Reações e threads não são compatíveis. +mídia têm suporte. Reações e threads não têm suporte. ## Instalação @@ -29,10 +29,10 @@ Instale o QQ Bot antes da configuração: openclaw plugins install @openclaw/qqbot ``` -## Configuração +## Configuração inicial -1. Acesse a [QQ Open Platform](https://q.qq.com/) e escaneie o código QR com o - QQ do seu telefone para se registrar / entrar. +1. Acesse a [QQ Open Platform](https://q.qq.com/) e escaneie o código QR com o QQ + do seu telefone para registrar-se / fazer login. 2. Clique em **Create Bot** para criar um novo bot do QQ. 3. Encontre **AppID** e **AppSecret** na página de configurações do bot e copie-os. @@ -75,7 +75,7 @@ Variáveis de ambiente da conta padrão: - `QQBOT_APP_ID` - `QQBOT_CLIENT_SECRET` -AppSecret com base em arquivo: +AppSecret baseado em arquivo: ```json5 { @@ -89,7 +89,7 @@ AppSecret com base em arquivo: } ``` -AppSecret SecretRef de ambiente: +AppSecret SecretRef por ambiente: ```json5 { @@ -103,16 +103,16 @@ AppSecret SecretRef de ambiente: } ``` -Observações: +Notas: -- O fallback de ambiente se aplica apenas à conta padrão do QQ Bot. +- O fallback por ambiente se aplica apenas à conta padrão do QQ Bot. - `openclaw channels add --channel qqbot --token-file ...` fornece apenas o AppSecret; o AppID já deve estar definido na configuração ou em `QQBOT_APP_ID`. - `clientSecret` também aceita entrada SecretRef, não apenas uma string em texto simples. -- Strings de marcador legadas `secretref:/...` não são valores `clientSecret` válidos; +- Strings de marcador `secretref:/...` legadas não são valores `clientSecret` válidos; use objetos SecretRef estruturados como no exemplo acima. -### Configuração de múltiplas contas +### Configuração de várias contas Execute vários bots do QQ em uma única instância do OpenClaw: @@ -146,8 +146,8 @@ openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-o ### Chats em grupo -O suporte do QQ Bot a chat em grupo usa OpenIDs de grupos do QQ, não nomes de exibição. Adicione o bot -a um grupo e mencione-o ou configure o grupo para funcionar sem menção. +O suporte do QQ Bot a chats em grupo usa OpenIDs de grupos do QQ, não nomes de exibição. Adicione o bot +a um grupo e então mencione-o ou configure o grupo para executar sem menção. ```json5 { @@ -174,34 +174,33 @@ a um grupo e mencione-o ou configure o grupo para funcionar sem menção. } ``` -`groups["*"]` define padrões para todos os grupos, e uma entrada concreta -`groups.GROUP_OPENID` substitui esses padrões para um grupo. As configurações de -grupo incluem: +`groups["*"]` define os padrões para todos os grupos, e uma entrada concreta +`groups.GROUP_OPENID` substitui esses padrões para um grupo. As configurações de grupo +incluem: -- `requireMention`: exige uma @menção antes que o bot responda. Padrão: `true`. +- `requireMention`: exige uma @menção antes de o bot responder. Padrão: `true`. - `ignoreOtherMentions`: descarta mensagens que mencionam outra pessoa, mas não o bot. -- `historyLimit`: mantém mensagens recentes de grupo sem menção como contexto para o próximo turno mencionado. Defina `0` para desativar. +- `historyLimit`: mantém mensagens recentes de grupo sem menção como contexto para a próxima rodada mencionada. Defina `0` para desativar. - `toolPolicy`: `full`, `restricted` ou `none` para ferramentas com escopo de grupo. - `name`: rótulo amigável usado em logs e no contexto do grupo. - `prompt`: prompt de comportamento por grupo anexado ao contexto do agente. Os modos de ativação são `mention` e `always`. `requireMention: true` mapeia para -`mention`; `requireMention: false` mapeia para `always`. Uma substituição de -ativação no nível da sessão, quando presente, prevalece sobre a configuração. +`mention`; `requireMention: false` mapeia para `always`. Uma substituição de ativação +em nível de sessão, quando presente, prevalece sobre a configuração. -A fila de entrada é por par. Pares de grupo recebem um limite maior de fila, mantêm -mensagens humanas à frente de conversas geradas por bot quando a fila está cheia -e mesclam rajadas de mensagens normais de grupo em um turno atribuído. Comandos -slash ainda são executados um por um. +A fila de entrada é por par. Pares de grupo recebem um limite de fila maior, mantêm mensagens +humanas à frente de conversas originadas por bot quando cheia e mesclam rajadas de mensagens +normais de grupo em uma única rodada atribuída. Comandos de barra ainda são executados um por um. ### Voz (STT / TTS) -STT e TTS oferecem suporte a configuração em dois níveis com fallback de prioridade: +O suporte a STT e TTS usa configuração em dois níveis com fallback por prioridade: -| Configuração | Específica do plugin | Fallback do framework | -| ------------ | -------------------------------------------------------- | ---------------------------- | -| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | -| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | +| Configuração | Específica do plugin | Fallback do framework | +| ------------ | --------------------------------------------------------- | ----------------------------- | +| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | +| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | ```json5 { @@ -217,7 +216,7 @@ STT e TTS oferecem suporte a configuração em dois níveis com fallback de prio voice: "your-voice", }, accounts: { - qq-main: { + "qq-main": { tts: { providers: { openai: { voice: "shimmer" }, @@ -231,15 +230,15 @@ STT e TTS oferecem suporte a configuração em dois níveis com fallback de prio ``` Defina `enabled: false` em qualquer um deles para desativar. -Substituições de TTS no nível da conta usam o mesmo formato de `messages.tts` e fazem deep-merge +Substituições de TTS em nível de conta usam o mesmo formato que `messages.tts` e fazem mesclagem profunda sobre a configuração de TTS do canal/global. -Anexos de voz recebidos do QQ são expostos aos agentes como metadados de mídia de áudio, enquanto -mantêm arquivos brutos de voz fora de `MediaPaths` genéricos. Respostas em texto simples +Anexos de voz recebidos pelo QQ são expostos aos agentes como metadados de mídia de áudio, enquanto +mantêm arquivos de voz brutos fora de `MediaPaths` genéricos. Respostas em texto simples `[[audio_as_voice]]` sintetizam TTS e enviam uma mensagem de voz nativa do QQ quando o TTS está configurado. -O comportamento de upload/transcodificação de áudio enviado também pode ser ajustado com +O comportamento de upload/transcodificação de áudio de saída também pode ser ajustado com `channels.qqbot.audioFormatPolicy`: - `sttDirectFormats` @@ -248,67 +247,67 @@ O comportamento de upload/transcodificação de áudio enviado também pode ser ## Formatos de destino -| Formato | Descrição | -| -------------------------- | ------------------ | -| `qqbot:c2c:OPENID` | Chat privado (C2C) | -| `qqbot:group:GROUP_OPENID` | Chat em grupo | -| `qqbot:channel:CHANNEL_ID` | Canal de guilda | +| Formato | Descrição | +| -------------------------- | ------------------- | +| `qqbot:c2c:OPENID` | Chat privado (C2C) | +| `qqbot:group:GROUP_OPENID` | Chat em grupo | +| `qqbot:channel:CHANNEL_ID` | Canal de guilda | -> Cada bot tem seu próprio conjunto de OpenIDs de usuários. Um OpenID recebido pelo Bot A **não pode** +> Cada bot tem seu próprio conjunto de OpenIDs de usuário. Um OpenID recebido pelo Bot A **não pode** > ser usado para enviar mensagens pelo Bot B. -## Comandos slash +## Comandos de barra Comandos integrados interceptados antes da fila de IA: -| Comando | Descrição | -| -------------- | ------------------------------------------------------------------------------------------------------------------- | -| `/bot-ping` | Teste de latência | -| `/bot-version` | Mostra a versão do framework OpenClaw | -| `/bot-help` | Lista todos os comandos | -| `/bot-me` | Mostra o ID de usuário QQ (openid) do remetente para configuração de `allowFrom`/`groupAllowFrom` | -| `/bot-upgrade` | Mostra o link do guia de upgrade do QQBot | -| `/bot-logs` | Exporta logs recentes do Gateway como um arquivo | -| `/bot-approve` | Aprova uma ação pendente do QQ Bot (por exemplo, confirmar um upload C2C ou de grupo) pelo fluxo nativo. | +| Comando | Descrição | +| -------------- | -------------------------------------------------------------------------------------------------------------- | +| `/bot-ping` | Teste de latência | +| `/bot-version` | Mostra a versão do framework OpenClaw | +| `/bot-help` | Lista todos os comandos | +| `/bot-me` | Mostra o ID de usuário QQ do remetente (openid) para configuração de `allowFrom`/`groupAllowFrom` | +| `/bot-upgrade` | Mostra o link do guia de upgrade do QQBot | +| `/bot-logs` | Exporta logs recentes do gateway como um arquivo | +| `/bot-approve` | Aprova uma ação pendente do QQ Bot (por exemplo, confirmar um upload C2C ou de grupo) pelo fluxo nativo. | -Acrescente `?` a qualquer comando para ajuda de uso (por exemplo, `/bot-upgrade ?`). +Anexe `?` a qualquer comando para ver ajuda de uso (por exemplo, `/bot-upgrade ?`). -Comandos de administrador (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) são permitidos apenas por mensagem direta e exigem que o openid do remetente esteja em uma lista explícita `allowFrom` sem curinga. Um curinga `allowFrom: ["*"]` permite chat, mas não concede acesso a comandos de administrador. Mensagens de grupo são comparadas primeiro com `groupAllowFrom` e fazem fallback para `allowFrom`. Executar um comando de administrador em um grupo retorna uma dica em vez de descartar silenciosamente. +Comandos administrativos (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) são exclusivos para mensagens diretas e exigem que o openid do remetente esteja em uma lista `allowFrom` explícita e sem curinga. Um curinga `allowFrom: ["*"]` permite chat, mas não concede acesso a comandos administrativos. Mensagens de grupo são comparadas primeiro com `groupAllowFrom` e fazem fallback para `allowFrom`. Executar um comando administrativo em um grupo retorna uma dica em vez de descartá-lo silenciosamente. ## Arquitetura do mecanismo -O QQ Bot é distribuído como um mecanismo autocontido dentro do plugin: +O QQ Bot é distribuído como um mecanismo autônomo dentro do plugin: -- Cada conta possui uma pilha de recursos isolada (conexão WebSocket, cliente de API, cache de token, raiz de armazenamento de mídia) indexada por `appId`. As contas nunca compartilham estado de entrada/saída. -- O logger de múltiplas contas marca linhas de log com a conta proprietária, para que diagnósticos permaneçam separáveis quando você executa vários bots em um único Gateway. -- Caminhos de entrada, saída e ponte de Gateway compartilham uma única raiz de payload de mídia em `~/.openclaw/media`, então uploads, downloads e caches de transcodificação ficam em um diretório protegido em vez de uma árvore por subsistema. -- A entrega de mídia rica passa por um único caminho `sendMedia` para destinos C2C e de grupo. Arquivos locais e buffers acima do limite de arquivo grande usam endpoints de upload em partes do QQ, enquanto payloads menores usam a API de mídia de envio único. -- Credenciais podem ser incluídas em backup e restauradas como parte de snapshots padrão de credenciais do OpenClaw; o mecanismo reanexa a pilha de recursos de cada conta na restauração sem exigir um novo par por código QR. +- Cada conta possui uma pilha de recursos isolada (conexão WebSocket, cliente de API, cache de token, raiz de armazenamento de mídia) identificada por `appId`. Contas nunca compartilham estado de entrada/saída. +- O logger para várias contas marca as linhas de log com a conta proprietária para manter os diagnósticos separáveis quando você executa vários bots em um gateway. +- Os caminhos de entrada, saída e ponte do gateway compartilham uma única raiz de payload de mídia em `~/.openclaw/media`, para que uploads, downloads e caches de transcodificação fiquem em um diretório protegido em vez de uma árvore por subsistema. +- A entrega de mídia avançada passa por um único caminho `sendMedia` para destinos C2C e de grupo. Arquivos locais e buffers acima do limite de arquivos grandes usam os endpoints de upload em partes do QQ, enquanto payloads menores usam a API de mídia em uma única chamada. +- Credenciais podem ser incluídas em backup e restauradas como parte dos snapshots padrão de credenciais do OpenClaw; o mecanismo reconecta a pilha de recursos de cada conta na restauração sem exigir um novo pareamento por código QR. ## Integração por código QR Como alternativa a colar `AppID:AppSecret` manualmente, o mecanismo oferece suporte a um fluxo de integração por código QR para vincular um QQ Bot ao OpenClaw: 1. Execute o caminho de configuração do QQ Bot (por exemplo, `openclaw channels add --channel qqbot`) e escolha o fluxo por código QR quando solicitado. -2. Escaneie o código QR gerado com o app do telefone vinculado ao QQ Bot de destino. -3. Aprove o pareamento no telefone. O OpenClaw persiste as credenciais retornadas em `credentials/` sob o escopo de conta correto. +2. Escaneie o código QR gerado com o aplicativo de telefone vinculado ao QQ Bot de destino. +3. Aprove o pareamento no telefone. O OpenClaw persiste as credenciais retornadas em `credentials/` no escopo correto da conta. Prompts de aprovação gerados pelo próprio bot (por exemplo, fluxos "permitir esta ação?" expostos pela API do QQ Bot) aparecem como prompts nativos do OpenClaw que você pode aceitar com `/bot-approve` em vez de responder pelo cliente QQ bruto. ## Solução de problemas - **O bot responde "gone to Mars":** credenciais não configuradas ou Gateway não iniciado. -- **Nenhuma mensagem de entrada:** verifique se `appId` e `clientSecret` estão corretos e se o +- **Sem mensagens de entrada:** verifique se `appId` e `clientSecret` estão corretos, e se o bot está habilitado na QQ Open Platform. -- **Autorespostas repetidas:** o OpenClaw registra índices de referência de saída do QQ como - escritos pelo bot e ignora eventos de entrada cujo `msgIdx` atual corresponde à - mesma conta de bot. Isso evita loops de eco da plataforma, ainda permitindo que usuários +- **Autorrespostas repetidas:** o OpenClaw registra índices de referência de saída do QQ como + originados pelo bot e ignora eventos de entrada cujo `msgIdx` atual corresponde a essa + mesma conta de bot. Isso evita loops de eco da plataforma, enquanto ainda permite que usuários citem ou respondam a mensagens anteriores do bot. - **Configuração com `--token-file` ainda aparece como não configurada:** `--token-file` define apenas o AppSecret. Você ainda precisa de `appId` na configuração ou em `QQBOT_APP_ID`. - **Mensagens proativas não chegam:** o QQ pode interceptar mensagens iniciadas pelo bot se - o usuário não tiver interagido recentemente. -- **Voz não transcrita:** verifique se STT está configurado e se o provedor está acessível. + o usuário não interagiu recentemente. +- **Voz não transcrita:** garanta que STT esteja configurado e que o provedor esteja acessível. ## Relacionados diff --git a/docs/pt-BR/channels/slack.md b/docs/pt-BR/channels/slack.md index a24a639c1..9a62c3962 100644 --- a/docs/pt-BR/channels/slack.md +++ b/docs/pt-BR/channels/slack.md @@ -1,47 +1,47 @@ --- read_when: - - Configurando o Slack ou depurando o modo socket/HTTP do Slack -summary: Configuração do Slack e comportamento em tempo de execução (Socket Mode + URLs de requisição HTTP) + - 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) title: Slack x-i18n: - generated_at: "2026-05-03T21:27:17Z" + generated_at: "2026-05-04T02:22:07Z" model: gpt-5.5 provider: openai - source_hash: d902fbbad23cee9b3f0ab7d240845b7b229e2d2507c5ea1d1a0fa3baa915d80a + source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b source_path: channels/slack.md workflow: 16 --- -Pronto para produção para DMs e canais por meio de integrações de app Slack. O modo padrão é Modo Socket; URLs de solicitação HTTP também são compatíveis. +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. - + DMs do Slack usam o modo de pareamento por padrão. - - Comportamento nativo de comandos e catálogo de comandos. + + Comportamento de comando nativo e catálogo de comandos. - - Diagnósticos entre canais e guias de reparo. + + Diagnósticos entre canais e playbooks de reparo. ## Configuração rápida - + - + Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: - - escolha **a partir de um manifesto** e selecione um workspace para seu app + - escolha **from a manifest** e selecione um workspace para seu app - cole o [manifesto de exemplo](#manifest-and-scope-checklist) abaixo e continue para criar - - gere um **Token de nível de app** (`xapp-...`) com `connections:write` - - instale o app e copie o **Token do bot** (`xoxb-...`) exibido + - gere um **App-Level Token** (`xapp-...`) com `connections:write` + - instale o app e copie o **Bot Token** (`xoxb-...`) exibido - + Configuração SecretRef recomendada: @@ -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)**: - - escolha **a partir de um manifesto** e selecione um workspace para seu app + - escolha **from a manifest** e selecione um workspace para seu app - cole o [manifesto de exemplo](#manifest-and-scope-checklist) e atualize as URLs antes de criar - - salve o **Segredo de assinatura** para verificação de solicitações - - instale o app e copie o **Token do bot** (`xoxb-...`) exibido + - salve o **Signing Secret** para verificação de solicitações + - instale o app e copie o **Bot Token** (`xoxb-...`) exibido - + Configuração SecretRef recomendada: @@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - Use caminhos de webhook exclusivos para HTTP com várias contas + Use caminhos de Webhook exclusivos para HTTP com várias contas Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito. - + ```bash openclaw gateway @@ -140,9 +140,9 @@ openclaw gateway -## Ajuste do transporte do Socket Mode +## Ajuste do transporte Socket Mode -O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segundos por padrão para o Socket Mode. Sobrescreva as configurações de transporte somente quando precisar de ajustes específicos do workspace ou do 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 ajustes específicos para o workspace ou o host: ```json5 { @@ -159,13 +159,13 @@ O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segu } ``` -Use isso somente para workspaces do Socket Mode que registram tempos limite de pong/server-ping do websocket do Slack ou que são executados em hosts com esgotamento 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 Slack. Mensagens e eventos do app continuam sendo estado da aplicação, não sinais de vivacidade do transporte. +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. ## Checklist de manifesto e escopos -O manifesto base do app Slack é o mesmo para o Socket Mode e para URLs de solicitação HTTP. Somente o bloco `settings` (e o `url` do comando slash) muda. +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. -Manifesto base (padrão do Socket Mode): +Manifesto base (Socket Mode padrão): ```json { @@ -240,7 +240,7 @@ Manifesto base (padrão do Socket Mode): } ``` -Para o **modo de URLs de solicitação HTTP**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória: +Para o **modo HTTP Request URLs**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória: ```json { @@ -258,7 +258,19 @@ Para o **modo de URLs de solicitação HTTP**, substitua `settings` pela variant "event_subscriptions": { "request_url": "https://gateway-host.example.com/slack/events", "bot_events": [ - /* same as Socket Mode */ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" ] }, "interactivity": { @@ -272,162 +284,167 @@ Para o **modo de URLs de solicitação HTTP**, substitua `settings` pela variant ### Configurações adicionais do manifesto -Exponha recursos diferentes que estendem os padrões acima. +Exiba recursos diferentes que estendem os padrões acima. -O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home_opened`. Quando um membro do workspace abre a aba Home, o OpenClaw publica uma visualização Home padrão segura com `views.publish`; nenhum payload de conversa nem configuração privada é incluído. A aba **Messages** 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 ou configuração privada é incluído. A aba **Messages** permanece 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 nuances: + Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com uma nuance: - - Use `/agentstatus` em vez de `/status`, porque o comando `/status` é reservado. - - Não mais que 25 comandos slash podem ser disponibilizados de uma vez. + - Use `/agentstatus` em vez de `/status` porque o comando `/status` é reservado. + - No máximo 25 comandos slash podem ficar disponíveis ao mesmo tempo. Substitua sua seção `features.slash_commands` existente por um subconjunto dos [comandos disponíveis](/pt-BR/tools/slash-commands#command-list): - + ```json - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]" - }, - { - "command": "/reset", - "description": "Reset the current session" - }, - { - "command": "/compact", - "description": "Compact the session context", - "usage_hint": "[instructions]" - }, - { - "command": "/stop", - "description": "Stop the current run" - }, - { - "command": "/session", - "description": "Manage thread-binding expiry", - "usage_hint": "idle or max-age " - }, - { - "command": "/think", - "description": "Set the thinking level", - "usage_hint": "" - }, - { - "command": "/verbose", - "description": "Toggle verbose output", - "usage_hint": "on|off|full" - }, - { - "command": "/fast", - "description": "Show or set fast mode", - "usage_hint": "[status|on|off]" - }, - { - "command": "/reasoning", - "description": "Toggle reasoning visibility", - "usage_hint": "[on|off|stream]" - }, - { - "command": "/elevated", - "description": "Toggle elevated mode", - "usage_hint": "[on|off|ask|full]" - }, - { - "command": "/exec", - "description": "Show or set exec defaults", - "usage_hint": "host= security= ask= node=" - }, - { - "command": "/model", - "description": "Show or set the model", - "usage_hint": "[name|#|status]" - }, - { - "command": "/models", - "description": "List providers/models", - "usage_hint": "[provider] [page] [limit=|size=|all]" - }, - { - "command": "/help", - "description": "Show the short help summary" - }, - { - "command": "/commands", - "description": "Show the generated command catalog" - }, - { - "command": "/tools", - "description": "Show what the current agent can use right now", - "usage_hint": "[compact|verbose]" - }, - { - "command": "/agentstatus", - "description": "Show runtime status, including provider usage/quota when available" - }, - { - "command": "/tasks", - "description": "List active/recent background tasks for the current session" - }, - { - "command": "/context", - "description": "Explain how context is assembled", - "usage_hint": "[list|detail|json]" - }, - { - "command": "/whoami", - "description": "Show your sender identity" - }, - { - "command": "/skill", - "description": "Run a skill by name", - "usage_hint": " [input]" - }, - { - "command": "/btw", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/side", - "description": "Ask a side question without changing session context", - "usage_hint": "" - }, - { - "command": "/usage", - "description": "Control the usage footer or show cost summary", - "usage_hint": "off|tokens|full|cost" - } - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]" + }, + { + "command": "/reset", + "description": "Reset the current session" + }, + { + "command": "/compact", + "description": "Compact the session context", + "usage_hint": "[instructions]" + }, + { + "command": "/stop", + "description": "Stop the current run" + }, + { + "command": "/session", + "description": "Manage thread-binding expiry", + "usage_hint": "idle or max-age " + }, + { + "command": "/think", + "description": "Set the thinking level", + "usage_hint": "" + }, + { + "command": "/verbose", + "description": "Toggle verbose output", + "usage_hint": "on|off|full" + }, + { + "command": "/fast", + "description": "Show or set fast mode", + "usage_hint": "[status|on|off]" + }, + { + "command": "/reasoning", + "description": "Toggle reasoning visibility", + "usage_hint": "[on|off|stream]" + }, + { + "command": "/elevated", + "description": "Toggle elevated mode", + "usage_hint": "[on|off|ask|full]" + }, + { + "command": "/exec", + "description": "Show or set exec defaults", + "usage_hint": "host= security= ask= node=" + }, + { + "command": "/model", + "description": "Show or set the model", + "usage_hint": "[name|#|status]" + }, + { + "command": "/models", + "description": "List providers/models", + "usage_hint": "[provider] [page] [limit=|size=|all]" + }, + { + "command": "/help", + "description": "Show the short help summary" + }, + { + "command": "/commands", + "description": "Show the generated command catalog" + }, + { + "command": "/tools", + "description": "Show what the current agent can use right now", + "usage_hint": "[compact|verbose]" + }, + { + "command": "/agentstatus", + "description": "Show runtime status, including provider usage/quota when available" + }, + { + "command": "/tasks", + "description": "List active/recent background tasks for the current session" + }, + { + "command": "/context", + "description": "Explain how context is assembled", + "usage_hint": "[list|detail|json]" + }, + { + "command": "/whoami", + "description": "Show your sender identity" + }, + { + "command": "/skill", + "description": "Run a skill by name", + "usage_hint": " [input]" + }, + { + "command": "/btw", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/side", + "description": "Ask a side question without changing session context", + "usage_hint": "" + }, + { + "command": "/usage", + "description": "Control the usage footer or show cost summary", + "usage_hint": "off|tokens|full|cost" + } + ] +} ``` - + 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 - "slash_commands": [ - { - "command": "/new", - "description": "Start a new session", - "usage_hint": "[model]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/help", - "description": "Show the short help summary", - "url": "https://gateway-host.example.com/slack/events" - } - // ...repeat for every command with the same `url` value - ] +{ + "slash_commands": [ + { + "command": "/new", + "description": "Start a new session", + "usage_hint": "[model]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/help", + "description": "Show the short help summary", + "url": "https://gateway-host.example.com/slack/events" + } + ] +} ``` + Repita esse valor de `url` em todos os comandos da lista. + @@ -447,7 +464,7 @@ 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 de pesquisa do Slack) + - `search:read` (se você depender de leituras da busca do Slack) @@ -455,20 +472,20 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home ## Modelo de tokens - `botToken` + `appToken` são obrigatórios para Socket Mode. -- O modo HTTP requer `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings de texto simples +- O modo HTTP exige `botToken` + `signingSecret`. +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto claro ou objetos SecretRef. - Tokens de configuração substituem o fallback de env. - O fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão. - `userToken` (`xoxp-...`) é somente por configuração (sem fallback de env) e o padrão é comportamento somente leitura (`userTokenReadOnly: true`). -Comportamento do instantâneo de status: +Comportamento do snapshot de status: -- A inspeção de conta do Slack rastreia campos `*Source` e `*Status` +- A inspeção da conta Slack rastreia campos `*Source` e `*Status` por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`). - O status é `available`, `configured_unavailable` ou `missing`. - `configured_unavailable` significa que a conta está configurada por SecretRef - ou outra fonte de segredo não inline, mas o caminho atual de comando/runtime + ou outra origem de segredo não inline, mas o caminho de comando/runtime atual não conseguiu resolver o valor real. - No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o par obrigatório é `botTokenStatus` + `appTokenStatus`. @@ -481,7 +498,7 @@ Para ações/leituras de diretório, o token de usuário pode ser preferido quan As ações do Slack são controladas por `channels.slack.actions.*`. -Grupos de ação disponíveis na ferramenta atual do Slack: +Grupos de ação disponíveis nas ferramentas Slack atuais: | Grupo | Padrão | | ---------- | ------- | @@ -491,28 +508,28 @@ Grupos de ação disponíveis na ferramenta atual do Slack: | memberInfo | ativado | | emojiList | ativado | -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 arquivo de entrada e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo. +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. ## Controle de acesso e roteamento - `channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a lista de permissões canônica de DM. + `channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a allowlist canônica de DM. - `pairing` (padrão) - `allowlist` - - `open` (requer que `channels.slack.allowFrom` inclua `"*"`) + - `open` (exige que `channels.slack.allowFrom` inclua `"*"`) - `disabled` Flags de DM: - - `dm.enabled` (padrão verdadeiro) + - `dm.enabled` (padrão true) - `channels.slack.allowFrom` - `dm.allowFrom` (legado) - - `dm.groupEnabled` (DMs em grupo padrão falso) - - `dm.groupChannels` (lista de permissões MPIM opcional) + - `dm.groupEnabled` (DMs em grupo padrão false) + - `dm.groupChannels` (allowlist opcional de MPIM) - Precedência de múltiplas contas: + Precedência em várias contas: - `channels.slack.accounts.default.allowFrom` se aplica apenas à conta `default`. - Contas nomeadas herdam `channels.slack.allowFrom` quando seu próprio `allowFrom` não está definido. @@ -524,27 +541,27 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - + `channels.slack.groupPolicy` controla o tratamento de canais: - `open` - `allowlist` - `disabled` - A lista de permissões de canais fica em `channels.slack.channels` e **deve usar IDs de canal estáveis do Slack** (por exemplo, `C12345678`) como chaves de configuração. + 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. - Nota de runtime: se `channels.slack` estiver completamente ausente (configuração apenas por env), o runtime volta para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). + 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). Resolução de nome/ID: - - entradas da lista de permissões de canais e entradas da lista de permissões de DM são resolvidas na inicialização quando o acesso ao 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 requer `channels.slack.dangerouslyAllowNameMatching: true` + - 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` - 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 do canal não é necessária para roteamento e uma chave baseada em nome parece funcionar. + Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de 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. - Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no fim da URL. + 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. Correto: @@ -561,7 +578,7 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- } ``` - Incorreto (bloqueado silenciosamente sob `groupPolicy: "allowlist"`): + Incorreto (bloqueado silenciosamente em `groupPolicy: "allowlist"`): ```json5 { @@ -580,19 +597,19 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - Mensagens de canal são bloqueadas por menção por padrão. + Mensagens de canal exigem menção por padrão. - Fontes de menção: + Origens de menção: - menção explícita ao app (`<@botId>`) - - menção a grupo de usuários do Slack (``) quando o usuário bot é membro desse grupo de usuários; requer `usergroups:read` + - menção a grupo de usuários do Slack (``) quando o usuário bot é membro desse grupo de usuários; exige `usergroups:read` - padrões regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - comportamento implícito de thread de resposta ao bot (desativado quando `thread.requireExplicitMention` é `true`) + - comportamento implícito de resposta ao bot em thread (desativado quando `thread.requireExplicitMention` é `true`) - Controles por canal (`channels.slack.channels.`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`): + Controles por canal (`channels.slack.channels.`; nomes apenas por resolução na inicialização ou `dangerouslyAllowNameMatching`): - `requireMention` - - `users` (lista de permissões) + - `users` (allowlist) - `allowBots` - `skills` - `systemPrompt` @@ -600,21 +617,21 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"` (chaves legadas sem prefixo ainda mapeiam apenas para `id:`) - `allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bot são aceitas apenas quando o bot remetente está explicitamente listado na lista de permissões `users` dessa sala, ou quando pelo menos um ID explícito de proprietário do Slack de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; certifique-se de que o app tenha o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a 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 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. ## Threads, sessões e tags de resposta -- DMs roteiam como `direct`; canais como `channel`; MPIMs como `group`. -- Vinculações de rota do Slack aceitam IDs brutos de pares mais formas de destino do Slack, como `channel:C12345678`, `user:U12345678` e `<@U12345678>`. -- Com `session.dmScope=main` padrão, DMs do Slack são consolidadas na sessão principal do agente. +- 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. - 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 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 threads para que o bot responda apenas 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 gate de `requireMention`. +- `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`. Controles de threading de resposta: @@ -622,18 +639,18 @@ 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 são compatíveis: +Tags manuais de resposta têm suporte: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` desativa **todo** o 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 continuam visíveis inline. +`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. ## Reações de confirmação -`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem de entrada. +`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. Ordem de resolução: @@ -645,28 +662,28 @@ Ordem de resolução: Notas: - O Slack espera shortcodes (por exemplo, `"eyes"`). -- Use `""` para desativar a reação para a conta do Slack ou globalmente. +- Use `""` para desativar a reação para a conta Slack ou globalmente. ## Streaming de texto `channels.slack.streaming` controla o comportamento de prévia ao vivo: - `off`: desativa streaming de prévia ao vivo. -- `partial` (padrão): substitui o texto de prévia pela saída parcial mais recente. -- `block`: acrescenta atualizações de prévia em blocos. +- `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. `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 deve estar disponível para que o streaming de texto nativo e o status de thread de assistente do Slack apareçam. A seleção da thread ainda segue `replyToMode`. +- 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 de nível superior do Slack ficam fora de thread por padrão, então não mostram a prévia de stream/status nativa no estilo de thread do Slack; em vez disso, o OpenClaw publica e edita uma prévia de rascunho na DM. -- Mídia e payloads não textuais usam entrega normal como fallback. -- Finais de mídia/erro cancelam edições de prévia pendentes; finais elegíveis de texto/bloco descarregam apenas quando podem editar a prévia no lugar. -- Se o streaming falhar no meio da resposta, o OpenClaw volta para entrega normal dos payloads restantes. +- 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. -Use prévia de rascunho em vez do streaming de texto nativo do Slack: +Use prévia de rascunho em vez de streaming de texto nativo do Slack: ```json5 { @@ -689,7 +706,7 @@ Chaves legadas: ## Fallback de reação de digitação -`typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto o OpenClaw processa uma resposta, depois a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "está digitando...". +`typingReaction` adiciona uma reação temporária à mensagem 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...". Ordem de resolução: @@ -699,42 +716,42 @@ Ordem de resolução: Notas: - O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`). -- A reação é de melhor esforço, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído. +- A reação é best-effort, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído. ## Mídia, fragmentação e entrega - - Anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticado por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. Os placeholders de arquivo incluem o `fileId` do Slack para que os agentes possam buscar o arquivo original com `download-file`. + + Os 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`. - Os downloads usam tempos limite ociosos e totais delimitados. Se a recuperação de arquivo do Slack travar ou falhar, o OpenClaw continua processando a mensagem e recorre ao placeholder de arquivo. + 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. - O limite de tamanho de entrada em runtime usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`. + O limite de tamanho de entrada em tempo de execução usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`. - + - fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000) - - `channels.slack.chunkMode="newline"` habilita divisão priorizando parágrafos - - envios de arquivo 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, envios de canal usam padrões por tipo MIME do pipeline de mídia + - `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`) + - 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 preferidos: + + Destinos explícitos preferenciais: - `user:` para DMs - `channel:` para canais - DMs do Slack apenas com texto/blocos podem publicar diretamente em IDs de usuário; uploads de arquivo e envios em thread abrem a DM primeiro pelas APIs de conversa do Slack porque esses caminhos exigem um ID de conversa concreto. + DMs do Slack somente com texto/blocos podem publicar diretamente em IDs de usuário; uploads de 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. -## Comandos e comportamento de barra +## Comandos e comportamento de slash -Comandos de barra 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 vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando: - `enabled: false` - `name: "openclaw"` @@ -745,30 +762,30 @@ Comandos de barra aparecem no Slack como um único comando configurado ou vário /openclaw /help ``` -Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais. +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. -- O modo automático de comando nativo 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 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 um valor de opção selecionado: +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: -- até 5 opções: blocos de botões +- 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 manipuladores de opções de interatividade estão disponíveis +- 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 - limites do Slack excedidos: valores de opção codificados recorrem a botões ```txt /think ``` -Sessões de barra usam chaves isoladas como `agent::slack:slash:` e ainda encaminham execuções de comando para a sessão de conversa de destino usando `CommandTargetSessionKey`. +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`. ## Respostas interativas -O Slack pode renderizar controles de resposta interativa criados pelo agente, mas esse recurso fica desabilitado por padrão. +O Slack pode renderizar controles de resposta interativos criados por agentes, mas esse recurso é desabilitado por padrão. Habilite globalmente: @@ -784,7 +801,7 @@ Habilite globalmente: } ``` -Ou habilite apenas para uma conta do Slack: +Ou habilite somente para uma conta do Slack: ```json5 { @@ -807,25 +824,25 @@ Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slac - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Essas diretivas são compiladas em Slack Block Kit e encaminham cliques ou seleções de volta pelo caminho de evento 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 eventos 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 um payload de blocos inválido. +- 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. ## Aprovações de exec 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. - Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal. -- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo de id de aprovação é `plugin:`. -- A autorização de aprovador ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack. +- 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. -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 app 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 de aprovação principal; o OpenClaw -só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser que aprovações +Isso usa a mesma superfície compartilhada de botões de aprovação 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. +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 por chat estão indisponíveis ou que a aprovação manual é o único caminho. Caminho de configuração: @@ -849,8 +866,8 @@ Comportamento padrão sem configuração explícita de aprovação de exec do Sl } ``` -Configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou -aderir à entrega no chat de origem: +A configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou +optar por entrega no chat de origem: ```json5 { @@ -871,32 +888,32 @@ ser roteados para outros chats ou destinos explícitos fora de banda. O encaminh 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á oferecem suporte a comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para o modelo completo de encaminhamento de aprovação. +`/approve` no mesmo chat também funciona em canais e DMs do Slack que já aceitam comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovações. ## Eventos e comportamento operacional -- Edições/exclusões de mensagem são mapeadas para eventos de sistema. -- Transmissões de thread (respostas de thread com "Also send to channel") são processadas como mensagens normais de usuário. -- Eventos de adição/remoção de reação são mapeados para eventos de sistema. -- Eventos de entrada/saída de membro, canal criado/renomeado e adição/remoção de pin são mapeados para eventos de sistema. +- 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. - `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 de contexto do histórico inicial da thread são filtrados por allowlists de remetente configuradas quando aplicável. -- Ações de bloco e interações modais emitem eventos de sistema `Slack interaction: ...` estruturados com campos de payload ricos: +- 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: - ações de bloco: valores selecionados, rótulos, valores de seletores e metadados `workflow_*` - - eventos modais `view_submission` e `view_closed` com metadados de canal roteado e entradas de formulário + - eventos modais `view_submission` e `view_closed` com metadados de canal roteados 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.*` - 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 salvo necessidade) -- acesso a canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- threads/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- 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` - entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -905,13 +922,13 @@ Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/co ## Solução de problemas - - Verifique, em ordem: + + Verifique, na ordem: - `groupPolicy` - - allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente com `groupPolicy: "allowlist"` porque o roteamento de canal prioriza ID por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copy link** — o valor `C...` no fim da URL é o ID do canal. + - 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. - `requireMention` - - allowlist de `users` por canal + - allowlist `users` por canal Comandos úteis: @@ -923,13 +940,13 @@ openclaw doctor - + Verifique: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (ou legado `channels.slack.dm.policy`) + - `channels.slack.dmPolicy` (ou o legado `channels.slack.dm.policy`) - aprovações de pareamento / entradas de allowlist - - eventos de DM do Slack Assistant: logs detalhados mencionando `drop message_changed` + - 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 remetente humano recuperável nos metadados da mensagem @@ -939,8 +956,8 @@ openclaw pairing list slack - - Valide tokens de bot + app e a habilitação de Socket Mode nas configurações do app Slack. + + Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do app do Slack. Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou `appTokenStatus: "configured_unavailable"`, a conta do Slack está @@ -949,12 +966,12 @@ openclaw pairing list slack - + Valide: - segredo de assinatura - - caminho do Webhook - - URLs de solicitação do Slack (Events + Interactivity + Slash Commands) + - caminho de Webhook + - URLs de solicitação do Slack (Eventos + Interatividade + Comandos slash) - `webhookPath` único por conta HTTP Se `signingSecretStatus: "configured_unavailable"` aparecer em snapshots de conta, @@ -963,11 +980,11 @@ openclaw pairing list slack - + Verifique se você pretendia usar: - - modo de comando nativo (`channels.slack.commands.native: true`) com comandos de barra correspondentes registrados no Slack - - ou modo de comando de barra único (`channels.slack.slashCommand.enabled: true`) + - 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. @@ -976,17 +993,17 @@ openclaw pairing list slack ## Referência de visão de anexos -O Slack pode anexar mídia baixada ao turno do agente quando os downloads de arquivo do Slack são bem-sucedidos e os limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável em vez de serem tratados como entrada de imagem. +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. ### Tipos de mídia compatíveis -| Tipo de mídia | Origem | Comportamento atual | Observações | +| 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` | Entrada do Slack não converte PDFs automaticamente em entrada de visão por imagem | -| Outros arquivos | URL de arquivo do Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem | -| Respostas em thread | Arquivos do início da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Inícios apenas com arquivo usam um espaço reservado 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 | +| 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) | +| 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 | ### Pipeline de entrada @@ -994,42 +1011,42 @@ Quando uma mensagem do Slack com anexos de arquivo chega: 1. O OpenClaw baixa o arquivo da URL privada do Slack usando o token do bot (`xoxb-...`). 2. O arquivo é gravado no armazenamento de mídia em caso de sucesso. -3. Os caminhos das mídias baixadas 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 imagens permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que conseguem lidar com eles. +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. ### Herança de anexos da raiz da thread Quando uma mensagem chega em uma thread (tem um pai `thread_ts`): -- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos raiz como contexto de início da thread. +- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos da raiz como contexto do iniciador 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 espaço reservado de anexo para que o fallback ainda possa incluir seus arquivos. +- 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 Quando uma única mensagem do Slack contém vários anexos de arquivo: - Cada anexo é processado independentemente pelo pipeline de mídia. -- As referências de mídia baixadas são agregadas ao contexto da mensagem. -- A ordem de processamento segue a ordem de arquivos do Slack na carga útil do evento. +- Referências de mídia baixada 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. ### 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 acima do limite e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos sem suporte. -- **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`. +- **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`. ### 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 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 em melhor esforço | Compartilhe novamente diretamente na thread do OpenClaw | -| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente por visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF | +| 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 | ### Documentação relacionada @@ -1043,13 +1060,13 @@ Quando uma única mensagem do Slack contém vários anexos de arquivo: - Vincule um usuário do Slack ao gateway. + Emparelhe um usuário do Slack ao Gateway. - Comportamento de canal e DM de grupo. + Comportamento de canais e DMs de grupo. - Encaminhe mensagens de entrada para agentes. + Roteie mensagens de entrada para agentes. Modelo de ameaças e hardening. diff --git a/docs/pt-BR/channels/tlon.md b/docs/pt-BR/channels/tlon.md index 748fe0aaa..9d9cdb848 100644 --- a/docs/pt-BR/channels/tlon.md +++ b/docs/pt-BR/channels/tlon.md @@ -1,40 +1,40 @@ --- read_when: - Trabalhando nos recursos do canal Tlon/Urbit -summary: Status de suporte, recursos e configuração do Tlon/Urbit +summary: Status, recursos e configuração do suporte ao Tlon/Urbit title: Tlon x-i18n: - generated_at: "2026-05-02T22:16:32Z" + generated_at: "2026-05-04T02:22:08Z" model: gpt-5.5 provider: openai - source_hash: 30915170786fc1ee8b84fb8be2ea42280262923064cfa9ca7107036096a13add + source_hash: 1718044541b431ff2437508e7e6659c14206f4aa84ab8b207e0d791dea2a48c5 source_path: channels/tlon.md workflow: 16 --- -O Tlon é um mensageiro descentralizado criado sobre o Urbit. O OpenClaw se conecta à sua nave Urbit e pode -responder a mensagens diretas e mensagens de chat em grupo. Respostas em grupo exigem uma menção @ por padrão e podem -ser ainda mais restritas por listas de permissão. +Tlon é um mensageiro descentralizado criado sobre Urbit. O OpenClaw se conecta ao seu ship Urbit e pode +responder a DMs e mensagens de chat em grupo. Respostas em grupo exigem uma menção @ por padrão e podem +ser ainda mais restritas por allowlists. -Status: Plugin incluído. Mensagens diretas, menções em grupo, respostas em threads, formatação de rich text e +Status: plugin integrado. DMs, menções em grupo, respostas em threads, formatação de rich text e uploads de imagens são compatíveis. Reações e enquetes ainda não são compatíveis. -## Plugin incluído +## Plugin integrado -O Tlon é distribuído como um Plugin incluído nas versões atuais do OpenClaw, então builds empacotados +Tlon é distribuído como um plugin integrado nas versões atuais do OpenClaw, então builds empacotados normais não precisam de uma instalação separada. -Se você estiver em uma build mais antiga ou em uma instalação personalizada que exclui o Tlon, instale um +Se você estiver em um build antigo ou em uma instalação personalizada que exclui o Tlon, instale um pacote npm atual: -Instale via CLI (registro npm): +Instalar via CLI (registro npm): ```bash openclaw plugins install @openclaw/tlon ``` -Use o pacote sem versão fixa para acompanhar a tag de versão oficial atual. Fixe uma versão exata -somente quando precisar de uma instalação reproduzível. +Use o pacote sem versão fixa para acompanhar a tag oficial de lançamento atual. Fixe uma versão +exata somente quando precisar de uma instalação reproduzível. Checkout local (ao executar a partir de um repositório git): @@ -46,13 +46,13 @@ Detalhes: [Plugins](/pt-BR/tools/plugin) ## Configuração -1. Verifique se o Plugin Tlon está disponível. - - As versões empacotadas atuais do OpenClaw já o incluem. - - Instalações mais antigas/personalizadas podem adicioná-lo manualmente com os comandos acima. -2. Reúna a URL da sua nave e o código de login. +1. Verifique se o plugin Tlon está disponível. + - Versões empacotadas atuais do OpenClaw já o incluem. + - Instalações antigas/personalizadas podem adicioná-lo manualmente com os comandos acima. +2. Reúna a URL do seu ship e o código de login. 3. Configure `channels.tlon`. -4. Reinicie o Gateway. -5. Envie uma mensagem direta para o bot ou mencione-o em um canal de grupo. +4. Reinicie o gateway. +5. Envie uma DM ao bot ou mencione-o em um canal de grupo. Configuração mínima (conta única): @@ -70,10 +70,10 @@ Configuração mínima (conta única): } ``` -## Naves privadas/LAN +## Ships privados/LAN -Por padrão, o OpenClaw bloqueia nomes de host e intervalos de IP privados/internos para proteção contra SSRF. -Se sua nave estiver em execução em uma rede privada (localhost, IP de LAN ou nome de host interno), +Por padrão, o OpenClaw bloqueia nomes de host e faixas de IP privados/internos para proteção contra SSRF. +Se o seu ship estiver sendo executado em uma rede privada (localhost, IP da LAN ou nome de host interno), você precisa habilitar isso explicitamente: ```json5 @@ -93,8 +93,8 @@ Isso se aplica a URLs como: - `http://192.168.x.x:8080` - `http://my-ship.local:8080` -⚠️ Habilite isso somente se você confiar na sua rede local. Esta configuração desativa as proteções contra SSRF -para solicitações à URL da sua nave. +⚠️ Habilite isso somente se você confiar na sua rede local. Essa configuração desativa as proteções contra SSRF +para solicitações à URL do seu ship. ## Canais de grupo @@ -110,7 +110,7 @@ A descoberta automática é habilitada por padrão. Você também pode fixar can } ``` -Desabilite a descoberta automática: +Desabilitar descoberta automática: ```json5 { @@ -124,7 +124,7 @@ Desabilite a descoberta automática: ## Controle de acesso -Lista de permissão de mensagens diretas (vazia = nenhuma mensagem direta permitida, use `ownerShip` para fluxo de aprovação): +Allowlist de DMs (vazio = nenhuma DM permitida, use `ownerShip` para fluxo de aprovação): ```json5 { @@ -161,7 +161,7 @@ Autorização de grupo (restrita por padrão): ## Proprietário e sistema de aprovação -Defina uma nave proprietária para receber solicitações de aprovação quando usuários não autorizados tentarem interagir: +Defina um ship proprietário para receber solicitações de aprovação quando usuários não autorizados tentarem interagir: ```json5 { @@ -173,19 +173,19 @@ Defina uma nave proprietária para receber solicitações de aprovação quando } ``` -A nave proprietária é **automaticamente autorizada em todos os lugares** — convites de mensagem direta são aceitos automaticamente e +O ship proprietário é **automaticamente autorizado em todos os lugares** — convites de DM são aceitos automaticamente e mensagens de canal são sempre permitidas. Você não precisa adicionar o proprietário a `dmAllowlist` ou `defaultAuthorizedShips`. -Quando definida, a nave proprietária recebe notificações por mensagem direta para: +Quando definido, o proprietário recebe notificações por DM para: -- Solicitações de mensagem direta de naves que não estão na lista de permissão +- Solicitações de DM de ships fora da allowlist - Menções em canais sem autorização - Solicitações de convite para grupo ## Configurações de aceitação automática -Aceitar automaticamente convites de mensagem direta (para naves em dmAllowlist): +Aceitar automaticamente convites de DM (para ships em dmAllowlist): ```json5 { @@ -197,51 +197,55 @@ Aceitar automaticamente convites de mensagem direta (para naves em dmAllowlist): } ``` -Aceitar automaticamente convites de grupo: +Aceitar automaticamente convites de grupo de ships confiáveis: ```json5 { channels: { tlon: { autoAcceptGroupInvites: true, + groupInviteAllowlist: ["~zod"], }, }, } ``` -## Destinos de entrega (CLI/Cron) +`autoAcceptGroupInvites` falha fechado quando `groupInviteAllowlist` está vazia. Defina a +allowlist para os ships cujos convites de grupo devem ser aceitos automaticamente. + +## Destinos de entrega (CLI/cron) Use estes com `openclaw message send` ou entrega por cron: -- Mensagem direta: `~sampel-palnet` ou `dm/~sampel-palnet` +- DM: `~sampel-palnet` ou `dm/~sampel-palnet` - Grupo: `chat/~host-ship/channel` ou `group:~host-ship/channel` -## Skill incluída +## Skill integrada -O Plugin Tlon inclui uma Skill incluída ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) -que fornece acesso via CLI a operações do Tlon: +O plugin Tlon inclui uma skill integrada ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) +que fornece acesso pela CLI a operações do Tlon: - **Contatos**: obter/atualizar perfis, listar contatos - **Canais**: listar, criar, publicar mensagens, buscar histórico - **Grupos**: listar, criar, gerenciar membros -- **Mensagens diretas**: enviar mensagens, reagir a mensagens -- **Reações**: adicionar/remover reações de emoji em publicações e mensagens diretas -- **Configurações**: gerenciar permissões do Plugin via comandos de barra +- **DMs**: enviar mensagens, reagir a mensagens +- **Reações**: adicionar/remover reações de emoji em publicações e DMs +- **Configurações**: gerenciar permissões do plugin por comandos slash -A Skill fica disponível automaticamente quando o Plugin é instalado. +A skill fica disponível automaticamente quando o plugin é instalado. -## Capacidades +## Recursos -| Recurso | Status | -| ---------------- | ------------------------------------------------ | -| Mensagens diretas | ✅ Compatível | -| Grupos/canais | ✅ Compatível (exige menção por padrão) | -| Threads | ✅ Compatível (respostas automáticas na thread) | -| Rich text | ✅ Markdown convertido para o formato do Tlon | -| Imagens | ✅ Enviadas para o armazenamento do Tlon | -| Reações | ✅ Via [Skill incluída](#bundled-skill) | -| Enquetes | ❌ Ainda não compatível | -| Comandos nativos | ✅ Compatível (somente proprietário por padrão) | +| Recurso | Status | +| ------------------- | -------------------------------------------------- | +| Mensagens diretas | ✅ Compatível | +| Grupos/canais | ✅ Compatível (exige menção por padrão) | +| Threads | ✅ Compatível (respostas automáticas na thread) | +| Rich text | ✅ Markdown convertido para o formato do Tlon | +| Imagens | ✅ Enviadas ao armazenamento do Tlon | +| Reações | ✅ Via [skill integrada](#bundled-skill) | +| Enquetes | ❌ Ainda não compatível | +| Comandos nativos | ✅ Compatível (somente proprietário por padrão) | ## Solução de problemas @@ -256,10 +260,10 @@ openclaw doctor Falhas comuns: -- **Mensagens diretas ignoradas**: remetente não está em `dmAllowlist` e nenhum `ownerShip` foi configurado para o fluxo de aprovação. +- **DMs ignoradas**: remetente não está em `dmAllowlist` e nenhum `ownerShip` foi configurado para o fluxo de aprovação. - **Mensagens de grupo ignoradas**: canal não descoberto ou remetente não autorizado. -- **Erros de conexão**: verifique se a URL da nave está acessível; habilite `allowPrivateNetwork` para naves locais. -- **Erros de autenticação**: verifique se o código de login está atual (códigos são rotacionados). +- **Erros de conexão**: verifique se a URL do ship está acessível; habilite `allowPrivateNetwork` para ships locais. +- **Erros de autenticação**: verifique se o código de login está atual (códigos fazem rotação). ## Referência de configuração @@ -268,31 +272,32 @@ Configuração completa: [Configuração](/pt-BR/gateway/configuration) Opções do provedor: - `channels.tlon.enabled`: habilita/desabilita a inicialização do canal. -- `channels.tlon.ship`: nome da nave Urbit do bot (por exemplo, `~sampel-palnet`). -- `channels.tlon.url`: URL da nave (por exemplo, `https://sampel-palnet.tlon.network`). -- `channels.tlon.code`: código de login da nave. -- `channels.tlon.allowPrivateNetwork`: permite URLs localhost/LAN (desvio de SSRF). -- `channels.tlon.ownerShip`: nave proprietária para o sistema de aprovação (sempre autorizada). -- `channels.tlon.dmAllowlist`: naves com permissão para enviar mensagem direta (vazia = nenhuma). -- `channels.tlon.autoAcceptDmInvites`: aceita automaticamente mensagens diretas de naves na lista de permissão. -- `channels.tlon.autoAcceptGroupInvites`: aceita automaticamente todos os convites de grupo. +- `channels.tlon.ship`: nome do ship Urbit do bot (por exemplo, `~sampel-palnet`). +- `channels.tlon.url`: URL do ship (por exemplo, `https://sampel-palnet.tlon.network`). +- `channels.tlon.code`: código de login do ship. +- `channels.tlon.allowPrivateNetwork`: permite URLs localhost/LAN (bypass de SSRF). +- `channels.tlon.ownerShip`: ship proprietário para o sistema de aprovação (sempre autorizado). +- `channels.tlon.dmAllowlist`: ships autorizados a enviar DM (vazio = nenhum). +- `channels.tlon.autoAcceptDmInvites`: aceita automaticamente DMs de ships na allowlist. +- `channels.tlon.autoAcceptGroupInvites`: aceita automaticamente convites de grupo de ships na allowlist. +- `channels.tlon.groupInviteAllowlist`: ships cujos convites de grupo podem ser aceitos automaticamente. - `channels.tlon.autoDiscoverChannels`: descobre automaticamente canais de grupo (padrão: true). - `channels.tlon.groupChannels`: ninhos de canais fixados manualmente. -- `channels.tlon.defaultAuthorizedShips`: naves autorizadas para todos os canais. +- `channels.tlon.defaultAuthorizedShips`: ships autorizados para todos os canais. - `channels.tlon.authorization.channelRules`: regras de autenticação por canal. -- `channels.tlon.showModelSignature`: acrescenta o nome do modelo às mensagens. +- `channels.tlon.showModelSignature`: anexa o nome do modelo às mensagens. ## Observações - Respostas em grupo exigem uma menção (por exemplo, `~your-bot-ship`) para responder. - Respostas em threads: se a mensagem recebida estiver em uma thread, o OpenClaw responde na thread. - Rich text: a formatação Markdown (negrito, itálico, código, cabeçalhos, listas) é convertida para o formato nativo do Tlon. -- Imagens: URLs são enviadas para o armazenamento do Tlon e incorporadas como blocos de imagem. +- Imagens: URLs são enviadas ao armazenamento do Tlon e incorporadas como blocos de imagem. -## Relacionado +## Relacionados -- [Visão geral de canais](/pt-BR/channels) — todos os canais compatíveis -- [Pareamento](/pt-BR/channels/pairing) — autenticação por mensagem direta e fluxo de pareamento +- [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis +- [Pareamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de pareamento - [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e exigência de menção - [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens -- [Segurança](/pt-BR/gateway/security) — modelo de acesso e fortalecimento +- [Segurança](/pt-BR/gateway/security) — modelo de acesso e proteção diff --git a/docs/pt-BR/channels/troubleshooting.md b/docs/pt-BR/channels/troubleshooting.md index d45ab55ce..68a16fcb7 100644 --- a/docs/pt-BR/channels/troubleshooting.md +++ b/docs/pt-BR/channels/troubleshooting.md @@ -1,19 +1,19 @@ --- read_when: - - O transporte do canal informa que está conectado, mas as respostas falham + - O transporte do canal diz que está conectado, mas as respostas falham - Você precisa de verificações específicas de canal antes da documentação aprofundada de provedores -summary: Solução rápida de problemas em nível de canal com assinaturas de falha e correções por canal +summary: Solução rápida de problemas no nível do canal com assinaturas de falha e correções por canal title: Solução de problemas de canais x-i18n: - generated_at: "2026-04-30T09:38:53Z" + generated_at: "2026-05-04T02:22:20Z" model: gpt-5.5 provider: openai - source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee + source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2 source_path: channels/troubleshooting.md workflow: 16 --- -Use esta página quando um canal conecta, mas o comportamento está incorreto. +Use esta página quando um canal se conecta, mas o comportamento está incorreto. ## Escada de comandos @@ -27,23 +27,23 @@ openclaw doctor openclaw channels status --probe ``` -Linha de base saudável: +Linha de base íntegra: - `Runtime: running` - `Connectivity probe: ok` -- `Capability: read-only`, `write-capable`, ou `admin-capable` -- A sondagem do canal mostra o transporte conectado e, quando compatível, `works` ou `audit ok` +- `Capability: read-only`, `write-capable` ou `admin-capable` +- A sondagem do canal mostra o transporte conectado e, quando houver suporte, `works` ou `audit ok` ## WhatsApp ### Assinaturas de falha do WhatsApp -| Sintoma | Verificação mais rápida | Correção | -| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Conectado, mas sem respostas em DM | `openclaw pairing list whatsapp` | Aprove o remetente ou altere a política/lista de permissões de DM. | -| Mensagens de grupo ignoradas | Verifique `requireMention` + padrões de menção na configuração | Mencione o bot ou flexibilize a política de menção para esse grupo. | -| Login por QR expira com 408 | Verifique as env `HTTPS_PROXY` / `HTTP_PROXY` do Gateway | Configure um proxy acessível; use `NO_PROXY` apenas para desvios. | -| Loops aleatórios de desconexão/relogin | `openclaw channels status --probe` + logs | Reconexões recentes são sinalizadas mesmo quando atualmente conectado; acompanhe os logs, reinicie o Gateway e religue se a instabilidade continuar. | +| Sintoma | Verificação mais rápida | Correção | +| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Conectado, mas sem respostas por DM | `openclaw pairing list whatsapp` | Aprove o remetente ou altere a política/lista de permissões de DM. | +| Mensagens de grupo ignoradas | Verifique `requireMention` + padrões de menção na configuração | Mencione o bot ou afrouxe a política de menção desse grupo. | +| Login por QR expira com 408 | Verifique as env `HTTPS_PROXY` / `HTTP_PROXY` do Gateway | Configure um proxy acessível; use `NO_PROXY` apenas para desvios. | +| Ciclos aleatórios de desconexão/novo login | `openclaw channels status --probe` + logs | Reconexões recentes são sinalizadas mesmo quando conectado no momento; observe os logs, reinicie o Gateway e, depois, revincule se a instabilidade continuar. | Solução de problemas completa: [Solução de problemas do WhatsApp](/pt-BR/channels/whatsapp#troubleshooting) @@ -51,15 +51,15 @@ Solução de problemas completa: [Solução de problemas do WhatsApp](/pt-BR/cha ### Assinaturas de falha do Telegram -| Sintoma | Verificação mais rápida | Correção | -| ------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `/start`, mas sem fluxo de resposta utilizável | `openclaw pairing list telegram` | Aprove o pareamento ou altere a política de DM. | -| Bot online, mas o grupo permanece silencioso | Verifique o requisito de menção e o modo de privacidade do bot | Desative o modo de privacidade para visibilidade no grupo ou mencione o bot. | -| Falhas de envio com erros de rede | Inspecione os logs em busca de falhas de chamada da API do Telegram | Corrija o roteamento de DNS/IPv6/proxy para `api.telegram.org`. | -| Inicialização relata `getMe returned 401` | Verifique a origem do token configurado | Copie novamente ou gere de novo o token do BotFather e atualize `botToken`, `tokenFile` ou o `TELEGRAM_BOT_TOKEN` da conta padrão. | +| Sintoma | Verificação mais rápida | Correção | +| ------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `/start`, mas sem fluxo de resposta utilizável | `openclaw pairing list telegram` | Aprove o pareamento ou altere a política de DM. | +| Bot online, mas o grupo permanece silencioso | Verifique o requisito de menção e o modo de privacidade do bot | Desative o modo de privacidade para visibilidade no grupo ou mencione o bot. | +| Falhas de envio com erros de rede | Inspecione os logs em busca de falhas de chamada à API do Telegram | Corrija o roteamento de DNS/IPv6/proxy para `api.telegram.org`. | +| Inicialização relata `getMe returned 401` | Verifique a origem do token configurado | Copie novamente ou regenere o token do BotFather e atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` da conta padrão. | | Polling trava ou reconecta lentamente | `openclaw logs --follow` para diagnósticos de polling | Atualize; se reinicializações forem falsos positivos, ajuste `pollingStallThresholdMs`. Travamentos persistentes ainda apontam para proxy/DNS/IPv6. | -| `setMyCommands` rejeitado na inicialização | Inspecione os logs por `BOT_COMMANDS_TOO_MUCH` | Reduza comandos do Telegram de Plugin/Skills/personalizados ou desative menus nativos. | -| Atualizou e a lista de permissões bloqueia você | `openclaw security audit` e listas de permissões na configuração | Execute `openclaw doctor --fix` ou substitua `@username` por IDs numéricos de remetente. | +| `setMyCommands` rejeitado na inicialização | Inspecione os logs em busca de `BOT_COMMANDS_TOO_MUCH` | Reduza comandos de Plugin/Skills/personalizados do Telegram ou desative menus nativos. | +| Atualizou e a lista de permissões bloqueia você | `openclaw security audit` e listas de permissões na configuração | Execute `openclaw doctor --fix` ou substitua `@username` por IDs numéricos de remetente. | Solução de problemas completa: [Solução de problemas do Telegram](/pt-BR/channels/telegram#troubleshooting) @@ -67,11 +67,12 @@ Solução de problemas completa: [Solução de problemas do Telegram](/pt-BR/cha ### Assinaturas de falha do Discord -| Sintoma | Verificação mais rápida | Correção | -| ------------------------------- | ------------------------------------ | --------------------------------------------------------- | -| Bot online, mas sem respostas em guild | `openclaw channels status --probe` | Permita a guild/canal e verifique a intenção de conteúdo da mensagem. | -| Mensagens de grupo ignoradas | Verifique os logs em busca de descartes por bloqueio de menção | Mencione o bot ou defina `requireMention: false` na guild/canal. | -| Respostas de DM ausentes | `openclaw pairing list discord` | Aprove o pareamento de DM ou ajuste a política de DM. | +| Sintoma | Verificação mais rápida | Correção | +| ----------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bot online, mas sem respostas em guild | `openclaw channels status --probe` | Permita a guild/canal e verifique a intent de conteúdo da mensagem. | +| Mensagens de grupo ignoradas | Verifique nos logs quedas por controle de menção | Mencione o bot ou defina `requireMention: false` para a guild/canal. | +| Uso de digitação/token, mas sem mensagem no Discord | O log da sessão mostra texto do assistente com `didSendViaMessagingTool: false` | O modelo respondeu em privado em vez de chamar a ferramenta de mensagens. Use um modelo confiável para chamadas de ferramenta ou defina `messages.groupChat.visibleReplies: "automatic"` para publicar automaticamente. | +| Respostas por DM ausentes | `openclaw pairing list discord` | Aprove o pareamento por DM ou ajuste a política de DM. | Solução de problemas completa: [Solução de problemas do Discord](/pt-BR/channels/discord#troubleshooting) @@ -79,11 +80,11 @@ Solução de problemas completa: [Solução de problemas do Discord](/pt-BR/chan ### Assinaturas de falha do Slack -| Sintoma | Verificação mais rápida | Correção | -| -------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| Modo socket conectado, mas sem respostas | `openclaw channels status --probe` | Verifique o token do app + token do bot e os escopos necessários; observe `botTokenStatus` / `appTokenStatus = configured_unavailable` em configurações baseadas em SecretRef. | -| DMs bloqueadas | `openclaw pairing list slack` | Aprove o pareamento ou flexibilize a política de DM. | -| Mensagem de canal ignorada | Verifique `groupPolicy` e a lista de permissões de canais | Permita o canal ou altere a política para `open`. | +| Sintoma | Verificação mais rápida | Correção | +| -------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Socket mode conectado, mas sem respostas | `openclaw channels status --probe` | Verifique o token do app + token do bot e os escopos necessários; observe `botTokenStatus` / `appTokenStatus = configured_unavailable` em configurações baseadas em SecretRef. | +| DMs bloqueadas | `openclaw pairing list slack` | Aprove o pareamento ou afrouxe a política de DM. | +| Mensagem de canal ignorada | Verifique `groupPolicy` e a lista de permissões do canal | Permita o canal ou altere a política para `open`. | Solução de problemas completa: [Solução de problemas do Slack](/pt-BR/channels/slack#troubleshooting) @@ -91,11 +92,11 @@ Solução de problemas completa: [Solução de problemas do Slack](/pt-BR/channe ### Assinaturas de falha do iMessage e BlueBubbles -| Sintoma | Verificação mais rápida | Correção | -| -------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- | -| Sem eventos de entrada | Verifique a acessibilidade do Webhook/servidor e permissões do app | Corrija a URL do Webhook ou o estado do servidor BlueBubbles. | -| Consegue enviar, mas não receber no macOS | Verifique as permissões de privacidade do macOS para automação do Mensagens | Conceda novamente permissões de TCC e reinicie o processo do canal. | -| Remetente de DM bloqueado | `openclaw pairing list imessage` ou `openclaw pairing list bluebubbles` | Aprove o pareamento ou atualize a lista de permissões. | +| Sintoma | Verificação mais rápida | Correção | +| -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- | +| Nenhum evento de entrada | Verifique a acessibilidade do webhook/servidor e as permissões do app | Corrija a URL do webhook ou o estado do servidor BlueBubbles. | +| Consegue enviar, mas não recebe no macOS | Verifique as permissões de privacidade do macOS para automação do Mensagens | Conceda novamente as permissões TCC e reinicie o processo do canal. | +| Remetente de DM bloqueado | `openclaw pairing list imessage` ou `openclaw pairing list bluebubbles` | Aprove o pareamento ou atualize a lista de permissões. | Solução de problemas completa: @@ -106,11 +107,11 @@ Solução de problemas completa: ### Assinaturas de falha do Signal -| Sintoma | Verificação mais rápida | Correção | -| ------------------------------- | -------------------------------------------- | ------------------------------------------------------- | -| Daemon acessível, mas bot silencioso | `openclaw channels status --probe` | Verifique a URL/conta do daemon `signal-cli` e o modo de recebimento. | -| DM bloqueada | `openclaw pairing list signal` | Aprove o remetente ou ajuste a política de DM. | -| Respostas de grupo não disparam | Verifique a lista de permissões de grupo e padrões de menção | Adicione remetente/grupo ou afrouxe o bloqueio. | +| Sintoma | Verificação mais rápida | Correção | +| ------------------------------- | -------------------------------------------- | ---------------------------------------------------------- | +| Daemon acessível, mas bot silencioso | `openclaw channels status --probe` | Verifique a URL/conta do daemon `signal-cli` e o modo de recebimento. | +| DM bloqueada | `openclaw pairing list signal` | Aprove o remetente ou ajuste a política de DM. | +| Respostas de grupo não disparam | Verifique a lista de permissões do grupo e os padrões de menção | Adicione remetente/grupo ou afrouxe o controle. | Solução de problemas completa: [Solução de problemas do Signal](/pt-BR/channels/signal#troubleshooting) @@ -118,12 +119,12 @@ Solução de problemas completa: [Solução de problemas do Signal](/pt-BR/chann ### Assinaturas de falha do QQ Bot -| Sintoma | Verificação mais rápida | Correção | -| ------------------------------- | ----------------------------------------------- | -------------------------------------------------------------- | -| Bot responde "foi para Marte" | Verifique `appId` e `clientSecret` na configuração | Defina credenciais ou reinicie o Gateway. | -| Sem mensagens de entrada | `openclaw channels status --probe` | Verifique as credenciais na QQ Open Platform. | -| Voz não transcrita | Verifique a configuração do provedor STT | Configure `channels.qqbot.stt` ou `tools.media.audio`. | -| Mensagens proativas não chegam | Verifique os requisitos de interação da plataforma QQ | QQ pode bloquear mensagens iniciadas pelo bot sem interação recente. | +| Sintoma | Verificação mais rápida | Correção | +| ------------------------------- | --------------------------------------------- | --------------------------------------------------------------- | +| Bot responde "foi para Marte" | Verifique `appId` e `clientSecret` na configuração | Defina as credenciais ou reinicie o Gateway. | +| Nenhuma mensagem de entrada | `openclaw channels status --probe` | Verifique as credenciais na QQ Open Platform. | +| Voz não transcrita | Verifique a configuração do provedor de STT | Configure `channels.qqbot.stt` ou `tools.media.audio`. | +| Mensagens proativas não chegam | Verifique os requisitos de interação da plataforma QQ | O QQ pode bloquear mensagens iniciadas pelo bot sem interação recente. | Solução de problemas completa: [Solução de problemas do QQ Bot](/pt-BR/channels/qqbot#troubleshooting) @@ -131,13 +132,13 @@ Solução de problemas completa: [Solução de problemas do QQ Bot](/pt-BR/chann ### Assinaturas de falha do Matrix -| Sintoma | Verificação mais rápida | Correção | -| ----------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ | -| Logado, mas ignora mensagens de sala | `openclaw channels status --probe` | Verifique `groupPolicy`, a lista de permissões de salas e o bloqueio por menção. | -| DMs não são processadas | `openclaw pairing list matrix` | Aprove o remetente ou ajuste a política de DM. | -| Salas criptografadas falham | `openclaw matrix verify status` | Verifique novamente o dispositivo e depois verifique `openclaw matrix verify backup status`. | -| Restauração de backup pendente/quebrada | `openclaw matrix verify backup status` | Execute `openclaw matrix verify backup restore` ou execute novamente com uma chave de recuperação. | -| Cross-signing/bootstrap parece incorreto | `openclaw matrix verify bootstrap` | Repare armazenamento secreto, cross-signing e estado do backup em uma única passagem. | +| Sintoma | Verificação mais rápida | Correção | +| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- | +| Conectado, mas ignora mensagens da sala | `openclaw channels status --probe` | Verifique `groupPolicy`, a lista de permissões da sala e o controle de menção. | +| DMs não são processadas | `openclaw pairing list matrix` | Aprove o remetente ou ajuste a política de DM. | +| Salas criptografadas falham | `openclaw matrix verify status` | Verifique novamente o dispositivo e, depois, confira `openclaw matrix verify backup status`. | +| Restauração de backup está pendente/quebrada | `openclaw matrix verify backup status` | Execute `openclaw matrix verify backup restore` ou rode novamente com uma chave de recuperação. | +| Assinatura cruzada/bootstrap parece incorreta | `openclaw matrix verify bootstrap` | Repare o armazenamento secreto, a assinatura cruzada e o estado do backup em uma única passagem. | Configuração completa: [Matrix](/pt-BR/channels/matrix) diff --git a/docs/pt-BR/cli/doctor.md b/docs/pt-BR/cli/doctor.md index 8e9b19e70..725022942 100644 --- a/docs/pt-BR/cli/doctor.md +++ b/docs/pt-BR/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - Você tem problemas de conectividade/autenticação e quer correções guiadas + - Você tem problemas de conectividade/autenticação e deseja correções guiadas - Você atualizou e quer uma verificação rápida summary: Referência da CLI para `openclaw doctor` (verificações de integridade + reparos guiados) title: Diagnóstico x-i18n: - generated_at: "2026-05-03T21:28:29Z" + generated_at: "2026-05-04T02:22:18Z" model: gpt-5.5 provider: openai - source_hash: d4baab5b0cd4d046d12ae5bd14ccf05224115856d45e630a57e77a2be15e5db0 + source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Verificações de integridade + correções rápidas para o gateway e os canais. +Verificações de integridade + correções rápidas para o Gateway e canais. Relacionado: @@ -35,44 +35,44 @@ openclaw doctor --generate-gateway-token ## Opções - `--no-workspace-suggestions`: desativa sugestões de memória/pesquisa do workspace -- `--yes`: aceita os padrões sem perguntar -- `--repair`: aplica correções recomendadas que não envolvem serviço sem perguntar; instalações e reescritas do serviço de gateway ainda exigem confirmação interativa ou comandos explícitos de gateway +- `--yes`: aceita os padrões sem solicitar confirmação +- `--repair`: aplica reparos recomendados que não envolvem serviço sem solicitar confirmação; instalações e reescritas do serviço do Gateway ainda exigem confirmação interativa ou comandos explícitos do Gateway - `--fix`: alias para `--repair` -- `--force`: aplica correções agressivas, incluindo sobrescrever a configuração personalizada do serviço quando necessário -- `--non-interactive`: executa sem prompts; apenas migrações seguras e correções que não envolvem serviço -- `--generate-gateway-token`: gera e configura um token de gateway -- `--deep`: verifica os serviços do sistema em busca de instalações extras do gateway +- `--force`: aplica reparos agressivos, incluindo sobrescrever configuração personalizada de serviço quando necessário +- `--non-interactive`: executa sem prompts; apenas migrações seguras e reparos que não envolvem serviço +- `--generate-gateway-token`: gera e configura um token do Gateway +- `--deep`: verifica serviços do sistema em busca de instalações extras do Gateway Observações: -- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções sem interface (cron, Telegram, sem terminal) pularão os prompts. -- Desempenho: execuções não interativas de `doctor` pulam o carregamento antecipado de plugins para que as verificações de integridade sem interface permaneçam rápidas. Sessões interativas ainda carregam plugins por completo quando uma verificação precisa da contribuição deles. +- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções sem interface (cron, Telegram, sem terminal) ignorarão prompts. +- Desempenho: execuções não interativas de `doctor` ignoram o carregamento antecipado de plugins para manter verificações de integridade sem interface rápidas. Sessões interativas ainda carregam plugins completamente quando uma verificação precisa da contribuição deles. - `--fix` (alias para `--repair`) grava um backup em `~/.openclaw/openclaw.json.bak` e remove chaves de configuração desconhecidas, listando cada remoção. -- `doctor --fix --non-interactive` informa definições de serviço de gateway ausentes ou obsoletas, mas não as instala nem reescreve fora do modo de correção de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador. +- `doctor --fix --non-interactive` relata definições de serviço do Gateway ausentes ou obsoletas, mas não as instala nem reescreve fora do modo de reparo de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher. - As verificações de integridade de estado agora detectam arquivos de transcrição órfãos no diretório de sessões. Arquivá-los como `.deleted.` exige uma confirmação interativa; `--fix`, `--yes` e execuções sem interface os deixam no lugar. -- O Doctor também verifica `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de tarefas cron e pode reescrevê-los no local antes que o agendador precise normalizá-los automaticamente em runtime. -- No Linux, o Doctor avisa quando o crontab do usuário ainda executa o `~/.openclaw/bin/ensure-whatsapp.sh` legado; esse script não é mais mantido e pode registrar falsas indisponibilidades do gateway do WhatsApp quando o cron não tem o ambiente de barramento de usuário do systemd. -- O Doctor limpa o estado legado de preparação de dependências de plugins criado por versões antigas do OpenClaw. Ele também repara plugins baixáveis configurados ausentes quando o registro consegue resolvê-los, e a passagem do Doctor 2026.5.2 instala automaticamente plugins baixáveis que uma configuração antiga já usa antes de marcar a configuração como tocada para essa versão. -- O Doctor repara configurações obsoletas de plugins removendo ids de plugins ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal correspondente pendente, destinos de heartbeat e substituições de modelo de canal quando a descoberta de plugins está saudável. -- O Doctor coloca em quarentena configurações inválidas de plugins desativando a entrada `plugins.entries.` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já pula apenas esse plugin inválido para que outros plugins e canais possam continuar em execução. -- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerencia o ciclo de vida do gateway. O Doctor ainda informa a integridade do gateway/serviço e aplica correções que não envolvem serviço, mas pula instalação/início/reinício/bootstrap do serviço e limpeza de serviços legados. -- No Linux, o Doctor ignora unidades systemd extras inativas semelhantes ao gateway e não reescreve metadados de comando/entrypoint para um serviço de gateway systemd em execução durante a correção. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador ativo. -- O Doctor migra automaticamente a configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e relacionados) para `talk.provider` + `talk.providers.`. -- Execuções repetidas de `doctor --fix` não informam/aplicam mais normalização do Talk quando a única diferença é a ordem das chaves do objeto. -- O Doctor inclui uma verificação de prontidão de pesquisa de memória e pode recomendar `openclaw configure --section model` quando credenciais de embeddings estão ausentes. -- O Doctor avisa quando nenhum proprietário de comando está configurado. O proprietário de comando é a conta do operador humano autorizada a executar comandos exclusivos do proprietário e aprovar ações perigosas. O pareamento por DM só permite que alguém converse com o bot; se você aprovou um remetente antes de existir o bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente. -- O Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais da CLI do Codex existem na home do Codex do operador. Inicializações locais do servidor de aplicativo do Codex usam homes isoladas por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente. -- O Doctor avisa quando skills permitidas para o agente padrão estão indisponíveis no ambiente de runtime atual porque bins, env vars, config ou requisitos de SO estão ausentes. `doctor --fix` pode desativar essas skills indisponíveis com `skills.entries..enabled=false`; instale/configure o requisito ausente quando quiser manter a skill ativa. -- Se o modo sandbox estiver ativado, mas o Docker estiver indisponível, o Doctor informa um aviso de alto sinal com correção (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`). -- Se arquivos legados de registro do sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, o Doctor os informa; `openclaw doctor --fix` migra entradas válidas para diretórios de registro fragmentados e coloca arquivos legados inválidos em quarentena. -- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho de comando atual, o Doctor informa um aviso somente leitura e não grava credenciais de fallback em texto puro. -- Se a inspeção de SecretRef de canal falhar em um caminho de correção, o Doctor continua e informa um aviso em vez de sair antecipadamente. -- Após migrações de diretório de estado, o Doctor avisa quando contas padrão habilitadas do Telegram ou Discord dependem de fallback por env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo do Doctor. -- A resolução automática de nome de usuário de `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho de comando atual. Se a inspeção do token estiver indisponível, o Doctor informa um aviso e pula a resolução automática nessa passagem. +- Doctor também verifica `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de tarefas cron e pode reescrevê-los no lugar antes que o agendador precise normalizá-los automaticamente em tempo de execução. +- No Linux, Doctor avisa quando o crontab do usuário ainda executa o legado `~/.openclaw/bin/ensure-whatsapp.sh`; esse script não é mais mantido e pode registrar falsas indisponibilidades do Gateway do WhatsApp quando o cron não tem o ambiente do barramento de usuário do systemd. +- Doctor limpa estado legado de preparação de dependências de plugins criado por versões antigas do OpenClaw. Ele também repara plugins baixáveis configurados ausentes quando o registro consegue resolvê-los, e a passagem de Doctor 2026.5.2 instala automaticamente plugins baixáveis que uma configuração antiga já usa antes de marcar a configuração como tocada para essa versão. Se o download falhar, Doctor relata o erro de instalação e preserva a entrada de plugin configurada para a próxima tentativa de reparo. +- Doctor repara configuração obsoleta de plugins removendo ids de plugins ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal pendente correspondente, alvos de Heartbeat e substituições de modelo de canal quando a descoberta de plugins está íntegra. +- Doctor coloca configuração inválida de plugins em quarentena desativando a entrada `plugins.entries.` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já ignora apenas esse plugin problemático, para que outros plugins e canais possam continuar em execução. +- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerencia o ciclo de vida do Gateway. Doctor ainda relata a integridade do Gateway/serviço e aplica reparos que não envolvem serviço, mas ignora instalação/início/reinício/bootstrap do serviço e limpeza de serviço legado. +- No Linux, Doctor ignora unidades systemd extras semelhantes ao Gateway que estejam inativas e não reescreve metadados de comando/entrypoint para um serviço systemd do Gateway em execução durante o reparo. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher ativo. +- Doctor migra automaticamente configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e relacionados) para `talk.provider` + `talk.providers.`. +- Execuções repetidas de `doctor --fix` não relatam/aplicam mais normalização do Talk quando a única diferença é a ordem das chaves do objeto. +- Doctor inclui uma verificação de prontidão de pesquisa de memória e pode recomendar `openclaw configure --section model` quando credenciais de embeddings estão ausentes. +- Doctor avisa quando nenhum proprietário de comandos está configurado. O proprietário de comandos é a conta do operador humano autorizada a executar comandos exclusivos de proprietário e aprovar ações perigosas. O pareamento por DM apenas permite que alguém fale com o bot; se você aprovou um remetente antes de existir o bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente. +- Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais do Codex CLI existem no diretório inicial Codex do operador. Inicializações locais do servidor de app do Codex usam diretórios iniciais isolados por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente. +- Doctor avisa quando Skills permitidas para o agente padrão estão indisponíveis no ambiente de execução atual porque bins, variáveis de ambiente, configuração ou requisitos de SO estão ausentes. `doctor --fix` pode desativar essas skills indisponíveis com `skills.entries..enabled=false`; instale/configure o requisito ausente em vez disso quando quiser manter a skill ativa. +- Se o modo sandbox estiver ativado mas o Docker estiver indisponível, Doctor relata um aviso de alto sinal com correção (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`). +- Se arquivos legados do registro do sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, Doctor os relata; `openclaw doctor --fix` migra entradas válidas para diretórios de registro particionados e coloca arquivos legados inválidos em quarentena. +- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho do comando atual, Doctor relata um aviso somente leitura e não grava credenciais fallback em texto simples. +- Se a inspeção de SecretRef do canal falhar em um caminho de correção, Doctor continua e relata um aviso em vez de sair antecipadamente. +- Após migrações de diretório de estado, Doctor avisa quando contas padrão ativadas do Telegram ou Discord dependem de fallback por env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo do Doctor. +- A resolução automática de nome de usuário `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho do comando atual. Se a inspeção do token estiver indisponível, Doctor relata um aviso e ignora a resolução automática nessa passagem. ## macOS: substituições de env do `launchctl` -Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor substitui seu arquivo de configuração e pode causar erros persistentes de “unauthorized”. +Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor sobrescreve seu arquivo de configuração e pode causar erros persistentes de “não autorizado”. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN diff --git a/docs/pt-BR/concepts/agent.md b/docs/pt-BR/concepts/agent.md index acad0407d..d2680511b 100644 --- a/docs/pt-BR/concepts/agent.md +++ b/docs/pt-BR/concepts/agent.md @@ -1,54 +1,54 @@ --- read_when: - - Alterar o runtime do agente, o bootstrap do workspace ou o comportamento da sessão -summary: Tempo de execução do agente, contrato do espaço de trabalho e inicialização da sessão -title: Tempo de execução do agente + - Alteração do ambiente de execução do agente, da inicialização do espaço de trabalho ou do comportamento da sessão +summary: Tempo de execução do agente, contrato do ambiente de trabalho e inicialização da sessão +title: Ambiente de execução do agente x-i18n: - generated_at: "2026-04-30T09:43:29Z" + generated_at: "2026-05-04T02:22:17Z" model: gpt-5.5 provider: openai - source_hash: f4d65ee96cece296251d7d3a0512f12d2dfa900db0e5ffc0f37dcddae7ea55ad + source_hash: 89bbbd05a9bf2054d3a1f24aeed005a05b61152a047b593addfb46817baae05a source_path: concepts/agent.md workflow: 16 --- -OpenClaw executa um **único runtime de agente incorporado** — um processo de agente por -Gateway, com seu próprio espaço de trabalho, arquivos de inicialização e armazenamento de sessões. Esta página -cobre esse contrato de runtime: o que o espaço de trabalho deve conter, quais arquivos são -injetados e como as sessões são inicializadas com base nele. +OpenClaw executa um **runtime de agente incorporado único** — um processo de agente por +Gateway, com seu próprio workspace, arquivos de bootstrap e armazenamento de sessões. Esta página +cobre esse contrato de runtime: o que o workspace deve conter, quais arquivos são +injetados e como as sessões fazem bootstrap com base nele. -## Espaço de trabalho (obrigatório) +## Workspace (obrigatório) -OpenClaw usa um único diretório de espaço de trabalho do agente (`agents.defaults.workspace`) como o **único** diretório de trabalho (`cwd`) do agente para ferramentas e contexto. +OpenClaw usa um único diretório de workspace do agente (`agents.defaults.workspace`) como o **único** diretório de trabalho (`cwd`) do agente para ferramentas e contexto. -Recomendado: use `openclaw setup` para criar `~/.openclaw/openclaw.json` caso esteja ausente e inicializar os arquivos do espaço de trabalho. +Recomendado: use `openclaw setup` para criar `~/.openclaw/openclaw.json` se ele estiver ausente e inicializar os arquivos do workspace. -Layout completo do espaço de trabalho + guia de backup: [Espaço de trabalho do agente](/pt-BR/concepts/agent-workspace) +Layout completo do workspace + guia de backup: [Workspace do agente](/pt-BR/concepts/agent-workspace) -Se `agents.defaults.sandbox` estiver habilitado, sessões que não sejam a principal podem substituir isso com -espaços de trabalho por sessão em `agents.defaults.sandbox.workspaceRoot` (consulte +Se `agents.defaults.sandbox` estiver habilitado, sessões que não sejam principais podem sobrescrever isso com +workspaces por sessão em `agents.defaults.sandbox.workspaceRoot` (consulte [Configuração do Gateway](/pt-BR/gateway/configuration)). -## Arquivos de inicialização (injetados) +## Arquivos de bootstrap (injetados) -Dentro de `agents.defaults.workspace`, o OpenClaw espera estes arquivos editáveis pelo usuário: +Dentro de `agents.defaults.workspace`, OpenClaw espera estes arquivos editáveis pelo usuário: - `AGENTS.md` — instruções operacionais + “memória” - `SOUL.md` — persona, limites, tom - `TOOLS.md` — notas de ferramentas mantidas pelo usuário (por exemplo, `imsg`, `sag`, convenções) - `BOOTSTRAP.md` — ritual único da primeira execução (excluído após a conclusão) - `IDENTITY.md` — nome/vibe/emoji do agente -- `USER.md` — perfil do usuário + forma de tratamento preferida +- `USER.md` — perfil do usuário + forma preferida de tratamento -No primeiro turno de uma nova sessão, o OpenClaw injeta o conteúdo desses arquivos diretamente no contexto do agente. +No primeiro turno de uma nova sessão, OpenClaw injeta o conteúdo desses arquivos no Contexto do Projeto do prompt do sistema. -Arquivos em branco são ignorados. Arquivos grandes são aparados e truncados com um marcador para manter os prompts enxutos (leia o arquivo para ver o conteúdo completo). +Arquivos em branco são ignorados. Arquivos grandes são aparados e truncados com um marcador para que os prompts permaneçam enxutos (leia o arquivo para ver o conteúdo completo). -Se um arquivo estiver ausente, o OpenClaw injeta uma única linha de marcador de “arquivo ausente” (e `openclaw setup` criará um modelo padrão seguro). +Se um arquivo estiver ausente, OpenClaw injeta uma única linha de marcador de “arquivo ausente” (e `openclaw setup` criará um modelo padrão seguro). -`BOOTSTRAP.md` é criado apenas para um **espaço de trabalho totalmente novo** (sem outros arquivos de inicialização presentes). Se você o excluir após concluir o ritual, ele não deverá ser recriado em reinicializações posteriores. +`BOOTSTRAP.md` só é criado para um **workspace totalmente novo** (sem outros arquivos de bootstrap presentes). Enquanto ele estiver pendente, OpenClaw o mantém no Contexto do Projeto e adiciona orientações de bootstrap ao prompt do sistema para o ritual inicial, em vez de copiá-lo para a mensagem do usuário. Se você excluí-lo depois de concluir o ritual, ele não deve ser recriado em reinicializações posteriores. -Para desabilitar completamente a criação de arquivos de inicialização (para espaços de trabalho pré-preenchidos), defina: +Para desabilitar totalmente a criação de arquivos de bootstrap (para workspaces pré-preenchidos), defina: ```json5 { agents: { defaults: { skipBootstrap: true } } } @@ -56,18 +56,18 @@ Para desabilitar completamente a criação de arquivos de inicialização (para ## Ferramentas integradas -Ferramentas principais (read/exec/edit/write e ferramentas de sistema relacionadas) estão sempre disponíveis, +Ferramentas principais (leitura/execução/edição/escrita e ferramentas de sistema relacionadas) estão sempre disponíveis, sujeitas à política de ferramentas. `apply_patch` é opcional e controlado por `tools.exec.applyPatch`. `TOOLS.md` **não** controla quais ferramentas existem; ele é -orientação sobre como _você_ quer que elas sejam usadas. +uma orientação sobre como _você_ quer que elas sejam usadas. ## Skills -O OpenClaw carrega Skills destes locais (maior precedência primeiro): +OpenClaw carrega Skills destes locais (maior precedência primeiro): -- Espaço de trabalho: `/skills` +- Workspace: `/skills` - Skills de agente do projeto: `/.agents/skills` -- Skills pessoais do agente: `~/.agents/skills` +- Skills de agente pessoais: `~/.agents/skills` - Gerenciadas/locais: `~/.openclaw/skills` - Incluídas (distribuídas com a instalação) - Pastas extras de Skills: `skills.load.extraDirs` @@ -77,12 +77,12 @@ Skills podem ser controladas por configuração/env (consulte `skills` em [Confi ## Limites do runtime O runtime de agente incorporado é construído sobre o núcleo de agente Pi (modelos, ferramentas e -pipeline de prompt). Gerenciamento de sessões, descoberta, conexão de ferramentas e entrega por canal -são camadas de responsabilidade do OpenClaw sobre esse núcleo. +pipeline de prompt). Gerenciamento de sessões, descoberta, conexão de ferramentas e entrega por canais +são camadas pertencentes ao OpenClaw sobre esse núcleo. ## Sessões -As transcrições de sessão são armazenadas como JSONL em: +Transcrições de sessão são armazenadas como JSONL em: - `~/.openclaw/agents//sessions/.jsonl` @@ -91,29 +91,29 @@ Pastas de sessão legadas de outras ferramentas não são lidas. ## Direcionamento durante streaming -Quando o modo de fila é `steer`, mensagens recebidas são injetadas na execução atual. +Quando o modo de fila é `steer`, mensagens de entrada são injetadas na execução atual. O direcionamento enfileirado é entregue **depois que o turno atual do assistente termina -de executar suas chamadas de ferramentas**, antes da próxima chamada ao LLM. O Pi drena todas as mensagens -de direcionamento pendentes juntas para `steer`; o `queue` legado drena uma mensagem por -limite de modelo. O direcionamento não ignora mais as chamadas de ferramentas restantes da mensagem +de executar suas chamadas de ferramenta**, antes da próxima chamada ao LLM. Pi drena todas as mensagens de +direcionamento pendentes juntas para `steer`; o `queue` legado drena uma mensagem por +limite de modelo. O direcionamento não ignora mais as chamadas de ferramenta restantes da mensagem atual do assistente. -Quando o modo de fila é `followup` ou `collect`, mensagens recebidas são mantidas até o -turno atual terminar; então um novo turno do agente começa com os payloads enfileirados. Consulte -[Fila](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering) para comportamento de modo +Quando o modo de fila é `followup` ou `collect`, mensagens de entrada são retidas até o +turno atual terminar; então, um novo turno do agente começa com os payloads enfileirados. Consulte +[Fila](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering) para o comportamento de modo e limites. O streaming por blocos envia blocos concluídos do assistente assim que eles terminam; ele fica **desativado por padrão** (`agents.defaults.blockStreamingDefault: "off"`). Ajuste o limite via `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; o padrão é text_end). -Controle a fragmentação suave de blocos com `agents.defaults.blockStreamingChunk` (padrão de -800–1200 caracteres; prefere quebras de parágrafo, depois novas linhas; frases por último). -Agregue chunks transmitidos com `agents.defaults.blockStreamingCoalesce` para reduzir +Controle a divisão suave de blocos com `agents.defaults.blockStreamingChunk` (padrão de +800 a 1200 caracteres; prefere quebras de parágrafo, depois novas linhas; frases por último). +Agrupe chunks transmitidos com `agents.defaults.blockStreamingCoalesce` para reduzir spam de linha única (mesclagem baseada em inatividade antes do envio). Canais que não sejam Telegram exigem -`*.blockStreaming: true` explícito para habilitar respostas em blocos. -Resumos verbosos de ferramentas são emitidos no início da ferramenta (sem debounce); a Control UI -transmite a saída da ferramenta via eventos do agente quando disponível. -Mais detalhes: [Streaming + fragmentação](/pt-BR/concepts/streaming). +`*.blockStreaming: true` explícito para habilitar respostas em bloco. +Resumos detalhados de ferramentas são emitidos no início da ferramenta (sem debounce); a UI de Controle +transmite a saída da ferramenta por eventos do agente quando disponível. +Mais detalhes: [Streaming + divisão em chunks](/pt-BR/concepts/streaming). ## Referências de modelo @@ -121,10 +121,10 @@ Referências de modelo na configuração (por exemplo, `agents.defaults.model` e - Use `provider/model` ao configurar modelos. - Se o ID do modelo em si contiver `/` (estilo OpenRouter), inclua o prefixo do provedor (exemplo: `openrouter/moonshotai/kimi-k2`). -- Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única - de provedor configurado para esse ID exato de modelo e só então recorre +- Se você omitir o provedor, OpenClaw tenta primeiro um alias, depois uma correspondência única + de provedor configurado para esse ID de modelo exato e só então recorre ao provedor padrão configurado. Se esse provedor não expuser mais o - modelo padrão configurado, o OpenClaw recorre ao primeiro + modelo padrão configurado, OpenClaw recorre ao primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido. ## Configuração (mínima) @@ -136,10 +136,10 @@ No mínimo, defina: --- -_A seguir: [Conversas em grupo](/pt-BR/channels/group-messages)_ 🦞 +_Próximo: [Conversas em grupo](/pt-BR/channels/group-messages)_ 🦞 ## Relacionados -- [Espaço de trabalho do agente](/pt-BR/concepts/agent-workspace) +- [Workspace do agente](/pt-BR/concepts/agent-workspace) - [Roteamento multiagente](/pt-BR/concepts/multi-agent) - [Gerenciamento de sessões](/pt-BR/concepts/session) diff --git a/docs/pt-BR/concepts/mantis.md b/docs/pt-BR/concepts/mantis.md index 94bf25c51..6be10de2a 100644 --- a/docs/pt-BR/concepts/mantis.md +++ b/docs/pt-BR/concepts/mantis.md @@ -1,77 +1,77 @@ --- read_when: - - Criando ou executando controle de qualidade visual ao vivo para erros do OpenClaw - - Adicionando verificação antes e depois para uma pull request + - Criar ou executar QA visual ao vivo para bugs do OpenClaw + - Adição de verificação antes e depois para uma solicitação de pull - Adicionando cenários de transporte em tempo real do Discord, Slack, WhatsApp ou outros - - Depuração de execuções de QA que precisam de capturas de tela, automação de navegador ou acesso VNC -summary: Mantis é o sistema visual de verificação de ponta a ponta para reproduzir falhas do OpenClaw em transportes ativos, capturar evidências de antes e depois e anexar artefatos a PRs. + - Depuração de execuções de garantia de qualidade que precisam de capturas de tela, automação de navegador ou acesso VNC +summary: Mantis é o sistema de verificação visual de ponta a ponta para reproduzir bugs do OpenClaw em transportes ativos, capturar evidências antes e depois e anexar artefatos a solicitações de integração. title: Louva-a-deus x-i18n: - generated_at: "2026-05-03T21:30:21Z" + generated_at: "2026-05-04T02:22:55Z" model: gpt-5.5 provider: openai - source_hash: 3463882b01a7941f6d758c509d6cd70e099aa8352053347fa9c37a80e5b256ce + source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d source_path: concepts/mantis.md workflow: 16 --- -Mantis é o sistema de verificação de ponta a ponta do OpenClaw para bugs que precisam de um -runtime real, um transporte real e prova visível. Ele executa um cenário contra uma ref ruim -conhecida, captura evidências, executa o mesmo cenário contra uma ref candidata e +Mantis é o sistema de verificação ponta a ponta do OpenClaw para erros que precisam de um +ambiente de execução real, um transporte real e prova visível. Ele executa um cenário contra uma ref +sabidamente ruim, captura evidências, executa o mesmo cenário contra uma ref candidata e publica a comparação como artefatos que um mantenedor pode inspecionar a partir de um PR ou de um comando local. -Mantis começa com Discord porque o Discord nos oferece uma primeira faixa de alto valor: -autenticação real de bot, canais de guilda reais, reações, threads, comandos nativos e uma -interface de navegador em que humanos podem confirmar visualmente o que o transporte mostrou. +Mantis começa com Discord porque Discord nos dá uma primeira linha de alto valor: +autenticação real de bot, canais reais de guilda, reações, threads, comandos nativos e uma +UI de navegador em que humanos podem confirmar visualmente o que o transporte mostrou. ## Objetivos -- Reproduzir um bug de uma issue ou PR do GitHub com o mesmo formato de transporte que os usuários +- Reproduzir um erro de uma issue ou PR do GitHub com o mesmo formato de transporte que os usuários veem. -- Capturar um artefato **antes** na ref de baseline antes de aplicar a correção. +- Capturar um artefato **antes** na ref de linha de base antes de aplicar a correção. - Capturar um artefato **depois** na ref candidata depois de aplicar a correção. - Usar um oráculo determinístico sempre que possível, como uma leitura de reação via REST do Discord - ou uma verificação de transcrição de canal. -- Capturar screenshots quando o bug tiver uma superfície de UI visível. + ou verificação de transcrição do canal. +- Capturar capturas de tela quando o erro tiver uma superfície de UI visível. - Executar localmente a partir de uma CLI controlada por agente e remotamente a partir do GitHub. -- Preservar estado de máquina suficiente para resgate por VNC quando login, automação de navegador ou +- Preservar estado de máquina suficiente para resgate via VNC quando login, automação de navegador ou autenticação de provedor travar. - Publicar status conciso em um canal Discord de operadores quando a execução estiver bloqueada, - precisar de ajuda manual por VNC ou terminar. + precisar de ajuda manual via VNC ou terminar. -## Não objetivos +## Não Objetivos -- Mantis não substitui testes unitários. Uma execução do Mantis normalmente deve se tornar - um teste de regressão menor depois que a correção for compreendida. -- Mantis não é o gate normal de CI rápido. Ele é mais lento, usa credenciais reais e - é reservado para bugs em que o ambiente real importa. +- Mantis não substitui testes unitários. Uma execução do Mantis normalmente deve virar + um teste de regressão menor depois que a correção for entendida. +- Mantis não é o gate normal de CI rápida. Ele é mais lento, usa credenciais reais e + é reservado para erros em que o ambiente real importa. - Mantis não deve exigir um humano para operação normal. VNC manual é um caminho de resgate, não o caminho feliz. -- Mantis não armazena segredos brutos em artefatos, logs, screenshots, relatórios em Markdown +- Mantis não armazena segredos brutos em artefatos, logs, capturas de tela, relatórios Markdown ou comentários de PR. ## Propriedade Mantis vive na pilha de QA do OpenClaw. -- OpenClaw possui o runtime de cenários, adaptadores de transporte, esquema de evidências e +- OpenClaw é responsável pelo runtime de cenário, adaptadores de transporte, esquema de evidências e CLI local em `pnpm openclaw qa mantis`. -- QA Lab possui as partes do harness de transporte real, auxiliares de captura de navegador e +- QA Lab é responsável pelas partes do harness de transporte real, auxiliares de captura de navegador e gravadores de artefatos. -- Crabbox possui as máquinas Linux aquecidas quando uma VM remota é necessária. -- GitHub Actions possui o ponto de entrada do workflow remoto e a retenção de artefatos. -- ClawSweeper possui o roteamento de comentários do GitHub: analisar comandos de mantenedores, - disparar o workflow e publicar o comentário final no PR. -- Agentes OpenClaw conduzem o Mantis por meio do Codex quando um cenário precisa de configuração agêntica, +- Crabbox é responsável por máquinas Linux aquecidas quando uma VM remota é necessária. +- GitHub Actions é responsável pelo ponto de entrada do workflow remoto e pela retenção de artefatos. +- ClawSweeper é responsável pelo roteamento de comentários do GitHub: analisar comandos de mantenedores, + despachar o workflow e publicar o comentário final no PR. +- Agentes OpenClaw conduzem Mantis por meio do Codex quando um cenário precisa de configuração agentica, depuração ou relatório de estado travado. Esse limite mantém o conhecimento de transporte no OpenClaw, o agendamento de máquinas no -Crabbox e a cola do fluxo de trabalho de mantenedores no ClawSweeper. +Crabbox e a cola do workflow de mantenedores no ClawSweeper. -## Formato do comando +## Formato Do Comando -O primeiro comando local verifica o bot do Discord, guilda, canal, envio de mensagem, +O primeiro comando local verifica o bot Discord, guilda, canal, envio de mensagem, envio de reação e caminho de artefato: ```bash @@ -90,34 +90,59 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -O executor cria worktrees destacadas de baseline e candidata sob o diretório de saída, +O executor cria worktrees destacadas de linha de base e candidata sob o diretório de saída, instala dependências, compila cada ref, executa o cenário com -`--allow-failures` e então escreve `baseline/`, `candidate/`, `comparison.json` -e `mantis-report.md`. Para o primeiro cenário do Discord, uma verificação bem-sucedida -significa que o status do baseline é `fail` e o status da candidata é `pass`. +`--allow-failures`, depois escreve `baseline/`, `candidate/`, `comparison.json`, +e `mantis-report.md`. Para o primeiro cenário Discord, uma verificação bem-sucedida +significa que o status da linha de base é `fail` e o status da candidata é `pass`. -O workflow de smoke do GitHub é `Mantis Discord Smoke`. O workflow de antes e depois do GitHub -para o primeiro cenário real é `Mantis Discord Status Reactions`. Ele -aceita: +O primeiro primitivo de VM/navegador é o smoke de desktop: -- `baseline_ref`: a ref esperada para reproduzir o comportamento apenas enfileirado. +```bash +pnpm openclaw qa mantis desktop-browser-smoke \ + --output-dir .artifacts/qa-e2e/mantis/desktop-browser +``` + +Ele aluga ou reutiliza uma máquina desktop Crabbox, inicia um navegador visível dentro da +sessão VNC, captura o desktop, puxa artefatos de volta para o diretório de saída local +e escreve o comando de reconexão no relatório. O comando usa por padrão o provedor +Hetzner porque ele é o primeiro provedor com cobertura funcional de desktop/VNC +na linha Mantis. Sobrescreva com `--provider`, `--crabbox-bin` ou +`OPENCLAW_MANTIS_CRABBOX_PROVIDER` ao executar contra outra frota Crabbox. + +Flags úteis do smoke de desktop: + +- `--lease-id ` ou `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` reutiliza um desktop aquecido. +- `--browser-url ` altera a página aberta no navegador visível. +- `--html-file ` renderiza um artefato HTML local do repo no navegador visível. Mantis usa isso para capturar a linha do tempo gerada de reações de status do Discord por meio de um desktop Crabbox real. +- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` mantém um lease recém-criado e aprovado aberto para inspeção via VNC. Execuções com falha mantêm o lease por padrão quando um foi criado, para que um operador possa se reconectar. +- `--class`, `--idle-timeout` e `--ttl` ajustam o tamanho da máquina e a duração do lease. + +O workflow de smoke do GitHub é `Mantis Discord Smoke`. O workflow GitHub de antes e depois +para o primeiro cenário real é `Mantis Discord Status Reactions`. Ele aceita: + +- `baseline_ref`: a ref esperada para reproduzir comportamento somente em fila. - `candidate_ref`: a ref esperada para mostrar `queued -> thinking -> done`. -Ele faz checkout da ref do harness do workflow, compila worktrees separadas de baseline e candidata, +Ele faz checkout da ref do harness do workflow, compila worktrees separadas de linha de base e candidata, executa `discord-status-reactions-tool-only` contra cada worktree e envia `baseline/`, `candidate/`, `comparison.json` e `mantis-report.md` como -artefatos do Actions. +artefatos do Actions. Ele também renderiza o HTML de linha do tempo de cada linha em um navegador +desktop Crabbox e publica essas capturas de tela VNC ao lado dos PNGs determinísticos +de linha do tempo no comentário do PR. O workflow compila a CLI Crabbox a partir de +`openclaw/crabbox` main para poder usar as flags atuais de lease de desktop/navegador +antes que a próxima versão binária do Crabbox seja lançada. -Você também pode disparar a execução de status-reactions diretamente de um comentário de PR: +Você também pode acionar a execução de reações de status diretamente a partir de um comentário de PR: ```text @Mantis discord status reactions ``` -O gatilho de comentário é intencionalmente estreito. Ele só executa em comentários de pull request -de usuários com acesso write, maintain ou admin, e só reconhece -solicitações de reação de status do Discord. Por padrão, ele usa a ref baseline ruim conhecida -e o SHA atual do head do PR como candidata. Mantenedores podem substituir qualquer uma das +O gatilho de comentário é intencionalmente estreito. Ele só é executado em comentários de pull request +de usuários com acesso de escrita, manutenção ou administração, e só reconhece +solicitações de reações de status do Discord. Por padrão, ele usa a ref de linha de base +sabidamente ruim e o SHA atual do head do PR como candidato. Mantenedores podem sobrescrever qualquer uma das refs: ```text @@ -135,43 +160,44 @@ O primeiro comando é explícito e focado no cenário. O segundo pode futurament ou issue para cenários Mantis recomendados a partir de labels, arquivos alterados e achados de revisão do ClawSweeper. -## Ciclo de vida da execução +## Ciclo De Vida Da Execução -1. Adquirir credenciais. +1. Obter credenciais. 2. Alocar ou reutilizar uma VM. -3. Preparar um checkout limpo para a ref de baseline. -4. Instalar dependências e compilar apenas o que o cenário precisa. -5. Iniciar um Gateway OpenClaw filho com um diretório de estado isolado. -6. Configurar o transporte real, provedor, modelo e perfil de navegador. -7. Executar o cenário e capturar evidências de baseline. -8. Parar o Gateway e preservar logs. -9. Preparar a ref candidata na mesma VM. -10. Executar o mesmo cenário e capturar evidências da candidata. -11. Comparar os resultados do oráculo e as evidências visuais. -12. Escrever Markdown, JSON, logs, screenshots e artefatos de rastreamento opcionais. -13. Enviar artefatos do GitHub Actions. -14. Publicar uma mensagem concisa de status no PR ou Discord. +3. Preparar o perfil de desktop/navegador quando o cenário precisar de evidência de UI. +4. Preparar um checkout limpo para a ref de linha de base. +5. Instalar dependências e compilar apenas o que o cenário precisa. +6. Iniciar um Gateway OpenClaw filho com um diretório de estado isolado. +7. Configurar o transporte real, provedor, modelo e perfil de navegador. +8. Executar o cenário e capturar evidências da linha de base. +9. Parar o gateway e preservar logs. +10. Preparar a ref candidata na mesma VM. +11. Executar o mesmo cenário e capturar evidências da candidata. +12. Comparar os resultados do oráculo e as evidências visuais. +13. Escrever Markdown, JSON, logs, capturas de tela e artefatos opcionais de rastreamento. +14. Enviar artefatos do GitHub Actions. +15. Publicar uma mensagem concisa de status no PR ou no Discord. -O cenário deve ser capaz de falhar de duas maneiras diferentes: +O cenário deve poder falhar de duas formas diferentes: -- **Bug reproduzido**: o baseline falhou da maneira esperada. +- **Erro reproduzido**: a linha de base falhou da forma esperada. - **Falha do harness**: configuração de ambiente, credenciais, API do Discord, navegador ou - provedor falhou antes que o oráculo do bug fosse significativo. + provedor falhou antes que o oráculo do erro fosse significativo. O relatório final deve separar esses casos para que mantenedores não confundam um ambiente instável com comportamento do produto. -## MVP do Discord +## MVP Do Discord O primeiro cenário deve mirar reações de status do Discord em canais de guilda em que -o modo de entrega de resposta de origem é `message_tool_only`. +o modo de entrega da resposta de origem é `message_tool_only`. Por que ele é uma boa semente para o Mantis: - Ele é visível no Discord como reações na mensagem disparadora. - Ele tem um oráculo REST forte por meio do estado de reação da mensagem do Discord. -- Ele exercita um Gateway OpenClaw real, autenticação de bot do Discord, despacho de mensagem, - modo de entrega de resposta de origem, estado de reação de status e ciclo de vida de turno do modelo. +- Ele exercita um Gateway OpenClaw real, autenticação de bot Discord, despacho de mensagem, + modo de entrega da resposta de origem, estado de reação de status e ciclo de vida de turno do modelo. - Ele é estreito o suficiente para manter a primeira implementação honesta. Formato esperado do cenário: @@ -205,12 +231,12 @@ evidence: screenshotMessageRow: true ``` -As evidências de baseline devem mostrar a reação de reconhecimento enfileirada, mas nenhuma -transição de ciclo de vida no modo somente ferramenta. As evidências da candidata devem mostrar reações de status de ciclo de vida -rodando quando `messages.statusReactions.enabled` está explicitamente +As evidências da linha de base devem mostrar a reação de confirmação em fila, mas nenhuma +transição de ciclo de vida no modo somente ferramenta. As evidências da candidata devem mostrar reações de status +de ciclo de vida rodando quando `messages.statusReactions.enabled` está explicitamente true. -O primeiro recorte executável é o cenário de QA real do Discord com opt-in: +A primeira fatia executável é o cenário QA Discord real opt-in: ```bash pnpm openclaw qa discord \ @@ -224,32 +250,32 @@ pnpm openclaw qa discord \ Ele configura o SUT com tratamento de guilda sempre ativo, `visibleReplies: "message_tool"`, `ackReaction: "👀"` e reações de status explícitas. O oráculo -consulta a mensagem disparadora real do Discord e espera a sequência observada +sonda a mensagem disparadora real do Discord e espera a sequência observada `👀 -> 🤔 -> 👍`. Os artefatos incluem `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` e `discord-status-reactions-tool-only-timeline.png`. -## Componentes de QA existentes +## Peças De QA Existentes -Mantis deve se basear na pilha privada de QA existente em vez de começar do +Mantis deve se apoiar na pilha privada de QA existente em vez de começar do zero: -- `pnpm openclaw qa discord` já executa uma faixa real do Discord com bots driver e +- `pnpm openclaw qa discord` já executa uma linha Discord real com bots de driver e SUT. - O executor de transporte real já escreve relatórios e artefatos de mensagens observadas - em `.artifacts/qa-e2e/`. -- Concessões de credenciais do Convex já fornecem acesso exclusivo a credenciais compartilhadas de + sob `.artifacts/qa-e2e/`. +- Leases de credenciais Convex já fornecem acesso exclusivo a credenciais compartilhadas de transporte real. -- O serviço de controle de navegador já oferece suporte a screenshots, snapshots, +- O serviço de controle de navegador já oferece suporte a capturas de tela, snapshots, perfis gerenciados headless e perfis CDP remotos. - QA Lab já tem uma UI de depuração e barramento para testes no formato de transporte. A primeira implementação do Mantis pode ser um executor fino de antes/depois sobre essas peças, mais uma camada de evidência visual. -## Modelo de evidências +## Modelo De Evidências -Toda execução escreve um diretório de artefatos estável: +Toda execução escreve um diretório estável de artefatos: ```text .artifacts/qa-e2e/mantis// @@ -270,78 +296,78 @@ Toda execução escreve um diretório de artefatos estável: ``` `mantis-summary.json` deve ser a fonte da verdade legível por máquina. O -relatório em Markdown é para comentários de PR e revisão humana. +relatório Markdown é para comentários de PR e revisão humana. O resumo deve incluir: - refs e SHAs testados - transporte e id do cenário -- provedor da máquina e id da máquina ou id da concessão -- fonte de credenciais sem valores secretos -- resultado do baseline +- provedor da máquina e id da máquina ou id do lease +- fonte de credencial sem valores secretos +- resultado da linha de base - resultado da candidata -- se o bug foi reproduzido no baseline +- se o erro foi reproduzido na linha de base - se a candidata o corrigiu - caminhos dos artefatos -- problemas de configuração ou limpeza sanitizados +- problemas sanitizados de configuração ou limpeza -Screenshots são evidências, não segredos. Elas ainda precisam de disciplina de redação: +Capturas de tela são evidências, não segredos. Elas ainda precisam de disciplina de redação: nomes de canais privados, nomes de usuários ou conteúdo de mensagens podem aparecer. Para PRs públicos, prefira links de artefatos do GitHub Actions em vez de imagens inline até que a história de redação esteja mais forte. -## Navegador e VNC +## Navegador E VNC -A faixa de navegador tem dois modos: +A linha de navegador tem dois modos: - **Automação headless**: padrão para CI. Chrome roda com CDP habilitado, e Playwright ou o controle de navegador do OpenClaw captura screenshots. -- **Resgate por VNC**: habilitado na mesma VM quando login, MFA, anti-automação do Discord +- **Resgate via VNC**: habilitado na mesma VM quando login, MFA, anti-automação do Discord, ou depuração visual precisa de um humano. -O perfil de navegador observador do Discord deve ser persistente o suficiente para evitar -login a cada execução, mas isolado do estado pessoal do navegador. Um perfil +O perfil de navegador do observador do Discord deve ser persistente o suficiente para evitar +login a cada execução, mas isolado do estado do navegador pessoal. Um perfil pertence ao pool de máquinas do Mantis, não a um laptop de desenvolvedor. -Quando o Mantis trava, ele publica uma mensagem de status no Discord com: +Quando o Mantis fica preso, ele publica uma mensagem de status no Discord com: - id da execução - id do cenário - provedor da máquina - diretório de artefatos - instruções de conexão VNC ou noVNC, se disponíveis -- texto curto do bloqueador +- texto curto do bloqueio -A primeira implantação privada pode publicar essas mensagens no canal de operadores existente -e migrar depois para um canal dedicado do Mantis. +A primeira implantação privada pode publicar essas mensagens no canal de operadores +existente e migrar para um canal dedicado do Mantis mais tarde. ## Máquinas -Mantis deve preferir AWS por meio do Crabbox para a primeira implementação remota. -Crabbox nos oferece máquinas aquecidas, rastreamento de concessões, hidratação, logs, resultados e -limpeza. Se a capacidade da AWS for lenta demais ou indisponível, adicione um provedor Hetzner +O Mantis deve preferir AWS por meio do Crabbox na primeira implementação remota. +O Crabbox nos dá máquinas aquecidas, rastreamento de concessões, hidratação, logs, resultados e +limpeza. Se a capacidade da AWS estiver lenta demais ou indisponível, adicione um provedor Hetzner por trás da mesma interface de máquina. Requisitos mínimos da VM: -- Linux com uma instalação de Chrome ou Chromium capaz de desktop -- acesso CDP para automação de navegador +- Linux com instalação do Chrome ou Chromium com suporte a desktop +- acesso CDP para automação do navegador - VNC ou noVNC para resgate - Node 22 e pnpm - checkout do OpenClaw e cache de dependências -- cache do navegador Playwright Chromium quando Playwright for usado -- CPU e memória suficientes para um Gateway OpenClaw, um navegador e uma execução de modelo -- acesso de saída ao Discord, GitHub, provedores de modelo e broker de credenciais +- cache do navegador Chromium do Playwright quando o Playwright for usado +- CPU e memória suficientes para um OpenClaw Gateway, um navegador e uma execução de modelo +- acesso de saída ao Discord, GitHub, provedores de modelo e ao broker de credenciais A VM não deve manter segredos brutos de longa duração fora dos armazenamentos esperados de credenciais ou perfil de navegador. ## Segredos -Segredos vivem em segredos de organização ou repositório do GitHub para execuções remotas, e em -um arquivo de segredo local controlado pelo operador para execuções locais. +Segredos ficam em segredos de organização ou repositório do GitHub para execuções remotas, e em +um arquivo de segredos local controlado pelo operador para execuções locais. -Nomes de segredo recomendados: +Nomes de segredos recomendados: - `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` @@ -352,10 +378,17 @@ Nomes de segredo recomendados: - `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` para uploads públicos de artefatos no GitHub - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` +- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` +- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -No longo prazo, o pool de credenciais do Convex deve continuar sendo a fonte normal para credenciais de transporte ao vivo. Os segredos do GitHub inicializam o broker e as lanes de fallback. +No longo prazo, o pool de credenciais do Convex deve continuar sendo a fonte normal de credenciais +de transporte ao vivo. Segredos do GitHub inicializam o broker e as pistas de fallback. +O fluxo de trabalho de reações de status do Discord mapeia os segredos do Mantis Crabbox de volta para +as variáveis de ambiente `CRABBOX_COORDINATOR` e `CRABBOX_COORDINATOR_TOKEN` +que a CLI do Crabbox espera. Os nomes simples de segredos do GitHub `CRABBOX_*` continuam +aceitos como fallback de compatibilidade. -O runner do Mantis nunca deve imprimir: +O executor do Mantis nunca deve imprimir: - tokens de bot do Discord - chaves de API de provedores @@ -364,17 +397,30 @@ O runner do Mantis nunca deve imprimir: - senhas de VNC - payloads brutos de credenciais -Uploads públicos de artefatos também devem ocultar metadados de destino do Discord, como IDs de bot, guild, canal e mensagem. O fluxo de trabalho de smoke do GitHub habilita `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` por esse motivo. +Uploads públicos de artefatos também devem redigir metadados de destino do Discord, como ids de bot, +guild, canal e mensagem. O fluxo de trabalho smoke do GitHub habilita +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` por esse motivo. -Se um token for colado acidentalmente em uma issue, PR, chat ou log, faça a rotação dele depois que o novo segredo tiver sido armazenado. +Se um token for colado acidentalmente em uma issue, PR, chat ou log, faça a rotação dele +depois que o novo segredo tiver sido armazenado. -## Artefatos do GitHub e comentários de PR +## Artefatos do GitHub e comentários em PRs -Os fluxos de trabalho do Mantis devem enviar o pacote completo de evidências como um artefato de curta duração do Actions. Quando o fluxo de trabalho for executado para um relatório de bug ou PR de correção, ele também deve publicar as capturas de tela PNG redigidas no branch `qa-artifacts` e fazer upsert de um comentário nesse bug ou PR de correção com capturas de tela inline de antes/depois. Não publique a prova principal apenas em um PR genérico de automação de QA. Logs brutos, mensagens observadas e outras evidências volumosas permanecem no artefato do Actions. +Os fluxos de trabalho do Mantis devem fazer upload do pacote completo de evidências como um artefato de Actions +de curta duração. Quando o fluxo de trabalho for executado para um relatório de bug ou PR de correção, ele também deve +publicar as capturas de tela PNG redigidas no branch `qa-artifacts` e atualizar ou inserir um +comentário nesse bug ou PR de correção com capturas de tela antes/depois embutidas. Não publique +a prova principal apenas em um PR genérico de automação de QA. Logs brutos, mensagens observadas +e outras evidências volumosas ficam no artefato de Actions. -Fluxos de trabalho de produção devem publicar esses comentários com o GitHub App do Mantis, não com `github-actions[bot]`. Armazene o ID do app e a chave privada como segredos do GitHub Actions `MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY`. O fluxo de trabalho usa um marcador oculto como chave de upsert, atualiza esse comentário quando o token consegue editá-lo e cria um novo comentário de propriedade do Mantis quando um marcador antigo de propriedade do bot não pode ser editado. +Fluxos de trabalho de produção devem publicar esses comentários com o GitHub App do Mantis, não +com `github-actions[bot]`. Armazene o id do app e a chave privada como segredos +`MANTIS_GITHUB_APP_ID` e `MANTIS_GITHUB_APP_PRIVATE_KEY` do GitHub Actions. +O fluxo de trabalho usa um marcador oculto como chave de atualização/inserção, atualiza esse +comentário quando o token pode editá-lo e cria um novo comentário de propriedade do Mantis quando +um marcador mais antigo de propriedade do bot não pode ser editado. -O comentário do PR deve ser curto e visual: +O comentário no PR deve ser curto e visual: ```md Mantis Discord Status Reactions QA @@ -394,60 +440,73 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Quando a execução falhar porque o harness falhou, o comentário deve dizer isso em vez de insinuar que o candidato falhou. +Quando a execução falhar porque o harness falhou, o comentário deve dizer isso em vez +de sugerir que o candidato falhou. ## Notas de implantação privada -Uma implantação privada talvez já tenha uma aplicação Discord do Mantis. Reutilize essa aplicação em vez de criar outro app quando ela tiver as permissões de bot corretas e puder passar por rotação com segurança. +Uma implantação privada talvez já tenha uma aplicação Discord do Mantis. Reutilize essa +aplicação em vez de criar outro app quando ela tiver as permissões de bot corretas +e puder passar por rotação com segurança. -Configure o canal inicial de notificação do operador por meio de segredos ou da configuração de implantação. Ele pode apontar primeiro para um canal existente de mantenedores ou operações e depois mudar para um canal dedicado do Mantis quando existir um. +Defina o canal inicial de notificação de operadores por meio de segredos ou configuração de implantação. +Ele pode apontar primeiro para um canal existente de mantenedores ou operações +e depois migrar para um canal dedicado do Mantis quando um existir. -Não coloque IDs de guild, IDs de canal, tokens de bot, cookies de navegador ou senhas de VNC neste documento. Armazene-os em segredos do GitHub, no broker de credenciais ou no armazenamento local de segredos do operador. +Não coloque ids de guild, ids de canal, tokens de bot, cookies de navegador ou senhas de VNC +neste documento. Armazene-os em segredos do GitHub, no broker de credenciais ou no +armazenamento local de segredos do operador. -## Como adicionar um cenário +## Adicionando um cenário Um cenário do Mantis deve declarar: -- ID e título +- id e título - transporte -- credenciais necessárias -- política de ref da baseline -- política de ref do candidato +- credenciais obrigatórias +- política de ref de baseline +- política de ref de candidato - patch de configuração do OpenClaw -- etapas de configuração +- etapas de setup - estímulo -- oráculo esperado da baseline -- oráculo esperado do candidato +- oráculo esperado de baseline +- oráculo esperado de candidato - alvos de captura visual - orçamento de timeout - etapas de limpeza -Os cenários devem preferir oráculos pequenos e tipados: +Cenários devem preferir oráculos pequenos e tipados: - estado de reação do Discord para bugs de reação -- referências de mensagem do Discord para bugs de threading -- ts de thread do Slack e estado da API de reação para bugs do Slack -- IDs de mensagem e cabeçalhos de email para bugs de email +- referências de mensagens do Discord para bugs de threading +- ts da thread do Slack e estado da API de reação para bugs do Slack +- ids e cabeçalhos de mensagens de email para bugs de email - capturas de tela do navegador quando a UI for o único observável confiável -Verificações por visão devem ser aditivas. Se uma API de plataforma puder provar o bug, use a API como o oráculo de aprovação/falha e mantenha capturas de tela para confiança humana. +Verificações por visão devem ser aditivas. Se uma API da plataforma puder provar o bug, use a +API como oráculo de aprovação/falha e mantenha as capturas de tela para confiança humana. ## Expansão de provedores -Depois do Discord, o mesmo runner pode adicionar: +Depois do Discord, o mesmo executor pode adicionar: - Slack: reações, threads, menções ao app, modais, uploads de arquivos. -- Email: autenticação do Gmail e threading de mensagens usando `gog` quando conectores não forem suficientes. +- Email: autenticação do Gmail e threading de mensagens usando `gog` onde conectores não forem + suficientes. - WhatsApp: login por QR, reidentificação, entrega de mensagens, mídia, reações. -- Telegram: gate de menções em grupo, comandos, reações quando disponíveis. -- Matrix: salas criptografadas, relações de thread ou resposta, retomada após reinicialização. +- Telegram: bloqueio por menção em grupo, comandos, reações quando disponíveis. +- Matrix: salas criptografadas, relações de thread ou resposta, retomada após reinício. -Cada transporte deve ter um cenário de smoke barato e um ou mais cenários de classe de bug. Cenários visuais caros devem permanecer opt-in. +Cada transporte deve ter um cenário smoke barato e um ou mais cenários de classe de bug. +Cenários visuais caros devem permanecer opt-in. ## Perguntas em aberto -- Qual bot do Discord deve ser o driver e qual deve ser o SUT quando o bot existente do Mantis for reutilizado? -- O login do navegador observador deve usar uma conta humana do Discord, uma conta de teste ou apenas evidência REST legível por bot na primeira fase? +- Qual bot do Discord deve ser o driver, e qual deve ser o SUT, quando o + bot existente do Mantis for reutilizado? +- O login do navegador observador deve usar uma conta humana do Discord, uma conta de teste + ou apenas evidência REST legível por bot para a primeira fase? - Por quanto tempo o GitHub deve reter artefatos do Mantis para PRs? -- Quando o ClawSweeper deve recomendar automaticamente o Mantis em vez de esperar por um comando de mantenedor? -- As capturas de tela devem ser redigidas ou recortadas antes do upload para PRs públicos? +- Quando o ClawSweeper deve recomendar automaticamente o Mantis em vez de esperar por um + comando de mantenedor? +- As capturas de tela devem ser redigidas ou cortadas antes do upload para PRs públicos? diff --git a/docs/pt-BR/concepts/progress-drafts.md b/docs/pt-BR/concepts/progress-drafts.md index c7d3e3bac..25ce758a9 100644 --- a/docs/pt-BR/concepts/progress-drafts.md +++ b/docs/pt-BR/concepts/progress-drafts.md @@ -1,37 +1,32 @@ --- read_when: - - Configurando atualizações visíveis de progresso para turnos de chat de longa duração - - Escolhendo entre os modos de streaming parcial, em bloco e de progresso + - Configurando atualizações de progresso visíveis para turnos de chat de longa duração + - Escolhendo entre os modos de transmissão parcial, em bloco e de progresso - Explicando como o OpenClaw atualiza uma mensagem de canal enquanto o trabalho está em andamento - - Solução de problemas de rascunhos de progresso, mensagens de progresso independentes ou alternativa de finalização + - Solução de problemas de rascunhos de progresso, mensagens de progresso independentes ou mecanismo de contingência de finalização summary: 'Rascunhos de progresso: uma mensagem visível de trabalho em andamento que é atualizada enquanto um agente é executado' title: Rascunhos de progresso x-i18n: - generated_at: "2026-05-03T21:30:40Z" + generated_at: "2026-05-04T02:23:06Z" model: gpt-5.5 provider: openai - source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c + source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe source_path: concepts/progress-drafts.md workflow: 16 --- -Rascunhos de progresso fazem turnos longos de agentes parecerem vivos no chat sem transformar -a conversa em uma pilha de respostas temporárias de status. +Rascunhos de progresso fazem turnos de agentes de longa duração parecerem ativos no chat sem transformar a conversa em uma pilha de respostas temporárias de status. -Quando os rascunhos de progresso estão habilitados, o OpenClaw cria uma mensagem visível -de trabalho em andamento, atualiza-a enquanto o agente lê, planeja, chama ferramentas ou -aguarda aprovação, e então transforma esse rascunho na resposta final quando o canal pode -fazer isso com segurança. +Quando os rascunhos de progresso estão habilitados, o OpenClaw cria uma única mensagem visível de trabalho em andamento somente depois que o turno comprova que está fazendo trabalho real, atualiza essa mensagem enquanto o agente lê, planeja, chama ferramentas ou aguarda aprovação e, então, transforma esse rascunho na resposta final quando o canal consegue fazer isso com segurança. ```text -Shelling -- reading recent channel context -- checking matching issues -- preparing reply +Shelling... +📖 Read: from docs/concepts/progress-drafts.md +🔎 Web Search: for "discord edit message" +🛠️ Exec: run tests ``` -Use rascunhos de progresso quando você quiser uma única mensagem de status organizada durante trabalhos -com muitas ferramentas e a resposta final quando o turno terminar. +Use rascunhos de progresso quando você quiser uma única mensagem de status organizada durante trabalhos com muitas ferramentas e a resposta final quando o turno terminar. ## Início Rápido @@ -49,72 +44,64 @@ Habilite rascunhos de progresso por canal com `streaming.mode: "progress"`: } ``` -Isso geralmente é suficiente. O OpenClaw escolherá um rótulo automático de uma palavra, adicionará -linhas compactas de progresso enquanto trabalho útil acontece e suprimirá conversas de progresso -autônomas duplicadas para esse turno. +Isso geralmente é suficiente. O OpenClaw escolherá um rótulo automático de uma palavra, aguardará até que o trabalho dure pelo menos cinco segundos ou emita um segundo evento de trabalho, adicionará linhas compactas de progresso enquanto trabalho útil acontece e suprimirá mensagens independentes duplicadas de progresso nesse turno. ## O Que os Usuários Veem Um rascunho de progresso tem duas partes: -| Parte | Finalidade | -| ------------------ | ---------------------------------------------------------------- | -| Rótulo | Um título curto como `Thinking` ou `Shelling`. | -| Linhas de progresso | Atualizações compactas da execução, como chamadas de ferramentas, etapas de tarefa ou aprovações. | +| Parte | Finalidade | +| ------------------- | ----------------------------------------------------------------------------- | +| Rótulo | Um título curto, como `Thinking...` ou `Shelling...`. | +| Linhas de progresso | Atualizações compactas de execução usando os mesmos rótulos e ícones da saída detalhada. | -O rótulo aparece imediatamente quando o agente começa a responder. Linhas de progresso são -adicionadas somente quando o agente emite atualizações úteis de trabalho. A resposta final substitui -o rascunho quando possível; caso contrário, o OpenClaw envia a resposta final normalmente e -limpa ou para de atualizar o rascunho de acordo com o transporte do canal. +O rótulo aparece depois que o agente inicia trabalho significativo e continua ocupado por cinco segundos ou emite um segundo evento de trabalho. Respostas somente em texto simples não mostram um rascunho de progresso. Linhas de progresso são adicionadas somente quando o agente emite atualizações úteis de trabalho, por exemplo `🛠️ Exec`, `🔎 Web Search` ou `✍️ Write: to /tmp/file`. Por padrão, elas usam o mesmo modo de explicação compacto de `/verbose`; defina `agents.defaults.toolProgressDetail: "raw"` ao depurar e também quiser comandos/detalhes brutos anexados. +A resposta final substitui o rascunho quando possível; caso contrário, o OpenClaw envia a resposta final normalmente e limpa ou para de atualizar o rascunho de acordo com o transporte do canal. ## Escolher Um Modo `channels..streaming.mode` controla o comportamento visível de andamento: -| Modo | Melhor para | O que aparece no chat | -| ---------- | -------------------------------- | ------------------------------------------------- | -| `off` | Canais silenciosos | Somente a resposta final. | -| `partial` | Ver o texto da resposta aparecer | Um rascunho editado com o texto mais recente da resposta. | +| Modo | Melhor para | O que aparece no chat | +| ---------- | ----------------------------------- | --------------------------------------------------- | +| `off` | Canais silenciosos | Somente a resposta final. | +| `partial` | Ver o texto da resposta aparecer | Um rascunho editado com o texto mais recente da resposta. | | `block` | Trechos maiores de prévia da resposta | Uma prévia atualizada ou anexada em trechos maiores. | -| `progress` | Turnos com muitas ferramentas ou de longa duração | Um rascunho de status, depois a resposta final. | +| `progress` | Turnos com muitas ferramentas ou longa duração | Um rascunho de status e, depois, a resposta final. | -Escolha `progress` quando os usuários se importam mais com "o que está acontecendo" do que em assistir -ao texto da resposta ser transmitido token por token. +Escolha `progress` quando os usuários se importam mais com "o que está acontecendo" do que com ver o texto da resposta ser transmitido token por token. Escolha `partial` quando a própria resposta é o sinal de progresso. -Escolha `block` quando você quiser atualizações de prévia em rascunho em trechos de texto maiores. No -Discord e Telegram, `streaming.mode: "block"` ainda é transmissão de prévia, não -entrega normal em blocos. Use `streaming.block.enabled` ou o legado -`blockStreaming` quando quiser respostas normais em blocos. +Escolha `block` quando você quiser atualizações de prévia em rascunho em trechos maiores de texto. No Discord e no Telegram, `streaming.mode: "block"` ainda é streaming de prévia, não entrega normal em blocos. Use `streaming.block.enabled` ou o legado `blockStreaming` quando quiser respostas normais em bloco. ## Configurar Rótulos Rótulos de progresso ficam em `channels..streaming.progress`. -O rótulo padrão é `auto`, que escolhe do conjunto integrado de rótulos de uma palavra do OpenClaw: +O rótulo padrão é `auto`, que escolhe a partir do conjunto integrado do OpenClaw de rótulos de uma palavra com reticências: ```text -Thinking -Shelling -Scuttling -Clawing -Pinching -Molting -Bubbling -Tiding -Reefing -Cracking -Sifting -Brining -Nautiling -Krilling -Barnacling -Lobstering -Tidepooling -Pearling -Snapping -Surfacing +Thinking... +Shelling... +Scuttling... +Clawing... +Pinching... +Molting... +Bubbling... +Tiding... +Reefing... +Cracking... +Sifting... +Brining... +Nautiling... +Krilling... +Barnacling... +Lobstering... +Tidepooling... +Pearling... +Snapping... +Surfacing... ``` Use um rótulo fixo: @@ -171,9 +158,28 @@ Oculte o rótulo e mostre somente as linhas de progresso: ## Controlar Linhas de Progresso -Linhas de progresso são habilitadas por padrão no modo de progresso. Elas vêm de eventos reais de execução: -inícios de ferramentas, atualizações de itens, planos de tarefa, aprovações, saída de comandos, resumos -de patches e atividades semelhantes do agente. +Linhas de progresso são habilitadas por padrão no modo de progresso. Elas vêm de eventos reais de execução: inícios de ferramentas, atualizações de itens, planos de tarefas, aprovações, saída de comandos, resumos de patches e atividades semelhantes do agente. + +O OpenClaw usa o mesmo formatador para rascunhos de progresso e `/verbose`: + +```json5 +{ + agents: { + defaults: { + toolProgressDetail: "explain", // explain | raw + }, + }, +} +``` + +`"explain"` é o padrão e mantém os rascunhos estáveis com rótulos concisos como `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` anexa o comando/detalhe subjacente quando disponível, o que é útil durante a depuração, mas deixa o chat mais ruidoso. + +Por exemplo, o mesmo comando aparece de forma diferente dependendo do modo de detalhe: + +| Modo | Linha de progresso | +| --------- | -------------------------------------------------------------------- | +| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` | +| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` | Limite quantas linhas permanecem visíveis: @@ -209,78 +215,58 @@ Mantenha o único rascunho de progresso, mas oculte linhas de ferramentas e tare } ``` -Com `toolProgress: false`, o OpenClaw ainda suprime as mensagens autônomas mais antigas -de progresso de ferramentas para esse turno. O canal permanece visualmente silencioso até a -resposta final, exceto pelo rótulo se algum estiver configurado. +Com `toolProgress: false`, o OpenClaw ainda suprime as mensagens independentes antigas de progresso de ferramentas nesse turno. O canal permanece visualmente silencioso até a resposta final, exceto pelo rótulo se um estiver configurado. ## Comportamento do Canal Cada canal usa o transporte mais limpo compatível: -| Canal | Transporte de progresso | Observações | -| --------------- | ----------------------------------- | --------------------------------------------------------------------- | -| Discord | Envia uma mensagem e depois a edita. | O texto final é editado no local quando cabe em uma mensagem de prévia segura. | -| Matrix | Envia um evento e depois o edita. | A configuração de transmissão no nível da conta controla rascunhos no nível da conta. | -| Microsoft Teams | Stream nativo do Teams em chats pessoais. | `streaming.mode: "block"` é mapeado para entrega em blocos do Teams. | -| Slack | Stream nativo ou publicação de rascunho editável. | A disponibilidade de thread afeta se a transmissão nativa pode ser usada. | -| Telegram | Envia uma mensagem e depois a edita. | Rascunhos visíveis mais antigos podem ser substituídos para que os carimbos de data/hora finais continuem úteis. | -| Mattermost | Publicação de rascunho editável. | A atividade de ferramentas é incorporada à mesma publicação em estilo de rascunho. | +| Canal | Transporte de progresso | Observações | +| --------------- | --------------------------------------- | --------------------------------------------------------------------- | +| Discord | Envia uma mensagem e depois a edita. | O texto final é editado no lugar quando cabe em uma mensagem segura de prévia. | +| Matrix | Envia um evento e depois o edita. | A configuração de streaming em nível de conta controla rascunhos em nível de conta. | +| Microsoft Teams | Stream nativo do Teams em chats pessoais. | `streaming.mode: "block"` mapeia para entrega em bloco do Teams. | +| Slack | Stream nativo ou publicação de rascunho editável. | A disponibilidade de thread afeta se o streaming nativo pode ser usado. | +| Telegram | Envia uma mensagem e depois a edita. | Rascunhos visíveis mais antigos podem ser substituídos para manter carimbos de data/hora finais úteis. | +| Mattermost | Publicação de rascunho editável. | A atividade de ferramentas é integrada à mesma publicação em estilo de rascunho. | -Canais sem suporte seguro a edição geralmente recorrem a indicadores de digitação ou -entrega somente final. +Canais sem suporte seguro a edição geralmente recorrem a indicadores de digitação ou entrega somente final. ## Finalização Quando a resposta final está pronta, o OpenClaw tenta manter o chat limpo: -- Se o rascunho puder se tornar a resposta final com segurança, o OpenClaw o edita no local. -- Se o canal usa transmissão nativa de progresso, o OpenClaw finaliza esse stream - quando o transporte nativo aceita o texto final. -- Se a resposta final tiver mídia, um prompt de aprovação, um destino explícito de resposta, - muitos trechos ou uma edição/envio com falha, o OpenClaw envia a resposta final pelo - caminho normal de entrega do canal. +- Se o rascunho puder se tornar a resposta final com segurança, o OpenClaw o edita no lugar. +- Se o canal usa streaming de progresso nativo, o OpenClaw finaliza esse stream quando o transporte nativo aceita o texto final. +- Se a resposta final tiver mídia, um prompt de aprovação, um alvo de resposta explícito, blocos demais ou uma edição/envio com falha, o OpenClaw envia a resposta final pelo caminho normal de entrega do canal. -O caminho alternativo é intencional. É melhor enviar uma nova resposta final do que -perder texto, direcionar uma resposta para a thread errada ou sobrescrever um rascunho com uma carga que o canal -não consegue representar com segurança. +O caminho de fallback é intencional. É melhor enviar uma nova resposta final do que perder texto, encadear uma resposta na thread errada ou sobrescrever um rascunho com um payload que o canal não consegue representar com segurança. ## Solução de Problemas -**Vejo apenas a resposta final.** +**Vejo somente a resposta final.** -Verifique se `channels..streaming.mode` está definido como `progress` para a -conta ou canal que tratou a mensagem. Alguns caminhos de grupo ou resposta citada podem -desabilitar prévias de rascunho para um turno quando o canal não consegue editar com segurança a -mensagem correta. +Verifique se `channels..streaming.mode` está definido como `progress` para a conta ou o canal que processou a mensagem. Alguns caminhos de grupo ou resposta com citação podem desabilitar prévias de rascunho para um turno quando o canal não consegue editar a mensagem certa com segurança. **Vejo o rótulo, mas nenhuma linha de ferramenta.** -Verifique `streaming.progress.toolProgress`. Se for `false`, o OpenClaw mantém o -comportamento de rascunho único, mas oculta linhas de progresso de ferramentas e tarefas. +Verifique `streaming.progress.toolProgress`. Se for `false`, o OpenClaw mantém o comportamento de rascunho único, mas oculta linhas de progresso de ferramentas e tarefas. **Vejo uma nova mensagem final em vez de um rascunho editado.** -Isso é um fallback de segurança. Pode acontecer com respostas com mídia, respostas longas, -destinos explícitos de resposta, rascunhos antigos do Telegram, destinos de thread ausentes no Slack, -mensagens de prévia excluídas ou falha na finalização de stream nativo. +Isso é um fallback de segurança. Pode acontecer para respostas com mídia, respostas longas, alvos de resposta explícitos, rascunhos antigos do Telegram, alvos de thread ausentes no Slack, mensagens de prévia excluídas ou falha na finalização de stream nativo. -**Ainda vejo mensagens autônomas de progresso.** +**Ainda vejo mensagens independentes de progresso.** -O modo de progresso suprime mensagens padrão autônomas de progresso de ferramentas quando um rascunho -está ativo. Se mensagens autônomas ainda aparecerem, verifique se o turno está realmente -usando o modo de progresso e não `streaming.mode: "off"` ou um caminho de canal que -não consegue criar um rascunho para essa mensagem. +O modo de progresso suprime mensagens padrão independentes de progresso de ferramentas quando um rascunho está ativo. Se mensagens independentes ainda aparecerem, verifique se o turno está realmente usando o modo de progresso e não `streaming.mode: "off"` ou um caminho de canal que não consegue criar um rascunho para essa mensagem. -**O Teams se comporta de forma diferente do Discord ou Telegram.** +**O Teams se comporta de forma diferente do Discord ou do Telegram.** -O Microsoft Teams usa um stream nativo em chats pessoais em vez do transporte genérico -de prévia por envio e edição. O Teams também trata `streaming.mode: "block"` como -entrega em blocos do Teams porque ele não tem o mesmo modo de bloco de prévia em rascunho -usado pelo Discord e Telegram. +O Microsoft Teams usa um stream nativo em chats pessoais em vez do transporte genérico de prévia por envio e edição. O Teams também trata `streaming.mode: "block"` como entrega em bloco do Teams porque não tem o mesmo modo de bloco de prévia em rascunho usado pelo Discord e pelo Telegram. -## Relacionados +## Relacionado -- [Transmissão e divisão em trechos](/pt-BR/concepts/streaming) +- [Streaming e divisão em blocos](/pt-BR/concepts/streaming) - [Mensagens](/pt-BR/concepts/messages) - [Configuração de canais](/pt-BR/gateway/config-channels) - [Discord](/pt-BR/channels/discord) diff --git a/docs/pt-BR/concepts/queue-steering.md b/docs/pt-BR/concepts/queue-steering.md index 13bc80cea..4cbf8b12c 100644 --- a/docs/pt-BR/concepts/queue-steering.md +++ b/docs/pt-BR/concepts/queue-steering.md @@ -1,97 +1,101 @@ --- read_when: - Explicando como o direcionamento se comporta enquanto um agente usa ferramentas - - Alterando o comportamento da fila de execuções ativas ou a integração de direcionamento em tempo de execução + - Alterar o comportamento da fila de execução ativa ou a integração de direcionamento em tempo de execução - Comparando os modos steer, queue, collect e followup summary: Como o direcionamento de execução ativa enfileira mensagens nos limites de tempo de execução title: Fila de direcionamento x-i18n: - generated_at: "2026-04-30T09:46:15Z" + generated_at: "2026-05-04T02:23:09Z" model: gpt-5.5 provider: openai - source_hash: 560390c8c26bcce95e0137f4336ad6e62bc3e2344cb15fd12ca3cfe4a85a8acc + source_hash: c8df35b127ae0c1e1b3b684a1f63ce33874eb3d0b7bf9d0df7cb9dfce093090a source_path: concepts/queue-steering.md workflow: 16 --- -Quando uma mensagem chega enquanto uma execução de sessão já está transmitindo em streaming, o OpenClaw pode -enviar essa mensagem para o tempo de execução ativo em vez de iniciar outra execução para -a mesma sessão. Os modos públicos são neutros em relação ao tempo de execução; o Pi e o -arcabouço nativo app-server do Codex implementam os detalhes de entrega de formas diferentes. +Quando uma mensagem chega enquanto uma execução de sessão já está transmitindo, o OpenClaw pode +enviar essa mensagem para o ambiente de execução ativo em vez de iniciar outra execução para +a mesma sessão. Os modos públicos são neutros em relação ao ambiente de execução; Pi e o harness +nativo de servidor de aplicativo do Codex implementam os detalhes de entrega de formas diferentes. -## Limite do tempo de execução +## Limite do ambiente de execução -A orientação não interrompe uma chamada de ferramenta que já está em execução. O Pi verifica -mensagens de orientação enfileiradas nos limites do modelo: +O direcionamento não interrompe uma chamada de ferramenta que já está em execução. Pi verifica +mensagens de direcionamento enfileiradas nos limites do modelo: -1. O assistente solicita chamadas de ferramenta. -2. O Pi executa o lote de chamadas de ferramenta da mensagem atual do assistente. -3. O Pi emite o evento de fim do turno. -4. O Pi drena as mensagens de orientação enfileiradas. -5. O Pi acrescenta essas mensagens como mensagens de usuário antes da próxima chamada ao LLM. +1. O assistente solicita chamadas de ferramentas. +2. Pi executa o lote de chamadas de ferramentas da mensagem atual do assistente. +3. Pi emite o evento de fim do turno. +4. Pi drena as mensagens de direcionamento enfileiradas. +5. Pi acrescenta essas mensagens como mensagens de usuário antes da próxima chamada ao LLM. Isso mantém os resultados das ferramentas pareados com a mensagem do assistente que os solicitou, -e então permite que a próxima chamada ao modelo veja a entrada mais recente do usuário. +e então permite que a próxima chamada do modelo veja a entrada mais recente do usuário. -O arcabouço nativo app-server do Codex expõe `turn/steer` em vez da -fila interna de orientação do Pi. O OpenClaw adapta os mesmos modos nesse contexto: +O harness nativo de servidor de aplicativo do Codex expõe `turn/steer` em vez da +fila interna de direcionamento do Pi. O OpenClaw adapta os mesmos modos ali: - `steer` agrupa mensagens enfileiradas durante a janela de silêncio configurada e então envia uma - única solicitação `turn/steer` com toda a entrada de usuário coletada na ordem de chegada. + única solicitação `turn/steer` com todas as entradas de usuário coletadas na ordem de chegada. - `queue` mantém o formato serializado legado enviando solicitações `turn/steer` separadas. -- `followup`, `collect`, `steer-backlog` e `interrupt` continuam sendo comportamento de - fila do OpenClaw ao redor do turno ativo do Codex. +- `followup`, `collect`, `steer-backlog` e `interrupt` permanecem como comportamento de fila + pertencente ao OpenClaw em torno do turno ativo do Codex. -Turnos de revisão do Codex e de compactação manual rejeitam orientação no mesmo turno. Quando um -tempo de execução não pode aceitar orientação, o OpenClaw recorre à fila de acompanhamento quando +Turnos de revisão do Codex e de Compaction manual rejeitam direcionamento no mesmo turno. Quando um +ambiente de execução não consegue aceitar direcionamento, o OpenClaw recorre à fila de acompanhamento quando esse modo permite. +Esta página explica o direcionamento em modo de fila para mensagens de entrada normais. Para o +comando explícito `/steer `, consulte [Direcionar](/tools/steer). + ## Modos -| Modo | Comportamento com execução ativa | Comportamento de acompanhamento posterior | +| Modo | Comportamento com execução ativa | Comportamento de acompanhamento posterior | | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `steer` | Injeta todas as mensagens de orientação enfileiradas juntas no próximo limite do tempo de execução. Este é o padrão. | Recorre ao acompanhamento somente quando a orientação está indisponível. | -| `queue` | Orientação legada uma por vez. O Pi injeta uma mensagem enfileirada por limite do modelo; o Codex envia solicitações `turn/steer` separadas. | Recorre ao acompanhamento somente quando a orientação está indisponível. | -| `steer-backlog` | Mesmo comportamento de orientação com execução ativa que `steer`. | Também mantém a mesma mensagem para um turno de acompanhamento posterior. | -| `followup` | Não orienta a execução atual. | Executa mensagens enfileiradas depois. | -| `collect` | Não orienta a execução atual. | Agrupa mensagens enfileiradas compatíveis em um turno posterior após a janela de debounce. | -| `interrupt` | Aborta a execução ativa e então inicia a mensagem mais recente. | Nenhum. | +| `steer` | Injeta todas as mensagens de direcionamento enfileiradas juntas no próximo limite do ambiente de execução. Este é o padrão. | Recorre ao acompanhamento somente quando o direcionamento está indisponível. | +| `queue` | Direcionamento legado uma por vez. Pi injeta uma mensagem enfileirada por limite de modelo; Codex envia solicitações `turn/steer` separadas. | Recorre ao acompanhamento somente quando o direcionamento está indisponível. | +| `steer-backlog` | Mesmo comportamento de direcionamento com execução ativa que `steer`. | Também mantém a mesma mensagem para um turno de acompanhamento posterior. | +| `followup` | Não direciona a execução atual. | Executa mensagens enfileiradas depois. | +| `collect` | Não direciona a execução atual. | Agrupa mensagens enfileiradas compatíveis em um turno posterior após a janela de debounce. | +| `interrupt` | Aborta a execução ativa e então inicia a mensagem mais recente. | Nenhum. | ## Exemplo de rajada Se quatro usuários enviarem mensagens enquanto o agente está executando uma chamada de ferramenta: -- `steer`: o tempo de execução ativo recebe todas as quatro mensagens na ordem de chegada antes - da próxima decisão do modelo. O Pi as drena no próximo limite do modelo; o Codex - as recebe como um único `turn/steer` em lote. -- `queue`: orientação serializada legada. O Pi injeta uma mensagem enfileirada por vez; - o Codex recebe solicitações `turn/steer` separadas. -- `collect`: o OpenClaw espera até a execução ativa terminar e então cria um turno de acompanhamento +- `steer`: o ambiente de execução ativo recebe todas as quatro mensagens na ordem de chegada antes + de sua próxima decisão do modelo. Pi as drena no próximo limite do modelo; Codex + as recebe como um `turn/steer` agrupado. +- `queue`: direcionamento serializado legado. Pi injeta uma mensagem enfileirada por vez; + Codex recebe solicitações `turn/steer` separadas. +- `collect`: o OpenClaw espera até que a execução ativa termine e então cria um turno de acompanhamento com mensagens enfileiradas compatíveis após a janela de debounce. ## Escopo -A orientação sempre mira a execução da sessão ativa atual. Ela não cria uma nova +O direcionamento sempre mira a execução de sessão ativa atual. Ele não cria uma nova sessão, não altera a política de ferramentas da execução ativa nem divide mensagens por remetente. Em -canais multiusuário, os prompts de entrada já incluem contexto de remetente e rota, para que -a próxima chamada ao modelo possa ver quem enviou cada mensagem. +canais multiusuário, os prompts de entrada já incluem contexto de remetente e rota, então +a próxima chamada do modelo consegue ver quem enviou cada mensagem. Use `collect` quando quiser que o OpenClaw crie um turno de acompanhamento posterior que possa agrupar mensagens compatíveis e preservar a política de descarte da fila de acompanhamento. Use -`queue` somente quando precisar do comportamento antigo de orientação uma por vez. +`queue` somente quando precisar do comportamento de direcionamento antigo uma por vez. ## Debounce `messages.queue.debounceMs` se aplica à entrega de acompanhamento, incluindo `collect`, -`followup`, `steer-backlog` e fallback de `steer` quando a orientação com execução ativa não está -disponível. Para o Pi, o `steer` ativo em si não usa o temporizador de debounce porque -o Pi agrupa mensagens naturalmente até o próximo limite do modelo. Para o arcabouço nativo -do Codex, o OpenClaw usa o mesmo valor de debounce como janela de silêncio antes de -enviar o `turn/steer` em lote. +`followup`, `steer-backlog` e fallback de `steer` quando o direcionamento com execução ativa não está +disponível. Para Pi, o próprio `steer` ativo não usa o temporizador de debounce porque +Pi naturalmente agrupa mensagens até o próximo limite do modelo. Para o harness nativo do +Codex, o OpenClaw usa o mesmo valor de debounce como a janela de silêncio antes de +enviar o `turn/steer` agrupado. ## Relacionados - [Fila de comandos](/pt-BR/concepts/queue) +- [Direcionar](/tools/steer) - [Mensagens](/pt-BR/concepts/messages) - [Loop do agente](/pt-BR/concepts/agent-loop) diff --git a/docs/pt-BR/concepts/queue.md b/docs/pt-BR/concepts/queue.md index f69dc4a1c..3178adc8e 100644 --- a/docs/pt-BR/concepts/queue.md +++ b/docs/pt-BR/concepts/queue.md @@ -2,63 +2,64 @@ read_when: - Alterando a execução ou a concorrência da resposta automática - Explicando os modos de /queue ou o comportamento de direcionamento de mensagens -summary: Modos da fila de resposta automática, padrões e substituições por sessão +summary: Modos de fila de resposta automática, padrões e substituições por sessão title: Fila de comandos x-i18n: - generated_at: "2026-05-02T05:45:29Z" + generated_at: "2026-05-04T02:23:01Z" model: gpt-5.5 provider: openai - source_hash: c59ea6802d8bf526f4005db3b1baa87d96a23d561c916f91520e8e641fbaf74f + source_hash: 085aebe7059020f027eb08bb382cce2d253ea117eed0ca77d6ffd208f295acb1 source_path: concepts/queue.md workflow: 16 --- -Serializamos execuções de resposta automática recebidas (todos os canais) por uma pequena fila em processo para impedir colisões entre múltiplas execuções de agente, enquanto ainda permitimos paralelismo seguro entre sessões. +Serializamos execuções de resposta automática de entrada (todos os canais) por meio de uma pequena fila em processo para evitar colisões entre múltiplas execuções de agente, ainda permitindo paralelismo seguro entre sessões. ## Por quê -- Execuções de resposta automática podem ser caras (chamadas de LLM) e podem colidir quando várias mensagens recebidas chegam em intervalos próximos. +- Execuções de resposta automática podem ser caras (chamadas de LLM) e podem colidir quando várias mensagens de entrada chegam em sequência próxima. - A serialização evita competição por recursos compartilhados (arquivos de sessão, logs, stdin da CLI) e reduz a chance de limites de taxa upstream. ## Como funciona -- Uma fila FIFO ciente de faixas esvazia cada faixa com um limite de concorrência configurável (padrão 1 para faixas não configuradas; a principal usa 4 por padrão, subagente usa 8). +- Uma fila FIFO ciente de faixas drena cada faixa com um limite de concorrência configurável (padrão 1 para faixas não configuradas; `main` usa 4 por padrão, `subagent` usa 8). - `runEmbeddedPiAgent` enfileira por **chave de sessão** (faixa `session:`) para garantir apenas uma execução ativa por sessão. - Cada execução de sessão é então enfileirada em uma **faixa global** (`main` por padrão), para que o paralelismo geral seja limitado por `agents.defaults.maxConcurrent`. -- Quando o registro detalhado está habilitado, execuções enfileiradas emitem um aviso curto se esperarem mais de ~2s antes de iniciar. -- Indicadores de digitação ainda disparam imediatamente no enfileiramento (quando o canal oferece suporte), então a experiência do usuário fica inalterada enquanto aguardamos nossa vez. +- Quando o log detalhado está habilitado, execuções enfileiradas emitem um aviso curto se esperaram mais de ~2s antes de iniciar. +- Indicadores de digitação ainda disparam imediatamente ao enfileirar (quando compatível com o canal), então a experiência do usuário permanece inalterada enquanto aguardamos a vez. ## Padrões -Quando não definido, todas as superfícies de canais recebidos usam: +Quando não configuradas, todas as superfícies de canal de entrada usam: - `mode: "steer"` - `debounceMs: 500` - `cap: 20` - `drop: "summarize"` -`steer` é o padrão porque mantém o turno do modelo ativo responsivo sem +`steer` é o padrão porque mantém a rodada ativa do modelo responsiva sem iniciar uma segunda execução de sessão. Ele drena todas as mensagens de direcionamento que chegaram antes do próximo limite do modelo. Se a execução atual não puder aceitar direcionamento, o OpenClaw recorre a uma entrada de fila de acompanhamento. ## Modos de fila -Mensagens recebidas podem direcionar a execução atual, aguardar um turno de acompanhamento ou fazer ambos: +Mensagens de entrada podem direcionar a execução atual, aguardar uma rodada de acompanhamento ou fazer ambos: -- `steer`: enfileira mensagens de direcionamento no runtime ativo. O Pi entrega todas as mensagens de direcionamento pendentes **depois que o turno atual do assistente termina de executar suas chamadas de ferramentas**, antes da próxima chamada de LLM; o app-server do Codex recebe um `turn/steer` em lote. Se a execução não estiver transmitindo ativamente ou o direcionamento estiver indisponível, o OpenClaw recorre a uma entrada de fila de acompanhamento. -- `queue` (legado): direcionamento antigo, um por vez. O Pi entrega uma mensagem de direcionamento enfileirada em cada limite do modelo; o app-server do Codex recebe solicitações `turn/steer` separadas. Prefira `steer`, a menos que você precise do comportamento serializado anterior. -- `followup`: enfileira cada mensagem para um turno posterior do agente depois que a execução atual termina. -- `collect`: combina mensagens enfileiradas em um **único** turno de acompanhamento após a janela de silêncio. Se as mensagens tiverem como destino canais/threads diferentes, elas são drenadas individualmente para preservar o roteamento. -- `steer-backlog` (também conhecido como `steer+backlog`): direciona agora **e** preserva a mesma mensagem para um turno de acompanhamento. -- `interrupt` (legado): aborta a execução ativa dessa sessão e depois executa a mensagem mais recente. +- `steer`: enfileira mensagens de direcionamento no runtime ativo. O Pi entrega todas as mensagens de direcionamento pendentes **depois que a rodada atual do assistente termina de executar suas chamadas de ferramenta**, antes da próxima chamada de LLM; o Codex app-server recebe um `turn/steer` em lote. Se a execução não estiver transmitindo ativamente ou o direcionamento estiver indisponível, o OpenClaw recorre a uma entrada de fila de acompanhamento. +- `queue` (legado): direcionamento antigo, um por vez. O Pi entrega uma mensagem de direcionamento enfileirada em cada limite do modelo; o Codex app-server recebe solicitações `turn/steer` separadas. Prefira `steer`, a menos que você precise do comportamento serializado anterior. +- `followup`: enfileira cada mensagem para uma rodada posterior do agente depois que a execução atual termina. +- `collect`: combina mensagens enfileiradas em uma **única** rodada de acompanhamento depois da janela de silêncio. Se as mensagens tiverem como destino canais/threads diferentes, elas são drenadas individualmente para preservar o roteamento. +- `steer-backlog` (também conhecido como `steer+backlog`): direciona agora **e** preserva a mesma mensagem para uma rodada de acompanhamento. +- `interrupt` (legado): aborta a execução ativa dessa sessão e então executa a mensagem mais recente. -Steer-backlog significa que você pode receber uma resposta de acompanhamento depois da execução direcionada, então -superfícies de streaming podem parecer duplicadas. Prefira `collect`/`steer` se você quiser -uma resposta por mensagem recebida. +Steer-backlog significa que você pode receber uma resposta de acompanhamento após a execução direcionada, então +superfícies de streaming podem parecer duplicadas. Prefira `collect`/`steer` se quiser +uma resposta por mensagem de entrada. -Para comportamento de temporização e dependência específico do runtime, consulte -[Fila de direcionamento](/pt-BR/concepts/queue-steering). +Para comportamento de temporização e dependências específico do runtime, consulte +[Fila de direcionamento](/pt-BR/concepts/queue-steering). Para o comando explícito `/steer `, +consulte [Direcionar](/tools/steer). Configure globalmente ou por canal via `messages.queue`: @@ -76,14 +77,14 @@ Configure globalmente ou por canal via `messages.queue`: } ``` -## Opções de fila +## Opções da fila -As opções se aplicam a `followup`, `collect` e `steer-backlog` (e a `steer` ou `queue` legado quando o direcionamento recorre a acompanhamento): +As opções se aplicam a `followup`, `collect` e `steer-backlog` (e a `steer` ou ao `queue` legado quando o direcionamento recorre a acompanhamento): -- `debounceMs`: janela de silêncio antes de drenar acompanhamentos enfileirados. Números sem unidade são milissegundos; as unidades `ms`, `s`, `m`, `h` e `d` são aceitas pelas opções de `/queue`. +- `debounceMs`: janela de silêncio antes de drenar acompanhamentos enfileirados. Números puros são milissegundos; as unidades `ms`, `s`, `m`, `h` e `d` são aceitas pelas opções de `/queue`. - `cap`: máximo de mensagens enfileiradas por sessão. Valores abaixo de `1` são ignorados. -- `drop: "summarize"`: padrão. Remove as entradas enfileiradas mais antigas conforme necessário, mantém resumos compactos e os injeta como um prompt sintético de acompanhamento. -- `drop: "old"`: remove as entradas enfileiradas mais antigas conforme necessário, sem preservar resumos. +- `drop: "summarize"`: padrão. Descarta as entradas enfileiradas mais antigas conforme necessário, mantém resumos compactos e os injeta como um prompt de acompanhamento sintético. +- `drop: "old"`: descarta as entradas enfileiradas mais antigas conforme necessário, sem preservar resumos. - `drop: "new"`: rejeita a mensagem mais recente quando a fila já está cheia. Padrões: `debounceMs: 500`, `cap: 20`, `drop: summarize`. @@ -92,39 +93,41 @@ Padrões: `debounceMs: 500`, `cap: 20`, `drop: summarize`. Para seleção de modo, o OpenClaw resolve: -1. Substituição de `/queue` inline ou armazenada por sessão. +1. Sobrescrita `/queue` inline ou armazenada por sessão. 2. `messages.queue.byChannel.`. 3. `messages.queue.mode`. -4. Padrão `steer`. +4. `steer` padrão. -Para opções, opções de `/queue` inline ou armazenadas vencem a configuração. Depois, -são aplicados debounce específico do canal (`messages.queue.debounceMsByChannel`), padrões -de debounce do Plugin, opções globais de `messages.queue` e padrões integrados. `cap` e `drop` são opções globais/de sessão, não chaves -de configuração por canal. +Para opções, opções `/queue` inline ou armazenadas vencem a configuração. Em seguida, +são aplicados o debounce específico do canal (`messages.queue.debounceMsByChannel`), os +padrões de debounce de Plugin, as opções globais de `messages.queue` e os padrões +integrados. `cap` e `drop` são opções globais/de sessão, não chaves de configuração +por canal. -## Substituições por sessão +## Sobrescritas por sessão - Envie `/queue ` como um comando independente para armazenar o modo da sessão atual. -- Opções podem ser combinadas: `/queue collect debounce:0.5s cap:25 drop:summarize` -- `/queue default` ou `/queue reset` limpa a substituição da sessão. +- As opções podem ser combinadas: `/queue collect debounce:0.5s cap:25 drop:summarize` +- `/queue default` ou `/queue reset` limpa a sobrescrita da sessão. ## Escopo e garantias -- Aplica-se a execuções de agentes de resposta automática em todos os canais recebidos que usam o pipeline de resposta do Gateway (web do WhatsApp, Telegram, Slack, Discord, Signal, iMessage, webchat etc.). -- A faixa padrão (`main`) é válida para todo o processo para mensagens recebidas + Heartbeats principais; defina `agents.defaults.maxConcurrent` para permitir várias sessões em paralelo. -- Faixas adicionais podem existir (por exemplo, `cron`, `cron-nested`, `nested`, `subagent`) para que trabalhos em segundo plano possam executar em paralelo sem bloquear respostas recebidas. Turnos isolados de agente Cron ocupam um slot `cron` enquanto a execução interna do agente usa `cron-nested`; ambos usam `cron.maxConcurrentRuns`. Fluxos `nested` não Cron compartilhados mantêm seu próprio comportamento de faixa. Essas execuções desacopladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). -- Faixas por sessão garantem que apenas uma execução de agente toque em determinada sessão por vez. -- Sem dependências externas nem threads de worker em segundo plano; TypeScript puro + promises. +- Aplica-se a execuções de agente de resposta automática em todos os canais de entrada que usam o pipeline de resposta do Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat etc.). +- A faixa padrão (`main`) é de todo o processo para entrada + heartbeats principais; defina `agents.defaults.maxConcurrent` para permitir várias sessões em paralelo. +- Faixas adicionais podem existir (por exemplo, `cron`, `cron-nested`, `nested`, `subagent`), para que tarefas em segundo plano possam executar em paralelo sem bloquear respostas de entrada. Rodadas isoladas de agente cron mantêm um slot `cron` enquanto sua execução interna de agente usa `cron-nested`; ambas usam `cron.maxConcurrentRuns`. Fluxos `nested` não cron compartilhados mantêm seu próprio comportamento de faixa. Essas execuções destacadas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). +- Faixas por sessão garantem que apenas uma execução de agente toque uma determinada sessão por vez. +- Sem dependências externas ou threads de worker em segundo plano; TypeScript puro + promises. ## Solução de problemas - Se comandos parecerem travados, habilite logs detalhados e procure linhas “queued for …ms” para confirmar que a fila está drenando. - Se você precisar da profundidade da fila, habilite logs detalhados e observe as linhas de temporização da fila. -- Execuções do app-server do Codex que aceitam um turno e depois param de emitir progresso são interrompidas pelo adaptador Codex, para que a faixa da sessão ativa possa ser liberada em vez de esperar pelo timeout da execução externa. -- Quando diagnósticos estão habilitados, sessões que permanecem em `processing` além de `diagnostics.stuckSessionWarnMs` sem resposta, ferramenta, status, bloco ou progresso ACP observado são classificadas pela atividade atual. Trabalho ativo é registrado como `session.long_running`; trabalho ativo sem progresso recente é registrado como `session.stalled`; `session.stuck` é reservado para bookkeeping de sessão obsoleto sem trabalho ativo, e somente esse caminho pode liberar a faixa de sessão afetada para que o trabalho enfileirado seja drenado. Diagnósticos `session.stuck` repetidos recuam enquanto a sessão permanecer inalterada. +- Execuções do Codex app-server que aceitam uma rodada e então param de emitir progresso são interrompidas pelo adaptador do Codex para que a faixa da sessão ativa possa ser liberada em vez de aguardar o timeout da execução externa. +- Quando diagnósticos estão habilitados, sessões que permanecem em `processing` além de `diagnostics.stuckSessionWarnMs` sem resposta, ferramenta, status, bloco ou progresso ACP observado são classificadas pela atividade atual. Trabalho ativo registra log como `session.long_running`; trabalho ativo sem progresso recente registra log como `session.stalled`; `session.stuck` é reservado para bookkeeping de sessão obsoleta sem trabalho ativo, e apenas esse caminho pode liberar a faixa da sessão afetada para que o trabalho enfileirado seja drenado. Diagnósticos `session.stuck` repetidos fazem backoff enquanto a sessão permanece inalterada. -## Relacionado +## Relacionados - [Gerenciamento de sessão](/pt-BR/concepts/session) - [Fila de direcionamento](/pt-BR/concepts/queue-steering) -- [Política de nova tentativa](/pt-BR/concepts/retry) +- [Direcionar](/tools/steer) +- [Política de repetição](/pt-BR/concepts/retry) diff --git a/docs/pt-BR/concepts/system-prompt.md b/docs/pt-BR/concepts/system-prompt.md index 9c3e8e051..227ca1e7d 100644 --- a/docs/pt-BR/concepts/system-prompt.md +++ b/docs/pt-BR/concepts/system-prompt.md @@ -1,153 +1,154 @@ --- read_when: - - Edição do texto do prompt do sistema, da lista de ferramentas ou das seções de tempo/Heartbeat - - Alteração da inicialização do espaço de trabalho ou do comportamento de injeção de Skills -summary: O que o prompt do sistema do OpenClaw contém e como ele é montado + - Editando o texto do prompt do sistema, a lista de ferramentas ou as seções de tempo/Heartbeat + - Alterando o comportamento de inicialização do espaço de trabalho ou de injeção de Skills +summary: O que o prompt de sistema do OpenClaw contém e como ele é montado title: Prompt do sistema x-i18n: - generated_at: "2026-05-03T21:30:48Z" + generated_at: "2026-05-04T02:23:15Z" model: gpt-5.5 provider: openai - source_hash: 93533ac8090897a7b5fd82b80e542a4ad573670408314b3519c5e317d0408ade + source_hash: 5e6067e760eccf58106f0a646c2656e902d5951580abd750f342d70b0568b81b source_path: concepts/system-prompt.md workflow: 16 --- -OpenClaw cria um prompt de sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent. +OpenClaw cria um prompt de sistema personalizado para cada execução de agente. O prompt é **propriedade da OpenClaw** e não usa o prompt padrão do pi-coding-agent. -O prompt é montado pelo OpenClaw e injetado em cada execução de agente. +O prompt é montado pela OpenClaw e injetado em cada execução de agente. -Plugins de provedor podem contribuir com orientações de prompt sensíveis ao cache sem substituir -o prompt completo de propriedade do OpenClaw. O runtime do provedor pode: +Plugins de provedor podem contribuir com orientações de prompt conscientes de cache sem substituir +o prompt completo de propriedade da OpenClaw. O runtime do provedor pode: - substituir um pequeno conjunto de seções principais nomeadas (`interaction_style`, `tool_call_style`, `execution_bias`) -- injetar um **prefixo estável** acima do limite do cache de prompt -- injetar um **sufixo dinâmico** abaixo do limite do cache de prompt +- injetar um **prefixo estável** acima do limite de cache do prompt +- injetar um **sufixo dinâmico** abaixo do limite de cache do prompt Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação de prompt legada -`before_prompt_build` para compatibilidade ou mudanças de prompt verdadeiramente globais, +`before_prompt_build` para compatibilidade ou alterações de prompt realmente globais, não para o comportamento normal do provedor. A sobreposição da família OpenAI GPT-5 mantém a regra principal de execução pequena e adiciona -orientações específicas do modelo para fixação de persona, saída concisa, disciplina de ferramentas, -busca paralela, cobertura de entregáveis, verificação, contexto ausente e -higiene da ferramenta de terminal. +orientações específicas de modelo para fixação de persona, saída concisa, disciplina de ferramentas, +consulta paralela, cobertura de entregáveis, verificação, contexto ausente e +higiene de ferramentas de terminal. ## Estrutura O prompt é intencionalmente compacto e usa seções fixas: -- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas mais orientações de uso de ferramentas em runtime. -- **Viés de execução**: orientação compacta de acompanhamento: agir no turno em - solicitações acionáveis, continuar até concluir ou ficar bloqueado, recuperar-se de resultados fracos de ferramentas, +- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas, além de orientação de uso de ferramentas em runtime. +- **Viés de Execução**: orientação compacta de acompanhamento: agir durante o turno em + solicitações acionáveis, continuar até concluir ou ser bloqueado, recuperar-se de resultados fracos de ferramentas, verificar estado mutável ao vivo e verificar antes de finalizar. -- **Segurança**: lembrete curto de proteção para evitar comportamento de busca de poder ou bypass de supervisão. +- **Segurança**: lembrete curto de proteção para evitar comportamento de busca de poder ou contornar supervisão. - **Skills** (quando disponíveis): informa ao modelo como carregar instruções de Skills sob demanda. -- **Autoatualização do OpenClaw**: como inspecionar a configuração com segurança com - `config.schema.lookup`, corrigir a configuração com `config.patch`, substituir a configuração - completa com `config.apply` e executar `update.run` somente mediante solicitação explícita do usuário. - A ferramenta `gateway`, exclusiva do proprietário, também se recusa a reescrever +- **Autoatualização da OpenClaw**: como inspecionar a configuração com segurança usando + `config.schema.lookup`, corrigir a configuração com `config.patch`, substituir a configuração completa + com `config.apply` e executar `update.run` apenas mediante solicitação explícita do usuário. A ferramenta `gateway`, exclusiva do proprietário, também se recusa a reescrever `tools.exec.ask` / `tools.exec.security`, incluindo aliases legados `tools.bash.*` - que são normalizados para esses caminhos exec protegidos. -- **Espaço de trabalho**: diretório de trabalho (`agents.defaults.workspace`). -- **Documentação**: caminho local para a documentação do OpenClaw (repositório ou pacote npm) e quando lê-la. -- **Arquivos do espaço de trabalho (injetados)**: indica que arquivos de inicialização estão incluídos abaixo. -- **Sandbox** (quando ativado): indica runtime em sandbox, caminhos de sandbox e se exec elevado está disponível. -- **Data e hora atuais**: hora local do usuário, fuso horário e formato de hora. -- **Tags de resposta**: sintaxe opcional de tags de resposta para provedores compatíveis. -- **Heartbeats**: prompt de Heartbeat e comportamento de confirmação, quando Heartbeats estão ativados para o agente padrão. -- **Runtime**: host, SO, Node, modelo, raiz do repositório (quando detectada), nível de raciocínio (uma linha). -- **Raciocínio**: nível atual de visibilidade + dica de alternância /reasoning. + que são normalizados para esses caminhos protegidos de exec. +- **Workspace**: diretório de trabalho (`agents.defaults.workspace`). +- **Documentação**: caminho local para a documentação da OpenClaw (repositório ou pacote npm) e quando lê-la. +- **Arquivos do Workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo. +- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos de sandbox e se exec elevado está disponível. +- **Data e Hora Atuais**: hora local do usuário, fuso horário e formato de hora. +- **Tags de Resposta**: sintaxe opcional de tag de resposta para provedores compatíveis. +- **Heartbeats**: prompt de Heartbeat e comportamento de confirmação, quando Heartbeats estão habilitados para o agente padrão. +- **Runtime**: host, SO, node, modelo, raiz do repositório (quando detectada), nível de pensamento (uma linha). +- **Raciocínio**: nível de visibilidade atual + dica de alternância /reasoning. -O OpenClaw mantém conteúdo estável grande, incluindo **Contexto do projeto**, acima do -limite interno do cache de prompt. Seções voláteis de canal/sessão, como -orientação de incorporação da UI de controle, **Mensagens**, **Voz**, **Contexto de chat em grupo**, +A OpenClaw mantém conteúdo grande e estável, incluindo **Contexto do Projeto**, acima do +limite interno de cache do prompt. Seções voláteis de canal/sessão, como +orientação de incorporação da Control UI, **Mensagens**, **Voz**, **Contexto de Chat em Grupo**, **Reações**, **Heartbeats** e **Runtime**, são anexadas abaixo desse limite -para que backends locais com caches de prefixo possam reutilizar o prefixo estável do espaço de trabalho -entre turnos de canal. Descrições de ferramentas também devem evitar incorporar nomes atuais -de canais quando o esquema aceito já carrega esse detalhe de runtime. +para que backends locais com caches de prefixo possam reutilizar o prefixo estável do workspace +entre turnos de canal. Descrições de ferramentas também devem evitar incorporar nomes de canais atuais +quando o esquema aceito já carrega esse detalhe de runtime. -A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração: +A seção Ferramentas também inclui orientação de runtime para trabalhos de longa duração: -- use Cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente) - em vez de loops de espera com `exec`, truques de atraso `yieldMs` ou consultas repetidas de `process` -- use `exec` / `process` somente para comandos que começam agora e continuam executando +- use cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente) + em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou polling repetido de `process` +- use `exec` / `process` apenas para comandos que começam agora e continuam em execução em segundo plano -- quando a ativação automática por conclusão estiver habilitada, inicie o comando uma vez e confie no - caminho de ativação baseado em push quando ele emitir saída ou falhar +- quando a ativação automática por conclusão estiver habilitada, inicie o comando uma vez e conte com + o caminho de ativação baseado em push quando ele emitir saída ou falhar - use `process` para logs, status, entrada ou intervenção quando precisar inspecionar um comando em execução - se a tarefa for maior, prefira `sessions_spawn`; a conclusão do subagente é - baseada em push e se anuncia automaticamente de volta ao solicitante -- não consulte `subagents list` / `sessions_list` em loop apenas para aguardar + baseada em push e anunciada automaticamente de volta ao solicitante +- não faça polling de `subagents list` / `sessions_list` em loop apenas para esperar a conclusão -Quando a ferramenta experimental `update_plan` está ativada, Ferramentas também instrui o -modelo a usá-la somente para trabalho de várias etapas não trivial, manter exatamente uma etapa +Quando a ferramenta experimental `update_plan` está habilitada, Ferramentas também instrui o +modelo a usá-la apenas para trabalho não trivial de várias etapas, manter exatamente uma etapa `in_progress` e evitar repetir o plano inteiro após cada atualização. -As proteções de segurança no prompt de sistema são consultivas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e listas de permissões de canal para imposição rígida; operadores podem desativá-las por design. +As proteções de segurança no prompt de sistema são consultivas. Elas orientam o comportamento do modelo, mas não aplicam políticas. Use política de ferramentas, aprovações de exec, sandboxing e allowlists de canais para aplicação rígida; operadores podem desabilitá-las por design. -Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora instrui o -agente a confiar primeiro nessa UI de aprovação nativa. Ele só deve incluir um comando manual -`/approve` quando o resultado da ferramenta informar que aprovações por chat estão indisponíveis ou que -aprovação manual é o único caminho. +Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora diz ao +agente para contar primeiro com essa interface de aprovação nativa. Ele só deve incluir um comando manual +`/approve` quando o resultado da ferramenta disser que aprovações por chat não estão disponíveis ou +que a aprovação manual é o único caminho. ## Modos de prompt -O OpenClaw pode renderizar prompts de sistema menores para subagentes. O runtime define um +A OpenClaw pode renderizar prompts de sistema menores para subagentes. O runtime define um `promptMode` para cada execução (não é uma configuração voltada ao usuário): - `full` (padrão): inclui todas as seções acima. -- `minimal`: usado para subagentes; omite **Skills**, **Recuperação de memória**, **Autoatualização do OpenClaw**, - **Aliases de modelo**, **Identidade do usuário**, **Tags de resposta**, - **Mensagens**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, - Espaço de trabalho, Sandbox, Data e hora atuais (quando conhecidas), Runtime e contexto - injetado continuam disponíveis. -- `none`: retorna somente a linha de identidade básica. +- `minimal`: usado para subagentes; omite **Skills**, **Recuperação de Memória**, **Autoatualização da OpenClaw + **, **Aliases de Modelo**, **Identidade do Usuário**, **Tags de Resposta**, + **Mensagens**, **Respostas Silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, + Workspace, Sandbox, Data e Hora Atuais (quando conhecidas), Runtime e contexto + injetado permanecem disponíveis. +- `none`: retorna apenas a linha de identidade base. -Quando `promptMode=minimal`, prompts injetados extras são rotulados como **Contexto do subagente** -em vez de **Contexto de chat em grupo**. +Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do Subagente +** em vez de **Contexto de Chat em Grupo**. -Para execuções de resposta automática de canal, o OpenClaw pode omitir a seção genérica **Respostas silenciosas** -quando o contexto de chat direto/em grupo já inclui o comportamento `NO_REPLY` -específico da conversa resolvido. Isso evita repetir mecânicas de token +Para execuções de resposta automática de canal, a OpenClaw pode omitir a seção genérica **Respostas Silenciosas** +quando o contexto de chat direto/grupo já inclui o comportamento `NO_REPLY` +específico da conversa resolvido. Isso evita repetir a mecânica de tokens tanto no prompt de sistema global quanto no contexto do canal. -## Instantâneos de prompt +## Snapshots de prompt -O OpenClaw mantém instantâneos de prompt versionados para o caminho feliz do runtime Codex em +A OpenClaw mantém snapshots de prompt comitados para o caminho feliz do runtime Codex em `test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Eles renderizam -parâmetros selecionados de thread/turno do servidor de app mais uma pilha reconstruída de camadas de prompt -vinculadas ao modelo para turnos diretos do Telegram, em grupo do Discord e de Heartbeat. Essa pilha -inclui um fixture fixado de prompt do modelo Codex `gpt-5.5` gerado a partir do formato +parâmetros selecionados de thread/turn do app-server, além de uma pilha reconstruída de camadas de prompt +vinculada ao modelo para turnos diretos do Telegram, grupo do Discord e Heartbeat. Essa pilha +inclui uma fixture fixada de prompt de modelo Codex `gpt-5.5` gerada a partir do formato do catálogo/cache de modelos do Codex, o texto de desenvolvedor de permissões do caminho feliz do Codex, -instruções de desenvolvedor do OpenClaw, instruções de modo de colaboração com escopo de turno -quando o OpenClaw as fornece, entrada de turno do usuário e referências às especificações dinâmicas de ferramentas. +instruções de desenvolvedor da OpenClaw, instruções de modo de colaboração com escopo de turno +quando a OpenClaw as fornece, entrada do turno do usuário e referências às especificações dinâmicas +de ferramentas. -Atualize o fixture fixado do prompt do modelo Codex com +Atualize a fixture fixada de prompt de modelo Codex com `pnpm prompt:snapshots:sync-codex-model`. Por padrão, o script procura o cache de runtime do Codex em `$CODEX_HOME/models_cache.json`, depois em -`~/.codex/models_cache.json` e só então recorre à convenção do checkout Codex +`~/.codex/models_cache.json` e só então recorre à convenção de checkout do Codex do mantenedor em `~/code/codex/codex-rs/models-manager/models.json`. Se -nenhuma dessas fontes existir, o comando sai sem alterar o fixture versionado. -Passe `--catalog ` para atualizar a partir de um arquivo `models_cache.json` +nenhuma dessas fontes existir, o comando encerra sem alterar a fixture +comitada. Passe `--catalog ` para atualizar a partir de um arquivo `models_cache.json` ou `models.json` específico. -Esses instantâneos ainda não são uma captura bruta byte a byte de uma solicitação OpenAI. O Codex -pode adicionar contexto de espaço de trabalho de propriedade do runtime, como `AGENTS.md`, contexto de ambiente, -memórias, instruções de app/Plugin e instruções integradas de modo de colaboração -Default dentro do runtime Codex depois que o OpenClaw envia parâmetros de thread e turno. +Esses snapshots ainda não são uma captura bruta byte a byte de uma solicitação OpenAI. O Codex +pode adicionar contexto de workspace de propriedade do runtime, como `AGENTS.md`, contexto de +ambiente, memórias, instruções de app/plugin e instruções internas do modo de colaboração Default +dentro do runtime do Codex depois que a OpenClaw envia +parâmetros de thread e turno. Regere-os com `pnpm prompt:snapshots:gen` e verifique desvios com -`pnpm prompt:snapshots:check`. A CI executa a verificação de desvio no shard adicional -de limite para que mudanças de prompt e atualizações de instantâneos permaneçam anexadas ao mesmo +`pnpm prompt:snapshots:check`. A CI executa a verificação de desvio no shard +de limite adicional para que alterações de prompt e atualizações de snapshot permaneçam anexadas ao mesmo PR. -## Injeção de inicialização do espaço de trabalho +## Injeção de bootstrap do workspace -Arquivos de inicialização são aparados e anexados em **Contexto do projeto** para que o modelo veja identidade e contexto de perfil sem precisar de leituras explícitas: +Arquivos de bootstrap são truncados e anexados em **Contexto do Projeto** para que o modelo veja contexto de identidade e perfil sem precisar de leituras explícitas: - `AGENTS.md` - `SOUL.md` @@ -155,77 +156,78 @@ Arquivos de inicialização são aparados e anexados em **Contexto do projeto** - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (somente em espaços de trabalho recém-criados) +- `BOOTSTRAP.md` (apenas em workspaces recém-criados) - `MEMORY.md` quando presente Todos esses arquivos são **injetados na janela de contexto** em cada turno, a menos que uma regra específica de arquivo se aplique. `HEARTBEAT.md` é omitido em execuções normais quando -Heartbeats estão desativados para o agente padrão ou +Heartbeats estão desabilitados para o agente padrão ou `agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a -uso de contexto inesperadamente alto e Compaction mais frequente. +uso inesperadamente alto de contexto e Compaction mais frequente. -Quando uma sessão roda no harness nativo do Codex, o Codex carrega `AGENTS.md` -por meio de sua própria descoberta de documentos do projeto. O OpenClaw ainda resolve os demais -arquivos de inicialização e os encaminha como instruções de configuração do Codex, então `SOUL.md`, +Quando uma sessão é executada no harness nativo do Codex, o Codex carrega `AGENTS.md` +por meio de sua própria descoberta de documentação de projeto. A OpenClaw ainda resolve os demais +arquivos de bootstrap e os encaminha como instruções de configuração do Codex, então `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` e -`MEMORY.md` mantêm a mesma função de contexto do espaço de trabalho sem duplicar +`MEMORY.md` mantêm o mesmo papel de contexto do workspace sem duplicar `AGENTS.md`. -Arquivos diários `memory/*.md` **não** fazem parte do Contexto do projeto de inicialização normal. Em turnos comuns, eles são acessados sob demanda por meio das ferramentas `memory_search` e `memory_get`, então não contam contra a janela de contexto, a menos que o modelo os leia explicitamente. Turnos simples `/new` e `/reset` são a exceção: o runtime pode prefixar memória diária recente como um bloco único de contexto de inicialização para esse primeiro turno. +Arquivos diários `memory/*.md` **não** fazem parte do Contexto do Projeto de bootstrap normal. Em turnos comuns, eles são acessados sob demanda pelas ferramentas `memory_search` e `memory_get`, portanto não contam contra a janela de contexto a menos que o modelo os leia explicitamente. Turnos simples `/new` e `/reset` são a exceção: o runtime pode prefixar memória diária recente como um bloco único de contexto de inicialização para esse primeiro turno. Arquivos grandes são truncados com um marcador. O tamanho máximo por arquivo é controlado por -`agents.defaults.bootstrapMaxChars` (padrão: 12000). O conteúdo total de inicialização injetado +`agents.defaults.bootstrapMaxChars` (padrão: 12000). O conteúdo total de bootstrap injetado entre arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars` (padrão: 60000). Arquivos ausentes injetam um marcador curto de arquivo ausente. Quando ocorre truncamento, -o OpenClaw pode injetar um bloco de aviso em Contexto do projeto; controle isso com +a OpenClaw pode injetar um aviso conciso no prompt de sistema; controle isso com `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; -padrão: `once`). +padrão: `once`). Contagens brutas/injetadas detalhadas permanecem em diagnósticos como +`/context`, `/status`, doctor e logs. -Sessões de subagente injetam somente `AGENTS.md` e `TOOLS.md` (outros arquivos de inicialização +Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (outros arquivos de bootstrap são filtrados para manter o contexto do subagente pequeno). Hooks internos podem interceptar esta etapa via `agent:bootstrap` para modificar ou substituir -os arquivos de inicialização injetados (por exemplo, trocar `SOUL.md` por uma persona alternativa). +os arquivos de bootstrap injetados (por exemplo, trocar `SOUL.md` por uma persona alternativa). -Se quiser fazer o agente soar menos genérico, comece com -[Guia de personalidade do SOUL.md](/pt-BR/concepts/soul). +Se você quiser fazer o agente soar menos genérico, comece com +[Guia de Personalidade SOUL.md](/pt-BR/concepts/soul). Para inspecionar quanto cada arquivo injetado contribui (bruto vs. injetado, truncamento, além da sobrecarga de esquema de ferramentas), use `/context list` ou `/context detail`. Consulte [Contexto](/pt-BR/concepts/context). ## Tratamento de tempo -O prompt de sistema inclui uma seção dedicada **Data e hora atuais** quando o -fuso horário do usuário é conhecido. Para manter o cache de prompt estável, agora ele inclui somente +O prompt de sistema inclui uma seção dedicada **Data e Hora Atuais** quando o +fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ele inclui apenas o **fuso horário** (sem relógio dinâmico ou formato de hora). Use `session_status` quando o agente precisar da hora atual; o cartão de status -inclui uma linha de carimbo de data/hora. A mesma ferramenta pode opcionalmente definir uma substituição de modelo -por sessão (`model=default` a limpa). +inclui uma linha de timestamp. A mesma ferramenta pode opcionalmente definir uma substituição de modelo por sessão +(`model=default` a limpa). Configure com: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Consulte [Data e hora](/pt-BR/date-time) para detalhes completos de comportamento. +Consulte [Data e Hora](/pt-BR/date-time) para detalhes completos de comportamento. ## Skills -Quando Skills elegíveis existem, o OpenClaw injeta uma **lista compacta de Skills disponíveis** +Quando existem Skills elegíveis, a OpenClaw injeta uma **lista compacta de Skills disponíveis** (`formatSkillsForPrompt`) que inclui o **caminho do arquivo** de cada Skill. O prompt instrui o modelo a usar `read` para carregar o SKILL.md no local listado -(espaço de trabalho, gerenciado ou empacotado). Se nenhuma Skill for elegível, a +(workspace, gerenciado ou empacotado). Se nenhuma Skill for elegível, a seção Skills é omitida. -A elegibilidade inclui regras de metadados de Skills, verificações de ambiente/configuração de runtime -e a lista efetiva de Skills permitidas do agente quando `agents.defaults.skills` ou +A elegibilidade inclui regras de metadados de Skill, verificações de ambiente/configuração de runtime +e a allowlist efetiva de Skills do agente quando `agents.defaults.skills` ou `agents.list[].skills` está configurado. -Skills empacotadas por Plugin são elegíveis somente quando o Plugin proprietário está ativado. -Isso permite que Plugins de ferramentas exponham guias operacionais mais profundos sem incorporar toda +Skills empacotadas em plugins são elegíveis apenas quando seu plugin proprietário está habilitado. +Isso permite que plugins de ferramentas exponham guias operacionais mais aprofundados sem incorporar toda essa orientação diretamente em cada descrição de ferramenta. ``` @@ -238,28 +240,28 @@ essa orientação diretamente em cada descrição de ferramenta. ``` -Isso mantém o prompt base pequeno, ao mesmo tempo que permite o uso direcionado de Skills. +Isso mantém o prompt base pequeno enquanto ainda habilita uso direcionado de Skills. -O orçamento da lista de Skills pertence ao subsistema de Skills: +O orçamento da lista de Skills é de propriedade do subsistema de Skills: - Padrão global: `skills.limits.maxSkillsPromptChars` - Substituição por agente: `agents.list[].skillsLimits.maxSkillsPromptChars` -Excertos genéricos delimitados de runtime usam uma superfície diferente: +Trechos genéricos delimitados em tempo de execução usam uma superfície diferente: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Essa separação mantém o dimensionamento de Skills separado do dimensionamento de leitura/injeção em runtime, como `memory_get`, resultados de ferramentas ao vivo e atualizações pós-Compaction do AGENTS.md. +Essa divisão mantém o dimensionamento de Skills separado do dimensionamento de leitura/injeção em tempo de execução, como `memory_get`, resultados de ferramentas ao vivo e atualizações pós-Compaction de AGENTS.md. ## Documentação -O prompt do sistema inclui uma seção **Documentação**. Quando a documentação local está disponível, ela aponta para o diretório local de documentação do OpenClaw (`docs/` em um checkout Git ou a documentação incluída no pacote npm). Se a documentação local não estiver disponível, ele recorre a [https://docs.openclaw.ai](https://docs.openclaw.ai). +O prompt do sistema inclui uma seção de **Documentação**. Quando a documentação local está disponível, ela aponta para o diretório local de documentação do OpenClaw (`docs/` em um checkout Git ou a documentação do pacote npm incluído). Se a documentação local não estiver disponível, ela recorre a [https://docs.openclaw.ai](https://docs.openclaw.ai). -A mesma seção também inclui a localização do código-fonte do OpenClaw. Checkouts Git expõem a raiz local do código-fonte para que o agente possa inspecionar o código diretamente. Instalações de pacote incluem a URL do código-fonte no GitHub e orientam o agente a revisar o código-fonte lá sempre que a documentação estiver incompleta ou desatualizada. O prompt também menciona o espelho público da documentação, o Discord da comunidade e o ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descoberta de Skills. Ele orienta o modelo a consultar a documentação primeiro para comportamento, comandos, configuração ou arquitetura do OpenClaw, e a executar `openclaw status` por conta própria quando possível (perguntando ao usuário apenas quando não tiver acesso). Especificamente para configuração, ele direciona os agentes para a ação de ferramenta `gateway` `config.schema.lookup` para documentação e restrições exatas em nível de campo, depois para `docs/gateway/configuration.md` e `docs/gateway/configuration-reference.md` para orientações mais amplas. +A mesma seção também inclui a localização do código-fonte do OpenClaw. Checkouts Git expõem a raiz local do código-fonte para que o agente possa inspecionar o código diretamente. Instalações de pacote incluem a URL do código-fonte no GitHub e instruem o agente a revisar o código-fonte ali sempre que a documentação estiver incompleta ou desatualizada. O prompt também menciona o espelho público da documentação, o Discord da comunidade e o ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descoberta de Skills. Ele instrui o modelo a consultar a documentação primeiro para comportamento, comandos, configuração ou arquitetura do OpenClaw, e a executar `openclaw status` por conta própria quando possível (perguntando ao usuário apenas quando não tiver acesso). Especificamente para configuração, ele direciona agentes para a ação de ferramenta `gateway` `config.schema.lookup` para documentação e restrições exatas no nível dos campos, depois para `docs/gateway/configuration.md` e `docs/gateway/configuration-reference.md` para orientação mais ampla. -## Relacionado +## Relacionados -- [Runtime do agente](/pt-BR/concepts/agent) -- [Workspace do agente](/pt-BR/concepts/agent-workspace) +- [Tempo de execução do agente](/pt-BR/concepts/agent) +- [Espaço de trabalho do agente](/pt-BR/concepts/agent-workspace) - [Mecanismo de contexto](/pt-BR/concepts/context-engine)