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

เวิร์กทรีที่ได้รับการจัดการช่วยให้งานของเอเจนต์มีสาขา git และ checkout เป็นของตนเอง โดยไม่วางไดเรกทอรีชั่วคราวไว้ภายในที่เก็บซอร์ส 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-` ตามด้วยอักขระเลขฐานสิบหกแบบสุ่ม 8 ตัว

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OpenClaw ใช้กฎการล้างข้อมูลเหล่านี้:

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

การกู้คืนจะสร้าง `openclaw/<name>` ใหม่ที่ commit เดิมก่อนการสร้างสแนปช็อต จากนั้นสร้างความแตกต่างของสแนปช็อตกลับมาเป็นการแก้ไขที่ยังไม่ได้ stage และไฟล์ที่ไม่ติดตาม วิธีนี้จะกัน commit สแนปช็อตสังเคราะห์ออกจากประวัติสาขา snapshot 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]
```

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

## เมธอดของ Gateway

| เมธอด               | วัตถุประสงค์                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `worktrees.list`     | แสดงระเบียนเวิร์กทรีที่ใช้งานอยู่และกู้คืนได้                            |
| `worktrees.branches` | แสดงสาขาในเครื่องและสาขารีโมตของที่เก็บสำหรับตัวเลือก base 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`) เพื่อให้ชื่อที่ส่งคืนทุกชื่อแก้ไขเป็น base ref ได้

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

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

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

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

สำหรับผู้เรียกที่ผูกกับพื้นที่ทำงาน `path` และรากของที่เก็บต้องตรงกับพื้นที่ทำงานของเอเจนต์เป้าหมายทุกประการ จากนั้น Workboard จะทำงานโดยตรงในไดเรกทอรีนั้นและบันทึกพื้นที่ทำงานแบบไดเรกทอรีแทนการสร้างเวิร์กทรีที่ได้รับการจัดการบนโฮสต์ เป้าหมายต้องใช้ Docker sandbox ที่เขียนได้และไม่ใช้ร่วมกันสำหรับพื้นที่ทำงานเดียวกัน แฮชคอนเทนเนอร์ที่กำลังทำงานต้องตรงกับ mount และนโยบายที่ร้องขอ และต้องไม่เปิดให้ใช้การดำเนินการแบบยกระดับ การควบคุมโฮสต์ เซสชันทั่วทั้งโฮสต์ การดำเนินการบนโฮสต์/Node ที่จัดเก็บถาวร หรือ Plugin และเครื่องมือ MCP ที่ยังไม่ได้จัดประเภท หากนโยบายเป้าหมายหรือคอนเทนเนอร์ที่กำลังทำงานมีขอบเขตกว้างกว่า การส่งงานจะปล่อยให้การ์ดยังไม่มีผู้รับและรายงานสถานะที่เข้ากันไม่ได้