Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці розташовані під openclaw gateway ….

Виявлення Bonjour

Налаштування локального mDNS + глобального DNS-SD.

Огляд виявлення

Як OpenClaw оголошує про шлюзи й знаходить їх.

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

Ключі конфігурації gateway верхнього рівня.

​
Запуск Gateway

Запустіть локальний процес Gateway: 
openclaw gateway
Псевдонім для запуску на передньому плані: 
openclaw gateway run
  • За замовчуванням 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, відновіть термінал перед виходом.

​
Параметри

​
--port <port>
number
Порт WebSocket (значення за замовчуванням береться з config/env; зазвичай 18789).
​
--bind <loopback|lan|tailnet|auto|custom>
string
Режим прив’язки слухача.
​
--auth <token|password>
string
Перевизначення режиму автентифікації.
​
--token <token>
string
Перевизначення токена (також задає OPENCLAW_GATEWAY_TOKEN для процесу).
​
--password <password>
string
Перевизначення пароля.
​
--password-file <path>
string
Прочитати пароль gateway з файлу.
​
--tailscale <off|serve|funnel>
string
Відкрити доступ до Gateway через Tailscale.
​
--tailscale-reset-on-exit
boolean
Скинути конфігурацію Tailscale serve/funnel під час завершення.
​
--allow-unconfigured
boolean
Дозволити запуск gateway без gateway.mode=local у конфігурації. Обходить захист запуску лише для разового/dev bootstrap; не записує й не виправляє файл конфігурації.
​
--dev
boolean
Створити dev config + робочий простір, якщо їх немає (пропускає BOOTSTRAP.md).
​
--reset
boolean
Скинути dev config + облікові дані + сесії + робочий простір (потребує --dev).
​
--force
boolean
Завершити будь-який наявний слухач на вибраному порту перед запуском.
​
--verbose
boolean
Докладні журнали.
​
--cli-backend-logs
boolean
Показувати в консолі лише журнали backend CLI (і ввімкнути stdout/stderr).
​
--ws-log <auto|full|compact>
string
за замовчуванням:"auto"
Стиль журналу WebSocket.
​
--compact
boolean
Псевдонім для --ws-log compact.
​
--raw-stream
boolean
Записувати сирі події потоку моделі в jsonl.
​
--raw-stream-path <path>
string
Шлях до jsonl сирого потоку.

​
Перезапуск Gateway

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force
openclaw gateway restart --safe просить запущений Gateway виконати попередню перевірку активної роботи OpenClaw перед перезапуском. Якщо активні операції в черзі, доставлення відповідей, вбудовані запуски або запуски завдань, Gateway повідомляє про блокувальники, об’єднує дубльовані запити безпечного перезапуску й перезапускається після завершення активної роботи. Звичайний restart зберігає наявну поведінку менеджера сервісів для сумісності. Використовуйте --force лише тоді, коли явно хочете негайний шлях примусового перевизначення.
Вбудований --password може бути видимим у локальних списках процесів. Надавайте перевагу --password-file, env або gateway.auth.password на основі SecretRef.

​
Профілювання запуску

  • Задайте OPENCLAW_GATEWAY_STARTUP_TRACE=1, щоб записувати в журнал таймінги фаз під час запуску Gateway, включно із затримкою eventLoopMax для кожної фази та таймінгами таблиць пошуку plugin для installed-index, реєстру manifest, планування запуску й роботи owner-map.
  • Задайте OPENCLAW_DIAGNOSTICS=timeline із OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>, щоб записати best-effort JSONL timeline діагностики запуску для зовнішніх QA harnesses. Також можна ввімкнути прапорець через diagnostics.flags: ["timeline"] у конфігурації; шлях все одно надається через env. Додайте OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1, щоб включити вибірки event-loop.
  • Запустіть pnpm test:startup:gateway -- --runs 5 --warmup 1, щоб виміряти швидкодію запуску Gateway. Бенчмарк записує перший вивід процесу, /healthz, /readyz, таймінги трасування запуску, затримку event-loop і подробиці таймінгів таблиць пошуку plugin.

​
Запит до запущеного Gateway

Усі команди запитів використовують WebSocket RPC.
  • За замовчуванням: зручно для читання людиною (кольорове в TTY).
  • --json: машинозчитуваний JSON (без стилізації/spinner).
  • --no-color (або NO_COLOR=1): вимкнути ANSI, зберігаючи людське компонування.
Коли ви задаєте --url, CLI не повертається до облікових даних із конфігурації або середовища. Передайте --token або --password явно. Відсутність явних облікових даних є помилкою.

​
gateway health

openclaw gateway health --url ws://127.0.0.1:18789
HTTP endpoint /healthz — це liveness probe: він повертає відповідь, щойно сервер може відповідати через HTTP. HTTP endpoint /readyz суворіший і залишається червоним, поки startup plugin sidecars, канали або налаштовані хуки ще стабілізуються. Локальні або автентифіковані докладні відповіді готовності містять діагностичний блок eventLoop із затримкою event-loop, використанням event-loop, співвідношенням CPU core та прапорцем degraded.

​
gateway usage-cost

Отримати зведення вартості використання з журналів сесій. 
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
​
--days <days>
number
за замовчуванням:"30"
Кількість днів для включення.

​
gateway stability

Отримати останній diagnostic stability recorder із запущеного Gateway. 
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
​
--limit <limit>
number
за замовчуванням:"25"
Максимальна кількість останніх подій для включення (макс. 1000).
​
--type <type>
string
Фільтрувати за типом діагностичної події, наприклад payload.large або diagnostic.memory.pressure.
​
--since-seq <seq>
number
Включати лише події після номера діагностичної послідовності.
​
--bundle [path]
string
Прочитати збережений stability bundle замість виклику запущеного Gateway. Використовуйте --bundle latest (або просто --bundle) для найновішого bundle у каталозі стану або передайте шлях до JSON bundle напряму.
​
--export
boolean
Записати придатний для поширення zip із діагностикою підтримки замість друку подробиць стабільності.
​
--output <path>
string
Шлях виводу для --export.
  • Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/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 diagnostics export

Записати локальний zip із діагностикою, призначений для додавання до звітів про помилки. Модель конфіденційності та вміст bundle описано в Експорт діагностики. 
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
​
--output <path>
string
Шлях до zip виводу. За замовчуванням — support export у каталозі стану.
​
--log-lines <count>
number
за замовчуванням:"5000"
Максимальна кількість очищених рядків журналу для включення.
​
--log-bytes <bytes>
number
за замовчуванням:"1000000"
Максимальна кількість байтів журналу для перевірки.
​
--url <url>
string
WebSocket URL Gateway для snapshot стану здоров’я.
​
--token <token>
string
Токен Gateway для snapshot стану здоров’я.
​
--password <password>
string
Пароль Gateway для snapshot стану здоров’я.
​
--timeout <ms>
number
за замовчуванням:"3000"
Тайм-аут snapshot статусу/стану здоров’я.
​
--no-stability-bundle
boolean
Пропустити пошук збереженого stability bundle.
​
--json
boolean
Надрукувати записаний шлях, розмір і manifest як JSON.
Експорт містить manifest, Markdown-зведення, форму конфігурації, очищені подробиці конфігурації, очищені зведення журналів, очищені snapshot статусу/стану здоров’я Gateway і найновіший stability bundle, якщо він існує. Він призначений для поширення. Він зберігає операційні подробиці, які допомагають із налагодженням, наприклад безпечні поля журналу OpenClaw, назви підсистем, коди статусу, тривалості, налаштовані режими, порти, id plugin, id провайдерів, несекретні налаштування функцій і заредаговані операційні повідомлення журналу. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookie, ідентифікатори акаунтів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Коли повідомлення у стилі LogTape схоже на текст payload користувача/чату/інструмента, експорт зберігає лише факт, що повідомлення було пропущено, а також його кількість байтів.

​
gateway status

gateway status показує сервіс Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливості підключення/автентифікації. 
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
​
--url <url>
string
Додайте явну ціль перевірки. Налаштований віддалений хост + localhost усе одно перевіряються.
​
--token <token>
string
Автентифікація токеном для перевірки.
​
--password <password>
string
Автентифікація паролем для перевірки.
​
--timeout <ms>
number
за замовчуванням:"10000"
Тайм-аут перевірки.
​
--no-probe
boolean
Пропустити перевірку підключення (перегляд лише сервісу).
​
--deep
boolean
Також сканувати сервіси системного рівня.
​
--require-rpc
boolean
Підвищити стандартну перевірку підключення до перевірки читання та завершуватися з ненульовим кодом, коли ця перевірка читання не вдається. Не можна поєднувати з --no-probe.
  • 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 пропускають розв’язання токена конфігурації.

​
gateway probe

gateway probe — це команда «debug everything». Вона завжди перевіряє:
  • ваш налаштований віддалений gateway (якщо задано), і
  • localhost (loopback) навіть якщо віддалений gateway налаштовано.
Якщо передати --url, ця явна ціль додається перед обома. Вивід для людини позначає цілі так:
  • URL (explicit)
  • Remote (configured) або Remote (configured, inactive)
  • Local loopback
Якщо доступні кілька gateway, команда друкує їх усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість установок усе одно запускає один gateway.
openclaw gateway probe
openclaw gateway probe --json
  • 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.

​
Віддалений доступ через SSH (паритет із Mac app)

Режим “Remote over SSH” у macOS app використовує локальне перенаправлення порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за адресою ws://127.0.0.1:<port>. Еквівалент CLI: 
openclaw gateway probe --ssh user@gateway-host
​
--ssh <target>
string
user@host або user@host:port (порт за замовчуванням 22).
​
--ssh-identity <path>
string
Файл ідентичності.
​
--ssh-auto
boolean
Вибрати перший виявлений хост gateway як SSH-ціль із розв’язаного endpoint виявлення (local. плюс налаштований wide-area domain, якщо є). Підказки лише TXT ігноруються.
Конфігурація (необов’язкова, використовується як значення за замовчуванням):
  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

​
gateway call <method>

Низькорівневий RPC-помічник. 
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
​
--params <json>
string
за замовчуванням:"{}"
Рядок JSON-об’єкта для params.
​
--url <url>
string
WebSocket URL Gateway.
​
--token <token>
string
Токен Gateway.
​
--password <password>
string
Пароль Gateway.
​
--timeout <ms>
number
Бюджет тайм-ауту.
​
--expect-final
boolean
Переважно для agent-style RPC, які транслюють проміжні події перед фінальним payload.
​
--json
boolean
Машинозчитуваний JSON-вивід.
--params має бути дійсним JSON.

​
Керування сервісом Gateway

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

​
Установлення з wrapper

Використовуйте --wrapper, коли керований сервіс має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або run-as helper. Wrapper отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати openclaw або Node із цими аргументами. 
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
Ви також можете задати wrapper через середовище. gateway install перевіряє, що шлях є виконуваним файлом, записує wrapper у service ProgramArguments і зберігає OPENCLAW_WRAPPER у середовищі сервісу для подальших примусових перевстановлень, оновлень і виправлень doctor. 
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
Щоб видалити збережений wrapper, очистьте OPENCLAW_WRAPPER під час перевстановлення: 
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
  • 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 не задано, установлення блокується, доки режим не буде задано явно.

​
Виявлення gateway (Bonjour)

gateway discover сканує beacons Gateway (_openclaw-gw._tcp).
  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: openclaw.internal.) і налаштуйте split DNS + DNS-сервер; див. Bonjour.
Лише gateway, для яких увімкнено виявлення Bonjour (типово), рекламують beacon. Записи Wide-Area discovery містять (TXT):
  • role (підказка ролі gateway)
  • transport (підказка транспорту, напр. gateway)
  • gatewayPort (порт WebSocket, зазвичай 18789)
  • sshPort (необов’язково; клієнти типово використовують 22 для SSH-цілей, коли його немає)
  • tailnetDns (ім’я хоста MagicDNS, коли доступне)
  • gatewayTls / gatewayTlsSha256 (TLS увімкнено + відбиток сертифіката)
  • cliPath (підказка віддаленого встановлення, записана в wide-area зону)

​
gateway discover

openclaw gateway discover
​
--timeout <ms>
number
за замовчуванням:"2000"
Тайм-аут для команди (browse/resolve).
​
--json
boolean
Машинозчитуваний вивід (також вимикає стилізацію/індикатор виконання).
Приклади: 
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
  • CLI сканує local. плюс налаштований wide-area домен, коли його ввімкнено.
  • wsUrl у JSON-виводі походить від розв’язаного endpoint сервісу, а не від підказок лише з TXT, як-от lanHost або tailnetDns.
  • У local. mDNS, sshPort і cliPath транслюються лише коли discovery.mdns.mode дорівнює full. Wide-area DNS-SD все одно записує cliPath; sshPort там також лишається необов’язковим.

​
Пов’язане