Ajan Döngüsü (OpenClaw)¶

Ajanik bir döngü, bir ajanın tam “gerçek” çalıştırmasıdır: alım → bağlamın birleştirilmesi → model çıkarımı → araç yürütme → akış halinde yanıtlar → kalıcılık. Bu, bir mesajı eylemlere ve nihai bir yanıta dönüştüren, oturum durumunu tutarlı tutan yetkili yoldur.

OpenClaw’da bir döngü, oturum başına tekil ve serileştirilmiş bir çalıştırmadır; model düşünürken, araçları çağırırken ve çıktıyı akış halinde gönderirken yaşam döngüsü ve akış olayları üretir. Bu doküman, 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 çözümler (sessionKey/sessionId), oturum meta verisini kalıcı hale getirir ve hemen { runId, acceptedAt } döndürür.
2. agentCommand ajanı çalıştırır: - model + düşünme/ayrıntı varsayılanlarını çözümler - Skills anlık görüntüsünü yükler - runEmbeddedPiAgent’yı (pi-agent-core çalışma zamanı) çağırır - gömülü döngü bir tane yaymazsa yaşam döngüsü sonu/hata olayı yayar
3. runEmbeddedPiAgent: - oturum başına ve global kuyruklar üzerinden çalıştırmaları serileştirir - modeli + kimlik doğrulama profilini çözümler ve pi oturumunu oluşturur - pi olaylarına abone olur ve asistan/araç deltalarını akış halinde iletir - zaman aşımını uygular -> aşılırsa çalıştırmayı iptal eder - yükleri + kullanım meta verisini 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, waitForAgentJob kullanır: - runId için yaşam döngüsü bitiş/hatayı bekler - { status: ok|error|timeout, startedAt, endedAt, error? } döndürür

Kuyruklama + eşzamanlılık¶

• Çalıştırmalar, oturum anahtarı başına (oturum şeridi) ve isteğe bağlı olarak global 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. Command Queue.

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

• Çalışma alanı çözümlenir ve oluşturulur; sandbox’lı çalıştırmalar bir sandbox çalışma alanı köküne yönlendirebilir.
• Skills yüklenir (veya bir anlık görüntüden yeniden kullanılır) ve ortama ile isteme enjekte edilir.
• Bootstrap/bağlam dosyaları çözümlenir ve sistem istemi raporuna enjekte edilir.
• Bir oturum yazma kilidi alınır; SessionManager akıştan önce açılır ve hazırlanır.

İstem oluşturma + sistem istemi¶

• Sistem istemi, OpenClaw’ın temel istemi, Skills istemi, bootstrap bağlamı ve çalıştırma başına geçersiz kılmalarla oluşturulur.
• Modele özgü sınırlar ve sıkıştırma için ayrılan belirteçler uygulanır.
• Modelin ne gördüğü için System prompt bölümüne bakın.

Kanca noktaları (nerede araya girebilirsiniz)¶

OpenClaw’da iki kanca sistemi vardır:

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

Dahili kancalar (Gateway kancaları)¶

• agent:bootstrap: sistem istemi kesinleşmeden ö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 Hooks bölümüne bakın.

Eklenti kancaları (ajan + gateway yaşam döngüsü)¶

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

• before_agent_start: çalıştırma başlamadan önce bağlam enjekte eder veya sistem istemini geçersiz kılar.
• agent_end: tamamlandıktan sonra nihai mesaj listesini ve çalıştırma meta verisini inceler.
• before_compaction / after_compaction: sıkıştırma döngülerini gözlemler veya notlar.
• before_tool_call / after_tool_call: araç parametrelerini/sonuçlarını yakalar.
• tool_result_persist: araç sonuçlarını oturum dökümüne yazılmadan önce senkron olarak dönüştürür.
• message_received / message_sending / message_sent: gelen + giden mesaj 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ı.

Kanca API’si ve kayıt ayrıntıları için Plugins bölümüne bakın.

Akış + kısmi yanıtlar¶

• Asistan deltaları pi-agent-core’dan akış halinde alınır ve assistant olayları olarak yayılır.
• Blok halinde akış, kısmi yanıtları text_end veya message_end üzerinde 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 Streaming bölümüne bakın.

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

• Araç başlatma/güncelleme/bitiş olayları tool akışında yayılır.
• Araç sonuçları, günlüğe kaydetmeden/yaymadan önce boyut ve görsel yükler açısından temizlenir.
• Mesajlaşma aracı gönderimleri, yinelenen asistan onaylarını bastırmak için izlenir.

Yanıt şekillendirme + bastırma¶

• Nihai yükler şunlardan oluşturulur:
• asistan metni (ve isteğe bağlı akıl yürütme)
• satır içi araç özetleri (ayrıntı açık + izinliyse)
• model hata verdiğinde asistan hata metni
• NO_REPLY, sessiz bir belirteç olarak kabul edilir ve giden yüklerden filtrelenir.
• Mesajlaşma aracı yinelenmeleri nihai yük listesinden kaldırılır.
• Görsellenebilir yük kalmazsa ve bir araç hata verdiyse, bir yedek araç hata yanıtı yayılır (bir mesajlaşma aracı zaten kullanıcıya görünür bir yanıt göndermediyse).

Sıkıştırma + yeniden denemeler¶

• Otomatik sıkıştırma compaction akış olaylarını yayar ve bir yeniden denemeyi tetikleyebilir.
• Yeniden denemede, yinelenen çıktıyı önlemek için bellek içi arabellekler ve araç özetleri sıfırlanır.
• Sıkıştırma hattı için Compaction bölümüne bakın.

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

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

Sohbet kanalı işleme¶

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

Zaman aşımları¶

• agent.wait varsayılan: 30 sn (yalnızca bekleme). timeoutMs parametresiyle geçersiz kılınır.
• Ajan çalışma zamanı: agents.defaults.timeoutSeconds varsayılan 600 sn; runEmbeddedPiAgent iptal zamanlayıcısında uygulanır.

Erken sona erebilecek durumlar¶

• 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)