OpenClaw 2026 リモート Gateway ペアリングと SSH トンネル： macOS クライアントの Health Check トラブルシュートと LaunchAgent 常駐チェックリスト
JEXCLOUD クラウド Mac 上で OpenClaw Gateway の起動まで済ませたのに、手元の macOS アプリでは 「Health check pending」 や gateway.remote のペアリング失敗 で止まっていませんか。2026 年で最も多い原因は「Gateway が落ちている」ことではなく、ローカル App ↔ SSH トンネル ↔ リモート 127.0.0.1:18789 のどこか一環が切れていることです。本稿はローカルの OpenClaw クライアントからリモート Gateway を操作する開発者と SRE 向けに、SSH トンネルと Direct WSS の選定マトリクス、LaunchAgent 常駐チェックリスト、Health Check 巡回スクリプトと対照トラブルシュート表を示します（設定の詳細は OpenClaw 公式 onboarding ドキュメントを参照してください）。
読了後に次の三つに答えられるようになります：① ネットワーク環境では SSH LocalForward と Direct wss:// のどちらを選ぶべきか；② OPENCLAW_GATEWAY_TOKEN と ai.openclaw.ssh-tunnel / ai.openclaw.gateway の二つの LaunchAgent をどう役割分担するか；③ CLI の openclaw health は通るのに UI が pending のとき、ポート・Token・トンネルプロセスのどれを見るべきか。
01 OpenClaw リモート Gateway の構成：ローカル macOS クライアントからクラウド Mac を操作
2026 年の OpenClaw は macOS で Gateway 接続に Local（Gateway と App が同一マシン）と Remote（Gateway は別 Mac、ローカル App は SSH トンネルまたは Direct WebSocket で接続）の二モードを提供します。本番では Gateway を JEXCLOUD ベアメタル Mac の 127.0.0.1:18789 で動かし、開発者のノート PC 上の OpenClaw.app は「リモコン」に徹する構成が一般的です。これはノード選定と launchd Token トラブルシュートの記事と補完関係にあります。あちらは「リモートマシンの導入と選定」、本稿は「ローカルからの接続・常駐・死活確認」です。
レビュー会議で過小評価されがちな痛点は次の五つです。
- トンネルが常駐しない：SSH セッションが切れてもローカル App は古い状態を表示し、Health Check がタイムアウトするまで Gateway 到達不能に気づきません。
- Token の二重系統の不一致：リモートの
launchctl環境変数、~/.openclaw設定、ローカル App に入力した Token が揃わないと pairing / device token 系のエラーが出ます。 - ポートと転送のずれ：デフォルト Gateway ポート 18789 が占有されている、または LocalForward の宛先が誤っていると、CLI はリモート直結成功・ローカル localhost 失敗になります。
- Health Check UI の遅延：CLI のヘルスチェックは通っているのに macOS アプリ UI が pending のまま（コミュニティ Issue：openclaw#66306）。
- セキュリティ露出：手っ取り早く Gateway を
0.0.0.0にバインドし mTLS なしで公開すると、パブリック IP 上では実質裸の状態です。127.0.0.1 + SSH/Tailscale を推奨します。
覚えておく一句：「Gateway はループバックのみ、トンネルが外向き、Token は単一の真実源」。いずれかを迂回すると、トラブルシュートは時間単位になります。
02 SSH トンネルか Direct WSS か：OpenClaw リモート接続の選定マトリクス
OpenClaw 設定の OpenClaw runs では、Transport は通常 SSH tunnel と Direct (ws/wss) の二択です。永遠に正しい選択肢はなく、ファイアウォール、Tailscale のカバレッジ、運用習慣に合うものを選びます。
| 観点 | SSH トンネル + LocalForward | Direct WSS |
|---|---|---|
| セキュリティ境界 | Gateway は 127.0.0.1 のみ待受；外向きは SSH 暗号化 | TLS 終端と Token が必要；Tailscale / 社内 DNS と併用が多い |
| ファイアウォール適合 | SSH 22（またはカスタムポート）が通ればよい | wss ポートと証明書チェーンの開放が必要；企業プロキシ下では失敗しやすい |
| 遅延と安定性 | SSH 1 ホップ増だが RTT 15–40 ms は許容；KeepAlive plist で自己修復 | ホップが少ない；安定した WSS リバプロキシがある環境向け |
| 運用の複雑さ | ~/.ssh/config とトンネル LaunchAgent の維持 |
証明書、リバプロキシ、Token ローテーション手順の維持 |
| 推奨シーン | 個人開発者のノート PC から JEXCLOUD 単一ノードを操作；専任 SRE のいない小チーム | Tailscale Serve / 統合 API ゲートウェイがある複数人チーム |
ヘルプセンターで SSH 鍵ログインを有効にし、リモート Gateway がループバックのみにバインドされているなら、まず SSH トンネルを選んでください。社内で安定した wss://gateway.example.ts.net があり、macOS クライアントの「Test remote」が継続して通る場合のみ Direct に切り替えます。
03 クラウド Mac の事前準備：PATH、Token 権限、SSH 設定断片
リモートホストでは、非対話 Shell から OpenClaw CLI を呼び出せる必要があります（pnpm link --global 後は /opt/homebrew/bin または /usr/local/bin への symlink を推奨）。Token ファイルの権限は 600、所有者は Gateway 実行ユーザーと一致させてください。
Host jex-openclaw-sg
HostName your-instance.jexcloud.com
User macuser
IdentityFile ~/.ssh/jexcloud_ed25519
LocalForward 18789 127.0.0.1:18789
ServerAliveInterval 30
ServerAliveCountMax 3<key>Label</key>
<string>ai.openclaw.ssh-tunnel</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/ssh</string>
<string>-N</string>
<string>jex-openclaw-sg</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>Gateway 本体は macOS アプリまたは CLI で LaunchAgent ai.openclaw.gateway をインストールします。環境変数 OPENCLAW_GATEWAY_TOKEN は launchctl setenv または plist の EnvironmentVariables で注入し、shell profile と plist の二重管理によるドリフトを避けてください。
04 OpenClaw リモート Gateway ペアリング六段階：Test remote から LaunchAgent 検証まで
- リモートで CLI を入れ Gateway を起動：JEXCLOUD インスタンスで
openclaw gateway install（またはアプリのガイドで LaunchAgent 導入）を実行し、lsof -i :18789が127.0.0.1のみを待受していることを確認します。 - Token の書き込みと検証：Gateway Token を生成し
chmod 600で保存；launchctl setenv OPENCLAW_GATEWAY_TOKEN '…'のあと Gateway Agent を再起動します。 - ローカルで SSH を設定：前節の
LocalForward 18789を~/.ssh/configに書き、ssh -N jex-openclaw-sgを手動実行。別ターミナルでcurl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/healthが 200 であること。 - トンネル LaunchAgent を導入：
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plistを実行し、ログイン後にトンネルが自動起動することを確認します。 - macOS クライアントでペアリング：設定 → OpenClaw runs → Remote + SSH tunnel を選択し
user@hostを入力（config エイリアスなら Host 名のみ可）、Test remote が通るまで実行します。 - 巡回とアラートを登録：Health スクリプトを
StartInterval（推奨 300s）または CI SSH ジョブに組み込み、失敗時はlaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnelと終了コードを on-call 用に記録します。
ペアリング後はアプリ内の onboarding セッションで Agent チャネルを検証できます。CLI のみ動き UI が pending の場合は次節の対照表で調査し、Gateway の再インストールは繰り返さないでください。
05 Health Check 巡回スクリプトと引用可能な技術データ
本番では UI の状態ランプではなくスクリプトで HTTP 200 を断言することを推奨します。以下はレビュー資料に引用可能な項目です（2026 年のコミュニティ実践と JEXCLOUD ノード観測に基く区間で、SLA ではありません）。
- デフォルト Gateway ポート：
18789（LocalForward はこれと一致させる；複数インスタンス時はドキュメントに従い追加ポートを計画）。 - Health エンドポイント：多くは
/healthで Bearer Token が必要；200 以外は監視の終了コードを非ゼロに。 - SSH トンネルの自己修復：LaunchAgent
KeepAlive+ServerAliveInterval 30で切断復旧を 30–90 秒 程度に抑えられることが多い（ネットワーク揺らぎによる）。 - アジア太平洋 RTT：東アジアの開発者が SSH で SG/JP/HK ノードにアクセスすると、CLI 往復は 15–35 ms が一般的；トンネル追加分は通常 < 5 ms で無視可能。
- Token ファイル権限：600 必須；所有者と Gateway プロセスユーザーが不一致だと launchd がサイレントに拒否することがあります。
#!/bin/bash
TOKEN="${OPENCLAW_GATEWAY_TOKEN:?}"
CODE=$(curl -sf -o /dev/null -w '%{http_code}' \
-H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health)
[[ "$CODE" == "200" ]] || exit 106 よくある FAQ、Health pending 対照、JEXCLOUD 選定のまとめ
| 現象 | 優先確認 | 対処 |
|---|---|---|
| CLI 200、UI pending | App キャッシュ、Transport モード、ローカル localhost 転送 | App 再起動；Remote+SSH を確認；Test remote を再実行 |
| pairing / token mismatch | 二重 Token、device token ファイル | plist と App 内 Token を統一；公式 remote gateway ドキュメントでペアリング再設定 |
| Connection refused | トンネルプロセス、ポート占有 | launchctl list | grep openclaw；18789 を確認 |
| トンネルが頻繁に切断 | ノート PC のスリープ、NAT タイムアウト | ServerAlive；トンネル KeepAlive plist；手動 ssh -N のみに依存しない |
家庭用回線や不安定な Wi‑Fiを 7×24 のトンネル入口にすると、NAT タイムアウトとスリープ戦略で「午前は動く、午後は全滅」になりがちです。Gateway を時間課金 VPS やオーバーセル仮想化に置くと、近隣争奪で Health が断続失敗することもあります。ローカル Mac 単体では自動更新再起動、Keychain ダイアログの無人対応も影響します。ローカル App の安定操作、Token の監査可能性、トンネルの自己修復が必要なチームには、Gateway を JEXCLOUD マルチリージョンのベアメタル Mac に置き、SSH ループバック + LaunchAgent 常駐が最も手間の少ない組み合わせであることが多いです：Apple Silicon 専有、約 120 秒デリバリー、プロジェクト単位で並列または M4 Pro へグレード可能。プランとノードは JEXCLOUD 料金ページ；GUI でのトラブルシュートは VNC ページのリモートデスクトップ開通手順と併用できます。