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

• /setjoingroups para permitir/negar adições 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)
• valores legados booleanos de channels.telegram.streamMode e streaming são mapeados automaticamente

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

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

• Texto em estilo Markdown é renderizado em HTML seguro para Telegram.
• HTML bruto do modelo é escapado para reduzir falhas de parse do Telegram.
• Se o Telegram rejeitar o HTML parseado, 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, 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 personalizados/de plugin/Skills ou desative channels.telegram.commands.native.
• 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 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 papel/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 específico de mensagem do Telegram

• off (padrão)
• first
• all

• chaves de sessão de tópico acrescentam :topic:<threadId>
• respostas e digitação têm como alvo 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" },      // Tópico Geral → agente main
            "3": { agentId: "zu" },        // Tópico Dev → agente zu
            "5": { agentId: "coder" }      // Revisão de código → agente coder
          }
        }
      }
    }
  }
}

• 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 dentro do tópico após um vínculo 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/alvos de resposta cientes da 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 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 apenas reações de usuário 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 sem fórum roteiam para a sessão do chat em grupo
  • grupos com 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 para emoji de identidade do agente (agents.list[].identity.emoji, senão ”👀”)

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

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

• defina channels.telegram.webhookUrl
• defina channels.telegram.webhookSecret (obrigatório quando webhookUrl estiver definido)
• channels.telegram.webhookPath opcional (padrão /telegram-webhook)
• channels.telegram.webhookHost opcional (padrão 127.0.0.1)
• channels.telegram.webhookPort opcional (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 de entrada e saída do Telegram.
• channels.telegram.timeoutSeconds substitui o timeout do cliente da API do Telegram (se não definido, o padrão do grammY se aplica).
• o histórico de contexto de grupo usa channels.telegram.historyLimit ou messages.groupChat.historyLimit (padrão 50); 0 desativa.
• o contexto suplementar de resposta/citação/encaminhamento atualmente é repassado como recebido.
• as 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 de 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 alvo :topic:)

• --buttons para teclados inline quando channels.telegram.capabilities.inlineButtons permitir
• --force-document para enviar imagens e GIFs de saída como documentos em vez de upload comprimido de foto ou mídia animada

• channels.telegram.actions.sendMessage=false desativa mensagens de saída do Telegram, incluindo enquetes
• channels.telegram.actions.poll=false desativa a criação de enquete no Telegram enquanto mantém envios regulares ativados

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (opcional; recai para IDs numéricos de dono 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 somente 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 exec.approval.resolve primeiro.
• 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 recorrem silenciosamente à 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 emite aviso 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 ter associação verificada.
• teste rápido de sessão: /activation always.

• quando channels.telegram.groups existe, o grupo precisa estar listado (ou incluir "*")
• verifique se o bot é membro do 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 comandos 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 personalizados/de plugin/Skills ou desative menus nativos
• setMyCommands failed com erros de rede/fetch normalmente indica problemas de alcance DNS/HTTPS para api.telegram.org

• Node 22+ + fetch/proxy personalizado podem disparar comportamento de aborto imediato se os tipos de AbortSignal não forem compatíveis.
• Alguns hosts resolvem api.telegram.org para IPv6 primeiro; saída IPv6 quebrada 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.
• Em hosts VPS com saída direta/TLS instável, encaminhe 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 da faixa 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 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 somente do Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• A mesma ativação opcional também está disponível por conta em channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se seu proxy resolver hosts de mídia do Telegram em 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.

• Substituições por 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