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

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

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

OmeniaClaw gateway --port 18789# debug/trace mirrored to stdioOmeniaClaw gateway --port 18789 --verbose# force-kill listener on selected port, then startOmeniaClaw gateway --force

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --follow

OmeniaClaw 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 (або OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_GATEWAY_PASSWORD), а reverse-proxy налаштування не для loopback можуть використовувати gateway.auth.mode: "trusted-proxy".

Endpoints, сумісні з OpenAI

Найефективніша поверхня сумісності OmeniaClaw тепер така:

• 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: він повертає OmeniaClaw, OmeniaClaw/default і OmeniaClaw/<agentId>.
• OmeniaClaw/default — стабільний псевдонім, який завжди відповідає налаштованому типовому agent.
• Використовуйте x-OmeniaClaw-model, коли потрібне перевизначення backend provider/model; інакше звичайна модель і налаштування embeddings вибраного agent залишаються керівними.

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

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

Установлені служби gateway записують визначений --port у metadata supervisor. Після зміни gateway.port запустіть OmeniaClaw doctor --fix або OmeniaClaw 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

OmeniaClaw gateway statusOmeniaClaw gateway status --deep   # adds a system-level service scanOmeniaClaw gateway status --jsonOmeniaClaw gateway installOmeniaClaw gateway restartOmeniaClaw gateway stopOmeniaClaw secrets reloadOmeniaClaw logs --followOmeniaClaw doctor

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

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

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

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

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

OmeniaClaw gateway status --deepOmeniaClaw 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
• Унікальний OmeniaClaw_CONFIG_PATH
• Унікальний OmeniaClaw_STATE_DIR
• Унікальний agents.defaults.workspace

Приклад:

OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/a.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-a OmeniaClaw gateway --port 19001OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/b.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-b OmeniaClaw 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.

OmeniaClaw gateway installOmeniaClaw gateway statusOmeniaClaw gateway restartOmeniaClaw gateway stop

OmeniaClaw gateway installsystemctl --user enable --now OmeniaClaw-gateway[-<profile>].serviceOmeniaClaw gateway status

sudo loginctl enable-linger <user>

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

OmeniaClaw gateway installOmeniaClaw gateway status --jsonOmeniaClaw gateway restartOmeniaClaw gateway stop

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

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

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --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

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

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

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

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

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

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

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

Пов’язане:

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

Пов’язане

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