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

このフローにより、macOS アプリは別のホスト（デスクトップ/サーバー）で実行されている OpenClaw ゲートウェイの完全なリモートコントロールとして機能できます。これはアプリの Remote over SSH（リモート実行）機能です。すべての機能—ヘルスチェック、Voice Wake 転送、Web Chat—は、設定 → 一般 の同じリモート SSH 設定を再利用します。

モード

  • Local (this Mac): すべてがラップトップで実行されます。SSH は関与しません。
  • Remote over SSH (default): OpenClaw コマンドはリモートホストで実行されます。Mac アプリは -o BatchMode と選択された ID/キー、およびローカルポートフォワードで SSH 接続を開きます。
  • Remote direct (ws/wss): SSH トンネルなし。Mac アプリはゲートウェイ URL に直接接続します（例: Tailscale Serve または公開 HTTPS リバースプロキシ経由）。

リモートトランスポート

リモートモードは2つのトランスポートをサポートします:

  • SSH tunnel（デフォルト）: ssh -N -L ... を使用してゲートウェイポートを localhost に転送します。トンネルはループバックであるため、ゲートウェイはノードの IP を 127.0.0.1 と見なします。
  • Direct (ws/wss): ゲートウェイ URL に直接接続します。ゲートウェイは実際のクライアント IP を見ます。

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

  1. Node + pnpm をインストールし、OpenClaw CLI をビルド/インストールします（pnpm install && pnpm build && pnpm link --global）。
  2. 非対話型シェルの PATH に openclaw があることを確認します（必要に応じて /usr/local/bin または /opt/homebrew/bin にシンボリックリンク）。
  3. キー認証で SSH を開きます。LAN 外での安定したアクセシビリティのために Tailscale IP を推奨します。

macOS アプリのセットアップ

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

Web Chat

  • SSH tunnel: Web Chat は転送された WebSocket コントロールポート（デフォルト 18789）経由でゲートウェイに接続します。
  • Direct (ws/wss): Web Chat は設定されたゲートウェイ URL に直接接続します。
  • 個別の WebChat HTTP サーバーはもうありません。

パーミッション

  • リモートホストはローカルと同じ TCC 承認が必要です（Automation、Accessibility、Screen Recording、Microphone、Speech Recognition、Notifications）。そのマシンでオンボーディングを実行して一度許可します。
  • ノードは node.list / node.describe 経由でパーミッション状態をアドバタイズするため、エージェントは何が利用可能かを知ることができます。

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

  • リモートホストではループバックバインドを優先し、SSH または Tailscale 経由で接続します。
  • Gateway を非ループバックインターフェースにバインドする場合は、トークン/パスワード認証を要求します。
  • Security と Tailscale を参照してください。

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

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

トラブルシューティング

  • exit 127 / not found: openclaw が非ログインシェルの PATH にありません。/etc/paths、シェル rc に追加するか、/usr/local/bin//opt/homebrew/bin にシンボリックリンクします。
  • Health probe failed: SSH アクセシビリティ、PATH、および Baileys がログインしていることを確認します（openclaw status --json）。
  • Web Chat stuck: ゲートウェイがリモートホストで実行されており、転送されたポートがゲートウェイ WS ポートと一致することを確認します。UI は健全な WS 接続を必要とします。
  • Node IP shows 127.0.0.1: SSH トンネルで予想されます。ゲートウェイが実際のクライアント IP を見るようにするには、Transport を Direct (ws/wss) に切り替えます。
  • Voice Wake: トリガーフレーズはリモートモードで自動的に転送されます。個別のフォワーダーは不要です。

通知音

スクリプトから openclaw と node.invoke を使用して、通知ごとに音を選択します。例:

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

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

← ドキュメントに戻る