Ana içeriğe atla

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Derin sorun giderme

Kesin komut basamakları ve günlük imzalarıyla belirti odaklı tanılama.

Yapılandırma

Görev odaklı kurulum kılavuzu + tam yapılandırma başvurusu.

Gizli bilgiler yönetimi

SecretRef sözleşmesi, çalışma zamanı anlık görüntü davranışı ve migrate/reload işlemleri.

Gizli bilgiler planı sözleşmesi

Kesin secrets apply hedef/yol kuralları ve yalnızca ref auth-profile davranışı.

​
5 dakikalık yerel başlatma

1

Gateway’i başlat

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Hizmet sağlığını doğrula

openclaw gateway status
openclaw status
openclaw logs --follow
Sağlıklı temel durum: Beklediğinizle eşleşen Runtime: running, Connectivity probe: ok ve Capability: .... Yalnızca erişilebilirlik değil, okuma kapsamlı RPC kanıtı gerektiğinde openclaw gateway status --require-rpc kullanın.
3

Kanal hazır olma durumunu doğrula

openclaw channels status --probe
Erişilebilir bir Gateway ile bu, hesap başına canlı kanal yoklamaları ve isteğe bağlı denetimler çalıştırır. Gateway erişilemezse CLI, canlı yoklama çıktısı yerine yalnızca yapılandırmaya dayalı kanal özetlerine geri döner.
Gateway yapılandırma yeniden yüklemesi etkin yapılandırma dosyası yolunu izler (profil/durum varsayılanlarından çözümlenir veya ayarlandığında OPENCLAW_CONFIG_PATH kullanılır). Varsayılan mod gateway.reload.mode="hybrid" değeridir. İlk başarılı yüklemeden sonra çalışan süreç etkin bellek içi yapılandırma anlık görüntüsünü sunar; başarılı yeniden yükleme bu anlık görüntüyü atomik olarak değiştirir.

​
Ç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

AyarÇözümleme sırası
Gateway portu--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bağlama moduCLI/geçersiz kılma → gateway.bind → loopback
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ı

gateway.reload.modeDavranış
offYapılandırma yeniden yüklemesi yok
hotYalnızca sıcak-güvenli değişiklikleri uygula
restartYeniden yükleme gerektiren değişikliklerde yeniden başlat
hybrid (varsayılan)Güvenliyse sıcak uygula, gerektiğinde yeniden başlat

​
Operatör komut kümesi

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw 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 --deep
openclaw 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 19001
OPENCLAW_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.
SSH tünelleri Gateway kimlik doğrulamasını atlatmaz. Paylaşılan gizli bilgi kimlik doğrulaması için istemciler tünel üzerinden bile hâlâ token/password göndermelidir. Kimlik taşıyan modlarda isteğin yine de ilgili kimlik doğrulama yolunu karşılaması gerekir.
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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Yeniden başlatmalar için openclaw gateway restart kullanın. Yeniden başlatma yerine openclaw gateway stop ve openclaw gateway start komutlarını zincirlemeyin.macOS’ta gateway stop varsayılan olarak launchctl bootout kullanır; bu, kalıcı bir devre dışı bırakma yapmadan LaunchAgent’ı geçerli önyükleme oturumundan kaldırır, böylece KeepAlive otomatik kurtarması beklenmeyen çökmelerden sonra hâlâ çalışır ve gateway start temiz biçimde yeniden etkinleştirir. Yeniden başlatmalar arasında otomatik yeniden doğmayı kalıcı olarak bastırmak için --disable geçirin: openclaw gateway stop --disable.LaunchAgent etiketleri ai.openclaw.gateway (varsayılan) veya ai.openclaw.<profile> (adlandırılmış profil) şeklindedir. openclaw doctor hizmet yapılandırması sapmasını denetler ve onarır.

​
Geliştirme profili hızlı yolu

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --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 status
openclaw channels status --probe
openclaw 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ı

İmzaOlası sorun
refusing to bind gateway ... without authGeçerli bir Gateway kimlik doğrulama yolu olmadan loopback dışı bağlama
another gateway instance is already listening / EADDRINUSEBağlantı noktası çakışması
Gateway start blocked: set gateway.mode=localYapılandırma uzak moda ayarlanmış veya hasarlı bir yapılandırmada yerel mod damgası eksik
unauthorized sırasında connectİstemci ile Gateway arasında kimlik doğrulama uyuşmazlığı
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:

​
İlgili