Gateway

• ~/.openclaw/openclaw.json içinde gateway.mode=local ayarlanmadıkça başlatmayı reddeder. Geçici/geliştirme çalıştırmaları için --allow-unconfigured kullanın; bu seçenek, yapılandırmayı yazmadan veya onarmadan korumayı atlar.
• Başlangıçta onarılabilir geçersiz bir yapılandırma bulunursa etkileşimli terminal, openclaw doctor --fix komutunu çalıştırmayı önerir ve onaydan sonra başlatmayı bir kez yeniden dener. Etkileşimsiz çalıştırmalar hiçbir zaman otomatik onarım yapmaz; bunun yerine komutu yazdırır. Onarılan yapılandırma hâlâ geçersizse başlatma durdurulmuş olarak kalır.
• openclaw onboard --mode local ve openclaw setup, gateway.mode=local değerini yazar. Yapılandırma dosyası mevcut ancak gateway.mode eksikse bu durum hasarlı/üzerine yazılmış yapılandırma olarak değerlendirilir ve Gateway sizin için local değerini tahmin etmeyi reddeder — ilk kurulumu yeniden çalıştırın, anahtarı elle ayarlayın veya --allow-unconfigured geçirin.
• Kimlik doğrulama olmadan loopback dışına bağlanma engellenir.
• --bind değerleri lan, tailnet ve custom günümüzde yalnızca IPv4 yolları üzerinden çözümlenir; yalnızca IPv6 kullanan kendi sunucunuzu getirin kurulumlarında Gateway'in önünde bir IPv4 sidecar'ı veya proxy gerekir.
• SIGUSR1, yetkilendirildiğinde süreç içi yeniden başlatmayı tetikler. commands.restart (varsayılan: etkin), dışarıdan gönderilen SIGUSR1 işlemlerini denetler; elle işletim sistemi sinyaliyle yeniden başlatmaları engellemek için bunu false olarak ayarlayın. Agent'a yönelik gateway aracı salt okunurdur; agent'lar yeniden başlatmayı insan onaylı openclaw yetkilendirme aracı üzerinden talep eder.
• SIGINT/SIGTERM süreci durdurur ancak özel terminal durumunu geri yüklemez — CLI'yi bir TUI veya ham mod girişiyle sarmalıyorsanız çıkıştan önce terminali kendiniz geri yükleyin.

• Kayıtlar operasyonel meta verileri tutar: olay adları, sayılar, bayt boyutları, bellek ölçümleri, kuyruk/oturum durumu, onay kimlikleri, kanal/Plugin adları ve sansürlenmiş oturum özetleri. Sohbet metnini, Webhook gövdelerini, araç çıktılarını, ham istek/yanıt gövdelerini, token'ları, çerezleri, gizli değerleri, ana makine adlarını ve ham oturum kimliklerini hariç tutarlar. Kaydediciyi tamamen devre dışı bırakmak için diagnostics.enabled: false ayarını kullanın.
• Ölümcül Gateway çıkışları, kapatma zaman aşımları ve yeniden başlatma başlangıç hataları, kaydedicide olaylar bulunduğunda 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.

• Yerel CLI yapılandırması eksik veya geçersiz olduğunda bile tanılama için kullanılabilir kalır.
• Varsayılan çıktı; okuma/yazma/yönetici işlemlerini değil, hizmet durumunu, WebSocket bağlantısını ve el sıkışma sırasında görülebilen kimlik doğrulama yeteneğini doğrular.
• İlk cihaz kimlik doğrulamasında yoklamalar değişiklik yapmaz: mevcutsa önbelleğe alınmış cihaz token'ını yeniden kullanırlar ancak yalnızca durumu kontrol etmek için asla yeni bir CLI cihaz kimliği veya salt okunur eşleştirme kaydı oluşturmazlar.
• Mümkün olduğunda, yoklama kimlik doğrulaması için yapılandırılmış kimlik doğrulama SecretRef'lerini çözümler. Gerekli bir SecretRef çözümlenmemişse, yoklama bağlantısı/kimlik doğrulaması başarısız olduğunda --json, rpc.authWarning değerini bildirir; --token/--password değerlerini açıkça iletin veya gizli değer kaynağını düzeltin. Yoklama başarılı olduğunda çözümlenmemiş kimlik doğrulama uyarıları bastırılır.
• Çalışan Gateway bildirdiğinde JSON çıktısı gateway.version değerini içerir; el sıkışma yoklaması sürüm meta verilerini sağlayamıyorsa --require-rpc, status.runtimeVersion RPC yüküne geri dönebilir.
• Dinleyen bir hizmet yeterli olmadığında ve okuma kapsamlı RPC'nin de sağlıklı olması gerektiğinde betiklerde/otomasyonda --require-rpc kullanın.
• --deep, ek launchd/systemd/schtasks kurulumlarını tarar; Gateway benzeri birden fazla hizmet bulunduğunda insan tarafından okunabilir çıktı temizleme ipuçlarını yazdırır (genellikle makine başına bir Gateway çalıştırın) ve ilgili olduğunda yakın tarihli bir yönetici yeniden başlatma devrini bildirir.
• --deep, yapılandırma doğrulamasını Plugin'e duyarlı modda (pluginValidation: "full") da çalıştırır ve Plugin manifest uyarılarını (ör. eksik kanal yapılandırması meta verileri) gösterir. Varsayılan gateway status, Plugin doğrulamasını atlayan hızlı salt okunur yolu korur.
• İnsan tarafından okunabilir çıktı, profil veya durum dizini sapmasını tanılamaya yardımcı olmak için çözümlenmiş dosya günlük yolunun yanı sıra CLI ile hizmetin yapılandırma yollarını/geçerliliğini içerir.
• İnsan tarafından okunabilir çıktı, uygulanan sınır ve uyarlamalı türetimiyle birlikte Gateway heap: değerini içerir. JSON çıktısı aynı raporu service.gatewayHeap olarak sunar.

• Hizmet kimlik doğrulama sapması kontrolleri, birimden hem Environment= hem de EnvironmentFile= değerlerini okur (%h, tırnak içine alınmış yollar, birden fazla dosya ve isteğe bağlı - dosyaları dahil).
• gateway.auth.token SecretRef'lerini birleştirilmiş çalışma zamanı ortamını kullanarak çözümler (önce hizmet komutu ortamı, ardından işlem ortamı geri dönüşü).
• Token sapması kontrolleri, token kimlik doğrulaması etkin olarak kullanılmadığında yapılandırma token'ının çözümlenmesini atlar (gateway.auth.mode açıkça password/none/trusted-proxy olduğunda veya parolanın öncelik kazanabildiği ve hiçbir token adayının öncelik kazanamadığı ayarlanmamış modda).

• 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, erişilebilirlikten ayrı olarak yoklamanın kimlik doğrulama hakkında neyi doğrulayabildiğini bildirir.
• 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ğu ancak okuma kapsamlı RPC'nin sınırlı olduğu anlamına gelir. Tam başarısızlık olarak değil, düşürülmüş erişilebilirlik olarak bildirilir.
• Connect: ok sonrasındaki Read probe: failed, WebSocket'in bağlandığı 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şilemezlik değil, düşürülmüş durumdur.
• gateway status gibi, yoklama da mevcut önbelleğe alınmış cihaz kimlik doğrulamasını yeniden kullanır ancak ilk cihaz kimliğini veya eşleştirme durumunu oluşturmaz.
• Çıkış kodu yalnızca yoklanan hedeflerin hiçbirine erişilemediğinde sıfırdan farklıdır.

Üst düzey:

• ok: en az bir hedefe erişilebilir.
• degraded: en az bir hedef bağlantıyı kabul etti ancak tam ayrıntılı RPC tanılamasını tamamlamadı.
• capability: erişilebilir hedeflerde görülen en iyi yetenek (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope veya unknown).
• primaryTargetId: etkin kazanan olarak değerlendirilecek en iyi hedef; sırasıyla: açık URL, SSH tüneli, yapılandırılmış uzak hedef, yerel geri döngü.
• warnings[]: code, message ve isteğe bağlı targetIds içeren, mümkün olan en iyi şekilde oluşturulmuş uyarı kayıtları.
• network: mevcut yapılandırmadan ve ana makine ağından türetilen yerel geri döngü/tailnet URL ipuçları.
• discovery.timeoutMs / discovery.count: bu yoklama geçişinde kullanılan gerçek keşif bütçesi/sonuç sayısı.

Hedef başına (targets[].connect): ok (erişilebilirlik + kısıtlı sınıflandırması), rpcOk (tam ayrıntılı RPC başarısı), scopeLimited (eksik operatör kapsamı nedeniyle ayrıntılı RPC başarısız oldu).

Hedef başına (targets[].auth): kullanılabilir olduğunda hello-ok cinsinden bildirilen role ve scopes ile gösterilen capability 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: farklı gateway kimliklerine erişilebildi veya OpenClaw erişilebilir hedeflerin aynı gateway olduğunu kanıtlayamadı. Aynı gateway'e yönelik bir SSH tüneli, proxy URL'si veya yapılandırılmış uzak URL bunu tetiklemez.
• auth_secretref_unresolved: yapılandırılmış bir kimlik doğrulama SecretRef'i, başarısız bir hedef için çözümlenemedi.
• probe_scope_limited: WebSocket bağlantısı başarılı oldu ancak okuma yoklaması eksik operator.read nedeniyle kısıtlandı.
• local_tls_runtime_unavailable: yerel Gateway TLS etkin ancak OpenClaw yerel sertifika parmak izini yükleyemedi.

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

• gateway start birden çok kez güvenle çalıştırılabilir: yönetilen hizmet zaten çalışıyorsa çalışan işlemi bildirir ve ona dokunmaz. Yüklenmiş ancak durdurulmuş bir hizmet önceden olduğu gibi başlatılır.
• Yönetilen bir hizmeti yeniden başlatmak için gateway restart kullanın. Yeniden başlatmanın yerine gateway stop ve gateway start komutlarını zincirlemeyin.
• Etkileşimsiz bir kabukta gateway stop, --force gerektirir. Etkileşimli terminaller mevcut istemsiz davranışı korur. Otomasyon ve testler için gateway run --dev veya boş bir porta sahip yalıtılmış bir --profile tercih edin.
• macOS'ta gateway stop, varsayılan olarak launchctl bootout kullanır; bu, kalıcı bir devre dışı bırakma oluşturmadan LaunchAgent'ı mevcut önyükleme oturumundan kaldırır. Böylece KeepAlive otomatik kurtarması gelecekteki çökmeler için etkin kalır ve gateway start, elle launchctl enable çalıştırmadan sorunsuz biçimde yeniden etkinleştirir. Gateway'in bir sonraki açık gateway start işlemine kadar yeniden başlatılmaması için KeepAlive ve RunAtLoad'u kalıcı olarak bastırmak üzere --disable iletin; elle durdurmanın yeniden başlatmalardan sonra da korunması gerektiğinde bunu kullanın.
• Gateway yaşam döngüsü değişiklikleri; CLI başlatma, durdurma ve yeniden başlatma işlemleri, güvenli yeniden başlatma istekleri, gözetmen yeniden başlatmaları ve ayrılmış devirler dâhil olmak üzere, mümkün olan en iyi şekilde anahtar-değer denetim kayıtlarını <state-dir>/logs/gateway-restart.log dosyasına ekler.
• Yaşam döngüsü komutları, betiklerde kullanım için --json kabul eder.

• gateway install, yönetilen Gateway hizmeti için yalnızca yığına yönelik bir NODE_OPTIONS değeri yazar. Node bir kapsayıcı veya hizmet sınırı bildirdiğinde kısıtlı belleğin %50'sini, aksi takdirde fiziksel belleğin %50'sini hedefler.
• Nominal hedef aralık 2048–8192 MiB'dir ve buna ek olarak %75 yerel ek kapasite üst sınırı uygulanır. Küçük ana makinelerde bu ek kapasite üst sınırı, uygulanan sınırı nominal 2048 MiB alt sınırının altına düşürebilir.
• Yüklü hizmette zaten saklanan geçerli ve açık bir --max-old-space-size, zorunlu yeniden yüklemeler ve doctor onarımları boyunca korunur. Diğer NODE_OPTIONS bayrakları yönetilen hizmete aktarılmaz.
• Kabuktaki NODE_OPTIONS ortam değeri bu politikayı geçersiz kılmaz. Yüklü değeri incelemek için gateway status veya doctor kullanın; yönetilen yığın ayarı bulunmayan eski hizmet meta verilerini yeniden oluşturmak için openclaw gateway install --force çalıştırın.
• Politika yalnızca yönetilen Gateway hizmeti için geçerlidir. Ön plandaki gateway run, node hizmetleri ve elle yazılmış gözetmen birimleri kendi çalışma zamanı yapılandırmalarını korur.

• Belirteç kimlik doğrulaması bir belirteç 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 belirteci hizmet ortamı meta verilerinde kalıcı hâle getirmez.
• Belirteç kimlik doğrulaması bir belirteç gerektiriyorsa ve yapılandırılmış belirteç SecretRef'i çözümlenemiyorsa yükleme, yedek düz metni kalıcı hâle getirmek yerine güvenli biçimde başarısız olur.
• gateway run üzerindeki 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ımlı kimlik doğrulama modunda yalnızca kabukta bulunan OPENCLAW_GATEWAY_PASSWORD, yükleme belirteci gereksinimlerini gevşetmez; yönetilen bir hizmet yüklerken 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 yükleme engellenir.