macos-launchd

macos-launchd

目的

このスキルは、バックグラウンドプロセスの実行、ログイン項目の管理、OpenClaw ゲートウェイサービスの設定などを目的に、LaunchDaemons や LaunchAgents を含む macOS の launchd サービスを管理します。plist ファイルと launchctl を使ったサービスの作成、読み込み、制御に重点を置いています。

使用する場面

システム起動時にスクリプトを実行する（LaunchDaemon）、ユーザーログイン時にアプリを実行する（LaunchAgent）、OpenClaw ゲートウェイサービスを再起動後も確実に動作させるなど、macOS サービスを自動化する必要がある場合にこのスキルを使用します。永続性が必要なシステムレベルのタスクや、OpenClaw を macOS 環境に統合する際に適用してください。

主な機能

• LaunchDaemons／Agents 用の plist ファイルを作成・編集し、Label、ProgramArguments、RunAtLoad などのキーを指定します。
• launchctl を使ってサービスを読み込み／読み込み解除し、実行を制御します。
• AppleScript の System Events または launchctl 相当の機能を使ってログイン項目を管理します。
• 認証用の $OPENCLAW_API_KEY などの環境変数を使って、ゲートウェイを実行するサービスを設定し、OpenClaw と統合します。
• 有効化／無効化などのサービス状態を管理し、Console.app でログを監視します。

使用パターン

タスクを実行するには、まず /Library/LaunchDaemons（システム全体用）または ~/Library/LaunchAgents（ユーザー固有用）に plist ファイルを作成します。launchctl コマンドを使って管理してください。OpenClaw と統合する場合は、plist にゲートウェイコマンドを記述し、環境変数を参照します。読み込み前に、必ず plist の構文を検証してください。プログラムからアクセスする場合は、たとえば osascript を使う AppleScript でログイン項目を追加します。

主なコマンド／API

• launchctl load [-w] /path/to/com.example.plist を使ってサービスを読み込みます。-w フラグは、永続ストレージに書き込みます。
• launchctl unload [-w] /path/to/com.example.plist で読み込みを解除します。
• サービスを起動／停止するには、launchctl start com.example.label または launchctl stop com.example.label を使います。
• plist の形式例（XML）：

  <?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.service</string>
      <key>ProgramArguments</key><array><string>/usr/bin/python3</string><string>/path/to/script.py</string></array>
      <key>RunAtLoad</key><true/>
    </dict>
  </plist>
  

• OpenClaw ゲートウェイの状態を確認するには、launchctl list | grep openclaw を使います。
• API に関する注意：直接利用できる API はありません。launchctl CLI または Swift の SystemConfiguration フレームワークを介して操作します。ユーザーコンテキストには、たとえば SCDynamicStoreCopyConsoleUser() を使います。

統合に関する注意

OpenClaw と統合する場合は、たとえば <string>/path/to/openclaw-gateway --key $OPENCLAW_API_KEY</string> のように、ProgramArguments の下にゲートウェイサービスを配置します。plist で EnvironmentVariablesOPENCLAW_API_KEYyour_key を使って環境変数を設定します。UserNameyourusername を追加し、正しいユーザーとしてサービスが実行されるようにします。スキル間の統合では、macos クラスターを参照してください。launchctl にアクセスできるよう、export PATH=$PATH:/usr/bin のようにパスをエクスポートします。

エラー処理

launchctl の終了コードを確認してください。成功時は 0、エラー時（plist が無効な場合の 78 など）は 0 以外です。読み込み前に plutil -lint /path/to/com.example.plist で構文エラーを解析し、検証します。サービスが失敗した場合は、launchctl error <label> を使うか、log show --predicate 'subsystem == "com.apple.launchd"' でシステムログを確認してください。OpenClaw の認証に失敗した場合は、$OPENCLAW_API_KEY が設定済みで、有効期限が切れていないことを確認してください。launchctl kickstart -k com.openclaw.gateway でサービスを再起動します。競合を避けるため、編集後は必ずサービスの読み込みを解除してから再読み込みしてください。

使用例

1. ログイン時にスクリプトを実行する LaunchAgent を作成する：まず、上記の形式で ~/Library/LaunchAgents/com.example.login.plist に plist ファイルを書き込み、次に launchctl load -w ~/Library/LaunchAgents/com.example.login.plist を実行します。確認するには、launchctl list | grep com.example を使います。
2. OpenClaw ゲートウェイを LaunchDaemon として設定する：ProgramArguments/path/to/openclaw-gateway--key$OPENCLAW_API_KEY を含む /Library/LaunchDaemons/com.openclaw.gateway.plist を作成し、sudo launchctl load -w /Library/LaunchDaemons/com.openclaw.gateway.plist を実行します。launchctl list com.openclaw.gateway で監視します。

グラフ上の関連性

• 関連先：macos（クラスター）。「macos」や「services」などのタグを共有しています。
• リンク先：launchd（タグ）。システム管理などの関連スキルに関連します。openclaw（埋め込みヒント）。ゲートウェイ固有の統合に関連します。
• 接続先：plist（タグ）。ファイル管理スキルに関連する可能性があります。launchctl（説明）。macos クラスターのコマンドラインユーティリティに関連します。