April 19, 2026 • バージョン: 2026.4.14

OpenClaw 2026.4.14 でゲートウェイ再起動時に Telegram setMyCommands が呼び出されない

OpenClaw 2026.4.14 にアップグレードした後、ゲートウェイ再起動時に Telegram ボットスラッシュコマンドが消えます。これは registerTelegramNativeCommands の初期化がスキップされる而导致し、結果として空のコマンドメニューになります。

🔍 症状

主な症状: ゲートウェイの再起動後、すべてのTelegramボットスラッシュコマンド（42〜58コマンド）がメニューから消える。
API検証: Telegram Bot APIのgetMyCommands呼び出しが空のリストを返す：
```
curl -s "https://api.telegram.org/bot<TOKEN>/getMyCommands"
{"ok":true,"result":[]}
```

ログの欠落: ゲートウェイ起動ログに予想されるコマンド登録メッセージが表示されない：

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

動作の不整合: 同じセッション内の Earlier restarts in the same session did successfully register commands, while later restarts skip registration entirely. This suggests a non-deterministic initialization failure.
回避策の確認: Bot API経由でsetMyCommandsを手動で呼び出すとコマンドが正常に復元されるため、Telegram API自体は機能しており、問題がOpenClawの初期化シーケンスにあることが確認できる。

症状確認用の診断コマンド

# 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

🧠 原因

技術的分析

根本原因は、OpenClaw 2026.4.14（コミット323493f）で導入された競合状態または初期化順序の依存関係にあります。コンパイル済みバンドルbot-BwMz6R6-.jsにあるregisterTelegramNativeCommands関数が、ゲートウェイ起動シーケンス中で呼び出されていません。

失敗の順序

ゲートウェイ起動: OpenClawゲートウェイが、Telegramプロバイダー（grammyベース）を含むすべての設定済みチャンネルを初期化する。
プロバイダーの初期化: TelegramプロバイダーがTelegram Bot APIへの正常接続時にreadyイベントまたは同等のライフサイクルシグナルを送信する。
コマンド登録トリガー: プロバイダーの準備完了時にスラッシュコマンドメニューを登録するため、registerTelegramNativeCommands関数を呼び出す必要がある。
失敗箇所: 2026.4.14では、登録トリガーが以下のいずれかの状態になっている：

コマンド定義が完全に読み込まれる前にトリガーされるイベントに接続されている
タイミング原因でfalseと評価される条件付きチェックの対象になっている
サイレントに失敗する未処理のPromise拒否によってブロックされている

アーキテクチャの不整合

不整合な動作（一部の再起動は成功し、他は失敗する）は、時間帯に依存しない競合状態を示している。考えられる要因：

非同期初期化チェーン: コマンド登録が外部データのフェッチ（データベースや設定ストアからのコマンド定義の読み込みなど）に依存している場合、ネットワークレイテンシーの変動により、データが利用可能になる前に登録が実行される可能性がある。
イベントハンドラー接続のタイミング: readyイベントハンドラーが、素早く起動するインスタンスではイベント発生後に接続される可能性がある。
モジュールインポート順序: ホット再起動とコールド再起動間のESモジュール初期化順序の違い。
接続プール状態: 長時間実行されるゲートウェイセッションでは、累積された接続プール状態が初期化タイミングに影響を与える可能性がある。

影響を受けるコードパス

// 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
}

🛠️ 解決手順

一時的な回避策

オプション1: 手動コマンド登録（一時的な修正）

# 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, ...}

オプション2: 応急処置としてのCronジョブ

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

オプション3: OpenClaw CLIで強制再登録

# 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}"

決定的な修正：バージョン修復

ステップ1: 現在のバージョンを確認

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

ステップ2: 前の安定バージョンにロールバック

# 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

ステップ3: 修正バージョンへのアップグレード（利用可能な場合）

# 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

ホットフィックス：初期化順序のパッチ

警告: これは一時的な手動修正です。メンテナンスウィンドウ中に適用してください。

# 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);
# });

🧪 検証

修正後の検証手順

ゲートウェイを再起動する

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

# For Docker
docker-compose restart gateway

# For PM2
pm2 restart openclaw

コマンド登録のゲートウェイログを確認する

# 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.

Telegram Bot APIで確認する

# 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 .

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

複数の連続した再起動を実行する

# 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"

検証の終了基準

✅ ゲートウェイログに起動時の「Telegram menu text exceeded」メッセージが含まれている
✅ getMyCommandsが空でない配列を返す
✅ Telegramボットの/メニューにすべての 예상コマンドが表示される
✅ 複数の連続した再起動後もコマンドが維持される
✅ 連続再起動テストスクリプトの終了コードが0

⚠️ よくある落とし穴

すべての再起動が同一の動作をすると思い込む: バグは一貫性なく発生します。数回の正常な再起動では問題が解決されたとは限りません。必ず連続再起動テストを使用して検証してください。
ログフィルタリング的无視: 関連するログメッセージは、ロギング設定によっては切り捨てられるか、複数の行に分割される場合があります。すべての関連エントリをキャプチャするには、grep -i telegramを追加のフィルタなしで 사용してください。
Dockerレイヤーキャッシング: Dockerを使用している場合、バージョン変更後に強制的に再ビルドしてください：
```
docker-compose build --no-cache
docker-compose up -d
```
環境変数のタイミング: TELEGRAM_BOT_TOKEN環境変数はゲートウェイ起動前に設定する必要があります。環境ファイルが正しく読み込まれていることを確認してください：
```
# Verify environment is loaded
env | grep TELEGRAM
```
Node.jsバージョンの相互作用: Node 22.22.1は他のバージョンとは異なる非同期タイミングを示す場合があります。（アップグレード前に使用していた）同じNodeバージョンでテストしてください。
ゲートウェイの高可用性設定: マルチインスタンス設定では、コマンド登録がべき等であることを確認してください。重複したsetMyCommands呼び出しはTelegramのレート制限を引き起こす可能性があります。
グレースフルシャットダウンの欠落: ゲートウェイプロセスを突然強制終了すると、Telegram Webhook接続が不整合な状態になる可能性があります。常にグレースフルシャットダウンシグナルを使用してください：
```
kill -SIGTERM <pid>  # Preferred
# Avoid: kill -SIGKILL <pid>
```
コマンド説明の長さ: 256文字を超える説明を持つカスタムコマンドを追加した場合、Telegram APIはバッチ全体を拒否します。「menu text exceeded」ログメッセージは、このセーフティネットが有効であることを示しています。
ファイアウォール/プロキシの干渉: 企業用プロキシはTelegram APIの応答を遅延させ、競合状態を 악化する可能性があります。直接接続をテストしてください：
```
curl -v --max-time 10 "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"
```

🔗 関連するエラー

UNAUTHORIZED (401) Bot API呼び出し時 — 通常はボットのトークンが正しくないことを示します。この問題ではありません。遭遇した場合はトークン設定を確認してください。
Telegram APIからのToo Many Requests (429) — 繰り返されるコマンド登録試行中のレート制限。自動再登録を実装する場合は指数関数的バックオフを実装してください。
アップグレード後の空のgetMyCommands応答（Issue #4521） — これはこのガイドで文書化されたバグの主な症状です。
_gatewayがETIMEDOUTでTelegramに接続できない — ネットワーク接続の問題で、コマンド登録バグとは関係ありませんが、同時に発生する可能性があります。
ボットのトークンローテーション後にコマンドが消える — 新しいトークンを使用した場合の予期される動作。コマンドはトークン固有です。トークンローテーション後に再登録してください。
Webhookとポーリングモードの不整合 — Telegram接続モードを切り替える場合、コマンド登録状態が移行全体で正しく維持されない可能性があります。
履歴：2026.3.xでのsetMyCommandsペイロードサイズエラー — 前のバージョンには60以上のコマンドが conservative ペイロード予算を超えた関連するバグがありました。これは2026.4.14で5700文字制限とともに部分的に修正されましたが、初期化の回帰を導入しました。

相互参照

OpenClaw GitHub: 進行中のパッチについてはtelegram + commandsでタグ付けされた問題を検索
grammyドキュメント: https://grammy.dev/plugins/commands — ボットコマンドメニュー登録APIの詳細
Telegram Bot API: setMyCommands — コマンド登録の公式API仕様