macOS アプリ

macOS アプリは OpenClaw の メニューバーコンパニオン です。権限を処理し、ローカル Gateway（launchd または手動）を管理/接続し、ノードとして macOS の機能を Agent に公開します。

- メニューバーにネイティブ通知とステータスを表示します。

- TCC 認証プロンプトを処理します（通知、アクセシビリティ、画面録画、マイク、音声認識、自動化/AppleScript）。

- Gateway（ローカルまたはリモート）を実行または接続します。

- macOS 固有のツール（Canvas、Camera、Screen Recording、''system.run''）を公開します。

- リモート モードでローカルノードホストサービス（launchd）を起動し、ローカル モードで停止します。

- UI 自動化のために PeekabooBridge をオプションでホストします。

- 必要に応じて npm/pnpm 経由でグローバル CLI（''openclaw''）をインストールします（Gateway ランタイムとして bun の使用は推奨されません）。

- ''ローカル（デフォルト）''：実行中のローカル Gateway が検出された場合、直接接続します。それ以外の場合は ''openclaw gateway install'' 経由で launchd サービスを有効にします。

- リモート：アプリは SSH/Tailscale 経由でリモート Gateway に接続し、ローカルで gateway プロセスを起動しません。

このモードでは、アプリはローカルの ノードホストサービス を起動し、リモート Gateway がこの Mac に接続できるようにします。

アプリは Gateway をサブプロセスとして起動しません。

アプリはラベル ''bot.molt.gateway'' のユーザーごとの LaunchAgent を管理します

(''bot.molt.<profile>'' when using ''--profile''/''OPENCLAW_PROFILE''; legacy ''com.openclaw.*'' will be uninstalled).

If using a named profile, replace the label with ''bot.molt.<profile>''.

LaunchAgent がインストールされていない場合は、アプリ内で有効にするか、''openclaw gateway install'' を実行できます。

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

PlatformsMacosPage step 03: P5

PlatformsMacosPage step 03: P6

macOS アプリはノードとして接続します。一般的なコマンド：

- Canvas：''canvas.present''、''canvas.navigate''、''canvas.eval''、''canvas.snapshot''、''canvas.a2ui.*''

- Camera：''camera.snap''、''camera.clip''

- Screen：''screen.record''

- System：''system.run''、''system.notify''

ノードは ''permissions'' マップを報告し、Agent がどの機能が許可されているかを判断できるようにします。

ノードサービスとアプリ IPC：

- ヘッドレスノードホストサービスが実行されている場合（リモートモード）、WS 経由でノードとして Gateway に接続します。

- ''system.run'' は macOS アプリ内（UI/TCC コンテキスト）で実行され、ローカル Unix ソケット経由でアプリと通信します。プロンプトと出力はアプリ内に残ります。

Diagram (SCI):

''system.run'' は macOS アプリの ''Exec approvals'' によって制御されます（Settings → Exec approvals）。セキュリティポリシー、確認ポリシー、許可リストはローカルに保存されます：

~/.openclaw/exec-approvals.json

Example:

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

Notes:

- ''allowlist'' エントリは、解決された実行可能ファイルパスに対する glob 一致です。

- プロンプトで「常に許可」を選択すると、そのコマンドが許可リストに追加されます。

''system.run'' の環境変数オーバーライドはフィルタリングされ（''PATH''、''DYLD_*''、''LD_*''、''NODE_OPTIONS''、''PYTHON*''、''PERL*''、''RUBYOPT'' を破棄）、アプリ環境とマージされます。

アプリはローカルアクションのために ''openclaw://'' URL スキームを登録します。

#

Gateway ''agent'' リクエストをトリガーします：

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

クエリパラメータ：

- ''message'' (required)

- ''sessionKey''（オプション）

- ''thinking''（オプション）

- ''deliver'' / ''to'' / ''channel''（オプション）

- ''timeoutSeconds''（オプション）

- ''key''（オプション：無人モードキー）

セキュリティ：

- ''key'' がない場合、アプリは確認ダイアログを表示します。

- 有効な ''key'' がある場合、無人で実行されます（個人用自動化向け）。

1. OpenClaw.app をインストールして起動します。

2. 権限チェックリストを完了します（TCC 認証プロンプト）。

3. ローカルモードが有効で、Gateway が実行中であることを確認します。

4. 端末アクセスが必要な場合は、CLI をインストールします。

- ''cd apps/macos && swift build''

- ''swift run OpenClaw''（または Xcode を使用）

- パッケージ化：''scripts/package-mac-app.sh''

デバッグ CLI を使用して、macOS アプリで使用される Gateway WebSocket ハンドシェイクと検出ロジックをアプリを起動せずに再現します：

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

Connect パラメータ：

- ''--url <ws://host:port>'': override config

- ''--mode <local|remote>'': resolve from config (default: per-config or local)

- ''--probe''：新しい健全性プローブを強制

- ''--timeout <ms>'': request timeout (default ''15000'')

- ''--json''：diff 用の構造化出力

Discovery パラメータ：

- ''--include-local''：それ以外の場合は「ローカル」としてフィルタリングされる gateways を含める

- ''--timeout <ms>'': overall discovery window (default ''2000'')

- ''--json'': structured output

ヒント：''openclaw gateway discover --json'' と比較して、macOS アプリの検出パイプライン（NWBrowser + tailnet DNS‑SD フォールバック）が Node CLI の ''dns-sd'' 検出と異なるかどうかを確認できます。

macOS アプリが リモート モードで実行されている場合、ローカル UI コンポーネントがリモート Gateway に localhost としてアクセスできるように SSH トンネルを開きます。

#

- 目的： 健全性チェック、ステータス、Web Chat、設定、その他のコントロールプレーン呼び出し

- ''ローカルポート：'' Gateway ポート（デフォルト ''18789''）、固定

- リモートポート： リモートホスト上の同じ Gateway ポート

- 動作： ランダムなローカルポートを使用しません。アプリは健全なトンネルを再利用するか、必要に応じて再起動します

- ''SSH form:'' ''ssh -N -L <local>:127.0.0.1:<remote>'', with BatchMode, ExitOnForwardFailure, keepalive enabled

- ''IP 観測：'' SSH トンネルはループバック経由で行われるため、gateway はノード IP を ''127.0.0.1'' として認識します。実際のクライアント IP を表示したい場合は、''Direct（ws/wss）'' トランスポートを使用してください（''macOS remote access'' を参照）。

設定手順については ''macOS remote access'' を参照してください。プロトコルの詳細については ''Gateway protocol'' を参照してください。

- ''Gateway runbook''

- ''Gateway（macOS）''

- ''macOS permissions''

- ''Canvas''