リモートアクセス

• オペレーター（ユーザーまたは macOS アプリ）: Gateway に到達できる場合は、LAN/Tailnet WebSocket への直接接続が最も簡単です。SSH トンネリングは汎用的なフォールバックです。
• Node（iOS/Android およびその他のデバイス）: Gateway の WebSocket（LAN/tailnet または SSH トンネル）に接続します。

​

基本的な考え方

​

トポロジーの選択肢

​

コマンドフロー（どこで何が実行されるか）

1. Telegram メッセージが Gateway に到着します。
2. Gateway が エージェントを実行し、Node ツールを呼び出すかどうかを判断します。
3. Gateway が Gateway WebSocket（node.invoke RPC）経由で Node を呼び出します。
4. Node が結果を返し、Gateway が Telegram に返信します。

​

SSH トンネル（CLI + ツール）

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

​

CLI のリモートデフォルト

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

​

認証情報の優先順位

• 明示的な認証情報（--token、--password、またはツールの gatewayToken）は、明示的な認証を受け付ける呼び出しパスでは常に優先されます。
• URL オーバーライドの安全性:
  • CLI の --url は、暗黙的な設定または環境の認証情報を再利用しません。
  • 環境の OPENCLAW_GATEWAY_URL は、環境の認証情報（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）のみを使用できます。
• ローカルモードのデフォルト:
  • トークン: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token（ローカルトークンが未設定の場合のみリモートへフォールバック）
  • パスワード: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password（ローカルパスワードが未設定の場合のみリモートへフォールバック）
• リモートモードのデフォルト:
  • トークン: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • パスワード: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Node ホストのローカルモードの例外: gateway.remote.token / gateway.remote.password は無視されます。
• リモートのプローブ/ステータスにおけるトークン確認は、デフォルトで厳格です。リモートモードを接続先とする場合は、gateway.remote.token のみを使用します（ローカルトークンへのフォールバックはありません）。
• Gateway の環境オーバーライドは、OPENCLAW_GATEWAY_* のみを使用します。

​

Chat UI のリモートアクセス

• SSH 経由で 18789 を転送し（前述を参照）、クライアントを ws://127.0.0.1:18789 に接続します。
• LAN/Tailnet の直接モードでは、設定済みのプライベート ws:// またはセキュアな wss:// URL にクライアントを接続します。
• macOS では、アプリのリモートモードが選択されたトランスポートを自動的に管理します。

​

macOS アプリのリモートモード

​

セキュリティルール（リモート/VPN）

• ループバック + SSH/Tailscale Serve が最も安全なデフォルトです（公開されません）。
• 平文の ws:// は、ループバック、プライベート/LAN（RFC 1918）、リンクローカル、CGNAT、.local、.ts.net のホストで許可されます。公開リモートホストでは wss:// を使用する必要があります。
• 非ループバックバインド（lan/tailnet/custom、またはループバックが利用できない場合の auto）では、Gateway 認証（トークン、パスワード、または gateway.auth.mode: "trusted-proxy" を設定した ID 対応リバースプロキシ）を使用する必要があります。
• gateway.remote.token / .password はクライアント認証情報のソースです。それだけではサーバー認証を設定しません。
• ローカル呼び出しパスでは、gateway.auth.* が未設定の場合にのみ、gateway.remote.* をフォールバックとして使用できます。
• gateway.auth.token / gateway.auth.password が SecretRef で明示的に設定されているにもかかわらず解決できない場合、解決はフェイルクローズします（リモートフォールバックによる隠蔽はありません）。
• gateway.remote.tlsFingerprint は、wss:// のリモート TLS 証明書を固定します。これには、オペレーター/制御トラフィックと、macOS の直接モードにおけるコンパニオン Node の両方が含まれます。保存済みのピンがない場合、macOS は通常のシステム信頼検証に合格した後にのみ初回使用時に固定します。自己署名またはプライベート CA の Gateway では、明示的なフィンガープリントまたは SSH 経由のリモート接続が必要です。
• __Tailscale Serve** は、gateway.auth.allowTailscale: true の場合、ID ヘッダーを介して Control UI/WebSocket トラフィックを認証できます。HTTP API エンドポイントではこのヘッダー認証を使用せず、代わりに Gateway の通常の HTTP 認証モードに従います。このトークンレスフローでは Gateway ホストが信頼されていることを前提とします。すべての接続で共有シークレット認証を使用するには、これを false に設定します。
• 信頼済みプロキシ認証は、デフォルトで非ループバックの ID 対応プロキシを想定します。同一ホストのループバックリバースプロキシでは、gateway.auth.trustedProxy.allowLoopback = true を明示的に設定する必要があります。
• ブラウザーによる制御はオペレーターアクセスと同等に扱ってください。tailnet のみに制限し、Node のペアリングを意図的に行います。

​

macOS: LaunchAgent による永続的な SSH トンネル

​

ステップ 1: SSH 設定を追加する

Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

​

ステップ 2: SSH キーをコピーする（初回のみ）

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

​

ステップ 3: Gateway トークンを設定する

openclaw config set gateway.remote.token "<your-token>"

​

ステップ 4: LaunchAgent を作成する

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

​

ステップ 5: LaunchAgent を読み込む

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

​

トラブルシューティング

# トンネルが実行中か確認する
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

# トンネルを再起動する
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

# トンネルを停止する
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

​

関連項目

• Tailscale
• 認証
• リモート Gateway のセットアップ