Ajan döngüsü

Bir ajan döngüsü, bir ajanın tam "gerçek" çalıştırmasıdır: alım → bağlam derleme → model çıkarımı → araç yürütme → akışlı yanıtlar → kalıcılık. Bir iletiyi eylemlere ve nihai yanıta dönüştüren, bu sırada oturum durumunu tutarlı tutan yetkili yoldur.

OpenClaw'da döngü, model düşünürken, araçları çağırırken ve çıktıyı akışa verirken yaşam döngüsü ve akış olayları yayan, oturum başına tek ve serileştirilmiş bir çalıştırmadır. Bu belge, bu özgün döngünün uçtan uca nasıl bağlandığını açıklar.

# Giriş noktaları

• Gateway RPC: agent ve agent.wait.
• CLI: agent komutu.

# Nasıl çalışır (üst düzey)

1. agent RPC parametreleri doğrular, oturumu çözer (sessionKey/sessionId), oturum meta verilerini kalıcılaştırır, hemen { runId, acceptedAt } döndürür.
2. agentCommand ajanı çalıştırır:
   • model + thinking/verbose/trace varsayılanlarını çözer
   • Skills anlık görüntüsünü yükler
   • runEmbeddedPiAgent çağrısı yapar (pi-agent-core çalışma zamanı)
   • gömülü döngü bir tane yaymazsa yaşam döngüsü bitiş/hata yayar
3. runEmbeddedPiAgent:
   • çalıştırmaları oturum başına + küresel kuyruklar üzerinden serileştirir
   • model + kimlik doğrulama profilini çözer ve pi oturumunu oluşturur
   • pi olaylarına abone olur ve asistan/araç deltalarını akışa verir
   • zaman aşımını uygular -> süre aşılırsa çalıştırmayı iptal eder
   • Codex app-server dönüşleri için, terminal olaydan önce app-server ilerlemesi üretmeyi durduran kabul edilmiş bir dönüşü iptal eder
   • payload'ları + kullanım meta verilerini döndürür
4. subscribeEmbeddedPiSession, pi-agent-core olaylarını OpenClaw agent akışına köprüler:
   • araç olayları => stream: "tool"
   • asistan deltaları => stream: "assistant"
   • yaşam döngüsü olayları => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait, waitForAgentRun kullanır:
   • runId için yaşam döngüsü bitiş/hata bekler
   • { status: ok|error|timeout, startedAt, endedAt, error? } döndürür

# Kuyruğa alma + eşzamanlılık

• Çalıştırmalar oturum anahtarı başına (oturum şeridi) ve isteğe bağlı olarak küresel bir şerit üzerinden serileştirilir.
• Bu, araç/oturum yarışlarını önler ve oturum geçmişini tutarlı tutar.
• Mesajlaşma kanalları, bu şerit sistemini besleyen kuyruk modlarını (collect/steer/followup) seçebilir. Bkz. Komut Kuyruğu.
• Transkript yazmaları da oturum dosyasında bir oturum yazma kilidiyle korunur. Kilit, süreç farkındalığına sahiptir ve dosya tabanlıdır; bu nedenle süreç içi kuyruğu atlayan veya başka bir süreçten gelen yazıcıları yakalar. Oturum transkript yazıcıları, oturumu meşgul olarak bildirmeden önce en fazla session.writeLock.acquireTimeoutMs kadar bekler; varsayılan 60000 ms'dir.
• Oturum yazma kilitleri varsayılan olarak yeniden girilebilir değildir. Bir yardımcı, tek bir mantıksal yazıcıyı korurken aynı kilidin edinilmesini kasıtlı olarak iç içe geçiriyorsa, bunu açıkça allowReentrant: true ile etkinleştirmelidir.

# Oturum + çalışma alanı hazırlığı

• Çalışma alanı çözülür ve oluşturulur; sandbox'lı çalıştırmalar bir sandbox çalışma alanı köküne yönlendirilebilir.
• Skills yüklenir (veya bir anlık görüntüden yeniden kullanılır) ve ortama ve isteme enjekte edilir.
• Bootstrap/bağlam dosyaları çözülür ve sistem istemi raporuna enjekte edilir.
• Bir oturum yazma kilidi edinilir; akış başlamadan önce SessionManager açılır ve hazırlanır. Daha sonraki herhangi bir transkript yeniden yazma, Compaction veya kısaltma yolu, transkript dosyasını açmadan veya değiştirmeden önce aynı kilidi almalıdır.

# İstem derleme + sistem istemi

• Sistem istemi, OpenClaw'un temel isteminden, Skills isteminden, bootstrap bağlamından ve çalıştırma başına geçersiz kılmalardan oluşturulur.
• Modele özgü sınırlar ve Compaction yedek belirteçleri uygulanır.
• Modelin ne gördüğü için bkz. Sistem istemi.

# Kanca noktaları (nerede araya girebilirsiniz)

OpenClaw iki kanca sistemine sahiptir:

• Dahili kancalar (Gateway kancaları): komutlar ve yaşam döngüsü olayları için olay güdümlü betikler.
• Plugin kancaları: ajan/araç yaşam döngüsü ve Gateway işlem hattı içindeki genişletme noktaları.

# Dahili kancalar (Gateway kancaları)

• agent:bootstrap: sistem istemi son haline getirilmeden önce bootstrap dosyaları oluşturulurken çalışır. Bootstrap bağlam dosyaları eklemek/kaldırmak için bunu kullanın.
• Komut kancaları: /new, /reset, /stop ve diğer komut olayları (Hooks belgesine bakın).

Kurulum ve örnekler için bkz. Kancalar.

# Plugin kancaları (ajan + Gateway yaşam döngüsü)

Bunlar ajan döngüsü veya Gateway işlem hattı içinde çalışır:

• before_model_resolve: model çözümlemesinden önce sağlayıcıyı/modeli deterministik olarak geçersiz kılmak için oturum öncesinde çalışır (messages yok).
• before_prompt_build: istem gönderiminden önce prependContext, systemPrompt, prependSystemContext veya appendSystemContext enjekte etmek için oturum yüklendikten sonra (messages ile) çalışır. Tur başına dinamik metin için prependContext kullanın; sistem istemi alanında durması gereken kararlı yönlendirme için sistem bağlamı alanlarını kullanın.
• before_agent_start: iki aşamada da çalışabilen eski uyumluluk kancası; yukarıdaki açık kancaları tercih edin.
• before_agent_reply: satır içi eylemlerden sonra ve LLM çağrısından önce çalışır; bir Plugin'in dönüşü üstlenmesine ve sentetik yanıt döndürmesine ya da dönüşü tamamen sessize almasına olanak tanır.
• agent_end: tamamlandıktan sonra nihai ileti listesini ve çalıştırma meta verilerini inceleyin.
• before_compaction / after_compaction: Compaction döngülerini gözlemleyin veya notlandırın.
• before_tool_call / after_tool_call: araç parametrelerine/sonuçlarına araya girin.
• before_install: yerleşik tarama bulgularını inceleyin ve isteğe bağlı olarak skill veya Plugin kurulumlarını engelleyin.
• tool_result_persist: araç sonuçları OpenClaw'a ait bir oturum transkriptine yazılmadan önce bunları eşzamanlı olarak dönüştürün.
• message_received / message_sending / message_sent: gelen + giden ileti kancaları.
• session_start / session_end: oturum yaşam döngüsü sınırları.
• gateway_start / gateway_stop: Gateway yaşam döngüsü olayları.

Giden/araç korumaları için kanca karar kuralları:

• before_tool_call: { block: true } terminaldir ve daha düşük öncelikli işleyicileri durdurur.
• before_tool_call: { block: false } işlemsizdir ve önceki bir engeli temizlemez.
• before_install: { block: true } terminaldir ve daha düşük öncelikli işleyicileri durdurur.
• before_install: { block: false } işlemsizdir ve önceki bir engeli temizlemez.
• message_sending: { cancel: true } terminaldir ve daha düşük öncelikli işleyicileri durdurur.
• message_sending: { cancel: false } işlemsizdir ve önceki bir iptali temizlemez.

Kanca API'si ve kayıt ayrıntıları için bkz. Plugin kancaları.

Harness'lar bu kancaları farklı şekilde uyarlayabilir. Codex app-server harness'ı, belgelenmiş aynalanmış yüzeyler için OpenClaw Plugin kancalarını uyumluluk sözleşmesi olarak korurken, Codex yerel kancaları ayrı, daha düşük düzeyli bir Codex mekanizması olarak kalır.

# Akış + kısmi yanıtlar

• Asistan deltaları pi-agent-core'dan akışa verilir ve assistant olayları olarak yayılır.
• Blok akışı, text_end veya message_end üzerinde kısmi yanıtlar yayabilir.
• Akıl yürütme akışı ayrı bir akış olarak veya blok yanıtları olarak yayılabilir.
• Parçalama ve blok yanıt davranışı için bkz. Akış.

# Araç yürütme + mesajlaşma araçları

• Araç başlangıç/güncelleme/bitiş olayları tool akışında yayılır.
• Araç sonuçları, günlüğe yazılmadan/yayılmadan önce boyut ve görüntü payload'ları açısından temizlenir.
• Mesajlaşma aracı gönderimleri, yinelenen asistan onaylarını bastırmak için izlenir.

# Yanıt şekillendirme + bastırma

• Nihai payload'lar şunlardan derlenir:
  • asistan metni (ve isteğe bağlı akıl yürütme)
  • satır içi araç özetleri (verbose + izin verildiğinde)
  • model hata verdiğinde asistan hata metni
• Tam sessiz belirteç NO_REPLY / no_reply, giden payload'lardan filtrelenir.
• Mesajlaşma aracı tekrarları nihai payload listesinden kaldırılır.
• İşlenebilir payload kalmazsa ve bir araç hata verdiyse, yedek bir araç hata yanıtı yayılır (bir mesajlaşma aracı zaten kullanıcı tarafından görülebilir bir yanıt göndermediyse).

# Compaction + yeniden denemeler

• Otomatik Compaction, compaction akış olayları yayar ve yeniden denemeyi tetikleyebilir.
• Yeniden denemede, yinelenen çıktıyı önlemek için bellek içi arabellekler ve araç özetleri sıfırlanır.
• Compaction işlem hattı için bkz. Compaction.

# Olay akışları (bugün)

• lifecycle: subscribeEmbeddedPiSession tarafından yayılır (ve yedek olarak agentCommand tarafından)
• assistant: pi-agent-core'dan akışa verilen deltalar
• tool: pi-agent-core'dan akışa verilen araç olayları

# Sohbet kanalı işleme

• Asistan deltaları sohbet delta iletilerinde arabelleğe alınır.
• Yaşam döngüsü bitiş/hata üzerinde bir sohbet final yayılır.

# Zaman aşımları

• agent.wait varsayılanı: 30 sn (yalnızca bekleme). timeoutMs parametresi geçersiz kılar.
• Ajan çalışma zamanı: agents.defaults.timeoutSeconds varsayılanı 172800 sn'dir (48 saat); runEmbeddedPiAgent iptal zamanlayıcısında uygulanır.
• Cron çalışma zamanı: yalıtılmış ajan dönüşü timeoutSeconds, cron tarafından sahiplenilir. Zamanlayıcı bu zamanlayıcıyı yürütme başladığında başlatır, yapılandırılmış son tarihte alttaki çalıştırmayı iptal eder, ardından zaman aşımını kaydetmeden önce sınırlı temizlik çalıştırır; böylece eski bir alt oturum şeridi takılı tutamaz.
• Oturum canlılık tanılamaları: tanılamalar etkinken, diagnostics.stuckSessionWarnMs, gözlemlenen yanıt, araç, durum, blok veya ACP ilerlemesi olmayan uzun processing oturumlarını sınıflandırır. Etkin gömülü çalıştırmalar, model çağrıları ve araç çağrıları session.long_running olarak raporlanır; yakın zamanda ilerleme olmayan etkin iş session.stalled olarak raporlanır; session.stuck, etkin iş olmayan eski oturum defteri tutma için ayrılmıştır. Eski oturum defteri tutma, etkilenen oturum şeridini hemen serbest bırakır; takılmış gömülü çalıştırmalar yalnızca diagnostics.stuckSessionAbortMs sonrasında (varsayılan: en az 10 dakika ve uyarı eşiğinin 5 katı) iptal edilip boşaltılır; böylece kuyruğa alınmış iş, yalnızca yavaş olan çalıştırmaları kesmeden devam edebilir. Kurtarma, yapılandırılmış istenen/tamamlanan sonuçlar yayar ve tanılama durumu yalnızca aynı işleme nesli hâlâ güncelse boşta olarak işaretlenir. Yinelenen session.stuck tanılamaları, oturum değişmeden kaldığı sürece geri çekilir.
• Model boşta kalma zaman aşımı: OpenClaw, boşta kalma penceresinden önce yanıt parçaları gelmezse bir model isteğini iptal eder. models.providers.<id>.timeoutSeconds, yavaş yerel/kendi barındırılan sağlayıcılar için bu boşta kalma gözetleyicisini uzatır; aksi halde OpenClaw, yapılandırıldığında agents.defaults.timeoutSeconds kullanır ve varsayılan olarak 120 sn ile sınırlar. Açık model veya ajan zaman aşımı olmayan Cron tetiklemeli çalıştırmalar boşta kalma gözetleyicisini devre dışı bırakır ve cron dış zaman aşımına dayanır.
• Sağlayıcı HTTP isteği zaman aşımı: models.providers.<id>.timeoutSeconds, bağlanma, başlıklar, gövde, SDK istek zaman aşımı, toplam korumalı-fetch iptal işleme ve model akışı boşta kalma gözetleyicisi dahil olmak üzere bu sağlayıcının model HTTP fetch'leri için geçerlidir. Tüm ajan çalışma zamanı zaman aşımını yükseltmeden önce, Ollama gibi yavaş yerel/kendi barındırılan sağlayıcılar için bunu kullanın.

# İşlerin erken bitebileceği yerler

• Ajan zaman aşımı (iptal)
• AbortSignal (iptal)
• Gateway bağlantı kesilmesi veya RPC zaman aşımı
• agent.wait zaman aşımı (yalnızca bekleme, ajanı durdurmaz)

# İlgili

• Araçlar — kullanılabilir ajan araçları
• Kancalar — ajan yaşam döngüsü olaylarıyla tetiklenen olay güdümlü betikler
• Compaction — uzun konuşmaların nasıl özetlendiği
• Exec Onayları — kabuk komutları için onay geçitleri
• Düşünme — düşünme/akıl yürütme düzeyi yapılandırması