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

Використовуйте цю сторінку для старту в день 1 і операцій дня 2 сервісу Gateway.

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

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

openclaw gateway status
openclaw status
openclaw 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.
• Автентифікація потрібна за замовчуванням. Налаштування зі спільним секретом використовують gateway.auth.token / gateway.auth.password (або OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), а non-loopback налаштування reverse-proxy можуть використовувати 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 і memory-конвеєрів очікують /v1/embeddings.
• Agent-native клієнти дедалі частіше віддають перевагу /v1/responses.

Примітка щодо планування:

• /v1/models орієнтований передусім на агентів: він повертає openclaw, openclaw/default і openclaw/<agentId>.
• openclaw/default — стабільний псевдонім, який завжди відповідає налаштованому типовому агенту.
• Використовуйте x-openclaw-model, коли потрібне перевизначення backend provider/model; інакше контроль зберігає звичайна модель і налаштування embedding вибраного агента.

Усе це працює на основному порту Gateway і використовує ту саму довірену межу операторської автентифікації, що й решта HTTP API Gateway.

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

Установлені сервіси gateway записують визначений --port у метадані супервізора. Після зміни gateway.port запустіть openclaw doctor --fix або openclaw gateway install --force, щоб launchd/systemd/schtasks запускали процес на новому порту.

Під час запуску Gateway використовує той самий ефективний порт і прив’язку, коли початково задає локальні origins Control UI для non-loopback прив’язок. Наприклад, --bind lan --port 3000 додає http://localhost:3000 і http://127.0.0.1:3000 до того, як виконується runtime валідація. Додайте будь-які origins віддаленого браузера, як-от HTTPS proxy URLs, до gateway.controlUi.allowedOrigins явно.

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

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

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 може обслуговувати кілька агентів і каналів.

Кілька 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, коли відповідає більше ніж одна ціль.
• Якщо це навмисно, ізолюйте порти, конфігурацію/стан і корені 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.

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

# Нагляд і життєвий цикл сервісу

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

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

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

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

Запуски агентів мають два етапи:

1. Негайне підтвердження прийняття (status:"accepted")
2. Фінальна відповідь завершення (status:"ok"|"error"), зі streamed-подіями agent між ними.

Див. повну документацію протоколу: Протокол Gateway.

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

# Liveness

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

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

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

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

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

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

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

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

Пов’язане:

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

# Пов’язане

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