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ı çalışma belirtileri:

• 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çinde Update 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, bir openclaw 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.

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

openclaw gateway install --forceopenclaw gateway restart

Geri alma sonrasında protokol uyuşmazlığı

Sürüm düşürme veya geri alma sonrasında günlüklerde sürekli protocol 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.

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

Şunları arayın:

• Gateway günlüklerinde protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.
• openclaw gateway status --deep içinde Established clients: veya openclaw doctor --deep içinde Gateway 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.

Düzeltme:

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

Eski bir Gateway'in daha yeni ve uyumsuz bir protokolü kabul etmesini sağlamayın. Protokol sürüm artışları iletişim sözleşmesini 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 kapsama sınırıdır. ~/.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:

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

Hedef kasıtlıysa 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ılmışsa 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ı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:

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

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.

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 maliyetleri
• Anthropic'ten neden HTTP 429 görüyorum?

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.

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 engellemesine işaret ediyorsa önce sağlayıcı tarafındaki filtrelemeyi düzeltin. OpenClaw'ın kullandığı API yolu için dar kapsamlı bir izin veya atlama kuralını tercih edin ve sitenin tamamı için 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 öğ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=0 uyarıları.
• Yalnızca daha yüksek istem token sayılarında veya tam ajan çalışma zamanı istemlerinde ortaya çıkan 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önderenler 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 → bahsedilene kadar grup mesajı yok sayılır.
• pairing request → gönderenin onaylanması gerekir.
• blocked / allowlist → gönderen/kanal politika tarafından filtrelendi.

İlgili:

• 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 hedefine 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ü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.

Kimlik doğrulama ayrıntı kodları hızlı haritası

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ükler nonce/imza hataları gösteriyorsa bağlanan istemciyi güncelleyin ve doğrulayın:

openclaw devices rotate / revoke / remove beklenmedik şekilde reddedilirse:

• Eşleştirilmiş cihaz token'ı oturumları, çağıranda ayrıca operator.admin bulunmadığı 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.

İlgili:

• 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.

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

Şunları arayın:

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

İlgili:

• 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

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. Genellikle openclaw status içinde belirgin bir belirti olmaz; çünkü siz kontrol edene kadar gateway yeniden çalışır duruma gelmiş olur.

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 bilgisayarda bile ENETDOWN ile 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 runs içeren state = not running değerini gösteren launchctl 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ı veya launchctl kickstart gibi harici bir tetikleyici onu 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 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.log içinde karşılık gelen bir received SIG*; shutting down satırı olmadan gün boyunca artan runs sayısı: düzgün kapatmalar bir sinyali günlüğe kaydeder; geçici çökmeler kaydetmez.

Yapılması gerekenler:

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. Her zaman açık sunucular olarak çalışması amaçlanan Mac mini / masaüstü ana bilgisayarlarda bakım uykusu etkinliğini azaltın:

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

   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.

3. launchd tarafından beklemeye alınan gelecekteki bir art arda çökme durumunun hızla yakalanması için bir canlılık izleyicisi ekleyin:

   # 5 dakikalık bir cron veya LaunchAgent için uygun, launchd uyumlu canlılık denetimi örneğistate=$(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 oluşturma eşiğini harici olarak yeniden etkinleştirmektir; art arda çökmelerden sonra macOS'te yalnızca 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 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.

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 bilgisayarda hem ~/Library/LaunchAgents/ai.openclaw.gateway.plist hem de ~/Library/LaunchAgents/ai.openclaw.node.plist öğesinin aynı anda yüklenmiş olması.

Yapılması gerekenler:

1. 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 node uninstall

2. OpenClaw'ı başlatmadan önce devralınan launchd işaretçilerini 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ı süreç göstermeli ve gelen kanal dağıtımı devam etmelidir.

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

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

İlgili:

• macOS platform notları
• Doctor
• Gateway CLI

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ü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 bellek sınırlamalı hizmet içinde çalıştığında 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 bir kararlılık paketi yakalamıştır. Paketi openclaw gateway stability --bundle latest ile 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çin openclaw gateway status içindeki Gateway heap: değerini inceleyin; not set diyorsa eski hizmet meta verilerini openclaw gateway install --force ile yeniden oluşturun. Ortam kabuğundaki NODE_OPTIONS kası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 export yakalayı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. Ham günlükleri kopyalamak yerine tanılama dışa aktarımını hata raporlarına ekleyin.

İlgili:

• Gateway sağlığı
• 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üzenlemenin atlandığı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 eriştiği hâlde uyarı bloğu yazdırmaya devam ediyorsa kullanın.

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

Şunları arayı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 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 veya operator.read iç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ı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
• Uzak erişim

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.

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

Şunları arayın:

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

Yaygın belirtiler:

• 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.

İlgili:

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

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.

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

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

İ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

Şunları arayın:

• 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.

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 → yürütme onayı bekliyor.
• SYSTEM_RUN_DENIED: allowlist miss → komut, izin verilenler listesi tarafından engellendi.

İlgili:

• Yürütme 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 oluyorsa kullanın.

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

Şunları arayın:

• plugins.allow değerinin ayarlanmış ve browser değerini içeriyor olup olmadığı.
• 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ı 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 konular:

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

İlgili Konular

• Doctor
• SSS
• Gateway operasyon kılavuzu