> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Руководство по эксплуатации Gateway Используйте эту страницу для первоначального запуска и последующей эксплуатации службы Gateway. Диагностика по симптомам с точными последовательностями команд и сигнатурами журналов. Руководство по настройке на основе задач и полный справочник по конфигурации. Контракт SecretRef, поведение снимка среды выполнения и операции миграции и перезагрузки. Точные правила цели/пути `secrets apply` и поведение профиля аутентификации, использующего только ссылки. ## Локальный запуск за 5 минут ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway --port 18789 # отладочные данные и трассировка дублируются в стандартный ввод-вывод openclaw gateway --port 18789 --verbose # принудительно завершить процесс, прослушивающий выбранный порт, затем запустить openclaw gateway --force ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status openclaw status openclaw logs --follow ``` Базовые признаки нормальной работы: `Runtime: running`, `Connectivity probe: ok` и строка `Capability`, соответствующая ожидаемому значению. Используйте `openclaw gateway status --require-rpc` для проверки RPC с областью чтения, а не только доступности. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw channels status --probe ``` Если Gateway доступен, команда выполняет оперативные проверки каналов для каждой учётной записи и необязательные аудиты. Если Gateway недоступен, CLI возвращается к сводкам каналов только на основе конфигурации. Перезагрузка конфигурации Gateway отслеживает путь к активному файлу конфигурации (определяемый из профиля и стандартных параметров состояния либо из `OPENCLAW_CONFIG_PATH`, если он задан). Режим по умолчанию — `gateway.reload.mode="hybrid"`. После первой успешной загрузки запущенный процесс обслуживает активный снимок конфигурации в памяти; успешная перезагрузка атомарно заменяет этот снимок. ## Модель среды выполнения * Один постоянно работающий процесс для маршрутизации, плоскости управления и подключений каналов. * Один мультиплексированный порт для: * управления и 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/` для каждого настроенного агента. `openclaw/default` — стабильный псевдоним, всегда сопоставляемый с настроенным агентом по умолчанию. Отправляйте `x-openclaw-model`, когда требуется переопределить серверного поставщика или модель; в противном случае управление сохраняют обычные настройки модели и эмбеддингов выбранного агента. Все эти эндпоинты работают на основном порту Gateway и используют ту же доверенную границу аутентификации оператора, что и остальная часть HTTP API Gateway. Административный HTTP RPC (`POST /api/v1/admin/rpc`) — это отдельный, по умолчанию отключённый маршрут плагина для инструментов хоста, которые не могут использовать RPC через WebSocket. См. [Административный HTTP RPC](/ru/plugins/admin-http-rpc). ### Приоритет порта и привязки | Параметр | Порядок разрешения | | -------------- | ---------------------------------------------------------------------------- | | Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | | Режим привязки | CLI/переопределение → `gateway.bind` → `loopback` (или `auto` в контейнерах) | Установленные службы 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`. ### Режимы горячей перезагрузки | `gateway.reload.mode` | Поведение | | ----------------------- | --------------------------------------------------------------------------------- | | `off` | Без перезагрузки конфигурации | | `hot` | Применять только изменения, безопасные для горячей перезагрузки | | `restart` | Перезапускать при изменениях, требующих перезагрузки | | `hybrid` (по умолчанию) | Применять без перезапуска, когда это безопасно, и перезапускать при необходимости | ## Набор команд оператора ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` `gateway status --deep` предназначен для дополнительного обнаружения служб (LaunchDaemons/системных модулей systemd/schtasks), а не для более глубокой проверки работоспособности RPC. ## Несколько экземпляров Gateway на одном хосте В большинстве установок следует запускать один Gateway на машину. Один Gateway может обслуживать несколько агентов и каналов. Несколько экземпляров Gateway нужны только тогда, когда вы намеренно хотите обеспечить изоляцию или использовать резервного бота. Полезные проверки: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status --deep openclaw 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` Пример: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` Подробная настройка: [/gateway/multiple-gateways](/ru/gateway/multiple-gateways). ## Удалённый доступ Предпочтительно: Tailscale/VPN. Резервный вариант: SSH-туннель. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh -N -L 18789:127.0.0.1:18789 user@gateway-host ``` Затем подключайте клиенты локально к `ws://127.0.0.1:18789`. SSH-туннели не позволяют обойти аутентификацию Gateway. При аутентификации с общим секретом клиенты даже через туннель должны отправлять `token`/`password`. В режимах с передачей удостоверения запрос всё равно должен удовлетворять требованиям соответствующего пути аутентификации. См.: [Удалённый Gateway](/ru/gateway/remote), [Аутентификация](/ru/gateway/authentication), [Tailscale](/ru/gateway/tailscale). ## Надзор и жизненный цикл службы Для надёжности на уровне производственной среды используйте запуск под управлением супервизора. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway install openclaw gateway status openclaw gateway restart openclaw gateway stop ``` Используйте `openclaw gateway restart` для перезапуска. Не используйте последовательный вызов `openclaw gateway stop` и `openclaw gateway start` вместо перезапуска. В macOS `gateway stop` по умолчанию использует `launchctl bootout`. Это удаляет LaunchAgent из текущего сеанса загрузки без постоянного отключения, поэтому автоматическое восстановление KeepAlive продолжает работать после непредвиденных сбоев, а `gateway start` корректно включает службу повторно. Чтобы постоянно запрещать автоматический повторный запуск после перезагрузок, передайте `--disable`: `openclaw gateway stop --disable`. Метки LaunchAgent: `ai.openclaw.gateway` (по умолчанию) или `ai.openclaw.` (именованный профиль). `openclaw doctor` проверяет и исправляет расхождения конфигурации службы. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway install systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` Чтобы служба продолжала работать после выхода из системы, включите lingering: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo loginctl enable-linger $(whoami) ``` На сервере без графической среды также убедитесь, что задан `XDG_RUNTIME_DIR` (`export XDG_RUNTIME_DIR=/run/user/$(id -u)`), прежде чем повторять команды `systemctl --user`. Пример пользовательского модуля для случая, когда требуется нестандартный путь установки: ```ini theme={"theme":{"light":"min-light","dark":"min-dark"}} [Unit] Description=Gateway OpenClaw After=network-online.target Wants=network-online.target StartLimitBurst=5 StartLimitIntervalSec=60 [Service] ExecStart=/usr/local/bin/openclaw gateway --port 18789 Restart=always RestartSec=5 RestartPreventExitStatus=78 TimeoutStopSec=30 TimeoutStartSec=30 SuccessExitStatus=0 143 OOMPolicy=continue KillMode=control-group [Install] WantedBy=default.target ``` ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway install openclaw gateway status --json openclaw gateway restart openclaw gateway stop ``` Управляемый запуск в Windows использует запланированную задачу с именем `OpenClaw Gateway` (или `OpenClaw Gateway ()` для именованных профилей). Если в создании запланированной задачи отказано, OpenClaw использует средство запуска из пользовательской папки автозагрузки, которое указывает на `gateway.cmd` в каталоге состояния. Используйте системный модуль для многопользовательских и постоянно работающих хостов. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` Используйте то же содержимое службы, что и для пользовательского модуля, но установите его в `/etc/systemd/system/openclaw-gateway[-].service` и скорректируйте `ExecStart=`, если исполняемый файл `openclaw` находится в другом месте. Не разрешайте `openclaw doctor --fix` также устанавливать пользовательскую службу Gateway для того же профиля и порта. Doctor отказывается от такой автоматической установки, если обнаруживает системную службу Gateway OpenClaw; используйте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, когда жизненным циклом управляет системный модуль. При ошибках недопустимой конфигурации процесс завершается с кодом `78`. Системные модули systemd в Linux используют `RestartPreventExitStatus=78`, чтобы прекратить повторные запуски до исправления конфигурации. В launchd и планировщике заданий Windows нет эквивалентного правила остановки по коду завершения, поэтому Gateway также сохраняет историю быстрых некорректных запусков и после повторяющихся сбоев запуска подавляет автоматический запуск учётных записей каналов и поставщиков. В этом безопасном режиме плоскость управления всё равно запускается для проверки и исправления, горячая перезагрузка конфигурации и `secrets.reload` не выполняют автоматический перезапуск каналов, а явный запрос оператора `channels.start` может отменить это ограничение. ## Быстрый запуск профиля разработки ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw --dev setup openclaw --dev gateway --allow-unconfigured openclaw --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](/ru/gateway/protocol). ## Операционные проверки ### Доступность * Откройте WS-соединение и отправьте `connect`. * Ожидайте ответ `hello-ok` со снимком состояния. ### Готовность ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw gateway status openclaw channels status --probe openclaw health ``` ### Восстановление после пропусков События не воспроизводятся повторно. При пропусках в последовательности обновите состояние (`health`, `system-presence`), прежде чем продолжить. ## Типичные признаки сбоев | Признак | Вероятная проблема | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `refusing to bind gateway ... without auth` | Привязка не к loopback-интерфейсу без допустимого способа аутентификации Gateway | | `another gateway instance is already listening` / `EADDRINUSE` | Конфликт портов | | `Gateway start blocked: set gateway.mode=local` | В конфигурации задан удалённый режим либо в повреждённой конфигурации отсутствует `gateway.mode` | | `unauthorized` при подключении | Несоответствие параметров аутентификации клиента и Gateway | Полные последовательности диагностики см. в разделе [Устранение неполадок Gateway](/ru/gateway/troubleshooting). ## Гарантии безопасности * Клиенты протокола Gateway немедленно завершают работу с ошибкой, если Gateway недоступен (без неявного перехода к прямому каналу). * Недопустимые первые кадры и первые кадры, не предназначенные для подключения, отклоняются, после чего соединение закрывается. * При корректном завершении работы перед закрытием сокета отправляется событие `shutdown`. ## Связанные разделы * [Конфигурация](/ru/gateway/configuration) * [Устранение неполадок Gateway](/ru/gateway/troubleshooting) * [Фоновый процесс](/ru/gateway/background-process) * [Состояние системы](/ru/gateway/health) * [Doctor](/ru/gateway/doctor) * [Аутентификация](/ru/gateway/authentication) * [Удалённый доступ](/ru/gateway/remote) * [Управление секретами](/ru/gateway/secrets)