macOS における OpenClaw ゲートウェイ復旧：エージェント主導の再起動失敗と 2026 年の LaunchAgent 強化

レンタル Apple Silicon Mac mini 上で OpenClaw を運用するプラットフォームエンジニアは、エージェント・CI フック・チャットオペボットからゲートウェイ再起動をかけ、ターミナルで同じコマンドを打つと成功するのに自動化からは失敗する状況を増やしています。2026 年の公開スレッドが示すのは壊れたゲートウェイバイナリではなくコンテキストギャップです。PATH 欠落、誤った作業ディレクトリ、満たされない TTY 前提、同期クラウド上の状態ディレクトリ。本稿は Mac mini への OpenClaw インストールとデプロイ、デーモンとポートの障害対応、ヘッドレスと GUI セッションの規律と整合する再現可能な復旧ランブックで、香港・日本・韓国・シンガポール・米国の VmMac リージョンを想定します。

SSH 切断後も OpenClaw を生かす主流が LaunchAgent 所有のゲートウェイであるため、そこに焦点を当てます。ログイン項目や場当たりの nohup は対象外です。次の再起動まで失敗を隠します。

「ターミナルでは動くがエージェントでは失敗」の分類

すべてのインシデントを三項目 diffで始めます。両コンテキストで whoami、pwd、printenv PATH を取得します。エージェントは同一ユーザーでも環境が削られます。OpenClaw CLI は PATH 上の node などにシェルアウトするため、/opt/homebrew/bin が無いと手動は成功して再起動だけ不安定に見えます。

• 非対話シェル： .zprofile が読まれない。必要な export は plist の EnvironmentVariables に移します。
• キチェーンのロック解除： 無人再起動はプロンプトをクリックできません。制御された保守ウィンドウで security による事前プロビジョニングを行います。
• ThrottleInterval の衝突： 短時間に再起動ループを打つと launchd のバックオフに当たります。数値調整はトラブルシュート記事を参照してください。

コンテキストドリフトを潰す LaunchAgent plist 項目

2026 年時点の OpenClaw ゲートウェイに最低限必要な plist 衛生：

• ProgramArguments は絶対パスのバイナリのみ。PATH を明示しない限り裸の openclaw は避けます。
• WorkingDirectory はローカルで非同期のフォルダ（例：/Users/laneuser/openclaw-run）。
• StandardOutPath と StandardErrorPath は同じローカルツリー下に置き事後分析に使います。
• ThrottleInterval は上流ウェブフックが再起動を殺到させる場合 10 以上。

再インストール前の症状対応マトリクス

症状	有力な原因	最初の手当	エスカレーション
stderr に command not found: node	LaunchAgent の PATH	EnvironmentVariables に Node の絶対パスを追加	plist で fnm/asdf により Node 版を固定
ゲートウェイが起動して 5 秒未満で終了	ポート衝突または不正トークンファイル	トラブルシュート記事のポート表と突合	シークレット回転＋再起動
PID ファイルはあるがプロセスが無い	クラッシュループ／OOM	ユニファイドメモリ圧力ログを確認	同時エージェント削減または SKU 上位へ
エージェントからの再起動だけ失敗	cwd またはサンドボックスプロファイル	WorkingDirectory とログラッパーを設定	サービス強制再インストール

強制ゲートウェイサービス再インストール（復旧経路）

plist 手術で直らないときは、ユーザエージェントをきれいに launchctl bootout したうえで、ベンダー手順に従い強制ゲートウェイインストールを行います。フラグは上流リリースノートに合わせて進化しますが、手順は常に停止 → エージェントアンインストール → 再インストール → 検証 → 再有効化です。変更管理のため OpenClaw バイナリと設定テンプレの前後チェックサムを記録します。

状態ディレクトリの配置と同期フォルダリスク

2026 年のコミュニティ記事は繰り返し、OpenClaw の状態を iCloud Drive・Dropbox・OneDrive に置かないよう警告しています。ファイルプロバイダの仮想化が部分的書き込みを生み、破損したゲートウェイ状態のように見えます。状態はローカル APFSに置き、ライブ同期ではなくオブジェクトストレージへの明示アーカイブでバックアップします。以前 Dropbox へシンボリックリンクしていた場合はリンクを削除し、ローカルディレクトリを作り直してからサービス定義を再インストールします。

復旧後の検証チェックリスト

1. ヘッドレスヘルス： VNC なしで SSH からローカルゲートウェイヘルスを curl します。
2. ウェブフックリプレイ： ステージングから署名付きテストペイロードを送ります。
3. ログ転送： JSON 行が 60 秒以内にコレクタへ届くことを確認します。
4. フェイルオーバーリージョン： ホストが米国でも顧客が日本なら、完了宣言前に合成 RTT を測ります。

ウェブフック受信のハードニングは ウェブフック／ゲートウェイ記事と突き合わせ、復旧でベアラートークンの穴を再度開けないようにします。

FAQ：クラウド Mac mini のゲートウェイ復旧

ターミナルの再起動は動くのにエージェントは失敗するのはなぜ？ 環境が異なります。PATH、cwd、TTY、キチェーンのプロンプト。LaunchAgent にすべて明示します。

状態は iCloud に置ける？ いいえ。ロック競合を避けるためローカル APFS パスを使います。

悪いアップグレード後の最初のコマンド？ ラベルを bootout し、ベンダー文書に従ってサービスを強制再インストールし、ヘッドレスで検証してから再度 bootstrap します。

2026 年、VmMac の Mac mini M4 がゲートウェイ復旧ループを簡素化する理由

復旧の一部はグリーンまでの時間です。Apple Silicon Mac mini M4 は、ラップトップ級のサーマルでスクリプト途中にスロットルが入るより、再インストールとコールドスタート検査を速く終えます。香港・日本・韓国・シンガポール・米国に並列ホストをレンタルすれば、壊れたレーンが再起動しているあいだウォームスタンバイレーンを維持でき、顧客から見えるダウンタイムを減らせます。メタルの近接と厳格な LaunchAgent 衛生、ローカル専用の状態を組み合わせれば、OpenClaw ゲートウェイは「自分の SSH セッションでは動く」という幽霊から解放されます。