Fundamentals

ลูปเอเจนต์

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

จุดเริ่มต้น

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

ลำดับการรัน

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

การจัดคิวและการทำงานพร้อมกัน

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

การเขียนทรานสคริปต์ยังได้รับการป้องกันเพิ่มเติมด้วยล็อกการเขียนเซสชันบนไฟล์เซสชัน ล็อกนี้รับรู้กระบวนการและทำงานบนไฟล์ จึงตรวจพบตัวเขียนที่ข้ามคิวภายในกระบวนการหรือมาจากกระบวนการอื่นได้ ตัวเขียนจะรอนานสูงสุด session.writeLock.acquireTimeoutMs (ค่าเริ่มต้น 60000 ms; เขียนทับด้วยตัวแปรสภาพแวดล้อม 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_model_resolve`	ก่อนเซสชัน (ไม่มี `messages`) เพื่อเขียนทับผู้ให้บริการ/โมเดลก่อนการแก้ไขอย่างแน่นอน
`before_prompt_build`	หลังโหลดเซสชัน (พร้อม `messages`) เพื่อแทรก `prependContext`, `systemPrompt`, `prependSystemContext` หรือ `appendSystemContext` ก่อนส่ง ใช้ `prependContext` สำหรับข้อความแบบไดนามิกต่อรอบ และใช้ฟิลด์บริบทระบบสำหรับคำแนะนำที่คงที่ซึ่งควรอยู่ในพื้นที่พรอมต์ระบบ
`before_agent_start`	ฮุกความเข้ากันได้แบบเดิมที่อาจรันในเฟสใดก็ได้ ควรใช้ฮุกที่ระบุชัดเจนด้านบน
`before_agent_reply`	หลังการดำเนินการแบบอินไลน์ ก่อนเรียก LLM ช่วยให้ Plugin รับช่วงรอบการทำงานและส่งคืนคำตอบสังเคราะห์หรือระงับคำตอบทั้งหมดได้
`agent_end`	หลังเสร็จสิ้น พร้อมรายการข้อความสุดท้ายและข้อมูลเมตาการรัน
`before_compaction` / `after_compaction`	สังเกตหรือใส่คำอธิบายประกอบรอบ Compaction
`before_tool_call` / `after_tool_call`	ดักพารามิเตอร์/ผลลัพธ์ของเครื่องมือ
`before_install`	หลังนโยบายการติดตั้งของผู้ดำเนินการทำงาน บนวัสดุติดตั้ง Skills/Plugin ที่จัดเตรียมไว้ เมื่อโหลดฮุก Plugin ในกระบวนการปัจจุบัน
`tool_result_persist`	แปลงผลลัพธ์ของเครื่องมือแบบซิงโครนัสก่อนเขียนลงในทรานสคริปต์เซสชันที่ OpenClaw เป็นเจ้าของ
`message_received` / `message_sending` / `message_sent`	ฮุกข้อความขาเข้าและขาออก
`session_start` / `session_end`	ขอบเขตวงจรการทำงานของเซสชัน
`gateway_start` / `gateway_stop`	เหตุการณ์วงจรการทำงานของ 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 ของแชตเมื่อเกิด สิ้นสุดวงจรการทำงาน/ข้อผิดพลาด

การหมดเวลา

ระยะหมดเวลา	ค่าเริ่มต้น	หมายเหตุ
`agent.wait`	30s	ใช้สำหรับรอเท่านั้น พารามิเตอร์ `timeoutMs` จะเขียนทับค่านี้ และไม่หยุดการทำงานเบื้องหลัง
รันไทม์ของเอเจนต์ (`agents.defaults.timeoutSeconds`)	172800s (48h)	บังคับใช้โดยตัวจับเวลายกเลิกของ `runEmbeddedAgent` ตั้งค่า `0` เพื่อให้งบเวลาการทำงานไม่จำกัด โดยตัวเฝ้าระวังความพร้อมใช้งานของสตรีมโมเดลยังคงมีผล
รอบการทำงานของเอเจนต์แบบแยกของ Cron	Cron เป็นผู้ดูแล	ตัวจัดกำหนดการเริ่มตัวจับเวลาของตนเองเมื่อเริ่มดำเนินการ ยกเลิกการทำงานเมื่อถึงกำหนดเวลาที่กำหนด จากนั้นดำเนินการล้างข้อมูลภายในขอบเขตที่จำกัดก่อนบันทึกการหมดเวลา เพื่อไม่ให้เซสชันลูกที่ค้างอยู่ทำให้ช่องทางติดค้าง
ระยะหมดเวลาเมื่อโมเดลไม่มีการทำงาน	Cloud 120s; โฮสต์เอง 300s	OpenClaw ยกเลิกคำขอโมเดลเมื่อไม่มีชิ้นส่วนการตอบกลับมาถึงก่อนสิ้นสุดช่วงเวลาที่ไม่มีการทำงาน `models.providers.<id>.timeoutSeconds` ขยายตัวเฝ้าระวังการไม่มีการทำงานนี้สำหรับผู้ให้บริการแบบภายในเครื่อง/โฮสต์เองที่ช้า แต่ยังคงถูกจำกัดด้วย `agents.defaults.timeoutSeconds` แบบจำกัดเวลาใดๆ ที่ต่ำกว่า หรือระยะหมดเวลาเฉพาะการทำงาน เนื่องจากค่าเหล่านั้นควบคุมการทำงานของเอเจนต์ทั้งหมด งบเวลาการทำงานแบบไม่จำกัดยังคงใช้ตัวเฝ้าระวังการไม่มีการทำงานตามประเภทผู้ให้บริการ การทำงานของโมเดล Cloud ที่ทริกเกอร์โดย Cron โดยไม่มีระยะหมดเวลาของโมเดล/เอเจนต์ที่ระบุอย่างชัดเจนจะใช้ค่าเริ่มต้นเดียวกัน แต่เมื่อระบุระยะหมดเวลาการทำงานของ Cron อย่างชัดเจน การหยุดชะงักของสตรีมโมเดล Cloud จะถูกจำกัดไว้ที่ 60s เพื่อให้โมเดลสำรองที่กำหนดค่าไว้ยังทำงานได้ก่อนถึงกำหนดเวลาภายนอกของ Cron การทำงานที่ทริกเกอร์โดย Cron บนปลายทางภายในเครื่องอย่างแท้จริง (loopback/baseUrl ส่วนตัว) จะยังคงเลือกไม่ใช้ระยะหมดเวลาการไม่มีการทำงานภายในเครื่อง ส่วนผู้ให้บริการที่โฮสต์เองบน baseUrl เครือข่ายจะได้รับตัวเฝ้าระวังโดยนัยที่ 300s เมื่อระบุระยะหมดเวลาการทำงานของ Cron อย่างชัดเจน การหยุดชะงักของระบบภายในเครื่อง/ที่โฮสต์เองจะถูกจำกัดตามระยะหมดเวลานั้น ตั้งค่า `models.providers.<id>.timeoutSeconds` สำหรับผู้ให้บริการภายในเครื่องที่ช้า
ระยะหมดเวลาคำขอ HTTP ของผู้ให้บริการ	`models.providers.<id>.timeoutSeconds`	ครอบคลุมการเชื่อมต่อ ส่วนหัว เนื้อหา ระยะหมดเวลาคำขอของ SDK การจัดการการยกเลิกของ guarded-fetch และตัวเฝ้าระวังการไม่มีการทำงานของสตรีมโมเดลสำหรับผู้ให้บริการนั้น ใช้สำหรับผู้ให้บริการแบบภายในเครื่อง/โฮสต์เองที่ช้า (เช่น Ollama) ก่อนเพิ่มระยะหมดเวลารันไทม์ของเอเจนต์ทั้งหมด และกำหนดระยะหมดเวลาของเอเจนต์/รันไทม์ให้สูงเท่ากันหรือสูงกว่าเมื่อคำขอโมเดลต้องทำงานนานขึ้น

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

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

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

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

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

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

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

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

Was this useful?