diff --git a/docs/uk/platforms/macos.md b/docs/uk/platforms/macos.md index 85bee1496..12065b634 100644 --- a/docs/uk/platforms/macos.md +++ b/docs/uk/platforms/macos.md @@ -1,50 +1,50 @@ --- read_when: - - Реалізація функцій застосунку macOS - - Зміна життєвого циклу gateway або мосту вузла в macOS -summary: Супутній застосунок OpenClaw для macOS (рядок меню + брокер gateway) -title: Застосунок macOS + - Реалізація функцій додатка macOS + - Зміна життєвого циклу Gateway або мостового з’єднання Node на macOS +summary: Додаток-супутник OpenClaw для macOS (рядок меню + брокер Gateway) +title: Додаток macOS x-i18n: - generated_at: "2026-04-05T18:11:14Z" + generated_at: "2026-04-17T07:59:54Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# Супутній застосунок OpenClaw для macOS (рядок меню + брокер gateway) +# Супутник OpenClaw для macOS (рядок меню + брокер Gateway) -Застосунок macOS — це **супутній застосунок у рядку меню** для OpenClaw. Він керує дозволами, -керує Gateway локально або підключається до нього (launchd або вручну), а також надає можливості macOS -агенту як вузол. +Додаток macOS є **супутником у рядку меню** для OpenClaw. Він відповідає за дозволи, +керує Gateway локально або під’єднується до нього (через launchd або вручну), а також надає можливості macOS +агенту як Node. ## Що він робить -- Показує нативні сповіщення та стан у рядку меню. -- Керує запитами TCC (сповіщення, Accessibility, Screen Recording, Microphone, - Speech Recognition, Automation/AppleScript). -- Запускає Gateway або підключається до нього (локального чи віддаленого). +- Показує нативні сповіщення та статус у рядку меню. +- Керує запитами TCC (Сповіщення, Універсальний доступ, Запис екрана, Мікрофон, + Розпізнавання мовлення, Automation/AppleScript). +- Запускає Gateway або під’єднується до нього (локального чи віддаленого). - Надає інструменти лише для macOS (Canvas, Camera, Screen Recording, `system.run`). -- Запускає локальний сервіс хоста вузла в режимі **remote** (launchd) і зупиняє його в режимі **local**. -- За потреби розміщує **PeekabooBridge** для UI-автоматизації. -- Встановлює глобальний CLI (`openclaw`) на запит через npm, pnpm або bun (застосунок надає перевагу npm, потім pnpm, потім bun; Node залишається рекомендованим середовищем виконання для Gateway). +- Запускає локальну службу хоста Node у режимі **remote** (launchd) і зупиняє її в режимі **local**. +- За потреби розміщує **PeekabooBridge** для автоматизації UI. +- За запитом встановлює глобальний CLI (`openclaw`) через npm, pnpm або bun (додаток надає перевагу npm, потім pnpm, потім bun; Node лишається рекомендованим середовищем виконання для Gateway). ## Режим local і remote -- **Local** (типово): застосунок підключається до запущеного локального Gateway, якщо він є; - інакше вмикає сервіс launchd через `openclaw gateway install`. -- **Remote**: застосунок підключається до Gateway через SSH/Tailscale і ніколи не запускає +- **Local** (типово): додаток під’єднується до запущеного локального Gateway, якщо він є; + інакше вмикає службу launchd через `openclaw gateway install`. +- **Remote**: додаток під’єднується до Gateway через SSH/Tailscale і ніколи не запускає локальний процес. - Застосунок запускає локальний **сервіс хоста вузла**, щоб віддалений Gateway міг звертатися до цього Mac. - Застосунок не запускає Gateway як дочірній процес. - Виявлення Gateway тепер надає перевагу іменам Tailscale MagicDNS замість сирих IP tailnet, - тому застосунок Mac надійніше відновлюється, коли IP tailnet змінюються. + Додаток запускає локальну **службу хоста Node**, щоб віддалений Gateway міг отримати доступ до цього Mac. + Додаток не породжує Gateway як дочірній процес. + Виявлення Gateway тепер надає перевагу іменам Tailscale MagicDNS замість сирих IP-адрес tailnet, + тому додаток для Mac надійніше відновлюється, коли IP-адреси tailnet змінюються. -## Керування Launchd +## Керування launchd -Застосунок керує LaunchAgent для кожного користувача з міткою `ai.openclaw.gateway` -(або `ai.openclaw.` при використанні `--profile`/`OPENCLAW_PROFILE`; застарілі `com.openclaw.*` також вивантажуються). +Додаток керує користувацьким LaunchAgent з міткою `ai.openclaw.gateway` +(або `ai.openclaw.` при використанні `--profile`/`OPENCLAW_PROFILE`; застарілі `com.openclaw.*` усе ще вивантажуються). ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway @@ -53,24 +53,24 @@ launchctl bootout gui/$UID/ai.openclaw.gateway Замініть мітку на `ai.openclaw.`, якщо використовуєте іменований профіль. -Якщо LaunchAgent не встановлено, увімкніть його із застосунку або виконайте +Якщо LaunchAgent не встановлено, увімкніть його в додатку або виконайте `openclaw gateway install`. -## Можливості вузла (mac) +## Можливості Node (mac) -Застосунок macOS представляє себе як вузол. Типові команди: +Додаток macOS представляє себе як Node. Поширені команди: - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` - Camera: `camera.snap`, `camera.clip` -- Screen: `screen.record` +- Screen: `screen.snapshot`, `screen.record` - System: `system.run`, `system.notify` -Вузол повідомляє мапу `permissions`, щоб агенти могли визначати, що дозволено. +Node повідомляє карту `permissions`, щоб агенти могли визначити, що дозволено. -Сервіс вузла + IPC застосунку: +Служба Node + IPC додатка: -- Коли працює безголовий сервіс хоста вузла (режим remote), він підключається до Gateway WS як вузол. -- `system.run` виконується в застосунку macOS (контекст UI/TCC) через локальний Unix socket; запити підтвердження та вивід залишаються в застосунку. +- Коли працює безголова служба хоста Node (режим remote), вона під’єднується до Gateway WS як Node. +- `system.run` виконується в додатку macOS (контекст UI/TCC) через локальний Unix-сокет; запити та вивід залишаються в межах додатка. Діаграма (SCI): @@ -83,8 +83,8 @@ Gateway -> Node Service (WS) ## Підтвердження виконання (system.run) -`system.run` контролюється через **Exec approvals** у застосунку macOS (Settings → Exec approvals). -Security + ask + allowlist зберігаються локально на Mac у: +`system.run` керується через **Exec approvals** у додатку macOS (Settings → Exec approvals). +Параметри security + ask + allowlist зберігаються локально на Mac у: ``` ~/.openclaw/exec-approvals.json @@ -111,16 +111,16 @@ Security + ask + allowlist зберігаються локально на Mac у Примітки: -- Записи `allowlist` — це glob-шаблони для визначених шляхів до двійкових файлів. -- Необроблений текст команди оболонки, що містить синтаксис керування оболонкою або розгортання (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом `allowlist` і потребує явного підтвердження (або додавання двійкового файла оболонки до allowlist). +- Записи `allowlist` — це glob-шаблони для визначених шляхів до бінарних файлів. +- Сирий текст shell-команди, що містить керувальний або розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом по allowlist і потребує явного підтвердження (або додавання бінарного файлу shell до allowlist). - Вибір “Always Allow” у запиті додає цю команду до allowlist. -- Перевизначення середовища `system.run` фільтруються (відкидаються `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`), а потім об’єднуються із середовищем застосунку. +- Перевизначення середовища для `system.run` фільтруються (відкидаються `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`), а потім об’єднуються із середовищем додатка. - Для оболонкових обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення середовища в межах запиту зводяться до невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -- Для рішень allow-always у режимі allowlist відомі обгортки диспетчеризації (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи виконуваних файлів замість шляхів обгорток. Якщо безпечне розгортання неможливе, запис до allowlist автоматично не зберігається. +- Для рішень allow-always у режимі allowlist відомі обгортки диспетчеризації (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи до виконуваних файлів, а не шляхи обгорток. Якщо безпечне розгортання неможливе, запис allowlist автоматично не зберігається. ## Глибокі посилання -Застосунок реєструє схему URL `openclaw://` для локальних дій. +Додаток реєструє URL-схему `openclaw://` для локальних дій. ### `openclaw://agent` @@ -133,26 +133,26 @@ __OC_I18N_900004__ - `thinking` (необов’язковий) - `deliver` / `to` / `channel` (необов’язкові) - `timeoutSeconds` (необов’язковий) -- `key` (необов’язковий ключ режиму без нагляду) +- `key` (необов’язковий ключ для unattended mode) Безпека: -- Без `key` застосунок запитує підтвердження. -- Без `key` застосунок застосовує коротке обмеження на довжину повідомлення для запиту підтвердження та ігнорує `deliver` / `to` / `channel`. -- Із чинним `key` виконання відбувається без нагляду (призначено для персональних автоматизацій). +- Без `key` додаток запитує підтвердження. +- Без `key` додаток застосовує коротке обмеження довжини повідомлення для запиту підтвердження й ігнорує `deliver` / `to` / `channel`. +- Із чинним `key` виконання відбувається в unattended mode (призначено для персональних автоматизацій). -## Потік початкового налаштування (типовий) +## Процес початкового налаштування (типовий) 1. Встановіть і запустіть **OpenClaw.app**. -2. Завершіть контрольний список дозволів (запити TCC). -3. Переконайтеся, що активний режим **Local** і Gateway працює. -4. Встановіть CLI, якщо вам потрібен доступ із термінала. +2. Пройдіть контрольний список дозволів (запити TCC). +3. Переконайтеся, що активний режим **Local** і Gateway запущено. +4. Встановіть CLI, якщо хочете доступ із термінала. ## Розміщення каталогу стану (macOS) -Уникайте розміщення каталогу стану OpenClaw в iCloud або інших папках із хмарною синхронізацією. -Шляхи з синхронізацією можуть додавати затримку і час від часу спричиняти конфлікти блокування файлів або синхронізації для -сеансів і облікових даних. +Уникайте розміщення каталогу стану OpenClaw в iCloud або інших папках, що синхронізуються з хмарою. +Шляхи з увімкненою синхронізацією можуть додавати затримку й інколи спричиняти конфлікти блокувань файлів або синхронізації +для сесій і облікових даних. Надавайте перевагу локальному шляху стану без синхронізації, наприклад: __OC_I18N_900005__ @@ -161,18 +161,18 @@ __OC_I18N_900005__ - `~/Library/Mobile Documents/com~apple~CloudDocs/...` - `~/Library/CloudStorage/...` -він покаже попередження та порекомендує повернутися до локального шляху. +він покаже попередження й порекомендує повернутися до локального шляху. -## Збірка та процес розробки (native) +## Робочий процес збирання та розробки (нативний) - `cd apps/macos && swift build` - `swift run OpenClaw` (або Xcode) -- Пакування застосунку: `scripts/package-mac-app.sh` +- Пакування додатка: `scripts/package-mac-app.sh` -## Налагодження підключення до gateway (CLI macOS) +## Налагодження з’єднання з Gateway (macOS CLI) -Використовуйте CLI для налагодження, щоб перевірити той самий handshake WebSocket Gateway і логіку виявлення, -які використовує застосунок macOS, без запуску самого застосунку. +Використовуйте CLI для налагодження, щоб перевірити те саме рукостискання WebSocket Gateway і логіку виявлення, +які використовує додаток macOS, не запускаючи сам додаток. __OC_I18N_900006__ Параметри connect: @@ -184,39 +184,39 @@ __OC_I18N_900006__ Параметри discovery: -- `--include-local`: включити gateway, які було б відфільтровано як “local” +- `--include-local`: включити Gateway, які інакше були б відфільтровані як “local” - `--timeout `: загальне вікно виявлення (типово: `2000`) - `--json`: структурований вивід для порівняння Порада: порівняйте з `openclaw gateway discover --json`, щоб побачити, чи -конвеєр виявлення застосунку macOS (`local.` плюс налаштований wide-area домен, з +конвеєр виявлення додатка macOS (`local.` плюс налаштований wide-area domain із резервними варіантами wide-area і Tailscale Serve) відрізняється від виявлення на основі `dns-sd` у Node CLI. -## Внутрішня логіка віддаленого підключення (SSH-тунелі) +## Внутрішня логіка віддаленого з’єднання (SSH-тунелі) -Коли застосунок macOS працює в режимі **Remote**, він відкриває SSH-тунель, щоб локальні UI-компоненти -могли звертатися до віддаленого Gateway так, ніби він працює на localhost. +Коли додаток macOS працює в режимі **Remote**, він відкриває SSH-тунель, щоб локальні компоненти UI +могли взаємодіяти з віддаленим Gateway так, ніби він працює на localhost. ### Керувальний тунель (порт WebSocket Gateway) -- **Призначення:** перевірки стану, status, Web Chat, конфігурація та інші виклики площини керування. -- **Локальний порт:** порт Gateway (типово `18789`), завжди стабільний. +- **Призначення:** перевірки стану, статус, Web Chat, конфігурація та інші виклики control-plane. +- **Локальний порт:** порт Gateway (типово `18789`), завжди сталий. - **Віддалений порт:** той самий порт Gateway на віддаленому хості. -- **Поведінка:** без випадкового локального порту; застосунок повторно використовує наявний справний тунель +- **Поведінка:** без випадкового локального порту; додаток повторно використовує наявний справний тунель або перезапускає його за потреби. - **Форма SSH:** `ssh -N -L :127.0.0.1:` з параметрами BatchMode + ExitOnForwardFailure + keepalive. -- **Звітність IP:** SSH-тунель використовує loopback, тому gateway бачитиме IP вузла - як `127.0.0.1`. Якщо ви хочете, щоб відображалась справжня IP-адреса клієнта, використовуйте транспорт **Direct (ws/wss)** - (див. [віддалений доступ macOS](/platforms/mac/remote)). +- **Звітування про IP:** SSH-тунель використовує loopback, тому gateway бачитиме IP + Node як `127.0.0.1`. Використовуйте транспорт **Direct (ws/wss)**, якщо хочете, щоб відображалася + справжня IP-адреса клієнта (див. [віддалений доступ macOS](/uk/platforms/mac/remote)). -Кроки налаштування див. у [віддалений доступ macOS](/platforms/mac/remote). Подробиці -протоколу див. у [протокол Gateway](/uk/gateway/protocol). +Інструкції з налаштування див. у [віддалений доступ macOS](/uk/platforms/mac/remote). Докладніше про протокол — +у [протокол Gateway](/uk/gateway/protocol). ## Пов’язана документація -- [Інструкція з експлуатації Gateway](/uk/gateway) +- [Інструкція з Gateway](/uk/gateway) - [Gateway (macOS)](/uk/platforms/mac/bundled-gateway) -- [Дозволи macOS](/platforms/mac/permissions) +- [Дозволи macOS](/uk/platforms/mac/permissions) - [Canvas](/uk/platforms/mac/canvas)