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

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

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

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

<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 โดยกำหนดหนึ่งรูปแบบต่อบรรทัดและใช้ # สำหรับความคิดเห็น:

.env.localfixtures/generated/**

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

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

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

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

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

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

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

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

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

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