Integrações10 min de leitura

Guia Completo de Integracao do OpenClaw com Telegram

Aprenda como criar um bot do Telegram e conecta-lo ao OpenClaw. Tutorial completo cobrindo criacao do bot, configuracao, comandos e configuracao de chat em grupo.

OpenClaw Guides

Tutorial Authors

2025-02-04

Visao Geral

A integracao com o Telegram permite que voce interaja com o OpenClaw atraves de um bot dedicado do Telegram. O OpenClaw usa o framework grammY para long-polling por padrao, com suporte opcional a webhook para implantacoes em producao.

Pre-requisitos

OpenClaw instalado e em execucao
Uma conta do Telegram

Passo 1: Criar um Bot do Telegram

Converse com o BotFather

Abra o Telegram e procure por @BotFather
Inicie uma conversa e envie /newbot
Siga as instrucoes:

You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

Salve o token do bot — voce precisara dele no proximo passo.

Desativar o Modo de Privacidade (Recomendado para Grupos)

Se voce planeja usar o bot em chats de grupo, desative o modo de privacidade para que ele possa ler todas as mensagens:

/setprivacy
@myopenclaw_bot
Disable

Apos alterar o modo de privacidade, voce deve remover e readicionar o bot aos grupos existentes para que a alteracao tenha efeito. Alternativamente, promova o bot a administrador do grupo — bots administradores sempre recebem todas as mensagens.

Passo 2: Configurar o OpenClaw

Armazenamento do Token

Voce pode armazenar o token do bot de duas formas. A configuracao tem precedencia sobre a variavel de ambiente.

Opcao A — Variavel de ambiente:

bash

# Adicionar a ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Opcao B — Diretamente na configuracao:

json5

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Configuracao Minima

Edite ~/.openclaw/openclaw.json:

json5

{
  channels: {
    telegram: {
      // Token do env TELEGRAM_BOT_TOKEN ou defina botToken diretamente
    }
  }
}

Isso e tudo que voce precisa — o OpenClaw inicia o long-polling automaticamente quando um canal Telegram esta configurado.

Passo 3: Teste Seu Bot

Abra o Telegram e procure pelo nome de usuario do seu bot
Inicie uma conversa com /start
Envie qualquer mensagem para testar

Controle de Acesso — Politica de DM

Controle quem pode enviar mensagens ao seu bot em chats privados via dmPolicy:

| Politica | Comportamento | |----------|---------------| | "pairing" (padrao) | Remetentes desconhecidos recebem um codigo de pareamento com expiracao; voce aprova via CLI | | "allowlist" | Apenas IDs de usuario / @nomes de usuario em allowFrom podem enviar mensagens | | "open" | Qualquer pessoa pode enviar mensagens ao bot | | "disabled" | DMs sao desativadas completamente |

Modo de Pareamento (Padrao)

Quando um novo usuario envia uma mensagem ao bot, ele recebe um codigo de pareamento. Aprove-o com:

bash

# Listar solicitacoes de pareamento pendentes
openclaw pairing list telegram

# Aprovar um codigo especifico
openclaw pairing approve telegram <CODE>

Os codigos de pareamento expiram apos 1 hora.

Modo Allowlist

json5

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

Modo Open

json5

{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

Suporte a Chat em Grupo

Ativar Acesso a Grupos

Adicione IDs de grupo ao objeto groups. Use "*" para permitir todos os grupos:

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // grupo especifico com padroes
        "-1009876543210": {             // grupo especifico com substituicoes
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

Ou permita todos os grupos:

json5

{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

Politica de Grupo

Controle quem pode interagir com o bot dentro dos grupos:

| Configuracao | Descricao | |--------------|-----------| | groupPolicy: "open" | Qualquer membro do grupo pode enviar mensagens ao bot | | groupPolicy: "allowlist" | Apenas remetentes em groupAllowFrom podem interagir | | groupPolicy: "disabled" | O bot ignora todas as mensagens do grupo |

json5

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

Requisito de Mencao

Por padrao, o bot requer uma @mention nos grupos. Voce pode alterar isso por grupo:

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // bot responde a todas as mensagens
        }
      }
    }
  }
}

Ou use o comando de sessao /activation always no chat do grupo.

Substituicoes por Grupo

Cada entrada de grupo suporta estes campos:

| Campo | Descricao | |-------|-----------| | groupPolicy | Substituir a politica de grupo global | | requireMention | Se @mention e necessario | | skills | Skills disponiveis neste grupo | | allowFrom | Lista de permissoes de remetentes para este grupo | | systemPrompt | Prompt de sistema personalizado para este grupo | | enabled | Ativar/desativar para este grupo especifico |

Formato de Mensagem e Fragmentacao

Modo de Analise HTML

O OpenClaw envia mensagens usando o modo de analise HTML do Telegram (nao Markdown). O Markdown do LLM e automaticamente convertido para tags HTML seguras. Se o Telegram rejeitar o HTML, a mensagem e reenviada como texto simples.

Fragmentacao de Texto

Mensagens longas sao divididas em multiplas mensagens do Telegram:

json5

{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // max de caracteres por mensagem (padrao: 4000)
      chunkMode: "newline"     // "length" (padrao) ou "newline"
    }
  }
}

"length" — divide no limite de caracteres
"newline" — divide nos limites de paragrafo antes de aplicar o limite de tamanho

Tratamento de Midia

Limite de Tamanho de Midia

json5

{
  channels: {
    telegram: {
      mediaMaxMb: 5    // tamanho maximo do arquivo em MB (padrao: 5)
    }
  }
}

Stickers

Stickers estaticos (WEBP) sao processados pela visao e descritos para o LLM
Stickers animados / de video sao ignorados
As descricoes de stickers sao armazenadas em cache em ~/.openclaw/telegram/sticker-cache.json para evitar chamadas de visao redundantes

Para permitir que o bot envie stickers:

json5

{
  channels: {
    telegram: {
      actions: {
        sticker: true    // padrao: false
      }
    }
  }
}

Historico e Contexto

json5

{
  channels: {
    telegram: {
      historyLimit: 50,        // contexto do grupo (padrao: 50)
      dmHistoryLimit: 100      // contexto de DM
    }
  }
}

Substituicao de DM por usuario:

json5

{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

Defina como 0 para desativar o historico.

Streaming

O OpenClaw suporta streaming baseado em rascunho em chats privados (com topicos de forum ativados):

| Configuracao | Descricao | |--------------|-----------| | streamMode: "off" | Streaming desativado (padrao) | | streamMode: "partial" | Atualizacoes continuas em uma mensagem de rascunho | | streamMode: "block" | Atualizacoes em blocos em uma mensagem de rascunho |

Configuracoes do modo block:

json5

{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Modo Webhook (Producao)

Para implantacoes em producao, use webhooks em vez de long-polling:

json5

{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // caminho local, padrao: /telegram-webhook
    }
  }
}

O listener de webhook se vincula a 0.0.0.0:8787. Quando webhookUrl esta definido, o OpenClaw muda automaticamente de polling para modo webhook.

Comandos

Comandos Nativos

O OpenClaw registra estes comandos no menu do bot do Telegram na inicializacao:

| Comando | Descricao | |---------|-----------| | /start | Mensagem de boas-vindas | | /status | Mostrar status do bot | | /reset | Redefinir conversa | | /model | Mostrar / trocar modelo |

Comandos Personalizados

Adicione entradas de menu via configuracao (apenas menu — eles nao executam a menos que sejam tratados em outro lugar):

json5

{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

Nomes de comandos devem ser em minusculas a-z0-9_, de 1 a 32 caracteres. A / inicial e removida automaticamente. Nao e possivel substituir comandos nativos.

Botoes Inline

Controle a disponibilidade de botoes inline:

| Configuracao | Escopo | |--------------|--------| | capabilities.inlineButtons: "off" | Desativado | | capabilities.inlineButtons: "dm" | Apenas DMs | | capabilities.inlineButtons: "group" | Apenas grupos | | capabilities.inlineButtons: "all" | DMs e grupos | | capabilities.inlineButtons: "allowlist" | Ambos + filtragem de remetente (padrao) |

Rede e Proxy

json5

{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Timeout de requisicao da Bot API (padrao: 500)
      network: {
        autoSelectFamily: false   // desativar Happy Eyeballs (padrao no Node 22)
      },
      proxy: "socks5://127.0.0.1:1080"   // Proxy SOCKS/HTTP para a Bot API
    }
  }
}

Solucao de Problemas

Bot Nao Responde

Verifique se o token esta correto:

bash

curl "https://api.telegram.org/bot<TOKEN>/getMe"

Verifique os logs do OpenClaw:

bash

openclaw logs --follow

Mensagens Nao Chegam em Grupos

O modo de privacidade deve estar desativado (/setprivacy → Disable) ou o bot deve ser administrador
Teste com /activation always (apenas sessao); persista via requireMention: false na configuracao

Falhas de Roteamento IPv6

O bot pode parar de responder silenciosamente se o roteamento IPv6 falhar. Verifique o DNS para api.telegram.org:

bash

dig api.telegram.org AAAA

Corrija ativando a saida IPv6 ou forcando IPv4:

bash

# Add to /etc/hosts
149.154.167.220  api.telegram.org

Ou use a configuracao de rede:

json5

{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

Abortos de Long-Polling (Node 22+)

O Node 22 e mais rigoroso com instancias de AbortSignal. Atualize o OpenClaw para a versao mais recente ou faca downgrade para o Node 20.

Falhas em `setMyCommands`

O HTTPS/DNS de saida para api.telegram.org pode estar bloqueado. Verifique suas regras de firewall.

Melhores Praticas de Seguranca

Nunca compartilhe o token do seu bot — revogue imediatamente via BotFather se comprometido
Use pairing ou allowlist para controle de acesso em DMs
Defina politicas de grupo para controlar quem pode interagir nos grupos
Encontre IDs de usuario com seguranca via openclaw logs --follow ou o endpoint getUpdates da Bot API — evite bots de ID de terceiros
Use webhooks com um secret para implantacoes em producao

Visao Geral

Pre-requisitos

Passo 1: Criar um Bot do Telegram

Converse com o BotFather

Desativar o Modo de Privacidade (Recomendado para Grupos)

Passo 2: Configurar o OpenClaw

Armazenamento do Token

Configuracao Minima

Passo 3: Teste Seu Bot

Controle de Acesso — Politica de DM

Modo de Pareamento (Padrao)

Modo Allowlist

Modo Open

Suporte a Chat em Grupo

Ativar Acesso a Grupos

Politica de Grupo

Requisito de Mencao

Substituicoes por Grupo

Formato de Mensagem e Fragmentacao

Modo de Analise HTML

Fragmentacao de Texto

Tratamento de Midia

Limite de Tamanho de Midia

Stickers

Historico e Contexto

Streaming

Modo Webhook (Producao)

Comandos

Comandos Nativos

Comandos Personalizados

Botoes Inline

Rede e Proxy

Solucao de Problemas

Bot Nao Responde

Mensagens Nao Chegam em Grupos

Falhas de Roteamento IPv6

Abortos de Long-Polling (Node 22+)

Falhas em setMyCommands

Melhores Praticas de Seguranca

Proximos Passos

Falhas em `setMyCommands`