Руководство по эксплуатации Gateway

Используйте эту страницу для первоначального запуска и последующей эксплуатации службы Gateway.

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

openclaw gateway --port 18789# отладочные данные и трассировка дублируются в стандартный ввод-выводopenclaw gateway --port 18789 --verbose# принудительно завершить процесс, прослушивающий выбранный порт, затем запуститьopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

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

• Один постоянно работающий процесс для маршрутизации, плоскости управления и подключений каналов.
• Один мультиплексированный порт для:
  • управления и RPC через WebSocket
  • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • HTTP-маршрутов плагинов, например необязательного /api/v1/admin/rpc
  • интерфейса управления и хуков
• Режим привязки по умолчанию: loopback. В обнаруженной контейнерной среде фактическое значение по умолчанию — auto (разрешается в 0.0.0.0 для перенаправления портов), если не активен режим serve/funnel Tailscale, который всегда принудительно использует loopback.
• По умолчанию требуется аутентификация. Конфигурации с общим секретом используют gateway.auth.token / gateway.auth.password (или OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), а конфигурации обратного прокси не через loopback могут использовать gateway.auth.mode: "trusted-proxy".

Эндпоинты, совместимые с OpenAI

Наиболее значимая поверхность совместимости OpenClaw:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Почему этот набор важен:

• Большинство интеграций Open WebUI, LobeChat и LibreChat сначала проверяют /v1/models.
• Многие конвейеры RAG и памяти ожидают /v1/embeddings.
• Клиенты, ориентированные на агентов, всё чаще предпочитают /v1/responses.

/v1/models в первую очередь ориентирован на агентов: он возвращает openclaw, openclaw/default и openclaw/<agentId> для каждого настроенного агента. openclaw/default — стабильный псевдоним, всегда сопоставляемый с настроенным агентом по умолчанию. Отправляйте x-openclaw-model, когда требуется переопределить серверного поставщика или модель; в противном случае управление сохраняют обычные настройки модели и эмбеддингов выбранного агента.

Все эти эндпоинты работают на основном порту Gateway и используют ту же доверенную границу аутентификации оператора, что и остальная часть HTTP API Gateway.

Административный HTTP RPC (POST /api/v1/admin/rpc) — это отдельный, по умолчанию отключённый маршрут плагина для инструментов хоста, которые не могут использовать RPC через WebSocket. См. Административный HTTP RPC.

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

Установленные службы Gateway записывают разрешённое значение --port в метаданные супервизора. После изменения gateway.port выполните openclaw doctor --fix или openclaw gateway install --force, чтобы launchd/systemd/schtasks запускал процесс на новом порту.

При запуске Gateway использует тот же фактический порт и режим привязки для формирования локальных источников интерфейса управления при привязках не к loopback. Например, --bind lan --port 3000 добавляет http://localhost:3000 и http://127.0.0.1:3000 до выполнения проверки среды выполнения. Явно добавьте все источники удалённых браузеров, например HTTPS-адреса прокси, в gateway.controlUi.allowedOrigins.

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

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

openclaw gateway statusopenclaw gateway status --deep   # добавляет проверку служб на уровне системыopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep предназначен для дополнительного обнаружения служб (LaunchDaemons/системных модулей systemd/schtasks), а не для более глубокой проверки работоспособности RPC.

Несколько экземпляров Gateway на одном хосте

В большинстве установок следует запускать один Gateway на машину. Один Gateway может обслуживать несколько агентов и каналов. Несколько экземпляров Gateway нужны только тогда, когда вы намеренно хотите обеспечить изоляцию или использовать резервного бота.

Полезные проверки:

openclaw gateway status --deepopenclaw gateway probe

Ожидаемое поведение:

• gateway status --deep может сообщать Other gateway-like services detected (best effort) и выводить рекомендации по очистке, если сохраняются устаревшие установки launchd/systemd/schtasks.
• gateway probe может предупреждать о multiple reachable gateway identities, когда отвечают разные экземпляры Gateway или когда OpenClaw не может доказать, что доступные цели являются одним и тем же Gateway. SSH-туннель, URL-адрес прокси или настроенный удалённый URL-адрес к одному Gateway представляют собой один 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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Подробная настройка: /gateway/multiple-gateways.

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

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

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

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

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

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

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

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=Gateway OpenClawAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

При ошибках недопустимой конфигурации процесс завершается с кодом 78. Системные модули systemd в Linux используют RestartPreventExitStatus=78, чтобы прекратить повторные запуски до исправления конфигурации. В launchd и планировщике заданий Windows нет эквивалентного правила остановки по коду завершения, поэтому Gateway также сохраняет историю быстрых некорректных запусков и после повторяющихся сбоев запуска подавляет автоматический запуск учётных записей каналов и поставщиков. В этом безопасном режиме плоскость управления всё равно запускается для проверки и исправления, горячая перезагрузка конфигурации и secrets.reload не выполняют автоматический перезапуск каналов, а явный запрос оператора channels.start может отменить это ограничение.

Быстрый запуск профиля разработки

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

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

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

• Первым кадром клиента должен быть connect.
• Gateway возвращает кадр hello-ok с snapshot (presence, health, stateVersion, uptimeMs), а также ограничениями policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events — это консервативный список для обнаружения, а не автоматически созданный перечень всех доступных для вызова вспомогательных маршрутов.
• Запросы: req(method, params) → res(ok/payload|error).
• К распространённым событиям относятся connect.challenge, agent, chat, session.message, session.operation, session.tool, включаемые по желанию session.approval, sessions.changed, presence, tick, health, heartbeat, события жизненного цикла сопряжения и подтверждения, а также shutdown.

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

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

Полную документацию протокола см. в разделе Протокол Gateway.

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

Доступность

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

Готовность

openclaw gateway statusopenclaw channels status --probeopenclaw health

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

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

Типичные признаки сбоев

Полные последовательности диагностики см. в разделе Устранение неполадок Gateway.

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

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

Связанные разделы

• Конфигурация
• Устранение неполадок Gateway
• Фоновый процесс
• Состояние системы
• Doctor
• Аутентификация
• Удалённый доступ
• Управление секретами