Ajan döngüsü

Aracı döngüsü, bir mesajı eylemlere ve bir yanıta dönüştüren, oturum başına serileştirilmiş çalıştırmadır: alım, bağlam oluşturma, model çıkarımı, araç yürütme, akış ve kalıcılık.

​

Giriş noktaları

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

​

Çalıştırma sırası

1. agent RPC parametreleri doğrular, oturumu çözümler (sessionKey/sessionId), oturum meta verilerini kalıcı hâle getirir ve hemen { runId, acceptedAt } döndürür.
2. agentCommand turu çalıştırır: model + düşünme/ayrıntı/iz varsayılanlarını çözümler, Skills anlık görüntüsünü yükler, runEmbeddedAgent çağrısını yapar ve gömülü döngü henüz bir tane yayınlamadıysa yedek bir yaşam döngüsü sonu/hatası yayınlar.
3. runEmbeddedAgent: çalıştırmaları oturum başına ve küresel kuyruklar aracılığıyla serileştirir, model + kimlik doğrulama profilini çözümler, OpenClaw oturumunu oluşturur, çalışma zamanı olaylarına abone olur, yardımcı/araç deltalarını akışla iletir, çalıştırma zaman aşımını uygular (süre dolduğunda iptal eder) ve yüklerle birlikte kullanım meta verilerini döndürür. Codex uygulama sunucusu turlarında ayrıca, kabul edilmiş bir tur terminal olayından önce uygulama sunucusu ilerlemesi üretmeyi durdurursa turu iptal eder.
4. subscribeEmbeddedAgentSession, çalışma zamanı olaylarını agent akışına köprüler: araç olaylarını stream: "tool"’ye, yardımcı deltalarını stream: "assistant"’e, yaşam döngüsü olaylarını stream: "lifecycle"’e (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun), bir runId üzerinde yaşam döngüsü sonu/hatasını bekler ve { status: ok|error|timeout, startedAt, endedAt, error? } döndürür.

​

Kuyruklama ve eşzamanlılık

Çalıştırmalar, oturum anahtarı (oturum hattı) başına ve isteğe bağlı olarak küresel bir hat üzerinden serileştirilerek araç/oturum yarışları önlenir. Mesajlaşma kanalları, bu hat sistemini besleyen bir kuyruk modu (yönlendirme/takip/toplama/kesme) seçer; bkz. Komut Kuyruğu. Transkript yazımları ayrıca oturum dosyasındaki bir oturum yazma kilidiyle korunur. Kilit süreç duyarlı ve dosya tabanlıdır; böylece süreç içi kuyruğu atlayan veya başka bir süreçten gelen yazıcıları yakalar. Yazıcılar, oturumu meşgul olarak bildirmeden önce varsayılan olarak 60 saniyeye kadar bekler (ortam geçersiz kılma değişkeni: OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS). Oturum yazma kilitleri varsayılan olarak yeniden girişli değildir. Tek bir mantıksal yazıcıyı korurken aynı kilidin alınmasını kasıtlı olarak iç içe yerleştiren bir yardımcı, allowReentrant: true ile açıkça etkinleştirilmelidir.

​

Oturum ve çalışma alanı hazırlığı

• Çalışma alanı çözümlenir ve oluşturulur; korumalı alan çalıştırmaları, bir korumalı alan ç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 eklenir.
• Önyükleme/bağlam dosyaları çözümlenir ve sistem istemine eklenir.
• Akış başlamadan önce bir oturum yazma kilidi alınır ve oturum transkript hedefi hazırlanır. Daha sonraki tüm transkript yeniden yazma, Compaction veya kesme yolları, SQLite transkript satırlarını değiştirmeden önce aynı kilidi almalıdır.

​

İstem oluşturma

Sistem istemi; OpenClaw’ın temel isteminden, Skills isteminden, önyükleme bağlamından ve çalıştırma başına geçersiz kılmalardan oluşturulur. Modele özgü sınırlar ve Compaction için ayrılmış belirteçler uygulanır. Modelin gördükleri için bkz. Sistem istemi.

​

Kancalar

OpenClaw’ın iki kanca sistemi vardır:

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

​

Dahili kancalar (Gateway kancaları)

• agent:bootstrap: sistem istemi kesinleşmeden önce önyükleme dosyaları oluşturulurken çalışır. Önyükleme bağlam dosyaları eklemek veya kaldırmak için kullanılır.
• Komut kancaları: /new, /reset, /stop ve diğer komut olayları (Kancalar belgesine bakın).

Kurulum ve örnekler için bkz. Kancalar.

​

Plugin kancaları

Bunlar aracı döngüsü veya Gateway işlem hattı içinde çalışır: Giden/araç korumaları için kanca karar kuralları:

• before_tool_call: { block: true } terminaldir ve daha düşük öncelikli işleyicileri durdurur. { block: false } işlem yapmaz ve önceki bir engeli temizlemez.
• before_install: yukarıdakiyle aynı terminal/işlemsiz semantiğine sahiptir. CLI kurulum ve güncelleme yollarını kapsaması gereken operatör sahipliğindeki kurulum izin verme/engelleme kararları için before_install değil, security.installPolicy kullanın.
• message_sending: { cancel: true } terminaldir ve daha düşük öncelikli işleyicileri durdurur. { cancel: false } işlem yapmaz ve önceki bir iptali temizlemez.

Kanca API’si ve kayıt ayrıntıları için bkz. Plugin kancaları. Donanımlar bu kancaları uyarlayabilir. Codex uygulama sunucusu donanımı, belgelenmiş yansıtılmış yüzeyler için uyumluluk sözleşmesi olarak OpenClaw Plugin kancalarını korur; Codex yerel kancaları ayrı, daha düşük seviyeli bir Codex mekanizmasıdır.

​

Akış

• Yardımcı deltaları, aracı çalışma zamanından assistant olayları olarak akışla iletilir.
• Blok akışı, text_end veya message_end üzerinde kısmi yanıtlar yayınlayabilir.
• Akıl yürütme akışı ayrı bir akış olabilir veya yanıtları engelleyebilir.
• Parçalama ve blok yanıt davranışı için bkz. Akış.

​

Araç yürütme

• Araç başlatma/güncelleme/sonlandırma olayları tool akışında yayınlanır.
• Araç sonuçları, günlüğe kaydedilmeden/yayınlanmadan önce boyut ve görüntü yükleri bakımından temizlenir.
• Mesajlaşma aracı gönderimleri, yinelenen yardımcı onaylarını engellemek için izlenir.

​

Yanıt şekillendirme

Nihai yükler; yardımcı metninden (isteğe bağlı akıl yürütmeyle birlikte), satır içi araç özetlerinden (ayrıntılı moddayken ve izin verildiğinde) ve model hata verdiğinde yardımcı hata metninden oluşturulur.

• Tam sessiz belirteç NO_REPLY, giden yüklerden filtrelenir.
• Mesajlaşma aracı yinelemeleri nihai yük listesinden kaldırılır.
• İşlenebilir yük kalmazsa ve bir araç hata verdiyse, bir mesajlaşma aracı kullanıcıya görünür bir yanıt göndermiş olmadığı sürece yedek bir araç hatası yanıtı yayınlanır.

​

Compaction ve yeniden denemeler

Otomatik Compaction, compaction akış olayları yayınlar ve yeniden denemeyi tetikleyebilir. Yeniden denemede, yinelenen çıktıyı önlemek için bellek içi arabellekler ve araç özetleri sıfırlanır. Bkz. Compaction.

​

Olay akışları

• lifecycle: subscribeEmbeddedAgentSession tarafından (ve yedek olarak agentCommand tarafından) yayınlanır.
• assistant: aracı çalışma zamanından akışla iletilen deltalar.
• tool: aracı çalışma zamanından akışla iletilen araç olayları.

Gateway, yaşam döngüsü ve araç başlatma/terminal olaylarını sınırlı, yalnızca meta veri içeren denetim defterine yansıtır. Bu yansıtma, istemleri, mesajları, araç bağımsız değişkenlerini, araç sonuçlarını veya ham hataları transkript/çalışma zamanı yolundan dışarı kopyalamadan kaynak bilgisini ve sonuç kodlarını kaydeder.

​

Sohbet kanalı işleme

Yardımcı deltaları, sohbet delta mesajlarında arabelleğe alınır. Yaşam döngüsü sonu/hatasında bir sohbet final yayınlanır.

​

Zaman aşımları

​

Takılı oturum tanılaması

Tanılama etkinleştirildiğinde, yerleşik iki dakikalık eşik; gözlemlenen yanıt, araç, durum, engel veya ACP ilerlemesi bulunmayan uzun processing oturumlarını sınıflandırır:

• Etkin gömülü çalışmalar, model çağrıları ve araç çağrıları session.long_running olarak bildirilir. Sahibi belirli sessiz model çağrıları, yavaş veya akışsız sağlayıcıların çok erken takılmış olarak işaretlenmemesi için iptal eşiğine kadar session.long_running olarak kalır.
• Yakın zamanda ilerleme göstermeyen etkin çalışma session.stalled olarak bildirilir. Sahibi belirli model çağrıları, iptal eşiğinde veya sonrasında session.stalled durumuna geçer; sahibi olmayan eski model/araç etkinliği uzun süreli olarak gizlenmez.
• session.stuck, sahibi olmayan eski model/araç etkinliğine sahip boşta bekleyen kuyruk oturumları dâhil olmak üzere kurtarılabilir eski oturum kayıtları için ayrılmıştır.

İptal eşiği en az 5 dakika ve uyarı eşiğinin 3 katıdır. Eski oturum kayıtları, kurtarma geçitleri geçildikten hemen sonra etkilenen oturum hattını serbest bırakır; takılmış gömülü çalışmalar yalnızca iptal eşiğinden sonra iptal edilip boşaltılır, böylece yalnızca yavaş çalışan işlemler kesilmeden kuyruktaki çalışma devam eder. Kurtarma, yapılandırılmış istenen/tamamlanan sonuçlar üretir; tanılama durumu yalnızca aynı işleme nesli hâlâ geçerliyse boşta olarak işaretlenir ve oturum değişmeden kaldığı sürece tekrarlanan session.stuck tanılamaları artan aralıklarla seyrekleştirilir.

​

İşlemlerin erken sonlanabileceği durumlar

• Agent zaman aşımı (iptal)
• AbortSignal (iptal)
• Gateway bağlantısının kesilmesi veya RPC zaman aşımı
• agent.wait zaman aşımı (yalnızca bekleme içindir, agent’ı durdurmaz)

​

İlgili

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