Gateway

• Varsayılan olarak Gateway, ~/.openclaw/openclaw.json içinde gateway.mode=local ayarlı değilse başlatmayı reddeder. Geçici/geliştirme çalıştırmaları için --allow-unconfigured kullanın.
• openclaw onboard --mode local ve openclaw setup komutlarının gateway.mode=local yazması beklenir. Dosya varsa ancak gateway.mode eksikse, bunu yerel modun örtük olarak varsayılması yerine bozuk veya üzerine yazılmış bir yapılandırma olarak değerlendirin ve onarın.
• Dosya varsa ve gateway.mode eksikse Gateway bunu şüpheli yapılandırma hasarı olarak değerlendirir ve sizin için "yereli tahmin etmeyi" reddeder.
• Kimlik doğrulama olmadan loopback dışına bağlama engellenir (güvenlik korkuluğu).
• lan, tailnet ve custom şu anda yalnızca IPv4 BYOH yolları üzerinden çözümlenir.
• Yalnızca IPv6 BYOH bugün bu yolda yerel olarak desteklenmez. Ana makinenin kendisi yalnızca IPv6 ise bir IPv4 sidecar veya proxy kullanın.
• SIGUSR1, yetkilendirildiğinde işlem içi yeniden başlatmayı tetikler (commands.restart varsayılan olarak etkindir; gateway aracı/yapılandırma uygulama/güncelleme izinli kalırken manuel yeniden başlatmayı engellemek için commands.restart: false ayarlayın).
• SIGINT/SIGTERM işleyicileri gateway işlemini durdurur, ancak özel terminal durumunu geri yüklemez. CLI'yi bir TUI veya raw-mode girdisiyle sararsanız çıkmadan önce terminali geri yükleyin.

• Kayıtlar operasyonel meta verileri tutar: olay adları, sayımlar, bayt boyutları, bellek okumaları, kuyruk/oturum durumu, onay id'leri, kanal/plugin adları ve redakte edilmiş oturum özetleri. Sohbet metni, webhook gövdeleri, araç çıktıları, ham istek veya yanıt gövdeleri, token'lar, çerezler, gizli değerler, ana makine adları veya ham oturum id'leri tutmazlar. Kaydediciyi tamamen devre dışı bırakmak için diagnostics.enabled: false ayarlayın.
• Ölümcül Gateway çıkışlarında, kapanış zaman aşımlarında ve yeniden başlatma başlatma hatalarında, kaydedicide olaylar varsa OpenClaw aynı tanılama anlık görüntüsünü ~/.openclaw/logs/stability/openclaw-stability-*.json konumuna yazar. En yeni paketi openclaw gateway stability --bundle latest ile inceleyin; --limit, --type ve --since-seq paket çıktısına da uygulanır.

• gateway status, yerel CLI yapılandırması eksik veya geçersiz olsa bile tanılama için kullanılabilir kalır.
• Varsayılan gateway status, hizmet durumunu, WebSocket bağlantısını ve el sıkışma sırasında görünen kimlik doğrulama yeteneğini kanıtlar. Okuma/yazma/yönetici işlemlerini kanıtlamaz.
• Tanılama yoklamaları, ilk kez cihaz kimlik doğrulaması için değişiklik yapmaz: varsa mevcut önbelleğe alınmış bir cihaz belirtecini yeniden kullanır, ancak yalnızca durumu denetlemek için yeni bir CLI cihaz kimliği veya salt okunur cihaz eşleştirme kaydı oluşturmaz.
• gateway status, mümkün olduğunda yoklama kimlik doğrulaması için yapılandırılmış kimlik doğrulama SecretRef'lerini çözer.
• Bu komut yolunda gerekli bir kimlik doğrulama SecretRef'i çözümlenmemişse, yoklama bağlantısı/kimlik doğrulaması başarısız olduğunda gateway status --json, rpc.authWarning bildirir; --token/--password açıkça geçirin veya önce gizli kaynak çözümleyin.
• Yoklama başarılı olursa, yanlış pozitiflerden kaçınmak için çözümlenmemiş auth-ref uyarıları bastırılır.
• Yoklama etkinleştirildiğinde, çalışan Gateway bildirirse JSON çıktısı gateway.version içerir; takip eden el sıkışma yoklaması sürüm meta verisi sağlayamazsa --require-rpc, status.runtimeVersion RPC yüküne geri dönebilir.
• Dinleyen bir hizmet yeterli olmadığında ve okuma kapsamlı RPC çağrılarının da sağlıklı olması gerektiğinde betiklerde ve otomasyonda --require-rpc kullanın.
• --deep, ek launchd/systemd/schtasks kurulumları için en iyi çaba taraması ekler. Birden fazla gateway benzeri hizmet algılandığında, insan çıktısı temizlik ipuçları yazdırır ve çoğu kurulumun makine başına bir gateway çalıştırması gerektiği konusunda uyarır.
• --deep, hizmet işlemi harici bir gözetmen yeniden başlatması için temiz şekilde çıktığında yakın tarihli bir Gateway gözetmen yeniden başlatma devrini de bildirir.
• --deep, yapılandırma doğrulamasını plugin farkındalıklı modda (pluginValidation: "full") çalıştırır ve yapılandırılmış plugin manifest uyarılarını (örneğin eksik kanal yapılandırma meta verisi) gösterir; böylece kurulum ve güncelleme smoke denetimleri bunları yakalar. Varsayılan gateway status, plugin doğrulamasını atlayan hızlı salt okunur yolu korur.
• İnsan çıktısı, profil veya durum dizini sapmasını tanılamaya yardımcı olmak için çözümlenen dosya günlük yolunu ve CLI ile hizmet yapılandırma yolları/geçerlilik anlık görüntüsünü içerir.

• Linux systemd kurulumlarında, hizmet kimlik doğrulama sapması denetimleri birimden hem Environment= hem de EnvironmentFile= değerlerini okur (%h, tırnaklı yollar, birden çok dosya ve isteğe bağlı - dosyaları dahil).
• Sapma denetimleri, birleştirilmiş çalışma zamanı ortamını kullanarak gateway.auth.token SecretRef'lerini çözer (önce hizmet komutu ortamı, ardından süreç ortamı geri dönüşü).
• Belirteç kimlik doğrulaması etkin olarak aktif değilse (açık gateway.auth.mode değeri password/none/trusted-proxy ise veya mod ayarlanmamışken parola kazanabiliyor ve hiçbir belirteç adayı kazanamıyorsa), belirteç sapması denetimleri yapılandırma belirteci çözümünü atlar.

• Reachable: yes, en az bir hedefin WebSocket bağlantısını kabul ettiği anlamına gelir.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only, yoklamanın kimlik doğrulama hakkında kanıtlayabildiği şeyi bildirir. Erişilebilirlikten ayrıdır.
• Read probe: ok, okuma kapsamlı ayrıntı RPC çağrılarının (health/status/system-presence/config.get) da başarılı olduğu anlamına gelir.
• Read probe: limited - missing scope: operator.read, bağlantının başarılı olduğunu ancak okuma kapsamlı RPC'nin sınırlı olduğunu belirtir. Bu, tam hata olarak değil bozulmuş erişilebilirlik olarak bildirilir.
• Connect: ok sonrasında Read probe: failed, Gateway'in WebSocket bağlantısını kabul ettiği, ancak takip eden okuma tanılamalarının zaman aşımına uğradığı veya başarısız olduğu anlamına gelir. Bu da erişilemeyen Gateway değil, bozulmuş erişilebilirliktir.
• gateway status gibi, yoklama mevcut önbelleğe alınmış cihaz kimlik doğrulamasını yeniden kullanır ancak ilk kez cihaz kimliği veya eşleştirme durumu oluşturmaz.
• Çıkış kodu yalnızca hiçbir yoklanan hedef erişilebilir olmadığında sıfır olmayan değerdir.

Üst düzey:

• ok: en az bir hedef erişilebilir.
• degraded: en az bir hedef bağlantı kabul etti ancak tam ayrıntılı RPC tanılamalarını tamamlamadı.
• capability: erişilebilir hedefler arasında görülen en iyi yetenek (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope veya unknown).
• primaryTargetId: şu sırada aktif kazanan olarak değerlendirilecek en iyi hedef: açık URL, SSH tüneli, yapılandırılmış uzak, ardından yerel loopback.
• warnings[]: code, message ve isteğe bağlı targetIds içeren en iyi çaba uyarı kayıtları.
• network: geçerli yapılandırma ve ana makine ağından türetilen yerel loopback/tailnet URL ipuçları.
• discovery.timeoutMs ve discovery.count: bu yoklama geçişi için kullanılan gerçek keşif bütçesi/sonuç sayısı.

Hedef başına (targets[].connect):

• ok: bağlantı sonrası erişilebilirlik + bozulmuş sınıflandırması.
• rpcOk: tam ayrıntı RPC başarısı.
• scopeLimited: ayrıntı RPC'si eksik operatör kapsamı nedeniyle başarısız oldu.

Hedef başına (targets[].auth):

• role: varsa hello-ok içinde bildirilen kimlik doğrulama rolü.
• scopes: varsa hello-ok içinde bildirilen verilen kapsamlar.
• capability: o hedef için gösterilen kimlik doğrulama yeteneği sınıflandırması.

• ssh_tunnel_failed: SSH tüneli kurulumu başarısız oldu; komut doğrudan yoklamalara geri döndü.
• multiple_gateways: ayrı gateway kimlikleri erişilebilirdi veya OpenClaw erişilebilir hedeflerin aynı gateway olduğunu kanıtlayamadı. Aynı gateway'e giden SSH tüneli, proxy URL'si veya yapılandırılmış uzak URL bu uyarıyı tetiklemez.
• auth_secretref_unresolved: yapılandırılmış bir kimlik doğrulama SecretRef'i başarısız bir hedef için çözülemedi.
• probe_scope_limited: WebSocket bağlantısı başarılı oldu, ancak okuma yoklaması eksik operator.read nedeniyle sınırlıydı.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Yönetilen bir hizmeti yeniden başlatmak için gateway restart kullanın. Yeniden başlatma yerine gateway stop ve gateway start komutlarını zincirlemeyin.
• macOS'te gateway stop varsayılan olarak launchctl bootout kullanır; bu, LaunchAgent'ı kalıcı bir devre dışı bırakma uygulamadan geçerli önyükleme oturumundan kaldırır — KeepAlive otomatik kurtarma gelecekteki çökmeler için etkin kalır ve gateway start, elle launchctl enable gerektirmeden temiz şekilde yeniden etkinleştirir. Gateway'in bir sonraki açık gateway start komutuna kadar yeniden doğmaması için KeepAlive ve RunAtLoad'u kalıcı olarak bastırmak üzere --disable geçirin; elle durdurmanın yeniden önyüklemelerden veya sistem yeniden başlatmalarından sonra da geçerli kalması gerektiğinde bunu kullanın.
• gateway restart --safe, çalışan Gateway'den etkin işleri ön kontrolden geçirmesini ve etkin işler boşaldıktan sonra birleştirilmiş tek bir yeniden başlatma zamanlamasını ister. Varsayılan güvenli yeniden başlatma, etkin işleri yapılandırılmış gateway.reload.deferralTimeoutMs süresine kadar bekler (varsayılan 5 dakika); bu bütçe dolduğunda yeniden başlatma zorlanır. Asla zorlamayan süresiz bir güvenli bekleme için gateway.reload.deferralTimeoutMs değerini 0 olarak ayarlayın. --safe, --force veya --wait ile birlikte kullanılamaz.
• gateway restart --wait 30s, o yeniden başlatma için yapılandırılmış yeniden başlatma boşaltma bütçesini geçersiz kılar. Birimsiz sayılar milisaniyedir; s, m ve h gibi birimler kabul edilir. --wait 0 süresiz bekler.
• gateway restart --safe --skip-deferral, OpenClaw farkındalıklı güvenli yeniden başlatmayı çalıştırır ancak erteleme kapısını atlar; böylece engelleyiciler bildirildiğinde bile Gateway yeniden başlatmayı hemen yayımlar. Takılı kalmış görev çalıştırma ertelemeleri için operatör kaçış yoludur; --safe gerektirir.
• gateway restart --force, etkin iş boşaltmasını atlar ve hemen yeniden başlatır. Operatör listelenen görev engelleyicilerini zaten incelemişse ve gateway'i hemen geri istiyorsa bunu kullanın.
• Yaşam döngüsü komutları betikleme için --json kabul eder.

• Token kimlik doğrulaması bir token gerektirdiğinde ve gateway.auth.token SecretRef tarafından yönetildiğinde, gateway install SecretRef'in çözümlenebilir olduğunu doğrular ancak çözümlenen token'ı hizmet ortamı meta verilerine kalıcı olarak kaydetmez.
• Token kimlik doğrulaması bir token gerektiriyorsa ve yapılandırılmış token SecretRef'i çözümlenemiyorsa, kurulum yedek düz metni kalıcı olarak kaydetmek yerine kapalı şekilde başarısız olur.
• gateway run üzerinde parola kimlik doğrulaması için satır içi --password yerine OPENCLAW_GATEWAY_PASSWORD, --password-file veya SecretRef destekli gateway.auth.password tercih edin.
• Çıkarımsanan kimlik doğrulama modunda, yalnızca kabukta ayarlı OPENCLAW_GATEWAY_PASSWORD kurulum token gereksinimlerini gevşetmez; yönetilen bir hizmet kurarken kalıcı yapılandırma (gateway.auth.password veya yapılandırma env) kullanın.
• Hem gateway.auth.token hem de gateway.auth.password yapılandırılmışsa ve gateway.auth.mode ayarlanmamışsa, mod açıkça ayarlanana kadar kurulum engellenir.