Приложение-компаньон OpenClaw для macOS (строка меню + брокер gateway)

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

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

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

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

  • Локальный (по умолчанию): приложение подключается к запущенному локальному 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 socket; запросы + вывод остаются в приложении.

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

Gateway -> Сервис узла (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
         Приложение Mac (UI + TCC + system.run)

Утверждения Exec (system.run)

system.run контролируется утверждениями Exec в приложении macOS (Настройки → Утверждения Exec). Безопасность + запрос + allowlist хранятся локально на 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-шаблоны для разрешенных путей бинарников.
  • Выбор "Всегда разрешать" в запросе добавляет эту команду в allowlist.
  • Переопределения окружения system.run фильтруются (отбрасывает PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) и затем объединяются с окружением приложения.

Deep links

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

openclaw://agent

Запускает запрос Gateway agent.

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

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

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

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

  • Без key приложение запрашивает подтверждение.
  • С действительным key запуск происходит автоматически (предназначено для персональных автоматизаций).

Поток онбординга (типичный)

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

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

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

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

Используйте отладочный CLI для упражнения той же логики рукопожатия Gateway 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>: разрешить из конфига (по умолчанию: конфиг или локально)
  • --probe: принудительная свежая проба здоровья
  • --timeout <ms>: таймаут запроса (по умолчанию: 15000)
  • --json: структурированный вывод для сравнения

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

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

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

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

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

Туннель управления (порт Gateway WebSocket)

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

Для шагов настройки см. macOS удаленный доступ. Для деталей протокола см. Протокол Gateway.

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

← Назад к документации