​

Gateway sorun giderme

​

Komut merdiveni

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

• openclaw gateway status, Runtime: running, Connectivity probe: ok ve bir Capability: ... satırı gösterir.
• openclaw doctor, engelleyici yapılandırma/hizmet sorunu bildirmez.
• openclaw channels status --probe, canlı hesap başına taşıma durumu ve, desteklenen yerlerde, works veya audit ok gibi probe/audit sonuçları gösterir.

​

Uzun bağlam için ek kullanım gerektiren Anthropic 429

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• Seçilen Anthropic Opus/Sonnet modeli params.context1m: true içeriyor.
• Geçerli Anthropic kimlik bilgisi uzun bağlam kullanımı için uygun değil.
• İstekler yalnızca 1M beta yoluna ihtiyaç duyan uzun oturumlarda/model çalıştırmalarında başarısız oluyor.

1. Normal bağlam penceresine geri dönmek için o modelde context1m özelliğini devre dışı bırakın.
2. Uzun bağlam istekleri için uygun bir Anthropic kimlik bilgisi kullanın veya bir Anthropic API anahtarına geçin.
3. Anthropic uzun bağlam istekleri reddedildiğinde çalıştırmaların sürmesi için fallback modeller yapılandırın.

• /providers/anthropic
• /reference/token-use
• /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic

​

Yerel OpenAI uyumlu backend doğrudan probe’ları geçiyor ama ajan çalıştırmaları başarısız oluyor

• curl ... /v1/models çalışıyor
• küçük doğrudan /v1/chat/completions çağrıları çalışıyor
• OpenClaw model çalıştırmaları yalnızca normal ajan dönüşlerinde başarısız oluyor

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

• doğrudan küçük çağrılar başarılı oluyor, ama OpenClaw çalıştırmaları yalnızca daha büyük prompt’larda başarısız oluyor
• messages[].content alanının dize beklediğini söyleyen backend hataları
• yalnızca daha büyük prompt-token sayılarında veya tam ajan çalışma zamanı prompt’larında görünen backend çökmeleri

• messages[...].content: invalid type: sequence, expected a string → backend yapılandırılmış Chat Completions içerik parçalarını reddediyor. Düzeltme: şunu ayarlayın: models.providers.<provider>.models[].compat.requiresStringContent: true.
• doğrudan küçük istekler başarılı oluyor, ama OpenClaw ajan çalıştırmaları backend/model çökmeleriyle başarısız oluyor (örneğin bazı inferrs derlemelerinde Gemma) → OpenClaw taşıması büyük olasılıkla zaten doğru; backend daha büyük ajan çalışma zamanı prompt biçiminde başarısız oluyor.
• araçlar devre dışı bırakıldıktan sonra başarısızlıklar azalıyor ama kaybolmuyor → araç şemaları baskının bir parçasıydı, ancak kalan sorun hâlâ üst akış model/sunucu kapasitesi veya bir backend hatası.

1. Yalnızca dize destekleyen Chat Completions backend’leri için compat.requiresStringContent: true ayarlayın.
2. OpenClaw’un araç şeması yüzeyini güvenilir biçimde işleyemeyen modeller/backend’ler için compat.supportsTools: false ayarlayın.
3. Mümkün olduğunda prompt baskısını azaltın: daha küçük çalışma alanı bootstrap’i, daha kısa oturum geçmişi, daha hafif yerel model veya daha güçlü uzun bağlam desteğine sahip bir backend.
4. Küçük doğrudan istekler geçmeye devam ederken OpenClaw ajan dönüşleri backend içinde hâlâ çöküyorsa, bunu üst akış sunucu/model sınırlaması olarak değerlendirin ve kabul edilen payload biçimiyle orada bir repro bildirin.

• /gateway/local-models
• /gateway/configuration
• /gateway/configuration-reference#openai-compatible-endpoints

​

Yanıt yok

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

• DM göndericileri için eşleştirme bekliyor.
• Grup bahsetme denetimi (requireMention, mentionPatterns).
• Kanal/grup allowlist uyumsuzlukları.

• drop guild message (mention required → grup mesajı, bahsetme olana kadar yok sayılır.
• pairing request → göndericinin onaylanması gerekiyor.
• blocked / allowlist → gönderici/kanal ilke tarafından filtrelendi.

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

​

Dashboard kontrol UI bağlantısı

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

• Doğru probe URL’si ve dashboard URL’si.
• İstemci ile gateway arasında kimlik doğrulama modu/token uyumsuzluğu.
• Cihaz kimliği gerektiğinde HTTP kullanımı.

• device identity required → güvenli olmayan bağlam veya eksik cihaz kimlik doğrulaması.
• origin not allowed → tarayıcı Origin, gateway.controlUi.allowedOrigins içinde değil (veya açık bir allowlist olmadan loopback olmayan bir tarayıcı origin’inden bağlanıyorsunuz).
• device nonce required / device nonce mismatch → istemci, challenge tabanlı cihaz kimlik doğrulama akışını (connect.challenge + device.nonce) tamamlamıyor.
• device signature invalid / device signature expired → istemci, geçerli el sıkışma için yanlış payload’ı (veya eski zaman damgasını) imzaladı.
• AUTH_TOKEN_MISMATCH ve canRetryWithDeviceToken=true → istemci, önbelleğe alınmış cihaz token’ı ile bir güvenilir yeniden deneme yapabilir.
• Bu önbelleğe alınmış token yeniden denemesi, eşlenmiş cihaz token’ı ile saklanan önbelleğe alınmış kapsam kümesini yeniden kullanır. Açık deviceToken / açık scopes çağıranlar ise istenen kapsam kümesini korur.
• Bu yeniden deneme yolu dışında, bağlanma kimlik doğrulama önceliği önce açık paylaşımlı token/parola, sonra açık deviceToken, sonra saklanan cihaz token’ı, sonra bootstrap token’dır.
• Eşzamansız Tailscale Serve Control UI yolunda, aynı {scope, ip} için başarısız denemeler sınırlayıcı başarısızlığı kaydetmeden önce serileştirilir. Aynı istemciden iki hatalı eşzamanlı yeniden deneme bu nedenle ikinci denemede iki düz uyumsuzluk yerine retry later gösterebilir.
• Bir tarayıcı-origin loopback istemcisinden too many failed authentication attempts (retry later) → aynı normalize edilmiş Origin kaynaklı tekrarlanan hatalar geçici olarak kilitlenir; başka bir localhost origin’i ayrı bir bucket kullanır.
• Bu yeniden denemeden sonra tekrarlanan unauthorized → paylaşımlı token/cihaz token’ı kayması; gerekiyorsa token yapılandırmasını yenileyin ve cihaz token’ını yeniden onaylayın/döndürün.
• gateway connect failed: → yanlış host/port/url hedefi.

​

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

openclaw --version
openclaw doctor
openclaw gateway status

1. connect.challenge bekliyor
2. challenge’a bağlı payload’ı imzalıyor
3. aynı challenge nonce ile connect.params.device.nonce gönderiyor

• eşlenmiş cihaz token oturumları yalnızca kendi cihazlarını yönetebilir; çağıran ayrıca operator.admin yetkisine sahip değilse
• openclaw devices rotate --scope ..., yalnızca çağıran oturumun zaten sahip olduğu operator kapsamlarını isteyebilir

• /web/control-ui
• /gateway/configuration (gateway kimlik doğrulama modları)
• /gateway/trusted-proxy-auth
• /gateway/remote
• /cli/devices

​

Gateway hizmeti çalışmıyor

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # sistem düzeyi hizmetleri de tarar

• Çıkış ipuçlarıyla birlikte Runtime: stopped.
• Hizmet yapılandırması uyumsuzluğu (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ı.

• Gateway start blocked: set gateway.mode=local veya existing config is missing gateway.mode → yerel gateway modu etkin değil ya da yapılandırma dosyası bozuldu ve gateway.mode değerini kaybetti. Düzeltme: yapılandırmanızda gateway.mode="local" ayarlayın veya beklenen yerel mod yapılandırmasını yeniden damgalamak için openclaw onboard --mode local / openclaw setup komutlarını yeniden çalıştırın. OpenClaw’u Podman üzerinden çalıştırıyorsanız varsayılan yapılandırma yolu ~/.openclaw/openclaw.json olur.
• refusing to bind gateway ... without auth → geçerli bir gateway kimlik doğrulama yolu olmadan loopback olmayan bağlama (token/parola veya yapılandırılmışsa trusted-proxy).
• another gateway instance is already listening / EADDRINUSE → port çakışması.
• Other gateway-like services detected (best effort) → eski veya paralel launchd/systemd/schtasks birimleri mevcut. Çoğu kurulum makine başına tek bir gateway kullanmalıdır; birden fazlasına gerçekten ihtiyacınız varsa port + yapılandırma/durum/çalışma alanını yalıtın. Bkz. /gateway#multiple-gateways-same-host.

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

​

Gateway son bilinen iyi yapılandırmayı geri yükledi

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

• Config auto-restored from last-known-good
• gateway: invalid config was restored from last-known-good backup
• config reload restored last-known-good config after invalid-config
• Etkin yapılandırmanın yanında zaman damgalı bir openclaw.json.clobbered.* dosyası
• Config recovery warning ile başlayan bir ana ajan sistem olayı

• Reddedilen yapılandırma başlangıçta veya sıcak yeniden yükleme sırasında doğrulamadan geçmedi.
• OpenClaw reddedilen payload’ı .clobbered.* olarak korudu.
• Etkin yapılandırma, son doğrulanmış son bilinen iyi kopyadan geri yüklendi.
• Sonraki ana ajan dönüşü, reddedilen yapılandırmayı körü körüne yeniden yazmaması için uyarılır.

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

• .clobbered.* mevcut → harici doğrudan düzenleme veya başlangıç okuması geri yüklendi.
• .rejected.* mevcut → OpenClaw’un sahip olduğu bir yapılandırma yazımı, commit öncesinde şema veya clobber denetimlerinde başarısız oldu.
• Config write rejected: → yazma işlemi gerekli yapıyı kaldırmayı, dosyayı keskin biçimde küçültmeyi veya geçersiz yapılandırmayı kalıcı kılmayı denedi.
• Config last-known-good promotion skipped → aday, *** gibi redakte edilmiş gizli anahtar yer tutucuları içeriyordu.

1. Doğruysa geri yüklenen etkin yapılandırmayı koruyun.
2. Yalnızca amaçlanan anahtarları .clobbered.* veya .rejected.* dosyasından kopyalayın, ardından bunları openclaw config set veya config.patch ile uygulayın.
3. Yeniden başlatmadan önce openclaw config validate çalıştırın.
4. Elle düzenleme yapıyorsanız, değiştirmek istediğiniz kısmi nesneyi değil tam JSON5 yapılandırmasını koruyun.

• /gateway/configuration#strict-validation
• /gateway/configuration#config-hot-reload
• /cli/config
• /gateway/doctor

​

Gateway probe uyarıları

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• JSON çıktısındaki warnings[].code ve primaryTargetId.
• Uyarının SSH fallback’i, birden fazla gateway, eksik scope’lar 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 ama komut yine de doğrudan yapılandırılmış/loopback hedefleri denedi.
• multiple reachable gateways detected → birden fazla hedef yanıt verdi. Bu genellikle kasıtlı çoklu gateway kurulumu veya eski/yinelenen dinleyiciler anlamına gelir.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → bağlantı kuruldu ama ayrıntı RPC’si scope ile sınırlı; cihaz kimliğini eşleyin veya operator.read içeren kimlik bilgileri kullanın.
• Capability: pairing-pending veya gateway closed (1008): pairing required → gateway yanıt verdi ama bu istemcinin normal operatör erişiminden önce hâlâ eşleştirme/onay alması gerekiyor.
• çözümlenmemiş gateway.auth.* / gateway.remote.* SecretRef uyarı metni → başarısız hedef için bu komut yolunda kimlik doğrulama materyali kullanılamıyordu.

• /cli/gateway
• /gateway#multiple-gateways-same-host
• /gateway/remote

​

Kanal bağlı ama mesajlar akmıyor

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

• DM ilkesi (pairing, allowlist, open, disabled).
• Grup allowlist’i ve bahsetme gereksinimleri.
• Eksik kanal API izinleri/scope’ları.

• mention required → mesaj grup bahsetme ilkesi nedeniyle yok sayıldı.
• pairing / bekleyen onay izleri → gönderici onaylanmamış.
• missing_scope, not_in_channel, Forbidden, 401/403 → kanal kimlik doğrulama/izin sorunu.

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

​

Cron ve Heartbeat teslimatı

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

• Cron etkin mi ve sonraki uyandırma mevcut mu.
• İş çalıştırma geçmişi durumu (ok, skipped, error).
• Heartbeat atlama nedenleri (quiet-hours, requests-in-flight, alerts-disabled, empty-heartbeat-file, no-tasks-due).

• cron: scheduler disabled; jobs will not run automatically → Cron devre dışı.
• cron: timer tick failed → scheduler tick başarısız oldu; dosya/günlük/çalışma zamanı hatalarını kontrol edin.
• heartbeat skipped ve reason=quiet-hours → etkin saat penceresinin dışında.
• heartbeat skipped ve reason=empty-heartbeat-file → HEARTBEAT.md mevcut ama yalnızca boş satırlar / markdown başlıkları içeriyor, bu yüzden OpenClaw model çağrısını atlıyor.
• heartbeat skipped ve reason=no-tasks-due → HEARTBEAT.md bir tasks: bloğu içeriyor ama bu tick sırasında hiçbir görev zamanı gelmiş değil.
• heartbeat: unknown accountId → Heartbeat teslim hedefi için geçersiz hesap kimliği.
• heartbeat skipped ve reason=dm-blocked → Heartbeat hedefi DM tarzı bir hedefe çözümlendi ama agents.defaults.heartbeat.directPolicy (veya ajan başına geçersiz kılma) block olarak ayarlı.

• /automation/cron-jobs#troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

​

Eşlenmiş Node aracı başarısız oluyor

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

• Node beklenen yeteneklerle çevrimiçi mi.
• Kamera/mikrofon/konum/ekran için OS izinleri verilmiş mi.
• Exec onayları ve allowlist durumu.

• NODE_BACKGROUND_UNAVAILABLE → Node uygulaması foreground’da olmalı.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → eksik OS izni.
• SYSTEM_RUN_DENIED: approval required → exec onayı bekleniyor.
• SYSTEM_RUN_DENIED: allowlist miss → komut allowlist tarafından engellendi.

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

​

Browser aracı başarısız oluyor

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

• plugins.allow ayarlı mı ve browser içeriyor mu.
• Geçerli browser yürütülebilir dosya yolu.
• CDP profil erişilebilirliği.
• existing-session / user profilleri için yerel Chrome kullanılabilirliği.

• unknown command "browser" veya unknown command 'browser' → paketle gelen browser plugin’i plugins.allow tarafından hariç tutulmuş.
• browser.enabled=true olduğu hâlde browser aracı eksik / kullanılamıyor → plugins.allow, browser’ı hariç tutuyor; bu yüzden plugin hiç yüklenmedi.
• Failed to start Chrome CDP on port → browser süreci 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: veya ftp: gibi desteklenmeyen bir şema kullanıyor.
• browser.cdpUrl has invalid port → yapılandırılmış CDP URL’sinde hatalı veya aralık dışı bir port var.
• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session, seçilen browser veri dizinine henüz bağlanamadı. Browser inceleme sayfasını açın, uzaktan hata ayıklamayı etkinleştirin, browser’ı açık tutun, ilk bağlanma istemini onaylayın, sonra yeniden deneyin. Oturum açılmış durum gerekmiyorsa, yönetilen openclaw profilini tercih edin.
• No Chrome tabs found for profile="user" → Chrome MCP bağlanma 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 host’undan erişilemiyor.
• Browser attachOnly is enabled ... not reachable veya Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profilinin erişilebilir bir hedefi yok ya da HTTP uç noktası yanıt verdi ama CDP WebSocket yine de açılamadı.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → geçerli gateway kurulumu tam Playwright paketini içermiyor; ARIA anlık görüntüleri ve temel sayfa ekran görüntüleri yine de çalışabilir, ancak gezinme, AI anlık görüntüleri, CSS seçici öğe ekran görüntüleri ve PDF dışa aktarma kullanılamaz durumda kalır.
• fullPage is not supported for element screenshots → ekran görüntüsü isteği --full-page ile --ref veya --element değerlerini birlikte kullandı.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session ekran görüntüsü çağrıları CSS --element değil, sayfa yakalama veya bir anlık görüntü --ref değeri 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ü ref’lerini gerektirir.
• existing-session file uploads currently support one file at a time. → Chrome MCP profillerinde çağrı başına tek yükleme gönderin.
• existing-session dialog handling does not support timeoutMs. → Chrome MCP profillerindeki iletişim kutusu kancaları timeout geçersiz kılmalarını desteklemez.
• response body is not supported for existing-session profiles yet. → responsebody hâlâ yönetilen bir browser veya ham CDP profili gerektirir.
• attach-only veya uzak CDP profillerinde eski viewport / dark-mode / locale / offline geçersiz kılmaları → etkin denetim oturumunu kapatmak ve Playwright/CDP öykünme durumunu tüm gateway’i yeniden başlatmadan serbest bırakmak için openclaw browser stop --browser-profile <name> çalıştırın.

• /tools/browser-linux-troubleshooting
• /tools/browser

​

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

​

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

• gateway.mode=remote ise CLI çağrıları uzaktaki hedefi kullanıyor olabilir; yerel hizmetiniz iyi durumda olsa bile.
• Açık --url çağrıları saklanan kimlik bilgilerine geri dönmez.

• gateway connect failed: → yanlış URL hedefi.
• unauthorized → uç noktaya ulaşılıyor ama kimlik doğrulama yanlış.

​

2) Bağlama ve kimlik doğrulama korkulukları daha katı

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

• Loopback olmayan bağlamalar (lan, tailnet, custom) geçerli bir gateway kimlik doğrulama yolu gerektirir: paylaşımlı token/parola kimlik doğrulaması veya doğru yapılandırılmış loopback olmayan bir trusted-proxy dağıtımı.
• gateway.token gibi eski anahtarlar gateway.auth.token yerine geçmez.

• refusing to bind gateway ... without auth → geçerli bir gateway kimlik doğrulama yolu olmadan loopback olmayan bağlama.
• Çalışma zamanı çalışırken Connectivity probe: failed → gateway canlı ama geçerli auth/url ile erişilemiyor.

​

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

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

• Dashboard/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şılanmamış.
• pairing required → gönderici/cihaz onaylanmalı.

openclaw gateway install --force
openclaw gateway restart

• /gateway/pairing
• /gateway/authentication
• /gateway/background-process