リモートアクセス

• オペレーター（あなた、または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）は、明示的な認証を受け付けるcallパスでは常に優先されます。
• URLオーバーライドの安全性:
  • CLI --urlは暗黙の設定/環境認証情報を再利用しません。
  • Env OPENCLAW_GATEWAY_URLは環境認証情報のみ（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）を使用できます。
• ローカルモードのデフォルト:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token（ローカルトークンが未設定の場合のみリモートフォールバック）
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password（ローカルパスワードが未設定の場合のみリモートフォールバック）
• リモートモードのデフォルト:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Node-hostのローカルモード例外: gateway.remote.token / gateway.remote.passwordは無視されます。
• リモートprobe/statusのトークンチェックはデフォルトで厳格です。リモートモードを対象にする場合、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はクライアント認証情報ソースです。それだけではサーバー認証を設定しません。
• ローカルcallパスは、gateway.auth.*が未設定の場合のみgateway.remote.*をフォールバックとして使用できます。
• gateway.auth.token / gateway.auth.passwordがSecretRefで明示的に設定されていて解決できない場合、解決はフェイルクローズします（リモートフォールバックで隠蔽しません）。
• gateway.remote.tlsFingerprintは、macOS直接モードを含め、wss://のリモートTLS証明書をピン留めします。保存済みピンがない場合、macOSは通常のシステム信頼が通った後の初回使用時にのみピン留めします。自己署名またはプライベートCAのGatewayには、明示的なフィンガープリントまたはSSH経由のRemoteが必要です。
• Tailscale Serveは、gateway.auth.allowTailscale: trueの場合、IDヘッダー経由でControl UI/WebSocketトラフィックを認証できます。HTTP APIエンドポイントはそのヘッダー認証を使用せず、代わりにGatewayの通常のHTTP認証モードに従います。このトークンレスフローはGatewayホストが信頼されていることを前提にします。共有シークレット認証を全体で使う場合はfalseに設定してください。
• Trusted-proxy認証は、デフォルトで非ループバックの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キーをコピーする（1回のみ）

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

​

トラブルシューティング

# Check if the tunnel is running
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

# Restart the tunnel
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

# Stop the tunnel
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

​

関連

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