Canal Telegram de OpenClaw
Mensajería
Fácil
Conecta OpenClaw a Telegram usando el framework grammY Bot API. Crea un bot de Telegram a través de @BotFather, obtén el token, y tu asistente de IA estará activo en Telegram en minutos. Usa long-polling por defecto con modo Webhook opcional. Uno de los canales más fáciles de configurar, con funciones ricas como botones inline, stickers, reacciones y soporte de grupos.
Info rápida
DificultadFácil
CategoríaMensajería
Funciones compatibles6 / 6
Telegram Funciones compatibles
Mensajes de texto
Compatible
Medios y archivos
Compatible
Reacciones
Compatible
Hilos
Compatible
Mensajes de voz
Compatible
Chat grupal
Compatible
Telegram Requisitos previos
- Una cuenta de Telegram
- Un Token de Bot de @BotFather (envía /newbot a @BotFather)
- OpenClaw Gateway en funcionamiento y configurado
- Node.js 18+ instalado en tu servidor
Telegram Configuración rápida
1
Crear un bot con @BotFather
Abre Telegram, busca @BotFather y envía /newbot. Sigue las indicaciones para nombrar tu bot y obtener el token de API. Guarda este token — lo necesitarás para la configuración.
2
Agregar configuración del canal Telegram
Agrega la configuración del canal Telegram en ~/.openclaw/openclaw.json. Pega el token del bot de @BotFather en el campo botToken. Configura el dmPolicy (pairing, allowlist u open) para controlar quién puede comunicarse con tu asistente.
3
Iniciar Gateway y probar
Inicia el proceso Gateway. Busca tu bot en Telegram y envíale un mensaje. Si usas la política pairing por defecto, aprueba al remitente con 'openclaw pairing approve telegram <code>'. OpenClaw debería responder a través del asistente de IA.
Telegram Ejemplo de configuración
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram Documentación Detallada
Descripción de la arquitectura
OpenClaw se conecta a Telegram a través del framework grammY — una biblioteca moderna de Telegram Bot API con TypeScript. El bot usa long-polling por defecto, consultando periódicamente los servidores de Telegram para nuevas actualizaciones. Funciona de inmediato sin configuración adicional.
También puedes cambiar al modo Webhook para despliegues en producción. En modo Webhook, Telegram envía las actualizaciones directamente a tu endpoint, siendo más eficiente y con menor latencia.
El long-polling funciona detrás de NATs y firewalls sin configuración. El modo Webhook requiere un endpoint HTTPS accesible públicamente.
Almacena tu token de bot con la variable de entorno TELEGRAM_BOT_TOKEN o en channels.telegram.botToken de tu config.
Crear tu bot con @BotFather
BotFather es la herramienta oficial de Telegram para crear y gestionar bots. Pasos:
1. Abre Telegram y busca @BotFather
2. Envía /newbot para iniciar la creación
3. Elige un nombre para mostrar (ej: "Mi Asistente IA")
4. Elige un nombre de usuario terminado en 'bot' (ej: "mi_asistente_ia_bot")
5. BotFather te dará un token API — guárdalo de forma segura
Después de la creación, personaliza con comandos de BotFather:
• /setdescription — Establecer descripción del perfil
• /setabouttext — Establecer texto "Acerca de"
• /setuserpic — Subir foto de perfil
• /setprivacy — Alternar modo privacidad para mensajes de grupo
Mantén tu token en secreto. Cualquier persona con el token puede controlar tu bot. Si se compromete, usa /revoke en BotFather para generar uno nuevo.
Políticas de DM
Las políticas de DM (Mensajes Directos) controlan quién puede interactuar con tu asistente IA en chats privados. OpenClaw soporta tres políticas:
• pairing (por defecto) — Los nuevos usuarios pasan por un flujo de emparejamiento. Envían un mensaje, reciben un código (válido 1 hora) y tú apruebas o rechazas por CLI.
• allowlist — Solo los IDs de usuario numéricos en allowFrom pueden contactar al bot. Los demás son ignorados.
• open — Cualquiera que envíe un mensaje al bot recibe respuesta. Usar con precaución en producción.
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}Para encontrar el ID numérico de Telegram de un usuario, usa @userinfobot o revisa los logs del Gateway cuando envían un mensaje.
Gestión de grupos
OpenClaw soporta grupos de Telegram con control de acceso flexible mediante dos mecanismos independientes:
1. Lista de grupos permitidos — Todos los grupos o solo los listados en channels.telegram.groups.
2. Política de grupo — Control de permisos de remitentes:
• open — Cualquier miembro puede activar el bot
• allowlist — Solo remitentes aprobados
• disabled — Mensajes de grupo ignorados
Por defecto, el bot requiere @mención en grupos. Puedes cambiar esto:
• Comando /activation always (solo sesión)
• requireMention: false en la config para efecto permanente
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}Para grupos tipo foro (temas), OpenClaw aísla cada tema por ID de hilo y puede aplicar configuraciones específicas por tema.
Para que el bot vea todos los mensajes del grupo sin ser admin, desactiva el modo privacidad en BotFather (/setprivacy), luego retira y vuelve a agregar el bot al grupo.
Formato y streaming de mensajes
OpenClaw ofrece varias opciones de formato y entrega:
Formato: El texto saliente usa el parser HTML de Telegram con conversión automática desde Markdown. Si falla el parsing HTML, se reintenta como texto plano.
Streaming: Las burbujas de borrador soportan streaming parcial en DMs. Dos modos:
• partial (por defecto) — Actualizaciones progresivas de un solo mensaje
• block — Envío en bloques completos
El texto se divide por defecto en 4,000 caracteres (límite de Telegram). Usa chunkMode: "newline" para dividir por párrafos.
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}Botones inline
OpenClaw soporta los botones de teclado inline interactivos de Telegram. Al habilitarlos, la IA puede mostrar botones bajo los mensajes. Al hacer clic, los datos de callback se envían al agente.
Modos disponibles:
• off — Botones desactivados (por defecto)
• dm — Solo en chats privados
• group — Solo en grupos
• all — En todos lados
• allowlist — Restringido por autorización
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}Stickers y medios
OpenClaw maneja stickers y archivos multimedia de Telegram:
Stickers: Los stickers estáticos se descargan y procesan mediante análisis visual. Las descripciones se almacenan en caché. Los stickers animados y de video se omiten. El agente puede enviar stickers por ID de archivo y buscar en caché.
Medios: El límite de subida/descarga es 5 MB por defecto. El bot soporta envío y recepción de imágenes, documentos, audio y video.
Activa la acción sticker en la config del agente para permitir el envío de stickers por ID de archivo o búsqueda en caché.
Reacciones
OpenClaw soporta el sistema de reacciones de Telegram:
Las reacciones recibidas generan eventos del sistema:
• off — Sin notificaciones
• own — Solo reacciones a mensajes del bot
• all — Todas las reacciones
Nivel de reacción del bot:
• off — Sin reacciones
• ack — Reacción de confirmación al procesar (por defecto)
• minimal — Reacciones básicas
• extensive — Rango completo de emojis
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}Comandos y herramientas
Los comandos nativos del bot (/status, /reset, etc.) se registran automáticamente en el menú de comandos de Telegram. Los comandos personalizados se pueden agregar pero solo funcionan como entradas de menú.
El agente también soporta acciones de herramientas:
• Enviar mensajes a chats específicos
• Reaccionar con emojis
• Eliminar mensajes
• Responder a mensajes específicos con [[reply_to:<id>]]
Usa [[reply_to_current]] en la respuesta del agente para responder directamente al mensaje actual.
Incluye [[audio_as_voice]] en las respuestas o configura asVoice: true para forzar formato de nota de voz.
Modo Webhook
Para despliegues en producción, se recomienda el modo Webhook sobre long-polling. Telegram envía las actualizaciones directamente a tu servidor, reduciendo latencia y uso de recursos.
Configura webhookUrl y webhookSecret. El endpoint local se vincula a 0.0.0.0:8787 por defecto.
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}Al cambiar de polling a Webhook, el Gateway registra automáticamente la URL del Webhook con Telegram al iniciar.
El modo Webhook requiere un endpoint HTTPS accesible públicamente. Asegúrate de que tu servidor tenga un certificado SSL válido.
Telegram Referencia de Configuración
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Activar o desactivar el canal Telegram |
| botToken | string | "" | Token Bot API de @BotFather. También soporta variable env TELEGRAM_BOT_TOKEN |
| dmPolicy | string | "pairing" | Control de acceso DM. Opciones: pairing, allowlist, open |
| allowFrom | number[] | [] | IDs de usuario Telegram permitidos (cuando dmPolicy es allowlist) |
| groupPolicy | string | "disabled" | Política de grupo. Opciones: disabled, open, allowlist |
| groups | string[] | [] | Lista de IDs de grupos permitidos |
| requireMention | boolean | true | Requerir @mención en grupos |
| streamMode | string | "partial" | Modo streaming. Opciones: partial, block |
| chunkMode | string | "split" | División de respuestas largas. Opciones: split, newline |
| webhookUrl | string | "" | URL HTTPS para modo Webhook |
| webhookSecret | string | "" | Token secreto para verificación Webhook |
| reactionNotifications | string | "off" | Notificaciones de reacciones. Opciones: off, own, all |
| reactionLevel | string | "ack" | Capacidad de reacción del bot. Opciones: off, ack, minimal, extensive |
| capabilities.inlineButtons | string | "off" | Modo botones inline. Opciones: off, dm, group, all, allowlist |
| configWrites | boolean | true | Migración auto de IDs al actualizar a supergrupo |
enabled
Type: booleanDefault: true
Activar o desactivar el canal Telegram
botToken
Type: stringDefault: ""
Token Bot API de @BotFather. También soporta variable env TELEGRAM_BOT_TOKEN
dmPolicy
Type: stringDefault: "pairing"
Control de acceso DM. Opciones: pairing, allowlist, open
allowFrom
Type: number[]Default: []
IDs de usuario Telegram permitidos (cuando dmPolicy es allowlist)
groupPolicy
Type: stringDefault: "disabled"
Política de grupo. Opciones: disabled, open, allowlist
groups
Type: string[]Default: []
Lista de IDs de grupos permitidos
requireMention
Type: booleanDefault: true
Requerir @mención en grupos
streamMode
Type: stringDefault: "partial"
Modo streaming. Opciones: partial, block
chunkMode
Type: stringDefault: "split"
División de respuestas largas. Opciones: split, newline
webhookUrl
Type: stringDefault: ""
URL HTTPS para modo Webhook
webhookSecret
Type: stringDefault: ""
Token secreto para verificación Webhook
reactionNotifications
Type: stringDefault: "off"
Notificaciones de reacciones. Opciones: off, own, all
reactionLevel
Type: stringDefault: "ack"
Capacidad de reacción del bot. Opciones: off, ack, minimal, extensive
capabilities.inlineButtons
Type: stringDefault: "off"
Modo botones inline. Opciones: off, dm, group, all, allowlist
configWrites
Type: booleanDefault: true
Migración auto de IDs al actualizar a supergrupo
Telegram Preguntas Frecuentes
Telegram Solución de Problemas
El bot ignora mensajes sin mención en grupos
El modo privacidad está activado por defecto. El bot solo recibe @menciones y comandos slash.
Desactiva el modo privacidad en BotFather (/setprivacy → Disable). Retira y reagrega el bot al grupo. Configura requireMention: false en OpenClaw.
El bot no responde a ningún mensaje
Token incorrecto, Gateway no iniciado, o problema de red.
Verifica el token: curl https://api.telegram.org/bot<token>/getMe. Revisa logs del Gateway. Para problemas IPv6, fuerza resolución IPv4 para api.telegram.org.
El Webhook no recibe actualizaciones
URL Webhook inaccesible, certificado SSL inválido, o Webhook mal registrado.
Verifica accesibilidad de la URL (curl). Valida el certificado SSL. Verifica estado: curl https://api.telegram.org/bot<token>/getWebhookInfo. Reinicia el Gateway.
Mensajes truncados o mal divididos
Telegram tiene límite de 4,096 caracteres. Las respuestas largas se dividen automáticamente.
Usa chunkMode: 'newline' para dividir por párrafos en lugar del límite de caracteres.