chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
ffbfd162bc
commit
e2023ef099
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете керувати Gateway із браузера
|
||||
- Ви хочете керувати Gateway з браузера
|
||||
- Вам потрібен доступ до Tailnet без SSH-тунелів
|
||||
sidebarTitle: Control UI
|
||||
summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T03:30:45Z"
|
||||
generated_at: "2026-05-04T05:53:54Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговує Gateway:
|
||||
Інтерфейс Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
|
||||
- типово: `http://<host>:18789/`
|
||||
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
|
||||
Він взаємодіє **безпосередньо з WebSocket Gateway** на тому самому порту.
|
||||
Він взаємодіє **безпосередньо з Gateway WebSocket** на тому самому порту.
|
||||
|
||||
## Швидке відкриття (локально)
|
||||
|
||||
@ -27,7 +27,7 @@ x-i18n:
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (або [http://localhost:18789/](http://localhost:18789/))
|
||||
|
||||
Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`.
|
||||
Якщо сторінка не завантажується, спершу запустіть Gateway: `openclaw gateway`.
|
||||
|
||||
Автентифікація передається під час WebSocket-рукостискання через:
|
||||
|
||||
@ -36,116 +36,116 @@ x-i18n:
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань дашборда зберігає токен для поточного сеансу вкладки браузера й вибраного URL Gateway; паролі не зберігаються. Початкове налаштування зазвичай генерує токен Gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай генерує токен gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Спарювання пристрою (перше підключення)
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
Коли ви підключаєтеся до інтерфейсу керування з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення спарювання**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
|
||||
**Що ви побачите:** "відключено (1008): потрібне спарювання"
|
||||
**Що ви побачите:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Перелічити запити в очікуванні">
|
||||
<Step title="Перелічіть запити, що очікують">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Схвалити за ID запиту">
|
||||
<Step title="Схваліть за ID запиту">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо браузер повторює спарювання зі зміненими даними автентифікації (роль/області дії/відкритий ключ), попередній запит в очікуванні замінюється, і створюється новий `requestId`. Перед схваленням повторно виконайте `openclaw devices list`.
|
||||
Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, і створюється новий `requestId`. Повторно запустіть `openclaw devices list` перед схваленням.
|
||||
|
||||
Якщо браузер уже спарено, і ви змінюєте його доступ із читання на запис/адміністрування, це розглядається як підвищення рівня схвалення, а не як тихе повторне підключення. OpenClaw зберігає старе схвалення активним, блокує ширше повторне підключення й просить явно схвалити новий набір областей дії.
|
||||
Якщо браузер уже сполучений і ви змінюєте для нього доступ із читання на запис/admin, це вважається підвищенням схвалення, а не тихим повторним підключенням. OpenClaw залишає старе схвалення активним, блокує ширше повторне підключення та просить явно схвалити новий набір областей доступу.
|
||||
|
||||
Після схвалення пристрій запам’ятовується й не потребуватиме повторного схвалення, якщо ви не відкличете його командою `openclaw devices revoke --device <id> --role <role>`. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів.
|
||||
Після схвалення пристрій запам’ятовується й не потребуватиме повторного схвалення, якщо ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <role>`. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів.
|
||||
|
||||
<Note>
|
||||
- Прямі браузерні підключення через local loopback (`127.0.0.1` / `localhost`) схвалюються автоматично.
|
||||
- Tailscale Serve може пропустити цикл спарювання для операторських сеансів інтерфейсу керування, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджено, а браузер надає ідентичність свого пристрою.
|
||||
- Прямі прив’язки Tailnet, браузерні підключення з LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тож зміна браузера або очищення даних браузера вимагатиме повторного спарювання.
|
||||
- Tailscale Serve може пропускати цикл сполучення для операторських сесій Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale перевірено, а браузер надає ідентичність свого пристрою.
|
||||
- Прямі прив’язки Tailnet, браузерні підключення з LAN і профілі браузера без ідентичності пристрою все одно потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому перемикання браузерів або очищення даних браузера вимагатиме повторного сполучення.
|
||||
|
||||
</Note>
|
||||
|
||||
## Особиста ідентичність (локальна для браузера)
|
||||
|
||||
Інтерфейс керування підтримує особисту ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сеансах. Вона зберігається в сховищі браузера, прив’язана до поточного профілю браузера й не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства в транскрипті для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або зміна браузера скидає її до порожнього стану.
|
||||
Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається в сховищі браузера, обмежена поточним профілем браузера та не синхронізується з іншими пристроями й не зберігається на сервері, окрім звичайних метаданих авторства в стенограмі для повідомлень, які ви справді надсилаєте. Очищення даних сайту або перемикання браузерів скидає її до порожнього стану.
|
||||
|
||||
Та сама локальна для браузера схема застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на ідентичність, визначену Gateway, лише в локальному браузері й ніколи не проходять повний цикл через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів без UI, які записують це поле напряму (наприклад, скриптових gateway або користувацьких дашбордів).
|
||||
Та сама локальна для браузера схема застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на ідентичність, визначену gateway, лише в локальному браузері й ніколи не проходять туди й назад через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, скриптовані gateway або користувацькі дашборди).
|
||||
|
||||
## Ендпоїнт конфігурації часу виконання
|
||||
## Ендпоїнт runtime-конфігурації
|
||||
|
||||
Інтерфейс керування отримує свої налаштування часу виконання з `/__openclaw/control-ui-config.json`. Цей ендпоїнт захищено тією самою автентифікацією gateway, що й решту HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а успішне отримання потребує вже дійсного токена/пароля Gateway, ідентичності Tailscale Serve або ідентичності довіреного проксі.
|
||||
Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Цей ендпоїнт захищено тією самою автентифікацією gateway, що й решту HTTP-поверхні: неавтентифіковані браузери не можуть отримати його, а успішне отримання вимагає або вже дійсного токена/пароля gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
|
||||
## Підтримка мов
|
||||
|
||||
Інтерфейс керування може локалізуватися під час першого завантаження на основі локалі вашого браузера. Щоб перевизначити її пізніше, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Вибір локалі розміщено в картці доступу до Gateway, а не в розділі вигляду.
|
||||
Control UI може локалізувати себе під час першого завантаження на основі локалі вашого браузера. Щоб перевизначити її пізніше, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Вибір локалі розміщено в картці доступу до Gateway, а не в розділі зовнішнього вигляду.
|
||||
|
||||
- Підтримувані локалі: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Неанглійські переклади ліниво завантажуються в браузері.
|
||||
- Вибрана локаль зберігається в сховищі браузера й повторно використовується під час майбутніх відвідувань.
|
||||
- Переклади неанглійськими мовами ліниво завантажуються в браузері.
|
||||
- Вибрана локаль зберігається в сховищі браузера та повторно використовується під час майбутніх відвідувань.
|
||||
- Відсутні ключі перекладу повертаються до англійської.
|
||||
|
||||
Переклади документації генеруються для того самого набору неанглійських локалей, але вбудований перемикач мов сайту документації Mintlify обмежений кодами локалей, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) все ще генерується в репозиторії публікації; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди.
|
||||
Переклади документації генеруються для того самого набору неанглійських локалей, але вбудований перемикач мов сайту документації Mintlify обмежений кодами локалей, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) все одно генерується в publish-репозиторії; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди.
|
||||
|
||||
## Теми вигляду
|
||||
## Теми зовнішнього вигляду
|
||||
|
||||
Панель вигляду зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [редактор tweakcn](https://tweakcn.com/editor/theme), виберіть або створіть тему, натисніть **Поділитися** й вставте скопійоване посилання теми у вигляд. Імпортер також приймає URL реєстру `https://tweakcn.com/r/themes/<id>`, URL редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/<id>`, сирі ID тем і стандартні назви тем, такі як `amethyst-haze`.
|
||||
Панель зовнішнього вигляду зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [редактор tweakcn](https://tweakcn.com/editor/theme), виберіть або створіть тему, натисніть **Поділитися** та вставте скопійоване посилання теми в розділ зовнішнього вигляду. Імпортер також приймає URL-адреси реєстру `https://tweakcn.com/r/themes/<id>`, URL-адреси редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/<id>`, сирі ID тем і типові назви тем, як-от `amethyst-haze`.
|
||||
|
||||
Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в конфігурацію gateway і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; очищення перемикає активну тему назад на Claw, якщо імпортовану тему було вибрано.
|
||||
Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в конфігурацію gateway і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; її очищення повертає активну тему до Claw, якщо було вибрано імпортовану тему.
|
||||
|
||||
## Що він може робити (сьогодні)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Чат і розмова">
|
||||
- Спілкуватися в чаті з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Розмовляти через браузерні сеанси реального часу. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а голосові Plugin реального часу лише з бекендом використовують relay-транспорт Gateway. Relay зберігає облікові дані провайдера на Gateway, поки браузер передає мікрофонний PCM через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Транслювати виклики інструментів і картки виводу інструментів наживо в чаті (події агента).
|
||||
- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Розмовляти через браузерні realtime-сесії. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а backend-only realtime voice plugins використовують relay-транспорт Gateway. Relay зберігає облікові дані провайдера на Gateway, тоді як браузер транслює PCM мікрофона через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Транслювати виклики інструментів + картки живого виводу інструментів у Chat (події агента).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Канали, інстанси, сеанси, сни">
|
||||
- Канали: статус вбудованих, а також комплектних/зовнішніх plugin-каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
<Accordion title="Канали, інстанси, сесії, сни">
|
||||
- Канали: статус вбудованих і bundled/external plugin-каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Інстанси: список присутності + оновлення (`system-presence`).
|
||||
- Сеанси: список + перевизначення моделі/мислення/швидкого режиму/докладності/трасування/reasoning для кожного сеансу (`sessions.list`, `sessions.patch`).
|
||||
- Сни: статус Dreaming, перемикач увімкнення/вимкнення та читач щоденника снів (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- Сесії: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Сни: статус Dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, skills, nodes, схвалення exec">
|
||||
<Accordion title="Cron, Skills, nodes, схвалення exec">
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`).
|
||||
- Вузли: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування списків дозволів gateway або вузла + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Nodes: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування allowlist для gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація">
|
||||
- Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останнього активного сеансу.
|
||||
- Записи містять захист базовим хешем, щоб запобігти перезапису паралельних редагувань.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для посилань у надісланому payload конфігурації; нерозв’язані активні надіслані посилання відхиляються до запису.
|
||||
- Схема + рендеринг форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, підібраними UI-підказками, зведеннями безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах object/wildcard/array/composition, а також схемами plugin + channel, коли вони доступні); редактор Raw JSON доступний лише тоді, коли знімок має безпечний сирий повний цикл.
|
||||
- Якщо знімок не може безпечно виконати повний цикл сирого тексту, інтерфейс керування примусово вмикає режим форми й вимикає сирий режим для цього знімка.
|
||||
- "Скинути до збереженого" в редакторі Raw JSON зберігає сиро створену форму (форматування, коментарі, компонування `$include`) замість повторного рендерингу сплощеного знімка, тож зовнішні редагування переживають скидання, коли знімок може безпечно виконати повний цикл.
|
||||
- Структуровані об’єктні значення SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок.
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії.
|
||||
- Записи включають захист base-hash, щоб запобігти перезапису паралельних правок.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють активне розв’язання SecretRef для посилань у надісланому payload конфігурації; нерозв’язані активні надіслані посилання відхиляються перед записом.
|
||||
- Рендеринг схеми + форми (`config.schema` / `config.schema.lookup`, включно з `title` / `description` поля, відповідними підказками UI, зведеннями безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах object/wildcard/array/composition, а також схемами plugin + channel, коли вони доступні); редактор Raw JSON доступний лише тоді, коли snapshot має безпечний raw round-trip.
|
||||
- Якщо snapshot не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим форми й вимикає режим Raw для цього snapshot.
|
||||
- Редактор Raw JSON "Скинути до збереженого" зберігає форму, створену в raw (форматування, коментарі, розміщення `$include`), замість повторного рендерингу сплощеного snapshot, тож зовнішні правки переживають скидання, коли snapshot може безпечно пройти round-trip.
|
||||
- Структуровані значення об’єктів SecretRef рендеряться лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню object-to-string.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Налагодження, журнали, оновлення">
|
||||
- Налагодження: знімки статусу/стану/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнали: live-tail файлових журналів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск оновлення пакета/git + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення для перевірки запущеної версії gateway.
|
||||
<Accordion title="Налагодження, логи, оновлення">
|
||||
- Налагодження: snapshot статусу/health/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Логи: live tail файлових логів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск package/git update + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення для перевірки поточної версії gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Нотатки панелі завдань Cron">
|
||||
- Для ізольованих завдань доставка типово оголошує зведення. Ви можете перемкнути на «немає», якщо потрібні лише внутрішні запуски.
|
||||
- Поля каналу/цілі з’являються, коли вибрано оголошення.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, заданим як дійсний URL Webhook HTTP(S).
|
||||
- Для завдань головного сеансу доступні режими доставки Webhook і «немає».
|
||||
- Розширені елементи керування редагуванням включають видалення після запуску, очищення перевизначення агента, точні/рознесені параметри cron, перевизначення моделі/мислення агента та перемикачі доставки за принципом best effort.
|
||||
- Валідація форми виконується inline з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не буде виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer-токен; якщо його пропущено, Webhook надсилається без заголовка автентифікації.
|
||||
- Для ізольованих завдань доставка типово оголошує зведення. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
|
||||
- Поля channel/target з’являються, коли вибрано announce.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, встановленим на дійсну URL-адресу HTTP(S) webhook.
|
||||
- Для завдань main-session доступні режими доставки webhook і none.
|
||||
- Розширені елементи редагування включають delete-after-run, clear agent override, точні/зміщені параметри cron, перевизначення agent model/thinking і best-effort перемикачі доставки.
|
||||
- Валідація форми вбудована з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надіслати окремий bearer-токен; якщо пропущено, webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий fallback: збережені legacy-завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
|
||||
|
||||
</Accordion>
|
||||
@ -155,54 +155,54 @@ x-i18n:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Семантика надсилання та історії">
|
||||
- `chat.send` є **неблокувальним**: він одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь передається потоково через події `chat`.
|
||||
- Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають нативний шлях до зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення.
|
||||
- `chat.send` є **неблокувальним**: він одразу підтверджує з `{ runId, status: "started" }`, а відповідь передається потоково через події `chat`.
|
||||
- Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають рідний шлях зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення.
|
||||
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення.
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту завеликі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення, створені асистентом, зберігаються як керовані медіапосилання та повертаються через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи залишаються сирі base64-навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також вилучає з видимого тексту асистента службові вбудовані теги директив лише для відображення (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), текстові XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), а також просочені ASCII/повноширинні керівні токени моделі, і пропускає записи асистента, увесь видимий текст яких є лише точним мовчазним токеном `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату зберігає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` на короткий час повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє.
|
||||
- Події `chat` наживо є станом доставки, тоді як `chat.history` перебудовується зі стійкого транскрипту сеансу. Після фінальних подій інструментів інтерфейс керування перезавантажує історію та зливає лише невеликий оптимістичний хвіст; межу транскрипту задокументовано в [WebChat](/uk/web/webchat).
|
||||
- `chat.inject` додає нотатку асистента до транскрипту сеансу та транслює подію `chat` для оновлень лише UI (без запуску агента й без доставки каналом).
|
||||
- Перемикачі моделі та мислення в заголовку чату негайно виправляють активний сеанс через `sessions.patch`; це сталі перевизначення сеансу, а не одноразові параметри надсилання на один хід.
|
||||
- Введення `/new` в інтерфейсі керування створює та перемикає на такий самий новий сеанс панелі, як New Chat. Введення `/reset` зберігає явне скидання Gateway на місці для поточного сеансу.
|
||||
- Перемикач моделі чату запитує налаштоване подання моделей Gateway. Якщо наявний `agents.defaults.models`, цей список дозволених значень керує перемикачем. Інакше перемикач показує явні записи `models.providers.*.models` плюс провайдерів із придатною автентифікацією. Повний каталог залишається доступним через налагоджувальний RPC `models.list` із `view: "all"`.
|
||||
- Коли свіжі звіти про використання сеансу Gateway показують високий тиск контексту, область компонувальника чату показує повідомлення про контекст і, на рекомендованих рівнях Compaction, компактну кнопку, яка запускає звичайний шлях Compaction сеансу. Застарілі знімки токенів приховані, доки Gateway знову не повідомить свіже використання.
|
||||
- Відповіді `chat.history` мають обмеження розміру для безпеки UI. Коли записи транскрипту завеликі, Gateway може обрізати довгі текстові поля, опускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення асистента або згенеровані зображення зберігаються як посилання на керовані медіа й віддаються назад через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи залишаються сирі base64-навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також вилучає з видимого тексту асистента інлайн-теги директив, призначені лише для відображення (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), простотекстові XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` та обрізані блоки викликів інструментів), а також витеклі ASCII/повноширинні керівні токени моделі, і опускає записи асистента, увесь видимий текст яких є лише точним тихим токеном `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату зберігає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` ненадовго повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє.
|
||||
- Живі події `chat` є станом доставки, тоді як `chat.history` перебудовується зі стійкого транскрипту сесії. Після фінальних подій інструментів Control UI перезавантажує історію та зливає лише невеликий оптимістичний хвіст; межу транскрипту задокументовано в [WebChat](/uk/web/webchat).
|
||||
- `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки каналом).
|
||||
- Вибирачі моделі й режиму мислення в заголовку чату негайно змінюють активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не опції надсилання лише для одного ходу.
|
||||
- Введення `/new` у Control UI створює ту саму нову сесію панелі керування, що й New Chat, і перемикається на неї. Введення `/reset` зберігає явне скидання Gateway на місці для поточної сесії.
|
||||
- Вибирач моделі чату запитує налаштоване подання моделей Gateway. Якщо присутній `agents.defaults.models`, цей список дозволених значень керує вибирачем. Інакше вибирач показує явні записи `models.providers.*.models` плюс провайдерів із придатною автентифікацією. Повний каталог лишається доступним через налагоджувальний RPC `models.list` з `view: "all"`.
|
||||
- Коли свіжі звіти використання сесії Gateway показують високий тиск контексту, область компонувальника чату показує повідомлення про контекст і, на рекомендованих рівнях compaction, компактну кнопку, що запускає звичайний шлях compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Режим розмови (браузерний realtime)">
|
||||
Режим розмови використовує зареєстрованого realtime-провайдера голосу. Налаштуйте OpenAI з `talk.provider: "openai"` плюс `talk.providers.openai.apiKey` або налаштуйте Google з `talk.provider: "google"` плюс `talk.providers.google.apiKey`; конфігурацію realtime-провайдера Voice Call усе ще можна повторно використати як резервну. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений токен автентифікації Live API для браузерного сеансу WebSocket, причому інструкції та декларації інструментів зафіксовані в токені Gateway. Провайдери, які відкривають лише бекендний realtime-міст, працюють через ретрансляційний транспорт Gateway, тож облікові дані та сокети постачальника залишаються на сервері, а браузерне аудіо проходить через автентифіковані RPC Gateway. Підказку сеансу Realtime збирає Gateway; `talk.realtime.session` не приймає перевизначень інструкцій, наданих викликачем.
|
||||
<Accordion title="Режим розмови (браузер у реальному часі)">
|
||||
Режим розмови використовує зареєстрованого провайдера голосу в реальному часі. Налаштуйте OpenAI з `talk.provider: "openai"` плюс `talk.providers.openai.apiKey` або налаштуйте Google з `talk.provider: "google"` плюс `talk.providers.google.apiKey`; конфігурацію провайдера реального часу Voice Call усе ще можна повторно використати як резервну. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений токен автентифікації Live API для браузерної WebSocket-сесії, з інструкціями та оголошеннями інструментів, зафіксованими в токені Gateway. Провайдери, які надають лише бекенд-міст реального часу, працюють через ретрансляційний транспорт Gateway, тож облікові дані та vendor-сокети лишаються на серверному боці, а аудіо браузера проходить через автентифіковані RPC Gateway. Підказку Realtime-сесії збирає Gateway; `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем.
|
||||
|
||||
У компонувальнику чату керування Talk — це кнопка з хвилями поруч із кнопкою диктування мікрофоном. Коли Talk запускається, рядок стану компонувальника показує `Connecting Talk...`, потім `Talk live`, поки аудіо підключене, або `Asking OpenClaw...`, поки realtime-виклик інструмента консультується з налаштованою більшою моделлю через `chat.send`.
|
||||
У компонувальнику чату елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану компонувальника показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключено, або `Asking OpenClaw...`, доки виклик інструменту в реальному часі звертається до налаштованої більшої моделі через `chat.send`.
|
||||
|
||||
Живий smoke для супровідників: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє браузерний обмін SDP WebRTC OpenAI, налаштування браузерного WebSocket Google Live з обмеженим токеном і браузерний адаптер ретрансляції Gateway з фейковим медіа мікрофона. Команда друкує лише стан провайдера й не журналює секрети.
|
||||
Живий smoke-тест для супровідників: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє обмін SDP браузерного WebRTC OpenAI, налаштування браузерного WebSocket Google Live з обмеженим токеном і браузерний адаптер ретрансляції Gateway з фальшивим мікрофонним медіа. Команда друкує лише статус провайдера й не записує секрети в журнал.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Зупинка та переривання">
|
||||
- Натисніть **Stop** (викликає `chat.abort`).
|
||||
- Поки виконання активне, звичайні наступні повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це наступне повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання на кшталт `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним каналом.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних виконань цього сеансу.
|
||||
- Натисніть **Зупинити** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні наступні повідомлення стають у чергу. Натисніть **Скерувати** на повідомленні в черзі, щоб впровадити це наступне повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним потоком.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`), щоб перервати всі активні запуски для цієї сесії.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Збереження часткового результату після переривання">
|
||||
- Коли виконання перервано, частковий текст асистента все ще може показуватися в UI.
|
||||
- Gateway зберігає перерваний частковий текст асистента в історію транскрипту, коли буферизований вивід існує.
|
||||
- Коли запуск перервано, частковий текст асистента все ще може показуватися в UI.
|
||||
- Gateway зберігає перерваний частковий текст асистента в історії транскрипту, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізняти часткові результати переривання від звичайного виводу завершення.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Встановлення PWA та Web Push
|
||||
## Встановлення PWA та web push
|
||||
|
||||
Інтерфейс керування постачається з `manifest.webmanifest` і service worker, тому сучасні браузери можуть установлювати його як самостійну PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладка або вікно браузера не відкриті.
|
||||
Control UI постачається з `manifest.webmanifest` і service worker, тому сучасні браузери можуть встановлювати його як окрему PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладка або вікно браузера не відкриті.
|
||||
|
||||
| Поверхня | Що вона робить |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він доступний. |
|
||||
| `ui/public/sw.js` | Service worker, який обробляє події `push` і кліки сповіщень. |
|
||||
| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, використана для підписування навантажень Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Збережені кінцеві точки підписок браузера. |
|
||||
| ----------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він стає доступним. |
|
||||
| `ui/public/sw.js` | Service worker, який обробляє події `push` і натискання сповіщень. |
|
||||
| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, що використовується для підпису Web Push-навантажень. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoint-и браузерних підписок. |
|
||||
|
||||
Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно зафіксувати ключі (для розгортань на кількох хостах, ротації секретів або тестів):
|
||||
|
||||
@ -210,27 +210,27 @@ x-i18n:
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (за замовчуванням `mailto:openclaw@localhost`)
|
||||
|
||||
Інтерфейс керування використовує ці обмежені областю методи Gateway для реєстрації та тестування браузерних підписок:
|
||||
Control UI використовує ці обмежені областю методи Gateway для реєстрації та тестування браузерних підписок:
|
||||
|
||||
- `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID.
|
||||
- `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`.
|
||||
- `push.web.unsubscribe` — видаляє зареєстровану кінцеву точку.
|
||||
- `push.web.unsubscribe` — видаляє зареєстрований endpoint.
|
||||
- `push.web.test` — надсилає тестове сповіщення до підписки викликача.
|
||||
|
||||
<Note>
|
||||
Web Push не залежить від шляху ретрансляції iOS APNS (див. [Конфігурацію](/uk/gateway/configuration) для push із підтримкою ретрансляції) і наявного методу `push.test`, які націлені на нативне мобільне сполучення.
|
||||
Web Push незалежний від шляху ретрансляції iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із ретрансляцією) і наявного методу `push.test`, які націлені на нативне мобільне спарювання.
|
||||
</Note>
|
||||
|
||||
## Розміщені вбудовування
|
||||
## Розміщені вбудування
|
||||
|
||||
Повідомлення асистента можуть показувати розміщений вебвміст вбудовано за допомогою шорткоду `[embed ...]`. Політикою пісочниці iframe керує `gateway.controlUi.embedSandbox`:
|
||||
Повідомлення асистента можуть відтворювати розміщений вебвміст інлайн за допомогою shortcode `[embed ...]`. Політикою sandbox для iframe керує `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Вимикає виконання скриптів усередині розміщених вбудовувань.
|
||||
Вимикає виконання скриптів у розміщених вбудуваннях.
|
||||
</Tab>
|
||||
<Tab title="scripts (за замовчуванням)">
|
||||
Дозволяє інтерактивні вбудовування, зберігаючи ізоляцію origin; це типовий режим, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
<Tab title="scripts (default)">
|
||||
Дозволяє інтерактивні вбудування, зберігаючи ізоляцію origin; це значення за замовчуванням і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту, яким навмисно потрібні сильніші привілеї.
|
||||
@ -250,14 +250,14 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна поведінка same-origin. Для більшості створених агентом ігор та інтерактивних полотен `scripts` є безпечнішим вибором.
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує поведінки same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором.
|
||||
</Warning>
|
||||
|
||||
Абсолютні зовнішні URL вбудовування `http(s)` залишаються заблокованими за замовчуванням. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Абсолютні зовнішні URL вбудувань `http(s)` за замовчуванням лишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Ширина повідомлення чату
|
||||
|
||||
Згруповані повідомлення чату використовують читабельну стандартну максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без виправлення вбудованого CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Згруповані повідомлення чату використовують читабельну максимальну ширину за замовчуванням. Розгортання на широких моніторах можуть перевизначити її без зміни вбудованого CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,13 +269,13 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
}
|
||||
```
|
||||
|
||||
Значення перевіряється до того, як потрапить у браузер. Підтримувані значення включають прості довжини та відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
Значення перевіряється перед тим, як потрапить у браузер. Підтримувані значення включають прості довжини та відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
|
||||
## Доступ до tailnet (рекомендовано)
|
||||
## Доступ tailnet (рекомендовано)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Інтегрований Tailscale Serve (бажано)">
|
||||
Тримайте Gateway на local loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
Тримайте Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,16 +285,16 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
За замовчуванням запити інтерфейсу керування/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, та приймає такі запити лише коли вони надходять на loopback із заголовками `x-forwarded-*` від Tailscale. Для операторських сеансів інтерфейсу керування з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає повторний цикл сполучення пристрою; браузери без пристрою та з'єднання з роллю вузла все ще проходять звичайні перевірки пристрою. Установіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані зі спільним секретом навіть для трафіку Serve. Тоді використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
За замовчуванням запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` за допомогою `tailscale whois` і зіставляючи її із заголовком, і приймає їх лише тоді, коли запит надходить на loopback із заголовками `x-forwarded-*` Tailscale. Для операторських сесій Control UI з ідентичністю пристрою браузера цей перевірений шлях Serve також пропускає цикл спарювання пристрою; браузери без пристрою та підключення з роллю node усе ще проходять звичайні перевірки пристрою. Установіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта та області автентифікації серіалізуються перед записами обмеження частоти. Тому одночасні невдалі повторні спроби з того самого браузера можуть показувати `retry later` у другому запиті замість двох звичайних невідповідностей, що виконуються паралельно.
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта та області автентифікації серіалізуються перед записами обмеження частоти. Тому одночасні невдалі повтори з того самого браузера можуть показати `retry later` у другому запиті замість двох звичайних невідповідностей, що змагаються паралельно.
|
||||
|
||||
<Warning>
|
||||
Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Прив'язати до tailnet + token">
|
||||
<Tab title="Прив’язка до tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -303,20 +303,20 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
Вставте відповідний спільний секрет у налаштування UI (надсилається як `connect.params.auth.token` або `connect.params.auth.password`).
|
||||
Вставте відповідний shared secret у налаштування UI (надсилається як `connect.params.auth.token` або `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Небезпечний HTTP
|
||||
|
||||
Якщо ви відкриваєте панель через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **небезпечному контексті** та блокує WebCrypto. За замовчуванням OpenClaw **блокує** підключення інтерфейсу керування без ідентичності пристрою.
|
||||
Якщо ви відкриваєте панель керування через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **незахищеному контексті** й блокує WebCrypto. За замовчуванням OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
|
||||
|
||||
Задокументовані винятки:
|
||||
|
||||
- сумісність небезпечного HTTP лише для localhost із `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішна автентифікація операторського інтерфейсу керування через `gateway.auth.mode: "trusted-proxy"`
|
||||
- аварійний `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- сумісність небезпечного HTTP лише для localhost з `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішна операторська автентифікація Control UI через `gateway.auth.mode: "trusted-proxy"`
|
||||
- аварійне `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально:
|
||||
|
||||
@ -324,7 +324,7 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Insecure-auth toggle behavior">
|
||||
<Accordion title="Поведінка перемикача небезпечної автентифікації">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -337,12 +337,12 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
|
||||
`allowInsecureAuth` — це лише локальний перемикач сумісності:
|
||||
|
||||
- Він дозволяє сеансам localhost Control UI продовжувати роботу без ідентичності пристрою в незахищених HTTP-контекстах.
|
||||
- Він дозволяє сеансам localhost Control UI продовжувати роботу без ідентичності пристрою в небезпечних HTTP-контекстах.
|
||||
- Він не обходить перевірки сполучення.
|
||||
- Він не послаблює вимоги до ідентичності віддалених (не localhost) пристроїв.
|
||||
- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Break-glass only">
|
||||
<Accordion title="Лише для аварійного доступу">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,30 +354,30 @@ Web Push не залежить від шляху ретрансляції iOS AP
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є суттєвим зниженням безпеки. Швидко скасуйте це після екстреного використання.
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в Control UI та є серйозним зниженням рівня безпеки. Швидко скасуйте це після аварійного використання.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Trusted-proxy note">
|
||||
- Успішна автентифікація trusted-proxy може дозволити сеанси Control UI **оператора** без ідентичності пристрою.
|
||||
<Accordion title="Примітка про довірений проксі">
|
||||
- Успішна автентифікація через довірений проксі може допускати сеанси Control UI **оператора** без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси Control UI з роллю вузла.
|
||||
- Зворотні проксі same-host loopback все одно не задовольняють автентифікацію trusted-proxy; див. [Автентифікація trusted proxy](/uk/gateway/trusted-proxy-auth).
|
||||
- Зворотні проксі same-host loopback усе одно не задовольняють автентифікацію через довірений проксі; див. [автентифікацію через довірений проксі](/uk/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Див. [Tailscale](/uk/gateway/tailscale), щоб отримати вказівки з налаштування HTTPS.
|
||||
Див. [Tailscale](/uk/gateway/tailscale), щоб отримати настанови з налаштування HTTPS.
|
||||
|
||||
## Політика безпеки вмісту
|
||||
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **same-origin**, URL-адреси `data:` і локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не спричиняють мережевих запитів.
|
||||
Control UI постачається зі суворою політикою `img-src`: дозволені лише ресурси **того самого джерела**, URL-адреси `data:` та локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не запускають мережеві запити.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), і далі відображаються, включно з автентифікованими маршрутами аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` і далі відображаються (корисно для корисних навантажень у протоколі).
|
||||
- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), і далі відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` і далі відображаються (корисно для payload у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені Control UI, і далі відображаються.
|
||||
- Віддалені URL-адреси аватарів, емітовані метаданими каналу, видаляються в допоміжних функціях аватарів Control UI і замінюються вбудованим логотипом/значком, тож скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Віддалені URL-адреси аватарів, які випускають метадані каналу, видаляються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
|
||||
@ -386,10 +386,20 @@ Control UI постачається зі строгою політикою `img-
|
||||
Коли автентифікацію gateway налаштовано, кінцева точка аватара Control UI вимагає той самий токен gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до сусіднього маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення й далі відображалося на інформаційних панелях.
|
||||
- Неавтентифіковані запити до будь-якого з маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення й далі відображалося на панелях.
|
||||
|
||||
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти gateway.
|
||||
Якщо ви вимикаєте автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стає неавтентифікованим, відповідно до решти gateway.
|
||||
|
||||
## Автентифікація маршруту медіа асистента
|
||||
|
||||
Коли автентифікацію gateway налаштовано, локальні попередні перегляди медіа асистента використовують двоетапний маршрут:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` вимагає звичайну операторську автентифікацію Control UI. Браузер надсилає токен gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений саме цим шляхом джерела.
|
||||
- URL-адреси зображень, аудіо, відео й документів, які відображає браузер, використовують `mediaTicket=<ticket>` замість активного токена або пароля gateway. Квиток швидко спливає й не може авторизувати інше джерело.
|
||||
|
||||
Це зберігає сумісність звичайного відображення медіа з нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані gateway у видимих медіа-URL.
|
||||
|
||||
## Збирання UI
|
||||
|
||||
@ -399,36 +409,36 @@ Gateway обслуговує статичні файли з `dist/control-ui`.
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Необов'язкова абсолютна база (коли потрібні фіксовані URL-адреси ресурсів):
|
||||
Необов’язкова абсолютна база (коли потрібні фіксовані URL-адреси ресурсів):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Для локальної розробки (окремий сервер розробки):
|
||||
Для локальної розробки (окремий dev server):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Потім спрямуйте UI на URL Gateway WS (наприклад, `ws://127.0.0.1:18789`).
|
||||
Потім спрямуйте UI на URL вашого Gateway WS (наприклад, `ws://127.0.0.1:18789`).
|
||||
|
||||
## Налагодження/тестування: сервер розробки + віддалений Gateway
|
||||
## Налагодження/тестування: dev server + віддалений Gateway
|
||||
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP-джерела. Це зручно, коли ви хочете запускати сервер розробки Vite локально, а Gateway — деінде.
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли потрібен локальний dev server Vite, але Gateway працює в іншому місці.
|
||||
|
||||
<Steps>
|
||||
<Step title="Start the UI dev server">
|
||||
<Step title="Запустіть UI dev server">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
</Step>
|
||||
<Step title="Open with gatewayUrl">
|
||||
<Step title="Відкрийте з gatewayUrl">
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
Необов'язкова одноразова автентифікація (за потреби):
|
||||
Необов’язкова одноразова автентифікація (за потреби):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -438,18 +448,18 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notes">
|
||||
<Accordion title="Примітки">
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження та видаляється з URL.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` за можливості слід передавати через фрагмент URL (`#token=...`). Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` і далі імпортуються один раз для сумісності, але лише як резервний варіант, і видаляються одразу після bootstrap.
|
||||
- `password` зберігається лише в пам'яті.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, закодуйте значення `gatewayUrl` для URL, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`), коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` і далі імпортуються один раз для сумісності, але лише як fallback, і видаляються відразу після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway знаходиться за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS proxy тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking.
|
||||
- Нелокальні розгортання Control UI мають явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це включає віддалені середовища розробки.
|
||||
- Запуск Gateway може додавати локальні origins, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, з ефективних runtime bind і порту, але origins віддалених браузерів усе одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім жорстко контрольованого локального тестування. Це означає дозволити будь-який browser origin, а не "зіставляти будь-який хост, який я використовую."
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для Host-header origin, але це небезпечний режим безпеки.
|
||||
- Розгортання Control UI не через loopback мають явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це включає віддалені dev setups.
|
||||
- Запуск Gateway може додавати локальні origins, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, з ефективних runtime bind і port, але віддалені browser origins усе одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, крім суворо контрольованого локального тестування. Це означає дозволити будь-який browser origin, а не «зіставити будь-який хост, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin з Host-заголовка, але це небезпечний режим безпеки.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,11 +476,11 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
}
|
||||
```
|
||||
|
||||
Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Деталі налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов'язане
|
||||
## Пов’язане
|
||||
|
||||
- [Панель керування](/uk/web/dashboard) — панель керування gateway
|
||||
- [Перевірки справності](/uk/gateway/health) — моніторинг справності gateway
|
||||
- [Панель](/uk/web/dashboard) — панель gateway
|
||||
- [Health Checks](/uk/gateway/health) — моніторинг стану gateway
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
|
||||
|
||||
Loading…
Reference in New Issue
Block a user