三つの痛み
1) チャネル沈黙。Telegram や Slack で反応がなくても管理 UI は開けることがあります。これは静的ファイルではなくインバウンドイベントやトークン更新の問題であることが多く、Web が開けることだけでは正常判定できません。
2) 間欠障害。上流 LLM のレート制限、DNS の揺らぎ、メモリ逼迫が原因のとき、タイムスタンプ付きログと health --json の保存がないと再現説明ができません。
3) 設定ドリフト。allowedOrigins や API キーを変更しても、実際に動いているプロセスが読み込むファイルや systemd/docker の環境が違うと「直したはずが効かない」状態になります。
層の切り分け順
まずプロセスとポート、次に openclaw doctor、続けて health --json、最後にメッセージブリッジのログという順を守ってください。層を飛ばして再インストールすると時間を失います。ノート PC のスリープは長寿命接続を切る典型的な要因で、アプリのバグではありません。
症状とコマンド
表は「どのログを最初に開くべきか」を決めるためのものです。プロセス層でポートが奪われているのに API キーだけ疑っても時間が溶けます。逆に doctor がすべて緑でも、上流が 429 を返しているなら health の JSON にその痕跡が残っていることが多いです。メッセージング層では、Bot の再リンクやワークスペース権限の変更が頻発するため、変更履歴とログの時刻を必ず突き合わせてください。
| 層 | 兆候 | 最初の一手 |
|---|---|---|
| プロセス | 接続拒否 | status |
| 設定 | CORS | doctor |
| API | 429/5xx | health --json |
| チャネル | DM 無反応 | logs --follow |
複数メンバーが触る環境では、同じホストにデバッグ用と本番用の設定ファイルが混在しがちです。どのサービスユニットやコンテナがどのパスを読むかを README に固定し、本稿の五手順をオンボーディング手順に含めると再発率が下がります。
五手順
各コマンドの出力はそのままテキストに貼り付け、インシデント番号と紐付けて保存してください。クラウド VM ではローカルループバックのポート番号がドキュメントと異なることがあるため、status に表示された実値で curl を書き換えます。CI から同じホストへデプロイしている場合は、デプロイ直後にだけ doctor を再実行し、設定のロールアウト漏れを早期に検知する運用が有効です。
openclaw status
openclaw doctor
openclaw health --json > /tmp/openclaw-health.json
openclaw logs --follow
curl -sS -m 5 http://127.0.0.1:18789/health || echo "probe failed"
閾値の目安
ローカルプローブは 5 秒 タイムアウト、health とログは 24 時間 保持推奨、空きメモリは 約 1.5 GiB 以上の余裕を。時刻ずれが 60 秒 を超えると署名検証に失敗することがあります。チャネルやモデルプロバイダを変更した当日は、変更前後で health --json を二つ保存して差分比較すると切り分けが速くなります。
FAQ と SFTPMAC リモート Mac
常時接続が必要なゲートウェイは、スリープしやすい個人端末より、リモート Mac 常駐が安定しやすいです。ファイル同期と同じ隔離パスで運用するなら SFTPMAC のようなホスト型 Mac がオーバーヘッドを下げます。Apple Silicon 上でエージェントとビルド成果物を扱うチームでは、ゲートウェイと SFTP/rsync を同一ホストにまとめると権限境界の説明も簡潔になります。
本稿の五手順をステージングで自動化スクリプト化してから本番へ移すと、インシデント時の証跡が揃いやすくなります。
Slack の場合はアプリの再認可や Bot のスコープ変更が UI から分かりにくいことがあり、ログに出た OAuth エラーを起点に管理コンソールを開くと早いです。Telegram では長時間放置したセッションが無効化されるため、モバイルとデスクトップの二重ログイン状態も併せて確認するとよいでしょう。いずれのチャネルでも、まず health のチャネル項目が green かどうかを見てから深掘りすると迷走が減ります。リモート Mac に移行する際は、同じ五手順を移行直後にもう一度通し、DNS とローカルファイアウォールの差分だけを残すと運用が楽になります。重大インシデント後は、設定ファイルのバックアップと doctor 出力を同じ時刻で保管しておくと再発分析が速くなります。以上を習慣化すれば、チャネル障害の平均復旧時間を短縮できます。
ゲートウェイを Apple 環境で 24/7 運用したい場合はプランをご確認ください。