--- read_when: - Trabalhando em recursos do Telegram ou Webhooks summary: Status, capacidades e configuração do suporte ao bot do Telegram title: Telegram x-i18n: generated_at: "2026-05-12T12:48:56Z" model: gpt-5.5 provider: openai source_hash: 185ac6051d3da2037b2727a6afca98bef946bc62c3f2b22cc9afe9831669297b source_path: channels/telegram.md workflow: 16 --- Pronto para produção em DMs de bot e grupos via grammY. Long polling é o modo padrão; o modo Webhook é opcional. A política padrão de DM para Telegram é emparelhamento. Diagnósticos entre canais e playbooks de reparo. Padrões e exemplos completos de configuração de canal. ## Configuração rápida Abra o Telegram e converse com **@BotFather** (confirme que o identificador é exatamente `@BotFather`). Execute `/newbot`, siga as instruções e salve o token. ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Fallback por env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão). O Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/env e então inicie o gateway. ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` Códigos de emparelhamento expiram após 1 hora. Adicione o bot ao seu grupo e então obtenha os dois IDs de que o acesso ao grupo precisa: - seu ID de usuário do Telegram, usado em `allowFrom` / `groupAllowFrom` - o ID do chat de grupo do Telegram, usado como chave em `channels.telegram.groups` Para a configuração inicial, obtenha o ID do chat de grupo em `openclaw logs --follow`, por um bot de ID encaminhado ou pelo `getUpdates` da Bot API. Depois que o grupo for permitido, `/whoami@` pode confirmar os IDs de usuário e grupo. IDs negativos de supergrupo do Telegram que começam com `-100` são IDs de chat de grupo. Coloque-os em `channels.telegram.groups`, não em `groupAllowFrom`. A ordem de resolução de token é ciente da conta. Na prática, valores de configuração prevalecem sobre o fallback por env, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão. ## Configurações no lado do Telegram 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 uma destas opções: - desative o modo de privacidade via `/setprivacy`, ou - 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 mudança. O status de administrador é controlado nas configurações do grupo do Telegram. Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento de grupo sempre ativo. - `/setjoingroups` para permitir/negar adições a grupos - `/setprivacy` para comportamento de visibilidade em grupo ## Controle de acesso e ativação `channels.telegram.dmPolicy` controla o acesso por mensagem direta: - `pairing` (padrão) - `allowlist` (exige pelo menos um ID de remetente em `allowFrom`) - `open` (exige que `allowFrom` inclua `"*"`) - `disabled` `dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use isso somente para bots intencionalmente públicos com ferramentas fortemente restritas; bots de proprietário único devem usar `allowlist` com IDs numéricos de usuário. `channels.telegram.allowFrom` aceita IDs numéricos de usuário do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados. Em configurações de múltiplas contas, um `channels.telegram.allowFrom` restritivo de nível superior é tratado como uma fronteira de segurança: entradas `allowFrom: ["*"]` em nível de conta não tornam essa conta pública, a menos que a allowlist efetiva da conta ainda contenha um curinga explícito após a mesclagem. `dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração. A configuração solicita apenas IDs numéricos de usuário. Se você fez upgrade e sua configuração contém entradas `@username` na allowlist, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram). Se você dependia anteriormente de arquivos de allowlist do armazenamento de emparelhamento, `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). Para bots de proprietário único, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de emparelhamento anteriores). Confusão comum: aprovação de emparelhamento por DM não significa "este remetente está autorizado em todos os lugares". O emparelhamento concede acesso por DM. Se ainda não existir proprietário de comandos, o primeiro emparelhamento aprovado também define `commands.ownerAllowFrom` para que comandos somente do proprietário e aprovações de exec tenham uma conta de operador explícita. A autorização de remetente em grupo ainda vem de allowlists explícitas na configuração. Se você quer "eu sou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos somente do proprietário, garanta que `commands.ownerAllowFrom` contenha `telegram:`. ### Encontrando seu ID de usuário do Telegram Mais seguro (sem bot de terceiros): 1. Envie uma DM ao seu bot. 2. Execute `openclaw logs --follow`. 3. Leia `from.id`. Método oficial da Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` Método de terceiros (menos privado): `@userinfobot` ou `@getidsbot`. Dois controles se aplicam juntos: 1. **Quais grupos são permitidos** (`channels.telegram.groups`) - sem configuração de `groups`: - com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo - com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`) - `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`) 2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (padrão) - `disabled` `groupAllowFrom` é usado para filtragem de remetente em grupo. Se não for definido, o Telegram recorre a `allowFrom`. Entradas `groupAllowFrom` devem ser IDs numéricos de usuário do Telegram (prefixos `telegram:` / `tg:` são normalizados). Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs negativos de chat pertencem a `channels.telegram.groups`. Entradas não numéricas são ignoradas para autorização de remetente. Fronteira de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações de armazenamento de emparelhamento de DM. O emparelhamento permanece somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico. Se `groupAllowFrom` não estiver definido, o Telegram recorre a `allowFrom` da configuração, não ao armazenamento de emparelhamento. Padrão prático para bots de proprietário único: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos de destino em `channels.telegram.groups`. Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa como padrão o modo fail-closed `groupPolicy="allowlist"`, a menos que `channels.defaults.groupPolicy` seja definido explicitamente. Configuração de grupo somente para proprietário: ```json5 { channels: { telegram: { enabled: true, dmPolicy: "pairing", allowFrom: [""], groupPolicy: "allowlist", groups: { "": { requireMention: true, }, }, }, }, } ``` Teste no grupo com `@ ping`. Mensagens comuns do grupo não acionam o bot enquanto `requireMention: true`. Exemplo: permitir qualquer membro em um grupo específico: ```json5 { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` Exemplo: permitir somente usuários específicos dentro de um grupo específico: ```json5 { channels: { telegram: { groups: { "-1001234567890": { requireMention: true, allowFrom: ["8734062810", "745123456"], }, }, }, }, } ``` Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram. - Coloque IDs negativos de chat 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: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot. Respostas em grupo exigem menção por padrão. A menção pode vir de: - menção nativa `@botusername`, ou - padrões de menção em: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` Alternâncias de comando em nível de sessão: - `/activation always` - `/activation mention` Elas atualizam apenas o estado da sessão. Use a configuração para persistência. Exemplo de configuração persistente: ```json5 { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` Obtendo o ID do chat de grupo: - encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot` - ou leia `chat.id` em `openclaw logs --follow` - ou inspecione o `getUpdates` da Bot API - depois que o grupo for permitido, execute `/whoami@` se comandos nativos estiverem habilitados ## Comportamento em runtime - O Telegram é controlado pelo processo do Gateway. - O roteamento é determinístico: mensagens de entrada do Telegram respondem de volta ao Telegram (o modelo não escolhe canais). - Mensagens de entrada são normalizadas no envelope de canal compartilhado com metadados de resposta, placeholders de mídia e contexto persistido de cadeia de respostas para respostas do Telegram que o Gateway observou. - Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum acrescentam `:topic:` para manter tópicos isolados. - Mensagens de DM podem carregar `message_thread_id`; o OpenClaw preserva o ID da thread para respostas, mas mantém DMs na sessão plana por padrão. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` ou uma configuração de tópico correspondente quando você quiser intencionalmente isolamento de sessão por tópico em DM. - Long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`. - Long polling é protegido dentro de cada processo do Gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, é provável que outro Gateway do OpenClaw, script ou poller externo esteja usando o mesmo token. - Reinícios por watchdog de long polling são acionados após 120 segundos sem liveness de `getUpdates` concluído por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se seu deployment ainda vir reinícios falsos por polling stall durante trabalho de longa duração. O valor é em milissegundos e é permitido de `30000` a `600000`; overrides por conta são compatíveis. - A Telegram Bot API não tem 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évia + `editMessageText` - grupos/tópicos: mensagem de prévia + `editMessageText` Requisito: - `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`) - `progress` mantém um rascunho de status editável para o progresso das ferramentas, limpa-o ao concluir e envia a resposta final como uma mensagem normal - `streaming.preview.toolProgress` controla se as atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando o streaming de prévia está ativo) - `streaming.preview.commandText` controla os detalhes de comando/execução dentro dessas linhas de progresso de ferramenta: `raw` (padrão, preserva o comportamento lançado) ou `status` (somente o rótulo da ferramenta) - valores legados de `channels.telegram.streamMode` e booleanos de `streaming` são detectados; execute `openclaw doctor --fix` para migrá-los para `channels.telegram.streaming.mode` Atualizações de prévia de progresso de ferramenta são as linhas curtas de status exibidas enquanto as ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. O Telegram mantém isso ativado por padrão para corresponder ao comportamento lançado do OpenClaw a partir de `v2026.4.22`. Para manter a prévia editada do texto da resposta, mas ocultar as linhas de progresso de ferramenta, defina: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` Para manter o progresso de ferramenta visível, mas ocultar o texto de comando/execução, defina: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` Use o modo `progress` quando quiser progresso de ferramenta visível sem editar a resposta final nessa mesma mensagem. Coloque a política de texto de comando em `streaming.progress`: ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` Use `streaming.mode: "off"` somente quando quiser entrega apenas final: edições de prévia do Telegram são desativadas e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens de status independentes. Solicitações de aprovação, cargas de mídia e erros ainda passam pela entrega final normal. Use `streaming.preview.toolProgress: false` quando quiser apenas manter as edições de prévia da resposta enquanto oculta as linhas de status de progresso de ferramenta. Respostas com citação selecionada no Telegram são a exceção. Quando `replyToMode` é `"first"`, `"all"` ou `"batched"` e a mensagem de entrada inclui texto de citação selecionada, o OpenClaw envia a resposta final pelo caminho nativo de resposta com citação do Telegram em vez de editar a prévia da resposta, então `streaming.preview.toolProgress` não consegue mostrar as linhas curtas de status para essa interação. Respostas à mensagem atual sem texto de citação selecionada ainda mantêm o streaming de prévia. Defina `replyToMode: "off"` quando a visibilidade do progresso de ferramenta for mais importante que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer a troca. Para respostas somente de texto: - prévias curtas em DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz a edição final no mesmo lugar - finais de texto longos que se dividem em várias mensagens do Telegram reutilizam a prévia existente como o primeiro trecho final quando possível, depois enviam somente os trechos restantes - finais em modo de progresso limpam o rascunho de status e usam a entrega final normal em vez de editar o rascunho para virar a resposta - se a edição final falhar antes de o texto concluído ser confirmado, o OpenClaw usa a entrega final normal e limpa a prévia obsoleta Para respostas complexas (por exemplo cargas de mídia), o OpenClaw recorre à entrega final normal e depois limpa a mensagem de prévia. O streaming de prévia é separado do streaming em bloco. Quando o streaming em bloco é ativado explicitamente para o Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplo. Stream de raciocínio somente do Telegram: - `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração - a prévia de raciocínio é excluída após a entrega final; use `/reasoning on` quando o raciocínio deve permanecer visível - a resposta final é enviada sem texto de raciocínio O texto de saída usa `parse_mode: "HTML"` do Telegram. - Texto semelhante a Markdown é renderizado como HTML seguro para Telegram. - Tags HTML compatíveis com o Telegram são preservadas; HTML não compatível é escapado. - Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples. Prévias de links são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`. O registro do menu de comandos do Telegram é tratado na inicialização com `setMyCommands`. Padrões de comandos nativos: - `commands.native: "auto"` ativa comandos nativos para o Telegram Adicione entradas personalizadas ao menu de comandos: ```json5 { channels: { telegram: { customCommands: [ { command: "backup", description: "Git backup" }, { command: "generate", description: "Create an image" }, ], }, }, } ``` Regras: - nomes são normalizados (remove `/` inicial, converte para minúsculas) - padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32` - comandos personalizados não podem substituir comandos nativos - conflitos/duplicatas são ignorados e registrados em log 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 apareçam no menu do Telegram Se comandos nativos estiverem desativados, os integrados serão removidos. Comandos personalizados/de Plugin ainda poderão ser registrados se configurados. Falhas comuns de configuração: - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos de Plugin/Skills/personalizados ou desative `channels.telegram.commands.native`. - falha de `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos curl diretos da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido para o endpoint completo `/bot`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot` final acidental. - `getMe returned 401` significa que o Telegram rejeitou o token de bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como falha de limpeza de Webhook. - `setMyCommands failed` com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado. ### Comandos de pareamento de dispositivo (Plugin `device-pair`) Quando o Plugin `device-pair` está instalado: 1. `/pair` gera código de configuração 2. cole o código no app iOS 3. `/pair pending` lista solicitações pendentes (incluindo função/escopos) 4. aprove a solicitação: - `/pair approve ` para aprovação explícita - `/pair approve` quando há somente 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. A transferência de bootstrap integrada mantém o token do nó primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. Verificações de escopo de bootstrap têm prefixo de função, então essa allowlist de operador satisfaz apenas solicitações de operador; funções que não são de operador ainda precisam de escopos sob seu próprio prefixo de função. Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar. Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios). Configure o escopo do teclado inline: ```json5 { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` Substituição por conta: ```json5 { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` Escopos: - `off` - `dm` - `group` - `all` - `allowlist` (padrão) O legado `capabilities: ["inlineButtons"]` é mapeado para `inlineButtons: "all"`. Exemplo de ação de mensagem: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "Choose an option:", buttons: [ [ { text: "Yes", callback_data: "yes" }, { text: "No", callback_data: "no" }, ], [{ text: "Cancel", callback_data: "cancel" }], ], } ``` Cliques de callback são passados ao agente como texto: `callback_data: ` Ações de ferramenta do Telegram incluem: - `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`) Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). Controles de gating: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (padrão: desativado) Observação: `edit` e `topic-create` atualmente são ativados por padrão e não têm seletores `channels.telegram.actions.*` separados. Envios em runtime usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), então caminhos de ação não fazem nova resolução ad hoc de SecretRef por envio. Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions) O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada: - `[[reply_to_current]]` responde à mensagem acionadora - `[[reply_to:]]` responde a um ID de mensagem específico do Telegram `channels.telegram.replyToMode` controla o tratamento: - `off` (padrão) - `first` - `all` Quando o encadeamento de resposta está ativado e o texto ou legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho nativo de citação do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas a partir do início e recorrem a uma resposta simples se o Telegram rejeitar a citação. Observação: `off` desativa o encadeamento de resposta implícito. Tags explícitas `[[reply_to_*]]` ainda são respeitadas. Supergrupos de fórum: - chaves de sessão de tópico acrescentam `:topic:` - respostas e indicador de digitação apontam para a thread do tópico - caminho de configuração do tópico: `channels.telegram.groups..topics.` 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 configurações do grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` é somente 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: ```json5 { channels: { telegram: { groups: { "-1001234567890": { topics: { "1": { agentId: "main" }, // General topic → main agent "3": { agentId: "zu" }, // Dev topic → zu agent "5": { agentId: "coder" } // Code review → coder agent } } } } } } ``` Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3` **Vinculação persistente de tópico ACP**: Tópicos de fórum podem fixar sessões do harness ACP por meio de vinculações ACP tipadas de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e um ID qualificado por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents). **Geração de ACP vinculada à conversa a partir do chat**: `/acp spawn --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de geração no tópico. Requer que `channels.telegram.threadBindings.spawnSessions` permaneça habilitado (padrão: `true`). O contexto do modelo expõe `MessageThreadId` e `IsForum`. Chats de DM com `message_thread_id` mantêm o roteamento de DM e metadados de resposta em sessões planas por padrão; eles só usam chaves de sessão cientes de conversa quando configurados com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` de nível superior para o padrão da conta, ou `direct..threadReplies` para uma DM. ### Mensagens de áudio O Telegram distingue notas de voz de arquivos de áudio. - padrão: comportamento de arquivo de áudio - tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz - transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina, não confiável, no contexto do agente; a detecção de menção ainda usa a transcrição bruta, então mensagens de voz controladas por menção continuam funcionando. Exemplo de ação de mensagem: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### Mensagens de vídeo O Telegram distingue arquivos de vídeo de notas de vídeo. Exemplo de ação de mensagem: ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` Notas de vídeo não aceitam legendas; o texto de mensagem fornecido é enviado separadamente. ### Stickers Tratamento de stickers recebidos: - WEBP estático: baixado e processado (placeholder ``) - TGS animado: ignorado - WEBM de vídeo: ignorado Campos de contexto de sticker: - `Sticker.emoji` - `Sticker.setName` - `Sticker.fileId` - `Sticker.fileUniqueId` - `Sticker.cachedDescription` Arquivo de cache de stickers: - `~/.openclaw/telegram/sticker-cache.json` Stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas de visão repetidas. Habilitar ações de sticker: ```json5 { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` Enviar ação de sticker: ```json5 { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` Pesquisar stickers em cache: ```json5 { action: "sticker-search", channel: "telegram", query: "cat waving", limit: 5, } ``` Reações do Telegram chegam como atualizações `message_reaction` (separadas dos payloads de mensagem). Quando habilitado, o OpenClaw enfileira eventos de sistema como: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` Configuração: - `channels.telegram.reactionNotifications`: `off | own | all` (padrão: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (padrão: `minimal`) Observações: - `own` significa reações de usuários apenas a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). - Eventos de reação ainda respeitam controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados. - O Telegram não fornece IDs de conversa em atualizações de reação. - grupos que não são fórum roteiam para a sessão de chat do grupo - grupos de fórum roteiam para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem `allowed_updates` para polling/Webhook inclui `message_reaction` automaticamente. `ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida. Ordem de resolução: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - fallback do emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") Observações: - O Telegram espera emoji unicode (por exemplo, "👀"). - Use `""` para desabilitar a reação para um canal ou conta. Gravações de configuração de canal são habilitadas por padrão (`configWrites !== false`). 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 de comando) Desabilitar: ```json5 { channels: { telegram: { configWrites: false, }, }, } ``` O padrão é polling longo. Para o modo Webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionais `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`). No modo de polling longo, o OpenClaw persiste seu marcador de reinício apenas depois que uma atualização é despachada com sucesso. Se um handler falhar, essa atualização permanece retentável no mesmo processo e não é gravada como concluída para deduplicação de reinício. O listener local se vincula a `127.0.0.1:8787`. Para ingresso público, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente. O modo Webhook valida guardas de solicitação, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram. O OpenClaw então processa a atualização de forma assíncrona pelas mesmas filas de bot por chat/por tópico usadas pelo polling longo, então turnos lentos de agente não seguram o ACK de entrega do Telegram. - 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.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são armazenados em buffer antes que o OpenClaw os despache como uma mensagem recebida. Aumente se partes do álbum chegarem atrasadas; reduza para diminuir a latência de resposta do álbum. - `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não definido, o padrão do grammY se aplica). Clientes de bot limitam valores configurados abaixo do guarda de solicitação de texto/digitação enviada de 60 segundos, para que o grammY não aborte a entrega de resposta visível antes que o guarda de transporte e o fallback do OpenClaw possam executar. O polling longo ainda usa um guarda de solicitação `getUpdates` de 45 segundos, para que polls ociosos não sejam abandonados indefinidamente. - `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinícios por travamento de polling falso-positivos. - o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita. - contexto suplementar de resposta/citação/encaminhamento é normalizado em uma janela de contexto de conversa selecionada quando o Gateway observou as mensagens pai; o cache de mensagens observadas é persistido ao lado do armazenamento de sessão. O Telegram inclui apenas um `reply_to_message` superficial nas atualizações, então cadeias mais antigas que o cache ficam limitadas ao payload de atualização atual do Telegram. - allowlists do Telegram principalmente controlam quem pode acionar o agente, não uma fronteira completa 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 a helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API enviada. A entrega da resposta final recebida também usa uma nova tentativa de envio seguro limitada para falhas de pré-conexão do Telegram, mas não tenta novamente envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis. Destinos de envio da CLI e da ferramenta de mensagem podem ser ID numérico de chat, nome de usuário ou um destino de tópico de fórum: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic" ``` Polls do Telegram usam `openclaw message poll` e aceitam tópicos de fórum: ```bash openclaw message poll --channel telegram --target 123456789 \ --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ --poll-duration-seconds 300 --poll-public ``` Flags de poll exclusivas do Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - `--thread-id` para tópicos de fórum (ou use um destino `:topic:`) O envio do Telegram também aceita: - `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite - `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot pode fixar nesse chat - `--force-document` para enviar imagens, GIFs e vídeos de saída como documentos em vez de uploads compactados de foto, mídia animada ou vídeo Controle de ações: - `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo polls - `channels.telegram.actions.poll=false` desabilita a criação de polls do Telegram, mantendo envios regulares habilitados O Telegram aceita aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram. Caminho de configuração: - `channels.telegram.execApprovals.enabled` (auto-habilita quando pelo menos um aprovador pode ser resolvido) - `channels.telegram.execApprovals.approvers` (recorre a IDs numéricos de proprietários de `commands.ownerAllowFrom`) - `channels.telegram.execApprovals.target`: `dm` (padrão) | `channel` | `both` - `agentFilter`, `sessionFilter` `channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e onde ele envia respostas normais. Eles não tornam alguém um aprovador de exec. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração com um proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`. A entrega no canal mostra o texto do comando no chat; habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega em um tópico de fórum, o OpenClaw preserva o tópico para o prompt de aprovação e o acompanhamento. Aprovações de exec expiram após 30 minutos por padrão. Botões de aprovação inline também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por meio de aprovações de plugin; outros são resolvidos primeiro por meio de aprovações de exec. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals). ## Controles de resposta de erro Quando o agente encontra um erro de entrega ou de provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: | Chave | Valores | Padrão | Descrição | | ----------------------------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável para o chat. `silent` suprime totalmente respostas de erro. | | `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. | Há suporte para substituições por conta, por grupo e por tópico (mesma herança de outras chaves de configuração do Telegram). ```json5 { channels: { telegram: { errorPolicy: "reply", errorCooldownMs: 120000, groups: { "-1001234567890": { errorPolicy: "silent", // suppress errors in this group }, }, }, }, } ``` ## Solução de problemas - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total. - BotFather: `/setprivacy` -> Desativar - depois remova e 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 grupos; o curinga `"*"` não pode ter a associação sondada. - 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 - revise os logs: `openclaw logs --follow` para motivos de ignorar mensagens - autorize a identidade do remetente (pareamento e/ou `allowFrom` numérico) - a autorização de comandos ainda se aplica mesmo quando a política do grupo é `open` - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de plugin/skill/personalizados ou desative menus nativos - chamadas de inicialização `deleteMyCommands` / `setMyCommands` e chamadas de digitação `sendChatAction` são limitadas e tentam novamente uma vez por meio do fallback de transporte do Telegram em caso de tempo limite da solicitação. Erros persistentes de rede/fetch geralmente indicam problemas de acessibilidade DNS/HTTPS para `api.telegram.org` - `getMe returned 401` é uma falha de autenticação do Telegram para o token de bot configurado. - Copie novamente ou regenere o token de bot no BotFather, depois atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão. - `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-lo como "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores. - Node 22+ + fetch/proxy personalizado podem disparar comportamento de aborto imediato se os tipos de AbortSignal não corresponderem. - Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; saída IPv6 com defeito pode causar falhas intermitentes da API do Telegram. - Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora repete essas tentativas como erros de rede recuperáveis. - Durante a inicialização do polling, o OpenClaw reutiliza a sonda `getMe` bem-sucedida da inicialização para o grammY, de modo que o executor não precise de um segundo `getMe` antes do primeiro `getUpdates`. - Se `deleteWebhook` falhar com um erro de rede transitório durante a inicialização do polling, o OpenClaw continua para long polling em vez de fazer outra chamada de plano de controle antes do polling. Um webhook ainda ativo aparece como um conflito de `getUpdates`; então o OpenClaw reconstrói o transporte do Telegram e tenta novamente a limpeza do webhook. - Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se há um `channels.telegram.timeoutSeconds` baixo; clientes de bot limitam valores configurados abaixo das proteções de solicitação de saída e de `getUpdates`, mas versões mais antigas podiam abortar todo polling ou resposta quando isso era definido abaixo dessas proteções. - Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness concluída de long-poll por padrão. - `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após a tolerância de inicialização, quando uma conta de webhook em execução não concluiu `setWebhook` após a tolerância de inicialização ou quando a última atividade bem-sucedida de transporte de polling está obsoleta. - Aumente `channels.telegram.pollingStallThresholdMs` apenas quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinicializações falsas por travamento de polling. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`. - O Telegram também respeita o env de proxy do processo para transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda podem ignorar `api.telegram.org`. - Se o proxy gerenciado do OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usará essa URL para transporte da Bot API. - Em hosts VPS com saída/TLS direta instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`: ```yaml channels: telegram: proxy: socks5://:@proxy-host:1080 ``` - Node 22+ usa `autoSelectFamily=true` por padrão (exceto WSL2). A ordem de resultados DNS do Telegram respeita `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, depois `channels.telegram.network.dnsResultOrder`, depois o padrão do processo, como `NODE_OPTIONS=--dns-result-order=ipv4first`; se nada se aplicar, Node 22+ recorre a `ipv4first`. - Se seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família: ```yaml channels: telegram: network: autoSelectFamily: false ``` - Respostas de intervalo de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas para downloads de mídia do Telegram por padrão. Se um fake-IP confiável ou proxy transparente reescrever `api.telegram.org` para algum outro endereço privado/interno/de uso especial durante downloads de mídia, você pode optar pelo bypass somente do Telegram: ```yaml channels: telegram: network: dangerouslyAllowPrivateNetwork: true ``` - A mesma opção 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 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-a apenas para ambientes de proxy confiáveis controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge, quando eles sintetizarem respostas privadas ou de uso especial fora do intervalo de benchmark RFC 2544. Deixe-a desativada para acesso normal ao Telegram pela internet pública. - Substituições de ambiente (temporárias): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - Valide respostas DNS: ```bash dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` Mais ajuda: [Solução de problemas de canais](/pt-BR/channels/troubleshooting). ## Referência de configuração Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway/config-channels#telegram). - inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados) - controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`) - aprovações de execução: `execApprovals`, `accounts.*.execApprovals` - comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands` - threads/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming` - formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - mídia/rede: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - raiz de API personalizada: `apiRoot` (somente raiz da Bot API; não inclua `/bot`) - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - ações/capacidades: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reações: `reactionNotifications`, `reactionLevel` - erros: `errorPolicy`, `errorCooldownMs` - gravações/histórico: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` Precedência de múltiplas contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw recorre ao primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`. ## Relacionado Pareie um usuário do Telegram ao gateway. Comportamento de lista de permissões de grupos e tópicos. Roteie mensagens de entrada para agentes. Modelo de ameaça e fortalecimento. Mapeie grupos e tópicos para agentes. Diagnósticos entre canais.