macOS では OpenClaw ゲートウェイが多くの場合 launchd によって監督される。オペレーター、ときにはエージェント自身が、それに依存している同じセッションから「ゲートウェイを再起動しよう」とする。そのパターンは、再起動を開始した RPC がまだ接続されたまま LaunchAgent をアンロードしうる。別シェルがログインするまで戻らないという現場報告と一致する。本稿は 理由、安全／不安全の判断表、7 つの具体手順と数値ガイド、復旧・並行の深掘り記事へのリンクをまとめる。
変更前に LaunchAgent ゲートウェイ復旧 と 対話チャットと長時間ジョブの並行性 を読み、重いワークスペースと再起動が衝突しないようにする。初回導入は インストールとデプロイ に従う。アカウントは ヘルプ、ゲートウェイと CI の分離は 料金。トークンと plist のドリフトは 設定ドリフト、スケジュール整合は スケジュールタスク整合、429 とバックオフは レート制限マトリックス。
失敗モード：launchd 下での自己首切り
ゲートウェイを サーバ と、実行中コマンドの 依存先 の両方として捉える。エージェントがゲートウェイが所有する同一 RPC チャネル越しに openclaw gateway restart（または同等ラッパー）を発行すると、launchd はクリーンな引き渡し前に bootout する可能性がある。再起動を開始した CLI はトランスポートエラーで終了し、bootstrap で健全へ戻る保証が残らない—特に SSH のみのヘッドレスでは。
- 症状 A：エージェントが再起動を呼び出した直後、
gateway statusが実行中から欠落へ一瞬で変わる。 - 症状 B：ログに launchd アンロード行と RPC 切断エラーが隣接する。
- 症状 C：外部モニタ（HTTP ヘルスや TCP）が数分タイムアウトするが loginwindow ユーザーが未開始。
マトリックス：誰がゲートウェイを再起動してよいか
| アクター | 典型コンテキスト | 判定 | より安全な代替 |
|---|---|---|---|
| 人間（2 本目の SSH） | screen または ssh user@host | 推奨 | 文書化された bootout／bootstrap 順序とログ取得 |
| OpenClaw 内の自動化エージェント | チャット処理中のツール呼び出し | 再起動は避ける | チケット発行。外部オーケストレータがミューテックス後に再起動 |
| スケジュール LaunchAgent | 夜間ドリフト修復 | plist が分離されていれば可 | チャットピークとずらす。スケジュール整合記事を参照 |
| 同一 Mac の CI ジョブ | パイプラインの「ゲートウェイバウンス」 | 非推奨 | 専用管理者ジョブキューと分離クレデンシャル |
第 2 マトリックス：再起動前チェックリスト
| チェック | 合格基準 |
|---|---|
| リスナー所有者 | 設定されたゲートウェイポート族に正確に 1 つの PID が一致。ロールバック用に PID を記録 |
| ログ用ディスク空き | 状態とログのボリュームに少なくとも 8 GB の空き。再起動中の書き込み失敗を防ぐ |
| 長時間ジョブとのミューテックス | ワークスペースジョブがゲートウェイ保守用に定義したコンパイルミューテックス層を保持していない |
| 認証トークン連続性 | クライアントが対話 GUI なしでディスクからトークンを再読み込みできる |
毎回ログに残す運用数値
- コールドスタート予算：
bootstrap後、失敗宣言まで最大 90 秒。AV またはフルディスクアクセス保留時はさらに長く。 - RPC プローブ間隔：最初の 1 分は 5 秒ごと、その後は指数バックオフ。
- 同時管理者操作：ホストあたりゲートウェイを変える操作は 1 つに制限。並列 plist 編集はどの変更が健康を壊したか追えなくなる。
ヘッドレスのヒント：GUI 権限ダイアログが疑われる場合は一時的に VNC で接続し一度クリックしてから SSH のみに戻す。
ホスト上 7 ステップ（HowTo の展開）
- 病んだゲートウェイ経由のコマンドを止める。同一 Mac mini M4 に 2 本目の SSH を開く。このセッションはリサイクルしようとする RPC に依存してはならない。
- 証拠取得：状態、直近ログ、権威あると思われる plist パス—設定ドリフト記事と突き合わせる。
lsof等でリスナー確認。ラボ共有機で誤った PID をbootoutしない。- macOS バージョンに合う launchd 意味論でアンロードし、ディスクから bootstrap して EnvironmentVariables と WorkingDirectory を適用。
- 外部シェルからヘルスをプローブし RPC が成功するまで。そこで初めてチャットクライアントを再接続。
- インシデント一行メモ：タイムスタンプ、理由、チャット／CI 影響—後でレート制限記事と相関しやすい。
- まだ赤なら LaunchAgent 復旧へ戻り既知良好 plist に切り替え、エージェントセッション内で再起動ループを繰り返さない。
FAQ
Ansible で再起動を自動化できるか
可能。ただしプレイブックの制御接続が、再起動対象のゲートウェイプロセスを経由してはならない。ゲートウェイを DB のように扱い、オーケストレーション面からバウンスする。
開発と本番でゲートウェイを分ける場合
plist、ポート、状態ディレクトリを分離する。どの LaunchAgent ラベルがどの環境か文書化し、bootout が誤ラベルを撃たないようにする。
ホストを完全分割すべきとき
チャット SLO と CI のプリエンプションがミューテックス層の後も衝突する場合—単一 launchd グラフに積むより NodeMac で 2 台目の専用 Mac mini M4 を追加する。
信頼できる OpenClaw 運用はビルドと同じハードウェア物語の恩恵を受ける：専用 Mac mini M4 が Apple Silicon 性能と ネイティブ macOS を与え、ヘッドレス保守の SSH と UI 権限プロンプト用の任意 VNC を組み合わせ、香港・日本・韓国・シンガポール・米国 でオペレータを深夜 3 時に起こすマシンに近づける。購入ではなくレンタルは、このランブックが実験エージェントと本番チャットを同一 launchd グラフに置くべきでないと証明したときに「ゲートウェイ専用 2 台目」を経済的に可能にする。次のリスクを積む前に 地域別プラン を比較する。