เวิร์กทรีที่มีการจัดการ

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

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

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

<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 โดยมีหนึ่งรูปแบบต่อบรรทัด พร้อมความคิดเห็น #:

.env.localfixtures/generated/**

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

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

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

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

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

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

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

{  "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 ที่ยังไม่ได้จัดประเภท หากนโยบายเป้าหมายหรือคอนเทนเนอร์ที่กำลังทำงานมีขอบเขตกว้างกว่า การส่งงานจะปล่อยให้การ์ดยังไม่มีผู้รับและรายงานสถานะที่เข้ากันไม่ได้