Kawanan

Swarm adalah cara eksperimental yang bersifat opsional untuk mengorkestrasi banyak sub-agen dari skrip Mode Kode. Gunakan alur kontrol JavaScript atau TypeScript biasa seperti Promise.all, while, dan if untuk menyebarkan pekerjaan, mengumpulkan hasil, dan mengambil keputusan.

Tidak ada DSL graf dan tidak ada format alur kerja terpisah. Program itulah orkestrasinya. Swarm menambahkan anak pengumpul yang dapat ditunggu, hasil terstruktur, konkurensi terbatas, dan pelaporan progres ke program tersebut.

Mengaktifkan Swarm

Jalur yang disarankan adalah Settings → Labs → Swarm di UI Kontrol. Tombol pengalih langsung berlaku dan menulis tools.swarm.enabled ke konfigurasi Anda.

Anda juga dapat mengaktifkan Swarm secara langsung di openclaw.json:

{  tools: {    swarm: {      enabled: true,      maxConcurrent: 8,      maxChildrenPerGroup: 50,      maxTotalPerGroup: 200,      waitTimeoutSecondsMax: 600,      defaultAgentId: "",    },  },}

Notasi singkat boolean mengaktifkan atau menonaktifkan fitur dengan semua nilai lainnya menggunakan nilai default:

{  tools: {    swarm: true,  },}

Nilai numerik harus berupa bilangan bulat positif. OpenClaw membatasi maxConcurrent ke 1–1000, maxChildrenPerGroup ke 1–10000, maxTotalPerGroup ke 1–100000, dan waitTimeoutSecondsMax ke 1–86400.

Anda dapat mengganti pengaturan Swarm untuk satu agen yang dikonfigurasi dengan agents.list[].tools.swarm. Objek per agen digabungkan di atas objek tingkat teratas tools.swarm.

Persyaratan

Global tamu agents.run, phase, dan log memerlukan Swarm dan Mode Kode OpenClaw sekaligus:

{  tools: {    codeMode: true,    swarm: true,  },}

Mode Kode juga harus memiliki akses efektif ke sessions_spawn. Profil alat, kebijakan izin/tolak, aturan penyedia, dan kebijakan sandbox dapat menghapus alat tersebut. Lihat aktivasi Mode Kode dan Sub-agen jika skrip melaporkan bahwa sessions_spawn tidak tersedia.

Nilai defaultAgentId dan agentId per eksekusi harus menyebut target terkonfigurasi yang diizinkan oleh kebijakan subagents.allowAgents milik peminta. OpenClaw menolak target yang tidak dikenal atau tidak diizinkan alih-alih beralih ke agen lain.

Menulis skrip Swarm

Saat Swarm diaktifkan, Mode Kode mengekspos API tamu berikut:

type AgentRunOptions = {  label?: string;  model?: string;  thinking?: string;  fastMode?: boolean | "auto";  agentId?: string;  schema?: Record<string, unknown>;  phase?: string;}; agents.run(prompt: string, options?: AgentRunOptions & { schema?: undefined }): Promise<string>;agents.run&lt;T&gt;(prompt: string, options: AgentRunOptions & { schema: Record<string, unknown> }): Promise&lt;T&gt;;phase(title: string): void;log(message: string): void;

Tanpa schema, agents.run() diselesaikan menjadi teks akhir anak. Dengan JSON Schema, nilainya diselesaikan menjadi nilai yang dikirimkan melalui alat structured_output milik anak. Anak yang gagal, dihentikan, kehabisan waktu, atau memiliki skema tidak valid menolak promise dengan SwarmAgentError. Baca deklarasi persis yang dihasilkan dan pola orkestrasi singkat dari API.read("agents.d.ts") di dalam Mode Kode.

Gunakan label untuk nama anak yang mudah dikenali di dasbor dan bilah samping. Gunakan phase dalam opsi untuk memublikasikan fase tepat sebelum anak tersebut dimulai, atau panggil phase() ketika beberapa anak berada dalam tahap yang sama. log() memublikasikan catatan progres singkat. Panggilan progres bersifat kirim-dan-lupakan; panggilan tersebut tidak menunda skrip jika UI tidak tersedia.

Menyebarkan secara paralel dengan hasil terstruktur

Contoh ini meluncurkan satu peneliti per topik, menunggu semuanya selesai, lalu meminta anak terakhir untuk menyintesis laporan terstruktur mereka:

const reportSchema = {  type: "object",  properties: {    finding: { type: "string" },    evidence: { type: "array", items: { type: "string" } },    confidence: { type: "number" },  },  required: ["finding", "evidence", "confidence"],  additionalProperties: false,}; const topics = ["authentication", "storage", "recovery"];phase("Tinjauan independen"); const reports = await Promise.all(  topics.map((topic) =>    agents.run(`Tinjau jalur ${topic}. Kembalikan satu temuan beserta bukti.`, {      label: `review-${topic}`,      thinking: "high",      fastMode: "auto",      schema: reportSchema,    }),  ),); phase("Sintesis");log(`Mengumpulkan ${reports.length} laporan independen.`); return await agents.run(  `Selaraskan laporan-laporan ini dan jelaskan perbedaannya:\n${JSON.stringify(reports)}`,  { label: "synthesis" },);

Promise.all adalah batas penyebaran dan penggabungan. OpenClaw memulai hingga maxConcurrent anak untuk grup tersebut dan mengantrekan sisanya sesuai urutan pengiriman.

Mengulang berdasarkan gerbang keputusan

Gunakan perulangan while yang dibatasi ketika setiap putaran menentukan apakah putaran lain diperlukan:

const gateSchema = {  type: "object",  properties: {    ready: { type: "boolean" },    reason: { type: "string" },    nextAction: { type: "string" },  },  required: ["ready", "reason", "nextAction"],  additionalProperties: false,}; let pass = 0;let decision = { ready: false, reason: "Belum diperiksa", nextAction: "Tinjau" }; while (!decision.ready && pass < 4) {  pass += 1;  phase(`Putaran keputusan ${pass}`);  decision = await agents.run(    `Periksa apakah bukti rilis sudah lengkap. Keputusan sebelumnya: ${JSON.stringify(decision)}`,    {      label: `release-gate-${pass}`,      schema: gateSchema,    },  );  log(decision.reason);} if (!decision.ready) {  throw new Error(`Gerbang masih tertutup setelah ${pass} putaran: ${decision.nextAction}`);} return decision;

Selalu batasi perulangan keputusan. maxTotalPerGroup adalah pengaman terakhir, bukan pengganti kondisi penghentian yang jelas.

Memproses anak pertama yang selesai

agents.run() mengembalikan promise biasa, sehingga Promise.race dapat bereaksi terhadap anak Mode Kode pertama. Untuk harness yang memanggil alat tingkat rendah, agents_wait menyediakan batas penyelesaian pertama yang sama: fungsi ini kembali segera setelah setidaknya satu eksekusi yang diminta selesai, atau ketika batas waktu terbatas berakhir. Lihat Menggunakan Swarm dari harness lain untuk perulangan pengurasan lengkap.

Perilaku anak pengumpul

Anak pengumpul adalah sesi sub-agen terisolasi biasa dengan jalur penyelesaian yang berbeda. Mereka menulis hasil pengumpul persisten untuk ditunggu oleh induk, alih-alih mengumumkan atau mengarahkan balasan kembali ke sesi induk.

Agen target ditentukan dalam urutan berikut:

1. agentId pada pemunculan atau panggilan agents.run().
2. tools.swarm.defaultAgentId.
3. Agen peminta.

Agen pekerja khusus yang ringan berguna ketika anak swarm memerlukan permukaan alat yang lebih kecil, model yang lebih murah, atau kebijakan sandbox yang lebih ketat. OpenClaw tidak menyertakan id agen worker bawaan; konfigurasikan satu sebelum menetapkannya sebagai default. Perketat pekerja tersebut dengan tools.swarm: false dalam konfigurasi per agennya agar dapat dimunculkan tetapi tidak dapat memulai swarm dari sesi tingkat teratasnya sendiri:

{  tools: { swarm: { enabled: true, defaultAgentId: "worker" } },  agents: {    list: [      {        id: "main",        default: true,        subagents: { allowAgents: ["worker"] },      },      { id: "worker", tools: { swarm: false } },    ],  },}

Persetujuan pengumpul gagal secara tertutup. Anak tidak pernah membuka prompt persetujuan operator. Tindakan alat yang memerlukan persetujuan ditolak, dan anak dapat melaporkan penolakan tersebut dalam hasilnya agar skrip dapat menentukan tindakan berikutnya.

Untuk keluaran terstruktur, OpenClaw menambahkan alat sintetis structured_output ke anak dan memvalidasi payload-nya terhadap JSON Schema yang diberikan. Payload yang tidak valid atau tidak ada menerima satu dorongan korektif. Jika percobaan ulang masih tidak lolos validasi, penyelesaian pengumpul mempertahankan teks mentah anak, membiarkan structured tidak disetel, dan menyertakan schemaError. Hasil agents_wait tingkat rendah mengekspos bidang-bidang tersebut untuk logika pemulihan eksplisit.

Anak merupakan simpul daun

Anak Swarm secara default merupakan simpul daun. Pengaman universal agents.defaults.subagents.maxSpawnDepth mencegah anak memunculkan anaknya sendiri pada kedalaman default 1. Pola orkestrasi yang lazim adalah mengembalikan pekerjaan kepada induk, bukan memunculkan pekerjaan tambahan dari anak:

const plan = await agents.run("Rencanakan pekerjaan ini sebagai tugas-tugas independen.", {  schema: {    type: "object",    properties: { tasks: { type: "array", items: { type: "string" } } },    required: ["tasks"],    additionalProperties: false,  },});return await Promise.all(plan.tasks.map((task) => agents.run(task)));

Sub-agen bertingkat merupakan pilihan eksplisit operator melalui agents.defaults.subagents.maxSpawnDepth dan tidak disarankan untuk Swarm. Batas grup, anggaran, dan observabilitas semuanya mengasumsikan grup pengumpul datar.

Setiap anak memiliki satu pemilik penerimaan. Anak pengumuman dan interaktif menggunakan agents.defaults.subagents.maxChildrenPerAgent (default 5) dan tidak menghitung anak pengumpul. Anak pengumpul hanya menggunakan maxChildrenPerGroup dan maxTotalPerGroup; mereka tidak menggunakan anggaran anak per sesi. Pengaman kedalaman pemunculan tetap berlaku untuk kedua mode.

Setelah diterima, anak di atas maxConcurrent mengantre secara FIFO dalam grup swarm mereka, yang berada di dalam jalur sub-agen global. Lapisan konkurensi ini mengantrekan pekerjaan alih-alih menolaknya. Pemunculan pengumpul yang melampaui salah satu batas grup ditolak dengan kunci konfigurasi terkait dalam pesan kesalahan.

Mengamati Swarm

Buka dasbor sesi induk di UI Kontrol saat swarm aktif. Widget Swarm merender setiap grup pengumpul aktif sebagai satu titik per anak dengan status mengantre, berjalan, selesai, atau gagal. Label muncul dalam tooltip titik, sehingga label singkat dan stabil membuat swarm yang lebih besar lebih mudah dibaca.

Bilah samping sesi mempertahankan struktur pohon induk/anak normal. Perluas baris induk untuk memeriksa anak pengumpul atau membuka transkripnya tanpa kehilangan hierarki swarm.

Hasil pengumpul tetap dapat ditunggu hingga grupnya diarsipkan. Setelah setiap anggota mencapai tenggat retensinya, OpenClaw mengarsipkan anak-anak grup tersebut sebagai satu batch agar swarm yang selesai tidak tetap berada dalam struktur sesi aktif.

Menggunakan Swarm dari harness lain

Anda dapat menggunakan Swarm tanpa OpenClaw Code Mode. Alat intinya tidak bergantung pada harness: mulai anak kolektor dengan sessions_spawn({ collect: true }) dan kumpulkan hasilnya dengan panggilan agents_wait yang dibatasi.

Codex Code Mode secara otomatis mengekspos alat OpenClaw dinamis yang memenuhi syarat di bawah tools.*. Mode ini tidak menggunakan API tamu QuickJS OpenClaw atau memerlukan tools.codeMode, tetapi tools.swarm tetap harus diaktifkan. Panggilan agents_wait harness Codex mendukung waktu tunggu penuh selama 600 detik. Gunakan pola ini:

const tasks = [  "Periksa jalur autentikasi.",  "Periksa jalur penyimpanan.",  "Periksa jalur pemulihan.",]; const launches = await Promise.all(  tasks.map((task, index) =>    tools.sessions_spawn({      task,      collect: true,      label: `review-${index + 1}`,    }),  ),); for (const launch of launches) {  if (launch.status !== "accepted") {    throw new Error(launch.error ?? "Peluncuran kolektor tidak diterima.");  }} const pending = new Set(launches.map((launch) => launch.runId));const completed = []; while (pending.size > 0) {  const ids = [...pending].slice(0, 1000);  const batch = await tools.agents_wait({    ids,    timeoutSeconds: 30,  });   // Putar jendela terbatas ini setelah id yang belum diperiksa.  for (const runId of ids) {    if (pending.delete(runId)) pending.add(runId);  }   for (const item of batch.completed) {    pending.delete(item.runId);    if (item.status !== "done") {      throw new Error(item.schemaError ?? item.result ?? `${item.runId}: ${item.status}`);    }    completed.push(item); // Proses setiap hasil segera setelah selesai.  }   for (const failure of batch.errors ?? []) {    pending.delete(failure.runId);    throw new Error(`${failure.runId}: ${failure.error}`);  }} return completed;

Setiap panggilan agents_wait menerima 1–1000 id proses. Panggilan tersebut mengembalikan:

type AgentsWaitResult = {  completed: Array<{    runId: string;    status: "done" | "failed" | "killed" | "timeout";    result: string;    structured?: unknown;    schemaError?: string;    sessionKey: string;    label?: string;    usage?: { inputTokens: number; outputTokens: number };  }>;  pending: string[];  errors?: Array<{    runId: string;    error: "not_found" | "not_owner";  }>;};

Panggilan segera kembali ketika salah satu anak yang diminta telah selesai, ketika setidaknya satu anak yang tertunda selesai, ketika tidak ada lagi id tertunda yang valid, atau ketika waktu tunggunya berakhir. Catatan yang selesai bersifat idempoten, sehingga meneruskan id proses yang sudah selesai akan mengembalikan hasilnya lagi. Hanya sesi yang melakukan peluncuran atau rantai induknya yang berwenang yang dapat menunggu kolektor.

Ini adalah polling panjang yang dibatasi, bukan loop status sibuk. Teruskan hanya id proses yang tersisa hingga pending kosong. Mode kolektor mendukung subagen native OpenClaw; mode ini tidak mendukung runtime ACP, pengikatan utas, sesi yang terlihat, atau mode sesi persisten.

Batas dan peta jalan

Swarm v1 menjalankan anak kolektor sekali jalan; API agents.session() yang direncanakan akan menambahkan pekerja multi-giliran dengan status. Saat ini, anak berjalan pada jalur subagen Gateway lokal; penempatan cloud direncanakan sebagai opsi peluncuran eksplisit. Definisi alur kerja tersimpan dan DSL graf bukan bagian dari arah Swarm saat ini.

Terkait

• Code Mode untuk runtime tamu QuickJS dan aturan aktivasi
• Subagen untuk kebijakan anak, isolasi, dan perilaku sesi
• Alat sandbox multiagen untuk pembatasan per agen
• Ikhtisar alat untuk profil alat dan perutean kebijakan