Canal Telegram do OpenClaw
Mensagens
Fácil
Conecte o OpenClaw ao Telegram usando o framework grammY Bot API. Crie um bot do Telegram via @BotFather, pegue o token, e seu assistente de IA estará ativo no Telegram em minutos. Usa long-polling por padrão com modo Webhook opcional. Um dos canais mais fáceis de configurar, com recursos ricos incluindo botões inline, stickers, reações e suporte a grupos.
Info rápida
DificuldadeFácil
CategoriaMensagens
Recursos suportados6 / 6
Telegram Recursos suportados
Mensagens de texto
Suportado
Mídia e arquivos
Suportado
Reações
Suportado
Threads
Suportado
Mensagens de voz
Suportado
Chat em grupo
Suportado
Telegram Pré-requisitos
- Uma conta do Telegram
- Um Token de Bot do @BotFather (envie /newbot para @BotFather)
- OpenClaw Gateway em execução e configurado
- Node.js 18+ instalado no seu servidor
Telegram Configuração rápida
1
Criar um bot com @BotFather
Abra o Telegram, procure por @BotFather e envie /newbot. Siga as instruções para nomear seu bot e obter o token da API. Guarde este token — você precisará dele para a configuração.
2
Adicionar configuração do canal Telegram
Adicione a configuração do canal Telegram em ~/.openclaw/openclaw.json. Cole o token do bot do @BotFather no campo botToken. Defina o dmPolicy (pairing, allowlist ou open) para controlar quem pode conversar com seu assistente.
3
Iniciar Gateway e testar
Inicie o processo Gateway. Procure seu bot no Telegram e envie uma mensagem. Se estiver usando a política pairing padrão, aprove o remetente com 'openclaw pairing approve telegram <code>'. O OpenClaw deve responder através do assistente de IA.
Telegram Exemplo de configuração
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram Documentação Detalhada
Visão geral da arquitetura
O OpenClaw se conecta ao Telegram através do framework grammY — uma biblioteca moderna e TypeScript-first para a Telegram Bot API. O bot usa long-polling por padrão, consultando periodicamente os servidores do Telegram para novas atualizações. Funciona imediatamente sem configuração adicional.
Você também pode mudar para o modo Webhook para implantações em produção. No modo Webhook, o Telegram envia as atualizações diretamente para o endpoint do seu servidor, sendo mais eficiente e com menor latência.
O long-polling funciona atrás de NATs e firewalls sem configuração. O modo Webhook requer um endpoint HTTPS acessível publicamente.
Armazene seu token de bot via variável de ambiente TELEGRAM_BOT_TOKEN ou na configuração em channels.telegram.botToken.
Criando seu bot com @BotFather
O BotFather é a ferramenta oficial do Telegram para criar e gerenciar bots. Passos:
1. Abra o Telegram e procure @BotFather
2. Envie /newbot para iniciar a criação
3. Escolha um nome de exibição (ex: "Meu Assistente IA")
4. Escolha um nome de usuário terminando em 'bot' (ex: "meu_assistente_ia_bot")
5. O BotFather retornará um token API — guarde em segurança
Após a criação, personalize com comandos do BotFather:
• /setdescription — Definir descrição do perfil
• /setabouttext — Definir texto "Sobre"
• /setuserpic — Enviar foto de perfil
• /setprivacy — Alternar modo privacidade para mensagens de grupo
Mantenha seu token em segredo. Qualquer pessoa com o token pode controlar seu bot. Se comprometido, use /revoke no BotFather para gerar um novo.
Políticas de DM
As políticas de DM (Mensagens Diretas) controlam quem pode interagir com seu assistente IA em chats privados. O OpenClaw suporta três políticas:
• pairing (padrão) — Novos usuários passam por um fluxo de pareamento. Enviam uma mensagem, recebem um código (válido por 1 hora) e você aprova ou recusa via CLI.
• allowlist — Apenas IDs de usuário numéricos listados em allowFrom podem contatar o bot. Os demais são ignorados.
• open — Qualquer pessoa que envie mensagem ao bot recebe resposta. Use com cautela em produção.
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}Para encontrar o ID numérico do Telegram de um usuário, use @userinfobot ou verifique os logs do Gateway quando enviarem uma mensagem.
Gerenciamento de grupos
O OpenClaw suporta grupos do Telegram com controle de acesso flexível via dois mecanismos independentes:
1. Lista de grupos permitidos — Todos os grupos ou apenas os listados em channels.telegram.groups.
2. Política de grupo — Controle de permissões de remetentes:
• open — Qualquer membro pode acionar o bot
• allowlist — Apenas remetentes aprovados
• disabled — Mensagens de grupo ignoradas
Por padrão, o bot requer @menção em grupos. Você pode mudar isso:
• Comando /activation always (apenas sessão)
• requireMention: false na config para efeito permanente
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}Para grupos estilo fórum (tópicos), o OpenClaw isola cada tópico pelo ID do thread e pode aplicar configurações específicas por tópico.
Para o bot ver todas as mensagens do grupo sem ser admin, desative o modo privacidade no BotFather (/setprivacy), depois remova e readicione o bot ao grupo.
Formatação e streaming de mensagens
O OpenClaw oferece várias opções de formatação e entrega:
Formatação: O texto de saída usa o parser HTML do Telegram com conversão automática de Markdown. Se o parsing HTML falhar, a mensagem é reenviada como texto simples.
Streaming: As bolhas de rascunho suportam streaming parcial de respostas em DMs. Dois modos:
• partial (padrão) — Atualizações progressivas de uma única mensagem
• block — Envio em blocos completos
O texto é dividido por padrão em 4.000 caracteres (limite do Telegram). Use chunkMode: "newline" para dividir por parágrafos.
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}Botões inline
O OpenClaw suporta os botões de teclado inline interativos do Telegram. Quando habilitados, a IA pode apresentar botões abaixo das mensagens. Ao clicar, os dados de callback são enviados ao agente.
Modos disponíveis:
• off — Botões desativados (padrão)
• dm — Apenas em chats privados
• group — Apenas em grupos
• all — Em todos os lugares
• allowlist — Restrito por autorização
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}Stickers e mídia
O OpenClaw lida com stickers e arquivos de mídia do Telegram:
Stickers: Stickers estáticos são baixados e processados por análise visual. Descrições são armazenadas em cache. Stickers animados e de vídeo são ignorados. O agente pode enviar stickers por ID de arquivo e buscar no cache.
Mídia: Limite de upload/download padrão de 5 MB. O bot suporta envio e recebimento de imagens, documentos, áudio e vídeo.
Ative a ação sticker na config do agente para permitir envio de stickers por ID de arquivo ou busca em cache.
Reações
O OpenClaw suporta o sistema de reações do Telegram para recebimento e envio de emojis:
Reações recebidas geram eventos do sistema:
• off — Sem notificações
• own — Apenas reações às mensagens do bot
• all — Todas as reações no chat
Nível de reação do bot:
• off — Sem reações
• ack — Reação de confirmação durante processamento (padrão)
• minimal — Reações básicas
• extensive — Gama completa de emojis
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}Comandos e ferramentas
Comandos nativos do bot (/status, /reset, etc.) são registrados automaticamente no menu de comandos do Telegram. Comandos personalizados podem ser adicionados mas funcionam apenas como entradas de menu.
O agente também suporta ações de ferramentas:
• Enviar mensagens para chats específicos
• Reagir com emojis
• Deletar mensagens
• Responder mensagens específicas com [[reply_to:<id>]]
Use [[reply_to_current]] na resposta do agente para responder diretamente à mensagem atual.
Inclua [[audio_as_voice]] nas respostas ou defina asVoice: true para forçar formato de nota de voz.
Modo Webhook
Para implantações em produção, o modo Webhook é recomendado ao invés do long-polling. O Telegram envia atualizações diretamente ao seu servidor, reduzindo latência e uso de recursos.
Defina webhookUrl e webhookSecret na configuração. O endpoint local vincula-se a 0.0.0.0:8787 por padrão.
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}Ao mudar de polling para Webhook, o Gateway registra automaticamente a URL do Webhook no Telegram ao iniciar.
O modo Webhook requer um endpoint HTTPS acessível publicamente. Certifique-se de que seu servidor tenha um certificado SSL válido.
Telegram Referência de Configuração
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Ativar ou desativar o canal Telegram |
| botToken | string | "" | Token Bot API do @BotFather. Também suporta variável env TELEGRAM_BOT_TOKEN |
| dmPolicy | string | "pairing" | Controle de acesso DM. Opções: pairing, allowlist, open |
| allowFrom | number[] | [] | IDs de usuário Telegram permitidos (quando dmPolicy é allowlist) |
| groupPolicy | string | "disabled" | Política de grupo. Opções: disabled, open, allowlist |
| groups | string[] | [] | Lista de IDs de grupos permitidos |
| requireMention | boolean | true | Exigir @menção em grupos |
| streamMode | string | "partial" | Modo streaming. Opções: partial, block |
| chunkMode | string | "split" | Divisão de respostas longas. Opções: split, newline |
| webhookUrl | string | "" | URL HTTPS para modo Webhook |
| webhookSecret | string | "" | Token secreto para verificação do Webhook |
| reactionNotifications | string | "off" | Notificações de reações. Opções: off, own, all |
| reactionLevel | string | "ack" | Capacidade de reação do bot. Opções: off, ack, minimal, extensive |
| capabilities.inlineButtons | string | "off" | Modo botões inline. Opções: off, dm, group, all, allowlist |
| configWrites | boolean | true | Migração automática de IDs ao atualizar para supergrupo |
enabled
Type: booleanDefault: true
Ativar ou desativar o canal Telegram
botToken
Type: stringDefault: ""
Token Bot API do @BotFather. Também suporta variável env TELEGRAM_BOT_TOKEN
dmPolicy
Type: stringDefault: "pairing"
Controle de acesso DM. Opções: pairing, allowlist, open
allowFrom
Type: number[]Default: []
IDs de usuário Telegram permitidos (quando dmPolicy é allowlist)
groupPolicy
Type: stringDefault: "disabled"
Política de grupo. Opções: disabled, open, allowlist
groups
Type: string[]Default: []
Lista de IDs de grupos permitidos
requireMention
Type: booleanDefault: true
Exigir @menção em grupos
streamMode
Type: stringDefault: "partial"
Modo streaming. Opções: partial, block
chunkMode
Type: stringDefault: "split"
Divisão de respostas longas. Opções: split, newline
webhookUrl
Type: stringDefault: ""
URL HTTPS para modo Webhook
webhookSecret
Type: stringDefault: ""
Token secreto para verificação do Webhook
reactionNotifications
Type: stringDefault: "off"
Notificações de reações. Opções: off, own, all
reactionLevel
Type: stringDefault: "ack"
Capacidade de reação do bot. Opções: off, ack, minimal, extensive
capabilities.inlineButtons
Type: stringDefault: "off"
Modo botões inline. Opções: off, dm, group, all, allowlist
configWrites
Type: booleanDefault: true
Migração automática de IDs ao atualizar para supergrupo
Telegram Perguntas Frequentes
Telegram Solução de Problemas
Bot ignora mensagens sem menção em grupos
O modo privacidade está ativado por padrão. O bot só recebe @menções e comandos com barra.
Desative o modo privacidade no BotFather (/setprivacy → Disable). Remova e readicione o bot ao grupo. Defina requireMention: false na config do OpenClaw.
Bot não responde a nenhuma mensagem
Token incorreto, Gateway não iniciado ou problema de rede.
Verifique o token: curl https://api.telegram.org/bot<token>/getMe. Consulte logs do Gateway. Para problemas IPv6, force resolução IPv4 para api.telegram.org.
Webhook não recebe atualizações
URL do Webhook inacessível, certificado SSL inválido ou Webhook não registrado.
Verifique acessibilidade da URL (curl). Valide o certificado SSL. Verifique status: curl https://api.telegram.org/bot<token>/getWebhookInfo. Reinicie o Gateway.
Mensagens truncadas ou divididas incorretamente
O Telegram tem limite de 4.096 caracteres. Respostas longas são divididas automaticamente.
Use chunkMode: 'newline' para dividir por parágrafos ao invés do limite de caracteres.