OpenClaw macOS IPCアーキテクチャ

現在のモデル： ローカルUnixソケットがノードホストサービスとmacOSアプリを接続し、実行承認とsystem.runを処理します。openclaw-macデバッグCLIはディスカバリ/接続チェック用に存在します。エージェントアクションはGateway WebSocketとnode.invoke経由で流れます。UI自動化にはPeekabooBridgeを使用します。

目標

  • TCC関連のすべての作業（通知、画面収録、マイク、音声認識、AppleScript）を担う単一のGUIアプリインスタンス。
  • 自動化のための小さなサーフェス：Gateway + ノードコマンド、UI自動化にはPeekabooBridge。
  • 予測可能なパーミッション：常に同じ署名済みバンドルID、launchdで起動されるため、TCC付与が維持される。

仕組み

Gateway + ノードトランスポート

  • アプリはGateway（ローカルモード）を実行し、ノードとして接続。
  • エージェントアクションはnode.invoke経由で実行（例：system.run、system.notify、canvas.*）。

ノードサービス + アプリIPC

  • ヘッドレスノードホストサービスがGateway WebSocketに接続。
  • system.runリクエストはローカルUnixソケット経由でmacOSアプリに転送。
  • アプリはUIコンテキストで実行し、必要に応じてプロンプトを表示し、出力を返す。

図解（SCI）：

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

PeekabooBridge（UI自動化）

  • UI自動化はbridge.sockという名前の別のUNIXソケットとPeekabooBridge JSONプロトコルを使用。
  • ホスト優先順位（クライアント側）：Peekaboo.app → Claude.app → OpenClaw.app → ローカル実行。
  • セキュリティ：ブリッジホストは許可されたTeamIDを要求。DEBUGのみの同一UIDエスケープハッチはPEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1で保護（Peekabooの規約）。
  • 詳細はPeekabooBridgeの使い方を参照。

運用フロー

  • 再起動/リビルド：SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • 既存インスタンスを終了
    • Swiftビルド＋パッケージ化
    • LaunchAgentの書き込み/ブートストラップ/キックスタート
  • 単一インスタンス：同じバンドルIDの別インスタンスが稼働中の場合、アプリは早期終了。

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

  • すべての特権サーフェスにTeamIDマッチを要求することを推奨。
  • PeekabooBridge：PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1（DEBUGのみ）はローカル開発用に同一UIDの呼び出し元を許可する場合がある。
  • すべての通信はローカルのみ。ネットワークソケットは公開されない。
  • TCCプロンプトはGUIアプリバンドルからのみ発生。リビルド間で署名済みバンドルIDを安定に保つこと。
  • IPC強化：ソケットモード0600、トークン、ピアUID検証、HMACチャレンジ/レスポンス、短いTTL。
arrow_back
前へ
Bundled Gateway
次へ
Skills
arrow_forward