Telegram

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

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

• chats diretos: mensagem de prévia + editMessageText
• grupos/tópicos: mensagem de prévia + editMessageText

• 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

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

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

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

• 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

• /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

• 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.

• commands.native: "auto" ativa comandos nativos para o Telegram

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

• 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

• 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

• 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<TOKEN>. apiRoot deve ser apenas a raiz da Bot API, e openclaw doctor --fix remove um /bot<TOKEN> 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)

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 <requestId> para aprovação explícita
   • /pair approve quando há somente uma solicitação pendente
   • /pair approve latest para a mais recente

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

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

• off
• dm
• group
• all
• allowlist (padrão)

{
  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" }],
  ],
}

• sendMessage (to, content, opcional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, opcional iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (padrão: desativado)

• [[reply_to_current]] responde à mensagem acionadora
• [[reply_to:<id>]] responde a um ID de mensagem específico do Telegram

• off (padrão)
• first
• all

• chaves de sessão de tópico acrescentam :topic:<threadId>
• respostas e indicador de digitação apontam para a thread do tópico
• caminho de configuração do tópico: channels.telegram.groups.<chatId>.topics.<threadId>

• envios de mensagem omitem message_thread_id (o Telegram rejeita sendMessage(...thread_id=1))
• ações de digitação ainda incluem message_thread_id

{
  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
          }
        }
      }
    }
  }
}

​

Mensagens 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.

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

​

Mensagens de vídeo

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

​

Stickers

• WEBP estático: baixado e processado (placeholder <media:sticker>)
• TGS animado: ignorado
• WEBM de vídeo: ignorado

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• 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 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

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

• O Telegram espera emoji unicode (por exemplo, ”👀”).
• Use "" para desabilitar a reação para um canal ou conta.

• 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)

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

• 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["<user_id>"].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.

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"

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id para tópicos de fórum (ou use um destino :topic:)

• --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

• 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

• 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

• 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.<id>.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:

channels:
  telegram:
    proxy: socks5://<user>:<password>@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:

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:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• A mesma opção está disponível por conta em channels.telegram.accounts.<accountId>.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.

• 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:

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