OpenClaw Gateway: как запустить и безопасно настроить

Короткий ответ

OpenClaw Gateway — постоянно работающий управляющий процесс OpenClaw. Он связывает агентные сессии, инструменты, события и подключения к каналам. CLI, TUI и Control UI обращаются к Gateway, а Gateway обслуживает контроль, HTTP API, Control UI и подключённые каналы через единый порт.

Базовый порядок такой:

1. Завершите установку и onboarding.
2. Запустите Gateway в терминале или установите фоновый сервис.
3. Выполните openclaw gateway status.
4. Откройте Control UI командой openclaw dashboard.
5. Отправьте контролируемое тестовое сообщение.
6. Затем отдельно подключайте каналы и расширяйте права.

По умолчанию Gateway использует loopback-bind. Для локальной проверки это позволяет не публиковать порт в сети; удалённый доступ нужно проектировать отдельно.

Что подключается к Gateway

• CLI отправляет команды управления, диагностики и настройки.
• TUI и Control UI предоставляют интерфейс для работы с ассистентом.
• Каналы передают сообщения из подключённых мессенджеров и других сервисов.
• Агентные сессии обрабатывают запросы, события и результаты выполнения инструментов.
• Модели, tools, skills и plugins расширяют поведение агента в пределах разрешённой конфигурации.

Наличие Gateway не означает, что каждый канал или инструмент уже настроен после установки. Подключение модели, канала и разрешений проверяется отдельно.

Входящие сообщения следует рассматривать как недоверенный ввод. Для выбранного процесса задайте минимальный набор каналов и инструментов.

Подготовьте окружение

Официальная инструкция указывает Node.js 24.16+ или 26.1+; Node 26 рекомендуется. Поддерживаются macOS, Linux и Windows, включая WSL2-сценарий.

Для macOS и Linux:

curl -fsSL https://openclaw.ai/install.sh | bash

Для Windows PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Если пакет установлен напрямую, завершите первоначальную настройку:

openclaw onboard --install-daemon

При быстром запуске Gateway может работать в текущем терминале. В таком случае остановите его сочетанием Ctrl+C, прежде чем устанавливать фоновый сервис. До завершения диагностики зафиксируйте выбранный способ установки и версию CLI.

Вариант A: запуск в терминале

Для локальной проверки запустите Gateway явно:

openclaw gateway --port 18789

Для подробного вывода:

openclaw gateway --port 18789 --verbose

Такой процесс работает, пока открыт терминал.

Вариант B: управляемый сервис

Установите сервис:

openclaw gateway install

Проверьте его:

openclaw gateway status

Для перезапуска используйте:

openclaw gateway restart

На macOS используется LaunchAgent, на Linux и WSL2 — systemd user unit, на нативной Windows — Scheduled Task с резервным вариантом через папку автозапуска, если создание задачи запрещено.

Минимальная проверка

После запуска выполните:

openclaw --version
openclaw doctor
openclaw gateway status
openclaw gateway status --require-rpc
openclaw dashboard

В документации здоровый базовый статус описан признаками Runtime: running и Connectivity probe: ok. Опция --require-rpc нужна, когда требуется подтвердить read-scope RPC-доступность.

Открыв Control UI, отправьте контролируемое тестовое сообщение и отдельно проверьте наличие ошибок в выводе или логах. Успешная загрузка интерфейса подтверждает доступность Control UI, но не доказывает корректность каждого канала или бизнес-сценария.

Для канала выполните:

openclaw channels status --probe

При доступном Gateway команда выполняет живые проверки аккаунтов каналов. Если Gateway недоступен, результат может быть только сводкой по конфигурации. Разбор ошибок и решение о готовности канала — отдельная операторская проверка.

Порт и bind

Порт Gateway разрешается в таком порядке:

1. аргумент --port;
2. OPENCLAW_GATEWAY_PORT;
3. gateway.port в конфигурации;
4. значение по умолчанию 18789.

Для bind действует порядок: CLI или override → gateway.bind → loopback. В контейнерной среде эффективным значением по умолчанию может быть auto, которое разрешается в 0.0.0.0 для port forwarding.

Пример запуска на другом порту:

openclaw gateway --port 19001

Если порт изменён в конфигурации уже установленного сервиса, выполните openclaw doctor --fix или openclaw gateway install --force, затем повторите проверку статуса и Control UI.

Аутентификация

Аутентификация Gateway включена по умолчанию. Для shared-secret схемы документация указывает gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN и OPENCLAW_GATEWAY_PASSWORD.

Сервисное окружение может отличаться от окружения интерактивного терминала, поэтому проверьте, что выбранный способ запуска получает нужный секрет. Не публикуйте токены в сообщениях, общих скриптах и открытых журналах.

Режим trusted-proxy предназначен для non-loopback-схем через reverse proxy и требует отдельной проверки доверенной инфраструктуры. Не включайте его только для обхода ошибки авторизации.

Перед подключением других сотрудников согласуйте пользователей, каналы, разрешённые инструменты, операции с подтверждением и порядок разбора инцидентов. Для изолированных экземпляров нужны раздельные порты, конфигурация, state-каталоги и рабочие области.

VPN или Tailscale

Для удалённого доступа документация рекомендует Tailscale или VPN. Перед подключением проверьте сетевой маршрут, firewall и способ передачи секрета.

SSH-туннель

Если Gateway слушает loopback на удалённой машине, создайте локальный туннель:

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

Клиент обращается к:

ws://127.0.0.1:18789

SSH-туннель не отменяет аутентификацию Gateway. После подключения выполните openclaw gateway status --require-rpc и откройте Control UI.

Если Gateway остановлен

1. Выполните openclaw gateway status --deep для поиска установленных сервисов и возможных конкурирующих экземпляров.
2. Проверьте openclaw logs --follow.
3. Запустите openclaw doctor и исправляйте только подтверждённую проблему.
4. Проверьте выбранные config/state-пути и пользователя, от имени которого работает сервис.
5. После исправления повторите gateway status --require-rpc.

Для Linux user service дополнительно проверьте systemctl --user status, XDG_RUNTIME_DIR и lingering. На Windows проверьте Scheduled Task или fallback-ярлык в Startup. На macOS учитывайте конфликт с системным LaunchDaemon: два владельца жизненного цикла могут конкурировать за один Gateway.

Ошибка авторизации

Сообщение unauthorized указывает на проблему согласования auth-настроек клиента и Gateway. Проверьте адрес и порт, token или password, доступность секрета сервису и значение OPENCLAW_CONFIG_PATH.

Не меняйте bind на более открытый режим как способ исправить авторизацию. Сначала подтвердите адрес, порт и секрет, затем повторите RPC-проверку.

Ошибка refusing to bind gateway ... without auth означает, что Gateway пытается слушать non-loopback-адрес без допустимого пути аутентификации. Вернитесь к loopback либо настройте auth до изменения сетевой доступности.

EADDRINUSE и сообщение о другом экземпляре Gateway указывают на конфликт порта или уже работающий Gateway. Проверьте статус, deep-сканирование и фактический процесс до изменения порта.