​

OpenClaw macOS コンパニオン（メニューバー + ゲートウェイブローカー）

​

何を行うか

• ネイティブ通知とステータスをメニューバーに表示します。
• TCC プロンプト（通知、アクセシビリティ、画面収録、マイク、音声認識、オートメーション / AppleScript）を管理します。
• Gateway（ローカルまたはリモート）を実行または接続します。
• macOS 専用ツール（Canvas、Camera、Screen Recording、system.run）を公開します。
• ローカルノードホストサービスを remote モード（launchd）で起動し、local モードでは停止します。
• UI 自動化のために PeekabooBridge を任意でホストします。
• 要求に応じて npm / pnpm 経由でグローバル CLI（openclaw）をインストールします（Gateway ランタイムには bun は推奨されません）。

​

ローカル vs リモート モード

• Local（デフォルト）: 実行中のローカル Gateway があれば接続します。存在しない場合は、openclaw gateway install を介して launchd サービスを有効化します。
• リモート: アプリは SSH / Tailscale でゲートウェイに接続し、ローカルプロセスの を起動しません。 リモート: アプリは SSH / Tailscale でゲートウェイに接続し、ローカルプロセスの を起動しません。 Remote: SSH / Tailscale 経由で Gateway に接続し、ローカルプロセスは起動しません。
  リモート Gateway からこの Mac に到達できるよう、ローカルの ノードホストサービスを起動します。
  アプリは Gateway を子プロセスとして起動しません。 このアプリは子プロセスとして Gateway を生成しません。 このアプリは子プロセスとして Gateway を生成しません。

​

launchd の制御

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

​

ノード機能（mac）

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: camera.snap, camera.clip
• Screen: screen.record
• System: system.run, system.notify

• ヘッドレスのノードホストサービスが実行中（remote モード）の場合、ノードとして Gateway の WS に接続します。
• system.run は、ローカルの Unix ソケット越しに macOS アプリ（UI / TCC コンテキスト）内で実行されます。プロンプトと出力はアプリ内に留まります。

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

​

実行承認（system.run）

~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

• allowlist エントリは、解決済みバイナリパスに対するグロブパターンです。
• プロンプトで「常に許可」を選択すると、そのコマンドが許可リストに追加されます。
• system.run の環境変数オーバーライドはフィルタリング（PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT を除外）された後、アプリの環境とマージされます。

​

ディープ リンク

​

openclaw://agent

open 'openclaw://agent?message=Hello%20from%20deep%20link'

• message（必須）
• sessionKey（任意）
• thinking（任意）
• deliver / to / channel（任意）
• timeoutSeconds（任意）
• key（無人モード用キー、任意）

• key がない場合、アプリは確認を求めます。
• key がない場合、アプリは確認プロンプトのメッセージ長を短く制限し、deliver / to / channel を無視します。
• 有効な key がある場合、実行は無人になります（個人用自動化を想定）。

​

オンボーディング フロー（一般的）

1. OpenClaw.app をインストールして起動します。
2. 権限チェックリスト（TCC プロンプト）を完了します。
3. Local モードが有効で、Gateway が実行中であることを確認します。
4. ターミナルから利用したい場合は、CLI をインストールします。

​

ビルド & 開発ワークフロー（ネイティブ）

• cd apps/macos && swift build
• swift run OpenClaw（または Xcode）
• アプリのパッケージ化: scripts/package-mac-app.sh

​

Gateway 接続のデバッグ（macOS CLI）

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

• --url <ws://host:port>: 設定を上書き
• --mode <local|remote>: 設定から解決（デフォルト: 設定またはローカル）
• --probe: 新規のヘルスプローブを強制
• --timeout <ms>: リクエスト タイムアウト（デフォルト: 15000）
• --json: 差分比較用の構造化出力

• --include-local: 「local」としてフィルタリングされる Gateway を含める
• --timeout <ms>: 全体の検出ウィンドウ（デフォルト: 2000）
• --json: 差分比較用の構造化出力

​

リモート接続の配管（SSH トンネル）

​

コントロール トンネル（Gateway WebSocket ポート）

• 目的: ヘルスチェック、ステータス、Web Chat、設定、その他のコントロールプレーン呼び出し。
• ローカル ポート: Gateway ポート（デフォルト 18789）。常に固定です。
• リモート ポート: リモート ホスト上の同一 Gateway ポート。
• 挙動: ランダムなローカル ポートは使用しません。既存の健全なトンネルを再利用し、必要に応じて再起動します。
• SSH 形態: BatchMode + ExitOnForwardFailure + keepalive オプション付きの ssh -N -L <local>:127.0.0.1:<remote>。
• IP レポート: SSH トンネルはループバックを使用するため、Gateway から見えるノード IP は 127.0.0.1 になります。実際のクライアント IP を表示したい場合は、Direct (ws/wss) トランスポートを使用してください（macOS remote access を参照）。 実際のクライアント IP を表示させたい場合は、Direct (ws/wss) を使用してください (macOS リモート アクセスを参照してください)。 実際のクライアント IP を表示させたい場合は、Direct (ws/wss) を使用してください (macOS リモート アクセスを参照してください)。

​

関連ドキュメント

• Gateway runbook
• Gateway（macOS）
• macOS permissions
• Canvas