2026 OPENCLAW
UPDATE_
WROTE_
WRONG_
NODE.

OpenClaw v2026.5.20 前後の障害のうち、「偽アップグレード」や「チャネル認証の不具合」と誤診されやすいものの正体は、LaunchAgent に焼き込まれた Node パスと対話シェルの which node の不一致です。openclaw update の follow-up が PATH 上の別 Nodeで post-install・doctor・再起動を走らせ、plist 内のサービス定義だけが書き換わると、次の gateway restart で launchd が即終了します。5.20 の公式修正（PR #84043）はGateway を託管する service Nodeを更新チェーン全体で使い、gateway status --json に runningVersion を出して CLI/Gateway プロトコル skew を可視化します。本稿は症状マトリクス・意思決定表・6 ステップ Runbook・三ゲート・ケーススタディ・FAQを示し、サイト内の《偽アップグレードと gateway status》《LaunchAgent token 失効》《invalid config と doctor》と役割分担し、リモート Apple Silicon Gatewayでの 7×24 対照検証とロールバックを支援します。

1. 課題の分解：版番号ではなく Node バイナリのドリフト

1）複数 Node の共存は日常：Homebrew の /opt/homebrew/opt/node/bin/node、nvm デフォルト 22.x、fnm グローバル 20.x が同一 Mac に並ぶ。openclaw gateway install はその時点の node 絶対パスを ai.openclaw.gateway plist に書く。2）PATH 切替がドリフトを誘発：ターミナルで nvm use 25 後に openclaw update すると、旧ロジックは新 PATH の nodeで follow-up を実行——パッケージ root が変わらなくても、別 prefix の openclaw を指す plist にすり替わる。3）「偽アップグレード」との違い：偽アップグレードは CLI 5.20・Gateway 5.12 の版ずれ；本稿はengines.node 未達やバイナリ不一致による起動直後クラッシュ／WS 握手失敗。4）プロトコル skew：5.20 は CLI が Gateway より 1 マイナー新しい場合の restart health check を維持；Node ドリフトで Gateway が上がらないと unauthorized や RPC タイムアウトが先に出る。5）レガシー updater LaunchAgent：Issue #82167 の ai.openclaw.update.* 再 launch と Gateway SIGTERM；5.20 以降 update が best-effort disable——Runbook に launchctl 一覧確認を必須化。

2. 意思決定表：Node を揃えるか、パッケージを戻すか

現場シグナル	第一アクション	禁止
openclaw --version と plist 内 node の major が不一致	PATH 固定 → service Node で update 再実行または gateway install --force	plist 未バックアップで ProgramArguments 手編集
gateway status --json に runningVersion なし	gateway restart --wait 後、launchd 終了コード確認	~/.openclaw 全削除
更新後 Telegram のみ断続切断	Node ドリフト排除後にチャネル層	5.2 HTTP タイムアウトと混在修復
ノート OK・リモート Mac 全滅	対照ノードで plist node と npm root -g 比較	ローカル nvm パスをリモートへコピー
本番変更監査が必要	対照機で 6 ステップ + 30 分プローブ	金曜夜ピークでロールバック窓なし更新

3. 6 ステップ実装 Runbook

Step 1 「三要素」証拠の固定

記録：openclaw --version、which node と node -v、plist の ProgramArguments 先頭 2 要素（node パス + openclaw エントリ）。openclaw gateway status --json の runningVersion（5.20+）も保存。

Step 2 engines.node 閾値の確認

グローバル openclaw の package.json で engines.node を確認。service Node の major が不足なら先に Node を上げる——doctor 合格でも Gateway 起動失敗を防ぐ。

Step 3 託管 Gateway 用 Node の整合（5.20 推奨）

2026.5.20 へ上げた後 openclaw update：公式は LaunchAgent 内 baked node を follow-up に優先使用。既にドリフトしている場合は openclaw gateway install --force で意図した nodeを再焼き込み、npm root -g と plist の一致を確認。

Step 4 レガシー updater LaunchAgent の整理

launchctl list | grep openclaw：ai.openclaw.update.* が再起動ループなら 5.20+ で update が disable；旧版は launchctl bootout gui/$UID/ai.openclaw.update.*（進行中タスク確認後）。Issue #82167 の「更新成功後 3 分ごと SIGTERM」を回避。

Step 5 Gateway 順序再起動と JSON プローブ

openclaw gateway restart --force --wait 後、openclaw gateway status --json を 3 連続。runningVersion が目標と一致し RPC が閾値内。リモート Mac は launchctl kick -k gui/$UID/ai.openclaw.gateway 後に繰り返し。

Step 6 リモート 7×24 対照とロールバック窓

対照ノードはnvm 未切替のクリーン PATHで Step 1–5 を再現。本番が失敗なら版固定と plist/npm prefix diff を保持；30 分 channels.probe が全緑で closure。

4. 三つの自己検査ゲート

第一Node ゲート：plist 内 node が存在し node -v が engines.node を満たす。第二版ゲート：gateway status --json の runningVersion と openclaw --version が許容 skew 内（5.20 健康チェック）。第三チャネルゲート：openclaw channels status --probe に赤なし、30 分以内に「再起動直後即終了」なし。

5. ケーススタディ：「update 成功、翌朝 Gateway 全チャネル停止」

チームは《偽アップグレード》で版文字列を確認し CLI/status とも 5.20 と判断、チャネル token 障害と誤認。plist と which node の diff でNode ドリフトを特定。MACGPU 対照機で単一 Homebrew Nodeに Gateway を再インストール後、本番 Studio は plist 先頭 2 要素差し替えと gateway install --force のみで 30 分以内復旧。変更票：nvm 付き対話シェルからリモート launchd へ update 禁止；更新窓は service アカウントまたは env -i 最小 PATH で統一。

6. 業界観点：Agent Gateway の「ランタイム固定」と Mac 託管

2026 年の Node 分岐（nvm/fnm/Volta/Homebrew）により「グローバル CLI」と「daemon 固定ランタイム」が二重の真実になる。OpenClaw 5.20 がmanaged service Nodeを更新チェーンに組み込んだのは、Agent 運用が「入ればよい」から固定・diff・ロールバック可能へ移行した印。エンタープライズは更新チケットに plist node パス、engines.node 検証、gateway status JSON を要求し始め——版番号スクショだけでは不十分。

Windows/Linux でも複数 Node はあるが、macOS launchd の絶対パス意味論はより厳格——一度ドリフトすれば全チャネル停止。Apple Silicon リモート Mac は専有メモリ・Metal・7×24 グラフィックス/Agent 混合負荷からゴールド対照環境として選ばれる：PATH がクリーン、ディスクスナップショット可能、ログをチケット再生可能。MACGPU リモート Mac なら本機 nvm と隔離したノードで 5.20 更新・Node 整合・ロールバックを先に完遂し、本番へ進めます。

7. 引用可能な数値しきい値

① plist node と which node 不一致：更新成功宣言禁止。② engines.node が Node ≥22（インストール包依存）：service Node 未達なら先にランタイム交換。③ 更新後 30 分で launchd 非 0 終了が 3 回超：デフォルトロールバックと plist diff 保存。④ gateway status --json 3 回 runningVersion 取得不能：Unhealthy。⑤ リモートとローカルの npm グローバル prefix 不一致：plist 断片のクロスマシン貼り付け禁止。

8. FAQ

Q：偽アップグレードとの違いは？A：偽アップグレードは版文字列；本稿はNode バイナリと plist パス。Q：5.20 必須？A：5.20 から公式修正；それ以前は gateway install --force で手動整合。Q：Docker は？A：コンテナ内は通常単一 Node；ボリュームとイメージ tag に注意。Q：plist 手編集？A：可能だがバックアップ必須；推奨は gateway install --force。Q：MACGPU ノードの役割？A：対照検証・PATH 隔離・ロールバック窓——変更承認の代替ではない。