OpenClaw 2026 クラウドMac バージョンアップグレード障害切り分け： ディスク事前チェック、launchd 残留ジョブ削除と update restart health チェックリスト

初回インストール onboardやlaunchd Token トラブルシュートとは異なり、本記事は「Gateway 稼働中でローリングアップグレードが必要」なパスに焦点を当てます。SSH でレンタル期間内のクラウドMacにログインし openclaw update を実行、数分で本番復帰を期待するのに launchd 再起動ループに陥る、という状況です。

on-call 振り返りでは、次の五つの痛点が過小評価されがちです。

• plugin-runtime-deps ENOSPC：2026.4.24 付近のバージョンはアップグレード時に ~/.openclaw/plugin-runtime-deps へ bundled 依存関係を展開します。ディスク余裕不足で mid-operation 失敗し、Gateway は ready 表示のまま実際は unhealthy になることがあります（openclaw#71835 参照）。
• stale ai.openclaw.update.* ジョブ：beta アップグレード後、launchd に updater job が残留し exit 127 で Gateway 再起動を繰り返すと、gateway status --deep プローブが失敗します（openclaw#81859 参照）。
• 混合バージョン false-ready：CLI は更新済みだが Gateway プロセスが旧版のまま、またはプラグイン読み込み失敗が「成功」表示を阻害せず、リモートクライアントの Health Check が pending のまま残ります。
• 複数 Node インストールパス：2026.5.20 以降 openclaw update は Gateway サービスをホストする Node を優先使用します。Homebrew Node と fnm Node が共存すると restart 時に誤ったバイナリへ切り替わる可能性があります。
• 契約期間と時間窓の圧力：日次/週次レンタルのインスタンスでアップグレード中に ENOSPC が発生すると、一時拡張か第二ノード並列化の判断窓が極めて短くなります。事前に契約期間マトリクスでバッファを確保してください。

覚えておく口訣：「先に df、次に update、deep status、doctor で job 削除、health 200 で完了」。ディスク事前チェックや残留ジョブ削除を省略すると、10分のアップグレードが数時間の手戻りになります。

openclaw update を実行する前に、表で「ストレージ / 計算リソース / 時間窓」を揃え、アップグレード途中でコンソールから拡張ボタンを押す事態を避けましょう。

WeChat ClawBot チャネルも併用している場合、アップグレード窓内では新規 QR バインディングを一時停止し、Gateway restart health 通過後に openclaw gateway restart でチャネル再接続することをおすすめします。

アップグレード前に非対話スクリプトでディスクと staging ディレクトリを検証し、深夜の on-call を避けましょう。

df -h / | awk 'NR==2{print "avail="$4,"use="$5}'
du -sh ~/.openclaw/plugin-runtime-deps 2>/dev/null || echo "no staging yet"
launchctl list | grep -E 'openclaw\.(gateway|update)'
openclaw --version
openclaw gateway status --json | head -c 400

• 引用可能：plugin-runtime-deps パス — デフォルト ~/.openclaw/plugin-runtime-deps。OPENCLAW_PLUGIN_STAGE_DIR で独立ボリュームへ指定可能。メジャーアップグレード一回あたり ≥ 8–15 GB の連続空き容量を確保（インストール済みプラグイン数に依存）。
• 引用可能：ENOSPC 典型ログ — failed to install bundled runtime deps: Error: ENOSPC: no space left on device。この場合 update を繰り返さず、先に拡張するか不完全 staging を rm -rf してから再試行してください。
• 引用可能：ルートボリューム警告閾値 — 本番環境ではルートボリューム使用率を長期的に < 80% に維持。 85% 超過時は OpenClaw アップグレードと Xcode キャッシュ書き込みの失敗率が著しく上昇します。

1. 設定と Token スナップショット：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)；現在の openclaw --version と gateway status --deep JSON を記録。
2. 事前チェックスクリプト実行：ルートボリューム空き ≥ 15 GB を確認；異常に大きい staging がないこと；launchd 内 openclaw 関連 job を一覧表示。
3. 低負荷時間帯で update：openclaw update（または npm update -g openclaw / brew upgrade openclaw、インストールパスと一致させる）；CLI 出力の restart health セクションを確認。
4. deep status プローブ：openclaw gateway status --deep；Connectivity probe は ok であること。stale updater job 表示時は次節の手順で削除後 kickstart。
5. doctor と health HTTP：openclaw doctor；curl -sf -H "Authorization: Bearer token $(openclaw config get gateway.auth.token)" http://127.0.0.1:18789/health が 200 を返すこと。
6. バージョン基線登録：CLI と Gateway hello バージョンを変更記録へ記載；料金ページでプラグインキャッシュ増加に伴う長期 1TB 必要性を評価；リモートクライアントペアリングテストを復旧。

openclaw update
openclaw gateway status --deep
openclaw doctor
curl -sf http://127.0.0.1:18789/health
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

2026.5.20 以降 openclaw update は CLI/Gateway 間に一版のプロトコル skew があっても restart health を試行し、Gateway サービスをホストする Node を優先使用して後続コマンドを実行します。「update 成功だが Gateway が誤った Node で動作」の確率を下げます。

gateway status --deep が connectivity failed を報告し、launchctl list に高 RunCount の ai.openclaw.update.* がある場合、公式診断に従い stale updater job を先に削除し、LaunchAgent を修復してください。

混合バージョンでは CLI の「ready」表示だけを信頼しないでください。restart health とプラグイン読み込み結果が正とします。gateway restart を繰り返しても効果がない場合、メンテナンス窓で openclaw gateway install --force を実行して LaunchAgent を再構築し、再度 openclaw doctor を実行してください。

OpenClaw アップグレードを自宅 Mac やスリープ頻度の高いノートPCに紐づけると、システム更新とディスク断片化がアップグレード窓にリスクを重ねます。オーバーセル VPS や非 macOSでは Apple チャネルと launchd ネイティブパスを辿れません。再現可能な update、秒単位ディスク拡張、専有ベアメタル計算が必要なチームには、JEXCLOUD マルチリージョンクラウドMac上で本記事の六段階手順に従い、ENOSPC 前に 1TB/2TB 拡張または M4 Pro 並列化でバッファを確保するのが最も安心な選択肢です。約120秒でプロビジョニング、プロジェクト単位の弾力契約。プランは JEXCLOUD 料金ページをご覧ください。