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

Углублённое устранение неполадок

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

Конфигурация

Руководство по настройке на основе задач и полный справочник по конфигурации.

Управление секретами

Контракт SecretRef, поведение снимка среды выполнения и операции миграции и перезагрузки.

Контракт плана секретов

Точные правила цели/пути secrets apply и поведение профиля аутентификации, использующего только ссылки.

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

1

Запустите Gateway

2

Проверьте работоспособность службы

Базовые признаки нормальной работы: Runtime: running, Connectivity probe: ok и строка Capability, соответствующая ожидаемому значению. Используйте openclaw gateway status --require-rpc для проверки RPC с областью чтения, а не только доступности.
3

Проверьте готовность каналов

Если 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/<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.

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

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

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

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

В большинстве установок следует запускать один Gateway на машину. Один Gateway может обслуживать несколько агентов и каналов. Несколько экземпляров Gateway нужны только тогда, когда вы намеренно хотите обеспечить изоляцию или использовать резервного бота. Полезные проверки:
Ожидаемое поведение:
  • 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
Пример:
Подробная настройка: /gateway/multiple-gateways.

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

Предпочтительно: Tailscale/VPN. Резервный вариант: SSH-туннель.
Затем подключайте клиенты локально к ws://127.0.0.1:18789.
SSH-туннели не позволяют обойти аутентификацию Gateway. При аутентификации с общим секретом клиенты даже через туннель должны отправлять token/password. В режимах с передачей удостоверения запрос всё равно должен удовлетворять требованиям соответствующего пути аутентификации.
См.: Удалённый Gateway, Аутентификация, Tailscale.

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

Для надёжности на уровне производственной среды используйте запуск под управлением супервизора.
Используйте 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.<profile> (именованный профиль). openclaw doctor проверяет и исправляет расхождения конфигурации службы.
При ошибках недопустимой конфигурации процесс завершается с кодом 78. Системные модули systemd в Linux используют RestartPreventExitStatus=78, чтобы прекратить повторные запуски до исправления конфигурации. В launchd и планировщике заданий Windows нет эквивалентного правила остановки по коду завершения, поэтому Gateway также сохраняет историю быстрых некорректных запусков и после повторяющихся сбоев запуска подавляет автоматический запуск учётных записей каналов и поставщиков. В этом безопасном режиме плоскость управления всё равно запускается для проверки и исправления, горячая перезагрузка конфигурации и secrets.reload не выполняют автоматический перезапуск каналов, а явный запрос оператора channels.start может отменить это ограничение.

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

По умолчанию используются изолированные состояние и конфигурация, а также базовый порт 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 со снимком состояния.

​
Готовность

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

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

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

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

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

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

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