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

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

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw 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-маршрутов Plugin, например необязательного /api/v1/admin/rpc
  • Control UI и хуков
• Режим привязки по умолчанию: loopback.
• По умолчанию требуется аутентификация. Настройки с общим секретом используют gateway.auth.token / gateway.auth.password (или OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), а настройки reverse proxy не для 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, когда нужно переопределить backend-провайдера/модель; иначе обычная модель и настройка embeddings выбранного агента остаются управляющими.

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

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

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

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

Запуск Gateway использует тот же эффективный порт и привязку, когда подготавливает локальные источники Control UI для привязок не к loopback. Например, --bind lan --port 3000 подготавливает http://localhost:3000 и http://127.0.0.1:3000 перед выполнением runtime-проверки. Явно добавьте любые удаленные источники браузера, например HTTPS proxy URL, в gateway.controlUi.allowedOrigins.

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

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

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

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

В большинстве установок следует запускать один gateway на машину. Один gateway может размещать несколько агентов и каналов.

Несколько gateway нужны только тогда, когда вы намеренно хотите изоляцию или rescue bot.

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

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-туннель, proxy 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@host

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

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

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

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

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 <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=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

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

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

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

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

• Первый кадр клиента должен быть connect.
• Gateway возвращает снимок hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
• hello-ok.features.methods / events — это консервативный список обнаружения, а не сгенерированный дамп каждого вызываемого вспомогательного маршрута.
• Запросы: req(method, params) → res(ok/payload|error).
• Частые события включают connect.challenge, agent, chat, session.message, session.operation, session.tool, 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 перед закрытием сокета.

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

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

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

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