chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
76b4cdad60
commit
a7494caba3
@ -1,66 +1,66 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете автоматизацію на основі подій для `/new`, `/reset`, `/stop` і подій життєвого циклу агента
|
||||
- Ви хочете створити, встановити або налагодити хуки
|
||||
- Ви хочете створювати, встановлювати або налагоджувати хуки
|
||||
summary: 'Хуки: автоматизація на основі подій для команд і подій життєвого циклу'
|
||||
title: Хуки
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T00:29:08Z"
|
||||
generated_at: "2026-04-26T23:10:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: cf40a64449347ef750b4b0e0a83b80e2e8fdef87d92daa71f028d2bf6a3d3d22
|
||||
source_hash: f1f9b1dc0c470502f782758e1542435f1e593750ff69a39f7f966c7d42e29c1e
|
||||
source_path: automation/hooks.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з каталогів і переглядати через `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пак хука, застарілий обробник чи додатковий каталог хуків.
|
||||
Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з директорій та переглядати за допомогою `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник або додаткову директорію хуків.
|
||||
|
||||
В OpenClaw є два типи хуків:
|
||||
|
||||
- **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу.
|
||||
- **Webhooks**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Webhooks](/uk/automation/cron-jobs#webhooks).
|
||||
- **Внутрішні хуки** (ця сторінка): виконуються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу.
|
||||
- **Webhooks**: зовнішні HTTP-ендпойнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Webhooks](/uk/automation/cron-jobs#webhooks).
|
||||
|
||||
Хуки також можуть постачатися всередині плагінів. `openclaw hooks list` показує як окремі хуки, так і хуки, якими керують плагіни.
|
||||
Хуки також можуть постачатися всередині плагінів. `openclaw hooks list` показує як окремі хуки, так і хуки, керовані плагінами.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
```bash
|
||||
# Перелічити доступні хуки
|
||||
# Показати доступні хуки
|
||||
openclaw hooks list
|
||||
|
||||
# Увімкнути хук
|
||||
openclaw hooks enable session-memory
|
||||
|
||||
# Перевірити статус хуків
|
||||
# Перевірити стан хуків
|
||||
openclaw hooks check
|
||||
|
||||
# Отримати докладну інформацію
|
||||
# Отримати детальну інформацію
|
||||
openclaw hooks info session-memory
|
||||
```
|
||||
|
||||
## Типи подій
|
||||
|
||||
| Подія | Коли спрацьовує |
|
||||
| ------------------------ | -------------------------------------------- |
|
||||
| `command:new` | Надіслано команду `/new` |
|
||||
| `command:reset` | Надіслано команду `/reset` |
|
||||
| `command:stop` | Надіслано команду `/stop` |
|
||||
| `command` | Будь-яка подія команди (загальний слухач) |
|
||||
| `session:compact:before` | Перед тим, як Compaction підсумує історію |
|
||||
| `session:compact:after` | Після завершення Compaction |
|
||||
| `session:patch` | Коли властивості сесії змінюються |
|
||||
| `agent:bootstrap` | Перед вставленням bootstrap-файлів робочої області |
|
||||
| `gateway:startup` | Після запуску каналів і завантаження хуків |
|
||||
| `message:received` | Вхідне повідомлення з будь-якого каналу |
|
||||
| `message:transcribed` | Після завершення транскрибування аудіо |
|
||||
| `message:preprocessed` | Після завершення обробки всіх медіа й посилань |
|
||||
| `message:sent` | Вихідне повідомлення доставлено |
|
||||
| Подія | Коли спрацьовує |
|
||||
| ------------------------ | ----------------------------------------------- |
|
||||
| `command:new` | Надіслано команду `/new` |
|
||||
| `command:reset` | Надіслано команду `/reset` |
|
||||
| `command:stop` | Надіслано команду `/stop` |
|
||||
| `command` | Будь-яка подія команди (загальний слухач) |
|
||||
| `session:compact:before` | Перед тим, як Compaction підсумує історію |
|
||||
| `session:compact:after` | Після завершення Compaction |
|
||||
| `session:patch` | Коли змінюються властивості сесії |
|
||||
| `agent:bootstrap` | Перед додаванням bootstrap-файлів робочої папки |
|
||||
| `gateway:startup` | Після запуску каналів і завантаження хуків |
|
||||
| `message:received` | Вхідне повідомлення з будь-якого каналу |
|
||||
| `message:transcribed` | Після завершення транскрибування аудіо |
|
||||
| `message:preprocessed` | Після завершення обробки медіа та посилань |
|
||||
| `message:sent` | Вихідне повідомлення доставлено |
|
||||
|
||||
## Написання хуків
|
||||
|
||||
### Структура хука
|
||||
|
||||
Кожен хук — це каталог, що містить два файли:
|
||||
Кожен хук — це директорія, що містить два файли:
|
||||
|
||||
```
|
||||
my-hook/
|
||||
@ -80,20 +80,20 @@ metadata:
|
||||
|
||||
# My Hook
|
||||
|
||||
Тут розміщується докладна документація.
|
||||
Тут розміщується детальна документація.
|
||||
```
|
||||
|
||||
**Поля метаданих** (`metadata.openclaw`):
|
||||
|
||||
| Поле | Опис |
|
||||
| --------- | ---------------------------------------------------- |
|
||||
| `emoji` | Емодзі для відображення в CLI |
|
||||
| `events` | Масив подій, які потрібно слухати |
|
||||
| `export` | Іменований експорт для використання (типово `"default"`) |
|
||||
| `os` | Обов’язкові платформи (наприклад, `["darwin", "linux"]`) |
|
||||
| `requires` | Обов’язкові `bins`, `anyBins`, `env` або шляхи `config` |
|
||||
| `always` | Обійти перевірки придатності (boolean) |
|
||||
| `install` | Методи встановлення |
|
||||
| Поле | Опис |
|
||||
| --------- | --------------------------------------------------------- |
|
||||
| `emoji` | Емодзі для відображення в CLI |
|
||||
| `events` | Масив подій, які потрібно відстежувати |
|
||||
| `export` | Іменований експорт для використання (типово `"default"`) |
|
||||
| `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) |
|
||||
| `requires` | Потрібні шляхи `bins`, `anyBins`, `env` або `config` |
|
||||
| `always` | Обійти перевірки відповідності (boolean) |
|
||||
| `install` | Методи встановлення |
|
||||
|
||||
### Реалізація обробника
|
||||
|
||||
@ -113,7 +113,7 @@ const handler = async (event) => {
|
||||
export default handler;
|
||||
```
|
||||
|
||||
Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте через push, щоб надіслати користувачу), і `context` (специфічні для події дані). Контексти хуків агентів і інструментальних плагінів також можуть містити `trace` — лише для читання W3C-сумісний діагностичний контекст трасування, який плагіни можуть передавати до структурованих логів для кореляції OTEL.
|
||||
Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте сюди, щоб надіслати користувачу), і `context` (специфічні для події дані). Контексти хуків агентів і плагінів інструментів також можуть містити `trace` — лише для читання, сумісний із W3C діагностичний контекст трасування, який плагіни можуть передавати в структуровані логи для кореляції OTEL.
|
||||
|
||||
### Основні моменти контексту подій
|
||||
|
||||
@ -125,49 +125,49 @@ export default handler;
|
||||
|
||||
**Події повідомлень** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
|
||||
|
||||
**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточний збагачений вміст), `context.from`, `context.channelId`.
|
||||
**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточне збагачене тіло), `context.from`, `context.channelId`.
|
||||
|
||||
**Події Bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`.
|
||||
**Події bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`.
|
||||
|
||||
**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть ініціювати події patch.
|
||||
**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати події patch.
|
||||
|
||||
**Події Compaction**: `session:compact:before` включає `messageCount`, `tokenCount`. `session:compact:after` додатково містить `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
|
||||
**Події Compaction**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додатково містить `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
|
||||
|
||||
`command:stop` спостерігає за тим, як користувач надсилає `/stop`; це стосується скасування/життєвого циклу команди, а не завершення роботи агента. Плагіни, яким потрібно перевірити природну фінальну відповідь і попросити агента зробити ще один прохід, мають використовувати типізований хук плагіна `before_agent_finalize`. Див. [Plugin hooks](/uk/plugins/hooks).
|
||||
`command:stop` фіксує, коли користувач надсилає `/stop`; це життєвий цикл скасування/команди, а не бар’єр фіналізації агента. Плагіни, яким потрібно перевірити природну фінальну відповідь і попросити агента зробити ще один прохід, повинні використовувати типізований хук плагіна `before_agent_finalize`. Див. [Plugin hooks](/uk/plugins/hooks).
|
||||
|
||||
## Виявлення хуків
|
||||
|
||||
Хуки виявляються з цих каталогів у порядку зростання пріоритету перевизначення:
|
||||
Хуки виявляються з таких директорій у порядку зростання пріоритету перевизначення:
|
||||
|
||||
1. **Вбудовані хуки**: постачаються з OpenClaw
|
||||
2. **Хуки плагінів**: хуки, вбудовані у встановлені плагіни
|
||||
3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих областей). Додаткові каталоги з `hooks.internal.load.extraDirs` мають той самий пріоритет.
|
||||
4. **Хуки робочої області**: `<workspace>/hooks/` (для окремого агента, типово вимкнені, доки їх явно не ввімкнути)
|
||||
1. **Вбудовані хуки**: постачаються разом з OpenClaw
|
||||
2. **Хуки плагінів**: постачаються всередині встановлених плагінів
|
||||
3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих папок). Додаткові директорії з `hooks.internal.load.extraDirs` мають такий самий пріоритет.
|
||||
4. **Хуки робочої папки**: `<workspace>/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути)
|
||||
|
||||
Хуки робочої області можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою.
|
||||
Хуки робочої папки можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією самою назвою.
|
||||
|
||||
Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не буде налаштовано. Увімкніть вбудований або керований хук через `openclaw hooks enable <name>`, встановіть пак хуків або задайте `hooks.internal.enabled=true`, щоб явно ввімкнути цю можливість. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові каталоги хуків і застарілі обробники вмикають широке виявлення.
|
||||
Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не налаштовані. Увімкніть вбудований або керований хук за допомогою `openclaw hooks enable <name>`, встановіть пакет хуків або задайте `hooks.internal.enabled=true`, щоб дозволити їх. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; `hooks.internal.enabled=true`, додаткові директорії хуків і застарілі обробники вмикають широке виявлення.
|
||||
|
||||
### Паки хуків
|
||||
### Пакети хуків
|
||||
|
||||
Паки хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення:
|
||||
Пакети хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <path-or-spec>
|
||||
```
|
||||
|
||||
Npm-специфікації підтримуються лише для реєстру (назва пакета + необов’язкова точна версія або dist-tag). Git/URL/file-специфікації та semver-діапазони відхиляються.
|
||||
Npm-специфікації підтримуються лише для реєстру (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються.
|
||||
|
||||
## Вбудовані хуки
|
||||
|
||||
| Хук | Події | Що робить |
|
||||
| --------------------- | ------------------------------ | ----------------------------------------------------- |
|
||||
| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `<workspace>/memory/` |
|
||||
| bootstrap-extra-files | `agent:bootstrap` | Вставляє додаткові bootstrap-файли за glob-шаблонами |
|
||||
| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` |
|
||||
| boot-md | `gateway:startup` | Виконує `BOOT.md` під час запуску gateway |
|
||||
| Хук | Події | Що робить |
|
||||
| -------------------- | ----------------------------- | ------------------------------------------------------ |
|
||||
| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `<workspace>/memory/` |
|
||||
| bootstrap-extra-files | `agent:bootstrap` | Додає додаткові bootstrap-файли за glob-шаблонами |
|
||||
| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` |
|
||||
| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли запускається gateway |
|
||||
|
||||
Увімкніть будь-який вбудований хук:
|
||||
Увімкнути будь-який вбудований хук:
|
||||
|
||||
```bash
|
||||
openclaw hooks enable <hook-name>
|
||||
@ -175,9 +175,9 @@ openclaw hooks enable <hook-name>
|
||||
|
||||
<a id="session-memory"></a>
|
||||
|
||||
### Докладно про session-memory
|
||||
### Деталі session-memory
|
||||
|
||||
Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає його в `<workspace>/memory/YYYY-MM-DD-slug.md`. Потребує налаштованого `workspace.dir`.
|
||||
Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файла через LLM і зберігає його в `<workspace>/memory/YYYY-MM-DD-slug.md`, використовуючи локальну дату хоста. Потрібно, щоб був налаштований `workspace.dir`.
|
||||
|
||||
<a id="bootstrap-extra-files"></a>
|
||||
|
||||
@ -198,28 +198,28 @@ openclaw hooks enable <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
Шляхи обчислюються відносно робочої області. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
|
||||
Шляхи обчислюються відносно робочої папки. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
|
||||
|
||||
<a id="command-logger"></a>
|
||||
|
||||
### Докладно про command-logger
|
||||
### Деталі command-logger
|
||||
|
||||
Логує кожну slash-команду в `~/.openclaw/logs/commands.log`.
|
||||
|
||||
<a id="boot-md"></a>
|
||||
|
||||
### Докладно про boot-md
|
||||
### Деталі boot-md
|
||||
|
||||
Виконує `BOOT.md` з активної робочої області під час запуску gateway.
|
||||
Запускає `BOOT.md` з активної робочої папки під час запуску gateway.
|
||||
|
||||
## Хуки плагінів
|
||||
|
||||
Плагіни можуть реєструвати типізовані хуки через Plugin SDK для глибшої інтеграції:
|
||||
перехоплення викликів інструментів, зміни промптів, керування потоком повідомлень тощо.
|
||||
перехоплення викликів інструментів, модифікації промптів, керування потоком повідомлень тощо.
|
||||
Використовуйте хуки плагінів, коли вам потрібні `before_tool_call`, `before_agent_reply`,
|
||||
`before_install` або інші внутрішньопроцесні хуки життєвого циклу.
|
||||
`before_install` або інші in-process хуки життєвого циклу.
|
||||
|
||||
Повний довідник по хуках плагінів див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
Повний довідник із хуків плагінів див. у [Plugin hooks](/uk/plugins/hooks).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -237,7 +237,7 @@ openclaw hooks enable <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
Змінні середовища для окремих хуків:
|
||||
Змінні середовища для окремого хука:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -254,7 +254,7 @@ openclaw hooks enable <hook-name>
|
||||
}
|
||||
```
|
||||
|
||||
Додаткові каталоги хуків:
|
||||
Додаткові директорії хуків:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -269,19 +269,19 @@ openclaw hooks enable <hook-name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення.
|
||||
Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки повинні використовувати систему на основі виявлення.
|
||||
</Note>
|
||||
|
||||
## Довідник CLI
|
||||
|
||||
```bash
|
||||
# Перелічити всі хуки (додайте --eligible, --verbose або --json)
|
||||
# Показати всі хуки (додайте --eligible, --verbose або --json)
|
||||
openclaw hooks list
|
||||
|
||||
# Показати докладну інформацію про хук
|
||||
# Показати детальну інформацію про хук
|
||||
openclaw hooks info <hook-name>
|
||||
|
||||
# Показати зведення придатності
|
||||
# Показати зведення відповідності
|
||||
openclaw hooks check
|
||||
|
||||
# Увімкнути/вимкнути
|
||||
@ -291,25 +291,25 @@ openclaw hooks disable <hook-name>
|
||||
|
||||
## Найкращі практики
|
||||
|
||||
- **Підтримуйте швидку роботу обробників.** Хуки виконуються під час обробки команд. Для важкої роботи використовуйте fire-and-forget через `void processInBackground(event)`.
|
||||
- **Коректно обробляйте помилки.** Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники теж могли виконатися.
|
||||
- **Фільтруйте події якомога раніше.** Відразу повертайтеся, якщо тип/дія події не стосується вашого випадку.
|
||||
- **Робіть обробники швидкими.** Хуки виконуються під час обробки команд. Запускайте важку роботу у фоновому режимі через `void processInBackground(event)`.
|
||||
- **Коректно обробляйте помилки.** Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники могли виконатися.
|
||||
- **Фільтруйте події рано.** Одразу повертайтеся, якщо тип/дія події не є релевантними.
|
||||
- **Використовуйте конкретні ключі подій.** Надавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати.
|
||||
|
||||
## Усунення несправностей
|
||||
## Усунення проблем
|
||||
|
||||
### Хук не виявлено
|
||||
|
||||
```bash
|
||||
# Перевірити структуру каталогу
|
||||
# Перевірити структуру директорії
|
||||
ls -la ~/.openclaw/hooks/my-hook/
|
||||
# Має показати: HOOK.md, handler.ts
|
||||
|
||||
# Перелічити всі виявлені хуки
|
||||
# Показати всі виявлені хуки
|
||||
openclaw hooks list
|
||||
```
|
||||
|
||||
### Хук непридатний
|
||||
### Хук не відповідає вимогам
|
||||
|
||||
```bash
|
||||
openclaw hooks info my-hook
|
||||
@ -319,7 +319,7 @@ openclaw hooks info my-hook
|
||||
|
||||
### Хук не виконується
|
||||
|
||||
1. Переконайтеся, що хук увімкнено: `openclaw hooks list`
|
||||
1. Переконайтеся, що хук увімкнений: `openclaw hooks list`
|
||||
2. Перезапустіть процес gateway, щоб хуки перезавантажилися.
|
||||
3. Перевірте логи gateway: `./scripts/clawlog.sh | grep hook`
|
||||
|
||||
@ -327,5 +327,5 @@ openclaw hooks info my-hook
|
||||
|
||||
- [Довідник CLI: hooks](/uk/cli/hooks)
|
||||
- [Webhooks](/uk/automation/cron-jobs#webhooks)
|
||||
- [Plugin hooks](/uk/plugins/hooks) — внутрішньопроцесні хуки життєвого циклу плагіна
|
||||
- [Plugin hooks](/uk/plugins/hooks) — in-process хуки життєвого циклу плагінів
|
||||
- [Конфігурація](/uk/gateway/configuration-reference#hooks)
|
||||
|
||||
176
docs/uk/ci.md
176
docs/uk/ci.md
File diff suppressed because one or more lines are too long
@ -1,42 +1,42 @@
|
||||
---
|
||||
read_when:
|
||||
- Налагодження проблем виявлення Bonjour на macOS/iOS
|
||||
- Зміна типів сервісів mDNS, записів TXT або UX виявлення
|
||||
summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та типові режими відмови)
|
||||
- Зміна типів сервісів mDNS, TXT-записів або UX виявлення
|
||||
summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та поширені режими відмов)
|
||||
title: Виявлення Bonjour
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T04:59:44Z"
|
||||
generated_at: "2026-04-26T23:10:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b055021bdcd92740934823dea2acf758c6ec991a15c0a315426dc359a7eea093
|
||||
source_hash: abaec96c53233e697155fd62a2fa6af972ab039cb480af8246f96359b5036e1f
|
||||
source_path: gateway/bonjour.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Виявлення Bonjour / mDNS
|
||||
|
||||
OpenClaw використовує Bonjour (mDNS / DNS‑SD) для виявлення активного Gateway (кінцева точка WebSocket).
|
||||
Багатоадресний перегляд `local.` — це **лише зручність у межах LAN**. Вбудований Plugin
|
||||
`bonjour` відповідає за рекламу в LAN і ввімкнений за замовчуванням. Для виявлення між мережами
|
||||
OpenClaw використовує Bonjour (mDNS / DNS‑SD) для виявлення активного Gateway (кінцевої точки WebSocket).
|
||||
Багатоадресний перегляд `local.` — це **зручність лише для LAN**. Вбудований plugin `bonjour`
|
||||
відповідає за рекламу в LAN і ввімкнений за замовчуванням. Для виявлення між мережами
|
||||
той самий маяк також можна опублікувати через налаштований домен wide-area DNS-SD.
|
||||
Виявлення все одно працює за принципом best-effort і **не** замінює підключення через SSH або Tailnet.
|
||||
Виявлення все одно залишається best-effort і **не** замінює підключення через SSH або Tailnet.
|
||||
|
||||
## Wide-area Bonjour (Unicast DNS-SD) через Tailscale
|
||||
|
||||
Якщо node і gateway перебувають у різних мережах, багатоадресний mDNS не перетинатиме
|
||||
Якщо node і gateway перебувають у різних мережах, багатоадресний mDNS не перетне
|
||||
цю межу. Ви можете зберегти той самий UX виявлення, переключившись на **unicast DNS‑SD**
|
||||
("Wide‑Area Bonjour") через Tailscale.
|
||||
|
||||
Загальні кроки:
|
||||
Кроки високого рівня:
|
||||
|
||||
1. Запустіть DNS-сервер на хості gateway (доступний через Tailnet).
|
||||
2. Опублікуйте записи DNS‑SD для `_openclaw-gw._tcp` у виділеній зоні
|
||||
(приклад: `openclaw.internal.`).
|
||||
3. Налаштуйте **split DNS** у Tailscale так, щоб вибраний домен резолвився через цей
|
||||
DNS-сервер для клієнтів (включно з iOS).
|
||||
3. Налаштуйте в Tailscale **split DNS**, щоб вибраний вами домен резолвився через цей
|
||||
DNS-сервер для клієнтів (зокрема iOS).
|
||||
|
||||
OpenClaw підтримує будь-який домен виявлення; `openclaw.internal.` — лише приклад.
|
||||
iOS/Android node переглядають і `local.`, і ваш налаштований wide-area домен.
|
||||
Node на iOS/Android переглядають і `local.`, і ваш налаштований wide-area домен.
|
||||
|
||||
### Конфігурація Gateway (рекомендовано)
|
||||
|
||||
@ -53,10 +53,10 @@ iOS/Android node переглядають і `local.`, і ваш налашто
|
||||
openclaw dns setup --apply
|
||||
```
|
||||
|
||||
Це встановить CoreDNS і налаштує його так, щоб він:
|
||||
Це встановлює CoreDNS і налаштовує його так, щоб він:
|
||||
|
||||
- слухав порт 53 лише на Tailscale-інтерфейсах gateway
|
||||
- обслуговував вибраний домен (приклад: `openclaw.internal.`) з `~/.openclaw/dns/<domain>.db`
|
||||
- слухав порт 53 лише на інтерфейсах Tailscale gateway
|
||||
- обслуговував вибраний вами домен (приклад: `openclaw.internal.`) з `~/.openclaw/dns/<domain>.db`
|
||||
|
||||
Перевірте з машини, підключеної до tailnet:
|
||||
|
||||
@ -72,52 +72,52 @@ dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
|
||||
- Додайте nameserver, що вказує на tailnet IP gateway (UDP/TCP 53).
|
||||
- Додайте split DNS, щоб ваш домен виявлення використовував цей nameserver.
|
||||
|
||||
Після того як клієнти приймуть DNS tailnet, iOS node і CLI-виявлення зможуть переглядати
|
||||
Щойно клієнти приймуть DNS tailnet, node на iOS і виявлення CLI зможуть переглядати
|
||||
`_openclaw-gw._tcp` у вашому домені виявлення без багатоадресності.
|
||||
|
||||
### Безпека listener Gateway (рекомендовано)
|
||||
### Безпека слухача Gateway (рекомендовано)
|
||||
|
||||
Порт Gateway WS (типово `18789`) за замовчуванням прив’язується до loopback. Для доступу через LAN/tailnet
|
||||
явно вкажіть bind і залиште автентифікацію ввімкненою.
|
||||
Порт WS Gateway (типово `18789`) за замовчуванням прив’язується до loopback. Для доступу через LAN/tailnet
|
||||
явно задайте прив’язку та залиште автентифікацію ввімкненою.
|
||||
|
||||
Для конфігурацій лише з tailnet:
|
||||
|
||||
- Установіть `gateway.bind: "tailnet"` у `~/.openclaw/openclaw.json`.
|
||||
- Перезапустіть Gateway (або перезапустіть застосунок macOS menubar).
|
||||
- Перезапустіть Gateway (або перезапустіть застосунок macOS у рядку меню).
|
||||
|
||||
## Що рекламується
|
||||
|
||||
Лише Gateway рекламує `_openclaw-gw._tcp`. Реклама через багатоадресність у LAN
|
||||
забезпечується вбудованим Plugin `bonjour`; публікація wide-area DNS-SD і надалі
|
||||
Лише Gateway рекламує `_openclaw-gw._tcp`. Реклама багатоадресності в LAN
|
||||
забезпечується вбудованим plugin `bonjour`; публікація wide-area DNS-SD і надалі
|
||||
належить Gateway.
|
||||
|
||||
## Типи сервісів
|
||||
|
||||
- `_openclaw-gw._tcp` — транспортний маяк gateway (використовується macOS/iOS/Android node).
|
||||
- `_openclaw-gw._tcp` — транспортний маяк gateway (використовується node на macOS/iOS/Android).
|
||||
|
||||
## Ключі TXT (не секретні підказки)
|
||||
## Ключі TXT (несекретні підказки)
|
||||
|
||||
Gateway рекламує невеликі не секретні підказки, щоб зробити UI-потоки зручнішими:
|
||||
Gateway рекламує невеликі несекретні підказки, щоб зробити UI-потоки зручнішими:
|
||||
|
||||
- `role=gateway`
|
||||
- `displayName=<дружня назва>`
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=<port>` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (лише коли TLS увімкнено)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і відбиток доступний)
|
||||
- `canvasPort=<port>` (лише коли ввімкнено canvas host; наразі те саме, що й `gatewayPort`)
|
||||
- `gatewayTls=1` (лише коли ввімкнено TLS)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли ввімкнено TLS і доступний відбиток)
|
||||
- `canvasPort=<port>` (лише коли ввімкнено хост canvas; наразі збігається з `gatewayPort`)
|
||||
- `transport=gateway`
|
||||
- `tailnetDns=<magicdns>` (лише в повному режимі mDNS, необов’язкова підказка, коли Tailnet доступний)
|
||||
- `sshPort=<port>` (лише в повному режимі mDNS; wide-area DNS-SD може його не включати)
|
||||
- `cliPath=<path>` (лише в повному режимі mDNS; wide-area 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` лише як підказки.
|
||||
- TXT-записи Bonjour/mDNS є **неавтентифікованими**. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації.
|
||||
- Клієнтам слід маршрутизувати через резолвлену кінцеву точку сервісу (SRV + A/AAAA). Сприймайте `lanHost`, `tailnetDns`, `gatewayPort` і `gatewayTlsSha256` лише як підказки.
|
||||
- Автоматичне націлювання SSH так само має використовувати резолвлений хост сервісу, а не підказки лише з TXT.
|
||||
- TLS pinning ніколи не повинен дозволяти рекламованому `gatewayTlsSha256` перевизначати раніше збережений pin.
|
||||
- iOS/Android node повинні трактувати прямі підключення на основі виявлення як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка, побаченого вперше.
|
||||
- Закріплення TLS ніколи не повинно дозволяти рекламованому `gatewayTlsSha256` перевизначати раніше збережений pin.
|
||||
- Node на iOS/Android повинні розглядати прямі підключення на основі виявлення як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка, побаченого вперше.
|
||||
|
||||
## Налагодження на macOS
|
||||
|
||||
@ -135,12 +135,12 @@ Gateway рекламує невеликі не секретні підказки
|
||||
dns-sd -L "<instance>" _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
Якщо перегляд працює, а резолв — ні, зазвичай це означає проблему з політикою LAN або
|
||||
Якщо перегляд працює, але резолв — ні, зазвичай це означає проблему з політикою LAN або
|
||||
резолвером mDNS.
|
||||
|
||||
## Налагодження в логах Gateway
|
||||
|
||||
Gateway записує ротаційний файл логу (під час запуску виводиться як
|
||||
Gateway записує циклічний лог-файл (виводиться під час запуску як
|
||||
`gateway log file: ...`). Шукайте рядки `bonjour:`, особливо:
|
||||
|
||||
- `bonjour: advertise failed ...`
|
||||
@ -148,9 +148,9 @@ Gateway записує ротаційний файл логу (під час з
|
||||
- `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`.
|
||||
|
||||
Щоб зібрати логи:
|
||||
|
||||
@ -161,24 +161,24 @@ iOS node використовує `NWBrowser` для виявлення `_opencl
|
||||
|
||||
## Коли вимикати Bonjour
|
||||
|
||||
Вимикайте Bonjour лише тоді, коли реклама через багатоадресність у LAN недоступна або шкідлива.
|
||||
Типовий випадок — Gateway, що працює за Docker bridge networking, WSL або політикою
|
||||
мережі, яка відкидає багатоадресність mDNS. У таких середовищах Gateway усе ще
|
||||
доступний через свою опубліковану URL-адресу, SSH, Tailnet або wide-area DNS-SD,
|
||||
Вимикайте Bonjour лише тоді, коли реклама багатоадресності в LAN недоступна або шкідлива.
|
||||
Поширений випадок — Gateway, який працює за Docker bridge networking, WSL або
|
||||
мережевою політикою, що відкидає багатоадресний трафік mDNS. У таких середовищах Gateway
|
||||
усе ще доступний через опублікований URL, SSH, Tailnet або wide-area DNS-SD,
|
||||
але автоматичне виявлення в LAN ненадійне.
|
||||
|
||||
Віддавайте перевагу наявному перевизначенню через середовище, коли проблема пов’язана з конкретним розгортанням:
|
||||
Віддавайте перевагу наявному перевизначенню через змінну середовища, коли проблема обмежена конкретним розгортанням:
|
||||
|
||||
```bash
|
||||
OPENCLAW_DISABLE_BONJOUR=1
|
||||
```
|
||||
|
||||
Це вимикає рекламу через багатоадресність у LAN без зміни конфігурації Plugin.
|
||||
Це безпечно для Docker-образів, service files, скриптів запуску та разового
|
||||
налагодження, оскільки налаштування зникає разом із середовищем.
|
||||
Це вимикає рекламу багатоадресності в LAN без зміни конфігурації plugin.
|
||||
Це безпечно для Docker-образів, service-файлів, скриптів запуску та одноразового
|
||||
налагодження, оскільки налаштування зникає разом зі змінною середовища.
|
||||
|
||||
Використовуйте конфігурацію Plugin лише тоді, коли ви свідомо хочете вимкнути
|
||||
вбудований Plugin виявлення LAN для цієї конфігурації OpenClaw:
|
||||
Використовуйте конфігурацію plugin лише тоді, коли ви свідомо хочете вимкнути
|
||||
вбудований plugin виявлення LAN для цієї конфігурації OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw plugins disable bonjour
|
||||
@ -186,76 +186,75 @@ openclaw plugins disable bonjour
|
||||
|
||||
## Особливості Docker
|
||||
|
||||
Комплектний Docker Compose встановлює `OPENCLAW_DISABLE_BONJOUR=1` для сервісу Gateway
|
||||
за замовчуванням. Docker bridge network зазвичай не пересилають багатоадресність mDNS
|
||||
(`224.0.0.251:5353`) між контейнером і LAN, тому якщо залишити Bonjour увімкненим, це може
|
||||
спричиняти повторні збої ciao `probing` або `announcing`, не забезпечуючи
|
||||
працездатне виявлення.
|
||||
Вбудований plugin Bonjour автоматично вимикає рекламу багатоадресності в LAN у виявлених
|
||||
контейнерах, коли `OPENCLAW_DISABLE_BONJOUR` не встановлено. Мережі Docker bridge
|
||||
зазвичай не пересилають багатоадресний трафік mDNS (`224.0.0.251:5353`) між контейнером
|
||||
та LAN, тому реклама з контейнера рідко робить виявлення працездатним.
|
||||
|
||||
Важливі нюанси:
|
||||
Важливі особливості:
|
||||
|
||||
- Вимкнення Bonjour не зупиняє Gateway. Воно лише зупиняє рекламу через багатоадресність у LAN.
|
||||
- Вимкнення Bonjour не змінює `gateway.bind`; Docker все ще за замовчуванням використовує
|
||||
- Вимкнення Bonjour не зупиняє Gateway. Воно лише зупиняє рекламу багатоадресності в LAN.
|
||||
- Вимкнення Bonjour не змінює `gateway.bind`; Docker і далі за замовчуванням використовує
|
||||
`OPENCLAW_GATEWAY_BIND=lan`, щоб опублікований порт хоста міг працювати.
|
||||
- Вимкнення Bonjour не вимикає wide-area DNS-SD. Використовуйте wide-area виявлення
|
||||
або Tailnet, коли Gateway і node не в одній LAN.
|
||||
- Повторне використання того самого `OPENCLAW_CONFIG_DIR` поза Docker не успадковує
|
||||
значення Compose за замовчуванням, якщо середовище все ще не задає `OPENCLAW_DISABLE_BONJOUR`.
|
||||
- Встановлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише для host networking, macvlan або іншої
|
||||
мережі, де багатоадресність mDNS гарантовано проходить.
|
||||
або Tailnet, коли Gateway і node не перебувають в одній LAN.
|
||||
- Повторне використання того самого `OPENCLAW_CONFIG_DIR` поза Docker не зберігає
|
||||
політику автоматичного вимкнення контейнера.
|
||||
- Установлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише для host networking, macvlan або іншої
|
||||
мережі, де відомо, що багатоадресний mDNS проходить; установлюйте `1`, щоб примусово вимкнути.
|
||||
|
||||
## Усунення проблем із вимкненим Bonjour
|
||||
|
||||
Якщо node більше не виявляє Gateway автоматично після налаштування Docker:
|
||||
|
||||
1. Перевірте, чи Gateway навмисно пригнічує рекламу в LAN:
|
||||
1. Підтвердьте, у якому режимі працює Gateway: автоматичному, примусово ввімкненому чи примусово вимкненому:
|
||||
|
||||
```bash
|
||||
docker compose config | grep OPENCLAW_DISABLE_BONJOUR
|
||||
```
|
||||
|
||||
2. Переконайтеся, що сам Gateway доступний через опублікований порт:
|
||||
2. Підтвердьте, що сам Gateway доступний через опублікований порт:
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:18789/healthz
|
||||
```
|
||||
|
||||
3. Використовуйте пряму ціль, коли Bonjour вимкнено:
|
||||
- Control UI або локальні інструменти: `http://127.0.0.1:18789`
|
||||
- Клієнти в LAN: `http://<gateway-host>:18789`
|
||||
- Клієнти між мережами: Tailnet MagicDNS, Tailnet IP, SSH tunnel або
|
||||
- UI керування або локальні інструменти: `http://127.0.0.1:18789`
|
||||
- Клієнти LAN: `http://<gateway-host>:18789`
|
||||
- Клієнти з інших мереж: Tailnet MagicDNS, Tailnet IP, SSH-тунель або
|
||||
wide-area DNS-SD
|
||||
|
||||
4. Якщо ви навмисно ввімкнули Bonjour у Docker за допомогою
|
||||
4. Якщо ви свідомо ввімкнули Bonjour у Docker за допомогою
|
||||
`OPENCLAW_DISABLE_BONJOUR=0`, протестуйте багатоадресність із хоста:
|
||||
|
||||
```bash
|
||||
dns-sd -B _openclaw-gw._tcp local.
|
||||
```
|
||||
|
||||
Якщо перегляд порожній або логи Gateway показують повторні скасування
|
||||
watchdog у ciao, поверніть `OPENCLAW_DISABLE_BONJOUR=1` і використовуйте прямий
|
||||
маршрут або маршрут через Tailnet.
|
||||
Якщо перегляд порожній або логи Gateway показують повторні скасування watchdog
|
||||
ciao, поверніть `OPENCLAW_DISABLE_BONJOUR=1` і використовуйте прямий маршрут або
|
||||
маршрут через Tailnet.
|
||||
|
||||
## Типові режими відмови
|
||||
## Поширені режими відмов
|
||||
|
||||
- **Bonjour не працює між мережами**: використовуйте Tailnet або SSH.
|
||||
- **Багатоадресність заблокована**: деякі мережі Wi‑Fi вимикають mDNS.
|
||||
- **Advertiser застряг у probing/announcing**: хости із заблокованою багатоадресністю,
|
||||
container bridge, WSL або зміни інтерфейсів можуть залишити advertiser ciao у
|
||||
неанонсованому стані. OpenClaw робить кілька повторних спроб, а потім вимикає Bonjour
|
||||
для поточного процесу Gateway, замість того щоб безкінечно перезапускати advertiser.
|
||||
- **Docker bridge networking**: комплектний Docker Compose вимикає Bonjour
|
||||
за замовчуванням через `OPENCLAW_DISABLE_BONJOUR=1`. Встановлюйте `0` лише для host,
|
||||
macvlan або іншої мережі з підтримкою mDNS.
|
||||
- **Рекламодавець застряг у probing/announcing**: хости із заблокованою багатоадресністю,
|
||||
container bridge, WSL або зміна інтерфейсів можуть залишити рекламодавець ciao у
|
||||
стані без анонсу. OpenClaw повторює спробу кілька разів, а потім вимикає Bonjour
|
||||
для поточного процесу Gateway замість безкінечного перезапуску рекламодавця.
|
||||
- **Docker bridge networking**: Bonjour автоматично вимикається у виявлених контейнерах.
|
||||
Установлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише для host, macvlan або іншої
|
||||
mDNS-сумісної мережі.
|
||||
- **Сон / зміна інтерфейсів**: macOS може тимчасово втрачати результати mDNS; повторіть спробу.
|
||||
- **Перегляд працює, а резолв — ні**: робіть назви машин простими (уникайте емодзі або
|
||||
пунктуації), а потім перезапустіть Gateway. Ім’я екземпляра сервісу похідне від
|
||||
- **Перегляд працює, але резолв — ні**: використовуйте прості назви машин (уникайте емодзі або
|
||||
пунктуації), потім перезапустіть Gateway. Ім’я екземпляра сервісу походить від
|
||||
імені хоста, тому надто складні назви можуть плутати деякі резолвери.
|
||||
|
||||
## Екрановані імена екземплярів (`\032`)
|
||||
|
||||
Bonjour/DNS‑SD часто екранує байти в іменах екземплярів сервісів як десяткові послідовності `\DDD`
|
||||
Bonjour/DNS‑SD часто екранує байти в іменах екземплярів сервісу як десяткові послідовності `\DDD`
|
||||
(наприклад, пробіли стають `\032`).
|
||||
|
||||
- Це нормально на рівні протоколу.
|
||||
@ -263,16 +262,17 @@ Bonjour/DNS‑SD часто екранує байти в іменах екзем
|
||||
|
||||
## Вимкнення / конфігурація
|
||||
|
||||
- `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`).
|
||||
- Docker Compose за замовчуванням встановлює `OPENCLAW_DISABLE_BONJOUR=1` для bridge networking; перевизначайте значення на `OPENCLAW_DISABLE_BONJOUR=0` лише коли багатоадресність mDNS доступна.
|
||||
- `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом bind для Gateway.
|
||||
- `OPENCLAW_SSH_PORT` перевизначає порт SSH, коли рекламується `sshPort` (legacy: `OPENCLAW_SSH_PORT`).
|
||||
- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено повний режим mDNS (legacy: `OPENCLAW_TAILNET_DNS`).
|
||||
- `OPENCLAW_CLI_PATH` перевизначає рекламований шлях CLI (legacy: `OPENCLAW_CLI_PATH`).
|
||||
- `openclaw plugins disable bonjour` вимикає рекламу багатоадресності в LAN, вимикаючи вбудований plugin.
|
||||
- `openclaw plugins enable bonjour` відновлює типовий plugin виявлення LAN.
|
||||
- `OPENCLAW_DISABLE_BONJOUR=1` вимикає рекламу багатоадресності в LAN без зміни конфігурації plugin; допустимі truthy-значення: `1`, `true`, `yes` і `on` (застаріле: `OPENCLAW_DISABLE_BONJOUR`).
|
||||
- `OPENCLAW_DISABLE_BONJOUR=0` примусово вмикає рекламу багатоадресності в LAN, зокрема всередині виявлених контейнерів; допустимі falsy-значення: `0`, `false`, `no` і `off`.
|
||||
- Коли `OPENCLAW_DISABLE_BONJOUR` не встановлено, Bonjour рекламується на звичайних хостах і автоматично вимикається всередині виявлених контейнерів.
|
||||
- `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом прив’язки Gateway.
|
||||
- `OPENCLAW_SSH_PORT` перевизначає порт SSH, коли рекламується `sshPort` (застаріле: `OPENCLAW_SSH_PORT`).
|
||||
- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено режим mDNS full (застаріле: `OPENCLAW_TAILNET_DNS`).
|
||||
- `OPENCLAW_CLI_PATH` перевизначає рекламований шлях CLI (застаріле: `OPENCLAW_CLI_PATH`).
|
||||
|
||||
## Пов’язана документація
|
||||
|
||||
- Політика виявлення та вибір транспорту: [Виявлення](/uk/gateway/discovery)
|
||||
- Сполучення node + підтвердження: [Сполучення Gateway](/uk/gateway/pairing)
|
||||
- Політика виявлення та вибір транспорту: [Discovery](/uk/gateway/discovery)
|
||||
- Сполучення node + підтвердження: [Gateway pairing](/uk/gateway/pairing)
|
||||
|
||||
@ -1,103 +1,103 @@
|
||||
---
|
||||
read_when:
|
||||
- Реалізація або зміна виявлення/оголошення Bonjour
|
||||
- Налаштування режимів віддаленого підключення (напряму чи через SSH)
|
||||
- Проєктування виявлення Node та сполучення для віддалених вузлів
|
||||
- Налаштування режимів віддаленого підключення (пряме чи через SSH)
|
||||
- Проєктування виявлення Node і сполучення для віддалених Node
|
||||
summary: Виявлення Node і транспорти (Bonjour, Tailscale, SSH) для пошуку Gateway
|
||||
title: Виявлення та транспорти
|
||||
title: Виявлення і транспорти
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T04:54:57Z"
|
||||
generated_at: "2026-04-26T23:10:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 615be0f501470772c257beb8e798c522c108b09081a603f44218404277fdf269
|
||||
source_hash: c396e6e07808e2571c6d7f539922b94443adbf39339027e6e962596c6f13deaa
|
||||
source_path: gateway/discovery.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Виявлення та транспорти
|
||||
|
||||
В OpenClaw є дві окремі проблеми, які на перший погляд виглядають схоже:
|
||||
OpenClaw має дві окремі проблеми, які на поверхні виглядають схожими:
|
||||
|
||||
1. **Віддалене керування оператором**: застосунок macOS у рядку меню керує Gateway, що працює деінде.
|
||||
2. **Сполучення Node**: iOS/Android (і майбутні вузли) знаходять Gateway і безпечно сполучаються з ним.
|
||||
1. **Віддалене керування оператором**: застосунок macOS у рядку меню керує Gateway, що працює в іншому місці.
|
||||
2. **Сполучення Node**: iOS/Android (і майбутні Node) знаходять Gateway і безпечно виконують сполучення.
|
||||
|
||||
Мета дизайну — зберегти все мережеве виявлення/оголошення в **Node Gateway** (`openclaw gateway`) і залишити клієнти (mac-застосунок, iOS) споживачами.
|
||||
Мета дизайну — зберегти все мережеве виявлення/оголошення в **Node Gateway** (`openclaw gateway`) і залишити клієнти (застосунок macOS, iOS) споживачами.
|
||||
|
||||
## Терміни
|
||||
|
||||
- **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)); більше не оголошується для
|
||||
- **Gateway**: один довготривалий процес Gateway, який володіє станом (сеанси, сполучення, реєстр Node) і запускає канали. У більшості конфігурацій використовується один на хост; можливі ізольовані конфігурації з кількома 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-міст (видалено)**: старіший транспорт Node (див.
|
||||
[Протокол моста](/uk/gateway/bridge-protocol)); більше не оголошується для
|
||||
виявлення і більше не є частиною поточних збірок.
|
||||
|
||||
Деталі протоколу:
|
||||
Подробиці протоколу:
|
||||
|
||||
- [Протокол Gateway](/uk/gateway/protocol)
|
||||
- [Протокол Bridge (застарілий)](/uk/gateway/bridge-protocol)
|
||||
- [Протокол моста (застарілий)](/uk/gateway/bridge-protocol)
|
||||
|
||||
## Чому ми зберігаємо і «прямий», і SSH
|
||||
|
||||
- **Прямий WS** забезпечує найкращий UX в одній мережі та в межах tailnet:
|
||||
- автоматичне виявлення в LAN через Bonjour
|
||||
- токени сполучення + ACL, якими керує Gateway
|
||||
- доступ до оболонки не потрібен; поверхня протоколу може залишатися вузькою й придатною для аудиту
|
||||
- доступ до оболонки не потрібен; поверхня протоколу може залишатися вузькою й придатною до аудиту
|
||||
- **SSH** залишається універсальним резервним варіантом:
|
||||
- працює всюди, де у вас є доступ по SSH (навіть через не пов’язані між собою мережі)
|
||||
- переживає проблеми з multicast/mDNS
|
||||
- працює всюди, де у вас є доступ SSH (навіть через непов’язані мережі)
|
||||
- працює попри проблеми з multicast/mDNS
|
||||
- не потребує нових вхідних портів, окрім SSH
|
||||
|
||||
## Вхідні джерела виявлення (як клієнти дізнаються, де знаходиться Gateway)
|
||||
## Джерела виявлення (як клієнти дізнаються, де знаходиться Gateway)
|
||||
|
||||
### 1) Виявлення через Bonjour / DNS-SD
|
||||
|
||||
Multicast Bonjour працює за принципом best-effort і не перетинає межі мереж. OpenClaw також може переглядати
|
||||
той самий маяк Gateway через налаштований домен wide-area DNS-SD, тож виявлення може охоплювати:
|
||||
Multicast Bonjour є best-effort і не проходить між мережами. OpenClaw також може переглядати
|
||||
той самий маяк Gateway через налаштований wide-area домен DNS-SD, тож виявлення може охоплювати:
|
||||
|
||||
- `local.` у тій самій LAN
|
||||
- налаштований домен unicast DNS-SD для міжмережевого виявлення
|
||||
- `local.` в межах тієї самої LAN
|
||||
- налаштований unicast-домен DNS-SD для міжмережевого виявлення
|
||||
|
||||
Цільовий напрям:
|
||||
Цільовий напрямок:
|
||||
|
||||
- **Gateway** оголошує свій WS-ендпойнт через Bonjour.
|
||||
- Клієнти переглядають і показують список «виберіть Gateway», а потім зберігають вибраний ендпойнт.
|
||||
- **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=<дружня назва>` (відображувана назва, налаштована оператором)
|
||||
- `lanHost=<hostname>.local`
|
||||
- `gatewayPort=18789` (Gateway WS + HTTP)
|
||||
- `gatewayTls=1` (лише коли TLS увімкнено)
|
||||
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і відбиток доступний)
|
||||
- `canvasPort=<port>` (порт canvas host; наразі збігається з `gatewayPort`, коли canvas host увімкнено)
|
||||
- `canvasPort=<port>` (порт хоста canvas; наразі такий самий, як `gatewayPort`, коли хост canvas увімкнено)
|
||||
- `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-підказки.
|
||||
- Для маршрутизації (хост/порт) слід надавати перевагу **розв’язаному ендпойнту служби** (SRV + A/AAAA), а не переданим через TXT `lanHost`, `tailnetDns` чи `gatewayPort`.
|
||||
- TXT-записи Bonjour/mDNS є **неавтентифікованими**. Клієнти повинні трактувати значення TXT лише як UX-підказки.
|
||||
- Для маршрутизації (host/port) слід надавати перевагу **розв’язаній кінцевій точці сервісу** (SRV + A/AAAA), а не значенням `lanHost`, `tailnetDns` чи `gatewayPort`, наданим через TXT.
|
||||
- TLS pinning ніколи не повинен дозволяти оголошеному `gatewayTlsSha256` перевизначати раніше збережений pin.
|
||||
- Вузли iOS/Android повинні вимагати явного підтвердження «довіряти цьому відбитку» перед збереженням pin під час першого підключення (перевірка поза каналом), коли вибраний маршрут є безпечним/на основі TLS.
|
||||
- Node iOS/Android повинні вимагати явне підтвердження «довіряти цьому відбитку» перед збереженням pin під час першого підключення (перевірка поза смугою) щоразу, коли вибраний маршрут є безпечним/базованим на TLS.
|
||||
|
||||
Вимкнення/перевизначення:
|
||||
|
||||
- `OPENCLAW_DISABLE_BONJOUR=1` вимикає оголошення.
|
||||
- Docker Compose типово використовує `OPENCLAW_DISABLE_BONJOUR=1`, оскільки мережі bridge
|
||||
зазвичай не передають multicast mDNS надійно; використовуйте `0` лише на host, macvlan
|
||||
або в іншій мережі з підтримкою mDNS.
|
||||
- Коли `OPENCLAW_DISABLE_BONJOUR` не задано, Bonjour оголошується на звичайних хостах
|
||||
і автоматично вимикається у виявлених контейнерах. Використовуйте `0` лише на host, macvlan
|
||||
або в іншій мережі з підтримкою mDNS; використовуйте `1` для примусового вимкнення.
|
||||
- `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.
|
||||
|
||||
@ -105,22 +105,22 @@ Multicast Bonjour працює за принципом best-effort і не пе
|
||||
|
||||
Для конфігурацій у стилі London/Vienna Bonjour не допоможе. Рекомендована «пряма» ціль:
|
||||
|
||||
- ім’я Tailscale MagicDNS (переважно) або стабільна tailnet IP-адреса.
|
||||
- ім’я Tailscale MagicDNS (бажано) або стабільна tailnet IP-адреса.
|
||||
|
||||
Якщо Gateway може визначити, що працює під Tailscale, він публікує `tailnetDns` як необов’язкову підказку для клієнтів (зокрема wide-area beacon).
|
||||
Якщо Gateway може визначити, що він працює під Tailscale, він публікує `tailnetDns` як необов’язкову підказку для клієнтів (зокрема для wide-area beacon).
|
||||
|
||||
MacOS-застосунок тепер віддає перевагу іменам MagicDNS над сирими Tailscale IP-адресами для виявлення gateway. Це підвищує надійність, коли tailnet IP-адреси змінюються (наприклад після перезапуску вузлів або повторного призначення CGNAT), тому що імена MagicDNS автоматично розв’язуються в поточну IP-адресу.
|
||||
Застосунок macOS тепер надає перевагу іменам MagicDNS над сирими Tailscale IP для виявлення gateway. Це підвищує надійність, коли tailnet IP змінюються (наприклад, після перезапуску Node або перепризначення CGNAT), оскільки імена MagicDNS автоматично розв’язуються в поточну IP-адресу.
|
||||
|
||||
Для сполучення мобільних вузлів підказки виявлення не послаблюють безпеку транспорту на tailnet/public маршрутах:
|
||||
Для сполучення мобільних Node підказки виявлення не послаблюють безпеку транспорту на маршрутах tailnet/public:
|
||||
|
||||
- iOS/Android, як і раніше, вимагають безпечний шлях першого підключення через tailnet/public (`wss://` або Tailscale Serve/Funnel).
|
||||
- Виявлена сира tailnet IP-адреса є підказкою для маршрутизації, а не дозволом використовувати відкритий віддалений `ws://`.
|
||||
- Пряме підключення через приватну LAN по `ws://` як і раніше підтримується.
|
||||
- Якщо вам потрібен найпростіший шлях Tailscale для мобільних вузлів, використовуйте Tailscale Serve, щоб і виявлення, і код налаштування розв’язувалися до того самого безпечного ендпойнта MagicDNS.
|
||||
- Виявлена сира tailnet IP — це підказка маршрутизації, а не дозвіл використовувати відкритий віддалений `ws://`.
|
||||
- Пряме приватне LAN-підключення через `ws://` залишається підтримуваним.
|
||||
- Якщо вам потрібен найпростіший шлях Tailscale для мобільних Node, використовуйте Tailscale Serve, щоб і виявлення, і код налаштування розв’язувалися до тієї самої захищеної кінцевої точки MagicDNS.
|
||||
|
||||
### 3) Ручна ціль / SSH
|
||||
### 3) Ручна / SSH-ціль
|
||||
|
||||
Коли прямий маршрут недоступний (або пряме підключення вимкнено), клієнти завжди можуть підключитися через SSH, переадресувавши loopback-порт gateway.
|
||||
Коли прямого маршруту немає (або прямий вимкнено), клієнти завжди можуть підключитися через SSH, переспрямувавши loopback-порт gateway.
|
||||
|
||||
Див. [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
@ -128,30 +128,30 @@ MacOS-застосунок тепер віддає перевагу іменам
|
||||
|
||||
Рекомендована поведінка клієнта:
|
||||
|
||||
1. Якщо налаштовано сполучений прямий ендпойнт і він доступний, використовуйте його.
|
||||
2. Інакше, якщо виявлення знаходить Gateway у `local.` або в налаштованому wide-area domain, запропонуйте варіант «Використовувати цей Gateway» в один дотик і збережіть його як прямий ендпойнт.
|
||||
3. Інакше, якщо налаштовано DNS/IP tailnet, спробуйте пряме підключення.
|
||||
Для мобільних вузлів на tailnet/public маршрутах пряме підключення означає безпечний ендпойнт, а не відкритий віддалений `ws://`.
|
||||
4. Інакше поверніться до SSH.
|
||||
1. Якщо налаштовано сполучену пряму кінцеву точку і вона доступна, використовуйте її.
|
||||
2. Інакше, якщо виявлення знаходить Gateway у `local.` або в налаштованому wide-area домені, запропонуйте вибір «Використовувати цей Gateway» в один дотик і збережіть його як пряму кінцеву точку.
|
||||
3. Інакше, якщо налаштовано tailnet DNS/IP, спробуйте пряме підключення.
|
||||
Для мобільних Node на маршрутах tailnet/public пряме підключення означає безпечну кінцеву точку, а не відкритий віддалений `ws://`.
|
||||
4. Інакше використовуйте SSH як резервний варіант.
|
||||
|
||||
## Сполучення + автентифікація (прямий транспорт)
|
||||
|
||||
Gateway є джерелом істини для допуску вузлів/клієнтів.
|
||||
Gateway є джерелом істини для допуску Node/клієнтів.
|
||||
|
||||
- Запити на сполучення створюються/схвалюються/відхиляються в Gateway (див. [Сполучення Gateway](/uk/gateway/pairing)).
|
||||
- Gateway забезпечує:
|
||||
- автентифікацію (токен / keypair)
|
||||
- автентифікацію (token / keypair)
|
||||
- області дії/ACL (Gateway не є сирим проксі до кожного методу)
|
||||
- обмеження швидкості
|
||||
|
||||
## Зони відповідальності за компонентами
|
||||
## Обов’язки за компонентами
|
||||
|
||||
- **Gateway**: оголошує маяки виявлення, володіє рішеннями щодо сполучення та хостить WS-ендпойнт.
|
||||
- **macOS-застосунок**: допомагає вибрати Gateway, показує запити на сполучення та використовує SSH лише як резервний варіант.
|
||||
- **Вузли iOS/Android**: переглядають Bonjour для зручності й підключаються до сполученого Gateway WS.
|
||||
- **Gateway**: оголошує маяки виявлення, керує рішеннями щодо сполучення та розміщує кінцеву точку WS.
|
||||
- **Застосунок macOS**: допомагає вибрати Gateway, показує запити на сполучення і використовує SSH лише як резервний варіант.
|
||||
- **Node iOS/Android**: переглядають Bonjour як зручну можливість і підключаються до сполученого Gateway WS.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Віддалений доступ](/uk/gateway/remote)
|
||||
- [Tailscale](/uk/gateway/tailscale)
|
||||
- [Виявлення через Bonjour](/uk/gateway/bonjour)
|
||||
- [Виявлення Bonjour](/uk/gateway/bonjour)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue
Block a user