Skip to main content
Використовуйте цю сторінку для початкового запуску та подальшої експлуатації служби Gateway.

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

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

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

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

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

Контракт SecretRef, поведінка знімка під час виконання та операції міграції й перезавантаження.

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

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

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

1

Запустіть Gateway

2

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

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

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

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

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

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

​
Кінцеві точки, сумісні з OpenAI

Найефективніша поверхня сумісності 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 і пам’яті очікують /v1/embeddings.
  • Клієнти, орієнтовані на агентів, дедалі частіше віддають перевагу /v1/responses.
/v1/models насамперед орієнтована на агентів: вона повертає openclaw, openclaw/default і openclaw/<agentId> для кожного налаштованого агента. openclaw/default — стабільний псевдонім, який завжди зіставляється з налаштованим стандартним агентом. Надсилайте x-openclaw-model, коли потрібно перевизначити внутрішнього провайдера/модель; інакше керування зберігають звичайна модель і налаштування вбудовування вибраного агента. Усі ці кінцеві точки працюють на основному порту Gateway і використовують ту саму довірену межу автентифікації оператора, що й решта HTTP API Gateway. Адміністративний HTTP RPC (POST /api/v1/admin/rpc) — це окремий, стандартно вимкнений маршрут Plugin для інструментів хоста, які не можуть використовувати RPC через WebSocket. Див. Адміністративний HTTP RPC.

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

Установлені служби Gateway записують визначений --port у метаданих супервізора. Після зміни gateway.port запустіть openclaw doctor --fix або openclaw gateway install --force, щоб launchd/systemd/schtasks запускав процес на новому порту. Під час запуску Gateway використовує той самий фактичний порт і прив’язку, коли формує локальні джерела інтерфейсу керування для прив’язок поза loopback. Наприклад, --bind lan --port 3000 додає http://localhost:3000 і http://127.0.0.1:3000 до перевірки конфігурації під час виконання. Явно додайте всі джерела віддалених браузерів, наприклад URL-адреси HTTPS-проксі, до gateway.controlUi.allowedOrigins.

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

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

gateway status --deep призначено для додаткового виявлення служб (LaunchDaemons/системних модулів systemd/schtasks), а не для поглибленої перевірки стану RPC.

​
Кілька Gateway (на одному хості)

У більшості інсталяцій слід запускати один Gateway на машину. Один Gateway може обслуговувати кілька агентів і каналів. Кілька Gateway потрібні лише для навмисної ізоляції або резервного бота. Корисні перевірки:
Очікувана поведінка:
  • gateway status --deep може повідомити про Other gateway-like services detected (best effort) і вивести підказки щодо очищення, якщо залишилися застарілі інсталяції launchd/systemd/schtasks.
  • gateway probe може попередити про multiple reachable gateway identities, коли відповідають різні Gateway або коли OpenClaw не може підтвердити, що доступні цілі є тим самим Gateway. SSH-тунель, URL-адреса проксі або налаштована віддалена URL-адреса до того самого Gateway — це один Gateway із кількома транспортами, навіть якщо порти транспортів відрізняються.
  • Якщо це зроблено навмисно, ізолюйте порти, конфігурацію/стан і кореневі каталоги робочих просторів для кожного Gateway.
Контрольний список для кожного екземпляра:
  • Унікальний gateway.port
  • Унікальний OPENCLAW_CONFIG_PATH
  • Унікальний OPENCLAW_STATE_DIR
  • Унікальний agents.defaults.workspace
Приклад:
Докладне налаштування: /gateway/multiple-gateways.

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

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

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

Для надійності на рівні виробничого середовища використовуйте запуск під наглядом.
Використовуйте 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 перевіряє та виправляє розбіжності в конфігурації служби.
У разі помилок неприпустимої конфігурації процес завершується з кодом 78. Модулі systemd у Linux використовують RestartPreventExitStatus=78, щоб припинити повторні запуски, доки конфігурацію не буде виправлено. launchd і планувальник завдань Windows не мають еквівалентного правила зупинки для окремого коду завершення, тому Gateway також зберігає історію швидких некоректних запусків і пригнічує автоматичний запуск облікових записів каналів/провайдерів після повторних помилок запуску. У цьому безпечному режимі площина керування все одно запускається для перевірки й виправлення, гарячі перезавантаження конфігурації та secrets.reload відмовляються автоматично перезапускати канали, а явний запит оператора channels.start може скасувати це пригнічення.

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

Стандартні значення включають ізольовані стан/конфігурацію та базовий порт Gateway 19001.

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

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

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

​
Працездатність

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

​
Готовність

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

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

​
Поширені ознаки помилок

Повні послідовності діагностики див. у розділі Усунення несправностей Gateway.

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

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

​
Пов’язані матеріали