Gateway トラブルシューティングガイド：問題の特定と解決方法

昨日まで問題なく動いていたシステムが、急に反応しなくなってしまう。開発者なら誰しもが経験する、非常にストレスの溜まる瞬間です。特に Gateway のような通信の要となる部分でトラブルが起きると、どこから手をつければいいのか分からなくなりますよね。

この記事では、Gateway の調子が悪い時にまず試すべき手順と、よくあるトラブルの解決策をまとめました。

必要なもの

作業を始める前に、以下の準備ができているか確認してください。

• openclaw がインストールされている環境
• ターミナル（CLI）へのアクセス権限
• 設定ファイルへのアクセス権限

クイックスタート

まずは、現在の状態を把握するための「コマンド・ラダー（診断の階段）」を一段ずつ登っていきましょう。以下のコマンドを上から順番に実行してください。

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常な状態であれば、以下のような信号が確認できます：

• openclaw gateway status で Runtime: running および RPC probe: ok と表示される。
• openclaw doctor でブロック要素となる設定やサービスの問題が報告されない。
• openclaw channels status --probe で各 Channel が接続済み（connected/ready）と表示される。

トラブルシューティング

状況に応じた具体的な解決策を見ていきましょう。

応答が返ってこない場合

Channel は稼働しているのに応答がないときは、再接続を試す前にルーティングとポリシーを確認するのがベストです。

openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow

チェックポイント:

• DM 送信者の Pairing が保留（pending）になっていないか。
• グループでのメンション強制設定（requireMention, mentionPatterns）。
• Channel やグループの Allowlist の不一致。

よくあるエラーログ:

• drop guild message (mention required：メンションされるまでメッセージを無視しています。
• pairing request：送信者の承認が必要です。
• blocked / allowlist：ポリシーによって送信者または Channel がフィルタリングされています。

Dashboard や UI が接続できない場合

Dashboard やコントロール UI が接続できないときは、URL、認証モード、Secure Context の前提条件を検証しましょう。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

チェックポイント:

• Probe URL と Dashboard URL が正しいか。
• クライアントと Gateway 間で認証モードやトークンが一致しているか。
• デバイス ID が必要な場面で HTTP を使用していないか。

よくあるエラーログ:

• device identity required：Secure Context ではない、またはデバイス認証が不足しています。
• unauthorized / 再接続ループ：トークンまたはパスワードの不一致です。
• gateway connect failed:：ホスト、ポート、または URL のターゲットが間違っています。

Gateway サービスが起動しない場合

サービスはインストールされているのに、プロセスが維持されない場合の確認手順です。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

チェックポイント:

• Runtime: stopped と共に出力される終了のヒント。
• CLI とサービスのコンフィグ不一致（Config (cli) vs Config (service)）。
• ポートやリスナーの競合。

よくあるエラーログ:

• Gateway start blocked: set gateway.mode=local：ローカル Gateway モードが有効になっていません。
• refusing to bind gateway ... without auth：ループバック以外でのバインドにトークンやパスワードが設定されていません。
• another gateway instance is already listening / EADDRINUSE：ポートが競合しています。

Cron や Heartbeat が実行されない場合

スケジューラーの状態を確認してから、配信ターゲットを検証します。

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

チェックポイント:

• Cron が有効で、次の実行予定（next wake）があるか。
• ジョブの履歴ステータス（ok, skipped, error）。
• Heartbeat がスキップされた理由（quiet-hours など）。

よくあるエラーログ:

• cron: scheduler disabled：Cron が無効設定になっています。
• heartbeat skipped (reason=quiet-hours)：アクティブ時間外です。

アップグレード後に動作が不安定になった場合

多くの場合、設定の乖離や、新しいバージョンで厳格になったデフォルト設定が原因です。以下の手順で再設定を試みてください。

1. 認証と URL の挙動確認：gateway.mode=remote の場合、CLI が意図しないリモート先を参照している可能性があります。
2. バインドと認証のガードレール：LAN や Tailnet へのバインドには認証設定が必須です。また、古い gateway.token キーは gateway.auth.token に置き換える必要があります。
3. デバイス ID の再確認：Dashboard や Node のデバイス承認が保留になっていないか確認してください。

もし設定を見直しても解決しない場合は、以下のコマンドでサービスのメタデータを強制的に再インストールするのが近道です。

openclaw gateway install --force
openclaw gateway restart

お困りの際は、こちらのツールも活用してみてください。 AI Setup Assistant

次のステップ

• /channels/troubleshooting
• /gateway/authentication
• /nodes/troubleshooting
• /automation/troubleshooting