Integrar OpenClaw com Telegram — Bot IA em 5 Minutos (2026)

Crie um bot Telegram com IA em 5 minutos usando OpenClaw. BotFather → Token → Pronto. Funciona em grupos, inline, webhooks. Tutorial passo a passo.

📅 02 de February de 2026 ⏱️ 8 min de leitura

Telegram — Guia Completo de Integração com OpenClaw

O Telegram é o canal nativo e recomendado para o OpenClaw. É onde a integração funciona melhor, com suporte completo a todas as funcionalidades e a configuração mais simples.

Se você está começando com OpenClaw, comece pelo Telegram. Este guia vai te levar do zero ao bot funcionando em menos de 15 minutos.

Por Que Telegram?

Comparado a outros canais de mensagem, o Telegram oferece vantagens únicas:

RecursoTelegramWhatsAppDiscord
Setup5 minutos20+ minutos10 minutos
CustoGratuitoAPI pagaGratuito
Grupos✅ Nativo✅ Limitado✅ Servers
Bots✅ API oficial⚠️ Não oficial✅ API oficial
ArquivosAté 2GBAté 100MBAté 100MB
Reações✅ Completo✅ Básico✅ Completo
Botões inline✅ Nativo❌ Não suporta✅ Componentes
Rate limitsGenerosoRestritivoModerado
Funcionalidades Suportadas

O OpenClaw no Telegram oferece:

  • ✅ Mensagens de texto — Conversas naturais com o agente
  • ✅ Mensagens de voz — Transcrição automática com Whisper
  • ✅ Imagens e documentos — Análise visual e processamento de arquivos
  • ✅ Reações — O agente pode reagir às suas mensagens
  • ✅ Botões inline — Interfaces interativas
  • ✅ Grupos e canais — Funciona em conversas coletivas
  • ✅ Notificações em tempo real — Alertas proativos
  • ✅ Histórico completo — Memória de conversas anteriores
  • ✅ Comandos — Ações rápidas com /comandos
⏱️ Tempo de Setup: 10-15 minutos

Nível: Iniciante
Pré-requisitos:

  • OpenClaw instalado e funcionando
  • Conta no Telegram (celular ou desktop)
Passo 1: Criar Seu Bot no Telegram

O Telegram exige que toda automação seja feita através de um “bot” — uma conta especial controlada por código. Você cria esse bot através do BotFather, que é o bot oficial do Telegram para gerenciar outros bots.

1.1 Encontre o BotFather
  1. Abra o Telegram (app ou web)
  2. Na barra de busca, digite @BotFather
  3. Clique no resultado com o selo azul de verificado ✓

⚠️ Cuidado: Existem imitações! O BotFather oficial tem o selo azul e o username exato @BotFather.

1.2 Inicie a Conversa

Clique em Start ou envie /start para começar.

O BotFather vai mostrar uma lista de comandos disponíveis.

1.3 Crie um Novo Bot

Envie o comando:

/newbot

O BotFather vai guiar você pelo processo de criação.

1.4 Escolha o Nome de Exibição

O BotFather pede: “Alright, a new bot. How are we going to call it? Please choose a name for your bot.”

Digite o nome que aparecerá nas conversas. Pode ter espaços e caracteres especiais.

Exemplos:

  • Assistente do João
  • Meu Agente IA
  • Bot da Loja
1.5 Escolha o Username

Agora o BotFather pede: “Good. Now let’s choose a username for your bot.”

O username deve:

  • Ser único (ninguém mais pode ter)
  • Terminar em bot ou Bot
  • Ter entre 5-32 caracteres
  • Usar apenas letras, números e underscores

Exemplos:

  • assistente_joao_bot
  • minha_loja_ai_bot
  • openclaw_demo_bot

💡 Dica: Se o nome que você quer já está em uso, tente adicionar números ou variações.

1.6 Copie o Token de Acesso

Após criar o bot, o BotFather envia uma mensagem com seu token de acesso HTTP API:

Done! Congratulations on your new bot. You will find it at t.me/seu_bot.

Use this token to access the HTTP API:
7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

For a description of the Bot API, see this page: https://core.telegram.org/bots/api

IMPORTANTE:

  • Copie esse token e guarde em local seguro
  • Nunca compartilhe publicamente (GitHub, fóruns, etc.)
  • Se vazar, gere um novo com /revoke no BotFather
Passo 2: Configurar o OpenClaw

Agora que você tem o bot criado, conecte-o ao OpenClaw.

2.1 Localize Seu Arquivo de Configuração

O arquivo principal de configuração do OpenClaw geralmente está em:

# Linux/Mac
~/clawd/openclaw.yaml
# ou
~/.config/openclaw/config.yaml

# Windows
C:\Users\SeuUsuario\clawd\openclaw.yaml
2.2 Adicione a Configuração do Telegram

Abra o arquivo em um editor de texto:

nano ~/clawd/openclaw.yaml

Adicione (ou modifique) a seção channels:

channels:
  telegram:
    enabled: true
    token: "7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"
2.3 Configuração Mínima Completa

Aqui está um exemplo de configuração básica funcional:

channels:
  telegram:
    enabled: true
    token: "SEU_TOKEN_AQUI"
    
    # Quem pode usar o bot (segurança)
    allowedUsers:
      - "seu_username_telegram"
2.4 Reinicie o OpenClaw

Para aplicar as mudanças:

openclaw gateway restart

Verifique se iniciou corretamente:

openclaw gateway status
Passo 3: Testar a Conexão3.1 Encontre Seu Bot

No Telegram, busque pelo username que você criou (ex: @assistente_joao_bot).

3.2 Inicie a Conversa

Clique em Start ou envie /start.

3.3 Teste com uma Mensagem

Envie qualquer mensagem:

Olá! Você está funcionando?

Se tudo estiver correto, o OpenClaw vai responder! 🎉

3.4 Verifique os Logs

Se não houver resposta, verifique os logs:

openclaw gateway logs

Procure por erros relacionados a Telegram ou ao token.

Configurações EssenciaisRestrição de Usuários

Por segurança, limite quem pode usar seu bot:

channels:
  telegram:
    # Por username (mais legível)
    allowedUsers:
      - "joao_silva"
      - "maria_souza"
    
    # Por ID numérico (mais seguro)
    allowedIds:
      - 123456789
      - 987654321

💡 Como descobrir seu ID: Envie uma mensagem para @userinfobot no Telegram.

Reações Automáticas

O OpenClaw pode reagir às suas mensagens com emojis:

channels:
  telegram:
    reactions:
      enabled: true
      mode: "minimal"  # minimal, moderate, full

Modos disponíveis:

  • minimal: Reage apenas em momentos importantes
  • moderate: Reações ocasionais durante a conversa
  • full: Reage a quase todas as mensagens
Botões Inline

Habilite botões interativos nas respostas:

channels:
  telegram:
    inlineButtons: true

Com isso ativado, o agente pode criar botões para ações rápidas, confirmações, e navegação.

Uso em Grupos

O OpenClaw pode participar de grupos no Telegram.

Configuração para Grupos
channels:
  telegram:
    allowGroups: true
    
    # Responder apenas quando mencionado
    replyOnMention: true
    
    # Ou responder sempre (cuidado com spam!)
    # replyOnMention: false
Adicionando o Bot ao Grupo
  1. Abra as configurações do grupo
  2. Clique em Add Members
  3. Busque pelo username do seu bot
  4. Adicione ao grupo
Melhores Práticas em Grupos
  • Sempre use replyOnMention: true — Evita que o bot responda a toda mensagem
  • Defina regras claras — Informe os membros sobre quando/como usar o bot
  • Monitore o uso — Verifique os logs para garantir que não há abuso
Configuração AvançadaWebhook vs Polling

Por padrão, o OpenClaw usa long polling — verifica periodicamente se há novas mensagens. É simples e funciona bem para uso pessoal.

Para produção com alto volume, configure webhook — o Telegram envia mensagens diretamente para seu servidor:

channels:
  telegram:
    webhook:
      enabled: true
      url: "https://seu-dominio.com/telegram/webhook"
      secret: "uma-chave-secreta-longa-e-aleatoria"

Requisitos para webhook:

  • Domínio próprio com HTTPS válido
  • Porta 443, 80, 88 ou 8443
  • IP público acessível
Configuração de Proxy

Se você está atrás de um firewall ou em região com restrições:

channels:
  telegram:
    proxy:
      enabled: true
      type: "socks5"  # ou "http"
      host: "proxy.exemplo.com"
      port: 1080
      username: "usuario"  # opcional
      password: "senha"    # opcional
Mensagens Silenciosas

Para enviar notificações sem som:

channels:
  telegram:
    defaultSilent: false  # Padrão: mensagens com som
    # Use true para modo silencioso por padrão
Comandos Disponíveis

O OpenClaw no Telegram suporta comandos especiais:

ComandoFunção
/startInicia conversa, mostra boas-vindas
/statusMostra status do agente e sessão
/helpLista comandos e funcionalidades
/reasoningAtiva/desativa modo de raciocínio visível
/verboseAtiva/desativa modo detalhado
/resetLimpa contexto da conversa atual
Comandos Personalizados

Você pode criar comandos customizados no BotFather:

  1. Envie /setcommands para o BotFather
  2. Selecione seu bot
  3. Envie a lista de comandos no formato:
start - Iniciar conversa
status - Ver status do agente
ajuda - Mostrar ajuda
TroubleshootingProblema: Bot Não Responde

Causas comuns:

  1. Token incorreto

    • Verifique se copiou o token completo
    • Gere um novo com /token no BotFather

  2. OpenClaw não está rodando

    • Execute openclaw gateway status
    • Reinicie com openclaw gateway restart

  3. Usuário não autorizado

    • Verifique allowedUsers ou allowedIds
    • Adicione seu username/ID à lista

  4. Firewall bloqueando

    • O OpenClaw precisa acessar api.telegram.org
    • Verifique regras de firewall
Problema: Erro “Unauthorized”

O token está incorreto ou foi revogado.

Solução:

  1. Vá ao BotFather
  2. Use /mybots para selecionar seu bot
  3. Clique em API Token e depois Revoke current token
  4. Copie o novo token e atualize seu openclaw.yaml
Problema: Respostas Lentas

Possíveis causas:

  1. Conexão com API do modelo — Verifique se Anthropic/OpenAI está respondendo
  2. Contexto muito grande — Reduza o histórico de mensagens
  3. Modelo pesado — Use um modelo mais leve para respostas rápidas

Solução temporária:

model:
  default: "claude-3-haiku"  # Modelo mais rápido
Problema: Bot Responde em Inglês

Configure o idioma no seu SOUL.md:

# SOUL.md

## Idioma
- Sempre responda em português brasileiro
- Use linguagem informal mas profissional
- Evite estrangeirismos quando houver equivalente em PT
Problema: Mensagens de Voz Não Funcionam

O processamento de voz requer configuração adicional:

transcription:
  enabled: true
  provider: "openai"  # usa Whisper API
  # ou
  provider: "local"   # usa Whisper local
Integração com Múltiplos Canais

O OpenClaw pode usar Telegram junto com outros canais:

channels:
  telegram:
    enabled: true
    token: "..."
  
  whatsapp:
    enabled: true
    # configuração do WhatsApp
  
  discord:
    enabled: true
    # configuração do Discord

Cada canal mantém sessões separadas, mas o agente compartilha:

  • Memória de longo prazo (MEMORY.md)
  • Personalidade (SOUL.md)
  • Skills e ferramentas
SegurançaProteja Seu Token
  • Nunca commite o token em repositórios públicos
  • Use variáveis de ambiente quando possível:
channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
  • Configure o .gitignore para ignorar arquivos de configuração sensíveis
Limite o Acesso
  • Use allowedUsers ou allowedIds em produção
  • Monitore logs regularmente
  • Revogue o token se suspeitar de comprometimento
Em Grupos
  • Use replyOnMention: true
  • Considere criar um grupo privado para testes
  • Não compartilhe informações sensíveis em grupos públicos
Próximos Passos

Agora que seu bot está funcionando:

  1. Personalizar SOUL.md — Defina a personalidade única do seu bot
  2. Configurar Memória — Ensine o bot a lembrar informações
  3. Criar Skills — Adicione novas habilidades e integrações
  4. Configurar Heartbeats — Faça o bot ser proativo
Recursos Externos

Encontrou um problema não listado aqui? Pergunte na nossa comunidade Discord — estamos sempre prontos para ajudar!

Última atualização: Fevereiro 2026