diff --git a/docs/pt-BR/channels/discord.md b/docs/pt-BR/channels/discord.md index 38c47f761..191c806aa 100644 --- a/docs/pt-BR/channels/discord.md +++ b/docs/pt-BR/channels/discord.md @@ -1,74 +1,74 @@ --- read_when: - - Trabalhando em recursos do canal Discord -summary: Status de suporte do bot do Discord, recursos e configuração + - Trabalhando nos recursos do canal Discord +summary: Status do suporte ao bot do Discord, capacidades e configuração title: Discord x-i18n: - generated_at: "2026-04-09T01:29:19Z" + generated_at: "2026-04-21T17:45:32Z" model: gpt-5.4 provider: openai - source_hash: 3cd2886fad941ae2129e681911309539e9a65a2352b777b538d7f4686a68f73f + source_hash: 1681315a6c246c4b68347f5e22319e132f30ea4e29a19e7d1da9e83dce7b68d0 source_path: channels/discord.md workflow: 15 --- -# Discord (Bot API) +# Discord (API de Bot) -Status: pronto para DMs e canais de servidor via gateway oficial do Discord. +Status: pronto para DMs e canais de servidor via o gateway oficial do Discord. As DMs do Discord usam o modo de pareamento por padrão. - + Comportamento nativo de comandos e catálogo de comandos. - - Diagnósticos e fluxo de reparo entre canais. + + Diagnósticos entre canais e fluxo de reparo. ## Configuração rápida -Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu servidor e pareá-lo com o OpenClaw. Recomendamos adicionar seu bot ao seu próprio servidor privado. Se você ainda não tiver um, [crie um primeiro](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (escolha **Create My Own > For me and my friends**). +Você precisará criar uma nova aplicação com um bot, adicionar o bot ao seu servidor e pareá-lo com o OpenClaw. Recomendamos adicionar seu bot ao seu próprio servidor privado. Se você ainda não tiver um, [crie um primeiro](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (escolha **Create My Own > For me and my friends**). - - Vá para o [Discord Developer Portal](https://discord.com/developers/applications) e clique em **New Application**. Dê a ele um nome como "OpenClaw". + + Acesse o [Portal do Desenvolvedor do Discord](https://discord.com/developers/applications) e clique em **New Application**. Dê um nome como "OpenClaw". - Clique em **Bot** na barra lateral. Defina o **Username** como o nome que você dá ao seu agente OpenClaw. + Clique em **Bot** na barra lateral. Defina o **Username** como o nome que você usa para seu agente OpenClaw. - - Ainda na página **Bot**, role para baixo até **Privileged Gateway Intents** e habilite: + + 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ção 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 por função e correspondência de nome para ID) + - **Presence Intent** (opcional; necessário apenas para atualizações de presença) - Role de volta para cima na página **Bot** e clique em **Reset Token**. + Role para cima novamente na página **Bot** e clique em **Reset Token**. Apesar do nome, isso gera seu primeiro token — nada está sendo "redefinido". - Copie o token e salve-o em algum lugar. Este é o seu **Bot Token** e você precisará dele em breve. + Copie o token e salve-o em algum lugar. Esse é o seu **Bot Token** e você precisará dele em breve. Clique em **OAuth2** na barra lateral. Você vai gerar uma URL de convite com as permissões corretas para adicionar o bot ao seu servidor. - Role para baixo até **OAuth2 URL Generator** e habilite: + Role para baixo até **OAuth2 URL Generator** e ative: - `bot` - `applications.commands` - Uma seção **Bot Permissions** aparecerá abaixo. Habilite: + Uma seção **Bot Permissions** aparecerá abaixo. Ative: - View Channels - Send Messages @@ -77,12 +77,12 @@ Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu ser - Attach Files - Add Reactions (opcional) - 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 do Discord. + Copie a URL gerada na parte inferior, cole-a no navegador, selecione seu servidor e clique em **Continue** para conectar. Agora você deverá ver seu bot no servidor do Discord. - - De volta ao app do Discord, você precisa habilitar o Modo de Desenvolvedor para poder copiar IDs internos. + + De volta ao aplicativo do Discord, você precisa ativar o Modo Desenvolvedor para poder copiar IDs internos. 1. Clique em **User Settings** (ícone de engrenagem ao lado do seu avatar) → **Advanced** → ative **Developer Mode** 2. Clique com o botão direito no **ícone do seu servidor** na barra lateral → **Copy Server ID** @@ -93,14 +93,14 @@ Você precisará criar um novo aplicativo com um bot, adicionar o bot ao seu ser - Para que o pareamento funcione, o Discord precisa permitir que seu bot envie DMs para você. Clique com o botão direito no **ícone do seu servidor** → **Privacy Settings** → ative **Direct Messages**. + 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 seu servidor** → **Privacy Settings** → ative **Direct Messages**. - Isso permite que membros do servidor (incluindo bots) enviem DMs para você. Mantenha isso ativado se quiser usar DMs do Discord com o OpenClaw. Se você pretende usar apenas canais do servidor, pode desativar as 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 servidor, pode desativar DMs após o pareamento. - - O token do seu bot do Discord é um segredo (como uma senha). Defina-o na máquina que executa o OpenClaw antes de enviar mensagens ao seu agente. + + O token do seu bot do Discord é um segredo (como uma senha). Defina-o na máquina que executa o OpenClaw antes de enviar mensagem ao seu agente. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,7 +110,7 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Se o OpenClaw já estiver em execução como um serviço em segundo plano, reinicie-o pelo app OpenClaw para Mac ou parando e reiniciando o processo `openclaw gateway run`. + Se o OpenClaw já estiver em execução como um serviço em segundo plano, reinicie-o pelo app Mac do OpenClaw ou parando e reiniciando o processo `openclaw gateway run`. @@ -118,9 +118,9 @@ openclaw gateway - Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e diga a ele. Se o Discord for seu primeiro canal, use a aba CLI / config em vez disso. + Converse com seu agente OpenClaw em qualquer canal existente (por exemplo, Telegram) e diga isso a ele. Se o Discord for seu primeiro canal, use a aba CLI / config. - > "Já configurei meu token do bot do Discord na config. Conclua a configuração do Discord com o User ID `` e o Server ID ``." + > "Já defini meu token do bot do Discord na configuração. Conclua a configuração do Discord com o User ID `` e o Server ID ``." Se você preferir configuração baseada em arquivo, defina: @@ -146,7 +146,7 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - Valores `token` em texto simples são suportados. Valores SecretRef também são suportados para `channels.discord.token` nos providers env/file/exec. Veja [Gerenciamento de segredos](/pt-BR/gateway/secrets). + Valores `token` em texto simples são suportados. Valores SecretRef também são suportados para `channels.discord.token` em provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). @@ -174,27 +174,27 @@ openclaw pairing approve discord Os códigos de pareamento expiram após 1 hora. - Agora você deve conseguir conversar com seu agente no Discord via DM. + Agora você já deve conseguir conversar com seu agente no Discord por DM. -A resolução de token reconhece contas. Valores de token na config têm prioridade sobre o fallback de env. `DISCORD_BOT_TOKEN` é usado apenas para a conta padrão. -Para chamadas avançadas de saída (ferramenta de mensagem/ações de canal), um `token` explícito por chamada é usado para aquela chamada. Isso se aplica a ações de envio e de leitura/sondagem (por exemplo, read/search/fetch/thread/pins/permissions). As configurações de política/retry da conta ainda vêm da conta selecionada no snapshot ativo do runtime. +A resolução de token considera a conta. Valores de token na configuração têm prioridade sobre o fallback de env. `DISCORD_BOT_TOKEN` é usado apenas para a conta padrão. +Para chamadas avançadas de saída (ferramenta de mensagem/ações de canal), um `token` explícito por chamada é usado nessa chamada. Isso se aplica a ações de envio e de leitura/sondagem (por exemplo, read/search/fetch/thread/pins/permissions). As configurações de política de conta/repetição ainda vêm da conta selecionada no snapshot de runtime ativo. ## Recomendado: configurar um workspace de servidor -Quando as DMs estiverem funcionando, você poderá configurar seu servidor do 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 onde há apenas você e seu bot. +Quando as DMs estiverem funcionando, você poderá configurar seu servidor do 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 onde só estão você e seu bot. - - Isso permite que seu agente responda em qualquer canal do seu servidor, não apenas em DMs. + + Isso permite que seu agente responda em qualquer canal no seu servidor, não apenas em DMs. - > "Adicione meu Server ID do Discord `` à allowlist de servidores" + > "Adicione meu Server ID do Discord `` à lista de permissões de servidores" @@ -220,11 +220,11 @@ Quando as DMs estiverem funcionando, você poderá configurar seu servidor do Di - Por padrão, seu agente só responde em canais de servidor quando é mencionado com @. Em um servidor privado, você provavelmente vai querer que ele responda a todas as mensagens. + Por padrão, seu agente só responde em canais de servidor quando é mencionado com @. Em um servidor privado, provavelmente você vai querer que ele responda a toda mensagem. - > "Permita que meu agente responda neste servidor sem precisar ser mencionado com @" + > "Permita que meu agente responda neste servidor sem precisar ser @mencionado" Defina `requireMention: false` na configuração do seu servidor: @@ -249,39 +249,39 @@ Quando as DMs estiverem funcionando, você poderá configurar seu servidor do Di - 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`) só é carregada em sessões de DM. Canais de servidor 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." - Se você precisar de contexto compartilhado em todos os canais, coloque as instruções estáveis em `AGENTS.md` ou `USER.md` (eles são injetados em toda sessão). Mantenha notas de longo prazo em `MEMORY.md` e acesse-as sob demanda com as 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` (eles são injetados em toda sessão). 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 do 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 melhor se encaixar no seu fluxo de trabalho. +Agora crie alguns canais no seu servidor do 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 fizer sentido para seu fluxo de trabalho. ## Modelo de runtime -- O gateway é responsável pela conexão com o Discord. -- O roteamento de respostas é determinístico: respostas recebidas do Discord voltam para o Discord. -- Por padrão (`session.dmScope=main`), chats diretos compartilham a sessão principal do agente (`agent:main:main`). -- Canais de servidor usam chaves de sessão isoladas (`agent::discord:channel:`). +- O Gateway controla a conexão com o Discord. +- O roteamento de respostas é determinístico: mensagens recebidas do Discord respondem de volta no Discord. +- Por padrão (`session.dmScope=main`), conversas diretas compartilham a sessão principal do agente (`agent:main:main`). +- Canais de servidor são chaves de sessão isoladas (`agent::discord:channel:`). - DMs em grupo são ignoradas por padrão (`channels.discord.dm.groupEnabled=false`). -- Comandos de barra nativos são executados em sessões de comando isoladas (`agent::discord:slash:`), enquanto ainda carregam `CommandTargetSessionKey` para a sessão de conversa roteada. +- Comandos slash nativos são executados em sessões de comando isoladas (`agent::discord:slash:`), enquanto ainda carregam `CommandTargetSessionKey` para a sessão de conversa roteada. ## Canais de fórum -Canais de fórum e mídia do Discord aceitam apenas postagens em tópicos. O OpenClaw oferece suporte a duas formas de criá-los: +Canais de fórum e mídia do Discord aceitam apenas postagens em tópicos. O OpenClaw oferece duas formas de criá-las: -- Envie uma mensagem para o pai do fórum (`channel:`) para criar um tópico automaticamente. O título do tópico usa a primeira linha não vazia da sua mensagem. +- Envie uma mensagem para o pai do fórum (`channel:`) para criar automaticamente um tópico. O título do tópico usa a primeira linha não vazia da sua mensagem. - Use `openclaw message thread create` para criar um tópico diretamente. Não passe `--message-id` para canais de fórum. -Exemplo: enviar ao pai do fórum para criar um tópico +Exemplo: enviar para o pai do fórum para criar um tópico ```bash openclaw message send --channel discord --target channel: \ @@ -299,7 +299,7 @@ Pais de fórum não aceitam componentes do Discord. Se você precisar de compone ## Componentes interativos -O OpenClaw oferece suporte a contêineres Discord components v2 para mensagens do agente. Use a ferramenta de mensagem com uma carga `components`. Os resultados de interação são roteados de volta ao 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 do agente. Use a ferramenta de mensagem com uma carga `components`. Os resultados de interação são roteados de volta ao agente como mensagens recebidas normais e seguem as configurações existentes de `replyToMode` do Discord. Blocos compatíveis: @@ -307,23 +307,23 @@ Blocos compatíveis: - Linhas de ação permitem até 5 botões ou um único menu de seleção - Tipos de seleção: `string`, `user`, `role`, `mentionable`, `channel` -Por padrão, componentes são de uso único. Defina `components.reusable=true` para permitir que botões, seleções e formulários sejam usados várias vezes até expirarem. +Por padrão, os componentes são de uso único. Defina `components.reusable=true` para permitir que botões, seleções e formulários sejam usados várias vezes até expirarem. Para restringir quem pode clicar em um botão, defina `allowedUsers` nesse botão (IDs de usuário do Discord, tags ou `*`). Quando configurado, usuários sem correspondência recebem uma negação efêmera. -Os comandos de barra `/model` e `/models` abrem um seletor de modelo interativo com menus suspensos de provider e modelo, além de uma etapa Submit. A resposta do seletor é efêmera e apenas o usuário que a invocou pode usá-la. +Os comandos slash `/model` e `/models` abrem um seletor interativo de modelo com menus suspensos de provedor e modelo, além de uma etapa de envio. A resposta do seletor é efêmera e apenas o usuário que a invocou pode usá-la. 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 de anexo +- Use `filename` para substituir o nome do upload quando ele precisar 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 automaticamente um botão de gatilho +- O OpenClaw adiciona um botão de acionamento automaticamente Exemplo: @@ -332,45 +332,45 @@ Exemplo: channel: "discord", action: "send", to: "channel:123456789012345678", - message: "Optional fallback text", + message: "Texto de fallback opcional", components: { reusable: true, - text: "Choose a path", + text: "Escolha um caminho", blocks: [ { type: "actions", buttons: [ { - label: "Approve", + label: "Aprovar", style: "success", allowedUsers: ["123456789012345678"], }, - { label: "Decline", style: "danger" }, + { label: "Recusar", style: "danger" }, ], }, { type: "actions", select: { type: "string", - placeholder: "Pick an option", + placeholder: "Escolha uma opção", options: [ - { label: "Option A", value: "a" }, - { label: "Option B", value: "b" }, + { label: "Opção A", value: "a" }, + { label: "Opção B", value: "b" }, ], }, }, ], modal: { - title: "Details", - triggerLabel: "Open form", + title: "Detalhes", + triggerLabel: "Abrir formulário", fields: [ - { type: "text", label: "Requester" }, + { type: "text", label: "Solicitante" }, { type: "select", - label: "Priority", + label: "Prioridade", options: [ - { label: "Low", value: "low" }, - { label: "High", value: "high" }, + { label: "Baixa", value: "low" }, + { label: "Alta", value: "high" }, ], }, ], @@ -390,20 +390,20 @@ Exemplo: - `open` (exige que `channels.discord.allowFrom` inclua `"*"`; legado: `channels.discord.dm.allowFrom`) - `disabled` - Se a política de DM não for open, usuários desconhecidos serão bloqueados (ou convidados a parear no modo `pairing`). + Se a política de DM não estiver aberta, usuários desconhecidos serão bloqueados (ou solicitados a fazer o pareamento no modo `pairing`). - Precedência com múltiplas contas: + Precedência para várias contas: - `channels.discord.accounts.default.allowFrom` se aplica apenas à conta `default`. - - Contas nomeadas herdam `channels.discord.allowFrom` quando o próprio `allowFrom` não está definido. + - Contas nomeadas herdam `channels.discord.allowFrom` quando seu próprio `allowFrom` não está definido. - Contas nomeadas não herdam `channels.discord.accounts.default.allowFrom`. - Formato do alvo de DM para entrega: + Formato de destino de DM para entrega: - `user:` - menção `<@id>` - IDs numéricos sem qualificador são ambíguos e rejeitados, a menos que um tipo explícito de alvo user/channel seja fornecido. + IDs numéricos sem qualificador são ambíguos e rejeitados, a menos que um tipo explícito de destino de usuário/canal seja fornecido. @@ -418,12 +418,12 @@ Exemplo: Comportamento de `allowlist`: - - o servidor deve corresponder a `channels.discord.guilds` (`id` preferido, slug aceito) - - allowlists opcionais de remetente: `users` (IDs estáveis recomendados) e `roles` (somente IDs de função); se qualquer uma estiver configurada, remetentes são permitidos quando correspondem a `users` OU `roles` - - correspondência direta por nome/tag é desativada por padrão; habilite `channels.discord.dangerouslyAllowNameMatching: true` apenas como modo de compatibilidade emergencial - - nomes/tags são suportados para `users`, mas IDs são mais seguros; `openclaw security audit` alerta quando entradas de nome/tag são usadas + - o servidor deve corresponder a `channels.discord.guilds` (`id` é preferido, slug é aceito) + - listas opcionais de remetentes permitidos: `users` (IDs estáveis recomendados) e `roles` (apenas IDs de função); se qualquer um estiver configurado, remetentes serão permitidos quando corresponderem a `users` OU `roles` + - correspondência direta por nome/tag é desativada por padrão; ative `channels.discord.dangerouslyAllowNameMatching: true` apenas como modo de compatibilidade de último recurso + - nomes/tags são compatíveis para `users`, mas IDs são mais seguros; `openclaw security audit` avisa quando entradas de nome/tag são usadas - se um servidor tiver `channels` configurado, canais não listados serão negados - - se um servidor não tiver bloco `channels`, todos os canais nesse servidor presente na allowlist serão permitidos + - se um servidor não tiver um bloco `channels`, todos os canais desse servidor na allowlist serão permitidos Exemplo: @@ -449,12 +449,12 @@ Exemplo: } ``` - Se você apenas definir `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 de runtime será `groupPolicy="allowlist"` (com um aviso nos logs), mesmo que `channels.defaults.groupPolicy` seja `open`. - Mensagens de servidor são bloqueadas por menção por padrão. + Mensagens de servidor são controladas por menção por padrão. A detecção de menção inclui: @@ -475,7 +475,7 @@ Exemplo: ### Roteamento de agente baseado em função -Use `bindings[].match.roles` para rotear membros de servidores do Discord para agentes diferentes por ID de função. Bindings baseados em função aceitam apenas IDs de função e são avaliados após bindings de peer ou parent-peer e antes de bindings somente de servidor. 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 servidores do Discord para agentes diferentes por ID de função. Bindings baseados em função aceitam apenas IDs de função e são avaliados após bindings de peer ou parent-peer e antes de bindings apenas de servidor. Se um binding também definir outros campos de correspondência (por exemplo, `peer` + `guildId` + `roles`), todos os campos configurados devem corresponder. ```json5 { @@ -499,33 +499,33 @@ Use `bindings[].match.roles` para rotear membros de servidores do Discord para a } ``` -## Configuração do Developer Portal +## Configuração do Portal do Desenvolvedor - 1. Discord Developer Portal -> **Applications** -> **New Application** + 1. Portal do Desenvolvedor do Discord -> **Applications** -> **New Application** 2. **Bot** -> **Add Bot** 3. Copie o token do bot - Em **Bot -> Privileged Gateway Intents**, habilite: + Em **Bot -> Privileged Gateway Intents**, ative: - Message Content Intent - Server Members Intent (recomendado) - Presence intent é opcional e necessária apenas se você quiser receber atualizações de presença. Definir a presença do bot (`setPresence`) não exige habilitar atualizações de presença para membros. + Presence intent é opcional e necessária apenas se você quiser receber atualizações de presença. Definir a presença do bot (`setPresence`) não exige ativar atualizações de presença para membros. - + Gerador de URL OAuth: - escopos: `bot`, `applications.commands` - Permissões típicas de linha de base: + Permissões básicas típicas: - View Channels - Send Messages @@ -539,32 +539,32 @@ Use `bindings[].match.roles` para rotear membros de servidores do Discord para a - Habilite o Discord Developer Mode e então copie: + Ative o Modo Desenvolvedor do Discord e depois copie: - ID do servidor - ID do canal - ID do usuário - Prefira IDs numéricos na config do OpenClaw para auditorias e sondagens confiáveis. + Prefira IDs numéricos na configuração do OpenClaw para auditorias e sondagens confiáveis. ## Comandos nativos e autenticação de comandos -- `commands.native` usa `"auto"` por padrão e está habilitado para Discord. +- `commands.native` usa `"auto"` por padrão e está ativado para Discord. - Substituição por canal: `channels.discord.commands.native`. - `commands.native=false` remove explicitamente comandos nativos do Discord registrados anteriormente. - A autenticação de comandos nativos usa as mesmas allowlists/políticas do Discord que o tratamento normal de mensagens. -- Os comandos ainda podem ficar visíveis na interface do Discord para usuários não autorizados; a execução ainda aplica a autenticação do OpenClaw e retorna "not authorized". +- Os comandos ainda podem ficar visíveis na interface do Discord para usuários não autorizados; a execução ainda aplica a autenticação do OpenClaw e retorna "não autorizado". -Consulte [Comandos de barra](/pt-BR/tools/slash-commands) para catálogo e comportamento de comandos. +Consulte [Comandos slash](/pt-BR/tools/slash-commands) para o catálogo e o comportamento dos comandos. -Configurações padrão dos comandos de barra: +Configurações padrão de comandos slash: - `ephemeral: true` -## Detalhes do recurso +## Detalhes dos recursos @@ -581,25 +581,26 @@ Configurações padrão dos comandos de barra: - `batched` Observação: `off` desativa o encadeamento implícito de respostas. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. - `first` sempre anexa a referência implícita de resposta nativa à primeira mensagem enviada pelo Discord no turno. + `first` sempre anexa a referência implícita de resposta nativa à primeira mensagem de saída do Discord no turno. `batched` só anexa a referência implícita de resposta nativa do Discord quando o - turno de entrada foi um lote com debounce de várias mensagens. Isso é útil - quando você quer respostas nativas principalmente para chats ambíguos e intensos, não para todo + turno de entrada foi um lote com debounce de múltiplas mensagens. Isso é útil + quando você quer respostas nativas principalmente para chats ambíguos com rajadas, não para todo 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 aparecem em contexto/histórico para que agentes possam direcionar mensagens específicas. - + O OpenClaw pode transmitir respostas em rascunho enviando uma mensagem temporária e editando-a à medida que o texto chega. - - `channels.discord.streaming` controla a transmissão de prévia (`off` | `partial` | `block` | `progress`, padrão: `off`). - - O padrão continua sendo `off` porque edições de prévia no Discord podem atingir limites de taxa rapidamente, especialmente quando vários bots ou gateways compartilham a mesma conta ou tráfego do servidor. - - `progress` é aceito para consistência entre canais e mapeia para `partial` no Discord. + - `channels.discord.streaming` controla o streaming de prévia (`off` | `partial` | `block` | `progress`, padrão: `off`). + - O padrão continua sendo `off` porque edições de prévia no Discord podem atingir limites de taxa rapidamente, especialmente quando vários bots ou gateways compartilham a mesma conta ou tráfego de servidor. + - `progress` é aceito para consistência entre canais e é mapeado para `partial` no Discord. - `channels.discord.streamMode` é um alias legado e é migrado automaticamente. - `partial` edita uma única mensagem de prévia à medida que os tokens chegam. - `block` emite blocos do tamanho de rascunho (use `draftChunk` para ajustar tamanho e pontos de quebra). + - `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia de rascunho (padrão: `true`). Defina como `false` para manter mensagens separadas de ferramenta/progresso. Exemplo: @@ -630,15 +631,15 @@ Configurações padrão dos comandos de barra: } ``` - A transmissão de prévia é somente texto; respostas com mídia recorrem à entrega normal. + O streaming de prévia é apenas de texto; respostas com mídia recorrem à entrega normal. - Observação: a transmissão de prévia é separada da transmissão em blocos. Quando a transmissão em blocos é explicitamente - habilitada para o Discord, o OpenClaw ignora a stream de prévia para evitar transmissão dupla. + Observação: o streaming de prévia é separado do streaming em blocos. Quando o streaming em blocos é explicitamente + ativado para Discord, o OpenClaw ignora o fluxo de prévia para evitar streaming duplo. - Contexto de histórico do servidor: + Contexto do histórico de servidor: - `channels.discord.historyLimit` padrão `20` - fallback: `messages.groupChat.historyLimit` @@ -652,27 +653,27 @@ Configurações padrão dos comandos de barra: Comportamento de tópicos: - tópicos do Discord são roteados como sessões de canal - - metadados do tópico pai podem ser usados para vínculo com a sessão pai - - a config do tópico herda a config do canal pai, a menos que exista uma entrada específica para o tópico + - metadados do tópico pai podem ser usados para vinculação à sessão pai + - a configuração do tópico herda a configuração do canal pai, a menos que exista uma entrada específica para o tópico - Os tópicos de canal são injetados como contexto **não confiável** (não como prompt do sistema). + Tópicos de canal são injetados como contexto **não confiável** (não como prompt de sistema). O contexto de resposta e de mensagem citada atualmente permanece como recebido. - Allowlists do Discord controlam principalmente quem pode acionar o agente, e não um limite completo de redação de contexto suplementar. + As allowlists do Discord controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar. - O Discord pode vincular um tópico a um alvo de sessão para que mensagens de acompanhamento nesse tópico continuem sendo roteadas para a mesma sessão (incluindo sessões de subagente). + O Discord pode vincular um tópico a um destino de sessão para que mensagens subsequentes nesse tópico continuem sendo roteadas para a mesma sessão (incluindo sessões de subagente). Comandos: - - `/focus ` vincula o tópico atual/novo a um alvo de subagente/sessão + - `/focus ` vincula o tópico atual/novo a um destino de subagente/sessão - `/unfocus` remove o vínculo do tópico atual - - `/agents` mostra execuções ativas e o estado do vínculo + - `/agents` mostra execuções ativas e estado do vínculo - `/session idle ` inspeciona/atualiza o desfoco automático por inatividade para vínculos focados - `/session max-age ` inspeciona/atualiza a idade máxima rígida para vínculos focados - Config: + Configuração: ```json5 { @@ -689,7 +690,7 @@ Configurações padrão dos comandos de barra: enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in + spawnSubagentSessions: false, // adesão explícita }, }, }, @@ -700,18 +701,18 @@ Configurações padrão dos comandos de barra: - `session.threadBindings.*` define padrões globais. - `channels.discord.threadBindings.*` substitui o comportamento do Discord. - - `spawnSubagentSessions` deve ser true para criar/vincular automaticamente tópicos para `sessions_spawn({ thread: true })`. - - `spawnAcpSessions` deve ser true para criar/vincular automaticamente tópicos para ACP (`/acp spawn ... --thread ...` ou `sessions_spawn({ runtime: "acp", thread: true })`). - - Se os vínculos de tópico estiverem desabilitados para uma conta, `/focus` e operações relacionadas de vínculo de tópico ficarão indisponíveis. + - `spawnSubagentSessions` deve ser `true` para criar/vincular automaticamente tópicos para `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` deve ser `true` para criar/vincular automaticamente tópicos para ACP (`/acp spawn ... --thread ...` ou `sessions_spawn({ runtime: "acp", thread: true })`). + - Se os vínculos de tópico estiverem desativados para uma conta, `/focus` e operações relacionadas de vínculo de tópico ficarão indisponíveis. - Consulte [Sub-agents](/pt-BR/tools/subagents), [ACP Agents](/pt-BR/tools/acp-agents) e [Referência de configuração](/pt-BR/gateway/configuration-reference). + Consulte [Sub-agentes](/pt-BR/tools/subagents), [Agentes ACP](/pt-BR/tools/acp-agents) e [Referência de configuração](/pt-BR/gateway/configuration-reference). - - Para workspaces ACP estáveis e "sempre ativos", configure vínculos ACP tipados no nível superior direcionados a conversas do Discord. + + Para workspaces ACP estáveis "sempre ativos", configure bindings ACP tipados de nível superior direcionados a conversas do Discord. - Caminho de config: + Caminho de configuração: - `bindings[]` com `type: "acp"` e `match.channel: "discord"` @@ -765,15 +766,15 @@ Configurações padrão dos comandos de barra: Observações: - - `/acp spawn codex --bind here` vincula o canal ou tópico atual do Discord no local e mantém mensagens futuras roteadas para a mesma sessão ACP. + - `/acp spawn codex --bind here` vincula o canal ou tópico atual do Discord no mesmo lugar e mantém mensagens futuras roteadas para a mesma sessão ACP. - Isso ainda pode significar "iniciar uma nova sessão ACP do Codex", mas não cria um novo tópico do Discord por si só. O canal existente continua sendo a superfície de chat. - - O Codex ainda pode ser executado em seu próprio `cwd` ou workspace de backend em disco. Esse workspace é estado de runtime, não um tópico do Discord. - - Mensagens do tópico podem herdar o vínculo ACP do canal pai. - - Em um canal ou tópico vinculado, `/new` e `/reset` redefinem a mesma sessão ACP no local. - - Vínculos temporários de tópico ainda funcionam e podem substituir a resolução do alvo enquanto ativos. - - `spawnAcpSessions` só é necessário quando o OpenClaw precisa criar/vincular um tópico filho via `--thread auto|here`. Não é necessário para `/acp spawn ... --bind here` no canal atual. + - O Codex ainda pode ser executado em seu próprio `cwd` ou workspace de backend no disco. Esse workspace é estado de runtime, não um tópico do Discord. + - Mensagens de tópico podem herdar o binding ACP do canal pai. + - Em um canal ou tópico vinculado, `/new` e `/reset` redefinem a mesma sessão ACP no mesmo lugar. + - Bindings temporários de tópico ainda funcionam e podem substituir a resolução do alvo enquanto estiverem ativos. + - `spawnAcpSessions` só é necessário quando o OpenClaw precisa criar/vincular um tópico filho por meio de `--thread auto|here`. Não é necessário para `/acp spawn ... --bind here` no canal atual. - Consulte [ACP Agents](/pt-BR/tools/acp-agents) para detalhes sobre o comportamento de vínculo. + Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para detalhes sobre o comportamento de binding. @@ -785,7 +786,7 @@ Configurações padrão dos comandos de barra: - `all` - `allowlist` (usa `guilds..users`) - Eventos de reação são transformados em eventos do sistema e anexados à sessão do Discord roteada. + Eventos de reação são transformados em eventos de sistema e anexados à sessão do Discord roteada. @@ -797,19 +798,19 @@ Configurações padrão dos comandos de barra: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, senão "👀") + - fallback para o emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") Observações: - O Discord aceita emoji unicode ou nomes de emoji personalizados. - - Use `""` para desativar a reação para um canal ou conta. + - Use `""` para desativar a reação em um canal ou conta. - - Gravações de config iniciadas pelo canal são habilitadas por padrão. + + Gravações de configuração iniciadas pelo canal são ativadas por padrão. - Isso afeta os fluxos `/config set|unset` (quando os recursos de comando estão habilitados). + Isso afeta os fluxos `/config set|unset` (quando os recursos de comando estão ativados). Desativar: @@ -825,8 +826,8 @@ Configurações padrão dos comandos de barra: - - Roteie o tráfego WebSocket do gateway do Discord e as consultas REST de inicialização (ID do aplicativo + resolução de allowlist) por um proxy HTTP(S) com `channels.discord.proxy`. + + Roteie o tráfego WebSocket do gateway do Discord e as consultas REST de inicialização (ID da aplicação + resolução de allowlist) por um proxy HTTP(S) com `channels.discord.proxy`. ```json5 { @@ -857,7 +858,7 @@ Configurações padrão dos comandos de barra: - Habilite a resolução do PluralKit para mapear mensagens com proxy para a identidade do membro do sistema: + Ative a resolução do PluralKit para mapear mensagens proxy para a identidade do membro do sistema: ```json5 { @@ -865,7 +866,7 @@ Configurações padrão dos comandos de barra: discord: { pluralkit: { enabled: true, - token: "pk_live_...", // optional; needed for private systems + token: "pk_live_...", // opcional; necessário para sistemas privados }, }, }, @@ -875,16 +876,16 @@ Configurações padrão dos comandos de barra: Observações: - allowlists podem usar `pk:` - - nomes de exibição de membro são correspondidos por nome/slug apenas quando `channels.discord.dangerouslyAllowNameMatching: true` - - buscas usam o ID da mensagem original e são restritas por janela de tempo - - se a busca falhar, mensagens com proxy são tratadas como mensagens de bot e descartadas, a menos que `allowBots=true` + - nomes de exibição de membros são correspondidos por nome/slug apenas quando `channels.discord.dangerouslyAllowNameMatching: true` + - buscas usam o ID original da mensagem e são limitadas por janela de tempo + - se a busca falhar, mensagens proxy serão tratadas como mensagens de bot e descartadas, a menos que `allowBots=true` - Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando habilita presença automática. + Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando ativa a presença automática. - Exemplo apenas de status: + Exemplo apenas com status: ```json5 { @@ -902,7 +903,7 @@ Configurações padrão dos comandos de barra: { channels: { discord: { - activity: "Focus time", + activity: "Tempo de foco", activityType: 4, }, }, @@ -915,7 +916,7 @@ Configurações padrão dos comandos de barra: { channels: { discord: { - activity: "Live coding", + activity: "Programação ao vivo", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, @@ -923,14 +924,14 @@ Configurações padrão dos comandos de barra: } ``` - Mapa de tipo de atividade: + Mapa de tipos de atividade: - - 0: Playing - - 1: Streaming (exige `activityUrl`) - - 2: Listening - - 3: Watching - - 4: Custom (usa o texto da atividade como estado do status; emoji é opcional) - - 5: Competing + - 0: Jogando + - 1: Streaming (requer `activityUrl`) + - 2: Ouvindo + - 3: Assistindo + - 4: Personalizado (usa o texto da atividade como estado do status; emoji é opcional) + - 5: Competindo Exemplo de presença automática (sinal de integridade do runtime): @@ -942,57 +943,57 @@ Configurações padrão dos comandos de barra: enabled: true, intervalMs: 30000, minUpdateIntervalMs: 15000, - exhaustedText: "token exhausted", + exhaustedText: "token esgotado", }, }, }, } ``` - A presença automática mapeia a disponibilidade do runtime para o status do Discord: saudável => online, degradado ou desconhecido => idle, esgotado ou indisponível => dnd. Substituições opcionais de texto: + A presença automática mapeia a disponibilidade do runtime para o status do Discord: saudável => online, degradado ou desconhecido => idle, esgotado ou indisponível => dnd. Substituições de texto opcionais: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (oferece suporte ao placeholder `{reason}`) + - `autoPresence.exhaustedText` (suporta o placeholder `{reason}`) O Discord oferece suporte ao tratamento de aprovações com botões em DMs e pode opcionalmente publicar prompts de aprovação no canal de origem. - Caminho de config: + Caminho de configuração: - `channels.discord.execApprovals.enabled` - `channels.discord.execApprovals.approvers` (opcional; usa fallback para `commands.ownerAllowFrom` quando possível) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - O Discord habilita automaticamente aprovações exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja a partir de `execApprovals.approvers` ou de `commands.ownerAllowFrom`. O Discord não infere aprovadores exec a partir de `allowFrom` do canal, `dm.allowFrom` legado ou `defaultTo` de mensagem direta. Defina `enabled: false` para desabilitar explicitamente o Discord como cliente nativo de aprovação. + O Discord ativa automaticamente aprovações exec nativas quando `enabled` não está definido ou está como `"auto"` e pelo menos um aprovador pode ser resolvido, seja por `execApprovals.approvers` ou por `commands.ownerAllowFrom`. O Discord não infere aprovadores exec a partir de `allowFrom` do canal, `dm.allowFrom` legado ou `defaultTo` de mensagem direta. Defina `enabled: false` para desativar explicitamente o Discord como cliente nativo de aprovação. - 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 no canal apenas em canais confiáveis. Se o ID do canal não puder ser derivado da chave de sessão, o OpenClaw recorre à entrega por DM. + Quando `target` é `channel` ou `both`, o prompt de aprovação fica visível no canal. 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, portanto só ative a entrega no canal em canais confiáveis. Se o ID do canal não puder ser derivado da chave da sessão, o OpenClaw usa fallback para entrega por DM. - O Discord também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Discord adiciona principalmente roteamento de DM para aprovadores e fanout para canal. + 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 o roteamento de DM para aprovadores e a distribuição para o canal. Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser - que aprovações via chat não estão disponíveis ou que a aprovação manual é o único caminho. + que aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho. - A autenticação do gateway para esse manipulador usa o mesmo contrato compartilhado de resolução de credenciais que outros clientes do gateway: + A autenticação do Gateway para esse manipulador usa o mesmo contrato compartilhado de resolução de credenciais que outros clientes do Gateway: - - autenticação local com prioridade para env (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` e então `gateway.auth.*`) - - no modo local, `gateway.remote.*` pode ser usado como fallback somente quando `gateway.auth.*` não estiver definido; SecretRefs locais configurados, mas não resolvidos, falham fechados - - suporte a modo remoto via `gateway.remote.*` quando aplicável - - substituições de URL são seguras para override: substituições de CLI não reutilizam credenciais implícitas, e substituições de env usam apenas credenciais de env + - autenticação local com prioridade para env (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` e depois `gateway.auth.*`) + - no modo local, `gateway.remote.*` pode ser usado como fallback apenas quando `gateway.auth.*` não está definido; SecretRefs locais configurados, mas não resolvidos, falham de forma fechada + - suporte ao modo remoto via `gateway.remote.*` quando aplicável + - substituições de URL são seguras para override: substituições via CLI não reutilizam credenciais implícitas, e substituições via env usam apenas credenciais de env - Comportamento de resolução de aprovação: + Comportamento da resolução de aprovação: - IDs prefixados com `plugin:` são resolvidos por `plugin.approval.resolve`. - Outros IDs são resolvidos por `exec.approval.resolve`. - - O Discord não faz aqui um salto extra de fallback de exec para plugin; o - prefixo do ID decide qual método do gateway ele chama. + - O Discord não faz aqui um hop extra de fallback de exec para plugin; o prefixo + do id decide qual método do gateway ele chama. Aprovações exec expiram após 30 minutos por padrão. Se aprovações falharem com - IDs de aprovação desconhecidos, verifique a resolução de aprovador, a habilitação do recurso e - se o tipo de ID de aprovação entregue corresponde à solicitação pendente. + IDs de aprovação desconhecidos, verifique a resolução do aprovador, a ativação do recurso e + se o tipo de id de aprovação entregue corresponde à solicitação pendente. Documentação relacionada: [Aprovações exec](/pt-BR/tools/exec-approvals) @@ -1016,16 +1017,16 @@ Os gates de ação ficam em `channels.discord.actions.*`. Comportamento padrão dos gates: -| Grupo de ação | 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 | +| Grupo de ação | Padrão | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | ativado | +| roles | desativado | +| moderation | desativado | +| presence | desativado | -## UI de Components v2 +## Interface Components v2 -O OpenClaw usa Discord components v2 para aprovações exec e marcadores de contexto cruzado. Ações de mensagem do Discord também podem aceitar `components` para UI personalizada (avançado; requer construir uma carga de componente via ferramenta do Discord), enquanto `embeds` legados continuam disponíveis, mas não são recomendados. +O OpenClaw usa components v2 do Discord para aprovações exec e marcadores entre contextos. As ações de mensagem do Discord também podem aceitar `components` para UI personalizada (avançado; requer construir uma carga de componente via a ferramenta do Discord), enquanto `embeds` legados continuam disponíveis, mas não são recomendados. - `channels.discord.ui.components.accentColor` define a cor de destaque usada por contêineres de componentes do Discord (hex). - Defina por conta com `channels.discord.accounts..ui.components.accentColor`. @@ -1049,15 +1050,15 @@ Exemplo: ## Canais de voz -O OpenClaw pode entrar em canais de voz do Discord para conversas contínuas em tempo real. Isso é separado de anexos de mensagens de voz. +O OpenClaw pode entrar em canais de voz do Discord para conversas contínuas em tempo real. Isso é separado de anexos de mensagem de voz. Requisitos: -- Habilite comandos nativos (`commands.native` ou `channels.discord.commands.native`). +- Ative comandos nativos (`commands.native` ou `channels.discord.commands.native`). - Configure `channels.discord.voice`. -- O bot precisa de permissões Connect + Speak no canal de voz alvo. +- O bot precisa de permissões Connect + Speak no canal de voz de destino. -Use o comando nativo exclusivo do Discord `/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 group policy que outros comandos do Discord. +Use o comando nativo exclusivo do Discord `/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 servidor que os outros comandos do Discord. Exemplo de entrada automática: @@ -1088,16 +1089,16 @@ Exemplo de entrada automática: Observações: - `voice.tts` substitui `messages.tts` apenas para reprodução por voz. -- Turnos de transcrição de voz derivam o status de owner de `allowFrom` do Discord (ou `dm.allowFrom`); falantes que não são owners não podem acessar ferramentas exclusivas de owner (por exemplo `gateway` e `cron`). -- Voz é habilitada por padrão; defina `channels.discord.voice.enabled=false` para desabilitá-la. +- 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`). +- Voz é ativada por padrão; defina `channels.discord.voice.enabled=false` para desativá-la. - `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 não estiverem definidos. -- O OpenClaw também monitora falhas de descriptografia na recepção e faz recuperação automática saindo e entrando novamente no canal de voz após falhas repetidas em uma janela curta. -- Se os logs de recepção mostrarem repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, isso pode ser o bug de recepção upstream de `@discordjs/voice` rastreado em [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). +- Os padrões de `@discordjs/voice` são `daveEncryption=true` e `decryptionFailureTolerance=24` quando não definidos. +- 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)`, isso pode ser o bug de recebimento upstream de `@discordjs/voice` rastreado em [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). ## Mensagens de voz -Mensagens de voz do Discord exibem uma prévia de forma de onda e exigem áudio OGG/Opus mais metadados. O OpenClaw gera a forma de onda automaticamente, mas precisa de `ffmpeg` e `ffprobe` disponíveis no host do gateway para inspecionar e converter arquivos de áudio. +Mensagens de voz do Discord exibem uma prévia de forma de onda e exigem áudio OGG/Opus mais metadados. O OpenClaw gera a forma de onda automaticamente, mas precisa que `ffmpeg` e `ffprobe` estejam disponíveis no host do gateway para inspecionar e converter arquivos de áudio. Requisitos e restrições: @@ -1114,19 +1115,19 @@ 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 - - reinicie o gateway após alterar as intents + - ative Message Content Intent + - ative Server Members Intent quando depender da resolução de usuário/membro + - reinicie o gateway após alterar intents - + - verifique `groupPolicy` - - verifique a allowlist de servidor em `channels.discord.guilds` - - se existir o mapa `guild channels`, apenas os canais listados serão permitidos + - verifique a allowlist de servidores em `channels.discord.guilds` + - se o mapa `channels` do servidor existir, apenas os canais listados serão permitidos - verifique o comportamento de `requireMention` e os padrões de menção Verificações úteis: @@ -1143,7 +1144,7 @@ openclaw logs --follow Causas comuns: - `groupPolicy="allowlist"` sem allowlist correspondente de servidor/canal - - `requireMention` configurado no lugar errado (deve ficar em `channels.discord.guilds` ou na entrada do canal) + - `requireMention` configurado no lugar errado (deve estar em `channels.discord.guilds` ou na entrada do canal) - remetente bloqueado pela allowlist `users` do servidor/canal @@ -1159,13 +1160,13 @@ openclaw logs --follow Ajuste de orçamento do listener: - conta única: `channels.discord.eventQueue.listenerTimeout` - - múltiplas contas: `channels.discord.accounts..eventQueue.listenerTimeout` + - várias contas: `channels.discord.accounts..eventQueue.listenerTimeout` Ajuste de timeout da execução do worker: - conta única: `channels.discord.inboundWorker.runTimeoutMs` - - múltiplas contas: `channels.discord.accounts..inboundWorker.runTimeoutMs` - - padrão: `1800000` (30 minutos); defina `0` para desabilitar + - várias contas: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - padrão: `1800000` (30 minutos); defina `0` para desativar Linha de base recomendada: @@ -1189,26 +1190,26 @@ openclaw logs --follow ``` Use `eventQueue.listenerTimeout` para configuração lenta do listener e `inboundWorker.runTimeoutMs` - apenas se você quiser uma válvula de segurança separada para turnos de agente enfileirados. + apenas se quiser uma válvula de segurança separada para turnos de agente enfileirados. - Verificações de permissão em `channels status --probe` funcionam apenas para IDs numéricos de canal. + Verificações de permissão de `channels status --probe` funcionam apenas para IDs numéricos de canal. - Se você usar chaves slug, a correspondência em runtime ainda pode funcionar, mas a sondagem não consegue verificar permissões completamente. + Se você usar chaves slug, a correspondência em runtime ainda pode funcionar, mas a sonda não consegue verificar completamente as permissões. - + - - DM desabilitada: `channels.discord.dm.enabled=false` - - política de DM desabilitada: `channels.discord.dmPolicy="disabled"` (legado: `channels.discord.dm.policy`) + - DM desativada: `channels.discord.dm.enabled=false` + - política de DM desativada: `channels.discord.dmPolicy="disabled"` (legado: `channels.discord.dm.policy`) - aguardando aprovação de pareamento no modo `pairing` - + Por padrão, mensagens criadas por bot são ignoradas. Se você definir `channels.discord.allowBots=true`, use regras estritas de menção e allowlist para evitar comportamento de loop. @@ -1216,20 +1217,20 @@ openclaw logs --follow - + - - mantenha o OpenClaw atualizado (`openclaw update`) para que a lógica de recuperação de recepção de voz do Discord esteja presente + - mantenha o OpenClaw atualizado (`openclaw update`) para que a lógica de recuperação de recebimento de voz do Discord esteja presente - confirme `channels.discord.voice.daveEncryption=true` (padrão) - - comece com `channels.discord.voice.decryptionFailureTolerance=24` (padrão upstream) e ajuste somente se necessário - - monitore logs para: + - 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 reentrada automática, colete logs e compare com [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) + - se as falhas continuarem após a nova entrada automática, colete os logs e compare com [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) -## Ponteiros para a referência de configuração +## Ponteiros da referência de configuração Referência principal: @@ -1244,8 +1245,8 @@ Campos do Discord de alto sinal: - worker de entrada: `inboundWorker.runTimeoutMs` - resposta/histórico: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - entrega: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- streaming: `streaming` (alias legado: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- mídia/retry: `mediaMaxMb`, `retry` +- streaming: `streaming` (alias legado: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- mídia/repetição: `mediaMaxMb`, `retry` - `mediaMaxMb` limita uploads de saída do Discord (padrão: `100MB`) - ações: `actions.*` - presença: `activity`, `status`, `activityType`, `activityUrl` @@ -1254,9 +1255,9 @@ Campos do Discord de alto sinal: ## Segurança e operações -- Trate tokens de bot como segredos (`DISCORD_BOT_TOKEN` preferido em ambientes supervisionados). -- Conceda permissões do Discord com privilégio mínimo. -- Se o estado/implantação de comandos estiver desatualizado, reinicie o gateway e verifique novamente com `openclaw channels status --probe`. +- Trate tokens de bot como segredos (`DISCORD_BOT_TOKEN` é preferido em ambientes supervisionados). +- Conceda permissões mínimas necessárias no Discord. +- Se a implantação/estado de comandos estiver desatualizada, reinicie o gateway e verifique novamente com `openclaw channels status --probe`. ## Relacionado @@ -1266,4 +1267,4 @@ Campos do Discord de alto sinal: - [Segurança](/pt-BR/gateway/security) - [Roteamento multiagente](/pt-BR/concepts/multi-agent) - [Solução de problemas](/pt-BR/channels/troubleshooting) -- [Comandos de barra](/pt-BR/tools/slash-commands) +- [Comandos slash](/pt-BR/tools/slash-commands) diff --git a/docs/pt-BR/channels/slack.md b/docs/pt-BR/channels/slack.md index df3101b6b..21a7a7c58 100644 --- a/docs/pt-BR/channels/slack.md +++ b/docs/pt-BR/channels/slack.md @@ -4,26 +4,26 @@ read_when: summary: Configuração do Slack e comportamento em tempo de execução (Socket Mode + URLs de solicitação HTTP) title: Slack x-i18n: - generated_at: "2026-04-21T13:35:14Z" + generated_at: "2026-04-21T17:45:34Z" model: gpt-5.4 provider: openai - source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf + source_hash: f30b372a3ae10b7b649532181306e42792aca76b41422516e9633eb79f73f009 source_path: channels/slack.md workflow: 15 --- # Slack -Status: pronto para produção para mensagens diretas + canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis. +Status: pronto para produção para DMs + canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis. - As mensagens diretas do Slack usam o modo de pareamento por padrão. + As DMs do Slack usam o modo de pareamento por padrão. Comportamento nativo de comandos e catálogo de comandos. - + Diagnósticos entre canais e guias de correção. @@ -33,16 +33,16 @@ Status: pronto para produção para mensagens diretas + canais via integrações - + Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: - - escolha **from a manifest** e selecione um workspace para o 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 **App-Level Token** (`xapp-...`) com `connections:write` - instale o app e copie o **Bot Token** (`xoxb-...`) exibido - + ```json5 { @@ -66,7 +66,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -79,17 +79,17 @@ openclaw gateway - + Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**: - - escolha **from a manifest** e selecione um workspace para o 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 **Signing Secret** para verificação de solicitações - instale o app e copie o **Bot Token** (`xoxb-...`) exibido - + ```json5 { @@ -106,14 +106,14 @@ openclaw gateway ``` - Use caminhos de webhook exclusivos para HTTP com várias contas + Use caminhos de Webhook exclusivos para HTTP com múltiplas contas - Dê a cada conta um `webhookPath` distinto (o padrão é `/slack/events`) para que os registros não entrem em conflito. + Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito. - + ```bash openclaw gateway @@ -291,12 +291,12 @@ openclaw gateway ### Configurações adicionais do manifesto -Exponha diferentes recursos que estendem os padrões acima. +Exiba diferentes recursos que ampliam os padrões acima. - Vários [comandos de barra nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com algumas nuances: + Vários [comandos de barra nativos](#commands-and-slash-behavior) podem ser usados no lugar de um único comando configurado, com algumas nuances: - Use `/agentstatus` em vez de `/status`, porque o comando `/status` é reservado. - Não é possível disponibilizar mais de 25 comandos de barra ao mesmo tempo. @@ -328,12 +328,12 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/session", - "description": "Gerenciar a expiração da vinculação à thread", - "usage_hint": "idle or max-age " + "description": "Gerenciar a expiração da vinculação da thread", + "usage_hint": "idle ou max-age " }, { "command": "/think", - "description": "Definir o nível de pensamento", + "description": "Definir o nível de raciocínio", "usage_hint": "" }, { @@ -358,7 +358,7 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/exec", - "description": "Mostrar ou definir padrões de exec", + "description": "Mostrar ou definir os padrões de execução", "usage_hint": "host= security= ask= node=" }, { @@ -386,7 +386,7 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/agentstatus", - "description": "Mostrar o status em tempo de execução, incluindo uso/cota do provedor quando disponível" + "description": "Mostrar o status de tempo de execução, incluindo uso/cota do provedor quando disponível" }, { "command": "/tasks", @@ -448,13 +448,13 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/session", - "description": "Gerenciar a expiração da vinculação à thread", - "usage_hint": "idle or max-age ", + "description": "Gerenciar a expiração da vinculação da thread", + "usage_hint": "idle ou max-age ", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/think", - "description": "Definir o nível de pensamento", + "description": "Definir o nível de raciocínio", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, @@ -484,7 +484,7 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/exec", - "description": "Mostrar ou definir padrões de exec", + "description": "Mostrar ou definir os padrões de execução", "usage_hint": "host= security= ask= node=", "url": "https://gateway-host.example.com/slack/events" }, @@ -518,7 +518,7 @@ Exponha diferentes recursos que estendem os padrões acima. }, { "command": "/agentstatus", - "description": "Mostrar o status em tempo de execução, incluindo uso/cota do provedor quando disponível", + "description": "Mostrar o status de tempo de execução, incluindo uso/cota do provedor quando disponível", "url": "https://gateway-host.example.com/slack/events" }, { @@ -562,10 +562,10 @@ Exponha diferentes recursos que estendem os padrões acima. - - Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app do Slack. + + Adicione o escopo bot `chat:write.customize` se quiser que as mensagens de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app do Slack. - Se você usar um ícone de emoji, o Slack espera a sintaxe `:emoji_name:`. + Se você usar um ícone de emoji, o Slack espera a sintaxe `:nome_do_emoji:`. @@ -586,47 +586,47 @@ Exponha diferentes recursos que estendem os padrões acima. - `botToken` + `appToken` são obrigatórios para Socket Mode. - O modo HTTP exige `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples - ou objetos SecretRef. -- Tokens de configuração substituem o fallback por variável de ambiente. +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings + em texto simples ou objetos SecretRef. +- Os tokens de configuração substituem o fallback por variável de ambiente. - O fallback por variável de ambiente `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão. -- `userToken` (`xoxp-...`) é apenas de configuração (sem fallback por variável de ambiente) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) é somente de configuração (sem fallback por variável de ambiente) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`). Comportamento do snapshot de status: -- A inspeção da conta do Slack rastreia campos `*Source` e `*Status` por credencial - (`botToken`, `appToken`, `signingSecret`, `userToken`). +- A inspeção de conta do Slack rastreia campos `*Source` e `*Status` + por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`). - O status é `available`, `configured_unavailable` ou `missing`. - `configured_unavailable` significa que a conta está configurada por SecretRef ou outra fonte de segredo não inline, mas o caminho atual de comando/tempo de execução não conseguiu resolver o valor real. -- No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o - par obrigatório é `botTokenStatus` + `appTokenStatus`. +- No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o par + obrigatório é `botTokenStatus` + `appTokenStatus`. -Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua sendo preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot não está disponível. +Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para gravações, o token de bot continua sendo preferido; gravações com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot não está disponível. -## Ações e gates +## Ações e controles As ações do Slack são controladas por `channels.slack.actions.*`. Grupos de ações disponíveis nas ferramentas atuais do Slack: -| Grupo | Padrão | -| ---------- | -------- | -| messages | habilitado | -| reactions | habilitado | -| pins | habilitado | -| memberInfo | habilitado | -| emojiList | habilitado | +| Group | Default | +| ---------- | ------- | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | 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`. ## Controle de acesso e roteamento - + `channels.slack.dmPolicy` controla o acesso por DM (legado: `channels.slack.dm.policy`): - `pairing` (padrão) @@ -634,15 +634,15 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `open` (exige que `channels.slack.allowFrom` inclua `"*"`; legado: `channels.slack.dm.allowFrom`) - `disabled` - Sinalizadores de DM: + Flags de DM: - `dm.enabled` (padrão true) - `channels.slack.allowFrom` (preferido) - `dm.allowFrom` (legado) - `dm.groupEnabled` (DMs em grupo com padrão false) - - `dm.groupChannels` (allowlist MPIM opcional) + - `dm.groupChannels` (allowlist opcional de MPIM) - Precedência de várias contas: + Precedência em múltiplas 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. @@ -652,7 +652,7 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - + `channels.slack.groupPolicy` controla o tratamento de canais: - `open` @@ -661,18 +661,18 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- A allowlist de canais fica em `channels.slack.channels` e deve usar IDs de canal estáveis. - Observação de tempo de execução: se `channels.slack` estiver completamente ausente (configuração somente por env), o tempo de execução volta para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). + Observação de tempo de execução: se `channels.slack` estiver completamente ausente (configuração somente por env), o tempo de execução usa `groupPolicy="allowlist"` como fallback e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). Resolução de nome/ID: - - entradas da allowlist de canais e da allowlist de DM são resolvidas na inicialização quando o acesso do token permite - - entradas não resolvidas por nome de canal são mantidas conforme configuradas, mas ignoradas para roteamento por padrão - - a autorização de entrada e o roteamento de canal usam ID primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` + - entradas da allowlist de canais e da allowlist de DMs são resolvidas na inicialização quando o acesso ao token permite + - entradas não resolvidas de nome de canal são mantidas como configuradas, mas ignoradas para roteamento por padrão + - a autorização de entrada e o roteamento de canais usam IDs primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` - Mensagens de canal são bloqueadas por menção por padrão. + As mensagens de canal são bloqueadas por menção por padrão. Fontes de menção: @@ -688,8 +688,8 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"` - (chaves legadas sem prefixo ainda mapeiam apenas para `id:`) + - formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"` + (chaves legadas sem prefixo ainda são mapeadas apenas para `id:`) @@ -697,14 +697,14 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- ## Threads, sessões e tags de resposta - DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`. -- Com o padrão `session.dmScope=main`, DMs do Slack são agrupadas na sessão principal do agente. +- Com o padrão `session.dmScope=main`, as DMs do Slack colapsam 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 desabilitar). -- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread 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 bloqueio de `requireMention`. +- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens existentes da thread são buscadas quando uma nova sessão de thread é iniciada (padrão `20`; defina `0` para desabilitar). +- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread 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 controle `requireMention`. -Controles de encadeamento de resposta: +Controles de encadeamento de respostas: - `channels.slack.replyToMode`: `off|first|all|batched` (padrão `off`) - `channels.slack.replyToModeByChatType`: por `direct|group|channel` @@ -715,22 +715,22 @@ Tags manuais de resposta são compatíveis: - `[[reply_to_current]]` - `[[reply_to:]]` -Observação: `replyToMode="off"` desabilita **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, onde tags explícitas ainda são respeitadas no modo `"off"`. A diferença reflete os modelos de thread da plataforma: threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis no fluxo principal do chat. +Observação: `replyToMode="off"` desabilita **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. A diferença reflete os modelos de threading das plataformas: threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis no fluxo principal do chat. ## Reações de confirmação -`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. +`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. Ordem de resolução: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário `"👀"`) +- fallback para o emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") Observações: -- O Slack espera shortcodes (por exemplo `"eyes"`). +- O Slack espera shortcodes (por exemplo, `"eyes"`). - Use `""` para desabilitar a reação para a conta do Slack ou globalmente. ## Streaming de texto @@ -740,17 +740,18 @@ Observações: - `off`: desabilita o streaming de visualização ao vivo. - `partial` (padrão): substitui o texto de visualização pela saída parcial mais recente. - `block`: acrescenta atualizações de visualização em blocos. -- `progress`: mostra o texto de status do progresso enquanto gera e, em seguida, envia o texto final. +- `progress`: mostra texto de status de progresso durante a geração e, em seguida, envia o texto final. +- `streaming.preview.toolProgress`: quando a visualização de rascunho está ativa, encaminha atualizações de ferramenta/progresso para a mesma mensagem de visualização editada (padrão: `true`). Defina como `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`). +`channels.slack.streaming.nativeTransport` controla o streaming nativo de texto do Slack quando `channels.slack.streaming.mode` é `partial` (padrão: `true`). -- Uma thread de resposta precisa estar disponível para que o streaming de texto nativo e o status de thread do assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`. +- Uma thread de resposta deve estar disponível para que o streaming nativo de texto e o status de thread do assistente do Slack apareçam. A seleção da thread ainda segue `replyToMode`. - Raízes de canais e chats em grupo ainda podem usar a visualização normal de rascunho quando o streaming nativo não estiver disponível. -- DMs de nível superior no Slack permanecem fora de thread por padrão, então não mostram a visualização no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível ali. -- Mídia e cargas não textuais voltam para a entrega normal. -- Se o streaming falhar no meio da resposta, o OpenClaw volta para a entrega normal para as cargas restantes. +- DMs de nível superior no Slack permanecem fora de thread por padrão, então não mostram a visualização no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível nelas. +- Mídia e cargas não textuais usam a entrega normal como fallback. +- Se o streaming falhar no meio da resposta, o OpenClaw usa a entrega normal como fallback para as cargas restantes. -Use a visualização de rascunho em vez do streaming de texto nativo do Slack: +Use a visualização de rascunho em vez do streaming nativo de texto do Slack: ```json5 { @@ -773,7 +774,7 @@ Chaves legadas: ## Fallback de reação de digitação -`typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto o OpenClaw processa uma resposta e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador padrão de status "is typing...". +`typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto o OpenClaw processa uma resposta e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "is typing...". Ordem de resolução: @@ -782,24 +783,24 @@ Ordem de resolução: Observações: -- O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`). -- A reação é best-effort, e a limpeza é tentada automaticamente depois que a resposta ou o caminho de falha é concluído. +- O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`). +- A reação é best-effort e a limpeza é tentada automaticamente após a conclusão da resposta ou do caminho de falha. ## 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 anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticada por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. - O limite padrão de tamanho de entrada em tempo de execução é `20MB`, a menos que seja substituído por `channels.slack.mediaMaxMb`. + O limite de tamanho de entrada em tempo de execução é `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`. - + - blocos 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 do canal usam os padrões de tipo MIME do pipeline de mídia + - 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 @@ -808,14 +809,14 @@ Observações: - `user:` para DMs - `channel:` para canais - DMs do Slack são abertas por meio das APIs de conversa do Slack ao enviar para destinos de usuário. + As DMs do Slack são abertas via APIs de conversa do Slack ao enviar para destinos de usuário. ## Comandos e comportamento de slash -Os 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 do comando: +Os comandos de barra aparecem no Slack como um único comando configurado ou como vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando: - `enabled: false` - `name: "openclaw"` @@ -828,28 +829,28 @@ Os comandos de barra aparecem no Slack como um único comando configurado ou vá Os comandos nativos exigem [configurações adicionais do manifesto](#additional-manifest-settings) no seu app do Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` nas configurações globais. -- O modo automático de comandos nativos fica **desligado** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. +- O modo automático de comandos nativos é **off** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack. ```txt /help ``` -Os menus nativos de argumentos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar um valor de opção selecionado: +Os menus nativos de argumentos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar o valor de uma opção selecionada: -- até 5 opções: blocos de botões -- 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 -- limites do Slack excedidos: valores de opção codificados voltam para botões +- até 5 opções: blocos de botão +- 6-100 opções: menu de seleção estático +- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando os manipuladores de opções de interatividade estão disponíveis +- limites do Slack excedidos: valores de opção codificados usam botões como fallback ```txt /think ``` -As sessões de slash usam chaves isoladas como `agent::slack:slash:` e ainda roteiam execuções de comando para a sessão de conversa de destino usando `CommandTargetSessionKey`. +As sessões de slash usam chaves isoladas como `agent::slack:slash:` e ainda roteiam execuções de comandos para a sessão de 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 interativos de resposta criados pelo agente, mas esse recurso está desabilitado por padrão. Habilite globalmente: @@ -865,7 +866,7 @@ Habilite globalmente: } ``` -Ou habilite apenas para uma conta do Slack: +Ou habilite para apenas uma conta do Slack: ```json5 { @@ -883,42 +884,42 @@ Ou habilite apenas para uma conta do Slack: } ``` -Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slack: +Quando habilitado, os agentes podem emitir diretivas de resposta exclusivas do Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Essas diretivas são compiladas em Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack. +Essas diretivas são compiladas em Slack Block Kit e encaminham cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack. Observações: -- Esta é uma UI específica do Slack. Outros canais não traduzem diretivas de Slack Block Kit para seus próprios sistemas de botõ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 volta para a resposta de texto original em vez de enviar uma carga de blocos inválida. +- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw usa a resposta de texto original como fallback em vez de enviar uma carga de blocos inválida. ## Aprovações de exec no Slack -O Slack pode atuar como um cliente nativo de aprovação com botões e interações interativas, em vez de voltar para a Web UI ou o terminal. +O Slack pode atuar como um cliente nativo de aprovação com botões interativos e interações, em vez de usar a Web UI ou o terminal como fallback. -- Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo em DM/canal. -- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo de id de aprovação é `plugin:`. +- As aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal. +- As aprovações de Plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo do ID de aprovação é `plugin:`. - A autorização do aprovador continua sendo aplicada: apenas 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 do Slack, os prompts de aprovação são renderizados como botões Block Kit diretamente na conversa. +Isso usa a mesma superfície compartilhada de botões de aprovação que outros canais. Quando `interactivity` está habilitado nas configurações do seu app do Slack, os 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 -deve incluir um comando manual `/approve` apenas 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. +deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser que as +aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho. Caminho de configuração: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (opcional; usa fallback para `commands.ownerAllowFrom` quando possível) +- `channels.slack.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como fallback quando possível) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter` O Slack habilita automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador é resolvido. Defina `enabled: false` para desabilitar explicitamente o Slack como cliente nativo de aprovação. -Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos. +Defina `enabled: true` para forçar aprovações nativas quando os aprovadores forem resolvidos. Comportamento padrão sem configuração explícita de aprovação de exec no Slack: @@ -930,7 +931,7 @@ Comportamento padrão sem configuração explícita de aprovação de exec no Sl } ``` -A configuração nativa explícita do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou +A configuração nativa explícita do Slack só é necessária quando você quiser substituir aprovadores, adicionar filtros ou optar pela entrega no chat de origem: ```json5 @@ -947,45 +948,45 @@ optar pela entrega no chat de origem: } ``` -O encaminhamento compartilhado `approvals.exec` é separado. Use-o apenas quando prompts de aprovação de exec também precisarem -ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado `approvals.plugin` também é -separado; botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegam +O encaminhamento compartilhado `approvals.exec` é separado. Use-o apenas quando os prompts de aprovação de exec também precisarem +ser encaminhados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado `approvals.plugin` também é +separado; os botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegarem 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ções. +O `/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. ## Eventos e comportamento operacional -- Edições/exclusões de mensagens e transmissões de thread são mapeadas para eventos de sistema. +- Edições/exclusões de mensagens e transmissões em thread são mapeadas para eventos de sistema. - Eventos de adicionar/remover reação são mapeados para eventos de sistema. - Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover pin são mapeados para eventos de sistema. - `channel_id_changed` pode migrar chaves de configuração do canal quando `configWrites` está habilitado. - Metadados de tópico/finalidade do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento. -- O iniciador da thread e o seed inicial de contexto do histórico da thread são filtrados pelas allowlists de remetente configuradas, quando aplicável. -- Ações de bloco e interações de modal emitem eventos de sistema estruturados `Slack interaction: ...` com campos de payload ricos: +- O iniciador da thread e a semeadura inicial do contexto do histórico da thread são filtrados pelas allowlists configuradas de remetente quando aplicável. +- Ações de bloco e interações de modal emitem eventos de sistema estruturados `Slack interaction: ...` com campos ricos de carga: - ações de bloco: valores selecionados, rótulos, valores de seletor e metadados `workflow_*` - eventos de modal `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário -## Ponteiros para a referência de configuração +## Ponteiros de referência de configuração Referência principal: - [Referência de configuração - Slack](/pt-BR/gateway/configuration-reference#slack) - Campos de Slack de alto sinal: + Campos do Slack de alto sinal: - modo/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - acesso por DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - alternância de compatibilidade: `dangerouslyAllowNameMatching` (break-glass; mantenha desativado, a menos que seja necessário) - - acesso de canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - 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` - - ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` + - entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` + - operações/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## Solução de problemas - - Verifique, nesta ordem: + + Verifique, em ordem: - `groupPolicy` - allowlist de canais (`channels.slack.channels`) @@ -1021,7 +1022,7 @@ openclaw pairing list slack Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou `appTokenStatus: "configured_unavailable"`, a conta do Slack está configurada, mas o tempo de execução atual não conseguiu resolver o valor - respaldado por SecretRef. + apoiado por SecretRef. @@ -1029,20 +1030,20 @@ openclaw pairing list slack Valide: - signing secret - - caminho do webhook + - caminho do Webhook - URLs de solicitação do Slack (Eventos + Interatividade + Comandos de barra) - `webhookPath` exclusivo por conta HTTP - Se `signingSecretStatus: "configured_unavailable"` aparecer nos snapshots - da conta, a conta HTTP está configurada, mas o tempo de execução atual não conseguiu - resolver o signing secret respaldado por SecretRef. + Se `signingSecretStatus: "configured_unavailable"` aparecer nos snapshots da + conta, a conta HTTP está configurada, mas o tempo de execução atual não conseguiu + resolver o signing secret apoiado por SecretRef. - - Verifique se a intenção era: + + Verifique se sua intenção era: - - modo de comando nativo (`channels.slack.commands.native: true`) com comandos de barra correspondentes registrados no Slack + - modo de comando nativo (`channels.slack.commands.native: true`) com os comandos de barra correspondentes registrados no Slack - ou modo de comando de barra único (`channels.slack.slashCommand.enabled: true`) Verifique também `commands.useAccessGroups` e as allowlists de canal/usuário. @@ -1055,7 +1056,7 @@ openclaw pairing list slack - [Pareamento](/pt-BR/channels/pairing) - [Grupos](/pt-BR/channels/groups) - [Segurança](/pt-BR/gateway/security) -- [Roteamento de canal](/pt-BR/channels/channel-routing) +- [Roteamento de canais](/pt-BR/channels/channel-routing) - [Solução de problemas](/pt-BR/channels/troubleshooting) - [Configuração](/pt-BR/gateway/configuration) - [Comandos de barra](/pt-BR/tools/slash-commands) diff --git a/docs/pt-BR/channels/telegram.md b/docs/pt-BR/channels/telegram.md index 39858bb40..177358f79 100644 --- a/docs/pt-BR/channels/telegram.md +++ b/docs/pt-BR/channels/telegram.md @@ -1,20 +1,20 @@ --- read_when: - Trabalhando em recursos do Telegram ou Webhooks -summary: Status do suporte ao bot do Telegram, capacidades e configuração +summary: Status do suporte do bot do Telegram, capacidades e configuração title: Telegram x-i18n: - generated_at: "2026-04-21T05:35:29Z" + generated_at: "2026-04-21T17:45:32Z" model: gpt-5.4 provider: openai - source_hash: b5c70775b55d4923a31ad8bae7f4c6e7cbae754c05c3a578180d63db2b59e39a + source_hash: 816238b53942b319a300843db62ec1d4bf8d84bc11094010926ac9ad457c6d3d source_path: channels/telegram.md workflow: 15 --- # Telegram (Bot API) -Status: pronto para produção para DMs + grupos de bots via grammY. Long polling é o modo padrão; o modo Webhook é opcional. +Status: pronto para produção para DMs de bot + grupos via grammY. O long polling é o modo padrão; o modo Webhook é opcional. @@ -53,8 +53,8 @@ Status: pronto para produção para DMs + grupos de bots via grammY. Long pollin } ``` - Fallback de ambiente: `TELEGRAM_BOT_TOKEN=...` (apenas conta padrão). - O Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e, em seguida, inicie o Gateway. + Fallback de variável de ambiente: `TELEGRAM_BOT_TOKEN=...` (apenas conta padrão). + O Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e então inicie o Gateway. @@ -71,39 +71,39 @@ openclaw pairing approve telegram - Adicione o bot ao seu grupo e, em seguida, defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. + Adicione o bot ao seu grupo e então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. -A ordem de resolução do token considera a conta. Na prática, os valores da configuração têm prioridade sobre o fallback de ambiente, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão. +A ordem de resolução do token considera a conta. Na prática, os valores de config vencem o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão. ## Configurações no lado do Telegram - Os bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem. + Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem. Se o bot precisar ver todas as mensagens do grupo, faça um destes procedimentos: - desative o modo de privacidade via `/setprivacy`, ou - - torne o bot um administrador do grupo. + - torne o bot administrador do grupo. - Ao alternar o modo de privacidade, remova e adicione novamente o bot em cada grupo para que o Telegram aplique a alteração. + Ao alternar o modo de privacidade, remova + adicione novamente o bot em cada grupo para que o Telegram aplique a mudança. - - O status de administrador é controlado nas configurações do grupo do Telegram. + + O status de administrador é controlado nas configurações do grupo no Telegram. - Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento contínuo em grupos. + Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento sempre ativo em grupos. - - `/setjoingroups` para permitir/negar adições em grupos + - `/setjoingroups` para permitir/negar adições a grupos - `/setprivacy` para o comportamento de visibilidade em grupos @@ -116,27 +116,27 @@ A ordem de resolução do token considera a conta. Na prática, os valores da co `channels.telegram.dmPolicy` controla o acesso a mensagens diretas: - `pairing` (padrão) - - `allowlist` (requer pelo menos um ID de remetente em `allowFrom`) - - `open` (requer que `allowFrom` inclua `"*"`) + - `allowlist` (exige pelo menos um ID de remetente em `allowFrom`) + - `open` (exige que `allowFrom` inclua `"*"`) - `disabled` `channels.telegram.allowFrom` aceita IDs numéricos de usuários do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados. `dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração. - A configuração solicita apenas IDs numéricos de usuário. + A configuração solicita apenas IDs numéricos de usuários. Se você atualizou e sua configuração contém entradas `@username` na allowlist, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; requer um token de bot do Telegram). - Se você dependia anteriormente de arquivos de allowlist do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). + Se você antes dependia de arquivos de allowlist do pairing-store, `openclaw doctor --fix` pode recuperar entradas em `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). - Para bots com um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores). + Para bots de um único dono, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso persistente na configuração (em vez de depender de aprovações de pareamento anteriores). - Confusão comum: a aprovação de pareamento de DM não significa "este remetente está autorizado em todos os lugares". - O pareamento concede acesso apenas a DM. A autorização de remetentes em grupos ainda vem de allowlists explícitas na configuração. - Se você quiser "estou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`. + Confusão comum: aprovar o pareamento de DM não significa "este remetente está autorizado em todos os lugares". + O pareamento concede acesso apenas à DM. A autorização do remetente em grupos ainda vem de allowlists explícitas na configuração. + Se você quiser "eu sou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`. ### Encontrando seu ID de usuário do Telegram Mais seguro (sem bot de terceiros): - 1. Envie uma DM ao seu bot. + 1. Envie uma DM para seu bot. 2. Execute `openclaw logs --follow`. 3. Leia `from.id`. @@ -151,12 +151,12 @@ curl "https://api.telegram.org/bot/getUpdates" - Dois controles se aplicam em conjunto: + Dois controles se aplicam juntos: 1. **Quais grupos são permitidos** (`channels.telegram.groups`) - sem configuração `groups`: - - com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID do grupo - - com `groupPolicy: "allowlist"` (padrão): os grupos são bloqueados até que você adicione entradas em `groups` (ou `"*"`) + - com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo + - com `groupPolicy: "allowlist"` (padrão): os grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`) - `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`) 2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`) @@ -164,15 +164,15 @@ curl "https://api.telegram.org/bot/getUpdates" - `allowlist` (padrão) - `disabled` - `groupAllowFrom` é usado para filtrar remetentes em grupos. Se não estiver definido, o Telegram usa `allowFrom` como fallback. + `groupAllowFrom` é usado para filtragem de remetentes em grupos. Se não estiver definido, o Telegram usa `allowFrom` como fallback. As entradas de `groupAllowFrom` devem ser IDs numéricos de usuários do Telegram (prefixos `telegram:` / `tg:` são normalizados). Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`. - Entradas não numéricas são ignoradas para autorização de remetentes. - Limite de segurança (`2026.2.25+`): a autenticação de remetente em grupo **não** herda aprovações do armazenamento de pareamento de DM. + Entradas não numéricas são ignoradas para autorização do remetente. + Limite de segurança (`2026.2.25+`): a autorização de remetente em grupos **não** herda aprovações de pareamento de DM do pairing-store. O pareamento continua sendo apenas para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico. - Se `groupAllowFrom` não estiver definido, o Telegram usa `allowFrom` da configuração como fallback, não o armazenamento de pareamento. - Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` sem definir e permita os grupos de destino em `channels.telegram.groups`. - Observação de runtime: se `channels.telegram` estiver completamente ausente, os padrões de runtime usam `groupPolicy="allowlist"` em fail-closed, a menos que `channels.defaults.groupPolicy` esteja explicitamente definido. + Se `groupAllowFrom` não estiver definido, o Telegram usa `allowFrom` da configuração como fallback, não o pairing store. + Padrão prático para bots de um único dono: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` sem definir e permita os grupos-alvo em `channels.telegram.groups`. + Observação de runtime: se `channels.telegram` estiver completamente ausente, os padrões de runtime usam fail-closed `groupPolicy="allowlist"` a menos que `channels.defaults.groupPolicy` seja explicitamente definido. Exemplo: permitir qualquer membro em um grupo específico: @@ -211,8 +211,8 @@ curl "https://api.telegram.org/bot/getUpdates" Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram. - - Coloque IDs negativos de grupos ou supergrupos do Telegram como `-1001234567890` em `channels.telegram.groups`. - - Coloque IDs de usuários do Telegram como `8734062810` em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot. + - Coloque IDs negativos de grupo ou supergrupo do Telegram como `-1001234567890` em `channels.telegram.groups`. + - Coloque IDs de usuário do Telegram como `8734062810` em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot. - Use `groupAllowFrom: ["*"]` apenas quando quiser que qualquer membro de um grupo permitido possa falar com o bot. @@ -228,7 +228,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Alternâncias de comando no nível da sessão: + Alternâncias de comando em nível de sessão: - `/activation always` - `/activation mention` @@ -249,7 +249,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Obtendo o ID do chat em grupo: + Obtendo o ID do chat de grupo: - encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot` - ou leia `chat.id` em `openclaw logs --follow` @@ -260,56 +260,57 @@ curl "https://api.telegram.org/bot/getUpdates" ## Comportamento em runtime -- O Telegram é controlado pelo processo Gateway. +- O Telegram é controlado pelo processo do Gateway. - O roteamento é determinístico: respostas recebidas do Telegram voltam para o Telegram (o modelo não escolhe canais). -- Mensagens recebidas são normalizadas no envelope compartilhado de canal com metadados de resposta e placeholders de mídia. +- As mensagens recebidas são normalizadas no envelope compartilhado de canais com metadados de resposta e placeholders de mídia. - Sessões de grupo são isoladas por ID do grupo. Tópicos de fórum acrescentam `:topic:` para manter os tópicos isolados. -- Mensagens de DM podem carregar `message_thread_id`; o OpenClaw as roteia com chaves de sessão conscientes de thread e preserva o ID da thread nas respostas. -- O long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`. -- Reinicializações do watchdog de long polling são acionadas após 120 segundos sem atividade concluída de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` apenas se sua implantação ainda apresentar reinicializações falsas por travamento de polling durante trabalhos de longa duração. O valor está em milissegundos e é permitido de `30000` a `600000`; substituições por conta são suportadas. -- A Bot API do Telegram não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica). +- Mensagens de DM podem transportar `message_thread_id`; o OpenClaw as roteia com chaves de sessão com reconhecimento de thread e preserva o ID da thread para respostas. +- O long polling usa o runner do grammY com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`. +- Reinicializações do watchdog de long polling são disparadas após 120 segundos sem atividade concluída de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` apenas se sua implantação ainda vir reinicializações falsas de polling travado durante trabalhos de longa duração. O valor está em milissegundos e é permitido de `30000` a `600000`; substituições por conta são suportadas. +- A Telegram Bot API não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica). ## Referência de recursos - + O OpenClaw pode transmitir respostas parciais em tempo real: - - chats diretos: mensagem de pré-visualização + `editMessageText` - - grupos/tópicos: mensagem de pré-visualização + `editMessageText` + - chats diretos: mensagem de prévia + `editMessageText` + - grupos/tópicos: mensagem de prévia + `editMessageText` Requisito: - `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`) - - `progress` é mapeado para `partial` no Telegram (compatibilidade com nomenclatura entre canais) + - `progress` corresponde a `partial` no Telegram (compatibilidade com nomenclatura entre canais) + - `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso. - `channels.telegram.streamMode` legado e valores booleanos de `streaming` são mapeados automaticamente - Para respostas somente com texto: + Para respostas somente de texto: - - DM: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar (sem segunda mensagem) - - grupo/tópico: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar (sem segunda mensagem) + - DM: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem) + - grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem) - Para respostas complexas (por exemplo, payloads de mídia), o OpenClaw usa a entrega final normal como fallback e depois limpa a mensagem de pré-visualização. + Para respostas complexas (por exemplo, payloads de mídia), o OpenClaw faz fallback para a entrega final normal e então limpa a mensagem de prévia. - O streaming de pré-visualização é separado do streaming em bloco. Quando o streaming em bloco está explicitamente habilitado para o Telegram, o OpenClaw ignora o stream de pré-visualização para evitar streaming duplo. + O streaming de prévia é separado do streaming em bloco. Quando o streaming em bloco é explicitamente habilitado para Telegram, o OpenClaw ignora o streaming de prévia para evitar streaming duplo. - Se o transporte nativo de rascunho não estiver disponível/for rejeitado, o OpenClaw automaticamente usa `sendMessage` + `editMessageText` como fallback. + Se o transporte nativo de rascunho estiver indisponível/for rejeitado, o OpenClaw faz fallback automaticamente para `sendMessage` + `editMessageText`. - Stream de raciocínio apenas do Telegram: + Stream de raciocínio somente do Telegram: - - `/reasoning stream` envia o raciocínio para a pré-visualização ao vivo enquanto gera + - `/reasoning stream` envia o raciocínio para a prévia ao vivo enquanto gera - a resposta final é enviada sem o texto de raciocínio - O texto de saída usa `parse_mode: "HTML"` do Telegram. + O texto de saída usa Telegram `parse_mode: "HTML"`. - - Texto no estilo Markdown é renderizado como HTML seguro para Telegram. - - HTML bruto do modelo é escapado para reduzir falhas de parsing do Telegram. - - Se o Telegram rejeitar o HTML processado, o OpenClaw tenta novamente como texto simples. + - Texto em estilo Markdown é renderizado em HTML seguro para Telegram. + - HTML bruto do modelo é escapado para reduzir falhas de parsing no Telegram. + - Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples. - As pré-visualizações de links são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`. + As prévias de link são habilitadas por padrão e podem ser desabilitadas com `channels.telegram.linkPreview: false`. @@ -318,7 +319,7 @@ curl "https://api.telegram.org/bot/getUpdates" Padrões de comandos nativos: - - `commands.native: "auto"` habilita comandos nativos para o Telegram + - `commands.native: "auto"` habilita comandos nativos para Telegram Adicione entradas personalizadas ao menu de comandos: @@ -337,7 +338,7 @@ curl "https://api.telegram.org/bot/getUpdates" Regras: - - os nomes são normalizados (remove `/` inicial, minúsculas) + - os nomes são normalizados (remover `/` inicial, minúsculas) - padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32` - comandos personalizados não podem sobrescrever comandos nativos - conflitos/duplicatas são ignorados e registrados em log @@ -345,30 +346,30 @@ curl "https://api.telegram.org/bot/getUpdates" Observações: - comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente - - comandos de plugin/Skills ainda podem funcionar quando digitados, mesmo que não sejam mostrados no menu do Telegram + - comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não sejam mostrados no menu do Telegram - Se os comandos nativos forem desativados, os integrados serão removidos. Comandos personalizados/de plugin ainda podem ser registrados se configurados. + Se os comandos nativos estiverem desabilitados, os embutidos serão removidos. Comandos personalizados/de Plugin ainda podem ser registrados se estiverem configurados. Falhas comuns de configuração: - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após a redução; reduza comandos de plugin/Skills/personalizados ou desative `channels.telegram.commands.native`. - - `setMyCommands failed` com erros de rede/fetch normalmente significa que o DNS/HTTPS de saída para `api.telegram.org` está bloqueado. + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o ajuste; reduza comandos de Plugin/Skills/personalizados ou desabilite `channels.telegram.commands.native`. + - `setMyCommands failed` com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado. - ### Comandos de pareamento de dispositivo (plugin `device-pair`) + ### Comandos de pareamento de dispositivo (Plugin `device-pair`) - Quando o plugin `device-pair` está instalado: + Quando o Plugin `device-pair` está instalado: 1. `/pair` gera um código de configuração 2. cole o código no app iOS - 3. `/pair pending` lista solicitações pendentes (incluindo função/escopos) + 3. `/pair pending` lista solicitações pendentes (incluindo role/scopes) 4. aprove a solicitação: - `/pair approve ` para aprovação explícita - - `/pair approve` quando há apenas uma solicitação pendente + - `/pair approve` quando houver apenas uma solicitação pendente - `/pair approve latest` para a mais recente - O código de configuração carrega um token de bootstrap de curta duração. O handoff de bootstrap integrado mantém o token do node principal em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap são prefixadas por função, então essa allowlist de operador satisfaz apenas solicitações de operador; funções não operadoras ainda precisam de escopos sob o prefixo da própria função. + O código de configuração carrega um token bootstrap de curta duração. A transferência bootstrap embutida mantém o token do node primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo bootstrap usam prefixo de role, então essa allowlist de operador satisfaz apenas solicitações de operador; roles que não são de operador ainda precisam de scopes sob o prefixo da própria role. - Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute novamente `/pair pending` antes de aprovar. + Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo role/scopes/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar. Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -415,7 +416,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (padrão) - O legado `capabilities: ["inlineButtons"]` é mapeado para `inlineButtons: "all"`. + O legado `capabilities: ["inlineButtons"]` corresponde a `inlineButtons: "all"`. Exemplo de ação de mensagem: @@ -435,7 +436,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Cliques de callback são passados ao agente como texto: + Cliques em callback são passados ao agente como texto: `callback_data: ` @@ -451,15 +452,15 @@ curl "https://api.telegram.org/bot/getUpdates" As ações de mensagem do canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Controles de gating: + Controles de bloqueio: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - - `channels.telegram.actions.sticker` (padrão: desativado) + - `channels.telegram.actions.sticker` (padrão: desabilitado) - Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm alternâncias `channels.telegram.actions.*` separadas. - Os envios em runtime usam o snapshot ativo de config/secrets (inicialização/reload), então os caminhos de ação não executam re-resolução ad hoc de SecretRef por envio. + Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm toggles `channels.telegram.actions.*` separados. + Envios em runtime usam o snapshot ativo de config/secrets (inicialização/reload), portanto os caminhos de ação não executam nova resolução ad hoc de SecretRef a cada envio. Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions) @@ -468,7 +469,7 @@ curl "https://api.telegram.org/bot/getUpdates" O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada: - - `[[reply_to_current]]` responde à mensagem que acionou a ação + - `[[reply_to_current]]` responde à mensagem que acionou - `[[reply_to:]]` responde a um ID específico de mensagem do Telegram `channels.telegram.replyToMode` controla o tratamento: @@ -477,7 +478,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Observação: `off` desativa o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. + Observação: `off` desabilita o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. @@ -489,15 +490,15 @@ curl "https://api.telegram.org/bot/getUpdates" - caminho de configuração do tópico: `channels.telegram.groups..topics.` - Caso especial do tópico Geral (`threadId=1`): + Caso especial do tópico geral (`threadId=1`): - envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`) - ações de digitação ainda incluem `message_thread_id` - Herança de tópico: entradas de tópico herdam as configurações do grupo, salvo substituição (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam sobrescritas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` é exclusivo de tópico e não herda dos padrões do grupo. - **Roteamento de agente por tópico**: Cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo: + **Roteamento de agente por tópico**: cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo: ```json5 { @@ -506,8 +507,8 @@ curl "https://api.telegram.org/bot/getUpdates" groups: { "-1001234567890": { topics: { - "1": { agentId: "main" }, // Tópico Geral → agente main - "3": { agentId: "zu" }, // Tópico de desenvolvimento → agente zu + "1": { agentId: "main" }, // Tópico geral → agente main + "3": { agentId: "zu" }, // Tópico de dev → agente zu "5": { agentId: "coder" } // Revisão de código → agente coder } } @@ -519,7 +520,7 @@ curl "https://api.telegram.org/bot/getUpdates" Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3` - **Vínculo persistente de tópico ACP**: Tópicos de fórum podem fixar sessões do harness ACP por meio de vínculos ACP tipados de nível superior: + **Vinculação persistente de tópico ACP**: tópicos de fórum podem fixar sessões do harness ACP por meio de vinculações ACP tipadas de nível superior: - `bindings[]` com `type: "acp"` e `match.channel: "telegram"` @@ -570,13 +571,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Isso atualmente se limita a tópicos de fórum em grupos e supergrupos. + Atualmente isso está limitado a tópicos de fórum em grupos e supergrupos. **Criação de ACP vinculado à thread a partir do chat**: - `/acp spawn --thread here|auto` pode vincular o tópico atual do Telegram a uma nova sessão ACP. - - Mensagens subsequentes no tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`). - - O OpenClaw fixa a mensagem de confirmação de criação no tópico após uma vinculação bem-sucedida. + - Mensagens posteriores do tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`). + - O OpenClaw fixa a mensagem de confirmação de criação dentro do tópico após uma vinculação bem-sucedida. - Requer `channels.telegram.threadBindings.spawnAcpSessions=true`. O contexto do template inclui: @@ -586,7 +587,7 @@ curl "https://api.telegram.org/bot/getUpdates" Comportamento de thread em DM: - - chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão e destinos de resposta conscientes de thread. + - chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão/alvos de resposta com reconhecimento de thread. @@ -596,7 +597,7 @@ curl "https://api.telegram.org/bot/getUpdates" O Telegram diferencia notas de voz de arquivos de áudio. - padrão: comportamento de arquivo de áudio - - tag `[[audio_as_voice]]` na resposta do agente para forçar o envio como nota de voz + - tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz Exemplo de ação de mensagem: @@ -634,7 +635,7 @@ curl "https://api.telegram.org/bot/getUpdates" - WEBP estático: baixado e processado (placeholder ``) - TGS animado: ignorado - - WEBM em vídeo: ignorado + - WEBM de vídeo: ignorado Campos de contexto do sticker: @@ -648,7 +649,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Os stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de vision. + Os stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de visão. Habilite ações de sticker: @@ -681,7 +682,7 @@ curl "https://api.telegram.org/bot/getUpdates" { action: "sticker-search", channel: "telegram", - query: "gato acenando", + query: "cat waving", limit: 5, } ``` @@ -702,18 +703,18 @@ curl "https://api.telegram.org/bot/getUpdates" Observações: - - `own` significa reações de usuário apenas em mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). + - `own` significa reações de usuários apenas em mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). - Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados. - - O Telegram não fornece IDs de thread em atualizações de reação. - - grupos sem fórum são roteados para a sessão de chat do grupo - - grupos com fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico de origem exato + - O Telegram não fornece IDs de thread nas atualizações de reação. + - grupos que não são fórum são roteados para a sessão do chat em grupo + - grupos de fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem `allowed_updates` para polling/Webhook inclui `message_reaction` automaticamente. - - `ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. + + `ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. Ordem de resolução: @@ -724,20 +725,20 @@ curl "https://api.telegram.org/bot/getUpdates" Observações: - - O Telegram espera emoji unicode (por exemplo, "👀"). - - Use `""` para desativar a reação para um canal ou conta. + - O Telegram espera emoji unicode (por exemplo "👀"). + - Use `""` para desabilitar a reação para um canal ou conta. - Gravações de configuração do canal são habilitadas por padrão (`configWrites !== false`). + As gravações de configuração do canal são habilitadas por padrão (`configWrites !== false`). - Gravações acionadas pelo Telegram incluem: + As gravações acionadas pelo Telegram incluem: - eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups` - - `/config set` e `/config unset` (requer habilitação do comando) + - `/config set` e `/config unset` (requer habilitação de comando) - Desative: + Desabilitar: ```json5 { @@ -757,33 +758,33 @@ curl "https://api.telegram.org/bot/getUpdates" Modo Webhook: - defina `channels.telegram.webhookUrl` - - defina `channels.telegram.webhookSecret` (obrigatório quando `webhookUrl` estiver definido) - - opcional `channels.telegram.webhookPath` (padrão `/telegram-webhook`) - - opcional `channels.telegram.webhookHost` (padrão `127.0.0.1`) - - opcional `channels.telegram.webhookPort` (padrão `8787`) + - defina `channels.telegram.webhookSecret` (obrigatório quando a URL do Webhook está definida) + - `channels.telegram.webhookPath` opcional (padrão `/telegram-webhook`) + - `channels.telegram.webhookHost` opcional (padrão `127.0.0.1`) + - `channels.telegram.webhookPort` opcional (padrão `8787`) - O listener local padrão para o modo Webhook se associa a `127.0.0.1:8787`. + O listener local padrão para o modo Webhook se vincula a `127.0.0.1:8787`. Se seu endpoint público for diferente, coloque um proxy reverso na frente e aponte `webhookUrl` para a URL pública. Defina `webhookHost` (por exemplo `0.0.0.0`) quando você intencionalmente precisar de entrada externa. - + - o padrão de `channels.telegram.textChunkLimit` é 4000. - - `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes de dividir por comprimento. - - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia do Telegram recebida e enviada. - - `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não estiver definido, aplica-se o padrão do grammY). - - `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinicializações falso-positivas por travamento de polling. - - o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desativa. - - o contexto suplementar de resposta/citação/encaminhamento atualmente é repassado como recebido. - - as allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar. + - `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho. + - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada no Telegram. + - `channels.telegram.timeoutSeconds` sobrescreve o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). + - `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinicializações falsas de polling travado. + - o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita. + - o contexto suplementar de resposta/citação/encaminhamento é atualmente passado como recebido. + - allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar. - controles de histórico de DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - a configuração `channels.telegram.retry` se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. + - a configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis de API de saída. - O destino de envio da CLI pode ser ID numérico do chat ou nome de usuário: + O alvo de envio da CLI pode ser um ID numérico de chat ou username: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" @@ -800,22 +801,22 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Flags de poll exclusivas do Telegram: + Flags de poll somente do Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` para tópicos de fórum (ou use um destino `:topic:`) + - `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`) - O envio do Telegram também oferece suporte a: + O envio no Telegram também oferece suporte a: - - `--buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite essa superfície - - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads comprimidos de foto ou mídia animada + - `--buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite isso + - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads compactados de foto ou mídia animada Controle de ações: - - `channels.telegram.actions.sendMessage=false` desativa mensagens de saída do Telegram, incluindo polls - - `channels.telegram.actions.poll=false` desativa a criação de polls no Telegram, mantendo envios regulares habilitados + - `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída no Telegram, incluindo polls + - `channels.telegram.actions.poll=false` desabilita a criação de polls no Telegram, mantendo envios normais habilitados @@ -825,38 +826,38 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Caminho de configuração: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (opcional; usa como fallback IDs numéricos de proprietário inferidos de `allowFrom` e `defaultTo` direto quando possível) + - `channels.telegram.execApprovals.approvers` (opcional; usa como fallback IDs numéricos de owners inferidos de `allowFrom` e `defaultTo` de mensagem direta quando possível) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter` - Os aprovadores devem ser IDs numéricos de usuários do Telegram. O Telegram habilita automaticamente aprovações de exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou da configuração numérica de proprietário da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desativar explicitamente o Telegram como cliente nativo de aprovação. Caso contrário, solicitações de aprovação usam outras rotas de aprovação configuradas ou a política de fallback de aprovação de exec. + Os aprovadores devem ser IDs numéricos de usuários do Telegram. O Telegram habilita automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou da configuração numérica de owner da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desabilitar explicitamente o Telegram como cliente nativo de aprovação. Caso contrário, solicitações de aprovação usam fallback para outras rotas de aprovação configuradas ou para a política de fallback de aprovação de exec. - O Telegram também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento de DMs para aprovadores, fanout para canal/tópico e dicas de digitação antes da entrega. + O Telegram também renderiza os botões compartilhados de aprovação usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento para DMs de aprovadores, fanout para canal/tópico e dicas de digitação antes da entrega. Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw - deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser - que aprovações no chat não estão disponíveis ou que a aprovação manual é o único caminho. + só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser + que aprovações por chat estão indisponíveis ou quando a aprovação manual for o único caminho. Regras de entrega: - `target: "dm"` envia prompts de aprovação apenas para DMs dos aprovadores resolvidos - `target: "channel"` envia o prompt de volta para o chat/tópico de origem no Telegram - - `target: "both"` envia para as DMs dos aprovadores e para o chat/tópico de origem + - `target: "both"` envia para DMs dos aprovadores e para o chat/tópico de origem - Apenas aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` nem os botões de aprovação do Telegram. + Apenas aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` e não podem usar botões de aprovação do Telegram. Comportamento de resolução de aprovação: - - IDs prefixados com `plugin:` sempre são resolvidos por aprovações de plugin. - - Outros IDs tentam `exec.approval.resolve` primeiro. - - Se o Telegram também estiver autorizado para aprovações de plugin e o Gateway disser - que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez via + - IDs com prefixo `plugin:` sempre são resolvidos via aprovações de Plugin. + - Outros IDs de aprovação tentam primeiro `exec.approval.resolve`. + - Se o Telegram também estiver autorizado para aprovações de Plugin e o gateway disser + que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez por `plugin.approval.resolve`. - - Negativas/erros reais de aprovação de exec não fazem fallback silencioso para - resolução de aprovação de plugin. + - Negações/erros reais de aprovação de exec não fazem fallback silencioso para + resolução de aprovação de Plugin. - A entrega no canal mostra o texto do comando no chat, portanto habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega a um tópico de fórum, o OpenClaw preserva o tópico tanto para o prompt de aprovação quanto para o acompanhamento pós-aprovação. As aprovações de exec expiram após 30 minutos por padrão. + A entrega no canal mostra o texto do comando no chat, então habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega em um tópico de fórum, o OpenClaw preserva o tópico tanto para o prompt de aprovação quanto para o acompanhamento após a aprovação. As aprovações de exec expiram após 30 minutos por padrão. - Botões de aprovação inline também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície de destino (`dm`, `group` ou `all`). + Botões inline de aprovação também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície de destino (`dm`, `group` ou `all`). Documentação relacionada: [Aprovações de exec](/pt-BR/tools/exec-approvals) @@ -865,7 +866,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Controles de resposta de erro -Quando o agente encontra um erro de entrega ou do provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: +Quando o agente encontra um erro de entrega ou de provider, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | @@ -895,40 +896,40 @@ Substituições por conta, por grupo e por tópico são suportadas (mesma heran - - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total. + - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade completa. - BotFather: `/setprivacy` -> Disable - - depois remova + adicione novamente o bot ao grupo + - então remova + adicione novamente o bot ao grupo - `openclaw channels status` avisa quando a configuração espera mensagens de grupo sem menção. - - `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ser verificado por associação. + - `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ser verificado por membership probe. - teste rápido de sessão: `/activation always`. - + - quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`) - - verifique a associação do bot ao grupo + - verifique a participação do bot no grupo - revise os logs: `openclaw logs --follow` para motivos de ignorar - - autorize a identidade do remetente (pareamento e/ou `allowFrom` numérico) - - a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open` - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de plugin/Skills/personalizados ou desative menus nativos + - autorize a identidade do seu remetente (pareamento e/ou `allowFrom` numérico) + - a autorização de comando ainda se aplica mesmo quando a política de grupo é `open` + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desabilite menus nativos - `setMyCommands failed` com erros de rede/fetch normalmente indica problemas de alcance DNS/HTTPS para `api.telegram.org` - + - - Node 22+ + fetch/proxy personalizado podem acionar comportamento de abort imediato se os tipos de AbortSignal não corresponderem. - - Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 com falha pode causar falhas intermitentes da API do Telegram. + - Node 22+ + fetch/proxy personalizado pode disparar comportamento de aborto imediato se os tipos de AbortSignal não coincidirem. + - Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 com problema pode causar falhas intermitentes na API do Telegram. - Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis. - - Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e recria o transporte do Telegram após 120 segundos sem atividade concluída de long-poll por padrão. - - Aumente `channels.telegram.pollingStallThresholdMs` apenas quando chamadas longas de `getUpdates` estiverem saudáveis, mas seu host ainda relatar reinicializações falso-positivas por travamento de polling. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`. - - Em hosts VPS com saída/TLS direta instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`: + - Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem atividade concluída de long-poll por padrão. + - Aumente `channels.telegram.pollingStallThresholdMs` apenas quando chamadas longas de `getUpdates` estiverem saudáveis, mas seu host ainda relatar reinicializações falsas de polling travado. Travamentos persistentes normalmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`. + - Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`: ```yaml channels: @@ -936,7 +937,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - O Node 22+ usa por padrão `autoSelectFamily=true` (exceto WSL2) e `dnsResultOrder=ipv4first`. + - Node 22+ usa por padrão `autoSelectFamily=true` (exceto WSL2) e `dnsResultOrder=ipv4first`. - Se seu host for WSL2 ou explicitamente funcionar melhor com comportamento somente IPv4, force a seleção de família: ```yaml @@ -946,11 +947,11 @@ channels: autoSelectFamily: false ``` - - Respostas na faixa de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas + - Respostas no intervalo de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas por padrão para downloads de mídia do Telegram. Se um fake-IP confiável ou proxy transparente reescrever `api.telegram.org` para algum outro endereço privado/interno/de uso especial durante downloads de mídia, você pode - optar pelo bypass exclusivo do Telegram: + habilitar o bypass somente para Telegram: ```yaml channels: @@ -959,21 +960,18 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - O mesmo opt-in está disponível por conta em + - A mesma habilitação opcional também está disponível por conta em `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a - flag perigosa desativada primeiro. A mídia do Telegram já permite a faixa de benchmark RFC 2544 - por padrão. + flag perigosa desabilitada primeiro. A mídia do Telegram já permite o intervalo de benchmark RFC 2544 por padrão. `channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as - proteções de SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy - confiáveis e controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge quando eles - sintetizarem respostas privadas ou de uso especial fora da faixa de benchmark RFC 2544. - Deixe desativado para acesso normal do Telegram pela internet pública. + proteções SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy + confiáveis e controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge, quando eles sintetizam respostas privadas ou de uso especial fora do intervalo de benchmark RFC 2544. Deixe isso desabilitado para acesso normal ao Telegram pela internet pública. - - Substituições por ambiente (temporárias): + - Substituições por variável de ambiente (temporárias): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -989,7 +987,7 @@ dig +short api.telegram.org AAAA Mais ajuda: [Solução de problemas do canal](/pt-BR/channels/troubleshooting). -## Ponteiros de referência de configuração do Telegram +## Ponteiros da referência de configuração do Telegram Referência principal: @@ -997,74 +995,75 @@ Referência principal: - `channels.telegram.botToken`: token do bot (BotFather). - `channels.telegram.tokenFile`: lê o token de um caminho de arquivo regular. Symlinks são rejeitados. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: pairing). -- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuários do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do armazenamento de pareamento em fluxos de migração de allowlist. -- `channels.telegram.actions.poll`: habilita ou desabilita a criação de polls no Telegram (padrão: habilitado; ainda requer `sendMessage`). -- `channels.telegram.defaultTo`: destino padrão do Telegram usado por `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido. +- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuários do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do pairing-store em fluxos de migração de allowlist. +- `channels.telegram.actions.poll`: habilita ou desabilita a criação de polls no Telegram (padrão: habilitado; ainda exige `sendMessage`). +- `channels.telegram.defaultTo`: alvo padrão do Telegram usado por `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (padrão: allowlist). -- `channels.telegram.groupAllowFrom`: allowlist de remetentes em grupo (IDs numéricos de usuários do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autenticação. A autenticação de grupo não usa fallback do armazenamento de pareamento de DM (`2026.2.25+`). +- `channels.telegram.groupAllowFrom`: allowlist de remetentes em grupo (IDs numéricos de usuários do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autenticação. A autenticação de grupo não usa fallback do pairing-store de DM (`2026.2.25+`). - Precedência de múltiplas contas: - - Quando dois ou mais IDs de conta estão configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. - - Se nenhum dos dois for definido, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` emite um aviso. + - Quando dois ou mais IDs de conta estão configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar explícito o roteamento padrão. + - Se nenhum dos dois estiver definido, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` emite um aviso. - `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` se aplicam apenas à conta `default`. - Contas nomeadas herdam `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando os valores no nível da conta não estão definidos. - Contas nomeadas não herdam `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. - `channels.telegram.groups`: padrões por grupo + allowlist (use `"*"` para padrões globais). - - `channels.telegram.groups..groupPolicy`: substituição por grupo para `groupPolicy` (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: padrão de exigência de menção. + - `channels.telegram.groups..groupPolicy`: sobrescrita por grupo para `groupPolicy` (`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: padrão de bloqueio por menção. - `channels.telegram.groups..skills`: filtro de Skills (omitir = todas as Skills, vazio = nenhuma). - - `channels.telegram.groups..allowFrom`: substituição por grupo para allowlist de remetentes. + - `channels.telegram.groups..allowFrom`: sobrescrita da allowlist de remetentes por grupo. - `channels.telegram.groups..systemPrompt`: prompt de sistema extra para o grupo. - `channels.telegram.groups..enabled`: desabilita o grupo quando `false`. - - `channels.telegram.groups..topics..*`: substituições por tópico (campos de grupo + `agentId` exclusivo de tópico). - - `channels.telegram.groups..topics..agentId`: roteia este tópico para um agente específico (substitui roteamento no nível de grupo e por binding). -- `channels.telegram.groups..topics..groupPolicy`: substituição por tópico para `groupPolicy` (`open | allowlist | disabled`). -- `channels.telegram.groups..topics..requireMention`: substituição por tópico para exigência de menção. -- `bindings[]` no nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos de vínculo persistente de tópico ACP (veja [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings)). + - `channels.telegram.groups..topics..*`: sobrescritas por tópico (campos de grupo + `agentId` exclusivo de tópico). + - `channels.telegram.groups..topics..agentId`: roteia este tópico para um agente específico (sobrescreve o roteamento no nível do grupo e de bindings). +- `channels.telegram.groups..topics..groupPolicy`: sobrescrita por tópico para `groupPolicy` (`open | allowlist | disabled`). +- `channels.telegram.groups..topics..requireMention`: sobrescrita por tópico para bloqueio por menção. +- `bindings[]` de nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos de vinculação persistente de tópico ACP (veja [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings)). - `channels.telegram.direct..topics..agentId`: roteia tópicos de DM para um agente específico (mesmo comportamento de tópicos de fórum). - `channels.telegram.execApprovals.enabled`: habilita o Telegram como cliente de aprovação de exec baseado em chat para esta conta. -- `channels.telegram.execApprovals.approvers`: IDs de usuários do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o proprietário. +- `channels.telegram.execApprovals.approvers`: IDs de usuários do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o owner. - `channels.telegram.execApprovals.target`: `dm | channel | both` (padrão: `dm`). `channel` e `both` preservam o tópico de origem do Telegram quando presente. -- `channels.telegram.execApprovals.agentFilter`: filtro opcional de ID de agente para prompts de aprovação encaminhados. -- `channels.telegram.execApprovals.sessionFilter`: filtro opcional de chave de sessão (substring ou regex) para prompts de aprovação encaminhados. -- `channels.telegram.accounts..execApprovals`: substituição por conta para roteamento de aprovação de exec no Telegram e autorização de aprovador. +- `channels.telegram.execApprovals.agentFilter`: filtro opcional por ID de agente para prompts de aprovação encaminhados. +- `channels.telegram.execApprovals.sessionFilter`: filtro opcional por chave de sessão (substring ou regex) para prompts de aprovação encaminhados. +- `channels.telegram.accounts..execApprovals`: sobrescrita por conta para roteamento de aprovação de exec no Telegram e autorização de aprovadores. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (padrão: allowlist). -- `channels.telegram.accounts..capabilities.inlineButtons`: substituição por conta. +- `channels.telegram.accounts..capabilities.inlineButtons`: sobrescrita por conta. - `channels.telegram.commands.nativeSkills`: habilita/desabilita comandos nativos de Skills no Telegram. - `channels.telegram.replyToMode`: `off | first | all` (padrão: `off`). -- `channels.telegram.textChunkLimit`: tamanho do chunk de saída (caracteres). -- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento. -- `channels.telegram.linkPreview`: alterna pré-visualizações de links para mensagens de saída (padrão: true). -- `channels.telegram.streaming`: `off | partial | block | progress` (pré-visualização de stream ao vivo; padrão: `partial`; `progress` é mapeado para `partial`; `block` é compatibilidade legada de modo de pré-visualização). O streaming de pré-visualização do Telegram usa uma única mensagem de pré-visualização que é editada no mesmo lugar. -- `channels.telegram.mediaMaxMb`: limite de mídia do Telegram de entrada/saída (MB, padrão: 100). -- `channels.telegram.retry`: política de repetição para auxiliares de envio do Telegram (CLI/ferramentas/ações) em erros recuperáveis da API de saída (attempts, minDelayMs, maxDelayMs, jitter). -- `channels.telegram.network.autoSelectFamily`: substitui `autoSelectFamily` do Node (true=habilita, false=desabilita). O padrão é habilitado no Node 22+, com WSL2 tendo padrão desabilitado. -- `channels.telegram.network.dnsResultOrder`: substitui a ordem de resultados DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in perigoso para ambientes confiáveis com fake-IP ou proxy transparente onde downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão da faixa de benchmark RFC 2544. +- `channels.telegram.textChunkLimit`: tamanho dos blocos de saída (caracteres). +- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho. +- `channels.telegram.linkPreview`: alterna prévias de link para mensagens de saída (padrão: true). +- `channels.telegram.streaming`: `off | partial | block | progress` (prévia de streaming ao vivo; padrão: `partial`; `progress` corresponde a `partial`; `block` é compatibilidade legada com modo de prévia). O streaming de prévia no Telegram usa uma única mensagem de prévia que é editada no mesmo lugar. +- `channels.telegram.streaming.preview.toolProgress`: reutiliza a mensagem de prévia ao vivo para atualizações de ferramenta/progresso quando o streaming de prévia está ativo (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso. +- `channels.telegram.mediaMaxMb`: limite de mídia recebida/enviada no Telegram (MB, padrão: 100). +- `channels.telegram.retry`: política de retry para helpers de envio do Telegram (CLI/ferramentas/ações) em erros recuperáveis de API de saída (tentativas, `minDelayMs`, `maxDelayMs`, jitter). +- `channels.telegram.network.autoSelectFamily`: sobrescreve `autoSelectFamily` do Node (true=habilita, false=desabilita). O padrão é habilitado no Node 22+, com WSL2 tendo padrão desabilitado. +- `channels.telegram.network.dnsResultOrder`: sobrescreve a ordem de resultado DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: habilitação perigosa opcional para ambientes confiáveis com fake-IP ou proxy transparente nos quais downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão do intervalo de benchmark RFC 2544. - `channels.telegram.proxy`: URL de proxy para chamadas da Bot API (SOCKS/HTTP). -- `channels.telegram.webhookUrl`: habilita o modo Webhook (requer `channels.telegram.webhookSecret`). +- `channels.telegram.webhookUrl`: habilita o modo Webhook (exige `channels.telegram.webhookSecret`). - `channels.telegram.webhookSecret`: segredo do Webhook (obrigatório quando `webhookUrl` está definido). - `channels.telegram.webhookPath`: caminho local do Webhook (padrão `/telegram-webhook`). - `channels.telegram.webhookHost`: host local de bind do Webhook (padrão `127.0.0.1`). - `channels.telegram.webhookPort`: porta local de bind do Webhook (padrão `8787`). - `channels.telegram.actions.reactions`: controla reações de ferramenta do Telegram. -- `channels.telegram.actions.sendMessage`: controla envios de mensagens de ferramenta do Telegram. -- `channels.telegram.actions.deleteMessage`: controla exclusões de mensagens de ferramenta do Telegram. -- `channels.telegram.actions.sticker`: controla ações de sticker do Telegram — envio e busca (padrão: false). +- `channels.telegram.actions.sendMessage`: controla envios de mensagem de ferramenta do Telegram. +- `channels.telegram.actions.deleteMessage`: controla exclusões de mensagem de ferramenta do Telegram. +- `channels.telegram.actions.sticker`: controla ações de sticker do Telegram — enviar e pesquisar (padrão: false). - `channels.telegram.reactionNotifications`: `off | own | all` — controla quais reações acionam eventos de sistema (padrão: `own` quando não definido). - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controla a capacidade de reação do agente (padrão: `minimal` quando não definido). -- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Há suporte a substituições por conta/grupo/tópico. +- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Sobrescritas por conta/grupo/tópico são suportadas. - `channels.telegram.errorCooldownMs`: ms mínimos entre respostas de erro para o mesmo chat (padrão: `60000`). Evita spam de erros durante indisponibilidades. - [Referência de configuração - Telegram](/pt-BR/gateway/configuration-reference#telegram) -Campos específicos do Telegram com alto sinal: +Campos específicos do Telegram com maior sinal: - inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados) -- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` no nível superior (`type: "acp"`) +- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`) - aprovações de exec: `execApprovals`, `accounts.*.execApprovals` - comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands` -- threading/respostas: `replyToMode` -- streaming: `streaming` (pré-visualização), `blockStreaming` +- threads/respostas: `replyToMode` +- streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming` - formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - mídia/rede: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` diff --git a/docs/pt-BR/gateway/multiple-gateways.md b/docs/pt-BR/gateway/multiple-gateways.md index c2bff2cd3..26630d689 100644 --- a/docs/pt-BR/gateway/multiple-gateways.md +++ b/docs/pt-BR/gateway/multiple-gateways.md @@ -1,100 +1,129 @@ --- read_when: - Executando mais de um Gateway na mesma máquina - - Você precisa de configuração/estado/portas isolados por Gateway -summary: Executar vários Gateways do OpenClaw no mesmo host (isolamento, portas e perfis) + - Você precisa de configuração/estado/portas isolados para cada Gateway +summary: Executar vários Gateways do OpenClaw em um único host (isolamento, portas e perfis) title: Vários Gateways x-i18n: - generated_at: "2026-04-05T12:41:51Z" + generated_at: "2026-04-21T17:45:33Z" model: gpt-5.4 provider: openai - source_hash: 061f204bf56b28c6bd0e2c9aee6c561a8a162ca219060117fea4d3a007f01899 + source_hash: 8c3fcb921bc6596040e9249467964bd9dcd40ea7c16e958bb378247b0f994a7b source_path: gateway/multiple-gateways.md workflow: 15 --- # Vários Gateways (mesmo host) -A maioria das configurações deve usar um único Gateway, porque um único Gateway pode lidar com várias conexões de mensagens e agentes. Se você precisar de isolamento mais forte ou redundância (por exemplo, um bot de resgate), execute Gateways separados com perfis/portas isolados. +A maioria das configurações deve usar um Gateway, porque um único Gateway pode lidar com várias conexões de mensageria e agents. Se você precisar de isolamento mais forte ou redundância (por exemplo, um bot de resgate), execute Gateways separados com perfis/portas isolados. -## Checklist de isolamento (obrigatório) +## Lista de verificação de isolamento (obrigatória) - `OPENCLAW_CONFIG_PATH` — arquivo de configuração por instância -- `OPENCLAW_STATE_DIR` — sessões, credenciais, caches por instância +- `OPENCLAW_STATE_DIR` — sessões, credenciais e caches por instância - `agents.defaults.workspace` — raiz de workspace por instância -- `gateway.port` (ou `--port`) — única por instância -- Portas derivadas (browser/canvas) não podem se sobrepor +- `gateway.port` (ou `--port`) — exclusivo por instância +- As portas derivadas (browser/canvas) não devem se sobrepor -Se esses itens forem compartilhados, você terá corridas de configuração e conflitos de porta. +Se eles forem compartilhados, você terá condições de corrida de configuração e conflitos de porta. -## Recomendado: perfis (`--profile`) +## Recomendado: use o perfil padrão para o principal e um perfil nomeado para o resgate -Perfis definem automaticamente o escopo de `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` e adicionam sufixos aos nomes dos serviços. +Os perfis aplicam escopo automaticamente a `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` e adicionam sufixos aos nomes de serviço. Para a maioria das configurações com bot de resgate, mantenha o bot principal no perfil padrão e dê apenas ao bot de resgate um perfil nomeado, como `rescue`. ```bash -# principal -openclaw --profile main setup -openclaw --profile main gateway --port 18789 +# principal (perfil padrão) +openclaw setup +openclaw gateway --port 18789 # resgate openclaw --profile rescue setup openclaw --profile rescue gateway --port 19001 ``` -Serviços por perfil: +Serviços: ```bash -openclaw --profile main gateway install +openclaw gateway install openclaw --profile rescue gateway install ``` +Se você quiser que ambos os Gateways usem perfis nomeados, isso também funciona, mas não é obrigatório. + ## Guia do bot de resgate -Execute um segundo Gateway no mesmo host com seu próprio: +Configuração recomendada: -- perfil/configuração -- diretório de estado -- workspace -- porta base (mais as portas derivadas) +- mantenha o bot principal no perfil padrão +- execute o bot de resgate em `--profile rescue` +- use um bot do Telegram completamente separado para a conta de resgate +- mantenha o bot de resgate em uma porta base diferente, como `19001` -Isso mantém o bot de resgate isolado do bot principal, para que ele possa depurar ou aplicar alterações de configuração se o bot principal estiver fora do ar. +Isso mantém o bot de resgate isolado do bot principal, para que ele possa depurar ou aplicar alterações de configuração se o bot principal estiver fora do ar. Deixe pelo menos 20 portas entre as portas base para que as portas derivadas de browser/canvas/CDP nunca colidam. -Espaçamento de portas: deixe pelo menos 20 portas entre as portas base para que as portas derivadas de browser/canvas/CDP nunca colidam. +### Canal/conta de resgate recomendado -### Como instalar (bot de resgate) +Para a maioria das configurações, use um bot do Telegram completamente separado para o perfil de resgate. + +Por que Telegram: + +- fácil de manter apenas para operadores +- token e identidade de bot separados +- independente do canal/da instalação do app do bot principal +- caminho de recuperação simples baseado em DM quando o bot principal estiver com problema + +A parte importante é a independência total: conta de bot separada, credenciais separadas, perfil do OpenClaw separado, workspace separado e porta separada. + +### Fluxo de instalação recomendado + +Use isto como configuração padrão, a menos que você tenha um motivo forte para fazer algo diferente: ```bash -# Bot principal (existente ou novo, sem parâmetro --profile) -# Executa na porta 18789 + portas do Chrome CDC/Canvas/... +# Bot principal (perfil padrão, porta 18789) openclaw onboard openclaw gateway install -# Bot de resgate (perfil + portas isolados) +# Bot de resgate (bot do Telegram separado, perfil separado, porta 19001) openclaw --profile rescue onboard -# Observações: -# - o nome do workspace receberá o sufixo -rescue por padrão -# - A porta deve ser pelo menos 18789 + 20 portas, -# é melhor escolher uma porta base completamente diferente, como 19789, -# - o restante da configuração inicial é igual ao normal - -# Para instalar o serviço (se isso não aconteceu automaticamente durante a configuração) openclaw --profile rescue gateway install ``` -## Mapeamento de portas (derivadas) +Durante `openclaw --profile rescue onboard`: + +- use o token do bot do Telegram separado +- mantenha o perfil `rescue` +- use uma porta base pelo menos 20 acima da do bot principal +- aceite o workspace de resgate padrão, a menos que você já gerencie um por conta própria + +Se o onboarding já tiver instalado o serviço de resgate para você, o `gateway install` final não será necessário. + +### O que o onboarding altera + +`openclaw --profile rescue onboard` usa o fluxo normal de onboarding, mas grava tudo em um perfil separado. + +Na prática, isso significa que o bot de resgate recebe seu próprio: + +- arquivo de configuração +- diretório de estado +- workspace (por padrão `~/.openclaw/workspace-rescue`) +- nome de serviço gerenciado + +Fora isso, os prompts são os mesmos do onboarding normal. + +## Mapeamento de portas (derivado) Porta base = `gateway.port` (ou `OPENCLAW_GATEWAY_PORT` / `--port`). -- porta do serviço de controle do navegador = base + 2 (somente loopback) -- o host de canvas é servido no servidor HTTP do Gateway (mesma porta de `gateway.port`) -- portas CDP do perfil do navegador são alocadas automaticamente a partir de `browser.controlPort + 9 .. + 108` +- porta do serviço de controle do browser = base + 2 (apenas loopback local) +- o host do canvas é servido no servidor HTTP do Gateway (mesma porta que `gateway.port`) +- as portas CDP do perfil do browser são alocadas automaticamente a partir de `browser.controlPort + 9 .. + 108` -Se você substituir qualquer uma delas na configuração ou no ambiente, deverá mantê-las exclusivas por instância. +Se você substituir qualquer um deles em config ou env, deve mantê-los exclusivos por instância. -## Observações sobre Browser/CDP (armadilha comum) +## Observações sobre browser/CDP (armadilha comum) - **Não** fixe `browser.cdpUrl` nos mesmos valores em várias instâncias. -- Cada instância precisa de sua própria porta de controle do navegador e intervalo de CDP (derivados da porta do gateway). +- Cada instância precisa de sua própria porta de controle do browser e de sua própria faixa de CDP (derivadas da porta do Gateway). - Se você precisar de portas CDP explícitas, defina `browser.profiles..cdpPort` por instância. - Chrome remoto: use `browser.profiles..cdpUrl` (por perfil, por instância). @@ -102,7 +131,7 @@ Se você substituir qualquer uma delas na configuração ou no ambiente, deverá ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \ -OPENCLAW_STATE_DIR=~/.openclaw-main \ +OPENCLAW_STATE_DIR=~/.openclaw \ openclaw gateway --port 18789 OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \ @@ -113,15 +142,15 @@ openclaw gateway --port 19001 ## Verificações rápidas ```bash -openclaw --profile main gateway status --deep +openclaw gateway status --deep openclaw --profile rescue gateway status --deep openclaw --profile rescue gateway probe -openclaw --profile main status +openclaw status openclaw --profile rescue status openclaw --profile rescue browser status ``` Interpretação: -- `gateway status --deep` ajuda a detectar serviços launchd/systemd/schtasks desatualizados de instalações mais antigas. +- `gateway status --deep` ajuda a detectar serviços launchd/systemd/schtasks antigos de instalações anteriores. - O texto de aviso de `gateway probe`, como `multiple reachable gateways detected`, é esperado apenas quando você executa intencionalmente mais de um gateway isolado. diff --git a/docs/pt-BR/tools/slash-commands.md b/docs/pt-BR/tools/slash-commands.md index 61978f248..316280adb 100644 --- a/docs/pt-BR/tools/slash-commands.md +++ b/docs/pt-BR/tools/slash-commands.md @@ -2,35 +2,35 @@ read_when: - Usando ou configurando comandos de chat - Depurando o roteamento de comandos ou permissões -summary: 'Comandos slash: texto vs nativo, configuração e comandos compatíveis' -title: Comandos slash +summary: 'Comandos de barra: texto vs nativos, configuração e comandos compatíveis' +title: Comandos de barra x-i18n: - generated_at: "2026-04-21T13:39:21Z" + generated_at: "2026-04-21T17:45:33Z" model: gpt-5.4 provider: openai - source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d + source_hash: 26923608329ba2aeece2d4bc8edfa40ae86e03719a9f590f26ff79f57d97521d source_path: tools/slash-commands.md workflow: 15 --- -# Comandos slash +# Comandos de barra Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **autônoma** que começa com `/`. -O comando de chat bash somente-host usa `! ` (com `/bash ` como alias). +O comando de chat bash somente do host usa `! ` (com `/bash ` como alias). -Existem dois sistemas relacionados: +Há dois sistemas relacionados: - **Comandos**: mensagens autônomas `/...`. - **Diretivas**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - As diretivas são removidas da mensagem antes que o modelo a veja. - - Em mensagens normais de chat (não somente-diretiva), elas são tratadas como “dicas inline” e **não** persistem configurações da sessão. - - Em mensagens somente-diretiva (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação. - - As diretivas são aplicadas apenas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única - lista de permissões usada; caso contrário, a autorização virá das listas de permissões/pareamento do canal mais `commands.useAccessGroups`. - Remetentes não autorizados verão as diretivas tratadas como texto simples. + - Em mensagens normais de chat (não apenas com diretivas), elas são tratadas como “dicas inline” e **não** persistem as configurações da sessão. + - Em mensagens somente com diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação. + - As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única + allowlist usada; caso contrário, a autorização vem das allowlists/emparelhamento do canal mais `commands.useAccessGroups`. + Remetentes não autorizados veem as diretivas tratadas como texto simples. -Também há alguns **atalhos inline** (somente remetentes em lista de permissões/autorizados): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -Eles são executados imediatamente, são removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal. +Também há alguns **atalhos inline** (somente remetentes autorizados/na allowlist): `/help`, `/commands`, `/status`, `/whoami` (`/id`). +Eles são executados imediatamente, removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal. ## Configuração @@ -59,109 +59,110 @@ Eles são executados imediatamente, são removidos antes que o modelo veja a men } ``` -- `commands.text` (padrão `true`) habilita o parsing de `/...` em mensagens de chat. - - Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), os comandos de texto continuam funcionando mesmo que você defina isso como `false`. +- `commands.text` (padrão `true`) ativa a análise de `/...` em mensagens de chat. + - Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), os comandos de texto ainda funcionam mesmo se você definir isso como `false`. - `commands.native` (padrão `"auto"`) registra comandos nativos. - - Auto: ligado para Discord/Telegram; desligado para Slack (até você adicionar comandos slash); ignorado para provedores sem suporte nativo. + - Auto: ligado para Discord/Telegram; desligado para Slack (até você adicionar slash commands); ignorado para provedores sem suporte nativo. - Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para substituir por provedor (bool ou `"auto"`). - - `false` limpa comandos registrados anteriormente no Discord/Telegram na inicialização. Os comandos do Slack são gerenciados no app Slack e não são removidos automaticamente. -- `commands.nativeSkills` (padrão `"auto"`) registra comandos de **skill** nativamente quando compatível. - - Auto: ligado para Discord/Telegram; desligado para Slack (o Slack exige criar um comando slash por skill). + - `false` limpa comandos registrados anteriormente no Discord/Telegram na inicialização. Os comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente. +- `commands.nativeSkills` (padrão `"auto"`) registra comandos de **skill** de forma nativa quando houver suporte. + - Auto: ligado para Discord/Telegram; desligado para Slack (o Slack exige a criação de um slash command por skill). - Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para substituir por provedor (bool ou `"auto"`). -- `commands.bash` (padrão `false`) habilita `! ` para executar comandos de shell no host (`/bash ` é um alias; exige listas de permissões de `tools.elevated`). -- `commands.bashForegroundMs` (padrão `2000`) controla por quanto tempo o bash espera antes de mudar para o modo em segundo plano (`0` envia para segundo plano imediatamente). -- `commands.config` (padrão `false`) habilita `/config` (lê/grava `openclaw.json`). -- `commands.mcp` (padrão `false`) habilita `/mcp` (lê/grava a configuração de MCP gerenciada pelo OpenClaw em `mcp.servers`). -- `commands.plugins` (padrão `false`) habilita `/plugins` (descoberta/status de Plugin mais controles de instalar + habilitar/desabilitar). -- `commands.debug` (padrão `false`) habilita `/debug` (substituições somente de runtime). -- `commands.restart` (padrão `true`) habilita `/restart` mais ações de ferramenta de reinicialização do Gateway. -- `commands.ownerAllowFrom` (opcional) define a lista de permissões explícita de owner para superfícies de comando/ferramenta exclusivas do owner. Isso é separado de `commands.allowFrom`. -- `commands.ownerDisplay` controla como ids de owner aparecem no prompt de sistema: `raw` ou `hash`. +- `commands.bash` (padrão `false`) ativa `! ` para executar comandos do shell do host (`/bash ` é um alias; requer allowlists de `tools.elevated`). +- `commands.bashForegroundMs` (padrão `2000`) controla quanto tempo o bash espera antes de mudar para o modo em segundo plano (`0` envia para segundo plano imediatamente). +- `commands.config` (padrão `false`) ativa `/config` (lê/grava `openclaw.json`). +- `commands.mcp` (padrão `false`) ativa `/mcp` (lê/grava a configuração de MCP gerenciada pelo OpenClaw em `mcp.servers`). +- `commands.plugins` (padrão `false`) ativa `/plugins` (descoberta/status de plugins mais controles de instalar + ativar/desativar). +- `commands.debug` (padrão `false`) ativa `/debug` (substituições somente de runtime). +- `commands.restart` (padrão `true`) ativa `/restart` mais ações de ferramenta para reiniciar o gateway. +- `commands.ownerAllowFrom` (opcional) define a allowlist explícita do proprietário para superfícies de comandos/ferramentas exclusivas do proprietário. Isso é separado de `commands.allowFrom`. +- `commands.ownerDisplay` controla como os ids do proprietário aparecem no prompt do sistema: `raw` ou `hash`. - `commands.ownerDisplaySecret` opcionalmente define o segredo HMAC usado quando `commands.ownerDisplay="hash"`. -- `commands.allowFrom` (opcional) define uma lista de permissões por provedor para autorização de comandos. Quando configurado, ela é a - única fonte de autorização para comandos e diretivas (listas de permissões/pareamento do canal e `commands.useAccessGroups` - são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o substituem. -- `commands.useAccessGroups` (padrão `true`) aplica listas de permissões/políticas para comandos quando `commands.allowFrom` não está definido. +- `commands.allowFrom` (opcional) define uma allowlist por provedor para autorização de comandos. Quando configurado, ela é a + única fonte de autorização para comandos e diretivas (allowlists/emparelhamento do canal e `commands.useAccessGroups` + são ignorados). Use `"*"` para um padrão global; chaves específicas do provedor têm precedência. +- `commands.useAccessGroups` (padrão `true`) aplica allowlists/políticas para comandos quando `commands.allowFrom` não está definido. ## Lista de comandos -Fonte de verdade atual: +Fonte da verdade atual: -- comandos embutidos do núcleo vêm de `src/auto-reply/commands-registry.shared.ts` -- comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts` -- comandos de Plugin vêm de chamadas `registerCommand()` do Plugin -- a disponibilidade real no seu Gateway ainda depende de flags de configuração, superfície do canal e Plugins instalados/habilitados +- os comandos embutidos do núcleo vêm de `src/auto-reply/commands-registry.shared.ts` +- os comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts` +- os comandos de plugins vêm de chamadas `registerCommand()` do plugin +- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície do canal e plugins instalados/ativados ### Comandos embutidos do núcleo Comandos embutidos disponíveis hoje: - `/new [model]` inicia uma nova sessão; `/reset` é o alias de redefinição. -- `/compact [instructions]` faz Compaction do contexto da sessão. Consulte [/concepts/compaction](/pt-BR/concepts/compaction). -- `/stop` aborta a execução atual. -- `/session idle ` e `/session max-age ` gerenciam a expiração do vínculo de thread. -- `/think ` define o nível de thinking. As opções vêm do perfil do provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou `on` binário apenas onde houver suporte. Aliases: `/thinking`, `/t`. +- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão reutilizados do backend CLI e executa novamente, no lugar, o carregamento inicial/de prompt do sistema. +- `/compact [instructions]` compacta o contexto da sessão. Veja [/concepts/compaction](/pt-BR/concepts/compaction). +- `/stop` interrompe a execução atual. +- `/session idle ` e `/session max-age ` gerenciam a expiração do vínculo da thread. +- `/think ` define o nível de raciocínio. As opções vêm do perfil do provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou apenas binário `on` quando houver suporte. Aliases: `/thinking`, `/t`. - `/verbose on|off|full` alterna a saída detalhada. Alias: `/v`. -- `/trace on|off` alterna a saída de rastreamento de Plugin para a sessão atual. +- `/trace on|off` alterna a saída de rastreamento de plugin para a sessão atual. - `/fast [status|on|off]` mostra ou define o modo rápido. -- `/reasoning [on|off|stream]` alterna a visibilidade de reasoning. Alias: `/reason`. +- `/reasoning [on|off|stream]` alterna a visibilidade do raciocínio. Alias: `/reason`. - `/elevated [on|off|ask|full]` alterna o modo elevado. Alias: `/elev`. -- `/exec host= security= ask= node=` mostra ou define padrões de exec. +- `/exec host= security= ask= node=` mostra ou define os padrões de execução. - `/model [name|#|status]` mostra ou define o modelo. - `/models [provider] [page] [limit=|size=|all]` lista provedores ou modelos de um provedor. - `/queue ` gerencia o comportamento da fila (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) mais opções como `debounce:2s cap:25 drop:summarize`. - `/help` mostra o resumo curto de ajuda. - `/commands` mostra o catálogo de comandos gerado. -- `/tools [compact|verbose]` mostra o que o agente atual pode usar agora. -- `/status` mostra o status do runtime, incluindo uso/quota do provedor quando disponível. -- `/tasks` lista tarefas ativas/recentes em segundo plano da sessão atual. +- `/tools [compact|verbose]` mostra o que o agente atual pode usar neste momento. +- `/status` mostra o status do runtime, incluindo uso/cota do provedor quando disponível. +- `/tasks` lista tarefas em segundo plano ativas/recentes para a sessão atual. - `/context [list|detail|json]` explica como o contexto é montado. - `/export-session [path]` exporta a sessão atual para HTML. Alias: `/export`. - `/whoami` mostra seu id de remetente. Alias: `/id`. - `/skill [input]` executa uma skill pelo nome. -- `/allowlist [list|add|remove] ...` gerencia entradas da lista de permissões. Somente texto. -- `/approve ` resolve prompts de aprovação do exec. -- `/btw ` faz uma pergunta lateral sem alterar o contexto futuro da sessão. Consulte [/tools/btw](/pt-BR/tools/btw). -- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes da sessão atual. +- `/allowlist [list|add|remove] ...` gerencia entradas da allowlist. Somente texto. +- `/approve ` resolve prompts de aprovação de execução. +- `/btw ` faz uma pergunta paralela sem alterar o contexto futuro da sessão. Veja [/tools/btw](/pt-BR/tools/btw). +- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes para a sessão atual. - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gerencia sessões ACP e opções de runtime. -- `/focus ` vincula a thread atual do Discord ou tópico/conversa do Telegram a um destino de sessão. +- `/focus ` vincula a thread atual do Discord ou o tópico/conversa do Telegram a um alvo de sessão. - `/unfocus` remove o vínculo atual. -- `/agents` lista agentes vinculados à thread da sessão atual. -- `/kill ` aborta um ou todos os subagentes em execução. +- `/agents` lista agentes vinculados à thread para a sessão atual. +- `/kill ` interrompe um ou todos os subagentes em execução. - `/steer ` envia direcionamento para um subagente em execução. Alias: `/tell`. -- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente owner. Exige `commands.config: true`. -- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente owner. Exige `commands.mcp: true`. -- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado do Plugin. `/plugin` é um alias. Somente owner para gravações. Exige `commands.plugins: true`. -- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente owner. Exige `commands.debug: true`. +- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente proprietário. Requer `commands.config: true`. +- `/mcp show|get|set|unset` lê ou grava a configuração do servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente proprietário. Requer `commands.mcp: true`. +- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado do plugin. `/plugin` é um alias. Somente proprietário para gravações. Requer `commands.plugins: true`. +- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente proprietário. Requer `commands.debug: true`. - `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custo. -- `/tts on|off|status|provider|limit|summary|audio|help` controla TTS. Consulte [/tools/tts](/pt-BR/tools/tts). -- `/restart` reinicia o OpenClaw quando habilitado. Padrão: habilitado; defina `commands.restart: false` para desabilitá-lo. -- `/activation mention|always` define o modo de ativação de grupo. -- `/send on|off|inherit` define a política de envio. Somente owner. -- `/bash ` executa um comando de shell no host. Somente texto. Alias: `! `. Exige `commands.bash: true` mais listas de permissões de `tools.elevated`. +- `/tts on|off|status|provider|limit|summary|audio|help` controla TTS. Veja [/tools/tts](/pt-BR/tools/tts). +- `/restart` reinicia o OpenClaw quando ativado. Padrão: ativado; defina `commands.restart: false` para desativá-lo. +- `/activation mention|always` define o modo de ativação em grupo. +- `/send on|off|inherit` define a política de envio. Somente proprietário. +- `/bash ` executa um comando do shell do host. Somente texto. Alias: `! `. Requer `commands.bash: true` mais allowlists de `tools.elevated`. - `!poll [sessionId]` verifica um trabalho bash em segundo plano. - `!stop [sessionId]` interrompe um trabalho bash em segundo plano. ### Comandos dock gerados -Comandos dock são gerados a partir de Plugins de canal com suporte a comando nativo. Conjunto incluído atual: +Os comandos dock são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto empacotado atual: - `/dock-discord` (alias: `/dock_discord`) - `/dock-mattermost` (alias: `/dock_mattermost`) - `/dock-slack` (alias: `/dock_slack`) - `/dock-telegram` (alias: `/dock_telegram`) -### Comandos de Plugin incluídos +### Comandos de plugins empacotados -Plugins incluídos podem adicionar mais comandos slash. Comandos incluídos atuais neste repositório: +Os plugins empacotados podem adicionar mais slash commands. Comandos empacotados atuais neste repositório: -- `/dreaming [on|off|status|help]` alterna Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de pareamento/configuração de dispositivo. Consulte [Pairing](/pt-BR/channels/pairing). -- `/phone status|arm [duration]|disarm` arma temporariamente comandos de alto risco do node de telefone. +- `/dreaming [on|off|status|help]` alterna o dreaming de memória. Veja [Dreaming](/pt-BR/concepts/dreaming). +- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de emparelhamento/configuração do dispositivo. Veja [Pairing](/pt-BR/channels/pairing). +- `/phone status|arm [duration]|disarm` arma temporariamente comandos de Node do telefone de alto risco. - `/voice status|list [limit]|set ` gerencia a configuração de voz do Talk. No Discord, o nome do comando nativo é `/talkvoice`. -- `/card ...` envia presets de rich card do LINE. Consulte [LINE](/pt-BR/channels/line). -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` inspeciona e controla o harness do app-server Codex incluído. Consulte [Codex Harness](/pt-BR/plugins/codex-harness). -- Comandos somente de QQBot: +- `/card ...` envia predefinições de rich card do LINE. Veja [LINE](/pt-BR/channels/line). +- `/codex status|models|threads|resume|compact|review|account|mcp|skills` inspeciona e controla o harness app-server Codex empacotado. Veja [Codex Harness](/pt-BR/plugins/codex-harness). +- Comandos somente do QQBot: - `/bot-ping` - `/bot-version` - `/bot-help` @@ -170,71 +171,71 @@ Plugins incluídos podem adicionar mais comandos slash. Comandos incluídos atua ### Comandos dinâmicos de skill -Skills invocáveis por usuário também são expostas como comandos slash: +As skills invocáveis pelo usuário também são expostas como slash commands: -- `/skill [input]` sempre funciona como ponto de entrada genérico. -- skills também podem aparecer como comandos diretos como `/prose` quando a skill/Plugin os registra. +- `/skill [input]` sempre funciona como o ponto de entrada genérico. +- as skills também podem aparecer como comandos diretos como `/prose` quando a skill/o plugin os registra. - o registro nativo de comandos de skill é controlado por `commands.nativeSkills` e `channels..commands.nativeSkills`. -Observações: +Notas: -- Os comandos aceitam um `:` opcional entre o comando e os argumentos (ex.: `/think: high`, `/send: on`, `/help:`). -- `/new ` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência aproximada); se não houver correspondência, o texto será tratado como corpo da mensagem. -- Para a divisão completa de uso por provedor, use `openclaw status --usage`. -- `/allowlist add|remove` exige `commands.config=true` e respeita `configWrites` do canal. -- Em canais com múltiplas contas, `/allowlist --account ` direcionado à configuração e `/config set channels..accounts....` também respeitam `configWrites` da conta de destino. +- Os comandos aceitam um `:` opcional entre o comando e os args (por exemplo, `/think: high`, `/send: on`, `/help:`). +- `/new ` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência difusa); se não houver correspondência, o texto é tratado como o corpo da mensagem. +- Para o detalhamento completo de uso por provedor, use `openclaw status --usage`. +- `/allowlist add|remove` requer `commands.config=true` e respeita `configWrites` do canal. +- Em canais com várias contas, `/allowlist --account ` direcionado à configuração e `/config set channels..accounts....` também respeitam `configWrites` da conta de destino. - `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo local de custo a partir dos logs de sessão do OpenClaw. -- `/restart` vem habilitado por padrão; defina `commands.restart: false` para desabilitá-lo. -- `/plugins install ` aceita as mesmas especificações de Plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:`. -- `/plugins enable|disable` atualiza a configuração do Plugin e pode solicitar uma reinicialização. -- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (exige `channels.discord.voice` e comandos nativos; não disponível como texto). -- Comandos de vínculo de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que vínculos de thread efetivos estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`). -- Referência de comando ACP e comportamento de runtime: [Agentes ACP](/pt-BR/tools/acp-agents). -- `/verbose` é voltado para depuração e visibilidade extra; mantenha-o **desligado** no uso normal. -- `/trace` é mais restrito que `/verbose`: ele revela apenas linhas de trace/debug do Plugin e mantém desativado o chatter normal e detalhado de ferramentas. -- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI de Sessions para limpá-la e voltar aos padrões da configuração. -- `/fast` é específico do provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos de Responses, enquanto solicitações Anthropic públicas diretas, incluindo tráfego autenticado por OAuth enviado a `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic). -- Resumos de falha de ferramenta continuam sendo mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`. -- `/reasoning`, `/verbose` e `/trace` são arriscados em configurações de grupo: podem revelar reasoning interno, saída de ferramenta ou diagnósticos de Plugin que você não pretendia expor. Prefira mantê-los desligados, especialmente em chats em grupo. +- `/restart` é ativado por padrão; defina `commands.restart: false` para desativá-lo. +- `/plugins install ` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:`. +- `/plugins enable|disable` atualiza a configuração do plugin e pode solicitar um reinício. +- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (requer `channels.discord.voice` e comandos nativos; não disponível como texto). +- Os comandos de vínculo de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que os vínculos de thread efetivos estejam ativados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`). +- Referência do comando ACP e comportamento de runtime: [ACP Agents](/pt-BR/tools/acp-agents). +- `/verbose` é destinado a depuração e visibilidade extra; mantenha-o **desativado** no uso normal. +- `/trace` é mais restrito que `/verbose`: ele apenas revela linhas de rastreamento/depuração pertencentes ao plugin e mantém desativado o chatter normal detalhado de ferramentas. +- `/fast on|off` persiste uma substituição da sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões da configuração. +- `/fast` é específico por provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos Responses, enquanto solicitações públicas diretas para Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Veja [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic). +- Resumos de falha de ferramenta ainda são mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`. +- `/reasoning`, `/verbose` e `/trace` são arriscados em ambientes de grupo: podem revelar raciocínio interno, saída de ferramenta ou diagnósticos de plugin que você não pretendia expor. Prefira deixá-los desativados, especialmente em chats de grupo. - `/model` persiste imediatamente o novo modelo da sessão. - Se o agente estiver ocioso, a próxima execução o usará imediatamente. - Se uma execução já estiver ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia com o novo modelo em um ponto limpo de nova tentativa. -- Se a atividade de ferramenta ou a saída de resposta já tiver começado, a troca pendente pode permanecer em fila até uma oportunidade posterior de nova tentativa ou até o próximo turno do usuário. -- **Caminho rápido:** mensagens somente-comando de remetentes em lista de permissões são tratadas imediatamente (ignorando fila + modelo). -- **Bloqueio por menção em grupo:** mensagens somente-comando de remetentes em lista de permissões ignoram exigências de menção. -- **Atalhos inline (somente remetentes em lista de permissões):** certos comandos também funcionam quando embutidos em uma mensagem normal e são removidos antes que o modelo veja o texto restante. +- Se a atividade de ferramenta ou a saída da resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário. +- **Caminho rápido:** mensagens somente com comandos de remetentes na allowlist são tratadas imediatamente (ignorando fila + modelo). +- **Bloqueio por menção em grupo:** mensagens somente com comandos de remetentes na allowlist ignoram requisitos de menção. +- **Atalhos inline (somente remetentes na allowlist):** certos comandos também funcionam quando incorporados em uma mensagem normal e são removidos antes que o modelo veja o restante do texto. - Exemplo: `hey /status` aciona uma resposta de status, e o texto restante continua pelo fluxo normal. - Atualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`). -- Mensagens somente-comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples. -- **Comandos de skill:** Skills `user-invocable` são expostas como comandos slash. Os nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (ex.: `_2`). - - `/skill [input]` executa uma skill pelo nome (útil quando limites de comando nativo impedem comandos por skill). +- Mensagens somente com comandos não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples. +- **Comandos de skill:** skills `user-invocable` são expostas como slash commands. Os nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`). + - `/skill [input]` executa uma skill pelo nome (útil quando limites de comandos nativos impedem comandos por skill). - Por padrão, comandos de skill são encaminhados ao modelo como uma solicitação normal. - - Skills podem opcionalmente declarar `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo). - - Exemplo: `/prose` (Plugin OpenProse) — consulte [OpenProse](/pt-BR/prose). -- **Argumentos de comando nativo:** o Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botões quando um comando oferece opções e você omite o argumento. + - As skills podem opcionalmente declarar `command-dispatch: tool` para encaminhar o comando diretamente para uma ferramenta (determinístico, sem modelo). + - Exemplo: `/prose` (plugin OpenProse) — veja [OpenProse](/pt-BR/prose). +- **Argumentos de comando nativo:** o Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite args obrigatórios). Telegram e Slack mostram um menu de botões quando um comando oferece escolhas e você omite o arg. ## `/tools` `/tools` responde a uma pergunta de runtime, não a uma pergunta de configuração: **o que este agente pode usar agora nesta conversa**. -- O `/tools` padrão é compacto e otimizado para leitura rápida. +- O padrão de `/tools` é compacto e otimizado para leitura rápida. - `/tools verbose` adiciona descrições curtas. -- Superfícies de comando nativo com suporte a argumentos expõem a mesma troca de modo `compact|verbose`. +- Superfícies com comandos nativos que oferecem suporte a argumentos expõem a mesma troca de modo como `compact|verbose`. - Os resultados têm escopo de sessão, então mudar agente, canal, thread, autorização do remetente ou modelo pode alterar a saída. - `/tools` inclui ferramentas realmente acessíveis em runtime, incluindo ferramentas do núcleo, ferramentas de - Plugin conectadas e ferramentas controladas pelo canal. + plugins conectados e ferramentas pertencentes ao canal. -Para editar perfis e substituições, use o painel Tools da UI de controle ou superfícies de configuração/catálogo em vez +Para editar perfis e substituições, use o painel Tools da UI de Controle ou as superfícies de config/catálogo em vez de tratar `/tools` como um catálogo estático. ## Superfícies de uso (o que aparece onde) -- **Uso/quota do provedor** (exemplo: “Claude 80% restante”) aparece em `/status` para o provedor do modelo atual quando o rastreamento de uso está habilitado. O OpenClaw normaliza janelas de provedor para `% restante`; para MiniMax, campos de porcentagem somente-restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag do modelo. -- **Linhas de token/cache** em `/status` podem usar como fallback a entrada de uso mais recente da transcrição quando o snapshot ao vivo da sessão é escasso. Valores ao vivo existentes diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou são menores. +- **Uso/cota do provedor** (exemplo: “Claude 80% restante”) aparece em `/status` para o provedor do modelo atual quando o rastreamento de uso está ativado. O OpenClaw normaliza janelas de provedor para `% restante`; no MiniMax, campos de percentual apenas-restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag do modelo. +- **Linhas de tokens/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o snapshot da sessão ao vivo é escasso. Valores ativos existentes diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado ao prompt quando os totais armazenados estiverem ausentes ou forem menores. - **Tokens/custo por resposta** é controlado por `/usage off|tokens|full` (anexado às respostas normais). -- `/model status` trata de **modelos/autenticação/endpoints**, não de uso. +- `/model status` trata de **modelos/auth/endpoints**, não de uso. ## Seleção de modelo (`/model`) @@ -251,16 +252,16 @@ Exemplos: /model status ``` -Observações: +Notas: - `/model` e `/model list` mostram um seletor compacto numerado (família do modelo + provedores disponíveis). -- No Discord, `/model` e `/models` abrem um seletor interativo com dropdowns de provedor e modelo mais uma etapa de envio. +- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo mais uma etapa de envio. - `/model <#>` seleciona a partir desse seletor (e prefere o provedor atual quando possível). -- `/model status` mostra a visualização detalhada, incluindo o endpoint do provedor configurado (`baseUrl`) e o modo de API (`api`) quando disponíveis. +- `/model status` mostra a visualização detalhada, incluindo o endpoint configurado do provedor (`baseUrl`) e o modo de API (`api`) quando disponíveis. -## Substituições de debug +## Substituições de depuração -`/debug` permite definir substituições de configuração **somente de runtime** (memória, não disco). Somente owner. Desabilitado por padrão; habilite com `commands.debug: true`. +`/debug` permite definir substituições de configuração **somente de runtime** (memória, não disco). Somente proprietário. Desativado por padrão; ative com `commands.debug: true`. Exemplos: @@ -272,14 +273,14 @@ Exemplos: /debug reset ``` -Observações: +Notas: -- As substituições se aplicam imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`. +- As substituições são aplicadas imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`. - Use `/debug reset` para limpar todas as substituições e voltar à configuração em disco. -## Saída de trace de Plugin +## Saída de rastreamento de plugin -`/trace` permite alternar **linhas de trace/debug de Plugin com escopo de sessão** sem ativar o modo verbose completo. +`/trace` permite alternar **linhas de rastreamento/depuração de plugin com escopo de sessão** sem ativar o modo detalhado completo. Exemplos: @@ -289,18 +290,18 @@ Exemplos: /trace off ``` -Observações: +Notas: -- `/trace` sem argumento mostra o estado atual de trace da sessão. -- `/trace on` habilita linhas de trace de Plugin para a sessão atual. -- `/trace off` desabilita essas linhas novamente. -- Linhas de trace de Plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente. +- `/trace` sem argumento mostra o estado atual de rastreamento da sessão. +- `/trace on` ativa linhas de rastreamento de plugin para a sessão atual. +- `/trace off` as desativa novamente. +- Linhas de rastreamento de plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente. - `/trace` não substitui `/debug`; `/debug` continua gerenciando substituições de configuração somente de runtime. -- `/trace` não substitui `/verbose`; a saída normal detalhada de ferramenta/status ainda pertence a `/verbose`. +- `/trace` não substitui `/verbose`; a saída normal detalhada de ferramentas/status continua pertencendo a `/verbose`. ## Atualizações de configuração -`/config` grava na sua configuração em disco (`openclaw.json`). Somente owner. Desabilitado por padrão; habilite com `commands.config: true`. +`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desativado por padrão; ative com `commands.config: true`. Exemplos: @@ -312,14 +313,14 @@ Exemplos: /config unset messages.responsePrefix ``` -Observações: +Notas: - A configuração é validada antes da gravação; alterações inválidas são rejeitadas. -- Atualizações de `/config` persistem após reinicializações. +- As atualizações de `/config` persistem após reinicializações. ## Atualizações de MCP -`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente owner. Desabilitado por padrão; habilite com `commands.mcp: true`. +`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desativado por padrão; ative com `commands.mcp: true`. Exemplos: @@ -330,14 +331,14 @@ Exemplos: /mcp unset context7 ``` -Observações: +Notas: -- `/mcp` armazena a configuração na configuração do OpenClaw, não em configurações de projeto controladas pelo Pi. +- `/mcp` armazena configuração na config do OpenClaw, não em configurações de projeto de propriedade do Pi. - Adaptadores de runtime decidem quais transportes são realmente executáveis. -## Atualizações de Plugin +## Atualizações de plugins -`/plugins` permite que operadores inspecionem Plugins descobertos e alternem a habilitação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desabilitado por padrão; habilite com `commands.plugins: true`. +`/plugins` permite que operadores inspecionem plugins descobertos e alternem a ativação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desativado por padrão; ative com `commands.plugins: true`. Exemplos: @@ -349,36 +350,36 @@ Exemplos: /plugins disable context7 ``` -Observações: +Notas: -- `/plugins list` e `/plugins show` usam descoberta real de Plugin no workspace atual mais a configuração em disco. -- `/plugins enable|disable` atualiza apenas a configuração do Plugin; não instala nem desinstala Plugins. -- Após alterações de habilitar/desabilitar, reinicie o Gateway para aplicá-las. +- `/plugins list` e `/plugins show` usam descoberta real de plugins com base no workspace atual mais a configuração em disco. +- `/plugins enable|disable` atualiza apenas a configuração do plugin; não instala nem desinstala plugins. +- Após alterações de ativação/desativação, reinicie o gateway para aplicá-las. -## Observações de superfície +## Notas de superfície - **Comandos de texto** são executados na sessão normal de chat (DMs compartilham `main`, grupos têm sua própria sessão). - **Comandos nativos** usam sessões isoladas: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (prefixo configurável via `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (aponta para a sessão do chat via `CommandTargetSessionKey`) -- **`/stop`** aponta para a sessão de chat ativa para poder abortar a execução atual. -- **Slack:** `channels.slack.slashCommand` ainda é compatível para um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um comando slash do Slack por comando embutido (os mesmos nomes de `/help`). Menus de argumento de comando para o Slack são entregues como botões efêmeros do Block Kit. + - Telegram: `telegram:slash:` (direciona para a sessão do chat via `CommandTargetSessionKey`) +- **`/stop`** mira a sessão de chat ativa para que possa interromper a execução atual. +- **Slack:** `channels.slack.slashCommand` ainda é compatível para um único comando no estilo `/openclaw`. Se você ativar `commands.native`, deverá criar um slash command do Slack por comando embutido (com os mesmos nomes de `/help`). Menus de argumentos de comando para o Slack são entregues como botões efêmeros do Block Kit. - Exceção nativa do Slack: registre `/agentstatus` (não `/status`) porque o Slack reserva `/status`. O `/status` em texto ainda funciona em mensagens do Slack. -## Perguntas laterais BTW +## Perguntas paralelas BTW -`/btw` é uma **pergunta lateral** rápida sobre a sessão atual. +`/btw` é uma **pergunta paralela** rápida sobre a sessão atual. Diferentemente do chat normal: - ele usa a sessão atual como contexto de fundo, -- ele é executado como uma chamada avulsa separada **sem ferramentas**, +- ele é executado como uma chamada única separada **sem ferramentas**, - ele não altera o contexto futuro da sessão, - ele não é gravado no histórico da transcrição, -- ele é entregue como um resultado lateral ao vivo em vez de uma mensagem normal do assistente. +- ele é entregue como um resultado paralelo ao vivo em vez de uma mensagem normal do assistente. -Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a +Isso faz de `/btw` algo útil quando você quer um esclarecimento temporário enquanto a tarefa principal continua. Exemplo: @@ -387,5 +388,5 @@ Exemplo: /btw o que estamos fazendo agora? ``` -Consulte [BTW Side Questions](/pt-BR/tools/btw) para o comportamento completo e os detalhes -da UX do cliente. +Veja [BTW Side Questions](/pt-BR/tools/btw) para o comportamento completo e os +detalhes de UX do cliente.