> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Приложение macOS

# Сопутствующее приложение 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.*` по‑прежнему выгружается).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

Пример:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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, не запуская само приложение.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/platforms/mac/remote)).

Шаги настройки см. в [удалённый доступ macOS](/platforms/mac/remote). Подробности протокола см. в [протокол Gateway](/gateway/protocol).

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

* [Runbook Gateway](/gateway)
* [Gateway (macOS)](/platforms/mac/bundled-gateway)
* [Разрешения macOS](/platforms/mac/permissions)
* [Canvas](/platforms/mac/canvas)