Sorun Giderme

Bu, ayrıntılı çalışma kılavuzudur. Önce hızlı triyaj akışı için /help/troubleshooting sayfasından başlayın.

Komut sıralaması

Şu sırayla çalıştırın:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Sağlıklı durum göstergeleri:

• openclaw gateway status, Runtime: running, Connectivity probe: ok ve bir Capability: ... 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 yerlerde works veya audit ok gö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 --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Şunları arayın:

• openclaw status / openclaw status --all içindeki Update restart. Bekleyen veya başarısız devirler, çalıştırılacak sonraki komutu içerir.
• Kanallar altındaki 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, ajan başına eski OAuth kimlik doğrulama gölge kopyalarını denetler ve tüm ajanların geçerli paylaşılan profili çözümlemesi için eski kopyaları kaldırır.

Bölünmüş kurulumlar ve daha yeni yapılandırma koruması

Bir güncellemeden sonra Gateway hizmeti beklenmedik biçimde durduğunda veya günlükler bir openclaw ikili dosyasının openclaw.json dosyasına 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ılmış yapılandırmayı inceleyebilir ancak işlem ve hizmet değişikliklerinin daha eski bir ikili dosyadan ç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.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Geri almadan sonra protokol uyuşmazlığı

Sürüm düşürme veya geri alma işleminden sonra günlükler sürekli protocol mismatch yazdırıyorsa kullanın. Daha eski bir Gateway çalışmaktadır ancak daha yeni bir yerel istemci işlemi, eski Gateway'in kullanamadığı bir protokol aralığıyla yeniden bağlanmayı sürdürmektedir.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Şunları arayın:

• Gateway günlüklerindeki protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.
• openclaw gateway status --deep içindeki Established clients: veya openclaw doctor --deep içindeki Gateway clients: işletim sistemi izin verdiğinde PID'ler ve komut satırlarıyla birlikte Gateway bağlantı noktasına bağlı etkin TCP istemcileri.
• Komut satırı, geri aldığınız daha yeni OpenClaw kurulumunu veya sarmalayıcıyı gösteren bir istemci işlemi.

Düzeltme:

1. gateway status --deep tarafından gösterilen eski OpenClaw istemci işlemini durdurun veya yeniden başlatın.
2. OpenClaw'u 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 --follow kabukları.
3. openclaw gateway status --deep veya openclaw doctor --deep komutunu yeniden çalıştırın ve eski istemci PID'sinin kaybolduğunu doğrulayın.

Daha eski bir Gateway'in daha yeni ve uyumsuz bir protokolü kabul etmesini sağlamayın. Protokol sürüm yükseltmeleri kablo üzerindeki sözleşmeyi korur; geri alma kurtarması bir işlem/sürüm temizleme sorunudur.

Yol dışına çıkma nedeniyle Skill sembolik bağlantısının atlanması

Günlükler şunu içerdiğinde kullanın:

Yapılandırılmış kökünün dışına çıkan skill yolu atlanıyor: ... reason=symlink-escape

Her skill kökü bir sınırlama sınırıdır. ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills veya ~/.openclaw/skills altındaki bir sembolik bağlantı, gerçek hedefi açıkça güvenilir olarak belirtilmediği sürece bu kökün dışına çözümlendiğinde atlanır.

Bağlantıyı inceleyin:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Hedef bilinçli olarak seçildiyse hem doğrudan skill kökünü hem de izin verilen sembolik bağlantı hedefini yapılandırın:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Ardından yeni bir oturum başlatın veya skills izleyicisinin yenilenmesini bekleyin. Çalışan işlem yapılandırma değişikliğinden önce başlatıldıysa Gateway'i yeniden başlatın.

~, / 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ırlı tutun.

Skill Workshop uygulama işleminin güvenilir sembolik bağlantılı çalışma alanı skill yolları üzerinden de yazması gerekiyorsa skills.workshop.allowSymlinkTargetWrites seçeneğini etkinleştirin. Salt okunur paylaşılan skill köklerinde devre dışı tutun.

İlgili:

• Skills yapılandırması
• Yapılandırma örnekleri

Anthropic 429: uzun bağlam için ek kullanım gerekli

Günlükler/hatalar HTTP 429: rate_limit_error: Extra usage is required for long context requests içerdiğinde kullanın.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Şunları arayın:

• 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: true değ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.

Düzeltme seçenekleri:

İlgili:

• Anthropic
• Token kullanımı ve maliyetler
• Anthropic'ten neden HTTP 429 görüyorum?

Üst sağlayıcıdan gelen engellenmiş 403 yanıtları

Üst 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 üst güvenlik katmanından gelebilir.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Şunları arayın:

• 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 curl yoklaması başarılı olurken normal SDK biçimli isteklerin başarısız olması.

Kanıtlar bir WAF/CDN engellemesini gösterdiğinde önce sağlayıcı tarafındaki filtrelemeyi düzeltin. OpenClaw'un kullandığı API yolu için dar kapsamlı bir izin verme veya atlama kuralını tercih edin ve sitenin tamamında korumayı devre dışı bırakmaktan kaçının.

İlgili:

• OpenAI uyumlu uç noktalar
• Sağlayıcı yapılandırması
• Günlükler

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.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"merhaba"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "merhaba" --jsonopenclaw logs --follow

Şunları arayın:

• 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/completions aynı yalın model kimliğiyle çalışmasına rağmen model_not_found veya 404 hataları.
• messages[].content değerinin bir dize olmasını beklediğini belirten arka uç hataları.
• OpenAI uyumlu yerel bir arka uçta aralıklı incomplete turn detected ... stopReason=stop payloads=0 uyarıları.
• Yalnızca daha yüksek istem-token sayılarında veya tam ajan çalışma zamanı istemlerinde görülen arka uç çökmeleri.

İlgili:

• Yapılandırma
• Yerel modeller
• OpenAI uyumlu uç noktalar

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.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

Şunları arayın:

• DM gönderenleri için eşleştirme bekliyor.
• Grup bahsetme kısıtlaması (requireMention, mentionPatterns).
• Kanal/grup izin listesi uyuşmazlıkları.

Yaygın belirtiler:

• drop guild message (mention required → grup mesajı bahsedilene kadar yok sayılır.
• pairing request → gönderenin onaylanması gerekir.
• blocked / allowlist → gönderen/kanal politika tarafından filtrelendi.

İlgili konular:

• Kanal sorunlarını giderme
• Gruplar
• Eşleştirme

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.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Şunları arayı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ı.

Bir güncellemeden sonra yerel tarayıcı 127.0.0.1:18789 adresine bağlanamıyorsa önce yerel Gateway hizmetini kurtarın ve panoyu sunduğunu doğrulayın:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

curl OpenClaw HTML'si döndürürse Gateway çalışıyordur ve kalan sorun büyük olasılıkla tarayıcı önbelleği, eski bir derin bağlantı veya güncelliğini yitirmiş sekme durumudur. http://127.0.0.1:18789 adresini doğrudan açın ve panodan ilerleyin. Yeniden başlatma sonrasında hizmet çalışır durumda kalmazsa openclaw gateway start komutunu çalıştırın ve openclaw gateway status değerini yeniden kontrol edin.

Kimlik doğrulama ayrıntı kodları hızlı eşlemesi

Sonraki işlemi seçmek için başarısız connect yanıtındaki error.details.code değerini kullanın:

Cihaz kimlik doğrulaması v2 geçiş kontrolü:

openclaw --versionopenclaw doctoropenclaw gateway status

Günlüklerde nonce/imza hataları görünüyorsa bağlanan istemciyi güncelleyin ve istemciyi doğrulayın:

openclaw devices rotate / revoke / remove beklenmedik biçimde reddedilirse:

• Eşleştirilmiş cihaz tokenı oturumları, çağıranda ayrıca operator.admin olmadığı sürece yalnızca kendi cihazlarını yönetebilir.
• openclaw devices rotate --scope ... yalnızca çağıran oturumun zaten sahip olduğu operatör kapsamlarını isteyebilir.

İlgili konular:

• 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 yüklü olduğu hâlde süreç çalışır durumda kalmıyorsa kullanın.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # sistem düzeyindeki hizmetleri de tara

Şunları arayın:

• Çıkış ipuçlarıyla birlikte Runtime: stopped.
• Hizmet yapılandırması uyuşmazlığı (Config (cli) ile Config (service)).
• Port/dinleyici çakışmaları.
• --deep kullanıldığında fazladan launchd/systemd/schtasks kurulumları.
• Other gateway-like services detected (best effort) temizleme ipuçları.

İlgili konular:

• Arka planda yürütme ve süreç aracı
• Yapılandırma
• Doctor

macOS gateway sessizce yanıt vermeyi durduruyor, ardından panoya dokunduğunuzda devam ediyor

macOS ana makinesindeki kanallar (Telegram, WhatsApp vb.) zaman zaman dakikalarca veya saatlerce sessiz kaldığında ve Control UI'yi açtığınız, SSH ile bağlandığınız ya da ana makineyle başka bir şekilde etkileşime geçtiğiniz anda Gateway yeniden çalışmaya başlıyor gibi göründüğünde kullanın. Genellikle openclaw status içinde belirgin bir belirti olmaz; çünkü kontrol ettiğiniz sırada Gateway yeniden çalışır durumdadır.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Şunları arayın:

• ~/.openclaw/logs/stability/ içinde error.code değeri ENETDOWN, ENETUNREACH, EHOSTUNREACH veya ECONNREFUSED gibi geçici bir ağ koduna ayarlanmış bir ya da daha fazla *-uncaught_exception.json paketi.
• Çökme zaman damgalarıyla örtüşen Entering Sleep state due to 'Maintenance Sleep' veya en0 driver is slow (msg: WillChangeState to 0) gibi pmset -g log satı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 giden connect(), normalde tam ağ bağlantısına sahip bir ana makinede bile ENETDOWN ile başarısız olabilir.
• Özellikle çökme ile sonraki başlatma arasındaki süre saniyeler yerine yaklaşık bir saat olduğunda, çıkış koduyla birlikte yakın zamanda birden çok runs içeren state = not running gösteren launchctl print çıktısı. macOS launchd, art arda çökmelerden sonra belgelenmemiş bir yeniden başlatma koruma geçidi uygular; bu geçit, etkileşimli oturum açma, pano bağlantısı veya launchctl kickstart gibi harici bir tetikleyici geçidi yeniden etkinleştirene kadar KeepAlive=true ayarının dikkate alınmasını durdurabilir.

Yaygın belirtiler:

• error.code değeri ENETDOWN veya benzer bir kod olan ve çağrı yığını Node net lookupAndConnect / Socket.connect içine işaret eden bir kararlılık paketi. OpenClaw 2026.5.26 ve daha yeni sürümler bunları zararsız geçici ağ hataları olarak sınıflandırır; böylece artık üst düzey yakalanmamış hata işleyicisine yayılmazlar. Daha eski bir sürüm kullanıyorsanız önce yükseltin.
• Control UI'ye bağlandığınız veya ana makineye SSH ile eriştiğiniz anda sona eren uzun sessiz dönemler: launchd'nin yeniden başlatma geçidini yeniden etkinleştiren şey, panonun Gateway üzerinde yaptığı herhangi bir işlem değil, kullanıcı tarafından görülebilen etkinliktir.
• Gün boyunca karşılık gelen bir received SIG*; shutting down satırı ~/Library/Logs/openclaw/gateway.log içinde bulunmadan artan runs sayısı: düzgün kapatmalar bir sinyal kaydeder; geçici çökmeler kaydetmez.

Yapılacaklar:

1. 2026.5.26 öncesi bir sürüm kullanıyorsanız Gateway'i yükseltin. Yükseltmeden sonra gelecekteki ENETDOWN hataları, işlemi sonlandırmak yerine uyarı olarak günlüğe kaydedilir.

2. Sürekli açık sunucular olarak çalışması amaçlanan Mac mini / masaüstü ana makinelerde bakım uykusu etkinliğini azaltın:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Bu, temeldeki sürücü kesintisini ö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ı gerçekleştirmeye devam edebilir.

3. launchd tarafından beklemeye alınan gelecekteki bir çökme serisinin hızla algılanması için bir canlılık izleyicisi ekleyin:

   # 5 dakikalık bir Cron veya LaunchAgent için uygun, launchd'yi dikkate alan örnek canlılık denetimistate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   Amaç, yeniden başlatma geçidini harici olarak yeniden etkinleştirmektir; macOS'te art arda çökmelerden sonra tek başına KeepAlive=true yeterli değildir.

İlgili:

• macOS platform notları
• Günlük kaydı
• Doctor

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 sağlık denetimleri sağlıklı ve kullanılamaz durumları arasında gidip geldiğinde ve hizmet çalışıyor gibi görünmesine rağmen kanal dağıtımı 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şlatma işlemini launchd'ye devretmeye çalışabilir ve tek bir kararlı Gateway işlemi yerine hızlı bir EADDRINUSE/yeniden başlatma döngüsüne girebilir.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Şunları arayın:

• 30 saniyelik örnek boyunca tek bir kararlı işlem yerine birden fazla Gateway PID'si.
• gateway.log içinde EADDRINUSE, another gateway instance is already listening veya yinelenen yeniden başlatma/devir satırları.
• Yalnızca tek bir yönetilen Gateway hizmeti çalıştırması gereken bir ana makinede hem ~/Library/LaunchAgents/ai.openclaw.gateway.plist hem de ~/Library/LaunchAgents/ai.openclaw.node.plist öğesinin aynı anda yüklenmiş olması.

Yapılacaklar:

1. Bu ana makinede yalnızca Gateway hizmeti çalışacaksa yönetilen Node hizmetini OpenClaw aracılığıyla kaldırın. Uzak Node özellikleri için Node hizmetini etkin olarak kullanıyorsanız bu adımı atlayın; hizmetin kaldırılması bu ana makinedeki söz konusu özellikleri durdurur:

   openclaw node uninstall

2. OpenClaw'ı başlatmadan önce devralınan launchd işaretlerini temizleyen kalıcı bir Gateway sarmalayıcısı kurun. Desteklenen --wrapper seç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:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install zorunlu yeniden kurulumlar, güncellemeler ve doctor onarımları boyunca sarmalayıcı yolunu korur.

3. Gateway'in yalnızca dinlemede değil, kararlı ve RPC hizmeti veriyor olduğunu doğrulayın:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID örneği, sürekli değişen bir PID kümesi yerine tek bir kararlı işlem göstermeli ve gelen kanal yönlendirmesi devam etmelidir.

4. Temeldeki 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:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

İlgili:

• macOS platform notları
• Doctor
• Gateway CLI

Yüksek bellek kullanımı sırasında Gateway kapanıyor

Gateway yük altında kaybolduğunda, denetleyici OOM türünde bir yeniden başlatma bildirdiğinde veya günlüklerde critical memory pressure bundle written ifadesi geçtiğinde kullanın.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Şunları arayın:

• En son kararlılık paketinde Reason: diagnostic.memory.pressure.critical.
• critical/rss_threshold, critical/heap_threshold veya critical/rss_growth ile birlikte Memory pressure:.
• Yığın sınırına yakın V8 heap: değerleri.
• agents/<agent>/sessions/<session>.jsonl veya sessions/<session>.jsonl gibi Largest session files: girdileri.
• Gateway bir kapsayıcı veya belleği sınırlı hizmet içinde çalışırken Linux cgroup bellek sayaçları.

Yaygın belirtiler:

• critical memory pressure bundle written yeniden başlatmadan kısa süre önce görünür → OpenClaw, OOM öncesi kararlılık paketini yakalamıştır. Paketi openclaw gateway stability --bundle latest ile inceleyin.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled Gateway günlüklerinde görünür → OpenClaw kritik bellek baskısı algılamıştır ancak OOM öncesi kararlılık anlık görüntüsü kapalıdır.
• Largest session files: çok büyük, redakte edilmiş bir transkript yolunu gösterir → tutulan oturum geçmişini azaltın, oturum büyümesini inceleyin veya yeniden başlatmadan önce eski transkriptleri etkin depodan çıkarın.
• V8 heap: kullanılan baytları yığın sınırına yakındır → istem/oturum baskısını azaltın, eşzamanlı işi azaltın veya yalnızca iş yükünün beklendiğini doğruladıktan sonra Node yığın sınırını yükseltin.
• 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 denemeler veya kuyruğa alınmış bir grup agent işi için en son günlükleri kontrol edin.
• Günlüklerde kritik bellek baskısı görünür ancak paket yoktur → varsayılan davranış budur. Gelecekteki kritik bellek baskısı olaylarında OOM öncesi kararlılık paketini yakalamak için diagnostics.memoryPressureSnapshot: true değerini ayarlayın.

Kararlılık paketi yük içermez. İleti metni, webhook gövdeleri, kimlik bilgileri, token'lar, çerezler veya ham oturum kimlikleri değil; operasyonel bellek kanıtları ve redakte edilmiş göreli dosya yolları içerir. Hata raporlarına ham günlükleri kopyalamak yerine tanılama dışa aktarımını ekleyin.

İlgili:

• Gateway durumu
• Tanılama dışa aktarımı
• Oturumlar

Gateway geçersiz yapılandırmayı reddetti

Gateway başlatma işlemi Invalid config ile başarısız olduğunda veya çalışırken yeniden yükleme günlükleri geçersiz bir düzenlemeyi atladığını belirttiğinde kullanın.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Şunları arayı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 --fix bozuk bir doğrudan düzenlemeyi onardıysa zaman damgalı bir openclaw.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.

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

İlgili:

• Yapılandırma
• Yapılandırma: çalışırken yeniden yükleme
• Yapılandırma: katı doğrulama
• Doctor

Gateway yoklama uyarıları

openclaw gateway probe bir şeye ulaştığı hâlde yine de bir uyarı bloğu yazdırdığında kullanın.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Şunlara bakın:

• JSON çıktısındaki warnings[].code ve primaryTargetId.
• Uyarının SSH geri dönüşü, birden fazla Gateway, eksik kapsamlar veya çözümlenmemiş kimlik doğrulama başvuruları hakkında olup olmadığı.

Yaygın belirtiler:

• 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 kanıtlayamadı. Aynı Gateway'e giden 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 veya operator.read kapsamına sahip kimlik bilgileri kullanın.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → bağlantı kuruldu ancak tam tanılama RPC kümesi zaman aşımına uğradı veya başarısız oldu. Bunu tanılama özellikleri kısıtlanmış erişilebilir bir Gateway olarak değerlendirin; --json çıktısındaki connect.ok ve connect.rpcOk değerlerini karşılaştırın.
• Capability: pairing-pending veya gateway 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.

İlgili:

• Gateway
• Aynı ana makinede birden fazla Gateway
• Uzaktan erişim

Kanal bağlı ancak iletiler akmıyor

Kanal durumu bağlıysa ancak ileti akışı durmuşsa ilkeye, izinlere ve kanala özgü teslimat kurallarına odaklanın.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Şunlara bakın:

• DM ilkesi (pairing, allowlist, open, disabled).
• Grup izin listesi ve bahsetme gereksinimleri.
• Eksik kanal API izinleri/kapsamları.

Yaygın belirtiler:

• mention required → ileti, grup bahsetme ilkesi tarafından yok sayıldı.
• pairing / bekleyen onay izleri → gönderen onaylanmamış.
• missing_scope, not_in_channel, Forbidden, 401/403 → kanal kimlik doğrulaması/izinleri sorunu.

İlgili:

• Kanal sorunlarını giderme
• Discord
• Telegram
• WhatsApp

Cron ve Heartbeat teslimatı

Cron veya Heartbeat çalışmadıysa ya da teslimat yapmadıysa önce zamanlayıcı durumunu, ardından teslimat hedefini doğrulayın.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Şunlara bakın:

• Cron'un etkin olması ve sonraki uyanma zamanının bulunması.
• İş çalıştırma geçmişinin durumu (ok, skipped, error).
• Heartbeat atlama nedenleri (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

İlgili:

• Heartbeat
• Zamanlanmış görevler
• Zamanlanmış görevler: sorun giderme

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.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

Şunlara bakın:

• Node'un beklenen yeteneklerle çevrimiçi olması.
• Kamera/mikrofon/konum/ekran için işletim sistemi izinleri.
• Çalıştırma onayları ve izin listesi durumu.

Yaygın belirtiler:

• 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 → çalıştırma onayı bekliyor.
• SYSTEM_RUN_DENIED: allowlist miss → komut izin listesi tarafından engellendi.

İlgili:

• Çalıştırma onayları
• Node sorunlarını giderme
• Node'lar

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 olduğunda kullanın.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Şunlara bakın:

• plugins.allow ayarının yapılıp yapılmadığına ve browser değerini içerip içermediğine.
• Geçerli tarayıcı yürütülebilir dosya yolu.
• CDP profilinin erişilebilirliği.
• existing-session / user profilleri için yerel Chrome kullanılabilirliği.

İlgili:

• Tarayıcı (OpenClaw tarafından yönetilen)
• Tarayıcı sorunlarını giderme

Yükseltme yaptıysanız ve bir şey aniden bozulduysa

Yükseltme sonrasındaki bozulmaların çoğu, yapılandırma sapmasından veya artık uygulanan daha katı varsayılanlardan kaynaklanır.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

Kontrollerden sonra hizmet yapılandırması ile çalışma zamanı hâlâ uyuşmuyorsa hizmet meta verilerini aynı profil/durum dizininden yeniden yükleyin:

openclaw gateway install --forceopenclaw gateway restart

İlgili:

• Kimlik doğrulama
• Arka planda yürütme ve işlem aracı
• Node eşleştirme

İlgili

• Doctor
• SSS
• Gateway çalışma kitabı