Telegram setMyCommands wird bei Gateway-Neustart in OpenClaw 2026.4.14 nicht aufgerufen

• Primäres Symptom: Alle Telegram-Bot-Slash-Befehle (42–58 Befehle) verschwinden nach einem Gateway-Neustart aus dem Menü.
• API-Verifizierung: Der getMyCommands Telegram Bot API-Aufruf gibt eine leere Liste zurück:

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

• Fehlende Protokollierung: Die Gateway-Startprotokolle enthalten nicht die erwartete Befehlsregistrierungsnachricht:

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

• Verhaltensinkonsistenz: Frühere Neustarts in derselben Sitzung haben die Befehle erfolgreich registriert, während spätere Neustarts die Registrierung vollständig überspringen. Dies deutet auf einen nicht-deterministischen Initialisierungsfehler hin.
• Workaround-Bestätigung: Das manuelle Aufrufen von setMyCommands über die Bot API stellt die Befehle erfolgreich wieder her, was bestätigt, dass die Telegram API selbst funktionsfähig ist und das Problem in der OpenClaw-Initialisierungssequenz liegt.

Diagnosebefehl zur Symptombestätigung

# Prüfen, ob Befehle registriert sind (sollte nach erfolgreicher Initialisierung ein nicht-leeres Array zurückgeben)
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length'

# Erwartete Ausgabe: > 0, wenn Befehle registriert sind
# Symptomatische Ausgabe: 0

Technische Analyse

Die Grundursache liegt in einem Race Condition oder einer Initialisierungsreihenfolge-Abhängigkeit, die in OpenClaw 2026.4.14 (Commit 323493f) eingeführt wurde. Die Funktion registerTelegramNativeCommands, die sich in dem kompilierten Bundle bot-BwMz6R6-.js befindet, wird während der Gateway-Startsequenz nicht aufgerufen.

Fehlersequenz

1. Gateway-Start: Das OpenClaw-Gateway initialisiert alle konfigurierten Kanäle, einschließlich des Telegram-Anbieters (grammy-basiert).
2. Anbieter-Initialisierung: Der Telegram-Anbieter emittiert ein ready-Event oder ein äquivalentes Lebenszyklussignal nach erfolgreicher Verbindung mit der Telegram Bot API.
3. Befehlsregistrierungs-Auslöser: Die Funktion registerTelegramNativeCommands sollte bei Anbieter-Bereitschaft aufgerufen werden, um das Slash-Befehlsmenü zu registrieren.
4. Fehlerpunkt: In Version 2026.4.14 ist der Registrierungsauslöser entweder:
• An ein Event angehängt, das feuert, bevor die Befehlsdefinitionen vollständig geladen sind
• Subjekt einer Bedingungsprüfung, die aufgrund von Timing false auswertet
• Blockiert durch eine nicht behandelte Promise-Rejection, die still fehlschlägt

Architektonische Inkonsistenz

Das inkonsistente Verhalten (manche Neustarts funktionieren, andere nicht) deutet auf eine zeitunabhängige Race Condition hin. Mögliche beitragende Faktoren:

• Asynchrone Initialisierungskette: Wenn die Befehlsregistrierung von externer Datenabfrage abhängt (z.B. Laden von Befehlsdefinitionen aus einer Datenbank oder einem Config-Store), können Netzwerklatenzschwankungen dazu führen, dass die Registrierung ausgeführt wird, bevor die Daten verfügbar sind.
• Event-Handler-Anhänge-Timing: Der ready-Event-Handler könnte angehängt werden, nachdem das Event auf schnell startenden Instanzen bereits gefeuert hat.
• Modul-Importreihenfolge: ES-Module-Initialisierungsreihenfolge-Unterschiede zwischen Heiß- und Kaltstarts.
• Verbindungspool-Zustand: In langlebigen Gateway-Sitzungen kann der akkumulierte Verbindungspool-Zustand das Initialisierungs-Timing beeinflussen.

Betroffener Codepfad

// Vereinfachte Darstellung des betroffenen Initialisierungspfads
async function initializeTelegramProvider(config) {
    const provider = new GrammyTelegramProvider(config);
    
    // Dieses Handler-Anhängen kann mit dem ready-Event konkurrieren
    provider.on('ready', async () => {
        // Dieser Block wird möglicherweise nicht ausgeführt, wenn 'ready' bereits gefeuert hat
        await registerTelegramNativeCommands(provider, config.commands);
    });
    
    await provider.start(); // ready-Event feuert hier auf schnellen Systemen
}

Sofortige Workarounds

Option 1: Manuelle Befehlsregistrierung (Temporäre Lösung)

# Verwendung von curl zum direkten Setzen von Befehlen über die 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"}
    ]
  }'

# Überprüfen, ob die Antwort {"ok": true, ...} enthält

Option 2: Cron-Job als Übergangslösung

# Zur crontab hinzufügen (crontab -e)
# Gateway neu starten und sofort Befehle erneut registrieren
@reboot sleep 30 && /opt/openclaw/scripts/reregister-commands.sh

Option 3: Erzwungene Neuregistrierung über OpenClaw CLI

# Falls OpenClaw ein CLI-Tool bereitstellt
openclaw commands register --channel telegram --force

# Oder über die Management-API
curl -X POST "http://localhost:3000/api/channels/telegram/commands/reload" \
  -H "Authorization: Bearer ${MANAGEMENT_API_TOKEN}"

Definitive Lösung: Versionsbereinigung

Schritt 1: Aktuelle Version identifizieren

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

Schritt 2: Auf vorherige stabile Version zurücksetzen

# Bei Verwendung von npm
npm install [email protected] --save

# Bei Verwendung von Docker
# docker-compose.yml bearbeiten
image: openclaw/openclaw:2026.4.13

# Neu erstellen und neu starten
docker-compose down && docker-compose up -d --build

Schritt 3: Auf feste Version aktualisieren (wenn verfügbar)

# OpenClaw GitHub-Releases auf 2026.4.15 oder später überwachen
# Sobald verfügbar:
npm install openclaw@latest --save
# oder
docker-compose pull && docker-compose up -d

Hot-Fix: Initialisierungsreihenfolge patchen

Warnung: Dies ist eine temporäre manuelle Korrektur; während eines Wartungsfensters anwenden.

# Das kompilierte Bundle finden
find /opt/openclaw -name "bot-BwMz6R6-.js" 2>/dev/null

# Original sichern
cp /opt/openclaw/dist/bot-BwMz6R6-.js /opt/openclaw/dist/bot-BwMz6R6-.js.bak

# Synchronen Registrierungsaufruf nach Anbieter-Initialisierung hinzufügen
# Vor dem existierenden ready-Handler einfügen:
# 
# VORHER (Zeile ~XXX):
# provider.on('ready', async () => {
#
# NACHHER (Patch):
# // Sofortiger Registrierungsversuch
# registerTelegramNativeCommands(provider, config.commands).catch(console.error);
# provider.on('ready', async () => {
#     await registerTelegramNativeCommands(provider, config.commands);
# });

Verifizierungsschritte nach der Korrektur

1. Gateway neu starten

# Für systemd-verwaltete Installationen
sudo systemctl restart openclaw-gateway

# Für Docker
docker-compose restart gateway

# Für PM2
pm2 restart openclaw

2. Gateway-Protokolle auf Befehlsregistrierung prüfen

# Auf die erwartete Protokollnachricht prüfen
sudo journalctl -u openclaw-gateway -f | grep -i "setMyCommands\|menu text exceeded\|Telegram menu"

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

3. Via Telegram Bot API verifizieren

# Anzahl der registrierten Befehle abrufen
COMMAND_COUNT=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length')
echo "Registrierte Befehle: ${COMMAND_COUNT}"

# Erwartet: > 0 (z.B. 42, 58, etc.)
# Fehler: 0

# Vollständige API-Antwort zum Debuggen
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq .

4. Im Telegram-Client testen

# Telegram öffnen und das /-Menü des Bots prüfen
# Alle zuvor verfügbaren Slash-Befehle sollten erscheinen
# Einen bekannten Befehl testen (z.B. /help), um die Funktionalität zu bestätigen

5. Mehrere aufeinanderfolgende Neustarts durchführen

# Konsistenz über Neustarts hinweg verifizieren (3 Mal ausführen)
for i in 1 2 3; do
    echo "=== Neustart $i ==="
    sudo systemctl restart openclaw-gateway
    sleep 10
    COUNT=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMyCommands" | jq '.result | length')
    echo "Befehlsanzahl: $COUNT"
    if [ "$COUNT" -eq 0 ]; then
        echo "FEHLER: Befehle bei Neustart $i nicht registriert"
        exit 1
    fi
done
echo "ERFOLG: Befehle über alle Neustarts hinweg konsistent registriert"

Verifizierungs-Ausstiegskriterien

• ✅ Gateway-Protokolle enthalten die "Telegram menu text exceeded"-Nachricht beim Start
• ✅ getMyCommands gibt ein nicht-leeres Array zurück
• ✅ Alle erwarteten Befehle erscheinen im /-Menü des Telegram-Bots
• ✅ Befehle bleiben nach mehreren aufeinanderfolgenden Neustarts bestehen
• ✅ Exit-Code 0 aus dem aufeinanderfolgenden Neustart-Testskript

• Annahme, dass alle Neustarts sich identisch verhalten: Der Bug manifestiert sich inkonsistent. Einige erfolgreiche Neustarts garantieren nicht, dass das Problem behoben ist. Verifizieren Sie immer mit dem aufeinanderfolgenden Neustart-Test.
• Log-Filterung ignorieren: Die relevante Protokollnachricht kann je nach Ihrer Protokollierungskonfiguration abgeschnitten oder auf mehrere Zeilen aufgeteilt sein. Verwenden Sie grep -i telegram ohne zusätzliche Filter, um sicherzustellen, dass Sie alle zugehörigen Einträge erfassen.
• Docker-Layer-Caching: Bei Verwendung von Docker müssen Sie nach Versionsänderungen einen erzwungenen Rebuild durchführen:

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

• Timing der Umgebungsvariablen: Die Umgebungsvariable TELEGRAM_BOT_TOKEN muss vor dem Gateway-Start gesetzt sein. Prüfen Sie, dass Ihre Umgebungsdatei korrekt geladen wird:

  # Umgebung prüfen
  env | grep TELEGRAM

• Node.js-Versions-Wechselwirkungen: Node 22.22.1 kann anderes asynchrones Timing aufweisen als andere Versionen. Testen Sie mit derselben Node-Version, die in der funktionierenden Umgebung verwendet wurde (vor dem Upgrade).
• Gateway-Hochverfügbarkeits-Konfigurationen: In Multi-Instanz-Setups sicherstellen, dass die Befehlsregistrierung idempotent ist. Doppelte setMyCommands-Aufrufe können die Rate-Limiting von Telegram auslösen.
• Fehlende Graceful Shutdown: Das abrupte Töten des Gateway-Prozesses kann die Telegram-Webhook-Verbindung in einem inkonsistenten Zustand hinterlassen. Immer Graceful-Shutdown-Signale verwenden:

  kill -SIGTERM <pid>  # Bevorzugt
  # Vermeiden: kill -SIGKILL <pid>

• Befehlsbeschreibungs-Länge: Wenn Sie benutzerdefinierte Befehle mit Beschreibungen hinzugefügt haben, die 256 Zeichen überschreiten, lehnt die Telegram API die gesamte Charge ab. Die Protokollnachricht "menu text exceeded" zeigt an, dass dieser Schutzmechanismus aktiv ist.
• Firewall/Proxy-Interferenz: Unternehmensproxys können die Telegram-API-Antwort verzögern und die Race Condition verschlimmern. Direkte Konnektivität testen:

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

• UNAUTHORIZED (401) bei Bot-API-Aufrufen — Typischerweise falsches Bot-Token, nicht dieses Problem. Token-Konfiguration prüfen, falls aufgetreten.
• Too Many Requests (429) von der Telegram API — Rate-Limiting während wiederholter Befehlsregistrierungsversuche. Exponentielles Backoff implementieren, wenn automatisierte Neuregistrierung implementiert wird.
• Leere getMyCommands-Antwort nach Upgrade (Issue #4521) — Dies ist das primäre Symptom des in diesem Leitfaden dokumentierten Bugs.
• Gateway kann keine Verbindung zu Telegram mit ETIMEDOUT herstellen — Netzwerk-Konnektivitätsproblem, nicht verwandt mit dem Befehlsregistrierungs-Bug, kann aber gleichzeitig auftreten.
• Befehle verschwinden nach Bot-Token-Rotation — Erwartetes Verhalten bei Verwendung eines neuen Tokens; Befehle sind token-spezifisch. Nach Token-Rotation erneut registrieren.
• Webhook vs. Polling-Modus-Inkonsistenz — Bei Wechsel zwischen Telegram-Verbindungsmodi wird der Befehlsregistrierungszustand möglicherweise nicht korrekt über den Übergang hinweg beibehalten.
• Historisch: setMyCommands-Payload-Größenfehler in 2026.3.x — Vorherige Version hatte einen verwandten Bug, bei dem 60+ Befehle das konservative Payload-Budget überschritten. Dies wurde in 2026.4.14 teilweise mit dem 5700-Zeichen-Limit behoben, führte aber die Initialisierungs-Regression ein.

Querverweis

• OpenClaw GitHub: Nach Issues suchen, die mit telegram + commands getaggt sind, für laufende Patches
• grammy-Dokumentation: https://grammy.dev/plugins/commands — Bot-Befehlsmenü-Registrierungs-API-Details
• Telegram Bot API: setMyCommands — Offizielle API-Spezifikation für Befehlsregistrierung