2026 年 OpenClaw v2026.5.20 を Mac VPS でアップグレード検収：managed Gateway Node、プロトコル乖離と Policy/Doctor 一枚 Runbook（意思決定表・FAQ 付き）
OpenClaw は 2026-05-21 に v2026.5.20 を公開し、多 Node 環境で openclaw update が Gateway を誤ったバイナリへ静かに切り替える問題や、CLI/Gateway のプロトコル版数乖離で再起動ヘルスチェックが効かなくなる本番級不具合を修正しました。Mac VPS 上で launchd により Gateway を 7×24 運用しているのに「上げたら起動しない・チャネルだけ緑・Cron が成功を失敗と報告する」不安があるなら、本稿が実行可能な結論を示します。四つの番号付き痛み、タイミング意思決定表、事前スナップショット、七段 Runbook、5.20 専用検収表、エラー対照、引用可能な三指標、FAQ、およびゲートウェイ排障・マルチチャネル・五月クリーン基線への内リンクを含みます。
目次
1. 痛みの分解：多 Node、プロトコル乖離、設定漂移
Mac クラウド上の OpenClaw 障害は「モデル課金切れ」だけではありません。Gateway プロセスは生き、18789 も LISTEN しているのに、CLI と Gateway が別 Node で動いている、またはプロトコル版数が 1 段ずれていると、アップグレード直後の gateway restart でヘルスチェックがタイムアウトし、チャネルがランダムに落ち、Cron が成功タスクを失敗と印字します。5.20 はこのクラスを「再現可能な検証項目」に落とし込むパッチです。
- 多 Node の静かな漂移：Homebrew Node、nvm、インストール脚本付属 Node が同居すると、旧版
openclaw updateはパッケージ根が同じでも follow-up コマンドを別 Node へ切り替え、managed Gateway サービスだけ旧パスを指し続けることがありました。 - CLI/Gateway プロトコル乖離：CLI が 5.20、Gateway が 5.18 のままだと再起動ヘルスチェックが誤判定し、チームはプラグイン再インストールなど誤った層を掘ります。
- doctor 新警告の放置：5.20 から
openclaw.jsonの平文 API Key、サンドボックスで隠れた MCP ツール、無効なthinkingFormatを警告します。diff を見ず--fixすると必要な provider フィールドまで消えるリスクがあります。 - Exec 承認パスの変更：Skill は
cat SKILL.md互換パスを許さず read ツール必須です。シェルで cat を組んだ自動化は「ツール拒否」の疑似障害になります。
オンコールではまず「プロセスは緑か」「18789 は開いているか」を確認し、次に Node パスと running version の一致へ進んでください。
2. 意思決定表：いつ 5.20 へ上げるか
| 方針 | 適用場面 | リスク | 推奨 |
|---|---|---|---|
| 即時アップグレード | update 後 Gateway 起動不能、多 Node 同居、Cron 終態の正確性が重要 | 10〜20 分のメンテ窓が必要 | 本 Runbook を低トラフィック帯で実行 |
| 次パッチ待ち | デスクトップ試験のみ、7×24 チャネルなし | 旧版 update/プロトコル問題を引き続き被る | 本番 Mac VPS には非推奨 |
| 新ノードクリーン構築 | 設定監査不能、プラグイン乱立 | ペアリング再スキャンと移行コスト | サイト密集リリース後クリーン基線に合わせて切替 |
Staging と本番で Node 管理方針が異なるチームは、staging で七段を通したうえで変更票に managed Node パスを明記してください。
3. アップグレード前スナップショット
バイナリを触る前に、次の出力を変更票テキストとして保存してください。ロールバック時の diff がここから始まります。
openclaw --version openclaw gateway status --json | tee /tmp/gw-before.json lsof -nP -iTCP:18789 -sTCP:LISTEN which node; node -v type -a node 2>/dev/null || true cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d) launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -80
ProgramArguments 内の Node 絶対パスと、gateway status --json の running Gateway version（5.20 以降より信頼性向上）を重点記録します。ゲートウェイ排障 Runbookの基線と食い違う場合は、先に基線修復してから 5.20 へ進んでください。
4. 七段 Runbook
ステップ 1：目標版をピンして update
openclaw update --tag v2026.5.20 # npm グローバル環境の例： # npm i -g openclaw@2026.5.20
コマンド終了時の再起動ヘルスチェック通過を待ちます。失敗したらプラグイン全再インストールに逃げず、ステップ 2 で Node を確認してください。
ステップ 2：managed Gateway Node が漂移していないか
openclaw --version which node node -v openclaw gateway status --json | jq '.server,.version,.runningVersion'
5.20 の修正要点は、openclaw update 以降の follow-up が managed Gateway サービスと同じ Node を使うことです。「CLI は Homebrew Node、launchd は /usr/local の別セット」状態を解消してください。両パスの node -v メジャー版は一致すべきです。
ステップ 3：Gateway 再起動と 18789 確認
openclaw gateway restart sleep 3 lsof -nP -iTCP:18789 -sTCP:LISTEN openclaw gateway status --deep
--deep プローブ失敗時は、ゲートウェイ Runbookに沿って gateway.auth、loopback、Token を確認し、モデル Provider は後回しにしてください。
ステップ 4：openclaw doctor（Policy プラグイン含む）
openclaw doctor openclaw doctor --fix # 削除・変更フィールドを diff 確認後のみ
5.20 同梱の Policy プラグインはチャネルコンプライアンスと workspace 修復ヒントを出します。「平文 API Key」警告は doctor を止めるのではなく、環境変数または SecretRef へ移行してください。
ステップ 5：主要チャネルスモーク
本番利用中の Telegram / Feishu / Slack 等で単発送受信を行います。並行チャネルではマルチチャネル検収 Runbookの単チャネル段階に従い、一度に変数を増やさないでください。
ステップ 6：Cron 試走
openclaw cron list # 低リスク計画タスクを 1 本起動し、終態 success かつ tool warning で上書きされないことを確認
5.20 は、成功 Cron が末尾 tool 警告で失敗扱いになる問題や、main-session と cron wake lane の相互ブロックを修正しています。アップグレード後はログと UI 終態が一致するはずです。
5. v2026.5.20 専用検収表
| 検収項目 | 合格基準 | 失敗時の第一確認 |
|---|---|---|
| プロトコル乖離ヘルスチェック | update 後 restart が 1 回成功 | CLI と Gateway が共に 5.20 か |
| managed Node 一致 | launchd と CLI の node パス/intent 一致 | launchctl print vs which node |
| gateway status 版数字段 | JSON に running Gateway version | 旧 plist がアンインストール済み接頭辞を指す |
| Policy / 平文キー | doctor にブロック級 secret 警告なし | キー移行後 gateway restart |
| Exec / Skill | read ツール経由で Skill 実行可 | shell cat SKILL.md 自動化を除去 |
6. エラー対照とロールバック
| 現象 | 典型根因 | 対処 |
|---|---|---|
| update 後 Gateway 起動不能 | Node パス漂移 | managed Node を揃える；必要なら gateway install --force（ゲートウェイ Runbook 参照） |
| doctor --fix 後モデル全滅 | provider フィールド誤削除 | openclaw.json.bak 復元、thinkingFormat を手動整理 |
| チャネル online だが無応答 | ペアリング/ウィンドウ（アップグレード非起因） | チャネル排障文を参照；先に Gateway 版数一致を証明 |
| Cron が依然失敗 | タスク自身の exec 拒否 | cron show + JSONL；Skill read パス確認 |
ロールバック：json バックアップを戻し、前 tag をピンして gateway restart。設定監査不能なら五月クリーン基線どおり新ノード再構築が早い場合もあります。
7. 三つの引用可能な判定
- Node 一致性：同一メンテ窓内で、managed launchd の Node と
openclaw updateが報告する Node のメジャー版が一致すること。不一致なら 5.20 修正が実効していません。 - 版数可視性：
gateway status --jsonで running Gateway version = 2026.5.20（同等文字列）が読め、openclaw --versionと揃うこと。 - Cron 終態：成功計画タスクが末尾 tool 警告で最終成果を上書きされないこと。Gateway 緑灯だけでなく、試走 1 本の delivered フラグを根拠にしてください。
8. FAQ
質問：Docker と npm のパス差は？ コンテナ内はイメージ内単一 Node が基準です。宿主机 Mac VPS の npm+launchd ほど Node 固定が重要です。Docker はイメージ tag とボリューム設定バックアップを揃えてください。
質問：5.18/5.19 を飛ばして 5.20 へ？ 可能です。必ずスナップショットを取り、staging で七段通過後に本番へ。
質問：初回 5 ステップとの関係は？ 5 ステップは「ゼロから立ち上げ」、本稿は「既存 7×24 インスタンスを 5.20 へ安全に上げる」です。新規は 5.20 から入り、マルチチャネル検収へ進んでください。
9. まとめ
v2026.5.20 の価値は機能リストより、Mac VPS で頻出する「上げたらゲートウェイが死ぬ」事故を Node とプロトコル契約へ収束させる点にあります。ノート PC や WSL2 は短時間試験向きですが、スリープ・NAT・多 Node 混在で update 漂移の再現が難しくなります。Linux VPS でも Gateway は動きますが、launchd と Apple スタック文書の積み上げ利点は Mac クラウド側に偏ります。OpenClaw を7×24 本番入口にするなら、メンテ窓で七段を完走し、managed Node・doctor・Cron 終態を変更テンプレに書き込む方が、毎回フル再インストールより時間を節約できます。安定ディスク、監査可能 launchd、SSH Runbook を求めるチームには、VPSMAC Apple Silicon Mac クラウドで 18789・設定バックアップ・アップグレード検収を同一運用面に載せる選択が、エッジ端末や過度コンテナ化実験スタックより 5 月密集発版期に制御しやすい——サイト内ゲートウェイ排障・マルチチャネル・クリーン基線ガイドが想定する環境と一致します。