setMyCommands de Telegram no se llama al reiniciar el Gateway en OpenClaw 2026.4.14

• Síntoma Principal: Todos los comandos de barra del bot de Telegram (42–58 comandos) desaparecen del menú después de un reinicio del gateway.
• Verificación de API: La llamada a la API del Bot de Telegram getMyCommands devuelve una lista vacía:

  curl -s "https://api.telegram.org/bot<TOKEN>/getMyCommands"
  {"ok":true,"result":[]}

• Ausencia de Registros: Los registros de inicio del gateway omiten el mensaje esperado de registro de comandos:

  {"subsystem":"gateway/channels/telegram"} Telegram menu text exceeded the conservative 5700-character payload budget; shortening descriptions to keep 58 commands visible.

• Inconsistencia de Comportamiento: Los reinicios anteriores en la misma sesión sí registraron los comandos correctamente, mientras que los reinicios posteriores omiten el registro por completo. Esto sugiere una falla de inicialización no determinística.
• Confirmación de Solución Alternativa: Invocar manualmente setMyCommands a través de la API del Bot restaura los comandos exitosamente, confirmando que la API de Telegram funciona correctamente y que el problema radica en la secuencia de inicialización de OpenClaw.

Comando de Diagnóstico para Confirmar el Síntoma

# Check if commands are registered (should return non-empty array after successful init)
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length'

# Expected output: > 0 if commands are registered
# Symptomatic output: 0

Análisis Técnico

La causa raíz radica en una condición de carrera o dependencia del orden de inicialización introducida en OpenClaw 2026.4.14 (commit 323493f). La función registerTelegramNativeCommands, ubicada en el paquete compilado bot-BwMz6R6-.js, no se invoca durante la secuencia de inicio del gateway.

Secuencia de Falla

1. Inicio del Gateway: El gateway de OpenClaw inicializa todos los canales configurados, incluyendo el proveedor de Telegram (basado en grammy).
2. Inicialización del Proveedor: El proveedor de Telegram emite un evento ready o una señal equivalente del ciclo de vida tras una conexión exitosa a la API del Bot de Telegram.
3. Disparador del Registro de Comandos: La función registerTelegramNativeCommands debería invocarse al estar listo el proveedor para registrar el menú de comandos de barra.
4. Punto de Falla: En 2026.4.14, el disparador del registro presenta alguno de estos problemas:
• Está adjunto a un evento que se ejecuta antes de que las definiciones de comandos estén completamente cargadas
• Está sujeto a una verificación condicional que se evalúa como false debido a problemas de temporización
• Está bloqueado por un rechazo de promesa no manejado que falla silenciosamente

Inconsistencia Arquitectónica

El comportamiento inconsistente (algunos reinicios funcionan, otros fallan) indica una condición de carrera independiente de la hora del día. Los factores posibles que contribuyen son:

• Cadena de Inicialización Asíncrona: Si el registro de comandos depende de la obtención de datos externos (por ejemplo, cargar definiciones de comandos desde una base de datos o almacén de configuración), las variaciones de latencia de red pueden causar que el registro se ejecute antes de que los datos estén disponibles.
• Temporización del Adjunto del Manejador de Eventos: El manejador del evento ready puede adjuntarse después de que el evento ya se haya ejecutado en instancias de inicio rápido.
• Orden de Importación de Módulos: Diferencias en el orden de inicialización de módulos ES entre reinicios en caliente y reinicios en frío.
• Estado del Pool de Conexiones: En sesiones de gateway de larga duración, el estado acumulado del pool de conexiones puede afectar la temporización de inicialización.

Ruta de Código Afectada

// Simplified representation of the affected initialization path
async function initializeTelegramProvider(config) {
    const provider = new GrammyTelegramProvider(config);
    
    // This handler attachment may race with the ready event
    provider.on('ready', async () => {
        // This block may not execute if 'ready' already fired
        await registerTelegramNativeCommands(provider, config.commands);
    });
    
    await provider.start(); // ready event fires here on fast systems
}

Soluciones Alternativas Inmediatas

Opción 1: Registro Manual de Comandos (Corrección Temporal)

# Using curl to set commands directly via Telegram Bot API
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command": "help", "description": "Show help information"},
      {"command": "status", "description": "Check system status"},
      {"command": "model", "description": "Switch AI model"},
      {"command": "cancel", "description": "Cancel ongoing operation"}
    ]
  }'

# Verify the response contains {"ok": true, ...}

Opción 2: Cron Job como Solución de Emergencia

# Add to crontab (crontab -e)
# Restart gateway and immediately re-register commands
@reboot sleep 30 && /opt/openclaw/scripts/reregister-commands.sh

Opción 3: Forzar Re-registro mediante CLI de OpenClaw

# If OpenClaw provides a CLI tool
openclaw commands register --channel telegram --force

# Or via the management API
curl -X POST "http://localhost:3000/api/channels/telegram/commands/reload" \
  -H "Authorization: Bearer ${MANAGEMENT_API_TOKEN}"

Corrección Definitiva: Remediación de Versión

Paso 1: Identificar la Versión Actual

cat /opt/openclaw/package.json | grep '"version"'
# Or via CLI
openclaw --version

Paso 2: Revertir a la Versión Estable Anterior

# If using npm
npm install [email protected] --save

# If using Docker
# Edit docker-compose.yml
image: openclaw/openclaw:2026.4.13

# Rebuild and restart
docker-compose down && docker-compose up -d --build

Paso 3: Actualizar a la Versión Corregida (Cuando Está Disponible)

# Monitor the OpenClaw GitHub releases for 2026.4.15 or later
# Once available:
npm install openclaw@latest --save
# or
docker-compose pull && docker-compose up -d

Corrección Rápida: Parchar el Orden de Inicialización

Advertencia: Esta es una corrección manual temporal; aplicar durante una ventana de mantenimiento.

# Locate the compiled bundle
find /opt/openclaw -name "bot-BwMz6R6-.js" 2>/dev/null

# Backup original
cp /opt/openclaw/dist/bot-BwMz6R6-.js /opt/openclaw/dist/bot-BwMz6R6-.js.bak

# Add synchronous registration call after provider initialization
# Insert before the existing ready handler:
# 
# BEFORE (line ~XXX):
# provider.on('ready', async () => {
#
# AFTER (patch):
# // Immediate registration attempt
# registerTelegramNativeCommands(provider, config.commands).catch(console.error);
# provider.on('ready', async () => {
#     await registerTelegramNativeCommands(provider, config.commands);
# });

Pasos de Verificación Post-Corrección

1. Reiniciar el Gateway

# For systemd-managed installations
sudo systemctl restart openclaw-gateway

# For Docker
docker-compose restart gateway

# For PM2
pm2 restart openclaw

2. Verificar los Registros del Gateway para el Registro de Comandos

# Check for the expected log message
sudo journalctl -u openclaw-gateway -f | grep -i "setMyCommands\|menu text exceeded\|Telegram menu"

# Expected output (success):
# {"subsystem":"gateway/channels/telegram"} Telegram menu text exceeded the conservative 5700-character payload budget; shortening descriptions to keep 58 commands visible.

3. Verificar a través de la API del Bot de Telegram

# Get the number of registered commands
COMMAND_COUNT=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length')
echo "Registered commands: ${COMMAND_COUNT}"

# Expected: > 0 (e.g., 42, 58, etc.)
# Failure: 0

# Full API response for debugging
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq .

4. Probar en el Cliente de Telegram

# Open Telegram and check the bot's / menu
# All previously available slash commands should appear
# Test a known command (e.g., /help) to confirm functionality

5. Realizar Múltiples Reinicios Consecutivos

# Verify consistency across restarts (run 3 times)
for i in 1 2 3; do
    echo "=== Restart $i ==="
    sudo systemctl restart openclaw-gateway
    sleep 10
    COUNT=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length')
    echo "Command count: $COUNT"
    if [ "$COUNT" -eq 0 ]; then
        echo "FAILURE: Commands not registered on restart $i"
        exit 1
    fi
done
echo "SUCCESS: Commands registered consistently across all restarts"

Criterios de Salida de Verificación

• ✅ Los registros del gateway contienen el mensaje "Telegram menu text exceeded" al iniciar
• ✅ getMyCommands devuelve un array no vacío
• ✅ Todos los comandos esperados aparecen en el menú / del bot de Telegram
• ✅ Los comandos persisten después de múltiples reinicios consecutivos
• ✅ Código de salida 0 de la prueba de reinicio consecutivo

• Asumir que Todos los Reinicios se Comportan de Forma Idéntica: El error se manifiesta de manera inconsistente. Algunos reinicios exitosos no garantizan que el problema esté resuelto. Siempre verificar usando la prueba de reinicio consecutivos.
• Ignorar el Filtrado de Registros: El mensaje de registro relevante puede estar truncado o dividido en varias líneas dependiendo de la configuración de registro. Use grep -i telegram sin filtros adicionales para asegurar que capture todas las entradas relacionadas.
• Caché de Capas de Docker: Si usa Docker, asegúrese de forzar una reconstrucción después de los cambios de versión:

  docker-compose build --no-cache
  docker-compose up -d

• Temporización de Variables de Entorno: La variable de entorno TELEGRAM_BOT_TOKEN debe establecerse antes de que el gateway inicie. Verifique que su archivo de entorno se cargue correctamente:

  # Verify environment is loaded
  env | grep TELEGRAM

• Interacciones de Versión de Node.js: Node 22.22.1 puede presentar diferentes temporizaciones asíncronas que otras versiones. Pruebe con la misma versión de Node que se usó en el entorno funcional (pre-actualización).
• Configuraciones de Alta Disponibilidad del Gateway: En configuraciones multi-instancia, asegúrese de que el registro de comandos sea idempotente. Las llamadas duplicadas a setMyCommands pueden activar la limitación de tasa de Telegram.
• Apagado Sin Gracia: Matar abruptamente el proceso del gateway puede dejar la conexión del Webhook de Telegram en un estado inconsistente. Siempre use señales de apagado con gracia:

  kill -SIGTERM <pid>  # Preferred
  # Avoid: kill -SIGKILL <pid>

• Longitud de Descripción de Comandos: Si ha agregado comandos personalizados con descripciones que exceden 256 caracteres, la API de Telegram rechazará todo el lote. El mensaje de registro "menu text exceeded" indica que esta protección está activa.
• Interferencia de Firewall/Proxy: Los proxies corporativos pueden retrasar la respuesta de la API de Telegram, exacerbando la condición de carrera. Pruebe la conectividad directa:

  curl -v --max-time 10 "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"

• UNAUTHORIZED (401) en llamadas a la API del Bot — Típicamente indica un token de bot incorrecto, no este problema. Verifique la configuración del token si lo encuentra.
• Too Many Requests (429) desde la API de Telegram — Limitación de tasa durante intentos repetidos de registro de comandos. Implemente retroceso exponencial si implementa re-registro automatizado.
• Respuesta vacía de getMyCommands después de la actualización (Issue #4521) — Este es el síntoma principal del error documentado en esta guía.
• El gateway falla al conectarse a Telegram con ETIMEDOUT — Problema de conectividad de red, no relacionado con el error de registro de comandos pero puede aparecer simultáneamente.
• Los comandos desaparecen después de la rotación del token del bot — Comportamiento esperado al usar un nuevo token; los comandos son específicos del token. Re-registre después de la rotación del token.
• Inconsistencia entre modo Webhook y modo Polling — Si cambia entre modos de conexión de Telegram, el estado de registro de comandos puede no persistir correctamente a través de la transición.
• Histórico: Error de tamaño de carga útil de setMyCommands en 2026.3.x — Una versión anterior tenía un error relacionado donde 60+ comandos excedían el presupuesto conservador de carga útil. Esto fue parcialmente abordado en 2026.4.14 con el límite de 5700 caracteres, pero introdujo la regresión de inicialización.

Referencia Cruzada

• OpenClaw GitHub: Busque issues etiquetados con telegram + commands para parches en curso
• Documentación de grammy: https://grammy.dev/plugins/commands — Detalles de la API de registro del menú de comandos del bot
• API del Bot de Telegram: setMyCommands — Especificación oficial de la API para registro de comandos