Telegram

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

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

• 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

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

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

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

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

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

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

​

Mensagens de áudio

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

​

Localizações e estabelecimentos

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

​

Stickers

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "gato acenando",
  limit: 5,
}

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

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

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

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

• 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

• 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 A
dig +short api.telegram.org AAAA