chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
7d6f54782b
commit
01737ba5b5
@ -6,28 +6,28 @@ sidebarTitle: Control UI
|
||||
summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:53:54Z"
|
||||
generated_at: "2026-05-04T07:08:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_hash: 896c75116d7a396571017ac6e6db7ff6ce328617e44470c303fd41af58aa2bd7
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Інтерфейс Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
|
||||
- типово: `http://<host>:18789/`
|
||||
- за замовчуванням: `http://<host>:18789/`
|
||||
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
|
||||
Він взаємодіє **безпосередньо з Gateway WebSocket** на тому самому порту.
|
||||
Він працює **безпосередньо з Gateway WebSocket** на тому самому порту.
|
||||
|
||||
## Швидке відкриття (локально)
|
||||
|
||||
Якщо Gateway запущено на тому самому комп’ютері, відкрийте:
|
||||
Якщо Gateway працює на тому самому комп’ютері, відкрийте:
|
||||
|
||||
- [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,117 +36,118 @@ x-i18n:
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай генерує токен gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань інформаційної панелі зберігає токен для поточного сеансу вкладки браузера й вибраної URL-адреси gateway; паролі не зберігаються. Під час онбордингу зазвичай генерується токен gateway для автентифікації зі спільним секретом при першому підключенні, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
Коли ви підключаєтеся до інтерфейсу керування з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
|
||||
**Що ви побачите:** "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`.
|
||||
|
||||
Якщо браузер уже сполучений і ви змінюєте для нього доступ із читання на запис/admin, це вважається підвищенням схвалення, а не тихим повторним підключенням. OpenClaw залишає старе схвалення активним, блокує ширше повторне підключення та просить явно схвалити новий набір областей доступу.
|
||||
Якщо браузер уже сполучено, і ви змінюєте доступ із читання на запис/адміністрування, це розглядається як оновлення схвалення, а не тихе повторне підключення. 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 може пропускати цикл сполучення для операторських сесій Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale перевірено, а браузер надає ідентичність свого пристрою.
|
||||
- Прямі прив’язки Tailnet, браузерні підключення з LAN і профілі браузера без ідентичності пристрою все одно потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому перемикання браузерів або очищення даних браузера вимагатиме повторного сполучення.
|
||||
- Tailscale Serve може пропустити цикл сполучення для операторських сеансів інтерфейсу керування, коли `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-конфігурації
|
||||
## Кінцева точка runtime-конфігурації
|
||||
|
||||
Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Цей ендпоїнт захищено тією самою автентифікацією gateway, що й решту HTTP-поверхні: неавтентифіковані браузери не можуть отримати його, а успішне отримання вимагає або вже дійсного токена/пароля gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
Інтерфейс керування отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Ця кінцева точка захищена тією самою автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть її отримати, а успішне отримання потребує або вже чинного токена/пароля gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
|
||||
## Підтримка мов
|
||||
|
||||
Control UI може локалізувати себе під час першого завантаження на основі локалі вашого браузера. Щоб перевизначити її пізніше, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Вибір локалі розміщено в картці доступу до Gateway, а не в розділі зовнішнього вигляду.
|
||||
Інтерфейс керування може локалізуватися під час першого завантаження на основі локалі вашого браузера. Щоб змінити це пізніше, відкрийте **Огляд -> Доступ до 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`) все одно генерується в publish-репозиторії; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди.
|
||||
Переклади документації генеруються для того самого набору неанглійських локалей, але вбудований у сайт документації перемикач мов Mintlify обмежений кодами локалей, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) все одно генерується в репозиторії публікації; вона може не з’являтися в цьому перемикачі, доки 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`).
|
||||
- Розмовляти через браузерні 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 (події агента).
|
||||
- Спілкування з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Розмова через браузерні realtime-сеанси. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а backend-only realtime голосові plugins використовують relay-транспорт Gateway. Relay зберігає облікові дані провайдера на Gateway, поки браузер передає PCM із мікрофона через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Потокова передача викликів інструментів і живих карток виводу інструментів у чаті (події агента).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Канали, інстанси, сесії, сни">
|
||||
- Канали: статус вбудованих і bundled/external plugin-каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Інстанси: список присутності + оновлення (`system-presence`).
|
||||
- Сесії: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
<Accordion title="Канали, екземпляри, сеанси, сни">
|
||||
- Канали: статус вбудованих і bundled/external plugin-каналів, вхід через QR і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Екземпляри: список присутності + оновлення (`system-presence`).
|
||||
- Сеанси: список + перевизначення моделі/мислення/швидкого режиму/детальності/трасування/міркування для кожного сеансу (`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, вузли, схвалення exec">
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`).
|
||||
- Nodes: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування allowlist для gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Вузли: список + caps (`node.list`).
|
||||
- Схвалення exec: редагування allowlist gateway або вузла + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація">
|
||||
- Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Застосування + перезапуск із валідацією (`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.
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останнього активного сеансу.
|
||||
- Записи містять захист base-hash, щоб запобігти перезапису паралельних редагувань.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для ref у надісланому payload конфігурації; нерозв’язані активні надіслані ref відхиляються до запису.
|
||||
- Схема + відтворення форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, відповідними підказками UI, підсумками безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах object/wildcard/array/composition, а також схемами plugin + channel, коли вони доступні); редактор Raw JSON доступний лише тоді, коли snapshot має безпечний raw round-trip.
|
||||
- Якщо snapshot не може безпечно виконати round-trip сирого тексту, інтерфейс керування примусово вмикає режим форми й вимикає режим Raw для цього snapshot.
|
||||
- У редакторі Raw JSON "Скинути до збереженого" зберігає raw-authored форму (форматування, коментарі, макет `$include`) замість повторного відтворення сплющеного snapshot, тому зовнішні редагування переживають скидання, коли snapshot може безпечно виконати round-trip.
|
||||
- Структуровані об’єктні значення SecretRef відтворюються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Налагодження, логи, оновлення">
|
||||
- Налагодження: snapshot статусу/health/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Логи: live tail файлових логів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск package/git update + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення для перевірки поточної версії gateway.
|
||||
<Accordion title="Налагодження, журнали, оновлення">
|
||||
- Налагодження: snapshot статусу/здоров’я/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнал подій містить таймінги оновлення/RPC інтерфейсу керування, а також записи чутливості браузера для довгих кадрів анімації або довгих задач, коли браузер надає ці типи записів PerformanceObserver.
|
||||
- Журнали: live tail файлових журналів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск оновлення package/git + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Нотатки панелі завдань Cron">
|
||||
- Для ізольованих завдань доставка типово оголошує зведення. Ви можете перемкнути на 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 title="Примітки до панелі завдань Cron">
|
||||
- Для ізольованих завдань доставка за замовчуванням оголошує підсумок. Ви можете перемкнути на none, якщо потрібні лише внутрішні запуски.
|
||||
- Поля каналу/цілі з’являються, коли вибрано оголошення.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, встановленим на чинну HTTP(S) URL-адресу webhook.
|
||||
- Для завдань основного сеансу доступні режими доставки webhook і none.
|
||||
- Розширені елементи керування редагуванням містять видалення після запуску, очищення перевизначення агента, параметри exact/stagger для cron, перевизначення моделі/мислення агента й перемикачі best-effort доставки.
|
||||
- Валідація форми виконується inline з помилками на рівні поля; недійсні значення вимикають кнопку збереження, доки їх не виправлено.
|
||||
- Установіть `cron.webhookToken`, щоб надсилати окремий bearer-токен; якщо його пропущено, webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий fallback: збережені legacy-завдання з `notify: true` все ще можуть використовувати `cron.webhook`, доки їх не мігровано.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,62 +156,62 @@ Control UI може локалізувати себе під час першог
|
||||
|
||||
<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` перебудовується зі стійкого транскрипту сесії. Після фінальних подій інструментів 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 знову не повідомить свіже використання.
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи стенограми завеликі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення асистента або згенеровані зображення зберігаються як керовані медіапосилання та повертаються через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи залишаються сирі image payload у base64 у відповіді історії чату.
|
||||
- `chat.history` також прибирає з видимого тексту асистента лише-відображувані inline directive tags (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text tool-call XML payloads (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки tool-call), а також витеклі ASCII/full-width model control tokens, і пропускає записи асистента, весь видимий текст яких є лише точним silent token `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату залишає локальні оптимістичні повідомлення користувача/асистента видимими, якщо `chat.history` ненадовго повертає старіший знімок; канонічна стенограма замінює ці локальні повідомлення, щойно історія Gateway наздоганяє.
|
||||
- Live-події `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="Режим розмови (браузер у реальному часі)">
|
||||
Режим розмови використовує зареєстрованого провайдера голосу в реальному часі. Налаштуйте 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` не приймає перевизначення інструкцій, надані викликачем.
|
||||
Режим розмови використовує зареєстрованого провайдера голосу в реальному часі. Налаштуйте 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. Провайдери, які відкривають лише backend realtime bridge, працюють через relay transport Gateway, тому облікові дані та vendor sockets залишаються на боці сервера, а браузерне аудіо проходить через автентифіковані RPC Gateway. Запит сесії Realtime збирається Gateway; `talk.realtime.session` не приймає наданих викликачем перевизначень інструкцій.
|
||||
|
||||
У компонувальнику чату елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану компонувальника показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключено, або `Asking OpenClaw...`, доки виклик інструменту в реальному часі звертається до налаштованої більшої моделі через `chat.send`.
|
||||
У композиторі чату елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключене, або `Asking OpenClaw...`, доки realtime tool call консультується з налаштованою більшою моделлю через `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 з фальшивим мікрофонним медіа. Команда друкує лише статус провайдера й не записує секрети в журнал.
|
||||
Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє обмін SDP браузерного WebRTC OpenAI, налаштування браузерного WebSocket Google Live з constrained-token і браузерний адаптер Gateway relay із фейковим медіа мікрофона. Команда друкує лише статус провайдера й не журналює секрети.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Зупинка та переривання">
|
||||
- Натисніть **Зупинити** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні наступні повідомлення стають у чергу. Натисніть **Скерувати** на повідомленні в черзі, щоб впровадити це наступне повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним потоком.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`), щоб перервати всі активні запуски для цієї сесії.
|
||||
- Натисніть **Stop** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб ввести це подальше повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання на кшталт `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним каналом.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Збереження часткового результату після переривання">
|
||||
- Коли запуск перервано, частковий текст асистента все ще може показуватися в UI.
|
||||
- Gateway зберігає перерваний частковий текст асистента в історії транскрипту, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізняти часткові результати переривання від звичайного виводу завершення.
|
||||
- Gateway зберігає перерваний частковий текст асистента в історії стенограми, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі стенограми могли відрізняти часткові результати переривання від звичайного завершеного виводу.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Встановлення PWA та web push
|
||||
|
||||
Control UI постачається з `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` | Збережені endpoint-и браузерних підписок. |
|
||||
| `ui/public/sw.js` | Service worker, який обробляє події `push` і кліки сповіщень. |
|
||||
| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID для підпису Web Push payloads. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoints підписок браузера. |
|
||||
|
||||
Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно зафіксувати ключі (для розгортань на кількох хостах, ротації секретів або тестів):
|
||||
Перевизначте пару ключів VAPID через env vars у процесі Gateway, коли потрібно зафіксувати ключі (для розгортань на кількох хостах, ротації секретів або тестів):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (за замовчуванням `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (типово `mailto:openclaw@localhost`)
|
||||
|
||||
Control UI використовує ці обмежені областю методи Gateway для реєстрації та тестування браузерних підписок:
|
||||
Control UI використовує ці scope-gated методи Gateway для реєстрації та тестування браузерних підписок:
|
||||
|
||||
- `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID.
|
||||
- `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`.
|
||||
@ -218,22 +219,22 @@ Control UI використовує ці обмежені областю мет
|
||||
- `push.web.test` — надсилає тестове сповіщення до підписки викликача.
|
||||
|
||||
<Note>
|
||||
Web Push незалежний від шляху ретрансляції iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із ретрансляцією) і наявного методу `push.test`, які націлені на нативне мобільне спарювання.
|
||||
Web Push незалежний від шляху relay iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із relay) і наявного методу `push.test`, які націлені на нативне мобільне сполучення.
|
||||
</Note>
|
||||
|
||||
## Розміщені вбудування
|
||||
## Вбудовані hosted embeds
|
||||
|
||||
Повідомлення асистента можуть відтворювати розміщений вебвміст інлайн за допомогою shortcode `[embed ...]`. Політикою sandbox для iframe керує `gateway.controlUi.embedSandbox`:
|
||||
Повідомлення асистента можуть показувати hosted web content inline за допомогою shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Вимикає виконання скриптів у розміщених вбудуваннях.
|
||||
Вимикає виконання скриптів усередині hosted embeds.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Дозволяє інтерактивні вбудування, зберігаючи ізоляцію origin; це значення за замовчуванням і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це стандартний режим, якого зазвичай достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту, яким навмисно потрібні сильніші привілеї.
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для same-site документів, яким навмисно потрібні сильніші привілеї.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,14 +251,14 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує поведінки same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором.
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна поведінка same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvases `scripts` є безпечнішим вибором.
|
||||
</Warning>
|
||||
|
||||
Абсолютні зовнішні URL вбудувань `http(s)` за замовчуванням лишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Абсолютні зовнішні URL embeds `http(s)` за замовчуванням залишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Ширина повідомлення чату
|
||||
## Ширина повідомлень чату
|
||||
|
||||
Згруповані повідомлення чату використовують читабельну максимальну ширину за замовчуванням. Розгортання на широких моніторах можуть перевизначити її без зміни вбудованого CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Згруповані повідомлення чату використовують читабельну типову максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без патчення bundled CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,13 +270,13 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
}
|
||||
```
|
||||
|
||||
Значення перевіряється перед тим, як потрапить у браузер. Підтримувані значення включають прості довжини та відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
Значення перевіряється перед тим, як потрапити до браузера. Підтримувані значення охоплюють прості довжини й відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
|
||||
## Доступ tailnet (рекомендовано)
|
||||
## Доступ до tailnet (рекомендовано)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Інтегрований Tailscale Serve (бажано)">
|
||||
Тримайте Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
Залиште Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,12 +286,12 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
За замовчуванням запити 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"`.
|
||||
За замовчуванням запити 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-адреси клієнта й auth scope серіалізуються перед записами rate-limit. Тому одночасні невдалі повторні спроби з того самого браузера можуть показати `retry later` на другому запиті замість двох простих невідповідностей, що змагаються паралельно.
|
||||
|
||||
<Warning>
|
||||
Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
|
||||
Автентифікація Serve без токена передбачає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію token/password.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -310,15 +311,15 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
|
||||
## Небезпечний HTTP
|
||||
|
||||
Якщо ви відкриваєте панель керування через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **незахищеному контексті** й блокує WebCrypto. За замовчуванням OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
|
||||
Якщо ви відкриваєте панель через plain HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **небезпечному контексті** та блокує WebCrypto. За замовчуванням OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
|
||||
|
||||
Задокументовані винятки:
|
||||
|
||||
- сумісність небезпечного HTTP лише для localhost з `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішна операторська автентифікація Control UI через `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 локально:
|
||||
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте інтерфейс локально:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
@ -337,12 +338,12 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
|
||||
`allowInsecureAuth` — це лише локальний перемикач сумісності:
|
||||
|
||||
- Він дозволяє сеансам localhost Control UI продовжувати роботу без ідентичності пристрою в небезпечних HTTP-контекстах.
|
||||
- Він дозволяє локальним сеансам інтерфейсу керування продовжувати роботу без ідентичності пристрою в незахищених HTTP-контекстах.
|
||||
- Він не обходить перевірки сполучення.
|
||||
- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень.
|
||||
- Він не послаблює вимоги до ідентичності віддалених (не localhost) пристроїв.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Лише для аварійного доступу">
|
||||
<Accordion title="Лише аварійний доступ">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,56 +355,56 @@ Web Push незалежний від шляху ретрансляції iOS APN
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в Control UI та є серйозним зниженням рівня безпеки. Швидко скасуйте це після аварійного використання.
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою для інтерфейсу керування і є серйозним зниженням рівня безпеки. Швидко скасуйте це після екстреного використання.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Примітка про довірений проксі">
|
||||
- Успішна автентифікація через довірений проксі може допускати сеанси Control UI **оператора** без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси Control UI з роллю вузла.
|
||||
- Зворотні проксі same-host loopback усе одно не задовольняють автентифікацію через довірений проксі; див. [автентифікацію через довірений проксі](/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`: дозволені лише ресурси **того самого джерела**, URL-адреси `data:` та локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не запускають мережеві запити.
|
||||
Інтерфейс керування постачається зі суворою політикою `img-src`: дозволені лише ресурси **same-origin**, URL-адреси `data:` і локально створені URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не ініціюють мережевих запитів.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), і далі відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` і далі відображаються (корисно для payload у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені Control UI, і далі відображаються.
|
||||
- Віддалені URL-адреси аватарів, які випускають метадані каналу, видаляються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Аватари й зображення, що надаються за відносними шляхами (наприклад `/avatars/<id>`), продовжують відображатися, зокрема автентифіковані маршрути аватарів, які інтерфейс отримує й перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` продовжують відображатися (корисно для payload у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені інтерфейсом керування, продовжують відображатися.
|
||||
- Віддалені URL-адреси аватарів, які передаються метаданими каналу, видаляються допоміжними функціями аватарів інтерфейсу керування й замінюються вбудованим логотипом/бейджем, тож скомпрометований або зловмисний канал не може примусово виконувати довільні віддалені запити зображень із браузера оператора.
|
||||
|
||||
Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
Вам не потрібно нічого змінювати, щоб отримати цю поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
|
||||
## Автентифікація маршруту аватара
|
||||
## Автентифікація маршруту аватарів
|
||||
|
||||
Коли автентифікацію gateway налаштовано, кінцева точка аватара Control UI вимагає той самий токен gateway, що й решта API:
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватарів інтерфейсу керування вимагає той самий токен gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення й далі відображалося на панелях.
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам інтерфейс керування передає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення все одно відображалося на інформаційних панелях.
|
||||
|
||||
Якщо ви вимикаєте автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стає неавтентифікованим, відповідно до решти gateway.
|
||||
Якщо вимкнути автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватарів також стане неавтентифікованим, відповідно до решти gateway.
|
||||
|
||||
## Автентифікація маршруту медіа асистента
|
||||
|
||||
Коли автентифікацію gateway налаштовано, локальні попередні перегляди медіа асистента використовують двоетапний маршрут:
|
||||
Коли налаштовано автентифікацію gateway, попередній перегляд локальних медіа асистента використовує двоетапний маршрут:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` вимагає звичайну операторську автентифікацію Control UI. Браузер надсилає токен gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений саме цим шляхом джерела.
|
||||
- URL-адреси зображень, аудіо, відео й документів, які відображає браузер, використовують `mediaTicket=<ticket>` замість активного токена або пароля gateway. Квиток швидко спливає й не може авторизувати інше джерело.
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` вимагає звичайної операторської автентифікації інтерфейсу керування. Браузер надсилає токен gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений цим точним шляхом джерела.
|
||||
- URL-адреси зображень, аудіо, відео й документів, що відображаються браузером, використовують `mediaTicket=<ticket>` замість активного токена або пароля gateway. Квиток швидко спливає й не може авторизувати інше джерело.
|
||||
|
||||
Це зберігає сумісність звичайного відображення медіа з нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані gateway у видимих медіа-URL.
|
||||
Це зберігає звичайне відображення медіа сумісним із нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані gateway у видимих URL-адресах медіа.
|
||||
|
||||
## Збирання UI
|
||||
## Збирання інтерфейсу
|
||||
|
||||
Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
|
||||
Gateway надає статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
@ -415,20 +416,20 @@ pnpm ui:build
|
||||
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`).
|
||||
Потім спрямуйте інтерфейс на URL-адресу WS вашого Gateway (наприклад `ws://127.0.0.1:18789`).
|
||||
|
||||
## Налагодження/тестування: dev server + віддалений Gateway
|
||||
## Налагодження/тестування: сервер розробки + віддалений Gateway
|
||||
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли потрібен локальний dev server Vite, але Gateway працює в іншому місці.
|
||||
Інтерфейс керування — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли потрібен локальний сервер розробки Vite, але Gateway працює в іншому місці.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть UI dev server">
|
||||
<Step title="Запустіть сервер розробки інтерфейсу">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -449,17 +450,17 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Примітки">
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження та видаляється з URL.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, закодуйте значення `gatewayUrl` для URL, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`), коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` і далі імпортуються один раз для сумісності, але лише як fallback, і видаляються відразу після bootstrap.
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL-адреси.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) за кожної можливості. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як fallback, і негайно видаляються після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS proxy тощо).
|
||||
- Коли встановлено `gatewayUrl`, інтерфейс не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway перебуває за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання 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-заголовка, але це небезпечний режим безпеки.
|
||||
- Розгортання інтерфейсу керування не через loopback мають явно встановлювати `gateway.controlUi.allowedOrigins` (повні origins). Це включає віддалені середовища розробки.
|
||||
- Запуск Gateway може додати локальні origins, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, з ефективного runtime bind і порту, але віддалені origins браузера все одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім суворо контрольованого локального тестування. Це означає дозволити будь-який origin браузера, а не «зіставити будь-який хост, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin за Host-заголовком, але це небезпечний режим безпеки.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -476,11 +477,11 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
}
|
||||
```
|
||||
|
||||
Деталі налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Подробиці налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Панель](/uk/web/dashboard) — панель gateway
|
||||
- [Health Checks](/uk/gateway/health) — моніторинг стану gateway
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
|
||||
- [Інформаційна панель](/uk/web/dashboard) — інформаційна панель gateway
|
||||
- [Перевірки стану](/uk/gateway/health) — моніторинг стану gateway
|
||||
- [TUI](/uk/web/tui) — термінальний користувацький інтерфейс
|
||||
- [WebChat](/uk/web/webchat) — чат-інтерфейс на основі браузера
|
||||
|
||||
Loading…
Reference in New Issue
Block a user