OpenClaw macOS IPC アーキテクチャの解説

macOS で自動化ツールを開発していると、アクセシビリティや画面収録などの権限（TCC）が頻繁にリセットされてしまう問題に直面することがあります。ビルドのたびにシステム設定を開いて権限を許可し直す作業は、開発の大きな妨げになります。

OpenClaw は、このパーミッション管理を安定させ、効率的にツールを実行するための IPC アーキテクチャを採用しています。

必要なもの

• Gateway (Local mode)
• Node host service
• Apple Development 署名用の ID
• scripts/restart-mac.sh

クイックスタート

OpenClaw を macOS 上でセットアップし、実行するための最短手順は以下の通りです。

1. 環境変数の設定とスクリプトの実行 ターミナルで以下のコマンドを実行して、アプリケーションをビルドし、LaunchAgent を登録します。

   SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh

2. プロセスの確認 このスクリプトは、既存のインスタンスを終了させた後、Swift ビルドとパッケージングを行い、LaunchAgent を起動します。

3. IPC の疎通確認 openclaw-mac デバッグ CLI を使用して、接続状態を確認できます。

4. 自動化の実行 Gateway 経由で node.invoke を呼び出すことで、system.run などのアクションが実行されます。

アーキテクチャの仕組み

OpenClaw は、権限が必要な処理を単一の GUI アプリに集約することで、TCC の許可を安定させています。

Gateway と Node の通信

アプリケーションはローカルモードで Gateway を実行し、自身も Node として接続します。エージェントのアクション（system.run, system.notify, canvas.* など）は、node.invoke を介して実行されます。

Node service とアプリ間の IPC

ヘッドレスな Node host service が Gateway の WebSocket に接続します。system.run のリクエストは、ローカル Unix socket を通じて macOS アプリに転送されます。アプリは UI コンテキストで実行し、必要に応じてユーザーにプロンプトを表示した後、出力を返します。

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

UI 自動化 (PeekabooBridge)

UI の自動化には、bridge.sock という名前の専用 UNIX socket と PeekabooBridge JSON プロトコルを使用します。クライアント側でのホスト優先順位は、Peekaboo.app → Claude.app → OpenClaw.app → ローカル実行の順です。

トラブルシューティング

• アプリがすぐに終了してしまう場合 OpenClaw は単一インスタンス設計です。同じ bundle ID を持つ別のインスタンスが既に動作している場合、新しいインスタンスは早期終了します。

• 開発中に署名なしクライアントから接続したい場合 DEBUG ビルドに限り、PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 を設定することで、同じ UID の呼び出し元からの接続を許可できます。

• 通信の安全性を確保したい場合 IPC は socket mode 0600、トークン、HMAC チャレンジ/レスポンス、短い TTL によって保護されています。すべての通信はローカルのみで行われ、ネットワーク socket は公開されません。

不明な点がある場合は、AI Setup Assistant を活用してください。

次のステップ

• PeekabooBridge usage