macOS companion app

macOS IPC

Архітектура IPC OpenClaw для macOS

Поточна модель: локальний Unix-сокет з’єднує хост-службу node з застосунком macOS для схвалень exec + system.run. Існує налагоджувальний CLI openclaw-mac для перевірок виявлення/підключення; дії агента й надалі проходять через WebSocket Gateway і node.invoke. Автоматизація UI використовує PeekabooBridge.

Цілі

Єдиний екземпляр GUI-застосунку, який володіє всією роботою, пов’язаною з TCC (сповіщення, запис екрана, мікрофон, мовлення, AppleScript).
Невелика поверхня для автоматизації: Gateway + команди node, а також PeekabooBridge для автоматизації UI.
Передбачувані дозволи: завжди той самий підписаний bundle ID, запущений через launchd, тому дозволи TCC зберігаються.

Як це працює

Gateway + транспорт node

Застосунок запускає Gateway (локальний режим) і підключається до нього як node.
Дії агента виконуються через node.invoke (наприклад, system.run, system.notify, canvas.*).
Поширені команди Mac node включають canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, system.run і system.notify.
Node повідомляє мапу permissions, щоб агенти могли бачити, чи доступний доступ до екрана, камери, мікрофона, мовлення, автоматизації або спеціальних можливостей.

Служба node + IPC застосунку

Безголова хост-служба node підключається до WebSocket Gateway.
Запити system.run пересилаються до застосунку macOS через локальний Unix-сокет.
Застосунок виконує exec у контексті UI, за потреби показує запит і повертає вивід.

Діаграма (SCI):

Code

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

PeekabooBridge (автоматизація UI)

Автоматизація UI використовує окремий UNIX-сокет із назвою bridge.sock і JSON-протокол PeekabooBridge.
Порядок пріоритету хостів (на стороні клієнта): Peekaboo.app → Claude.app → OpenClaw.app → локальне виконання.
Безпека: хости bridge вимагають дозволений TeamID; аварійний вихід лише для DEBUG з тим самим UID захищено змінною PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (конвенція Peekaboo).
Див.: Використання PeekabooBridge для деталей.

Операційні потоки

Перезапуск/перезбирання: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
- Завершує наявні екземпляри
- Swift build + package
- Записує/бутстрапить/запускає LaunchAgent через kickstart
Єдиний екземпляр: застосунок завершує роботу раніше, якщо вже запущено інший екземпляр із тим самим bundle ID.

Нотатки щодо посилення захисту

Надавайте перевагу вимозі збігу TeamID для всіх привілейованих поверхонь.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (лише DEBUG) може дозволити викликачів із тим самим UID для локальної розробки.
Уся комунікація залишається лише локальною; мережеві сокети не відкриваються.
Запити TCC походять лише з bundle GUI-застосунку; зберігайте підписаний bundle ID стабільним між перезбираннями.
Посилення IPC: режим сокета 0600, токен, перевірки peer-UID, challenge/response HMAC, короткий TTL.

Пов’язане

Was this useful?