2026-04-16 ヘッドレスレンタルクラウド Mac 上の OpenClaw ゲートウェイ アップグレードとロールバック
レンタルした Apple Silicon Mac が SSH しか話さないとき、OpenClaw のアップグレードは純粋なオペレーションです。Finder のクリック導線も「アプリを再起動」もありません。本 2026-04-16 プレイブックは イングレス凍結、npm の前に停止 の順序、~/.openclaw のチェックサム付きバックアップ、盲目的 @latest ではないバージョン固定、openclaw doctor 検証、グローバルインストール後に時折必要なゲートウェイ二重启動、そしてビルドが横滑りしたとき 3 分以内 の tarball ロールバック を扱います。環境変数とシークレット（2026-04-15）、ヘルスプローブ、nginx イングレス へリンクし、HK / JP / KR / SG / US でスタックを一貫させます。
ヘッドレスゲートウェイ特有のリスク
- ホットなグローバル npm — Node がハンドルを掴んだまま置換すると部分インストールや「幽霊」バージョンが出ます。
- launchd の重なり — 先に unload しないと、ユーザ LaunchAgent がアップグレード途中にゲートウェイを再起動します。
- 設定ドリフト — 新マイナーでキー名が変わることがあります。秘密を除いた
openclaw.jsonを Git で追跡するエクスポートを残してください。 - Webhook のスローダウン — 準備チェックなしで nginx を開くと相手が猛烈にリトライします。健康チェック記事のプローブを使ってください。
まず公衆トラフィックを凍結
nginx リバースプロキシ を使うホストでは、上流をメンテナンスに切り替えるか作業中 503 と Retry-After: 90 を返します。内部カナリアは 127.0.0.1:18789 に届くべきで、世界に戻す前に検証できます。
バックアップ表：npm に触る前に tar するもの
| パス / アーティファクト | 含める？ | メモ |
|---|---|---|
~/.openclaw（または $OPENCLAW_STATE_DIR） |
常に | 先にゲートウェイ停止；shasum -a 256 で gzip 整合性を確認 |
| グローバル npm prefix ツリー | 任意 | npm prefix -g と npm ls -g --depth=0 のテキストを diff 用に保存 |
| launchd plist | 常に | ~/Library/LaunchAgents から同じ tarball フォルダへコピー |
TS=$(date +%Y%m%d-%H%M)
tar -czf "/Volumes/backups/openclaw-state-$TS.tgz" -C "$HOME" .openclaw
shasum -a 256 "/Volumes/backups/openclaw-state-$TS.tgz" > "/Volumes/backups/openclaw-state-$TS.tgz.sha256"
インストールとピン留め：DB マイグレーション並みに semver を扱う
本番ゲートウェイはインフラリポで明示的な semver（例 1.24.3）を追跡します。CI は少し速く浮かせてもよいですが、シンガポール で相手先に向く Mac が深夜 2 時に破壊的プラグイン API で驚かせるべきではありません。サービス停止後：
npm install -g openclaw@1.24.3
openclaw gateway status を実行し、報告ビルドと openclaw --version を比較してください。不一致は遷移中です。
検証・再起動・二回バウンスが要るとき
openclaw doctor を実行し stdout をログシッパーへ。plist に従い launchctl bootstrap/kickstart で起動。ログに古いモジュールパスや奇妙な require スタックがあれば、もう一度きれいに停/起してください—オンロールがフラッピングと誤認しないよう文書化。nginx メンテを上げる前に ヘルスプローブ の合成チェックを再実行します。
ロールバック：状態を戻し、祈らない
- ゲートウェイと nginx 上流を再び停止。
- 必要なら壊れたグローバルインストールを削除：
npm rm -g openclawの後に旧 semver を再インストール。 - tarball を展開：
tar -xzf openclaw-state-....tgz -C "$HOME"（所有者確認）。 - plist が変われば復元；必要に応じ
launchctl bootout/bootstrap。 - doctor と内部 curl を検証；その後にだけ公衆イングレスで 200 を返す。
関連 Runbook とシークレット規律
アップグレードは秘密ローテーションと同じファイルに触れます。launchd 環境ガイド と調整し、.env と plist キーを一致させてください。ブルーグリーンで第二ゲートウェイユーザーを足すなら、同記事のとおり OPENCLAW_STATE_DIR を分割。連続失敗後の容量は、疲弊した 1 台に延々パッチを当てるより 料金 からウィットネスノードを追加。
FAQ：クラウド Mac のゲートウェイアップグレード
| 質問 | 回答 |
|---|---|
| npm の代わりに pnpm？ | サポート—同じ停止/バックアップ/ピン/起動規律を踏襲し、runbook にストアパスを記録。 |
| 毎週自動アップグレード？ | カナリア + 自動 doctor + プローブゲートがある場合のみ。本番を人なしページャで自動アップグレードしない。 |
| インシデントはどこへ？ | 既存ブリッジを使い、構造化ログ フィールドと相関。 |
まとめ： OpenClaw アップグレードを DB フェイルオーバーと同列に—トラフィック凍結、状態バックアップ、バージョン固定、二回検証、全リージョンでロールバックをリハーサルして筋肉記憶に。
