Primäre Manifestationen

Der Telegram-Bot nimmt Nachrichten normal an und verarbeitet sie, aber die native Befehlsregistrierung findet beim Gateway-Start niemals statt.

Diagnoseausgabe-Muster

Fehlende Protokolleinträge bash

Search for setMyCommands in logs

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

Expected: Multiple entries like:

[INFO] TelegramProvider: Registering native commands via setMyCommands

[INFO] TelegramProvider: Successfully registered 8 bot commands

[DEBUG] bot.api.setMyCommands called with

Actual: Zero matches

Kein Autovervollständigungsmenü Wenn Sie / in einem Telegram-DM mit dem Bot eingeben, erscheint kein Befehlsmenü. Die Slash-Befehl-Autovervollständigungsfunktion erfordert, dass setMyCommands während der Initialisierung aufgerufen wurde.

Konfiguration erscheint korrekt json { “channels”: { “telegram”: { “enabled”: true, “token”: “123456789:ABCdefGHI…”, “commands”: { “native”: true, “nativeSkills”: true } } } }

CLI-Verifizierungsbefehle

bash

Check if commands are registered via Telegram API

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

Expected after successful registration:

{

“ok”: true,

“result”: [

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

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

…

]

}

Actual (bug present):

{

“ok”: true,

“result”: []

}

Merkmale des stillen Fehlers

• Keine ERROR- oder WARN-Protokolleinträge auf Anwendungsebene
• Gateway-Start wird erfolgreich abgeschlossen (Exit-Code 0)
• Telegram-Bot reagiert normal auf Nachrichten
• Skill-Befehle werden korrekt ausgeführt, wenn manuell aufgerufen
• Nur das Befehlsmenü/die Autovervollständigung fehlt

Architektonischer Kontext

Die setMyCommands-Registrierung erfolgt in der Initialisierungssequenz des Telegram-Providers. Der Codepfad existiert in dist/bot-BwMz6R6-.js, wird aber aufgrund einer oder mehrerer Frührückgabe-Bedingungen nie erreicht.

Primäre Ursachen

1. Konfigurationsschema-Konflikt

Der Telegram-Provider prüft commands.native als Zeichenkettenwert, aber der Konfigurationsschema-Validator wandelt "true" in boolesches true oder "auto" in einen unerwarteten Enum um. Die Bedingungsprüfung schlägt still fehl:

javascript // In provider initialization (inferred from behavior) if (config.commands?.native !== ‘auto’ && config.commands?.native !== true) { return early; // Exits before setMyCommands is called }

// Problem: If config.commands.native is boolean true (not string ’true’) // or if the path is channels.telegram.commands.native vs nested structure // The comparison evaluates incorrectly

2. Asynchroner Initialisierungs-Wettlaufbedingung

Der Telegram-Provider kann initialisieren, bevor die Befehlsregistrierung gefüllt ist:

Gateway Start │ ├── Load Channels Config │ │ │ └── TelegramProvider.init() │ │ │ └── bot.api.setMyCommands(retryCommands) │ │ │ └── retryCommands = [] ← Commands not yet loaded │ └── Load Plugins/Skills │ └── Populate command registry

Wenn retryCommands zum Zeitpunkt der Provider-Initialisierung ausgewertet wird, ist die Skill-Befehlsliste leer, da Plugins nach der Provider-Initialisierung laden.

3. Fehlerunterdrückung in Promise-Kette

Der setMyCommands-Aufruf ist in ein Promise mit einem .catch()-Handler eingewickelt, der Fehler unterdrückt, ohne zu protokollieren:

javascript // Inferred from symptom “no error, no warning” bot.api.setMyCommands(retryCommands) .then(() => logger.info(‘Commands registered’)) .catch(err => { // Error swallowed here - no logging // void err or empty catch block });

4. Feature-Flag-Überschreibung

Eine Umgebungsvariable oder ein Feature-Flag könnte die Befehlsregistrierung global deaktivieren:

bash

These environment variables would prevent registration

OPENCLAW_TELEGRAM_COMMANDS_ENABLED=false OPENCLAW_DISABLE_NATIVE_COMMANDS=1 TELEGRAM_SKIP_COMMAND_REGISTRATION=true

5. Provider-Bedingungsauswertungsfehler

Der Telegram-Provider könnte eine Guard-Bedingung haben, die falsch ausgewertet wird:

javascript // Probable code path issue class TelegramProvider { async start() { // Bug: Checks wrong property path if (!this.config.channel?.commands?.native) { return this.startPolling(); // Skips command registration }

    // This code is never reached
    await this.registerCommands();
}

}

// Correct path should be: if (!this.config.commands?.native) { … }

Fehlersequenzdiagramm

┌─────────────────────────────────────────────────────────────┐ │ Gateway Startup │ ├─────────────────────────────────────────────────────────────┤ │ 1. Config.load() → Merges JSON + env vars │ │ └── channels.telegram.commands.native: true (boolean) │ │ │ │ 2. PluginRegistry.load() │ │ └── Skills loaded, command registry empty │ │ │ │ 3. TelegramProvider.init() │ │ └── Checks: config.commands?.native !== ‘auto’ │ │ └── Boolean true !== String ‘auto’ → exits early │ │ │ │ 4. setMyCommands() never called │ │ └── retryCommands: [] │ │ │ │ 5. Gateway ready, polling active │ │ └── Commands not registered, no errors logged │ └─────────────────────────────────────────────────────────────┘

Plattformspezifische Auslöser

Lösungsstrategie 1: Konfigurationspfad-Korrektur

Das wahrscheinlichste Problem ist ein falscher Konfigurationspfad oder ein Typ-Konflikt. OpenClaw 2026.4.14 erwartet eine spezifische Schemastruktur.

Schritt 1: Konfigurationsschema überprüfen

bash

Check actual loaded configuration

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

Schritt 2: Korrekte Konfiguration anwenden

Bearbeiten Sie Ihre openclaw.json:

json // BEFORE (incorrect - may be wrong path or type) { “channels”: { “telegram”: { “commands”: { “native”: true } } } }

// AFTER (correct schema) { “channels”: { “telegram”: { “commands”: { “native”: “auto” } } } }

Hinweis: Verwenden Sie die Zeichenkette "auto" anstelle des booleschen true. Der Code vergleicht mit Zeichenkettenliteralen 'auto' und true (Zeichenkette), nicht mit booleschem true.

Schritt 3: Gateway neu starten

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

Direct (development)

pkill -f openclaw-gateway && openclaw gateway start

Lösungsstrategie 2: Manuelle Befehlsregistrierung (Sofortmaßnahme)

Für sofortige Abhilfe während der Untersuchung des Startproblems:

Schritt 1: Erforderliche Befehle identifizieren

bash

List all registered commands from OpenClaw

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

Schritt 2: Über Telegram-API registrieren

bash

Replace with your bot token

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”} }’

Schritt 3: Registrierung verifizieren

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

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

Lösungsstrategie 3: Umgebungsvariablen-Überschreibung

Wenn der Konfigurationspfad korrekt ist, der Provider aber trotzdem die Registrierung überspringt:

Schritt 1: Debug-Umgebungsvariable setzen

bash

Add to your shell profile or LaunchAgent plist EnvironmentVariables

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

Schritt 2: Laufzeitcache leeren

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

Schritt 3: Mit ausführlicher Protokollierung neu starten

bash

Run with debug output

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

Lösungsstrategie 4: Code-Level-Hotfix

Wenn Sie Zugriff auf die Änderung des Laufzeitcodes haben:

Schritt 1: Provider-Datei finden

bash

Find the Telegram provider

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

Schritt 2: Bedingte Prüfung patchen

Finden Sie die Frührückgabe-Bedingung und korrigieren Sie den Vergleich:

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

// AFTER (fixed) if (config.commands?.native === false || config.commands?.native === ‘false’) { return early; }

Schritt 3: Fehlerprotokollierung zum Catch-Block hinzufügen

javascript // Find the setMyCommands call and add logging 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 }); // Don’t swallow - let it propagate }

Lösungsstrategie 5: Provider-Startreihenfolge-Fix

Wenn das Problem eine Wettlaufbedingung mit dem Plugin-Laden ist:

Schritt 1: Startabhängigkeit hinzufügen

Für LaunchAgent (ai.openclaw.gateway.plist): xml KeepAlive SuccessfulExit StartInterval 5

Für 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

Sofortige Verifizierungsschritte

Schritt 1: Gateway-Protokolle auf Befehlsregistrierung prüfen

bash

Tail logs with command registration filter

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

Or for recent startup

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

Erwartete Ausgabe:

[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

Tatsächliche Ausgabe (Bug noch vorhanden):

No matching entries found

Schritt 2: Über Telegram-API verifizieren

bash

Replace with your bot token

TELEGRAM_TOKEN=“123456789:ABCdefGHI…”

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

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

Tatsächlich (nicht behoben): json { “ok”: true, “result”: [] }

Schritt 3: Befehlsmenü in Telegram testen

1. Öffnen Sie einen DM mit Ihrem Telegram-Bot
2. Geben Sie / ein — das Befehlsmenü sollte mit Autovervollständigung erscheinen
3. Testen Sie jeden Befehl: /help, /status, /new, /reset

Erwartet: Befehlsmenü erscheint sofort bei Eingabe von /

Tatsächlich (nicht behoben): Kein Menü erscheint; Befehle müssen manuell eingegeben werden

Automatisiertes Verifizierungsskript

bash #!/bin/bash

verify-telegram-commands.sh

TELEGRAM_TOKEN="${OPENCLAW_TELEGRAM_TOKEN:-}”

if [ -z “$TELEGRAM_TOKEN” ]; then echo “ERROR: OPENCLAW_TELEGRAM_TOKEN not set” exit 1 fi

echo “=== Telegram Bot Commands Verification ===” echo ""

Check registered commands

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

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

if [ “$COUNT” -gt 0 ]; then echo "" echo “✓ SUCCESS: Commands are registered” exit 0 else echo "" echo “✗ FAILURE: No commands registered” exit 1 fi

Führen Sie die Verifizierung aus: bash chmod +x verify-telegram-commands.sh ./verify-telegram-commands.sh

Erwartete Ausgabe:

=== 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

Protokollanalyse-Checkliste

Prüfen Sie nach Anwendung der Fixes, ob diese Protokolleinträge beim Start erscheinen:

Konfigurationsfallen

1. Typumwandlungs-Konflikt

json // INCORRECT - boolean instead of string “native”: true

// CORRECT - string value “native”: “auto”

Der Provider-Code vergleicht wahrscheinlich mit Zeichenkettenliteralen. Boolean true wird niemals gleich der Zeichenkette "true" in JavaScript sein.

2. Verschachtelte Pfadfehler

json // INCORRECT - wrong nesting “telegram”: { “plugin”: { “commands”: { “native”: true } } }

// CORRECT - expected path “telegram”: { “commands”: { “native”: “auto” } }

3. Umgebungsvariablen-Überschreibung ignoriert

bash

Set in shell but not passed to LaunchAgent

export OPENCLAW_TELEGRAM_COMMANDS_ENABLED=true # Ignored by LaunchAgent

Correct: Add to plist EnvironmentVariables

EnvironmentVariables OPENCLAW_TELEGRAM_COMMANDS_ENABLED true

Plattformspezifische Fallen

macOS LaunchAgent

Docker-Container

Linux Systemd

Laufzeitfallen

1. Token-Konflikt

Wenn das Bot-Token in openclaw.json sich vom Token in Umgebungsvariablen unterscheidet, referenzieren getMyCommands und setMyCommands verschiedene Bots.

bash

Verify token consistency

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

2. BotFather-Befehlsbereich

Telegram-Bots können Befehle in verschiedenen Bereichen registriert haben:

• default - Alle Chats
• commands_in_private - Nur private Chats
• Pro-Chat-Bereich mit chat_id

Wenn Befehle zuvor mit einem Bereich über BotFather gesetzt wurden, überschreibt setMyCommands diese möglicherweise nicht.

bash

Clear all command scopes

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 ‘{}’ # Delete default scope too

3. Rate-Limiting

Telegram begrenzt setMyCommands auf ca. 1 Aufruf pro Sekunde. Wenn das Gateway während des Debuggings schnell neu startet, lehnt die API möglicherweise Aufrufe ab.

bash

Check for rate limit errors

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

4. Bot-Modus-Einschränkungen

Bots in bestimmten Modi (z.B. inline-only, eingeschränkt) können setMyCommands nicht verwenden.

Entwicklungsfallen

Hot-Reload verfehlt Provider

Einige Hot-Reload-Implementierungen initialisieren Plugins neu, aber nicht den Telegram-Provider. Befehle werden nie neu registriert.

bash

Full restart required, not just config reload

pkill -f openclaw openclaw gateway start

Debug-Protokollierung unterdrückt Fehler

Hohe logLevel-Einstellungen (debug, trace) können manchmal dazu führen, dass Fehler auf einer Ebene protokolliert werden, die herausgefiltert wird.

bash

Explicitly enable all Telegram-related logs

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

Direkt zugehörige Fehler

Historisch zugehörige Probleme

Ähnliche Symptome in anderen Kanälen

Externe Referenzen

• 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

Zugehörige Protokollmuster

Suchen Sie nach diesen Mustern in Gateway-Protokollen bei der Diagnose ähnlicher Probleme:

bash

All Telegram-related logging

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

Command registration attempts

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

API errors

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

Configuration loading

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