Gateway

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

• Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/plugin і заредаговані зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie, секретні значення, імена хостів або сирі id сесій. Задайте diagnostics.enabled: false, щоб повністю вимкнути recorder.
• Під час фатальних завершень Gateway, тайм-аутів завершення й помилок запуску після перезапуску 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-підключення та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування.
• Діагностичні перевірки не вносять змін для автентифікації пристрою вперше: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність CLI-пристрою чи запис read-only сполучення пристрою лише для перевірки статусу.
• gateway status за можливості розв’язує налаштовані auth SecretRefs для автентифікації перевірки.
• Якщо обов’язковий auth SecretRef не розв’язано в цьому шляху команди, gateway status --json повідомляє rpc.authWarning, коли підключення/автентифікація перевірки не вдається; передайте --token/--password явно або спершу розв’яжіть джерело секрету.
• Якщо перевірка успішна, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибних спрацювань.
• Використовуйте --require-rpc у скриптах і автоматизації, коли сервіс, що прослуховує порт, недостатній і потрібно, щоб RPC-виклики з областю читання також були справними.
• --deep додає best-effort сканування додаткових установок launchd/systemd/schtasks. Коли виявлено кілька gateway-подібних сервісів, вивід для людини друкує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину.
• --deep також повідомляє про нещодавню передачу перезапуску супервізора Gateway, коли процес сервісу коректно завершився для перезапуску зовнішнім супервізором.
• Вивід для людини містить розв’язаний шлях до файлового журналу, а також знімок шляхів/чинності конфігурації CLI проти сервісу, щоб допомогти діагностувати розбіжність профілю або state-dir.

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

• 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: доступність після connect + degraded класифікації.
• rpcOk: успішне повне RPC деталей.
• scopeLimited: RPC деталей не вдалося через відсутню область оператора.

Для кожної цілі (targets[].auth):

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

• ssh_tunnel_failed: налаштування SSH-тунелю не вдалося; команда повернулася до прямих перевірок.
• multiple_gateways: доступна більше ніж одна ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot.
• 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Використовуйте gateway restart, щоб перезапустити керований сервіс. Не поєднуйте gateway stop і gateway start як заміну перезапуску; на macOS gateway stop навмисно вимикає LaunchAgent перед його зупинкою.
• gateway restart --safe просить запущений Gateway попередньо перевірити активну роботу OpenClaw і відкласти перезапуск, доки доставка відповідей, embedded runs і task runs не завершаться. --safe не можна поєднувати з --force або --wait.
• gateway restart --wait 30s перевизначає налаштований бюджет drain для цього перезапуску. Числа без одиниць — мілісекунди; приймаються одиниці на кшталт s, m і h. --wait 0 очікує безстроково.
• gateway restart --force пропускає drain активної роботи та перезапускає негайно. Використовуйте це, коли оператор уже перевірив перелічені блокувальники завдань і хоче повернути 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 не задано, установлення блокується, доки режим не буде задано явно.