OpenClaw バックグラウンドデーモンと launchd

2026 OpenClaw デーモンとバックグラウンド：
launchd・ログ・復旧チェックリスト

常時稼働の OpenClaw で壁になるのは、SSH 切断で死ぬこと、launchd が即終了すること、ログが見つからないことです。本稿は openclaw onboard --install-daemon、前景との違い、表、5 手順、3 指標、関連ガイドへのリンクをまとめます。

01. 3つの痛み

OpenClaw を長時間動かすと、ノートのスリープ・SSH 切断・ログ欠落の三つで詰まりがちです。本稿は基本インストール後、launchd 相当の再現性（再起動方針・統合ログ・手順化された復旧）を求める運用者向けです。

1) セッション依存：ターミナルや SSH の前景実行はハングアップで終了します。スリープやシェル終了と同時にサービスが止まり、launchd が無いと常駐できません。

2) 古い plist パス：Node や CLI の移動後も LaunchAgents が旧バイナリを指すと、ジョブは読み込まれているのに不透明な終了コードで即終了します。

3) ログ分散：標準出力だけでは TCC 拒否やカーネル側メッセージが見えず、log show に載る情報が欠落すると切り分けが推測頼みになります。

グローバル CLI だけ更新してエージェントを再読み込みしないと「新 CLI・旧デーモン」のズレが出ます。OS 更新や手動の brew upgrade node のたびに plist を差分管理してください。

02. openclaw onboard --install-daemon

オンボーディングは魔法ではなく足場作りです。触るファイルを把握しておくと、OS 更新後や手動アップグレード後のずれ調査が速くなります。

典型的にはユーザ LaunchAgents の plist を書き、環境と作業ディレクトリを揃え、ログイン後の自動起動を登録します。エージェントを読み込むのと同じ macOS ユーザで入れてください。sudo と GUI ログインユーザを混在させると典型的な失敗になります。前提整理は インストール・デプロイガイド から。

日払い Mac では解放時のデータ消失を前提に、ワークスペース鍵と plist の控えを取ってください。詳細は 日払いデプロイの落とし穴。SSH シェルと GUI ログインで PATH が食い違う場合は EnvironmentVariables を入れるか、ProgramArguments は絶対パスに寄せます。

開発と本番で Label やポートが重複するとフラップします。環境ごとにラベルとソケットを名前空間分離してください。アクセシビリティや連絡先などのプライバシー確認は一度 GUI セッションが要ることがあり、レンタル Mac では短時間の VNC で許可してから SSH メンテに戻るのが現実的です。

03. 前景と launchd

観点 前景 ユーザ LaunchAgent
用途デバッグ・初回長時間・無人
寿命端末・SSH に連動launchd 管理、KeepAlive は任意
調査ターミナル出力launchctl・コンソール・log show・plist

終了コードの意味は コマンドエラー FAQ と突き合わせてください。KeepAlive の過剰設定は再起動ストームを招きます。まず前景で設定を直してからデーモンに戻すのが安全です。

04. 5ステップ復旧

障害時は手順を飛ばさず直列で進めてください。いきなり再インストールすると、同じ誤字の plist を再生成して根本原因が隠れます。

  1. launchctl list | grep -i openclaw で PID と LastExitStatus を記録。ジョブ自体が無い場合は、正しい GUI ユーザ向け（gui/$(id -u)）に読み込んだか、誤って root のシステムドメインだけを見ていないか確認します。
  2. log show で node や openclaw に絞った述語で直近1時間を取得し、チケットに添付。絞り込みが強すぎると見逃すので、必要なら com.apple.xpc.launchd がラベルを参照する行まで広げます。
  3. ~/Library/LaunchAgents/*.plist を開き、ProgramArguments・WorkingDirectory・書き込み可能パスを検証。シェルが展開する ~ と launchd の扱いは一致しないことがあるため、明示設定を確認します。
  4. launchctl bootout で一旦外し、plist を修正し、macOS の版に合わせて bootstrap または従来の load で戻します。古い macOS では unload/load でした。運用ドキュメントに版別コマンドを固定しておくと深夜のミスが減ります。
  5. OpenClaw をロールバックするか openclaw onboard --install-daemon を再実行し、重複 plist を削除。ロールバック後はインストール直後と同じスモーク（チャネル・Webhook の応答）を必ず繰り返します。
ls ~/Library/LaunchAgents/ | grep -i openclaw
launchctl list | grep -i openclaw

切り分けは システムより先にインフラ：ディスク空き・時刻同期・DNS/TLS。これを飛ばすとアプリ設定を空振りします。共有ビルド Mac では plist 変更を版管理すると再現性が上がります。

05. 指標と低スペック Mac

  • 1: 失敗から 15 分以内に統合ログを保存（ローテーション前）。
  • 2: RAM が持続的に 80% 超なら Node 系デーモンの OOM リスクが上がります（8GB 構成に注意）。
  • 3: 一定の短周期クラッシュは設定起因、間隔がランダムならリソース・ディスク満杯・ネット断を疑います。

Xcode やシミュレータが CPU を奪うとイベントループが飢餓します。負荷を分離するかマシンを分けてください。メモリと安定ホストについては 料金 と リモート接続ガイド を参照。コンテナ本番の型は 本番デプロイ にありますが、ネイティブ macOS の中心は依然として launchd です。

06. tmux と専用 Mac

週次のヘルスチェックとして launchctl list の状態・空きディスク・API 遅延を表に出すと推移が見えます。tmux/screen/nohup はスリープや電源管理との統合が弱く、plist ベースの健全性チェックとも相性が悪いです。launchd は再起動後の復帰と電源イベントの扱いに強いです。

検証は インストール検証 を仕上げたうえで本チェックリストを当て、異常時は コマンドエラー FAQ と突き合わせてください。低コスト試行は 日払いとローカル費用の比較。プラン詳細は 料金 です。

07. OpenClaw デーモンで効く plist キー

Label と ProgramArguments 以外にも信頼性を左右するキーがあります。WorkingDirectory は launchd が起動する前に実在している必要があり、オンボーディング時のシンボリックリンクが後から壊れると即終了します。RunAtLoad は plist 読み込み直後に起動するかどうかを決め、ノートでは「手動起動想定」と衝突しがちです。

ThrottleInterval はクラッシュループの CPU 飽和を抑えますが、根本原因の隠蔽にならないよう前景で設定修正を先に済ませてください。EnvironmentVariables には対話シェルが頼っていた PATH や NODE_OPTIONS、API 向け先の上書きを重ねがけします。将来のアップグレードで変数が消えないよう社内 Wiki にキー単位で記録してください。

複数環境では Label を積極的に名前空間化します。重複ラベルは二枚目の plist を静かに失敗させたり、先に載ったジョブと競合させます。com.example.openclaw.prod と .staging のように分け、新しい macOS では launchctl print gui/$(id -u) で実効グラフを確認すると確実です。

08. ログ：統合ログ・ファイル・ローテーション

デーモン化後はターミナル出力だけに頼れません。インシデント中は log stream や log show の述語を主軸にし、必要なら plist に StandardOutPath と StandardErrorPath を足してテキストログを永続化します。ディスク肥大に注意し、外部共有前に権限とマスキングを確認してください。トークンが stderr に出る場合があります。

launchd の時刻とアプリ側ログを突き合わせ、PID の再利用で時系列が混乱する場合は log show --style syslog ヘッダのブートセッション UUID をメモします。日払い Mac ではインスタンス解放前にログを退避してください。エフェメラルディスクは次利用者で残らないことがあります。

09. スリープ・電源・ヘッドレスクラウド Mac

ノートはスリープし、多くのクラウド Mac はワークステーション設定のままです。Power Nap やスリープに入るとバックグラウンド通信が予測しづらく止まります。常時エージェントでは方針が許す範囲で AC 接続時のスリープを pmset で抑止するか、設定修正までの橋渡しに caffeinate を限定的に使います。誰が省電力プロファイルを戻せるかを文書化しないと、善意の既定値復元で夜間ジョブだけが静かに死にます。

データセンターの Mac mini では、Node の CPU を長時間叩いたときのサーマルとファン挙動を確認してください。スロットリングはプロセスが落ちなくても外向き Webhook の遅延として現れることがあります。

10. 権限・TCC・GUI 限定プロンプト

画面収録・アクセシビリティ・カレンダーなどに触れる機能は 透明性・同意・管理（TCC） の承認が要ることがあり、純粋な SSH デーモンでは入力待ちで停滞します。初回同意は一度 VNC などのグラフィカルセッションで完了し、付与済み権限のチェックリストと、セキュリティチームの許可があればポリシーのスナップショットを残します。ユーザ再構築や plist 移行後は再プロンプトが必要になる場合があります。

Apple Silicon で Rosetta を跨ぐ構成では、plist が意図したアーキテクチャのバイナリを指しているか確認してください。ログインシェルが nvm フックを読み込みデーモンが読まない、という組み合わせで「シェルでは動くのに launchd だけ失敗」が起きがちです。

11. アップグレードとロールバックのリズム

OpenClaw の更新は他の本番依存と同様に、版の固定・リリースノート確認・非本番 Mac でのステージングを徹底します。更新後は launchctl bootout と再読み込みで新しいバイナリパスを確実に拾わせます。直前の node_modules ツリーやロックファイルのアーカイブを残し、迅速なロールバック路を確保してください。

手順のリハーサルに隔離ハードが欲しいとき、短期の 日払い Mac で plist 編集・権限プロンプト・launchd リロード周期を安く試せます。合成負荷を一週間問題なく回せたら、同じ plist テンプレを共有インフラへ昇格させます。段階を踏むほどページャ騒ぎが減り、業務フローへの応答性が保たれます。

12. 監視フックと合成チェック

本番デーモンには API と同程度の可観測性を付けます。1 分おきに叩ける軽量な ヘルスコマンド（例：openclaw status や HTTP プローブ）を用意し、連続 3 回失敗でアラート、といった具合にフラップを抑えます。終了コードで拾えないシグネチャは統合ログベースのアラートを併用します。

夜間にチャット・メール・ファイルなど実際のチャネルを叩く 合成会話 やツール呼び出しをスケジュールし、所要時間と成功を記録します。メモリリークやディスクリプタ上限の手前では、遅延の悪化がハード障害に先行します。ダッシュボードはビルドファーム監視と同じ入口に寄せ、当番が二重ログインしなくて済むようにします。

深刻度 を文書化します。黄はエージェント再起動、赤は待機 Mac へフェイルオーバーや版の巻き戻し、など具体コマンド（launchctl kickstart、plist 再読み込み、パッケージダウングレード）まで紐づけます。四半期にステージングで plist を意図的に壊すゲームデイを行い、手順の穴を炙り出してください。資産台帳には OpenClaw を載せるシリアルやレンタル ID、plist 版、OS アップグレード承認者を記録し、設定ドリフトを早期に検知します。

13. 常時稼働エージェントのセキュリティ姿勢

常時オンラインのデーモンは、読み込んだアカウントの権限をそのまま引き継ぎます。そのアカウントをサービス ID のように扱い、ディスク上は最小権限、不要な管理者権限は避け、秘密情報はプレーンな plist や Git ではなくキーチェーンやボールトへ。API 鍵は CI トークンと同じ周期でローテし、再起動なしで回せる担当を決めておきます。

外向き通信は明示的にホワイトリスト化し、方針が許せばホストファイアウォールやプロキシで絞ります。接続失敗をアプリエラーと区別してログに残すと、権限問題と一時的な DNS 失敗を切り分けやすくなります。リモート Mac 群では VPN やゼロトラストを、自動化が触れるリージョンと整合させ、地理ブロックの不意打ちを避けます。

版変更のたびに plist と環境のスナップショット をバックアップします。~/Library/LaunchAgents、関連シェルプロファイル、マスク済み launchctl print 出力を tarball にすると監査と将来の自分への再現性が上がります。変更履歴には日付・担当・理由・ロールバック手順を短く残し、ヒーロー的な深夜調査を減らします。

ツール実行が可能なアシスタントではファイルシステム範囲を厳しくし、世界書き込み可能パスを避け、ユーザが更新できるバイナリには整合性チェックを検討します。レンタル Mac を実験で共有する場合はテナント間でユーザを分け、他人のトークンを LaunchAgents が引き継がないようにします。侵害が疑われるときの キルスイッチ（アンロード・資格情報失効・関係者通知）をステージングで演習し、本番で初めてコマンドを考えないようにしてください。

大きな macOS アップグレードのたびに権限ダイアログ・ハードンドランタイム・Gatekeeper の変化を再確認し、plist の文字列が同じでも挙動が変わり得ることをリリースチェックに組み込みます。セキュリティと信頼性は同じ土台、すなわち平時と異常時の双方で予測可能な launchd 挙動に立脚します。