2026年 OpenClaw 定時タスク／スケジューリングが macOS ヘッドレス専用リモート Macで動かない／タイムアウトする？ゲートウェイライフサイクル、環境変数と launchd の突き合わせ——再現チェックリスト＋FAQ
専用リモート Macをヘッドレスで運用していると、OpenClaw の「あとで実行」系は地味な理由で失敗しがちです。ゲートウェイ再起動でメモリ上のタイマが消えた、launchd ジョブの PATH が SSH のログインシェルと違う、省電力ポリシーで「空いているはず」の時間まで実行が遅延した、など。本稿ではスケジューラ症状とゲートウェイライフサイクルを分離し、launchd と対話シェルの対照、SSH で再現できるチェックリストを整理します。バックグラウンド実行と SSH 運用の落とし穴は 2026年 OpenClaw & SSH自動化深掘り実践：落とし穴回避・安定バックグラウンド実行・安全デプロイ、専用 Mac 上の書き出しとキュー／タイムアウトの整理は Unity iOS 書き出し：リモート Mac mini + Xcode 完全ガイド (2026) を参照してください。
1. まず分類する（TL;DR）
そもそも動かない： launchd が読み込まれていない、ユーザコンテキストが違う、EnvironmentVariables が足りない、ゲートウェイプロセスが生きていて仕事を受け取れない、などが疑われます。
動くがタイムアウトする： コールドキャッシュ、ヘッドレスで Keychain プロンプトが詰まる、モデル API へのネットワーク、同時実行制限——しばしば「スケジューラのバグ」と誤読されます。
- ログの一点： 同一の壁時計ウィンドウで、ゲートウェイの標準出力／標準エラーと、ラッパーの
StandardOutPath/StandardErrorPathを突き合わせる。 - 環境の一点：
OPENCLAW_*は SSH セッションだけでなく、launchd ジョブ内で印字して確認する。 - ライフサイクルの一点： 予定時刻と実行のあいだにゲートウェイが再起動したか（設定リロード、OOM、手動の
launchctl kickstartなど）。
2. ゲートウェイライフサイクルと「スケジューラ」
OpenClaw は長寿命接続やルーティング状態をゲートウェイプロセス内に持つことが多いです。そのプロセスが終了すると、メモリ上にしかなかった遅延実行やタイマは、期待した時刻どおりに発火しないことがあります——launchd がすぐにバイナリを立ち上げ直したとしても同様です。
再現しやすい確認：
- 設定ホットリロード、ポート競合、
OPENCLAW_GATEWAY_TOKENローテーションなど、再起動の前後でログを対応づける。 - 「絶対に逃せない」タスクは外部の cron／
launchdから薄い CLI を叩く durable なスケジューリングを優先し、ゲートウェイ内タイマはドキュメント上ベストエフォートと割り切る。 launchctl bootoutとbootstrapのサイクルのあと、ペアリングとワーカ健全性を再確認してから次の実行を信頼する。
3. 環境：揃えるべき「三つの世界」
ヘッドレス Mac では、SSH ログインシェル、GUI セッション、launchd がそれぞれ別のファイルを読み、PATH も異なります。
| コンテキスト | 典型的な環境の出どころ | リスク |
|---|---|---|
launchd LaunchAgent |
Plist の EnvironmentVariables／ラッパースクリプト |
HOME、PATH、API キーが欠ける |
| SSH 対話 | ~/.zprofile、~/.zshrc |
「SSH では動く」がデーモンでは動かない |
macOS cron |
環境は最小限；PATH に Homebrew が無いことが多い |
黙って失敗／別バイナリを叩く |
修正パターン： 秘密情報とパスを一箇所（専用の env ファイルなど）に集約し、plist か小さなラッパーから明示的に読み込む——対話シェルの初期化に依存しない。
4. launchd チェックリスト（再現順）
リモート Mac に SSH したうえで、次の順に潰します。
- Label とドメイン： ユーザエージェントは
~/Library/LaunchAgentsに置きユーザ単位で読み込む。システムデーモンと混ぜると「一度も動かない」典型原因になります。 - Program と引数： バイナリと設定ファイルは可能な限り絶対パス。
- WorkingDirectory： 相対パスや Unix ソケットを使うなら明示。
- RunAtLoad / StartCalendarInterval / StartInterval： トリガーが「起動時」か「時計」か、認識と一致しているか。
- ThrottleInterval / KeepAlive： 短い再起動ループでスケジュール作業が飢餓していないか。
- StandardOutPath / StandardErrorPath： 必ず tail できるファイルへ。ヘッドレスの切り分けはここが生命線です。
- リソース上限： 負荷時にファイル記述子やメモリで詰まっていないか。
5. ヘッドレス専用リモート Mac 特有の論点
- 電源とスリープ： 省エネ設定やデスクトップでも一部サブシステムが省電力側に寄ることがある。無人運用の前提と矛盾していないか。
- GUI と SSH： ウィンドウサーバやアクセシビリティ API が要る処理は、ログイン済みコンソールが必要な場合がある。純粋な SSH とは置き換えられません。
- タイムゾーン： スケジュール調査では
TZと壁時計をログに残す。リージョン違いのオペレータが「遅い」と誤読しがちです。 - ディスク I/O： リモートディスクや同時 CI／モデル取得でタイムアウトが跳ねることがある。
6. FAQ——症状から次の一手へ
| 症状 | ありがちな原因 | 次の一手 |
|---|---|---|
| ログにジョブが現れない | Plist 未読み込み／ユーザ違い | launchctl list、bootstrap、ドメイン修正 |
| SSH 手動では動くが cron では動かない | PATH／環境のずれ |
絶対パス、plist へのインライン環境 |
| 一定時間でタイムアウト | クライアント側デッドライン vs コールドスタート | キャッシュを温める、プリフライトと本処理を分離 |
| 設定変更のあと不安定 | ゲートウェイ再起動でタイマ喪失 | スケジュールを外部化、再起動ログを確認 |
Mac mini なら、スケジュールは「地味に」安定しやすい
スケジューリングの信頼性は、多くの場合プロセスの安定性、環境の継承が正しいこと、電源状態が予測できることに分解できます。Apple Silicon の Mac mini は、そのあたりを静かに満たしやすい筐体です。macOS は一般的なデスクトップに比べ長期間クラッシュしにくく、待機電力も低いため、常時ゲートウェイと定期ジョブがサーマルやファン曲線と争いにくいです。
開発者・運用者にとっては、ネイティブ Unix ツールチェーン、予測しやすい launchd の意味論、SSH ファーストのワークフローが揃うと、plist が正しければ「手元のノートだけ動く」系の驚きが減ります。Gatekeeper と SIP も、cron ラッパーをすり替えるクラスの事故を抑えます。
24/7 のデスク常駐向けに設計されたハードウェアで本チェックリストを回したいなら、コンパクトで効率的、ラボ機器の横に置きやすい Mac mini M4 は現実的な出発点です。
SSHMac のトップページから、同時実行・ストレージ・常時ゲートウェイの要件に合うプランを選べます。