diff --git a/docs/uk/gateway/bonjour.md b/docs/uk/gateway/bonjour.md index 40d86bcd3..7ead4f256 100644 --- a/docs/uk/gateway/bonjour.md +++ b/docs/uk/gateway/bonjour.md @@ -2,13 +2,13 @@ read_when: - Налагодження проблем виявлення Bonjour на macOS/iOS - Зміна типів сервісів mDNS, записів TXT або UX виявлення -summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та поширені режими відмови) -title: Виявлення Bonjour +summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та поширені режими відмов) +title: виявлення Bonjour x-i18n: - generated_at: "2026-04-26T00:18:18Z" + generated_at: "2026-04-26T04:54:58Z" model: gpt-5.4 provider: openai - source_hash: ced3a4a81ab6a4e8c32a33c967ff3e173485c3e644885192012eaca8b81a065f + source_hash: 625d4fbf8fe46938ee42f267d2bdabe6ab9c2766d6b2debc30de3c43f0de724c source_path: gateway/bonjour.md workflow: 15 --- @@ -16,46 +16,46 @@ x-i18n: # Виявлення Bonjour / mDNS OpenClaw використовує Bonjour (mDNS / DNS‑SD) для виявлення активного Gateway (кінцевої точки WebSocket). -Багатоадресний перегляд `local.` — це **зручність лише для LAN**. Вбудований -plugin `bonjour` відповідає за рекламування в LAN і ввімкнений за замовчуванням. Для міжмережевого виявлення -той самий маяк також може публікуватися через налаштований домен DNS-SD широкої зони. -Виявлення все одно є best-effort і **не** замінює підключення через SSH або Tailnet. +Багатоадресний перегляд `local.` — це **лише зручність у межах LAN**. Вбудований Plugin `bonjour` +відповідає за рекламу в LAN і ввімкнений за замовчуванням. Для виявлення між різними мережами +той самий маяк також може публікуватися через налаштований домен wide-area DNS-SD. +Виявлення все одно виконується за принципом best-effort і **не** замінює підключення через SSH або Tailnet. -## Bonjour широкої зони (Unicast DNS-SD) через Tailscale +## Wide-area Bonjour (Unicast DNS-SD) через Tailscale -Якщо Node і Gateway перебувають у різних мережах, багатоадресний mDNS не перетне +Якщо node і gateway перебувають у різних мережах, багатоадресний mDNS не перетне цю межу. Ви можете зберегти той самий UX виявлення, переключившись на **unicast DNS‑SD** -("Bonjour широкої зони") через Tailscale. +("Wide‑Area Bonjour") через Tailscale. Загальні кроки: -1. Запустіть DNS-сервер на хості Gateway (доступний через Tailnet). +1. Запустіть DNS-сервер на хості gateway (доступний через Tailnet). 2. Опублікуйте записи DNS‑SD для `_openclaw-gw._tcp` у виділеній зоні (приклад: `openclaw.internal.`). -3. Налаштуйте в Tailscale **split DNS**, щоб вибраний вами домен резолвився через цей +3. Налаштуйте в Tailscale **split DNS**, щоб вибраний домен резолвився через цей DNS-сервер для клієнтів (зокрема iOS). OpenClaw підтримує будь-який домен виявлення; `openclaw.internal.` — лише приклад. -Node на iOS/Android переглядають і `local.`, і налаштований вами домен широкої зони. +Node iOS/Android переглядають і `local.`, і налаштований вами wide-area домен. ### Конфігурація Gateway (рекомендовано) ```json5 { gateway: { bind: "tailnet" }, // лише tailnet (рекомендовано) - discovery: { wideArea: { enabled: true } }, // вмикає публікацію DNS-SD широкої зони + discovery: { wideArea: { enabled: true } }, // вмикає публікацію wide-area DNS-SD } ``` -### Одноразове налаштування DNS-сервера (хост Gateway) +### Одноразове налаштування DNS-сервера (хост gateway) ```bash openclaw dns setup --apply ``` -Це встановить CoreDNS і налаштує його так, щоб він: +Це встановлює CoreDNS і налаштовує його так, щоб він: -- слухав порт 53 лише на інтерфейсах Tailscale Gateway +- слухав порт 53 лише на Tailscale-інтерфейсах gateway - обслуговував вибраний вами домен (приклад: `openclaw.internal.`) з `~/.openclaw/dns/.db` Перевірте з машини, підключеної до tailnet: @@ -67,57 +67,57 @@ dig @ -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short ### Налаштування DNS у Tailscale -У консолі адміністрування Tailscale: +У консолі адміністратора Tailscale: -- Додайте nameserver, що вказує на tailnet IP Gateway (UDP/TCP 53). +- Додайте nameserver, що вказує на tailnet IP gateway (UDP/TCP 53). - Додайте split DNS, щоб ваш домен виявлення використовував цей nameserver. -Після того як клієнти приймуть DNS tailnet, Node на iOS і виявлення через CLI зможуть переглядати -`_openclaw-gw._tcp` у вашому домені виявлення без багатоадресності. +Щойно клієнти приймуть DNS tailnet, node iOS і виявлення CLI зможуть переглядати +`_openclaw-gw._tcp` у вашому домені виявлення без багатоадресної передачі. ### Безпека слухача Gateway (рекомендовано) -Порт WS Gateway (типово `18789`) за замовчуванням прив’язується до loopback. Для доступу з LAN/tailnet +Порт WS Gateway (типово `18789`) за замовчуванням прив’язується до loopback. Для доступу через LAN/tailnet явно задайте прив’язку та залиште автентифікацію ввімкненою. Для конфігурацій лише з tailnet: - Установіть `gateway.bind: "tailnet"` у `~/.openclaw/openclaw.json`. -- Перезапустіть Gateway (або перезапустіть застосунок рядка меню macOS). +- Перезапустіть Gateway (або перезапустіть застосунок macOS у рядку меню). ## Що рекламується -Лише Gateway рекламує `_openclaw-gw._tcp`. Рекламування багатоадресності в LAN -забезпечується вбудованим plugin `bonjour`; публікація DNS-SD широкої зони й надалі +Лише Gateway рекламує `_openclaw-gw._tcp`. Багатоадресна реклама в LAN +забезпечується вбудованим Plugin `bonjour`; публікація wide-area DNS-SD і надалі належить Gateway. ## Типи сервісів -- `_openclaw-gw._tcp` — транспортний маяк gateway (використовується Node на macOS/iOS/Android). +- `_openclaw-gw._tcp` — маяк транспортного рівня gateway (використовується node macOS/iOS/Android). -## Ключі TXT (несекретні підказки) +## Ключі TXT (не секретні підказки) -Gateway рекламує невеликі несекретні підказки, щоб зробити UI-потоки зручнішими: +Gateway рекламує невеликі не секретні підказки, щоб зробити UI-потоки зручнішими: - `role=gateway` -- `displayName=<дружня назва>` +- `displayName=` - `lanHost=.local` -- `gatewayPort=` (WS + HTTP Gateway) -- `gatewayTls=1` (лише коли TLS увімкнено) -- `gatewayTlsSha256=` (лише коли TLS увімкнено і доступний відбиток) -- `canvasPort=` (лише коли ввімкнено хост canvas; наразі такий самий, як `gatewayPort`) +- `gatewayPort=` (Gateway WS + HTTP) +- `gatewayTls=1` (лише коли ввімкнено TLS) +- `gatewayTlsSha256=` (лише коли ввімкнено TLS і доступний відбиток) +- `canvasPort=` (лише коли ввімкнено canvas host; наразі збігається з `gatewayPort`) - `transport=gateway` -- `tailnetDns=` (лише у повному режимі mDNS, необов’язкова підказка, коли доступний Tailnet) -- `sshPort=` (лише у повному режимі mDNS; DNS-SD широкої зони може його не включати) -- `cliPath=` (лише у повному режимі mDNS; DNS-SD широкої зони все одно записує його як підказку для віддаленого встановлення) +- `tailnetDns=` (лише в режимі mDNS full, необов’язкова підказка, коли Tailnet доступний) +- `sshPort=` (лише в режимі mDNS full; wide-area DNS-SD може його не включати) +- `cliPath=` (лише в режимі mDNS full; wide-area DNS-SD усе одно записує його як підказку для віддаленого встановлення) Примітки щодо безпеки: -- Записи TXT у Bonjour/mDNS **неавтентифіковані**. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації. -- Клієнти повинні маршрутизувати за допомогою резолвленої кінцевої точки сервісу (SRV + A/AAAA). Розглядайте `lanHost`, `tailnetDns`, `gatewayPort` і `gatewayTlsSha256` лише як підказки. -- Автоматичне націлювання SSH так само повинно використовувати резолвлений хост сервісу, а не лише підказки з TXT. -- TLS pinning ніколи не повинен дозволяти рекламованому `gatewayTlsSha256` перевизначати раніше збережений pin. -- Node на iOS/Android повинні розглядати прямі підключення на основі виявлення як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка, побаченого вперше. +- Записи Bonjour/mDNS TXT **неавтентифіковані**. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації. +- Клієнти мають маршрутизувати трафік, використовуючи резолвлену кінцеву точку сервісу (SRV + A/AAAA). Сприймайте `lanHost`, `tailnetDns`, `gatewayPort` і `gatewayTlsSha256` лише як підказки. +- Автоматичне націлювання SSH так само має використовувати резолвлений хост сервісу, а не підказки лише з TXT. +- Прив’язка TLS ніколи не повинна дозволяти рекламованому `gatewayTlsSha256` перевизначати раніше збережену прив’язку. +- Node iOS/Android мають розглядати прямі підключення на основі виявлення як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка при першому використанні. ## Налагодження на macOS @@ -135,62 +135,66 @@ Gateway рекламує невеликі несекретні підказки, dns-sd -L "" _openclaw-gw._tcp local. ``` -Якщо перегляд працює, а резолв — ні, зазвичай це означає проблему з політикою LAN або -резолвером mDNS. +Якщо перегляд працює, а резолв — ні, зазвичай проблема в політиці LAN або +в резолвері mDNS. -## Налагодження в журналах Gateway +## Налагодження в логах Gateway -Gateway записує журнал у циклічний log-файл (виводиться під час запуску як -`gateway log file: ...`). Шукайте рядки `bonjour:`, особливо: +Gateway записує циклічний файл журналу (друкується під час запуску як +`gateway log file: ...`). Шукайте рядки `bonjour:`, зокрема: - `bonjour: advertise failed ...` - `bonjour: ... name conflict resolved` / `hostname conflict resolved` - `bonjour: watchdog detected non-announced service ...` - `bonjour: disabling advertiser after ... failed restarts ...` -## Налагодження на iOS Node +## Налагодження на node iOS -iOS Node використовує `NWBrowser` для виявлення `_openclaw-gw._tcp`. +Node iOS використовує `NWBrowser` для виявлення `_openclaw-gw._tcp`. -Щоб зібрати журнали: +Щоб зібрати логи: - Settings → Gateway → Advanced → **Discovery Debug Logs** - Settings → Gateway → Advanced → **Discovery Logs** → відтворіть проблему → **Copy** Журнал містить переходи стану браузера та зміни набору результатів. -## Поширені режими відмови +## Поширені режими відмов -- **Bonjour не працює між мережами**: використовуйте Tailnet або SSH. -- **Багатоадресність заблокована**: деякі мережі Wi‑Fi вимикають mDNS. -- **Рекламування застрягло на probing/announcing**: хости із заблокованою багатоадресністю, - мостами контейнерів, WSL або змінами інтерфейсів можуть залишити рекламувальник ciao у - стані без оголошення. OpenClaw повторює спробу кілька разів, а потім вимикає Bonjour - для поточного процесу Gateway замість безкінечного перезапуску рекламувальника. +- **Bonjour не працює між різними мережами**: використовуйте Tailnet або SSH. +- **Багатоадресна передача заблокована**: деякі Wi‑Fi мережі вимикають mDNS. +- **Рекламування зависло на probing/announcing**: хости із заблокованою багатоадресною передачею, + мости контейнерів, WSL або зміни інтерфейсів можуть залишити рекламодавець ciao у + стані non-announced. OpenClaw повторює спробу кілька разів, а потім вимикає Bonjour + для поточного процесу Gateway замість безкінечного перезапуску рекламодавця. +- **Мережа Docker bridge**: вбудований Docker Compose за замовчуванням вимикає Bonjour + через `OPENCLAW_DISABLE_BONJOUR=1`. Установлюйте `0` лише для host, + macvlan або іншої мережі з підтримкою mDNS. - **Сон / зміни інтерфейсів**: macOS може тимчасово втрачати результати mDNS; повторіть спробу. -- **Перегляд працює, а резолв — ні**: використовуйте прості назви машин (уникайте емодзі чи - розділових знаків), а потім перезапустіть Gateway. Ім’я екземпляра сервісу походить від - імені хоста, тому надто складні імена можуть заплутати деякі резолвери. +- **Перегляд працює, а резолв — ні**: використовуйте прості назви машин (уникайте емодзі або + пунктуації), а потім перезапустіть Gateway. Ім’я екземпляра сервісу походить від + імені хоста, тому надто складні імена можуть плутати деякі резолвери. ## Екрановані імена екземплярів (`\032`) -Bonjour/DNS‑SD часто екранує байти в іменах екземплярів сервісів як десяткові послідовності `\DDD` +Bonjour/DNS‑SD часто екранує байти в іменах екземплярів сервісу як десяткові послідовності `\DDD` (наприклад, пробіли стають `\032`). - Це нормально на рівні протоколу. -- UI повинні декодувати це для відображення (iOS використовує `BonjourEscapes.decode`). +- UI мають декодувати це для відображення (iOS використовує `BonjourEscapes.decode`). ## Вимкнення / конфігурація -- `openclaw plugins disable bonjour` вимикає рекламування багатоадресності в LAN, вимикаючи вбудований plugin. +- `openclaw plugins disable bonjour` вимикає багатоадресну рекламу в LAN, вимикаючи вбудований plugin. - `openclaw plugins enable bonjour` відновлює типовий plugin виявлення в LAN. -- `OPENCLAW_DISABLE_BONJOUR=1` вимикає рекламування багатоадресності в LAN без зміни конфігурації plugin; допустимі truthy-значення: `1`, `true`, `yes` і `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`). +- `OPENCLAW_DISABLE_BONJOUR=1` вимикає багатоадресну рекламу в LAN без зміни конфігурації plugin; підтримувані truthy-значення: `1`, `true`, `yes` і `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`). +- Docker Compose за замовчуванням установлює `OPENCLAW_DISABLE_BONJOUR=1` для bridge networking; перевизначайте на `OPENCLAW_DISABLE_BONJOUR=0` лише коли доступна багатоадресна передача mDNS. - `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом прив’язки Gateway. - `OPENCLAW_SSH_PORT` перевизначає порт SSH, коли рекламується `sshPort` (legacy: `OPENCLAW_SSH_PORT`). -- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено повний режим mDNS (legacy: `OPENCLAW_TAILNET_DNS`). +- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено режим mDNS full (legacy: `OPENCLAW_TAILNET_DNS`). - `OPENCLAW_CLI_PATH` перевизначає рекламований шлях CLI (legacy: `OPENCLAW_CLI_PATH`). -## Пов’язана документація +## Пов’язані документи - Політика виявлення та вибір транспорту: [Виявлення](/uk/gateway/discovery) -- Спарювання Node + схвалення: [Спарювання Gateway](/uk/gateway/pairing) +- Парування node та схвалення: [Парування Gateway](/uk/gateway/pairing) diff --git a/docs/uk/gateway/discovery.md b/docs/uk/gateway/discovery.md index fcf118503..ca7ceea62 100644 --- a/docs/uk/gateway/discovery.md +++ b/docs/uk/gateway/discovery.md @@ -1,35 +1,35 @@ --- read_when: - Реалізація або зміна виявлення/оголошення Bonjour - - Налаштування режимів віддаленого з’єднання (пряме чи SSH) - - Проєктування виявлення Node + спарювання для віддалених вузлів -summary: Виявлення Node і транспорти (Bonjour, Tailscale, SSH) для пошуку gateway + - Налаштування режимів віддаленого підключення (напряму чи через SSH) + - Проєктування виявлення Node та сполучення для віддалених вузлів +summary: Виявлення Node і транспорти (Bonjour, Tailscale, SSH) для пошуку Gateway title: Виявлення та транспорти x-i18n: - generated_at: "2026-04-24T03:16:22Z" + generated_at: "2026-04-26T04:54:57Z" model: gpt-5.4 provider: openai - source_hash: 684e5aeb1f74a90bf8689f8b25830be2c9e497fcdeda390d98f204d7cb4134b8 + source_hash: 615be0f501470772c257beb8e798c522c108b09081a603f44218404277fdf269 source_path: gateway/discovery.md workflow: 15 --- # Виявлення та транспорти -OpenClaw має дві різні проблеми, які на поверхні виглядають схожими: +В OpenClaw є дві окремі проблеми, які на перший погляд виглядають схоже: -1. **Віддалене керування оператором**: застосунок рядка меню macOS керує gateway, що працює в іншому місці. -2. **Спарювання Node**: iOS/Android (і майбутні вузли) знаходять gateway і безпечно спаровуються. +1. **Віддалене керування оператором**: застосунок macOS у рядку меню керує Gateway, що працює деінде. +2. **Сполучення Node**: iOS/Android (і майбутні вузли) знаходять Gateway і безпечно сполучаються з ним. -Мета дизайну — зберігати все мережеве виявлення/оголошення в **Node Gateway** (`openclaw gateway`) і залишати клієнти (mac app, iOS) споживачами. +Мета дизайну — зберегти все мережеве виявлення/оголошення в **Node Gateway** (`openclaw gateway`) і залишити клієнти (mac-застосунок, iOS) споживачами. ## Терміни -- **Gateway**: один довготривалий процес gateway, який володіє станом (сесії, спарювання, реєстр вузлів) і запускає канали. У більшості конфігурацій використовується один на хост; ізольовані конфігурації з кількома gateway також можливі. -- **Gateway WS (control plane)**: endpoint WebSocket на `127.0.0.1:18789` типово; може бути прив’язаний до LAN/tailnet через `gateway.bind`. -- **Direct WS transport**: endpoint Gateway WS, доступний з LAN/tailnet (без SSH). -- **SSH transport (fallback)**: віддалене керування через переспрямування `127.0.0.1:18789` через SSH. -- **Legacy TCP bridge (removed)**: старіший транспорт вузлів (див. +- **Gateway**: один довготривалий процес Gateway, який володіє станом (сеанси, сполучення, реєстр вузлів) і запускає канали. У більшості конфігурацій використовується один на хост; можливі ізольовані конфігурації з кількома Gateway. +- **Gateway WS (площина керування)**: WebSocket-ендпойнт на `127.0.0.1:18789` за замовчуванням; може бути прив’язаний до LAN/tailnet через `gateway.bind`. +- **Прямий транспорт WS**: Gateway WS-ендпойнт, доступний із LAN/tailnet (без SSH). +- **Транспорт SSH (резервний варіант)**: віддалене керування через переадресацію `127.0.0.1:18789` поверх SSH. +- **Застарілий TCP-міст (видалений)**: старіший транспорт вузлів (див. [Протокол Bridge](/uk/gateway/bridge-protocol)); більше не оголошується для виявлення і більше не є частиною поточних збірок. @@ -38,86 +38,89 @@ OpenClaw має дві різні проблеми, які на поверхні - [Протокол Gateway](/uk/gateway/protocol) - [Протокол Bridge (застарілий)](/uk/gateway/bridge-protocol) -## Чому ми зберігаємо і "direct", і SSH +## Чому ми зберігаємо і «прямий», і SSH -- **Direct WS** забезпечує найкращий UX в одній мережі та в межах tailnet: +- **Прямий WS** забезпечує найкращий UX в одній мережі та в межах tailnet: - автоматичне виявлення в LAN через Bonjour - - токени спарювання + ACL, якими володіє gateway - - не потрібен доступ до оболонки; поверхня протоколу може залишатися вузькою та придатною до аудиту + - токени сполучення + ACL, якими керує Gateway + - доступ до оболонки не потрібен; поверхня протоколу може залишатися вузькою й придатною для аудиту - **SSH** залишається універсальним резервним варіантом: - - працює всюди, де у вас є доступ SSH (навіть у різних, не пов’язаних між собою мережах) - - переживає проблеми multicast/mDNS + - працює всюди, де у вас є доступ по SSH (навіть через не пов’язані між собою мережі) + - переживає проблеми з multicast/mDNS - не потребує нових вхідних портів, окрім SSH -## Джерела виявлення (як клієнти дізнаються, де знаходиться gateway) +## Вхідні джерела виявлення (як клієнти дізнаються, де знаходиться Gateway) -### 1) Виявлення Bonjour / DNS-SD +### 1) Виявлення через Bonjour / DNS-SD Multicast Bonjour працює за принципом best-effort і не перетинає межі мереж. OpenClaw також може переглядати -той самий маяк gateway через налаштований wide-area домен DNS-SD, тому виявлення може охоплювати: +той самий маяк Gateway через налаштований домен wide-area DNS-SD, тож виявлення може охоплювати: -- `local.` в тій самій LAN -- налаштований unicast домен DNS-SD для виявлення між мережами +- `local.` у тій самій LAN +- налаштований домен unicast DNS-SD для міжмережевого виявлення -Цільовий напрямок: +Цільовий напрям: -- **gateway** оголошує свій endpoint WS через Bonjour. -- Клієнти переглядають і показують список “виберіть gateway”, а потім зберігають вибраний endpoint. +- **Gateway** оголошує свій WS-ендпойнт через Bonjour. +- Клієнти переглядають і показують список «виберіть Gateway», а потім зберігають вибраний ендпойнт. -Деталі усунення несправностей і маяка: [Bonjour](/uk/gateway/bonjour). +Подробиці щодо усунення несправностей і маяка: [Bonjour](/uk/gateway/bonjour). -#### Деталі маяка сервісу +#### Подробиці маяка служби -- Типи сервісів: +- Типи служб: - `_openclaw-gw._tcp` (маяк транспорту gateway) - Ключі TXT (не секретні): - `role=gateway` - `transport=gateway` - - `displayName=` (зрозуміла користувачу назва, налаштована оператором) + - `displayName=` (зрозуміле ім’я, налаштоване оператором) - `lanHost=.local` - `gatewayPort=18789` (Gateway WS + HTTP) - `gatewayTls=1` (лише коли TLS увімкнено) - `gatewayTlsSha256=` (лише коли TLS увімкнено і відбиток доступний) - - `canvasPort=` (порт хоста canvas; наразі той самий, що й `gatewayPort`, коли хост canvas увімкнено) + - `canvasPort=` (порт canvas host; наразі збігається з `gatewayPort`, коли canvas host увімкнено) - `tailnetDns=` (необов’язкова підказка; визначається автоматично, коли доступний Tailscale) - - `sshPort=` (лише в повному режимі mDNS; wide-area DNS-SD може його пропускати, і тоді типовим SSH лишається `22`) - - `cliPath=` (лише в повному режимі mDNS; wide-area DNS-SD усе одно записує його як підказку для віддаленого встановлення) + - `sshPort=` (лише в повному режимі mDNS; wide-area DNS-SD може його не включати, у такому разі для SSH залишаються типові значення `22`) + - `cliPath=` (лише в повному режимі mDNS; wide-area DNS-SD все одно записує його як підказку для віддаленого встановлення) Примітки щодо безпеки: -- TXT-записи Bonjour/mDNS **неавтентифіковані**. Клієнти повинні трактувати значення TXT лише як UX-підказки. -- Маршрутизація (host/port) має надавати перевагу **визначеному endpoint сервісу** (SRV + A/AAAA), а не значенням `lanHost`, `tailnetDns` або `gatewayPort`, наданим через TXT. -- Закріплення TLS ніколи не повинно дозволяти оголошеному `gatewayTlsSha256` перевизначати раніше збережений pin. -- Вузли iOS/Android повинні вимагати явного підтвердження “довіряти цьому fingerprint” перед збереженням pin при першому підключенні (перевірка поза каналом), коли обраний маршрут є захищеним/заснованим на TLS. +- TXT-записи Bonjour/mDNS **не автентифіковані**. Клієнти повинні розглядати значення TXT лише як UX-підказки. +- Для маршрутизації (хост/порт) слід надавати перевагу **розв’язаному ендпойнту служби** (SRV + A/AAAA), а не переданим через TXT `lanHost`, `tailnetDns` чи `gatewayPort`. +- TLS pinning ніколи не повинен дозволяти оголошеному `gatewayTlsSha256` перевизначати раніше збережений pin. +- Вузли iOS/Android повинні вимагати явного підтвердження «довіряти цьому відбитку» перед збереженням pin під час першого підключення (перевірка поза каналом), коли вибраний маршрут є безпечним/на основі TLS. Вимкнення/перевизначення: - `OPENCLAW_DISABLE_BONJOUR=1` вимикає оголошення. +- Docker Compose типово використовує `OPENCLAW_DISABLE_BONJOUR=1`, оскільки мережі bridge + зазвичай не передають multicast mDNS надійно; використовуйте `0` лише на host, macvlan + або в іншій мережі з підтримкою mDNS. - `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом прив’язки Gateway. -- `OPENCLAW_SSH_PORT` перевизначає порт SSH, який оголошується, коли виводиться `sshPort`. +- `OPENCLAW_SSH_PORT` перевизначає SSH-порт, що оголошується, коли виводиться `sshPort`. - `OPENCLAW_TAILNET_DNS` публікує підказку `tailnetDns` (MagicDNS). - `OPENCLAW_CLI_PATH` перевизначає оголошений шлях CLI. -### 2) Tailnet (міжмережевий сценарій) +### 2) Tailnet (міжмережевий) -Для конфігурацій у стилі Лондон/Відень Bonjour не допоможе. Рекомендована ціль “direct” така: +Для конфігурацій у стилі London/Vienna Bonjour не допоможе. Рекомендована «пряма» ціль: -- ім’я Tailscale MagicDNS (бажано) або стабільна IP-адреса tailnet. +- ім’я Tailscale MagicDNS (переважно) або стабільна tailnet IP-адреса. -Якщо gateway може визначити, що він працює під Tailscale, він публікує `tailnetDns` як необов’язкову підказку для клієнтів (зокрема для wide-area маяків). +Якщо Gateway може визначити, що працює під Tailscale, він публікує `tailnetDns` як необов’язкову підказку для клієнтів (зокрема wide-area beacon). -Застосунок macOS тепер надає перевагу іменам MagicDNS над сирими IP-адресами Tailscale для виявлення gateway. Це підвищує надійність, коли IP-адреси tailnet змінюються (наприклад, після перезапуску вузлів або перепризначення CGNAT), тому що імена MagicDNS автоматично визначають поточну IP-адресу. +MacOS-застосунок тепер віддає перевагу іменам MagicDNS над сирими Tailscale IP-адресами для виявлення gateway. Це підвищує надійність, коли tailnet IP-адреси змінюються (наприклад після перезапуску вузлів або повторного призначення CGNAT), тому що імена MagicDNS автоматично розв’язуються в поточну IP-адресу. -Для спарювання мобільних вузлів підказки виявлення не послаблюють безпеку транспорту на маршрутах tailnet/public: +Для сполучення мобільних вузлів підказки виявлення не послаблюють безпеку транспорту на tailnet/public маршрутах: -- iOS/Android усе ще вимагають захищений шлях першого підключення через tailnet/public (`wss://` або Tailscale Serve/Funnel). -- Виявлена сира IP-адреса tailnet — це підказка маршрутизації, а не дозвіл використовувати відкритий віддалений `ws://`. -- Пряме підключення `ws://` у приватній LAN, як і раніше, підтримується. -- Якщо вам потрібен найпростіший шлях Tailscale для мобільних вузлів, використовуйте Tailscale Serve, щоб і виявлення, і код налаштування визначали той самий захищений endpoint MagicDNS. +- iOS/Android, як і раніше, вимагають безпечний шлях першого підключення через tailnet/public (`wss://` або Tailscale Serve/Funnel). +- Виявлена сира tailnet IP-адреса є підказкою для маршрутизації, а не дозволом використовувати відкритий віддалений `ws://`. +- Пряме підключення через приватну LAN по `ws://` як і раніше підтримується. +- Якщо вам потрібен найпростіший шлях Tailscale для мобільних вузлів, використовуйте Tailscale Serve, щоб і виявлення, і код налаштування розв’язувалися до того самого безпечного ендпойнта MagicDNS. -### 3) Ручна / SSH-ціль +### 3) Ручна ціль / SSH -Коли прямого маршруту немає (або direct вимкнено), клієнти завжди можуть підключитися через SSH, переспрямувавши loopback-порт gateway. +Коли прямий маршрут недоступний (або пряме підключення вимкнено), клієнти завжди можуть підключитися через SSH, переадресувавши loopback-порт gateway. Див. [Віддалений доступ](/uk/gateway/remote). @@ -125,30 +128,30 @@ Multicast Bonjour працює за принципом best-effort і не пе Рекомендована поведінка клієнта: -1. Якщо налаштовано спарений direct-endpoint і він доступний, використовуйте його. -2. Інакше, якщо виявлення знаходить gateway у `local.` або в налаштованому wide-area домені, запропонуйте вибір “Використовувати цей gateway” в один дотик і збережіть його як direct-endpoint. -3. Інакше, якщо налаштовано DNS/IP tailnet, спробуйте direct. - Для мобільних вузлів на маршрутах tailnet/public direct означає захищений endpoint, а не відкритий віддалений `ws://`. +1. Якщо налаштовано сполучений прямий ендпойнт і він доступний, використовуйте його. +2. Інакше, якщо виявлення знаходить Gateway у `local.` або в налаштованому wide-area domain, запропонуйте варіант «Використовувати цей Gateway» в один дотик і збережіть його як прямий ендпойнт. +3. Інакше, якщо налаштовано DNS/IP tailnet, спробуйте пряме підключення. + Для мобільних вузлів на tailnet/public маршрутах пряме підключення означає безпечний ендпойнт, а не відкритий віддалений `ws://`. 4. Інакше поверніться до SSH. -## Спарювання + автентифікація (direct transport) +## Сполучення + автентифікація (прямий транспорт) -gateway є джерелом істини для допуску вузлів/клієнтів. +Gateway є джерелом істини для допуску вузлів/клієнтів. -- Запити на спарювання створюються/схвалюються/відхиляються в gateway (див. [Спарювання Gateway](/uk/gateway/pairing)). -- gateway забезпечує: +- Запити на сполучення створюються/схвалюються/відхиляються в Gateway (див. [Сполучення Gateway](/uk/gateway/pairing)). +- Gateway забезпечує: - автентифікацію (токен / keypair) - - області дії/ACL (gateway не є сирим проксі до кожного методу) + - області дії/ACL (Gateway не є сирим проксі до кожного методу) - обмеження швидкості -## Відповідальність за компонентами +## Зони відповідальності за компонентами -- **Gateway**: оголошує маяки виявлення, володіє рішеннями про спарювання та розміщує endpoint WS. -- **macOS app**: допомагає вибрати gateway, показує запити на спарювання і використовує SSH лише як резервний варіант. -- **iOS/Android nodes**: переглядають Bonjour для зручності та підключаються до спареного Gateway WS. +- **Gateway**: оголошує маяки виявлення, володіє рішеннями щодо сполучення та хостить WS-ендпойнт. +- **macOS-застосунок**: допомагає вибрати Gateway, показує запити на сполучення та використовує SSH лише як резервний варіант. +- **Вузли iOS/Android**: переглядають Bonjour для зручності й підключаються до сполученого Gateway WS. ## Пов’язане - [Віддалений доступ](/uk/gateway/remote) - [Tailscale](/uk/gateway/tailscale) -- [Виявлення Bonjour](/uk/gateway/bonjour) +- [Виявлення через Bonjour](/uk/gateway/bonjour) diff --git a/docs/uk/install/docker.md b/docs/uk/install/docker.md index 0f8168490..45460740f 100644 --- a/docs/uk/install/docker.md +++ b/docs/uk/install/docker.md @@ -1,46 +1,46 @@ --- read_when: - - Вам потрібен контейнеризований Gateway замість локальних встановлень - - Ви перевіряєте процес роботи з Docker + - Ви хочете контейнеризований Gateway замість локальних встановлень + - Ви перевіряєте потік Docker summary: Необов’язкове налаштування та онбординг OpenClaw на основі Docker title: Docker x-i18n: - generated_at: "2026-04-23T23:00:30Z" + generated_at: "2026-04-26T04:54:58Z" model: gpt-5.4 provider: openai - source_hash: ee6bfd2d4ad8b4629c5077d401b8fec36e71b250da3cccdd9ec3cb9c2abbdfc2 + source_hash: 9b2d73da68266946f62feca240bdd94336a3f15e9ca48f0a52209f4ae4a85ffe source_path: install/docker.md workflow: 15 --- -Docker **необов’язковий**. Використовуйте його лише якщо вам потрібен контейнеризований Gateway або ви хочете перевірити процес роботи з Docker. +Docker **необов’язковий**. Використовуйте його лише якщо хочете контейнеризований Gateway або перевірити потік Docker. ## Чи підходить мені Docker? - **Так**: вам потрібне ізольоване, тимчасове середовище Gateway або ви хочете запускати OpenClaw на хості без локальних встановлень. -- **Ні**: ви працюєте на власному комп’ютері й просто хочете найшвидший цикл розробки. Натомість використовуйте звичайний процес встановлення. -- **Примітка про sandboxing**: типовий backend sandbox використовує Docker, коли sandboxing увімкнено, але sandboxing типово вимкнений і **не** вимагає, щоб увесь Gateway працював у Docker. Також доступні backend-и sandbox SSH і OpenShell. Див. [Sandboxing](/uk/gateway/sandboxing). +- **Ні**: ви запускаєте на власній машині й просто хочете найшвидший цикл розробки. Натомість використовуйте звичайний потік встановлення. +- **Примітка щодо ізоляції**: типовий бекенд sandbox використовує Docker, коли ізоляцію ввімкнено, але за замовчуванням ізоляція вимкнена і **не** вимагає запуску всього Gateway у Docker. Також доступні бекенди sandbox SSH і OpenShell. Див. [Ізоляція](/uk/gateway/sandboxing). ## Передумови - Docker Desktop (або Docker Engine) + Docker Compose v2 -- Щонайменше 2 ГБ RAM для збирання образу (`pnpm install` може бути примусово завершено через OOM на хостах із 1 ГБ з кодом виходу 137) -- Достатньо місця на диску для образів і журналів -- Якщо ви запускаєте на VPS/публічному хості, перегляньте - [Посилення безпеки для мережевої експозиції](/uk/gateway/security), - особливо політику firewall Docker `DOCKER-USER`. +- Щонайменше 2 ГБ RAM для збирання образу (`pnpm install` може бути завершено через OOM на хостах із 1 ГБ з кодом виходу 137) +- Достатньо дискового простору для образів і журналів +- Якщо запускаєте на VPS/публічному хості, перегляньте + [Посилення безпеки для мережевої доступності](/uk/gateway/security), + особливо політику файрвола Docker `DOCKER-USER`. ## Контейнеризований Gateway - Із кореня репозиторію запустіть сценарій налаштування: + У корені репозиторію запустіть скрипт налаштування: ```bash ./scripts/docker/setup.sh ``` - Це локально збирає образ gateway. Щоб натомість використати попередньо зібраний образ: + Це локально збере образ Gateway. Щоб натомість використовувати попередньо зібраний образ: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" @@ -54,24 +54,24 @@ Docker **необов’язковий**. Використовуйте його - Сценарій налаштування автоматично запускає онбординг. Він: + Скрипт налаштування запускає онбординг автоматично. Він: - - запропонує ввести API-ключі провайдерів - - згенерує токен gateway і запише його в `.env` - - запустить gateway через Docker Compose + - запросить API-ключі провайдерів + - згенерує токен Gateway і запише його в `.env` + - запустить Gateway через Docker Compose - Під час налаштування онбординг перед запуском і записи конфігурації виконуються через - `openclaw-gateway` напряму. `openclaw-cli` призначено для команд, які ви запускаєте вже після - того, як контейнер gateway існує. + Під час налаштування передстартовий онбординг і запис конфігурації виконуються + безпосередньо через `openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте після того, + як контейнер gateway уже існує. - Відкрийте `http://127.0.0.1:18789/` у браузері й вставте налаштований - спільний секрет у Settings. Сценарій налаштування типово записує токен у `.env`; якщо ви перемкнете конфігурацію контейнера на автентифікацію паролем, використовуйте натомість цей + Відкрийте `http://127.0.0.1:18789/` у браузері та вставте налаштований + спільний секрет у Settings. Скрипт налаштування за замовчуванням записує токен у `.env`; якщо ви перемкнете конфігурацію контейнера на автентифікацію паролем, використовуйте натомість цей пароль. - Потрібен URL ще раз? + Потрібна URL-адреса знову? ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -80,7 +80,7 @@ Docker **необов’язковий**. Використовуйте його - Використовуйте контейнер CLI, щоб додати канали повідомлень: + Використовуйте контейнер CLI, щоб додати канали обміну повідомленнями: ```bash # WhatsApp (QR) @@ -98,9 +98,9 @@ Docker **необов’язковий**. Використовуйте його -### Ручний процес +### Ручний потік -Якщо ви віддаєте перевагу виконанню кожного кроку самостійно замість використання сценарію налаштування: +Якщо ви віддаєте перевагу запуску кожного кроку вручну замість використання скрипта налаштування: ```bash docker build -t openclaw:local -f Dockerfile . @@ -113,105 +113,117 @@ docker compose up -d openclaw-gateway Запускайте `docker compose` з кореня репозиторію. Якщо ви ввімкнули `OPENCLAW_EXTRA_MOUNTS` -або `OPENCLAW_HOME_VOLUME`, сценарій налаштування записує `docker-compose.extra.yml`; +або `OPENCLAW_HOME_VOLUME`, скрипт налаштування записує `docker-compose.extra.yml`; додавайте його через `-f docker-compose.yml -f docker-compose.extra.yml`. Оскільки `openclaw-cli` спільно використовує мережевий простір імен `openclaw-gateway`, це інструмент після запуску. До `docker compose up -d openclaw-gateway` запускайте онбординг -і записи конфігурації на етапі налаштування через `openclaw-gateway` з +і записи конфігурації під час налаштування через `openclaw-gateway` з `--no-deps --entrypoint node`. ### Змінні середовища -Сценарій налаштування приймає такі необов’язкові змінні середовища: +Скрипт налаштування приймає такі необов’язкові змінні середовища: -| Змінна | Призначення | -| ----------------------------- | -------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | Використати віддалений образ замість локального збирання | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Установити додаткові apt-пакети під час збирання (назви через пробіл) | -| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності Plugin-ів під час збирання (назви через пробіл) | -| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mount-и хоста (через кому у форматі `source:target[:opts]`) | -| `OPENCLAW_HOME_VOLUME` | Зберігати `/home/node` в іменованому Docker volume | -| `OPENCLAW_SANDBOX` | Добровільно ввімкнути bootstrap sandbox (`1`, `true`, `yes`, `on`) | -| `OPENCLAW_DOCKER_SOCKET` | Перевизначити шлях до сокета Docker | +| Variable | Purpose | +| ------------------------------ | --------------------------------------------------------------- | +| `OPENCLAW_IMAGE` | Використовувати віддалений образ замість локального збирання | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Встановити додаткові apt-пакети під час збирання (імена через пробіл) | +| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності плагінів під час збирання (імена через пробіл) | +| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mounts хоста (через кому у форматі `source:target[:opts]`) | +| `OPENCLAW_HOME_VOLUME` | Зберігати `/home/node` в іменованому Docker volume | +| `OPENCLAW_SANDBOX` | Увімкнути bootstrap sandbox (`1`, `true`, `yes`, `on`) | +| `OPENCLAW_DOCKER_SOCKET` | Перевизначити шлях до Docker socket | +| `OPENCLAW_DISABLE_BONJOUR` | Вимкнути рекламу Bonjour/mDNS (для Docker за замовчуванням `1`) | -### Перевірки стану +### Перевірки здоров’я -Endpoint-и probe контейнера (автентифікація не потрібна): +Кінцеві точки probe контейнера (автентифікація не потрібна): ```bash curl -fsS http://127.0.0.1:18789/healthz # liveness curl -fsS http://127.0.0.1:18789/readyz # readiness ``` -Docker image містить вбудований `HEALTHCHECK`, який опитує `/healthz`. +Образ Docker містить вбудований `HEALTHCHECK`, який виконує ping до `/healthz`. Якщо перевірки постійно не проходять, Docker позначає контейнер як `unhealthy`, і системи оркестрації можуть перезапустити або замінити його. -Автентифікований глибокий знімок стану: +Автентифікований глибокий знімок стану здоров’я: ```bash docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" ``` -### LAN vs loopback +### LAN чи loopback -`scripts/docker/setup.sh` типово встановлює `OPENCLAW_GATEWAY_BIND=lan`, щоб доступ хоста до -`http://127.0.0.1:18789` працював із публікацією портів Docker. +`scripts/docker/setup.sh` за замовчуванням встановлює `OPENCLAW_GATEWAY_BIND=lan`, щоб +доступ хоста до `http://127.0.0.1:18789` працював із публікацією порту Docker. -- `lan` (типово): браузер хоста і CLI хоста можуть досягати опублікованого порту gateway. +- `lan` (за замовчуванням): браузер хоста і CLI хоста можуть досягати опублікованого порту gateway. - `loopback`: лише процеси всередині мережевого простору імен контейнера можуть - безпосередньо досягати gateway. + напряму досягати gateway. Використовуйте значення режиму bind у `gateway.bind` (`lan` / `loopback` / `custom` / -`tailnet` / `auto`), а не псевдоніми хоста на кшталт `0.0.0.0` чи `127.0.0.1`. +`tailnet` / `auto`), а не хост-аліаси на кшталт `0.0.0.0` чи `127.0.0.1`. -### Сховище і збереження даних +### Bonjour / mDNS -Docker Compose монтує `OPENCLAW_CONFIG_DIR` у `/home/node/.openclaw`, а -`OPENCLAW_WORKSPACE_DIR` у `/home/node/.openclaw/workspace`, тому ці шляхи +Мережа мосту Docker зазвичай ненадійно пересилає багатокастовий трафік Bonjour/mDNS +(`224.0.0.251:5353`). Тому комплектна конфігурація Compose за замовчуванням встановлює +`OPENCLAW_DISABLE_BONJOUR=1`, щоб Gateway не потрапляв у crash-loop і не +перезапускав рекламу повторно, коли міст втрачає багатокастовий трафік. + +Для хостів Docker використовуйте опубліковану URL-адресу Gateway, Tailscale або DNS-SD широкої зони. +Встановлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише під час роботи з host networking, macvlan +або іншою мережею, де багатокастовий mDNS точно працює. + +### Сховище та збереження даних + +Docker Compose виконує bind-mount `OPENCLAW_CONFIG_DIR` до `/home/node/.openclaw` і +`OPENCLAW_WORKSPACE_DIR` до `/home/node/.openclaw/workspace`, тож ці шляхи зберігаються після заміни контейнера. У цьому змонтованому каталозі конфігурації OpenClaw зберігає: - `openclaw.json` для конфігурації поведінки - `agents//agent/auth-profiles.json` для збереженої OAuth/API-key автентифікації провайдера -- `.env` для секретів runtime із середовища, таких як `OPENCLAW_GATEWAY_TOKEN` +- `.env` для секретів середовища виконання, що передаються через env, як-от `OPENCLAW_GATEWAY_TOKEN` -Повні подробиці про збереження даних у розгортаннях на VM див. -в [Docker VM Runtime - What persists where](/uk/install/docker-vm-runtime#what-persists-where). +Повні відомості про збереження даних у розгортаннях на VM див. у +[Docker VM Runtime - Що і де зберігається](/uk/install/docker-vm-runtime#what-persists-where). -**Гарячі точки зростання диска:** стежте за `media/`, файлами JSONL сесій, `cron/runs/*.jsonl`, -і циклічними файловими журналами в `/tmp/openclaw/`. +**Точки росту використання диска:** стежте за `media/`, файлами JSONL сеансів, `cron/runs/*.jsonl`, +і ротаційними файловими журналами в `/tmp/openclaw/`. -### Допоміжні shell-скрипти (необов’язково) +### Допоміжні команди shell (необов’язково) -Для простішого повсякденного керування Docker установіть `ClawDock`: +Для зручнішого повсякденного керування Docker встановіть `ClawDock`: ```bash mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -Якщо ви встановили ClawDock зі старого сирого шляху `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте команду встановлення вище, щоб ваш локальний файл helper відстежував нове розташування. +Якщо ви встановили ClawDock зі старого raw-шляху `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте наведену вище команду встановлення, щоб локальний файл helper відстежував нове розташування. Після цього використовуйте `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` тощо. Запустіть -`clawdock-help`, щоб побачити всі команди. -Повний посібник із helper див. у [ClawDock](/uk/install/clawdock). +`clawdock-help`, щоб переглянути всі команди. +Повний посібник із helper-команд див. у [ClawDock](/uk/install/clawdock). - + ```bash export OPENCLAW_SANDBOX=1 ./scripts/docker/setup.sh ``` - Користувацький шлях до сокета (наприклад, rootless Docker): + Власний шлях до socket (наприклад, rootless Docker): ```bash export OPENCLAW_SANDBOX=1 @@ -219,14 +231,14 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - Сценарій монтує `docker.sock` лише після того, як пройдено передумови sandbox. Якщо - налаштування sandbox не може завершитися, сценарій скидає `agents.defaults.sandbox.mode` - до `off`. + Скрипт монтує `docker.sock` лише після успішного проходження передумов sandbox. Якщо + налаштування sandbox не вдається завершити, скрипт скидає `agents.defaults.sandbox.mode` + на `off`. - Вимкніть виділення псевдо-TTY у Compose через `-T`: + Вимкніть виділення псевдо-TTY Compose за допомогою `-T`: ```bash docker compose run -T --rm openclaw-cli gateway probe @@ -235,16 +247,16 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - `openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тому CLI-команди - можуть досягати gateway через `127.0.0.1`. Розглядайте це як спільну - межу довіри. Конфігурація compose скидає `NET_RAW`/`NET_ADMIN` і вмикає + + `openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тож CLI + команди можуть досягати gateway через `127.0.0.1`. Розглядайте це як спільну + межу довіри. Конфігурація compose видаляє `NET_RAW`/`NET_ADMIN` і вмикає `no-new-privileges` для `openclaw-cli`. - - Образ працює як `node` (uid 1000). Якщо ви бачите помилки доступу до - `/home/node/.openclaw`, переконайтеся, що ваші bind mount-и хоста належать uid 1000: + + Образ працює від імені `node` (uid 1000). Якщо ви бачите помилки дозволів для + `/home/node/.openclaw`, переконайтеся, що ваші bind mounts хоста належать uid 1000: ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -253,8 +265,8 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - Упорядкуйте свій Dockerfile так, щоб шари залежностей кешувалися. Це дає змогу уникнути повторного запуску - `pnpm install`, якщо lockfile-и не змінювалися: + Упорядкуйте Dockerfile так, щоб шари залежностей кешувалися. Це дозволяє уникнути повторного запуску + `pnpm install`, доки lockfile не зміниться: ```dockerfile FROM node:24-bookworm @@ -276,61 +288,61 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - Типовий образ орієнтований на безпеку й працює як непривілейований `node`. Для більш + + Типовий образ орієнтований на безпеку й працює від непривілейованого `node`. Для більш функціонального контейнера: 1. **Зберігайте `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"` 2. **Вбудуйте системні залежності**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` - 3. **Установіть браузери Playwright**: + 3. **Встановіть браузери Playwright**: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` - 4. **Зберігайте завантаження браузерів**: задайте + 4. **Зберігайте завантаження браузера**: встановіть `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` і використовуйте `OPENCLAW_HOME_VOLUME` або `OPENCLAW_EXTRA_MOUNTS`. - - Якщо ви вибираєте OpenAI Codex OAuth у майстрі, він відкриває URL у браузері. У - Docker або headless-конфігураціях скопіюйте повний redirect URL, на який ви потрапите, і вставте - його назад у майстер, щоб завершити автентифікацію. + + Якщо у майстрі ви оберете OAuth OpenAI Codex, він відкриє URL-адресу в браузері. У + Docker або headless-середовищах скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте + її назад у майстер, щоб завершити автентифікацію. - Основний Docker image використовує `node:24-bookworm` і публікує анотації OCI базового образу, - включно з `org.opencontainers.image.base.name`, - `org.opencontainers.image.source` та іншими. Див. - [Анотації OCI image](https://github.com/opencontainers/image-spec/blob/main/annotations.md). + Основний образ Docker використовує `node:24-bookworm` і публікує анотації OCI базового образу, + зокрема `org.opencontainers.image.base.name`, + `org.opencontainers.image.source` та інші. Див. + [Анотації образу OCI](https://github.com/opencontainers/image-spec/blob/main/annotations.md). ### Запуск на VPS? Див. [Hetzner (Docker VPS)](/uk/install/hetzner) і -[Docker VM Runtime](/uk/install/docker-vm-runtime) для кроків розгортання на спільних VM, -включно з вбудовуванням бінарних файлів, збереженням даних і оновленнями. +[Docker VM Runtime](/uk/install/docker-vm-runtime) для кроків розгортання на спільній VM, +зокрема підготовки бінарних файлів, збереження даних і оновлень. -## Agent Sandbox +## Sandbox агента -Коли `agents.defaults.sandbox` увімкнено з backend Docker, gateway -виконує інструменти агента (shell, читання/запис файлів тощо) всередині ізольованих Docker -контейнерів, тоді як сам gateway залишається на хості. Це створює жорстку межу -навколо недовірених або багатокористувацьких сесій агента без контейнеризації всього +Коли `agents.defaults.sandbox` увімкнено з Docker-бекендом, gateway +запускає виконання інструментів агента (shell, читання/запис файлів тощо) в ізольованих Docker +контейнерах, тоді як сам gateway залишається на хості. Це створює жорстку межу +навколо недовірених або багатокористувацьких сеансів агентів без контейнеризації всього gateway. -Обсяг sandbox може бути на рівні агента (типово), сесії або спільний. Кожен scope -отримує власний робочий простір, змонтований у `/workspace`. Ви також можете налаштувати -політики allow/deny для інструментів, ізоляцію мережі, обмеження ресурсів і браузерні +Область sandbox може бути для кожного агента окремо (за замовчуванням), для кожного сеансу або спільною. Кожна область +отримує власний workspace, змонтований у `/workspace`. Ви також можете налаштувати +політики дозволу/заборони інструментів, ізоляцію мережі, обмеження ресурсів і браузерні контейнери. -Повну інформацію про конфігурацію, образи, примітки з безпеки та профілі кількох агентів див. у: +Повну конфігурацію, образи, примітки щодо безпеки та профілі для кількох агентів див. тут: -- [Sandboxing](/uk/gateway/sandboxing) -- повний довідник із sandbox +- [Ізоляція](/uk/gateway/sandboxing) -- повний довідник із sandbox - [OpenShell](/uk/gateway/openshell) -- інтерактивний доступ shell до контейнерів sandbox -- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів +- [Sandbox і інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів ### Швидке ввімкнення @@ -359,27 +371,27 @@ scripts/sandbox-setup.sh Зберіть образ sandbox за допомогою [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) - або задайте `agents.defaults.sandbox.docker.image` на ваш користувацький образ. - Контейнери автоматично створюються для кожної сесії за потреби. + або встановіть власний образ у `agents.defaults.sandbox.docker.image`. + Контейнери автоматично створюються для кожного сеансу за потреби. - - Установіть `docker.user` у UID:GID, що відповідає власнику змонтованого робочого простору, - або змініть власника папки робочого простору через `chown`. + + Встановіть `docker.user` у UID:GID, що відповідає власнику змонтованого workspace, + або змініть власника папки workspace через chown. - - OpenClaw запускає команди через `sh -lc` (login shell), що зчитує - `/etc/profile` і може скидати PATH. Задайте `docker.env.PATH`, щоб додати - ваші користувацькі шляхи до інструментів на початок, або додайте сценарій у `/etc/profile.d/` у вашому Dockerfile. + + OpenClaw запускає команди через `sh -lc` (login shell), який завантажує + `/etc/profile` і може скинути PATH. Встановіть `docker.env.PATH`, щоб додати + шляхи до ваших користувацьких інструментів, або додайте скрипт у `/etc/profile.d/` у вашому Dockerfile. - + VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини й повторіть спробу. - - Отримайте нове посилання dashboard і підтвердьте браузерний пристрій: + + Отримайте нове посилання dashboard і схваліть пристрій браузера: ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -391,7 +403,7 @@ scripts/sandbox-setup.sh - + Скиньте режим і bind gateway: ```bash @@ -402,10 +414,10 @@ scripts/sandbox-setup.sh -## Пов’язане +## Пов’язані матеріали - [Огляд встановлення](/uk/install) — усі способи встановлення - [Podman](/uk/install/podman) — альтернатива Docker на базі Podman - [ClawDock](/uk/install/clawdock) — спільнотне налаштування Docker Compose -- [Оновлення](/uk/install/updating) — як підтримувати OpenClaw актуальним +- [Оновлення](/uk/install/updating) — як підтримувати OpenClaw в актуальному стані - [Конфігурація](/uk/gateway/configuration) — конфігурація gateway після встановлення diff --git a/docs/uk/logging.md b/docs/uk/logging.md index cc81d25db..7da5517d2 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,30 +1,29 @@ --- read_when: - - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців. - - Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних. - - Ви усуваєте неполадки й вам потрібно швидко знайти журнали. -summary: Журнали файлів, вивід консолі, CLI tailing і вкладка Logs в Control UI + - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців + - Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних + - Ви усуваєте несправності й вам потрібно швидко знайти журнали +summary: Файлові журнали, вивід у консолі, відстеження виводу CLI та вкладка «Журнали» в Control UI title: Журналювання x-i18n: - generated_at: "2026-04-25T23:50:25Z" + generated_at: "2026-04-26T04:54:59Z" model: gpt-5.4 provider: openai - source_hash: 01b139a45937e4a718837ddcf58cfcf6f0230e416942fd6844c27d0c7d71605e + source_hash: 3d4d32e4cdee429221c020fcb9e862e8f7c06f1e7973f36deac2a3476e8c31c8 source_path: logging.md workflow: 15 --- OpenClaw має дві основні поверхні журналювання: -- **Журнали файлів** (рядки JSON), які записує Gateway. -- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI. +- **Файлові журнали** (рядки JSON), які записує Gateway. +- **Вивід у консолі**, що показується в терміналах і в інтерфейсі Gateway Debug UI. -Вкладка **Logs** у Control UI виконує tail для журналу файлу gateway. На цій сторінці -пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. +Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. ## Де зберігаються журнали -За замовчуванням Gateway записує циклічний файл журналу в: +За замовчуванням Gateway записує циклічний файл журналу за шляхом: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` @@ -44,7 +43,7 @@ OpenClaw має дві основні поверхні журналювання: ### CLI: live tail (рекомендовано) -Використовуйте CLI, щоб виконувати tail для файлу журналу gateway через RPC: +Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: ```bash openclaw logs --follow @@ -52,32 +51,28 @@ openclaw logs --follow Корисні поточні параметри: -- `--local-time`: відображати часові мітки у вашому локальному часовому поясі +- `--local-time`: відображати часові позначки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (тут приймається через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді RPC із підтримкою агентів (приймається тут через спільний клієнтський шар) Режими виводу: -- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. -- **Не-TTY-сеанси**: звичайний текст. -- `--json`: JSON із розділенням по рядках (одна подія журналу на рядок). -- `--plain`: примусово використовувати звичайний текст у TTY-сеансах. +- **Сеанси TTY**: зручні для читання, кольорові, структуровані рядки журналу. +- **Сеанси без TTY**: звичайний текст. +- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). +- `--plain`: примусово використовувати звичайний текст у сеансах TTY. - `--no-color`: вимкнути кольори ANSI. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або -середовища; якщо цільовий Gateway -вимагає автентифікацію, самостійно додайте `--token`. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; якщо цільовий Gateway вимагає автентифікації, додайте `--token` самостійно. -У режимі JSON CLI виводить об’єкти з позначкою `type`: +У режимі JSON CLI виводить об’єкти з міткою `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу - `notice`: підказки про обрізання / ротацію - `raw`: нерозібраний рядок журналу -Якщо local loopback Gateway запитує pairing, `openclaw logs` автоматично повертається -до налаштованого локального файлу журналу. Явні цілі `--url` не -використовують цей резервний варіант. +Якщо Gateway у local loopback запитує сполучення, `openclaw logs` автоматично переключається на налаштований локальний файл журналу. Явні цілі `--url` не використовують цей резервний варіант. Якщо Gateway недоступний, CLI виводить коротку підказку виконати: @@ -87,12 +82,12 @@ openclaw doctor ### Control UI (веб) -Вкладка **Logs** у Control UI виконує tail того самого файлу за допомогою `logs.tail`. -Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. +Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`. +Про те, як її відкрити, дивіться [/web/control-ui](/uk/web/control-ui). -### Журнали лише каналів +### Журнали лише каналу -Щоб фільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте: +Щоб відфільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: ```bash openclaw channels logs --channel whatsapp @@ -100,28 +95,27 @@ openclaw channels logs --channel whatsapp ## Формати журналів -### Журнали файлів (JSONL) +### Файлові журнали (JSONL) -Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI аналізують ці -записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу є об’єктом JSON. CLI і Control UI аналізують ці записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення). -### Вивід консолі +### Вивід у консолі -Журнали консолі **враховують TTY** і форматуються для зручності читання: +Журнали консолі **враховують TTY** і відформатовані для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольори рівнів (info/warn/error) -- Необов’язковий компактний або JSON-режим +- Кольорове позначення рівнів (info/warn/error) +- Необов’язковий компактний режим або режим JSON Форматування консолі керується `logging.consoleStyle`. -### Журнали WebSocket Gateway +### Журнали Gateway WebSocket -`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: +`openclaw gateway` також має журналювання протоколу WebSocket для трафіку RPC: - звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю докладного відображення +- `--ws-log auto|compact|full`: вибрати стиль докладного відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -134,7 +128,7 @@ openclaw gateway --verbose --ws-log full ## Налаштування журналювання -Уся конфігурація журналювання знаходиться в `logging` у `~/.openclaw/openclaw.json`. +Усі налаштування журналювання знаходяться в розділі `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -151,52 +145,42 @@ openclaw gateway --verbose --ws-log full ### Рівні журналювання -- `logging.level`: рівень **журналів файлів** (JSONL). +- `logging.level`: рівень **файлових журналів** (JSONL). - `logging.consoleLevel`: рівень докладності **консолі**. -Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тож ви можете підвищити докладність для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тому ви можете підвищити докладність для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на вивід консолі та докладність WS-журналу; він не змінює -рівні журналів файлів. +`--verbose` впливає лише на вивід у консоль і докладність WS-журналів; він не змінює рівні файлових журналів. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручно для людей, кольорово, із часовими мітками. -- `compact`: щільніший вивід (найкраще для довгих сеансів). +- `pretty`: зручний для людини, кольоровий, із часовими позначками. +- `compact`: щільніший вивід (найкраще для тривалих сеансів). - `json`: JSON у кожному рядку (для обробників журналів). ### Редагування конфіденційних даних -Підсумки інструментів можуть редагувати конфіденційні токени до того, як вони потраплять у консоль: +Підсумки інструментів можуть приховувати конфіденційні токени до того, як вони потраплять у консоль: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Редагування конфіденційних даних впливає **лише на вивід консолі** і не змінює журнали файлів. +Редагування застосовується на рівні приймачів журналювання для **виводу в консоль**, **діагностики консолі, спрямованої в stderr**, і **файлових журналів**. Файлові журнали залишаються у форматі JSONL, але відповідні секретні значення маскуються до запису рядка на диск. ## Діагностика та OpenTelemetry -Діагностика — це структуровані, машинозчитувані події для запусків моделей і -телеметрії потоку повідомлень (webhooks, черги, стан сеансу). Вони **не** -замінюють журнали — вони живлять метрики, трасування та експортери. Події генеруються -в процесі незалежно від того, експортуєте ви їх чи ні. +Діагностика — це структуровані, машинозчитувані події для запусків моделей і телеметрії потоку повідомлень (Webhooks, постановка в чергу, стан сеансу). Вони **не** замінюють журнали — вони живлять метрики, трасування та експортери. Події генеруються в процесі незалежно від того, експортуєте ви їх чи ні. Дві суміжні поверхні: -- **Експорт OpenTelemetry** — надсилання метрик, трасувань і журналів через OTLP/HTTP до - будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, - Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, - назви метрик/span, змінні середовища та модель конфіденційності описані на окремій сторінці: +- **Експорт OpenTelemetry** — надсилання метрик, трасувань і журналів через OTLP/HTTP до будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, назви метрик/span, змінні середовища та модель конфіденційності описані на окремій сторінці: [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -- **Прапорці діагностики** — цільові прапорці debug-журналу, які спрямовують додаткові журнали в - `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру - та підтримують wildcard-вирази (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` - або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: +- **Прапорці діагностики** — цільові прапорці налагоджувального журналу, які спрямовують додаткові журнали в `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру й підтримують шаблони з підстановками (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). -Щоб увімкнути події діагностики для Plugin або спеціальних sink без експорту OTLP: +Щоб увімкнути події діагностики для Plugin або власних приймачів без експорту OTLP: ```json5 { @@ -204,18 +188,17 @@ openclaw gateway --verbose --ws-log full } ``` -Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). +Для експорту OTLP до колектора дивіться [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -## Поради з усунення неполадок +## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях до файлу, - вказаний у `logging.file`. -- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. +- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях до файлу, вказаний у `logging.file`. +- **Потрібно більше подробиць?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель конфіденційності -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-журналу -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі WS-журналу, префікси підсистем і захоплення консолі -- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог metric/span, модель конфіденційності +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці налагоджувального журналу +- [Внутрішня реалізація журналювання Gateway](/uk/gateway/logging) — стилі WS-журналів, префікси підсистем і перехоплення консолі +- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник по полях `diagnostics.*`