Перейти к основному содержимому

Веб-интерфейсы

Control UI

Control UI — это небольшое одностраничное приложение на Vite + Lit, обслуживаемое Gateway:

  • по умолчанию: http://:18789/
  • опциональный префикс: установите gateway.controlUi.basePath (например, /openclaw)

Он общается напрямую с WebSocket Gateway на том же порту.

Быстрый запуск (локально)​

Если Gateway запущен на том же компьютере, откройте:

Если страница не загружается, сначала запустите Gateway: openclaw gateway. Аутентификация передается во время рукопожатия WebSocket через:

  • connect.params.auth.token
  • connect.params.auth.password Панель настроек панели управления позволяет сохранить токен; пароли не сохраняются. Мастер начальной настройки по умолчанию генерирует токен gateway, поэтому вставьте его здесь при первом подключении.

Сопряжение устройства (первое подключение)​

Когда вы подключаетесь к Control UI с нового браузера или устройства, Gateway требует однократного подтверждения сопряжения — даже если вы находитесь в той же сети Tailnet с gateway.auth.allowTailscale: true. Это мера безопасности для предотвращения несанкционированного доступа. Что вы увидите: “disconnected (1008): pairing required” Чтобы подтвердить устройство:

# Список ожидающих запросов
openclaw devices list

# Подтвердить по ID запроса
openclaw devices approve <requestId>

После подтверждения устройство запоминается и не потребует повторного подтверждения, пока вы не отзовете его с помощью openclaw devices revoke --device --role . См. Devices CLI для ротации и отзыва токенов. Примечания:

  • Локальные подключения (127.0.0.1) подтверждаются автоматически.
  • Удаленные подключения (LAN, Tailnet и т.д.) требуют явного подтверждения.
  • Каждый профиль браузера генерирует уникальный ID устройства, поэтому смена браузера или очистка данных браузера потребует повторного сопряжения.

Поддержка языков​

Control UI может локализовать себя при первой загрузке на основе языковых настроек вашего браузера, и вы можете изменить язык позже с помощью переключателя в карточке Access.

  • Поддерживаемые локали: en, zh-CN, zh-TW, pt-BR, de, es
  • Переводы на другие языки загружаются в браузере лениво.
  • Выбранная локаль сохраняется в хранилище браузера и используется при последующих посещениях.
  • Отсутствующие ключи перевода возвращаются к английскому языку.

Что он может делать (сегодня)​

  • Чат с моделью через Gateway WS (chat.history, chat.send, chat.abort, chat.inject)
  • Потоковые вызовы инструментов + карточки живого вывода инструментов в чате (события агента)
  • Каналы: WhatsApp/Telegram/Discord/Slack + плагины каналов (Mattermost и др.) статус + QR-логин + конфигурация на канал (channels.status, web.login.*, config.patch)
  • Экземпляры: список присутствия + обновление (system-presence)
  • Сессии: список + переопределения thinking/verbose для каждой сессии (sessions.list, sessions.patch)
  • Cron-задания: список/добавление/редактирование/запуск/включение/отключение + история запусков (cron.*)
  • Навыки: статус, включение/отключение, установка, обновление API-ключей (skills.*)
  • Узлы: список + возможности (node.list)
  • Одобрения exec: редактирование списков разрешений gateway или узлов + политика запроса для exec host=gateway/node (exec.approvals.*)
  • Конфигурация: просмотр/редактирование ~/.openclaw/openclaw.json (config.get, config.set)
  • Конфигурация: применение + перезапуск с валидацией (config.apply) и пробуждение последней активной сессии
  • Запись конфигурации включает защиту base-hash для предотвращения конфликтов при параллельном редактировании
  • Схема конфигурации + рендеринг форм (config.schema, включая схемы плагинов и каналов); редактор Raw JSON остается доступным
  • Отладка: снимки статуса/здоровья/моделей + журнал событий + ручные RPC-вызовы (status, health, models.list)
  • Логи: живой вывод файловых логов gateway с фильтром/экспортом (logs.tail)
  • Обновление: запуск обновления пакета/git + перезапуск (update.run) с отчетом о перезапуске

Примечания к панели cron-заданий:

  • Для изолированных заданий доставка по умолчанию — анонс сводки. Вы можете переключить на none, если хотите только внутренние запуски.
  • Поля channel/target появляются при выборе announce.
  • Режим webhook использует delivery.mode = "webhook" с delivery.to, установленным на валидный HTTP(S) URL вебхука.
  • Для заданий основной сессии доступны режимы доставки webhook и none.
  • Расширенные элементы управления редактированием включают delete-after-run, clear agent override, опции cron exact/stagger, переопределения модели/thinking агента и переключатели доставки best-effort.
  • Валидация формы встроенная, с ошибками на уровне полей; невалидные значения отключают кнопку сохранения до исправления.
  • Установите cron.webhookToken, чтобы отправлять выделенный bearer-токен; если опущено, вебхук отправляется без заголовка авторизации.
  • Устаревший фолбэк: сохраненные устаревшие задания с notify: true все еще могут использовать cron.webhook до миграции.

Поведение чата​

  • chat.send — неблокирующий: он немедленно подтверждается с { runId, status: "started" }, а ответ передается через события chat.
  • Повторная отправка с тем же idempotencyKey возвращает { status: "in_flight" } во время выполнения и { status: "ok" } после завершения.
  • Ответы chat.history ограничены по размеру для безопасности UI. Когда записи транскрипта слишком велики, Gateway может обрезать длинные текстовые поля, опускать тяжелые блоки метаданных и заменять слишком большие сообщения на заглушку ([chat.history omitted: message too large]).
  • chat.inject добавляет примечание ассистента в транскрипт сессии и рассылает событие chat для обновлений только в UI (без запуска агента, без доставки в канал).
  • Остановка:
    • Нажмите Stop (вызывает chat.abort)
    • Введите /stop (или отдельные фразы прерывания, такие как stop, stop action, stop run, stop openclaw, please stop) для аборта вне полосы
    • chat.abort поддерживает { sessionKey } (без runId) для прерывания всех активных запусков для этой сессии
  • Сохранение частичного результата при аборте:
    • Когда запуск прерван, частичный текст ассистента все еще может отображаться в UI
    • Gateway сохраняет частичный текст ассистента из прерванного запуска в историю транскрипта, если существует буферизованный вывод
    • Сохраненные записи включают метаданные аборта, чтобы потребители транскрипта могли отличать частичные результаты аборта от обычного завершенного вывода

Доступ через Tailnet (рекомендуется)​

Интегрированный Tailscale Serve (предпочтительно)​

Оставьте Gateway на loopback и позвольте Tailscale Serve проксировать его с HTTPS:

openclaw gateway --tailscale serve

Откройте:

  • https:/// (или ваш настроенный gateway.controlUi.basePath)

По умолчанию запросы Serve для Control UI/WebSocket могут аутентифицироваться через заголовки идентификации Tailscale (tailscale-user-login), когда gateway.auth.allowTailscale имеет значение true. OpenClaw проверяет идентификацию, разрешая адрес x-forwarded-for с помощью tailscale whois и сопоставляя его с заголовком, и принимает их только тогда, когда запрос попадает на loopback с заголовками x-forwarded-* от Tailscale. Установите gateway.auth.allowTailscale: false (или принудительно gateway.auth.mode: "password"), если хотите требовать токен/пароль даже для трафика Serve. Аутентификация Serve без токена предполагает, что хост gateway доверенный. Если на этом хосте может выполняться ненадежный локальный код, требуйте аутентификацию по токену/паролю.

Привязка к tailnet + токен​

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

Затем откройте:

  • http://<tailscale-ip>:18789/ (или ваш настроенный gateway.controlUi.basePath)

Вставьте токен в настройки UI (отправляется как connect.params.auth.token).

Небезопасный HTTP​

Если вы открываете панель управления по обычному HTTP (http://<lan-ip> или http://<tailscale-ip>), браузер работает в небезопасном контексте и блокирует WebCrypto. По умолчанию OpenClaw блокирует подключения Control UI без идентификации устройства. Рекомендуемое решение: используйте HTTPS (Tailscale Serve) или откройте UI локально:

  • https:/// (Serve)
  • http://127.0.0.1:18789/ (на хосте gateway)

Поведение переключателя небезопасной аутентификации:

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth не обходит проверку идентификации устройства или сопряжения Control UI. Только для аварийных случаев:

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

dangerouslyDisableDeviceAuth отключает проверку идентификации устройства Control UI и является серьезным снижением безопасности. Отмените быстро после аварийного использования. См. Tailscale для руководства по настройке HTTPS.

Сборка UI​

Gateway обслуживает статические файлы из dist/control-ui. Соберите их с помощью:

pnpm ui:build # автоматически устанавливает зависимости UI при первом запуске

Опциональный абсолютный базовый путь (когда нужны фиксированные URL ресурсов):

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

Для локальной разработки (отдельный dev-сервер):

pnpm ui:dev # автоматически устанавливает зависимости UI при первом запуске

Затем укажите UI на URL WebSocket вашего Gateway (например, ws://127.0.0.1:18789).

Отладка/тестирование: dev-сервер + удаленный Gateway​

Control UI — это статические файлы; цель WebSocket настраивается и может отличаться от HTTP-источника. Это удобно, когда вы хотите иметь Vite dev-сервер локально, а Gateway работает где-то еще.

  1. Запустите dev-сервер UI: pnpm ui:dev
  2. Откройте URL вида:
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

Опциональная одноразовая аутентификация (если нужно):

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

Примечания:

  • gatewayUrl сохраняется в localStorage после загрузки и удаляется из URL.
  • token импортируется в память для текущей вкладки и удаляется из URL; он не сохраняется в localStorage.
  • password хранится только в памяти.
  • Когда gatewayUrl установлен, UI не возвращается к учетным данным из конфигурации или окружения. Укажите token (или password) явно. Отсутствие явных учетных данных является ошибкой.
  • Используйте wss://, когда Gateway находится за TLS (Tailscale Serve, HTTPS-прокси и т.д.).
  • gatewayUrl принимается только в окне верхнего уровня (не встроенном), чтобы предотвратить clickjacking.
  • Развертывания Control UI не на loopback должны явно устанавливать gateway.controlUi.allowedOrigins (полные origin). Это включает удаленные dev-настройки.
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true включает режим фолбэка на origin из заголовка Host, но это опасный режим безопасности.

Пример:

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

Детали настройки удаленного доступа: Удаленный доступ.

ВебПанель управления