Ana içeriğe atla

​
Gateway sorun giderme

Bu sayfa derin runbook’tur. Önce hızlı triyaj akışını istiyorsanız /help/troubleshooting ile başlayın.

​
Komut merdiveni

Bunları önce, bu sırayla çalıştırın: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Beklenen sağlıklı sinyaller:
  • openclaw gateway status içinde Runtime: running ve RPC probe: ok görünür.
  • openclaw doctor engelleyici yapılandırma/hizmet sorunu olmadığını bildirir.
  • openclaw channels status --probe bağlı/hazır kanalları gösterir.

​
Yanıt yok

Kanallar ayakta ama hiçbir şey yanıt vermiyorsa, herhangi bir şeyi yeniden bağlamadan önce yönlendirme ve politikayı kontrol edin. 
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow
Şunları arayın:
  • DM gönderenleri için eşleştirmenin beklemede olması.
  • Grup bahsetme kısıtlaması (requireMention, mentionPatterns).
  • Kanal/grup izin listesi uyumsuzlukları.
Yaygın imzalar:
  • drop guild message (mention required → bahsedilene kadar grup mesajı yok sayılır.
  • pairing request → gönderenin onaya ihtiyacı var.
  • blocked / allowlist → gönderen/kanal politika tarafından filtrelendi.
İlgili:

​
Gösterge paneli kontrol arayüzü bağlantısı

Gösterge paneli/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 status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
Şunları arayın:
  • Doğru probe URL’si ve gösterge paneli URL’si.
  • İstemci ile gateway arasında kimlik doğrulama modu/belirteci uyumsuzluğu.
  • Cihaz kimliği gerektiği hâlde HTTP kullanımı.
Yaygın imzalar:
  • device identity required → güvenli olmayan bağlam veya eksik cihaz kimlik doğrulaması.
  • unauthorized / yeniden bağlanma döngüsü → belirteç/parola uyumsuzluğu.
  • gateway connect failed: → yanlış ana makine/port/url hedefi.
İlgili:

​
Gateway hizmeti çalışmıyor

Hizmet kurulu ancak süreç ayakta kalmıyorsa bunu kullanın. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep
Şunları arayın:
  • Çıkış ipuçlarıyla birlikte Runtime: stopped.
  • Hizmet yapılandırması uyumsuzluğu (Config (cli) ile Config (service)).
  • Port/dinleyici çakışmaları.
Yaygın imzalar:
  • Gateway start blocked: set gateway.mode=local → yerel gateway modu etkin değil. Düzeltme: yapılandırmanızda gateway.mode="local" ayarlayın (veya openclaw configure çalıştırın). OpenClaw’ı Podman ile özel openclaw kullanıcısı üzerinden çalıştırıyorsanız, yapılandırma dosyası ~openclaw/.openclaw/openclaw.json konumundadır.
  • refusing to bind gateway ... without auth → belirteç/parola olmadan loopback dışı bağlama.
  • another gateway instance is already listening / EADDRINUSE → port çakışması.
İlgili:

​
Kanal bağlı, mesajlar akmıyor

Kanal durumu bağlı ancak mesaj akışı durmuşsa, politika, izinler ve kanala özgü teslim kurallarına odaklanın. 
openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels
Şunları arayın:
  • DM politikası (pairing, allowlist, open, disabled).
  • Grup izin listesi ve bahsetme gereksinimleri.
  • Eksik kanal API izinleri/kapsamları.
Yaygın imzalar:
  • mention required → mesaj grup bahsetme politikası tarafından yok sayıldı.
  • pairing / bekleyen onay izleri → gönderen onaylı değil.
  • missing_scope, not_in_channel, Forbidden, 401/403 → kanal kimlik doğrulama/izin sorunu.
İlgili:

​
Cron ve heartbeat teslimi

Cron veya heartbeat çalışmadıysa ya da teslim edilmediyse, önce zamanlayıcı durumunu, ardından teslim hedefini doğrulayın. 
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
Şunları arayın:
  • Cron etkin ve bir sonraki uyanış mevcut.
  • İş çalıştırma geçmişi durumu (ok, skipped, error).
  • Heartbeat atlama nedenleri (quiet-hours, requests-in-flight, alerts-disabled).
Yaygın imzalar:
  • cron: scheduler disabled; jobs will not run automatically → cron devre dışı.
  • cron: timer tick failed → zamanlayıcı tik’i başarısız; dosya/log/çalışma zamanı hatalarını kontrol edin.
  • heartbeat skipped ile birlikte reason=quiet-hours → etkin saatler penceresinin dışında.
  • heartbeat: unknown accountId → heartbeat teslim hedefi için geçersiz hesap kimliği.
İlgili:

​
Eşleştirilmiş düğüm aracı başarısız

Bir düğüm eşleştirilmiş ancak araçlar başarısızsa, ön plan, izin ve onay durumunu izole edin. 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
Şunları arayın:
  • Beklenen yeteneklerle çevrimiçi düğüm.
  • Kamera/mikrofon/konum/ekran için işletim sistemi izinleri.
  • Çalıştırma onayları ve izin listesi durumu.
Yaygın imzalar:
  • NODE_BACKGROUND_UNAVAILABLE → düğüm uygulaması ön planda olmalı.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → eksik işletim sistemi izni.
  • SYSTEM_RUN_DENIED: approval required → çalıştırma onayı beklemede.
  • SYSTEM_RUN_DENIED: allowlist miss → komut izin listesi tarafından engellendi.
İlgili:

​
Tarayıcı aracı başarısız

Gateway’in kendisi sağlıklı olmasına rağmen tarayıcı aracı eylemleri başarısız oluyorsa bunu kullanın. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
Şunları arayın:
  • Geçerli tarayıcı yürütülebilir dosya yolu.
  • CDP profilinin erişilebilirliği.
  • profile="chrome" için eklenti röle sekmesi iliştirmesi.
Yaygın imzalar:
  • Failed to start Chrome CDP on port → tarayıcı süreci başlatılamadı.
  • browser.executablePath not found → yapılandırılan yol geçersiz.
  • Chrome extension relay is running, but no tab is connected → eklenti rölesi iliştirilmedi.
  • Browser attachOnly is enabled ... not reachable → yalnızca iliştirilen profilin erişilebilir hedefi yok.
İlgili:

​
Güncelleme yaptıysanız ve bir şeyler aniden bozulduysa

Güncelleme sonrası bozulmaların çoğu yapılandırma kayması ya da artık daha sıkı varsayılanların uygulanmasından kaynaklanır.

​
1. Kimlik doğrulama ve URL geçersiz kılma davranışı değişti

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
Bakılacaklar:
  • gateway.mode=remote ise, yerel hizmetiniz sağlamken CLI çağrıları uzak hedefi işaret ediyor olabilir.
  • Açık --url çağrıları, saklanan kimlik bilgilerine geri dönmez.
Yaygın imzalar:
  • gateway connect failed: → yanlış URL hedefi.
  • unauthorized → uç nokta erişilebilir ancak kimlik doğrulama yanlış.

​
2. Bağlama ve kimlik doğrulama korkulukları daha sıkı

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
Bakılacaklar:
  • Loopback dışı bağlamalar (lan, tailnet, custom) için kimlik doğrulama yapılandırılmalıdır.
  • gateway.token gibi eski anahtarlar gateway.auth.token yerine geçmez.
Yaygın imzalar:
  • refusing to bind gateway ... without auth → bağlama+kimlik doğrulama uyumsuzluğu.
  • Çalışma zamanı çalışırken RPC probe: failed → gateway canlı ancak mevcut kimlik doğrulama/url ile erişilemez.

​
3. Eşleştirme ve cihaz kimliği durumu değişti

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor
Bakılacaklar:
  • Gösterge paneli/düğümler için bekleyen cihaz onayları.
  • Politika veya kimlik değişikliklerinden sonra bekleyen DM eşleştirme onayları.
Yaygın imzalar:
  • device identity required → cihaz kimlik doğrulaması karşılanmadı.
  • pairing required → gönderen/cihaz onaylanmalıdır.
Kontrollerden sonra hizmet yapılandırması ile çalışma zamanı hâlâ uyuşmuyorsa, aynı profil/durum dizininden hizmet meta verilerini yeniden yükleyin: 
openclaw gateway install --force
openclaw gateway restart
İlgili: