Перейти до основного вмісту
Використовуйте цю сторінку для запуску Gateway service у перший день і для операцій другого дня.

Поглиблене усунення несправностей

Діагностика від симптомів із точними послідовностями команд і сигнатурами журналів.

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

Орієнтований на завдання посібник із налаштування + повний довідник конфігурації.

Керування секретами

Контракт SecretRef, поведінка runtime snapshot і операції міграції/перезавантаження.

Контракт плану секретів

Точні правила цілі/шляху secrets apply і поведінка профілю автентифікації лише за посиланням.

​
5-хвилинний локальний запуск

1

Запустіть Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Перевірте справність служби

openclaw gateway status
openclaw status
openclaw logs --follow
Базовий справний стан: Runtime: running, Connectivity probe: ok і Capability: ..., що відповідає вашим очікуванням. Використовуйте openclaw gateway status --require-rpc, коли потрібне підтвердження RPC з областю читання, а не лише доступність.
3

Перевірте готовність каналів

openclaw channels status --probe
За доступного gateway це виконує live-перевірки каналів для кожного облікового запису й необов’язкові аудити. Якщо gateway недоступний, CLI натомість повертається до підсумків каналів лише з конфігурації, без виводу live-перевірок.
Перезавантаження конфігурації Gateway відстежує шлях активного файла конфігурації (визначений із типових значень профілю/стану або з OPENCLAW_CONFIG_PATH, якщо задано). Типовий режим — gateway.reload.mode="hybrid". Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно замінює цей знімок.

​
Модель виконання

  • Один постійно запущений процес для маршрутизації, control plane і підключень каналів.
  • Один мультиплексований порт для:
    • WebSocket-керування/RPC
    • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • HTTP-маршрутів Plugin, як-от необов’язковий /api/v1/admin/rpc
    • Control UI і хуків
  • Типовий режим прив’язки: loopback.
  • Автентифікація потрібна за замовчуванням. Налаштування зі спільним секретом використовують gateway.auth.token / gateway.auth.password (або OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), а налаштування reverse proxy не через loopback можуть використовувати gateway.auth.mode: "trusted-proxy".

​
OpenAI-сумісні endpoints

Найцінніша поверхня сумісності OpenClaw тепер така:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Чому цей набір важливий:
  • Більшість інтеграцій Open WebUI, LobeChat і LibreChat спершу перевіряють /v1/models.
  • Багато RAG- і memory-конвеєрів очікують /v1/embeddings.
  • Agent-native клієнти дедалі частіше віддають перевагу /v1/responses.
Примітка щодо планування:
  • /v1/models орієнтований насамперед на agent: він повертає openclaw, openclaw/default і openclaw/<agentId>.
  • openclaw/default — стабільний псевдонім, який завжди відповідає налаштованому типовому agent.
  • Використовуйте x-openclaw-model, коли потрібне перевизначення backend-провайдера/моделі; інакше звичайні налаштування моделі та embeddings вибраного agent залишаються керівними.
Усе це працює на основному порту Gateway і використовує ту саму межу автентифікації довіреного оператора, що й решта HTTP API Gateway. Admin HTTP RPC (POST /api/v1/admin/rpc) — це окремий, типово вимкнений маршрут Plugin для host tooling, який не може використовувати WebSocket RPC. Див. Admin HTTP RPC.

​
Пріоритет порту й прив’язки

НалаштуванняПорядок визначення
Порт Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Режим прив’язкиCLI/override → gateway.bind → loopback
Встановлені служби gateway записують визначений --port у metadata супервізора. Після зміни gateway.port запустіть openclaw doctor --fix або openclaw gateway install --force, щоб launchd/systemd/schtasks запускали процес на новому порту. Під час запуску Gateway використовує той самий фактичний порт і прив’язку, коли засіває локальні джерела Control UI для прив’язок не через loopback. Наприклад, --bind lan --port 3000 засіває http://localhost:3000 і http://127.0.0.1:3000 до запуску runtime- валідації. Додавайте будь-які джерела віддаленого браузера, як-от HTTPS proxy URLs, до gateway.controlUi.allowedOrigins явно.

​
Режими гарячого перезавантаження

gateway.reload.modeПоведінка
offБез перезавантаження конфігурації
hotЗастосовувати лише hot-safe зміни
restartПерезапускати за змін, що потребують перезапуску
hybrid (типово)Застосовувати гаряче, коли безпечно; перезапускати, коли потрібно

​
Набір команд оператора

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep призначено для додаткового виявлення служб (LaunchDaemons/systemd system units/schtasks), а не для глибшої RPC-перевірки справності.

​
Кілька gateways (той самий host)

Більшість установок мають запускати один gateway на машину. Один gateway може розміщувати кілька agents і каналів. Кілька gateways потрібні лише тоді, коли ви навмисно хочете ізоляцію або rescue bot. Корисні перевірки: 
openclaw gateway status --deep
openclaw gateway probe
Очікувана поведінка:
  • gateway status --deep може повідомити Other gateway-like services detected (best effort) і вивести підказки з очищення, коли застарілі встановлення launchd/systemd/schtasks усе ще присутні.
  • gateway probe може попередити про multiple reachable gateway identities, коли відповідають різні gateways або коли OpenClaw не може довести, що доступні цілі є тим самим gateway. SSH tunnel, proxy URL або налаштований remote URL до того самого gateway — це один gateway із кількома transport, навіть якщо порти transport відрізняються.
  • Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного gateway.
Контрольний список для кожного екземпляра:
  • Унікальний gateway.port
  • Унікальний OPENCLAW_CONFIG_PATH
  • Унікальний OPENCLAW_STATE_DIR
  • Унікальний agents.defaults.workspace
Приклад: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Докладне налаштування: /gateway/multiple-gateways.

​
Віддалений доступ

Бажано: Tailscale/VPN. Резервний варіант: SSH-тунель. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Потім підключайте клієнти локально до ws://127.0.0.1:18789.
SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти все одно мають надсилати token/password навіть через тунель. Для режимів із передаванням ідентичності запит усе одно має відповідати цьому шляху автентифікації.
Див.: Віддалений Gateway, Автентифікація, Tailscale.

​
Нагляд і життєвий цикл служби

Використовуйте запуск під наглядом для надійності, подібної до продакшн-середовища. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Використовуйте openclaw gateway restart для перезапусків. Не поєднуйте openclaw gateway stop і openclaw gateway start як заміну перезапуску.На macOS gateway stop типово використовує launchctl bootout — це вилучає LaunchAgent із поточної сесії завантаження без постійного вимкнення, тож автоматичне відновлення KeepAlive усе одно працює після неочікуваних збоїв, а gateway start повторно вмикає службу коректно. Щоб постійно приглушити автоматичний повторний запуск між перезавантаженнями, передайте --disable: openclaw gateway stop --disable.Мітки LaunchAgent: ai.openclaw.gateway (типово) або ai.openclaw.<profile> (іменований профіль). openclaw doctor перевіряє та виправляє розбіжності конфігурації служби.

​
Швидкий шлях для dev-профілю

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Типові значення включають ізольовані стан/конфігурацію та базовий порт gateway 19001.

​
Короткий довідник протоколу (погляд оператора)

  • Першим кадром клієнта має бути connect.
  • Gateway повертає знімок hello-ok (presence, health, stateVersion, uptimeMs, обмеження/політика).
  • hello-ok.features.methods / events — це консервативний список для виявлення, а не згенерований дамп кожного callable helper route.
  • Запити: req(method, params) → res(ok/payload|error).
  • Поширені події включають connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, події життєвого циклу pairing/approval і shutdown.
Запуски агента мають два етапи:
  1. Негайне підтвердження прийняття (status:"accepted")
  2. Фінальна відповідь про завершення (status:"ok"|"error"), із потоковими подіями agent між ними.
Див. повну документацію протоколу: Протокол Gateway.

​
Операційні перевірки

​
Liveness

  • Відкрийте WS і надішліть connect.
  • Очікуйте відповідь hello-ok зі знімком.

​
Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Відновлення після пропусків

Події не відтворюються повторно. У разі пропусків послідовності оновіть стан (health, system-presence) перед продовженням.

​
Поширені ознаки збоїв

СигнатураЙмовірна проблема
refusing to bind gateway ... without authПрив’язка не до loopback без дійсного шляху автентифікації Gateway
another gateway instance is already listening / EADDRINUSEКонфлікт порту
Gateway start blocked: set gateway.mode=localКонфігурацію встановлено в remote-режим, або в пошкодженій конфігурації бракує позначки local-режиму
unauthorized during connectНевідповідність автентифікації між клієнтом і Gateway
Для повних діагностичних послідовностей використовуйте Усунення несправностей Gateway.

​
Гарантії безпеки

  • Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного fallback до прямого каналу).
  • Недійсні або не-connect перші кадри відхиляються й закриваються.
  • Коректне завершення роботи надсилає подію shutdown перед закриттям сокета.
Пов’язане:

​
Пов’язане