2026年 OpenClaw macOS デュアル LaunchAgent 共存トラブルシュート：ai.openclaw.gateway と ai.openclaw.mac の並行運用——launchctl 修復、設定の単一化、専有リモート Mac の SSH ヘッドレス運用チェックリスト＋FAQ
1 台の macOS ホストでは、OpenClaw が役割分割されることが多いです。ゲートウェイ（ai.openclaw.gateway）が HTTP／WebSocket を受けてワークを振り分け、Mac ランタイム（ai.openclaw.mac）が Apple 固有の CLI・UI 自動化・ローカル推論エンドポイントを担当します。どちらも launchd 下で動かすのは正しい設計ですが、起動順・環境の二重定義・ポート衝突が典型の失敗要因です。本稿では再現可能な launchctl 修復手順、OPENCLAW_* の単一ソース化、専有リモート Mac を SSH ヘッドレスで載せるチェックリストをまとめます。常駐運用の全体像は 2026年最新 OpenClaw デプロイ・安定運用マニュアル：SSH、systemdから24時間自動再起動まで、plist に載せる秘密情報の衛生は 2026年 OpenClaw 安全運用マニュアル：リモート Mac mini で Lobster エンジンと SecretRef を活用した零漏洩 AI デプロイ と併読すると運用が通しやすくなります。
1. なぜ LaunchAgent が二つあるのか
ゲートウェイ（ai.openclaw.gateway）：外向きまたは VPN 側のポートをリッスンし、（ローカルリバプロと組み合わせた場合は）TLS 終端や RPC のファンアウトを担います。ループバック依存が生きてから起動するのが安全です。
Mac エージェント（ai.openclaw.mac）：xcodebuild、公証フロー、AppleScript／ショートカット、画面キャプチャ系ツールなど macOS 固有タスクを実行し、ゲートウェイプロセスに GUI セッションを背負わせなくて済みます。
ラベルを分けると launchctl list の曖昧さが減り、片方だけを再起動してもう片方を落とさずに済みます。
2. TL;DR — 共存のルール
- 環境ファイルは 1 つ、plist は 2 つ：両方とも同じ
EnvironmentVariables、またはProgramArgumentsのラッパーで読み込む共有~/.config/openclaw/envを使い、OPENCLAW_HOMEを plist ごとに食い違わせない。 - ポートは契約：ゲートウェイは
OPENCLAW_GATEWAY_PORT（例）で待ち受け、Mac エージェントはループバック RPC や UNIX ドメインソケットを使う——ペアを runbook に明記する。 - ThrottlePolicy：キーチェーンや Xcode ライセンス系デーモンより先に何度も respawn する場合は、Mac エージェント側に
ThrottleIntervalを検討する。 - ヘッドレス Mac：ウィンドウサーバ API が要るフローでは、永続的な GUI ログイン文脈が必要。純粋な SSH のみではアクセシビリティ許可まわりが謎失敗しがち。
3. 棚卸し：launchd が何を動かしているか
plist をいじる前に SSH で状態を採取します。
launchctl print gui/$(id -u)/ai.openclaw.gatewayおよび同様にai.openclaw.mac- macOS 13 以降：
launchctl blame gui/$(id -u)/ai.openclaw.gatewayで直近の終了理由 log show --style syslog --predicate 'process == "launchd"' --last 15mをラベルで絞る
4. launchctl 修復シーケンス（安全な順序）
- 古いジョブを bootout：
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist（ai.openclaw.macも同様）。ファイル削除ではなく実行インスタンスの除去。 - plist を再 bootstrap：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist—— 先にゲートウェイ、続けて Mac エージェント。 RunAtLoadが false のとき kickstart：launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway- 終了コード確認：
launchctl print gui/$(id -u)/ai.openclaw.gateway | grep -i lastexit
plist を編集した直後は必ず bootout のあと bootstrap。load／unload は OS 世代で意味がずれるため、現行ペアを優先します。
5. 設定の単一化チェックリスト
| 観点 | ゲートウェイ plist | Mac エージェント plist |
|---|---|---|
OPENCLAW_HOME |
インストールルートの絶対パスで一致必須。 | 同一パス。チルダ展開の罠を避け /Users/… を使う。 |
PATH |
ProgramArguments で絶対パスにしない場合は Homebrew の bin などを含める。 |
xcode-select 未整備で xcodebuild を叩くならツールチェーン側パスを追加。 |
| 秘密情報 | EnvironmentVariables、または launchd が読める 0600 ファイル。 |
同一ファイルを参照。ローテーション後に plist 間でキーが食い違わないようにする。 |
| 作業ディレクトリ | WorkingDirectory → ゲートウェイパッケージルート。 |
別ディレクトリでも OPENCLAW_CONFIG など共有設定パスは揃える。 |
| Throttle／クラッシュ | KeepAlive で正常終了を吸収する設定例あり。 |
起動直後のキーチェーン競合なら ThrottleInterval を 5 秒以上。 |
6. 専有リモート Mac — SSH ヘッドレス運用チェックリスト
自動化用マシンはシングルテナント前提が無難です。複数管理者の GUI セッションが重なると、画面収録やアクセシビリティの同意キャッシュが壊れやすくなります。
- SSH 強化：公開鍵のみ、
AllowUsers automation、長時間ビルド向けClientAliveInterval。 - セッション方針：署名用アイデンティティをキーチェーンに持つ専用オートメーションアカウントを切り、人間用デスクトップと共有しない。
- ヘッドレス GUI：ウィンドウサーバ API が要るフローでは自動ログインまたは維持されたコンソールセッションを文書化。TTY のみで安全な処理と分ける。
- 可観測性：ログを
~/Library/Logs/OpenClaw/に tee しローテーション。インシデント後はlaunchctl printのスナップショットを残す。 - アップデート：macOS メジャーアップグレードはゲート。plist 変更を本番に載せる前に
xcode-selectと公証スモークを再実行。
7. FAQ — 症状 → 疑い → 対処
| 症状 | 疑う箇所 | 対処 |
|---|---|---|
| 片方だけ起動し、もう片方が即終了 | OPENCLAW_HOME の不一致、ProgramArguments のバイナリ欠落 |
対話シェルで同じ argv を実行し、絶対パスを両 plist に貼り直す。 |
ゲートウェイログに EADDRINUSE |
古いゲートウェイやトンネルがポート占有 | lsof -nP -iTCP:<port> -sTCP:LISTEN、ゲートウェイを bootout、トンネル上流と番号を揃える。 |
SSH 手動では Mac エージェントが動くが launchd では失敗 |
環境差（HOME、TMPDIR、キーチェーン ACL） |
シェル環境を plist にミラー。オートメーション用 GUI セッションでキーチェーンを一度アンロック。 |
| 数秒ごとのフラッピング再起動 | ネットワーク／DNS 準備前にクラッシュ | ThrottleInterval を追加。ゲートウェイのヘルスが 200 を返すまで従属起動を遅延。 |
| 画面収録まわりの権限エラー | ヘッドレスユーザーが TCC プロンプトを完了していない | 物理／コンソールセッションで同意を完了。企業管理なら MDM プロファイルで配布。 |
8. このスタックは「邪魔にならない」ハードに載せる
ゲートウェイと Mac エージェントの二層は、Apple Silicon の Mac mini が得意とする負荷帯です。ネイティブ Unix サービス、予測しやすい熱挙動、タワー級ワークステーションに比べた静音性——ローカル推論とゲートウェイ I/O を同時に回しても頭打ちが出にくい構成です。macOS は launchd・SSH・開発者ツールとの相性が良く、Mac エージェント経路にわざわざハイパーバイザ下で組む必要もありません。
Mac mini M4 クラスは待機電力がごく低い一方、ユニファイドメモリ帯域でゲートウェイの同時接続と Xcode 系ジョブを支えやすく、Gatekeeper と SIP により典型的な Windows 自動化ホストより攻撃面を絞り込みやすいです。ラックを増やさず専有の常時オン Mac で OpenClaw を載せたい場合、コンパクトで静か、シングルテナント SSH に閉じやすい Mac mini M4 はバランスの良い入口になります。
上記のデュアルエージェント構成を、熱と電力で足を引っ張られない筐体に載せ替えたい場合は、ホームの Mac mini プランから 同じ plist レイアウトをレンタル／自前ホストに写経してください。今が Mac mini M4 を検討する好機です。