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 сейчас разрешаются через BYOH-пути только IPv4.
• BYOH только с IPv6 сейчас нативно не поддерживается на этом пути. Используйте IPv4-sidecar или прокси, если сам хост работает только с IPv6.
• SIGUSR1 запускает внутрипроцессный перезапуск, когда это разрешено (commands.restart включен по умолчанию; задайте commands.restart: false, чтобы заблокировать ручной перезапуск, при этом применение/обновление через инструмент или конфигурацию gateway остается разрешенным).
• Обработчики SIGINT/SIGTERM останавливают процесс Gateway, но не восстанавливают какое-либо пользовательское состояние терминала. Если вы оборачиваете CLI с помощью TUI или ввода в raw-режиме, восстановите терминал перед выходом.

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

• gateway status остается доступной для диагностики, даже если локальная конфигурация CLI отсутствует или недействительна.
• gateway status по умолчанию подтверждает состояние службы, подключение WebSocket и возможность аутентификации, видимую во время рукопожатия. Она не подтверждает операции чтения/записи/администрирования.
• Диагностические проверки не изменяют состояние при первичной аутентификации устройства: они повторно используют существующий кэшированный токен устройства, если он есть, но не создают новую идентичность устройства CLI или запись связывания устройства только для чтения только для проверки состояния.
• gateway status по возможности разрешает настроенные SecretRefs аутентификации для аутентификации проверки.
• Если требуемый SecretRef аутентификации не разрешен в этом пути команды, gateway status --json сообщает rpc.authWarning, когда проверка подключения/аутентификации не проходит; передайте --token/--password явно или сначала разрешите источник секрета.
• Если проверка проходит успешно, предупреждения о неразрешенных ссылках аутентификации подавляются, чтобы избежать ложных срабатываний.
• Когда проверка включена, вывод 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-окружения (сначала окружение команды службы, затем резервно окружение процесса).
• Если аутентификация токеном фактически не активна (явный 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, проверка повторно использует существующую кэшированную аутентификацию устройства, но не создает первичную идентичность устройства или состояние связывания.
• Код выхода ненулевой только когда ни одна проверенная цель недостижима.

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

• 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: настроенный 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 предварительно проверить активную работу OpenClaw и отложить перезапуск, пока не завершатся доставка ответов, встроенные запуски и запуски задач. --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 для скриптов.

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