OpenClawの接続状態をCLIで即座に確認・診断する方法

「設定は完璧なはずなのに、なぜか動かない……」 開発をしていると、そんな壁にぶつかることがよくあります。特に外部サービスとの連携では、どこに原因があるのかを特定するだけで一苦労です。

当てずっぽうでデバッグを繰り返すのは、もう終わりにしましょう。Channel の接続状態を確実に確認し、問題を素早く解決するためのガイドを用意しました。

クイックチェック

• openclaw status — ローカルのサマリーを表示します。Gateway の到達性やモード、アップデートのヒント、連携済み Channel の認証経過時間、セッションと最近のアクティビティを確認できます。
• openclaw status --all — ローカルの完全な診断結果を表示します（読み取り専用、カラー表示）。デバッグ用に内容をそのまま貼り付けるのに適しています。
• openclaw status --deep — 実行中の Gateway にも問い合わせを行い、サポートされている場合は Channel ごとのプローブを実行します。
• openclaw health --json — 実行中の Gateway にヘルスのスナップショットを要求します（WS のみ。Baileys のソケットには直接アクセスしません）。
• WhatsApp や WebChat で /status というメッセージを単体で送信すると、エージェントを呼び出さずにステータス応答を受け取れます。
• Logs: /tmp/openclaw/openclaw-*.log を tail で監視し、web-heartbeat, web-reconnect, web-auto-reply, web-inbound でフィルタリングしてください。

詳細な診断

• ディスク上の認証情報: ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json（更新日時が最近であることを確認してください）。
• Session store: ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json（パスは設定で上書き可能です）。セッション数や最近の宛先は status コマンドで確認できます。
• 再連携の流れ: ログにステータスコード 409–515 や loggedOut が表示された場合は、openclaw channels logout && openclaw channels login --verbose を実行してください。（注：QR ログインフローは、ペアリング後のステータス 515 に対して一度だけ自動再起動します。）

ヘルスモニターの設定

• gateway.channelHealthCheckMinutes: Gateway が Channel のヘルスチェックを行う頻度です。デフォルトは 5 です。0 に設定すると、ヘルスモニターによる再起動をグローバルに無効化できます。
• gateway.channelStaleEventThresholdMinutes: 接続済みの Channel がアイドル状態のまま、ヘルスモニターが「停滞（stale）」と判断して再起動するまでの時間です。デフォルトは 30 です。この値は gateway.channelHealthCheckMinutes 以上に設定することをおすすめします。
• gateway.channelMaxRestartsPerHour: Channel またはアカウントごとの、1時間あたりのヘルスモニターによる再起動回数の上限です。デフォルトは 10 です。
• channels.<provider>.healthMonitor.enabled: グローバルな監視は有効にしたまま、特定の Channel のみヘルスモニターによる再起動を無効にします。
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled: Channel レベルの設定よりも優先される、マルチアカウント用のオーバーライド設定です。
• これらの設定は、現在対応している Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, WhatsApp の組み込み Channel モニターに適用されます。

トラブルシューティング

• logged out またはステータス 409–515 の場合 → openclaw channels logout を実行してから openclaw channels login で再連携してください。
• Gateway に接続できない場合 → openclaw gateway --port 18789 で起動してください（ポートが使用中の場合は --force を使用します）。
• インバウンドメッセージが届かない場合 → 連携しているスマートフォンがオンラインであること、および送信者が許可されていること（channels.whatsapp.allowFrom）を確認してください。グループチャットの場合は、許可リストとメンションルール（channels.whatsapp.groups, agents.list[].groupChat.mentionPatterns）が一致しているか確認してください。

専用の “health” コマンド

openclaw health --json は、実行中の Gateway に対してヘルスのスナップショットを要求します（CLI から直接 Channel のソケットを操作することはありません）。認証情報の状態や経過時間、各 Channel のプローブ結果のサマリー、Session store のサマリー、およびプローブの所要時間を報告します。Gateway に接続できない場合や、プローブが失敗・タイムアウトした場合は、ゼロ以外の終了コードを返します。

オプション:

• --json: 機械可読な JSON 形式で出力します。
• --timeout <ms>: デフォルトの 10 秒のタイムアウト設定を上書きします。
• --probe: キャッシュされたスナップショットを返す代わりに、すべての Channel に対してライブプローブを強制実行します。

ヘルススナップショットには、ok（真偽値）、ts（タイムスタンプ）、durationMs（プローブ時間）、Channel ごとのステータス、エージェントの利用可能性、および Session store のサマリーが含まれます。

AI Setup Assistant

次のステップ

• Gateway の設定詳細
• Channel 連携ガイド