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

Приложение для 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> при использовании --profile/OPENCLAW_PROFILE; устаревшие com.openclaw.* все еще выгружаются).

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

Замените метку на ai.openclaw.<profile> при запуске именованного профиля. Если 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