Configuração do Telegram no OpenClaw

Um bot do Telegram é o canal mais rápido de colocar no ar, porque toda a configuração se resume a um token do BotFather e a um comando que o armazena. Veja a configuração rápida passo a passo, as regras de precedência de tokens, os ajustes que ficam do lado do Telegram, e não na configuração, e a escolha de transporte entre long polling e webhook.

Configuração rápida

• Os dois fluxos do BotFather terminam com um token que você cola no OpenClaw: o fluxo por chat, em que você conversa com a conta BotFather, confirma que o nome de usuário está exato, executa o comando de novo bot e salva o token, ou o fluxo web, no app web do BotFather, que roda em todos os clientes do Telegram e permite criar o bot em uma interface e copiar o token.
• A forma mais rápida de configurar é o comando channels add com o canal Telegram e o token, que grava o token na configuração para você; editar à mão significa, em vez disso, um bloco Telegram com o canal ativado, o token do bot, a política de DM pairing e uma entrada de grupo curinga que exige menção, e a variável de ambiente do token do bot é um fallback apenas para a conta padrão, já que contas nomeadas precisam usar a chave de token ou um arquivo de token.
• Com a recarga a quente padrão, o gateway em execução aplica a nova configuração do canal, e a verificação channels status confere se o Telegram está pronto; se o gateway estiver offline, você o inicia como serviço gerenciado ou no terminal, e um ambiente de serviço alterado precisa de um reinício para ser carregado.
• Enviar qualquer mensagem ao bot cria a solicitação de pareamento que o comando pairing list mostra e o comando approve aceita, com códigos que expiram após uma hora; adicionar o bot a um grupo exige então o seu ID numérico de usuário para as listas de permissões e o ID do chat do grupo como chave no mapa groups, lido nos logs, em um bot que mostra IDs de mensagens encaminhadas ou nas atualizações da Bot API e confirmado com o comando whoami quando o grupo estiver permitido, e IDs negativos de supergrupo vão em groups, nunca na lista de remetentes do grupo.

O Telegram não usa openclaw channels login telegram.

Tokens e o lado do Telegram

A resolução de tokens considera a conta: um arquivo de token tem prioridade sobre a chave de token do bot, a chave de token do bot tem prioridade sobre o ambiente, a configuração sempre vence a variável de ambiente, que só é resolvida para a conta padrão, e, depois de uma inicialização bem-sucedida, o OpenClaw guarda em cache a identidade do bot por até 24 horas, para que os reinícios evitem uma chamada getMe extra; um token alterado ou removido limpa esse cache. Do lado do Telegram, os bots vêm com o modo de privacidade ativado por padrão, o que limita quais mensagens de grupo eles recebem; para ver todas as mensagens do grupo, você desativa o modo de privacidade com o comando set-privacy ou torna o bot admin do grupo, e, depois de alternar o modo de privacidade, remove e adiciona de novo o bot em cada grupo para que o Telegram aplique a mudança. O status de admin é controlado nas configurações do grupo, e bots admins recebem todas as mensagens do grupo, o que combina com um comportamento de grupo sempre ativo. As opções úteis do BotFather são a configuração de entrada em grupos, que permite ou nega adições a grupos, e a configuração de privacidade para a visibilidade em grupos, ambas também disponíveis no app web do BotFather.

Long polling ou webhook

• Long polling é o padrão; o modo webhook exige uma URL de webhook e um segredo de webhook, com um caminho opcional que por padrão é a rota telegram-webhook, um host que por padrão é o loopback, uma porta que por padrão é 8787 e um caminho de certificado para um PEM autoassinado em configurações com IP direto ou sem domínio; o listener reserva a rota health para health checks, então o caminho do webhook precisa usar outra rota, e uma configuração existente nessa rota precisa mudar, atualizar a URL e o mapeamento do proxy reverso e verificar a mudança do listener com a verificação de status.
• No modo long polling, o OpenClaw salva sua posição de reinício depois que uma atualização é registrada na fila durável de entrada, então um handler que falhou continua podendo ser tentado de novo a partir dessa fila; o listener local escuta no loopback na porta 8787 por padrão, e entrada pública significa um proxy reverso na frente dele ou um host curinga definido de propósito.
• O modo webhook valida as proteções da requisição, o token secreto do Telegram e o corpo JSON, registra a atualização na fila durável antes de devolver um 200 vazio e marca a adoção durável bem-sucedida com um cabeçalho de entrega aceita que as respostas de health, roteamento, autenticação, validação e erro de armazenamento omitem, para que um proxy reverso possa exigi-lo em vez de deduzir a aceitação pelo tempo de resposta; depois da gravação durável, as atualizações são reivindicadas e processadas pelo escoamento central de entrada, com faixas por chat e por tópico, e turnos lentos do agente nunca seguram a confirmação de entrega do Telegram.

O OpenClaw no Telegram é o post do canal ao qual esta configuração pertence, e o controle de acesso do OpenClaw no Telegram, o que decidir em seguida sobre quem pode falar com o bot.

Onde as configurações dão errado

Quase toda configuração de Telegram que falha se resume a uma de três coisas: um token colado para uma conta nomeada pela variável de ambiente que só serve à conta padrão, um ID de grupo colocado na lista de remetentes em vez de no mapa groups, ou o modo de privacidade deixado ativado com a exigência de menção desligada. O guia de solução de problemas do Telegram no OpenClaw percorre esses sintomas em ordem, e conectar seu primeiro canal em cinco minutos é o passo a passo para um primeiro canal.

Na Diali

Na Diali, o canal Telegram é conectado pelo painel, e a configuração de execução é gerada a partir dele e substituída a cada nova versão, então as etapas do BotFather no início deste post são a parte que continua do seu lado. O Telegram na Diali descreve o canal na Diali, e a página de segurança da Diali, a fronteira que todo canal conectado compartilha.

• Um token do BotFather; a CLI o grava para você.
• Códigos de pareamento expiram após uma hora; IDs de grupo vão em groups.
• Long polling por padrão; webhooks exigem um segredo e uma rota livre.