Manifestaciones principales

El bot de Telegram acepta y procesa mensajes normalmente, pero el registro de comandos nativos nunca ocurre durante el inicio del gateway.

Patrones de salida de diagnóstico

Entradas de registro faltantes bash

Buscar setMyCommands en los registros

grep -i “setMyCommands|setMyCommands|commands.native|BOT_COMMANDS” /var/log/openclaw/gateway.log

Esperado: Múltiples entradas como:

[INFO] TelegramProvider: Registering native commands via setMyCommands

[INFO] TelegramProvider: Successfully registered 8 bot commands

[DEBUG] bot.api.setMyCommands called with

Actual: Cero coincidencias

Sin menú de autocompletado Cuando se escribe / en un DM de Telegram con el bot, no aparece ningún menú de comandos. La función de autocompletado de comandos con barra diagonal requiere que se haya llamado a setMyCommands durante la inicialización.

La configuración parece correcta json { “channels”: { “telegram”: { “enabled”: true, “token”: “123456789:ABCdefGHI…”, “commands”: { “native”: true, “nativeSkills”: true } } } }

Comandos de verificación de CLI

bash

Verificar si los comandos están registrados a través de la API de Telegram

curl -s “https://api.telegram.org/bot/getMyCommands” | jq .

Esperado después del registro exitoso:

{

“ok”: true,

“result”: [

{“command”: “help”, “description”: “Show available commands”},

{“command”: “status”, “description”: “Check system status”},

…

]

}

Actual (error presente):

{

“ok”: true,

“result”: []

}

Características de fallo silencioso

• No hay entradas de registro de nivel ERROR o WARN
• El inicio del gateway se completa exitosamente (código de salida 0)
• El bot de Telegram responde a los mensajes normalmente
• Los comandos de skills se ejecutan correctamente cuando se llaman manualmente
• Solo falta el menú/autocompletado de comandos

Contexto arquitectónico

El registro de setMyCommands ocurre en la secuencia de inicialización del proveedor de Telegram. La ruta del código existe en dist/bot-BwMz6R6-.js pero nunca se alcanza debido a una o más condiciones de retorno anticipado.

Causas raíz principales

1. Desajuste del esquema de configuración

El proveedor de Telegram verifica commands.native como un valor de cadena, pero el validador del esquema de configuración convierte "true" a booleano true o "auto" a un enum inesperado. La verificación condicional falla silenciosamente:

javascript // En la inicialización del proveedor (inferido del comportamiento) if (config.commands?.native !== ‘auto’ && config.commands?.native !== true) { return early; // Sale antes de que se llame a setMyCommands }

// Problema: Si config.commands.native es booleano true (no cadena ’true’) // o si la ruta es channels.telegram.commands.native vs estructura anidada // La comparación se evalúa incorrectamente

2. Condición de carrera en inicialización asíncrona

El proveedor de Telegram puede inicializarse antes de que se complete el registro de comandos:

Inicio del Gateway │ ├── Cargar configuración de canales │ │ │ └── TelegramProvider.init() │ │ │ └── bot.api.setMyCommands(retryCommands) │ │ │ └── retryCommands = [] ← Comandos aún no cargados │ └── Cargar Plugins/Skills │ └── Poblar registro de comandos

Cuando retryCommands se evalúa en el momento de inicialización del proveedor, la lista de comandos de skills está vacía porque los plugins se cargan después de que se inicializa el proveedor.

3. Errores ignorados en la cadena de Promesas

La llamada a setMyCommands está envuelta en una Promesa con un manejador .catch() que ignora los errores sin registrarlos:

javascript // Inferido del síntoma “sin error, sin advertencia” bot.api.setMyCommands(retryCommands) .then(() => logger.info(‘Commands registered’)) .catch(err => { // Error ignorado aquí - sin registro // void err o bloque catch vacío });

4. Anulación de feature flag

Una variable de entorno o feature flag puede estar deshabilitando el registro de comandos globalmente:

bash

Estas variables de entorno evitarían el registro

OPENCLAW_TELEGRAM_COMMANDS_ENABLED=false OPENCLAW_DISABLE_NATIVE_COMMANDS=1 TELEGRAM_SKIP_COMMAND_REGISTRATION=true

5. Error en la evaluación de condición del proveedor

El proveedor de Telegram puede tener una condición de guardia que se evalúa incorrectamente:

javascript // Problema probable en la ruta del código class TelegramProvider { async start() { // Bug: Verifica la ruta de propiedad incorrecta if (!this.config.channel?.commands?.native) { return this.startPolling(); // Omite el registro de comandos }

    // Este código nunca se alcanza
    await this.registerCommands();
}

}

// La ruta correcta debería ser: if (!this.config.commands?.native) { … }

Diagrama de secuencia de fallos

┌─────────────────────────────────────────────────────────────┐ │ Inicio del Gateway │ ├─────────────────────────────────────────────────────────────┤ │ 1. Config.load() → Combina JSON + vars de entorno │ │ └── channels.telegram.commands.native: true (booleano) │ │ │ │ 2. PluginRegistry.load() │ │ └── Skills cargados, registro de comandos vacío │ │ │ │ 3. TelegramProvider.init() │ │ └── Verifica: config.commands?.native !== ‘auto’ │ │ └── Booleano true !== Cadena ‘auto’ → sale temprano │ │ │ │ 4. setMyCommands() nunca llamado │ │ └── retryCommands: [] │ │ │ │ 5. Gateway listo, polling activo │ │ └── Comandos no registrados, sin errores en registros │ └─────────────────────────────────────────────────────────────┘

Desencadenantes específicos del entorno

Estrategia de corrección 1: Corrección de ruta de configuración

El problema más probable es una ruta de configuración incorrecta o un error de coincidencia de tipo. OpenClaw 2026.4.14 espera una estructura de esquema específica.

Paso 1: Verificar el esquema de configuración

bash

Verificar la configuración cargada realmente

cat ~/.openclaw/openclaw.json | jq ‘.channels.telegram.commands’

Paso 2: Aplicar la configuración correcta

Edita tu openclaw.json:

json // ANTES (incorrecto - puede tener ruta incorrecta o tipo incorrecto) { “channels”: { “telegram”: { “commands”: { “native”: true } } } }

// DESPUÉS (esquema correcto) { “channels”: { “telegram”: { “commands”: { “native”: “auto” } } } }

Nota: Usa la cadena "auto" en lugar del booleano true. El código compara con los literales de cadena 'auto' y true (cadena), no con el booleano true.

Paso 3: Reiniciar el Gateway

bash

macOS LaunchAgent

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Linux systemd

sudo systemctl restart openclaw-gateway

Docker

docker restart openclaw-gateway

Directo (desarrollo)

pkill -f openclaw-gateway && openclaw gateway start

Estrategia de corrección 2: Registro manual de comandos (inmediato)

Para alivio inmediato mientras se investiga el problema de inicio:

Paso 1: Identificar los comandos requeridos

bash

Listar todos los comandos registrados de OpenClaw

grep -r “BOT_COMMANDS|registerCommand|command.*description”
~/.openclaw/node_modules/openclaw/dist/ 2>/dev/null
| head -30

Paso 2: Registrar a través de la API de Telegram

bash

Reemplazar con tu token de bot

curl -X POST “https://api.telegram.org/bot/setMyCommands”
-H “Content-Type: application/json”
-d ‘{ “commands”: [ {“command”: “help”, “description”: “Show available commands and usage”}, {“command”: “status”, “description”: “Display system status and health”}, {“command”: “new”, “description”: “Start a new conversation thread”}, {“command”: “reset”, “description”: “Reset conversation context”}, {“command”: “model”, “description”: “Show or change the active AI model”}, {“command”: “skills”, “description”: “List available skill plugins”} ], “scope”: {“type”: “default”} }’

Paso 3: Verificar el registro

bash curl -s “https://api.telegram.org/bot/getMyCommands” | jq .

Salida esperada: json { “ok”: true, “result”: [ {“command”: “help”, “description”: “Show available commands and usage”}, {“command”: “status”, “description”: “Display system status and health”} ] }

Estrategia de corrección 3: Anulación de variable de entorno

Si la ruta de configuración es correcta pero el proveedor aún omite el registro:

Paso 1: Establecer variable de entorno de depuración

bash

Agregar a tu perfil de shell o EnvironmentVariables de LaunchAgent

export OPENCLAW_TELEGRAM_COMMANDS_DEBUG=1 export DEBUG=openclaw:telegram:commands

Paso 2: Limpiar caché de runtime

bash rm -rf ~/.openclaw/cache/* rm -rf ~/.openclaw/runtime/state.json

Paso 3: Reiniciar con registro detallado

bash

Ejecutar con salida de depuración

openclaw gateway start –log-level debug 2>&1 | grep -i “command|setMy”

Estrategia de corrección 4: Hotfix a nivel de código

Si tienes acceso para modificar el código de runtime:

Paso 1: Localizar el archivo del proveedor

bash

Encontrar el proveedor de Telegram

find ~/.openclaw/node_modules -name “provider-telegram*.js” -o
-name “TelegramProvider.js” 2>/dev/null

Paso 2: Corregir la verificación condicional

Localiza la condición de retorno anticipado y corrige la comparación:

javascript // ANTES (con error) if (config.commands?.native !== ‘auto’ && config.commands?.native !== true) { return early; }

// DESPUÉS (corregido) if (config.commands?.native === false || config.commands?.native === ‘false’) { return early; }

Paso 3: Agregar registro de errores al bloque Catch

javascript // Encontrar la llamada setMyCommands y agregar registro try { await bot.api.setMyCommands(retryCommands); logger.info(TelegramProvider: Registered ${retryCommands.length} native commands); } catch (err) { logger.error(‘TelegramProvider: Failed to register commands’, { error: err.message }); // No ignorar - dejar que se propague }

Estrategia de corrección 5: Corrección del orden de inicio del proveedor

Si el problema es una condición de carrera con la carga de plugins:

Paso 1: Agregar dependencia de inicio

Para LaunchAgent (ai.openclaw.gateway.plist): xml KeepAlive SuccessfulExit StartInterval 5

Para systemd (openclaw-gateway.service): ini [Unit] After=network.target After=time-sync.target Wants=time-sync.target

[Service] ExecStartPre=/bin/sleep 3 Restart=on-failure RestartSec=5

Pasos de verificación inmediatos

Paso 1: Verificar registros del gateway para registro de comandos

bash

Monitorear registros con filtro de registro de comandos

tail -f /var/log/openclaw/gateway.log 2>/dev/null | grep -E “setMyCommands|commands.*registered|native.*command”

O para inicio reciente

grep -E “setMyCommands|commands.*registered|native.*command”
/var/log/openclaw/gateway.log | tail -20

Salida esperada:

[TIMESTAMP] INFO TelegramProvider: Initializing native command registration [TIMESTAMP] INFO TelegramProvider: Built-in commands loaded: help, status, new, reset, model [TIMESTAMP] INFO TelegramProvider: Skill commands loaded: 4 commands [TIMESTAMP] INFO TelegramProvider: Calling setMyCommands with 8 commands [TIMESTAMP] INFO TelegramProvider: Successfully registered 8 bot commands via setMyCommands

Salida actual (error aún presente):

No se encontraron entradas coincidentes

Paso 2: Verificar a través de la API de Telegram

bash

Reemplazar con tu token de bot

TELEGRAM_TOKEN=“123456789:ABCdefGHI…”

curl -s “https://api.telegram.org/bot${TELEGRAM_TOKEN}/getMyCommands" | jq .

Esperado: json { “ok”: true, “result”: [ { “command”: “help”, “description”: “Show available commands” }, { “command”: “status”, “description”: “Display system status” } ] }

Actual (sin corregir): json { “ok”: true, “result”: [] }

Paso 3: Probar menú de comandos en Telegram

1. Abre un DM con tu bot de Telegram
2. Escribe / — el menú de comandos debe aparecer con autocompletado
3. Prueba cada comando: /help, /status, /new, /reset

Esperado: El menú de comandos aparece inmediatamente al escribir /

Actual (sin corregir): No aparece ningún menú; los comandos deben escribirse manualmente

Script de verificación automatizado

bash #!/bin/bash

verify-telegram-commands.sh

TELEGRAM_TOKEN="${OPENCLAW_TELEGRAM_TOKEN:-}”

if [ -z “$TELEGRAM_TOKEN” ]; then echo “ERROR: OPENCLAW_TELEGRAM_TOKEN no está definido” exit 1 fi

echo “=== Verificación de comandos del bot de Telegram ===” echo ""

Verificar comandos registrados

RESPONSE=$(curl -s “https://api.telegram.org/bot${TELEGRAM_TOKEN}/getMyCommands") COUNT=$(echo “$RESPONSE” | jq ‘.result | length’)

echo “Comandos registrados: $COUNT” echo “$RESPONSE” | jq -r ‘.result[] | " /” + .command + " - " + .description’

if [ “$COUNT” -gt 0 ]; then echo "" echo “✓ ÉXITO: Los comandos están registrados” exit 0 else echo "" echo “✗ FALLO: No hay comandos registrados” exit 1 fi

Ejecutar la verificación: bash chmod +x verify-telegram-commands.sh ./verify-telegram-commands.sh

Salida esperada:

=== Telegram Bot Commands Verification ===

Registered commands: 6 /help - Show available commands /status - Display system status /new - Start a new conversation /reset - Reset conversation context /model - Show or change AI model /skills - List skill plugins

✓ SUCCESS: Commands are registered

Lista de verificación de análisis de registros

Después de aplicar las correcciones, verifica que estas entradas de registro aparezcan al inicio:

Errores de configuración

1. Error de coerción de tipo

json // INCORRECTO - booleano en lugar de cadena “native”: true

// CORRECTO - valor de cadena “native”: “auto”

El código del proveedor probablemente compara con literales de cadena. El booleano true nunca será igual a la cadena "true" en JavaScript.

2. Errores de ruta anidada

json // INCORRECTO - anidación incorrecta “telegram”: { “plugin”: { “commands”: { “native”: true } } }

// CORRECTO - ruta esperada “telegram”: { “commands”: { “native”: “auto” } }

3. Anulación de variable de entorno ignorada

bash

Establecida en shell pero no pasada a LaunchAgent

export OPENCLAW_TELEGRAM_COMMANDS_ENABLED=true # Ignorado por LaunchAgent

Correcto: Agregar a EnvironmentVariables del plist

EnvironmentVariables OPENCLAW_TELEGRAM_COMMANDS_ENABLED true

Trampas específicas de plataforma

macOS LaunchAgent

Contenedor Docker

Linux Systemd

Errores de runtime

1. Token no coincide

Si el token del bot usado en openclaw.json difiere del token en variables de entorno, getMyCommands y setMyCommands referenciarán diferentes bots.

bash

Verificar consistencia del token

jq ‘.channels.telegram.token’ ~/.openclaw/openclaw.json echo $OPENCLAW_TELEGRAM_TOKEN

2. Alcance de comandos de BotFather

Los bots de Telegram pueden tener comandos registrados en diferentes alcances:

• default - Todos los chats
• commands_in_private - Solo chats privados
• Alcance por chat con chat_id

Si los comandos fueron establecidos previamente con un alcance a través de BotFather, setMyCommands puede no sobrescribirlos.

bash

Limpiar todos los alcances de comandos

curl -X POST “https://api.telegram.org/bot/deleteMyCommands”
-H “Content-Type: application/json”
-d ‘{“scope”: {“type”: “all_private_chats”}}’

curl -X POST “https://api.telegram.org/bot/deleteMyCommands”
-H “Content-Type: application/json”
-d ‘{}’ # Eliminar alcance por defecto también

3. Limitación de tasa

Telegram limita setMyCommands a aproximadamente 1 llamada por segundo. Si el gateway se reinicia rápidamente durante la depuración, la API puede rechazar las llamadas.

bash

Verificar errores de límite de tasa

grep -i “Too Many Requests|retry_after” /var/log/openclaw/gateway.log

4. Restricciones del modo del bot

Los bots en ciertos modos (por ejemplo, inline-only, restringidos) no pueden usar setMyCommands.

Errores de desarrollo

Hot Reload omite el proveedor

Algunas implementaciones de hot-reload re-inicializan los plugins pero no el proveedor de Telegram. Los comandos nunca se vuelven a registrar.

bash

Se requiere reinicio completo, no solo recarga de config

pkill -f openclaw openclaw gateway start

El registro de depuración silencia los errores

Los ajustes altos de logLevel (debug, trace) a veces pueden causar que los errores se registren en un nivel que se filtra.

bash

Habilitar explícitamente todos los registros relacionados con Telegram

openclaw gateway start –log-level debug –log-filter “telegram,commands,provider”

Errores directamente relacionados

Problemas históricamente relacionados

Síntomas similares en otros canales

Referencias externas

• Telegram Bot API: setMyCommands — https://core.telegram.org/bots/api#setmycommands
• Telegram Bot API: getMyCommands — https://core.telegram.org/bots/api#getmycommands
• grammY Commands Plugin — https://grammy.dev/plugins/commands
• OpenClaw Config Schema — ~/.openclaw/node_modules/openclaw/schema/config.json

Patrones de registro relacionados

Buscar estos patrones en los registros del gateway al diagnosticar problemas similares:

bash

Todo el registro relacionado con Telegram

grep -E “TelegramProvider|Telegram.*provider|telegram” /var/log/openclaw/gateway.log

Intentos de registro de comandos

grep -E “setMyCommands|register.*command|command.*registration” /var/log/openclaw/gateway.log

Errores de API

grep -E “api.*error|api.*fail|telegram.*error” /var/log/openclaw/gateway.log

Carga de configuración

grep -E “config.*load|channels.*init|provider.*start” /var/log/openclaw/gateway.log