การรันเบื้องหลัง + เครื่องมือจัดการโปรเซส¶

OpenClaw รันคำสั่งเชลล์ผ่านเครื่องมือ exec และเก็บงานที่รันเป็นเวลานานไว้ในหน่วยความจำ เครื่องมือ process ใช้จัดการเซสชันเบื้องหลังเหล่านั้น The process tool manages those background sessions.

exec tool¶

พารามิเตอร์หลัก:

• command (จำเป็น)
• yieldMs (ค่าเริ่มต้น 10000): ย้ายไปเบื้องหลังอัตโนมัติหลังดีเลย์นี้
• background (bool): เริ่มทำงานในเบื้องหลังทันที
• timeout (วินาที, ค่าเริ่มต้น 1800): ยุติโพรเซสหลังหมดเวลา
• elevated (bool): รันบนโฮสต์หากโหมดยกระดับถูกเปิดใช้งาน/อนุญาต
• ต้องการ TTY จริงหรือไม่? ตั้งค่า pty: true.
• workdir, env

พฤติกรรม:

• การรันแบบ foreground จะส่งเอาต์พุตกลับโดยตรง
• เมื่อย้ายไปเบื้องหลัง (ระบุชัดเจนหรือจากการหมดเวลา) เครื่องมือจะส่งคืน status: "running" + sessionId และส่วนท้ายแบบย่อ
• เอาต์พุตจะถูกเก็บไว้ในหน่วยความจำจนกว่าจะมีการโพลหรือเคลียร์เซสชัน
• หากเครื่องมือ process ไม่ได้รับอนุญาต exec จะรันแบบซิงโครนัสและละเว้น yieldMs/background.

การเชื่อมต่อกับโปรเซสลูก¶

เมื่อสปอว์นโพรเซสลูกที่รันยาวนานนอกเครื่องมือ exec/process (เช่น การ respawn ของ CLI หรือ helper ของ Gateway) ให้ผูกตัวช่วยบริดจ์โพรเซสลูกเพื่อให้สัญญาณยุติถูกส่งต่อ และถอดตัวรับฟังเมื่อออก/เกิดข้อผิดพลาด วิธีนี้ช่วยหลีกเลี่ยงโพรเซสกำพร้าบน systemd และทำให้พฤติกรรมการปิดระบบสอดคล้องกันข้ามแพลตฟอร์ม This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.

การแทนค่าด้วย environment:

• PI_BASH_YIELD_MS: yield เริ่มต้น (มิลลิวินาที)
• PI_BASH_MAX_OUTPUT_CHARS: เพดานเอาต์พุตในหน่วยความจำ (ตัวอักษร)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: เพดาน stdout/stderr ที่ค้างอยู่ต่อสตรีม (ตัวอักษร)
• PI_BASH_JOB_TTL_MS: TTL สำหรับเซสชันที่เสร็จสิ้นแล้ว (มิลลิวินาที, จำกัดไว้ที่ 1 นาที–3 ชั่วโมง)

คอนฟิก (แนะนำ):

• tools.exec.backgroundMs (ค่าเริ่มต้น 10000)
• tools.exec.timeoutSec (ค่าเริ่มต้น 1800)
• tools.exec.cleanupMs (ค่าเริ่มต้น 1800000)
• tools.exec.notifyOnExit (ค่าเริ่มต้น true): เข้าคิวอีเวนต์ของระบบ + ขอฮาร์ตบีตเมื่อ exec ที่รันเบื้องหลังออกจากการทำงาน

process tool¶

การกระทำ:

• list: เซสชันที่กำลังรัน + ที่เสร็จสิ้น
• poll: ระบายเอาต์พุตใหม่สำหรับเซสชัน (รายงานสถานะการออกด้วย)
• log: อ่านเอาต์พุตที่ถูกรวม (รองรับ offset + limit)
• write: ส่ง stdin (data, eof เป็นทางเลือก)
• kill: ยุติเซสชันเบื้องหลัง
• clear: ลบเซสชันที่เสร็จสิ้นแล้วออกจากหน่วยความจำ
• remove: ฆ่าโพรเซสหากกำลังรัน มิฉะนั้นให้เคลียร์หากเสร็จสิ้นแล้ว

หมายเหตุ:

• แสดงรายการ/คงอยู่ในหน่วยความจำเฉพาะเซสชันที่รันเบื้องหลังเท่านั้น
• เซสชันจะสูญหายเมื่อรีสตาร์ตโพรเซส (ไม่มีการบันทึกลงดิสก์)
• ล็อกของเซสชันจะถูกบันทึกลงประวัติแช็ตก็ต่อเมื่อคุณรัน process poll/log และมีการบันทึกผลลัพธ์ของเครื่องมือ
• process มีขอบเขตต่อเอเจนต์; จะเห็นเฉพาะเซสชันที่เริ่มโดยเอเจนต์นั้น
• process list รวม name ที่ได้มาจากการประมวลผล (กริยาคำสั่ง + เป้าหมาย) เพื่อสแกนอย่างรวดเร็ว
• process log ใช้ offset/limit แบบอิงบรรทัด (ละเว้น offset เพื่อดึง N บรรทัดสุดท้าย)

ตัวอย่าง¶

รันงานยาวและโพลภายหลัง:

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

เริ่มในเบื้องหลังทันที:

{ "tool": "exec", "command": "npm run build", "background": true }

ส่ง stdin:

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }