Procedura operacyjna Gateway

Użyj tej strony do uruchomienia usługi Gateway w dniu 1 oraz operacji w dniu 2.

5-minutowe uruchomienie lokalne

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

Model środowiska uruchomieniowego

• Jeden stale działający proces do routingu, płaszczyzny sterowania i połączeń kanałów.
• Pojedynczy multipleksowany port dla:
  • sterowania/RPC przez WebSocket
  • API HTTP zgodnych z OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • interfejsu sterowania i hooków
• Domyślny tryb wiązania: loopback.
• Uwierzytelnianie jest domyślnie wymagane. Konfiguracje ze współdzielonym sekretem używają gateway.auth.token / gateway.auth.password (albo OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_GATEWAY_PASSWORD), a konfiguracje reverse proxy poza loopback mogą używać gateway.auth.mode: "trusted-proxy".

Endpointy zgodne z OpenAI

Najważniejsza powierzchnia zgodności OmeniaClaw to teraz:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Dlaczego ten zestaw ma znaczenie:

• Większość integracji Open WebUI, LobeChat i LibreChat najpierw sprawdza /v1/models.
• Wiele potoków RAG i pamięci oczekuje /v1/embeddings.
• Klienci natywni dla agentów coraz częściej preferują /v1/responses.

Uwaga planistyczna:

• /v1/models jest ukierunkowane na agenty: zwraca OmeniaClaw, OmeniaClaw/default i OmeniaClaw/<agentId>.
• OmeniaClaw/default to stabilny alias, który zawsze mapuje się na skonfigurowanego agenta domyślnego.
• Użyj x-OmeniaClaw-model, gdy chcesz nadpisać dostawcę/model backendu; w przeciwnym razie wybrany agent zachowuje kontrolę nad swoim zwykłym modelem i konfiguracją embeddingów.

Wszystkie te endpointy działają na głównym porcie Gateway i używają tej samej granicy zaufanego uwierzytelniania operatora co reszta API HTTP Gateway.

Priorytet portu i wiązania

Zainstalowane usługi Gateway zapisują rozwiązany --port w metadanych nadzorcy. Po zmianie gateway.port uruchom OmeniaClaw doctor --fix albo OmeniaClaw gateway install --force, aby launchd/systemd/schtasks uruchamiał proces na nowym porcie.

Uruchomienie Gateway używa tego samego efektywnego portu i wiązania, gdy inicjuje lokalne źródła interfejsu sterowania dla wiązań poza loopback. Na przykład --bind lan --port 3000 inicjuje http://localhost:3000 i http://127.0.0.1:3000, zanim zostanie uruchomiona walidacja środowiska uruchomieniowego. Dodaj jawnie wszelkie źródła zdalnych przeglądarek, takie jak adresy URL proxy HTTPS, do gateway.controlUi.allowedOrigins.

Tryby gorącego przeładowania

Zestaw poleceń operatora

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 służy do dodatkowego wykrywania usług (LaunchDaemons/jednostki systemowe systemd/schtasks), a nie do głębszej sondy kondycji RPC.

Wiele Gateway (ten sam host)

Większość instalacji powinna uruchamiać jeden Gateway na maszynę. Pojedynczy Gateway może obsługiwać wiele agentów i kanałów.

Wiele Gateway jest potrzebnych tylko wtedy, gdy celowo chcesz izolacji albo bota ratunkowego.

Przydatne kontrole:

OmeniaClaw gateway status --deepOmeniaClaw gateway probe

Czego oczekiwać:

• gateway status --deep może zgłosić Other gateway-like services detected (best effort) i wypisać wskazówki czyszczenia, gdy przestarzałe instalacje launchd/systemd/schtasks nadal istnieją.
• gateway probe może ostrzec o multiple reachable gateways, gdy odpowiada więcej niż jeden cel.
• Jeśli to celowe, izoluj porty, konfigurację/stan i katalogi główne obszarów roboczych dla każdego Gateway.

Lista kontrolna dla instancji:

• Unikalny gateway.port
• Unikalny OmeniaClaw_CONFIG_PATH
• Unikalny OmeniaClaw_STATE_DIR
• Unikalny agents.defaults.workspace

Przykład:

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

Szczegółowa konfiguracja: /gateway/multiple-gateways.

Dostęp zdalny

Preferowane: Tailscale/VPN. Awaryjnie: tunel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@host

Następnie podłącz klientów lokalnie do ws://127.0.0.1:18789.

Zobacz: Zdalny Gateway, Uwierzytelnianie, Tailscale.

Nadzór i cykl życia usługi

Używaj nadzorowanych uruchomień dla niezawodności zbliżonej do produkcyjnej.

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

Szybka ścieżka profilu deweloperskiego

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --dev status

Wartości domyślne obejmują izolowany stan/konfigurację oraz bazowy port Gateway 19001.

Szybka referencja protokołu (widok operatora)

• Pierwsza ramka klienta musi być connect.
• Gateway zwraca migawkę hello-ok (presence, health, stateVersion, uptimeMs, limity/polityka).
• hello-ok.features.methods / events to konserwatywna lista wykrywania, a nie wygenerowany zrzut każdej możliwej do wywołania trasy pomocniczej.
• Żądania: req(method, params) → res(ok/payload|error).
• Typowe zdarzenia obejmują connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, zdarzenia cyklu życia parowania/zatwierdzania oraz shutdown.

Uruchomienia agentów są dwuetapowe:

1. Natychmiastowe potwierdzenie przyjęcia (status:"accepted")
2. Końcowa odpowiedź zakończenia (status:"ok"|"error"), z przesyłanymi po drodze zdarzeniami agent.

Zobacz pełną dokumentację protokołu: Protokół Gateway.

Kontrole operacyjne

Żywotność

• Otwórz WS i wyślij connect.
• Oczekuj odpowiedzi hello-ok z migawką.

Gotowość

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

Odzyskiwanie po lukach

Zdarzenia nie są odtwarzane. Przy lukach w sekwencji odśwież stan (health, system-presence) przed kontynuacją.

Typowe sygnatury awarii

Pełne ścieżki diagnostyczne znajdziesz w Rozwiązywanie problemów z Gateway.

Gwarancje bezpieczeństwa

• Klienci protokołu Gateway szybko kończą działanie, gdy Gateway jest niedostępny (bez niejawnego przełączania awaryjnego bezpośrednio na kanał).
• Nieprawidłowe pierwsze ramki lub pierwsze ramki bez połączenia są odrzucane i zamykane.
• Łagodne zamknięcie emituje zdarzenie shutdown przed zamknięciem gniazda.

Powiązane:

• Rozwiązywanie problemów
• Proces w tle
• Konfiguracja
• Stan
• Diagnostyka
• Uwierzytelnianie

Powiązane

• Konfiguracja
• Rozwiązywanie problemów z Gateway
• Dostęp zdalny
• Zarządzanie sekretami