---
read_when:
    - การเพิ่มหรือแก้ไขลักษณะการทำงานของการดำเนินการเบื้องหลัง
    - การดีบักงาน exec ที่ทำงานเป็นเวลานาน
summary: การดำเนินการคำสั่งเบื้องหลังและการจัดการกระบวนการ
title: การดำเนินการเบื้องหลังและเครื่องมือจัดการกระบวนการ
x-i18n:
    generated_at: "2026-07-12T16:07:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12
    source_path: gateway/background-process.md
    workflow: 16
---

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

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

พารามิเตอร์:

| พารามิเตอร์ | คำอธิบาย |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command`    | จำเป็น คำสั่งเชลล์ที่จะเรียกใช้ |
| `workdir`    | ไดเรกทอรีทำงาน หากไม่ระบุจะใช้ cwd เริ่มต้น |
| `env`        | ตัวแปรสภาพแวดล้อมเพิ่มเติมสำหรับคำสั่ง |
| `yieldMs`    | จำนวนมิลลิวินาทีที่จะรอก่อนย้ายไปทำงานเบื้องหลัง (ค่าเริ่มต้น 10000) |
| `background` | เรียกใช้ในเบื้องหลังทันที |
| `timeout`    | ระยะหมดเวลาเป็นวินาที (ค่าเริ่มต้นคือ `tools.exec.timeoutSec`) และจะยุติโปรเซสเมื่อหมดเวลา ตั้งค่า `timeout: 0` เพื่อปิดระยะหมดเวลาของโปรเซส exec สำหรับการเรียกครั้งนั้น |
| `pty`        | เรียกใช้ในเทอร์มินัลจำลองเมื่อพร้อมใช้งาน (CLI ที่ต้องใช้ TTY, เอเจนต์เขียนโค้ด) |
| `elevated`   | เรียกใช้นอกแซนด์บ็อกซ์ หากเปิดใช้งาน/อนุญาตโหมดยกระดับ (`gateway` โดยค่าเริ่มต้น หรือ `node` เมื่อเป้าหมาย exec คือ `node`) |
| `host`       | เป้าหมาย exec: `auto`, `sandbox`, `gateway` หรือ `node` |
| `node`       | รหัส/ชื่อ Node ใช้ร่วมกับ `host: "node"` |

ลักษณะการทำงาน:

- การทำงานเบื้องหน้าจะส่งคืนเอาต์พุตโดยตรง
- เมื่อย้ายไปทำงานเบื้องหลัง (โดยระบุชัดเจนหรือเนื่องจากหมดเวลา `yieldMs`) เครื่องมือจะส่งคืน `status: "running"` + `sessionId` และส่วนท้ายสั้น ๆ ของเอาต์พุต
- การทำงานเบื้องหลังและการทำงานที่ใช้ `yieldMs` จะสืบทอด `tools.exec.timeoutSec` เว้นแต่การเรียกจะระบุ `timeout` ไว้อย่างชัดเจน
- เอาต์พุตจะคงอยู่ในหน่วยความจำจนกว่าจะมีการสำรวจหรือล้างเซสชัน
- หากไม่อนุญาตให้ใช้เครื่องมือ `process` การทำงานของ `exec` จะเป็นแบบซิงโครนัสและไม่สนใจ `yieldMs`/`background`
- คำสั่ง exec ที่สร้างขึ้นจะได้รับ `OPENCLAW_SHELL=exec` เพื่อใช้กับกฎเชลล์/โปรไฟล์ที่รับรู้บริบท
- สำหรับงานที่ใช้เวลานานและเริ่มตอนนี้: ให้เริ่มเพียงครั้งเดียว แล้วใช้การปลุกอัตโนมัติเมื่อเสร็จสิ้น (หากเปิดใช้งาน) เมื่อคำสั่งสร้างเอาต์พุตหรือล้มเหลว
- หากการปลุกอัตโนมัติเมื่อเสร็จสิ้นไม่พร้อมใช้งาน หรือคุณต้องการยืนยันความสำเร็จแบบไม่มีเอาต์พุตสำหรับคำสั่งที่จบอย่างเรียบร้อยโดยไม่สร้างเอาต์พุต ให้สำรวจด้วย `process`
- อย่าจำลองการแจ้งเตือนหรือการติดตามผลแบบหน่วงเวลาด้วยลูป `sleep` หรือการสำรวจซ้ำ ๆ — ให้ใช้ Cron สำหรับงานในอนาคต

### การแทนที่ด้วยตัวแปรสภาพแวดล้อม

| ตัวแปร | ผล |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_BASH_YIELD_MS`                 | ระยะรอเริ่มต้นก่อนย้ายไปทำงานเบื้องหลัง (มิลลิวินาที) ค่าเริ่มต้น 10000 จำกัดอยู่ระหว่าง 10-120000 |
| `OPENCLAW_BASH_MAX_OUTPUT_CHARS`         | ขีดจำกัดเอาต์พุตในหน่วยความจำ (จำนวนอักขระ) |
| `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS` | ขีดจำกัด stdout/stderr ที่รอดำเนินการต่อสตรีม (จำนวนอักขระ) |
| `OPENCLAW_BASH_JOB_TTL_MS`               | TTL สำหรับเซสชันที่เสร็จสิ้นแล้ว (มิลลิวินาที) จำกัดอยู่ระหว่าง 1 นาที-3 ชั่วโมง |
| `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`    | เกณฑ์ระยะเวลาที่ไม่มีเอาต์พุต ก่อนทำเครื่องหมายเซสชันเบื้องหลังที่ยังเขียนข้อมูลได้ว่าน่าจะกำลังรออินพุต ค่าเริ่มต้น 15000 |

### การกำหนดค่า (แนะนำให้ใช้แทนการแทนที่ด้วยตัวแปรสภาพแวดล้อม)

| คีย์ | ค่าเริ่มต้น | ผล |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `tools.exec.backgroundMs`             | 10000   | เหมือนกับ `OPENCLAW_BASH_YIELD_MS` |
| `tools.exec.timeoutSec`               | 1800    | ระยะหมดเวลาเริ่มต้นต่อการเรียก |
| `tools.exec.cleanupMs`                | 1800000 | เหมือนกับ `OPENCLAW_BASH_JOB_TTL_MS` |
| `tools.exec.notifyOnExit`             | true    | เพิ่มเหตุการณ์ระบบเข้าคิว + ขอ Heartbeat เมื่อ exec ที่ทำงานเบื้องหลังสิ้นสุดลง |
| `tools.exec.notifyOnExitEmptySuccess` | false   | เพิ่มเหตุการณ์เสร็จสิ้นเข้าคิวด้วย สำหรับการทำงานเบื้องหลังที่สำเร็จแต่ไม่มีเอาต์พุต |

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

เมื่อสร้างโปรเซสลูกที่ทำงานเป็นเวลานานนอกเครื่องมือ exec/process (การเริ่ม CLI ใหม่, ตัวช่วย Gateway) ให้แนบตัวช่วยเชื่อมต่อโปรเซสลูก เพื่อส่งต่อสัญญาณยุติการทำงานและถอดตัวรับฟังเมื่อออกจากโปรเซสหรือเกิดข้อผิดพลาด วิธีนี้ช่วยหลีกเลี่ยงโปรเซสกำพร้าบน systemd และทำให้การปิดระบบสอดคล้องกันในทุกแพลตฟอร์ม

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

การดำเนินการ:

| การดำเนินการ | ผล |
| ----------- | ----------------------------------------------------------------------------- |
| `list`      | เซสชันที่กำลังทำงาน + เสร็จสิ้นแล้ว |
| `poll`      | ดึงเอาต์พุตใหม่ของเซสชันออกมา (รวมถึงรายงานสถานะการออก) |
| `log`       | อ่านเอาต์พุตรวมและคำแนะนำสำหรับการกู้คืนอินพุต รองรับ `offset` + `limit` |
| `write`     | ส่ง stdin (`data`, และ `eof` ซึ่งเป็นตัวเลือก) |
| `send-keys` | ส่งโทเค็นปุ่มหรือไบต์ที่ระบุไปยังเซสชันที่ใช้ PTY |
| `submit`    | ส่ง Enter/อักขระขึ้นบรรทัดใหม่ไปยังเซสชันที่ใช้ PTY |
| `paste`     | ส่งข้อความตามตัวอักษร โดยเลือกครอบด้วยโหมดวางแบบมีวงเล็บกำกับได้ |
| `kill`      | ยุติเซสชันเบื้องหลัง |
| `clear`     | ลบเซสชันที่เสร็จสิ้นแล้วออกจากหน่วยความจำ |
| `remove`    | ยุติหากกำลังทำงาน มิฉะนั้นล้างหากเสร็จสิ้นแล้ว |

หมายเหตุ:

- จะแสดงรายการ/เก็บไว้เฉพาะเซสชันเบื้องหลังเท่านั้น — อยู่ในหน่วยความจำเท่านั้น ไม่ได้อยู่บนดิสก์ เซสชันจะสูญหายเมื่อโปรเซสเริ่มใหม่
- เซสชันเบื้องหลังที่ยังทำงานอยู่จะขัดขวางการพักโฮสต์แบบร่วมมือและการเริ่ม Gateway ใหม่อย่างปลอดภัย จนกว่าเจ้าของโปรเซสจะยืนยันว่าโปรเซสสิ้นสุดจริง
- `process remove` สามารถซ่อนเซสชันที่กำลังทำงานได้ทันทีหลังจากขอยุติ แต่การพักและการเริ่มใหม่จะยังคงถูกขัดขวางจนกว่าจะยืนยันการสิ้นสุด
- บันทึกเซสชันจะถูกบันทึกลงในประวัติแชตเฉพาะเมื่อคุณเรียกใช้ `process poll`/`log` และผลลัพธ์ของเครื่องมือถูกบันทึกไว้
- `process` มีขอบเขตแยกตามเอเจนต์ โดยจะเห็นเฉพาะเซสชันที่เอเจนต์นั้นเริ่มไว้
- ใช้ `poll`/`log` สำหรับตรวจสอบสถานะ บันทึก หรือยืนยันการเสร็จสิ้น เมื่อการปลุกอัตโนมัติเมื่อเสร็จสิ้นไม่พร้อมใช้งาน
- ใช้ `log` ก่อนกู้คืน CLI แบบโต้ตอบ เพื่อให้เห็นทรานสคริปต์ปัจจุบัน สถานะ stdin และคำแนะนำการรออินพุตพร้อมกัน
- ใช้ `write`/`send-keys`/`submit`/`paste`/`kill` เมื่อต้องการป้อนข้อมูลหรือแทรกแซง
- `process list` มี `name` ที่คำนวณขึ้น (กริยาของคำสั่ง + เป้าหมาย) เพื่อให้ตรวจดูได้อย่างรวดเร็ว
- `process list`, `poll` และ `log` จะรายงาน `waitingForInput` เฉพาะเมื่อเซสชันยังมี stdin ที่เขียนได้ และไม่มีการทำงานนานกว่าเกณฑ์การรออินพุต (ค่าเริ่มต้น 15000 มิลลิวินาที, `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`)
- `process log` ใช้ `offset`/`limit` แบบอิงบรรทัด เมื่อไม่ระบุทั้งสองค่า ระบบจะส่งคืน 200 บรรทัดล่าสุดพร้อมคำแนะนำการแบ่งหน้า เมื่อระบุ `offset` แต่ไม่ระบุ `limit` ระบบจะส่งคืนตั้งแต่ `offset` ถึงท้ายสุด (ไม่จำกัดไว้ที่ 200)
- `timeout` ของ `poll` จะรอสูงสุดตามจำนวนมิลลิวินาทีที่กำหนดก่อนส่งคืน โดยค่าที่มากกว่า 30000 จะถูกจำกัดไว้ที่ 30000
- การสำรวจมีไว้สำหรับตรวจสอบสถานะตามต้องการ ไม่ใช่สำหรับกำหนดตารางลูปการรอ หากงานควรเกิดขึ้นภายหลัง ให้ใช้ Cron

## ตัวอย่าง

เรียกใช้งานที่ใช้เวลานานและสำรวจในภายหลัง:

```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>" }
```

วางข้อความตามตัวอักษร:

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

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

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