Sub-agen

Sub-agent adalah proses agent latar belakang yang dimunculkan dari proses agent yang sudah ada. Mereka berjalan dalam sesi sendiri (agent:<agentId>:subagent:<uuid>) dan, ketika selesai, mengumumkan hasilnya kembali ke channel chat peminta. Setiap proses sub-agent dilacak sebagai tugas latar belakang.

Tujuan utama:

• Memparalelkan pekerjaan "riset / tugas panjang / tool lambat" tanpa memblokir proses utama.
• Menjaga sub-agent tetap terisolasi secara default (pemisahan sesi + sandboxing opsional).
• Menjaga permukaan tool sulit disalahgunakan: sub-agent tidak mendapatkan tool sesi secara default.
• Mendukung kedalaman penyarangan yang dapat dikonfigurasi untuk pola orkestrator.

Perintah slash

Gunakan /subagents untuk memeriksa proses sub-agent untuk sesi saat ini:

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

/subagents info menampilkan metadata proses (status, timestamp, id sesi, path transkrip, pembersihan). Gunakan sessions_history untuk tampilan pemanggilan kembali terbatas dan terfilter keamanan; periksa path transkrip di disk saat Anda membutuhkan transkrip lengkap mentah.

Kontrol pengikatan thread

Perintah ini berfungsi pada channel yang mendukung pengikatan thread persisten. Lihat Channel yang mendukung thread di bawah.

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

Perilaku spawn

Agent memulai sub-agent latar belakang dengan sessions_spawn. Penyelesaian sub-agent kembali sebagai peristiwa sesi induk internal; agent induk/peminta memutuskan apakah pembaruan yang terlihat pengguna diperlukan.

Mode konteks

Sub-agent native dimulai terisolasi kecuali pemanggil secara eksplisit meminta fork transkrip saat ini.

Gunakan fork seperlunya. Ini untuk delegasi peka konteks, bukan pengganti penulisan prompt tugas yang jelas.

Tool: sessions_spawn

Memulai proses sub-agent dengan deliver: false pada lane subagent global, lalu menjalankan langkah pengumuman dan memposting balasan pengumuman ke channel chat peminta.

Ketersediaan bergantung pada kebijakan tool efektif pemanggil. Profil coding dan full mengekspos sessions_spawn secara default. Profil messaging tidak; tambahkan tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] atau gunakan tools.profile: "coding" untuk agent yang harus mendelegasikan pekerjaan. Kebijakan allow/deny channel/grup, provider, sandbox, dan per-agent masih dapat menghapus tool setelah tahap profil. Gunakan /tools dari sesi yang sama untuk mengonfirmasi daftar tool efektif.

Default:

• Model: sub-agent native mewarisi pemanggil kecuali Anda menetapkan agents.defaults.subagents.model (atau agents.list[].subagents.model per-agent). Spawn runtime ACP menggunakan model subagent terkonfigurasi yang sama saat ada; jika tidak, harness ACP mempertahankan defaultnya sendiri. sessions_spawn.model eksplisit tetap menang.
• Thinking: sub-agent native mewarisi pemanggil kecuali Anda menetapkan agents.defaults.subagents.thinking (atau agents.list[].subagents.thinking per-agent). Spawn runtime ACP juga menerapkan agents.defaults.models["provider/model"].params.thinking untuk model yang dipilih. sessions_spawn.thinking eksplisit tetap menang.
• Timeout proses: OpenClaw menggunakan agents.defaults.subagents.runTimeoutSeconds saat ditetapkan; jika tidak, OpenClaw beralih ke 0 (tanpa timeout). sessions_spawn tidak menerima override timeout per-panggilan.
• Pengiriman tugas: sub-agent native menerima tugas yang didelegasikan dalam pesan [Subagent Task] pertama yang terlihat. Prompt sistem sub-agent membawa aturan runtime dan konteks perutean, bukan duplikat tersembunyi dari tugas tersebut.

Spawn sub-agent native yang diterima menyertakan metadata model child yang diselesaikan dalam hasil tool: resolvedModel berisi ref model yang diterapkan dan resolvedProvider berisi prefiks provider saat ref memilikinya.

Mode prompt delegasi

agents.defaults.subagents.delegationMode hanya mengontrol panduan prompt; ini tidak mengubah kebijakan tool atau menegakkan delegasi.

• suggest (default): pertahankan dorongan prompt standar untuk menggunakan sub-agent untuk pekerjaan yang lebih besar atau lebih lambat.
• prefer: beri tahu agent utama untuk tetap responsif dan mendelegasikan apa pun yang lebih terlibat daripada balasan langsung melalui sessions_spawn.

Override per-agent menggunakan agents.list[].subagents.delegationMode.

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

Parameter tool

Nama tugas dan penargetan

taskName adalah handle yang menghadap model untuk orkestrasi, bukan kunci sesi. Gunakan untuk nama anak yang stabil seperti review_subagents, linux_validation, atau docs_update saat koordinator mungkin perlu memeriksa anak tersebut nanti.

Resolusi target menerima kecocokan taskName persis dan prefiks yang tidak ambigu. Pencocokan dibatasi ke jendela target aktif/terbaru yang sama seperti yang digunakan oleh target /subagents bernomor, sehingga anak selesai yang sudah usang tidak membuat handle yang digunakan ulang menjadi ambigu. Jika dua anak aktif atau terbaru berbagi taskName yang sama, target menjadi ambigu; gunakan indeks daftar, kunci sesi, atau id run sebagai gantinya.

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

Alat: sessions_yield

Mengakhiri giliran model saat ini dan menunggu event runtime, terutama event penyelesaian sub-agen, tiba sebagai pesan berikutnya. Gunakan setelah melakukan spawn pekerjaan anak yang diperlukan saat peminta tidak dapat membuat jawaban akhir sampai penyelesaian tersebut tiba.

sessions_yield adalah primitif penunggu. Jangan menggantinya dengan loop polling atas subagents, sessions_list, sessions_history, shell sleep, atau polling proses hanya untuk mendeteksi penyelesaian anak.

Hanya gunakan sessions_yield saat daftar alat efektif sesi menyertakannya. Beberapa profil alat minimal atau kustom mungkin mengekspos sessions_spawn dan subagents tanpa mengekspos sessions_yield; dalam kasus itu, jangan menciptakan loop polling hanya untuk menunggu penyelesaian.

Saat ada anak aktif, OpenClaw menyuntikkan blok prompt Active Subagents ringkas yang dibuat runtime ke dalam giliran normal sehingga peminta dapat melihat sesi anak saat ini, id run, status, label, tugas, dan alias taskName tanpa polling. Field tugas dan label dalam blok tersebut dikutip sebagai data, bukan instruksi, karena dapat berasal dari argumen spawn yang disediakan pengguna/model.

Alat: subagents

Mencantumkan run sub-agen yang di-spawn dan dimiliki oleh sesi peminta. Cakupannya dibatasi ke peminta saat ini; anak hanya dapat melihat anak yang dikontrolnya sendiri.

Gunakan subagents untuk status sesuai permintaan dan debugging. Gunakan sessions_yield untuk menunggu event penyelesaian.

Sesi terikat utas

Saat pengikatan utas diaktifkan untuk sebuah kanal, sub-agen dapat tetap terikat ke sebuah utas sehingga pesan lanjutan pengguna dalam utas tersebut tetap diarahkan ke sesi sub-agen yang sama.

Kanal yang mendukung utas

Kanal apa pun dengan adapter pengikatan sesi dapat mendukung sesi subagen persisten yang terikat utas (sessions_spawn dengan thread: true). Adapter bawaan saat ini mencakup utas Discord, utas Matrix, topik forum Telegram, dan pengikatan percakapan saat ini untuk Feishu. Gunakan kunci config threadBindings per kanal untuk pengaktifan, timeout, dan spawnSessions.

Alur cepat

Kontrol manual

Sakelar config

• Default global: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Kunci override kanal dan auto-bind spawn bersifat khusus adapter. Lihat Kanal yang mendukung utas di atas.

Lihat Referensi konfigurasi dan Perintah slash untuk detail adapter saat ini.

Allowlist

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

Penemuan

Gunakan agents_list untuk melihat id agen mana yang saat ini diizinkan untuk sessions_spawn. Respons mencakup model efektif setiap agen yang dicantumkan dan metadata runtime tertanam sehingga pemanggil dapat membedakan OpenClaw, Codex app-server, dan runtime native terkonfigurasi lainnya.

Entri allowAgents harus menunjuk ke id agen terkonfigurasi di agents.list[]. ["*"] berarti agen target terkonfigurasi apa pun plus peminta. Jika config agen dihapus tetapi id-nya tetap berada di allowAgents, sessions_spawn menolak id tersebut dan agents_list menghilangkannya. Jalankan openclaw doctor --fix untuk membersihkan entri allowlist usang, atau tambahkan entri agents.list[] minimal saat target harus tetap dapat di-spawn sambil mewarisi default.

Arsip otomatis

• Sesi sub-agen diarsipkan secara otomatis setelah agents.defaults.subagents.archiveAfterMinutes (default 60).
• Arsip menggunakan sessions.delete dan mengganti nama transkrip menjadi *.deleted.<timestamp> (folder yang sama).
• cleanup: "delete" mengarsipkan segera setelah pengumuman (tetap menyimpan transkrip melalui penggantian nama).
• Arsip otomatis bersifat best-effort; timer tertunda hilang jika gateway dimulai ulang.
• Timeout run terkonfigurasi tidak mengarsipkan secara otomatis; timeout hanya menghentikan run. Sesi tetap ada sampai arsip otomatis.
• Arsip otomatis berlaku sama untuk sesi kedalaman-1 dan kedalaman-2.
• Pembersihan browser terpisah dari pembersihan arsip: tab/proses browser yang dilacak ditutup secara best-effort saat run selesai, bahkan jika catatan transkrip/sesi disimpan.

Sub-agen bersarang

Secara default, sub-agen tidak dapat melakukan spawn sub-agennya sendiri (maxSpawnDepth: 1). Tetapkan maxSpawnDepth: 2 untuk mengaktifkan satu level penyusunan — pola orkestrator: utama → sub-agen orkestrator → sub-sub-agen pekerja.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

Level kedalaman

Rantai pengumuman

Hasil mengalir kembali ke atas rantai:

1. Worker kedalaman-2 selesai → memberi pengumuman kepada induknya (orkestrator kedalaman-1).
2. Orkestrator kedalaman-1 menerima pengumuman, menyintesis hasil, selesai → memberi pengumuman ke utama.
3. Agen utama menerima pengumuman dan menyampaikannya kepada pengguna.

Setiap level hanya melihat pengumuman dari anak langsungnya.

Kebijakan alat berdasarkan kedalaman

• Peran dan cakupan kontrol ditulis ke metadata sesi saat spawn. Itu mencegah kunci sesi datar atau yang dipulihkan mendapatkan kembali hak istimewa orkestrator secara tidak sengaja.
• Kedalaman 1 (orkestrator, ketika maxSpawnDepth >= 2): mendapatkan sessions_spawn, subagents, sessions_list, sessions_history agar dapat men-spawn anak dan memeriksa statusnya. Alat sesi/sistem lain tetap ditolak.
• Kedalaman 1 (leaf, ketika maxSpawnDepth == 1): tidak ada alat sesi (perilaku default saat ini).
• Kedalaman 2 (worker leaf): tidak ada alat sesi — sessions_spawn selalu ditolak pada kedalaman 2. Tidak dapat men-spawn anak lebih lanjut.

Batas spawn per agen

Setiap sesi agen (pada kedalaman apa pun) dapat memiliki maksimal maxChildrenPerAgent (default 5) anak aktif pada satu waktu. Ini mencegah fan-out tak terkendali dari satu orkestrator.

Penghentian berantai

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

• /stop di chat utama menghentikan semua agen kedalaman-1 dan berantai ke anak kedalaman-2 mereka.

Autentikasi

Auth sub-agen diselesaikan berdasarkan id agen, bukan berdasarkan tipe sesi:

• Kunci sesi sub-agen adalah agent:<agentId>:subagent:<uuid>.
• Penyimpanan auth dimuat dari agentDir agen tersebut.
• Profil auth agen utama digabungkan sebagai fallback; profil agen mengesampingkan profil utama saat ada konflik.

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

Pengumuman

Sub-agen melaporkan kembali melalui langkah pengumuman:

• Langkah pengumuman berjalan di dalam sesi sub-agen (bukan sesi peminta).
• Jika sub-agen membalas persis ANNOUNCE_SKIP, tidak ada yang diposting.
• Jika teks asisten terbaru adalah token senyap persis NO_REPLY / no_reply, output pengumuman ditekan meskipun progres yang terlihat sebelumnya ada.

Pengiriman bergantung pada kedalaman peminta:

• Sesi peminta tingkat atas menggunakan panggilan agent tindak lanjut dengan pengiriman eksternal (deliver=true).
• Sesi subagen peminta bertingkat menerima injeksi tindak lanjut internal (deliver=false) sehingga orkestrator dapat menyintesis hasil anak di dalam sesi.
• Jika sesi subagen peminta bertingkat hilang, OpenClaw melakukan fallback ke peminta sesi tersebut saat tersedia.

Untuk sesi peminta tingkat atas, pengiriman langsung mode penyelesaian terlebih dahulu menyelesaikan rute percakapan/thread terikat dan override hook apa pun, lalu mengisi field channel-target yang hilang dari rute tersimpan sesi peminta. Ini menjaga penyelesaian tetap berada di chat/topik yang benar bahkan ketika asal penyelesaian hanya mengidentifikasi channel.

Agregasi penyelesaian anak dicakup ke run peminta saat ini saat membangun temuan penyelesaian bertingkat, mencegah output anak dari run lama bocor ke pengumuman saat ini. Balasan pengumuman mempertahankan routing thread/topik saat tersedia pada adapter channel.

Konteks pengumuman

Konteks pengumuman dinormalisasi menjadi blok peristiwa internal yang stabil:

Run terminal yang gagal melaporkan status kegagalan tanpa memutar ulang teks balasan yang ditangkap. Output tool/toolResult tidak dipromosikan menjadi teks hasil anak.

Baris statistik

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

• Runtime (mis. runtime 5m12s).
• Penggunaan token (input/output/total).
• Estimasi biaya saat harga model dikonfigurasi (models.providers.*.models[].cost).
• sessionKey, sessionId, dan path transkrip agar agen utama dapat mengambil riwayat melalui sessions_history atau memeriksa file di disk.

Metadata internal dimaksudkan hanya untuk orkestrasi; balasan yang menghadap pengguna harus ditulis ulang dengan suara asisten normal.

Mengapa lebih memilih sessions_history

sessions_history adalah jalur orkestrasi yang lebih aman:

• Recall asisten dinormalisasi terlebih dahulu: tag berpikir dihapus; scaffolding <relevant-memories> / <relevant_memories> dihapus; blok payload XML tool-call teks biasa (<tool_call>, <function_call>, <tool_calls>, <function_calls>) dihapus, termasuk payload terpotong yang tidak pernah tertutup dengan bersih; scaffolding tool-call/result yang diturunkan dan marker konteks historis dihapus; token kontrol model yang bocor (<|assistant|>, ASCII <|...|> lain, lebar penuh <｜...｜>) dihapus; XML tool-call MiniMax yang malformed dihapus.
• Teks yang menyerupai kredensial/token disunting.
• Blok panjang dapat dipotong.
• Riwayat yang sangat besar dapat membuang baris lama atau mengganti baris terlalu besar dengan [sessions_history omitted: message too large].
• Gunakan nextOffset saat ada untuk membuka halaman mundur melalui jendela transkrip yang lebih lama.
• Pemeriksaan transkrip mentah di disk adalah fallback saat Anda membutuhkan transkrip byte-for-byte lengkap.

Kebijakan alat

Sub-agen menggunakan profil dan pipeline kebijakan alat yang sama seperti induk atau agen target terlebih dahulu. Setelah itu, OpenClaw menerapkan lapisan pembatasan sub-agen.

Tanpa tools.profile yang restriktif, sub-agen mendapatkan semua alat kecuali alat pesan, alat sesi, dan alat sistem:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

sessions_history tetap menjadi tampilan recall yang dibatasi dan disanitasi di sini juga — ini bukan dump transkrip mentah.

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

Override melalui config

{  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 adalah filter allow-only final. Ini dapat mempersempit set alat yang sudah diselesaikan, tetapi tidak dapat menambahkan kembali alat yang dihapus oleh tools.profile. Misalnya, tools.profile: "coding" menyertakan web_search/web_fetch tetapi bukan alat browser. Untuk mengizinkan sub-agen profil coding menggunakan otomatisasi browser, tambahkan browser pada tahap profil:

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

Gunakan agents.list[].tools.alsoAllow: ["browser"] per agen ketika hanya satu agen yang seharusnya mendapatkan otomatisasi browser.

Konkurensi

Sub-agen menggunakan lane antrean in-process khusus:

• Nama lane: subagent
• Konkurensi: agents.defaults.subagents.maxConcurrent (default 8)

Liveness dan pemulihan

OpenClaw tidak memperlakukan ketiadaan endedAt sebagai bukti permanen bahwa sub-agen masih hidup. Run yang belum berakhir dan lebih lama dari jendela stale-run berhenti dihitung sebagai aktif/tertunda di /subagents list, ringkasan status, gating penyelesaian turunan, dan pemeriksaan konkurensi per sesi.

Setelah restart gateway, run pulihan yang stale dan belum berakhir dipangkas kecuali sesi anaknya ditandai abortedLastRun: true. Sesi anak yang dibatalkan saat restart tersebut tetap dapat dipulihkan melalui alur pemulihan orphan sub-agen, yang mengirim pesan resume sintetis sebelum menghapus marker aborted.

Pemulihan restart otomatis dibatasi per sesi anak. Jika anak sub-agen yang sama diterima untuk pemulihan orphan berulang kali di dalam jendela rapid re-wedge, OpenClaw menyimpan tombstone pemulihan pada sesi itu dan berhenti melanjutkannya otomatis pada restart berikutnya. Jalankan openclaw tasks maintenance --apply untuk merekonsiliasi catatan tugas, atau openclaw doctor --fix untuk menghapus flag pemulihan aborted yang stale pada sesi yang ditombstone.

Menghentikan

• Mengirim /stop di chat peminta membatalkan sesi peminta dan menghentikan run sub-agen aktif apa pun yang di-spawn darinya, berantai ke anak bertingkat.

Batasan

• Pengumuman sub-agen bersifat best-effort. Jika gateway restart, pekerjaan "announce back" yang tertunda hilang.
• Sub-agen masih berbagi resource proses gateway yang sama; perlakukan maxConcurrent sebagai katup pengaman.
• sessions_spawn selalu non-blocking: ini langsung mengembalikan { status: "accepted", runId, childSessionKey }.
• Konteks sub-agen hanya menginjeksi AGENTS.md dan TOOLS.md (tanpa SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, atau BOOTSTRAP.md). Subagen native Codex mengikuti batas yang sama: TOOLS.md tetap berada dalam instruksi thread Codex yang diwariskan, sementara file persona, identitas, dan pengguna yang hanya untuk induk diinjeksi sebagai instruksi kolaborasi bercakupan turn agar anak tidak mengkloningnya.
• Kedalaman bertingkat maksimum adalah 5 (rentang maxSpawnDepth: 1–5). Kedalaman 2 direkomendasikan untuk sebagian besar kasus penggunaan.
• maxChildrenPerAgent membatasi anak aktif per sesi (default 5, rentang 1–20).

Terkait

• Agen ACP
• Kirim agen
• Tugas latar belakang
• Alat sandbox multi-agen