Вопрос

OpenClaw Gateway: что это и как им управлять

Что держит Gateway на одном порту, как его запустить, проверить, перезапустить и поднять второй инстанс для изоляции.

· 5 мин чтения

Коротко

  • Gateway — один долгоживущий процесс. Каналы, WebSocket, HTTP API и Control UI на одном порту (18789 по умолчанию).
  • Запуск: openclaw gateway --port 18789. Под супервизором ставьте через openclaw gateway install, для рестарта зовите openclaw gateway restart.
  • Перезагрузка конфига: режим gateway.reload.mode="hybrid" по умолчанию применяет безопасные правки горячо, остальное требует рестарта.
  • Удалённый доступ: Tailscale или SSH-туннель; туннель не отменяет auth, клиент по-прежнему передаёт token или password из gateway.auth.*.

Сверено с документацией OpenClaw 2026.9.9, 10 октября 2026.

Gateway в OpenClaw — один процесс, через который идут все каналы сообщений (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat) и к которому подключаются клиенты и узлы (role: "node"). Он же поднимает Control UI и HTTP API. На хосте должен быть ровно один Gateway: только он открывает сессию WhatsApp через Baileys, и держать два экземпляра на одной машине обычно не нужно.

Из чего состоит Gateway

Архитектура простая: один процесс и один мультиплексный порт. На нём работают WebSocket для панели управления и RPC, HTTP-эндпоинты /v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke, маршруты плагинов вроде POST /api/v1/admin/rpc, а также Control UI и хуки. Эндпоинт /v1/models отдаёт openclaw, openclaw/default и openclaw/<agentId> для каждого настроенного агента. openclaw/default — это стабильный псевдоним для агента по умолчанию.

Соединения делятся на три типа. Клиенты (macOS-приложение, CLI, веб-админка) подключаются по WebSocket с запросами health, status, send, agent и подпиской на события tick, agent, presence, shutdown. Узлы (macOS, iOS, Android, headless) подключаются к тому же WS, но заявляют role: "node" с явными caps и командами (camera.*, screen.record, location.get). Первым кадром всегда идёт connect, иначе соединение жёстко закрывается.

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

Порт по умолчанию: 18789. Порядок разрешения: флаг --port, переменная OPENCLAW_GATEWAY_PORT, ключ gateway.port, и только потом 18789. Режим привязки (--bind): loopback по умолчанию, lan, tailnet, auto, custom. Внутри контейнера auto раскрывается в 0.0.0.0, а Tailscale serve/funnel всегда принудительно ставит loopback.

Аутентификация по умолчанию включена. Для общего секрета задаётся gateway.auth.token или gateway.auth.password (или OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD). Для не-loopback reverse-proxy есть режим gateway.auth.mode: "trusted-proxy". Привязка за пределы loopback без аутентификации блокируется на старте.

Запуск, проверка, остановка

Базовые команды, которые пригодятся в первый день:

openclaw gateway --port 18789
openclaw gateway --port 18789 --verbose
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

Здоровый ответ gateway status содержит Runtime: running, Connectivity probe: ok и строку Capability, совпадающую с ожидаемой. Чтобы получить подтверждение RPC с областью чтения, а не только проверку доступности порта, добавьте флаг --require-rpc. Глубокий осмотр системных сервисов — это флаг --deep: он ищет LaunchDaemons, systemd-юниты, schtasks, а не более глубокий RPC-зонд.

Если меняли gateway.port, обновите установленный сервис: openclaw doctor --fix или openclaw gateway install --force, иначе launchd/systemd/schtasks продолжит запускать процесс на старом порте.

Жизненный цикл и супервизия

Для продакшена используйте супервизор. На macOS это launchd:

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

Перезапускайте через openclaw gateway restart, а не цепочкой stop + start. На macOS stop под капотом зовёт launchctl bootout и проверяет, что LaunchAgent выгружен и процесс вышел. Чтобы подавить авто-восстановление через перезагрузку, добавьте openclaw gateway stop --disable.

Перезагрузка конфига в режиме hybrid (по умолчанию): безопасные изменения применяются к активному снимку конфигурации атомарно, остальные требуют перезапуска. Режимы hot и restart убраны в v2026.7.2-beta.4 и стабильно заменены на hybrid начиная с v2026.8.1; openclaw doctor --fix переводит оба старых значения в hybrid.

Для ручного перезапуска отправляйте SIGUSR2 — это авторизованный перезапуск внутри процесса. SIGUSR1 занят инспектором Node, для рестарта используйте SIGUSR2 или openclaw gateway restart. Чтобы запретить внешний SIGUSR2, поставьте commands.restart в false.

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

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

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

После прокидывания порта клиенты подключаются к ws://127.0.0.1:18789. Туннель не отменяет аутентификацию: клиент по-прежнему обязан передать token или password.

Чтобы посмотреть настроенный токен, на хосте шлюза выполните openclaw gateway auth-token --show. Команда требует интерактивный терминал и отказывается писать в пайп, чтобы секрет не утек в логи. Если постоянный токен не задан, сначала openclaw doctor --generate-gateway-token, затем перезапуск Gateway, затем снова auth-token --show.

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

Обычно это лишнее, один Gateway держит несколько агентов и каналов. Дополнительный экземпляр имеет смысл только для изоляции или резервного бота. Тогда каждому инстансу задают разные 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

Частые ошибки

  • Стартуют командой openclaw gateway, но в конфиге нет gateway.mode=local, и процесс отказывается подниматься. Решение: openclaw onboard --mode local или флаг --allow-unconfigured для разовых запусков.
  • Перезапускают Gateway цепочкой stop + start, а это не штатный перезапуск. Используйте openclaw gateway restart.
  • Сменили gateway.port, но не обновили установленный сервис. После правки выполните openclaw doctor --fix или openclaw gateway install --force.
  • Открывают порт наружу и забывают про аутентификацию. Без общего секрета или trusted-proxy привязка за пределы loopback блокируется. На LAN и публичных биндах аутентификация обязательна.
  • Используют SIGUSR1 для рестарта, а это сигнал инспектора Node. Для авторизованного рестарта отправляйте SIGUSR2 или вызывайте openclaw gateway restart.