Como integrar o Telegram ao OpenClaw: do BotFather à configuração

Imagine poder fazer uma pergunta ao seu assistente de IA diretamente no Telegram, sem abrir o navegador, entrar em um site e esperar a página carregar. Com o OpenClaw e um Telegram Bot, você consegue fazer isso em cerca de meia hora. Não é necessário conhecer desenvolvimento backend nem dominar a configuração de servidores.

Este artigo mostra todo o processo: criar um Bot no BotFather, obter o Token, configurar o OpenClaw, restringir o acesso com uma lista de permissão e, por fim, iniciar e testar a conexão. Também reúne os erros que encontrei e uma lista prática de diagnóstico. O resultado é um assistente pessoal de IA disponível 24 horas por dia.

Uma forma barata de manter seu “lagostim”: ArkClaw deixa os AI Agents mais acessíveis

O OpenClaw, conhecido como “lagostim”, está em alta, mas sua configuração pode afastar muita gente. O ArkClaw, da Volcengine, da ByteDance, reduz bastante essa barreira. Sem lidar com servidor ou configuração de Token, você ganha com um clique um agente de IA disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O principal atrativo é o preço: a mensalidade custa apenas 9,9 yuans. Com meu código de convite ZLKUK54M (cadastre-se aqui), o valor cai para 8,9 yuans. Quem programa também pode assinar o Coding Plan Pro e usá-lo sem custo adicional.

Antes de começar: conceitos básicos que você precisa conhecer

Antes de colocar a mão na massa, vale entender alguns conceitos importantes. Não é teoria por teoria: esses pontos evitam bastante retrabalho.

Um Telegram Bot não é uma conta comum. Ele funciona mais como uma interface de resposta automática: recebe mensagens e envia respostas, mas não inicia uma conversa por conta própria. Pense em um bot de atendimento, que só responde depois que você faz uma pergunta.

Quem é o BotFather? É a “fábrica de Bots” oficial do Telegram. Todos os Bots são criados por meio dele. O próprio BotFather também é um Bot: você conversa com ele para criar e configurar o seu. Quando ouvi isso pela primeira vez, achei curioso usar um Bot para gerenciar outros Bots.

Qual é o papel do OpenClaw? Em termos simples, ele é a ponte entre o Telegram e um grande modelo de linguagem. O Telegram recebe a mensagem; o OpenClaw a encaminha para o Claude ou o GPT e envia a resposta da IA de volta ao Telegram. Você não precisa escrever código para montar esse fluxo.

Separe estes itens:

• Uma conta do Telegram
• Uma instalação do OpenClaw em execução. Se ainda não instalou, consulte a documentação oficial ou meu tutorial de instalação anterior
• Uma API Key de um modelo de IA. Pode ser Claude, GPT ou Gemini; uma opção com cota gratuita serve para os primeiros testes

Na prática, a preparação não é complicada. O OpenClaw aceita várias plataformas, como Telegram, WhatsApp e WeCom, além de diferentes modelos de IA. Depois da primeira configuração, trocar de modelo também é simples.

Etapa 1: crie seu Telegram Bot com o BotFather

Agora começa a configuração de fato. Abra o Telegram e pesquise @BotFather. Escolha a conta oficial com o selo azul de verificação: existem várias imitações.

O diálogo para criar o Bot é bem simples:

1. Envie o comando /newbot ao BotFather
2. Ele pedirá o nome de exibição do Bot. Escolha o que preferir, como “Meu assistente de IA”
3. Em seguida, defina o nome de usuário. Há duas regras: ele deve terminar em bot e ser único em todo o Telegram. Na minha primeira tentativa, AIAssistantBot já estava ocupado; precisei testar três ou quatro opções

Se aparecer a mensagem de que o nome de usuário já está em uso, acrescente números ou as iniciais do seu nome, como MyAwesomeAI2024Bot.

Obter o Bot Token é a parte mais importante. Depois que o Bot é criado, o BotFather envia uma sequência longa de caracteres, parecida com esta:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

Esse Token é tão importante quanto a chave da sua casa. Já vi uma pessoa enviar o Token por engano a um repositório público do GitHub; a cota foi consumida e o prejuízo chegou a centenas de yuans. Copie-o imediatamente para um gerenciador de senhas ou uma nota criptografada. Não o deixe no histórico de conversas nem em uma nota comum na nuvem.

Configurações opcionais, mas recomendadas:

• Use /setdescription para definir a descrição exibida quando alguém abre o Bot
• Use /setabouttext para preencher as informações “Sobre”
• Use /setuserpic para enviar uma imagem de perfil e deixar o Bot mais apresentável

Não se esqueça de obter seu ID de usuário do Telegram. Você precisará dele para configurar a lista de permissão. Pesquise @userinfobot no Telegram e envie /start. O Bot retornará um ID numérico, como 123456789. Guarde-o também.

Etapa 2: configure o canal do Telegram no OpenClaw

Com o Bot Token em mãos, o próximo passo é configurar o OpenClaw. Parece técnico, mas consiste basicamente em editar um arquivo JSON.

Localize o arquivo de configuração. Atualmente, em 2026, o diretório de estado padrão do OpenClaw costuma ser ~/.openclaw/, e o arquivo principal é openclaw.json. Confirme os nomes e a hierarquia dos campos do Telegram na documentação oficial do canal Telegram. Materiais antigos podem mencionar ~/.clawdbot/config/channels.json, caminho anterior à mudança de nome. Se ainda estiver usando o diretório antigo, migre-o seguindo as instruções de renomeação da série. Em uma implantação com Docker, confirme se o volume montado corresponde ao caminho definido por OPENCLAW_HOME ou ~/.openclaw.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

O trecho abaixo é um exemplo para facilitar o entendimento. Ele atende ao uso individual, autoriza explicitamente seu ID e evita a incerteza de depender apenas do pareamento. Os nomes reais dos campos e os valores padrão, como o uso comum de pairing nas mensagens privadas, devem seguir a documentação oficial e o arquivo gerado pelo assistente. Não copie estruturas de array desatualizadas:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789]
    }
  }
}

O que você precisa saber sobre os campos oficiais:

• botToken: o Token copiado do BotFather. Verifique se não há espaços nem quebras de linha extras
• dmPolicy / allowFrom: definem quem pode enviar mensagens privadas ao Bot. Para uso individual, allowlist com seu ID numérico costuma ser a opção mais simples. Se você mantiver o padrão oficial pairing, na primeira mensagem privada será necessário executar openclaw pairing approve telegram <CODE> no Gateway; consulte a documentação oficial
• enabled: ativa ou desativa o canal

Como editar o arquivo?

No Linux ou macOS:

nano ~/.openclaw/openclaw.json

Com Docker, entre no contêiner e edite o mesmo arquivo no diretório montado. O caminho dentro do contêiner depende do volume configurado no Compose.

docker exec -it openclaw sh
vi /root/.openclaw/openclaw.json

Outra opção é editar diretamente o arquivo no diretório montado do host.

Erros comuns:

• A sintaxe do JSON é rígida: não pode haver vírgula depois do último par de chave e valor
• Ao colar o Token, é fácil incluir aspas ou espaços extras; confira com atenção
• allowFrom é um array. Mesmo com apenas um usuário, mantenha o formato de array; consulte a documentação oficial sobre os formatos aceitos para o ID

Na primeira vez que configurei, deixei uma vírgula a mais. O OpenClaw não iniciou e levei um bom tempo examinando os logs até encontrar o problema. Uma ferramenta de validação de JSON, como o JSONLint on-line, ajuda a evitar esse tipo de erro.

Etapa 3: proteja seu Bot com uma lista de permissão

A lista de permissão é realmente importante. Imagine que o Bot Token vaze e qualquer pessoa no mundo possa consumir sua cota de IA. Um amigo passou por isso e gastou em três dias toda a cota mensal do Claude.

Por que restringir o acesso:

• Impede que desconhecidos consumam sua cota de IA, que custa dinheiro
• Evita o vazamento de informações sensíveis, já que suas conversas com a IA podem conter dados de trabalho
• Mantém os custos sob controle, especialmente com modelos caros, como o GPT-4

Como configurar a política de acesso? Lembra do ID obtido com @userinfobot? Na configuração oficial, um dos campos comuns para mensagens privadas é channels.telegram.allowFrom, usado em conjunto com dmPolicy.

Exemplo para um único usuário, com os campos dentro de channels.telegram:

"dmPolicy": "allowlist",
"allowFrom": [123456789]

Exemplo para vários usuários, como uma equipe:

"dmPolicy": "allowlist",
"allowFrom": [123456789, 987654321, 555555555]

Como obter o ID de outros usuários do Telegram:

1. Peça para a pessoa procurar @userinfobot no Telegram. O método recomendado oficialmente é conversar primeiro com seu Bot e ler o valor from.id nos logs com openclaw logs --follow
2. Envie o comando /start
3. Anote o ID numérico retornado
4. Adicione-o ao array allowFrom

Para uma equipe, mantenha um documento que associe os IDs aos nomes das pessoas autorizadas. Quando alguém sair, remova seu ID imediatamente da lista. É uma medida básica de segurança.

Sobre o modo Pairing, ou pareamento:

A política padrão para mensagens privadas do Telegram costuma ser pairing: no primeiro contato, é necessário executar openclaw pairing approve telegram <CODE> na máquina do Gateway. Se quiser permitir acesso apenas pelo ID do usuário, como neste tutorial, use dmPolicy: "allowlist" e preencha allowFrom explicitamente; consulte a documentação oficial.

Etapa 4: inicie o OpenClaw e teste a conexão

Com a configuração pronta, chegou a hora de verificar se o Bot funciona.

Inicie o Gateway:

Em uma instalação local, depois de executar openclaw onboard --install-daemon, você pode primeiro consultar openclaw gateway status:

openclaw gateway
# Ou use o serviço do sistema já instalado:
openclaw gateway start

Iniciar pelo código-fonte é uma situação menos comum. No uso cotidiano, prefira a Gateway CLI; não substitua os comandos oficiais por um npm start presumido.

Em uma implantação com Docker:

docker compose up -d

Verifique o status do serviço:

Depois de iniciar, consulte os logs para confirmar que o canal do Telegram foi carregado. Com Docker:

docker compose logs openclaw -f

Você deve encontrar mensagens parecidas com estas:

[INFO] Loading Telegram channel: telegram-main
[INFO] Telegram bot connected successfully
[INFO] Listening for messages...

Se aparecer um erro, não se preocupe. Anote a mensagem e use a lista de diagnóstico a seguir.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Teste a primeira conversa:

1. Pesquise no Telegram o nome de usuário do seu Bot, aquele que termina em bot
2. Toque no botão Start na parte inferior da conversa
3. Envie uma mensagem de teste, como “Olá” ou “Hi there”
4. Se tudo estiver correto, o Bot responderá com uma mensagem gerada pela IA em poucos segundos

Fiquei genuinamente animado quando vi a primeira resposta. A sensação é parecida com construir um robô e descobrir que ele realmente consegue conversar com você.

Se o Bot não responder, não reinstale tudo imediatamente. A lista abaixo resolve rapidamente cerca de 90% dos casos.

Lista de diagnóstico para problemas comuns

O Bot não responde ou a configuração não entra em vigor? Vamos investigar por etapas. Organizei em uma checklist os problemas que encontrei; seguindo a ordem, você provavelmente conseguirá resolvê-los.

Problema 1: o Bot não responde a nenhuma mensagem

É o caso mais comum e pode ter várias causas. Verifique nesta ordem:

• O serviço do OpenClaw está em execução? Confirme com docker ps ou ps aux | grep openclaw
• O Bot Token está correto? Verifique channels.telegram.botToken em ~/.openclaw/openclaw.json e confirme que não há espaços nem aspas extras
• Seu ID está em allowFrom, ao usar allowlist, ou o pairing foi concluído? Confirme o ID com @userinfobot ou pelo método oficial dos logs
• O JSON do arquivo de configuração é válido? Confira com a ferramenta on-line JSONLint
• A AI API Key ainda é válida e tem cota disponível? Consulte o saldo no painel do provedor de IA

Comandos úteis:

# Consulte os logs do OpenClaw
docker compose logs openclaw -f

# Valide o arquivo de configuração
cat ~/.openclaw/openclaw.json | jq .

Problema 2: erro “Unauthorized” ou “Forbidden”

Na maioria das vezes, esse erro está relacionado à lista de permissão. Confira:

• Com dmPolicy: "allowlist", seu ID de usuário do Telegram está em allowFrom? A documentação oficial também aceita formatos de string com prefixo
• Se estiver usando pairing, confirme que executou openclaw pairing approve telegram <CODE> no Gateway
• Depois de alterar a configuração, reinicie o serviço do OpenClaw

Problema 3: o Bot demora para responder

Uma resposta muito lenta pode ter estas causas:

• A API do modelo de IA está lenta, principalmente nos horários de pico
• Há um problema de rede entre o servidor e o provedor de IA
• Faltam recursos no servidor; verifique o uso de CPU e memória

Possíveis melhorias:

• Teste um modelo de IA com resposta mais rápida
• Se estiver usando GPT-4, experimente GPT-3.5 ou Claude 3 Haiku
• Aumente os recursos do servidor ou melhore a conexão de rede

Problema 4: as alterações no arquivo de configuração não entram em vigor

Isso também aconteceu comigo: passei um bom tempo ajustando a configuração, mas nada mudava porque eu tinha esquecido de reiniciar o serviço.

Solução:

docker compose restart
# Ou:
systemctl restart openclaw

Problema 5: como consultar o histórico de conversas do Bot

O OpenClaw salva as conversas localmente. Você pode:

• Consultar os arquivos de log no caminho padrão
• Usar a Control UI do OpenClaw, se estiver habilitada
• Consultar diretamente o banco de dados, como SQLite ou outro banco configurado

Problema 6: o que fazer se o Bot Token vazar

Se você enviar o Token por engano a um repositório público ou ele vazar de outra forma:

1. Use imediatamente o comando /revoke no BotFather para revogar o Token
2. Gere um novo Token com o comando /token
3. Atualize o arquivo de configuração do OpenClaw
4. Reinicie o serviço
5. Consulte o uso no provedor de IA para identificar possíveis abusos

Configurações avançadas, se você precisar

Os recursos básicos já resolvem a maior parte das necessidades. Ainda assim, o OpenClaw oferece opções avançadas para quem quiser ir além.

Configure uma mensagem de boas-vindas e um menu de comandos:

No BotFather, use /setcommands para definir o menu do Bot, por exemplo:

start - Iniciar conversa
help - Consultar ajuda
clear - Limpar histórico da conversa

Quando o usuário digitar /, verá esses comandos como sugestões.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Ative o modo de pareamento por mensagem privada:

Se quiser permitir o uso por várias pessoas sem manter manualmente uma lista de permissão, experimente o modo de código de pareamento:

"enableDmPairing": true

O OpenClaw gera um código de pareamento. Na primeira utilização, cada usuário informa esse código para ativar o acesso. É uma opção adequada quando você oferece o Bot como serviço a outras pessoas.

Atribua modelos de IA diferentes a usuários diferentes:

O OpenClaw permite atribuir modelos por usuário. Por exemplo, administradores podem usar GPT-4, enquanto usuários comuns usam GPT-3.5. Consulte a seção Multi-Model da documentação oficial do OpenClaw para ver a configuração.

Integre Skills do OpenClaw:

Skills são um dos recursos mais importantes do OpenClaw. Elas permitem que o assistente execute ações reais, como:

• Criar, ler e editar arquivos
• Executar comandos Shell
• Pesquisar na web
• Escrever e depurar código

Tenha cuidado ao habilitar Skills, principalmente a execução de comandos Shell, que envolve riscos de segurança maiores.

Configure a memória das conversas e respostas personalizadas:

O OpenClaw salva automaticamente o histórico das conversas. Você pode definir a extensão da memória, prompts personalizados e outros ajustes para adaptar o assistente ao seu modo de uso.

Não vou detalhar esses recursos avançados aqui. Consulte a documentação oficial do OpenClaw se quiser explorá-los.

Conclusão

O processo é mais simples do que parece. Criar o Bot no BotFather, obter o Token, configurar o OpenClaw, definir a lista de permissão e testar tudo leva cerca de meia hora.

Revise os pontos que mais causam erro:

• Proteja o Bot Token e nunca o envie a um repositório público
• A lista de permissão é essencial para a segurança; não pule essa etapa
• Respeite a sintaxe rígida do JSON, pois até uma vírgula extra impede a inicialização
• Reinicie o serviço depois de alterar a configuração

Se você seguiu o tutorial, agora deve ter um assistente de IA funcional no Telegram. Basta abrir o aplicativo e fazer uma pergunta, sem passar pelo navegador, pelo login de um site e pelo carregamento da página.

Próximos passos:

• Teste modelos de IA diferentes para descobrir qual combina melhor com suas necessidades
• Explore as Skills do OpenClaw para permitir que o assistente execute ações reais
• Se a experiência funcionar bem, libere o acesso para integrantes da equipe

Além do Telegram, o OpenClaw se conecta ao WhatsApp, ao WeCom e a outras plataformas. Depois de aprender essa configuração, você terá uma boa base para os demais canais.

Se surgir algum problema, retorne à lista de diagnóstico ou peça ajuda à comunidade do OpenClaw. Parte da graça dessas ferramentas está justamente em aprender algo novo sempre que você resolve um erro.

Agora, vá conversar com seu assistente de IA.