TUI и WebChat

· 5 мин чтения · admin

TUI (Terminal UI) — текстовый интерфейс для чата с агентом прямо в терминале. Работает в двух режимах: через Gateway (полный функционал) и локально (без сервера). WebChat — нативный чат для macOS/iOS, подключается к Gateway через WebSocket.

TUI: быстрый старт

Через Gateway


# 1. Запустить Gateway
openclaw gateway

# 2. Открыть TUI
openclaw tui

Удалённый Gateway:


openclaw tui --url ws://: --token

Локальный режим (без Gateway)


openclaw chat
# или
openclaw tui --local

openclaw chat и openclaw terminal — это алиасы для openclaw tui --local. Работает с встроенным runtime агента. Gateway-фичи (каналы, ноды, cron) недоступны.

Что видно на экране

Элемент Что показывает
Header URL подключения, текущий агент, сессия
Chat log Сообщения пользователя, ответы агента, system-уведомления, tool-карточки
Status line Состояние: connecting, running, streaming, idle, error
Footer Агент + сессия + модель + think/fast/verbose/trace + счётчик токенов
Input Редактор с автодополнением

Агенты и сессии

  • Агенты — уникальные slug’и (main, research). Gateway отдаёт список.
  • Сессии принадлежат агенту. Ключ: agent::
  • /session main → раскрывается в agent::main
  • /session agent:other:main → переключение на другой агент

    • Горячие клавиши

    Комбинация Действие
    Enter Отправить сообщение
    Esc Прервать активный run
    Ctrl+C Очистить ввод (дважды — выход)
    Ctrl+D Выход
    Ctrl+L Выбор модели
    Ctrl+G Выбор агента
    Ctrl+P Выбор сессии
    Ctrl+O Свернуть/развернуть tool output
    Ctrl+T Показать/скрыть thinking

    Slash-команды

    Основные

    Команда Что делает
    /help Справка
    /status Статус подключения
    /agent Сменить агента (/agents — список)
    /session Сменить сессию (/sessions — список)
    /model Сменить модель (/models — список)

    Управление сессией

    Команда Что делает
    `/think low\ medium\ high>` Уровень thinking
    `/fast off>` Быстрый режим
    `/verbose full\ off>` Детализация
    `/trace off>` Трассировка
    `/reasoning off\ stream>` Показ reasoning
    `/deliver off>` Доставка ответов в каналы
    `/elevated off\ ask\ full>` Повышенный доступ
    /new или /reset Сбросить сессию
    /abort Прервать run

    Локальные shell-команды

    Строка с ! в начале выполняет shell-команду на машине с TUI:

    
!openclaw config validate
!ls -la ~/.openclaw/
  • TUI спросит разрешение один раз за сессию
  • Команды выполняются в fresh shell (без persistent cd/env)
  • Одиночный ! без команды — отправляется как обычное сообщение

    • Ремонт конфига через TUI

    Локальный режим полезен для починки конфига без запущенного Gateway:

    
openclaw chat

    
Сравни мой gateway auth config с документацией и предложи минимальный фикс.

    
!openclaw config file
!openclaw config validate
!openclaw doctor

    После правки: !openclaw config validate → если всё ок, запускайте Gateway.

    Tool output

  • Tool calls отображаются как карточки с аргументами и результатами
  • Ctrl+O — свернуть/развернуть
  • Во время выполнения — partial updates стримятся в ту же карточку

    • Доставка (delivery)

    По умолчанию сообщения идут только в TUI (не в каналы). Включить доставку:

    
/deliver on

    Или запустить с флагом: openclaw tui --deliver

    Цвета терминала

    TUI использует стандартный foreground цвет терминала. Если автоопределение темы неправильное:

    
OPENCLAW_THEME=light openclaw tui   # светлая тема
OPENCLAW_THEME=dark openclaw tui    # тёмная тема

    Опции запуска

    Опция Описание
    --local Локальный режим (без Gateway)
    --url WebSocket URL Gateway
    --token Gateway token
    --password Gateway password
    --session Ключ сессии (по умолчанию main)
    --deliver Включить доставку в каналы
    --thinking Переопределить thinking level
    --message Отправить сообщение после подключения
    --history-limit Лимит истории (по умолчанию 200)

    ⚠️ При --url TUI не берёт credentials из конфига. Передавайте --token или --password явно.

    WebChat (macOS/iOS)

    WebChat — нативный SwiftUI чат для macOS и iOS. Подключается напрямую к Gateway WebSocket.

  • Использует те же сессии и правила маршрутизации, что и другие каналы
  • Deterministic routing: ответы всегда возвращаются в WebChat
  • Не нужен встроенный браузер или отдельный сервер
  • Использует chat.history, chat.send, chat.inject

    • Быстрый старт

  • Запустить Gateway
  • Открыть WebChat (macOS/iOS приложение) или вкладку Chat в Control UI
  • Убедиться что Gateway auth настроен (по умолчанию — shared-secret)

    • Особенности

  • chat.history обрезается для стабильности: длинные тексты truncates, oversized записи заменяются плейсхолдером
  • Inline directive теги ([[reply_to_*]], [[audio_as_voice]]) вырезаются из видимого текста
  • Reasoning-флаги (isReasoning: true) не показываются как видимые сообщения
  • chat.inject добавляет заметку агента в транскрипт без запуска run
  • Прерванные runs сохраняют partial output в истории
  • Если Gateway недоступен — WebChat в режиме только чтение

    • Удалённый доступ

    Через SSH-туннель или Tailscale. Отдельный WebChat-сервер не нужен.

    Настройка

  • gateway.webchat.chatHistoryMaxChars — максимум символов для text полей в chat.history
  • gateway.auth.allowTailscale — разрешить Tailscale Serve identity headers
  • gateway.auth.mode: "trusted-proxy" — auth через reverse proxy

    • Типичные проблемы

    Проблема Решение
    Нет ответа после отправки /status — проверить подключение. openclaw logs --follow — логи
    disconnected Gateway запущен? --url/--token/--password правильные?
    Нет агентов в picker openclaw agents list + проверить routing config
    Пустой session picker Возможно global scope или нет сессий
    Нет доставки в каналы /deliver on или --deliver флаг

    Что дальше

  • Control UI — веб-интерфейс
  • Конфигурация Gateway — настройки сервера
  • CLI справочник — все команды CLI