--- read_when: - Реалізація функцій застосунку для macOS - Зміна життєвого циклу Gateway або мостового підключення Node у macOS summary: Супутній застосунок OpenClaw для macOS (рядок меню + брокер Gateway) title: Програма для macOS x-i18n: generated_at: "2026-05-06T04:12:57Z" model: gpt-5.5 provider: openai source_hash: cc67a88303073bb771fcec09e7366f710a6bd5500f584f8782232deaa69e599d source_path: platforms/macos.md workflow: 16 --- Застосунок macOS — це **супутник у рядку меню** для OpenClaw. Він керує дозволами, керує/під’єднується до Gateway локально (launchd або вручну) і надає macOS можливості агенту як Node. ## Що він робить - Показує нативні сповіщення та стан у рядку меню. - Керує запитами TCC (Сповіщення, Accessibility, Запис екрана, Мікрофон, Розпізнавання мовлення, Automation/AppleScript). - Запускає або під’єднується до Gateway (локального чи віддаленого). - Надає інструменти лише для macOS (Canvas, Camera, Screen Recording, `system.run`). - Запускає локальну службу хоста Node у **віддаленому** режимі (launchd) і зупиняє її в **локальному** режимі. - За бажанням розміщує **PeekabooBridge** для автоматизації UI. - Встановлює глобальний CLI (`openclaw`) на запит через npm, pnpm або bun (застосунок віддає перевагу npm, потім pnpm, потім bun; Node залишається рекомендованим середовищем виконання Gateway). ## Локальний і віддалений режим - **Локальний** (за замовчуванням): застосунок під’єднується до запущеного локального Gateway, якщо він є; інакше вмикає службу launchd через `openclaw gateway install`. - **Віддалений**: застосунок під’єднується до Gateway через SSH/Tailscale і ніколи не запускає локальний процес. Застосунок запускає локальну **службу хоста Node**, щоб віддалений Gateway міг досягти цього Mac. Застосунок не запускає Gateway як дочірній процес. Виявлення Gateway тепер віддає перевагу іменам Tailscale MagicDNS замість сирих IP-адрес tailnet, тому застосунок Mac надійніше відновлюється, коли IP-адреси tailnet змінюються. ## Керування launchd Застосунок керує LaunchAgent для кожного користувача з міткою `ai.openclaw.gateway` (або `ai.openclaw.` під час використання `--profile`/`OPENCLAW_PROFILE`; застарілі `com.openclaw.*` усе ще вивантажуються). ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` Замініть мітку на `ai.openclaw.` під час запуску іменованого профілю. Якщо LaunchAgent не встановлено, увімкніть його із застосунку або виконайте `openclaw gateway install`. ## Можливості Node (mac) Застосунок macOS представляє себе як Node. Поширені команди: - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` - Camera: `camera.snap`, `camera.clip` - Screen: `screen.snapshot`, `screen.record` - System: `system.run`, `system.notify` Node повідомляє карту `permissions`, щоб агенти могли визначати, що дозволено. Служба Node + IPC застосунку: - Коли безголова служба хоста Node працює (віддалений режим), вона під’єднується до Gateway WS як Node. - `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 (Settings → Exec approvals). Безпека + запит + список дозволеного зберігаються локально на Mac у: ``` ~/.openclaw/exec-approvals.json ``` Приклад: ```json { "version": 1, "defaults": { "security": "deny", "ask": "on-miss" }, "agents": { "main": { "security": "allowlist", "ask": "on-miss", "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }] } } } ``` Нотатки: - Записи `allowlist` — це glob-шаблони для розв’язаних шляхів до бінарних файлів або голі назви команд для команд, викликаних через PATH. - Сирий текст команди shell, що містить синтаксис керування shell або розгортання (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом списку дозволеного й потребує явного схвалення (або додавання бінарного файлу shell до списку дозволеного). - Вибір "Always Allow" у запиті додає цю команду до списку дозволеного. - Перевизначення середовища `system.run` фільтруються (відкидаються `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`), а потім об’єднуються із середовищем застосунку. - Для обгорток shell (`bash|sh|zsh ... -c/-lc`) перевизначення середовища в межах запиту скорочуються до невеликого явного списку дозволеного (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). - Для рішень «завжди дозволяти» в режимі списку дозволеного відомі обгортки диспетчеризації (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають шляхи до внутрішніх виконуваних файлів замість шляхів до обгорток. Якщо розгортання небезпечне, запис у список дозволеного автоматично не зберігається. ## Глибокі посилання Застосунок реєструє URL-схему `openclaw://` для локальних дій. ### `openclaw://agent` Запускає запит Gateway `agent`. __OC_I18N_900004__ Параметри запиту: - `message` (обов’язковий) - `sessionKey` (необов’язковий) - `thinking` (необов’язковий) - `deliver` / `to` / `channel` (необов’язковий) - `timeoutSeconds` (необов’язковий) - `key` (необов’язковий ключ автоматичного режиму) Безпека: - Без `key` застосунок запитує підтвердження. - Без `key` застосунок застосовує коротке обмеження повідомлення для запиту підтвердження та ігнорує `deliver` / `to` / `channel`. - З дійсним `key` запуск відбувається без участі користувача (призначено для особистих автоматизацій). ## Потік онбордингу (типовий) 1. Встановіть і запустіть **OpenClaw.app**. 2. Виконайте контрольний список дозволів (запити TCC). 3. Переконайтеся, що режим **Локальний** активний і Gateway працює. 4. Встановіть CLI, якщо потрібен доступ із термінала. ## Розміщення каталогу стану (macOS) Уникайте розміщення каталогу стану OpenClaw в iCloud або інших хмарно синхронізованих папках. Шляхи, що підтримуються синхронізацією, можуть додавати затримку й іноді спричиняти перегони блокування файлів/синхронізації для сеансів і облікових даних. Надавайте перевагу локальному несинхронізованому шляху стану, наприклад: __OC_I18N_900005__ Якщо `openclaw doctor` виявить стан у: - `~/Library/Mobile Documents/com~apple~CloudDocs/...` - `~/Library/CloudStorage/...` він попередить і порадить повернутися до локального шляху. ## Збірка та робочий процес розробки (нативний) - `cd apps/macos && swift build` - `swift run OpenClaw` (або Xcode) - Пакування застосунку: `scripts/package-mac-app.sh` ## Налагодження підключення Gateway (macOS CLI) Використовуйте налагоджувальний CLI, щоб виконати той самий WebSocket-рукостиск Gateway і логіку виявлення, які використовує застосунок macOS, без запуску застосунку. __OC_I18N_900006__ Параметри підключення: - `--url `: перевизначити конфігурацію - `--mode `: розв’язати з конфігурації (за замовчуванням: конфігурація або локальний) - `--probe`: примусово виконати нову перевірку стану - `--timeout `: таймаут запиту (за замовчуванням: `15000`) - `--json`: структурований вивід для порівняння Параметри виявлення: - `--include-local`: включити шлюзи, які були б відфільтровані як "local" - `--timeout `: загальне вікно виявлення (за замовчуванням: `2000`) - `--json`: структурований вивід для порівняння Порівняйте з `openclaw gateway discover --json`, щоб побачити, чи конвеєр виявлення застосунку macOS (`local.` плюс налаштований домен wide-area, з резервними варіантами wide-area і Tailscale Serve) відрізняється від виявлення CLI Node на основі `dns-sd`. ## Інфраструктура віддаленого підключення (SSH-тунелі) Коли застосунок macOS працює у **віддаленому** режимі, він відкриває SSH-тунель, щоб локальні UI компоненти могли спілкуватися з віддаленим Gateway так, ніби він був на localhost. ### Керівний тунель (порт WebSocket Gateway) - **Призначення:** перевірки стану, статус, Web Chat, конфігурація та інші виклики площини керування. - **Локальний порт:** порт Gateway (за замовчуванням `18789`), завжди стабільний. - **Віддалений порт:** той самий порт Gateway на віддаленому хості. - **Поведінка:** без випадкового локального порту; застосунок повторно використовує наявний справний тунель або перезапускає його за потреби. - **Форма SSH:** `ssh -N -L :127.0.0.1:` з BatchMode + ExitOnForwardFailure + параметрами keepalive. - **Звітування IP:** SSH-тунель використовує loopback, тому Gateway бачитиме IP Node як `127.0.0.1`. Використовуйте транспорт **Direct (ws/wss)**, якщо хочете, щоб з’являвся реальний IP клієнта (див. [віддалений доступ macOS](/uk/platforms/mac/remote)). Кроки налаштування див. у [віддаленому доступі macOS](/uk/platforms/mac/remote). Подробиці протоколу див. у [протоколі Gateway](/uk/gateway/protocol). ## Пов’язана документація - [Інструкція з експлуатації Gateway](/uk/gateway) - [Gateway (macOS)](/uk/platforms/mac/bundled-gateway) - [Дозволи macOS](/uk/platforms/mac/permissions) - [Canvas](/uk/platforms/mac/canvas)