Integração Completa: Telegram + OpenClaw em 2026

O Telegram é uma das plataformas mais populares para interagir com bots — e por boas razões. APIs robustas, suporte a grupos, arquivos grandes, e uma base de usuários que espera inovação.

Neste tutorial, vamos configurar uma integração completa entre Telegram e OpenClaw.

Por Que Telegram?

Antes de começar, vamos entender as vantagens:

Sim Vantagens

• Disponível em todo lugar: Apps nativos para iOS, Android, Desktop, Web
• Sem limite de mensagens: Diferente do WhatsApp
• Suporte a arquivos grandes: Até 2GB por arquivo
• Grupos e canais: Organize conversas por tema
• Bot API madura: Documentação excelente
• Reações e replies: UI rica para interações

Atenção: Considerações

• Precisa de número de telefone para registro
• Menos popular que WhatsApp no Brasil
• Sem integração nativa com iMessage

Pré-requisitos

Antes de começar, você precisa de:

1. OpenClaw instalado e funcionando
2. Conta no Telegram (pode ser a sua pessoal)
3. 10 minutos para configurar

Passo 1: Criar o Bot

Acesse o BotFather

O BotFather é o bot oficial do Telegram para criar outros bots.

1. Abra o Telegram
2. Busque por @BotFather
3. Inicie uma conversa

Crie seu bot

Envie o comando:

/newbot

O BotFather vai perguntar:

1. Nome do bot: O nome de exibição (ex: “Meu Assistente IA”)
2. Username: Identificador único, deve terminar em bot (ex: meu_assistente_ia_bot)

Copie o Token

Após criar, você receberá uma mensagem com o token:

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Atenção: Guarde este token em segredo! Qualquer pessoa com ele pode controlar seu bot.

Passo 2: Configurar o OpenClaw

Edite seu config.yaml:

channels:
  telegram:
    token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    
    # Quem pode usar o bot
    allowList:
      - "123456789"  # Seu user ID
    
    # Ou aceitar qualquer um (cuidado!)
    # allowAll: true

Descobrir seu User ID

Você precisa do seu ID numérico do Telegram. Existem algumas formas:

Opção 1: Bot @userinfobot

1. Busque @userinfobot no Telegram
2. Envie qualquer mensagem
3. Ele responde com seu ID

Opção 2: Bot @getmyid_bot

1. Busque @getmyid_bot
2. Envie /start
3. Receba seu ID

Passo 3: Reiniciar e Testar

openclaw gateway restart

Agora abra o Telegram, encontre seu bot pelo username e envie uma mensagem!

Recursos Avançados

Grupos

Quer usar o bot em um grupo? Configure:

channels:
  telegram:
    token: "seu-token"
    allowList:
      - "123456789"      # Seu ID
      - "-987654321"     # ID do grupo (negativo)

Dica: IDs de grupo são negativos. Para descobrir, adicione o bot ao grupo e veja nos logs do OpenClaw.

Menções em Grupos

Por padrão, o bot responde a todas as mensagens em grupos permitidos. Para responder apenas quando mencionado:

channels:
  telegram:
    mentionOnly: true

Reações

O OpenClaw pode reagir a mensagens. Configure o estilo:

channels:
  telegram:
    reactions:
      mode: minimal  # none | minimal | normal

Webhooks vs Polling

Por padrão, o OpenClaw usa polling (consulta periódica). Para melhor performance, configure webhooks:

channels:
  telegram:
    webhook:
      url: "https://seu-dominio.com/webhook/telegram"
      secretToken: "um-segredo-forte"

Requisitos para webhook:

• Domínio com HTTPS válido
• Porta 443, 80, 88 ou 8443
• OpenClaw acessível publicamente

Comandos Úteis

Você pode configurar comandos que aparecem no menu do Telegram:

No BotFather

Envie para @BotFather:

/setcommands

Escolha seu bot e envie a lista:

status - Ver status do sistema
ajuda - Obter ajuda
limpar - Limpar contexto da conversa

No OpenClaw

Configure respostas personalizadas:

channels:
  telegram:
    commands:
      status: "Use /status para ver informações do sistema"

Segurança

AllowList é Essencial

Nunca use allowAll: true em produção a menos que você queira que qualquer pessoa use seu bot (e sua API).

Grupos Públicos

Se adicionar o bot a grupos públicos, considere:

• Usar mentionOnly: true
• Limitar os comandos disponíveis
• Monitorar uso para abusos

Rotação de Token

Se suspeitar que o token vazou:

1. Vá ao @BotFather
2. Envie /revoke
3. Escolha seu bot
4. Atualize o token no OpenClaw

Troubleshooting

Bot não responde

Verifique:

1. Token está correto?
2. Seu ID está na allowList?
3. Gateway está rodando? (openclaw gateway status)
4. Logs mostram erros? (openclaw gateway logs)

Mensagens duplicadas

Provavelmente você tem webhook E polling ativos. Escolha um:

channels:
  telegram:
    polling: false  # Se usar webhook

Demora para responder

• Verifique a conexão com a API do Claude
• Mensagens longas levam mais tempo para processar
• Considere usar webhook em vez de polling

Integrações Práticas

Notificações Automáticas

Configure o OpenClaw para enviar alertas:

// Exemplo de skill que notifica
message.send({
  channel: "telegram",
  target: "123456789",
  message: "🚨 Servidor fora do ar!"
});

Resumo de Links

Envie um link e peça:

https://exemplo.com/artigo-longo

Resume isso pra mim

Transcrição de Áudio

Envie um áudio ou vídeo e peça:

Transcreve isso

Próximos Passos

Com Telegram configurado, explore:

• Conectar WhatsApp também
• Skills personalizadas
• Automações com cron

O Telegram + OpenClaw é uma combinação poderosa. Seu assistente de IA está sempre a uma mensagem de distância, em qualquer dispositivo.

Configure agora e transforme como você interage com IA no dia a dia.