Gateway

• Varsayılan olarak, ~/.openclaw/openclaw.json içinde gateway.mode=local ayarlanmadıkça Gateway başlamayı 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 bozuk veya üzerine yazılmış bir yapılandırma olarak değerlendirin ve yerel modu örtük olarak varsaymak yerine 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 ötesine bağlanma engellenir (güvenlik koruması).
• SIGUSR1, yetkilendirildiğinde süreç içi yeniden başlatmayı tetikler (commands.restart varsayılan olarak etkindir; manuel yeniden başlatmayı engellemek için commands.restart: false ayarlayın, gateway aracı/yapılandırma uygulama/güncelleme ise izinli kalır).
• SIGINT/SIGTERM işleyicileri gateway sürecini durdurur, ancak özel terminal durumunu geri yüklemez. CLI'yi bir TUI veya raw-mode girişle 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, 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, host adları veya ham oturum kimliklerini tutmazlar. Kaydediciyi tamamen devre dışı bırakmak için diagnostics.enabled: false ayarlayın.
• Ölümcül Gateway çıkışlarında, kapanma zaman aşımlarında ve yeniden başlatma başlatma hatalarında, kaydedicinin 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 zamanı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ış cihaz token'ını yeniden kullanırlar, ancak yalnızca durumu denetlemek için yeni bir CLI cihaz kimliği veya salt okunur cihaz eşleme kaydı oluşturmazlar.
• 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 değerini açıkça iletin veya önce gizli kaynak bilgisini çözün.
• Yoklama başarılı olursa, yanlış pozitifleri önlemek için çözümlenmemiş auth-ref uyarıları bastırılır.
• 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 çabayla bir tarama ekler. Birden çok Gateway benzeri hizmet algılandığında, insan çıktısı temizleme ipuçları yazdırır ve çoğu kurulumun makine başına bir Gateway çalıştırması gerektiği konusunda uyarır.
• --deep, hizmet süreci harici bir süpervizör yeniden başlatması için temiz şekilde çıktığında yakın tarihli bir Gateway süpervizör yeniden başlatma devrini de bildirir.
• --deep, yapılandırma doğrulamasını Plugin farkındalığı modunda (pluginValidation: "full") çalıştırır ve yapılandırılmış Plugin manifest uyarılarını (örneğin eksik kanal yapılandırma metaverisi) yüzeye çıkarır; 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 state-dir sapmasını tanılamaya yardımcı olmak için çözümlenmiş dosya günlük yolunu ve CLI-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ı env değerini kullanarak gateway.auth.token SecretRef'lerini çözer (önce hizmet komutu env, sonra süreç env yedeği).
• Token kimlik doğrulaması etkin olarak aktif değilse (açık gateway.auth.mode değeri password/none/trusted-proxy ise ya da mod ayarlanmamışken parolanın kazanabildiği ve hiçbir token adayının kazanamadığı durumda), token sapması denetimleri yapılandırma token çözümlemesini 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 neyi kanıtlayabildiğini bildirir. Bu, 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 gösterir. Bu, tam hata olarak değil düşük kaliteli 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 bir Gateway değil, düşük kaliteli erişilebilirliktir.
• gateway status gibi, probe mevcut önbelleğe alınmış cihaz kimlik doğrulamasını yeniden kullanır ancak ilk kez cihaz kimliği veya eşleme durumu oluşturmaz.
• Çıkış kodu yalnızca yoklanan hiçbir hedef erişilebilir değilse sıfır olmayan değerdir.

Üst düzey:

• ok: en az bir hedef erişilebilir.
• degraded: en az bir hedef bağlantıyı kabul etti ancak tam ayrıntı 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ırayla etkin kazanan olarak ele alınacak en iyi hedef: açık URL, SSH tüneli, yapılandırılmış uzak ve ardından local loopback.
• warnings[]: code, message ve isteğe bağlı targetIds içeren en iyi çabayla uyarı kayıtları.
• network: geçerli yapılandırmadan ve host ağından türetilen local 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ı + düşük kalite sınıflandırmasından sonraki erişilebilirlik.
• rpcOk: tam ayrıntı RPC başarısı.
• scopeLimited: ayrıntı RPC, eksik operator 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 verilmiş kapsamlar.
• capability: o hedef için yüzeye çıkarılan 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: birden fazla hedef erişilebilirdi; bir kurtarma botu gibi izole profilleri kasıtlı olarak çalıştırmıyorsanız bu olağandışıdır.
• 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 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'ta gateway stop varsayılan olarak launchctl bootout kullanır; bu, LaunchAgent'ı kalıcı bir devre dışı bırakma oluşturmadan geçerli önyükleme oturumundan kaldırır — KeepAlive otomatik kurtarması gelecekteki çökmeler için etkin kalır ve gateway start, manuel launchctl enable gerektirmeden temiz şekilde yeniden etkinleştirir. Gateway bir sonraki açık gateway start komutuna kadar yeniden doğmasın diye KeepAlive ve RunAtLoad'u kalıcı olarak bastırmak için --disable iletin; manuel durdurmanın yeniden başlatmalardan veya sistem yeniden başlatmalarından sonra da korunması gerektiğinde bunu kullanın.
• gateway restart --safe, çalışan Gateway'den etkin OpenClaw çalışmalarını ön denetimden geçirmesini ve yanıt teslimi, gömülü çalıştırmalar ve görev çalıştırmaları boşalana kadar yeniden başlatmayı ertelemesini ister. --safe, --force veya --wait ile birleştirilemez.
• 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. Çıplak 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 geçidini atlar; böylece engelleyiciler bildirilse bile Gateway yeniden başlatmayı hemen yayar. Takılmış görev çalıştırma ertelemeleri için operatör kaçış yoludur; --safe gerektirir.
• gateway restart --force, etkin çalışma boşaltmasını atlar ve hemen yeniden başlatır. Operatör listelenen görev engelleyicilerini zaten incelediğinde ve Gateway'i hemen geri istediğinde 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 yazmaz.
• 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 yazmak 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ımsal kimlik doğrulama modunda, yalnızca kabuktaki 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.