Bir ajanı tanılama

Bu kılavuz, bir ajanın neden çalıştırma üretmediğini nasıl bulacağınızı gösterir.

Yukarıdan aşağıya doğru ilerleyin: önce ajanın kendi çalıştırmaları, sonra arka ucu, sonra sunucu, sonra ana makine.

1. Ajanın çalıştırma geçmişini denetleyin

Ayarlar → Çalışma alanı → Ajanlar → ajanı seçin → Loglar.

Her çalıştırma bir durum rozeti, bir süre (devam ederken “Running…”), başlangıç ve tamamlanma zamanları, PID’si ve kullandığı adaptörü gösterir. Görünüm, o çalıştırmanın ham olay akışını açar. Durdur, çalışan bir süreci sonlandırır ve çalıştırmayı “Killed by user” olarak işaretler; başlıktaki Çalışanı sonlandır ise o ajanın devam eden her çalıştırması için aynısını yapar.

Şöyle okuyun:

Hiç çalıştırma yok — gönderim hiç gerçekleşmedi. Composer’daki anmalar @ ile sözcük karakterlerinden (harfler, rakamlar, alt çizgi) oluşur. Çözümleme, ajan adı üzerinde tam veya önek eşleşmesidir; bu nedenle @code-reviewer, code olarak ayrıştırılır ve yine de code-reviewer adlı bir ajanı uyandırabilir. Boşluk içeren bir ad, tek bir belirteç olarak anılamaz. Ardından 2. adıma geçin.
Hemen hatayla biten bir çalıştırma — Görünüm’ü açın. Arka ucun başlatılamaması burada bir süreç hatası olarak görünür.
“Running…” durumunda takılı kalan bir çalıştırma — durdurun, ardından Ayarlar sekmesinde ajanın Sessizlik zaman aşımı değerini denetleyin. Ayarlanmamış bir zaman aşımı, moda özgü varsayılanı kullanır.
İşe yarar çıktısı olmayan tamamlanmış bir çalıştırma — bildirdiği çıktıyı üretmeden biten bir çalıştırmada çalıştırma günlüğünün durumu completed olarak kalır; gerçek gösterge rozet değil, özet metnidir.

Loglar sekmesi maliyet göstermez. Harcama için Gözlemlenebilirlik → İçgörüler içindeki ajan başına tabloyu kullanın.

2. Ajanın arka ucunu denetleyin

Ayarlar → Sunucu → Model sağlayıcıları (/settings/server/providers).

Algılanan runner’lar listesi her adaptörü yoklama sonucuyla birlikte gösterir — kurulu bir sürüm, “Denetleniyor…” veya “Bulunamadı” — ayrıca çözümlenen yolu ve bulunan bir CLI için yetenek çipleri. Yeniden yoklamak için sayfa başlığındaki Yenile’ye tıklayın.

Yoklama, baktığınız makinede değil cc_server’ı barındıran makinede çalışır. Web istemcisindeyseniz veya eşleştirilmiş bir cihazdaysanız, “Bulunamadı” CLI’nin sunucu ana makinesinde eksik olduğu anlamına gelir.

Doğrulanacak iki şey:

Ajanın hiç değilse bir adaptörü ayarlı mı. Adaptörü boş olan bir ajan Control Center (built-in) adaptörüne gönderilir ve çalıştırma günlüğüne cc-harness yazılır; böylece döküm neyin çalıştığını adıyla söyler. Model de yoksa Anthropic’ten varsayılanını ister — bir Anthropic hesabı bağlamadıysanız bu, No credential for provider "anthropic" hatasıyla başarısız olur. Önceden tanımlı uzmanlar adaptörsüz gelir.
Yerleşik adaptörün bir modeli var mı. Model listesi, aynı sayfanın aşağısında bağlanan sağlayıcılardan canlı olarak gelir; bu nedenle kayıtlı kimlik bilgisi olmayan bir sağlayıcı hiç model sağlamaz.

Adaptör kataloğunun kendisi sabittir — yeni bir adaptör kaydetmenin hiçbir yolu yoktur. Burada adaptör başına değiştirebileceğiniz şeyler, o adaptörün başlatma argümanları ve ortam değişkenleridir. Kimlik bilgileri çözümlenirken adaptör başına ortam geçersiz kılmanın, bağlı bir sağlayıcı hesabını sessizce geçtiğini unutmayın.

3. Sunucuyu denetleyin

Ayarlar → Sunucu → Bağlantı ve durum (/settings/server/connection), bu istemcinin hangi sunucuyla konuştuğunu ve sunucunun neler bildirdiğini gösterir.

Headless bir sunucuda GET /healthz, istemci olmadan aynı bilgiyi verir. Tasarımı gereği kimlik doğrulama istemez ve CORS’a açıktır:

curl http://localhost:9030/healthz

Sunucunun durumunu, saniye cinsinden çalışma süresini, canlı bağlantı sayısını, bağlanılan portu, yapı sürümünü ve git SHA’sını, çalışma alanı şema sürümünü, RPC katalog sürümünü, sunucu kimliğini, adını ve kimlik parmak izini, bağlamanın güvensiz olup olmadığını ve watching / indexing / pending sayaçlarını içeren bir codeGraph bloğunu döndürür. Bir önbellek trafik gördüyse ayrıca bir caches bloğu içerir; bir demo sunucusu demo: true ekler.

Bir değişiklik “testlerde çalışıyor ama uygulamada çalışmıyor” olduğunda bilinmesi gereken iki şey:

Masaüstü uygulaması, kaynak kod yerine önceden derlenmiş bir cc_server ikili dosyasını başlatmayı tercih eder. Yeni bir RPC işlemi veya MCP aracı, ikili dosya yeniden derlenene kadar ortaya çıkmaz; alt sürecin git SHA’sı uygulamanınkinden farklıysa önyükleme günlüğe bir uyarı yazar.
Masaüstü uygulaması, 20 saniye içinde hazır olduğunu bildiren banner’ını yazdırmayan başlatılmış sunucuyu sonlandırır ve bir hata ekranına düşer.

4. Ana makineyi denetleyin

Ayarlar → Sunucu → Tanılama ve gizlilik (/settings/server/diagnostics), ana makine düzeyindeki sayfadır. Şunları içerir:

Korumalı alan — ana anahtar, algılanan arka uç ve bir kurulum ipucu. Sunucudan yalnızca algılanan arka uç gelir; aşağıdaki Dikkat bölümüne bakın. Sıfırlama denetimi yoktur.
Anlamsal arama — cihaz üzerindeki gömme modelinin yaşam döngüsü: kurulu, yüzdeyle indiriliyor, kurulu değil veya kurulum hatası. Model kurulana kadar bellek ve kod araması yalnızca anahtar sözcükle çalışır.
Sistem davranışı — ajanlar çalışırken bilgisayarı uyanık tut.
Log düzeyi — bir hatayı yeniden üretmeden önce yükseltin.
Gizlilik — ham diff içeriğinin ajanın modeline iletilip iletilmeyeceği ve çökme raporlarının gönderilip gönderilmeyeceği.

Algılama ve uygulama artık uyuşuyor: algılayıcı yerel bir arka uç bildiriyorsa, o ana makinedeki ajan çalıştırmaları gerçekten onun içine alınır. Ancak bu bölümdeki tek canlı şey algılayıcıdır. Ana anahtar ve arka uç seçici cihazınızda saklanan tercihlerdir ve sunucu bunların hiçbirini okumaz — sunucunun kendi anahtarı --sandbox’tır (varsayılan olarak on, vazgeçmek için off).

Dolayısıyla buradaki bir uyarı üzerinde durmaya değer, ancak genellikle bir ajanın başarısız olmasının nedeni değildir. Sunucunun hangi durumda olduğunu doğrulamak için başlangıç günlüğünü okuyun: arka uç notuyla birlikte agent sandbox ON, bir kurulum ipucuyla no OS-native agent sandbox on this host ya da agent sandbox DISABLED by --sandbox off yazar. GET /healthz hiçbir sandbox alanı taşımaz.

Arka ucun olmadığı yerlerde — Windows’ta her zaman, bwrap ve socat olmadan Linux veya WSL2’de — çalıştırmalar sandbox’a alınmaz ve onları sınırlayan şeyler şunlardır: konuşmanın kendi checkout’u, salt okunur forge belirteci ve push ağ geçidi, eylem korumaları, ortam temizliği ve modunun izin verdiği araç yüzeyi.

Sık karşılaşılan hatalar

Çalıştırma hiç başlamıyor ve adaptör “Bulunamadı” gösteriyor

CLI’yi sunucu ana makinesine kurun, ardından Model sağlayıcıları sayfasında Yenile’ye tıklayın. Ya da ajanı, CLI gerektirmeyen yerleşik adaptöre geçirin ve aynı sayfadan bir sağlayıcı bağlayın.

Ajan push yapamıyor veya pull request açamıyor

Git’in ya da ajanın ne yazdırdığını okuyun. Control Center policy: …, bir eylem kuralının bunu reddettiği ya da bir onayın yanıtsız kaldığı anlamına gelir: Ayarlar → Çalışma alanı → Ajan izinleri altında Uzak depoya push et ve Pull request aç kurallarını denetleyin. Git, Control Center’ın push edebilen bir GitHub kimlik bilgisi olmadığını söylüyorsa GitHub App’i o depoya kurun ya da GitHub’ı bağlayın.

Anlamsal arama işe yarar bir şey döndürmüyor

Ayarlar → Sunucu → Tanılama ve gizlilik → Anlamsal arama yolunu denetleyin. Gömme modeli kurulana kadar arama yalnızca anahtar sözcükle çalışır. Model kurulmadan önce yazılan satırlar hiçbir zaman geriye dönük doldurulmaz; bu nedenle sonrasında bile yalnızca anahtar sözcükle aranır.

Sunucu hiç önyüklenmiyor

Yerel kitaplıklar zorunludur ve bozulmuş bir mod yoktur. Eksik bir dylib yüzünden cc_server başlamayı reddeder ve hatada sorunlu dosyayı adıyla belirtir. Yerel dosyaları scripts/natives/build_natives.sh ile hazırlayın ve sunucu ikili dosyasını yeniden derleyin.

Bir eylem sessizce reddediliyor

Onaylayıcı bağlı değilken prompt koruma kararı, tasarım gereği reddedilir. Çalışma alanının kurallarını Ayarlar → Çalışma alanı → Ajan izinleri altından denetleyin.