Telegram

Estado: listo para producción para mensajes directos de bot + grupos a través de grammY. El modo de long polling es el predeterminado; el modo webhook es opcional.

Configuración rápida

Paso 1: Crear el token del bot en BotFather

Abre Telegram y chatea con @BotFather (confirma que el identificador sea exactamente @BotFather). Ejecuta /newbot, sigue las indicaciones y guarda el token.

Paso 2: Configurar el token y la política de mensajes directos

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

Respaldo de variable de entorno: TELEGRAM_BOT_TOKEN=... (solo cuenta predeterminada). Telegram no usa openclaw channels login telegram; configura el token en config/env, luego inicia la puerta de enlace.

Paso 3: Iniciar la puerta de enlace y aprobar el primer mensaje directo

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Los códigos de emparejamiento expiran después de 1 hora.

Paso 4: Agregar el bot a un grupo

Agrega el bot a tu grupo, luego configura channels.telegram.groups y groupPolicy para que coincidan con tu modelo de acceso.

ℹ️ El orden de resolución del token tiene en cuenta la cuenta. En la práctica, los valores de configuración tienen prioridad sobre el respaldo de la variable de entorno, y TELEGRAM_BOT_TOKEN solo se aplica a la cuenta predeterminada.

Configuraciones del lado de Telegram

Control de acceso y activación

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Comportamiento en tiempo de ejecución

• Telegram es propiedad del proceso de la puerta de enlace.
• El enrutamiento es determinista: las respuestas entrantes de Telegram vuelven a Telegram (el modelo no elige canales).
• Los mensajes entrantes se normalizan en el sobre de canal compartido con metadatos de respuesta y marcadores de posición de medios.
• Las sesiones de grupo están aisladas por ID de grupo. Los temas del foro agregan :topic:<threadId> para mantener los temas aislados.
• Los mensajes directos pueden llevar message_thread_id; OpenClaw los enruta con claves de sesión conscientes del hilo y preserva el ID del hilo para las respuestas.
• El long polling usa grammY runner con secuenciación por chat/hilo. La concurrencia general del sumidero del runner usa agents.defaults.maxConcurrent.
• La API de Bot de Telegram no tiene soporte para acuses de recibo (sendReadReceipts no se aplica).

Referencia de funciones

Solución de problemas

Más ayuda: Solución de problemas del canal.

Puntos de referencia de configuración de Telegram

Referencia principal:

• channels.telegram.enabled: habilita/deshabilita el inicio del canal.
• channels.telegram.botToken: token del bot (BotFather).
• channels.telegram.tokenFile: lee el token desde la ruta del archivo.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (predeterminado: pairing).
• channels.telegram.allowFrom: lista de permitidos de MD (IDs de usuario de Telegram numéricos). allowlist requiere al menos un ID de remitente. open requiere "*". openclaw doctor --fix puede resolver entradas heredadas @username a IDs y puede recuperar entradas de lista de permitidos de archivos de almacenamiento de emparejamiento en flujos de migración de lista de permitidos.
• channels.telegram.actions.poll: habilita o deshabilita la creación de encuestas de Telegram (predeterminado: habilitado; aún requiere sendMessage).
• channels.telegram.defaultTo: objetivo de Telegram predeterminado utilizado por la CLI --deliver cuando no se proporciona un --reply-to explícito.
• channels.telegram.groupPolicy: open | allowlist | disabled (predeterminado: allowlist).
• channels.telegram.groupAllowFrom: lista de permitidos de remitentes de grupo (IDs de usuario de Telegram numéricos). openclaw doctor --fix puede resolver entradas heredadas @username a IDs. Las entradas no numéricas se ignoran en el momento de la autorización. La autorización de grupo no usa el respaldo del almacenamiento de emparejamiento de MD (2026.2.25+).
• Precedencia de múltiples cuentas:
  • Cuando se configuran dos o más IDs de cuenta, configura channels.telegram.defaultAccount (o incluye channels.telegram.accounts.default) para hacer explícito el enrutamiento predeterminado.
  • Si no se establece ninguno, OpenClaw recurre al primer ID de cuenta normalizado y openclaw doctor advierte.
  • channels.telegram.accounts.default.allowFrom y channels.telegram.accounts.default.groupAllowFrom se aplican solo a la cuenta default.
  • Las cuentas con nombre heredan channels.telegram.allowFrom y channels.telegram.groupAllowFrom cuando los valores a nivel de cuenta no están establecidos.
  • Las cuentas con nombre no heredan channels.telegram.accounts.default.allowFrom / groupAllowFrom.
• channels.telegram.groups: valores predeterminados por grupo + lista de permitidos (usa "*" para valores predeterminados globales).
  • channels.telegram.groups.<id>.groupPolicy: anulación por grupo para groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: habilitación de mención predeterminada.
  • channels.telegram.groups.<id>.skills: filtro de habilidades (omitir = todas las habilidades, vacío = ninguna).
  • channels.telegram.groups.<id>.allowFrom: anulación de la lista de permitidos de remitentes por grupo.
  • channels.telegram.groups.<id>.systemPrompt: mensaje de sistema adicional para el grupo.
  • channels.telegram.groups.<id>.enabled: deshabilita el grupo cuando es false.
  • channels.telegram.groups.<id>.topics.<threadId>.*: anulaciones por tema (campos de grupo + agentId solo para tema).
  • channels.telegram.groups.<id>.topics.<threadId>.agentId: enruta este tema a un agente específico (anula el enrutamiento a nivel de grupo y vinculaciones).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: anulación por tema para groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: anulación por tema para requerimiento de mención.