macOS launchctl の基本 - launchd でジョブを動かす（plist と新旧コマンド）

「Mac で定期実行したい」「常駐プロセスを自動起動したい」——cron ではなく launchd / launchctl の出番です。ただ launchctl は新旧2系統のコマンドがあって混乱しがち。この記事では、plist の書き方と新構文（bootstrap 系）を中心に、基本を整理します（man・Apple 公式を一次ソースに確認）。

launchd / launchctl とは

• launchd: macOS の統合サービス管理（Tiger / 10.4〜、PID 1）。従来の init・cron・xinetd 等を置き換える存在
• launchctl: その launchd を操作する CLI
• 基本はオンデマンド起動。条件（ログイン・時刻・間隔など）に応じてジョブを起動します

LaunchAgents と LaunchDaemons

まず「Agent か Daemon か」を決めます。これで置き場所と権限が変わります。

• GUI を使う・ユーザー権限でよい・自分のログイン中だけ → Agent
• ログイン前から・root で・常時 → Daemon

plist の基本

ジョブは plist（XML）で定義します。主なキーは次のとおり。

最小例（ユーザー Agent）:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.myjob</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/myscript.sh</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/myjob.out</string>
  <key>StandardErrorPath</key>
  <string>/tmp/myjob.err</string>
</dict>
</plist>

定期実行・常駐の指定

<key>StartInterval</key>
<integer>300</integer>

<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key><integer>3</integer>
  <key>Minute</key><integer>55</integer>
</dict>

<key>KeepAlive</key>
<dict>
  <key>SuccessfulExit</key><false/>
</dict>

StartCalendarInterval は Minute / Hour / Day / Weekday / Month を指定でき、省略したキーはワイルドカード。スリープ中に来た時刻は、次回起動時に1回だけ実行されます（cron 同様、溜まって連発はしない）。

新コマンド（bootstrap 系）と旧コマンド

macOS 10.10 以降はドメイン指定の新構文が推奨です（旧 load/unload も動きますが非推奨）。

• ドメイン: Agent は gui/$(id -u)、Daemon は system（sudo 必要）

Daemon の場合は sudo ＋ system ドメイン:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.foo.plist
sudo launchctl bootout    system/com.example.foo
sudo launchctl print      system/com.example.foo

実用フロー

# 1. plist を検証（構文チェック）
plutil -lint ~/Library/LaunchAgents/com.example.myjob.plist
 
# 2. パーミッション（Agentは644・自分の所有でOK）
chmod 644 ~/Library/LaunchAgents/com.example.myjob.plist
 
# 3. 読み込み
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.myjob.plist
 
# 4. 確認
launchctl print gui/$(id -u)/com.example.myjob
launchctl list | grep myjob

plist を変更したら「bootout → bootstrap」

launchctl bootout    gui/$(id -u)/com.example.myjob
launchctl bootstrap  gui/$(id -u) ~/Library/LaunchAgents/com.example.myjob.plist

よくある落とし穴

• 絶対パス必須: launchd の PATH は最小限。スクリプト内のコマンドもフルパスで書く（WorkingDirectory も絶対パス）
• ログ出力先を指定しないと消える: StandardOutPath / StandardErrorPath を必ず設定。デバッグの命綱
• Daemon にユーザー環境は無い: HOME や dotfiles、PATH は引き継がれない。必要なら EnvironmentVariables で明示
• Label の重複禁止: 重複するとロード失敗
• すぐ終わるプロセスは再起動が抑制される: 既定の ThrottleInterval（約10秒）より短時間で終了し続けると、launchd がクラッシュ扱いにして再起動を保留
• SIP 保護領域（/System/Library/...）は触らない
• launchctl print の出力はスクリプトでパースしない（Apple がリリースごとに変わりうると明言）

まとめ

• まず Agent（ログイン時・ユーザー）か Daemon（起動時・root）かを決め、対応する場所に plist を置く
• plist は Label ＋ ProgramArguments が基本。定期実行は StartCalendarInterval / StartInterval、常駐は KeepAlive
• コマンドは新構文（bootstrap / bootout / kickstart / print）を使う（旧 load/unload は非推奨だが動く）
• 流れは 作成 → plutil -lint → 配置 → bootstrap → print/log。変更時は bootout → bootstrap
• ハマりどころは 絶対パス・ログ出力先・最小PATH・10秒スロットル

cron に慣れていると最初は戸惑いますが、plist ＋ bootstrap/bootout の型さえ掴めば、Mac の定期実行・常駐は launchd で完結します。ちなみに筆者はこの検証を tmux のペインから叩いていました（tmux のペイン位置の指し方）。シェルスクリプト側の安全策はset -euo pipefailも合わせてどうぞ。

参考リンク

• launchd.plist(5) man page（manpagez）
• Creating Launch Daemons and Agents（Apple Developer）
• A launchd Tutorial（launchd.info）
• launchctl（ss64.com）
• tmux のペイン位置の指し方（当ブログ）