Skip to Content
Guia do UsuárioRecursosCanaisTelegram

Telegram

Este guia aborda a configuração de um canal do Qwen Code no Telegram.

Pré-requisitos

  • Uma conta do Telegram
  • Um token de bot do Telegram (veja abaixo)

Criando um Bot

  1. Abra o Telegram e procure por @BotFather 
  2. Envie /newbot e siga as instruções para escolher um nome e um username
  3. O BotFather fornecerá um token do bot — guarde-o com segurança

Encontrando Seu User ID

Para usar senderPolicy: "allowlist" ou "pairing", você precisa do seu user ID do Telegram (um ID numérico, não seu username).

A maneira mais fácil de encontrá-lo:

  1. Procure por @userinfobot  no Telegram
  2. Envie qualquer mensagem — ele responderá com seu user ID

Configuração

Adicione o canal ao ~/.qwen/settings.json:

{
  "channels": {
    "my-telegram": {
      "type": "telegram",
      "token": "$TELEGRAM_BOT_TOKEN",
      "senderPolicy": "allowlist",
      "allowedUsers": ["YOUR_USER_ID"],
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "instructions": "You are a concise coding assistant responding via Telegram. Keep responses short.",
      "groupPolicy": "disabled",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Defina o token do bot como uma variável de ambiente:

export TELEGRAM_BOT_TOKEN=<seu-token-do-botfather>

Ou adicione-o a um arquivo .env que seja carregado antes da execução.

Executando

# Start only the Telegram channel
qwen channel start my-telegram
 
# Or start all configured channels together
qwen channel start

Em seguida, abra seu bot no Telegram e envie uma mensagem. Você verá “Working…” aparecer imediatamente, seguido pela resposta do agente.

Conversas em Grupo

Para usar o bot em grupos do Telegram:

  1. Defina groupPolicy como "allowlist" ou "open" na configuração do seu canal
  2. Desative o modo de privacidade no BotFather: /mybots → selecione seu bot → Bot Settings → Group Privacy → Turn Off
  3. Adicione o bot a um grupo. Se ele já estiver no grupo, remova e adicione-o novamente (o Telegram armazena em cache as configurações de privacidade do momento em que o bot entrou)
  4. Se estiver usando groupPolicy: "allowlist", adicione o chat ID do grupo a groups na sua configuração

Por padrão, o bot exige uma @menção ou uma resposta para responder em grupos. Defina "requireMention": false para um grupo específico para que ele responda a todas as mensagens (útil para grupos de tarefas dedicados). Veja Conversas em Grupo para detalhes completos.

Imagens e Arquivos

Você pode enviar fotos e documentos para o bot, não apenas texto.

Fotos: Envie uma foto e o agente a analisará usando suas capacidades de visão. Isso requer um modelo multimodal — adicione "model": "qwen3.5-plus" (ou outro modelo com capacidade de visão) à configuração do seu canal. As legendas das fotos são passadas como o texto da mensagem.

Documentos: Envie um PDF, arquivo de código ou qualquer documento. O bot faz o download e o salva localmente para que o agente possa lê-lo com suas ferramentas de arquivo. Isso funciona com qualquer modelo. O limite de tamanho de arquivo do Telegram é de 20MB.

Dicas

  • Mantenha as instruções concisas e focadas — O Telegram tem um limite de 4096 caracteres por mensagem. Adicionar instruções como “mantenha as respostas curtas” ajuda o agente a permanecer dentro dos limites.
  • Use sessionScope: "user" — Isso dá a cada usuário sua própria conversa. Use /clear para recomeçar.
  • Restrinja o acesso — Use senderPolicy: "allowlist" para um conjunto fixo de usuários, ou "pairing" para permitir que novos usuários solicitem acesso com um código que você aprova via CLI. Veja DM Pairing para detalhes.

Formatação de Mensagens

As respostas em markdown do agente são automaticamente convertidas para HTML compatível com o Telegram. Blocos de código, negrito, itálico, links e listas são suportados.

Solução de Problemas

O bot não responde

  • Verifique se o token do bot está correto e se a variável de ambiente está definida
  • Verifique se seu user ID está em allowedUsers se estiver usando senderPolicy: "allowlist", ou se você foi aprovado se estiver usando "pairing"
  • Verifique a saída do terminal em busca de erros

O bot não responde em grupos

  • Verifique se groupPolicy está definido como "allowlist" ou "open" (o padrão é "disabled")
  • Se estiver usando "allowlist", verifique se o chat ID do grupo está na configuração groups
  • Certifique-se de que Group Privacy está desligado no BotFather — sem isso, o bot não consegue ver mensagens que não sejam comandos em grupos
  • Se você alterou o modo de privacidade depois de adicionar o bot a um grupo, remova e adicione o bot novamente ao grupo
  • Por padrão, o bot exige uma @menção ou uma resposta. Envie @seubot oi para testar

”Desculpe, algo deu errado ao processar sua mensagem”

Isso geralmente significa que o agente encontrou um erro. Verifique a saída do terminal para obter detalhes.

O bot demora muito para responder

O agente pode estar executando várias chamadas de ferramenta (lendo arquivos, pesquisando, etc.). O indicador “Working…” é exibido enquanto o agente está processando. Tarefas complexas podem levar um minuto ou mais.

Last updated on
Visão geralWeChat