Subagen

Subagen adalah proses agen latar belakang yang dibuat dari proses agen yang sudah ada. Masing-masing berjalan dalam sesinya sendiri (agent:<agentId>:subagent:<uuid>) dan, setelah selesai, mengumumkan hasilnya kembali ke saluran obrolan peminta. Setiap proses subagen dilacak sebagai tugas latar belakang.

Tujuan:

• Memparalelkan riset, tugas panjang, dan pekerjaan alat yang lambat tanpa memblokir proses utama.
• Menjaga subagen tetap terisolasi secara default (pemisahan sesi, sandbox opsional).
• Menjaga agar permukaan alat sulit disalahgunakan: secara default, subagen tidak mendapatkan alat sesi atau pesan.
• Mendukung kedalaman penyarangan yang dapat dikonfigurasi untuk pola orkestrator.

Perintah garis miring

/subagents memeriksa proses subagen untuk sesi saat ini:

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

/subagents info menampilkan metadata proses (status, stempel waktu, id sesi, jalur transkrip, pembersihan). /subagents log mencetak giliran obrolan terbaru untuk suatu proses; tambahkan token tools untuk menyertakan pesan pemanggilan/hasil alat (secara default dihilangkan). Gunakan sessions_history untuk tampilan ingatan terbatas yang difilter demi keamanan dari dalam giliran agen, atau periksa jalur transkrip pada disk untuk transkrip lengkap mentah.

Kontrol pengikatan utas

Perintah ini berfungsi pada saluran dengan pengikatan utas persisten. Lihat Saluran yang mendukung utas di bawah.

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

Perilaku pembuatan

Agen memulai subagen latar belakang dengan alat sessions_spawn. Penyelesaian dikembalikan sebagai peristiwa internal sesi induk; agen induk/peminta memutuskan apakah pembaruan yang terlihat oleh pengguna diperlukan.

Mode konteks

Subagen native dimulai secara terisolasi kecuali pemanggil secara eksplisit meminta pencabangan transkrip saat ini.

Gunakan fork secara hemat. Mode ini ditujukan untuk pendelegasian yang sensitif terhadap konteks, bukan pengganti penulisan perintah tugas yang jelas.

Alat: sessions_spawn

Memulai proses subagen dengan deliver: false pada jalur global subagent, lalu menjalankan langkah pengumuman dan memposting balasan pengumuman ke saluran obrolan peminta.

Ketersediaan bergantung pada kebijakan alat efektif milik pemanggil. Profil bawaan coding mencakup sessions_spawn; messaging dan minimal tidak mencakupnya. full mengizinkan setiap alat. Tambahkan tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"], atau gunakan tools.profile: "coding", untuk agen dengan profil lebih terbatas yang tetap harus mendelegasikan pekerjaan. Kebijakan izin/tolak untuk saluran/grup, penyedia, sandbox, dan per agen masih dapat menghapus alat setelah tahap profil. Gunakan /tools dari sesi yang sama untuk mengonfirmasi daftar alat efektif.

Nilai default:

• Model: subagen native mewarisi pemanggil kecuali Anda menetapkan agents.defaults.subagents.model (atau agents.list[].subagents.model per agen). Pembuatan runtime ACP menggunakan model subagen terkonfigurasi yang sama jika tersedia; jika tidak, harness ACP mempertahankan nilai defaultnya sendiri. sessions_spawn.model yang ditetapkan secara eksplisit tetap diprioritaskan.
• Pemikiran: subagen native mewarisi pemanggil kecuali Anda menetapkan agents.defaults.subagents.thinking (atau agents.list[].subagents.thinking per agen). Pembuatan runtime ACP juga menerapkan agents.defaults.models["provider/model"].params.thinking untuk model yang dipilih. sessions_spawn.thinking yang ditetapkan secara eksplisit tetap diprioritaskan.
• Batas waktu proses: OpenClaw menggunakan agents.defaults.subagents.runTimeoutSeconds jika ditetapkan; jika tidak, nilainya kembali ke 0 (tanpa batas waktu). sessions_spawn tidak menerima penggantian batas waktu per panggilan.
• Pengiriman tugas: subagen native menerima tugas yang didelegasikan dalam pesan [Subagent Task] pertama yang terlihat. Perintah sistem subagen membawa aturan runtime dan konteks perutean, bukan duplikat tugas tersembunyi.

Pembuatan subagen native yang diterima menyertakan metadata model agen turunan yang telah ditetapkan dalam hasil alat: resolvedModel berisi referensi model yang diterapkan dan resolvedProvider berisi prefiks penyedia ketika referensi tersebut memilikinya.

Mode perintah pendelegasian

agents.defaults.subagents.delegationMode hanya mengontrol panduan perintah; pengaturan ini tidak mengubah kebijakan alat atau memberlakukan pendelegasian.

• suggest (default): mempertahankan dorongan perintah standar untuk menggunakan subagen bagi pekerjaan yang lebih besar atau lebih lambat.
• prefer: memberi tahu agen utama agar tetap responsif dan mendelegasikan segala sesuatu yang lebih rumit daripada balasan langsung melalui sessions_spawn.

Penggantian per agen: agents.list[].subagents.delegationMode.

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

Parameter alat

Nama tugas dan penargetan

taskName adalah nama pengenal yang ditujukan untuk model guna orkestrasi, bukan kunci sesi. Gunakan untuk nama turunan stabil seperti review_subagents, linux_validation, atau docs_update saat koordinator mungkin perlu memeriksa turunan tersebut nanti.

Resolusi target menerima kecocokan persis taskName dan prefiks yang tidak ambigu. Pencocokan dibatasi pada jendela target aktif/terbaru yang sama seperti yang digunakan oleh target /subagents bernomor, sehingga turunan selesai yang sudah usang tidak membuat nama pengenal yang digunakan kembali menjadi ambigu. Jika dua turunan aktif atau terbaru memiliki taskName yang sama, target menjadi ambigu; gunakan indeks daftar, kunci sesi, atau id eksekusi sebagai gantinya.

Target yang dicadangkan last dan all bukan nilai taskName yang valid karena keduanya sudah memiliki makna kontrol.

Alat: sessions_yield

Mengakhiri giliran model saat ini dan menunggu peristiwa runtime, terutama peristiwa penyelesaian subagen, tiba sebagai pesan berikutnya. Gunakan setelah membuat pekerjaan turunan yang diperlukan ketika peminta tidak dapat menghasilkan jawaban akhir sampai penyelesaian tersebut tiba.

sessions_yield adalah primitif penantian. Jangan menggantinya dengan perulangan polling pada subagents, sessions_list, sessions_history, perintah shell sleep, atau polling proses hanya untuk mendeteksi penyelesaian turunan.

Gunakan sessions_yield hanya jika daftar alat efektif sesi menyertakannya. Beberapa profil alat minimal atau khusus mungkin menyediakan sessions_spawn dan subagents tanpa menyediakan sessions_yield; dalam hal tersebut, jangan membuat perulangan polling hanya untuk menunggu penyelesaian.

Saat terdapat turunan aktif, OpenClaw menyisipkan blok perintah ringkas buatan runtime Subagen Aktif ke dalam giliran normal agar peminta dapat melihat sesi turunan, id eksekusi, status, label, tugas, dan alias taskName saat ini tanpa polling. Bidang tugas dan label dalam blok tersebut dikutip sebagai data, bukan instruksi, karena dapat berasal dari argumen pembuatan yang diberikan pengguna/model.

Alat: subagents

Mencantumkan eksekusi subagen yang dibuat dan dimiliki oleh sesi peminta. Cakupannya terbatas pada peminta saat ini; turunan hanya dapat melihat turunan yang dikendalikannya sendiri.

Gunakan subagents untuk status sesuai permintaan dan pengawakutuan. Gunakan sessions_yield untuk menunggu peristiwa penyelesaian.

Sesi terikat utas

Saat pengikatan utas diaktifkan untuk suatu kanal, subagen dapat tetap terikat pada utas sehingga pesan pengguna lanjutan di utas tersebut terus dirutekan ke sesi subagen yang sama.

Kanal yang mendukung utas

Suatu kanal mendukung sesi subagen persisten yang terikat utas (sessions_spawn dengan thread: true) saat mendaftarkan adaptor pengikatan percakapan. Kanal bawaan dengan dukungan tersebut: Discord, iMessage, Matrix, dan Telegram. Discord dan Matrix secara default membuat utas turunan; Telegram dan iMessage secara default mengikat percakapan saat ini. Gunakan kunci konfigurasi threadBindings per kanal untuk pengaktifan, batas waktu, dan spawnSessions.

Alur cepat

Kontrol manual

Sakelar konfigurasi

• Default global: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Kunci penggantian kanal dan pengikatan otomatis saat pembuatan bersifat khusus adaptor. Lihat Kanal yang mendukung utas di atas.

Lihat Referensi konfigurasi dan Perintah garis miring untuk detail adaptor saat ini.

Daftar izin

Jika sesi peminta berjalan dalam sandbox, sessions_spawn menolak target yang akan berjalan tanpa sandbox.

Penemuan

Gunakan agents_list untuk melihat id agen mana yang saat ini diizinkan bagi sessions_spawn. Respons menyertakan model efektif dan metadata runtime tertanam dari setiap agen yang dicantumkan agar pemanggil dapat membedakan OpenClaw, server aplikasi Codex, dan runtime native terkonfigurasi lainnya.

Entri allowAgents harus menunjuk ke id agen yang dikonfigurasi dalam agents.list[]. ["*"] berarti agen target terkonfigurasi apa pun beserta peminta. Jika konfigurasi agen dihapus tetapi id-nya tetap ada dalam allowAgents, sessions_spawn menolak id tersebut dan agents_list menghilangkannya. Jalankan openclaw doctor --fix untuk membersihkan entri daftar izin yang sudah usang, atau tambahkan entri minimal agents.list[] jika target harus tetap dapat dibuat sambil mewarisi default.

Pengarsipan otomatis

• Sesi subagen otomatis diarsipkan setelah agents.defaults.subagents.archiveAfterMinutes (default 60).
• Pengarsipan menggunakan sessions.delete dan mengganti nama transkrip menjadi *.deleted.<timestamp> (folder yang sama).
• cleanup: "delete" segera mengarsipkan setelah pengumuman (tetap menyimpan transkrip melalui penggantian nama).
• Pengarsipan otomatis bersifat upaya terbaik; pewaktu tertunda hilang jika gateway dimulai ulang.
• Batas waktu eksekusi yang dikonfigurasi tidak mengarsipkan secara otomatis; batas tersebut hanya menghentikan eksekusi. Sesi tetap ada hingga pengarsipan otomatis.
• Pengarsipan otomatis berlaku sama untuk sesi kedalaman-1 dan kedalaman-2.
• Pembersihan peramban terpisah dari pembersihan arsip: tab/proses peramban yang dilacak ditutup dengan upaya terbaik saat eksekusi selesai, meskipun catatan transkrip/sesi disimpan.

Subagen bertingkat

Secara default, subagen tidak dapat membuat subagen mereka sendiri (maxSpawnDepth: 1). Tetapkan maxSpawnDepth: 2 untuk mengaktifkan satu tingkat penyarangan — pola orkestrator: utama → subagen orkestrator → sub-subagen pekerja.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // mengizinkan subagen membuat turunan (default: 1, rentang 1-5)        maxChildrenPerAgent: 5, // maksimum turunan aktif per sesi agen (default: 5, rentang 1-20)        maxConcurrent: 8, // batas jalur konkurensi global (default: 8)        runTimeoutSeconds: 900, // batas waktu default untuk sessions_spawn (0 = tanpa batas waktu)        announceTimeoutMs: 120000, // batas waktu pengumuman gateway per panggilan      },    },  },}

Tingkat kedalaman

Rantai pengumuman

Hasil mengalir kembali ke atas melalui rantai:

1. Pekerja kedalaman 2 selesai → mengumumkan kepada induknya (orkestrator kedalaman 1).
2. Orkestrator kedalaman 1 menerima pengumuman, menyintesis hasil, lalu selesai → mengumumkan kepada agen utama.
3. Agen utama menerima pengumuman dan menyampaikannya kepada pengguna.

Setiap tingkat hanya melihat pengumuman dari anak langsungnya.

Kebijakan alat berdasarkan kedalaman

• Peran dan cakupan kontrol ditulis ke metadata sesi saat pembuatan. Hal ini mencegah kunci sesi datar atau yang dipulihkan mendapatkan kembali hak istimewa orkestrator secara tidak sengaja.
• Kedalaman 1 (orkestrator, saat maxSpawnDepth >= 2): mendapatkan sessions_spawn, subagents, sessions_list, sessions_history agar dapat membuat anak dan memeriksa statusnya. Alat sesi/sistem lainnya tetap ditolak.
• Kedalaman 1 (daun, saat maxSpawnDepth == 1): tidak ada alat sesi (perilaku bawaan saat ini).
• Kedalaman 2 (pekerja daun): tidak ada alat sesi — sessions_spawn selalu ditolak pada kedalaman 2. Tidak dapat membuat anak lebih lanjut.

Batas pembuatan per agen

Setiap sesi agen (pada kedalaman apa pun) dapat memiliki paling banyak maxChildrenPerAgent (bawaan 5) anak aktif pada satu waktu. Ini mencegah penyebaran tak terkendali dari satu orkestrator.

Penghentian berantai

Menghentikan orkestrator kedalaman 1 secara otomatis menghentikan semua anak kedalaman 2 miliknya:

• /stop di obrolan utama menghentikan semua agen kedalaman 1 dan meneruskannya ke anak kedalaman 2 mereka.

Autentikasi

Autentikasi subagen ditentukan berdasarkan ID agen, bukan jenis sesi:

• Kunci sesi subagen adalah agent:<agentId>:subagent:<uuid>.
• Penyimpanan autentikasi dimuat dari agentDir milik agen tersebut.
• Profil autentikasi agen utama digabungkan sebagai cadangan; profil agen menggantikan profil utama jika terjadi konflik.

Penggabungan bersifat aditif, sehingga profil utama selalu tersedia sebagai cadangan. Autentikasi yang sepenuhnya terisolasi per agen belum didukung.

Pengumuman

Subagen melaporkan kembali melalui langkah pengumuman:

• Langkah pengumuman berjalan di dalam sesi subagen (bukan sesi peminta).
• Jika subagen membalas persis ANNOUNCE_SKIP, tidak ada yang diposting.
• Jika teks asisten terbaru adalah token senyap persis NO_REPLY / no_reply, keluaran pengumuman disembunyikan meskipun sebelumnya terdapat progres yang terlihat.

Pengiriman bergantung pada kedalaman peminta:

• Sesi peminta tingkat teratas menggunakan panggilan agent lanjutan dengan pengiriman eksternal (deliver=true).
• Sesi subagen peminta bertingkat menerima injeksi lanjutan internal (deliver=false) agar orkestrator dapat menyintesis hasil anak di dalam sesi.
• Jika sesi subagen peminta bertingkat sudah tidak ada, OpenClaw kembali ke peminta sesi tersebut jika tersedia.

Untuk sesi peminta tingkat teratas, pengiriman langsung dalam mode penyelesaian terlebih dahulu menentukan rute percakapan/utas yang terikat dan penggantian hook, lalu mengisi bidang kanal-target yang belum tersedia dari rute tersimpan milik sesi peminta. Hal ini menjaga penyelesaian tetap berada di obrolan/topik yang tepat meskipun asal penyelesaian hanya mengidentifikasi kanal.

Agregasi penyelesaian anak dibatasi pada proses peminta saat ini ketika membangun temuan penyelesaian bertingkat, sehingga keluaran anak usang dari proses sebelumnya tidak bocor ke pengumuman saat ini. Balasan pengumuman mempertahankan perutean utas/topik jika tersedia pada adaptor kanal.

Konteks pengumuman

Konteks pengumuman dinormalisasi menjadi blok peristiwa internal yang stabil:

Proses terminal yang gagal melaporkan status kegagalan tanpa memutar ulang teks balasan yang tertangkap. Keluaran alat/hasil alat tidak dipromosikan menjadi teks hasil anak.

Baris statistik

Payload pengumuman menyertakan baris statistik di bagian akhir (bahkan saat dibungkus):

• Runtime (misalnya runtime 5m12s).
• Penggunaan token (masukan/keluaran/total).
• Perkiraan biaya saat harga model dikonfigurasi (models.providers.*.models[].cost).
• sessionKey, sessionId, dan jalur transkrip agar agen utama dapat mengambil riwayat melalui sessions_history atau memeriksa berkas di disk.

Metadata internal hanya ditujukan untuk orkestrasi; balasan kepada pengguna harus ditulis ulang dengan gaya asisten yang wajar.

Mengapa memilih sessions_history

sessions_history adalah jalur orkestrasi yang lebih aman untuk membaca transkrip anak dari dalam giliran agen:

• Menyamarkan teks yang menyerupai kredensial/token meskipun penyamaran log serbaguna dinonaktifkan.
• Memotong blok teks panjang (4000 karakter per blok) dan membuang tanda tangan pemikiran, payload pemutaran ulang penalaran, serta data gambar sebaris.
• Menerapkan batas respons 80 KB; baris yang terlalu besar diganti dengan [sessions_history omitted: message too large].
• Gunakan nextOffset jika tersedia untuk menelusuri mundur jendela transkrip yang lebih lama.
• sessions_history tidak menghapus tag penalaran, perancah <relevant-memories>, atau XML panggilan alat dari teks pesan — fungsi ini mengembalikan blok konten terstruktur yang mendekati bentuk transkrip mentah, hanya disamarkan dan dibatasi ukurannya. /subagents log menerapkan pembersih prosa yang lebih ketat (menghapus tag penalaran, perancah memori, dan XML panggilan alat) karena perintah tersebut merender baris obrolan biasa, bukan blok terstruktur.
• Pemeriksaan transkrip mentah di disk adalah cadangan saat Anda membutuhkan transkrip lengkap yang identik bita demi bita.

Kebijakan alat

Subagen terlebih dahulu menggunakan profil dan alur kebijakan alat yang sama seperti agen induk atau target. Setelah itu, OpenClaw menerapkan lapisan pembatasan subagen.

Subagen selalu kehilangan gateway, agents_list, session_status, dan cron tanpa memandang kedalaman atau peran (alat tingkat sistem/interaktif, atau alat yang seharusnya dikoordinasikan oleh agen utama). Subagen daun (perilaku bawaan kedalaman 1, dan selalu pada kedalaman 2) juga kehilangan subagents, sessions_list, sessions_history, dan sessions_spawn. Subagen tidak pernah mendapatkan alat message — alat tersebut dinonaktifkan saat pembuatan, bukan disaring oleh daftar penolakan ini — dan sessions_send tetap ditolak agar subagen hanya berkomunikasi melalui rantai pengumuman.

sessions_history juga tetap menjadi tampilan pengingatan yang dibatasi dan dibersihkan di sini — bukan dump transkrip mentah.

Saat maxSpawnDepth >= 2, subagen orkestrator kedalaman 1 juga menerima sessions_spawn, subagents, sessions_list, dan sessions_history agar dapat mengelola anak-anaknya.

Penggantian melalui konfigurasi

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // penolakan menang        deny: ["gateway", "cron"],        // jika allow ditetapkan, kebijakan menjadi hanya-izinkan (penolakan tetap menang)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow adalah filter akhir yang hanya mengizinkan. Filter ini dapat mempersempit kumpulan alat yang telah ditentukan, tetapi tidak dapat menambahkan kembali alat yang dihapus oleh tools.profile. Sebagai contoh, tools.profile: "coding" menyertakan web_search/web_fetch, tetapi tidak menyertakan alat browser. Agar subagen dengan profil pengodean dapat menggunakan otomatisasi peramban, tambahkan peramban pada tahap profil:

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

Gunakan agents.list[].tools.alsoAllow: ["browser"] per agen jika hanya satu agen yang boleh mendapatkan otomatisasi peramban.

Konkurensi

Subagen menggunakan jalur antrean dalam proses khusus:

• Nama jalur: subagent
• Konkurensi: agents.defaults.subagents.maxConcurrent (bawaan 8)

Keaktifan dan pemulihan

OpenClaw tidak menganggap ketiadaan endedAt sebagai bukti permanen bahwa subagen masih aktif. Proses yang belum berakhir dan lebih lama daripada jendela proses usang (2 jam, atau batas waktu proses yang dikonfigurasi ditambah masa tenggang singkat, mana pun yang lebih lama) berhenti dihitung sebagai aktif/tertunda dalam /subagents list, ringkasan status, gerbang penyelesaian turunan, dan pemeriksaan konkurensi per sesi.

Setelah Gateway dimulai ulang, proses usang yang dipulihkan tetapi belum berakhir akan dipangkas kecuali sesi anaknya ditandai abortedLastRun: true. Proses yang dibatalkan akibat mulai ulang tetap terdaftar untuk alur pemulihan subagen yatim: proses usang diselesaikan tanpa melanjutkan, sementara sesi anak yang masih baru menerima pesan lanjutan sintetis sebelum penanda pembatalan dihapus.

Pemulihan mulai ulang otomatis dibatasi per sesi anak. Jika anak subagen yang sama berulang kali diterima untuk pemulihan yatim di dalam jendela kemacetan ulang cepat, OpenClaw menyimpan batu nisan pemulihan pada sesi tersebut dan berhenti melanjutkannya secara otomatis pada mulai ulang berikutnya. Jalankan openclaw tasks maintenance --apply untuk merekonsiliasi catatan tugas, atau openclaw doctor --fix untuk menghapus tanda pemulihan terbatal yang usang pada sesi berbatu nisan.

Menghentikan

• Mengirim /stop di obrolan peminta membatalkan sesi peminta dan menghentikan semua proses subagen aktif yang dibuat darinya, lalu meneruskannya ke anak bertingkat.

Batasan

• Pengumuman subagen bersifat upaya terbaik. Jika Gateway dimulai ulang, pekerjaan "announce back" yang tertunda akan hilang.
• Subagen tetap berbagi sumber daya proses Gateway yang sama; perlakukan maxConcurrent sebagai katup pengaman.
• sessions_spawn selalu nonpemblokiran: fungsi ini segera mengembalikan { status: "accepted", runId, childSessionKey }.
• Konteks subagen hanya menyuntikkan AGENTS.md dan TOOLS.md (tanpa SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, atau BOOTSTRAP.md). Subagen bawaan Codex mengikuti batasan yang sama: TOOLS.md tetap berada dalam instruksi utas Codex yang diwarisi, sedangkan berkas persona, identitas, dan pengguna khusus induk disuntikkan sebagai instruksi kolaborasi yang cakupannya terbatas pada giliran agar agen anak tidak menyalinnya.
• Kedalaman penyarangan maksimum adalah 5 (rentang maxSpawnDepth: 1-5). Kedalaman 2 direkomendasikan untuk sebagian besar kasus penggunaan.
• maxChildrenPerAgent membatasi jumlah agen anak aktif per sesi (nilai bawaan 5, rentang 1-20).

Terkait

• Alat sesi dan perubahan status
• Agen ACP
• Pengiriman agen
• Tugas latar belakang
• Alat sandbox multiagen