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

• /setjoingroups para permitir/negar adição a grupos
• /setprivacy para comportamento de visibilidade em grupos

• 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 é mapeado para partial no Telegram (compatibilidade com nomenclatura entre canais)
• streaming.preview.toolProgress controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: true). Defina false para manter mensagens separadas de ferramenta/progresso.
• channels.telegram.streamMode legado e valores booleanos de streaming são mapeados automaticamente

• DM: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem)
• grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem)

• /reasoning stream envia reasoning para a prévia ao vivo durante a geração
• a resposta final é enviada sem o texto de reasoning

• Texto em estilo Markdown é renderizado para HTML seguro para Telegram.
• HTML bruto do modelo é escapado para reduzir falhas de parsing do Telegram.
• Se o Telegram rejeitar o HTML parseado, o OpenClaw tenta novamente como texto simples.

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

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

• nomes são normalizados (remove / inicial, minúsculas)
• padrão válido: a-z, 0-9, _, comprimento 1..32
• comandos personalizados não podem sobrescrever 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 sejam mostrados 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.
• 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 um 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 houver apenas 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, mediaUrl, replyToMessageId, messageThreadId opcionais)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, iconColor, iconCustomEmojiId opcionais)

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

• [[reply_to_current]] responde à mensagem que acionou
• [[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 digitação são direcionadas à 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
          }
        }
      }
    }
  }
}

• bindings[] com type: "acp" e match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto pode vincular o tópico atual do Telegram a uma nova sessão ACP.
• Mensagens subsequentes do tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de /acp steer).
• O OpenClaw fixa a mensagem de confirmação do spawn no tópico após um binding bem-sucedido.
• Requer channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• chats privados com message_thread_id mantêm o roteamento de DM, mas usam chaves de sessão e alvos de resposta cientes de thread.

​

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

{
  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 em 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 apenas reações de usuários a mensagens enviadas pelo bot (best-effort via cache de mensagens enviadas).
• 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 thread em atualizações de reação.
  • grupos que não são fórum são roteados para a sessão de chat do grupo
  • grupos de fórum são roteados 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 para emoji de identidade do agente (agents.list[].identity.emoji, caso contrário "👀")

• O Telegram espera emoji Unicode (por exemplo "👀").
• Use "" para desativar 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 ativação de comandos)

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

• defina channels.telegram.webhookUrl
• defina channels.telegram.webhookSecret (obrigatório quando webhookUrl estiver definido)
• opcional channels.telegram.webhookPath (padrão /telegram-webhook)
• opcional channels.telegram.webhookHost (padrão 127.0.0.1)
• opcional channels.telegram.webhookPort (padrão 8787)

• o padrão de channels.telegram.textChunkLimit é 4000.
• channels.telegram.chunkMode="newline" prefere limites de parágrafo (linhas em branco) antes da divisão por comprimento.
• channels.telegram.mediaMaxMb (padrão 100) limita o tamanho de mídia do Telegram de entrada e saída.
• channels.telegram.timeoutSeconds sobrescreve o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY).
• channels.telegram.pollingStallThresholdMs tem padrão 120000; ajuste entre 30000 e 600000 apenas para reinicializações falso-positivas de polling travado.
• o histórico de contexto de grupo usa channels.telegram.historyLimit ou messages.groupChat.historyLimit (padrão 50); 0 desativa.
• contexto suplementar de resposta/citação/encaminhamento atualmente é repassado como recebido.
• allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo 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 aos helpers de envio do Telegram (CLI/tools/actions) para erros recuperáveis da API de saída.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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 permitir
• --pin ou --delivery '{"pin":true}' para solicitar entrega fixada quando o bot puder fixar naquela conversa
• --force-document para enviar imagens e GIFs de saída como documentos em vez de uploads comprimidos de foto ou mídia animada

• channels.telegram.actions.sendMessage=false desativa mensagens de saída do Telegram, incluindo polls
• channels.telegram.actions.poll=false desativa a criação de polls no Telegram, mantendo envios regulares ativados

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (opcional; usa como fallback IDs numéricos do proprietário inferidos de allowFrom e defaultTo direto quando possível)
• channels.telegram.execApprovals.target (dm | channel | both, padrão: dm)
• agentFilter, sessionFilter

• target: "dm" envia prompts de aprovação apenas para DMs de aprovadores resolvidos
• target: "channel" envia o prompt de volta para o chat/tópico de origem no Telegram
• target: "both" envia para DMs de aprovadores e para o chat/tópico de origem

• IDs com prefixo plugin: sempre são resolvidos por aprovações de Plugin.
• Outros IDs tentam primeiro exec.approval.resolve.
• Se o Telegram também estiver autorizado para aprovações de Plugin e o Gateway disser que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez via plugin.approval.resolve.
• Negativas/erros reais de aprovação de exec não fazem fallback silencioso para resolução de aprovação de Plugin.

• se requireMention=false, o modo de privacidade do Telegram deve permitir visibilidade completa.
  • BotFather: /setprivacy -> Disable
  • depois remova + 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 grupo; o curinga "*" não pode ser verificado por associação.
• teste rápido de sessão: /activation always.

• quando channels.telegram.groups existe, o grupo deve estar listado (ou incluir "*")
• verifique a participação do bot no grupo
• revise os logs: openclaw logs --follow para motivos de ignorar

• autorize sua identidade de remetente (pareamento e/ou allowFrom numérico)
• a autorização de comando ainda se aplica mesmo quando a política de grupo é open
• setMyCommands failed com BOT_COMMANDS_TOO_MUCH significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desative menus nativos
• setMyCommands failed com erros de rede/fetch geralmente indica problemas de alcance DNS/HTTPS até api.telegram.org

• Node 22+ + fetch/proxy personalizado pode disparar comportamento de abort imediato se os tipos de AbortSignal não corresponderem.
• Alguns hosts resolvem api.telegram.org para IPv6 primeiro; saída IPv6 com falha pode causar falhas intermitentes na API do Telegram.
• Se os logs incluírem TypeError: fetch failed ou Network request for 'getUpdates' failed!, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis.
• 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ído de long poll por padrão.
• Aumente channels.telegram.pollingStallThresholdMs apenas quando chamadas longas de getUpdates estiverem saudáveis, mas seu host ainda relatar reinicializações falso-positivas de polling travado. Stalls persistentes normalmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e api.telegram.org.
• Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por channels.telegram.proxy:

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

• Node 22+ usa por padrão autoSelectFamily=true (exceto WSL2) e dnsResultOrder=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 na faixa 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 ativar o bypass exclusivo do Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• O mesmo opt-in 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 a faixa de benchmark RFC 2544 por padrão.

• Sobrescritas por variável 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