Шлюз

Runbook шлюза

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

Глубокое устранение неполадок

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

Конфигурация

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

Управление секретами

Контракт SecretRef, поведение снимка состояния во время выполнения и операции миграции/перезагрузки.

Контракт плана секретов

Точные правила применения секретов (target/path) и поведение auth-profile только по ссылке.

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

Шаг 1: Запуск шлюза

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

Шаг 2: Проверка работоспособности службы

openclaw gateway status
openclaw status
openclaw logs --follow

Здоровое базовое состояние: Runtime: running и RPC probe: ok.

Шаг 3: Проверка готовности каналов

openclaw channels status --probe

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

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

  • Один постоянно работающий процесс для маршрутизации, плоскости управления и подключений каналов.
  • Один мультиплексированный порт для:
    • WebSocket управления/RPC
    • HTTP API (OpenAI-совместимые, Responses, вызов инструментов)
    • UI управления и хуков
  • Режим привязки по умолчанию: loopback.
  • Аутентификация требуется по умолчанию (gateway.auth.token / gateway.auth.password, или OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

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

НастройкаПорядок разрешения
Порт шлюза--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Режим привязкиCLI/переопределение → gateway.bind → loopback

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

gateway.reload.modeПоведение
offБез перезагрузки конфигурации
hotПрименять только безопасные для горячей замены изменения
restartПерезапуск при изменениях, требующих перезагрузки
hybrid (по умолчанию)Горячее применение, когда безопасно, перезапуск, когда требуется

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

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

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

Предпочтительно: Tailscale/VPN. Запасной вариант: SSH-туннель.

ssh -N -L 18789:127.0.0.1:18789 user@host

Затем подключайте клиенты локально к ws://127.0.0.1:18789.

⚠️ Если настроена аутентификация шлюза, клиенты все равно должны отправлять данные аутентификации (token/password) даже через SSH-туннели.

См.: Удаленный шлюз, Аутентификация, Tailscale.

Надзор и жизненный цикл службы

Используйте управляемые запуски для надежности, приближенной к производственной.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

Несколько шлюзов на одном хосте

В большинстве настроек должен работать один шлюз. Используйте несколько только для строгой изоляции/резервирования (например, для резервного профиля). Контрольный список для каждого экземпляра:

  • Уникальный gateway.port
  • Уникальный OPENCLAW_CONFIG_PATH
  • Уникальный OPENCLAW_STATE_DIR
  • Уникальный agents.defaults.workspace

Пример:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

См.: Несколько шлюзов.

Быстрый путь для dev-профиля

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

Краткий справочник по протоколу (с точки зрения оператора)

  • Первый фрейм от клиента должен быть connect.
  • Шлюз возвращает снимок состояния hello-ok (presence, health, stateVersion, uptimeMs, лимиты/политики).
  • Запросы: req(method, params) → res(ok/payload|error).
  • Общие события: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Запуски агента выполняются в два этапа:

  1. Немедленное подтверждение принятия (status:"accepted")
  2. Финальный ответ о завершении (status:"ok"|"error"), с потоковыми событиями agent между ними.

Полная документация по протоколу: Протокол шлюза.

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

Активность (Liveness)

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

Готовность (Readiness)

openclaw gateway status
openclaw channels status --probe
openclaw health

Восстановление после разрыва

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

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

СигнатураВероятная проблема
refusing to bind gateway ... without authПривязка не к loopback без токена/пароля
another gateway instance is already listening / EADDRINUSEКонфликт портов
Gateway start blocked: set gateway.mode=localВ конфигурации установлен удаленный режим
unauthorized во время подключенияНесоответствие аутентификации между клиентом и шлюзом

Для полных лестниц диагностики используйте Устранение неполадок шлюза.

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

  • Клиенты протокола шлюза быстро завершаются с ошибкой при недоступности шлюза (без неявного перехода на прямой канал).
  • Неверные/не-connect первые фреймы отклоняются и соединение закрывается.
  • Плавное завершение работы отправляет событие shutdown перед закрытием сокета.

Связанные темы:

Конфигурация