Saltar al contenido principal

Añade un canal de Telegram a OpenClaw

· 7 min de lectura
Rafael Fernandes
Rafael Fernandes
Ingeniero de PLN y Redactor Técnico en WiLine
Share:
OpenClaw+

Ya desplegaste OpenClaw y lo aseguraste detrás de HTTPS. Ahora hazlo usable — habla con tu agente desde el móvil vía Telegram. Creamos un bot, lo conectamos, superamos la barrera de emparejamiento de OpenClaw y obtenemos una respuesta real. Cada comando y tropiezo de abajo proviene de un despliegue real.

Reproducibilidad

Continúa de las Partes 1–2 en el mismo Instancia WEC — OpenClaw 2026.6.8. Telegram usa polling (el gateway consulta la API de Telegram), así que no se requiere ningún webhook público ni dominio — esto funciona en una máquina privada.

Lo que vas a construir​

Tu móvil habla con un bot de Telegram; el gateway de OpenClaw consulta a Telegram en busca de mensajes, los procesa con tu modelo y responde — sin necesidad de puertos entrantes.

Requisitos previos​

  • Parte 1 + Parte 2 completas — OpenClaw en marcha en ~/openclaw
  • Una cuenta de Telegram y un cliente de Telegram con sesión iniciada — la app del móvil/escritorio, o web.telegram.org. (No puedes crear un bot desde la página web pública de t.me; mira la Solución de problemas.)

Paso 1 — Crear un bot de Telegram​

En la app de Telegram, toca buscar y escribe BotFather, luego abre la cuenta oficial — la que tiene el tilde azul.

Buscando BotFather en Telegram

Toca Start — BotFather responde con los comandos que entiende (verás opciones como /newbot, /mybots, /token y más). Envía /newbot y luego sigue sus dos indicaciones:

  1. Name — un nombre para mostrar, p. ej. My OpenClaw Agent
  2. Username — debe ser único y terminar en bot, p. ej. wiline_openclaw_bot

BotFather confirma con "Done! Congratulations on your new bot" y te da el token — la línea después de Use this token to access the HTTP API:, como 1234567890:AA....

BotFather emitiendo el token del bot

El token del bot es una credencial

Cualquiera que lo tenga controla tu bot. Difumínalo en la captura de arriba y haz /revoke en BotFather si alguna vez se filtra.

Paso 2 — Conectar el bot a OpenClaw​

En la VM, dentro de ~/openclaw, registra el canal con tu token:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<your-bot-token>"
# Added Telegram account "default".

channels add ejecutándose con éxito

Paso 3 — Activar y verificar​

Reinicia el gateway para que tome el canal, luego comprueba el estado:

docker compose restart openclaw-gateway
docker compose run --rm openclaw-cli channels status
# - Telegram default: enabled, configured, running, mode:polling, token:config

mode:polling significa que el gateway está consultando activamente a Telegram — sin puerto entrante ni webhook.

channels status mostrando Telegram en marcha en modo polling

Paso 4 — Enviar un mensaje al bot (barrera de emparejamiento)​

Abre tu bot (t.me/<your-bot-username>), toca Start y envía un mensaje.

OpenClaw trata a los remitentes desconocidos como no confiables — así que en lugar de responder, el bot devuelve un código de emparejamiento y tu id de usuario de Telegram. Es el mismo patrón de seguridad que el emparejamiento de dispositivos de la Parte 2.

El bot respondiendo con el código de emparejamiento

Paso 5 — Aprobar el emparejamiento​

En la VM, aprueba el código del mensaje del bot:

docker compose run --rm openclaw-cli pairing approve telegram <pairing-code>
# Approved telegram sender <id>.
# Command owner configured telegram:<id> (commands.ownerAllowFrom was empty).
nota

Aprobar al primer usuario como command owner cambia una configuración que requiere reiniciar el gateway — OpenClaw lo hace automáticamente (verás config change requires gateway restart y luego el reinicio del proveedor de Telegram en los logs). Espera unos segundos a que vuelva antes de enviar otro mensaje.

Aprobando el emparejamiento en la VM — &quot;Approved telegram sender …&quot;

Paso 6 — Chatear con tu agente​

De vuelta en Telegram, simplemente háblale — no hace falta más configuración; OpenClaw con tu modelo responde de forma conversacional desde el primer momento. Prueba con algo como:

In one sentence, what's the point of putting a reverse proxy in front of my agent?

Responde con una respuesta real — toda la cadena está activa: tu móvil → Telegram → gateway → OpenAI → respuesta. Tu agente autoalojado ya cabe en tu bolsillo. (Darle herramientas y skills llega en guías posteriores; el chat conversacional funciona de inmediato.)

El agente respondiendo de forma conversacional por Telegram

Solución de problemas (errores reales)​

1. El botón "Start" de BotFather no hace nada en un navegador​

Abrir t.me/BotFather en un navegador web normal muestra un botón Start que no hace nada — esa página es solo la tarjeta pública del bot y necesita un cliente de Telegram con sesión iniciada al que delegar. Usa la app de escritorio/móvil, o inicia sesión en web.telegram.org (vincula un dispositivo de escritorio escaneando el QR desde tu móvil: Settings → Devices → Link Desktop Device), y luego escríbele a BotFather ahí.

2. El bot devuelve un código de emparejamiento en lugar de responder​

No es un error — es la barrera de emparejamiento. Los remitentes desconocidos deben aprobarse primero (Paso 5). Tras la aprobación, el bot chatea con normalidad.

3. Proxy headers detected from untrusted address​

Si seguiste la Parte 2, el gateway registra esto porque Caddy está por delante de él. Es una advertencia, no un fallo. Para silenciarla y restaurar la detección correcta del cliente, establece gateway.trustedProxies con la red de tu proxy.

Notas de seguridad y dimensionamiento​

  • El emparejamiento es la barrera — solo los usuarios de Telegram aprobados llegan al agente; el primer usuario aprobado se convierte en command owner.
  • Polling, no webhooks — no se abre ningún puerto entrante, lo que mantiene intacto el endurecimiento de la Parte 2.
  • Dimensionamiento — en una máquina de 2 vCPU el gateway registró event loop degraded bajo carga. Para un bot con mucho tráfico, dale más CPU/RAM.

Qué sigue​

Terminaste la Parte 3 de la serie Self-hosting OpenClaw. Sigue:

Después empieza la serie Self-hosting Hermes — Autoaloja el Hermes Agent con memoria persistente — para un agente cuyo contexto sobrevive a los reinicios.

Los archivos complementarios de la serie viven en el repo de manifiestos de WiLine (enlace pendiente con el repo).

Desmontaje​

Elimina el canal de Telegram (mantiene en marcha el resto de OpenClaw):

docker compose run --rm openclaw-cli channels remove --channel telegram
docker compose restart openclaw-gateway

Y haz /revoke del token del bot en BotFather si ya terminaste con él.