Telegram

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

Para ver todas as mensagens dos grupos:

• desative o modo de privacidade por meio de /setprivacy, ou
• torne o bot administrador do grupo.

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

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

• /setjoingroups — permitir ou 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 prefira uma interface em vez de comandos de chat.

O OpenClaw transmite respostas parciais em tempo real em chats diretos, grupos e tópicos: envia uma mensagem de prévia, executa editMessageText repetidamente e finaliza no mesmo local.

• channels.telegram.streaming é off | partial | block | progress (padrão: partial)
• prévias curtas da resposta inicial passam por debounce e depois 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, mostra 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 comando/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 de prévia de rascunho nativa 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 durante a execução das ferramentas (execução de comandos, leitura de arquivos, atualizações de planejamento, resumos de patches, preâmbulo/comentário do Codex no modo app-server). O Telegram as mantém habilitadas por padrão (corresponde ao comportamento lançado a partir de 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 comando/execução:

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

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

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

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

Para respostas somente de texto: prévias curtas recebem a edição final no mesmo local; respostas finais longas divididas em várias mensagens reutilizam a prévia como o primeiro fragmento e enviam apenas o restante; respostas finais no modo de progresso limpam o rascunho de status e usam a entrega final normal; se a edição final falhar antes da confirmação da conclusão, o OpenClaw recorre à entrega final normal e remove a prévia obsoleta. Para respostas complexas (cargas de mídia), o OpenClaw sempre recorre à entrega 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 é habilitada explicitamente, o OpenClaw ignora a transmissão da prévia para evitar transmissão duplicada.

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

Por padrão, o texto enviado usa mensagens HTML padrão do Telegram, legíveis nos clientes atuais: negrito, itálico, links, código, spoilers, citações — não blocos avançados exclusivos da Bot API 10.2 (tabelas nativas, detalhes, mídia avançada, fórmulas).

Habilite mensagens avançadas da Bot API 10.2:

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

Quando habilitado: o agente é informado de que mensagens avançadas estão disponíveis para esse bot/essa conta (com o contrato de autoria compatível com Markdown + ilhas HTML); o texto Markdown é renderizado pelo IR de Markdown do OpenClaw como blocos avançados tipados da Bot API 10.2 (títulos, tabelas, detalhes, listas de verificação, mídia avançada, fórmulas, mapas, colagens); as legendas de mídia continuam usando legendas HTML do Telegram (mensagens avançadas não substituem legendas, e as legendas têm um limite de 1024 caracteres).

Isso mantém o texto do modelo afastado dos símbolos especiais de Markdown avançado do Telegram, para que valores monetários como $400-600K não 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: desabilitado, para compatibilidade com clientes — alguns clientes atuais para Desktop, Web, Android e de terceiros renderizam mensagens avançadas aceitas como não compatíveis. Mantenha essa opção desabilitada, a menos que todos os clientes usados com o bot consigam renderizá-las. /status mostra se as mensagens avançadas estão habilitadas ou desabilitadas na sessão atual.

As prévias de links são habilitadas por padrão. channels.telegram.linkPreview: false desabilita a detecção automática de entidades para 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 do / inicial, 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/Skills ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram. Se os comandos nativos forem desabilitados, 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 Plugin/Skills/personalizados ou desabilite channels.telegram.commands.native.
• Falhas de deleteWebhook, deleteMyCommands ou setMyCommands com 404: Not Found, enquanto comandos curl diretos da Bot API funcionam, geralmente significam que channels.telegram.apiRoot foi definido como o endpoint completo de /bot<TOKEN>. apiRoot deve ser somente a raiz da Bot API; openclaw doctor --fix remove um /bot<TOKEN> final 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 é interrompido antes do polling, portanto isso não é informado como uma falha de limpeza de Webhook.
• setMyCommands failed com erros de rede/busca geralmente 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 detalhes de autenticação alterados (função, escopos, chave pública), a solicitação pendente anterior será substituída por um novo requestId; execute novamente /pair pending antes de aprovar.

Mais detalhes: Pareamento.

Configure o escopo do teclado embutido:

{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 capabilities: ["inlineButtons"] legado é mapeado para "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: "Abrir aplicativo:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Iniciar", web_app: { url: "https://example.com/app" } }],  },],},}

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

Cliques de callback não reivindicados por um manipulador interativo de plugin registrado são encaminhados 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 embutidos presentation opcionais; edições somente de botões atualizam a marcação da resposta)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

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

Controle de disponibilidade: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (padrão: desabilitado). edit, createForumTopic e editForumTopic são habilitados por padrão, sem opção 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 resposta
• [[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á habilitado 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 recorrem a uma resposta simples se o Telegram rejeitar a citação.

off desabilita apenas o encadeamento implícito de respostas; as tags explícitas [[reply_to_*]] continuam sendo respeitadas.

Supergrupos de fórum: as chaves de sessão do tópico 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 não encontrada"), 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ópico herdam as configurações do grupo, salvo quando substituídas (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId é exclusivo do tópico e não herda os padrões do grupo. topics."*" define os padrões para todos os tópicos desse grupo; IDs de tópico exatos ainda têm precedência sobre "*".

Roteamento de agentes por tópico: cada tópico pode ser roteado para um agente diferente por meio de agentId na configuração do tópico, atribuindo a ele 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 template expõe MessageThreadId e IsForum. Conversas por mensagem direta com message_thread_id mantêm os metadados de resposta, mas usam chaves de sessão compatíveis com threads somente quando getMe do Telegram informa has_topics_enabled: true. As substituições descontinuadas dm.threadReplies e direct.*.threadReplies foram removidas; o modo de threads do BotFather é a única fonte da verdade. Execute openclaw doctor --fix para remover chaves de configuração obsoletas.

Mensagens de áudio

O Telegram distingue 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 e gerado por máquina, mas a detecção de menções ainda usa a transcrição bruta para manter o funcionamento de mensagens de voz condicionadas a menções.

{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 mensagens de vídeo. Mensagens de vídeo não oferecem suporte a legendas; o texto fornecido para a mensagem é enviado separadamente.

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

Localizações e estabelecimentos

Use a ação existente send com um único objeto independente location. As coordenadas enviam um marcador nativo; adicionar name e address envia um cartão nativo de estabelecimento. Envios de localização não podem ser combinados com texto de mensagem nem 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",},}

Stickers

Recebimento: 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 SQLite do plugin do OpenClaw para reduzir chamadas repetidas de visão.

Habilite ações de stickers:

{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: "gato acenando",limit: 5,}

As reações do Telegram chegam como atualizações message_reaction, separadas das cargas de 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 (melhor esforço por meio de um cache de mensagens enviadas). Os eventos de reação continuam respeitando 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 nas atualizações de reação: grupos que não são fóruns são roteados para a sessão de conversa do grupo; grupos de fórum são roteados 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
• emoji de fallback da identidade do agente (agents.list[].identity.emoji, caso contrário, "👀")

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

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

all (mensagens diretas + grupos, incluindo eventos ambientes da sala), direct (somente mensagens diretas), group-all (todas as mensagens de grupo, exceto eventos ambientes da sala; sem mensagens diretas), group-mentions (grupos quando o bot é mencionado; sem mensagens diretas — 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 a habilitação do comando).

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 (PEM de certificado 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 e, em seguida, confirma a atualização em sua fila de entrada durável 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 conversa/tópico usadas pelo long polling; assim, execuções lentas do agente não retêm o ACK de entrega do Telegram.

• channels.telegram.textChunkLimit padrão 4000; streaming.chunkMode="newline" prioriza limites de parágrafo (linhas em branco) antes da divisão por tamanho.
• 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 que o OpenClaw os encaminhe como uma única mensagem de entrada. Aumente-o se partes do álbum chegarem com atraso; 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 restringem 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 solicitação getUpdates de 45 segundos 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 detecção falso-positiva de sondagem travada.
• o histórico de contexto do grupo 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 pai; 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, cadeias mais antigas que o cache ficam limitadas a essa carga útil.
• as listas de permissões do Telegram controlam principalmente quem pode acionar o agente, não constituindo um limite completo de ocultação do contexto complementar.
• histórico de MD: 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

Flags de enquete exclusivas do Telegram: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (ou um destino :topic:). --poll-option repete 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 permite), --pin ou --delivery '{"pin":true}' para solicitar a entrega fixada quando o bot pode 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 enquanto mantém os envios regulares ativados.

O Telegram oferece suporte a aprovações de execução nas 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 (recorre aos IDs numéricos dos proprietários em commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (padrão) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom e defaultTo controlam quem pode conversar com o bot e para onde ele envia respostas normais — eles 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, portanto, configurações com um único proprietário funcionam 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. Por padrão, as aprovações de execução expiram após 30 minutos.

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 prefixados com plugin: são resolvidos por meio das aprovações do Plugin; 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 total: BotFather /setprivacy -> Disable; 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 verifica IDs numéricos explícitos de grupos; não é possível sondar a associação com o 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 saber os motivos de omissão.

• Autorize sua identidade de 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 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 para o token de bot configurado. Copie novamente ou gere outro 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 "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para uma chamada posterior da API.

• O Node 22+ com fetch/proxy personalizado pode acionar um comportamento de interrupção imediata se os tipos de AbortSignal forem incompatíveis.
• Alguns hosts resolvem api.telegram.org primeiro para IPv6; uma saída IPv6 com problemas 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 da sondagem, o OpenClaw reutiliza para o grammY a sondagem getMe bem-sucedida da inicialização, para que o executor não precise de uma segunda getMe antes do primeiro getUpdates.
• Se deleteWebhook falhar com um erro transitório de rede durante a inicialização da sondagem, o OpenClaw prossegue para o long polling em vez de realizar outra chamada de plano de controle antes da sondagem. Um webhook ainda ativo surge então como um conflito getUpdates; o OpenClaw reconstrói o transporte e tenta novamente limpar o webhook.
• Se os soquetes do Telegram forem reciclados em uma cadência fixa curta, verifique se há um channels.telegram.timeoutSeconds baixo — os clientes de bot restringem os valores configurados abaixo das proteções de solicitação de saída e getUpdates, mas versões anteriores podiam interromper cada sondagem ou resposta quando esse valor era definido abaixo dessas proteções.
• Polling stall detected nos logs significa que, por padrão, o OpenClaw reinicia a sondagem e reconstrói o transporte após 120 segundos sem atividade concluída do long polling.
• openclaw channels status --probe e openclaw doctor avisam quando uma conta de sondagem em execução não concluiu getUpdates após o período de tolerância da inicialização, quando uma conta de webhook em execução não concluiu setWebhook após o período de tolerância da inicialização ou quando a última atividade bem-sucedida do transporte de sondagem está desatualizada.
• Aumente channels.telegram.pollingStallThresholdMs somente quando chamadas getUpdates de longa duração estiverem íntegras, mas seu host ainda informar reinicializações falso-positivas por sondagem travada. Travamentos 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 bots: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e variantes em minúsculas. NO_PROXY / no_proxy ainda podem ignorar api.telegram.org.
• Se OPENCLAW_PROXY_URL estiver definido para 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 bots.
• 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), recorrendo a ipv4first no Node 22+ se nenhuma opção se aplicar.
• No WSL2, ou quando o comportamento somente 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 confiável ou transparente reescrever api.telegram.org para algum outro endereço privado/interno/de uso especial durante downloads de mídia, habilite a exceção exclusiva do Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• A mesma habilitação 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, primeiro mantenha 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 de DNS:

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