> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
Агент -> 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](https://docs2.openclaw.ai/ru/platforms/mac/peekaboo.md).

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

* Перезапуск и повторная сборка: `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 запросов.

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

* [Приложение macOS](https://docs2.openclaw.ai/ru/platforms/macos.md)
* [Поток IPC macOS (подтверждения выполнения команд)](https://docs2.openclaw.ai/ru/tools/exec-approvals-advanced.md#macos-ipc-flow)