​

リモートOpenClaw（macOS ⇄ リモートホスト）

​

モード

• Local（このMac）: すべてがラップトップ上で実行されます。SSHは関与しません。
• Remote over SSH（デフォルト）: OpenClawコマンドはリモートホスト上で実行されます。macアプリは、-o BatchModeと選択したidentity/key、およびローカルポートフォワードを使ってSSH接続を開きます。
• Remote direct（ws/wss）: SSHトンネルは使いません。macアプリはgateway URLへ直接接続します（たとえばTailscale Serveや公開HTTPS reverse proxy経由）。

​

リモート転送

• SSHトンネル（デフォルト）: ssh -N -L ...を使ってgatewayポートをlocalhostへ転送します。トンネルはloopbackなので、gatewayにはノードのIPが127.0.0.1として見えます。
• Direct（ws/wss）: gateway URLへ直接接続します。gatewayには実際のクライアントIPが見えます。

​

リモートホスト側の前提条件

1. Node + pnpmをインストールし、OpenClaw CLIをビルド/インストールする（pnpm install && pnpm build && pnpm link --global）。
2. 非対話シェルでもopenclawがPATH上にあることを確認する（必要に応じて/usr/local/binまたは/opt/homebrew/binへsymlinkする）。
3. キー認証でSSHを開く。LAN外でも安定して到達できるよう、Tailscale IPを推奨します。

​

macOSアプリのセットアップ

1. _Settings → General_を開きます。
2. OpenClaw runsでRemote over SSHを選択し、次を設定します:
   • Transport: SSH tunnelまたはDirect (ws/wss)。
   • SSH target: user@host（任意で:port）。
     • gatewayが同じLAN上にあり、Bonjourを公開している場合は、検出リストから選んでこのフィールドを自動入力できます。
   • Gateway URL（Directのみ）: wss://gateway.example.ts.net（またはローカル/LAN用のws://...）。
   • Identity file（高度な設定）: キーへのパス。
   • Project root（高度な設定）: コマンドに使うリモートcheckoutパス。
   • CLI path（高度な設定）: 実行可能なopenclawエントリポイント/バイナリへの任意のパス（公開されている場合は自動入力される）。
3. Test remoteを押します。成功すれば、リモートのopenclaw status --jsonが正しく実行されていることを意味します。失敗は通常PATH/CLIの問題です。終了コード127はCLIがリモートで見つからないことを意味します。
4. これでヘルスチェックとWeb Chatも自動的にこのSSHトンネル経由で実行されます。

​

Web Chat

• SSHトンネル: Web Chatは転送されたWebSocket control port（デフォルト18789）経由でgatewayへ接続します。
• Direct（ws/wss）: Web Chatは設定済みgateway URLへ直接接続します。
• 独立したWebChat HTTPサーバーはもう存在しません。

​

権限

• リモートホストには、ローカルと同じTCC承認（Automation、Accessibility、Screen Recording、Microphone、Speech Recognition、Notifications）が必要です。そのマシンで一度オンボーディングを実行して付与してください。
• ノードはnode.list / node.describeを介して自分の権限状態を公開するため、エージェントは何が利用可能か把握できます。

​

セキュリティに関する注記

• リモートホストではloopback bindを優先し、SSHまたはTailscale経由で接続してください。
• SSHトンネリングは厳格なhost-key checkingを使用します。まずホストキーを信頼して、~/.ssh/known_hostsに存在するようにしてください。
• Gatewayを非loopbackインターフェースにbindする場合は、有効なGateway認証を必須にしてください: token、password、またはgateway.auth.mode: "trusted-proxy"を使うID認識型reverse proxy。
• SecurityとTailscaleも参照してください。

​

WhatsAppログインフロー（リモート）

• リモートホスト上でopenclaw channels login --verboseを実行します。スマートフォンのWhatsAppでQRをスキャンしてください。
• 認証が期限切れになった場合は、そのホスト上で再度ログインを実行してください。ヘルスチェックにはリンク問題が表示されます。

​

トラブルシューティング

• exit 127 / not found: 非ログインシェルでopenclawがPATH上にありません。/etc/paths、シェルrc、または/usr/local/bin//opt/homebrew/binへのsymlinkで追加してください。
• Health probe failed: SSH到達性、PATH、およびBaileysがログイン済みか（openclaw status --json）を確認してください。
• Web Chatが止まる: gatewayがリモートホスト上で動作しており、転送ポートがgateway WSポートと一致していることを確認してください。UIには正常なWS接続が必要です。
• Node IPが127.0.0.1として表示される: SSHトンネルでは想定どおりです。gatewayに実際のクライアントIPを見せたい場合は、Transportを**Direct (ws/wss)**へ切り替えてください。
• Voice Wake: remoteモードではトリガーフレーズが自動的に転送されます。別個のforwarderは不要です。

​

通知音

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass