Sorun giderme

Bu sayfa en sık karşılaşılan sorunları, olduklarında ne gördüğünü ve nasıl çözeceğini listeler. Sorunun burada yoksa sondaki Sorun bildirmek bölümüne bak.

Sağlayıcılar

Claude Code oturumunun süresi doldu ya da API anahtarı geçersiz

Ne görürsün: proje sohbetinde Claude Code oturumunun süresinin dolduğunu (ya da anahtarın reddedildiğini) söyleyen 🔑 simgeli bir mesaj; tüm ekip duraklatılmıştır ve ajanlar hata durumundadır.

Çözüm:

1. Bir terminalde yeniden giriş yap. Agentbits içindeki Terminal → Kabuklar’ı da kullanabilirsin.

   claude auth login    # Codex CLI için: codex login

2. Ayarlar → Sağlayıcılar’da sağlayıcıyı yeniden test et (Test et). Claude Code için claude auth status kontrol edilir.

3. Üst bardaki Devam et’e tıkla. Hata durumları sıfırlanır ve ekip yeniden başlar.

Anthropic API ya da OpenAI API kullanıyorsan anahtarı yeniden gir: Ayarlar → Sağlayıcılar’da sağlayıcıyı silip yeni anahtarla tekrar ekle.

CLI bulunamıyor

Agentbits, Claude Code’u ya da Codex CLI’ı içermez ve kurmaz; onları PATH üzerinde arar. Ayarlar → Sağlayıcılar → Sağlayıcı ekle formunda ● kurulu ya da ○ bulunamadı görünür.

○ bulunamadı görüyorsan:

1. CLI’ı kur ve bir kez giriş yap (claude auth login ya da codex login).
2. PATH üzerinde olmayan bir klasöre kurulduysa tam yolunu CLI yolu (boş = PATH’ten bul) alanına yaz.
3. Sağlayıcıyı kaydedip yeniden test et.

Projeler ve klasörler

“Klasör seçilmedi”: CLI ajanları çalışmıyor

Claude Code ve Codex CLI ajanları projenin klasöründe çalışır. Klasörü olmayan bir projede bölüm satırında amber renkli Klasör seçilmedi çipi görünür ve o projedeki CLI görevleri reddedilir. İzin Matrisi’nde de “klasör seçilmedi — CLI ajanları çalışmaz” yazar.

Çözüm: proje sekmesine çift tıkla (ya da klasör çipinin yanındaki proje ayarları düğmesini kullan), bir Klasör seç ve kaydet. Demo ve API sağlayıcıları klasör gerektirmez.

Uyarı: CLI ajanları o klasördeki dosyaları gerçekten değiştirir. Boş bir klasörle ya da bir git dalıyla başla.

Klasör reddediliyor

Bir klasör seçtiğinde Agentbits onu denetler ve neden kullanılamadığını söyler:

Mesaj	Ne yapmalı
“Bu klasör Agentbits uygulamasının kendisi…”	Başka bir klasör seç. Ajanlar uygulamanın kendi kodunu değiştirmemeli.
“Bu klasör zaten … projesinde kullanılıyor.”	Her klasör tek bir projeye aittir. O projeyi aç ya da başka bir klasör seç.
“Bu klasör ajanlar için fazla geniş…”	Sürücü kökü, kullanıcı klasörün ya da Agentbits verisini içeren bir klasör kullanılamaz. Projenin kendi klasörünü seç.
“klasör bulunamadı” (proje seçicide)	Klasör taşınmış ya da adı değişmiş. Proje ayarlarından yeni yerini seç.

Ajanlar çalışmaya başlamıyor

Görevler To do’da bekliyorsa ya da hiçbir şey ilerlemiyorsa sırayla şunlara bak:

• Onay kartları. Onay iste açık ajanlar seni bekler. Şablondan kurulan ajanlarda bu ayar açık başlar. Sol paneldeki kartı onayla.
• Tümünü duraklat. Üst barda Devam et görünüyorsa her şey duraklatılmıştır. Duraklatma, uygulama yeniden açılınca da sürer.
• Otopilot. Kapalıyken boştaki ajanlar görevleri kendiliğinden almaz. Ayarlar → Genel’den aç ya da görevleri kendin başlat.
• Bekletilen görevler. Reddettiğin ya da durdurduğun, iki kez hata veren ya da uygulama kapanırken yarıda kalan bir görev kendiliğinden yeniden alınmaz. Elle başlat ya da yeniden To do’ya taşı.
• Lider yok. Lider olmadan sohbet mesajını görevlere çeviremez. Organizasyon → Takımlar’dan ya da proje ayarlarından bir lider seç.
• Codex CLI. Dosya okuma izni kapalı bir Codex ajanı çalışmaz.

Uygulama penceresi ve veriler

“Veriler yüklenemedi” ve Tekrar dene

Uygulama Veriler yüklenemedi ekranıyla açılıyorsa Tekrar dene’ye tıkla. Sorun sürerse:

• Eski bir sürüme mi döndün? Yeni bir sürümün yükselttiği veritabanı eski sürümle açılamaz. Yeni sürümü yeniden kur.
• Sorunun verilerinde olup olmadığını anlamak için uygulamayı bir kez AGENTBITS_DATA_DIR ile boş bir veri klasöründe başlat (bkz. Kurulum). Bu gerçek verilerine dokunmaz.
• Bir yedeğe elle dönmek için uygulamayı kapat, backups klasöründeki bir dosyayı veri klasörüne agentbits.db adıyla kopyala ve yanındaki agentbits.db-wal ile agentbits.db-shm dosyalarını sil. Önce mevcut dosyaları güvenli bir yere kopyala.

Yalnızca bir bölümde Bu görünüm bir hatayla karşılaştı mesajını görüyorsan Tekrar dene’ye tıkla ya da başka bir bölüme geç. Pencerenin geri kalanı çalışmaya devam eder.

Kabuklarda Pipe modu rozeti

Terminal → Kabuklar’da Pipe modu · etkileşimli programlar desteklenmez yazıyorsa gerçek terminal bileşeni yüklenememiştir. Kabuklar komut çalıştırmaya devam eder ama tam ekran programlar, şifre istemleri ve ok tuşları çalışmaz; Ctrl+C de yalnızca yazılan satırı siler. Ajan terminalleri bundan etkilenmez.

Kaynaktan çalıştırıyorsan npm install’u yeniden çalıştır. --no-optional ya da --omit=optional kullanma, electron-rebuild çalıştırma.

Kurulumda SmartScreen uyarısı

Kurulum dosyaları, ister indir ister kendin derle, kod imzalı olmadığı için Windows “Windows bilgisayarınızı korudu” uyarısı verir. Ek bilgi’ye, ardından Yine de çalıştır’a tıkla.

macOS paketleri henüz gerçek bir Mac’te denenmedi. Noter onayı olmadığı için macOS ilk açılışta uyarır: Sistem Ayarları → Gizlilik ve Güvenlik’i açıp Yine de Aç’ı seç.

Kaynaktan çalıştırma

Siyah pencere, ERR_CONNECTION_TIMED_OUT

Pencere siyah kalıyor ve terminalde localhost:5173 için ERR_CONNECTION_TIMED_OUT görünüyorsa uygulama geliştirme sunucusuna ulaşamıyordur. Birkaç kez yeniden dener, olmazsa bir sorun giderme sayfası gösterir.

1. npm run dev’i durdurup yeniden başlat.

2. Ayrı bir PowerShell penceresinde sunucunun cevap verdiğini kontrol et: curl.exe -I http://127.0.0.1:5173.

3. Antivirüsün ya da güvenlik duvarının Node.js’i engellemediğinden emin ol.

4. Geçici çözüm olarak uygulamayı geliştirme sunucusu olmadan derleyip çalıştır:

   npm run build
   npm start

“Electron failed to install correctly”

Electron indirmesi büyük olasılıkla npm install sırasında yarıda kalmıştır. Kurulumunu yeniden çalıştır:

node node_modules\electron\install.js

İndirme engelleniyor ya da yavaşsa bir ayna kullan:

$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
node node_modules\electron\install.js

Ardından node_modules\electron\dist\electron.exe dosyası var olmalı.

PowerShell: “running scripts is disabled on this system”

PowerShell’in yürütme ilkesi npm ve npx betiklerini engelleyebilir. Kendi kullanıcın için yerel betiklere izin ver ya da doğrudan npm.cmd’yi çağır:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# ya da ilkeyi değiştirmeden:
npm.cmd run dev

Bu ayar uygulamanın kendi Kabuklar’ını etkilemez.

Güncellemeden sonra veritabanı modülü hatası

better-sqlite3 modül hatası görürsen electron-rebuild çalıştırma. node_modules klasörünü silip npm install’u yeniden çalıştır ve Node.js 22 ya da üstünü kullandığından emin ol.

Sorun bildirmek

GitHub’da bir issue aç; işletim sistemini, Agentbits sürümünü (Ayarlar → Genel’de görünür), kullandığın sağlayıcıyı ve soruna götüren adımları yaz. Ekran görüntülerinden API anahtarlarını, yolları ve kişisel verileri çıkar. Durum çubuğundaki Geri bildirim düğmesini de kullanabilirsin; hazır bir e-posta açar.

Güvenlik sorunları herkese açık bir issue’ya yazılmamalı. Güvenlik sayfasında anlatıldığı gibi gizli olarak bildir.