OpenClaw
Integraciones10 min de lectura

Guia Completa de Integracion de OpenClaw con Telegram

Aprende como crear un bot de Telegram y conectarlo a OpenClaw. Tutorial completo que cubre creacion del bot, configuracion, comandos y configuracion de chats grupales.

O

OpenClaw Guides

Tutorial Authors

Descripcion General

La integracion con Telegram te permite interactuar con OpenClaw a traves de un bot de Telegram dedicado. OpenClaw usa el framework grammY para long-polling por defecto, con soporte opcional de webhook para despliegues en produccion.

Requisitos Previos

  • OpenClaw instalado y en ejecucion
  • Una cuenta de Telegram

Paso 1: Crear un Bot de Telegram

Habla con BotFather

  1. Abre Telegram y busca @BotFather
  2. Inicia un chat y envia /newbot
  3. Sigue las instrucciones:
You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

Guarda el token del bot — lo necesitaras en el siguiente paso.

Deshabilitar el Modo de Privacidad (Recomendado para Grupos)

Si planeas usar el bot en chats grupales, deshabilita el modo de privacidad para que pueda leer todos los mensajes:

/setprivacy
@myopenclaw_bot
Disable

Despues de cambiar el modo de privacidad, debes eliminar y volver a agregar el bot a los grupos existentes para que el cambio surta efecto. Alternativamente, promueve el bot a administrador del grupo — los bots administradores siempre reciben todos los mensajes.

Paso 2: Configurar OpenClaw

Almacenamiento del Token

Puedes almacenar el token del bot de dos formas. La configuracion tiene prioridad sobre la variable de entorno.

Opcion A — Variable de entorno:

bash
# Agregar a ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Opcion B — Directamente en la configuracion:

json5
// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Configuracion Minima

Edita ~/.openclaw/openclaw.json:

json5
{
  channels: {
    telegram: {
      // Token desde la variable de entorno TELEGRAM_BOT_TOKEN o establece botToken directamente
    }
  }
}

Eso es todo lo que necesitas — OpenClaw inicia el long-polling automaticamente cuando se configura un canal de Telegram.

Paso 3: Prueba Tu Bot

  1. Abre Telegram y busca el nombre de usuario de tu bot
  2. Inicia un chat con /start
  3. Envia cualquier mensaje para probar

Control de Acceso — Politica de MD

Controla quien puede enviar mensajes a tu bot en chats privados mediante dmPolicy:

| Politica | Comportamiento | |----------|----------------| | "pairing" (por defecto) | Los remitentes desconocidos reciben un codigo de emparejamiento con expiracion; lo apruebas via CLI | | "allowlist" | Solo los IDs de usuario / @nombres_de_usuario en allowFrom pueden enviar mensajes | | "open" | Cualquier persona puede enviar mensajes al bot | | "disabled" | Los mensajes directos estan completamente desactivados |

Modo de Emparejamiento (Por Defecto)

Cuando un nuevo usuario envia un mensaje al bot, recibe un codigo de emparejamiento. Apruebalo con:

bash
# Listar solicitudes de emparejamiento pendientes
openclaw pairing list telegram

# Aprobar un codigo especifico
openclaw pairing approve telegram <CODE>

Los codigos de emparejamiento expiran despues de 1 hora.

Modo Allowlist

json5
{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

Modo Abierto

json5
{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

Soporte para Chats Grupales

Habilitar Acceso de Grupo

Agrega los IDs de grupo al objeto groups. Usa "*" para permitir todos los grupos:

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // grupo especifico con valores por defecto
        "-1009876543210": {             // grupo especifico con anulaciones
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

O permite todos los grupos:

json5
{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

Politica de Grupo

Controla quien puede interactuar con el bot dentro de los grupos:

| Configuracion | Descripcion | |---------------|-------------| | groupPolicy: "open" | Cualquier miembro del grupo puede enviar mensajes al bot | | groupPolicy: "allowlist" | Solo los remitentes en groupAllowFrom pueden interactuar | | groupPolicy: "disabled" | El bot ignora todos los mensajes del grupo |

json5
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

Requisito de Mencion

Por defecto, el bot requiere una @mencion en los grupos. Puedes cambiar esto por grupo:

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // el bot responde a todos los mensajes
        }
      }
    }
  }
}

O usa el comando de solo sesion /activation always en el chat grupal.

Anulaciones Por Grupo

Cada entrada de grupo admite estos campos:

| Campo | Descripcion | |-------|-------------| | groupPolicy | Anular la politica de grupo global | | requireMention | Si se requiere @mencion | | skills | Skills disponibles en este grupo | | allowFrom | Lista de remitentes permitidos para este grupo | | systemPrompt | Prompt de sistema personalizado para este grupo | | enabled | Habilitar/deshabilitar para este grupo especifico |

Formato de Mensajes y Fragmentacion

Modo de Analisis HTML

OpenClaw envia mensajes usando el modo de analisis HTML de Telegram (no Markdown). El Markdown del LLM se convierte automaticamente a etiquetas HTML seguras. Si Telegram rechaza el HTML, el mensaje se reintenta como texto plano.

Fragmentacion de Texto

Los mensajes largos se dividen en multiples mensajes de Telegram:

json5
{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // maximo de caracteres por mensaje (por defecto: 4000)
      chunkMode: "newline"     // "length" (por defecto) o "newline"
    }
  }
}
  • "length" — divide en el limite de caracteres
  • "newline" — divide en los limites de parrafo antes de aplicar el limite de longitud

Manejo de Medios

Limite de Tamano de Medios

json5
{
  channels: {
    telegram: {
      mediaMaxMb: 5    // tamano maximo de archivo en MB (por defecto: 5)
    }
  }
}

Stickers

  • Los stickers estaticos (WEBP) se procesan a traves de vision y se describen al LLM
  • Los stickers animados / de video se omiten
  • Las descripciones de stickers se almacenan en cache en ~/.openclaw/telegram/sticker-cache.json para evitar llamadas de vision redundantes

Para habilitar que el bot envie stickers:

json5
{
  channels: {
    telegram: {
      actions: {
        sticker: true    // por defecto: false
      }
    }
  }
}

Historial y Contexto

json5
{
  channels: {
    telegram: {
      historyLimit: 50,        // contexto de grupo (por defecto: 50)
      dmHistoryLimit: 100      // contexto de MD
    }
  }
}

Anulacion por usuario en MD:

json5
{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

Establece en 0 para deshabilitar el historial.

Streaming

OpenClaw soporta streaming basado en borradores en chats privados (con temas de foro habilitados):

| Configuracion | Descripcion | |---------------|-------------| | streamMode: "off" | Streaming deshabilitado (por defecto) | | streamMode: "partial" | Actualizaciones continuas a un mensaje borrador | | streamMode: "block" | Actualizaciones por bloques a un mensaje borrador |

Configuracion del modo de bloques:

json5
{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Modo Webhook (Produccion)

Para despliegues en produccion, usa webhooks en lugar de long-polling:

json5
{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // ruta local, por defecto: /telegram-webhook
    }
  }
}

El listener de webhook se enlaza a 0.0.0.0:8787. Cuando se establece webhookUrl, OpenClaw cambia automaticamente de polling a modo webhook.

Comandos

Comandos Nativos

OpenClaw registra estos comandos en el menu de bot de Telegram al iniciar:

| Comando | Descripcion | |---------|-------------| | /start | Mensaje de bienvenida | | /status | Mostrar estado del bot | | /reset | Reiniciar conversacion | | /model | Mostrar / cambiar modelo |

Comandos Personalizados

Agrega entradas de menu a traves de la configuracion (solo menu — no se ejecutan a menos que se manejen en otro lugar):

json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

Los nombres de comandos deben ser en minusculas a-z0-9_, de 1 a 32 caracteres. El / inicial se elimina automaticamente. No se pueden anular los comandos nativos.

Botones Inline

Controla la disponibilidad de botones inline:

| Configuracion | Alcance | |---------------|---------| | capabilities.inlineButtons: "off" | Deshabilitado | | capabilities.inlineButtons: "dm" | Solo en MD | | capabilities.inlineButtons: "group" | Solo en grupos | | capabilities.inlineButtons: "all" | Tanto en MD como en grupos | | capabilities.inlineButtons: "allowlist" | Ambos + filtrado de remitentes (por defecto) |

Red y Proxy

json5
{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Tiempo de espera de solicitud a Bot API (por defecto: 500)
      network: {
        autoSelectFamily: false   // deshabilitar Happy Eyeballs (por defecto en Node 22)
      },
      proxy: "socks5://127.0.0.1:1080"   // Proxy SOCKS/HTTP para Bot API
    }
  }
}

Solucion de Problemas

El Bot No Responde

  1. Verifica que el token sea correcto:
bash
curl "https://api.telegram.org/bot<TOKEN>/getMe"
  1. Revisa los logs de OpenClaw:
bash
openclaw logs --follow

Los Mensajes No Llegan en los Grupos

  • El modo de privacidad debe estar deshabilitado (/setprivacy → Disable) o el bot debe ser administrador
  • Prueba con /activation always (solo sesion); persiste mediante requireMention: false en la configuracion

Fallos de Enrutamiento IPv6

El bot puede dejar de responder silenciosamente si el enrutamiento IPv6 falla. Verifica el DNS para api.telegram.org:

bash
dig api.telegram.org AAAA

Solucion habilitando la salida IPv6 o forzando IPv4:

bash
# Add to /etc/hosts
149.154.167.220  api.telegram.org

O usa la configuracion de red:

json5
{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

Abortos de Long-Polling (Node 22+)

Node 22 es mas estricto con las instancias de AbortSignal. Actualiza OpenClaw a la ultima version o baja a Node 20.

Fallos de setMyCommands

El HTTPS/DNS saliente hacia api.telegram.org puede estar bloqueado. Verifica las reglas de tu firewall.

Mejores Practicas de Seguridad

  1. Nunca compartas tu token del bot — revocalo inmediatamente via BotFather si se ve comprometido
  2. Usa emparejamiento o allowlist para el control de acceso en MD
  3. Establece politicas de grupo para controlar quien puede interactuar en los grupos
  4. Encuentra IDs de usuario de forma segura via openclaw logs --follow o el endpoint getUpdates de la Bot API — evita bots de terceros para obtener IDs
  5. Usa webhooks con un secreto para despliegues en produccion

Siguientes Pasos