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

Текущая модель: локальный сокет Unix подключает службу хоста узла к приложению macOS для утверждений exec + system.run. Существует отладочный CLI openclaw-mac для проверки обнаружения/подключения; действия агента все еще проходят через WebSocket шлюза и node.invoke. Автоматизация пользовательского интерфейса использует PeekabooBridge.

Цели

  • Один экземпляр GUI-приложения, которое владеет всей работой, связанной с TCC (уведомления, запись экрана, микрофон, речь, AppleScript).
  • Небольшая поверхность для автоматизации: команды шлюза + узла, плюс PeekabooBridge для автоматизации пользовательского интерфейса.
  • Предсказуемые разрешения: всегда один и тот же подписанный идентификатор пакета, запускаемый launchd, чтобы предоставления TCC сохранялись.

Как это работает

Шлюз + транспорт узла

  • Приложение запускает шлюз (локальный режим) и подключается к нему как узел.
  • Действия агента выполняются через node.invoke (например, system.run, system.notify, canvas.*).

Служба узла + IPC приложения

  • Безголовая служба хоста узла подключается к WebSocket шлюза.
  • Запросы system.run пересылаются приложению macOS через локальный сокет Unix.
  • Приложение выполняет exec в контексте пользовательского интерфейса, запрашивает при необходимости и возвращает вывод.

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

Агент -> Шлюз -> Служба узла (WS)
                      |  IPC (UDS + токен + HMAC + TTL)
                      v
                  Приложение Mac (UI + TCC + system.run)

PeekabooBridge (автоматизация пользовательского интерфейса)

  • Автоматизация пользовательского интерфейса использует отдельный сокет UNIX с именем bridge.sock и протокол JSON PeekabooBridge.
  • Порядок предпочтения хоста (на стороне клиента): Peekaboo.app → Claude.app → OpenClaw.app → локальное выполнение.
  • Безопасность: хосты моста требуют разрешенного TeamID; escape hatch same-UID только для DEBUG защищен PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (соглашение Peekaboo).
  • См.: Использование PeekabooBridge для деталей.

Операционные потоки

  • Перезапуск/пересборка: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • Убивает существующие экземпляры
    • Сборка Swift + упаковка
    • Записывает/инициализирует/запускает LaunchAgent
  • Один экземпляр: приложение выходит рано, если уже запущен другой экземпляр с тем же идентификатором пакета.

Примечания по укреплению

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