เอเจนต์ย่อย

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• ทำงาน “วิจัย / งานยาว / เครื่องมือช้า” แบบขนานโดยไม่บล็อกการรันหลัก
• แยกเอเจนต์ย่อยออกจากกันโดยค่าเริ่มต้น (การแยกเซสชัน + การ sandbox แบบเลือกใช้ได้)
• ทำให้พื้นผิวเครื่องมือใช้งานผิดได้ยาก: เอเจนต์ย่อยจะไม่ได้รับเครื่องมือเซสชันโดยค่าเริ่มต้น
• รองรับความลึกของการซ้อนที่กำหนดค่าได้สำหรับรูปแบบตัวประสานงาน

​

คำสั่งสแลช

/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

​

การควบคุมการผูกเธรด

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

​

พฤติกรรมการสร้าง

​

โหมดบริบท

​

เครื่องมือ: sessions_spawn

• โมเดล: สืบทอดจากผู้เรียก เว้นแต่คุณตั้งค่า agents.defaults.subagents.model (หรือ agents.list[].subagents.model รายเอเจนต์); sessions_spawn.model ที่ระบุอย่างชัดเจนยังคงมีผลเหนือกว่า
• Thinking: สืบทอดจากผู้เรียก เว้นแต่คุณตั้งค่า agents.defaults.subagents.thinking (หรือ agents.list[].subagents.thinking รายเอเจนต์); sessions_spawn.thinking ที่ระบุอย่างชัดเจนยังคงมีผลเหนือกว่า
• หมดเวลาการรัน: หากละ sessions_spawn.runTimeoutSeconds ไว้ OpenClaw จะใช้ agents.defaults.subagents.runTimeoutSeconds เมื่อมีการตั้งค่า; มิฉะนั้นจะถอยกลับเป็น 0 (ไม่หมดเวลา)

​

โหมดพรอมต์การมอบหมายงาน

• suggest (ค่าเริ่มต้น): คงการกระตุ้นในพรอมต์มาตรฐานให้ใช้เอเจนต์ย่อยสำหรับงานที่ใหญ่กว่าหรือช้ากว่า
• prefer: บอกเอเจนต์หลักให้ตอบสนองต่อเนื่องและมอบหมายสิ่งใดก็ตามที่ซับซ้อนกว่าการตอบกลับโดยตรงผ่าน sessions_spawn

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

​

พารามิเตอร์เครื่องมือ

​

ชื่องานและการกำหนดเป้าหมาย

​

เครื่องมือ: sessions_yield

​

เครื่องมือ: subagents

​

เซสชันที่ผูกกับ thread

​

ช่องทางที่รองรับ thread

​

ลำดับอย่างย่อ

​

การควบคุมแบบ manual

​

สวิตช์การกำหนดค่า

• ค่าเริ่มต้นแบบ global: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours
• คีย์ override ของช่องทางและ auto-bind เมื่อสร้าง เป็นแบบเฉพาะ adapter ดู ช่องทางที่รองรับ thread ด้านบน

​

Allowlist

​

การค้นพบ

​

การเก็บถาวรอัตโนมัติ

• เซสชันเอเจนต์ย่อยจะถูกเก็บถาวรโดยอัตโนมัติหลังจาก agents.defaults.subagents.archiveAfterMinutes (ค่าเริ่มต้น 60)
• การเก็บถาวรใช้ sessions.delete และเปลี่ยนชื่อทรานสคริปต์เป็น *.deleted.<timestamp> (โฟลเดอร์เดียวกัน)
• cleanup: "delete" จะเก็บถาวรทันทีหลังจากประกาศ (ยังคงเก็บทรานสคริปต์ไว้ผ่านการเปลี่ยนชื่อ)
• การเก็บถาวรอัตโนมัติเป็นแบบ best-effort; timer ที่ค้างอยู่จะหายไปหาก Gateway รีสตาร์ท
• runTimeoutSeconds ไม่ เก็บถาวรอัตโนมัติ; มันเพียงหยุดการรัน เซสชันยังคงอยู่จนกว่าจะถูกเก็บถาวรอัตโนมัติ
• การเก็บถาวรอัตโนมัติใช้กับเซสชัน depth-1 และ depth-2 เท่า ๆ กัน
• การล้างข้อมูลเบราว์เซอร์แยกจากการล้างข้อมูลเก็บถาวร: แท็บ/กระบวนการเบราว์เซอร์ที่ติดตามจะถูกปิดแบบ best-effort เมื่อการรันเสร็จสิ้น แม้ว่าจะเก็บระเบียนทรานสคริปต์/เซสชันไว้ก็ตาม

​

เอเจนต์ย่อยแบบซ้อน

{
  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 when omitted (0 = no timeout)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}

​

ระดับความลึก

​

สายประกาศ

1. worker depth-2 เสร็จสิ้น → ประกาศไปยัง parent ของมัน (orchestrator depth-1)
2. orchestrator depth-1 ได้รับประกาศ สังเคราะห์ผลลัพธ์ เสร็จสิ้น → ประกาศไปยัง main
3. เอเจนต์ main ได้รับประกาศและส่งต่อให้ผู้ใช้

​

นโยบายเครื่องมือตามความลึก

• บทบาทและขอบเขตการควบคุมจะถูกเขียนลงในเมตาดาต้าเซสชันตอน spawn ซึ่งช่วยป้องกันไม่ให้คีย์เซสชันแบบแบนหรือที่กู้คืนมาได้รับสิทธิ์ orchestrator กลับมาโดยไม่ตั้งใจ
• ความลึก 1 (orchestrator, เมื่อ maxSpawnDepth >= 2): ได้รับ sessions_spawn, subagents, sessions_list, sessions_history เพื่อให้จัดการลูกของตนได้ เครื่องมือเซสชัน/ระบบอื่น ๆ ยังคงถูกปฏิเสธ
• ความลึก 1 (leaf, เมื่อ maxSpawnDepth == 1): ไม่มีเครื่องมือเซสชัน (พฤติกรรมเริ่มต้นปัจจุบัน)
• ความลึก 2 (leaf worker): ไม่มีเครื่องมือเซสชัน — sessions_spawn จะถูกปฏิเสธเสมอที่ความลึก 2 ไม่สามารถ spawn ลูกเพิ่มเติมได้

​

ขีดจำกัดการ spawn ต่อเอเจนต์

​

การหยุดแบบ cascade

• /stop ในแชตหลักจะหยุดเอเจนต์ความลึก 1 ทั้งหมดและ cascade ไปยังลูกความลึก 2 ของพวกมัน
• /subagents kill <id> หยุดซับเอเจนต์ที่ระบุและ cascade ไปยังลูกของมัน
• /subagents kill all หยุดซับเอเจนต์ทั้งหมดของผู้ร้องขอและ cascade

​

การยืนยันตัวตน

• คีย์เซสชันซับเอเจนต์คือ agent:<agentId>:subagent:<uuid>
• auth store ถูกโหลดจาก agentDir ของเอเจนต์นั้น
• โปรไฟล์ auth ของเอเจนต์หลักจะถูกผสานเข้าเป็น fallback; โปรไฟล์เอเจนต์จะ override โปรไฟล์หลักเมื่อมีความขัดแย้ง

​

ประกาศ

• ขั้นตอนประกาศทำงานภายในเซสชันซับเอเจนต์ (ไม่ใช่เซสชันผู้ร้องขอ)
• หากซับเอเจนต์ตอบกลับว่า ANNOUNCE_SKIP แบบตรงตัว จะไม่มีการโพสต์สิ่งใด
• หากข้อความ assistant ล่าสุดเป็นโทเค็นเงียบแบบตรงตัว NO_REPLY / no_reply เอาต์พุตประกาศจะถูกระงับ แม้เคยมีความคืบหน้าที่มองเห็นได้ก่อนหน้า

• เซสชันผู้ร้องขอระดับบนใช้การเรียก agent แบบ follow-up พร้อมการส่งมอบภายนอก (deliver=true)
• เซสชันซับเอเจนต์ผู้ร้องขอที่ซ้อนกันจะได้รับการฉีด follow-up ภายใน (deliver=false) เพื่อให้ orchestrator สามารถสังเคราะห์ผลลัพธ์ลูกภายในเซสชันได้
• หากเซสชันซับเอเจนต์ผู้ร้องขอที่ซ้อนกันหายไป OpenClaw จะ fallback ไปยังผู้ร้องขอของเซสชันนั้นเมื่อพร้อมใช้งาน

​

บริบทประกาศ

​

บรรทัดสถิติ

• รันไทม์ (เช่น runtime 5m12s)
• การใช้โทเค็น (input/output/total)
• ค่าใช้จ่ายโดยประมาณเมื่อมีการตั้งค่าราคาโมเดล (models.providers.*.models[].cost)
• sessionKey, sessionId และเส้นทาง transcript เพื่อให้เอเจนต์หลักดึงประวัติผ่าน sessions_history หรือตรวจไฟล์บนดิสก์ได้

​

เหตุผลที่ควรเลือก sessions_history

• การเรียกคืนของ assistant ถูกทำให้เป็นมาตรฐานก่อน: ลบ thinking tags; ลบ scaffolding <relevant-memories> / <relevant_memories>; ลบบล็อก payload XML การเรียกเครื่องมือแบบข้อความล้วน (<tool_call>, <function_call>, <tool_calls>, <function_calls>) รวมถึง payload ที่ถูกตัดและปิดไม่สมบูรณ์; ลบ scaffolding การเรียก/ผลลัพธ์เครื่องมือที่ถูกลดระดับและ marker บริบทประวัติ; ลบโทเค็นควบคุมโมเดลที่รั่ว (<|assistant|>, ASCII <|...|> อื่น ๆ, แบบ full-width <｜...｜>); ลบ XML การเรียกเครื่องมือ MiniMax ที่ malformed
• ข้อความที่คล้าย credential/token จะถูก redact
• บล็อกยาวสามารถถูกตัดให้สั้นลงได้
• ประวัติขนาดใหญ่มากสามารถทิ้งแถวเก่ากว่าหรือแทนที่แถวที่ใหญ่เกินด้วย [sessions_history omitted: message too large]
• การตรวจ transcript ดิบบนดิสก์เป็น fallback เมื่อคุณต้องการ transcript แบบ byte-for-byte เต็มรูปแบบ

​

นโยบายเครื่องมือ

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

Override ผ่าน 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: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

​

Concurrency

• ชื่อ lane: subagent
• Concurrency: agents.defaults.subagents.maxConcurrent (ค่าเริ่มต้น 8)

​

Liveness และการกู้คืน

​

การหยุด

• การส่ง /stop ในแชตผู้ร้องขอจะ abort เซสชันผู้ร้องขอและหยุดรันซับเอเจนต์ที่ยังทำงานอยู่ซึ่ง spawn จากเซสชันนั้น พร้อม cascade ไปยังลูกที่ซ้อนอยู่
• /subagents kill <id> หยุดซับเอเจนต์ที่ระบุและ cascade ไปยังลูกของมัน

​

ข้อจำกัด

• การประกาศของซับเอเจนต์เป็นแบบ best-effort หาก gateway รีสตาร์ท งาน “announce back” ที่ pending จะหายไป
• ซับเอเจนต์ยังคงใช้ทรัพยากร process ของ gateway เดียวกัน; ให้ถือว่า maxConcurrent เป็นวาล์วนิรภัย
• sessions_spawn เป็นแบบ non-blocking เสมอ: ส่งคืน { status: "accepted", runId, childSessionKey } ทันที
• บริบทซับเอเจนต์ฉีดเฉพาะ AGENTS.md, TOOLS.md, SOUL.md, IDENTITY.md และ USER.md (ไม่มี MEMORY.md, HEARTBEAT.md หรือ BOOTSTRAP.md)
• ความลึกการซ้อนสูงสุดคือ 5 (maxSpawnDepth range: 1–5) แนะนำให้ใช้ความลึก 2 สำหรับกรณีใช้งานส่วนใหญ่
• maxChildrenPerAgent จำกัดจำนวนลูกที่ทำงานอยู่ต่อเซสชัน (ค่าเริ่มต้น 5, range 1–20)

​

ที่เกี่ยวข้อง

• เอเจนต์ ACP
• ส่งเอเจนต์
• งานเบื้องหลัง
• เครื่องมือแซนด์บ็อกซ์หลายเอเจนต์