2026年 OpenClaw リモートベアメタル Mac Gateway ハイブリッド reload とモデルルーティング：
Token plist 整合と launchd 排障チェックリスト

OpenClaw Gateway を CALMVPS ベアメタル リモート Mac に常駐させたあと、現場で最も多い変更は次の二つです。① デフォルトモデルやルーティング表だけ切り替えたいのに、プロセス全体を再起動して Slack/Webhook が一時切断される。② SSH セッションで OPENCLAW_GATEWAY_TOKEN を設定したのに LaunchAgent plist が未同期のため、ヘルスチェックと gateway.remote のペアリングが繰り返し失敗する。2026.4.x から gateway.reload.mode=hybrid が公式にサポートされ、多くのルート変更で全量 bounce を避けられます。2026.5.x では gateway status --deep が ai.openclaw.update.* の stale タスクをより明示します。

本稿は、すでにリモートで Gateway を稼働させている開発者と SRE 向けに、再現可能な hybrid 六段、Token 境界リスト、エラー対照表、アップグレード後の triage 経路を整理します。読了後、いつホットリロードで足りるか、いつ全再起動が必要か、Token を plist に置くべきか、launchd ループのどの層から見るかを判断できる状態を目指します。

01 全再起動と Token ドリフト：リモート Gateway の運用痛み

レンタルノードで 7×24 Gateway を回すと、「初回インストール」より「設定変更」の方が時間を取られることが多いです。典型的な痛みは次のとおりです。

  • ルート変更コストの過小評価：デフォルトモデルを A から B へ、あるいは workspace 単位の provider マップを追加するたびに launchctl kickstart -k でサービス全体を再起動すると、Webhook と長寿命接続が再起動ウィンドウで落ち、当番が上流モデル障害と誤判定しがちです。
  • 環境の二重化：SSH でリモート Mac に入り、対話 shell で export OPENCLAW_GATEWAY_TOKEN=... したあとローカル curl のヘルスチェックは成功する。しかし launchd が起動した Gateway プロセスはその変数を読めず、制御面と自動化スクリプトは未認可のままです。これが「Token を設定したのに効かない」最多パターンです。
  • 設定ルートのずれ：設定をユーザーディレクトリに置きながら plist の OPENCLAW_HOME や WorkingDirectory が別パスだと、hybrid reload が読むファイルとエディタで編集しているファイルが一致しません。
  • アップグレード後の launchd ノイズ：2026.5.12 前後の macOS では、アップデート完了後に Gateway が起動せず、ai.openclaw.update.* の submit タスクが exit 127 で gateway シグナルを繰り返し引く事例がありました。ポート占有だけを見ると launchd 層の根本原因を見逃します。

本番では hybrid ホットリロードで日常のルート変更の揺れを抑え、Token と plist を単一の真実源にして SSH と daemon の分裂を防ぐ必要があります。以下は Gateway が loopback（多くは 127.0.0.1:18789）を listen し、外部は SSH トンネルまたはリバースプロキシ経由という前提です。公網公開そのものは本稿の範囲外です。

リモート Mac で「curl が通る」ことは「daemon 設定が正しい」ことと同義ではありません。受け入れ基準は launchd プロセスの環境変数であり、現在の SSH セッションではありません。

02 リロードモード対照：hybrid、off、全再起動

gateway.reload.mode を変更する前に、次の表で「どの変更がホットリロード可能か、どれが再起動必須か」をチームで揃えてください。

OpenClaw Gateway 設定変更と推奨処理（2026.4.x+）
変更種別 hybrid ホットリロード 全再起動 / daemon 再インストール
デフォルト model ID、ルート表、workspace 級 provider マップ 通常 hybrid reload 可 invalid-key 時は validate 後に再起動
OPENCLAW_GATEWAY_TOKEN ローテーション ホットリロードのみは非推奨。plist 更新後 bootout/bootstrap 推奨：Gateway 側を先に、クライアントをローリング
listen アドレス / ポート、TLS 終端方式 一般に非対応 再起動必須。ファイアウォールとトンネル再確認
Node メジャーアップ、openclaw 大バージョン跨ぎ 対象外 託管 Gateway 用 Node を使用。複数 Node で binary 誤結合を避ける
gateway.reload.mode を off から hybrid へ 初回は設定書き込みと validate daemon が新設定を読まない場合 LaunchAgent を一度再起動

hybrid の設計意図は、設定が合法ならルーティング関連フィールドを長接続を drop せず反映することです。認証境界、listen ソケット、ランタイム変更には完全なサービス刷新が必要です。

03 2026.4.x アーキテクチャと前提条件

CALMVPS ベアメタルノードでは、単一リモート Mac で Gateway daemonを動かし、ローカルまたは他リージョンから SSH -L 18789:127.0.0.1:18789 または Tailscale で制御面に触れる構成を推奨します。計算集約タスクは並列リソースへ分割できますが、制御面 Token は主 Gateway インスタンスにだけ向けるべきです。複数インスタンスで同一 Token を共有すると監査が混乱します。

  • ランタイム：OpenClaw 2026.4.x ドキュメントでは Node 22.16+ が一般的です。方針が許せばベアメタルイメージで Node 24 LTS を固定し、Gateway 託管 Node との不一致を減らします。
  • インストール経路：openclaw onboard --install-daemon が LaunchAgent を書き込みます。以降の本番変更は .zshrc の export より plist の EnvironmentVariables を優先してください。
  • 設定検証：openclaw config validate がある場合、各ホットリロード前に実行し invalid-key を解消します。さもないと reload が黙って失敗またはロールバックします。
  • バージョン可視性：2026.5 以降 openclaw gateway status の JSON に稼働中 Gateway バージョンが含まれ、CLI との skew を早期に検知できます。

公式リポジトリとリリースノートは schema を随時更新します。リリースまたは入庫後、次のリンクを再度開いてフィールド名とコマンドを確認してください。

openclaw/openclaw（GitHub リポジトリ）

04 hybrid reload と Token plist 六段手順

以下六段は、SSH でリモートベアメタル Mac に入り、Gateway が launchd 管理下にある前提です。「ルートのホットリロード」と「Token の固定化」を同じフローに置くのは、YAML だけ直して plist を忘れる漏れを減らすためです。

  1. daemon 健全性の確認：openclaw gateway status を実行し、現行バージョン、listen アドレス、ヘルス結果を記録します。深い triage なら --deep で stale ai.openclaw.update.* を確認します。
  2. hybrid モードの設定：Gateway が読む設定ルートで gateway.reload.mode を hybrid にします（ネストパスは openclaw config validate 出力に従います）。保存後 validate し invalid-key がゼロになるまで繰り返します。
  3. モデルルーティングの変更：デフォルト model ID、provider map、workspace 上書きを更新します。保存パスは plist の WorkingDirectory / OPENCLAW_HOME と一致させてください。
  4. ホットリロードとルート受け入れ：バージョン文書に従い reload をトリガー（または hybrid の自動拾い）し、新モデル経由の短いリクエストを送り、provider 側ログまたは応答メタデータで切替を確認します。
  5. Token を plist に固定：OPENCLAW_GATEWAY_TOKEN を LaunchAgent plist の EnvironmentVariables に書き込みます。gateway.remote 利用時はトンネル前端と一致する URL も同じ場所に置きます。launchctl bootout / bootstrap でサービスを更新し、SSH セッション export のみに頼らないでください。
  6. エンドツーエンドのヘルスチェック：Gateway ホスト以外から、本番と同じ Token で gateway.remote またはローカル転送 URL にアクセスします。同時にホスト上で curl -sf http://127.0.0.1:18789/...（ヘルスパスは各バージョン文書参照）で loopback を確認します。
gateway-hybrid-check.sh 
openclaw config validate
openclaw gateway status
openclaw gateway status --json
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

LaunchAgent の plist 実名は openclaw onboard --install-daemon の生成結果に従います。上記は一般的な命名例です。実行前に ~/Library/LaunchAgents/ で実ファイル名を確認してください。

05 アップグレード後 launchd 残存と gateway.remote 排障

openclaw update 後に Gateway が起動しない場合、「launchd 層 → 設定層 → ネットワーク層」の順で見ることを推奨します。OS 再インストールから入る必要は通常ありません。

リモート Gateway よくある現象と第一選択の修復
現象 優先確認 第一選択の修復
status --deep 失敗だが LaunchAgent は loaded launchctl list の ai.openclaw.update.* が高 RUN_COUNT、exit 127 stale updater submit を除去。doctor 指示で plist 修復。gateway を bootstrap
401 / token mismatch SSH export と plist の一致 plist を正とし Token を統一。ローテは Gateway 先行
gateway.remote は到達するがペアリング失敗 LAN と公網 DNS 分裂、トンネル SAN remote URL をクライアントが実際に通るトンネル前端に合わせる
ホットリロード後も旧モデル 誤った設定コピーを編集していないか OPENCLAW_HOME を揃え validate 後再試行。必要なら一度だけ全再起動
update 後 CLI と Gateway プロトコル skew 複数 Node、非託管 Node で gateway 起動 託管 Gateway Node で後続コマンド。バージョン番号を揃える

GitHub Issue #81859 は beta アップグレード後の stale updater による gateway ループを記録しています。upstream は status/deep と doctor に検知を追加済みです。triage はインストール中の OpenClaw 版 release note を正としてください。

openclaw/openclaw Issue #81859（macOS launchd updater 残存）

06 ティア判断、引用可能パラメータ、CALMVPS シナリオ

「単一 Gateway + 複数ルート」が必ず M4 Pro を要するわけではありません。同一インスタンスで重い Skills 試装、多チャネル Webhook、ローカル小モデル推論を重ねるとメモリとディスクのピークが重なります。調達と容量レビューに次のパラメータをそのまま引用できます。

  • デフォルト制御ポート：18789（loopback listen。外部はトンネルまたはリバースプロキシ + Token）。
  • ホットリロードモードキー：gateway.reload.mode=hybrid（2026.4.x 文書。フィールドパスは validate 出力準拠）。
  • 認証環境変数：OPENCLAW_GATEWAY_TOKEN は LaunchAgent EnvironmentVariables に必須。対話 shell と一致させます。
  • 推奨 Gateway 宿主：多チャネル + Cron 併用なら M4 24GB から。ルート実験と並列 Skills 評価は M4 Pro。ログと workspace 成長が速い場合は 1TB/2TB 拡張を CPU 昇格より先に。

Gateway を睡眠の多いノート PC に置くと、ホットリロードウィンドウとフタ閉じ再起動の重なり、Token が shell のみに存在が弱点になります。macOS ツールチェーンのない Linux VPS だけでは launchd と一部チャネル挙動を再現しにくいです。予測可能な hybrid 運用、plist 級 Token、ドキュメント化されたアップグレード後 triageが必要なチームには、CALMVPS マルチリージョン ベアメタル Macが Gateway 宿主として適しています。Apple Silicon 専有、約 120 秒デプロイ、日次・週次の並列リソースでスパイクを吸収できます。機種と料金は CALMVPS 料金ページをご確認ください。