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

प्रबंधित वर्कट्री किसी एजेंट कार्य को उसकी अपनी 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 के नया सेशन पृष्ठ पर, Gateway स्रोत फ़ोल्डर चुनने के लिए स्थान पिकर का उपयोग करें, फिर वर्कट्री चुनें (वैकल्पिक बेस शाखा और वर्कट्री नाम के साथ)। यह विकल्प केवल तब दिखाई देता है जब Gateway पुष्टि कर देता है कि चुना गया फ़ोल्डर Git चेकआउट है; सामान्य फ़ोल्डर सीधे चलते हैं और कोई Git आइसोलेशन नियंत्रण नहीं दिखाते। सक्रिय एजेंट वर्कस्पेस के Git-समर्थित होने पर iOS चैट कार्रवाइयों से और Android नई चैट के पास यही विकल्प उपलब्ध कराते हैं।

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

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

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

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

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

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

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

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

• रन समाप्त होने पर, यह वर्कट्री केवल तभी हटाता है जब git status --porcelain खाली हो और git log HEAD --not --remotes --oneline को कोई बिना पुश किया कमिट न मिले। अन्यथा यह केवल गतिविधि लॉक छोड़ता है।
• प्रति घंटा क्लीनअप, 7 दिनों से अधिक निष्क्रिय अनलॉक किए गए Workboard- और सेशन-स्वामित्व वाले वर्कट्री के स्नैपशॉट बनाकर उन्हें हटा देता है, भले ही वे गंदे हों। मैन्युअल वर्कट्री कभी स्वचालित रूप से नहीं हटाए जाते।
• स्नैपशॉट रिकॉर्ड 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]

सेटिंग्स के अंतर्गत Control UI का वर्कट्री पृष्ठ समान कार्रवाइयाँ और बेस-शाखा पिकर के साथ निर्माण उपलब्ध कराता है, प्रत्येक वर्कट्री का स्वामी दिखाता है (मैन्युअल, Workboard, या उसके चैट के लिंक वाला स्वामी सेशन), और हटाने पर विफल स्नैपशॉट रिपोर्ट होने की स्थिति में बलपूर्वक पुनः प्रयास उपलब्ध कराता है।

Gateway विधियाँ

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

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 सैंडबॉक्स का उपयोग करना चाहिए, उसके लाइव कंटेनर हैश को अनुरोधित माउंट और नीति से मेल खाना चाहिए, और उसे उन्नत निष्पादन, होस्ट नियंत्रण, होस्ट-व्यापी सेशन, स्थायी होस्ट/नोड निष्पादन, या अवर्गीकृत Plugin और MCP टूल उपलब्ध नहीं कराने चाहिए। यदि लक्ष्य नीति या लाइव कंटेनर अधिक व्यापक है, तो डिस्पैच कार्ड को बिना क्लेम किए छोड़ देता है और असंगत स्थिति रिपोर्ट करता है।