Skip to main content

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.

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

​
เครื่องมือ exec

พารามิเตอร์หลัก:
  • command (จำเป็น)
  • yieldMs (ค่าเริ่มต้น 10000): ย้ายไปทำงานเบื้องหลังโดยอัตโนมัติหลังจากหน่วงเวลานี้
  • background (bool): ทำงานเบื้องหลังทันที
  • timeout (วินาที, ค่าเริ่มต้น tools.exec.timeoutSec): ยุติกระบวนการหลังจากหมดเวลานี้; ตั้งค่า timeout: 0 เฉพาะเมื่อต้องการปิดการหมดเวลาของกระบวนการ exec สำหรับการเรียกครั้งนั้น
  • elevated (bool): ทำงานนอก sandbox หากเปิดใช้/อนุญาตโหมด elevated (gateway เป็นค่าเริ่มต้น หรือ node เมื่อเป้าหมาย exec คือ node)
  • ต้องใช้ TTY จริงหรือไม่? ตั้งค่า pty: true
  • workdir, env
ลักษณะการทำงาน:
  • การทำงานเบื้องหน้าจะคืนเอาต์พุตโดยตรง
  • เมื่อถูกย้ายไปทำงานเบื้องหลัง (ระบุชัดเจนหรือหมดเวลา) เครื่องมือจะคืน status: "running" + sessionId และส่วนท้ายสั้นๆ
  • การทำงานเบื้องหลังและการทำงานด้วย yieldMs จะสืบทอดค่า tools.exec.timeoutSec เว้นแต่การเรียกจะระบุ timeout ชัดเจน
  • เอาต์พุตจะถูกเก็บไว้ในหน่วยความจำจนกว่าเซสชันจะถูก poll หรือล้าง
  • หากไม่อนุญาตเครื่องมือ process คำสั่ง exec จะทำงานแบบ synchronous และละเว้น yieldMs/background
  • คำสั่ง exec ที่ถูก spawn จะได้รับ OPENCLAW_SHELL=exec สำหรับกฎเชลล์/โปรไฟล์ที่รับรู้บริบท
  • สำหรับงานที่ทำงานนานและเริ่มตอนนี้ ให้เริ่มเพียงครั้งเดียวและพึ่งพาการปลุกเมื่อเสร็จสิ้นโดยอัตโนมัติ เมื่อเปิดใช้งานและคำสั่งมีเอาต์พุตหรือทำงานล้มเหลว
  • หากไม่มีการปลุกเมื่อเสร็จสิ้นโดยอัตโนมัติ หรือคุณต้องการยืนยันความสำเร็จแบบเงียบ สำหรับคำสั่งที่ออกสำเร็จโดยไม่มีเอาต์พุต ให้ใช้ process เพื่อยืนยันการเสร็จสิ้น
  • อย่าจำลองการเตือนความจำหรือการติดตามผลแบบหน่วงเวลาด้วยลูป sleep หรือการ poll ซ้ำ; ใช้ cron สำหรับงานในอนาคต

​
การเชื่อมต่อกระบวนการลูก

เมื่อ spawn กระบวนการลูกที่ทำงานนานนอกเครื่องมือ exec/process (เช่น การ respawn ของ CLI หรือ helper ของ Gateway) ให้แนบ helper สะพานกระบวนการลูก เพื่อส่งต่อสัญญาณการยุติและถอด listener เมื่อ exit/error วิธีนี้ช่วยหลีกเลี่ยงกระบวนการค้างบน systemd และทำให้ลักษณะการปิดระบบสอดคล้องกันข้ามแพลตฟอร์ม การ override สภาพแวดล้อม:
  • PI_BASH_YIELD_MS: ค่า yield เริ่มต้น (ms)
  • PI_BASH_MAX_OUTPUT_CHARS: ขีดจำกัดเอาต์พุตในหน่วยความจำ (chars)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: ขีดจำกัด stdout/stderr ที่รอดำเนินการต่อสตรีม (chars)
  • PI_BASH_JOB_TTL_MS: TTL สำหรับเซสชันที่เสร็จแล้ว (ms, จำกัดอยู่ที่ 1m–3h)
  • OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: เกณฑ์เอาต์พุตว่างก่อนทำเครื่องหมายเซสชันเบื้องหลังที่เขียนได้ว่าน่าจะกำลังรออินพุต (ค่าเริ่มต้น 15000 ms)
การกำหนดค่า (แนะนำ):
  • tools.exec.backgroundMs (ค่าเริ่มต้น 10000)
  • tools.exec.timeoutSec (ค่าเริ่มต้น 1800)
  • tools.exec.cleanupMs (ค่าเริ่มต้น 1800000)
  • tools.exec.notifyOnExit (ค่าเริ่มต้น true): เพิ่มอีเวนต์ระบบลงคิว + ขอ Heartbeat เมื่อ exec ที่ทำงานเบื้องหลังออก
  • tools.exec.notifyOnExitEmptySuccess (ค่าเริ่มต้น false): เมื่อเป็น true จะเพิ่มอีเวนต์การเสร็จสิ้นสำหรับการทำงานเบื้องหลังที่สำเร็จแต่ไม่มีเอาต์พุตด้วย

​
เครื่องมือ process

การดำเนินการ:
  • list: เซสชันที่กำลังทำงาน + เสร็จแล้ว
  • poll: ระบายเอาต์พุตใหม่สำหรับเซสชัน (รายงานสถานะการออกด้วย)
  • log: อ่านเอาต์พุตที่รวมไว้และแสดงคำแนะนำการกู้คืนอินพุต (รองรับ offset + limit)
  • write: ส่ง stdin (data, eof ที่ไม่บังคับ)
  • send-keys: ส่งโทเค็นคีย์หรือไบต์ที่ระบุชัดเจนไปยังเซสชันที่รองรับด้วย PTY
  • submit: ส่ง Enter / carriage return ไปยังเซสชันที่รองรับด้วย PTY
  • paste: ส่งข้อความ literal โดยเลือกห่อด้วยโหมด bracketed paste ได้
  • kill: ยุติเซสชันเบื้องหลัง
  • clear: ลบเซสชันที่เสร็จแล้วออกจากหน่วยความจำ
  • remove: kill หากกำลังทำงาน มิฉะนั้น clear หากเสร็จแล้ว
หมายเหตุ:
  • เฉพาะเซสชันที่ทำงานเบื้องหลังเท่านั้นที่จะถูกแสดงรายการ/คงอยู่ในหน่วยความจำ
  • เซสชันจะสูญหายเมื่อกระบวนการรีสตาร์ต (ไม่มีการคงอยู่บนดิสก์)
  • บันทึกเซสชันจะถูกบันทึกลงประวัติแชทเฉพาะเมื่อคุณเรียกใช้ process poll/log และมีการบันทึกผลลัพธ์เครื่องมือ
  • process ถูกจำกัดขอบเขตต่อ agent; จะเห็นเฉพาะเซสชันที่เริ่มโดย agent นั้น
  • ใช้ poll / log สำหรับสถานะ บันทึก การยืนยันความสำเร็จแบบเงียบ หรือ การยืนยันการเสร็จสิ้นเมื่อไม่มีการปลุกเมื่อเสร็จสิ้นโดยอัตโนมัติ
  • ใช้ log ก่อนกู้คืน CLI แบบโต้ตอบ เพื่อให้ transcript ปัจจุบัน สถานะ stdin และคำใบ้การรออินพุตปรากฏพร้อมกัน
  • ใช้ write / send-keys / submit / paste / kill เมื่อคุณต้องการอินพุต หรือการแทรกแซง
  • process list มี name ที่อนุมานได้ (กริยาคำสั่ง + เป้าหมาย) เพื่อสแกนอย่างรวดเร็ว
  • process list, poll และ log รายงาน waitingForInput เฉพาะ เมื่อเซสชันยังมี stdin ที่เขียนได้และว่างนานกว่าเกณฑ์ การรออินพุต
  • process log ใช้ offset/limit แบบอิงบรรทัด
  • เมื่อไม่ระบุทั้ง offset และ limit จะคืน 200 บรรทัดสุดท้ายและมีคำใบ้การแบ่งหน้า
  • เมื่อระบุ offset และไม่ระบุ limit จะคืนตั้งแต่ offset ถึงท้ายสุด (ไม่จำกัดไว้ที่ 200)
  • การ poll ใช้สำหรับสถานะตามต้องการ ไม่ใช่การจัดตารางลูปรอ หากงานควร เกิดขึ้นภายหลัง ให้ใช้ cron แทน

​
ตัวอย่าง

เรียกใช้งานยาวและ poll ภายหลัง: 
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }
ตรวจสอบเซสชันแบบโต้ตอบก่อนส่งอินพุต: 
{ "tool": "process", "action": "log", "sessionId": "<id>" }
เริ่มทำงานเบื้องหลังทันที: 
{ "tool": "exec", "command": "npm run build", "background": true }
ส่ง stdin: 
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
ส่งคีย์ PTY: 
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
ส่งบรรทัดปัจจุบัน: 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
วางข้อความ literal: 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

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