Como conectar o OpenClaw ao Telegram

Resposta curta. Crie um bot com o @BotFather no Telegram (/newbot) e copie o token dele. Dê o token ao OpenClaw e permita que apenas o seu próprio ID numérico de usuário do Telegram possa falar com ele. Na sua própria máquina isso é openclaw channels add --channel telegram --token <token> mais dmPolicy: "allowlist" com o seu ID em allowFrom. Na PlayNHost, você cola o token e o seu ID na página Agente, e reinicia.

Verificado em 6 de novembro de 2026, correto para o OpenClaw 2026.11.1.

Este guia usa a documentação do Telegram do OpenClaw e o painel da PlayNHost como ele funciona hoje. O Telegram já vem embutido no OpenClaw: não há plugin para instalar.

Passo 1: crie o bot e copie o token dele

1. No Telegram, abra uma conversa com o @BotFather. Confira se o nome de usuário é exatamente @BotFather.
2. Envie /newbot, escolha um nome de exibição e depois um nome de usuário que termine em bot.
3. O BotFather responde com o token, que se parece com 123456789:AAH.... Mantenha-o privado: quem tiver o token pode controlar o seu bot.

O BotFather também tem um web app (t.me/BotFather?startapp) que faz a mesma coisa com botões.

Use um bot em que nada mais esteja rodando. Se um OpenClaw antigo no seu notebook, ou qualquer outro programa, ainda usa o mesmo token, pare-o primeiro ou crie um bot novo.

Passo 2: descubra o seu ID de usuário do Telegram

A lista de permitidos do OpenClaw pede o seu ID de usuário numérico, não o seu @usuário, o seu número de telefone nem o ID do bot. As formas que a documentação do OpenClaw lista:

• Pelo próprio bot (sem terceiros). Enquanto o bot está no modo pairing, mande qualquer mensagem a ele. A resposta de pareamento inclui "Your Telegram user id" (o seu ID de usuário do Telegram). Na PlayNHost, esse é o caminho que sugerimos, veja abaixo.
• Pelo log do OpenClaw. Rode openclaw logs --follow, mande uma mensagem ao bot e leia senderUserId na entrada telegram pairing request.
• Pela API do próprio Telegram. Mande uma mensagem ao bot e depois abra https://api.telegram.org/bot<bot_token>/getUpdates e leia message.from.id.
• Um bot de terceiros como @userinfobot ou @getidsbot. A documentação do OpenClaw diz que isso é menos privado.

Passo 3 na PlayNHost: cole o token e o seu ID

Você precisa de uma chave de provedor de IA na mesma página. Sem ela, o Start para com "Your agent is not set up yet: it needs an API key from one AI provider and a Telegram or Discord bot token." (o seu agente ainda não está configurado: ele precisa de uma chave de API de um provedor de IA e de um token de bot do Telegram ou do Discord).

1. Abra o seu servidor em panel.playnhost.com, depois a aba Agente.
2. Em Provedor de IA, defina uma chave se ainda não o fez (veja qual chave de provedor de IA usar).
3. Em Apps de chat, aperte Definir em Token do bot do Telegram, cole o token do BotFather e aperte Salvar. O painel confere o formato; se você colar algo errado, aparece "That is not a valid telegram bot token." (esse não é um token de bot do Telegram válido). Depois de salvo, a linha mostra só os quatro últimos caracteres, e o token nunca é mostrado de novo.
4. Ainda não sabe o seu ID? Deixe IDs de usuário do Telegram vazio e aperte Iniciar. Quando o agente estiver no ar, o console mostra (em inglês):

   [PlayNHost] Your agent is running
   [PlayNHost] Telegram: nobody can message your agent yet. Send your bot any message: it answers with your Telegram user ID. Copy that ID, put it on the Agent page, then restart. Ignore the pairing code in its reply.

   Mande uma mensagem ao seu bot no Telegram. Ele responde uma vez com um código de pareamento e o seu ID de usuário do Telegram (o OpenClaw envia um código mais ou menos uma vez por hora para cada pessoa e ignora as mensagens entre um e outro). Copie o ID e ignore o código: na PlayNHost não há nada para aprovar. Esse passo não deixa ninguém entrar.
5. Em Quem pode falar com ele, digite o seu ID em IDs de usuário do Telegram e aperte Salvar. Vários IDs vão em uma linha, separados por vírgulas.
6. A página diz "As alterações valem na próxima vez que o seu agente iniciar." Aperte Reiniciar agora. O console então confirma:

   [PlayNHost] Telegram: only user 123456789 can message your agent.

7. Mande uma mensagem ao seu bot. O seu agente responde. Mensagens de qualquer outra conta do Telegram são ignoradas.

O que a PlayNHost configura por você

• Com IDs no painel Agente, os DMs do Telegram usam dmPolicy: "allowlist" com exatamente esses IDs, que é o que a documentação do OpenClaw recomenda para um bot com um único dono. Sem nenhum ID, usam pairing: desconhecidos recebem um código e são ignorados, e ninguém consegue aprová-los sem a linha de comando ou o painel de controle do OpenClaw, e um servidor da PlayNHost não oferece nenhum dos dois.
• Os IDs que você lista também passam a ser os donos de comandos do OpenClaw (commands.ownerAllowFrom), então os comandos exclusivos do dono funcionam para você desde a primeira mensagem.
• O token chega ao OpenClaw como TELEGRAM_BOT_TOKEN no ambiente dele. Um token gravado no arquivo de configurações do próprio OpenClaw teria prioridade sobre esse, então o início o remove do arquivo: o token do painel Agente é o que vale.
• Os grupos continuam fechados: o OpenClaw não admite nenhum grupo até que um seja adicionado às configurações dele, e uma configuração que deixe qualquer pessoa falar com o agente volta para os seus IDs no próximo início.

Passo 3 na sua própria máquina

1. Adicione o token:

   openclaw channels add --channel telegram --token <bot-token>

   ou defina TELEGRAM_BOT_TOKEN no ambiente do Gateway. Um token no arquivo de configuração tem prioridade sobre a variável de ambiente.
2. Permita só você mesmo em ~/.openclaw/openclaw.json:

   {
     channels: {
       telegram: {
         enabled: true,
         dmPolicy: "allowlist",
         allowFrom: ["123456789"],
       },
     },
     commands: {
       ownerAllowFrom: ["telegram:123456789"],
     },
   }

   A parte commands faz de você o dono para os comandos exclusivos do dono: o OpenClaw não faz isso para uma lista de permitidos escrita à mão. Uma allowlist com allowFrom vazio bloqueia todos os DMs e é rejeitada pela verificação de configuração do OpenClaw.
3. Ou mantenha o modo pairing padrão e aprove a si mesmo depois da sua primeira mensagem:

   openclaw pairing list telegram
   openclaw pairing approve telegram <CODE>

   Os códigos expiram em uma hora. O primeiro pareamento aprovado também faz de você o dono de comandos.
4. Confira o canal com openclaw channels status --probe.

Quando ele não responde

Quer o Discord também? Veja conectar o OpenClaw ao Discord. Ainda não configurou? Crie um servidor OpenClaw.

A PlayNHost não é afiliada à OpenClaw Foundation. O OpenClaw é um software de código aberto sob a licença MIT.