--- title: "Telegram — Guia Completo de Integração com OpenClaw 2026" url: "https://openclaw.ia.br/integracoes/telegram/" markdown_url: "https://openclaw.ia.br/integracoes/telegram.MD" description: "Tutorial completo para configurar OpenClaw no Telegram. Crie seu bot, configure grupos, botões inline, webhooks, e resolva problemas comuns. Passo a passo em português." date: "2026-02-02" author: "" --- # Telegram — Guia Completo de Integração com OpenClaw 2026 Tutorial completo para configurar OpenClaw no Telegram. Crie seu bot, configure grupos, botões inline, webhooks, e resolva problemas comuns. Passo a passo em português. # 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: | Recurso | Telegram | WhatsApp | Discord | |---------|----------|----------|---------| | Setup | 5 minutos | 20+ minutos | 10 minutos | | Custo | Gratuito | API paga | Gratuito | | Grupos | ✅ Nativo | ✅ Limitado | ✅ Servers | | Bots | ✅ API oficial | ⚠ Não oficial | ✅ API oficial | | Arquivos | Até 2GB | Até 100MB | Até 100MB | | Reações | ✅ Completo | ✅ Básico | ✅ Completo | | Botões inline | ✅ Nativo | ❌ Não suporta | ✅ Componentes | | Rate limits | Generoso | Restritivo | Moderado | ### 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: ```bash # 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: ```bash nano ~/clawd/openclaw.yaml ``` Adicione (ou modifique) a seção `channels`: ```yaml channels: telegram: enabled: true token: "7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw" ``` ### 2.3 Configuração Mínima Completa Aqui está um exemplo de configuração básica funcional: ```yaml 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: ```bash openclaw gateway restart ``` Verifique se iniciou corretamente: ```bash openclaw gateway status ``` --- ## Passo 3: Testar a Conexão ### 3.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: ```bash openclaw gateway logs ``` Procure por erros relacionados a Telegram ou ao token. --- ## Configurações Essenciais ### Restrição de Usuários Por segurança, limite quem pode usar seu bot: ```yaml 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: ```yaml 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: ```yaml 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 ```yaml 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çada ### Webhook 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: ```yaml 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: ```yaml 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: ```yaml 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: | Comando | Função | |---------|--------| | `/start` | Inicia conversa, mostra boas-vindas | | `/status` | Mostra status do agente e sessão | | `/help` | Lista comandos e funcionalidades | | `/reasoning` | Ativa/desativa modo de raciocínio visível | | `/verbose` | Ativa/desativa modo detalhado | | `/reset` | Limpa 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 ``` --- ## Troubleshooting ### Problema: 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:** ```yaml model: default: "claude-3-haiku" # Modelo mais rápido ``` ### Problema: Bot Responde em Inglês Configure o idioma no seu SOUL.md: ```markdown # 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: ```yaml 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: ```yaml 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ça ### Proteja Seu Token - **Nunca** commite o token em repositórios públicos - Use variáveis de ambiente quando possível: ```yaml 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](/tutoriais/personalizar-soul/)** — Defina a personalidade única do seu bot 2. **[Configurar Memória](/tutoriais/configurar-memoria/)** — Ensine o bot a lembrar informações 3. **[Criar Skills](/tutoriais/criar-skills/)** — Adicione novas habilidades e integrações 4. **[Configurar Heartbeats](/tutoriais/heartbeats/)** — Faça o bot ser proativo --- ## Recursos Externos - [Documentação oficial do Telegram Bot API](https://core.telegram.org/bots/api) - [BotFather no Telegram](https://t.me/BotFather) - [Comunidade OpenClaw no Discord](https://discord.gg/clawd) - [GitHub do OpenClaw](https://github.com/openclaw/openclaw) --- *Encontrou um problema não listado aqui? Pergunte na nossa [comunidade Discord](https://discord.gg/clawd) — estamos sempre prontos para ajudar!* --- *Última atualização: Fevereiro 2026*