ورک‌تری‌های مدیریت‌شده

درخت‌های کاری مدیریت‌شده به یک وظیفهٔ عامل، شاخه و checkout گیت مختص خود را می‌دهند، بدون آنکه دایرکتوری‌های موقت را داخل مخزن منبع قرار دهند. OpenClaw آن‌ها را زیر دایرکتوری وضعیت خود ایجاد می‌کند، در پایگاه دادهٔ وضعیت مشترک ثبت می‌کند و پیش از حذف، از محتوای ردیابی‌شده و ردیابی‌نشدهٔ نادیده‌گرفته‌نشدهٔ آن‌ها snapshot می‌گیرد.

چیدمان و نام‌ها

هر درخت کاری در این مسیر قرار دارد:

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

اثر انگشت مخزن، 16 نویسهٔ هگزادسیمال نخست یک هش SHA-256 از دایرکتوری مشترک و متعارف گیت و URL مبدأ است. نام ارائه‌شده باید با [a-z0-9][a-z0-9-]{0,63} مطابقت داشته باشد. بدون نام، OpenClaw مقدار wt- را به‌همراه هشت نویسهٔ هگزادسیمال تصادفی تولید می‌کند.

OpenClaw شاخهٔ openclaw/<name> را در ref پایهٔ درخواستی ایجاد می‌کند. بدون ref پایه، origin را واکشی می‌کند، در صورت موجود بودن از شاخهٔ پیش‌فرض راه‌دور استفاده می‌کند و هنگامی که مخزن آفلاین است یا راه‌دور قابل‌استفاده‌ای ندارد، به HEAD محلی بازمی‌گردد.

آماده‌سازی فایل‌های نادیده‌گرفته‌شده

برای کپی‌کردن فایل‌های ردیابی‌نشده و نادیده‌گرفته‌شدهٔ منتخب در یک درخت کاری جدید، .worktreeinclude را در ریشهٔ مخزن منبع اضافه کنید. این فایل از نحو الگوی gitignore استفاده می‌کند، با یک الگو در هر خط و توضیحات #:

.env.localfixtures/generated/**

فقط فایل‌هایی واجد شرایط‌اند که گیت آن‌ها را هم نادیده‌گرفته‌شده و هم ردیابی‌نشده گزارش کند. فایل‌های ردیابی‌شده از قبل از طریق گیت موجودند و هرگز در این مرحله کپی نمی‌شوند. OpenClaw فایل‌های مقصدی را که از قبل وجود دارند بازنویسی یا تغییر نمی‌دهد، دایرکتوری‌های دارای پیوند نمادین را دنبال نمی‌کند و حالت فایل‌های کپی‌شده را حفظ می‌کند. فقط مسیرهایی را ثبت می‌کند که واقعاً ایجاد کرده است؛ بنابراین ویرایش‌های بعدی manifest نمی‌توانند باعث شوند آن فایل‌ها حفاظت خود در برابر پاک‌سازی را از دست بدهند.

اجرای راه‌اندازی مخزن

اگر .openclaw/worktree-setup.sh در مخزن منبع وجود داشته باشد و اجرایی باشد، OpenClaw آن را با درخت کاری جدید به‌عنوان دایرکتوری جاری اجرا می‌کند. اسکریپت این مقادیر را دریافت می‌کند:

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

خروج با کد غیرصفر، ایجاد را متوقف می‌کند و درخت کاری و شاخهٔ جدید را حذف می‌کند. این یک قرارداد محلی مخزن است؛ هیچ کلید پیکربندی OpenClaw برای آن وجود ندارد.

درخت‌های کاری نشست

با یک نشست درخت کاری، یک گفت‌وگوی ایزوله را از پوشه‌ای مبتنی بر Git آغاز کنید: در صفحهٔ New session در Control UI، از انتخاب‌گر Place برای انتخاب پوشهٔ منبع Gateway استفاده کنید، سپس Worktree را انتخاب کنید (با شاخهٔ پایه و نام درخت کاری اختیاری). این انتخاب فقط پس از آن ظاهر می‌شود که Gateway تأیید کند پوشهٔ انتخاب‌شده یک checkout گیت است؛ پوشه‌های معمولی مستقیماً اجرا می‌شوند و هیچ کنترل ایزوله‌سازی Git نشان نمی‌دهند. هنگامی که فضای کاری عامل فعال مبتنی بر Git باشد، iOS همین انتخاب را از Chat actions و Android آن را کنار New Chat ارائه می‌کند.

عامل‌های کدنویسی همچنین می‌توانند هنگامی که کار پیگیری تأییدشده‌ای خارج از وظیفهٔ جاری کشف می‌کنند، spawn_task را فراخوانی کنند. Control UI بدون آغاز هیچ کاری یک تراشهٔ پیشنهاد نشان می‌دهد، درحالی‌که یک TUI مبتنی بر Gateway یک اعلان تعاملی با همان کنش‌ها نمایش می‌دهد. انتخاب Start in worktree یک درخت کاری تازه و متعلق به نشست از پروژهٔ پیشنهادی ایجاد می‌کند و اعلان خودبسنده را به‌عنوان نخستین نوبت آن می‌فرستد؛ ردکردن پیشنهاد، مخزن را دست‌نخورده باقی می‌گذارد. پیشنهادها و شناسه‌هایشان موقتی‌اند و پس از راه‌اندازی مجدد Gateway باقی نمی‌مانند.

OpenClaw این ابزارها را فقط در اختیار نشست‌های اپراتور دارای رابط کاربری عملیاتی Gateway قرار می‌دهد. نشست‌های کانال و نشست‌های TUI محلی/تعبیه‌شده تا زمانی که این سطوح قرارداد قابل‌حمل و نوع‌دار کنش وظیفه نداشته باشند، آن‌ها را دریافت نمی‌کنند.

درخت کاری مدیریت‌شدهٔ حاصل، متعلق به نشست است و هر اجرای عامل در آن نشست از checkout آن استفاده می‌کند. هنگامی که فضای کاری یک زیردایرکتوری مخزن باشد، درخت کاری در ریشهٔ مخزن لنگر می‌اندازد و نشست از زیردایرکتوری متناظر داخل آن اجرا می‌شود. ایجاد درخت کاری نشست از دامنهٔ operator.write متد استفاده می‌کند، اما hookهای checkout مخزن و مرحلهٔ .openclaw/worktree-setup.sh فقط برای فراخواننده‌های operator.admin اجرا می‌شوند، زیرا کد مخزن را اجرا می‌کنند؛ آماده‌سازی .worktreeinclude همچنان برای هر فراخواننده اعمال می‌شود. حذف نشست فقط زمانی درخت کاری را حذف می‌کند که انجام این کار بدون اتلاف باشد. درخت‌های کاری کثیف یا شاخه‌های دارای commitهای pushنشده در دسترس باقی می‌مانند؛ پاک‌سازی ساعتی از درخت‌های کاری نشست پس از 7 روز عدم فعالیت snapshot می‌گیرد و فعالیت اخیر نشست را فعالیت درخت کاری محسوب می‌کند. درخت‌های کاری حذف‌شده، همان‌طور که در ادامه شرح داده شده است، از snapshotهایشان قابل‌بازیابی باقی می‌مانند.

sessions.create می‌تواند شامل یک cwd مطلق باشد تا مستقیماً در پوشه‌ای دیگر از Gateway اجرا شود، checkout منبع را همراه با worktree: true انتخاب کند، یا دایرکتوری کاری یک Node جفت‌شده را تنظیم کند. هر مسیر صریح میزبان به operator.admin نیاز دارد؛ ایجاد عادی گفت‌وگوی درخت کاری همچنان operator.write باقی می‌ماند و به فضای کاری پیکربندی‌شده متصل می‌ماند.

sessions.create همچنین worktreeBaseRef و worktreeName را در کنار worktree: true می‌پذیرد تا ref پایه و نام درخت کاری را انتخاب کند (شاخه به openclaw/<name> تبدیل می‌شود)؛ هر دو در operator.write باقی می‌مانند. درخت کاری ایجادشده در نتیجهٔ ایجاد بازگردانده می‌شود و به‌صورت worktree: { id, branch, repoRoot } در ردیف نشست پایدار می‌شود تا فهرست نشست‌ها بتواند checkout و شاخه را نشان دهد. حذف نشست، یک checkout کثیف حفظ‌شده را به‌صورت worktreePreserved گزارش می‌کند، به‌جای آنکه بی‌سروصدا آن را باقی بگذارد.

Snapshotها، پاک‌سازی و بازیابی

حذف ابتدا یک commit مصنوعی شامل فایل‌های ردیابی‌شده و ردیابی‌نشدهٔ نادیده‌گرفته‌نشده ایجاد می‌کند و سپس آن را در refs/openclaw/snapshots/<id> سنجاق می‌کند. فایل‌های نادیده‌گرفته‌شده هرگز وارد پایگاه دادهٔ اشیای مخزن نمی‌شوند. OpenClaw فقط فایل‌های نادیده‌گرفته‌شده‌ای را که واقعاً آماده کرده است در ردیف‌های تکه‌بندی‌شدهٔ پایگاه دادهٔ وضعیت مشترک ذخیره می‌کند؛ مجموعه‌مسیر ثبت‌شده حتی اگر .worktreeinclude بعداً تغییر کند یا ناپدید شود، مرجع معتبر باقی می‌ماند. بازیابی آن بایت‌ها را از snapshot تغییرناپذیر می‌خواند و حالت‌های کامل آن‌ها را دوباره اعمال می‌کند. اگر دیگر نتوان از یک مسیر ثبت‌شده به‌شکلی ایمن snapshot گرفت، پاک‌سازی خودکار درخت کاری زنده را حفظ می‌کند. اگر ایجاد snapshot ناموفق باشد، حذف متوقف می‌شود. حذف اجباری صریح می‌تواند بدون snapshot ادامه یابد.

OpenClaw این قواعد پاک‌سازی را اعمال می‌کند:

• در پایان اجرا، فقط زمانی درخت کاری را حذف می‌کند که git status --porcelain خالی باشد و git log HEAD --not --remotes --oneline هیچ commit پوش‌نشده‌ای پیدا نکند. در غیر این صورت فقط قفل فعالیت را آزاد می‌کند.
• پاک‌سازی ساعتی از درخت‌های کاری متعلق به Workboard و نشست که بیش از 7 روز بدون فعالیت و بدون قفل بوده‌اند snapshot می‌گیرد و آن‌ها را حذف می‌کند، حتی اگر کثیف باشند. درخت‌های کاری دستی هرگز به‌طور خودکار حذف نمی‌شوند.
• رکوردهای snapshot تا 30 روز قابل‌بازیابی باقی می‌مانند. سپس پاک‌سازی، ref مربوط به snapshot و ردیف رجیستری را حذف می‌کند.
• یک قفل فرایند زندهٔ OpenClaw و هر قفل خارجی یا ناشناختهٔ درخت کاری گیت، درخت کاری را در برابر جمع‌آوری زباله محافظت می‌کند.

بازیابی، openclaw/<name> را در commit اصلی پیش از snapshot دوباره ایجاد می‌کند و سپس تفاوت‌های snapshot را به‌صورت تغییرات stageنشده و فایل‌های ردیابی‌نشده بازسازی می‌کند. این کار commit مصنوعی snapshot را خارج از تاریخچهٔ شاخه نگه می‌دارد. ref مربوط به snapshot به‌عنوان منشأ ثبت‌شده باقی می‌ماند.

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 یا نشست مالک همراه با پیوندی به گفت‌وگوی آن) و هنگامی که حذف، snapshot ناموفق را گزارش می‌کند، امکان تلاش مجدد اجباری را ارائه می‌دهد.

متدهای Gateway

worktrees.list به operator.read نیاز دارد و متدهای تغییردهنده به operator.admin نیاز دارند. worktrees.branches برای فضاهای کاری عامل پیکربندی‌شده به operator.write نیاز دارد، درحالی‌که هر مسیر میزبان دیگری به operator.admin نیاز دارد (مطابق با محدودیت cwd در sessions.create). این متد فقط refهای موجود را می‌خواند و هرگز واکشی نمی‌کند؛ شاخه‌هایی که فقط روی راه‌دور هستند به‌صورت واجد نام راه‌دور بازگردانده می‌شوند (origin/feature-a) تا هر نام بازگردانده‌شده به‌عنوان ref پایه قابل‌حل باشد. New Session همچنین می‌تواند وضعیت نوع‌دار مخزن را از این متد درخواست کند؛ یک دایرکتوری ساده یا checkout دردسترس‌نبوده به‌جای واداشتن رابط کاربری به استنباط قابلیت Git از یک رشتهٔ خطا، هیچ شاخه‌ای بازنمی‌گرداند.

فضاهای کاری Workboard

Plugin مربوط به Workboard که همراه محصول ارائه می‌شود، می‌تواند فضای کاری یک کارت را به‌صورت درخت کاری مدیریت‌شده محقق کند:

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

path checkout گیت منبع را مشخص می‌کند. branch اختیاری است و به ref پایه تبدیل می‌شود. برای فراخواننده‌ای با دسترسی کامل به میزبان، Workboard مقدار wb-<card-id> را ایجاد می‌کند یا دوباره به‌کار می‌گیرد، زیرعامل را با checkout مدیریت‌شده به‌عنوان دایرکتوری کاری اجرا می‌کند و مسیر و شاخهٔ حل‌شده را دوباره در کارت می‌نویسد. کلاینت‌های Gateway برای تحقق روی میزبان کامل به operator.admin نیاز دارند. در پایان اجرا، Workboard فقط زمانی checkout را حذف می‌کند که بدون اتلاف بودن آن قابل‌اثبات باشد؛ کار کثیف یا commitهای پوش‌نشده در دسترس باقی می‌مانند.

برای فراخواننده‌ای محدود به فضای کاری، path و ریشهٔ مخزن باید دقیقاً با فضای کاری عامل هدف مطابقت داشته باشند. سپس Workboard مستقیماً در آن دایرکتوری اجرا می‌شود و به‌جای تحقق یک درخت کاری مدیریت‌شده روی میزبان، یک فضای کاری دایرکتوری ثبت می‌کند. هدف باید برای همان فضای کاری از یک sandbox داکر قابل‌نوشتن و غیرمشترک استفاده کند، هش کانتینر زندهٔ آن باید با mountها و خط‌مشی درخواستی مطابقت داشته باشد و نباید اجرای ارتقایافته، کنترل میزبان، نشست‌های سراسری میزبان، اجرای پایدار میزبان/Node یا ابزارهای Plugin و MCP طبقه‌بندی‌نشده را در معرض دسترسی قرار دهد. اگر خط‌مشی هدف یا کانتینر زنده گسترده‌تر باشد، واگذاری کارت را بدون تخصیص باقی می‌گذارد و وضعیت ناسازگار را گزارش می‌کند.