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

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.

Глибоке усунення несправностей

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

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

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

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

Контракт SecretRef, поведінка знімка runtime та операції migrate/reload.

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

Точні правила цілі/шляху для secrets apply і поведінка auth-profile лише з посиланнями.

​
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 із read-scope, а не лише доступність.
3

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

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

​
Модель runtime

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

​
Endpoints, сумісні з 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.
  • Agent-native клієнти дедалі частіше віддають перевагу /v1/responses.
Примітка щодо планування:
  • /v1/models орієнтований насамперед на agent: він повертає openclaw, openclaw/default і openclaw/<agentId>.
  • openclaw/default — стабільний псевдонім, який завжди відповідає налаштованому типовому agent.
  • Використовуйте x-openclaw-model, коли потрібне перевизначення backend provider/model; інакше звичайна модель і налаштування embeddings вибраного agent залишаються керівними.
Усе це працює на головному порту Gateway і використовує ту саму довірену межу operator auth, що й решта HTTP API Gateway.

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

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

​
Режими hot reload

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

​
Набір команд operator

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 і channels. Кілька 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 gateways, коли відповідає більше ніж одна ціль.
  • Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного gateway.
Checklist для кожного екземпляра:
  • Унікальний 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 tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Потім підключайте клієнти локально до ws://127.0.0.1:18789.
SSH tunnels не обходять gateway auth. Для shared-secret auth клієнти все одно мають надсилати token/password навіть через tunnel. Для режимів з identity-bearing запит усе одно має відповідати цьому auth path.
Див.: Віддалений Gateway, Автентифікація, Tailscale.

​
Supervision і життєвий цикл служби

Використовуйте supervised запуски для надійності, подібної до production. 
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 із поточної boot session без постійного вимкнення, тож автоматичне відновлення KeepAlive і далі працює після неочікуваних збоїв, а gateway start повторно вмикає його коректно. Щоб постійно пригнітити auto-respawn між перезавантаженнями, передайте --disable: openclaw gateway stop --disable.Мітки LaunchAgent: ai.openclaw.gateway (типово) або ai.openclaw.<profile> (іменований profile). openclaw doctor аудіює та виправляє drift конфігурації служби.

​
Швидкий шлях dev profile

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

​
Короткий довідник протоколу (operator view)

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

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

​
Liveness

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

​
Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Відновлення після розривів

Events не відтворюються повторно. У разі розривів sequence оновіть state (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Конфігурацію встановлено в віддалений режим, або позначка локального режиму відсутня в пошкодженій конфігурації
unauthorized during connectНевідповідність автентифікації між клієнтом і Gateway
Для повних послідовностей діагностики використовуйте усунення несправностей Gateway.

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

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

​
Пов’язане