chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
650b2ea20b
commit
a3729ffbfd
@ -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/<domain>.db`
|
||||
|
||||
Перевірте з машини, підключеної до tailnet:
|
||||
@ -67,57 +67,57 @@ dig @<TAILNET_IPV4> -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=<friendly name>`
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=<port>` (WS + HTTP Gateway)
|
||||
- `gatewayTls=1` (лише коли TLS увімкнено)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і доступний відбиток)
|
||||
- `canvasPort=<port>` (лише коли ввімкнено хост canvas; наразі такий самий, як `gatewayPort`)
|
||||
- `gatewayPort=<port>` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (лише коли ввімкнено TLS)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли ввімкнено TLS і доступний відбиток)
|
||||
- `canvasPort=<port>` (лише коли ввімкнено canvas host; наразі збігається з `gatewayPort`)
|
||||
- `transport=gateway`
|
||||
- `tailnetDns=<magicdns>` (лише у повному режимі mDNS, необов’язкова підказка, коли доступний Tailnet)
|
||||
- `sshPort=<port>` (лише у повному режимі mDNS; DNS-SD широкої зони може його не включати)
|
||||
- `cliPath=<path>` (лише у повному режимі mDNS; DNS-SD широкої зони все одно записує його як підказку для віддаленого встановлення)
|
||||
- `tailnetDns=<magicdns>` (лише в режимі mDNS full, необов’язкова підказка, коли Tailnet доступний)
|
||||
- `sshPort=<port>` (лише в режимі mDNS full; wide-area DNS-SD може його не включати)
|
||||
- `cliPath=<path>` (лише в режимі 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 "<instance>" _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)
|
||||
|
||||
@ -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=<friendly name>` (зрозуміла користувачу назва, налаштована оператором)
|
||||
- `displayName=<friendly name>` (зрозуміле ім’я, налаштоване оператором)
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=18789` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (лише коли TLS увімкнено)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і відбиток доступний)
|
||||
- `canvasPort=<port>` (порт хоста canvas; наразі той самий, що й `gatewayPort`, коли хост canvas увімкнено)
|
||||
- `canvasPort=<port>` (порт canvas host; наразі збігається з `gatewayPort`, коли canvas host увімкнено)
|
||||
- `tailnetDns=<magicdns>` (необов’язкова підказка; визначається автоматично, коли доступний Tailscale)
|
||||
- `sshPort=<port>` (лише в повному режимі mDNS; wide-area DNS-SD може його пропускати, і тоді типовим SSH лишається `22`)
|
||||
- `cliPath=<path>` (лише в повному режимі mDNS; wide-area DNS-SD усе одно записує його як підказку для віддаленого встановлення)
|
||||
- `sshPort=<port>` (лише в повному режимі mDNS; wide-area DNS-SD може його не включати, у такому разі для SSH залишаються типові значення `22`)
|
||||
- `cliPath=<path>` (лише в повному режимі 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)
|
||||
|
||||
@ -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
|
||||
|
||||
<Steps>
|
||||
<Step title="Зберіть образ">
|
||||
Із кореня репозиторію запустіть сценарій налаштування:
|
||||
У корені репозиторію запустіть скрипт налаштування:
|
||||
|
||||
```bash
|
||||
./scripts/docker/setup.sh
|
||||
```
|
||||
|
||||
Це локально збирає образ gateway. Щоб натомість використати попередньо зібраний образ:
|
||||
Це локально збере образ Gateway. Щоб натомість використовувати попередньо зібраний образ:
|
||||
|
||||
```bash
|
||||
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
|
||||
@ -54,24 +54,24 @@ Docker **необов’язковий**. Використовуйте його
|
||||
</Step>
|
||||
|
||||
<Step title="Завершіть онбординг">
|
||||
Сценарій налаштування автоматично запускає онбординг. Він:
|
||||
Скрипт налаштування запускає онбординг автоматично. Він:
|
||||
|
||||
- запропонує ввести API-ключі провайдерів
|
||||
- згенерує токен gateway і запише його в `.env`
|
||||
- запустить gateway через Docker Compose
|
||||
- запросить API-ключі провайдерів
|
||||
- згенерує токен Gateway і запише його в `.env`
|
||||
- запустить Gateway через Docker Compose
|
||||
|
||||
Під час налаштування онбординг перед запуском і записи конфігурації виконуються через
|
||||
`openclaw-gateway` напряму. `openclaw-cli` призначено для команд, які ви запускаєте вже після
|
||||
того, як контейнер gateway існує.
|
||||
Під час налаштування передстартовий онбординг і запис конфігурації виконуються
|
||||
безпосередньо через `openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте після того,
|
||||
як контейнер gateway уже існує.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Відкрийте Control UI">
|
||||
Відкрийте `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 **необов’язковий**. Використовуйте його
|
||||
</Step>
|
||||
|
||||
<Step title="Налаштуйте канали (необов’язково)">
|
||||
Використовуйте контейнер CLI, щоб додати канали повідомлень:
|
||||
Використовуйте контейнер CLI, щоб додати канали обміну повідомленнями:
|
||||
|
||||
```bash
|
||||
# WhatsApp (QR)
|
||||
@ -98,9 +98,9 @@ Docker **необов’язковий**. Використовуйте його
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Ручний процес
|
||||
### Ручний потік
|
||||
|
||||
Якщо ви віддаєте перевагу виконанню кожного кроку самостійно замість використання сценарію налаштування:
|
||||
Якщо ви віддаєте перевагу запуску кожного кроку вручну замість використання скрипта налаштування:
|
||||
|
||||
```bash
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
@ -113,105 +113,117 @@ docker compose up -d openclaw-gateway
|
||||
|
||||
<Note>
|
||||
Запускайте `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`.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Оскільки `openclaw-cli` спільно використовує мережевий простір імен `openclaw-gateway`, це
|
||||
інструмент після запуску. До `docker compose up -d openclaw-gateway` запускайте онбординг
|
||||
і записи конфігурації на етапі налаштування через `openclaw-gateway` з
|
||||
і записи конфігурації під час налаштування через `openclaw-gateway` з
|
||||
`--no-deps --entrypoint node`.
|
||||
</Note>
|
||||
|
||||
### Змінні середовища
|
||||
|
||||
Сценарій налаштування приймає такі необов’язкові змінні середовища:
|
||||
Скрипт налаштування приймає такі необов’язкові змінні середовища:
|
||||
|
||||
| Змінна | Призначення |
|
||||
| ----------------------------- | -------------------------------------------------------------- |
|
||||
| `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.
|
||||
|
||||
<Note>
|
||||
Використовуйте значення режиму 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`.
|
||||
</Note>
|
||||
|
||||
### Сховище і збереження даних
|
||||
### 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/<agentId>/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).
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Увімкнення sandbox агента для Docker gateway">
|
||||
<Accordion title="Увімкнути sandbox агента для Docker gateway">
|
||||
```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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація / CI (неінтерактивно)">
|
||||
Вимкніть виділення псевдо-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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Примітка про безпеку спільної мережі">
|
||||
`openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тому CLI-команди
|
||||
можуть досягати gateway через `127.0.0.1`. Розглядайте це як спільну
|
||||
межу довіри. Конфігурація compose скидає `NET_RAW`/`NET_ADMIN` і вмикає
|
||||
<Accordion title="Примітка щодо безпеки спільної мережі">
|
||||
`openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тож CLI
|
||||
команди можуть досягати gateway через `127.0.0.1`. Розглядайте це як спільну
|
||||
межу довіри. Конфігурація compose видаляє `NET_RAW`/`NET_ADMIN` і вмикає
|
||||
`no-new-privileges` для `openclaw-cli`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи і EACCES">
|
||||
Образ працює як `node` (uid 1000). Якщо ви бачите помилки доступу до
|
||||
`/home/node/.openclaw`, переконайтеся, що ваші bind mount-и хоста належать uid 1000:
|
||||
<Accordion title="Дозволи та EACCES">
|
||||
Образ працює від імені `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
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Швидші перебудови">
|
||||
Упорядкуйте свій 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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Параметри контейнера для досвідчених користувачів">
|
||||
Типовий образ орієнтований на безпеку й працює як непривілейований `node`. Для більш
|
||||
<Accordion title="Контейнерні параметри для досвідчених користувачів">
|
||||
Типовий образ орієнтований на безпеку й працює від непривілейованого `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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OpenAI Codex OAuth (headless Docker)">
|
||||
Якщо ви вибираєте OpenAI Codex OAuth у майстрі, він відкриває URL у браузері. У
|
||||
Docker або headless-конфігураціях скопіюйте повний redirect URL, на який ви потрапите, і вставте
|
||||
його назад у майстер, щоб завершити автентифікацію.
|
||||
<Accordion title="OAuth OpenAI Codex (headless Docker)">
|
||||
Якщо у майстрі ви оберете OAuth OpenAI Codex, він відкриє URL-адресу в браузері. У
|
||||
Docker або headless-середовищах скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте
|
||||
її назад у майстер, щоб завершити автентифікацію.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Метадані базового образу">
|
||||
Основний 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).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Запуск на 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
|
||||
<Accordion title="Образ відсутній або контейнер sandbox не запускається">
|
||||
Зберіть образ 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`.
|
||||
Контейнери автоматично створюються для кожного сеансу за потреби.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помилки доступу в sandbox">
|
||||
Установіть `docker.user` у UID:GID, що відповідає власнику змонтованого робочого простору,
|
||||
або змініть власника папки робочого простору через `chown`.
|
||||
<Accordion title="Помилки дозволів у sandbox">
|
||||
Встановіть `docker.user` у UID:GID, що відповідає власнику змонтованого workspace,
|
||||
або змініть власника папки workspace через chown.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Користувацькі інструменти не знайдено в sandbox">
|
||||
OpenClaw запускає команди через `sh -lc` (login shell), що зчитує
|
||||
`/etc/profile` і може скидати PATH. Задайте `docker.env.PATH`, щоб додати
|
||||
ваші користувацькі шляхи до інструментів на початок, або додайте сценарій у `/etc/profile.d/` у вашому Dockerfile.
|
||||
<Accordion title="У sandbox не знайдено користувацькі інструменти">
|
||||
OpenClaw запускає команди через `sh -lc` (login shell), який завантажує
|
||||
`/etc/profile` і може скинути PATH. Встановіть `docker.env.PATH`, щоб додати
|
||||
шляхи до ваших користувацьких інструментів, або додайте скрипт у `/etc/profile.d/` у вашому Dockerfile.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OOM під час збирання образу (вихід 137)">
|
||||
<Accordion title="Під час збирання образу завершено через OOM (код виходу 137)">
|
||||
VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини й повторіть спробу.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Unauthorized або потрібне сполучення в Control UI">
|
||||
Отримайте нове посилання dashboard і підтвердьте браузерний пристрій:
|
||||
<Accordion title="Unauthorized або потрібне pairing у Control UI">
|
||||
Отримайте нове посилання dashboard і схваліть пристрій браузера:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
@ -391,7 +403,7 @@ scripts/sandbox-setup.sh
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ціль Gateway показує ws://172.x.x.x або помилки сполучення з Docker CLI">
|
||||
<Accordion title="Ціль gateway показує ws://172.x.x.x або помилки pairing з Docker CLI">
|
||||
Скиньте режим і bind gateway:
|
||||
|
||||
```bash
|
||||
@ -402,10 +414,10 @@ scripts/sandbox-setup.sh
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [Огляд встановлення](/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 після встановлення
|
||||
|
||||
@ -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 <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці 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 <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тому ви можете підвищити докладність для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level <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.*`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user