Como conectar seu agente de IA ao Telegram (guia completo de configuração)

Por que Telegram?

O Telegram é o canal recomendado para seu agente OpenClaw por várias razões. Possui uma API de Bot madura e bem documentada, funciona em todas as plataformas (iOS, Android, desktop, web), suporta formatação de mensagens, compartilhamento de arquivos e teclados inline, e a criação de bots é completamente gratuita sem processo de aprovação.

Mais importante: as mensagens do Telegram entre você e seu bot são privadas. OpenClaw se comunica com os servidores do Telegram para entregar suas mensagens, mas o modelo de IA só processa o que você envia — seu histórico de conversas fica no seu VPS.

Passo 1: criar seu bot no Telegram

Abra o Telegram e procure por @BotFather — o serviço oficial de criação de bots do Telegram. Inicie uma conversa e envie:

/newbot

O BotFather pedirá:

1. Um nome para seu bot — este é o nome de exibição que as pessoas veem (ex.: "Meu Assistente IA")
2. Um nome de usuário — deve terminar com "bot" (ex.: "meuassistente_bot")

Após confirmar os dois, o BotFather envia um token de bot — uma string longa como 1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ. Copie e salve imediatamente.

Passo 2: configurar a privacidade do bot

Por padrão, bots em grupos recebem todas as mensagens. Para um agente pessoal, convém mantê-lo focado. No BotFather:

/setprivacy

Selecione seu bot e escolha Enable. Isso significa que seu bot só recebe mensagens direcionadas a ele (começando com / ou mencionando-o). Para uso pessoal em mensagens diretas, essa configuração não muda nada, mas é uma boa prática.

Considere também definir uma descrição e foto de perfil:

/setdescription
/setuserpic

Passo 3: obter seu ID de usuário do Telegram

OpenClaw precisa saber qual conta do Telegram está autorizada a interagir com seu agente — você não quer que qualquer pessoa envie mensagens para sua IA pessoal. Para obter seu ID de usuário, abra uma conversa com @userinfobot e envie /start. Ele responde com seu ID numérico de usuário.

Anote isso. Durante a instalação do k-claw, você fornecerá esse ID como usuário autorizado.

Passo 4: instalar OpenClaw via k-claw

Com seu token de bot e ID de usuário prontos, execute o instalador do k-claw no seu VPS:

curl -fsSL https://claw.krokanti.com/install | bash

Quando o instalador perguntar sobre seu canal de mensagens, selecione Telegram. Ele solicitará:

• Seu token de bot (do BotFather)
• Seu ID de usuário do Telegram (do @userinfobot)
• Sua chave de API de IA
• O modelo de IA que você quer usar

O instalador configura OpenClaw, define o serviço systemd e inicia seu agente automaticamente.

Passo 5: começar a conversar

Abra o Telegram e procure seu bot pelo nome de usuário. Envie /start para inicializá-lo, depois pergunte qualquer coisa:

Qual é a capital da Austrália?
Resuma os pontos principais do último e-mail que compartilhei com você.
Me lembre amanhã às 9h de revisar a proposta do projeto.

Seu agente responde diretamente no chat, com o modelo de IA processando cada mensagem via API e o histórico de conversas armazenado de forma privada no seu VPS.

Comandos úteis do bot

OpenClaw vem com vários comandos integrados que você pode configurar no BotFather para uma melhor experiência de usuário:

/setcommands

Depois cole:

start - Inicializar o agente
help - Mostrar comandos disponíveis
memory - Mostrar o que o agente lembra
clear - Limpar o contexto da conversa
status - Verificar o status do agente

Solução de problemas

Problemas comuns após a configuração:

• Bot não responde: Verifique o serviço systemd — systemctl status kclaw-agent. Procure por erros nos logs com journalctl -u kclaw-agent -n 50.
• Erro de token inválido: Certifique-se de ter copiado o token completo do BotFather sem espaços extras.
• Erro de usuário não autorizado: Verifique se seu ID de usuário do Telegram corresponde ao fornecido durante a instalação. IDs são apenas numéricos.
• Limites de taxa da API: Se você estiver enviando muitas mensagens rapidamente, a API de IA pode limitar as requisições. OpenClaw lida com tentativas automáticas, mas os tempos de resposta podem diminuir temporariamente.

O painel do k-claw mostra o status da sua instalação e logs em tempo real, tornando mais fácil diagnosticar qualquer problema sem precisar acessar seu servidor via SSH.