Gateway

• За замовчуванням Gateway відмовляється запускатися, якщо в ~/.openclaw/openclaw.json не задано gateway.mode=local. Використовуйте --allow-unconfigured для ad-hoc/dev запусків.
• Очікується, що openclaw onboard --mode local і openclaw setup записують gateway.mode=local. Якщо файл існує, але gateway.mode відсутній, вважайте це зламаною або перезаписаною конфігурацією та відновіть її, замість неявно припускати локальний режим.
• Якщо файл існує, а gateway.mode відсутній, Gateway трактує це як підозріле пошкодження конфігурації та відмовляється "вгадувати local" за вас.
• Прив’язування поза межами loopback без автентифікації заблоковано (захисне обмеження).
• SIGUSR1 запускає перезапуск у процесі, коли це дозволено (commands.restart увімкнено за замовчуванням; задайте commands.restart: false, щоб заблокувати ручний перезапуск, при цьому застосування/оновлення gateway tool/config залишаються дозволеними).
• Обробники SIGINT/SIGTERM зупиняють процес gateway, але не відновлюють жоден користувацький стан термінала. Якщо ви обгортаєте CLI за допомогою TUI або введення в raw-mode, відновіть термінал перед виходом.

• Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черг/сесій, назви каналів/Plugin і відредаговані зведення сесій. Вони не зберігають текст чатів, тіла webhook, виводи tool, raw тіла запитів або відповідей, токени, cookies, секретні значення, hostnames або raw session ids. Задайте diagnostics.enabled: false, щоб повністю вимкнути recorder.
• Під час fatal Gateway exits, shutdown timeouts і restart startup failures OpenClaw записує той самий diagnostic 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 за можливості розв’язує налаштовані SecretRefs автентифікації для автентифікації зондування.
• Якщо потрібний SecretRef автентифікації не розв’язано в цьому шляху команди, gateway status --json повідомляє rpc.authWarning, коли з’єднання/автентифікація зондування не вдається; явно передайте --token/--password або спочатку розв’яжіть джерело секрету.
• Якщо зондування успішне, попередження про нерозв’язані посилання автентифікації пригнічуються, щоб уникнути хибних спрацювань.
• Використовуйте --require-rpc у скриптах і автоматизації, коли сервісу, що прослуховує, недостатньо і також потрібна справність RPC-викликів з областю читання.
• --deep додає найкраще можливе сканування додаткових інсталяцій 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[]: записи попереджень у режимі найкращого зусилля з 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: доступною була більш ніж одна ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад рятувального бота.
• 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.
• У виведеному режимі автентифікації лише оболонковий OPENCLAW_GATEWAY_PASSWORD не послаблює вимоги до токена під час установлення; використовуйте тривалу конфігурацію (gateway.auth.password або конфігураційний env) під час установлення керованого сервісу.
• Якщо налаштовано і gateway.auth.token, і gateway.auth.password, а gateway.auth.mode не задано, установлення блокується, доки режим не буде задано явно.