chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d5ba4152d5
commit
4c86898de4
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете керувати Gateway із браузера
|
||||
- Ви хочете керувати Gateway через браузер
|
||||
- Вам потрібен доступ до Tailnet без SSH-тунелів
|
||||
sidebarTitle: Control UI
|
||||
summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T01:53:33Z"
|
||||
generated_at: "2026-05-06T03:12:17Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8421a302ce5585594cf50c16dc0993a2f4d6614de034cf46a9d2e35d39076ee4
|
||||
source_hash: 2c16b37405d7a490b89ea90f2b006c01b9a7b1a3e5278769006b4dc94e7d83aa
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговує Gateway:
|
||||
|
||||
- типово: `http://<host>:18789/`
|
||||
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
- за замовчуванням: `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/))
|
||||
|
||||
@ -36,7 +36,7 @@ Control UI — це невеликий односторінковий засто
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраного URL Gateway; паролі не зберігаються. Onboarding зазвичай генерує токен Gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай генерує токен gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
@ -57,97 +57,99 @@ Control UI — це невеликий односторінковий засто
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, і створюється новий `requestId`. Перед схваленням знову виконайте `openclaw devices list`.
|
||||
Якщо браузер повторює сполучення зі зміненими даними автентифікації (роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, і створюється новий `requestId`. Перед схваленням повторно виконайте `openclaw devices list`.
|
||||
|
||||
Якщо браузер уже сполучено, і ви змінюєте його доступ із читання на запис/адміністрування, це вважається підвищенням схвалення, а не тихим повторним підключенням. 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 може пропустити цикл сполучення для операторських сесій Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджено, а браузер надає ідентичність свого пристрою.
|
||||
- Прямі прив'язки Tailnet, браузерні підключення через LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому перемикання браузерів або очищення даних браузера вимагатиме повторного сполучення.
|
||||
|
||||
</Note>
|
||||
|
||||
## Особиста ідентичність (локально в браузері)
|
||||
## Особиста ідентичність (локальна для браузера)
|
||||
|
||||
Control UI підтримує персональну ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції в спільних сесіях. Вона зберігається в сховищі браузера, обмежена поточним профілем браузера й не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства стенограми для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або зміна браузера скидає її до порожнього стану.
|
||||
Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім'я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається у сховищі браузера, обмежена поточним профілем браузера і не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства стенограми для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або перемикання браузерів скидає її до порожнього стану.
|
||||
|
||||
Такий самий локальний для браузера шаблон застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на ідентичність, визначену Gateway, лише в локальному браузері й ніколи не проходять туди й назад через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` все ще доступне для клієнтів без UI, які записують це поле безпосередньо (наприклад, скриптові gateway або власні дашборди).
|
||||
Та сама локальна для браузера схема застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на визначену gateway ідентичність лише в локальному браузері й ніколи не проходять зворотний шлях через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, скриптові gateway або кастомні дашборди).
|
||||
|
||||
## Ендпоінт конфігурації виконання
|
||||
## Ендпойнт конфігурації середовища виконання
|
||||
|
||||
Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Цей ендпоінт захищений тією самою автентифікацією Gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а успішне отримання потребує або вже чинного токена/пароля Gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
Control UI отримує свої налаштування середовища виконання з `/__openclaw/control-ui-config.json`. Цей ендпойнт захищений тією самою автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а успішне отримання потребує або вже чинного токена/пароля gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі.
|
||||
|
||||
## Підтримка мов
|
||||
|
||||
Control UI може локалізувати себе під час першого завантаження на основі локалі вашого браузера. Щоб змінити це пізніше, відкрийте **Огляд -> Доступ до 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`) все ще генерується в репозиторії публікації; вона може не з'являтися в цьому перемикачі, доки 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 використовують ретрансляційний транспорт Gateway. Сесії провайдера, якими володіє клієнт, починаються з `talk.client.create`; ретрансляційні сесії Gateway починаються з `talk.session.create`. Ретрансляція зберігає облікові дані провайдера на Gateway, поки браузер транслює PCM з мікрофона через `talk.session.appendAudio` і пересилає виклики інструментів провайдера `openclaw_agent_consult` через `talk.client.toolCall` для політики Gateway та більшої налаштованої моделі OpenClaw.
|
||||
- Потоково передавайте виклики інструментів і живі картки виводу інструментів у чаті (події агента).
|
||||
- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Оновлення історії чату запитують обмежене нещодавнє вікно з обмеженнями тексту для кожного повідомлення, щоб великі сесії не змушували браузер рендерити повне корисне навантаження стенограми до того, як чат стане придатним до використання.
|
||||
- Розмовляти через браузерні realtime-сесії. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а backend-only realtime голосові plugins використовують транспорт ретрансляції Gateway. Сесії провайдера, якими володіє клієнт, починаються з `talk.client.create`; сесії ретрансляції Gateway починаються з `talk.session.create`. Ретрансляція зберігає облікові дані провайдера на Gateway, поки браузер транслює PCM мікрофона через `talk.session.appendAudio` і пересилає виклики інструментів провайдера `openclaw_agent_consult` через `talk.client.toolCall` для політики Gateway та більшої налаштованої моделі OpenClaw.
|
||||
- Транслювати виклики інструментів і живі картки виводу інструментів у Чаті (події агента).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Канали, інстанси, сесії, сни">
|
||||
- Канали: статус вбудованих, а також bundled/external Plugin-каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Інстанси: список присутності + оновлення (`system-presence`).
|
||||
- Сесії: список + перевизначення моделі/мислення/швидкого режиму/докладності/трасування/міркування для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Сни: статус Dreaming, перемикач увімкнення/вимкнення та читач Щоденника снів (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
<Accordion title="Канали, екземпляри, сесії, сни">
|
||||
- Канали: вбудовані та bundled/зовнішні plugin-канали, статус, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Оновлення перевірки каналів зберігають попередній знімок видимим, доки повільні перевірки провайдера завершуються, а часткові знімки позначаються, коли перевірка або аудит перевищує свій UI-бюджет.
|
||||
- Екземпляри: список присутності + оновлення (`system-presence`).
|
||||
- Сесії: список + перевизначення моделі/мислення/швидкого режиму/детальності/трасування/reasoning для кожної сесії (`sessions.list`, `sessions.patch`).
|
||||
- Сни: статус Dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, Node, схвалення exec">
|
||||
<Accordion title="Cron, skills, nodes, схвалення exec">
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, установлення, оновлення ключів API (`skills.*`).
|
||||
- Node: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування allowlist Gateway або Node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`).
|
||||
- Nodes: список + можливості (`node.list`).
|
||||
- Схвалення exec: редагування списків дозволів gateway або node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація">
|
||||
- Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії.
|
||||
- Записи включають захист базового хеша, щоб запобігти перезапису паралельних редагувань.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для посилань у надісланому payload конфігурації; нерозв’язані активні надіслані посилання відхиляються перед записом.
|
||||
- Схема + рендеринг форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, відповідними підказками UI, зведеннями безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах object/wildcard/array/composition, а також схемами Plugin + каналів, коли вони доступні); редактор Raw JSON доступний лише тоді, коли snapshot має безпечний raw round-trip.
|
||||
- Якщо snapshot не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим Форми та вимикає режим Raw для цього snapshot.
|
||||
- У редакторі Raw JSON "Скинути до збереженого" зберігає raw-авторську форму (форматування, коментарі, макет `$include`) замість повторного рендерингу сплющеного snapshot, тож зовнішні редагування переживають скидання, коли snapshot може безпечно виконати round-trip.
|
||||
- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок.
|
||||
- Записи містять захист base-hash, щоб запобігти перезапису одночасних редагувань.
|
||||
- Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв'язання активних SecretRef для посилань у надісланому корисному навантаженні конфігурації; нерозв'язані активні надіслані посилання відхиляються до запису.
|
||||
- Рендеринг схеми та форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, відповідними UI-підказками, негайними підсумками дочірніх елементів, метаданими документації на вузлах вкладених об'єктів/wildcard/масивів/композиції, а також схемами plugin + каналів, коли вони доступні); редактор Raw JSON доступний лише тоді, коли знімок має безпечний сирий round-trip.
|
||||
- Якщо знімок не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим Форми та вимикає режим Raw для цього знімка.
|
||||
- У редакторі Raw JSON "Скинути до збереженого" зберігається сиро-авторська форма (форматування, коментарі, макет `$include`) замість повторного рендерингу сплощеного знімка, тому зовнішні редагування переживають скидання, коли знімок може безпечно пройти round-trip.
|
||||
- Структуровані значення об'єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню об'єкта в рядок.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Налагодження, журнали, оновлення">
|
||||
- Налагодження: snapshots стану/здоров’я/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнал подій містить таймінги оновлення/RPC Control UI, а також записи чутливості браузера для довгих кадрів анімації або довгих задач, коли браузер надає ці типи записів PerformanceObserver.
|
||||
- Журнали: живий tail файлових журналів gateway з фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск оновлення package/git + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного gateway.
|
||||
- Налагодження: знімки статусу/стану/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`).
|
||||
- Журнал подій містить таймінги оновлення/RPC Control UI, таймінги повільного рендерингу чату/конфігурації та записи про чутливість браузера для довгих кадрів анімації або довгих завдань, коли браузер надає ці типи записів PerformanceObserver.
|
||||
- Журнали: live tail файлових журналів gateway із фільтром/експортом (`logs.tail`).
|
||||
- Оновлення: запуск package/git-оновлення + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити запущену версію gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Нотатки панелі завдань Cron">
|
||||
- Для ізольованих завдань доставка типово оголошує зведення. Ви можете перемкнути на none, якщо хочете внутрішні-only запуски.
|
||||
- Поля каналу/цілі з’являються, коли вибрано announce.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, заданим як чинний HTTP(S) Webhook URL.
|
||||
- Для завдань основної сесії доступні режими доставки webhook і none.
|
||||
- Розширені елементи керування редагуванням включають delete-after-run, очищення перевизначення агента, точні/рознесені параметри cron, перевизначення моделі/мислення агента та best-effort перемикачі доставки.
|
||||
- Для ізольованих завдань доставка за замовчуванням оголошує підсумок. Ви можете перемкнути на none, якщо хочете внутрішні-only запуски.
|
||||
- Поля каналу/цілі з'являються, коли вибрано оголошення.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, встановленим на чинну HTTP(S) webhook URL-адресу.
|
||||
- Для завдань main-session доступні режими доставки webhook і none.
|
||||
- Розширені елементи керування редагуванням містять delete-after-run, очищення перевизначення агента, точні/з розкиданням параметри cron, перевизначення моделі/мислення агента та перемикачі доставки best-effort.
|
||||
- Валідація форми вбудована з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не буде виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надіслати окремий bearer token; якщо пропущено, Webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий fallback: збережені legacy-завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer-токен; якщо його пропущено, webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий fallback: збережені legacy-завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не мігрують.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,66 +157,66 @@ Control UI може локалізувати себе під час першог
|
||||
## Поведінка чату
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Send and history semantics">
|
||||
- `chat.send` є **неблокувальним**: він одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
|
||||
<Accordion title="Семантика надсилання та історії">
|
||||
- `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` Control UI прибирає з видимого тексту помічника лише-відображувальні вбудовані теги директив (наприклад `[[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` або токеном підтвердження heartbeat `HEARTBEAT_OK`.
|
||||
- Під час активного надсилання та фінального оновлення історії подання чату зберігає видимими локальні оптимістичні повідомлення користувача/помічника, якщо `chat.history` на короткий час повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє.
|
||||
- Живі події `chat` є станом доставлення, тоді як `chat.history` перебудовується зі сталого транскрипту сесії. Після фінальних подій інструментів Control UI перезавантажує історію та об’єднує лише невеликий оптимістичний хвіст; межу транскрипту задокументовано в [WebChat](/uk/web/webchat).
|
||||
- `chat.inject` додає нотатку помічника до транскрипту сесії та транслює подію `chat` для оновлень лише в UI (без запуску агента й без доставлення каналом).
|
||||
- Заголовок чату показує фільтр агента перед вибором сесії, а вибір сесії обмежений вибраним агентом. Перемикання агентів показує лише сесії, прив’язані до цього агента, і повертається до основної сесії цього агента, якщо в нього ще немає збережених сесій панелі керування.
|
||||
- На ширинах робочого столу елементи керування чатом залишаються в одному компактному рядку й згортаються під час прокручування транскрипту вниз; прокручування вгору, повернення до початку або досягнення кінця відновлює елементи керування.
|
||||
- Послідовні дублікати суто текстових повідомлень рендеряться як одна бульбашка з бейджем кількості. Повідомлення, що містять зображення, вкладення, вивід інструментів або попередні перегляди canvas, залишаються незгорнутими.
|
||||
- Вибірники моделі та thinking у заголовку чату негайно виправляють активну сесію через `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` обмежені за розміром для безпеки інтерфейсу. Коли записи стенограми завеликі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Згенеровані асистентом зображення зберігаються як посилання на керовані медіа й повертаються через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи сирі payload-и зображень base64 залишаються у відповіді історії чату.
|
||||
- Під час відтворення `chat.history` Control UI прибирає з видимого тексту асистента лише-відображальні inline-теги директив (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML payload-и викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), а також витеклі ASCII/повноширинні керівні токени моделі, і пропускає записи асистента, весь видимий текст яких є лише точним тихим токеном `NO_REPLY` / `no_reply` або токеном підтвердження Heartbeat `HEARTBEAT_OK`.
|
||||
- Під час активного надсилання й фінального оновлення історії подання чату залишає локальні оптимістичні повідомлення користувача/асистента видимими, якщо `chat.history` на мить повертає старіший знімок; канонічна стенограма замінює ці локальні повідомлення, щойно історія Gateway наздоганяє актуальний стан.
|
||||
- Live-події `chat` є станом доставки, тоді як `chat.history` перебудовується зі сталої стенограми сесії. Після фінальних подій інструментів Control UI перезавантажує історію й об'єднує лише невеликий оптимістичний хвіст; межу стенограми задокументовано в [WebChat](/uk/web/webchat).
|
||||
- `chat.inject` додає нотатку асистента до стенограми сесії та транслює подію `chat` для оновлень лише інтерфейсу (без запуску агента й без доставки в канал).
|
||||
- Заголовок чату показує фільтр агента перед вибором сесії, а вибір сесії обмежується вибраним агентом. Перемикання агентів показує лише сесії, пов'язані з цим агентом, і повертається до головної сесії цього агента, якщо в нього ще немає збережених сесій панелі керування.
|
||||
- На desktop-ширинах елементи керування чатом залишаються в одному компактному рядку та згортаються під час прокручування стенограми вниз; прокручування вгору, повернення до верху або досягнення низу відновлює елементи керування.
|
||||
- Послідовні дублікати текстових повідомлень відображаються як одна бульбашка з бейджем кількості. Повідомлення, що містять зображення, вкладення, вивід інструментів або попередні перегляди полотна, не згортаються.
|
||||
- Вибір моделі чату та режиму мислення одразу змінює активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не параметри надсилання лише для одного ходу.
|
||||
- Введення `/new` у Control UI створює й перемикає на ту саму нову сесію панелі керування, що й New Chat. Введення `/reset` зберігає явне скидання на місці Gateway для поточної сесії.
|
||||
- Вибір моделі чату запитує налаштоване подання моделей Gateway. Якщо присутній `agents.defaults.models`, цей allowlist керує вибором. Інакше вибір показує явні записи `models.providers.*.models` плюс провайдерів із придатною автентифікацією. Повний каталог залишається доступним через налагоджувальний RPC `models.list` із `view: "all"`.
|
||||
- Коли свіжі звіти про використання сесії Gateway показують високий тиск контексту, область композитора чату показує повідомлення про контекст і, на рекомендованих рівнях Compaction, компактну кнопку, що запускає звичайний шлях Compaction для сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Talk mode (browser realtime)">
|
||||
Режим Talk використовує зареєстрованого realtime-провайдера голосу. Налаштуйте OpenAI за допомогою `talk.realtime.provider: "openai"` плюс `talk.realtime.providers.openai.apiKey`, або налаштуйте Google за допомогою `talk.realtime.provider: "google"` плюс `talk.realtime.providers.google.apiKey`. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений auth-токен Live API для браузерної WebSocket-сесії, а інструкції та декларації інструментів заблоковані в токені Gateway. Провайдери, які відкривають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані та сокети постачальника залишаються на боці сервера, а браузерне аудіо проходить через автентифіковані RPC Gateway. Підказку Realtime-сесії збирає Gateway; `talk.client.create` не приймає надані викликачем перевизначення інструкцій.
|
||||
<Accordion title="Режим розмови (браузерний realtime)">
|
||||
Режим розмови використовує зареєстрованого realtime-провайдера голосу. Налаштуйте OpenAI з `talk.realtime.provider: "openai"` плюс `talk.realtime.providers.openai.apiKey` або налаштуйте Google з `talk.realtime.provider: "google"` плюс `talk.realtime.providers.google.apiKey`. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений auth-токен Live API для браузерної WebSocket-сесії, з інструкціями та деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, що надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тому облікові дані й vendor-сокети залишаються на сервері, а аудіо браузера проходить через автентифіковані RPC Gateway. Підказку Realtime-сесії формує Gateway; `talk.client.create` не приймає наданих викликачем перевизначень інструкцій.
|
||||
|
||||
У компонувальнику Chat елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування мікрофоном. Коли Talk запускається, рядок стану компонувальника показує `Connecting Talk...`, потім `Talk live`, поки аудіо підключене, або `Asking OpenClaw...`, поки realtime-виклик інструмента консультується з налаштованою більшою моделлю через `talk.client.toolCall`.
|
||||
У композиторі чату елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, поки аудіо під'єднане, або `Asking OpenClaw...`, поки realtime-виклик інструмента консультується з налаштованою більшою моделлю через `talk.client.toolCall`.
|
||||
|
||||
Живий smoke для супровідників: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє браузерний обмін SDP OpenAI WebRTC, налаштування браузерного WebSocket Google Live з обмеженим токеном і браузерний адаптер relay Gateway із фейковими медіа мікрофона. Команда друкує лише статус провайдера й не записує секрети в журнал.
|
||||
Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє обмін SDP OpenAI browser WebRTC, налаштування Google Live constrained-token browser WebSocket і браузерний адаптер relay Gateway із фейковим мікрофонним медіа. Команда друкує лише стан провайдера й не логує секрети.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Stop and abort">
|
||||
<Accordion title="Зупинка та скасування">
|
||||
- Натисніть **Stop** (викликає `chat.abort`).
|
||||
- Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це подальше повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання на кшталт `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним потоком.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії.
|
||||
- Введіть `/stop` (або окремі фрази скасування, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб скасувати поза основним потоком.
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`), щоб скасувати всі активні запуски для цієї сесії.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Abort partial retention">
|
||||
- Коли запуск перервано, частковий текст помічника все ще може показуватися в UI.
|
||||
- Gateway зберігає перерваний частковий текст помічника в історію транскрипту, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізнити часткові результати переривання від звичайного виводу завершення.
|
||||
<Accordion title="Збереження часткових даних після скасування">
|
||||
- Коли запуск скасовано, частковий текст асистента все одно може показуватися в інтерфейсі.
|
||||
- Gateway зберігає скасований частковий текст асистента в історію стенограми, коли існує буферизований вивід.
|
||||
- Збережені записи містять метадані скасування, щоб споживачі стенограми могли відрізняти часткові дані після скасування від звичайного виводу завершення.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Установлення PWA та веб push
|
||||
## Встановлення 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` | Збережені endpoints браузерних підписок. |
|
||||
| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він доступний. |
|
||||
| `ui/public/sw.js` | Service worker, який обробляє події `push` і кліки сповіщень. |
|
||||
| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, що використовується для підписування payload-ів Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Збережені endpoint-и браузерних підписок. |
|
||||
|
||||
Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно закріпити ключі (для багатохостових розгортань, ротації секретів або тестів):
|
||||
Перевизначте пару ключів VAPID через env vars у процесі 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 методи Gateway, щоб реєструвати й тестувати браузерні підписки:
|
||||
Control UI використовує ці методи Gateway з обмеженням scope, щоб реєструвати й тестувати браузерні підписки:
|
||||
|
||||
- `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID.
|
||||
- `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`.
|
||||
@ -222,22 +224,22 @@ Control UI використовує ці обмежені scope методи Gat
|
||||
- `push.web.test` — надсилає тестове сповіщення до підписки викликача.
|
||||
|
||||
<Note>
|
||||
Web Push не залежить від relay-шляху iOS APNS (див. [Конфігурація](/uk/gateway/configuration) щодо push на основі relay) і наявного методу `push.test`, які націлені на нативне мобільне спарювання.
|
||||
Web Push незалежний від relay-шляху iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push на основі relay) та наявного методу `push.test`, які націлені на нативне mobile pairing.
|
||||
</Note>
|
||||
|
||||
## Хостингові вбудовування
|
||||
## Hosted embeds
|
||||
|
||||
Повідомлення помічника можуть рендерити хостинговий вебвміст inline за допомогою shortcode `[embed ...]`. Політикою sandbox iframe керує `gateway.controlUi.embedSandbox`:
|
||||
Повідомлення асистента можуть відтворювати розміщений вебвміст inline за допомогою shortcode `[embed ...]`. Політикою sandbox для iframe керує `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Вимикає виконання скриптів усередині хостингових вбудовувань.
|
||||
Вимикає виконання скриптів усередині розміщених embed-ів.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Дозволяє інтерактивні вбудовування, зберігаючи ізоляцію origin; це значення за замовчуванням і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
<Tab title="scripts (типово)">
|
||||
Дозволяє інтерактивні embed-и, зберігаючи ізоляцію origin; це типовий режим, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту, яким навмисно потрібні сильніші привілеї.
|
||||
Додає `allow-same-origin` поверх `allow-scripts` для same-site документів, яким навмисно потрібні сильніші привілеї.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -254,14 +256,14 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує поведінки same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором.
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує same-origin поведінки. Для більшості згенерованих агентом ігор та інтерактивних полотен `scripts` є безпечнішим вибором.
|
||||
</Warning>
|
||||
|
||||
Абсолютні зовнішні URL вбудовування `http(s)` залишаються заблокованими за замовчуванням. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Абсолютні зовнішні `http(s)` URL для embed залишаються заблокованими типово. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Ширина повідомлення чату
|
||||
## Ширина повідомлень чату
|
||||
|
||||
Згруповані повідомлення чату використовують читабельну стандартну максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без виправлення bundled CSS, установивши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Згруповані повідомлення чату використовують читабельну типову максимальну ширину. Розгортання на широких моніторах можуть перевизначити її без patching bundled CSS, задавши `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -273,13 +275,13 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
}
|
||||
```
|
||||
|
||||
Значення перевіряється до того, як потрапляє в браузер. Підтримувані значення включають прості довжини та відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
Значення перевіряється перед тим, як потрапить до браузера. Підтримувані значення включають прості довжини й відсотки, як-от `960px` або `82%`, а також обмежені вирази ширини `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` і `fit-content(...)`.
|
||||
|
||||
## Доступ до tailnet (рекомендовано)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Integrated Tailscale Serve (preferred)">
|
||||
Залиште Gateway на loopback і дайте Tailscale Serve проксувати його через HTTPS:
|
||||
<Tab title="Інтегрований Tailscale Serve (бажано)">
|
||||
Тримайте Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -289,16 +291,16 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
За замовчуванням запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, та приймає їх лише тоді, коли запит потрапляє на loopback із заголовками Tailscale `x-forwarded-*`. Для операторських сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає цикл спарювання пристрою; браузери без пристрою та підключення з роллю node все ще проходять звичайні перевірки пристрою. Установіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані спільного секрету навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`.
|
||||
Типово запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` за допомогою `tailscale whois` і зіставляючи її із заголовком, і приймає їх лише тоді, коли запит потрапляє на loopback із заголовками `x-forwarded-*` від Tailscale. Для операторських сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає round trip pairing пристрою; браузери без пристрою та підключення з роллю node все одно проходять звичайні перевірки пристрою. Установіть `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>
|
||||
Auth Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
|
||||
Tokenless Serve auth припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію token/password.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Bind to tailnet + token">
|
||||
<Tab title="Прив'язка до tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -312,20 +314,20 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Небезпечний HTTP
|
||||
## Незахищений HTTP
|
||||
|
||||
Якщо відкрити панель керування через звичайний 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`
|
||||
- аварійний режим `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
- `http://127.0.0.1:18789/` (на хості Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка перемикача небезпечної автентифікації">
|
||||
@ -341,12 +343,12 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
|
||||
`allowInsecureAuth` — це лише локальний перемикач сумісності:
|
||||
|
||||
- Він дозволяє сеансам localhost Control UI продовжувати роботу без ідентичності пристрою в небезпечних HTTP-контекстах.
|
||||
- Він не обходить перевірки сполучення.
|
||||
- Він не пом’якшує вимоги до ідентичності віддалених (не localhost) пристроїв.
|
||||
- Він дозволяє сеансам localhost Control UI продовжувати роботу без ідентичності пристрою в незахищених HTTP-контекстах.
|
||||
- Він не обходить перевірки спарювання.
|
||||
- Він не послаблює вимоги до ідентичності віддаленого (не localhost) пристрою.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Лише аварійний доступ">
|
||||
<Accordion title="Лише аварійний режим">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -358,14 +360,14 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є серйозним послабленням безпеки. Швидко поверніть попередні налаштування після аварійного використання.
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є суттєвим зниженням рівня безпеки. Після аварійного використання швидко поверніть попередні налаштування.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Примітка щодо довіреного проксі">
|
||||
- Успішна автентифікація через довірений проксі може допускати **операторські** сеанси Control UI без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси Control UI з роллю вузла.
|
||||
- Зворотні проксі same-host loopback усе одно не задовольняють автентифікацію довіреного проксі; див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth).
|
||||
<Accordion title="Примітка щодо trusted-proxy">
|
||||
- Успішна автентифікація trusted-proxy може допускати **операторські** сеанси Control UI без ідентичності пристрою.
|
||||
- Це **не** поширюється на сеанси Control UI з роллю Node.
|
||||
- Зворотні проксі loopback на тому самому хості все одно не задовольняють автентифікацію trusted-proxy; див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -374,36 +376,36 @@ Web Push не залежить від relay-шляху iOS APNS (див. [Кон
|
||||
|
||||
## Політика безпеки вмісту
|
||||
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **того самого джерела**, URL-адреси `data:` та локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не спричиняють мережевих запитів.
|
||||
Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **того самого origin**, URL `data:` і локально згенеровані URL `blob:`. Віддалені URL зображень `http(s)` і URL відносно протоколу відхиляються браузером і не спричиняють мережевих запитів.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад `/avatars/<id>`), усе одно відображаються, зокрема маршрути автентифікованих аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`.
|
||||
- Вбудовані URL-адреси `data:image/...` усе одно відображаються (корисно для корисних навантажень у протоколі).
|
||||
- Локальні URL-адреси `blob:`, створені Control UI, усе одно відображаються.
|
||||
- Віддалені URL-адреси аватарів, створені метаданими каналу, видаляються в допоміжних засобах аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може примусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Аватари й зображення, які обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), усе ще відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує і перетворює на локальні URL `blob:`.
|
||||
- Вбудовані URL `data:image/...` усе ще відображаються (корисно для корисних навантажень усередині протоколу).
|
||||
- Локальні URL `blob:`, створені Control UI, усе ще відображаються.
|
||||
- URL віддалених аватарів, згенеровані метаданими каналу, вилучаються допоміжними засобами аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Щоб отримати цю поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
|
||||
Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена і не налаштовується.
|
||||
|
||||
## Автентифікація маршруту аватарів
|
||||
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватарів Control UI вимагає той самий токен gateway, що й решта API:
|
||||
Коли автентифікацію Gateway налаштовано, кінцева точка аватарів Control UI вимагає той самий токен 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). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
|
||||
- Сам Control UI пересилає токен 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>` вимагає звичайної операторської автентифікації Control UI. Браузер надсилає токен Gateway як bearer-заголовок під час перевірки доступності.
|
||||
- Успішні відповіді з метаданими містять короткочасний `mediaTicket`, обмежений цим точним шляхом джерела.
|
||||
- URL зображень, аудіо, відео й документів, які відображає браузер, використовують `mediaTicket=<ticket>` замість активного токена або пароля Gateway. Квиток швидко спливає і не може авторизувати інше джерело.
|
||||
|
||||
Це зберігає сумісність звичайного відображення медіа з нативними медіаелементами браузера без розміщення багаторазових облікових даних gateway у видимих URL-адресах медіа.
|
||||
Це зберігає сумісність звичайного відтворення медіа з нативними медіаелементами браузера, не розміщуючи багаторазові облікові дані Gateway у видимих медіа-URL.
|
||||
|
||||
## Збирання UI
|
||||
|
||||
@ -413,26 +415,26 @@ Gateway обслуговує статичні файли з `dist/control-ui`.
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Необов’язкова абсолютна база (коли потрібні фіксовані URL-адреси ресурсів):
|
||||
Необов’язкова абсолютна база (коли потрібні фіксовані URL ресурсів):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Для локальної розробки (окремий dev server):
|
||||
Для локальної розробки (окремий сервер розробки):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Потім вкажіть UI на URL-адресу WS вашого Gateway (наприклад `ws://127.0.0.1:18789`).
|
||||
Потім спрямуйте UI на ваш WS URL Gateway (наприклад, `ws://127.0.0.1:18789`).
|
||||
|
||||
## Налагодження/тестування: dev server + віддалений Gateway
|
||||
## Налагодження/тестування: сервер розробки + віддалений Gateway
|
||||
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP-джерела. Це зручно, коли потрібно використовувати локальний dev server Vite, але Gateway працює в іншому місці.
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується і може відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати Vite dev server локально, а Gateway працює в іншому місці.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть dev server UI">
|
||||
<Step title="Запустіть сервер розробки UI">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -453,17 +455,17 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Примітки">
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL.
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження і видаляється з URL.
|
||||
- Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) за можливості. Фрагменти не надсилаються на сервер, що запобігає витокам через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як fallback, і видаляються одразу після початкового завантаження.
|
||||
- `token` за можливості слід передавати через фрагмент URL (`#token=...`). Фрагменти не надсилаються на сервер, що запобігає витоку в журналах запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як резервний варіант, і негайно видаляються після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли встановлено `gatewayUrl`, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway розміщено за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання Control UI не через loopback мають явно встановити `gateway.controlUi.allowedOrigins` (повні джерела). Це включає віддалені середовища розробки.
|
||||
- Запуск Gateway може додавати локальні джерела, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, з фактичних runtime-прив’язки та порту, але віддалені джерела браузера все одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім жорстко контрольованого локального тестування. Це означає дозволити будь-яке джерело браузера, а не «зіставити будь-який хост, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для джерела з Host-заголовка, але це небезпечний режим безпеки.
|
||||
- Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway знаходиться за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання Control UI не через loopback повинні явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це стосується і віддалених середовищ розробки.
|
||||
- Під час запуску Gateway може додавати локальні origins, як-от `http://localhost:<port>` і `http://127.0.0.1:<port>`, на основі фактичних runtime bind і порту, але віддалені browser origins все одно потребують явних записів.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім жорстко контрольованого локального тестування. Це означає дозволити будь-який browser origin, а не «зіставити з будь-яким хостом, який я використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим резервного використання Host-header origin, але це небезпечний режим безпеки.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -480,11 +482,11 @@ Control UI — це статичні файли; ціль WebSocket налашт
|
||||
}
|
||||
```
|
||||
|
||||
Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Подробиці налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Панель керування](/uk/web/dashboard) — панель керування gateway
|
||||
- [Перевірки справності](/uk/gateway/health) — моніторинг справності gateway
|
||||
- [Панель керування](/uk/web/dashboard) — панель керування Gateway
|
||||
- [Перевірки справності](/uk/gateway/health) — моніторинг справності Gateway
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [WebChat](/uk/web/webchat) — інтерфейс чату на основі браузера
|
||||
- [WebChat](/uk/web/webchat) — чат-інтерфейс у браузері
|
||||
|
||||
Loading…
Reference in New Issue
Block a user