Telegram

Por padrão, os bots do Telegram usam o Modo de Privacidade, que limita quais mensagens de grupo eles recebem.

Para ver todas as mensagens do grupo, faça uma destas opções:

• desative o modo de privacidade usando /setprivacy; ou
• torne o bot administrador do grupo.

Após alterar o modo de privacidade, remova e adicione novamente o bot em cada grupo para que o Telegram aplique a alteração.

O status de administrador é controlado nas configurações do grupo do Telegram. Bots administradores recebem todas as mensagens do grupo, o que é útil para um comportamento sempre ativo em grupos.

• /setjoingroups — permitir/negar adições a grupos
• /setprivacy — comportamento de visibilidade em grupos

As mesmas configurações estão disponíveis no aplicativo web do BotFather, caso você prefira uma interface em vez de comandos de chat.

O OpenClaw transmite respostas parciais em tempo real em conversas diretas, grupos e tópicos: envia uma mensagem de prévia e depois chama editMessageText repetidamente, finalizando-a no mesmo lugar.

• channels.telegram.streaming aceita off | partial | block | progress (padrão: partial)
• prévias iniciais curtas da resposta passam por debounce e são materializadas após um atraso limitado se a execução ainda estiver ativa
• progress mantém um único rascunho de status editável para o progresso das ferramentas, exibe o rótulo de status estável quando há atividade de resposta antes do progresso das ferramentas, limpa-o na conclusão e envia a resposta final como uma mensagem normal
• streaming.preview.toolProgress controla se as atualizações de ferramentas/progresso reutilizam a mesma mensagem de prévia editada (padrão: true quando a transmissão da prévia está ativa)
• streaming.preview.commandText controla os detalhes de comandos/execução nessas linhas: raw (padrão) ou status (somente o rótulo da ferramenta)
• streaming.progress.commentary (padrão: false) habilita texto de comentário/preâmbulo do assistente no rascunho temporário de progresso
• channels.telegram.streamMode legado, valores booleanos de streaming e chaves descontinuadas da prévia nativa de rascunho são detectados; execute openclaw doctor --fix para migrá-los

As linhas de progresso das ferramentas são as atualizações curtas de status exibidas enquanto as ferramentas são executadas (execução de comandos, leitura de arquivos, atualizações de planejamento, resumos de patches, preâmbulo/comentários do Codex no modo de servidor de aplicativo). O Telegram as mantém ativadas por padrão (corresponde ao comportamento lançado a partir da v2026.4.22).

Mantenha as edições da prévia da resposta, mas oculte as linhas de progresso das ferramentas:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

Mantenha o progresso das ferramentas visível, mas oculte o texto de comandos/execução:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

O modo progress exibe o progresso das ferramentas sem editar a resposta final nessa mensagem. Defina a política de texto dos comandos em streaming.progress:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" desativa as edições da prévia e suprime mensagens genéricas de ferramentas/progresso, em vez de enviá-las como mensagens de status independentes; solicitações de aprovação, mídias e erros ainda seguem o envio final normal. streaming.preview.toolProgress: false mantém apenas as edições da prévia da resposta.

Para respostas contendo apenas texto: prévias curtas recebem a edição final no mesmo lugar; respostas finais longas, divididas em várias mensagens, reutilizam a prévia como o primeiro trecho e depois enviam somente o restante; respostas finais no modo de progresso limpam o rascunho de status e usam o envio final normal; se a edição final falhar antes da confirmação da conclusão, o OpenClaw recorre ao envio final normal e remove a prévia obsoleta. Para respostas complexas (cargas de mídia), o OpenClaw sempre recorre ao envio final normal e remove a prévia.

A transmissão da prévia e a transmissão em blocos são mutuamente exclusivas — quando a transmissão em blocos está explicitamente habilitada, o OpenClaw ignora a transmissão da prévia para evitar transmissão duplicada.

Raciocínio: /reasoning stream transmite o raciocínio para a prévia ao vivo durante a geração e depois exclui a prévia do raciocínio após o envio final (use /reasoning on para mantê-la visível). A resposta final é enviada sem o texto do raciocínio.

Por padrão, o texto de saída usa mensagens HTML padrão do Telegram, legíveis nos clientes atuais: negrito, itálico, links, código, spoilers e citações — não os blocos exclusivos de conteúdo avançado da API de Bots 10.1 (tabelas nativas, detalhes, mídia avançada e fórmulas).

Habilite as mensagens avançadas da API de Bots 10.1:

{channels: {telegram: {  richMessages: true,},},}

Quando habilitadas: o agente é informado de que mensagens avançadas estão disponíveis para esse bot/essa conta; o texto Markdown é renderizado por meio da IR de Markdown do OpenClaw como HTML avançado do Telegram; cargas explícitas de HTML avançado preservam as tags compatíveis com a API de Bots 10.1 (títulos, tabelas, detalhes, mídia avançada e fórmulas); as legendas de mídia continuam usando legendas HTML do Telegram (mensagens avançadas não substituem legendas, e elas têm limite de 1024 caracteres).

Isso impede que o texto do modelo use os símbolos de Markdown avançado do Telegram, evitando que valores monetários como $400-600K sejam interpretados como matemática. Textos avançados longos são divididos automaticamente de acordo com os limites do Telegram. Tabelas que excedem o limite de 20 colunas recorrem a um bloco de código.

Padrão: desativado, por compatibilidade com clientes — alguns clientes atuais para Desktop, Web, Android e de terceiros exibem mensagens avançadas aceitas como incompatíveis. Mantenha esse recurso desativado, a menos que todos os clientes usados com o bot consigam renderizá-las. /status mostra se as mensagens avançadas estão ativadas ou desativadas na sessão atual.

As prévias de links ficam ativadas por padrão. channels.telegram.linkPreview: false desativa a detecção automática de entidades em texto avançado.

O menu de comandos do Telegram é registrado na inicialização com setMyCommands. commands.native: "auto" habilita comandos nativos para o Telegram.

Adicione entradas personalizadas ao menu de comandos:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Backup do Git" },    { command: "generate", description: "Criar uma imagem" },  ],},},}

Regras: os nomes são normalizados (remoção da / inicial e conversão para minúsculas); padrão válido: a-z, 0-9, _, comprimento de 1-32; comandos personalizados não podem substituir comandos nativos; conflitos/duplicatas são ignorados e registrados.

Comandos personalizados são apenas entradas de menu — eles não implementam comportamentos automaticamente. Comandos de Plugin/skill ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram. Se os comandos nativos estiverem desativados, os comandos integrados serão removidos; comandos personalizados/de Plugin ainda poderão ser registrados se estiverem configurados.

Falhas comuns de configuração:

• setMyCommands failed com BOT_COMMANDS_TOO_MUCH após uma nova tentativa de redução significa que o menu ainda excede o limite; reduza os comandos de plugins/Skills/personalizados ou desative channels.telegram.commands.native.
• Falhas de deleteWebhook, deleteMyCommands ou setMyCommands com 404: Not Found, enquanto comandos curl diretos da API de Bots funcionam, normalmente significam que channels.telegram.apiRoot foi definido como o endpoint completo /bot<TOKEN>. apiRoot deve conter somente a raiz da API de Bots; openclaw doctor --fix remove um sufixo /bot<TOKEN> adicionado acidentalmente.
• getMe returned 401 significa que o Telegram rejeitou o token de bot configurado. Atualize botToken, tokenFile ou TELEGRAM_BOT_TOKEN (conta padrão) com o token atual do BotFather; o OpenClaw interrompe a execução antes do polling, portanto isso não é relatado como uma falha na limpeza do Webhook.
• setMyCommands failed com erros de rede/fetch normalmente significa que o DNS/HTTPS de saída para api.telegram.org está bloqueado.

Comandos de pareamento de dispositivos (Plugin device-pair)

Quando instalado:

1. /pair gera um código de configuração
2. cole o código no aplicativo para iOS
3. /pair pending lista as solicitações pendentes (incluindo função/escopos)
4. aprove: /pair approve <requestId>, /pair approve (única solicitação pendente) ou /pair approve latest

Se um dispositivo tentar novamente com dados de autenticação alterados (função, escopos ou chave pública), a solicitação pendente anterior será substituída por uma nova requestId; execute /pair pending novamente antes de aprovar.

Mais detalhes: Pareamento.

Configure o escopo do teclado inline:

{channels: {telegram: {  capabilities: {    inlineButtons: "allowlist",  },},},}

Substituição por conta:

{channels: {telegram: {  accounts: {    main: {      capabilities: {        inlineButtons: "allowlist",      },    },  },},},}

Escopos: off, dm, group, all, allowlist (padrão). O formato legado capabilities: ["inlineButtons"] corresponde a "all".

Exemplo de ação de mensagem:

{action: "send",channel: "telegram",to: "123456789",message: "Escolha uma opção:",buttons: [[  { text: "Sim", callback_data: "yes" },  { text: "Não", callback_data: "no" },],[{ text: "Cancelar", callback_data: "cancel" }],],}

Exemplo de botão de Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "Abra o aplicativo:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Iniciar", web_app: { url: "https://example.com/app" } }],  },],},}

Os botões web_app funcionam somente em conversas privadas entre um usuário e o bot.

Cliques de callback que não são tratados por um manipulador interativo de Plugin registrado são repassados ao agente como texto: callback_data: <value>.

Ações:

• sendMessage (to, content, mediaUrl opcional, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content ou caption, botões inline opcionais em presentation; edições somente de botões atualizam a marcação de resposta)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

Aliases ergonômicos: send, react, delete, edit, sticker, sticker-search, topic-create.

Controle de acesso: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (padrão: desativado). edit, createForumTopic e editForumTopic são ativados por padrão, sem alternância dedicada. Os envios em tempo de execução usam o snapshot ativo de configuração/segredos da inicialização/recarga, portanto os caminhos de ação não resolvem novamente os valores de SecretRef a cada envio.

Semântica da remoção de reações: /tools/reactions.

Tags explícitas de encadeamento de respostas na saída gerada:

• [[reply_to_current]] — responde à mensagem que acionou a execução
• [[reply_to:<id>]] — responde a um ID de mensagem específico

channels.telegram.replyToMode: off (padrão), first, all.

Quando o encadeamento de respostas está ativado e o texto/legenda original está disponível, o OpenClaw adiciona automaticamente um trecho de citação nativo. O Telegram limita o texto de citações nativas a 1024 unidades de código UTF-16; mensagens mais longas são citadas a partir do início e voltam para uma resposta simples se o Telegram rejeitar a citação.

off desativa apenas o encadeamento implícito de respostas; as tags explícitas [[reply_to_*]] ainda são respeitadas.

Supergrupos de fórum: as chaves de sessão de tópicos recebem o sufixo :topic:<threadId>; respostas e indicadores de digitação são direcionados à thread do tópico; o caminho de configuração do tópico é channels.telegram.groups.<chatId>.topics.<threadId>.

O tópico Geral (threadId=1) é um caso especial: os envios de mensagens omitem message_thread_id (o Telegram rejeita sendMessage(...thread_id=1) com "thread not found"), mas as ações de digitação ainda incluem message_thread_id (empiricamente necessário para que o indicador de digitação apareça).

As entradas de tópicos herdam as configurações do grupo, a menos que sejam substituídas (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId é exclusivo do tópico e não herda os padrões do grupo. topics."*" define padrões para todos os tópicos desse grupo; IDs exatos de tópicos ainda têm precedência sobre "*".

Roteamento de agente por tópico: cada tópico pode ser direcionado a um agente diferente por meio de agentId na configuração do tópico, recebendo seu próprio espaço de trabalho, memória e sessão:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Tópico Geral -> agente principal            "3": { agentId: "zu" },        // Tópico de desenvolvimento -> agente zu            "5": { agentId: "coder" }      // Revisão de código -> agente coder          }        }      }    }  }}

Cada tópico passa a ter sua própria chave de sessão, por exemplo, 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 tipadas de nível superior (bindings[] com type: "acp", 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.

Criação de ACP vinculada à thread pelo chat: /acp spawn <agent> --thread here|auto vincula o tópico atual a uma nova sessão ACP; mensagens subsequentes são encaminhadas diretamente para ela, e o OpenClaw fixa a confirmação da criação no tópico. Requer channels.telegram.threadBindings.spawnSessions (padrão: true).

O contexto do modelo expõe MessageThreadId e IsForum. Conversas por MD com message_thread_id mantêm os metadados de resposta, mas só usam chaves de sessão compatíveis com threads quando getMe do Telegram informa has_topics_enabled: true. As substituições descontinuadas dm.threadReplies e direct.*.threadReplies foram removidas; o modo com threads do BotFather é a única fonte da verdade. Execute openclaw doctor --fix para remover chaves de configuração obsoletas.

Mensagens de áudio

O Telegram diferencia mensagens de voz de arquivos de áudio. Padrão: comportamento de arquivo de áudio; use a tag [[audio_as_voice]] na resposta do agente para forçar o envio como mensagem de voz. As transcrições de mensagens de voz recebidas são apresentadas no contexto do agente como texto não confiável gerado por máquina, mas a detecção de menções ainda usa a transcrição bruta para que mensagens de voz sujeitas à exigência de menção continuem funcionando.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

Mensagens de vídeo

O Telegram diferencia arquivos de vídeo de mensagens de vídeo. Mensagens de vídeo não oferecem suporte a legendas; o texto fornecido na mensagem é enviado separadamente.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

Localizações e locais

Use a ação send existente com um único objeto location independente. As coordenadas enviam um marcador nativo; adicionar name e address envia um cartão nativo de local. Envios de localização não podem ser combinados com texto de mensagem ou mídia.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Torre Eiffel",address: "Champ de Mars, Paris",},}

Figurinhas

Recebidas: WEBP estático é baixado e processado (espaço reservado <media:sticker>); TGS animado e WEBM de vídeo são ignorados.

Campos de contexto do sticker: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. As descrições são armazenadas em cache no estado do plugin SQLite do OpenClaw para reduzir chamadas repetidas de visão.

Ative as ações de sticker:

{channels: {telegram: {  actions: {    sticker: true,  },},},}

Envie:

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

Pesquise stickers armazenados em cache:

{action: "sticker-search",channel: "telegram",query: "cat waving",limit: 5,}

As reações do Telegram chegam como atualizações message_reaction, separadas dos payloads das mensagens. Quando habilitado, o OpenClaw enfileira eventos de sistema como Telegram reaction added: 👍 by Alice (@alice) on msg 42.

• channels.telegram.reactionNotifications: off | own | all (padrão: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (padrão: minimal)

own significa apenas reações de usuários a mensagens enviadas pelo bot (em caráter de melhor esforço, por meio de um cache de mensagens enviadas). Os 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 threads nas atualizações de reação: grupos que não são fóruns são encaminhados para a sessão do chat em grupo; grupos que são fóruns são encaminhados para a sessão do tópico geral (: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. messages.ackReactionScope determina quando ele é enviado.

Ordem de resolução do emoji:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback para o emoji de identidade do agente (agents.list[].identity.emoji; caso contrário, "👀")

O Telegram espera um emoji Unicode (por exemplo, "👀"); use "" para desabilitar a reação para um canal ou uma conta.

Escopo (messages.ackReactionScope, padrão: "group-mentions"; atualmente sem substituição por conta ou canal do Telegram):

all (MDs + grupos, incluindo eventos ambientes de sala), direct (somente MDs), group-all (todas as mensagens de grupo, exceto eventos ambientes de sala; sem MDs), group-mentions (grupos quando o bot é mencionado; sem MDs — padrão), off / none (desabilitado).

As gravações de configuração do canal são habilitadas por padrão (configWrites !== false). As gravações acionadas pelo Telegram incluem eventos de migração de grupo (migrate_to_chat_id, atualiza channels.telegram.groups) e /config set / /config unset (requer que os comandos estejam habilitados).

Desabilite:

{channels: {telegram: {  configWrites: false,},},}

O padrão é long polling. Para o modo webhook, defina channels.telegram.webhookUrl e channels.telegram.webhookSecret; opcionais: webhookPath (padrão: /telegram-webhook), webhookHost (padrão: 127.0.0.1), webhookPort (padrão: 8787), webhookCertPath (certificado PEM autoassinado para configurações com IP direto ou sem domínio).

No modo long polling, o OpenClaw persiste seu marcador de reinicialização somente depois que uma atualização é despachada com sucesso; uma falha no manipulador deixa essa atualização disponível para nova tentativa no mesmo processo, em vez de marcá-la como concluída.

O listener local se vincula a 127.0.0.1:8787 por padrão. Para entrada pública, coloque um proxy reverso à frente da porta local ou defina webhookHost: "0.0.0.0" intencionalmente.

O modo webhook valida as proteções da solicitação, o token secreto do Telegram e o corpo JSON, depois confirma a atualização em sua fila durável de entrada antes de retornar um 200 vazio. A adoção durável bem-sucedida inclui x-openclaw-delivery-accepted: durable; respostas de integridade, roteamento, autenticação, validação e erro de armazenamento omitem esse cabeçalho. Proxies reversos e controladores de host podem exigir o cabeçalho para distinguir a adoção pelo OpenClaw de um 200 vazio genérico, sem inferir a aceitação pelo tempo de resposta.

Em seguida, o OpenClaw processa a atualização de forma assíncrona pelas mesmas filas do bot por chat/tópico usadas pelo long polling, para que execuções lentas do agente não retenham o ACK de entrega do Telegram.

• channels.telegram.textChunkLimit tem como padrão 4000; streaming.chunkMode="newline" prioriza limites de parágrafo (linhas em branco) antes da divisão por comprimento.
• channels.telegram.mediaMaxMb (padrão 100) limita o tamanho da mídia de entrada e saída.
• channels.telegram.mediaGroupFlushMs (padrão 500, intervalo 10-60000) controla por quanto tempo álbuns/grupos de mídia ficam em buffer antes de o OpenClaw encaminhá-los como uma única mensagem de entrada. Aumente esse valor se partes do álbum chegarem atrasadas; diminua-o para reduzir a latência da resposta ao álbum.
• channels.telegram.timeoutSeconds substitui o tempo limite do cliente da API (o padrão do grammY se aplica se não estiver definido). Os clientes de bot ajustam os valores configurados abaixo da proteção de 60 segundos para solicitações de texto/digitação de saída, para que o grammY não interrompa a entrega de respostas visíveis antes que a proteção de transporte e o fallback do OpenClaw possam ser executados. O long polling ainda usa uma proteção de 45 segundos para solicitações getUpdates, para que sondagens ociosas não sejam abandonadas indefinidamente.
• channels.telegram.pollingStallThresholdMs tem como padrão 120000; ajuste entre 30000 e 600000 somente para reinicializações por falsos positivos de interrupção do polling.
• o histórico de contexto de grupos usa channels.telegram.historyLimit ou messages.groupChat.historyLimit (padrão 50); 0 desativa.
• o contexto complementar de resposta/citação/encaminhamento é normalizado em uma única janela de contexto de conversa selecionada quando o Gateway observou as mensagens anteriores; o cache de mensagens observadas fica no estado SQLite do Plugin do OpenClaw, e openclaw doctor --fix importa arquivos auxiliares legados. O Telegram inclui apenas um reply_to_message superficial por atualização, portanto as cadeias anteriores ao cache ficam limitadas a esse payload.
• as listas de permissões do Telegram controlam principalmente quem pode acionar o agente, não constituindo um limite completo de redação do contexto complementar.
• histórico de MDs: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final de entrada usa uma nova tentativa limitada de envio seguro para falhas anteriores à conexão, mas não repete envelopes de rede ambíguos posteriores ao envio que poderiam duplicar mensagens visíveis.

Os destinos de envio da CLI e da ferramenta de mensagens aceitam um ID numérico de chat, nome de usuário ou destino de tópico de fórum:

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"

As enquetes usam openclaw message poll e oferecem suporte a tópicos de fórum:

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

Opções de enquete exclusivas do Telegram: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (ou um destino :topic:). --poll-option é repetida de 2 a 12 vezes (limite de opções do Telegram).

O envio pelo Telegram também oferece suporte a --presentation com blocos buttons para teclados embutidos (quando channels.telegram.capabilities.inlineButtons permitir), --pin ou --delivery '{"pin":true}' para solicitar a entrega fixada quando o bot puder fixar mensagens nesse chat, e --force-document para enviar imagens, GIFs e vídeos de saída como documentos em vez de uploads compactados/animados/de vídeo.

Controle de ações: channels.telegram.actions.sendMessage=false desativa todas as mensagens de saída, incluindo enquetes; channels.telegram.actions.poll=false desativa a criação de enquetes, mantendo os envios normais ativados.

O Telegram oferece suporte a aprovações de execução em MDs dos aprovadores e pode, opcionalmente, publicar solicitações no chat ou tópico de origem. Os aprovadores devem ser IDs numéricos de usuários do Telegram.

• channels.telegram.execApprovals.enabled ("auto" ativa quando pelo menos um aprovador pode ser resolvido)
• channels.telegram.execApprovals.approvers (usa como fallback os IDs numéricos dos proprietários em commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (padrão) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom e defaultTo controlam quem pode falar com o bot e para onde ele envia respostas normais — elas não tornam alguém um aprovador de execução. O primeiro pareamento aprovado por MD inicializa commands.ownerAllowFrom quando ainda não existe um proprietário de comandos, permitindo que configurações com um único proprietário funcionem sem duplicar IDs em execApprovals.approvers.

A entrega no canal mostra o texto do comando no chat; ative channel ou both somente em grupos/tópicos confiáveis. Quando a solicitação chega a um tópico de fórum, o OpenClaw preserva o tópico para a solicitação de aprovação e o acompanhamento. As aprovações de execução expiram após 30 minutos por padrão.

Os botões de aprovação embutidos também exigem que channels.telegram.capabilities.inlineButtons permita a superfície de destino (dm, group ou all). IDs de aprovação com o prefixo plugin: são resolvidos por meio das aprovações de plugins; os demais são resolvidos primeiro por meio das aprovações de execução.

Consulte Aprovações de execução.

• Se requireMention=false, o modo de privacidade do Telegram deve permitir visibilidade completa: BotFather /setprivacy -> Disable, depois remova e adicione novamente o bot ao grupo.
• openclaw channels status exibe um aviso quando a configuração espera mensagens de grupo sem menção.
• openclaw channels status --probe verifica IDs numéricos explícitos de grupos; não é possível sondar a associação do curinga "*".
• 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.
• Consulte openclaw logs --follow para identificar os motivos de mensagens ignoradas.

• Autorize sua identidade de remetente (pareamento e/ou allowFrom numérico); a autorização de comandos continua sendo aplicada mesmo quando a política do grupo é open.
• setMyCommands failed com BOT_COMMANDS_TOO_MUCH significa que o menu nativo tem entradas demais; reduza os comandos de plugins/Skills/personalizados ou desative os menus nativos.
• As chamadas de inicialização deleteMyCommands / setMyCommands e as chamadas de digitação sendChatAction são limitadas e repetidas uma vez por meio do fallback de transporte do Telegram em caso de tempo limite da solicitação. Erros persistentes de rede/fetch geralmente significam que o DNS/HTTPS para api.telegram.org está inacessível.

• getMe returned 401 é uma falha de autenticação do Telegram referente ao token de bot configurado. Copie novamente ou gere de novo o token no BotFather e atualize channels.telegram.botToken, tokenFile, accounts.<id>.botToken ou TELEGRAM_BOT_TOKEN (conta padrão).
• deleteWebhook 401 Unauthorized durante a inicialização também é uma falha de autenticação; tratá-la como se "não existisse nenhum webhook" apenas adiaria a mesma falha de token inválido para uma chamada posterior da API.

• O Node 22+ com fetch/proxy personalizado pode causar um comportamento de cancelamento imediato se os tipos de AbortSignal não corresponderem.
• Alguns hosts resolvem api.telegram.org primeiro para IPv6; uma saída IPv6 com defeito causa falhas intermitentes da API.
• Logs com TypeError: fetch failed ou Network request for 'getUpdates' failed! são repetidos como erros de rede recuperáveis.
• Durante a inicialização do polling, o OpenClaw reutiliza no grammY a sondagem getMe bem-sucedida da inicialização, para que o executor não precise de um segundo getMe antes do primeiro getUpdates.
• Se deleteWebhook falhar com um erro de rede transitório durante a inicialização do polling, o OpenClaw prossegue para o long polling em vez de realizar outra chamada ao plano de controle antes do polling. Um Webhook ainda ativo aparece então como um conflito de getUpdates; o OpenClaw reconstrói o transporte e repete a limpeza do Webhook.
• Se os soquetes do Telegram forem reciclados em uma cadência fixa curta, verifique se channels.telegram.timeoutSeconds está baixo — os clientes de bot ajustam os valores configurados abaixo das proteções de solicitação de saída e de getUpdates, mas versões anteriores podiam cancelar cada polling ou resposta quando o valor era definido abaixo dessas proteções.
• Polling stall detected nos logs significa que o OpenClaw reinicia o polling e reconstrói o transporte após 120 segundos sem atividade concluída de long polling por padrão.
• openclaw channels status --probe e openclaw doctor exibem um aviso quando uma conta de polling em execução não concluiu getUpdates após o período de tolerância da inicialização, uma conta de Webhook em execução não concluiu setWebhook após esse período, ou a última atividade bem-sucedida do transporte de polling está desatualizada.
• Aumente channels.telegram.pollingStallThresholdMs somente quando chamadas getUpdates de longa duração estiverem íntegras, mas seu host ainda relatar reinicializações por falsos positivos de interrupção do polling. Interrupções persistentes geralmente indicam problemas de proxy, DNS, IPv6 ou saída TLS para api.telegram.org.
• O Telegram respeita as variáveis de ambiente de proxy do processo para o transporte da API de Bot: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e as variantes em letras minúsculas. NO_PROXY / no_proxy ainda podem ignorar o proxy para api.telegram.org.
• Se OPENCLAW_PROXY_URL estiver definida em um ambiente de serviço e nenhuma variável de ambiente de proxy padrão estiver presente, o Telegram também usará essa URL para o transporte da API de Bot.
• Em hosts VPS com saída direta/TLS instável, encaminhe as chamadas da API do Telegram por um proxy:

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• O Node 22+ usa autoSelectFamily=true por padrão (exceto no WSL2). A ordem dos resultados de DNS do Telegram respeita OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, depois channels.telegram.network.dnsResultOrder e, em seguida, o padrão do processo (por exemplo, NODE_OPTIONS=--dns-result-order=ipv4first), usando ipv4first como fallback no Node 22+ se nenhuma opção for aplicável.
• No WSL2, ou quando o comportamento somente com IPv4 funcionar melhor, force a seleção da família:

channels:telegram:network:  autoSelectFamily: false

• As respostas do intervalo de benchmark RFC 2544 (198.18.0.0/15) já são permitidas por padrão para downloads de mídia do Telegram. Se um proxy fake-IP ou transparente confiável reescrever api.telegram.org para algum outro endereço privado/interno/de uso especial durante downloads de mídia, habilite explicitamente a exceção exclusiva do Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• A mesma habilitação explícita está disponível por conta em channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se o proxy resolver hosts de mídia do Telegram para 198.18.x.x, mantenha primeiro a opção perigosa desativada — esse intervalo já é permitido por padrão.

• Substituições temporárias por variáveis de ambiente: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Valide as respostas DNS:

dig +short api.telegram.org Adig +short api.telegram.org AAAA