---
read_when:
    - คุณต้องการแบรนช์และไดเรกทอรีเช็กเอาต์แบบแยกสำหรับงานของเอเจนต์
    - คุณกำลังกำหนดค่าการ์ด Workboard ที่ใช้พื้นที่ทำงานแบบ worktree
    - คุณจำเป็นต้องกู้คืนหรือล้าง worktree ที่ OpenClaw จัดการอยู่
summary: เรียกใช้งานของเอเจนต์ในสำเนาการเช็กเอาต์ git ที่แยกออกจากกัน พร้อมการบันทึกสแนปชอตและการล้างข้อมูลโดยอัตโนมัติ
title: เวิร์กทรีที่มีการจัดการ
x-i18n:
    generated_at: "2026-07-12T16:06:05Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 12a33dc2d9f1ff30060ddead200196b09cfe9498462f58a7aa8a73fa2273f31f
    source_path: concepts/managed-worktrees.md
    workflow: 16
---

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

## โครงสร้างและชื่อ

เวิร์กทรีแต่ละรายการอยู่ที่:

```text
<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>
```

ลายนิ้วมือของที่เก็บคืออักขระฐานสิบหก 16 ตัวแรกของแฮช SHA-256 ที่คำนวณจากไดเรกทอรีร่วมของ git แบบบัญญัติและ URL ของ origin ชื่อที่ระบุต้องตรงกับ `[a-z0-9][a-z0-9-]{0,63}` หากไม่ระบุชื่อ OpenClaw จะสร้างชื่อ `wt-` ตามด้วยอักขระฐานสิบหกแบบสุ่มแปดตัว

OpenClaw สร้างสาขา `openclaw/<name>` ที่ ref ฐานตามคำขอ หากไม่มี ref ฐาน ระบบจะดึงข้อมูลจาก `origin` ใช้สาขาเริ่มต้นของรีโมตเมื่อมี และย้อนกลับไปใช้ `HEAD` ในเครื่องเมื่อที่เก็บออฟไลน์หรือไม่มีรีโมตที่ใช้งานได้

## จัดเตรียมไฟล์ที่ถูกละเว้น

เพิ่ม `.worktreeinclude` ที่รากของที่เก็บซอร์สเพื่อคัดลอกไฟล์ที่ไม่ได้ติดตามและถูกละเว้นซึ่งเลือกไว้ไปยังเวิร์กทรีใหม่ ไฟล์นี้ใช้ไวยากรณ์รูปแบบของ gitignore โดยกำหนดหนึ่งรูปแบบต่อบรรทัดและใช้ `#` สำหรับความคิดเห็น:

```gitignore
.env.local
fixtures/generated/**
```

เฉพาะไฟล์ที่ git รายงานว่าทั้งถูกละเว้นและไม่ได้ติดตามเท่านั้นที่เข้าเกณฑ์ ไฟล์ที่ติดตามแล้วมีอยู่ผ่าน git อยู่แล้วและขั้นตอนนี้จะไม่คัดลอกไฟล์เหล่านั้น OpenClaw จะไม่เขียนทับไฟล์ปลายทางหรือตามไดเรกทอรีที่เป็นลิงก์สัญลักษณ์ และจะรักษาโหมดของไฟล์ที่คัดลอกไว้

## เรียกใช้การตั้งค่าที่เก็บ

หาก `.openclaw/worktree-setup.sh` มีอยู่ในที่เก็บซอร์สและสามารถเรียกทำงานได้ OpenClaw จะเรียกใช้โดยกำหนดให้เวิร์กทรีใหม่เป็นไดเรกทอรีปัจจุบัน สคริปต์จะได้รับ:

```text
OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>
```

รหัสออกที่ไม่ใช่ศูนย์จะยกเลิกการสร้างและนำเวิร์กทรีใหม่กับสาขาออก นี่เป็นสัญญาภายในที่เก็บ จึงไม่มีคีย์การกำหนดค่า OpenClaw สำหรับสิ่งนี้

## เวิร์กทรีของเซสชัน

เริ่มแชตแบบแยกจากพื้นที่ทำงาน git ของเอเจนต์ที่ใช้งานอยู่ด้วยเซสชันที่รองรับด้วยเวิร์กทรี: เปิดใช้ **Worktree** ในหน้า New session ของ Control UI (ซึ่งมีตัวเลือกสาขาฐานและชื่อเวิร์กทรีแบบไม่บังคับด้วย) หรือใช้เมนู Chat actions บน iOS หรือการทำงานในเมนูเพิ่มเติมข้าง New Chat บน Android ตัวเลือกนี้ใช้ได้เฉพาะกับเอเจนต์ที่รองรับด้วย git และไคลเอ็นต์มีความสามารถดังกล่าว ส่วนไคลเอ็นต์ที่ตรวจสอบล่วงหน้าไม่ได้จะแสดงข้อผิดพลาดจาก Gateway แทน

เอเจนต์เขียนโค้ดยังสามารถเรียก `spawn_task` เมื่อพบงานติดตามผลที่ยืนยันแล้วและอยู่นอกขอบเขตงานปัจจุบัน Control UI จะแสดงชิปคำแนะนำโดยไม่เริ่มดำเนินการใด ๆ ขณะที่ TUI ที่รองรับด้วย Gateway จะแสดงพรอมต์แบบโต้ตอบพร้อมการทำงานเดียวกัน การเลือก **Start in worktree** จะสร้างเวิร์กทรีใหม่ที่เซสชันเป็นเจ้าของจากโครงการที่แนะนำ และส่งพรอมต์ที่มีข้อมูลครบถ้วนในตัวเองเป็นเทิร์นแรก การปิดคำแนะนำจะไม่เปลี่ยนแปลงที่เก็บ คำแนะนำและ ID ของคำแนะนำเป็นข้อมูลชั่วคราวและจะไม่คงอยู่หลังจาก Gateway เริ่มทำงานใหม่

OpenClaw เปิดให้ใช้เครื่องมือเหล่านี้เฉพาะในเซสชันผู้ดำเนินการที่มี UI ของ Gateway ซึ่งดำเนินการได้ เซสชันช่องทางและเซสชัน TUI แบบภายในเครื่อง/แบบฝังจะไม่ได้รับเครื่องมือเหล่านี้จนกว่าพื้นผิวดังกล่าวจะมีสัญญาการทำงานของงานแบบมีชนิดที่พกพาได้

เวิร์กทรีที่มีการจัดการซึ่งได้มาจะเป็นของเซสชัน และการเรียกใช้เอเจนต์ทุกครั้งในเซสชันนั้นจะใช้เช็กเอาต์ของเวิร์กทรี เมื่อพื้นที่ทำงานเป็นไดเรกทอรีย่อยของที่เก็บ เวิร์กทรีจะยึดที่รากของที่เก็บ และเซสชันจะทำงานจากไดเรกทอรีย่อยที่ตรงกันภายในเวิร์กทรี การสร้างเวิร์กทรีของเซสชันใช้ขอบเขต `operator.write` ของเมธอด แต่ขั้นตอน `.openclaw/worktree-setup.sh` จะทำงานเฉพาะสำหรับผู้เรียกที่มี `operator.admin` เนื่องจากเป็นการเรียกใช้โค้ดของที่เก็บ ส่วนการจัดเตรียม `.worktreeinclude` ยังคงใช้กับผู้เรียกทุกคน การลบเซสชันจะนำเวิร์กทรีออกเฉพาะเมื่อทำได้โดยไม่สูญเสียข้อมูล เวิร์กทรีที่มีการเปลี่ยนแปลงหรือสาขาที่มีคอมมิตซึ่งยังไม่ได้พุชจะยังคงพร้อมใช้งาน การล้างข้อมูลรายชั่วโมงจะสร้างสแนปช็อตเวิร์กทรีของเซสชันหลังจากไม่มีการใช้งาน 7 วัน โดยถือว่ากิจกรรมล่าสุดของเซสชันเป็นกิจกรรมของเวิร์กทรี เวิร์กทรีที่นำออกแล้วยังคงกู้คืนได้จากสแนปช็อตตามที่อธิบายไว้ด้านล่าง

`sessions.create` สามารถมี `cwd` แบบพาธสัมบูรณ์ร่วมกับ `worktree: true` เมื่องานมุ่งเป้าไปยังโครงการอื่นนอกเหนือจากพื้นที่ทำงานของเอเจนต์ที่กำหนดค่าไว้ พาธโฮสต์ที่ระบุอย่างชัดเจนดังกล่าวต้องใช้ `operator.admin` ส่วนการสร้างแชตเวิร์กทรีทั่วไปยังคงใช้ `operator.write` และยึดกับพื้นที่ทำงานที่กำหนดค่าไว้

`sessions.create` ยังยอมรับ `worktreeBaseRef` และ `worktreeName` ควบคู่กับ `worktree: true` เพื่อเลือก ref ฐานและชื่อเวิร์กทรี (สาขาจะเป็น `openclaw/<name>`) โดยทั้งคู่ยังคงใช้ `operator.write` เวิร์กทรีที่สร้างขึ้นจะถูกส่งคืนในผลลัพธ์การสร้างและบันทึกคงอยู่ในแถวของเซสชันเป็น `worktree: { id, branch, repoRoot }` เพื่อให้รายการเซสชันแสดงเช็กเอาต์และสาขาได้ การลบเซสชันจะรายงานเช็กเอาต์ที่มีการเปลี่ยนแปลงและเก็บรักษาไว้เป็น `worktreePreserved` แทนที่จะปล่อยทิ้งไว้อย่างเงียบ ๆ

## สแนปช็อต การล้างข้อมูล และการกู้คืน

ก่อนนำออก ระบบจะสร้างคอมมิตสังเคราะห์ที่มีไฟล์ที่ติดตามแล้วและไฟล์ที่ไม่ได้ติดตามซึ่งไม่ได้ถูกละเว้น จากนั้นตรึงไว้ที่ `refs/openclaw/snapshots/<id>` ไฟล์ที่ git ละเว้นจะไม่รวมอยู่ในฐานข้อมูลออบเจ็กต์ของที่เก็บ ส่วนไฟล์ที่เลือกโดย `.worktreeinclude` จะถูกคัดลอกอีกครั้งระหว่างการกู้คืน หากสร้างสแนปช็อตไม่สำเร็จ การนำออกจะหยุดลง การบังคับลบอย่างชัดเจนสามารถดำเนินการต่อได้โดยไม่มีสแนปช็อต

OpenClaw ใช้กฎการล้างข้อมูลต่อไปนี้:

- เมื่อการเรียกใช้สิ้นสุด ระบบจะนำเวิร์กทรีออกเฉพาะเมื่อ `git status --porcelain` ว่างเปล่าและ `git log HEAD --not --remotes --oneline` ไม่พบคอมมิตที่ยังไม่ได้พุช มิฉะนั้นระบบจะปล่อยเฉพาะล็อกกิจกรรม
- การล้างข้อมูลรายชั่วโมงจะสร้างสแนปช็อตและนำเวิร์กทรีที่ Workboard และเซสชันเป็นเจ้าของซึ่งไม่ได้ล็อกและไม่มีการใช้งานนานกว่า 7 วันออก แม้ว่าจะมีการเปลี่ยนแปลงอยู่ก็ตาม เวิร์กทรีที่สร้างด้วยตนเองจะไม่ถูกนำออกโดยอัตโนมัติ
- ระเบียนสแนปช็อตจะกู้คืนได้เป็นเวลา 30 วัน หลังจากนั้นการล้างข้อมูลจะลบ ref ของสแนปช็อตและแถวในรีจิสทรี
- ล็อกของกระบวนการ OpenClaw ที่ยังทำงานอยู่และล็อกเวิร์กทรีของ git ที่มาจากภายนอกหรือไม่รู้จักจะป้องกันเวิร์กทรีจากการเก็บกวาดขยะ

การกู้คืนจะสร้าง `openclaw/<name>` ขึ้นใหม่ที่คอมมิตเดิมก่อนสร้างสแนปช็อต จากนั้นสร้างความแตกต่างของสแนปช็อตกลับมาเป็นการแก้ไขที่ยังไม่ได้จัดเตรียมและไฟล์ที่ไม่ได้ติดตาม วิธีนี้ทำให้คอมมิตสแนปช็อตสังเคราะห์ไม่เข้าไปอยู่ในประวัติสาขา ref ของสแนปช็อตจะยังคงถูกบันทึกไว้เป็นแหล่งที่มา

## CLI

```bash
openclaw worktrees list [--json]
openclaw worktrees create <repo-root> [--name <name>] [--base-ref <ref>] [--json]
openclaw worktrees remove <id> [--force] [--json]
openclaw worktrees restore <id> [--json]
openclaw worktrees gc [--json]
```

หน้า **Worktrees** ของ Control UI ภายใต้ Settings มีการทำงานเดียวกัน พร้อมการสร้างโดยใช้ตัวเลือกสาขาฐาน แสดงเจ้าของเวิร์กทรีแต่ละรายการ (สร้างด้วยตนเอง, Workboard หรือเซสชันเจ้าของพร้อมลิงก์ไปยังแชตของเซสชันนั้น) และมีตัวเลือกบังคับลองใหม่เมื่อการนำออกรายงานว่าการสร้างสแนปช็อตล้มเหลว

## เมธอดของ Gateway

| เมธอด               | วัตถุประสงค์                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `worktrees.list`     | แสดงรายการระเบียนเวิร์กทรีที่ใช้งานอยู่และกู้คืนได้                            |
| `worktrees.branches` | แสดงรายการสาขาในเครื่องและสาขารีโมตของที่เก็บสำหรับตัวเลือก ref ฐาน    |
| `worktrees.create`   | สร้างหรือนำเวิร์กทรีที่มีการจัดการและมีชื่อกลับมาใช้ใหม่                               |
| `worktrees.remove`   | สร้างสแนปช็อตและนำเวิร์กทรีออก การบังคับนำออกจะรายงาน `snapshotError` |
| `worktrees.restore`  | กู้คืนเวิร์กทรีที่นำออกแล้วจากสแนปช็อต                           |
| `worktrees.gc`       | เรียกใช้การล้างข้อมูลรายการที่ไม่มีการใช้งาน กำพร้า และหมดระยะเวลาเก็บรักษาทันที                            |

`worktrees.list` ต้องใช้ `operator.read` และเมธอดที่แก้ไขข้อมูลต้องใช้ `operator.admin` ส่วน `worktrees.branches` ต้องใช้ `operator.write` สำหรับพื้นที่ทำงานของเอเจนต์ที่กำหนดค่าไว้ ขณะที่พาธโฮสต์อื่นต้องใช้ `operator.admin` (ตรงกับเกณฑ์ cwd ของ `sessions.create`) เมธอดนี้อ่านเฉพาะ ref ที่มีอยู่และจะไม่ดึงข้อมูล และสาขาที่มีเฉพาะบนรีโมตจะถูกส่งกลับพร้อมคุณสมบัติรีโมต (`origin/feature-a`) เพื่อให้ทุกชื่อที่ส่งคืนสามารถแก้ไขเป็น ref ฐานได้

## พื้นที่ทำงานของ Workboard

[Plugin Workboard](/th/plugins/workboard) ที่รวมมาให้สามารถสร้างพื้นที่ทำงานของการ์ดเป็นเวิร์กทรีที่มีการจัดการได้:

```json
{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}
```

`path` ระบุเช็กเอาต์ git ต้นทาง `branch` เป็นตัวเลือกและจะกลายเป็น ref ฐาน เมื่อการส่งงานเริ่มเวิร์กเกอร์ของการ์ด Workboard จะสร้างหรือนำ `wb-<card-id>` กลับมาใช้ใหม่ เรียกใช้เอเจนต์ย่อยโดยใช้เช็กเอาต์ที่มีการจัดการเป็นไดเรกทอรีทำงาน และเขียนพาธกับสาขาที่แก้ไขแล้วกลับไปยังการ์ด การสร้างพื้นที่ทำงานที่ทริกเกอร์ผ่าน Gateway ต้องใช้ `operator.admin` เมื่อการเรียกใช้สิ้นสุด Workboard จะนำเช็กเอาต์ออกเฉพาะเมื่อพิสูจน์ได้ว่าจะไม่สูญเสียข้อมูล งานที่มีการเปลี่ยนแปลงหรือคอมมิตที่ยังไม่ได้พุชจะยังคงพร้อมใช้งาน

ขณะนี้เอเจนต์แบบฝังที่ทำงานในแซนด์บ็อกซ์จะปฏิเสธไดเรกทอรีทำงานของงานที่อยู่นอกพื้นที่ทำงานของเอเจนต์ที่กำหนดค่าไว้ ใช้เอเจนต์เป้าหมายที่ไม่อยู่ในแซนด์บ็อกซ์สำหรับการ์ดเวิร์กทรีที่มีการจัดการของ Workboard จนกว่ารันไทม์แซนด์บ็อกซ์จะรองรับการเมานต์เช็กเอาต์แบบเพิ่มเติม