---
read_when:
    - Налагодження або налаштування доступу WebChat
summary: Статичний хост Loopback WebChat і використання Gateway WS для UI чату
title: Вебчат
x-i18n:
    generated_at: "2026-06-27T18:32:12Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 108dd98f975a2d2e980921bd0f486c3683c18ba6eb37111163af87929a9d7973
    source_path: web/webchat.md
    workflow: 16
---

Стан: SwiftUI-інтерфейс чату для macOS/iOS напряму взаємодіє з Gateway WebSocket.

## Що це таке

- Нативний інтерфейс чату для Gateway (без вбудованого браузера й без локального статичного сервера).
- Використовує ті самі сесії та правила маршрутизації, що й інші канали.
- Детермінована маршрутизація: відповіді завжди повертаються до WebChat.

## Швидкий старт

1. Запустіть Gateway.
2. Відкрийте інтерфейс WebChat (застосунок macOS/iOS) або вкладку чату Control UI.
3. Переконайтеся, що налаштовано коректний шлях автентифікації Gateway (`shared-secret` за замовчуванням,
   навіть на loopback).

## Як це працює (поведінка)

- Інтерфейс підключається до Gateway WebSocket і використовує `chat.history`, `chat.send` та `chat.inject`.
- `chat.history` обмежено для стабільності: Gateway може обрізати довгі текстові поля, пропускати важкі метадані та замінювати завеликі записи на `[chat.history omitted: message too large]`.
- Коли видиме повідомлення асистента було обрізано в `chat.history`, Control UI може відкрити бічний переглядач і за запитом отримати повний запис, нормалізований для відображення, через `chat.message.get`, не збільшуючи стандартний payload історії.
- `chat.history` дотримується активної гілки транскрипту для сучасних append-only файлів сесій, тому покинуті гілки переписування та замінені копії prompt не відображаються у WebChat.
- Записи Compaction відображаються як явний розділювач стисненої історії. Розділювач пояснює, що стиснений транскрипт збережено як checkpoint, і посилається на елементи керування checkpoint сесій, де оператори можуть створити гілку або відновити стан із цього стисненого подання, якщо їхні дозволи це допускають.
- Control UI запам’ятовує базовий Gateway `sessionId`, повернений `chat.history`, і додає його до наступних викликів `chat.send`, тому повторні підключення й оновлення сторінки продовжують ту саму збережену розмову, доки користувач не почне або не скине сесію.
- Control UI об’єднує дублікати відправлень у процесі виконання для тієї самої сесії, повідомлення та вкладень перед створенням нового run id для `chat.send`; Gateway усе одно дедуплікує повторні запити, які повторно використовують той самий ключ ідемпотентності.
- Файли запуску workspace і очікувані інструкції `BOOTSTRAP.md` передаються через Project Context у системному prompt агента, а не копіюються в користувацьке повідомлення WebChat. Обрізання bootstrap додає лише стислий recovery-напомин у системний prompt; детальні лічильники й config knobs залишаються на діагностичних поверхнях.
- `chat.history` також нормалізовано для відображення: контекст OpenClaw лише для runtime,
  обгортки inbound envelope, inline-теги директив доставки
  на кшталт `[[reply_to_*]]` і `[[audio_as_voice]]`, plain-text XML-payloads викликів інструментів
  (зокрема `<tool_call>...</tool_call>`,
  `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
  `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів), а також
  leaked ASCII/full-width tokens керування моделлю вилучаються з видимого тексту,
  а записи асистента, чий увесь видимий текст є лише точним silent
  token `NO_REPLY` / `no_reply`, пропускаються.
- Payloads відповідей із reasoning-прапорцем (`isReasoning: true`) виключаються з вмісту асистента у WebChat, тексту replay транскрипту та аудіоблоків, тому payloads лише для мислення не з’являються як видимі повідомлення асистента чи відтворюване аудіо.
- `chat.inject` додає нотатку асистента безпосередньо до транскрипту та транслює її в інтерфейс (без запуску агента).
- Перервані запуски можуть залишати частковий вивід асистента видимим в інтерфейсі.
- Gateway зберігає перерваний частковий текст асистента в історії транскрипту, коли існує буферизований вивід, і позначає ці записи метаданими переривання.
- Історія завжди отримується з Gateway (без стеження за локальними файлами).
- Якщо Gateway недоступний, WebChat працює лише для читання.

### Модель транскрипту та доставки

WebChat має два окремі шляхи даних:

- JSONL-файл сесії є довговічним транскриптом моделі/runtime. Для звичайних запусків агента вбудований OpenClaw runtime зберігає видимі для моделі повідомлення `user`, `assistant` і `toolResult` через свій менеджер сесій. WebChat не записує довільний текст доставки, стану чи допоміжний текст у цей транскрипт.
- Події Gateway `ReplyPayload` є live-проєкцією доставки. Їх можна нормалізувати для відображення у WebChat/каналі, потокового передавання блоків, тегів директив, вбудовування медіа, прапорців TTS/аудіо та fallback-поведінки інтерфейсу. Вони самі по собі не є канонічним журналом сесії.
- Harnesses, яким потрібні видимі відповіді через `tools.message`, усе ще використовують WebChat як внутрішній sink відповіді джерела для поточного запуску. `message.send` без цілі з цього активного запуску WebChat проєктується в той самий чат і дзеркалиться в транскрипт сесії; WebChat не стає повторно використовуваним outbound-каналом і ніколи не успадковує `lastChannel`.
- WebChat вставляє записи асистента в транскрипт лише тоді, коли Gateway володіє відображеним повідомленням поза звичайним вбудованим ходом агента: `chat.inject`, відповіді команд без агента, перерваний частковий вивід і керовані WebChat додатки до медіатранскрипту.
- `chat.history` читає збережений транскрипт сесії та застосовує проєкцію відображення WebChat. Якщо live-текст асистента з’являється під час запуску, але зникає після перезавантаження історії, спершу перевірте, чи сирий JSONL містить текст асистента, потім чи проєкція `chat.history` його вилучила, а потім чи optimistic-tail merge у Control UI замінив локальний стан доставки збереженим snapshot.
- `chat.message.get` використовує ті самі правила гілки транскрипту та проєкції відображення, що й `chat.history`, включно зі scope активного агента, але націлюється на один запис транскрипту за `messageId` і повертає чесну причину недоступності, коли повний вміст більше неможливо повернути.

Фінальні відповіді звичайного запуску агента мають бути довговічними, бо вбудований runtime записує `message_end` асистента. Будь-який fallback, який дзеркалить доставлений фінальний payload у транскрипт, має спершу уникнути дублювання ходу асистента, який вбудований runtime уже записав.

## Панель інструментів агентів Control UI

- Панель Tools у Control UI `/agents` має два окремі подання:
  - **Доступно просто зараз** використовує `tools.effective(sessionKey=...)` і показує виведену сервером
    read-only проєкцію поточного inventory сесії, включно з core, plugin, інструментами, що належать каналу,
    і вже виявленими інструментами MCP server.
  - **Конфігурація інструментів** використовує `tools.catalog` і залишається зосередженою на profiles, overrides і
    семантиці catalog.
- Доступність runtime має scope сесії. Перемикання сесій на тому самому агенті може змінити
  список **Доступно просто зараз**. Якщо налаштовані MCP servers ще не були підключені або були змінені
  після останнього discovery, панель показує повідомлення замість того, щоб непомітно запускати MCP transports
  зі шляху читання.
- Редактор конфігурації не означає доступність runtime; ефективний доступ усе одно дотримується пріоритету policy
  (`allow`/`deny`, per-agent та provider/channel overrides).

## Віддалене використання

- Remote mode тунелює Gateway WebSocket через SSH/Tailscale.
- Не потрібно запускати окремий сервер WebChat.

## Довідник конфігурації (WebChat)

Повна конфігурація: [Конфігурація](/uk/gateway/configuration)

WebChat не має збереженого розділу конфігурації. Gateway використовує вбудований ліміт відображення `chat.history`; API clients можуть надсилати per-request `maxChars`, щоб перевизначити його для одного виклику `chat.history`. Legacy-конфігурація `channels.webchat` і `gateway.webchat` виведена з ужитку; запустіть `openclaw doctor --fix`, щоб її видалити.

Пов’язані глобальні опції:

- `gateway.port`, `gateway.bind`: host/port WebSocket.
- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
  автентифікація WebSocket через shared-secret.
- `gateway.auth.allowTailscale`: вкладка чату browser Control UI може використовувати
  identity headers Tailscale Serve, коли це ввімкнено.
- `gateway.auth.mode: "trusted-proxy"`: автентифікація reverse-proxy для browser clients за identity-aware **non-loopback** proxy source (див. [Автентифікація довіреного proxy](/uk/gateway/trusted-proxy-auth)).
- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: ціль віддаленого Gateway.
- `session.*`: сховище сесій і стандартні main key.

## Пов’язане

- [Control UI](/uk/web/control-ui)
- [Dashboard](/uk/web/dashboard)