macOS companion app

IPC в macOS

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

Локальный сокет Unix соединяет службу хоста Node с приложением macOS для подтверждения выполнения команд и system.run. Для проверок обнаружения и подключения предусмотрен отладочный CLI openclaw-mac (apps/macos/Sources/OpenClawMacCLI); действия агента по-прежнему проходят через WebSocket Gateway и node.invoke. Путь computer.act на базе Node запускает встроенную автоматизацию Peekaboo внутри процесса; автономные клиенты Peekaboo используют PeekabooBridge.

Цели

Единственный экземпляр приложения с графическим интерфейсом, отвечающий за всю работу, связанную с TCC (уведомления, запись экрана, микрофон, речь, AppleScript).
Минимальная поверхность автоматизации: Gateway + команды Node, внутрипроцессный computer.act, а также PeekabooBridge для автономных клиентов автоматизации интерфейса.
Предсказуемые разрешения: всегда один и тот же идентификатор подписанного пакета, запускаемого через launchd, чтобы разрешения TCC сохранялись.

Принцип работы

Транспорт Gateway + Node

Приложение запускает Gateway (в локальном режиме) и подключается к нему как Node.
Действия агента выполняются через node.invoke (например, system.run, system.notify, canvas.*).
Команды Node включают canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run и system.notify.
Node передаёт карту permissions, чтобы агенты могли определить, доступен ли доступ к экрану, камере, микрофону, распознаванию речи, автоматизации или специальным возможностям.

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

Фоновая служба хоста Node без графического интерфейса подключается к WebSocket Gateway.
Запросы system.run перенаправляются в приложение macOS через локальный сокет Unix (ExecApprovalsSocket.swift).
Приложение выполняет команду в контексте пользовательского интерфейса, при необходимости запрашивает подтверждение и возвращает результат.

Схема (SCI):

text

Агент -> Gateway -> Служба Node (WS)                      |  IPC (UDS + токен + HMAC + TTL)                      v                  Приложение Mac (интерфейс + TCC + system.run)

PeekabooBridge (автоматизация интерфейса)

Встроенный инструмент агента computer не использует этот сокет. Сопряжённый Node macOS выполняет computer.act в процессе приложения с помощью встроенных служб Peekaboo.
Для автоматизации интерфейса используется отдельный сокет UNIX (~/Library/Application Support/OpenClaw/<socket>) и протокол JSON PeekabooBridge.
Порядок предпочтения хостов (на стороне клиента): Peekaboo.app -> Claude.app -> OpenClaw.app -> локальное выполнение.
Безопасность: хостам моста требуется TeamID из списка разрешённых (встроенный PeekabooBridgeHostCoordinator разрешает фиксированную команду и собственную команду подписи приложения); обходное решение только для DEBUG, допускающее тот же UID, контролируется параметром PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (соглашение Peekaboo).
Подробности см. в разделе Использование PeekabooBridge.

Рабочие процессы

Перезапуск и повторная сборка: scripts/restart-mac.sh завершает существующие экземпляры, выполняет повторную сборку с помощью Swift, заново упаковывает и перезапускает приложение. Команда автоматически обнаруживает доступный идентификатор подписи и, если он не найден, использует --no-sign; передайте --sign, чтобы потребовать подпись (операция завершится ошибкой, если ключ недоступен), или --no-sign, чтобы принудительно использовать путь без подписи. Переменная SIGN_IDENTITY, заданная в окружении, удаляется на пути с подписью, чтобы собственное автоматическое обнаружение идентификатора в scripts/codesign-mac-app.sh выбрало сертификат.
Единственный экземпляр: приложение проверяет NSWorkspace.runningApplications на наличие дубликата идентификатора пакета и завершает работу, если обнаружено более одного экземпляра (isDuplicateInstance() в MenuBar.swift).

Примечания по усилению защиты

Для всех привилегированных поверхностей предпочтительно требовать совпадение TeamID.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (только для DEBUG) может разрешать обращения от процессов с тем же UID при локальной разработке.
Весь обмен данными остаётся исключительно локальным; сетевые сокеты не открываются.
Запросы TCC исходят только от пакета приложения с графическим интерфейсом; сохраняйте идентификатор подписанного пакета неизменным между повторными сборками.
Усиление защиты сокета подтверждений выполнения команд: режим файла 0600, общий токен, проверка UID однорангового процесса (getpeereid), механизм «запрос — ответ» на основе HMAC-SHA256 и короткий TTL запросов.

Связанные материалы

Was this useful?