OpenClaw の Mac mini M4 ゲートウェイアップグレードは、チームが ドレイン を飛ばし、稼働中の webhook で LaunchAgent を跳ね返すか、openclaw config validate を任意の芝居にすると静かに失敗する。この 2026-04-29 矩陣は 入口ドレイン → 状態スナップショット → 検証 → 再起動 → doctor → スモーク を順序づけ、症状をロールバックレバーに写す 2 表を提供する—四月のパッチ列車が同じ橋のインシデントを開け直さないように。
CLI バージョンピンと非対話アップグレード／ロールバック、LaunchAgent 再起動と外部シェルランブック、ポストインストールスモークとヘルス証拠、ログ・アップグレード・ロールバック運用ランブック とセットで読む。
「brew upgrade && launchd を蹴る」が戦略にならない理由
ゲートウェイは長寿命 TLS、ツールサンドボックス、macOS 権限状態を同居させる。ドレインなしのバイナリ差し替えは、旧コードが半分しか署名済み webhook を抱えたまま新コードが別 schema 既定を期待する状態を残す。Apple Silicon では古いブラウザサンドボックス由来の統合メモリ圧が新プロセスを「遅い」ように見せ、真因は順序ミスであることが多い。
- イングレス競合：新 plist の後に旧コードが webhook を受け取り、冪等キャッシュを壊す。
- アイデンティティドリフト：
openclaw --versionは新ビットだがopenclaw gateway statusは部分再起動で古いリスナーを表示。 - 無音の設定ずれ：検証スキップ；起動書き込みが永続だと思ったカスタム許可リストを削る。
オペレータ規則：変更チケットにドレイン開始、validate 合格、スモーク再生のタイムスタンプがなければ、アップグレードはクローズできない—チャットボットが緑でもだ。
マトリクス A—フェーズ、合格シグナル、証跡
| フェーズ | 合格シグナル | 証跡 |
|---|---|---|
| ドレイン | キュー深さゼロかつ N 分間新規インバウンドなし | タイムスタンプ付きログ抜粋またはプロキシ指標キャプチャ |
| 検証 | openclaw config validate がゼロ終了 |
マスク済み stdout をオブジェクトストアへ |
| スモーク | 署名再生 + doctor クリーン + gateway status 期待どおり | 再生 ID をチケットにリンク |
マトリクス B—症状、順序バグ、ロールバック
| 症状 | 順序バグ | ロールバック |
|---|---|---|
| 再起動直後に 401 嵐 | 検証前再起動が設定パスを書き換えた | plist と状態スナップショットを復元；リスナー前に再検証。 |
| ツール二重実行 | 冪等キャッシュが温まる前にトラフィック復帰 | 再ドレイン；アップグレード前エクスポートの重複除去キーを再生。 |
| ヘッドレス Mac で GUI プロンプト | アップグレード後の TCC 回帰チェックをスキップ | 文書化された VNC ブレークグラスに従い、さらなるアップグレードを凍結。 |
変更窓の数値ガードレール
- ドレイン忍耐：キュー空後、新規インバウンドがゼロであることをさらに少なくとも 5 分 確認してから再起動。
- 検証バジェット：validate が 2 回 を超えて失敗したらバイナリを戻す—三回目の密かな編集はしない。
- スモーク幅：本番健全宣言の前に少なくとも 三 種類の webhook 形状を再生。
8 HowTo（JSON-LD と同型）
- スコープ凍結：semver、オーナー、ロールバックオーナーをチケットに。
- イングレス排水：プロキシフラグまたはセカンダリ昇格—切替を記録。
- 状態スナップショット：バイナリ移動前にディレクトリと plist 環境を。
- バイナリ適用：承認済みパッケージ経路のみ；チェックサム証明なしに手コピーと CI 成果物を混ぜない。
openclaw config validateを実行し、リスナー再起動前に stdout を添付。- LaunchAgent 再起動；
openclaw gateway statusで期待バインドを証明。 openclaw doctorを実行し、その順でステージング webhook スモーク。- トラフィックを段階的に戻す：エラー率アラームと十五分ウォッチ窓を添える。
よくある質問
ゲートウェイごとにスタンバイ Mac が必要か？
本番チャット入口にはそう—ホットスタンバイか、プライマリ排水中に署名イベントをバッファできるエッジキュー。
SSH と VNC の役割は？
検証と再起動には SSH 優先の自動化；アップグレード後にヘッドレス権限回復が詰まるときだけ VNC。
本番秘密を共有せず容量を足すには？
香港・日本・韓国・シンガポール・米国 で別の専用ホストを 料金 から追加し、ステージングのアップグレードを一世代先に保つ。
ネイティブ macOS で再現可能な OpenClaw アップグレードは振付け問題：ドレイン がイングレス競合を取り除き、openclaw config validate がリスナー覚醒前に schema ドリフトを捕らえ、構造化 スモーク が冪等度がジャンプを生き延びたことを証明する。香港・日本・韓国・シンガポール・米国 で Mac mini M4 を借りる とステージングと本番を物理分離し、秘密ではなくランブックだけを共有できる。矩陣が順序バグを繰り返すなら semver を追う前に証拠要件を締める；ユーザーが欲しいのは安定 webhook であって長いリリースノートではない。