Bầy đàn

Swarm là một cách thử nghiệm, cần chủ động bật để điều phối nhiều sub-agent từ một script Code Mode. Sử dụng luồng điều khiển JavaScript hoặc TypeScript thông thường như Promise.all, while và if để phân tán công việc, thu thập kết quả và đưa ra quyết định.

Không có DSL đồ thị và không có định dạng quy trình làm việc riêng. Chương trình chính là phần điều phối. Swarm bổ sung các tiến trình con thu thập có thể chờ, kết quả có cấu trúc, mức đồng thời có giới hạn và báo cáo tiến độ cho chương trình đó.

Bật Swarm

Cách được khuyến nghị là Settings → Labs → Swarm trong Control UI. Nút bật/tắt có hiệu lực ngay lập tức và ghi tools.swarm.enabled vào cấu hình của bạn.

Bạn cũng có thể bật trực tiếp Swarm trong openclaw.json:

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

Dạng viết tắt Boolean bật hoặc tắt tính năng trong khi tất cả giá trị khác giữ giá trị mặc định:

{  tools: {    swarm: true,  },}

Các giá trị số phải là số nguyên dương. OpenClaw giới hạn maxConcurrent trong khoảng 1–1000, maxChildrenPerGroup trong khoảng 1–10000, maxTotalPerGroup trong khoảng 1–100000 và waitTimeoutSecondsMax trong khoảng 1–86400.

Bạn có thể ghi đè Swarm cho một agent đã cấu hình bằng agents.list[].tools.swarm. Đối tượng theo từng agent được hợp nhất để ghi đè lên đối tượng tools.swarm cấp cao nhất.

Yêu cầu

Các biến toàn cục khách agents.run, phase và log yêu cầu cả Swarm lẫn OpenClaw Code Mode:

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

Code Mode cũng phải có quyền truy cập hiệu lực vào sessions_spawn. Hồ sơ công cụ, chính sách cho phép/từ chối, quy tắc nhà cung cấp và chính sách sandbox có thể loại bỏ công cụ đó. Xem kích hoạt Code Mode và Sub-agent nếu script báo rằng sessions_spawn không khả dụng.

Các giá trị defaultAgentId và agentId theo từng lần chạy phải chỉ định một đích đã cấu hình được chính sách subagents.allowAgents của bên yêu cầu cho phép. OpenClaw từ chối đích không xác định hoặc không được phép thay vì chuyển sang một agent khác.

Viết script Swarm

Khi Swarm được bật, Code Mode cung cấp API khách sau:

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;

Nếu không có schema, agents.run() phân giải thành văn bản cuối cùng của tiến trình con. Khi có JSON Schema, nó phân giải thành giá trị được gửi thông qua công cụ structured_output của tiến trình con. Tiến trình con thất bại, bị kết thúc, hết thời gian chờ hoặc không hợp lệ theo schema sẽ từ chối promise với SwarmAgentError. Đọc các khai báo chính xác được tạo và những mẫu điều phối ngắn từ API.read("agents.d.ts") bên trong Code Mode.

Dùng label để đặt tên dễ nhận biết cho tiến trình con trong bảng điều khiển và thanh bên. Dùng phase trong các tùy chọn để công bố một giai đoạn ngay trước khi tiến trình con đó bắt đầu, hoặc gọi phase() khi nhiều tiến trình con thuộc cùng một giai đoạn. log() công bố một ghi chú tiến độ ngắn. Các lệnh gọi tiến độ hoạt động theo kiểu gửi rồi bỏ qua; chúng không làm chậm script nếu UI không khả dụng.

Phân tán song song với kết quả có cấu trúc

Ví dụ này khởi chạy một tiến trình nghiên cứu cho mỗi chủ đề, chờ tất cả hoàn tất, rồi yêu cầu tiến trình con cuối cùng tổng hợp các báo cáo có cấu trúc của chúng:

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("Đánh giá độc lập"); const reports = await Promise.all(  topics.map((topic) =>    agents.run(`Đánh giá luồng ${topic}. Trả về một phát hiện kèm bằng chứng.`, {      label: `review-${topic}`,      thinking: "high",      fastMode: "auto",      schema: reportSchema,    }),  ),); phase("Tổng hợp");log(`Đã thu thập ${reports.length} báo cáo độc lập.`); return await agents.run(  `Đối chiếu các báo cáo này và giải thích các điểm bất đồng:\n${JSON.stringify(reports)}`,  { label: "synthesis" },);

Promise.all là ranh giới phân tán và hội tụ. OpenClaw khởi chạy tối đa maxConcurrent tiến trình con cho nhóm và xếp phần còn lại vào hàng đợi theo thứ tự gửi.

Lặp theo cổng quyết định

Sử dụng vòng lặp while có giới hạn khi mỗi lượt quyết định liệu có cần thêm một lượt nữa hay không:

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: "Chưa kiểm tra", nextAction: "Đánh giá" }; while (!decision.ready && pass < 4) {  pass += 1;  phase(`Lượt quyết định ${pass}`);  decision = await agents.run(    `Kiểm tra xem bằng chứng phát hành đã đầy đủ chưa. Quyết định trước đó: ${JSON.stringify(decision)}`,    {      label: `release-gate-${pass}`,      schema: gateSchema,    },  );  log(decision.reason);} if (!decision.ready) {  throw new Error(`Cổng vẫn đóng sau ${pass} lượt: ${decision.nextAction}`);} return decision;

Luôn đặt giới hạn cho các vòng lặp quyết định. maxTotalPerGroup là cơ chế bảo vệ cuối cùng, không phải sự thay thế cho một điều kiện dừng rõ ràng.

Xử lý tiến trình con hoàn tất đầu tiên

agents.run() trả về một promise thông thường, vì vậy Promise.race có thể phản ứng với tiến trình con Code Mode đầu tiên. Đối với các harness gọi các công cụ cấp thấp hơn, agents_wait cung cấp cùng ranh giới hoàn tất đầu tiên: nó trả về ngay khi ít nhất một lần chạy được yêu cầu hoàn tất hoặc khi hết thời gian chờ có giới hạn. Xem Sử dụng Swarm từ các harness khác để biết vòng lặp thu kết quả đầy đủ.

Cách tiến trình con thu thập hoạt động

Tiến trình con thu thập là các phiên sub-agent cô lập thông thường nhưng có đường dẫn hoàn tất khác. Chúng ghi kết quả thu thập bền vững để tiến trình cha chờ thay vì thông báo hoặc điều hướng phản hồi trở lại phiên cha.

Agent đích được phân giải theo thứ tự sau:

1. agentId trong lệnh khởi tạo hoặc lệnh gọi agents.run().
2. tools.swarm.defaultAgentId.
3. Agent gửi yêu cầu.

Một agent thực thi chuyên dụng, tinh gọn sẽ hữu ích khi các tiến trình con swarm cần phạm vi công cụ nhỏ hơn, mô hình rẻ hơn hoặc chính sách sandbox chặt chẽ hơn. OpenClaw không cung cấp sẵn id agent worker; hãy cấu hình một agent trước khi chỉ định nó làm mặc định. Gia cố agent thực thi đó bằng tools.swarm: false trong cấu hình theo từng agent để nó có thể được khởi tạo nhưng không thể bắt đầu swarm từ các phiên cấp cao nhất của chính nó:

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

Các yêu cầu phê duyệt của tiến trình thu thập mặc định sẽ bị từ chối. Tiến trình con không bao giờ mở lời nhắc phê duyệt cho người vận hành. Một thao tác công cụ cần phê duyệt sẽ bị từ chối, và tiến trình con có thể báo cáo việc từ chối đó trong kết quả để script quyết định hành động tiếp theo.

Đối với đầu ra có cấu trúc, OpenClaw thêm một công cụ structured_output tổng hợp vào tiến trình con và xác thực payload của nó theo JSON Schema được cung cấp. Payload không hợp lệ hoặc bị thiếu sẽ nhận một lời nhắc sửa duy nhất. Nếu lần thử lại vẫn không vượt qua xác thực, kết quả hoàn tất của tiến trình thu thập sẽ giữ lại văn bản thô của tiến trình con, để structured chưa được đặt và bao gồm schemaError. Kết quả agents_wait cấp thấp cung cấp các trường đó cho logic khôi phục tường minh.

Tiến trình con là nút lá

Theo mặc định, tiến trình con Swarm là nút lá. Cơ chế bảo vệ phổ quát agents.defaults.subagents.maxSpawnDepth ngăn một tiến trình con khởi tạo các tiến trình con riêng ở độ sâu mặc định 1. Mẫu điều phối thông thường là trả công việc về tiến trình cha, không phải khởi tạo thêm công việc từ tiến trình con:

const plan = await agents.run("Lập kế hoạch cho công việc này thành các tác vụ độc lập.", {  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-agent lồng nhau là tính năng mà người vận hành phải chủ động bật thông qua agents.defaults.subagents.maxSpawnDepth và không được khuyến nghị cho Swarm. Giới hạn nhóm, ngân sách và khả năng quan sát đều giả định các nhóm thu thập phẳng.

Mỗi tiến trình con có một chủ thể quản lý việc tiếp nhận. Tiến trình con thông báo và tương tác sử dụng agents.defaults.subagents.maxChildrenPerAgent (mặc định 5) và không tính các tiến trình con thu thập. Tiến trình con thu thập chỉ sử dụng maxChildrenPerGroup và maxTotalPerGroup; chúng không tiêu thụ ngân sách tiến trình con theo phiên. Cơ chế bảo vệ độ sâu khởi tạo vẫn áp dụng cho cả hai chế độ.

Sau khi được tiếp nhận, các tiến trình con vượt quá maxConcurrent sẽ xếp hàng FIFO trong nhóm swarm của chúng, được lồng bên trong làn sub-agent toàn cục. Các lớp đồng thời này xếp công việc vào hàng đợi thay vì từ chối. Một lần khởi tạo tiến trình thu thập vượt quá một trong hai giới hạn nhóm sẽ bị từ chối với khóa cấu hình liên quan trong lỗi.

Quan sát một Swarm

Mở bảng điều khiển của phiên cha trong Control UI khi một swarm đang hoạt động. Tiện ích Swarm hiển thị mỗi nhóm thu thập đang hoạt động bằng một dấu chấm cho mỗi tiến trình con với trạng thái đang chờ, đang chạy, hoàn tất hoặc thất bại. Nhãn xuất hiện trong chú giải của dấu chấm, vì vậy các nhãn ngắn và ổn định giúp các swarm lớn dễ đọc hơn.

Thanh bên phiên giữ nguyên cây cha/con thông thường. Mở rộng hàng của tiến trình cha để kiểm tra một tiến trình con thu thập hoặc mở bản ghi hội thoại của nó mà không làm mất cấu trúc phân cấp swarm.

Kết quả thu thập vẫn có thể được chờ cho đến khi nhóm được lưu trữ. Sau khi mọi thành viên đạt thời hạn lưu giữ, OpenClaw lưu trữ các tiến trình con của nhóm theo lô để các swarm đã hoàn tất không còn nằm trong cây phiên đang hoạt động.

Sử dụng Swarm từ các harness khác

Bạn có thể sử dụng Swarm mà không cần OpenClaw Code Mode. Các công cụ cốt lõi của Swarm không phụ thuộc vào harness: khởi chạy các collector con bằng sessions_spawn({ collect: true }) và thu thập kết quả từ chúng bằng các lệnh gọi agents_wait có giới hạn.

Codex Code Mode tự động cung cấp các công cụ OpenClaw động đủ điều kiện trong tools.*. Chế độ này không sử dụng API khách QuickJS của OpenClaw hoặc yêu cầu tools.codeMode, nhưng tools.swarm vẫn phải được bật. Các lệnh gọi agents_wait của harness Codex hỗ trợ đầy đủ thời gian chờ 600 giây. Sử dụng mẫu sau:

const tasks = [  "Kiểm tra đường dẫn xác thực.",  "Kiểm tra đường dẫn lưu trữ.",  "Kiểm tra đường dẫn khôi phục.",]; 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 ?? "Yêu cầu khởi chạy collector không được chấp nhận.");  }} 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,  });   // Luân chuyển cửa sổ có giới hạn này qua các id chưa được kiểm tra.  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); // Xử lý từng kết quả ngay khi hoàn tất.  }   for (const failure of batch.errors ?? []) {    pending.delete(failure.runId);    throw new Error(`${failure.runId}: ${failure.error}`);  }} return completed;

Mỗi lệnh gọi agents_wait chấp nhận 1–1000 id lượt chạy. Lệnh gọi trả về:

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";  }>;};

Lệnh gọi trả về ngay lập tức khi bất kỳ tiến trình con được yêu cầu nào đã hoàn tất, khi ít nhất một tiến trình con đang chờ hoàn tất, khi không còn id đang chờ hợp lệ nào, hoặc khi hết thời gian chờ. Các bản ghi đã hoàn tất có tính lũy đẳng, vì vậy việc truyền id của một lượt chạy đã hoàn tất sẽ trả lại kết quả của lượt chạy đó. Chỉ phiên khởi chạy hoặc chuỗi phiên cha được ủy quyền của phiên đó mới có thể chờ một collector.

Đây là cơ chế thăm dò dài có giới hạn, không phải vòng lặp trạng thái bận. Chỉ tiếp tục truyền các id lượt chạy còn lại cho đến khi pending trống. Chế độ collector hỗ trợ các sub-agent OpenClaw gốc; chế độ này không hỗ trợ runtime ACP, liên kết luồng, các phiên hiển thị hoặc chế độ phiên liên tục.

Giới hạn và lộ trình

Swarm v1 chạy các tiến trình collector con dùng một lần; API agents.session() dự kiến sẽ bổ sung các worker nhiều lượt có trạng thái. Hiện tại, các tiến trình con chạy trên lane sub-agent của Gateway cục bộ; việc triển khai trên đám mây được lên kế hoạch dưới dạng một tùy chọn khởi chạy rõ ràng. Các định nghĩa quy trình làm việc đã lưu và DSL đồ thị không thuộc định hướng hiện tại của Swarm.

Liên quan

• Code Mode để biết runtime khách QuickJS và các quy tắc kích hoạt
• Sub-agent để biết chính sách tiến trình con, khả năng cách ly và hành vi phiên
• Công cụ sandbox đa agent để biết các hạn chế riêng cho từng agent
• Tổng quan về công cụ để biết các hồ sơ công cụ và định tuyến chính sách