Gateway operasyon kılavuzu

Bu sayfayı Gateway hizmetinin 1. gün başlatması ve 2. gün operasyonları için kullanın.

5 dakikalık yerel başlatma

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

Çalışma zamanı modeli

• Yönlendirme, denetim düzlemi ve kanal bağlantıları için sürekli açık tek süreç.
• Şunlar için tek çoğullamalı port:
  • WebSocket denetimi/RPC
  • HTTP API’leri, OpenAI uyumlu (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Denetim kullanıcı arayüzü ve hook’lar
• Varsayılan bağlama modu: loopback.
• Kimlik doğrulama varsayılan olarak gereklidir. Paylaşılan gizli bilgi kurulumları gateway.auth.token / gateway.auth.password (veya OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_GATEWAY_PASSWORD) kullanır ve local loopback olmayan ters proxy kurulumları gateway.auth.mode: "trusted-proxy" kullanabilir.

OpenAI uyumlu uç noktalar

OmeniaClaw’ın en yüksek getirili uyumluluk yüzeyi artık şudur:

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

Bu kümenin neden önemli olduğu:

• Çoğu Open WebUI, LobeChat ve LibreChat entegrasyonu önce /v1/models yoklar.
• Birçok RAG ve bellek hattı /v1/embeddings bekler.
• Ajan yerel istemciler giderek daha fazla /v1/responses tercih eder.

Planlama notu:

• /v1/models ajan önceliklidir: OmeniaClaw, OmeniaClaw/default ve OmeniaClaw/<agentId> döndürür.
• OmeniaClaw/default, her zaman yapılandırılmış varsayılan ajana eşlenen kararlı takma addır.
• Bir arka uç sağlayıcı/model geçersiz kılması istediğinizde x-OmeniaClaw-model kullanın; aksi halde seçilen ajanın normal model ve embedding kurulumu denetimde kalır.

Bunların tümü ana Gateway portunda çalışır ve Gateway HTTP API’sinin geri kalanıyla aynı güvenilir operatör kimlik doğrulama sınırını kullanır.

Port ve bağlama önceliği

Kurulu Gateway hizmetleri çözümlenen --port değerini gözetmen metaverisine kaydeder. gateway.port değiştirildikten sonra launchd/systemd/schtasks süreci yeni portta başlatsın diye OmeniaClaw doctor --fix veya OmeniaClaw gateway install --force çalıştırın.

Gateway başlatması, local loopback olmayan bağlamalar için yerel Denetim kullanıcı arayüzü origin’lerini tohumlarken aynı etkin portu ve bağlamayı kullanır. Örneğin, --bind lan --port 3000, çalışma zamanı doğrulaması çalışmadan önce http://localhost:3000 ve http://127.0.0.1:3000 değerlerini tohumlar. HTTPS proxy URL’leri gibi uzak tarayıcı origin’lerini gateway.controlUi.allowedOrigins içine açıkça ekleyin.

Sıcak yeniden yükleme modları

Operatör komut kümesi

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, daha derin bir RPC sağlık yoklaması için değil, ek hizmet keşfi (LaunchDaemons/systemd sistem birimleri/schtasks) içindir.

Birden fazla Gateway (aynı ana makine)

Çoğu kurulum makine başına bir Gateway çalıştırmalıdır. Tek bir Gateway birden fazla ajan ve kanalı barındırabilir.

Yalnızca bilinçli olarak yalıtım veya kurtarma botu istediğinizde birden fazla Gateway gerekir.

Yararlı denetimler:

OmeniaClaw gateway status --deepOmeniaClaw gateway probe

Beklenecekler:

• gateway status --deep, eski launchd/systemd/schtasks kurulumları hâlâ duruyorsa Other gateway-like services detected (best effort) bildirebilir ve temizlik ipuçları yazdırabilir.
• Birden fazla hedef yanıt verdiğinde gateway probe, multiple reachable gateways hakkında uyarabilir.
• Bu bilinçliyse portları, yapılandırma/durumu ve çalışma alanı köklerini Gateway başına yalıtın.

Örnek başına kontrol listesi:

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

Örnek:

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

Ayrıntılı kurulum: /gateway/multiple-gateways.

Uzak erişim

Tercih edilen: Tailscale/VPN. Geri dönüş: SSH tüneli.

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

Ardından istemcileri yerel olarak ws://127.0.0.1:18789 adresine bağlayın.

Bkz.: Uzak Gateway, Kimlik doğrulama, Tailscale.

Gözetim ve hizmet yaşam döngüsü

Üretim benzeri güvenilirlik için gözetimli çalıştırmaları kullanın.

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

Geliştirme profili hızlı yolu

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

Varsayılanlar yalıtılmış durum/yapılandırma ve temel Gateway portu 19001 içerir.

Protokol hızlı başvurusu (operatör görünümü)

• İlk istemci karesi connect olmalıdır.
• Gateway hello-ok anlık görüntüsünü döndürür (presence, health, stateVersion, uptimeMs, sınırlar/politika).
• hello-ok.features.methods / events, çağrılabilir her yardımcı rotanın üretilmiş dökümü değil, temkinli bir keşif listesidir.
• İstekler: req(method, params) → res(ok/payload|error).
• Yaygın olaylar arasında connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, eşleştirme/onay yaşam döngüsü olayları ve shutdown bulunur.

Ajan çalıştırmaları iki aşamalıdır:

1. Anında kabul edildi onayı (status:"accepted")
2. Arada akışla gelen agent olaylarıyla nihai tamamlama yanıtı (status:"ok"|"error").

Tam protokol belgelerine bakın: Gateway Protokolü.

Operasyonel denetimler

Canlılık

• WS açın ve connect gönderin.
• Anlık görüntü içeren hello-ok yanıtı bekleyin.

Hazır olma

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

Boşluk kurtarma

Olaylar yeniden oynatılmaz. Sıra boşluklarında devam etmeden önce durumu yenileyin (health, system-presence).

Yaygın hata imzaları

Tam tanılama merdivenleri için Gateway Sorun Giderme sayfasını kullanın.

Güvenlik garantileri

• Gateway kullanılamadığında Gateway protokol istemcileri hızla başarısız olur (örtük doğrudan kanal yedeği yoktur).
• Geçersiz/bağlanmayan ilk çerçeveler reddedilir ve kapatılır.
• Zarif kapatma, soket kapanmadan önce shutdown olayını yayar.

İlgili:

• Sorun Giderme
• Arka Plan Süreci
• Yapılandırma
• Sağlık
• Doctor
• Kimlik Doğrulama

İlgili

• Yapılandırma
• Gateway sorun giderme
• Uzaktan erişim
• Gizli bilgiler yönetimi