Gateway

• По умолчанию Gateway отказывается запускаться, если в ~/.openclaw/openclaw.json не задано gateway.mode=local. Используйте --allow-unconfigured для разовых запусков или запусков в разработке.
• Ожидается, что openclaw onboard --mode local и openclaw setup записывают gateway.mode=local. Если файл существует, но gateway.mode отсутствует, считайте это поврежденной или перезаписанной конфигурацией и исправьте ее, а не предполагайте локальный режим неявно.
• Если файл существует и gateway.mode отсутствует, Gateway считает это подозрительным повреждением конфигурации и отказывается «угадывать local» за вас.
• Привязка за пределами loopback без аутентификации блокируется (защитное ограничение).
• lan, tailnet и custom сейчас разрешаются через IPv4-only пути BYOH.
• IPv6-only BYOH сегодня не поддерживается нативно на этом пути. Используйте IPv4 sidecar или прокси, если сам хост является IPv6-only.
• SIGUSR1 запускает перезапуск внутри процесса, когда это разрешено (commands.restart включен по умолчанию; задайте commands.restart: false, чтобы заблокировать ручной перезапуск, при этом применение/обновление инструмента и конфигурации gateway останутся разрешенными).
• Обработчики SIGINT/SIGTERM останавливают процесс gateway, но не восстанавливают пользовательское состояние терминала. Если вы оборачиваете CLI через TUI или ввод в raw-mode, восстановите терминал перед выходом.

• Записи сохраняют операционные metadata: имена событий, счетчики, размеры в байтах, показания памяти, состояние очереди/сеанса, approval ids, имена channel/plugin и отредактированные сводки сеансов. Они не сохраняют текст чата, тела webhook, вывод инструментов, raw-тела запросов или ответов, токены, cookies, значения секретов, hostnames или raw id сеансов. Задайте diagnostics.enabled: false, чтобы полностью отключить recorder.
• При фатальных завершениях Gateway, тайм-аутах shutdown и сбоях запуска при restart OpenClaw записывает тот же диагностический snapshot в ~/.openclaw/logs/stability/openclaw-stability-*.json, когда у recorder есть события. Изучите новейший bundle с помощью openclaw gateway stability --bundle latest; --limit, --type и --since-seq также применяются к выводу bundle.

• gateway status остается доступной для диагностики, даже когда локальная конфигурация CLI отсутствует или недействительна.
• Стандартная gateway status подтверждает состояние службы, подключение WebSocket и возможность аутентификации, видимую во время рукопожатия. Она не подтверждает операции чтения/записи/администрирования.
• Диагностические проверки не изменяют состояние при первой аутентификации устройства: они повторно используют существующий кэшированный токен устройства, если он есть, но не создают новую идентичность устройства CLI или запись сопряжения устройства только для чтения только для проверки статуса.
• gateway status по возможности разрешает настроенные auth SecretRefs для аутентификации проверки.
• Если обязательный auth SecretRef не разрешен в этом пути команды, gateway status --json сообщает rpc.authWarning, когда подключение/аутентификация проверки завершается ошибкой; передайте --token/--password явно или сначала разрешите источник секрета.
• Если проверка успешна, предупреждения о неразрешенных auth-ref подавляются, чтобы избежать ложных срабатываний.
• Когда проверка включена, вывод JSON включает gateway.version, если запущенный Gateway ее сообщает; --require-rpc может откатиться к полезной нагрузке RPC status.runtimeVersion, если последующая проверка рукопожатия не может предоставить метаданные версии.
• Используйте --require-rpc в скриптах и автоматизации, когда прослушивающей службы недостаточно и вызовы RPC с областью чтения также должны быть работоспособны.
• --deep добавляет best-effort-сканирование дополнительных установок launchd/systemd/schtasks. Когда обнаружено несколько служб, похожих на gateway, вывод для пользователя печатает подсказки по очистке и предупреждает, что в большинстве установок следует запускать один gateway на машину.
• --deep также сообщает о недавней передаче перезапуска супервизора Gateway, когда процесс службы штатно завершился для внешнего перезапуска супервизором.
• --deep запускает проверку конфигурации в режиме с учетом Plugin (pluginValidation: "full") и показывает предупреждения настроенного манифеста Plugin (например, отсутствующие метаданные конфигурации канала), чтобы smoke-проверки установки и обновления их обнаруживали. Стандартная gateway status сохраняет быстрый путь только для чтения, который пропускает проверку Plugin.
• Вывод для пользователя включает разрешенный путь файлового журнала, а также снимок путей/валидности конфигурации CLI и службы, чтобы помочь диагностировать расхождение профиля или каталога состояния.

• В установках Linux systemd проверки расхождения аутентификации службы читают значения Environment= и EnvironmentFile= из unit-файла (включая %h, пути в кавычках, несколько файлов и необязательные файлы с -).
• Проверки расхождения разрешают SecretRefs gateway.auth.token с использованием объединенного runtime-окружения (сначала окружение команды службы, затем fallback на окружение процесса).
• Если аутентификация токеном фактически не активна (явный gateway.auth.mode со значением password/none/trusted-proxy или не заданный режим, где пароль может победить и ни один кандидат токена не может победить), проверки расхождения токена пропускают разрешение токена конфигурации.

• Reachable: yes означает, что хотя бы одна цель приняла подключение WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only сообщает, что проверка смогла подтвердить об аутентификации. Это отдельно от достижимости.
• Read probe: ok означает, что вызовы RPC детализации с областью чтения (health/status/system-presence/config.get) также успешно выполнены.
• Read probe: limited - missing scope: operator.read означает, что подключение успешно, но RPC с областью чтения ограничен. Это сообщается как ухудшенная достижимость, а не полный сбой.
• Read probe: failed после Connect: ok означает, что Gateway принял соединение WebSocket, но последующая диагностика чтения превысила тайм-аут или завершилась ошибкой. Это также ухудшенная достижимость, а не недостижимый Gateway.
• Как и gateway status, probe повторно использует существующую кэшированную аутентификацию устройства, но не создает идентичность устройства или состояние сопряжения при первом использовании.
• Код выхода ненулевой только когда ни одна проверенная цель не достижима.

Верхний уровень:

• ok: хотя бы одна цель достижима.
• degraded: хотя бы одна цель приняла подключение, но не завершила полную подробную RPC-диагностику.
• capability: лучшая возможность, замеченная среди достижимых целей (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope или unknown).
• primaryTargetId: лучшая цель, которую следует считать активным победителем, в таком порядке: явный URL, SSH-туннель, настроенная удаленная цель, затем local loopback.
• warnings[]: best-effort-записи предупреждений с code, message и необязательными targetIds.
• network: подсказки URL local loopback/tailnet, полученные из текущей конфигурации и сетевых данных хоста.
• discovery.timeoutMs и discovery.count: фактически использованный бюджет обнаружения/количество результатов для этого прохода проверки.

Для каждой цели (targets[].connect):

• ok: достижимость после подключения + классификация ухудшенного состояния.
• rpcOk: полный успех подробного RPC.
• scopeLimited: подробный RPC завершился ошибкой из-за отсутствующей области оператора.

Для каждой цели (targets[].auth):

• role: роль аутентификации, сообщенная в hello-ok, когда доступна.
• scopes: предоставленные области, сообщенные в hello-ok, когда доступны.
• capability: показанная классификация возможности аутентификации для этой цели.

• ssh_tunnel_failed: настройка SSH-туннеля завершилась ошибкой; команда откатилась к прямым проверкам.
• multiple_gateways: были достижимы разные идентичности gateway, или OpenClaw не смог доказать, что достижимые цели являются одним и тем же gateway. SSH-туннель, URL proxy или настроенный удаленный URL к тому же gateway не вызывают это предупреждение.
• auth_secretref_unresolved: настроенный auth SecretRef не удалось разрешить для цели с ошибкой.
• probe_scope_limited: подключение WebSocket успешно, но проверка чтения была ограничена из-за отсутствующего operator.read.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Используйте gateway restart, чтобы перезапустить управляемый сервис. Не связывайте gateway stop и gateway start в цепочку как замену перезапуску.
• В macOS gateway stop по умолчанию использует launchctl bootout, что удаляет LaunchAgent из текущего загрузочного сеанса без сохранения отключения — автоматическое восстановление KeepAlive остается активным для будущих сбоев, а gateway start повторно включает сервис без ручного launchctl enable. Передайте --disable, чтобы постоянно подавить KeepAlive и RunAtLoad, чтобы Gateway не запускался снова до следующего явного gateway start; используйте это, когда ручная остановка должна переживать перезагрузки или рестарты системы.
• gateway restart --safe просит работающий Gateway предварительно проверить активную работу и запланировать один объединенный перезапуск после завершения активной работы. Безопасный перезапуск по умолчанию ожидает активную работу до настроенного gateway.reload.deferralTimeoutMs (по умолчанию 5 минут); когда этот бюджет истекает, перезапуск выполняется принудительно. Установите gateway.reload.deferralTimeoutMs в 0 для бессрочного безопасного ожидания, которое никогда не выполняет принудительный перезапуск. --safe нельзя сочетать с --force или --wait.
• gateway restart --wait 30s переопределяет настроенный бюджет ожидания завершения работы для этого перезапуска. Числа без единиц измеряются в миллисекундах; поддерживаются единицы вроде s, m и h. --wait 0 ждет бессрочно.
• gateway restart --safe --skip-deferral выполняет безопасный перезапуск с учетом OpenClaw, но обходит шлюз отсрочки, поэтому Gateway немедленно выдает событие перезапуска, даже если сообщаются блокировщики. Аварийный выход для оператора при зависших отсрочках запусков задач; требует --safe.
• gateway restart --force пропускает ожидание завершения активной работы и перезапускает немедленно. Используйте это, когда оператор уже проверил перечисленные блокировщики задач и хочет вернуть Gateway в работу прямо сейчас.
• Команды жизненного цикла принимают --json для сценариев.

• Когда token auth требует токен, а gateway.auth.token управляется через SecretRef, gateway install проверяет, что SecretRef можно разрешить, но не сохраняет разрешенный токен в метаданные окружения сервиса.
• Если token auth требует токен, а настроенный SecretRef токена не разрешается, установка завершается отказом вместо сохранения fallback в виде открытого текста.
• Для password auth в gateway run предпочитайте OPENCLAW_GATEWAY_PASSWORD, --password-file или gateway.auth.password на базе SecretRef вместо встроенного --password.
• В выводимом режиме auth заданный только в оболочке OPENCLAW_GATEWAY_PASSWORD не смягчает требования к токену при установке; при установке управляемого сервиса используйте устойчивую конфигурацию (gateway.auth.password или config env).
• Если настроены и gateway.auth.token, и gateway.auth.password, а gateway.auth.mode не задан, установка блокируется, пока режим не будет задан явно.