2026年 OpenClaw リモート Gateway 接続とペアリングの切り分け実践：gateway.remote、OPENCLAW_GATEWAY_TOKEN と Pairing／Relay エラー意思決定表＋専有リモート Mac の SSH 再現チェックリスト＋FAQ
OpenClaw の制御面と HTTP ゲートウェイが同一ホストにないとき、失敗の多くは三層に分類できます。リモート URL の誤り（gateway.remote）、トークン不一致（OPENCLAW_GATEWAY_TOKEN）、トランスポートの意味論（ペアリング承認と Relay／WebSocket 経路）。本稿では 2026 年向けの切り分け表を runbook に貼れる形で整理し、専有のリモート Mac 向けに SSH で再現可能なチェックリストを示します。初回セットアップの最短手順は 2026年、リモートMac miniでOpenClawを10分で起動（SSH + 最小依存関係） と併せて読むと、ローカル検証からリモート URL への移行が素直です。
TL;DR — 押さえること
- 認証より先に到達性：クライアント側ホストから、
gateway.remoteに書いたベース URL と同じ宛先へcurl -vする。TLS や DNS がここで落ちるならペアリングコードは無関係。 - トークンは単一の真実：
OPENCLAW_GATEWAY_TOKEN（またはドキュメントの秘密参照）を、ゲートウェイセッションを開始するランタイムにだけ揃える——LaunchAgent の plist、シェルプロファイル、CI のシークレット。再起動後に両端で同じリテラルか検証する。 - ペアリングは状態機械：「pending／期限切れ／既にバインド済み」は、時刻ずれ、インストール ID の再利用、同一コードを奪い合う二番目のクライアントなどが典型で、「ネットが悪い」だけではない。
- Relay エラーは経路とプロキシ形状：HTTP ヘルスは通るのにストリームが落ちるときは、企業プロキシによる WebSocket 阻害やトンネル縁の二重 TLS 終端を疑う。
専有ノード上のビルド体感を数値で押さえたい場合は 2026年Macレンタル Xcodeビルド実測：ビルド時間はどれくらい？ も参照してください。
1. 心のモデル：ローカルエージェントとリモートゲートウェイ
スタックを二つの協調プロセスとして扱います。（A）Apple 専用ツールを持つ macOS 側ワーカー、（B）クライアント向けに HTTP／WebSocket 面を出すゲートウェイ。（B）がリモートのとき、Mac は実質バックエンドノードであり、SSH トンネル、Tailscale、Cloudflare Tunnel など制御された入口越しに外向きダイアルするか、到達可能にする必要があります。gateway.remote は（B）の安定アドレスを指す設定キーに過ぎず、ネットワーク方針や TLS 信頼の代替にはなりません。
専有リモート Mac は、キーチェーン、Xcode パス、CPU／ディスクのノイジーネイバー排除を決定的にしたいときに有利です。その代わり、到達性と秘密配布を最後まで自分で持ちます。
2. gateway.remote と OPENCLAW_GATEWAY_TOKEN — 設定の意思決定表
ログが曖昧でも、どちらのホストがクライアントでどちらがゲートウェイか分かっているときに使います。
| 目的 | 設定／検証 | よくある誤り |
|---|---|---|
| LAN 内の別ホストにゲートウェイ | gateway.remote = https://10.x.x.x:PORT（または LAN DNS 上の HTTPS ホスト名） |
LAN 内では別解像度になるパブリックホスト名（スプリット DNS の罠） |
| リバーストンネル背後のゲートウェイ | URL はトンネル正面のドメインと一致、証明書 SAN もそのホスト名に合わせる | Mac 上のヘルスは 127.0.0.1 なのに gateway.remote が古い DNS のまま |
| ゲートウェイセッションの認証 | ゲートウェイ環境とクライアント環境で同一リテラル：OPENCLAW_GATEWAY_TOKEN |
対話シェルにはあるが LaunchAgent の EnvironmentVariables にない |
| 資格情報の安全なローテーション | 先にゲートウェイを更新して再起動し、その後クライアントを順に巻き替え（重複許容があればオーバーラップ） | 片側だけ再起動——新トークンを拾ったのは一方だけ |
3. ペアリングと Relay — 症状 → 疑う層 → 最初の一手
| 症状 | 疑う層 | 最初の一手 |
|---|---|---|
| 接続直後に 401／403 | トークンまたは認証ミドルウェア | 実行中サービスから実効環境を取得（端末の表示ではない）。ゲートウェイログの「bad token」と突き合わせる。 |
| ペアリングコードが見つからない／期限切れ | ペアリング状態／時刻 | 両ホストで NTP を確認。古い UI コードの再利用をやめる。製品がサポートすれば古いペアリングを失効。 |
| HTTP 200 のあとストリーム切断、「relay」再試行 | WebSocket／プロキシ／アイドルタイムアウト | 同一経路で wscat 等を試す。keepalive を上げる。トンネルのアイドル上限を確認。 |
| リモートクライアントからだけ TLS ハンドシェイク失敗 | 証明書チェーンまたは SNI | クライアント側ネットから openssl s_client -connect host:443 -servername host |
| Wi-Fi では動くが VPN では失敗 | スプリットトンネル／DNS | Mac でゲートウェイホスト名の解決を比較（dig／scutil --dns） |
4. 専有リモート Mac — SSH で再現可能なチェックリスト
専用リモート Mac（共有 GUI ユーザーなし）で、チームが同じ順序を踏めるようにします。
- SSH 基盤：公開鍵認証、
AllowUsersの限定、必要ならMatch UserとChrootDirectory（開発ツールで Xcode パスを壊さないこと）。 - ローカルゲートウェイ断片の確認（ある場合）：
curl -sf http://127.0.0.1:PORT/healthまたはドキュメントのプローブ。 - リモート URL の証明：Mac 上から
gateway.remoteと同じ scheme／host のcurl -v "$GATEWAY_URL"。 - launchd 向けに環境を固定：
OPENCLAW_GATEWAY_TOKENとリモート URL を LaunchAgent plist にミラー。launchctl bootout／bootstrapは既存の OpenClaw 手順に合わせる。 - ログを一度キャプチャ：stderr／stdout をローテーション付きファイルへ、または組織で合意した
log stream述語——ペアリングと Relay を PII なしで区別できる程度。 - ロールバックスイッチ：密封されたシークレット管理に既知良好な旧トークンを残し、二段階（ゲートウェイ → クライアント）で戻す手順を文書化。
5. FAQ
ペアリングフローと長寿命トークンの両方が必要か
多くの構成ではその通りです。ペアリングはデバイスやインストール ID への信頼のブートストラップ、OPENCLAW_GATEWAY_TOKEN（類似物）は日常の API 呼び出しの認証です。トークンを回すと、製品ドキュメントに従い再ペアリングまたは再登録が必要になることがあります。
Relay エラーが直結 Ethernet だけで消える理由
コンシューマ向け Wi-Fi やゲストネットでは長寿命 WebSocket を落としたりキャプティブポータルを挟むことがあります。Ethernet や WebSocket を明示許可した企業 VPN ではその変数が消えます——A／B で切り分けてください。
gateway.remote を SSH -L 越しの localhost に向けられるか
可能です。Mac 上の OpenClaw プロセスがその URL を転送ポートに解決できる必要があります。127.0.0.1 を明示し、複数トンネルで衝突しないローカルポートを runbook に書いてください。
6. ゲートウェイ縁を Mac mini で載せる理由
リモートゲートウェイの切り分けは、安定したネットワーク、信頼できる時刻、長時間デーモンに尽きます。Apple Silicon の Mac mini は待機電力が非常に低く、静音で、macOS の Gatekeeper、SIP、FileVault を使えば、常時稼働の汎用 Windows ユーティリティホストに比べ運用上の攻撃面を小さくしやすいです。ネイティブ OpenSSH、Homebrew の TLS ツール、予測しやすい Xcode パスにより、Apple 中心の自動化では専有リモート Mac パターンのサポートコストが下がります。
ペアリング、Relay、トークンローテーションを製品作業に集中しながら維持したいなら、Mac mini M4 は実用的なアンカーになります。下の CTA から、Tailnet やトンネル設計に合うプランをホームで比較してください。