Komut sıralaması
Şu sırayla çalıştırın:openclaw gateway status;Runtime: running,Connectivity probe: okve birCapability: ...satırı gösterir.openclaw doctor, engelleyici yapılandırma/hizmet sorunu olmadığını bildirir.openclaw channels status --probe, hesap başına canlı aktarım durumunu ve desteklendiği yerlerdeworksveyaaudit okgösterir.
Güncellemeden sonra
Bir güncelleme tamamlandığı hâlde Gateway çalışmıyorsa, kanallar boşsa veya model çağrıları 401 hatalarıyla başarısız oluyorsa kullanın.openclaw status/openclaw status --alliçindeUpdate restart. Bekleyen veya başarısız devirler, çalıştırılacak sonraki komutu içerir.- Kanallar altında
plugin load failed: dependency tree corrupted; run openclaw doctor --fix: Kanal yapılandırması hâlâ mevcuttur ancak kanal yüklenemeden önce Plugin kaydı başarısız olmuştur. - Yeniden kimlik doğrulamasından sonra sağlayıcı 401 hataları:
openclaw doctor --fix, güncelliğini yitirmiş ajan başına OAuth kimlik doğrulama gölgelerini denetler ve eski kopyaları kaldırarak tüm ajanların geçerli paylaşılan profili çözümlemesini sağlar.
Ayrık kurulumlar ve daha yeni yapılandırma koruması
Bir güncellemeden sonra Gateway hizmeti beklenmedik biçimde durduğunda veya günlükler, biropenclaw ikilisinin openclaw.json dosyasına en son yazan sürümden daha eski olduğunu gösterdiğinde kullanın.
OpenClaw, yapılandırma yazma işlemlerini meta.lastTouchedVersion ile damgalar. Salt okunur komutlar daha yeni bir OpenClaw tarafından yazılan yapılandırmayı inceleyebilir ancak işlem ve hizmet değişikliklerinin daha eski bir ikiliden çalıştırılması reddedilir. Engellenen eylemler: Gateway hizmetini başlatma/durdurma/yeniden başlatma/kaldırma, zorunlu hizmet yeniden kurulumu, hizmet modunda Gateway başlatma ve gateway --force bağlantı noktası temizliği.
PATH'i düzeltin
openclaw daha yeni kuruluma çözümlenecek şekilde PATH değişkenini düzeltin, ardından eylemi yeniden çalıştırın.Gateway hizmetini yeniden kurun
Güncelliğini yitirmiş sarmalayıcıları kaldırın
openclaw ikilisine işaret eden güncelliğini yitirmiş sistem paketi veya eski sarmalayıcı girdilerini kaldırın.Geri alma sonrasında protokol uyuşmazlığı
Sürüm düşürme veya geri alma sonrasında günlüklerde sürekliprotocol mismatch yazdırıldığında kullanın. Daha eski bir Gateway çalışmaktadır ancak daha yeni bir yerel istemci işlemi, eski Gateway’in iletişim kuramadığı bir protokol aralığıyla yeniden bağlanmayı sürdürmektedir.
- Gateway günlüklerinde
protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>. openclaw gateway status --deepiçindeEstablished clients:veyaopenclaw doctor --deepiçindeGateway clients: Gateway bağlantı noktasına bağlı etkin TCP istemcileri; işletim sistemi izin verdiğinde PID’ler ve komut satırlarıyla birlikte.- Komut satırı, geri aldığınız daha yeni OpenClaw kurulumuna veya sarmalayıcıya işaret eden bir istemci işlemi.
gateway status --deeptarafından gösterilen güncelliğini yitirmiş OpenClaw istemci işlemini durdurun veya yeniden başlatın.- OpenClaw’ı gömülü olarak kullanan uygulamaları veya sarmalayıcıları yeniden başlatın: yerel panolar, düzenleyiciler, uygulama sunucusu yardımcıları veya uzun süre çalışan
openclaw logs --followkabukları. openclaw gateway status --deepveyaopenclaw doctor --deepkomutunu yeniden çalıştırın ve güncelliğini yitirmiş istemci PID’sinin kaybolduğunu doğrulayın.
Yol dışına çıkma nedeniyle Skill sembolik bağlantısının atlanması
Günlükler şunu içerdiğinde kullanın:~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills veya ~/.openclaw/skills altındaki bir sembolik bağlantı, gerçek hedefi bu kökün dışına çözümleniyorsa hedef açıkça güvenilir olarak işaretlenmediği sürece atlanır.
Bağlantıyı inceleyin:
~, / veya eşitlenmiş bir proje klasörünün tamamı gibi geniş hedefler kullanmayın. allowSymlinkTargets kapsamını, güvenilir SKILL.md dizinlerini içeren gerçek skill köküyle sınırlandırın.
Skill Workshop uygulamasının bu güvenilir sembolik bağlantılı çalışma alanı skill yolları üzerinden de yazması gerekiyorsa skills.workshop.allowSymlinkTargetWrites ayarını etkinleştirin. Salt okunur paylaşılan skill kökleri için devre dışı bırakın.
İlgili:
Uzun bağlam için Anthropic 429 ek kullanım gereksinimi
Günlükler/hatalar şunu içerdiğinde kullanın:HTTP 429: rate_limit_error: Extra usage is required for long context requests.
- Seçilen Anthropic modeli, genel kullanıma sunulmuş 1M destekli bir Claude 4.x modelidir (Opus 4.6/4.7/4.8, Sonnet 4.6) veya model yapılandırması hâlâ eski
params.context1m: truedeğerini taşımaktadır. - Geçerli Anthropic kimlik bilgisi uzun bağlam kullanımı için uygun değildir.
- İstekler yalnızca 1M bağlam yoluna ihtiyaç duyan uzun oturumlarda/model çalıştırmalarında başarısız olur.
Standart bir bağlam penceresi kullanın
context1m değerini kaldırın.Uygun bir kimlik bilgisi kullanın
Yedek modelleri yapılandırın
Yukarı akış 403 engellenen yanıtları
Bir yukarı akış LLM sağlayıcısı,Your request was blocked gibi genel bir 403 döndürdüğünde kullanın.
Bunun her zaman bir OpenClaw yapılandırma sorunu olduğunu varsaymayın. Yanıt, OpenAI uyumlu bir uç noktanın önündeki CDN, WAF, bot yönetimi kuralı veya ters proxy gibi bir yukarı akış güvenlik katmanından gelebilir.
- Aynı sağlayıcı altındaki birden fazla modelin aynı şekilde başarısız olması.
- Normal bir sağlayıcı API hatası yerine HTML veya genel güvenlik metni.
- Aynı istek zamanına ait sağlayıcı tarafı güvenlik olayları.
- Küçük bir doğrudan
curlyoklaması başarılı olurken normal SDK biçimli isteklerin başarısız olması.
Yerel OpenAI uyumlu arka uç doğrudan yoklamaları geçiyor ancak ajan çalıştırmaları başarısız oluyor
Şu durumlarda kullanın:curl ... /v1/modelsçalışır.- Küçük doğrudan
/v1/chat/completionsçağrıları çalışır. - OpenClaw model çalıştırmaları yalnızca normal ajan turlarında başarısız olur.
- Küçük doğrudan çağrılar başarılı olur ancak OpenClaw çalıştırmaları yalnızca daha büyük istemlerde başarısız olur.
- Doğrudan
/v1/chat/completionsaynı yalın model kimliğiyle çalışmasına rağmenmodel_not_foundveya 404 hataları. messages[].contentöğesinin bir dize beklediğine ilişkin arka uç hataları.- OpenAI uyumlu yerel bir arka uçla aralıklı
incomplete turn detected ... stopReason=stop payloads=0uyarıları. - Yalnızca daha yüksek istem token sayılarında veya tam ajan çalışma zamanı istemlerinde ortaya çıkan arka uç çökmeleri.
Yaygın belirtiler
Yaygın belirtiler
- Yerel bir MLX/vLLM tarzı sunucuyla
model_not_found:baseUrlöğesinin/v1içerdiğini,/v1/chat/completionsarka uçları içinapideğerinin"openai-completions"olduğunu vemodels.providers.<provider>.models[].iddeğerinin yalın, sağlayıcıya yerel kimlik olduğunu doğrulayın. Sağlayıcı önekiyle bir kez seçin; örneğinmlx/mlx-community/Qwen3-30B-A3B-6bit. Katalog girdisinimlx-community/Qwen3-30B-A3B-6bitolarak bırakın. messages[...].content: invalid type: sequence, expected a string: Arka uç, yapılandırılmış Chat Completions içerik bölümlerini reddeder. Düzeltme:models.providers.<provider>.models[].compat.requiresStringContent: trueayarını belirleyin.validation.keysveya["role","content"]gibi izin verilen ileti anahtarları: Arka uç, Chat Completions iletilerindeki OpenAI tarzı yeniden oynatma meta verilerini reddeder. Düzeltme:models.providers.<provider>.models[].compat.strictMessageKeys: trueayarını belirleyin.incomplete turn detected ... stopReason=stop payloads=0: Arka uç Chat Completions isteğini tamamladı ancak bu tur için kullanıcıya görünür bir asistan metni döndürmedi. OpenClaw, yeniden oynatılması güvenli olan boş OpenAI uyumlu turları bir kez yeniden dener; kalıcı hatalar genellikle arka ucun boş/metin dışı içerik yaydığı veya nihai yanıt metnini bastırdığı anlamına gelir.- Küçük doğrudan istekler başarılı olur ancak OpenClaw ajan çalıştırmaları arka uç/model çökmeleriyle başarısız olur (örneğin bazı
inferrsderlemelerinde Gemma): OpenClaw aktarımı büyük olasılıkla zaten doğrudur; arka uç, daha büyük ajan çalışma zamanı istem biçiminde başarısız olmaktadır. - Araçlar devre dışı bırakıldıktan sonra hatalar azalır ancak kaybolmaz: Araç şemaları baskının bir parçasıdır ancak kalan sorun hâlâ yukarı akış model/sunucu kapasitesi veya bir arka uç hatasıdır.
Düzeltme seçenekleri
Düzeltme seçenekleri
- Yalnızca dize destekleyen Chat Completions arka uçları için
compat.requiresStringContent: trueayarını belirleyin. - Her iletide yalnızca
rolevecontentkabul eden katı Chat Completions arka uçları içincompat.strictMessageKeys: trueayarını belirleyin. - OpenClaw’ın araç şeması yüzeyini güvenilir biçimde işleyemeyen modeller/arka uçlar için
compat.supportsTools: falseayarını belirleyin. - Mümkün olduğunda istem baskısını azaltın: daha küçük çalışma alanı önyüklemesi, daha kısa oturum geçmişi, daha hafif bir yerel model veya daha güçlü uzun bağlam desteğine sahip bir arka uç.
- Küçük doğrudan istekler başarılı olmaya devam ederken OpenClaw ajan turları hâlâ arka uç içinde çöküyorsa bunu bir yukarı akış sunucu/model sınırlaması olarak değerlendirin ve kabul edilen yük biçimiyle birlikte orada bir yeniden üretim kaydı açın.
Yanıt yok
Kanallar çalışıyor ancak hiçbir şey yanıt vermiyorsa herhangi bir şeyi yeniden bağlamadan önce yönlendirmeyi ve politikayı kontrol edin.- DM gönderenler için eşleştirme bekliyor.
- Grup bahsetme kısıtlaması (
requireMention,mentionPatterns). - Kanal/grup izin listesi uyuşmazlıkları.
drop guild message (mention required→ bahsedilene kadar grup mesajı yok sayılır.pairing request→ gönderenin onaylanması gerekir.blocked/allowlist→ gönderen/kanal politika tarafından filtrelendi.
Pano kontrol arayüzü bağlantısı
Pano/kontrol arayüzü bağlanmıyorsa URL’yi, kimlik doğrulama modunu ve güvenli bağlam varsayımlarını doğrulayın.- Doğru yoklama URL’si ve pano URL’si.
- İstemci ile Gateway arasında kimlik doğrulama modu/token uyuşmazlığı.
- Cihaz kimliğinin gerekli olduğu yerde HTTP kullanımı.
127.0.0.1:18789 hedefine bağlanamıyorsa önce yerel Gateway hizmetini kurtarın ve panoyu sunduğunu doğrulayın:
curl OpenClaw HTML’si döndürüyorsa Gateway çalışıyordur ve kalan sorun muhtemelen tarayıcı önbelleği, eski bir derin bağlantı veya güncelliğini yitirmiş sekme durumudur. Doğrudan http://127.0.0.1:18789 adresini açın ve panodan ilerleyin. Yeniden başlatma sonrasında hizmet çalışmaya devam etmiyorsa openclaw gateway start komutunu çalıştırın ve openclaw gateway status değerini yeniden kontrol edin.
Bağlantı / kimlik doğrulama belirtileri
Bağlantı / kimlik doğrulama belirtileri
device identity required→ güvenli olmayan bağlam veya eksik cihaz kimlik doğrulaması.origin not allowed→ tarayıcıOrigin,gateway.controlUi.allowedOriginsiçinde değil (veya açık bir izin listesi olmadan geri döngü olmayan bir tarayıcı kaynağından bağlanıyorsunuz).device nonce required/device nonce mismatch→ istemci, sorgulamaya dayalı cihaz kimlik doğrulama akışını tamamlamıyor (connect.challenge+device.nonce).device signature invalid/device signature expired→ istemci, mevcut el sıkışma için yanlış yükü (veya güncelliğini yitirmiş zaman damgasını) imzaladı.AUTH_TOKEN_MISMATCHilecanRetryWithDeviceToken=true→ istemci, önbelleğe alınmış cihaz token’ıyla bir güvenilir yeniden deneme gerçekleştirebilir.- Bu önbelleğe alınmış token’la yeniden deneme, eşleştirilmiş cihaz token’ıyla saklanan önbellekteki kapsam kümesini yeniden kullanır. Açık
deviceToken/ açıkscopesçağıranları ise talep ettikleri kapsam kümesini korur. AUTH_SCOPE_MISMATCH→ cihaz token’ı tanındı ancak onaylanan kapsamları bu bağlantı isteğini kapsamıyor; paylaşılan bir Gateway token’ını döndürmek yerine yeniden eşleştirin veya istenen kapsam sözleşmesini onaylayın.- Bu yeniden deneme yolunun dışında bağlantı kimlik doğrulama önceliği şöyledir: önce açık paylaşılan token/parola, ardından açık
deviceToken, sonra saklanan cihaz token’ı ve son olarak önyükleme token’ı. - Asenkron Tailscale Serve Kontrol Arayüzü yolunda aynı
{scope, ip}için başarısız girişimler, sınırlayıcı hatayı kaydetmeden önce sıraya alınır. Bu nedenle aynı istemciden eş zamanlı iki hatalı yeniden denemenin ikinci girişiminde iki düz uyuşmazlık yerineretry latergörülebilir. - Tarayıcı kaynaklı bir geri döngü istemcisinden
too many failed authentication attempts (retry later)→ aynı normalleştirilmişOriginkaynağından yinelenen hatalı girişimler geçici olarak engellenir; başka bir localhost kaynağı ayrı bir dilim kullanır. - Bu yeniden denemeden sonra yinelenen
unauthorized→ paylaşılan token/cihaz token’ı sapması; token yapılandırmasını yenileyin ve gerekirse cihaz token’ını yeniden onaylayın/döndürün. gateway connect failed:→ yanlış ana makine/port/URL hedefi.
Kimlik doğrulama ayrıntı kodları hızlı haritası
Sonraki işlemi seçmek için başarısızconnect yanıtındaki error.details.code değerini kullanın:
scope-upgrade ile başarısız oluyorsa çağıranın client.id: "gateway-client" ve client.mode: "backend" kullandığını, ayrıca açık bir deviceIdentity veya cihaz token’ını zorlamadığını doğrulayın.connect.challenge için bekleyin
connect.challenge değerini bekler.Yükü imzalayın
Cihaz nonce değerini gönderin
connect.params.device.nonce değerini gönderir.openclaw devices rotate / revoke / remove beklenmedik şekilde reddedilirse:
- Eşleştirilmiş cihaz token’ı oturumları, çağıranda ayrıca
operator.adminbulunmadığı sürece yalnızca kendi cihazlarını yönetebilir. openclaw devices rotate --scope ...yalnızca çağıran oturumunun zaten sahip olduğu operatör kapsamlarını isteyebilir.
- Yapılandırma (Gateway kimlik doğrulama modları)
- Kontrol Arayüzü
- Cihazlar
- Uzaktan erişim
- Güvenilir proxy kimlik doğrulaması
Gateway hizmeti çalışmıyor
Hizmet kurulu olduğu hâlde süreç çalışmaya devam etmiyorsa kullanın.- Çıkış ipuçlarıyla
Runtime: stopped. - Hizmet yapılandırması uyuşmazlığı (
Config (cli)ileConfig (service)). - Port/dinleyici çakışmaları.
--deepkullanıldığında ek launchd/systemd/schtasks kurulumları.Other gateway-like services detected (best effort)temizleme ipuçları.
Yaygın belirtiler
Yaygın belirtiler
Gateway start blocked: set gateway.mode=localveyaexisting config is missing gateway.mode→ yerel Gateway modu etkin değil ya da yapılandırma dosyasının üzerine yazılmış vegateway.modekaybolmuş. Düzeltme: yapılandırmanızdagateway.mode="local"değerini ayarlayın veya beklenen yerel mod yapılandırmasını yeniden damgalamak içinopenclaw onboard --mode local/openclaw setupkomutunu yeniden çalıştırın. OpenClaw’ı Podman aracılığıyla çalıştırıyorsanız varsayılan yapılandırma yolu~/.openclaw/openclaw.jsonşeklindedir.refusing to bind gateway ... without auth→ geçerli bir Gateway kimlik doğrulama yolu (token/parola veya yapılandırıldığı yerde güvenilir proxy) olmadan geri döngü dışı bağlama.another gateway instance is already listening/EADDRINUSE→ port çakışması.Other gateway-like services detected (best effort)→ güncelliğini yitirmiş veya paralel launchd/systemd/schtasks birimleri mevcut. Çoğu kurulumda makine başına bir Gateway tutulmalıdır; birden fazlası gerekiyorsa portları, yapılandırmayı, durumu ve çalışma alanını birbirinden ayırın. Bkz. /gateway#multiple-gateways-same-host.- Doctor’dan
System-level OpenClaw gateway service detected→ kullanıcı düzeyindeki hizmet eksikken bir systemd sistem birimi mevcut. Doctor’ın bir kullanıcı hizmeti kurmasına izin vermeden önce kopyayı kaldırın veya devre dışı bırakın ya da amaçlanan denetleyici sistem birimiyseOPENCLAW_SERVICE_REPAIR_POLICY=externaldeğerini ayarlayın. Gateway service port does not match current gateway config→ kurulu denetleyici hâlâ eski--portdeğerini sabitliyor.openclaw doctor --fixveyaopenclaw gateway install --forcekomutunu çalıştırın, ardından Gateway hizmetini yeniden başlatın.
macOS Gateway sessizce yanıt vermeyi durduruyor, ardından panoya dokunduğunuzda devam ediyor
Kanalların (Telegram, WhatsApp vb.) bir macOS ana bilgisayarında zaman zaman dakikalarca veya saatlerce sessiz kaldığı ve Control UI’ı açtığınızda, SSH ile bağlandığınızda ya da ana bilgisayarla başka bir şekilde etkileşime geçtiğinizde gateway’in geri geldiği durumlarda kullanın. Genellikleopenclaw status içinde belirgin bir belirti olmaz; çünkü siz kontrol edene kadar gateway yeniden çalışır duruma gelmiş olur.
~/.openclaw/logs/stability/içindeerror.codedeğeriENETDOWN,ENETUNREACH,EHOSTUNREACHveyaECONNREFUSEDgibi geçici bir ağ koduna ayarlanmış bir ya da daha fazla*-uncaught_exception.jsonpaketi.- Çökme zaman damgalarıyla örtüşen
Entering Sleep state due to 'Maintenance Sleep'veyaen0 driver is slow (msg: WillChangeState to 0)gibipmset -g logsatırları. Power Nap / Maintenance Sleep, Wi-Fi sürücüsünü kısa süreliğine 0 durumuna geçirir; bu aralığa denk gelen herhangi bir gidenconnect(), normalde tam ağ bağlantısına sahip bir ana bilgisayarda bileENETDOWNile başarısız olabilir. - Özellikle çökme ile sonraki başlatma arasındaki boşluk saniyeler yerine yaklaşık bir saat olduğunda, çıkış koduyla birlikte birden çok yakın tarihli
runsiçerenstate = not runningdeğerini gösterenlaunchctl printçıktısı. macOS launchd, art arda çökmelerden sonra belgelenmemiş bir yeniden oluşturma koruma eşiği uygular; bu eşik, etkileşimli oturum açma, pano bağlantısı veyalaunchctl kickstartgibi harici bir tetikleyici onu yeniden etkinleştirene kadarKeepAlive=trueayarının dikkate alınmasını durdurabilir.
error.codedeğeriENETDOWNveya benzer bir kod olan ve çağrı yığını NodenetlookupAndConnect/Socket.connectiçine işaret eden bir kararlılık paketi. OpenClaw2026.5.26ve sonraki sürümler bunları zararsız geçici ağ hataları olarak sınıflandırır; böylece artık üst düzey yakalanmamış işleyiciye yayılmazlar. Daha eski bir sürüm kullanıyorsanız önce yükseltin.- Control UI’a veya ana bilgisayara SSH ile bağlandığınız anda sona eren uzun sessiz dönemler: launchd’ın yeniden oluşturma eşiğini yeniden etkinleştiren, panonun gateway üzerinde yaptığı herhangi bir işlem değil, kullanıcının görebildiği etkinliktir.
~/Library/Logs/openclaw/gateway.logiçinde karşılık gelen birreceived SIG*; shutting downsatırı olmadan gün boyunca artanrunssayısı: düzgün kapatmalar bir sinyali günlüğe kaydeder; geçici çökmeler kaydetmez.
-
2026.5.26öncesi bir sürüm kullanıyorsanız gateway’i yükseltin. Yükseltmeden sonra gelecektekiENETDOWNhataları işlemi sonlandırmak yerine uyarı olarak günlüğe kaydedilir. -
Her zaman açık sunucular olarak çalışması amaçlanan Mac mini / masaüstü ana bilgisayarlarda bakım uykusu etkinliğini azaltın:
Bu, altta yatan sürücü dalgalanmasını önemli ölçüde azaltır ancak tamamen ortadan kaldırmaz. Sistem, bu bayraklardan bağımsız olarak TCP keepalive ve mDNS bakımı için bazı bakım uykularını yine de gerçekleştirebilir.
-
launchd tarafından beklemeye alınan gelecekteki bir art arda çökme durumunun hızla yakalanması için bir canlılık izleyicisi ekleyin:
Amaç, yeniden oluşturma eşiğini harici olarak yeniden etkinleştirmektir; art arda çökmelerden sonra macOS’te yalnızca
KeepAlive=trueyeterli değildir.
Yinelenen gateway/node LaunchAgent’larıyla macOS launchd gözetmen döngüsü
Bir macOS kurulumu birkaç saniyede bir yeniden başlatılmaya devam ettiğinde,openclaw
durum denetimleri sağlıklı ve kullanılamaz durumları arasında gidip geldiğinde ve hizmet
çalışıyor görünmesine rağmen kanal gönderimi durduğunda bunu kullanın.
Bu durum, hem ai.openclaw.gateway hem de
ai.openclaw.node LaunchAgent’larının etkin olduğu ve her birinin
OPENCLAW_LAUNCHD_LABEL eklediği eski kurulumlarda gözlemlenmiştir. Bu durumda OpenClaw, launchd
gözetimini algılayabilir, yeniden başlatmayı launchd’a geri devretmeye çalışabilir ve tek bir kararlı
gateway işlemi yerine hızlı bir EADDRINUSE/yeniden oluşturma döngüsüne girebilir.
- 30 saniyelik örnek boyunca tek bir kararlı işlem yerine birden fazla gateway PID’si.
gateway.logiçindeEADDRINUSE,another gateway instance is already listeningveya yinelenen yeniden başlatma/devir satırları.- Yalnızca tek bir yönetilen gateway hizmeti çalıştırması gereken bir
ana bilgisayarda hem
~/Library/LaunchAgents/ai.openclaw.gateway.plisthem de~/Library/LaunchAgents/ai.openclaw.node.plistöğesinin aynı anda yüklenmiş olması.
-
Bu ana bilgisayarda yalnızca Gateway hizmetinin çalışması gerekiyorsa yönetilen node
hizmetini OpenClaw aracılığıyla kaldırın. Uzak node özellikleri için node
hizmetini aktif olarak kullanıyorsanız bu adımı atlayın; hizmetin kaldırılması bu ana
bilgisayardaki söz konusu özellikleri durdurur:
-
OpenClaw’ı başlatmadan önce devralınan launchd
işaretçilerini temizleyen kalıcı bir Gateway sarmalayıcısı kurun. Desteklenen
--wrapperseçeneğini kullanın;~/.openclaw/service-env/altındaki oluşturulmuş dosyayı düzenlemeyin; çünkü hizmetin yeniden kurulması, güncellenmesi ve Doctor onarımı bu dosyayı yeniden oluşturur:gateway install, zorunlu yeniden kurulumlar, güncellemeler ve doctor onarımları boyunca sarmalayıcı yolunu korur. -
Gateway’in yalnızca dinlemede değil, kararlı ve RPC hizmeti veriyor olduğunu doğrulayın:
PID örneği, sürekli değişen bir PID kümesi yerine tek bir kararlı süreç göstermeli ve gelen kanal dağıtımı devam etmelidir.
-
Temel ikili LaunchAgent döngüsünün düzeltildiği bir sürüme yükselttikten
sonra geçici çözümü kaldırın ve normal yönetilen hizmeti yeniden kurun:
Gateway, yüksek bellek kullanımı sırasında kapanıyor
Gateway yük altında kaybolduğunda, gözetmen OOM tarzı bir yeniden başlatma bildirdiğinde veya günlüklerdecritical memory pressure bundle written ifadesi geçtiğinde kullanın.
- En son kararlılık paketinde
Reason: diagnostic.memory.pressure.critical. critical/rss_threshold,critical/heap_thresholdveyacritical/rss_growthile birlikteMemory pressure:.- Yığın sınırına yakın
V8 heap:değerleri. agents/<agent>/sessions/<session>.jsonlveyasessions/<session>.jsonlgibiLargest session files:girdileri.- Gateway bir kapsayıcı veya bellek sınırlamalı hizmet içinde çalıştığında Linux cgroup bellek sayaçları.
critical memory pressure bundle written, yeniden başlatmadan kısa süre önce görünür → OpenClaw, OOM öncesi bir kararlılık paketi yakalamıştır. Paketiopenclaw gateway stability --bundle latestile inceleyin.memory pressure: level=critical, Gateway günlüklerinde görünür → OpenClaw kritik bellek baskısı algılamış ve mevcut süreç içi bellek bilgilerini kaydetmiştir.Largest session files:, redakte edilmiş çok büyük bir transkript yolunu gösterir → yeniden başlatmadan önce saklanan oturum geçmişini azaltın, oturum büyümesini inceleyin veya eski transkriptleri etkin depodan çıkarın.V8 heap:kullanılan baytlar yığın sınırına yakındır → önce istem/oturum baskısını düşürün veya eşzamanlı işleri azaltın. Yönetilen bir hizmet içinopenclaw gateway statusiçindekiGateway heap:değerini inceleyin;not setdiyorsa eski hizmet meta verileriniopenclaw gateway install --forceile yeniden oluşturun. Ortam kabuğundakiNODE_OPTIONSkasıtlı olarak yok sayılır. Açık bir gözetmen düzeyi yığın geçersiz kılmasını yalnızca sürekli iş yükünü doğruladıktan ve yeterli yerel bellek payı bıraktıktan sonra kullanın.Memory pressure: critical/rss_growth→ bellek, tek bir örnekleme aralığında hızla büyümüştür. Büyük bir içe aktarma, kontrolden çıkan araç çıktısı, yinelenen yeniden denemeler veya kuyruğa alınmış bir agent işi grubu için en son günlükleri kontrol edin.- Günlüklerde kritik bellek baskısı görünüyor ancak paket yok → mevcut operasyonel kanıtları elde etmek için olaydan sonra
openclaw gateway diagnostics exportyakalayın.
Gateway geçersiz yapılandırmayı reddetti
Gateway başlatma işlemiInvalid config ile başarısız olduğunda veya çalışırken yeniden yükleme günlükleri geçersiz bir düzenlemenin atlandığını belirttiğinde kullanın.
Invalid config at ...config reload skipped (invalid config): ...Config write rejected: ...- Etkin yapılandırmanın yanında zaman damgalı bir
openclaw.json.rejected.*dosyası. doctor --fixbozuk bir doğrudan düzenlemeyi onardıysa zaman damgalı biropenclaw.json.clobbered.*dosyası.- OpenClaw, her yapılandırma yolu için en son 32
.clobbered.*dosyasını tutar ve daha eskilerini dönüşümlü olarak kaldırır.
Ne oldu
Ne oldu
- Yapılandırma; başlatma, çalışırken yeniden yükleme veya OpenClaw’a ait bir yazma işlemi sırasında doğrulanamadı.
- Gateway başlatma işlemi,
openclaw.jsondosyasını yeniden yazmak yerine güvenli biçimde başarısız olur. - Çalışırken yeniden yükleme, geçersiz harici düzenlemeleri atlar ve mevcut çalışma zamanı yapılandırmasını etkin tutar.
- OpenClaw’a ait yazma işlemleri, geçersiz/yıkıcı yükleri kaydetmeden önce reddeder ve
.rejected.*kaydeder. - Onarımın sahibi
openclaw doctor --fixolur. Reddedilen yükü.clobbered.*olarak korurken JSON olmayan önekleri kaldırabilir veya bilinen son sağlam kopyayı geri yükleyebilir. - Tek bir yapılandırma yolu için çok sayıda onarım gerçekleştiğinde OpenClaw, en yeni onarılmış yükün erişilebilir kalması için eski
.clobbered.*dosyalarını dönüşümlü olarak kaldırır.
İncele ve onar
İncele ve onar
Yaygın belirtiler
Yaygın belirtiler
.clobbered.*mevcut → doctor, etkin yapılandırmayı onarırken bozuk bir harici düzenlemeyi korudu..rejected.*mevcut → OpenClaw tarafından yönetilen bir yapılandırma yazma işlemi, kaydetmeden önce şema veya üzerine yazma denetimlerinde başarısız oldu.Config write rejected:→ yazma işlemi gerekli yapıyı kaldırmaya, dosyayı önemli ölçüde küçültmeye veya geçersiz yapılandırmayı kalıcı hâle getirmeye çalıştı.config reload skipped (invalid config):→ doğrudan düzenleme doğrulamadan geçemedi ve çalışan Gateway tarafından yok sayıldı.Invalid config at ...→ başlatma, Gateway hizmetleri çalışmaya başlamadan önce başarısız oldu.missing-meta-vs-last-good,gateway-mode-missing-vs-last-goodveyasize-drop-vs-last-good:*→ OpenClaw tarafından yönetilen bir yazma işlemi, bilinen son iyi yedekle karşılaştırıldığında alan veya boyut kaybettiği için reddedildi.Config last-known-good promotion skipped→ aday,***gibi sansürlenmiş gizli bilgi yer tutucuları içeriyordu.
Düzeltme seçenekleri
Düzeltme seçenekleri
- doctor aracının önek eklenmiş/üzerine yazılmış yapılandırmayı onarması veya bilinen son iyi sürümü geri yüklemesi için
openclaw doctor --fixkomutunu çalıştırın. - Yalnızca amaçlanan anahtarları
.clobbered.*veya.rejected.*içinden kopyalayın, ardındanopenclaw config setya daconfig.patchile uygulayın. - Yeniden başlatmadan önce
openclaw config validatekomutunu çalıştırın. - Elle düzenliyorsanız yalnızca değiştirmek istediğiniz kısmi nesneyi değil, JSON5 yapılandırmasının tamamını koruyun.
Gateway yoklama uyarıları
openclaw gateway probe bir şeye eriştiği hâlde uyarı bloğu yazdırmaya devam ediyorsa kullanın.
- JSON çıktısındaki
warnings[].codeveprimaryTargetId. - Uyarının SSH geri dönüşü, birden fazla gateway, eksik kapsamlar veya çözümlenmemiş kimlik doğrulama başvuruları hakkında olup olmadığı.
SSH tunnel failed to start; falling back to direct probes.→ SSH kurulumu başarısız oldu ancak komut yine de doğrudan yapılandırılmış/geri döngü hedeflerini denedi.multiple reachable gateway identities detected→ farklı gateway’ler yanıt verdi veya OpenClaw erişilebilir hedeflerin aynı gateway olduğunu doğrulayamadı. Aynı gateway’e yönelik bir SSH tüneli, proxy URL’si veya yapılandırılmış uzak URL, aktarım bağlantı noktaları farklı olsa bile birden fazla aktarıma sahip tek bir gateway olarak değerlendirilir.Read-probe diagnostics are limited by gateway scopes (missing operator.read)→ bağlantı kuruldu ancak ayrıntı RPC’si kapsamla sınırlı; cihaz kimliğini eşleştirin veyaoperator.readiçeren kimlik bilgilerini kullanın.Gateway accepted the WebSocket connection, but follow-up read diagnostics failed→ bağlantı kuruldu ancak tanılama RPC’lerinin tamamı zaman aşımına uğradı veya başarısız oldu. Bunu tanılamaları kısıtlı, erişilebilir bir Gateway olarak değerlendirin;--jsonçıktısındakiconnect.okveconnect.rpcOkdeğerlerini karşılaştırın.Capability: pairing-pendingveyagateway closed (1008): pairing required→ gateway yanıt verdi ancak bu istemcinin normal operatör erişiminden önce hâlâ eşleştirilmesi/onaylanması gerekiyor.- Çözümlenmemiş
gateway.auth.*/gateway.remote.*SecretRef uyarı metni → başarısız hedef için bu komut yolunda kimlik doğrulama malzemesi kullanılamıyordu.
Kanal bağlı ancak mesajlar iletilmiyor
Kanal durumu bağlıysa ancak mesaj akışı durmuşsa ilkeye, izinlere ve kanala özgü teslim kurallarına odaklanın.- DM ilkesi (
pairing,allowlist,open,disabled). - Grup izin verilenler listesi ve bahsetme gereksinimleri.
- Eksik kanal API izinleri/kapsamları.
mention required→ mesaj, grubun bahsetme ilkesi nedeniyle yok sayıldı.pairing/ bekleyen onay izleri → gönderen onaylanmamış.missing_scope,not_in_channel,Forbidden,401/403→ kanal kimlik doğrulama/izin sorunu.
Cron ve Heartbeat teslimi
Cron veya Heartbeat çalışmadıysa ya da teslimat yapmadıysa önce zamanlayıcı durumunu, ardından teslimat hedefini doğrulayın.- Cron’un etkin olması ve bir sonraki uyanma zamanının bulunması.
- İş çalıştırma geçmişi durumu (
ok,skipped,error). - Heartbeat atlama nedenleri (
quiet-hours,requests-in-flight,cron-in-progress,lanes-busy,alerts-disabled,empty-heartbeat-file).
Yaygın belirtiler
Yaygın belirtiler
cron: scheduler disabled; jobs will not run automatically→ cron devre dışı.cron: timer tick failed→ zamanlayıcı tetiklemesi başarısız oldu; dosya/günlük/çalışma zamanı hatalarını kontrol edin.heartbeat skippedilereason=quiet-hours→ etkin saatler aralığının dışında.heartbeat skippedilereason=empty-heartbeat-file→ Heartbeat izleyicisinin geçici içeriği yalnızca boşluk, yorum, başlık, çit veya boş kontrol listesi iskeleti içeriyor; bu nedenle OpenClaw model çağrısını atlıyor.heartbeat: unknown accountId→ Heartbeat teslimat hedefi için geçersiz hesap kimliği.heartbeat skippedilereason=dm-blocked→ Heartbeat hedefi,agents.defaults.heartbeat.directPolicy(veya aracı başına geçersiz kılma)blockolarak ayarlanmışken DM tarzı bir hedefe çözümlendi.
Node eşleştirildi ancak araç başarısız oluyor
Bir Node eşleştirildiği hâlde araçlar başarısız oluyorsa ön plan, izin ve onay durumlarını ayrı ayrı inceleyin.- Node’un beklenen yeteneklerle çevrimiçi olması.
- Kamera/mikrofon/konum/ekran için işletim sistemi izinlerinin verilmiş olması.
- Yürütme onayları ve izin verilenler listesinin durumu.
NODE_BACKGROUND_UNAVAILABLE→ Node uygulaması ön planda olmalıdır.*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ işletim sistemi izni eksik.SYSTEM_RUN_DENIED: approval required→ yürütme onayı bekliyor.SYSTEM_RUN_DENIED: allowlist miss→ komut, izin verilenler listesi tarafından engellendi.
Tarayıcı aracı başarısız oluyor
Gateway’in kendisi sağlıklı olduğu hâlde tarayıcı aracı eylemleri başarısız oluyorsa kullanın.plugins.allowdeğerinin ayarlanmış vebrowserdeğerini içeriyor olup olmadığı.- Geçerli tarayıcı yürütülebilir dosya yolu.
- CDP profilinin erişilebilirliği.
existing-session/userprofilleri için yerel Chrome kullanılabilirliği.
Plugin / yürütülebilir dosya belirtileri
Plugin / yürütülebilir dosya belirtileri
unknown command "browser"veyaunknown command 'browser'→ paketle gelen tarayıcı Plugin’iplugins.allowtarafından hariç tutuluyor.browser.enabled=trueiken tarayıcı aracı eksik / kullanılamıyor →plugins.allow,browserdeğerini hariç tutuyor; bu nedenle Plugin hiç yüklenmedi.Failed to start Chrome CDP on port→ tarayıcı işlemi başlatılamadı.browser.executablePath not found→ yapılandırılmış yol geçersiz.browser.cdpUrl must be http(s) or ws(s)→ yapılandırılmış CDP URL’si,file:veyaftp:gibi desteklenmeyen bir şema kullanıyor.browser.cdpUrl has invalid port→ yapılandırılmış CDP URL’sinin bağlantı noktası hatalı veya izin verilen aralığın dışında.Playwright is not available in this gateway build; '<feature>' is unsupported.→ mevcut gateway kurulumunda temel tarayıcı çalışma zamanı bağımlılığı yok; OpenClaw’u yeniden yükleyin veya güncelleyin, ardından gateway’i yeniden başlatın. ARIA anlık görüntüleri ve temel sayfa ekran görüntüleri çalışmaya devam edebilir ancak gezinme, yapay zekâ anlık görüntüleri, CSS seçicili öğe ekran görüntüleri ve PDF dışa aktarma kullanılamaz.
Chrome MCP / mevcut oturum belirtileri
Chrome MCP / mevcut oturum belirtileri
Could not find DevToolsActivePort for chrome→ Chrome MCP mevcut oturumu henüz seçilen tarayıcı veri dizinine bağlanamadı. Tarayıcı inceleme sayfasını açın, uzaktan hata ayıklamayı etkinleştirin, tarayıcıyı açık tutun, ilk bağlantı istemini onaylayın ve ardından yeniden deneyin. Oturum açılmış durum gerekmiyorsa yönetilenopenclawprofilini tercih edin.No browser tabs found for profile="user"→ Chrome MCP bağlantı profilinde açık yerel Chrome sekmesi yok.Remote CDP for profile "<name>" is not reachable→ yapılandırılmış uzak CDP uç noktasına gateway ana makinesinden erişilemiyor.Browser attachOnly is enabled ... not reachableveyaBrowser attachOnly is enabled and CDP websocket ... is not reachable→ yalnızca bağlantı profilinin erişilebilir bir hedefi yok ya da HTTP uç noktası yanıt verdi ancak CDP WebSocket yine de açılamadı.
Öğe / ekran görüntüsü / yükleme belirtileri
Öğe / ekran görüntüsü / yükleme belirtileri
fullPage is not supported for element screenshots→ ekran görüntüsü isteği,--full-pagedeğerini--refveya--elementile birlikte kullandı.element screenshots are not supported for existing-session profiles; use ref from snapshot.→ Chrome MCP /existing-sessionekran görüntüsü çağrıları CSS--elementyerine sayfa yakalamayı veya anlık görüntü--refdeğerini kullanmalıdır.existing-session file uploads do not support element selectors; use ref/inputRef.→ Chrome MCP yükleme kancaları CSS seçicileri değil, anlık görüntü başvuruları gerektirir.existing-session file uploads currently support one file at a time.→ Chrome MCP profillerinde her çağrıda tek bir yükleme gönderin.existing-session dialog handling does not support timeoutMs.→ Chrome MCP profillerindeki iletişim kutusu kancaları zaman aşımı geçersiz kılmalarını desteklemez.existing-session type does not support timeoutMs overrides.→profile="user"/ Chrome MCP mevcut oturum profillerindeact:typeiçintimeoutMsdeğerini atlayın veya özel bir zaman aşımı gerektiğinde yönetilen/CDP tarayıcı profili kullanın.response body is not supported for existing-session profiles yet.→responsebodyhâlâ yönetilen bir tarayıcı veya ham CDP profili gerektiriyor.- Yalnızca bağlantı veya uzak CDP profillerinde eski görünüm alanı / koyu mod / yerel ayar / çevrimdışı geçersiz kılmaları → gateway’in tamamını yeniden başlatmadan etkin denetim oturumunu kapatmak ve Playwright/CDP öykünme durumunu serbest bırakmak için
openclaw browser stop --browser-profile <name>komutunu çalıştırın.
Yükseltme yaptıysanız ve bir şey aniden bozulduysa
Yükseltme sonrası bozulmaların çoğu, yapılandırma sapmasından veya artık uygulanan daha katı varsayılanlardan kaynaklanır.1. Kimlik doğrulama ve URL geçersiz kılma davranışı değişti
1. Kimlik doğrulama ve URL geçersiz kılma davranışı değişti
- Eğer
gateway.mode=remoteise yerel hizmetiniz sorunsuz olsa bile CLI çağrıları uzak hedefe yöneliyor olabilir. - Açıkça yapılan
--urlçağrıları, saklanan kimlik bilgilerine geri dönmez.
gateway connect failed:→ yanlış URL hedefi.unauthorized→ uç noktaya erişilebiliyor ancak kimlik doğrulama yanlış.
2. Bağlama ve kimlik doğrulama korumaları daha katıdır
2. Bağlama ve kimlik doğrulama korumaları daha katıdır
- Geri döngü olmayan bağlamalar (
lan,tailnet,custom) geçerli bir Gateway kimlik doğrulama yolu gerektirir: paylaşılan belirteç/parola kimlik doğrulaması veya doğru yapılandırılmış, geri döngü olmayan birtrusted-proxydağıtımı. gateway.tokengibi eski anahtarlar,gateway.auth.tokenyerine geçmez.
refusing to bind gateway ... without auth→ geçerli bir Gateway kimlik doğrulama yolu olmadan geri döngü olmayan bağlama.- Çalışma zamanı çalışırken
Connectivity probe: failed→ Gateway etkin ancak mevcut kimlik doğrulama/URL ile erişilemiyor.
3. Eşleştirme ve cihaz kimliği durumu değişti
3. Eşleştirme ve cihaz kimliği durumu değişti
- Gösterge paneli/Node’lar için bekleyen cihaz onayları.
- İlke veya kimlik değişikliklerinden sonra bekleyen DM eşleştirme onayları.
device identity required→ cihaz kimlik doğrulaması karşılanmadı.pairing required→ gönderenin/cihazın onaylanması gerekir.