OpenClaw の macOS ゲートウェイは launchd 経由で再起動後も生きる想定ですが、2026.x チャネルの急速な更新では、バイナリだけ上がり LaunchAgent が再読み込みされず、すべてのメッセージブリッジが無言になる静かな障害が起き得ます。本プレイブックは症状と修正の対応、復旧戦術のマトリックス比較、NodeMac Mac mini M4 上で SSH からパスを推測せず実行できる9つの再現手順をまとめます。
OpenClaw 運用ランブック（ログ場所とアップグレード方針）と併用し、一から組み直す場合は 初回 macOS インストール を参照してください。
LaunchAgent のドリフトであり「AI が死んだ」ではないサイン
- プロセスがいないがクラッシュダイアログもない：
psにゲートワーカーがおらず CPU アイドル—典型的な未ロードエージェント。 - 再起動後すべてのプロバイダが HTTP 401：dotenv に鍵はあるが、plist に必要変数が埋め込まれておらずデーモンが空の環境を継承。
- 手動 CLI は成功、自動起動は失敗：ターミナルではゲートウェイが動くがログアウト後に止まる。LaunchAgent が古い作業ディレクトリや旧レイアウトのエントリ名を指している。
復旧オプション・マトリックス
| 戦術 | ダウンタイム | 使う場面 |
|---|---|---|
launchctl kickstart -k |
5–15 秒 | エージェントはロード済みだがプロセス固着。最初の一手 |
| Unload + load plist | 20–40 秒 | ProgramArguments や WorkingDirectory を編集した後 |
openclaw gateway install --force |
1–3 分 | ベンダー CLI が plist を書き換え可能。再起動前に diff 確認 |
| パッケージロールバック + plist バックアップ | 5–10 分 | 本番をブロックする回帰。最後に良好だった tarball から復元 |
環境変数：デーモンが読む場所
対話シェルは .zshrc を読みますが、LaunchAgent は読みません。プロバイダ鍵が plist に反映されないファイルだけにあると、ゲートウェイは未認証で起動しログに紛らわしい 401 が並びます。
- 必須キーを一覧化（API トークン、任意のプロキシ URL）し、ローテ後に貼れるランブック断片にする。
- plist の
EnvironmentVariablesにミラー または 起動時に dotenv を明示読み込みするベンダー公式ラッパーを使う。マシンごとに1戦略に統一し、中途半端に両方にしない。 - 再起動テスト：四半期で実施し、資格情報ローテ後 24 時間 以内に欠落を検知。
- plist 権限をサービスユーザーに限定。world-readable な plist は秘密をローカル全アカウントに漏らす。
- 有効ドメインを文書化（
gui/$(id -u)と background の違い）し、初任が誤ったジョブを unload しないようにする。
ヘッドレスクラウド Mac のヒント：ゲートウェイ UI を短時間見る必要がある場合は VNC ガイド に従い VNC を使う。それ以外は SSH のままログと HTTP ヘルスで判断する。
バイナリが健全でも自動起動が壊れる理由
パッケージ更新は同時に3つの脆い接点を動かします。ProgramArguments 内の実行パス、相対設定が解決される作業ディレクトリ、ゲートウェイバンドルが期待する Node.js の版。いずれかがずれても launchd はジョブを「設定済み」とみなし即終了する—オペレータは実際には常駐していない UI に緑チェックを見ることになる。
アップグレードごとにミニマイグレーションとして扱う：plist をスナップショットし、ゲートウェイエントリスクリプトのチェックサムを記録し、少なくとも 7 日間 前の tarball を保持する。クラウド Mac はボットが応答しなくても課金が続く。金曜夕方のデプロイが顧客向け自動化を孤立させた瞬間に、この規律が元を取る。
- 本番ゲートウェイの自動アップグレードを抑制。ステージングのカナリアが最新を先に取る。
- Node メジャーをベンダー文書と揃える。メジャー不一致は最初のログ行にモジュール解決エラーとして現れがち。
- シークレットローテを中央化し、plist 変更をパニックごとではなくフリート一度で済ませる。
9ステップ復旧ランブック（Mac mini M4 で SSH）
- 接続確認 を LaunchAgent と同じ SSH ユーザーで。権限不一致は「手動OK・ブートNG」の典型原因。
launchctl print gui/$(id -u)を取得し、インシデントメモと一緒に保存して diff 可能にする。~/Library/LaunchAgents/で plist を特定し、ProgramArgumentsのパスがディスク上に存在するか確認。-k付き kickstart で強制再起動。30 秒 待ちリスニングポートを確認。- まだダウンなら plist をきれいに unload/load。以前試した
/Library/LaunchDaemonsに古いコピーがないか確認。 - 環境変数を突き合わせ。欠けを注入し再度ロード。
- ゲートウェイログを 2 分 tail しクラッシュループを見る。同一スタックトレースが3回超ならロールバックへ。
- 統合スモーク（最もリスクの低いチャネルでテストメッセージ）を流してから復旧宣言。
- 社内ドキュメントを更新し、実際に効いたコマンドを記録。HK・JP・KR・SG・US のクラウド Mac フリートは1つの正典ページを共有する。
モデルプロバイダを責める前のチェックリスト
| チェック | 合格基準 |
|---|---|
| DNS／外向き HTTPS | プロバイダ向け curl -I が 2xx/401（タイムアウトでない） |
| ディスク空き | システムボリュームに少なくとも 25 GB |
| 時刻ずれ | NTP ずれ 2 分 未満。時刻ジャンプ時 JWT は静かに失敗する |
FAQ
アップデート後に OpenClaw がメニューバーから消えるのはなぜ？
ゲートウェイプロセスは終了したが launchd が LaunchAgent の plist を再読み込みしていないか、パッケージレイアウト変更後も plist が古いプログラムパスを指している可能性がある。plist を検証しエージェントを再読み込みし、環境変数が再起動後も残ることを確認する。
本番ゲートウェイで kickstart を実行しても安全？
数秒のダウンタイムを許容できるなら可。メッセージブリッジに依存するチームはメンテナンス枠を推奨。再起動直後1分間は必ずログを tail する。
ノート PC を抱えたまま常時オンゲートウェイを維持したくない場合は、ユーザーに近いリージョンで SSH/VNC 付き専用 Mac mini M4 を揃えた NodeMac 料金 を比較し、このランブックをアップデート後の標準チェックリストにしてください。
Mac mini M4 ハードウェアはデーモン復旧を退屈なほど安定させる：Apple Silicon の余裕性能でゲートウェイ、ローカルヘルパー、軽い自動化が共存しスワップ地獄になりにくく、ユニファイドメモリはログスパイク時の OOM を減らす。NodeMac は 専用物理マシン（共有 VM ではない）を香港・日本・韓国・シンガポール・米国で SSH と VNC 付きに提供し、アップデート直後からこのプレイブックをリモートで実行できる。レンタルは資本支出を避けつつ LaunchAgent 方針を反復し、プラットフォームヘルプ でフリート全体のアクセス衛生を保つのに合う。