Skip to main content

​
Рунбук сервиса Gateway

Используйте эту страницу для запуска в первый день (day-1) и эксплуатации во второй день (day-2) сервиса Gateway.

Deep troubleshooting

Диагностика от симптомов с точными последовательностями команд и сигнатурами логов.

Configuration

Руководство по настройке, ориентированное на задачи, + полный справочник по конфигурации.

​
Локальный запуск за 5 минут

1

Start the Gateway

2

Verify service health

Базовое состояние: Runtime: running и RPC probe: ok.
3

Validate channel readiness

Перезагрузка конфигурации Gateway отслеживает путь к активному файлу конфигурации (определяется из значений профиля/состояния по умолчанию или из OPENCLAW_CONFIG_PATH, если задан). Режим по умолчанию: gateway.reload.mode="hybrid" (безопасные изменения применяются на лету, критические — с перезапуском).

​
Модель выполнения

  • Один постоянно работающий процесс для маршрутизации, control plane и подключений каналов.
  • Мультиплексирование на одном порту.
    • WebSocket control/RPC
    • OpenResponses (HTTP): /v1/responses.
    • Control UI и хуки
  • Режим привязки по умолчанию: loopback.
  • Аутентификация Gateway по умолчанию обязательна: задайте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN) либо gateway.auth.password.

​
Приоритет порта и привязки

​
Режимы горячей перезагрузки

​
Набор команд оператора

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

Предпочтительно Tailscale/VPN; в противном случае — SSH-туннель: Резервный вариант: SSH-туннель.
Затем клиенты подключаются к ws://127.0.0.1:18789 через туннель.
Если настроен токен, клиенты должны включать его в connect.params.auth.token даже через туннель.
См.: Remote Gateway, Authentication, Tailscale.

​
Контроль и жизненный цикл службы

Используйте supervised-запуск для надежности уровня production.
Метки LaunchAgent: ai.openclaw.gateway (по умолчанию) или ai.openclaw.<profile> при запуске именованного профиля. openclaw doctor проверяет и устраняет расхождения конфигурации службы.

​
Несколько Gateway (на одном хосте)

Обычно не требуется: один Gateway может обслуживать несколько каналов сообщений и агентов. Используйте несколько Gateway только для резервирования или строгой изоляции (например, rescue bot). Checklist per instance:
  • уникальный gateway.port
  • уникальный OPENCLAW_CONFIG_PATH
  • уникальный OPENCLAW_STATE_DIR
  • уникальный agents.defaults.workspace
Пример:
См. Multiple gateways.

​
Профиль Dev (--dev)

По умолчанию включают изолированное состояние/конфигурацию и базовый порт gateway 19001.

​
Протокол (взгляд оператора)

  • Клиенты должны переподключиться.
  • Gateway возвращает снимок hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • Запросы: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Типичные события: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Запуски агента двухэтапные:
  1. Немедленное подтверждение принятия (status:"accepted")
  2. Ответы agent двухэтапные: сначала res ack {runId,status:"accepted"}, затем финальный res {runId,status:"ok"|"error",summary} после завершения выполнения; потоковый вывод приходит как event:"agent".
Полная документация: Протокол Gateway и Протокол Bridge (устаревший).

​
Операционные проверки

​
Проверка доступности (liveness)

  • Откройте WS и отправьте connect.
  • Ожидайте ответ hello-ok со снимком состояния.

​
Готовность (readiness)

​
Восстановление после пропуска последовательности

События не воспроизводятся повторно. При пропуске последовательности обновите состояние (health, system-presence) перед продолжением.

​
Типичные сигнатуры сбоев

Для полной диагностики используйте Gateway Troubleshooting.

​
Гарантии безопасности

  • Нет резервного перехода к прямым подключениям Baileys; если Gateway недоступен, отправки немедленно завершаются ошибкой.
  • Некорректные первые фреймы подключения или повреждённый JSON отклоняются, и сокет закрывается.
  • Корректное завершение: перед закрытием отправляется событие shutdown; клиенты должны обрабатывать закрытие и переподключение.
Связано: