2026 クラウド Mac 上の OpenClaw ゲートウェイデーモン トラブルシュート：launchd、ログ、ポート
香港・東京・ソウル・シンガポール・米国のレンタル Apple Silicon Mac に OpenClaw を載せるプラットフォームエンジニアは、いずれ同じ失敗モードに直面する。対話的に CLI を叩く限り万事 OK だが、ログアウトや夜間再起動のあとゲートウェイデーモンが生き残らない。2026 年の修正はめったに「インストーラを再実行」ではなく、launchd の状態、ユニファイドログ、リリースノートと整合する Node ランタイム、ローカル設定から読む待受ポートを順に潰す作業である。本稿は 5 列の症状マトリクス、8 ステップの復旧手順、ヘッドレス環境での権限注意、Runbook に貼れる FAQ をまとめる。ゲートウェイが安定したら OpenClaw と Xcode iOS ビルド自動化（クラウド Mac） を読み、オーケストレーション層と CI トリガーを一本化するとよい。
MacLogin を含むプロバイダーは SSH と任意の VNC を渡すが、GUI セッション永続を保証しない。別アカウントで sudo インストールしたり、Node を上げたのに plist をリロードしなかったりすると、インタプリタの絶対パスが死んだまま静かに落ちる。環境ドリフトも多い。対話シェルの profile だけに export した API キーは launchd から見えない。CI シークレットと同じ厳格さで扱い、0600 の明示ファイルか、サービスユーザーがアンロックできるキーチェーン項目へ置く。同一ホストで重い Xcode ジョブを並走させると、ユニファイドメモリのピークが OOM を招き、一見ネットワークタイムアウトに見える。ゲートウェイとビルドキューを別ユーザーか別ホストへ分離するのが現実的だ。
変更窓で関係者に事前通知し、本番 Webhook 橋を持つノードでは、まず読み取り専用で openclaw dashboard の到達性だけ確かめ、書き込み経路は後から戻す。接続・リージョンの話は ヘルプ、容量は 料金ページ。本文は SSH が通っている前提のプロセス衛生に限定する。四半期ごとに「plist を壊す変更」と「安全に bootout する手順」をドリルし、オンコールが迷子にならないよう Runbook を印刷または Wiki 固定化するとよい。
大規模チームでは、複数の OpenClaw プラグインが同じポート帯を奪い合うことがある。設定ファイルの gateway セクションと OS ファイアウォール、さらにリバースプロキシの upstream を一つの表にまとめ、変更時は三者同時レビューを義務化する。東京から米国西海岸ノードを叩く場合、RTT 150–220 ms を前提に webhook タイムアウトと再試行バックオフを再計算し、失敗時のデッドレターキューを監視ダッシュボードに載せる。
ヘッドレスクラウド Mac でゲートウェイが落ちる理由
推奨パス openclaw onboard --install-daemon は ai.openclaw.gateway のような LaunchAgent をユーザードメインへ登録する。誤ったユーザーで入れた ProgramArguments は、毎回即クラッシュする。ユニファイドログに繰り返し fork エラーが出るなら、まず空き容量と ~/.openclaw の書き込み可否を疑う。
ゲートウェイ後に Xcode 自動化ガイド の CI 橋を載せる場合、ビルド失敗のノイズがログを埋めないようログレベルを段階的に上げる。リージョンごとに「ゴールデンイメージ」を再検証し、クローン AMI の TCC 状態がズレていないかを確認する。
症状マトリクス：深刻度・信号・最初の一手
深刻度でその場修復か、~/.openclaw/ のスナップショット取得かを決める。
| 症状 | 深刻度 | すぐ取る信号 | 最初のコマンド／行動 | 典型根本原因 |
|---|---|---|---|---|
| ダッシュボードが開かない | 高 | 固定 IP で ERR_CONNECTION_REFUSED | launchctl print gui/$(id -u)/ai.openclaw.gateway |
エージェント未ロードまたはクラッシュループ |
| モデル API が 401 | 中 | 60 秒周期の認証失敗ログ | LaunchAgent plist の環境変数を印刷 | デーモン文脈に API キーなし |
| アイドルなのに高 CPU | 中 | Activity Monitor で node >120% 持続 | 短時間デバッグログを有効化し 5 分採取 | 再接続ループや webhook 嵐 |
| ログアウト後だけ死ぬ | 高 | 対話 openclaw dashboard は OK |
~/Library/LaunchAgents に plist があるか |
デーモン未インストール（前景のみ） |
| チェック | 推奨値 | メモ |
|---|---|---|
| Node メジャー | 22.16+ または 24.x（製品指示に従う） | plist は絶対パス。Node 更新後は必ず reload |
| LISTEN ポート | 設定の gateway ブロックと一致 | 設定と FW を同時にいじると二重不整合 |
| ディスク空き | システムボリューム 15% 以上の余裕 | ログ肥大でランダムに起動失敗することがある |
MEMORY.md とツール設定をエクスポート。悪い plist ループは書き込み途中でセッションを切る。
8 ステップ・ゲートウェイ復旧チェックリスト
- Node ベースライン：
node -vを OpenClaw 最小バージョンに合わせる。ここがズレると以降は無意味。 - CLI 健全性：
openclaw doctor等で赤をゼロにしてから launchd に触る。 - LaunchAgent 調査：plist パスと
ProgramArgumentsをメモする前にbootoutしない。 - デーモン再インストール：本番ユーザで
openclaw onboard --install-daemon。 - ユーザードメイン起動：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist（実名は要確認）。 - ログストリーム：
log stream --style syslog --predicate 'process == "node"'を約 180 秒、ノイズを絞って見る。 - リスナー確認：
lsof -nP -iTCP -sTCP:LISTEN | grep nodeで設定と突合。片側だけ乱暴に変えない。 - E2E 証明：ローカルダッシュボード URL、メッセージブリッジのテスト、その後 CI webhook。壁時計の復旧時間を記録し、MTTR 15 分目標なら四半期リハーサル。
launchd、フルディスクアクセス、ヘッドレス macOS
OpenClaw の一部ツールは TCC で守られたファイルに触れる。SSH だけでは、フルディスクアクセスやオートメーションの初回承認を一度 VNC 経由で済ませ、デーモンが権利を継承できるようにする必要がある。GUI 操作禁止の組織では MDM のプライバシープロファイルか、Apple の無人 Mac mini 向け 2026 ガイダンスに沿った事前承認を使う。人間用と自動化用 macOS ユーザを分離し、誰かのデバッグ bootout が本番エージェントを巻き込まないようにする。MacLogin マルチリージョンではリージョンごとに権限検証を繰り返す。遅延は TCC を壊さないが、再承認されていないクローンは壊す。
共有ホストの Node と CLI ドリフト
Homebrew、nvm、fnm が積み上がると複数 Node が共存し、LaunchAgent は絶対パスを保持する。夜間アップグレードだけして plist をリロードし忘れるのが静かな殺し屋になる。チーム公開 Runbook でピン留めし、変更窓だけ OpenClaw を上げる。埋め込みと Xcode を同時に載せると OOM がタイムアウトに見える。オンボーディング時の which node を CMDB の MacLogin ホスト ID に貼り、24 時間以内に二人が同じゲートウェイを「直した」ときに npm グローバル接頭辞の衝突を防ぐ。
よくある質問
root で動かすべき？ いいえ。ワークスペースとキーチェーンに届く最小ユーザーで。
リバースプロキシで公開するポートは？ 設定で定義されたポート。TLS は Nginx/Caddy で終端し localhost のみへ。
東京から米ノードをテストするには？ RTT +150–220 ms を見込み webhook タイムアウトを調整。料金ページ のリージョン一覧で近いノードを選ぶ。
Mac mini M4 が OpenClaw ゲートウェイの安定に効く理由
安定性はソフトとヘッドルームの両方。Mac mini M4 のユニファイドメモリはモデルキャッシュとファイルインデックスを同時に抱えやすく、リポジトリ監視とメッセージキューを並べてもスワップ地獄になりにくい。これは Xcode 自動化ガイド の CI ブリッジとも相性が良い。MacLogin は HK・JP・KR・SG・US で展開し、コンプライアンス境界に合わせてゲートウェイを同居させられる。サンドボックス／ステージング／本番でホストを分ければ plist ミスや実験プラグインが本番橋を巻き込むリスクを下げられる。Webhook 量に応じて 料金ページ から CPU・メモリを伸ばし、デーモン初回承認用に SSH と任意の VNC を残す。
