Операційний посібник Gateway

Скористайтеся цією сторінкою для запуску в перший день і операцій другого дня для служби Gateway.

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Модель 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 у 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

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

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

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

Більшість інсталяцій мають запускати один gateway на машину. Один gateway може обслуговувати кілька agents і channels.

Кілька gateways потрібні лише тоді, коли ви навмисно хочете ізоляції або rescue bot.

Корисні перевірки:

openclaw gateway status --deepopenclaw 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 19001OPENCLAW_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.

Див.: Віддалений Gateway, Автентифікація, Tailscale.

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

Використовуйте supervised запуски для надійності, подібної до production.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

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

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 statusopenclaw channels status --probeopenclaw health

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

Events не відтворюються повторно. У разі розривів sequence оновіть state (health, system-presence) перед продовженням.

Поширені сигнатури збоїв

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

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

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

Пов’язане:

• Усунення несправностей
• Фоновий процес
• Конфігурація
• Стан
• Діагностика
• Автентифікація

Пов’язане

• Конфігурація
• Усунення несправностей Gateway
• Віддалений доступ
• Керування секретами