OpenClaw が Webhook に応答しなくなったり、ゲートウェイが 401 を返し始めたとき、最速で復旧するのは無秩序な再起動ではありません。openclaw doctor、構造化ログ、チャネルプローブによる診断パスです。本稿では 2026 年のコマンド群を整理し、よくある障害と修正の対応表を示し、フタを閉じるたびにスリープするノート PC ではなく、Apple Silicon Mac mini をレンタルして同じループをステージングする理由を説明します。運用チームが週次で doctor の出力をテンプレ化すると、インシデント時の「何が変わったか」の説明責任が一気に下がります。
まず doctor が必要なシグナル
次のパターンが繰り返すときはフォーラムを飛ばしてください。ゲートウェイは健全なのにエージェントがジョブを取らない、ログに Unauthorized とコード 1008、トンネル編集後に Slack イベントが二重に届く。いずれも openclaw doctor がバージョンのずれ、欠落した環境変数、古いトークンを、無関係なスタックトレースを何時間も追う前に表に出します。診断の第一歩として doctor を固定し、出力をインシデントチャンネルに貼る運用にすると、エスカレーションの質が上がります。
最近 Node を上げた場合は openclaw status --deep と doctor をセットで。OpenClaw の 2026 年ドキュメントでは複数の CLI パスに Node 22.16 以上 または Node 24 を前提としています。古いランタイムでもインストールは通っても、プラグインが ESM 専用ヘルパーを import した時点で失敗します。CI とステージングの Node バージョンを揃えないと、ローカルだけ成功するという地獄が続きます。
インシデント開始時点でスナップショットを書き出してください。doctor の出力をコピーし秘密をマスクし、openclaw logs の先頭 200 行 を添付する。この習慣があるチームはチケット完了が 40〜60% 速いと言われます。ベンダーや社内レビュアーが同じ事実を共有できるからです。スクショの再構成に時間を溶かさなくて済みます。
VPN のスプリットトンネルを切り替えた直後は、ゲートウェイが使うネットワークパスと同じ経路から doctor を再実行してください。非対称ルーティングでは、ノートからのプローブは成功してもデーモンアカウントからは失敗する典型例が起きます。クラウド Mac に SSH してそこから実行すれば、本番に近い経路で検証できます。詳しいトンネルとプロキシの話は ゲートウェイ・プロキシ・トンネル強化 を参照してください。
さらに、プロファイルが複数ある環境ではどの ~/.openclaw を読んでいるかを doctor が指摘することがあります。環境変数で上書きしている場合は、LaunchAgent の plist と対話シェルの .zshrc の両方を確認し、意図しない二重定義を消してください。設定の「見えている場所」と「実際に効いている場所」がズレていると、トークンを更新しても古いプロセスが古いファイルを掴んだままになります。
症状マトリクス：コマンドと意味
マトリクスはトリアージボードとして使います。コマンドは本番相当のステージングで安全に実行できます。ゲートウェイ再起動が要る変更はメンテナンス枠で進めてください。
| 症状 | 最初のコマンド | 「良い」状態 |
|---|---|---|
| ゲートウェイは起動しているが UI が繋がらない | openclaw gateway status | リスナー PID が一つ、想定のバインド（多くはプロキシ背後の 127.0.0.1） |
| ランダム切断 | openclaw logs --follow | チャット往復後 5 分 TLS またはトークンエラーが繰り返さない |
| Slack／Discord が沈黙 | openclaw channels status --probe | 有効な各チャネルが到達可能で OAuth スコープが有効 |
| デプロイ後のポート競合 | lsof -nP -iTCP:PORT | grep LISTEN | OpenClaw 関連プロセスがポートを一つだけ占有 |
| プロバイダからの LLM 401 | API キー環境変数と課金を確認 | 自動化には従量課金の開発者キーが必要（一般向けサブスクではない） |
ゲートウェイトークンと allowedOrigins
設定がフラットな gateway.token から gateway.auth.token に移ったとき、多くのチームでダッシュボード連携が壊れました。リバースプロキシがレガシーヘッダーを注入しているなら、openclaw doctor --generate-gateway-token で再生成し、プロキシとローカルの ~/.openclaw/openclaw.json のコピーの両方を更新してください。
ブラウザクライアントには明示的な allowedOrigins が必要です。開発では http://localhost:3000、本番ではホスト名を列挙します。ワイルドカード * は便利ですが危険で、インターネットに晒した OpenClaw では監査で即フラグが立ちます。トンネル構成ではオリジンを ゲートウェイ・プロキシ・トンネル強化 の指針に揃えてください。
EADDRINUSE が出たら、二つのプロファイルかゾンビ node が同じポートを奪っていることが多いです。古い PID を終了し、二度目の lsof で確認し、文書化したサービスマネージャ経由で再起動してください。macOS サーバーでは LaunchAgent と cron のパターン に従い、再起動を決定的に保ちます。plist の重複ラベルや、手動起動と LaunchAgent の二重登録は典型の落とし穴です。
トークンをローテーションしたら、プロキシのキャッシュや古い systemd／launchd ユニットが古い環境を読み込んでいないかも確認してください。設定ファイルを編集した直後にプロセスが再起動されていないと、doctor は新設定を読んでいるのに実プロセスは古いトークンを握る、という状態が起きえます。
HTTP 200 を超えたチャネルプローブ
Webhook が 200 OK でも署名検証が静かに失敗すればイベントは落ちます。シークレットをローテーションした後は openclaw channels status --probe を実行し、各チャット面から合成メッセージを送ってください。ログの相関 ID を残します。多くのチームはステージングで 14 日 のログ保持を維持し、本番インシデントと比較します。
HTTP コールバックを手でデバッグするときは、連携が送るのと同じヘッダで curl してください。Authorization: Bearer … プレフィックスの欠落や、貼り付けトークンに余分な改行があると、プロバイダ障害に見える 401 になります。ボディサイズも比較してください。一部プロキシは 1 MB 超のペイロードを切り詰め、大きな JSON ツールコールが壊れるまで気づきません。上限を上げるかチャンクアップロードに切り替えます。
WhatsApp やモバイル優先ブリッジでは、ベンダー推奨どおり競合するデスクトップセッションをログアウトしてください。重複セッションは「どこにでも届くのに OpenClaw だけに届かない」ように見えます。Discord／Slack はワークスペース管理者がポリシーを厳しくした後、メッセージ履歴の閲覧 や メッセージ送信 のインテントが欠けていることが多いです。
週次 の 5 分プローブジョブをスケジュールしてください。openclaw health --json を叩き非ゼロ終了ならメールする、cron 一行でも構いません。月曜のスタンドアップより先にデモ中に表に出る回帰を減らせます。長期運用ではプローブ結果を時系列で保存し、週ごとの失敗率をダッシュボード化するとトレンドが見えます。
診断をクラウド Mac で行う理由
ノートはサスペンドし、VPN はフラップし、MDM はデーモンを止めます。72 時間 のソークテストには向きません。Apple Silicon のレンタル Mac mini は常時オンラインで、ローカル macOS と同一の Unix ツールを提供し、個人 BYOD からシークレットを分離します。SSH で反復が速い：doctor、vim で設定編集、サービス再起動、ログストリームをデスクに歩かずに回せます。
コストは弾力レンタル 1 日 16.9 ドル と、エンジニアが午後丸ごとブロックされる機会損失を比較してください。診断に GPU は要りません。安定電源、正確な時計、トリアージ中に OS パッチで勝手に再起動しないマシンが要ります。インシデントが閉じたらレンタルを止められます。倉庫に資産として置いたハードではできません。
運用上のコツ：クラウドホストと CI イメージでディレクトリ構成を揃え、openclaw.json のパスを移植可能に保ちます。/Users/alice/Projects のようにハードコードすると、共有自動化アカウントに移したときに何時間も書き換えが発生します。
メモリ計画も重要です。小さめ Mac mini ティアで複数チャネルブリッジを同時有効にする前に、空き RAM を少なくとも 4 GB 確保してください。doctor はスワップスラッシングが始まるまで警告しません。プローブ負荷試験中は Activity Monitor の memory_pressure または vm_stat を監視します。
クラウド側ではタイムゾーンと NTP のずれもログの相関を狂わせます。診断ベンチでは date とプロバイダ側のタイムスタンプを突き合わせ、署名付き Webhook の時刻窓エラーがないか確認してください。Apple Silicon は消費電力対パフォーマンスが良いため、常時 tail を複数開いてもノートより静かに回せます。
よくある質問
新しい OpenClaw ビルドでは gateway.token はどこへ行きましたか？
最近のリリースでは認証が gateway.auth.token 配下にネストされます。ダッシュボードが古いフラットキーを読んでいる場合は、openclaw doctor --generate-gateway-token でトークンを再生成し、リバースプロキシや UI が期待するすべての場所に貼り付けてください。
再起動直後に EADDRINUSE が出るのはなぜですか？
LaunchAgent、手動ターミナル、取り残された node プロセスが同じゲートウェイポートを束縛できます。lsof -i :PORT で PID を特定し、重複プロファイルを止め、プロファイルごとに openclaw gateway インスタンスが一つだけ動くようにしてください。
クラウド Mac mini は OpenClaw 診断に役立ちますか？
はい。Apple Silicon Mac mini はローカル macOS と同じ Unix ツール、長時間ログ tail のための安定電源、スリープするノートからの分離を提供します。レンタルはコストを弾力的に保ちながらゲートウェイ強化を反復できます。
ホストが退屈であれば OpenClaw は輝きます。信頼できる電源、高速 SSD、本番に近い macOS の挙動。Apple Silicon は doctor の同時実行、ログ集約、Webhook 検証用の軽量ブラウザに余裕を与え、巨大タワーのファン騒音なしに済みます。SSH 自動化に任意で VNC を足せば、インシデントではスケールアップし、静かな週ではスケールダウンする診断ベンチになります。AI エージェントがデプロイメントの一部になった Mac 系 HTML ショップにとって、まさに求める弾力です。
常時オン Apple Silicon で OpenClaw をステージング
ノートのスリープや MDM の不意打ちなしに、doctor・ゲートウェイ・チャネルプローブを回すにはクラウド Mac mini のレンタルが向きます。まずプランを確認し、ヘルプで SSH を配線してください。