O poder do Telegram com o modo de tópicos do OpenClaw

O OpenClaw é um framework de agentes de IA de código aberto que automatiza tarefas em plataformas de mensagens como Slack, Discord, WhatsApp e Telegram. Um dos principais motivos do sucesso do OpenClaw é que ele transforma grandes modelos de linguagem em agentes — programas de software que podem rodar por horas ou dias, executar sequências complexas de ações e manter contexto em vários canais. O Telegram, com sua rica Bot API e suporte a discussões encadeadas, é uma escolha natural. No entanto, configurar o OpenClaw no Telegram e aproveitar o modo de tópicos não é óbvio para muitos novos usuários. Este artigo traz um tutorial passo a passo para conectar seu assistente ao Telegram, explica como o modo de tópicos funciona nos bastidores, oferece casos de uso reais e termina com dicas e orientações de solução de problemas. Todas as informações neste guia vêm da documentação oficial do OpenClaw e da experiência da comunidade.

Por que o Telegram?

O Telegram é popular porque oferece suporte a bots, chats em grupo, canais privados e tópicos no estilo fórum. A plataforma tem um limite generoso de tamanho de mensagem (4096 caracteres), upload de mídia, emojis de reação e teclados inline. Diferente de algumas plataformas de mensagens, a Bot API do Telegram é gratuita, estável e bem documentada. A camada de gateway do OpenClaw tem suporte de primeira classe ao Telegram; a integração está pronta para produção para DMs de bots e grupos e funciona por long polling ou webhooks. Em outras palavras, uma vez configurado corretamente, seu assistente vai enviar e receber mensagens de forma confiável sem precisar escrever nenhum código personalizado.

Configurando o OpenClaw com o Telegram

1. Crie seu bot e obtenha o token da API

Abra o Telegram e inicie uma conversa com o @BotFather oficial. Execute /newbot, escolha um nome e um nome de usuário e copie o token retornado. Você vai colar esse token na configuração do OpenClaw. Os bots do Telegram são gerenciados inteiramente pelo BotFather; você também pode usar /setprivacy e /setjoingroups para alternar o comportamento em grupos depois.

2. Configure o OpenClaw

Abra seu openclaw.json arquivo de configuração (normalmente em ~/.openclaw) e adicione uma telegram seção sob a channels chave:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

O botToken campo guarda o token que você recebeu do BotFather. O dmPolicy controla como seu assistente responde a mensagens diretas: pairing (padrão) significa que o bot só responde a DMs de usuários que você aprovar; open permite todos; allowlist restringe o acesso a uma lista específica de IDs de usuário; e disabled desativa o suporte a DMs. O requireMention flag é importante para grupos: quando definido como true, o bot só responde quando seu nome de usuário é mencionado, evitando responder a todas as mensagens de um chat de grupo movimentado.

3. Inicie o gateway e emparelhe sua conta

Depois de salvar a configuração, execute openclaw gateway para iniciar o gateway de mensagens. Em seguida, você precisa aprovar sua conta do Telegram gerando um código de emparelhamento e aprovando-o. Em outro terminal, execute openclaw pairing list telegram para ver as solicitações pendentes e depois aprove seu próprio ID de usuário usando openclaw pairing approve telegram <CODE>. Os códigos expiram após uma hora, então conclua esta etapa logo. Depois do emparelhamento, as mensagens da sua conta do Telegram serão encaminhadas para seu agente OpenClaw.

4. Adicione o bot a grupos e tópicos

Para permitir que seu assistente participe de chats em grupo ou tópicos de fórum, adicione-o aos grupos do Telegram desejados e atualize a channels.telegram.groups configuração. Por exemplo:

"channels": {
  "telegram": {
    "groups": {
      "-100123456789": { "requireMention": true },
      "*": { "requireMention": false }
    },
    "groupPolicy": "allowlist"
  }
}

Aqui, a * entrada serve como regra geral para qualquer grupo; requireMention: true garante que o assistente não faça spam no canal. Você também pode definir groupPolicy a open para permitir que o bot entre automaticamente em qualquer grupo que o convide, ou disabled para bloquear totalmente o uso em grupos. Depois de configurar os grupos, reinicie o gateway e adicione o bot novamente a cada grupo se você alterou as configurações de privacidade.

Entendendo o modo de tópicos

O Telegram introduziu tópicos de fórum em 2022, permitindo que grupos grandes dividam conversas em tópicos separados. O OpenClaw aproveita esse recurso anexando :topic:<threadId> às suas chaves de sessão internas. Isso significa que cada tópico tem seu próprio contexto de conversa; mensagens enviadas em um tópico não vazam para outro. Dois comportamentos importantes surgem desse design:

1. Isolamento de tópicos: Quando o assistente recebe uma mensagem com um message_thread_id, ele usa uma chave de sessão como telegram:<chatId>:topic:<threadId>. As respostas são enviadas de volta ao mesmo tópico. É assim que o agente mantém o contexto em longas discussões com vários ramos.
2. Tópico geral vs. específico: O Telegram trata o ID de tópico 1 como o tópico “geral” padrão. Ao enviar mensagens para o tópico 1, você deve omitir o message_thread_id na chamada da API; caso contrário, o Telegram rejeita. O OpenClaw lida com isso automaticamente ao enviar respostas.

O modo de tópicos não se limita a supergrupos de fórum. Em chats privados (DMs), o Telegram às vezes anexa um message_thread_id às respostas a mensagens mais antigas. O OpenClaw preserva esse ID e usa chaves de sessão cientes de tópicos, então seu histórico de conversa continua organizado mesmo em DMs.

Configuração do modo de resposta

Por padrão, o OpenClaw define channels.telegram.replyToMode a desativado, o que desativa o encadeamento implícito de respostas. Se você prefere que o assistente responda diretamente à mensagem que o acionou, defina replyToMode a first ou todos. Você também pode incluir tags explícitas como [[reply_to_current]] ou [[reply_to:<messageId>]] na resposta do seu agente. Essas tags instruem o gateway a encadear a resposta adequadamente.

Streaming e indicadores de digitação

O OpenClaw oferece suporte a respostas parciais em streaming no Telegram. Com channels.telegram.streaming definido como partial ou progress, o gateway envia uma mensagem temporária e a edita conforme o modelo gera texto. Isso proporciona uma experiência melhor em respostas longas. Você pode até ativar a saída de raciocínio em tempo real pelo /reasoning stream comando durante uma conversa. Os indicadores de digitação são enviados automaticamente, inclusive em tópicos; no entanto, para o ID de tópico 1 (tópico geral), o Telegram ignora message_thread_id na ação de digitação.

Reações, figurinhas e comandos inline

A Bot API do Telegram oferece suporte a reações em mensagens, figurinhas e botões inline. O OpenClaw expõe esses recursos por meio de seu sistema de ações:

• Reações: O react ação permite que o agente reaja a uma mensagem com um emoji. As notificações de reação podem ser configuradas via channels.telegram.reactionNotifications e reactionLevel, permitindo notificações para mensagens do bot, todas as mensagens ou nenhuma. Observe que o Telegram não fornece IDs de tópico para reações, então elas sempre são encaminhadas para o tópico principal.
• Figurinhas: Ative as ações de figurinhas definindo channels.telegram.actions.sticker: true. As figurinhas são armazenadas em cache localmente; você pode pesquisar o cache com a sticker-search ação e enviar uma figurinha com sticker.
• Botões inline: Configure o channels.telegram.capabilities.inlineButtons para definir quando os teclados inline são permitidos (off, dm, group, all ou allowlist). Depois, você pode enviar uma mensagem com botões incluindo um buttons array no corpo da ação.

Casos de uso do modo de tópicos

O modo de tópicos libera fluxos de trabalho poderosos que, de outra forma, seriam confusos ou impossíveis em um único chat. Veja alguns cenários práticos:

1. Coordenação de vários projetos

Imagine que você gerencia vários projetos ao mesmo tempo. Crie um único supergrupo no Telegram e ative os tópicos de fórum. Para cada projeto, crie um tópico dedicado (por exemplo, Redesign do site, Campanha de marketing, Correções de bugs). Quando você envia uma mensagem ao seu assistente dentro de um tópico, o OpenClaw usa automaticamente uma chave de sessão exclusiva para aquele tópico. Isso mantém o contexto da conversa separado, então quando você pergunta sobre “o prazo”, o assistente sabe a qual projeto você se refere.

2. Tópicos paralelos privados em chats de grupo

Em um chat movimentado de família ou equipe, você pode querer fazer uma pergunta ao assistente sem interromper a discussão principal. Responda à sua mensagem anterior ou mencione o bot em uma resposta; o Telegram anexa um message_thread_id, fazendo o OpenClaw encaminhar a conversa para um tópico vinculado àquela mensagem. Agora você pode fazer perguntas de acompanhamento como “Qual é a minha lista de tarefas?” ou “Resuma as mensagens de hoje” sem encher o chat principal.

3. Tarefas de longa duração

Algumas tarefas levam tempo: resumir um documento longo, gerar um relatório ou executar um script. Iniciar essas tarefas em um tópico mantém as atualizações de progresso organizadas. Defina channels.telegram.streaming a progress para que o assistente envie uma mensagem de prévia e a edite até o resultado final ficar pronto. Se você tiver várias tarefas longas, cada tópico permanece isolado, evitando interferência entre elas.

4. Sessões de brainstorming

Os tópicos de fórum podem funcionar como salas de brainstorming. Por exemplo, abra um tópico chamado Ideias para o blog e faça brainstorming de ideias de artigos com seu agente. O assistente manterá o contexto sobre as sugestões anteriores dentro do tópico, facilitando refinar e expandir ideias. Enquanto isso, seu chat geral continua limpo.

5. Suporte ao cliente ou FAQ

Se você administra um chat de comunidade, pode criar tópicos para diferentes dúvidas de suporte. Os usuários fazem perguntas em seus próprios tópicos, e seu agente OpenClaw responde com informações personalizadas. Como as chaves de sessão são específicas de cada tópico, o agente não vai misturar respostas. Você pode até delegar tarefas: o agente pode abrir issues no GitHub ou criar eventos de calendário como ações de acompanhamento.

Solução de problemas e dicas

Modo de privacidade: Os bots do Telegram usam o modo de privacidade por padrão, o que significa que só veem mensagens que começam com / comandos ou que os mencionem. Se você precisa de visibilidade total das mensagens em um grupo, desative a privacidade via /setprivacy ou torne o bot um administrador. Lembre-se de remover e adicionar o bot novamente para que as mudanças tenham efeito.

Limites de histórico: O OpenClaw armazena um histórico limitado por chat ou tópico (50 mensagens por padrão para grupos, configurável via channels.telegram.historyLimit). Aumente esse limite se seu agente precisar de mais contexto, mas fique atento ao uso de memória.

Webhook vs long polling: Por padrão, o OpenClaw usa long polling, que é mais fácil de configurar. Se você quiser usar webhooks (por exemplo, para reduzir a latência), defina channels.telegram.webhookUrl e webhookSecret. Consulte a documentação para opções de porta e host.

Tags explícitas de resposta: Uso [[reply_to_current]] ou [[reply_to:<id>]] nas respostas do seu agente quando você precisa de controle refinado sobre os destinos das respostas. Isso é especialmente útil para bots que monitoram vários tópicos ao mesmo tempo.

Gerenciando acesso: Uso channels.telegram.allowFrom e groupPolicy para restringir quem pode falar com seu bot e em quais grupos ele pode entrar. Isso evita spam e comandos não autorizados.

Conclusão

O Telegram é uma das plataformas mais versáteis para rodar um agente OpenClaw. Entendendo como o modo de tópicos funciona e configurando grupos e DMs corretamente, você pode criar conversas ricas e com múltiplos contextos que permanecem organizadas. Use tópicos para separar projetos, executar tarefas longas, facilitar brainstorming ou oferecer suporte ao cliente. Aproveite recursos como prévias em streaming, botões inline e notificações de reação para criar uma experiência envolvente. Com a configuração certa, seu assistente OpenClaw vai parecer um participante natural da sua comunidade no Telegram.