2026年 OpenClaw アップデート後の CLI と gateway のバージョン不一致：npm グローバルと ~/.openclaw/lib のダブルスタック同期、LaunchAgent 再起動と openclaw doctor——専用リモート Mac の SSH で再現できるチェックリスト＋FAQ

OpenClaw を更新したあと、CLI は新しいセマバーなのに gateway プロセスだけ古いビルドのまま——という状況は、npm -g 側と ~/.openclaw/lib 配下のランタイムがずれ、launchd が古いバイナリを握り続けているときに起きやすいです。本稿では ダブルスタック同期 の順序、LaunchAgent の再起動パターン、openclaw doctor による修復を、SSH だけの専用リモート Mac でも再現できる形でまとめます。長時間の対話型メンテには 2026年リモート Mac CI：SSH ControlMaster による接続再利用と tmux の永続セッション——セルフホスト Runner の長時間ジョブにおける安定性比較と切断復旧の意思決定マトリクス＋FAQ、SSH 自動化全般の落とし穴は 2026年 OpenClaw & SSH自動化深掘り実践：落とし穴回避・安定バックグラウンド実行・安全デプロイと併読すると運用しやすいです。

1. TL;DR — 「バージョン不一致」が指すもの

インストール面が二つ： npm install -g openclaw（または採用しているパッケージマネージャ）由来のグローバル CLI と、~/.openclaw/lib に展開される ランタイム／gateway ペイロード。片方だけ更新すると、プロトコル・設定スキーマ・プラグイン ABI が食い違います。

常駐プロセスは一つ： gateway は多くの場合 LaunchAgent の plist で起動され、サービスを再起動するまで新しいファイルを読みません。対話シェルではいまの openclaw が見えていても、gateway は古いまま、というパターンが典型です。

doctor → 再起動： まず openclaw doctor でパス・権限・環境のヒントを直し、そのあと LaunchAgent を規定順で再読込し、リスナーとワーカーが同じバージョンラインになるようにします。

2. npm グローバルと ~/.openclaw/lib がずれる典型原因

2026 年時点でよくあるパターンは次のとおりです。

部分アップグレード： npm update -g openclaw は成功したが、過去の実行で ~/.openclaw/lib に展開されたアプリ束が原子置換されていない。
複数の Node／npm プレフィックス： SSH セッションは nvm／fnm のパスを使う一方、launchd は最小限の PATH のまま——エージェントが古い Node や古いラッパーを呼び続ける。
ユーザーとデーモン： LaunchAgent はログイン中のユーザーで動くが、別ユーザーで入れたり sudo で書いたりすると ~/.openclaw の所有権が上書きを阻む。
手コピー： 開発機からバイナリやシンボリックリンクを lib にコピーし、公式インストーラを通さない。

3. 事実確認（SSH・変更前に同じユーザーで）

LaunchAgent を所有するユーザー（多くは CI または運用アカウント）で実行します。

which openclaw と openclaw version（リリースノートに従い openclaw --version の場合も）。
npm 経路なら npm list -g openclaw --depth=0。
~/.openclaw/lib の更新時刻：ls -lt ~/.openclaw/lib | head。
gateway ビルド：ドキュメントの version または health エンドポイント、あるいは ps／ログでコマンドラインを読み、リリースノートと突き合わせる。
launchctl list | grep -i openclaw（ラベルは plist 名に合わせて読み替え）。

4. ダブルスタック同期：推奨順序

次の手順を 一つのメンテナンス窓 にまとめます。

利用側を止める： トラフィックを一時停止するかメンテ表示にし、gateway がストリーム途中で入れ替わらないようにする。
公式の手順でアップグレード： 多くの場合 npm install -g openclaw@latest に加え、~/.openclaw/lib を更新するポストインストール（openclaw install や同梱スクリプトなど）を実行する。
ディスク確認： ホームを載せるボリュームで df -h。展開失敗は中途半端なツリーが残ります。
doctor： openclaw doctor を実行し、表示された修正（パス・権限・欠けたディレクトリ）を適用する。
LaunchAgent 再起動： unload／bootstrap または gateway ラベルに kickstart -k。Mac エージェントと gateway を分けている場合は依存順（gateway を先に）で再起動する。
再確認： CLI・ディスク上 lib のタイムスタンプ・gateway の health／version が一致すること。

5. LaunchAgent 再起動 — 再現しやすいパターン

対話型 Mac では GUI ユーザエージェントドメイン gui/$(id -u) を使います。ai.openclaw.gateway は実際の plist のラベルに置き換えてください。

グレースフル： ジョブが既にロード済みなら launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway。
plist 編集後のフルリロード： launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist のあと launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist。
確認： launchctl print gui/$(id -u)/ai.openclaw.gateway で終了ステータスを確認し、分割された標準出力／標準エラーログを tail する。

CLI のシェルだけ再起動しても gateway は更新されません——SSH 専用ホストでいちばん多い「直ったつもり」です。

6. openclaw doctor — 遠隔で何を期待するか

openclaw doctor は自動の整合チェックです。典型的には Node の下限、書き込み可能な設定ディレクトリ、gateway への接続、プラグインパスを見ます。SSH では次に注意します。

launchd の環境に合わせた ログインシェルで実行するか、plist の EnvironmentVariables と同じ PATH・OPENCLAW_* を明示的に export する。
~/.openclaw 配下の権限修復を提案されたら適用したうえでエージェントを再起動する——doctor が常にサービスまで再起動してくれるとは限りません。
標準出力は ~/Library/Logs/OpenClaw/ などにリダイレクトし、共有 CI マシンでの監査に残す。

7. 症状 → 原因（早見表）

症状	有力な原因	まず打つ手
CLI は新しいが API が拒否／スキーマエラー	gateway が古いビルドのまま	lib 同期のあと LaunchAgent を再起動し、health エンドポイントで確認
cron／launchd では `openclaw` が見つからないが SSH では動く	`PATH` の不一致	plist にフルパスを書くか `/usr/local/bin` へシンボリックリンク
`~/.openclaw` への書き込みが Permission denied	root とユーザの混在インストール	エージェントユーザへ `chown -R` し、doctor を再実行
アップグレード後に断続的に「プロトコル不正」	ポート違いの gateway が二つ、または古い子プロセス	`pgrep -lf openclaw` で迷子 PID を整理し、リスナーを一つに

8. SSH 向け 1 枚チェックリスト

LaunchAgent ユーザで SSH：whoami／id。
変更前の記録：CLI バージョン、npm グローバル、~/.openclaw/lib の mtime、health／ログからの gateway バージョン。
公式手順でアップグレード＋ lib 更新。
openclaw doctor → 修正適用。
gateway の LaunchAgent を再起動し、リスナーが一つか確認（lsof -nP -iTCP -sTCP:LISTEN）。
変更後：バージョンが揃い、gateway を叩く CLI コマンドを 1 本スモークする。
ログ抜粋とタイムスタンプを runbook に残す（長い SSH 手順は ControlMaster や tmux と組み合わせると運用者の負担が下がります）。

9. FAQ

質問	短答
`~/.openclaw/lib` を手で消してよい？	ドキュメントに書かれている場合のみ。インストーラ／doctor を優先し、盲信削除はプラグインを壊しやすい。
`brew` と npm、どちらが正しい？	ホストごとにサポートされた経路を一つに。パッケージマネージャの混在がダブルスタックずれの起点になりやすい。
doctor は成功なのに gateway が古い	プロセスが再起動していない——`kickstart -k` か bootout／bootstrap。
CI から SSH だけで更新できる？	ジョブが同一ユーザー・同一環境なら可能。メンテ窓を設け、終了後にリスナーを必ず確認する。

gateway のバージョン揃えに Mac mini が向く理由

整合を取りやすいのは、機械が静かで常時稼働し、ユーザランドが単一で説明しやすいときです。Apple Silicon の Mac mini はバックグラウンドの gateway やログ負荷に対してワット当たりの性能が高く、アイドル時の消費電力も小さい——24 時間エージェントを回してもラックの騒音の心配が少ない構成になります。

macOS ではネイティブに launchd が使え、POSIX の挙動も予測しやすく、ヘッドレス修復には SSH がそのまま使えます。Gatekeeper と SIP は「バージョン不一致」に見えるバイナリのすり替えのような事象を減らし、M シリーズのユニファイドメモリは CLI・gateway・CI タスクを同時に載せても応答性を保ちやすいです。

OpenClaw のアップグレードと doctor 駆動の修復を安定して回したいチームにとって、コンパクトでコスト効率のよい土台として Mac mini M4 は現実的な選択肢です。本稿のチェックリストを、邪魔にならない筐体で回したい場合の出発点にもなります。

SSHMac のトップページで、CPU・メモリ・ストレージをゲートウェイ同時接続とログ保持に合わせて選べます。