วงรอบเอเจนต์

ลูปเอเจนต์คือการทำงานต่อเซสชันแบบอนุกรมที่เปลี่ยนข้อความให้เป็น การดำเนินการและการตอบกลับ ได้แก่ การรับข้อมูล การประกอบบริบท การอนุมานของโมเดล การเรียกใช้เครื่องมือ การสตรีม และการคงข้อมูล

จุดเริ่มต้น

• Gateway RPC: agent และ agent.wait
• CLI: openclaw agent

ลำดับการทำงาน

1. agent RPC ตรวจสอบพารามิเตอร์ แก้ไขเซสชัน (sessionKey/sessionId) คงข้อมูลเมตาของเซสชัน และส่งคืน { runId, acceptedAt } ทันที
2. agentCommand ดำเนินรอบการทำงาน: แก้ไขค่าเริ่มต้นของโมเดล + การคิด/ความละเอียด/การติดตาม โหลดสแนปช็อต Skills เรียก runEmbeddedAgent และส่งเหตุการณ์สำรอง สิ้นสุดวงจรชีวิต/ข้อผิดพลาด หากลูปที่ฝังอยู่ยังไม่ได้ส่งเหตุการณ์ดังกล่าว
3. runEmbeddedAgent: จัดลำดับการทำงานแบบอนุกรมผ่านคิวต่อเซสชันและคิวส่วนกลาง แก้ไขโมเดล + โปรไฟล์การยืนยันตัวตน สร้างเซสชัน OpenClaw สมัครรับเหตุการณ์รันไทม์ สตรีมเดลตาของผู้ช่วย/เครื่องมือ บังคับใช้ระยะหมดเวลาของการทำงาน (ยกเลิกเมื่อหมดเวลา) และส่งคืนเพย์โหลดพร้อมข้อมูลเมตาการใช้งาน สำหรับรอบการทำงานของ Codex app-server ยังยกเลิกรอบที่ยอมรับแล้วด้วย หากหยุดสร้างความคืบหน้าของ app-server ก่อนเกิดเหตุการณ์สิ้นสุด
4. subscribeEmbeddedAgentSession เชื่อมเหตุการณ์รันไทม์เข้ากับสตรีม agent: เหตุการณ์เครื่องมือไปยัง stream: "tool" เดลตาของผู้ช่วยไปยัง stream: "assistant" และเหตุการณ์วงจรชีวิตไปยัง stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait (waitForAgentRun) รอ สิ้นสุดวงจรชีวิต/ข้อผิดพลาด บน runId และส่งคืน { status: ok|error|timeout, startedAt, endedAt, error? }

การเข้าคิวและภาวะพร้อมกัน

การทำงานจะถูกจัดลำดับแบบอนุกรมตามคีย์เซสชัน (เลนเซสชัน) และอาจผ่านเลนส่วนกลางด้วย เพื่อป้องกันสภาวะแข่งขันของเครื่องมือ/เซสชัน ช่องทางการรับส่งข้อความจะเลือกโหมดคิว (steer/followup/collect/interrupt) ที่ป้อนเข้าสู่ระบบเลนนี้ โปรดดู คิวคำสั่ง

การเขียนทรานสคริปต์ยังได้รับการป้องกันเพิ่มเติมด้วยล็อกการเขียนเซสชันบนไฟล์เซสชัน ล็อกนี้รับรู้กระบวนการและทำงานบนไฟล์ จึงตรวจจับผู้เขียนที่ข้ามคิวภายในกระบวนการหรือมาจากกระบวนการอื่นได้ โดยค่าเริ่มต้น ผู้เขียนจะรอได้สูงสุด 60 วินาที (แทนที่ด้วยตัวแปรสภาพแวดล้อม OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) ก่อนรายงานว่าเซสชันไม่ว่าง

โดยค่าเริ่มต้น ล็อกการเขียนเซสชันไม่รองรับการกลับเข้าซ้ำ ตัวช่วยที่ตั้งใจซ้อนการขอล็อกเดียวกันโดยยังคงผู้เขียนเชิงตรรกะเพียงรายเดียวไว้ ต้องเลือกใช้ allowReentrant: true

การเตรียมเซสชันและพื้นที่ทำงาน

• พื้นที่ทำงานได้รับการแก้ไขและสร้างขึ้น การทำงานในแซนด์บ็อกซ์อาจเปลี่ยนเส้นทางไปยังรากพื้นที่ทำงานของแซนด์บ็อกซ์
• โหลด Skills (หรือนำกลับมาใช้จากสแนปช็อต) และแทรกลงในสภาพแวดล้อมและพรอมต์
• แก้ไขไฟล์บูตสแตรป/บริบทและแทรกลงในพรอมต์ระบบ
• ขอล็อกการเขียนเซสชันและเตรียมเป้าหมายทรานสคริปต์ของเซสชันก่อนเริ่มสตรีม เส้นทางที่เขียนทรานสคริปต์ใหม่ ทำ Compaction หรือตัดทอนในภายหลัง ต้องขอล็อกเดียวกันก่อนแก้ไขแถวทรานสคริปต์ใน SQLite

การประกอบพรอมต์

พรอมต์ระบบสร้างขึ้นจากพรอมต์พื้นฐานของ OpenClaw พรอมต์ Skills บริบทบูตสแตรป และค่าที่แทนที่สำหรับแต่ละการทำงาน โดยบังคับใช้ขีดจำกัดเฉพาะโมเดลและโทเค็นสำรองสำหรับ Compaction โปรดดู พรอมต์ระบบ สำหรับสิ่งที่โมเดลมองเห็น

ฮุก

OpenClaw มีระบบฮุกสองระบบ:

• ฮุกภายใน (ฮุก Gateway): สคริปต์ที่ขับเคลื่อนด้วยเหตุการณ์สำหรับคำสั่งและเหตุการณ์วงจรชีวิต
• ฮุก Plugin: จุดขยายภายในวงจรชีวิตของเอเจนต์/เครื่องมือและไปป์ไลน์ Gateway

ฮุกภายใน (ฮุก Gateway)

• agent:bootstrap: ทำงานขณะสร้างไฟล์บูตสแตรปก่อนพรอมต์ระบบเสร็จสมบูรณ์ ใช้เพื่อเพิ่มหรือลบไฟล์บริบทบูตสแตรป
• ฮุกคำสั่ง: /new, /reset, /stop และเหตุการณ์คำสั่งอื่น ๆ (ดูเอกสารฮุก)

โปรดดู ฮุก สำหรับการตั้งค่าและตัวอย่าง

ฮุก Plugin

ฮุกเหล่านี้ทำงานภายในลูปเอเจนต์หรือไปป์ไลน์ Gateway:

กฎการตัดสินใจของฮุกสำหรับตัวป้องกันขาออก/เครื่องมือ:

• before_tool_call: { block: true } เป็นผลลัพธ์สิ้นสุดและหยุดตัวจัดการที่มีลำดับความสำคัญต่ำกว่า { block: false } ไม่ดำเนินการใด ๆ และไม่ล้างการบล็อกก่อนหน้า
• before_install: มีความหมายด้านการสิ้นสุด/ไม่ดำเนินการเช่นเดียวกับด้านบน ใช้ security.installPolicy ไม่ใช่ before_install สำหรับการตัดสินใจอนุญาต/บล็อกการติดตั้งที่ผู้ปฏิบัติงานเป็นเจ้าของ ซึ่งต้องครอบคลุมเส้นทางการติดตั้งและอัปเดตผ่าน CLI
• message_sending: { cancel: true } เป็นผลลัพธ์สิ้นสุดและหยุดตัวจัดการที่มีลำดับความสำคัญต่ำกว่า { cancel: false } ไม่ดำเนินการใด ๆ และไม่ล้างการยกเลิกก่อนหน้า

โปรดดู ฮุก Plugin สำหรับ API ของฮุกและรายละเอียดการลงทะเบียน

ฮาร์เนสสามารถปรับใช้ฮุกเหล่านี้ได้ ฮาร์เนส Codex app-server ใช้ฮุก Plugin ของ OpenClaw เป็นสัญญาความเข้ากันได้สำหรับพื้นผิวที่ทำสำเนาตามเอกสาร ส่วนฮุกเนทีฟของ Codex เป็นกลไก Codex ระดับต่ำที่แยกต่างหาก

การสตรีม

• เดลตาของผู้ช่วยสตรีมจากรันไทม์เอเจนต์เป็นเหตุการณ์ assistant
• การสตรีมแบบบล็อกสามารถส่งคำตอบบางส่วนบน text_end หรือ message_end
• การสตรีมกระบวนการให้เหตุผลอาจเป็นสตรีมแยกต่างหากหรือเป็นคำตอบแบบบล็อก
• โปรดดู การสตรีม สำหรับลักษณะการแบ่งส่วนและคำตอบแบบบล็อก

การเรียกใช้เครื่องมือ

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

การจัดรูปแบบคำตอบ

เพย์โหลดสุดท้ายประกอบขึ้นจากข้อความของผู้ช่วย (รวมกระบวนการให้เหตุผลที่เลือกเปิดใช้ได้) สรุปเครื่องมือแบบอินไลน์ (เมื่อเปิดโหมดละเอียดและได้รับอนุญาต) และข้อความข้อผิดพลาดของผู้ช่วยเมื่อโมเดลเกิดข้อผิดพลาด

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

Compaction และการลองใหม่

Compaction อัตโนมัติจะส่งเหตุการณ์สตรีม compaction และสามารถกระตุ้นการลองใหม่ เมื่อมีการลองใหม่ บัฟเฟอร์ในหน่วยความจำและสรุปเครื่องมือจะถูกรีเซ็ตเพื่อหลีกเลี่ยงผลลัพธ์ซ้ำ โปรดดู Compaction

สตรีมเหตุการณ์

• lifecycle: ส่งโดย subscribeEmbeddedAgentSession (และส่งเป็นเหตุการณ์สำรองโดย agentCommand)
• assistant: เดลตาที่สตรีมจากรันไทม์เอเจนต์
• tool: เหตุการณ์เครื่องมือที่สตรีมจากรันไทม์เอเจนต์

Gateway ฉายเหตุการณ์วงจรชีวิตและเหตุการณ์เริ่มต้น/สิ้นสุดของเครื่องมือไปยัง บัญชีแยกประเภทการตรวจสอบ ที่มีขอบเขตจำกัดและเก็บเฉพาะข้อมูลเมตา การฉายนี้บันทึกที่มาและ รหัสผลลัพธ์โดยไม่คัดลอกพรอมต์ ข้อความ อาร์กิวเมนต์ของเครื่องมือ ผลลัพธ์ของเครื่องมือ หรือข้อผิดพลาดดิบออกจากเส้นทางทรานสคริปต์/รันไทม์

การจัดการช่องทางแชต

เดลตาของผู้ช่วยจะถูกบัฟเฟอร์ลงในข้อความแชต delta ระบบจะส่งแชต final เมื่อเกิด สิ้นสุดวงจรชีวิต/ข้อผิดพลาด

การหมดเวลา

การวินิจฉัยเซสชันที่ค้าง

เมื่อเปิดใช้การวินิจฉัย เกณฑ์สองนาทีในตัวจะจำแนกเซสชัน processing ที่ทำงานนานโดยไม่พบความคืบหน้าของการตอบกลับ เครื่องมือ สถานะ บล็อก หรือ ACP:

• การทำงานแบบฝัง การเรียกโมเดล และการเรียกเครื่องมือที่ยังทำงานอยู่จะรายงานเป็น session.long_running การเรียกโมเดลที่อยู่ภายใต้การควบคุมและไม่มีเอาต์พุตจะยังคงเป็น session.long_running จนถึงเกณฑ์การยกเลิก เพื่อไม่ให้ผู้ให้บริการที่ทำงานช้าหรือไม่ใช้สตรีมถูกระบุว่าหยุดชะงักเร็วเกินไป
• งานที่ยังทำงานอยู่แต่ไม่มีความคืบหน้าล่าสุดจะรายงานเป็น session.stalled การเรียกโมเดลที่อยู่ภายใต้การควบคุมจะเปลี่ยนเป็น session.stalled เมื่อถึงหรือผ่านเกณฑ์การยกเลิก; กิจกรรมโมเดล/เครื่องมือที่ค้างและไม่มีเจ้าของจะไม่ถูกซ่อนไว้ว่าเป็นงานที่ทำงานยาวนาน
• session.stuck สงวนไว้สำหรับข้อมูลการจัดการเซสชันที่ค้างซึ่งกู้คืนได้ รวมถึงเซสชันในคิวที่ไม่มีการทำงานแต่ยังมีกิจกรรมโมเดล/เครื่องมือที่ค้างและไม่มีเจ้าของ

เกณฑ์การยกเลิกมีค่าอย่างน้อย 5 นาทีและเป็น 3 เท่าของเกณฑ์การเตือน การจัดการเซสชันที่ค้างจะปล่อยเลนของเซสชันที่ได้รับผลกระทบทันทีหลังผ่านเกณฑ์การกู้คืน; การทำงานแบบฝังที่หยุดชะงักจะถูกยกเลิกและระบายออกหลังจากผ่านเกณฑ์การยกเลิกเท่านั้น เพื่อให้งานในคิวกลับมาทำงานต่อได้โดยไม่ตัดการทำงานที่เพียงแค่ช้า การกู้คืนจะส่งผลลัพธ์แบบมีโครงสร้างสำหรับสถานะที่ร้องขอ/เสร็จสมบูรณ์; สถานะการวินิจฉัยจะถูกทำเครื่องหมายว่าไม่มีการทำงานก็ต่อเมื่อรุ่นการประมวลผลเดียวกันยังเป็นรุ่นปัจจุบัน และการวินิจฉัย session.stuck ซ้ำจะเพิ่มช่วงเว้นระยะขณะที่เซสชันยังคงไม่เปลี่ยนแปลง

จุดที่การทำงานอาจสิ้นสุดก่อนกำหนด

• เอเจนต์หมดเวลา (ยกเลิก)
• AbortSignal (ยกเลิก)
• Gateway ตัดการเชื่อมต่อหรือ RPC หมดเวลา
• agent.wait หมดเวลา (รอเท่านั้น ไม่หยุดเอเจนต์)

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

• เครื่องมือ - เครื่องมือที่เอเจนต์ใช้ได้
• ฮุก - สคริปต์ที่ขับเคลื่อนด้วยเหตุการณ์ซึ่งทริกเกอร์โดยเหตุการณ์ในวงจรชีวิตของเอเจนต์
• Compaction - วิธีสรุปบทสนทนาที่ยาว
• การอนุมัติการดำเนินการ - ด่านการอนุมัติสำหรับคำสั่งเชลล์
• การคิด - การกำหนดค่าระดับการคิด/การให้เหตุผล