2026 OpenClaw アップグレード護航実践：`openclaw backup create`、受け入れラダーと ACP / `gateway probe` リグレッショントリアージ Runbook

アップグレード護航でよくある六つの誤り（手を入れる前に整理）

1. イメージ tag だけ変えて backup create をしない：ロールバック時に設定を記憶頼みにし、「直前の良好状態」のペアリングとチャネル状態を証明できません。
2. 「dashboard が開く＝probe 合格」とみなす：2026 年の多数の issue では daemon は healthy でも loopback probe がタイムアウトします（特に Windows で provider 拡張が起動を遅らせる）。
3. Node 基線を揃えずに OpenClaw を上げる：公式推奨は Node 24 です。22.x で無理に上げると CLI と Gateway のハンドシェイクが分裂しやすく、Node 24 onboard Runbookを参照してください。
4. 半アップグレードの split-brain：CLI は新バージョン、Gateway プロセスは reload されていない。見かけはtools.profile でツールが動かないと似ますが、根因は新ランタイムが載っていないことです。
5. ACP リグレッションを「モデル不良」と誤認：2026.3.13+ で ACP bridge / device 流が失敗しても、host 上の acpx 直結は正常な場合があります。本稿の ACP トリアージを先に行い、モデル変更は後回しにしてください。
6. スリープするノートで本番アップグレード窓を取る：蓋を閉めると probe 失敗が版の問題と誤判定されます。権威ある Gateway は常時稼働のリモート Mac に置き、SSH 転送常駐 Runbookを参照してください。

2026 年の上流・コミュニティ文書では、「アップグレード」を単なる npm install -g ではなく可逆的な状態遷移と定義する流れが強まっています。openclaw backup create は現在の ~/.openclaw（または Docker ボリュームに対応するディレクトリ）を命名可能なアーカイブにし、probe が連続失敗したり ACP 登録が消えたりしたときに、数分でアップグレード前の組み合わせへ戻す選択肢を残します。これはリリースチャネル固定マトリクスの「既知良好 tag/digest」と同じ FinOps 思考の両面です。一方はバイナリを固定し、もう一方は実行時設定とペアリングを固定します。

実務では、初めて本番アップグレードを行うチームの多くが、変更チケットに「OpenClaw バージョン更新」だけを書き、バックアップパス・SHA・リストア演習日を書きません。夜間ピークにイメージ pull と全量 probe を同時に行うと、帯域とディスク I/O が飽和し、「probe タイムアウト」を「ACP 障害」と誤認し、チャットで同じプロンプトを繰り返してリリース窓を失います。護航 Runbook の価値は、この隠れコストを監査可能・再現可能・責任者を割り当て可能な手順列に落とすことにあります。

Gateway を 7×24 で提供する必要がある場合は、変更窓の前に権威ある Gateway プロセスが一つだけ権威ポートを listen していることを確認し、リモート Mac に十分なディスク水位と帯域余裕を確保してください。ノートは SSH ローカル転送で Control UI に触れるだけにすると、「スリープによる Gateway 疑似停止」と「probe 経路と業務経路の不一致」という二種類の偽陽性を同時に避けやすくなります。

SRE の観点では、本稿の護航とバージョン移行総チェックリストの違いは次のとおりです。総チェックリストは「どのディレクトリを動かし、複数 Gateway をどう切り替えるか」、本稿は「すでに上げた直後に probe/ACP 証拠で残すか戻すか」です。変更チケットに両方をリンクし、当番が長文から順序を推測しないようにしてください。GHCR イメージ利用時は digest SHA とバックアップパスをチケットに併記し、「バイナリ + 状態ツリー」の二重アンカーにします。

Windows/macOS ノートでは、エンドポイント保護が ~/.openclaw をスキャンし、backup create 中の I/O を遅らせてバックアップ半端や probe 起動競合を起こすことがあります。ノートでバックアップする場合は変更窓にリアルタイムスキャンを止めるか除外設定し、チケットに記録してください。より良い実務は、バックアップと受け入れをリモート Mac サーバーで行い、ノートは転送と承認のみに留めることです。

実務では、アップグレードごとに「証拠パック」フォルダ（バージョン出力、probe JSON、doctor 概要、backup パス）を変更チケット番号で 90 日保管することを推奨します。probe 偽陽性率が急上昇したとき、過去パックと比較すれば起動チェーンの遅延か監視閾値の厳しさかを切り分けられ、「先週も赤だったはず」という記憶頼みの議論を減らせます。証拠パックは監査にも有効で、アップグレード前に backup があり、その後ラダーを実行したことを示せます。SOC2 や社内変更管理を求める顧客向けに特に有用です。

本稿はです・ます調で、on-call 当番がそのままチケットに貼れる手順を優先して書いています。英語の CLI 出力やコマンド名は原文のまま記載し、日本語で意図がぶれないよう補足しています。アップグレード護航は「最新版への突撃」ではなく、backup と probe 証拠によって可逆性を確保する作業です。この前提をチームで共有できれば、夜間の判断が速くなり、誤ロールバックも減らせます。

アップグレード前：openclaw backup create とディレクトリ境界チェックリスト

変更窓の開始前に、バックアップ → バージョン指紋の記録 → 権威 Gateway が一つだけを固定で実行します。コマンドはインストールした CLI に合わせてください（2026 文書の典型例は下記）。サブコマンド名はチャネルで多少異なる場合がありますが、openclaw backup --help を正とし、原則は変わりません：アップグレード前にリストア可能なローカルアーカイブが必須です。

変更チケットの添付に、バックアップパスとサイズ、openclaw --version、Node バージョン、使用中のイメージ digest（Docker 時）、gateway status 概要を載せることを推奨します。probe 失敗の深夜に次の当番が証拠を取り直す手間を減らせます。コンプライアンスチーム向けには、バックアップに Token が含まれるか、リストア後に資格情報をローテーションするかも記載し、「リストア成功だが監査不合格」という第二の事故を避けてください。

バックアップは「任意の保険」ではなく、護航の最初のハードゲートです。証拠のない変更チケットは、事後検討で「直前の良好状態のペアリングとチャネル」に答えられません。Docker Compose 利用時は bind mount がホストの固定パスを指し、iCloud やクラウド同期外であることを確認してください。リモート Mac 常駐では OPENCLAW_STATE_DIR と担当者をチケットに書き、タイムゾーンをまたぐ当番に引き継げるようにします。

Token やペアリングファイルは状態ツリーに含まれることが多いです。アーカイブは機密扱いで保管し、リストア前にローテーション要否を評価してください。本番 Gateway を専用リモート Mac に載せる計画がある場合は、レンタル料金とヘルプセンターの接続手順を先に確認し、ノートでバックアップした後にディスクや帯域不足で状態ツリー全体を載せられない事態を避けてください。

GHCR イメージと Control UI を使うチームは、backup 前後で volume の読み取り専用点検を行い、skills・チャネル資格情報・カスタム設定が想定パスにあることを確認してください。Docker と npm を混在（compose Gateway + ローカル CLI）する場合、どちらの状態ツリーに backup が対応するかを明記し、誤ったホストへリストアしないでください。リモート Mac 常駐では、backup を状態ディレクトリと同じディスクに置き、地域間コピー前に checksum を検証し、「backup はあるがリストア時に破損」という第二事故を防いでください。

openclaw --version
node -v   # 目標：v24.x。合わなければ Node 基線を先に揃えてから OpenClaw を上げる

openclaw backup create
ls -la ~/.openclaw/backup 2>/dev/null || ls -la "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/backup"

openclaw gateway status
openclaw config get gateway.auth.token 2>/dev/null | head -c 8; echo "…(redacted)"

# Before upgrade: one backup, one authoritative gateway, Node 24 baseline
# After upgrade: single reload then run acceptance ladder steps 1 through 6
# On failure: backup restore or digest rollback only first — never stack config patches on bad release

アップグレード後の受け入れラダー：status から「本番投入可」判定まで

アップグレード完了後、Control UI やチャットの一言だけで変更を閉じないでください。固定ラダー（各ステップで失敗したら停止し、stderr とバージョンを記録）を推奨します。

1. openclaw status — CLI と設定が読める
2. openclaw gateway status — プロセス/ポート/バインド概要
3. openclaw gateway probe（または --json）— loopback ハンドシェイクと遅延
4. openclaw doctor — 設定と依存の警告
5. 最小業務プローブ：読み取り専用ツールまたは channels status --probe
6. ACP 有効時：bridge 登録とセッション作成（下記トリアージ）

「本番投入可」は、ステップ 1–4 が連続成功し、ステップ 5 が実際に使うチャネル/ツール面で成功した状態と定義するのがよいです。「巻き戻し必須」は、reload/再起動後も同じステップが二連続で失敗し、本番 Agent に影響がある場合です。まずバックアップ復元、またはdigest ロールバックでチケット記録の tag/digest に戻し、不良版の上に設定パッチを重ねないでください。

probe と dashboard の分裂は 2026 年の典型的な「偽成功」です。daemon 概要は healthy でも loopback probe がタイムアウトします。Windows では provider 拡張の起動遅延、Docker では同一 compose プロジェクトの単回 reload 漏れが多いです。チケットテンプレートに「アップグレード後に一度 reload」を書き、launchd と手動の二重 18789 を避けてください。

ACP を使う場合は bridge 登録と openclaw devices list をステップ 6 に含めます。2026.3.x の既知リグレッション期間では、CLI device 流と Gateway バージョン不一致が「モデル不良」に見えますが、host の acpx は正常なことがあります。本稿の症状表を先に使い、モデル変更やルーティング変更は後回しにしてください。

受け入れラダーの出力はチケットに貼り付け、OpenClaw/Node バージョン、probe 遅延またはエラーコード、doctor 警告概要を最低限残してください。--json 利用時は JSON を添付し、第二台や事後検討で再現しやすくします。tools.profile トリアージと交差する場合はステップ 5 で「最小ツールプローブ」の成否を明記し、allowlist 問題を probe/ACP 障害と混同しないでください。

アップグレード当晚の最短コマンド要約（フルラダーと症状表の代替にはなりません）：backup create → アップグレード → 単回 reload → status → gateway status → gateway probe → doctor → channels status --probe →（ACP 利用時）bridge／devices 確認 → クローズまたは restore／digest ロールバック。ステップを飛ばすと半アップグレードと probe 偽陽性が混ざり、事後監査が困難になります。

リバースプロキシや Cloudflare Tunnel では、loopback probe と外部 dashboard 経路が一致しないことがあります。probe 失敗でも外部チャネルが正常なら、まずリモートホストの loopbackで probe を実行し、Upgrade ヘッダやアイドルタイムアウトを除外してからリバプロチェックリストを参照してください。外部 URL が開くことと loopback ハンドシェイク成功を同一視しないでください。

openclaw status
openclaw gateway status
openclaw gateway probe
openclaw doctor

# docker compose pull && docker compose up -d
# docker compose restart <gateway-service>

openclaw channels status --probe

# Post-upgrade acceptance (do not skip):
# 1 status  2 gateway status  3 gateway probe  4 doctor  5 channels --probe  6 ACP if enabled

設定を直し続ける vs 版固定ロールバック vs ACP 一時停止：決定マトリクス

on-call は「もう一度 config」と「即ロールバック」の間で揺れがちです。下表で素早く決め、結果をチケットに残し、次の当番が同じ試行錯誤を繰り返さないようにしてください。

よくある夜間シナリオ：アップグレード後、Telegram チャネルは正常でツールプローブも通るが、gateway probe だけタイムアウトし dashboard は開く。このときはマトリクス第一行——業務チャネルは正常で probe のみ赤——に当てはめます。まず監視ノイズとして記録し、provider の起動時間を調べ、すぐ digest ロールバックは避けてください。監視 SLA が probe をハードゲートにしているなら、チケットに「業務無損だが SLA 発火」と書き、patch 巻き戻しか起動遅延プラグインの一時無効を選びます。別シナリオは ACP 全断だが Slack チャットは正常：bridge 登録を優先し、既知リグレッション期間なら minor 巻き戻し、または ACP を一時オフにしてチャネル SLA を守ります。第三シナリオは probe・チャネル・ツールがすべて赤：backup 復元後の段階検証以外では config の重ね貼りをしないでください。YAML を増やすほど、事後にどの変更が原因か追えなくなります。

六ステップ「バックアップ—アップグレード—ラダー受け入れ—記録」Runbook

1. 変更チケット作成：OpenClaw/Node/イメージ tag/digest、リモート Mac Gateway の有無を記載。
2. backup create + チェックリスト：バックアップサイズと同期ディスク除外を確認。
3. アップグレード実行：npm グローバルまたは compose pull/up。チケットあたり一段のみ（beta→stable を飛ばさない）。
4. 単回 reload：権威ポートは Gateway 一プロセスのみ。Docker と launchd の二重起動禁止。
5. ラダー 1–6 実行：失敗時はログを保存し以降のステップを止める。
6. クローズまたは巻き戻し：成功なら「既知良好組み合わせ」表を更新。失敗なら backup restore または digest ロールバックし MTTR を記録。

四半期に一度、非本番トラフィックの専用リモート Mac で軽い卓上演習を推奨します。digest A→B→A を意図的に行い、バックアップ復元とラダースクリプトが文書と一致するか検証してください。ログ tarball と compose SHA は検索可能なチケットに残し、監査とタイムゾーン当番の引き継ぎに使います。

六ステップ Runbook の時間箱（チームで調整可）：チケット作成と backup で 10–15 分、アップグレードと reload で 5–10 分、ラダー受け入れで 10–15 分、失敗時の巻き戻し判断は 5 分以内に開始。digest と backup が事前固定されていれば、MTTR はおおむね 15–35 分に収まることが多いです。60 分を超えても判定できない場合は、変因を同時に変えすぎているか、権威 Gateway が一つに定まっていない可能性が高いです。変更を止め、既知良好組み合わせへ戻し、非ピークで段階アップをやり直してください。長時間の設定試行を勤勉と混同しないでください。護航では迅速な復旧が優先で、根本原因分析は復旧後の別チケットに分けます。

Runbook 第六ステップでは決裁者と期限を明記してください。例：probe が二連続失敗したら 10 分以内に backup restore か digest ロールバックを選択する。ロールバック後は「既知良好組み合わせ」表（OpenClaw + Node + digest + 最後に成功した probe 時刻）を更新し、リリースチャネルマトリクスと整合させ、未検証 latest へ再漂流しないようにします。

変更チケットに書く五つの定量指標

• 護航 MTTR：probe 初回失敗から既知良好組み合わせ復帰までの中央値（分）。小規模チームは ≤15 分を目安（backup と digest が事前固定されている前提）。
• probe 偽陽性率：dashboard/チャネルは正常だが probe が赤の割合。二週連続で >25% なら起動チェーンか監視プローブを直し、毎週の強制ロールバックは避ける。
• バックアップなしアップグレード比率：チケットに backup 証拠がない回数。本番目標は 0。
• ラダースキップ率：1–6 を完了せずクローズした比率。チケット必須項目でほぼ 0 に抑える。
• ロールバック後 24h 再発率：同一 digest 組み合わせが一日以内に再び失敗した回数。2 回超ならチャネル凍結と根因チケットを起票。

チームで本稿を共有する際は、backup と probe ラダーを「推奨」ではなく変更管理規程の必須要件として明文化してください。規程には「ラダー 1–4 未完了のクローズ禁止」「無 backup アップグレードのエスカレーション条件」も書いておくと、当番の判断がさらに揃います。推奨のままでは当番交代のたびに手順が省略され、無 backup アップグレードが再発しやすくなります。規程化後は四半期ごとに軽い演習で手順が古くなっていないか確認し、OpenClaw の CLI 変更があれば Runbook 脚注を更新してください。半年に一度、上流の release note と照合して既知リグレッション期間と ACP 分診列を見直すと、古い版番号のまま on-call を誤導するリスクを下げられます。

六地域のリモート Mac では、アップグレード窓を安定性受け入れとディスク水位確認と並列で計画してください。ピークにイメージ pull と全量 probe を重ねると、「ネットワーク揺れ」を「ACP 障害」と誤認しやすくなります。常時稼働・専用・チケット化可能なノードでアップグレードと受け入れを完了し、ノートは SSH 転送のみに留めるのが安定です。

npm グローバル経路と Docker Compose 経路の護航の違い

ローカル npm グローバルで上げたあと最も多い漏れは「CLI は新しいが launchd の Gateway は古いまま」です。アップグレード後は単一の仕組みで一度だけ reload してください。Docker 経路では「新イメージの pull」と「同じ compose プロジェクトへの up -d」を同一チケットステップに結び、up 直後にラダー 1–4 を実行します。pull だけ、または別 compose ファイルへの up は半アップグレードと同型の split-brain を生みます。

どちらの経路でも backup の意味は同じで、状態ツリーの完全性を証明できることが重要です。Docker では docker compose down -v で volume を消さないマウント設計にし、npm では状態ディレクトリを同期外に置いてください。六地域間で Gateway を移すときは、backup をチケットとともに運び、先に目的地でリストア演習を行い、空設定からの賭けアップグレードは避けてください。

WebSocket 1006 とペアリング衝突との接続

アップグレード後に Control UI で 1006 やペアリング衝突が出たら、モデルやチャネルを直す前にラダー 1–3 を完了し、ペアリングと 1006 Runbookを参照してください。同じ夜にリバプロ・Token・OpenClaw 版を同時に変えると根因が分からなくなります。チケットは「版アップ」と「ネットワーク/リバプロ」を子チケットに分け、probe ラダーが通るまでマージしないでください。backup 復元で 1006 が消えるなら、根因は「恒久的不良版」ではなく「アップグレード後の設定または実行環境の変化」と記録します。

まとめ：アップグレードは「最新を賭ける」ことではなく「可逆移行」である

チャットで「上がった？」と一度聞くだけ、YAML を二三フィールド手で直すだけでは、監査にも第二台での再現にも耐えません。backup create、受け入れラダー、ACP/probe トリアージを Runbook に書くと、「アップグレード事故」は一晩の盲試から、バックアップ・復帰点・指標がある十分程度の事象に圧縮できます。

個人ノートで最新チャネルを追い続ける場合、スリープによる Gateway 疑似停止、probe と業務経路の不一致、電源ポリシーとの衝突という三つの隠れコストを受け入れる必要があります。7×24・Node 24 基線・変更のチケット化が必要な本番 Gateway なら、MACCOME の Mac mini（M4 / M4 Pro）と六地域の柔軟リースに載せる方が、蓋を閉めたノートで probe タイムアウトと戦うより総コストで有利なことが多いです。公開プランは多地域ノードとリースガイドを参照し、トポロジは SSH 常駐 Runbook で配線してください。

MACCOME への移行の要点は「Mac が一台増える」ことではなく、バックアップ・probe ラダー・ACP トリアージを再現可能な変更脚本に落とすことです。専用リモート Mac は常時電源と専用状態ディレクトリを提供し、六地域ノードは遅延とコンプライアンスに合わせた接続点を選べます。柔軟リースはアップグレード窓とコストを揃えます。この脚本をチケットシステムと監視アラートに結びつけると、アップグレードは個人の工夫からチーム能力へ移り、当番は表に従うだけでよくなります。

最後に、本稿を社内の変更チケットテンプレートと揃えてください。backup 証拠、ラダー 1–6 のチェック、決定マトリクスの選択、MTTR の開始・終了時刻の欄がないテンプレートは、護航を口伝に戻します。ノートからリモート Mac への移行を検討中なら、多地域ガイドでプランを見積もり、非ピーク窓で backup→アップ→ラダー→（任意）リストア演習を一度通し、実測分で MTTR 目標を校正してください。

アップグレード護航の引き渡しチェックリスト（チケットに貼付可）

• チケットに移行総チェックリスト、digest ロールバック、本 Runbook へのリンクがある。
• backup create 完了。添付にパス・サイズ・バージョン指紋がある。
• 権威 Gateway が一つだけ。launchd/compose の二重起動がない。
• アップグレードは一段のみ。チャネルを飛ばしていない。
• アップグレード後に単回 reload し、ラダー 1–6 の出力を保存した。
• probe 失敗時は症状表でトリアージし、モデルとリバプロを同時に変えていない。
• 巻き戻し時は backup 復元または digest ロールバックし、既知良好組み合わせ表を更新した。
• MTTR と probe 偽陽性の有無を記録した。

チェックリストをチケットの勾配項目にすると、初めての当番でも護航を閉じられます。「だいたい backup から」という口頭より拡張しやすいです。六地域ノードへ広がるチームでは、安定性受け入れの前提条件としても使え、地域ネットワーク揺れを OpenClaw 版欠陥と誤認して誤ロールバックするのを防げます。

OpenClaw を「個人実験」から「チーム基盤」へ進めるなら、本 Runbook と無人 Gateway チェックリストをオンボーディングに含めてください。前者はアップグレード当晚の手順、後者は平常時の常駐とログ・ディスクの健康です。両方で、護航を一度きりの英雄譚ではなく再現可能なプラットフォーム慣行にできます。MACCOME 六地域リモート Mac の価値は、その慣行のハードウェアとリース基盤——常時電源・専用・チケット化——を提供することにあります。正しいサーバーで正しい CLI ラダーを実行し、蓋を閉めたノートで probe タイムアウトと戦わないでください。

関連記事（本稿と連携）

• バージョン移行総チェックリスト：ディレクトリ移行と複数 Gateway 切替。
• 不良版 digest ロールバック：イメージ digest 固定と compose 手順。
• SSH 転送常駐：ノートとリモート Mac のトポロジ。
• 安定性受け入れ：多地域 probe のばらつきと受け入れ。

当番は本ページをブックマークし、変更システムに本稿と digest ロールバック記事を固定リンクしてください。公開日は 2026-05-21 です。本稿はです・ます調で統一しています。緊急時はチャット履歴を探すより、openclaw backup create → upgrade → reload → gateway probe の順で実行する方が早いです。

護航が成功したかどうかは「チャットで OK と返ったか」ではなく、「ラダー出力が保存され、backup がリストア可能で、決定マトリクスがチェックされたか」で判断してください。この三つを変更クローズの必須条件にし、体感で巻き戻すか不良版に留まるかを決めないでください。

MACCOME リモート Mac で何度もアップグレードしている場合は、「前回 probe を通過した digest と backup ファイル名」をマシン説明やチケットテンプレートの先頭に貼り、次の on-call の検索時間を短くしてください。多国チームでは変更窓表にprobe を実行したタイムゾーンとノード地域を書き、亜洲のメンバーが米州ノードのピークでイメージ pull した結果、地域帯域飽和を OpenClaw 欠陥と誤認しないようにします。最後に、本稿の CLI 例はすべて環境の openclaw --help を正としてください。サブコマンドやフラグが変わったら Runbook 脚注に対応バージョンを記録し、半年後も同じ護航手順を再現できるようにしてください。専用ノードとリースを検討する場合は、多地域ガイドとレンタル料金をあわせて参照し、インフラ判断とアップグレード護航の証拠チェーンを同一チケットで閉じてください。