Alt aracılar

Alt ajanlar, mevcut bir ajan çalıştırmasından başlatılan arka plan ajan çalıştırmalarıdır. Kendi oturumlarında (agent:<agentId>:subagent:<uuid>) çalışırlar ve tamamlandıklarında sonuçlarını istekte bulunan sohbet kanalına duyururlar. Her alt ajan çalıştırması bir arka plan görevi olarak izlenir.

Birincil hedefler:

• Ana çalıştırmayı engellemeden "araştırma / uzun görev / yavaş araç" çalışmalarını paralelleştirmek.
• Alt ajanları varsayılan olarak yalıtılmış tutmak (oturum ayrımı + isteğe bağlı korumalı alan).
• Araç yüzeyinin kötüye kullanımını zorlaştırmak: alt ajanlar varsayılan olarak oturum araçlarını almaz.
• Orkestratör desenleri için yapılandırılabilir iç içe geçme derinliğini desteklemek.

Slash komutu

Geçerli oturum için alt ajan çalıştırmalarını incelemek üzere /subagents kullanın:

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info, çalıştırma meta verilerini (durum, zaman damgaları, oturum kimliği, döküm yolu, temizleme) gösterir. Sınırlı ve güvenlik filtreli bir geri çağırma görünümü için sessions_history kullanın; ham tam döküme ihtiyacınız olduğunda diskteki döküm yolunu inceleyin.

Konu bağlama denetimleri

Bu komutlar kalıcı konu bağlamalarını destekleyen kanallarda çalışır. Aşağıdaki Konu destekleyen kanallar bölümüne bakın.

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

Başlatma davranışı

Ajanlar sessions_spawn ile arka plan alt ajanları başlatır. Alt ajan tamamlanmaları iç ebeveyn oturum olayları olarak döner; ebeveyn/istekte bulunan ajan kullanıcıya dönük bir güncellemenin gerekip gerekmediğine karar verir.

Bağlam modları

Yerel alt ajanlar, çağıran açıkça geçerli dökümü çatallamayı istemedikçe yalıtılmış olarak başlar.

fork seçeneğini ölçülü kullanın. Bu, bağlama duyarlı delegasyon içindir; net bir görev istemi yazmanın yerine geçmez.

Araç: sessions_spawn

Global subagent hattında deliver: false ile bir alt ajan çalıştırması başlatır, ardından bir duyuru adımı çalıştırır ve duyuru yanıtını istekte bulunan sohbet kanalına gönderir.

Kullanılabilirlik, çağıranın etkin araç ilkesine bağlıdır. coding ve full profilleri varsayılan olarak sessions_spawn sunar. messaging profili sunmaz; iş devretmesi gereken ajanlar için tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] ekleyin veya tools.profile: "coding" kullanın. Kanal/grup, sağlayıcı, korumalı alan ve ajan başına izin/verme ilkeleri profil aşamasından sonra aracı yine de kaldırabilir. Etkin araç listesini doğrulamak için aynı oturumdan /tools kullanın.

Varsayılanlar:

• Model: agents.defaults.subagents.model (veya ajan başına agents.list[].subagents.model) ayarlamadığınız sürece yerel alt ajanlar çağıranı devralır. ACP çalışma zamanı başlatmaları, mevcut olduğunda aynı yapılandırılmış alt ajan modelini kullanır; aksi takdirde ACP harness kendi varsayılanını korur. Açık bir sessions_spawn.model yine de kazanır.
• Thinking: agents.defaults.subagents.thinking (veya ajan başına agents.list[].subagents.thinking) ayarlamadığınız sürece yerel alt ajanlar çağıranı devralır. ACP çalışma zamanı başlatmaları, seçilen model için agents.defaults.models["provider/model"].params.thinking değerini de uygular. Açık bir sessions_spawn.thinking yine de kazanır.
• Çalıştırma zaman aşımı: OpenClaw, ayarlandığında agents.defaults.subagents.runTimeoutSeconds kullanır; aksi takdirde 0 değerine (zaman aşımı yok) geri döner. sessions_spawn çağrı başına zaman aşımı geçersiz kılmalarını kabul etmez.
• Görev teslimi: yerel alt ajanlar devredilen görevi ilk görünür [Subagent Task] mesajlarında alır. Alt ajan sistem istemi, görevin gizli bir kopyasını değil çalışma zamanı kurallarını ve yönlendirme bağlamını taşır.

Kabul edilen yerel alt ajan başlatmaları, araç sonucunda çözümlenmiş çocuk model meta verilerini içerir: resolvedModel uygulanan model başvurusunu içerir ve resolvedProvider, başvuruda varsa sağlayıcı önekini içerir.

Delegasyon istem modu

agents.defaults.subagents.delegationMode yalnızca istem rehberliğini denetler; araç ilkesini değiştirmez veya delegasyonu zorunlu kılmaz.

• suggest (varsayılan): daha büyük veya daha yavaş işler için alt ajanları kullanmaya yönelik standart istem yönlendirmesini korur.
• prefer: ana ajana yanıt verebilir kalmasını ve doğrudan yanıttan daha kapsamlı olan her şeyi sessions_spawn üzerinden devretmesini söyler.

Ajan başına geçersiz kılmalar agents.list[].subagents.delegationMode kullanır.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

Araç parametreleri

Görev adları ve hedefleme

taskName, orkestrasyon için modele görünen bir tanıtıcıdır, oturum anahtarı değildir. Bir koordinatörün daha sonra ilgili alt öğeyi incelemesi gerekebileceğinde review_subagents, linux_validation veya docs_update gibi kararlı alt adları için kullanın.

Hedef çözümleme tam taskName eşleşmelerini ve belirsiz olmayan öneki kabul eder. Eşleştirme, numaralı /subagents hedeflerinin kullandığı aynı etkin/yakın hedef penceresiyle sınırlıdır; bu nedenle eski tamamlanmış bir alt öğe, yeniden kullanılan bir tanıtıcıyı belirsiz hale getirmez. İki etkin veya yakın alt öğe aynı taskName değerini paylaşıyorsa hedef belirsizdir; bunun yerine liste dizinini, oturum anahtarını veya çalıştırma kimliğini kullanın.

Ayrılmış hedefler last ve all, zaten denetim anlamları taşıdıkları için geçerli taskName değerleri değildir.

Araç: sessions_yield

Geçerli model dönüşünü sonlandırır ve başta alt aracı tamamlama olayları olmak üzere çalışma zamanı olaylarının sonraki ileti olarak gelmesini bekler. İstekte bulunan, bu tamamlamalar gelene kadar nihai yanıt üretemediğinde gerekli alt çalışmayı başlattıktan sonra kullanın.

sessions_yield bekleme ilkelidir. Alt öğe tamamlanmasını algılamak için onu subagents, sessions_list, sessions_history üzerinde yoklama döngüleriyle, kabuk sleep komutuyla veya süreç yoklamasıyla değiştirmeyin.

Yalnızca oturumun etkin araç listesi bunu içerdiğinde sessions_yield kullanın. Bazı en küçük veya özel araç profilleri, sessions_yield sunmadan sessions_spawn ve subagents sunabilir; bu durumda tamamlanmayı beklemek için yoklama döngüsü icat etmeyin.

Etkin alt öğeler olduğunda OpenClaw, normal dönüşlere kompakt ve çalışma zamanı tarafından oluşturulmuş bir Active Subagents istem bloğu enjekte eder; böylece istekte bulunan, yoklama yapmadan geçerli alt oturumları, çalıştırma kimliklerini, durumları, etiketleri, görevleri ve taskName diğer adlarını görebilir. Bu bloktaki görev ve etiket alanları, kullanıcı/model tarafından sağlanan başlatma argümanlarından gelebilecekleri için talimat değil, veri olarak alıntılanır.

Araç: subagents

İstekte bulunan oturumun sahip olduğu başlatılmış alt aracı çalıştırmalarını listeler. Geçerli istekte bulunanla sınırlıdır; bir alt öğe yalnızca kendi denetlediği alt öğeleri görebilir.

İsteğe bağlı durum ve hata ayıklama için subagents kullanın. Tamamlama olaylarını beklemek için sessions_yield kullanın.

İş parçacığına bağlı oturumlar

Bir kanal için iş parçacığı bağlamaları etkinleştirildiğinde, bir alt aracı bir iş parçacığına bağlı kalabilir; böylece o iş parçacığındaki takip kullanıcı iletileri aynı alt aracı oturumuna yönlendirilmeye devam eder.

İş parçacığını destekleyen kanallar

Oturum bağlama adaptörü olan herhangi bir kanal, kalıcı iş parçacığına bağlı alt aracı oturumlarını destekleyebilir (thread: true ile sessions_spawn). Paketlenmiş adaptörler şu anda Discord iş parçacıklarını, Matrix iş parçacıklarını, Telegram forum konularını ve Feishu için geçerli konuşma bağlamalarını içerir. Etkinleştirme, zaman aşımları ve spawnSessions için kanal başına threadBindings yapılandırma anahtarlarını kullanın.

Hızlı akış

Elle denetimler

Yapılandırma anahtarları

• Küresel varsayılan: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Kanal geçersiz kılma ve başlatma otomatik bağlama anahtarları adaptöre özeldir. Yukarıdaki İş parçacığını destekleyen kanallar bölümüne bakın.

Geçerli adaptör ayrıntıları için Yapılandırma başvurusu ve Slash komutları bölümlerine bakın.

İzin listesi

İstekte bulunan oturum sandbox içindeyse, sessions_spawn sandbox dışında çalışacak hedefleri reddeder.

Keşif

Şu anda sessions_spawn için hangi aracı kimliklerine izin verildiğini görmek için agents_list kullanın. Yanıt, çağıranların OpenClaw, Codex uygulama sunucusu ve diğer yapılandırılmış yerel çalışma zamanlarını ayırt edebilmesi için listelenen her aracının etkin modelini ve gömülü çalışma zamanı meta verilerini içerir.

allowAgents girdileri agents.list[] içindeki yapılandırılmış aracı kimliklerini göstermelidir. ["*"], yapılandırılmış herhangi bir hedef aracı artı istekte bulunan anlamına gelir. Bir aracı yapılandırması silinir ancak kimliği allowAgents içinde kalırsa, sessions_spawn bu kimliği reddeder ve agents_list onu atlar. Eski izin listesi girdilerini temizlemek için openclaw doctor --fix çalıştırın veya hedef, varsayılanları devralırken başlatılabilir kalmalıysa en küçük bir agents.list[] girdisi ekleyin.

Otomatik arşivleme

• Alt aracı oturumları agents.defaults.subagents.archiveAfterMinutes sonrasında otomatik olarak arşivlenir (varsayılan 60).
• Arşivleme sessions.delete kullanır ve dökümü *.deleted.<timestamp> olarak yeniden adlandırır (aynı klasör).
• cleanup: "delete" duyurudan hemen sonra arşivler (dökümü yeniden adlandırma yoluyla yine saklar).
• Otomatik arşivleme en iyi çabayla yapılır; Gateway yeniden başlatılırsa bekleyen zamanlayıcılar kaybolur.
• Yapılandırılmış çalıştırma zaman aşımları otomatik arşivleme yapmaz; yalnızca çalıştırmayı durdurur. Oturum otomatik arşivlemeye kadar kalır.
• Otomatik arşivleme, derinlik 1 ve derinlik 2 oturumlarına eşit şekilde uygulanır.
• Tarayıcı temizliği arşiv temizliğinden ayrıdır: döküm/oturum kaydı tutulsa bile izlenen tarayıcı sekmeleri/süreçleri çalıştırma bittiğinde en iyi çabayla kapatılır.

İç içe alt aracılar

Varsayılan olarak, alt aracılar kendi alt aracılarını başlatamaz (maxSpawnDepth: 1). Bir düzey iç içe yerleştirmeyi etkinleştirmek için maxSpawnDepth: 2 ayarlayın: orkestratör deseni: ana → orkestratör alt aracı → çalışan alt-alt aracılar.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // alt aracıların alt öğe başlatmasına izin ver (varsayılan: 1)        maxChildrenPerAgent: 5, // aracı oturumu başına en fazla etkin alt öğe (varsayılan: 5)        maxConcurrent: 8, // küresel eşzamanlılık hattı sınırı (varsayılan: 8)        runTimeoutSeconds: 900, // sessions_spawn için varsayılan zaman aşımı (0 = zaman aşımı yok)        announceTimeoutMs: 120000, // çağrı başına Gateway duyuru zaman aşımı      },    },  },}

Derinlik düzeyleri

Duyuru zinciri

Sonuçlar zincirde yukarı doğru akar:

1. Derinlik-2 çalışanı tamamlanır → üst ögesine (derinlik-1 orkestratörü) duyurur.
2. Derinlik-1 orkestratörü duyuruyu alır, sonuçları sentezler, tamamlanır → ana ajana duyurur.
3. Ana ajan duyuruyu alır ve kullanıcıya iletir.

Her seviye yalnızca doğrudan alt ögelerinden gelen duyuruları görür.

Derinliğe göre araç politikası

• Rol ve denetim kapsamı, oluşturma sırasında oturum meta verilerine yazılır. Bu, düz veya geri yüklenmiş oturum anahtarlarının yanlışlıkla orkestratör ayrıcalıklarını geri kazanmasını önler.
• Derinlik 1 (orkestratör, maxSpawnDepth >= 2 olduğunda): alt ögeler oluşturabilmesi ve durumlarını inceleyebilmesi için sessions_spawn, subagents, sessions_list, sessions_history alır. Diğer oturum/sistem araçları reddedilmiş kalır.
• Derinlik 1 (yaprak, maxSpawnDepth == 1 olduğunda): oturum aracı yoktur (geçerli varsayılan davranış).
• Derinlik 2 (yaprak çalışan): oturum aracı yoktur — sessions_spawn, derinlik 2'de her zaman reddedilir. Daha fazla alt öge oluşturamaz.

Ajan başına oluşturma sınırı

Her ajan oturumu (herhangi bir derinlikte) aynı anda en fazla maxChildrenPerAgent (varsayılan 5) etkin alt ögeye sahip olabilir. Bu, tek bir orkestratörden kontrolsüz yayılımı önler.

Zincirleme durdurma

Bir derinlik-1 orkestratörünü durdurmak, tüm derinlik-2 alt ögelerini otomatik olarak durdurur:

• Ana sohbette /stop, tüm derinlik-1 ajanlarını durdurur ve derinlik-2 alt ögelerine zincirleme uygulanır.

Kimlik doğrulama

Alt ajan kimlik doğrulaması, oturum türüne göre değil ajan kimliğine göre çözümlenir:

• Alt ajan oturum anahtarı agent:<agentId>:subagent:<uuid> şeklindedir.
• Kimlik doğrulama deposu, o ajanın agentDir konumundan yüklenir.
• Ana ajanın kimlik doğrulama profilleri yedek olarak birleştirilir; çakışmalarda ajan profilleri ana profilleri geçersiz kılar.

Birleştirme eklemelidir, bu nedenle ana profiller yedek olarak her zaman kullanılabilir. Ajan başına tamamen yalıtılmış kimlik doğrulama henüz desteklenmez.

Duyuru

Alt ajanlar bir duyuru adımı aracılığıyla geri bildirim yapar:

• Duyuru adımı, istekte bulunan oturumda değil alt ajan oturumunun içinde çalışır.
• Alt ajan tam olarak ANNOUNCE_SKIP yanıtını verirse hiçbir şey gönderilmez.
• En son asistan metni tam sessiz belirteç olan NO_REPLY / no_reply ise, daha önce görünür ilerleme olsa bile duyuru çıktısı bastırılır.

Teslim, istekte bulunanın derinliğine bağlıdır:

• Üst düzey istek oturumları, harici teslim (deliver=true) ile takip agent çağrısı kullanır.
• İç içe istek yapan subagent oturumları, orkestratörün alt öge sonuçlarını oturum içinde sentezleyebilmesi için dahili takip enjeksiyonu (deliver=false) alır.
• İç içe istek yapan subagent oturumu yoksa OpenClaw, kullanılabildiğinde o oturumun istekte bulunanına geri döner.

Üst düzey istek oturumları için tamamlama modu doğrudan teslim, önce bağlı konuşma/iş parçacığı rotasını ve hook geçersiz kılmasını çözer, ardından eksik kanal-hedef alanlarını istekte bulunan oturumun depolanmış rotasından doldurur. Bu, tamamlama kaynağı yalnızca kanalı tanımlasa bile tamamlamaların doğru sohbet/konuda kalmasını sağlar.

Alt öge tamamlama toplaması, iç içe tamamlama bulguları oluşturulurken geçerli istek çalıştırmasıyla kapsamlandırılır; bu, eski önceki çalışma alt öge çıktılarının geçerli duyuruya sızmasını önler. Duyuru yanıtları, kanal bağdaştırıcılarında kullanılabildiğinde iş parçacığı/konu yönlendirmesini korur.

Duyuru bağlamı

Duyuru bağlamı, kararlı bir dahili olay bloğuna normalleştirilir:

Terminalde başarısız olan çalıştırmalar, yakalanan yanıt metnini yeniden oynatmadan başarısızlık durumu bildirir. Tool/toolResult çıktısı alt öge sonuç metnine yükseltilmez.

İstatistik satırı

Duyuru yükleri sonda bir istatistik satırı içerir (sarmalanmış olsa bile):

• Çalışma zamanı (ör. runtime 5m12s).
• Token kullanımı (girdi/çıktı/toplam).
• Model fiyatlandırması yapılandırıldığında tahmini maliyet (models.providers.*.models[].cost).
• Ana ajanın sessions_history aracılığıyla geçmişi alabilmesi veya diskteki dosyayı inceleyebilmesi için sessionKey, sessionId ve transkript yolu.

Dahili meta veriler yalnızca orkestrasyon içindir; kullanıcıya dönük yanıtlar normal asistan sesiyle yeniden yazılmalıdır.

Neden sessions_history tercih edilmeli

sessions_history daha güvenli orkestrasyon yoludur:

• Asistan geri çağırması önce normalleştirilir: düşünme etiketleri kaldırılır; <relevant-memories> / <relevant_memories> iskeleti kaldırılır; düz metin tool-call XML yük blokları (<tool_call>, <function_call>, <tool_calls>, <function_calls>) kaldırılır, temiz kapanmayan kırpılmış yükler dahil; düşürülmüş tool-call/result iskeleti ve tarihsel bağlam işaretleri kaldırılır; sızmış model denetim belirteçleri (<|assistant|>, diğer ASCII <|...|>, tam genişlikli <｜...｜>) kaldırılır; hatalı biçimlendirilmiş MiniMax tool-call XML kaldırılır.
• Kimlik bilgisi/token benzeri metin sansürlenir.
• Uzun bloklar kırpılabilir.
• Çok büyük geçmişler daha eski satırları düşürebilir veya aşırı büyük bir satırı [sessions_history omitted: message too large] ile değiştirebilir.
• Eski transkript pencerelerinde geriye doğru sayfalama yapmak için mevcut olduğunda nextOffset kullanın.
• Tam bayt bayt transkripte ihtiyacınız olduğunda ham disk üzerindeki transkript incelemesi yedek yoldur.

Araç politikası

Alt ajanlar önce ebeveyn veya hedef ajanla aynı profil ve araç politikası iş hattını kullanır. Ardından OpenClaw, alt ajan kısıtlama katmanını uygular.

Kısıtlayıcı bir tools.profile yoksa alt ajanlar mesaj aracı, oturum araçları ve sistem araçları hariç tüm araçları alır:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

sessions_history burada da sınırlı, temizlenmiş bir geri çağırma görünümü olarak kalır — ham transkript dökümü değildir.

maxSpawnDepth >= 2 olduğunda, derinlik-1 orkestratör alt ajanları ayrıca alt ögelerini yönetebilmeleri için sessions_spawn, subagents, sessions_list ve sessions_history alır.

Yapılandırma ile geçersiz kılma

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow son bir yalnızca izin filtresidir. Zaten çözülmüş araç kümesini daraltabilir, ancak tools.profile tarafından kaldırılmış bir aracı geri ekleyemez. Örneğin, tools.profile: "coding" web_search/web_fetch içerir, ancak browser aracını içermez. Coding profilli alt ajanların tarayıcı otomasyonu kullanmasına izin vermek için browser'ı profil aşamasında ekleyin:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Yalnızca bir ajanın tarayıcı otomasyonu alması gerektiğinde ajan başına agents.list[].tools.alsoAllow: ["browser"] kullanın.

Eşzamanlılık

Alt ajanlar özel bir süreç içi kuyruk hattı kullanır:

• Hat adı: subagent
• Eşzamanlılık: agents.defaults.subagents.maxConcurrent (varsayılan 8)

Canlılık ve kurtarma

OpenClaw, endedAt yokluğunu bir alt ajanın hâlâ canlı olduğuna dair kalıcı kanıt olarak ele almaz. Eski çalışma penceresinden daha eski sonlandırılmamış çalıştırmalar /subagents list, durum özetleri, alt tamamlama geçidi ve oturum başına eşzamanlılık kontrollerinde etkin/beklemede olarak sayılmayı bırakır.

Bir Gateway yeniden başlatmasından sonra, alt oturumları abortedLastRun: true olarak işaretlenmedikçe eski sonlandırılmamış geri yüklenmiş çalıştırmalar budanır. Bu yeniden başlatmada iptal edilmiş alt oturumlar, iptal işaretini temizlemeden önce sentetik bir sürdürme mesajı gönderen alt ajan yetim kurtarma akışı aracılığıyla kurtarılabilir kalır.

Otomatik yeniden başlatma kurtarması alt oturum başına sınırlıdır. Aynı alt ajan alt ögesi hızlı yeniden sıkışma penceresi içinde tekrar tekrar yetim kurtarma için kabul edilirse OpenClaw, o oturumda bir kurtarma mezar taşı kalıcılaştırır ve sonraki yeniden başlatmalarda onu otomatik sürdürmeyi durdurur. Görev kaydını uzlaştırmak için openclaw tasks maintenance --apply veya mezar taşlı oturumlardaki eski iptal edilmiş kurtarma bayraklarını temizlemek için openclaw doctor --fix çalıştırın.

Durdurma

• İstekte bulunan sohbette /stop göndermek, istekte bulunan oturumu iptal eder ve ondan oluşturulmuş tüm etkin alt ajan çalıştırmalarını durdurur; bu, iç içe alt ögelere zincirleme uygulanır.

Sınırlamalar

• Alt ajan duyurusu en iyi çaba esasına dayanır. Gateway yeniden başlatılırsa bekleyen "geri duyur" işi kaybolur.
• Alt ajanlar hâlâ aynı gateway süreci kaynaklarını paylaşır; maxConcurrent değerini bir emniyet valfi olarak ele alın.
• sessions_spawn her zaman engellemesizdir: hemen { status: "accepted", runId, childSessionKey } döndürür.
• Alt ajan bağlamı yalnızca AGENTS.md ve TOOLS.md enjekte eder (SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md veya BOOTSTRAP.md yok). Codex yerel subagents aynı sınırı izler: TOOLS.md devralınan Codex iş parçacığı talimatlarında kalırken, yalnızca ebeveyne ait persona, kimlik ve kullanıcı dosyaları, alt ögelerin bunları klonlamaması için tur kapsamlı iş birliği talimatları olarak enjekte edilir.
• Maksimum iç içe geçme derinliği 5'tir (maxSpawnDepth aralığı: 1–5). Çoğu kullanım durumu için derinlik 2 önerilir.
• maxChildrenPerAgent, oturum başına etkin alt ögeleri sınırlar (varsayılan 5, aralık 1–20).

İlgili

• ACP ajanları
• Ajan gönderimi
• Arka plan görevleri
• Çok ajanlı sandbox araçları