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

Agent -> Gateway -> Node Service (WS)                      |  IPC (UDS + token + HMAC + TTL)                      v                  Mac App (UI + 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?