प्रबंधित वर्कट्रीज़

प्रबंधित वर्कट्री किसी एजेंट कार्य को उसकी अपनी git ब्रांच और चेकआउट देती हैं, बिना स्रोत रिपॉज़िटरी के भीतर अस्थायी डायरेक्टरियाँ रखे। OpenClaw उन्हें अपनी स्टेट डायरेक्टरी के अंतर्गत बनाता है, साझा स्टेट डेटाबेस में दर्ज करता है, और हटाने से पहले उनकी ट्रैक की गई तथा अनदेखी न की गई अनट्रैक्ड सामग्री के स्नैपशॉट बनाता है।

लेआउट और नाम

प्रत्येक वर्कट्री यहाँ स्थित होती है:

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

रिपॉज़िटरी फ़िंगरप्रिंट, कैनॉनिकल git कॉमन डायरेक्टरी और ओरिजिन URL पर बने SHA-256 हैश के पहले 16 हेक्साडेसिमल वर्ण होते हैं। दिया गया नाम [a-z0-9][a-z0-9-]{0,63} से मेल खाना चाहिए। नाम न होने पर OpenClaw wt- और उसके बाद आठ यादृच्छिक हेक्साडेसिमल वर्ण जनरेट करता है।

OpenClaw अनुरोधित बेस रेफ़ पर openclaw/<name> ब्रांच बनाता है। बेस रेफ़ न होने पर यह 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 वर्कस्पेस से वर्कट्री-समर्थित सेशन के साथ एक पृथक चैट शुरू करें: Control UI के New session पेज पर वर्कट्री सक्षम करें (जो बेस-ब्रांच पिकर और वैकल्पिक वर्कट्री नाम भी प्रदान करता है), या iOS पर Chat actions मेनू अथवा Android पर New Chat के पास ओवरफ़्लो एक्शन का उपयोग करें। यह विकल्प केवल git-समर्थित एजेंट के लिए उपलब्ध है, जहाँ क्लाइंट के पास वह क्षमता हो; जो क्लाइंट इसकी पूर्व-जाँच नहीं कर सकते, वे इसके बजाय Gateway त्रुटि दिखाते हैं।

कोडिंग एजेंट वर्तमान कार्य के बाहर पुष्टि किए गए अनुवर्ती कार्य का पता चलने पर spawn_task भी कॉल कर सकते हैं। Control UI कुछ भी शुरू किए बिना सुझाव चिप दिखाता है, जबकि Gateway-समर्थित TUI समान कार्रवाइयों वाला इंटरैक्टिव प्रॉम्प्ट दिखाता है। वर्कट्री में शुरू करें चुनने पर सुझाए गए प्रोजेक्ट से एक नई सेशन-स्वामित्व वाली वर्कट्री बनती है और स्व-समाहित प्रॉम्प्ट उसके पहले टर्न के रूप में भेजा जाता है; सुझाव ख़ारिज करने पर रिपॉज़िटरी अपरिवर्तित रहती है। सुझाव और उनकी ID अस्थायी होते हैं और Gateway पुनः आरंभ होने के बाद बने नहीं रहते।

OpenClaw ये टूल केवल ऐसी ऑपरेटर सेशन को उपलब्ध कराता है जिनमें कार्रवाई योग्य Gateway UI हो। चैनल सेशन और स्थानीय/एम्बेडेड TUI सेशन को ये तब तक प्राप्त नहीं होते, जब तक उन सतहों में पोर्टेबल टाइप किया गया कार्य-कार्रवाई अनुबंध न हो।

परिणामी प्रबंधित वर्कट्री सेशन के स्वामित्व में होती है, और उस सेशन में प्रत्येक एजेंट रन उसके चेकआउट का उपयोग करता है। जब वर्कस्पेस रिपॉज़िटरी की उपडायरेक्टरी होता है, तो वर्कट्री रिपॉज़िटरी रूट पर एंकर होती है और सेशन उसके भीतर मेल खाने वाली उपडायरेक्टरी से चलता है। सेशन वर्कट्री निर्माण मेथड के operator.write स्कोप का उपयोग करता है, लेकिन रिपॉज़िटरी चेकआउट हुक और .openclaw/worktree-setup.sh चरण केवल operator.admin कॉलर के लिए चलते हैं, क्योंकि वे रिपॉज़िटरी कोड निष्पादित करते हैं; .worktreeinclude प्रावधान फिर भी प्रत्येक कॉलर पर लागू होता है। सेशन हटाने पर वर्कट्री केवल तभी हटती है जब ऐसा करना हानिरहित हो। गंदी वर्कट्री या अनपुश्ड कमिट वाली ब्रांच उपलब्ध रहती हैं; प्रति घंटा क्लीनअप 7 निष्क्रिय दिनों के बाद सेशन वर्कट्री के स्नैपशॉट बनाता है और हाल की सेशन गतिविधि को वर्कट्री गतिविधि मानता है। हटाई गई वर्कट्री नीचे बताए अनुसार अपने स्नैपशॉट से पुनर्स्थापित की जा सकती हैं।

जब कोई कार्य कॉन्फ़िगर किए गए एजेंट वर्कस्पेस के अलावा किसी प्रोजेक्ट को लक्षित करता है, तो sessions.create में worktree: true के साथ एक निरपेक्ष cwd शामिल हो सकता है। उस स्पष्ट होस्ट पथ के लिए operator.admin आवश्यक है; सामान्य वर्कट्री चैट निर्माण operator.write ही रहता है और कॉन्फ़िगर किए गए वर्कस्पेस से एंकर रहता है।

sessions.create, बेस रेफ़ और वर्कट्री नाम चुनने के लिए worktree: true के साथ worktreeBaseRef और worktreeName भी स्वीकार करता है (ब्रांच openclaw/<name> बनती है); दोनों operator.write पर रहते हैं। बनाई गई वर्कट्री create परिणाम में लौटाई जाती है और सेशन पंक्ति पर worktree: { id, branch, repoRoot } के रूप में स्थायी रूप से संग्रहीत की जाती है, ताकि सेशन सूचियाँ चेकआउट और ब्रांच दिखा सकें। सेशन हटाने पर संरक्षित गंदे चेकआउट को चुपचाप छोड़ने के बजाय worktreePreserved के रूप में रिपोर्ट किया जाता है।

स्नैपशॉट, क्लीनअप और पुनर्स्थापना

हटाने की प्रक्रिया पहले ट्रैक की गई और अनदेखी न की गई अनट्रैक्ड फ़ाइलों वाली एक सिंथेटिक कमिट बनाती है, फिर उसे refs/openclaw/snapshots/<id> पर पिन करती है। अनदेखी की गई फ़ाइलें कभी रिपॉज़िटरी ऑब्जेक्ट डेटाबेस में प्रवेश नहीं करतीं। OpenClaw केवल वास्तव में प्रावधान की गई अनदेखी फ़ाइलों को खंडित साझा-स्टेट डेटाबेस पंक्तियों में संग्रहीत करता है; दर्ज पथ सेट प्रामाणिक बना रहता है, भले ही .worktreeinclude बाद में बदल जाए या गायब हो जाए। पुनर्स्थापना उन बाइट्स को अपरिवर्तनीय स्नैपशॉट से पढ़ती है और उनके पूर्ण मोड पुनः लागू करती है। जब कोई दर्ज पथ सुरक्षित रूप से स्नैपशॉट नहीं किया जा सकता, तो स्वचालित क्लीनअप लाइव वर्कट्री को सुरक्षित रखता है। स्नैपशॉट निर्माण विफल होने पर हटाना रुक जाता है। स्पष्ट फ़ोर्स डिलीट स्नैपशॉट के बिना जारी रह सकता है।

OpenClaw ये क्लीनअप नियम लागू करता है:

• रन समाप्त होने पर यह वर्कट्री को केवल तभी हटाता है जब git status --porcelain खाली हो और git log HEAD --not --remotes --oneline को कोई अनपुश्ड कमिट न मिले। अन्यथा यह केवल गतिविधि लॉक जारी करता है।
• प्रति घंटा क्लीनअप 7 दिनों से अधिक समय से निष्क्रिय, अनलॉक की गई Workboard- और सेशन-स्वामित्व वाली वर्कट्री के स्नैपशॉट बनाकर उन्हें हटा देता है, भले ही वे गंदी हों। मैन्युअल वर्कट्री कभी स्वचालित रूप से नहीं हटाई जातीं।
• जब worktrees.cleanup.maxCount या worktrees.cleanup.maxTotalSizeGb कॉन्फ़िगर हो, तो क्लीनअप सबसे कम हाल में सक्रिय Workboard- और सेशन-स्वामित्व वाली वर्कट्री के स्नैपशॉट बनाकर उन्हें तब तक हटाता है, जब तक कुल संख्या और डिस्क आकार सीमाओं के भीतर न आ जाएँ। सभी प्रबंधित वर्कट्री कुल में गिनी जाती हैं, लेकिन मैन्युअल और अन्यथा सुरक्षित वर्कट्री कभी सीमा के कारण बेदखल नहीं की जातीं, इसलिए योग्य वर्कट्री उपलब्ध होने तक सीमा पार रह सकती है। 0 या अनसेट सीमा को अक्षम करता है।
• स्नैपशॉट रिकॉर्ड 30 दिनों तक पुनर्स्थापित किए जा सकते हैं। इसके बाद क्लीनअप स्नैपशॉट रेफ़ और रजिस्ट्री पंक्ति हटा देता है।
• एक लाइव OpenClaw प्रोसेस लॉक और कोई भी बाहरी या अपरिचित git वर्कट्री लॉक, वर्कट्री को गार्बेज कलेक्शन से सुरक्षित रखता है।

पुनर्स्थापना मूल प्री-स्नैपशॉट कमिट पर openclaw/<name> को पुनः बनाती है, फिर स्नैपशॉट अंतरों को अनस्टेज्ड संशोधनों और अनट्रैक्ड फ़ाइलों के रूप में फिर से बनाती है। इससे सिंथेटिक स्नैपशॉट कमिट ब्रांच इतिहास से बाहर रहती है। स्नैपशॉट रेफ़ उद्गम के रूप में दर्ज रहता है।

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]

Settings के अंतर्गत Control UI का वर्कट्री पेज समान कार्रवाइयाँ प्रदान करता है, साथ ही बेस-ब्रांच पिकर से निर्माण की सुविधा देता है, प्रत्येक वर्कट्री का स्वामी (मैन्युअल, Workboard, या उसके चैट के लिंक सहित स्वामी सेशन) दिखाता है, और हटाने पर विफल स्नैपशॉट की रिपोर्ट आने पर फ़ोर्स रीट्राई प्रदान करता है। इसका क्लीनअप अनुभाग कॉन्फ़िगरेशन संदर्भ में वर्णित worktrees.cleanup अवधारण सीमाओं को संपादित करता है।

Gateway मेथड

worktrees.list के लिए operator.read आवश्यक है, और परिवर्तनकारी मेथड के लिए operator.admin आवश्यक है। कॉन्फ़िगर किए गए एजेंट वर्कस्पेस के लिए worktrees.branches को operator.write चाहिए, जबकि किसी अन्य होस्ट पथ के लिए operator.admin आवश्यक है (sessions.create cwd सीमा से मेल खाते हुए)। यह केवल मौजूदा रेफ़ पढ़ता है और कभी फ़ेच नहीं करता, तथा केवल-रिमोट ब्रांच रिमोट-योग्य रूप में लौटती हैं (origin/feature-a), ताकि लौटाया गया प्रत्येक नाम बेस रेफ़ के रूप में रिज़ॉल्व हो।

Workboard वर्कस्पेस

बंडल किया गया Workboard Plugin कार्ड वर्कस्पेस को प्रबंधित वर्कट्री के रूप में मूर्त रूप दे सकता है:

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

path स्रोत git चेकआउट की पहचान करता है। branch वैकल्पिक है और बेस रेफ़ बनता है। पूर्ण-होस्ट कॉलर के लिए Workboard wb-<card-id> बनाता या पुनः उपयोग करता है, प्रबंधित चेकआउट को कार्यशील डायरेक्टरी बनाकर सबएजेंट चलाता है, और रिज़ॉल्व किया गया पथ तथा ब्रांच वापस कार्ड में लिखता है। पूर्ण-होस्ट मूर्त रूप देने के लिए Gateway क्लाइंट को operator.admin चाहिए। रन समाप्त होने पर Workboard चेकआउट केवल तभी हटाता है जब यह सिद्ध रूप से हानिरहित हो; गंदा कार्य या अनपुश्ड कमिट उपलब्ध रहते हैं।

वर्कस्पेस-बाउंड कॉलर के लिए path और रिपॉज़िटरी रूट का लक्ष्य एजेंट वर्कस्पेस से बिल्कुल मेल खाना आवश्यक है। इसके बाद Workboard सीधे उस डायरेक्टरी में चलता है और प्रबंधित वर्कट्री को होस्ट पर मूर्त रूप देने के बजाय डायरेक्टरी वर्कस्पेस दर्ज करता है। लक्ष्य को उसी वर्कस्पेस के लिए लिखने योग्य, गैर-साझा Docker सैंडबॉक्स का उपयोग करना चाहिए, उसके लाइव कंटेनर हैश को अनुरोधित माउंट और नीति से मेल खाना चाहिए, और उसमें उन्नत निष्पादन, होस्ट नियंत्रण, होस्ट-व्यापी सेशन, स्थायी होस्ट/Node निष्पादन, या अवर्गीकृत Plugin और MCP टूल उजागर नहीं होने चाहिए। यदि लक्ष्य नीति या लाइव कंटेनर अधिक व्यापक है, तो डिस्पैच कार्ड को अनक्लेम्ड छोड़ देता है और असंगत स्थिति रिपोर्ट करता है।