OpenClaw で一番つらいのはチュートリアルがターミナルで成功したあとだ。LaunchAgent が起動し、骨太さしかない PATH を継承して node が見つからず、ゲートウェイが静かに再起動を繰り返し、API 利用者には不安定な 502 が見える。2026年では macOS launchd を zsh とは別 OS とみなせ。きれいな .zprofile は読まれず、nvm の関数スイッチは知らない。シンボリックリンクを雑にすると動的リンカまで食い違う。このプレイブックではツールチェーンを pin し、環境変数を plist に焼き、本番エージェントを向ける前にレンタルの Mac mini でスモークする手順をまとめる。
深掘りは openclaw doctor のゲートウェイ診断、秘密のレイヤリングは JSON env プロファイル、共有ホストは Mac mini 隔離チェックリスト を参照。
launchd が対話前提を壊す理由
対話シェルは rc、direnv、エディタ連携を読み込む。launchd ジョブは plist スキーマに書かれた環境だけを継承する。書いていないものは未定義。だから tmux では which node が /opt/homebrew/bin/node なのに、同じユーザーの LaunchAgent ログでは command not found になる。偶然ではなく二つのブートグラフだ。
HOME も罠だ。自動化アカウントがクローンイメージ由来だと home がズレる。OpenClaw は ~/.openclaw や $OPENCLAW_HOME に状態を書く。HOME が漂流するとインシデント時に誰も設定を見つけられない。クローン運用では明示的に焼け。
CPU 時間のバケツも異なる。対話ユーザーとデーモンでは熱・電源設定が違い、Notebook と同じ体感は期待しない。
Homebrew Node／nvm／pin された tarball
Homebrew は Apple Silicon で /opt/homebrew に安定 symlink を張る。ProgramArguments から /opt/homebrew/bin/node を直接指せるので LaunchAgent に最適。nvm は人間には楽だがデーモンには脆い：バージョン切替はシェル関数であって launchd が期待するファイルレイアウトではない。どうしても nvm なら固定バージョンへパスを出すラッパーを用意し plist からそれを呼ぶ。ProgramArguments にログインシェル無しで source /.nvm/nvm.sh && nvm use を直書きしないこと。
規制産業では Node 公式 tarball を checksum し /usr/local/node-20.11.1 のように展開して pin するのが一般的だ。アップグレードは brew の自動移動ではなく意図的なファイル差し替えになる。四半期に30分は pin 替えとスモークに充てろ。飛ばすとセキュリティパッチが静かに漂流する。
Rosetta とネイティブ ARM を混在させないことも明記しろ。Intel パスを ARM ホストへコピーすると悲惨な結果になる。
LaunchEnvironmentVariables と WorkingDirectory
WorkingDirectory で OpenClaw 設定の相対パスを安定させ、openclaw.json を含むディレクトリを指す。LaunchEnvironmentVariables に PATH、許可された NODE_OPTIONS、SDK の場所を載せる。キーは12個以内を目安にし、監査で読めるサイズに留める。
StandardOutPath／StandardErrorPath はローテーション付きのサービス別ログへ。Console.app は親切だが CI grep に弱い。集中ログが無い間は 50MB ローテ・5世代が無難。
Unix ドメインソケットを書くなら、truncate 後も append 権限があるか必ず確認する。
ツールチェーン選択マトリクス
| アプローチ | デーモン親和性 | アップグレード摩擦 | 向く場面 |
|---|---|---|---|
| Homebrew Node | 高 | 中（パス変動） | 小規模チーム・単一ゲートウェイ |
| nvm デフォルト別名 | ラップ無しなら低 | 人間には低 | ノートのみ、LaunchAgent には不向き |
| pin tarball | 非常に高 | 高（手解凍） | コンプライアンス重視 |
緊急ロールバックでは tarball ディレクトリを差し戻せる一方、brew は深夜に動いてしまうことがある—ロックファイルや禁止ウィンドウを運用で縛れ。
5分スモーク手順
launchctl print gui/$UID/com.yourorg.openclaw.gatewayで最終退出理由がゼロか確認。curl -fsSでヘルスを二度、間に10秒スリープして遅延 TLS リロードを捕捉。/usr/bin/trueにフォークする無害ツール呼び出しで子プロセス PATH を検証。- ログを一度ローテして truncate 後も append できるか見る。
launchctl bootoutで止め、再起動し30秒以内に同一ポートへバインドするか確認。
人手だと四番目をディスク逼迫直前まで忘れる。シェルスクリプトを infra リポへ。
リバプロがあるなら upstream keep-alive とゲートウェイ reload の競合もセットで見る。
PATH ドリフトを捕まえる doctor
openclaw doctor は版ズレ・欠落バイナリ・空の環境を赤くする。LaunchAgent を所有する同一アカウントで実行し、管理者分離なら sudo -u でも比較する。対話 doctor が Node 20.11 なのに plist ログが 18.19 なら二 toolchain が戦っている。
TLS ストアを叱られたら OpenClaw 本体より先にキーチェーン信頼を直せ。macOS アップデートで中間証明書が動き「上流403」に見えることがある。詳細は doctor 記事 へ。
ファイル権限と umask
LaunchAgent はユーザ既定 umask で動き、対話シェルで chmod した前提の 0022 と違うことがある。共有ディレクトリにソケットや pid を置くなら「昨日動いた」に頼らずグループ読みを明示。複数オペレータがミニを共有するなら POSIX グループを揃え ACL は慎重に。世界読みディレクトリはセキュリティレビューで必ず聞かれる。
Gatekeeper の隔離属性も忘れるな。ダウンロードしたバイナリに com.apple.quarantine が付くと薄いログでは PATH 間違いに見える。checksum 後に意図的に剥がす。無差別 xattr -d は避ける。
アップグレード窗と孤児 plist
Node のバンプと OpenClaw リリースを協調させろ。ステージでランタイム先行→スモーク→メンテ窗で本番。ロールバック手順には旧 plist の ProgramArguments を含める。Git に世代付き plist を最低二本。
グローバル npm は Intel と Apple Silicon でホームが違う。Intel Mac から plist をコピペしたら絶対パスを全部見直せ。
FAQ
ターミナルでは動く OpenClaw が LaunchAgent で落ちるのはなぜ？
ターミナルは shell 初期化を読むが launchd は読まない。PATH と toolchain は plist かラッパで明示する。
plist から nvm use を呼ぶべき？
避ける。絶対パスのバイナリか、対話 source を使わない固定 NODE_HOME ラッパを使う。
初回スモークはどのくらい？
少なくとも5分の安定トラフィックと再起動サイクルで遅延 import と権限を拾う。
TCC はどこ？
カメラ・マイク・連絡先・AppleScript など GUI 承認が一度必要な経路がある。VNC 付きマシンでリハーサルせよ。
初回安定性は結局ハードウェアの形をした問題だ。本番ゲートウェイが触れるのと同じ Apple Silicon 挙動、同じキーチェーン、同じファンカーブが必要。MacHTML の クラウド Mac mini を1日約16.9ドルで借りれば調達遅延なく参照機を得られる。plist は SSH、TCC は VNC、スモークが終われば解体—睡眠で websocket を落とす開発ノートよりマシだ。
Apple Silicon の効率は長時間 doctor と合成トラフィックにも効く。静音で電力が読みやすく、ファイルロックを嘘つく Linux コンテナで macOS を擬態する必要もない。
実機 macOS で OpenClaw LaunchAgent をリハーサル
クラウド Mac mini を借りて PATH・plist ブートストラップ・doctor スモークを Apple Silicon で固めてから本番カットオーバーへ。