---
read_when:
    - برای یک وظیفهٔ عامل، یک شاخه و نسخهٔ کاری مجزا می‌خواهید
    - در حال پیکربندی کارت‌های Workboard با فضاهای کاری worktree هستید
    - باید یک worktree مدیریت‌شده توسط OpenClaw را بازیابی یا پاک‌سازی کنید
summary: وظایف عامل را در نسخه‌های کاری ایزولهٔ git با snapshot‌گیری و پاک‌سازی خودکار اجرا کنید
title: ورک‌تری‌های مدیریت‌شده
x-i18n:
    generated_at: "2026-07-27T15:21:44Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 98ed2579b7243544dbdb550c4b8a292ccd4ab494fd4a45b2404256691c831401
    source_path: concepts/managed-worktrees.md
    workflow: 16
---

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

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

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

```text
<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 استفاده می‌کند، با یک الگو در هر خط و توضیحات `#`:

```gitignore
.env.local
fixtures/generated/**
```

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

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

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

```text
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

```bash
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`     | فهرست‌کردن رکوردهای درخت کاری فعال و قابل‌بازیابی.                            |
| `worktrees.branches` | فهرست‌کردن شاخه‌های محلی و راه‌دور یک مخزن برای انتخاب‌گرهای ref پایه.    |
| `worktrees.create`   | ایجاد یا استفادهٔ مجدد از یک درخت کاری مدیریت‌شدهٔ نام‌گذاری‌شده.                               |
| `worktrees.remove`   | گرفتن snapshot و حذف یک درخت کاری. حذف‌های اجباری `snapshotError` را گزارش می‌کنند. |
| `worktrees.restore`  | بازیابی یک درخت کاری حذف‌شده از snapshot آن.                           |
| `worktrees.gc`       | اجرای فوری پاک‌سازی عدم فعالیت، موارد یتیم و دورهٔ نگهداشت.                            |

`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](/fa/plugins/workboard) که همراه محصول ارائه می‌شود، می‌تواند فضای کاری یک کارت را به‌صورت درخت کاری مدیریت‌شده محقق کند:

```json
{
  "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 طبقه‌بندی‌نشده را در معرض دسترسی قرار دهد. اگر خط‌مشی هدف یا کانتینر زنده گسترده‌تر باشد، واگذاری کارت را بدون تخصیص باقی می‌گذارد و وضعیت ناسازگار را گزارش می‌کند.