---
read_when:
    - การเพิ่มหรือแก้ไขพฤติกรรมการดำเนินคำสั่งในพื้นหลัง
    - การดีบักงาน exec ที่ทำงานเป็นเวลานาน
summary: การเรียกใช้ exec ในเบื้องหลังและการจัดการกระบวนการ
title: เครื่องมือ exec แบบทำงานเบื้องหลังและเครื่องมือจัดการกระบวนการ
x-i18n:
    generated_at: "2026-05-10T19:35:52Z"
    model: gpt-5.5
    provider: openai
    source_hash: 95fb986cf0c07ef3d054189ce2838b441ae24f07703f8edc1ddb8aca3a58b300
    source_path: gateway/background-process.md
    workflow: 16
---

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 ภายหลัง:

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

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

ตรวจสอบเซสชันแบบโต้ตอบก่อนส่งอินพุต:

```json
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

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

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

ส่ง stdin:

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

ส่งคีย์ PTY:

```json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
```

ส่งบรรทัดปัจจุบัน:

```json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

วางข้อความ literal:

```json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

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

- [เครื่องมือ Exec](/th/tools/exec)
- [การอนุมัติ Exec](/th/tools/exec-approvals)