---
read_when:
    - تريد فرعًا ونسخة عمل معزولين لمهمة وكيل
    - أنت تهيّئ بطاقات Workboard باستخدام مساحات عمل worktree
    - تحتاج إلى استعادة شجرة عمل مُدارة بواسطة OpenClaw أو تنظيفها
summary: شغّل مهام الوكيل في نسخ عمل معزولة من git مع لقطات تلقائية وتنظيف تلقائي
title: مساحات العمل المُدارة
x-i18n:
    generated_at: "2026-07-12T05:50:26Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 12a33dc2d9f1ff30060ddead200196b09cfe9498462f58a7aa8a73fa2273f31f
    source_path: concepts/managed-worktrees.md
    workflow: 16
---

تمنح أشجار العمل المُدارة مهمة الوكيل فرع Git ونسخة عمل خاصة بها، من دون وضع أدلة مؤقتة داخل مستودع المصدر. ينشئها OpenClaw ضمن دليل حالته، ويسجلها في قاعدة بيانات الحالة المشتركة، ويلتقط لقطات لمحتوياتها المتعقبة وغير المتعقبة وغير المتجاهلة قبل الإزالة.

## التخطيط والأسماء

توجد كل شجرة عمل في:

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

بصمة المستودع هي أول 16 محرفًا سداسيًا عشريًا من تجزئة SHA-256 محسوبة على دليل Git المشترك المتعارف عليه وعنوان URL للأصل. يجب أن يطابق الاسم المُقدَّم `[a-z0-9][a-z0-9-]{0,63}`. عند عدم تقديم اسم، ينشئ OpenClaw اسمًا يبدأ بـ `wt-` متبوعًا بثمانية محارف سداسية عشرية عشوائية.

ينشئ OpenClaw الفرع `openclaw/<name>` عند مرجع الأساس المطلوب. عند عدم تقديم مرجع أساس، يجلب `origin`، ويستخدم الفرع الافتراضي البعيد عند توفره، ويرجع إلى `HEAD` المحلي عندما يكون المستودع غير متصل أو لا يحتوي على مستودع بعيد صالح للاستخدام.

## توفير الملفات المتجاهلة

أضف `.worktreeinclude` إلى جذر مستودع المصدر لنسخ ملفات محددة متجاهلة وغير متعقبة إلى شجرة عمل جديدة. يستخدم الملف صياغة أنماط gitignore، بنمط واحد في كل سطر، مع تعليقات تبدأ بـ `#`:

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

لا تكون مؤهلة إلا الملفات التي يبلغ Git بأنها متجاهلة وغير متعقبة معًا. تكون الملفات المتعقبة موجودة بالفعل عبر Git ولا تُنسخ أبدًا في هذه الخطوة. لا يستبدل OpenClaw ملفات الوجهة ولا يتبع الأدلة ذات الروابط الرمزية، ويحافظ على أوضاع الملفات المنسوخة.

## تشغيل إعداد المستودع

إذا كان `.openclaw/worktree-setup.sh` موجودًا في مستودع المصدر وقابلًا للتنفيذ، يشغّله OpenClaw مع تعيين شجرة العمل الجديدة بوصفها دليله الحالي. يتلقى السكربت:

```text
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** إلى إنشاء شجرة عمل جديدة مملوكة للجلسة من المشروع المقترح وإرسال المطالبة المستقلة بوصفها أول دورة فيها؛ ولا يؤدي رفض الاقتراح إلى أي تغيير في المستودع. الاقتراحات ومعرّفاتها مؤقتة ولا تستمر بعد إعادة تشغيل Gateway.

لا يتيح OpenClaw هذه الأدوات إلا لجلسات المشغّل التي تحتوي على واجهة 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` لاختيار مرجع الأساس واسم شجرة العمل (ويصبح الفرع `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 يومًا. بعد ذلك يحذف التنظيف مرجع اللقطة وصف السجل.
- يحمي قفل عملية OpenClaw نشطة وأي قفل أجنبي أو غير معروف لشجرة عمل Git شجرة العمل من جمع المهملات.

تعيد الاستعادة إنشاء `openclaw/<name>` عند التثبيت الأصلي السابق للّقطة، ثم تعيد بناء اختلافات اللقطة كتعديلات غير مرحّلة وملفات غير متعقبة. يُبقي هذا تثبيت اللقطة الاصطناعي خارج سجل الفرع. يظل مرجع اللقطة مسجلًا لإثبات المصدر.

## 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** ضمن Settings في Control UI الإجراءات نفسها، بالإضافة إلى الإنشاء باستخدام أداة اختيار فرع الأساس، وتعرض مالك كل شجرة عمل (يدويًا، أو Workboard، أو الجلسة المالكة مع رابط إلى محادثتها)، وتوفر إعادة محاولة قسرية عندما تبلغ الإزالة عن فشل اللقطة.

## طرق Gateway

| الطريقة               | الغرض                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `worktrees.list`     | سرد سجلات أشجار العمل النشطة والقابلة للاستعادة.                            |
| `worktrees.branches` | سرد الفروع المحلية والبعيدة لمستودع لاستخدامها في أدوات اختيار مرجع الأساس.    |
| `worktrees.create`   | إنشاء شجرة عمل مُدارة مسماة أو إعادة استخدامها.                               |
| `worktrees.remove`   | التقاط لقطة لشجرة عمل وإزالتها. تُبلغ عمليات الإزالة القسرية عن `snapshotError`. |
| `worktrees.restore`  | استعادة شجرة عمل مُزالة من لقطتها.                                           |
| `worktrees.gc`       | تشغيل تنظيف الخمول والعناصر اليتيمة وسياسة الاحتفاظ الآن.                       |

يتطلب `worktrees.list` نطاق `operator.read`، وتتطلب الطرق التي تُجري تغييرات نطاق `operator.admin`. يحتاج `worktrees.branches` إلى `operator.write` لمساحات عمل الوكلاء المُعدّة، بينما يتطلب أي مسار مضيف آخر نطاق `operator.admin` (مطابقًا لشرط `cwd` في `sessions.create`). يقرأ المراجع الموجودة فقط ولا يجلب أبدًا، وتُعاد الفروع الموجودة عن بُعد فقط مؤهلة باسم المستودع البعيد (`origin/feature-a`) بحيث يمكن استخدام كل اسم مُعاد بوصفه مرجع أساس.

## مساحات عمل Workboard

يمكن لـ [Plugin Workboard المضمن](/ar/plugins/workboard) تجسيد مساحة عمل بطاقة بوصفها شجرة عمل مُدارة:

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

يحدد `path` نسخة عمل Git المصدرية. ويكون `branch` اختياريًا ويصبح مرجع الأساس. عندما يبدأ الإرسال عامل البطاقة، ينشئ Workboard أو يعيد استخدام `wb-<card-id>`، ويشغّل الوكيل الفرعي مع نسخة العمل المُدارة بوصفها دليل عمله، ويكتب المسار والفرع المحسومين مرة أخرى في البطاقة. يتطلب التجسيد الذي يشغّله Gateway نطاق `operator.admin`. عند نهاية التشغيل، لا يزيل Workboard نسخة العمل إلا عندما يمكن إثبات عدم فقدان أي شيء؛ ويظل العمل غير النظيف أو التثبيتات غير المدفوعة متاحة.

ترفض الوكلاء المضمنة والمعزولة حاليًا دليل عمل لمهمة يقع خارج مساحة عمل الوكيل المُعدّة. استخدم وكيلًا مستهدفًا غير معزول لبطاقات Workboard ذات أشجار العمل المُدارة إلى أن يدعم وقت تشغيل العزل تركيبًا إضافيًا لنسخة العمل.