Обзор платформ

Приложение для macOS

Приложение для macOS — это компаньон в строке меню для OpenClaw. Оно управляет разрешениями, управляет/подключается к Шлюзу локально (launchd или вручную) и предоставляет возможности macOS агенту как узел.

Что оно делает

Показывает нативные уведомления и статус в строке меню.
Управляет запросами TCC (Уведомления, Специальные возможности, Запись экрана, Микрофон, Распознавание речи, Автоматизация/AppleScript).
Запускает или подключается к Шлюзу (локальному или удаленному).
Предоставляет инструменты, доступные только в macOS (Canvas, Камера, Запись экрана, system.run).
Запускает локальную службу узла в удаленном режиме (launchd) и останавливает её в локальном режиме.
Опционально размещает PeekabooBridge для автоматизации пользовательского интерфейса.
Устанавливает глобальный CLI (openclaw) через npm/pnpm по запросу (bun не рекомендуется для среды выполнения Шлюза).

Локальный vs удаленный режим

Локальный (по умолчанию): приложение подключается к запущенному локальному Шлюзу, если он присутствует; в противном случае оно включает службу launchd через openclaw gateway install.
Удаленный: приложение подключается к Шлюзу через SSH/Tailscale и никогда не запускает локальный процесс. Приложение запускает локальную службу узла, чтобы удаленный Шлюз мог получить доступ к этому Mac. Приложение не запускает Шлюз как дочерний процесс.

Управление Launchd

Приложение управляет LaunchAgent для каждого пользователя с меткой ai.openclaw.gateway (или ai.openclaw. при использовании --profile/OPENCLAW_PROFILE; устаревшие com.openclaw.* все еще выгружаются).

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

Замените метку на ai.openclaw. при запуске именованного профиля. Если LaunchAgent не установлен, включите его из приложения или выполните openclaw gateway install.

Возможности узла (mac)

Приложение для macOS представляется как узел. Общие команды:

Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
Камера: camera.snap, camera.clip
Экран: screen.record
Система: system.run, system.notify

Узел сообщает карту permissions, чтобы агенты могли решать, что разрешено. Служба узла + IPC приложения:

Когда служба узла без графического интерфейса запущена (удаленный режим), она подключается к WebSocket Шлюза как узел.
system.run выполняется в приложении для macOS (контекст UI/TCC) через локальный Unix-сокет; запросы и вывод остаются в приложении.

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

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

Одобрения выполнения (system.run)

system.run контролируется Одобрениями выполнения в приложении для macOS (Настройки → Одобрения выполнения). Безопасность, запрос и белый список хранятся локально на Mac в:

~/.openclaw/exec-approvals.json

Пример:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

Примечания:

Записи allowlist — это шаблоны glob для разрешенных путей к бинарным файлам.
Необработанный текст команды оболочки, содержащий синтаксис управления или подстановки оболочки (&&, ||, ;, |, ```, $, <, >, (, )), рассматривается как промах белого списка и требует явного одобрения (или добавления бинарного файла оболочки в белый список).
Выбор «Всегда разрешать» в запросе добавляет эту команду в белый список.
Переопределения окружения system.run фильтруются (удаляются PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4), а затем объединяются с окружением приложения.
Для оболочек-оберток (bash|sh|zsh ... -c/-lc) переопределения окружения в рамках запроса сокращаются до небольшого явного белого списка (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
Для решений «разрешить всегда» в режиме белого списка известные обертки диспетчеризации (env, nice, nohup, stdbuf, timeout) сохраняют пути к внутренним исполняемым файлам вместо путей к оберткам. Если развертывание небезопасно, запись в белый список не сохраняется автоматически.

Глубокие ссылки

Приложение регистрирует схему URL openclaw:// для локальных действий.

openclaw://agent

Запускает запрос agent к Шлюзу.

open 'openclaw://agent?message=Hello%20from%20deep%20link'

Параметры запроса:

message (обязательно)
sessionKey (опционально)
thinking (опционально)
deliver / to / channel (опционально)
timeoutSeconds (опционально)
key (опциональный ключ для автономного режима)

Безопасность:

Без key приложение запрашивает подтверждение.
Без key приложение применяет короткое ограничение на длину сообщения для запроса подтверждения и игнорирует deliver / to / channel.
С действительным key выполнение происходит автономно (предназначено для личных автоматизаций).

Процесс начальной настройки (типичный)

Установите и запустите OpenClaw.app.
Пройдите контрольный список разрешений (запросы TCC).
Убедитесь, что активен Локальный режим и Шлюз запущен.
Установите CLI, если нужен доступ из терминала.

Размещение каталога состояния (macOS)

Избегайте размещения каталога состояния OpenClaw в iCloud или других папках, синхронизируемых с облаком. Пути с синхронизацией могут добавлять задержки и иногда вызывать гонки блокировок/синхронизации файлов для сессий и учетных данных. Предпочтительнее использовать локальный несинхронизируемый путь, например:

OPENCLAW_STATE_DIR=~/.openclaw

Если openclaw doctor обнаружит состояние в:

~/Library/Mobile Documents/com~apple~CloudDocs/...
~/Library/CloudStorage/...

он предупредит и порекомендует вернуться к локальному пути.

Сборка и рабочий процесс разработки (нативный)

cd apps/macos && swift build
swift run OpenClaw (или Xcode)
Упаковка приложения: scripts/package-mac-app.sh

Отладка подключения к шлюзу (macOS CLI)

Используйте отладочный CLI, чтобы проверить ту же логику рукопожатия и обнаружения WebSocket Шлюза, которую использует приложение для macOS, без запуска самого приложения.

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Опции подключения:

--url <ws://host:port>: переопределить конфигурацию
--mode <local|remote>: определить из конфигурации (по умолчанию: из конфигурации или local)
--probe: принудительно выполнить свежую проверку здоровья
--timeout <ms>: таймаут запроса (по умолчанию: 15000)
--json: структурированный вывод для сравнения

Опции обнаружения:

--include-local: включать шлюзы, которые были бы отфильтрованы как «локальные»
--timeout <ms>: общее окно обнаружения (по умолчанию: 2000)
--json: структурированный вывод для сравнения

Совет: сравните с openclaw gateway discover --json, чтобы увидеть, отличается ли конвейер обнаружения приложения для macOS (NWBrowser + резервный DNS‑SD tailnet) от обнаружения на основе dns-sd в Node CLI.

Организация удаленного подключения (SSH-туннели)

Когда приложение для macOS работает в удаленном режиме, оно открывает SSH-туннель, чтобы локальные компоненты пользовательского интерфейса могли общаться с удаленным Шлюзом, как если бы он был на localhost.

Управляющий туннель (порт WebSocket Шлюза)

Назначение: проверки здоровья, статус, Web Chat, конфигурация и другие вызовы плоскости управления.
Локальный порт: порт Шлюза (по умолчанию 18789), всегда стабильный.
Удаленный порт: тот же порт Шлюза на удаленном хосте.
Поведение: нет случайного локального порта; приложение повторно использует существующий рабочий туннель или перезапускает его при необходимости.
Форма SSH: ssh -N -L <local>:127.0.0.1:<remote> с опциями BatchMode + ExitOnForwardFailure + keepalive.
Отчетность об IP: SSH-туннель использует loopback, поэтому шлюз будет видеть IP узла как 127.0.0.1. Используйте транспорт Прямой (ws/wss), если хотите, чтобы отображался реальный IP клиента (см. Удаленный доступ для macOS).

Шаги настройки см. в разделе Удаленный доступ для macOS. Подробности протокола см. в разделе Протокол Шлюза.

Связанная документация

Платформы Приложение для Linux

Что оно делает​

Локальный vs удаленный режим​

Управление Launchd​

Возможности узла (mac)​

Одобрения выполнения (system.run)​

Глубокие ссылки​

openclaw://agent​

Процесс начальной настройки (типичный)​

Размещение каталога состояния (macOS)​

Сборка и рабочий процесс разработки (нативный)​

Отладка подключения к шлюзу (macOS CLI)​

Организация удаленного подключения (SSH-туннели)​

Управляющий туннель (порт WebSocket Шлюза)​

Связанная документация​