macOS上のOpenClaw：openclaw gateway restartが成功しても待受と本体が古いまま残る問題

リモートMacでOpenClawのゲートウェイを常駐させる現場では、拡張の配布、ヘルスプローブ、ペアリングの再握手までを一つの常駐プロセスに寄せがちです。そこで一番腹が立つのは、`openclaw gateway restart`が終了コードゼロで返るのに、待ち受けポートやUNIXソケット、管理用エンドポイントの応答だけが前夜のビルド文字列のまま固定される場面です。これはネットワークの幽霊ではなく、多くの場合、`launchd`のユーザーLaunchAgentとして登録された`com.openclaw.gateway`が、`ProgramArguments`や`WorkingDirectory`の古い写像を抱えたまま再評価されていないことを示します。

SSHとGUIログインではPATHや鍵の見え方が変わり、再起動が子だけ触って外向き本体が旧世代のまま残る分裂が起きます。

この稿は、まず公式の段階的切り分けを最優先に置き、launchd前提の導入と強制再インストール、lastTouchedVersionと深いパスの分裂、遠隔CLIと設定ドリフトの健康診断、429や無返信に見えるチャネル症状、メモリとjsonl周辺の退行と巻き戻し、ComposeとトークンとWebSocketの組合せと往復して読みます。

まず症状を言語化します。CLIは成功、ログは穏やか、しかし`curl`の応答ヘッダや管理用のバージョン行だけが古い。あるいは拡張の表向きのロードは成功に見えるのに挙動が変わらない。ここでいきなり`bootout`へ飛ぶのは早すぎます。

公式ラダーは、429や資格情報、二重トグル、拡張隔離といった、launchd以外の原因を先に切り分けるための順路です。記録はタイムスタンプ付きで残し、次の担当が同じ迷路に入らないようにします。

`~/Library/LaunchAgents/com.openclaw.gateway.plist`は、ディスク上の真実の入口です。`plutil -p`で`ProgramArguments`と`WorkingDirectory`を読み、実体バイナリの絶対パスが今回の導入ルートと一致するかを確認します。

ドメインを取り違えると、コマンドは綺麗に終わっても、見ているLaunchAgentが別物のままです。SSHセッションのbootstrapと、コンソールユーザのGUIドメインを取り違えないよう、`launchctl print`の差分を残します。

修復の核は`launchctl bootout`と`bootstrap`のペアです。曖昧な`kick`より、登録の再構築が必要な症例に合います。停止による短い穴はあるため、関係者へ短いメンテ告知を出します。

plistのメタデータが導入レイアウトと食い違うなら、`gateway install --force`を検討します。トークンやペアリングJSONは退避してから実行し、戻し手順までセットで計画します。

セマンティックバージョンの三点セット、CLI、ゲートウェイ本体、永続メタの行が揃わないと、split-brainに似た部分成功が続きます。brewと手動導入を混ぜたホストほど、ラッパーと実体の二重化に注意します。

拡張パックはコアのsemverとは別契約です。コアだけ上がり、拡張のAPI面が追いついていないと、待受が新しくなったように見えても深い経路だけが旧挙動のままという罠が出ます。

リモートMacでは、更新ウィンドウがバラけると症状が時間差で顕在化します。CIイメージが月曜にCLIだけ上げ、金曜までLaunchAgentが古いまま、という典型です。導入後フックでplistの指差し検証を自動化すると再発率が下がります。

監視は起動時の一行バージョンと、一定間隔のハートビートに埋め込みます。浅い緑だけを信じない文化にします。

ベースラインは、semver行、plist指紋、`launchctl print`抜粋、待ち受け一覧、最小プローブの束です。週次で回し、アップグレード直後は必ず回します。

バックアップは装飾ではなく演習まで含めます。退避したトークンを本当に戻せるか、ステージングで一度だけでも検証します。

1. 成功に見える症状の型

終了コードゼロは健康診断ではありません。ユーザーLaunchAgentは、ラッパーだけ入れ替わり、長寿命サイドカーが旧UNIXソケットを握ったままという姿を取りがちです。

部分再読込は紛らわしいです。doctorの要約は緑でも、深いプローブだけが旧ポリシーを返す。セマンバー食い違いや429とも見分けにくいです。

2. 公式ラダーを先に完了する理由

飛ばすと一時間単位で迷子になります。構造化された診断は、デーモン再起動失敗と、再起動は成功だが設定が悪い、を分離します。

429や資格情報が原因なら、launchdを直しても同じ地獄です。記録をタイムライン化します。

3. plistの真実とbootout/bootstrap

登録の再構築が必要なら、`launchctl bootout`と`bootstrap`のペアが現実的です。ドメインは文脈依存なので手順書へ明記します。

4. 手順化された復旧チェックリスト

1. 症状の四点セットを採取する：期待semver、実行中semver、plist更新時刻、ラダー各段の出力。
2. 公式ラダーを上から順に実行し、429や資格情報を先に除外する。
3. `plutil -p ~/Library/LaunchAgents/com.openclaw.gateway.plist`でProgramArgumentsを確認する。
4. 正しいbootstrapドメインで`launchctl bootout`し、続けて`bootstrap`する。
5. `launchctl print`で`com.openclaw.gateway`が期待バイナリを指すかgrep相当で確認する。
6. メタが壊れているならトークン類を退避してから`gateway install --force`を検討する。
7. 整合後に最小プローブと深いルートの両方を再実行する。

# 1) 先に公式ラダー（doctor/プローブ/拡張の順）
#    参照: 20260506-openclaw-official-troubleshooting-gateway-probe-extensions-429-runbook-2026-ja.html

# 2) ユーザーLaunchAgentの実体確認
/usr/bin/plutil -p ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 3) 正しいDOMAINへ置換してから再登録
/usr/bin/launchctl bootout DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist || true
/usr/bin/launchctl bootstrap DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 4) Label com.openclaw.gateway の生存確認
/usr/bin/launchctl print DOMAIN | /usr/bin/grep -n "com.openclaw.gateway" || true

# 5) それでもProgramArgumentsがズレるなら退避の上で強制導入
#    openclaw gateway install --force

5. 介入の比較表

最小介入で不変条件を戻す目安です。

6. セマンティックバージョン整合と遠隔ドリフト

CLIとゲートウェイと永続メタはセットで動かすのが健全です。lastTouchedVersionの食い違いは、成功メッセージと矛盾する挙動を生みます。

遠隔Macでは更新タイミングがバラけるため、導入後フックでplistの絶対パス検証を自動化するのが効きます。

7. リモートMacの運用ベースライン

復旧後は、semver行、plist指紋、`launchctl`抜粋、待ち受け一覧、最小と深い両プローブを一ファイルに束ねます。ヘッダにホスト名を書きます。

週次とツール変更直後に回し、ゆっくりした腐敗を拾います。

8. 典型痛みの番号付き列挙

1. 終了コードゼロと、応答ヘッダの世代が一致しない。
2. GUIドメインとSSHドメインの取り違えで、見ているプロセスが別物。
3. セマンバーは揃ったように見えるが、拡張API面だけが旧契約のまま。
4. トークンは新しいのに待受が旧秘密のままというクライアント視点の分裂。

9. FAQ

質問：すぐ`bootout`で良いですか。回答：短い停止は伴います。先に429や資格情報をラダーで切り分けてください。

質問：`gateway install --force`は万能ですか。回答：導入物の不整合には効きますが、上流障害や誤設定の仮面を被ることもあります。

10. まとめとホステッドMac

成功メッセージは契約の履行を保証しません。公式ラダーで上層要因を切り分け、`com.openclaw.gateway`を`bootout`/`bootstrap`で再登録し、必要なら強制導入とsemver整合へ進みます。

運用の仕上げはベースライン化です。証跡が揃うほど、再発の説明が速くなります。

再現性の高いリモートMac環境を検討するなら、SFTPMACのホステッドMacプランも合わせて見てください。公開手順書と併せると、夜間の切り分けが軽くなります。