OpenClaw をアップグレードしたあと、どの種類の不具合でしょうか。gateway が立ち上がらない、RPC プローブが失敗する、あるいは CLI は新しいのにユーザー向け systemd が古いパスを指したまま、といった症状です。本稿は本番読者向けに、まず七つの隠れた前提で split brain（新旧バイナリの分岐） を炙り出し、症状表で「設定に刻まれたバージョン」と「トークン／リモート URL」系を分け、続けて 六段階の安全な復旧 Runbook（PATH → gateway install --force → gateway restart → doctor）と、破壊的な環境変数の門 をいつ開くかを示します。文中では cron とアップグレード後の回帰、リモートモード、本番オブザーバビリティ へ役割分担で誘導します。
公式トラブルシューティングでは、新しい OpenClaw が openclaw.json を書き込み meta.lastTouchedVersion などを更新したのに、PATH 上ではまだ 古い openclaw バイナリ が解決される場合、読み取りは通っても、ゲートウェイのインストール／再起動／削除など 破壊的な変更 では CLI が拒否し、半分新しいメタデータを書き込まないようにします。これが本番でいう split brain に近い光景です。
「npm が成功した」と「サービスが新バイナリに切り替わった」を同一視する： npm install -g はグローバル接頭辞下の実行ファイルだけを更新します。launchd や systemd --user のユニットが古い絶対パスを指していれば、再起動後も同じです。
ログインシェルとサービス環境で PATH を混ぜる： 対話シェルで which openclaw が正しくても、デーモン環境 と一致するとは限りません。
複数のインストール元を無視する： Homebrew、公式スクリプト、npm グローバルが同時に存在し、先頭の PATH の順で決まります。
アップグレード後に gateway install --force を飛ばす： 公式はバイナリがずれたときにサービス封入を入れ直すよう勧めます。手動で一度 gateway を起動しただけでは、次の再起動で再び分岐する地雷が残ります。
「doctor のエラーは全部設定が壊れた」と決めつける： 場合によっては バイナリと設定ガード の不一致です。まずバージョンを揃えてからキーを直します。
リモートとローカルを行き来しながら設定のスナップショットを取らない： リモートモードの記事 と同じ規律で、先に openclaw config get gateway.mode を確認してからプローブ先を決めます。
アップグレード後に channels だけ見てスケジュール面を見ない： cron と Gateway は同じ系譜です。回帰確認は cron 記事 のチェックリストを読みます。
共通の根は、「設定が読める」と「実行面が揃っている」を混同することです。正しい心構えは、設定の印は最後にファイルを書いた版を表す一方、サービスを動かすバイナリの身元は別に検証する、というものです。
下表は当直メモを「アップグレードが悪い気がする」から「サインできる分岐」へ進めるためのものです。
| 兆候 | split brain 寄り | 認証／セッション寄り | リモート URL／トポロジ寄り |
|---|---|---|---|
| doctor のキーワード | 新旧バイナリの分岐を示し、gateway の破壊的動作を止める | トークン／デバイス系のエラーコードで、バイナリ版と無関係 | RPC プローブが失敗し、ローカルの gateway status --deep が想定外ホストを指す |
| gateway status | ランタイムの挙動と CLI の --version が明らかに食い違う | ランタイムは動くが unauthorized のまま | ローカルは stopped、実体はリモートで動いている |
| 最初の手 | PATH を揃える → gateway install --force → 再起動 | トークン／デバイス握手を切り替えるか揃える | gateway.remote.url と環境変数が リモートモード記事 と一致するか確認する |
アップグレード当夜の黄金の二点：(A) どのバイナリが動いているか。(B) どの印が誰によって書かれたか。これが揃ってからチャンネルと cron を議論します。
Tailscale／プライベートトンネル と組み合わせる場合、「トンネルが通る」と「RPC が通る」を同一視しないでください。Tailscale プライベート公開 の記事に沿って両端で受け入れます。
以下は順序に敏感な手順です。いずれかで新旧がまだ一致しないなら、並行して設定とバイナリをいじらず、一つ前の段に戻ります。
現場の固定： openclaw --version、ユニットに見えるバイナリの絶対パス、doctor の出力をスクリーンショットで保存します。
PATH とエイリアスの修正： 非対話セッションでも which openclaw が 意図したアップグレード版 を指すようにし、パスを隠すシェルエイリアスを外します。
インストール元の一本化： 文書で推奨される npm／インストーラなど、単一の保守チャネルを選び、「前は brew、今は npm」の長期混在を避けます。
サービス封入の入れ直し： PATH を確認したうえで、同一ユーザーとして openclaw gateway install --force を実行し、launchd／systemd のメタデータを更新します。
Gateway のコールドスタート： openclaw gateway restart のあと、gateway status と RPC プローブを実行します。
回帰チェック： openclaw doctor → channels status --probe → cron list に期待どおり登録されているか照合します。
openclaw --version command -v openclaw openclaw gateway status openclaw doctor openclaw gateway install --force openclaw gateway restart openclaw channels status --probe
ヒント： ログにポート競合、メモリの尖り、compose の起動順が出る場合は、Gateway not ready の実践記 と closed(1000) RPC を併読し、リソース系の故障を split brain と取り違えないようにします。
公式トラブルシューティングでは「新しい設定＋古いバイナリ」を危険な組み合わせとみなします。古いプロセスがゲートウェイのサービスメタデータを書き換えられると、ディスク状態が再現不能な混成になり得ます。利用者保護のため、新しい OpenClaw は gateway 関連の破壊的操作に 硬い門 をかけることがあります。対応する OPENCLAW_* 環境変数（名称と意味は 当該版の公式ドキュメント に従います）は、緊急で古いバイナリに一度だけ必要な場合に限り設定します。
注意： この種の変数は「すべてのチェックを飛ばす魔法のスイッチ」ではありません。リスクを理解し、サービス封入を壊しうることを受け入れる狭い局面向けです。ドキュメントにロールバック条項がない限り、既定は未設定のままにします。
保守しやすいやり方は通常、PATH を直し、サービスを入れ替え、新しいバイナリでアップグレードを完走することです。ベンダが古いパッケージの取得を止めたなど特別な場合だけ、別の変更票にダウングレード経路を書き、監査用の写しを残します。
プラットフォーム側で内部合意に使える定量的なアンカーです。
openclaw --version のスクリーンショット を残し、復旧後に完全一致させます。doctor のクリーン結果を記録します。ノート PCや共有開発機上の Gateway はスリープ、OS アップデート、マルチユーザーと衝突しやすく、OpenClaw を 7×24 で常駐し SSH 可能で、ディスクとネットワークの前提を契約に書ける専用のリモート Mac に載せる方が、繰り返しの「アップグレード後の分岐」より長期的に得をしやすいです。NodeMini のクラウド Mac Mini レンタル は固定 SSH と専用算力を提供し、AI ゲートウェイや社内自動化のホストに向きます。仕様と接続は レンタル料金の説明 と ヘルプセンター を参照してください。OpenClaw の実践記事はブログで OpenClaw カテゴリ を絞り、「観測 → cron → リモートモード → 本稿のアップグレード分岐」の順で読むと理解が進みます。
「最後にどの版の OpenClaw が設定ファイルを書き終えたか」という版の印と捉えてください。PATH 上がまだ古いバイナリだと、「サービスメタデータへの書き込みを守る」といった保護的な挙動になります。PATH を直し、Runbook に沿ってサービスを入れ替えたあとで doctor を再確認し、通常は JSON を一行ずつ直す前に見ます。
split brain が排除される前は、cron 一覧は「正常に見えても」実行面が拒否する可能性があります。まず本稿の第3節を完了してから、cron の手順書 で周期回帰をします。ほかの記事は OpenClaw フィルタ からどうぞ。
gateway.mode、gateway.remote.url、両端の gateway status を突き合わせます。詳細は リモートモードの切り分け です。マシン選定は先に レンタル料金ページ をご覧ください。