Gateway runbook
Gateway hizmetinin ilk gün başlatılması ve sonraki operasyonları için bu sayfayı kullanın.Derin sorun giderme
Belirti odaklı tanılama; tam komut sıraları ve log imzalarıyla.
Yapılandırma
Görev odaklı kurulum kılavuzu + tam yapılandırma referansı.
Secrets yönetimi
SecretRef sözleşmesi, çalışma zamanı snapshot davranışı ve migrate/reload işlemleri.
Secrets plan sözleşmesi
Tam
secrets apply hedef/yol kuralları ve yalnızca ref kullanan auth-profile davranışı.5 dakikalık yerel başlangıç
Gateway config reload, etkin config dosyası yolunu izler (profil/durum varsayılanlarından çözülür veya ayarlanmışsa
OPENCLAW_CONFIG_PATH kullanılır).
Varsayılan mod gateway.reload.mode="hybrid" şeklindedir.
İlk başarılı yüklemeden sonra çalışan süreç, etkin bellek içi config snapshot’unu sunar; başarılı bir reload bu snapshot’u atomik olarak değiştirir.Çalışma zamanı modeli
- Yönlendirme, kontrol düzlemi ve kanal bağlantıları için sürekli çalışan tek bir süreç.
- Şunlar için tek, çoklamalı port:
- WebSocket kontrol/RPC
- HTTP API’leri, OpenAI uyumlu (
/v1/models,/v1/embeddings,/v1/chat/completions,/v1/responses,/tools/invoke) - Control UI ve hook’lar
- Varsayılan bind modu:
loopback. - Varsayılan olarak auth gereklidir. Ortak gizli anahtar kullanan kurulumlar
gateway.auth.token/gateway.auth.password(veyaOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD) kullanır; loopback olmayan reverse-proxy kurulumları isegateway.auth.mode: "trusted-proxy"kullanabilir.
OpenAI uyumlu uç noktalar
OpenClaw’un en yüksek etkili uyumluluk yüzeyi artık şudur:GET /v1/modelsGET /v1/models/{id}POST /v1/embeddingsPOST /v1/chat/completionsPOST /v1/responses
- Çoğu Open WebUI, LobeChat ve LibreChat entegrasyonu önce
/v1/modelsyolunu prob eder. - Birçok RAG ve bellek pipeline’ı
/v1/embeddingsbekler. - Aracı odaklı istemciler giderek daha fazla
/v1/responsestercih ediyor.
/v1/modelsönce aracı yaklaşımını benimser:openclaw,openclaw/defaultveopenclaw/<agentId>döndürür.openclaw/default, yapılandırılmış varsayılan aracıya her zaman eşlenen kararlı takma addır.- Bir backend sağlayıcı/model geçersiz kılması istediğinizde
x-openclaw-modelkullanın; aksi takdirde seçili aracının normal model ve embedding kurulumu kontrolü elinde tutar.
Port ve bind önceliği
| Ayar | Çözümleme sırası |
|---|---|
| Gateway port | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| Bind modu | CLI/override → gateway.bind → loopback |
Hot reload modları
gateway.reload.mode | Davranış |
|---|---|
off | Config reload yok |
hot | Yalnızca hot-safe değişiklikleri uygula |
restart | Reload gerektiren değişikliklerde yeniden başlat |
hybrid (varsayılan) | Güvenliyse hot-apply, gerekliyse yeniden başlat |
Operatör komut kümesi
gateway status --deep, daha derin bir RPC sağlık probu için değil, ek hizmet keşfi (LaunchDaemons/systemd system
birimleri/schtasks) içindir.
Birden fazla gateway (aynı host)
Çoğu kurulum makine başına tek bir gateway çalıştırmalıdır. Tek bir gateway birden çok aracı ve kanalı barındırabilir. Yalnızca özellikle yalıtım veya bir kurtarma botu istediğinizde birden fazla gateway gerekir. Yararlı kontroller:gateway status --deep,Other gateway-like services detected (best effort)bildirebilir ve eski launchd/systemd/schtasks kurulumları hâlâ ortadaysa temizleme ipuçları yazdırabilir.gateway probe, birden fazla hedef yanıt verdiğindemultiple reachable gatewaysuyarısı verebilir.- Bu kasıtlıysa, gateway başına portları, config/state alanlarını ve workspace köklerini ayırın.
Uzak erişim
Tercih edilen: Tailscale/VPN. Yedek: SSH tüneli.ws://127.0.0.1:18789 adresine bağlayın.
Bkz.: Uzak Gateway, Kimlik Doğrulama, Tailscale.
Denetim ve hizmet yaşam döngüsü
Üretime benzer güvenilirlik için denetimli çalıştırmalar kullanın.- macOS (launchd)
- Linux (systemd user)
- Windows (native)
- Linux (system service)
ai.openclaw.gateway (varsayılan) veya ai.openclaw.<profile> (adlandırılmış profil) şeklindedir. openclaw doctor, hizmet config kaymasını denetler ve onarır.Tek host üzerinde birden fazla gateway
Çoğu kurulum tek Gateway çalıştırmalıdır. Birden fazlasını yalnızca katı yalıtım/yedeklilik için kullanın (örneğin bir kurtarma profili). Örnek başına kontrol listesi:- Benzersiz
gateway.port - Benzersiz
OPENCLAW_CONFIG_PATH - Benzersiz
OPENCLAW_STATE_DIR - Benzersiz
agents.defaults.workspace
Geliştirme profili hızlı yol
19001 içerir.
Protokol hızlı başvuru (operatör görünümü)
- İlk istemci çerçevesi
connectolmalıdır. - Gateway
hello-oksnapshot’u döndürür (presence,health,stateVersion,uptimeMs, limits/policy). hello-ok.features.methods/events, çağrılabilir her yardımcı rota için üretilmiş bir 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ı veshutdownbulunur.
- Anında kabul onayı (
status:"accepted") - Arada akış hâlindeki
agentolaylarıyla son tamamlama yanıtı (status:"ok"|"error").
Operasyonel kontroller
Liveness
- WS açın ve
connectgönderin. - Snapshot içeren
hello-okyanıtını bekleyin.
Readiness
Gap recovery
Olaylar yeniden oynatılmaz. Sıra boşluklarında, devam etmeden önce durumu yenileyin (health, system-presence).
Yaygın hata imzaları
| İmza | Olası sorun |
|---|---|
refusing to bind gateway ... without auth | Geçerli bir gateway auth yolu olmadan loopback olmayan bind |
another gateway instance is already listening / EADDRINUSE | Port çakışması |
Gateway start blocked: set gateway.mode=local | Config uzak moda ayarlı veya hasarlı bir config içinde local-mode damgası eksik |
unauthorized during connect | İstemci ile gateway arasında auth uyumsuzluğu |
Güvenlik garantileri
- Gateway protokol istemcileri, Gateway kullanılamadığında hızlı başarısız olur (örtük doğrudan kanal yedeğine düşme yok).
- Geçersiz/
connectolmayan ilk çerçeveler reddedilir ve bağlantı kapatılır. - Zarif kapatma, soket kapanmadan önce
shutdownolayı gönderir.
İlgili: