chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
9234cb7dc3
commit
da7db2d0e9
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете керувати Gateway з браузера
|
||||
- Ви хочете керувати Gateway із браузера
|
||||
- Вам потрібен доступ до Tailnet без SSH-тунелів
|
||||
sidebarTitle: Control UI
|
||||
summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:08:57Z"
|
||||
generated_at: "2026-05-04T09:20:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 896c75116d7a396571017ac6e6db7ff6ce328617e44470c303fd41af58aa2bd7
|
||||
source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
Control UI — це невеликий односторінковий застосунок **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,180 +36,183 @@ x-i18n:
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань інформаційної панелі зберігає токен для поточного сеансу вкладки браузера й вибраної URL-адреси gateway; паролі не зберігаються. Під час онбордингу зазвичай генерується токен gateway для автентифікації зі спільним секретом при першому підключенні, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера й вибраної URL-адреси gateway; паролі не зберігаються. Онбординг зазвичай генерує gateway-токен для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
Коли ви підключаєтеся до інтерфейсу керування з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки для запобігання несанкціонованому доступу.
|
||||
|
||||
**Що ви побачите:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Список очікуваних запитів">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Схвалення за ID запиту">
|
||||
<Step title="Approve by request 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-конфігурації
|
||||
|
||||
Інтерфейс керування отримує свої 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`).
|
||||
- Розмова через браузерні 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 title="Chat and Talk">
|
||||
- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Розмовляти через браузерні realtime-сесії. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а голосові realtime plugins, що працюють лише на backend, використовують relay-транспорт Gateway. Relay зберігає облікові дані провайдера на Gateway, поки браузер транслює мікрофонний PCM через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw.
|
||||
- Потоково передавати виклики інструментів і live-картки виводу інструментів у Chat (події агента).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Канали, екземпляри, сеанси, сни">
|
||||
- Канали: статус вбудованих і bundled/external plugin-каналів, вхід через QR і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- Канали: статус вбудованих і 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`).
|
||||
- Сесії: список + перевизначення моделі/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Dreams: статус dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, вузли, схвалення exec">
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`).
|
||||
- Вузли: список + caps (`node.list`).
|
||||
- Схвалення exec: редагування allowlist gateway або вузла + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Nodes: список + caps (`node.list`).
|
||||
- Схвалення exec: редагування allowlist gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація">
|
||||
<Accordion title="Config">
|
||||
- Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останнього активного сеансу.
|
||||
- Застосування + перезапуск із валідацією (`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 відтворюються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для refs у надісланому payload конфігурації; нерозв’язані активні надіслані refs відхиляються до запису.
|
||||
- Schema + рендеринг форми (`config.schema` / `config.schema.lookup`, зокрема поля `title` / `description`, відповідні підказки UI, зведення безпосередніх дочірніх елементів, метадані документації на вкладених object/wildcard/array/composition nodes, а також plugin + channel schemas, коли доступні); редактор Raw JSON доступний лише тоді, коли snapshot має безпечний сирий round-trip.
|
||||
- Якщо snapshot не може безпечно виконати raw text round-trip, Control UI примусово вмикає режим Form і вимикає режим Raw для цього snapshot.
|
||||
- Редактор Raw JSON "Reset to saved" зберігає raw-authored форму (форматування, коментарі, структуру `$include`) замість повторного рендерингу сплющеного snapshot, тож зовнішні редагування переживають reset, коли snapshot може безпечно виконати round-trip.
|
||||
- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню object-to-string.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Налагодження, журнали, оновлення">
|
||||
- Налагодження: snapshot статусу/здоров’я/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнал подій містить таймінги оновлення/RPC інтерфейсу керування, а також записи чутливості браузера для довгих кадрів анімації або довгих задач, коли браузер надає ці типи записів PerformanceObserver.
|
||||
- Журнали: live tail файлових журналів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск оновлення package/git + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного gateway.
|
||||
<Accordion title="Debug, logs, update">
|
||||
- Debug: snapshot статусу/здоров’я/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнал подій містить часи refresh/RPC Control UI, а також записи чутливості браузера для довгих кадрів анімації або довгих завдань, коли браузер надає ці типи записів PerformanceObserver.
|
||||
- Logs: live tail файлових журналів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Update: запуск оновлення package/git + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного gateway.
|
||||
|
||||
</Accordion>
|
||||
<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 надсилається без заголовка автентифікації.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- Для ізольованих завдань доставлення типово оголошує зведення. Ви можете перемкнути на none, якщо потрібні лише внутрішні запуски.
|
||||
- Поля каналу/цілі з’являються, коли вибрано announce.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, встановленим на дійсну HTTP(S) webhook URL-адресу.
|
||||
- Для завдань main-session доступні режими доставлення webhook і none.
|
||||
- Розширені елементи керування редагуванням містять delete-after-run, clear agent override, точні/stagger параметри cron, перевизначення agent model/thinking і best-effort перемикачі доставлення.
|
||||
- Валідація форми вбудована з помилками на рівні поля; недійсні значення вимикають кнопку збереження, доки їх не виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо пропущено, webhook надсилається без заголовка auth.
|
||||
- Застарілий fallback: збережені legacy-завдання з `notify: true` все ще можуть використовувати `cron.webhook`, доки їх не мігровано.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Поведінка чату
|
||||
## Поведінка Chat
|
||||
|
||||
<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, тому перезавантаження не залежать від того, чи залишаються сирі 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 знову не повідомить свіже використання.
|
||||
- Відповіді `chat.history` мають обмеження розміру для безпеки UI. Коли записи стенограми завеликі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати завеликі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Зображення помічника/згенеровані зображення зберігаються як керовані посилання на медіа й повертаються через автентифіковані медіа-URL Gateway, тож перезавантаження не залежать від того, чи залишаються сирі base64-навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також прибирає з видимого тексту помічника лише-для-відображення вбудовані теги директив (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text 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 (без запуску агента й без доставлення каналом).
|
||||
- Заголовок чату показує фільтр агента перед вибирачем сесії, а вибирач сесії обмежується вибраним агентом. Перемикання агентів показує лише сесії, пов’язані з цим агентом, і повертається до головної сесії цього агента, якщо в нього ще немає збережених сесій панелі керування.
|
||||
- На настільних ширинах елементи керування чатом залишаються в одному компактному рядку й згортаються під час прокручування стенограми вниз; прокручування вгору, повернення на початок або досягнення низу відновлює елементи керування.
|
||||
- Послідовні дублікати лише текстових повідомлень відображаються як одна бульбашка з лічильником. Повідомлення, що містять зображення, вкладення, вивід інструментів або попередні перегляди canvas, не згортаються.
|
||||
- Вибирачі моделі й мислення в заголовку чату негайно оновлюють активну сесію через `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. Провайдери, які відкривають лише backend realtime bridge, працюють через relay transport Gateway, тому облікові дані та vendor sockets залишаються на боці сервера, а браузерне аудіо проходить через автентифіковані RPC Gateway. Запит сесії Realtime збирається Gateway; `talk.realtime.session` не приймає наданих викликачем перевизначень інструкцій.
|
||||
<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 отримує одноразовий обмежений auth-токен Live API для браузерної WebSocket-сесії, з інструкціями та деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, що надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані й vendor-сокети залишаються на сервері, тоді як браузерне аудіо рухається через автентифіковані RPC Gateway. Промпт Realtime-сесії збирає Gateway; `talk.realtime.session` не приймає перевизначень інструкцій, наданих викликачем.
|
||||
|
||||
У композиторі чату елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключене, або `Asking OpenClaw...`, доки realtime tool call консультується з налаштованою більшою моделлю через `chat.send`.
|
||||
У композиторі Chat елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування мікрофоном. Коли Talk запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, поки аудіо під’єднане, або `Asking OpenClaw...`, поки realtime-виклик інструмента консультується з налаштованою більшою моделлю через `chat.send`.
|
||||
|
||||
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 із фейковим медіа мікрофона. Команда друкує лише статус провайдера й не журналює секрети.
|
||||
Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє OpenAI browser WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup і Gateway relay browser adapter із фальшивим медіа мікрофона. Команда друкує лише стан провайдера й не логує секрети.
|
||||
|
||||
</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 зберігає перерваний частковий текст асистента в історії стенограми, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі стенограми могли відрізняти часткові результати переривання від звичайного завершеного виводу.
|
||||
<Accordion title="Збереження часткових даних після переривання">
|
||||
- Коли запуск перервано, частковий текст помічника все ще може показуватися в UI.
|
||||
- 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 payloads. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoints підписок браузера. |
|
||||
| `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 через env vars у процесі Gateway, коли потрібно зафіксувати ключі (для розгортань на кількох хостах, ротації секретів або тестів):
|
||||
Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно зафіксувати ключі (для multi-host розгортань, ротації секретів або тестів):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (типово `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (за замовчуванням `mailto:openclaw@localhost`)
|
||||
|
||||
Control UI використовує ці scope-gated методи Gateway для реєстрації та тестування браузерних підписок:
|
||||
|
||||
@ -219,19 +222,19 @@ Control UI використовує ці scope-gated методи Gateway для
|
||||
- `push.web.test` — надсилає тестове сповіщення до підписки викликача.
|
||||
|
||||
<Note>
|
||||
Web Push незалежний від шляху relay iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із relay) і наявного методу `push.test`, які націлені на нативне мобільне сполучення.
|
||||
Web Push незалежний від шляху ретрансляції iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із підтримкою ретрансляції) і наявного методу `push.test`, які націлені на нативне mobile pairing.
|
||||
</Note>
|
||||
|
||||
## Вбудовані hosted embeds
|
||||
## Розміщені вбудовування
|
||||
|
||||
Повідомлення асистента можуть показувати hosted web content inline за допомогою shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`:
|
||||
Повідомлення помічника можуть відображати розміщений вебвміст inline за допомогою shortcode `[embed ...]`. Політика sandbox для iframe керується `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Вимикає виконання скриптів усередині hosted embeds.
|
||||
Вимикає виконання скриптів усередині розміщених вбудовувань.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це стандартний режим, якого зазвичай достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
Дозволяє інтерактивні вбудовування, зберігаючи ізоляцію origin; це значення за замовчуванням і зазвичай його достатньо для автономних браузерних ігор/віджетів.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для same-site документів, яким навмисно потрібні сильніші привілеї.
|
||||
@ -251,14 +254,14 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна поведінка same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvases `scripts` є безпечнішим вибором.
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує same-origin поведінки. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором.
|
||||
</Warning>
|
||||
|
||||
Абсолютні зовнішні URL embeds `http(s)` за замовчуванням залишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Абсолютні зовнішні `http(s)` URL вбудовувань залишаються заблокованими за замовчуванням. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Ширина повідомлень чату
|
||||
|
||||
Згруповані повідомлення чату використовують читабельну типову максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без патчення bundled CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Згруповані повідомлення чату використовують читабельну стандартну максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без патчення bundled CSS, встановивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -270,13 +273,13 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
}
|
||||
```
|
||||
|
||||
Значення перевіряється перед тим, як потрапити до браузера. Підтримувані значення охоплюють прості довжини й відсотки, як-от `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
|
||||
@ -284,14 +287,14 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
Відкрийте:
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
- `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 також пропускає round trip device-pairing; браузери без пристрою й з’єднання node-role все ще проходять звичайні перевірки пристрою. Встановіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта й auth scope серіалізуються перед записами rate-limit. Тому одночасні невдалі повторні спроби з того самого браузера можуть показати `retry later` на другому запиті замість двох простих невідповідностей, що змагаються паралельно.
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта й auth scope серіалізуються перед записами rate-limit. Тому одночасні хибні повторні спроби з того самого браузера можуть показати `retry later` на другому запиті замість двох звичайних невідповідностей, що змагаються паралельно.
|
||||
|
||||
<Warning>
|
||||
Автентифікація Serve без токена передбачає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію token/password.
|
||||
Tokenless Serve auth припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте token/password auth.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -302,30 +305,30 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
Потім відкрийте:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
- `http://<tailscale-ip>:18789/` (або налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
Вставте відповідний shared secret у налаштування UI (надсилається як `connect.params.auth.token` або `connect.params.auth.password`).
|
||||
Вставте відповідний спільний секрет у налаштування UI (надсилається як `connect.params.auth.token` або `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Небезпечний HTTP
|
||||
## Незахищений HTTP
|
||||
|
||||
Якщо ви відкриваєте панель через plain HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`), браузер працює в **небезпечному контексті** та блокує WebCrypto. За замовчуванням OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
|
||||
Якщо ви відкриваєте панель керування через звичайний 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) або відкрийте інтерфейс локально:
|
||||
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
- `http://127.0.0.1:18789/` (на хості Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка перемикача небезпечної автентифікації">
|
||||
<Accordion title="Поведінка перемикача незахищеної автентифікації">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -338,12 +341,12 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
|
||||
`allowInsecureAuth` — це лише локальний перемикач сумісності:
|
||||
|
||||
- Він дозволяє локальним сеансам інтерфейсу керування продовжувати роботу без ідентичності пристрою в незахищених HTTP-контекстах.
|
||||
- Він дозволяє сесіям Control UI на localhost продовжувати роботу без ідентичності пристрою в незахищених HTTP-контекстах.
|
||||
- Він не обходить перевірки сполучення.
|
||||
- Він не послаблює вимоги до ідентичності віддалених (не localhost) пристроїв.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Лише аварійний доступ">
|
||||
<Accordion title="Лише аварійний режим">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -355,56 +358,56 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою для інтерфейсу керування і є серйозним зниженням рівня безпеки. Швидко скасуйте це після екстреного використання.
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є серйозним зниженням рівня безпеки. Швидко поверніть попередні налаштування після аварійного використання.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Примітка про довірений проксі">
|
||||
- Успішна автентифікація через довірений проксі може допускати сеанси інтерфейсу керування **оператора** без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси інтерфейсу керування з роллю вузла.
|
||||
- Зворотні проксі same-host loopback все одно не задовольняють автентифікацію через довірений проксі; див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth).
|
||||
<Accordion title="Примітка щодо довіреного проксі">
|
||||
- Успішна автентифікація trusted-proxy може допускати **операторські** сесії Control UI без ідентичності пристрою.
|
||||
- Це **не** поширюється на сесії Control UI з роллю node.
|
||||
- Зворотні проксі loopback на тому самому хості все одно не задовольняють автентифікацію trusted-proxy; див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Див. [Tailscale](/uk/gateway/tailscale) щодо настанов із налаштування HTTPS.
|
||||
Див. [Tailscale](/uk/gateway/tailscale), щоб отримати рекомендації з налаштування HTTPS.
|
||||
|
||||
## Політика безпеки вмісту
|
||||
|
||||
Інтерфейс керування постачається зі суворою політикою `img-src`: дозволені лише ресурси **same-origin**, URL-адреси `data:` і локально створені URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не ініціюють мережевих запитів.
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **з того самого origin**, URL-адреси `data:` і локально створені URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і URL-адреси без протоколу відхиляються браузером і не спричиняють мережевих запитів.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари й зображення, що надаються за відносними шляхами (наприклад `/avatars/<id>`), продовжують відображатися, зокрема автентифіковані маршрути аватарів, які інтерфейс отримує й перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` продовжують відображатися (корисно для payload у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені інтерфейсом керування, продовжують відображатися.
|
||||
- Віддалені URL-адреси аватарів, які передаються метаданими каналу, видаляються допоміжними функціями аватарів інтерфейсу керування й замінюються вбудованим логотипом/бейджем, тож скомпрометований або зловмисний канал не може примусово виконувати довільні віддалені запити зображень із браузера оператора.
|
||||
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад `/avatars/<id>`), усе одно відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` усе одно відображаються (корисно для payload у межах протоколу).
|
||||
- Локальні URL-адреси `blob:`, створені Control UI, усе одно відображаються.
|
||||
- Віддалені URL-адреси аватарів, які передаються метаданими каналу, вилучаються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/значком, тому скомпрометований або шкідливий канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Вам не потрібно нічого змінювати, щоб отримати цю поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена й не налаштовується.
|
||||
|
||||
## Автентифікація маршруту аватарів
|
||||
## Автентифікація маршруту аватара
|
||||
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватарів інтерфейсу керування вимагає той самий токен gateway, що й решта API:
|
||||
Коли автентифікацію Gateway налаштовано, endpoint аватарів Control UI вимагає той самий токен Gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам інтерфейс керування передає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення все одно відображалося на інформаційних панелях.
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до сусіднього маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен Gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення все одно відображалося на панелях керування.
|
||||
|
||||
Якщо вимкнути автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватарів також стане неавтентифікованим, відповідно до решти gateway.
|
||||
Якщо ви вимкнете автентифікацію Gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти Gateway.
|
||||
|
||||
## Автентифікація маршруту медіа асистента
|
||||
|
||||
Коли налаштовано автентифікацію gateway, попередній перегляд локальних медіа асистента використовує двоетапний маршрут:
|
||||
Коли автентифікацію Gateway налаштовано, локальні медіапопередні перегляди асистента використовують двоетапний маршрут:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` вимагає звичайної операторської автентифікації інтерфейсу керування. Браузер надсилає токен gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений цим точним шляхом джерела.
|
||||
- URL-адреси зображень, аудіо, відео й документів, що відображаються браузером, використовують `mediaTicket=<ticket>` замість активного токена або пароля gateway. Квиток швидко спливає й не може авторизувати інше джерело.
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` вимагає звичайної операторської автентифікації Control UI. Браузер надсилає токен Gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений саме цим шляхом джерела.
|
||||
- URL-адреси зображень, аудіо, відео та документів, що відображаються браузером, використовують `mediaTicket=<ticket>` замість активного токена або пароля Gateway. Квиток швидко спливає та не може авторизувати інше джерело.
|
||||
|
||||
Це зберігає звичайне відображення медіа сумісним із нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані gateway у видимих URL-адресах медіа.
|
||||
Це зберігає сумісність звичайного рендерингу медіа з нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані Gateway у видимих URL-адресах медіа.
|
||||
|
||||
## Збирання інтерфейсу
|
||||
## Збирання UI
|
||||
|
||||
Gateway надає статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
|
||||
Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
@ -416,20 +419,20 @@ pnpm ui:build
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Для локальної розробки (окремий сервер розробки):
|
||||
Для локальної розробки (окремий dev-сервер):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Потім спрямуйте інтерфейс на URL-адресу WS вашого Gateway (наприклад `ws://127.0.0.1:18789`).
|
||||
Потім спрямуйте UI на вашу URL-адресу Gateway WS (наприклад `ws://127.0.0.1:18789`).
|
||||
|
||||
## Налагодження/тестування: сервер розробки + віддалений Gateway
|
||||
## Налагодження/тестування: dev-сервер + віддалений Gateway
|
||||
|
||||
Інтерфейс керування — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли потрібен локальний сервер розробки Vite, але Gateway працює в іншому місці.
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли ви хочете локально використовувати dev-сервер Vite, але Gateway працює деінде.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть сервер розробки інтерфейсу">
|
||||
<Step title="Запустіть dev-сервер UI">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -450,17 +453,17 @@ pnpm ui:dev
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Примітки">
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL-адреси.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) за кожної можливості. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як fallback, і негайно видаляються після bootstrap.
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL.
|
||||
- Якщо ви передаєте повний endpoint `ws://` або `wss://` через `gatewayUrl`, закодуйте значення `gatewayUrl` для URL, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) whenever possible. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як fallback, і видаляються одразу після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли встановлено `gatewayUrl`, інтерфейс не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway перебуває за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання інтерфейсу керування не через 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-заголовком, але це небезпечний режим безпеки.
|
||||
- Розгортання Control UI не через loopback повинні явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це включає віддалені dev-налаштування.
|
||||
- Запуск 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>
|
||||
@ -477,11 +480,11 @@ pnpm ui:dev
|
||||
}
|
||||
```
|
||||
|
||||
Подробиці налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Докладні відомості про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Інформаційна панель](/uk/web/dashboard) — інформаційна панель gateway
|
||||
- [Панель керування](/uk/web/dashboard) — панель керування gateway
|
||||
- [Перевірки стану](/uk/gateway/health) — моніторинг стану gateway
|
||||
- [TUI](/uk/web/tui) — термінальний користувацький інтерфейс
|
||||
- [WebChat](/uk/web/webchat) — чат-інтерфейс на основі браузера
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
|
||||
|
||||
Loading…
Reference in New Issue
Block a user