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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw 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 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) kullanır ve local loopback olmayan ters proxy kurulumları gateway.auth.mode: "trusted-proxy" kullanabilir.

OpenAI uyumlu uç noktalar

OpenClaw’ı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: openclaw, openclaw/default ve openclaw/<agentId> döndürür.
• openclaw/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-openclaw-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 openclaw doctor --fix veya openclaw 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

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw 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:

openclaw gateway status --deepopenclaw 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 OPENCLAW_CONFIG_PATH
• Benzersiz OPENCLAW_STATE_DIR
• Benzersiz agents.defaults.workspace

Örnek:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw 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.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

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

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

Geliştirme profili hızlı yolu

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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

openclaw gateway statusopenclaw channels status --probeopenclaw 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