openclaw update · バックアップ固定 · doctor · ロールバック
すでに OpenClaw を本番で動かしている開発者や小規模チームがバージョン追従でつまずくのは「openclaw update が打てない」ことではなく、アップグレード後に Gateway が立ち上がらない、ポートが古いプロセスに占有されたまま、PATH が旧バイナリを指す、設定移行でツール設定が黙って書き換わるといった事後の症状です。本稿ではまず五つのアップグレードリスクを分解し、公式 update・npm グローバル・ソースビルドの対照表、六手順で再現可能な Runbook（バックアップとチャネル方針を含む）、アップグレード後の doctor とヘルスチェックの順序、ポート競合と二重インストールの証跡表を示します。マルチプラットフォームインストールとデーモン、インストールと doctor 切り分け、ランタイム障害切り分けと相互リンクし、アップグレード・観測・ロールバックを一枚に揃えます。
公式ドキュメントは openclaw update とその後の openclaw doctor を推奨しますが、本番ではパッケージマネージャの切り替えにデーモンが追従しない、旧 Gateway がリスナーを解放しない、同一ホストに複数 CLI が共存するといった層が重なります。本番強化チェックリストを読んでいれば、チャネルホワイトリストとリスン面の縮小はアップグレード順序と強く相関することが分かります。Gateway を止めずにパッケージだけ差し替えると、18789 が古い PID に占有されたままになるのが典型症状です。
アップグレードを単なる CLI イベントとして扱うと、バージョン番号とリスン面・身元情報を結びつける文脈が失われます。運用で先に書き留めるべきは、プロセスドリフト、黙った設定移行、チャネル供給タイミングの衝突、ロールバック証跡の欠如、ヘルステレメトリの欠落です。以下の各項目は変更チケットに添付できるアーティファクトに対応し、「update を打った」から「失敗をバージョン文字列とバックアップパスで説明できる」まで引き上げます。社内ではレビュー責任者とロールバック承認者を明記し、同じコマンドでもステージングと本番で plist や unit の参照パスが違う場合は、その差分をチケットに残すと後追いが容易になります。
プロセスとパッケージ版の乖離：グローバル npm は新ビルドを指しているのに、launchd や systemd が旧ワーキングディレクトリでビルドしたバイナリを起動しており、openclaw --version と gateway status の報告が一致しません。
設定移行と黙った書き換え：メジャーでは openclaw.json の意味が変わることがあり、doctor が移行を試みますが、マージ方針がチームの GitOps レビューとズレると「ディスク上のファイルだけが変わり PR にない」状態になります。
自動更新チャネルと変更窓の衝突：安定チャネルの遅延とジッターは全員同時に落ちるのを防ぐためのものですが、ビジネスリリース窓と揃っていないと金曜夜に計画外再起動が発生します。チャネルプローブと組み合わせる場合は、コールバックを信じる前に Gateway が本当に再起動したかを確認します。
ロールバック証跡の不足：バックアップや版固定の記録がないと「最新をもう一度入れる」以外に既知良好状態へ戻せません。常駐クラウド構成と併用するとノードに cron や外部 webhook も載り、ロールバック順序を誤ると停止時間が増幅します。
観測フィールドの欠落：「アップグレード成功」のスクリーンショットだけを残し gateway status --deep やバインドアドレスを保存しないと、事後に露出面がセキュリティベースラインに合致していたと証明できません。
上記五つをリリース前チェックリストに落とし込んでから次の節でインストール経路を比較すれば、「更新できる」が「監査できロールバックできる更新」に昇格します。個人ノート PC のスリープや OS メンテ窓はデーモン状態を一時的に乱し、SLA を契約に書けるクラウド Mac ノードでなければアップグレード窓と可用性を受け入れ基準に落としにくい、という整理も現場では繰り返し出ます。
三経路に絶対の優劣はなく、チーム規模、監査のためのコミット固定の要否、Gateway 自動再起動を許容するかとの適合が問われます。公式 update サブコマンドは多くのチーム向け、グローバルパッケージマネージャは CI イメージ向け、ソースビルドはパッチを送るチームや dev チャネルを固定する必要があるグループ向けです。
| 次元 | openclaw update | npm グローバル / brew | git ソースビルド |
|---|---|---|---|
| 習熟コスト | 低；一コマンドで取得・doctor・再起動ヒントを連鎖 | 中；doctor と gateway 再起動を自組み立て | 高；pnpm ビルドとパス管理が必要 |
| 版の追跡性 | 中；リリースメタデータ依存 | 強；package の版を固定 | 強；commit SHA を固定可能 |
| ロールバック経路 | 中；版固定とバックアップと組み合わせ | 強；npm i -g openclaw@x | 強；git checkout 後に再ビルド |
| 自動化適性 | 強；runbook に向く | 強；イメージ層に向く | 弱；ビルド時間とキャッシュ設計が重い |
| デーモンとの関係 | stop してから start の順を確認 | 同左 | 二重パスが最も出やすい |
持続可能アップグレードの鍵は「失敗を版番号とバックアップパスで説明できるか」であり、「たまに gateway が立ち上がるか」ではありません。
すでに マルチプラットフォーム install-daemon を実践しているなら、本節の選型結論を運用手帳に書き込み、「ドキュメントは brew、実機は npm、cron は第三のパス」という三体問題を避けます。
以下六手順は on-call 手帳で一行ずつチェックできるように書いてあります。インストール方式が何であれ順序さえ揃えば、新しいメンバーでも一時間以内に演習できます。ランタイム三分割と併用する場合は、アップグレード後に gateway status の断片を残し、チャネル層とモデル層の問題を切り分けやすくしてください。事前にステージングで同じ順序を一度通すと、本番窓での判断が速くなり、doctor の警告が出た場合にどこで止めるかも合意しやすくなります。
変更窓を固定：チケットに目標版と許容中断分を明記する。大規模なモデル鍵ローテーションと同じ夜に実行しない。
設定と身元パスをバックアップ：公式バックアップか、少なくとも ~/.openclaw 内の設定・身元関連ディレクトリをアーカイブし、チェックサムを検証する。
Gateway をグレースフル停止：先に openclaw gateway stop、リスナ解放を確認してから更新コマンド。半端なアップグレード状態でポートを占有しない。
更新を実行しチャネルを記録：openclaw update を使う場合は、出力の版とチャネル情報をチケットの索引フィールドに保存する。
doctor と health を順に実行：移行ヒントと警告を収集。想定外のフィールド変更があれば自動再起動を止め手動 diff。
チャネルをプローブし最小メッセージ：許可された環境でプローブを送るか channels status を呼び、コールバック経路がまだ届くか確認する。
openclaw gateway stop openclaw update openclaw doctor openclaw gateway start openclaw health openclaw gateway status --deep
ヒント：update 内蔵の再起動と手動スクリプトが競合すると一時的に二重リスンが出ます。アップグレード手順は「止める・入れる・起こす」を直列化し並列にしないでください。
コミュニティでよくあるのは「アップグレード後もポートが埋まっている」「CLI は新しいがプロセスは旧ビルド」です。切り分けではまず単一の真実に寄せます：バインドアドレス、プロセスのバイナリパス、パッケージの設置場所。設定を疑う前にこれらを揃えます。インストールと doctor チェックリストと併読する際は、下表をチケットの付録に貼ってください。
ポート占有：証跡は lsof -i :18789 等で旧 PID が見えること。先に gateway stop、失敗時のみ手順に従い安全に終了し残りを再確認。
二重インストール経路：which openclaw と npm root -g のプレフィックスが食い違う。PATH を正規化し余分なグローバルパッケージを外すかエイリアスを固定。
デーモンユニット未更新：plist や unit が旧 WorkingDirectory を参照。daemon を再インストールするか文書の force 手順の後に kickstart。
設定検証失敗：doctor がフィールド移行の衝突を報告。バックアップから復元し段階アップグレードするか JSON を手でマージして doctor を再実行。
ヘルス偽陽性：health は通るがチャネルにコールバックなし。ランタイム切り分け記事の三分割に従い、早締めしない。
ロールバック後も異常：環境変数やシェル起動スクリプトが旧 NODE_PATH を注入。ログインセッションと CI イメージ層のキャッシュを掃除。
注意：共有ノードで「試しに」一時 export したパスが profile に残ると個人の試行が全件事故になります。共有プールでは Unix ユーザを分けるかコンテナ境界を使ってください。
以下三つは小規模チームが OpenClaw を導入する際によく観測するレンジであり、プロジェクト前のすり合わせ用でありベンダ保証ではありません。実際のチケット計測に置き換えてください。
| チーム規模 | 変更頻度 | リスク許容 | より安定しやすい第一選択 |
|---|---|---|---|
| 個人 | アドホック | 高 | 公式 update と手動停起、zip バックアップ保持 |
| 小チーム | 週次 | 中 | npm 版固定、変更チケット、doctor 出力を保管 |
| プラットフォーム | 日次 | 低 | イメージビルド、カナリアノード、自動プローブ |
| 外部協業 | 不規則 | 中 | 読み取り専用 Runbook と独立ノード、HOME 共有禁止 |
個人端末ではスリープ、ディスク空き、OS 更新窓がデーモンを繰り返し妨げます。手順が正しくてもローカルでは「受け入れ可能なアップグレード SLA」を満たしにくく、契約に書けるクラウド Mac Mini ノードで初めてプロセス常駐・ネットワーク入口・メンテ窓を条項に落とせます。
よくある誤解：「health が通った」＝「チャネルとモデルも健全」。health はゲートウェイ部分集合に過ぎず、完全な受け入れはランタイム切り分けの順を踏む必要があります。
ロールバック可能な OpenClaw アップグレードと観測可能な Gateway ライフサイクルが欲しく、ノードを常時オンにしノート PC のスリープで Agent が切れないようにしたい場合、とくに本番自動化と iOS 関連ビルド環境が絡むなら、VpsMesh の Mac Mini クラウドレンタルがしばしば最適解です。周期課金、リージョン選択、専用ノードの監査可能性があり、アップグレード議論を実測の可用性に載せられます。
強く推奨します。少なくとも設定と身元に関わるパスをバックアップしてから update を実行してください。インストールと doctor 切り分けの長文と併読。ノード注文は注文ページ。
ロールバック演習、当番、プローブスクリプト保守の工数を一回のリリースコストに含め、価格ページと三年 TCO の長文と突き合わせて判断します。
まず ヘルプセンター。アップグレード後にチャネルだけ異常なら ランタイム障害切り分けの順に従い、続けて本文でポートと PATH を再確認します。