Перейти к основному содержанию

​
Сопутствующее приложение OpenClaw для macOS (строка меню + брокер шлюза)

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

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

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

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

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

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

Приложение управляет пользовательским LaunchAgent с меткой bot.molt.gateway (или bot.molt.<profile> при использовании --profile/OPENCLAW_PROFILE; устаревший com.openclaw.* по‑прежнему выгружается). 
launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway
Замените метку на bot.molt.<profile> при запуске именованного профиля. Если LaunchAgent не установлен, включите его из приложения или выполните openclaw gateway install.

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

Приложение macOS представляет себя как узел. Распространённые команды:
  • Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
  • Camera: camera.snap, camera.clip
  • Screen: screen.record
  • System: system.run, system.notify
Узел сообщает карту permissions, чтобы агенты могли определить, что разрешено. Служба узла + IPC приложения:
  • Когда запущена headless‑служба хоста узла (удалённый режим), она подключается к Gateway по WS как узел.
  • 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 (Настройки → Exec approvals). Безопасность + запросы + список разрешённых хранятся локально на 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 для разрешённых путей к бинарным файлам.
  • Выбор «Always Allow» в запросе добавляет эту команду в список разрешённых.
  • Переопределения переменных окружения system.run фильтруются (удаляются PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT), а затем объединяются с окружением приложения.

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

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

​
openclaw://agent

Запускает запрос Gateway agent. 
open 'openclaw://agent?message=Hello%20from%20deep%20link'
Параметры запроса:
  • message (обязательно)
  • sessionKey (необязательно)
  • thinking (необязательно)
  • deliver / to / channel (необязательно)
  • timeoutSeconds (необязательно)
  • key (необязательно, ключ режима без участия пользователя)
Безопасность:
  • Без key приложение запрашивает подтверждение.
  • Без key приложение применяет ограничение на длину сообщения для запроса подтверждения и игнорирует deliver / to / channel.
  • С действительным key выполнение происходит без участия пользователя (предназначено для персональных автоматизаций).

​
Поток посадки (обычный)

  1. Установите и запустите OpenClaw.app.
  2. Завершите чек‑лист разрешений (запросы TCC).
  3. Убедитесь, что активен локальный режим и Gateway запущен.
  4. Установите CLI, если нужен доступ из терминала.

​
Процесс сборки и разработки (native)

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

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

Используйте отладочный CLI, чтобы воспроизвести то же рукопожатие WebSocket Gateway и логику обнаружения, которые использует приложение 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>: разрешать из конфига (по умолчанию: конфиг или локально)
  • --probe: принудительно выполнить новый health‑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‑туннель, чтобы локальные UI‑компоненты могли общаться с удалённым Gateway так, как если бы он был на localhost.

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

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

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