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

このフローでは、macOSアプリが別のホスト（デスクトップ/サーバー）で稼働しているOpenClaw Gatewayのフルリモート制御として機能します。アプリのRemote over SSH（リモート実行）機能です。ヘルスチェック、Voice Wake転送、Web Chatなど、すべての機能が_設定 → General_の同じリモートSSH設定を再利用します。

モード

Local (this Mac)：すべてがノートPC上で動作。SSHは不要。
Remote over SSH（デフォルト）：OpenClawコマンドはリモートホスト上で実行。macアプリは-o BatchModeと選択したID/キー、ローカルポートフォワードを使用してSSH接続を確立。
Remote direct (ws/wss)：SSHトンネルなし。macアプリがGateway URLに直接接続（例：Tailscale ServeやパブリックHTTPSリバースプロキシ経由）。

リモートトランスポート

リモートモードは2つのトランスポートをサポート：

SSHトンネル（デフォルト）：ssh -N -L ...でGatewayポートをlocalhostに転送。トンネルがループバックのため、GatewayにはノードIPが127.0.0.1として表示。
Direct (ws/wss)：Gateway URLに直接接続。Gatewayには実際のクライアントIPが表示。

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

Node + pnpmをインストールし、OpenClaw CLIをビルド/インストール（pnpm install && pnpm build && pnpm link --global）。
openclawが非インタラクティブシェルのPATH上にあることを確認（必要に応じて/usr/local/binや/opt/homebrew/binにシンボリックリンク）。
SSH鍵認証を開放。LAN外での安定した到達性にはTailscale IPを推奨。

macOSアプリの設定

_設定 → General_を開く。
OpenClaw runsでRemote over SSHを選択し、以下を設定：
- Transport：SSHトンネルまたは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（詳細）：コマンドに使用されるリモートチェックアウトパス。
- CLI path（詳細）：実行可能なopenclawエントリポイント/バイナリのパス（アドバタイズ時に自動入力）。
Test remoteを押す。成功はリモートのopenclaw status --jsonが正しく実行されたことを示す。失敗は通常PATH/CLIの問題。exit 127はCLIがリモートで見つからないことを意味。
ヘルスチェックとWeb Chatは自動的にこのSSHトンネル経由で実行。

Web Chat

SSHトンネル：Web Chatは転送されたWebSocketコントロールポート（デフォルト18789）経由でGatewayに接続。
Direct (ws/wss)：Web Chatは設定済みのGateway URLに直接接続。
別のWebChat HTTPサーバーは存在しません。

パーミッション

リモートホストもローカルと同じTCC承認が必要（Automation、Accessibility、画面収録、マイク、音声認識、通知）。そのマシンでオンボーディングを実行して一度付与してください。
ノードはnode.list / node.describe経由でパーミッション状態をアドバタイズするため、エージェントは利用可能な機能を把握できます。

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

リモートホストではループバックバインドを推奨し、SSHまたはTailscale経由で接続。
SSHトンネリングは厳密なホストキーチェックを使用。~/.ssh/known_hostsにホストキーが存在するよう事前に信頼してください。
Gatewayを非ループバックインターフェースにバインドする場合は、トークン/パスワード認証を必須に。
セキュリティとTailscaleを参照。

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

リモートホスト上でopenclaw channels login --verboseを実行。WhatsAppアプリでQRコードをスキャン。
認証が期限切れになったらそのホストで再度ログイン。ヘルスチェックがリンクの問題を報告。

トラブルシューティング

exit 127 / not found：非ログインシェルでのopenclawがPATHにない。/etc/paths、シェルrcに追加するか、/usr/local/bin//opt/homebrew/binにシンボリックリンクを作成。
ヘルスプローブ失敗：SSHの到達性、PATH、Baileysのログイン状態（openclaw status --json）を確認。
Web Chatが固まる：リモートホストでGatewayが稼働中で、転送ポートがGateway WSポートと一致することを確認。UIは健全なWS接続が必要。
ノードIPが127.0.0.1と表示：SSHトンネルでは想定通り。Gatewayに実際のクライアントIPを表示させたい場合はTransportを**Direct (ws/wss)**に切り替え。
Voice Wake：トリガーフレーズはリモートモードで自動転送。別途フォワーダーは不要。

通知サウンド

スクリプトからopenclawとnode.invokeで通知ごとにサウンドを選択できます：

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

アプリにグローバルな「デフォルトサウンド」トグルはありません。呼び出し元がリクエストごとにサウンド（またはなし）を選択します。