---
read_when:
    - إضافة سلوك التنفيذ في الخلفية أو تعديله
    - تصحيح أخطاء مهام التنفيذ طويلة الأمد
summary: تنفيذ الأوامر في الخلفية وإدارة العمليات
title: التنفيذ في الخلفية وأداة العمليات
x-i18n:
    generated_at: "2026-07-12T05:50:10Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b540455797df71dcdb18b0caa5f5088e81ef8823e0ec79364bebad8e6f060f12
    source_path: gateway/background-process.md
    workflow: 16
---

ينفّذ OpenClaw أوامر الصدفة عبر أداة `exec` ويحتفظ بالمهام طويلة التشغيل في الذاكرة. تدير أداة `process` تلك الجلسات التي تعمل في الخلفية.

## أداة exec

المعلمات:

| المعلمة     | الوصف                                                                                                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command`    | مطلوبة. أمر الصدفة المراد تنفيذه.                                                                                                                                                  |
| `workdir`    | دليل العمل؛ احذفه لاستخدام دليل العمل الحالي الافتراضي.                                                                                                                           |
| `env`        | متغيرات بيئة إضافية للأمر.                                                                                                                                                         |
| `yieldMs`    | عدد المللي ثواني للانتظار قبل نقل المهمة إلى الخلفية (القيمة الافتراضية 10000).                                                                                                    |
| `background` | التشغيل في الخلفية فورًا.                                                                                                                                                          |
| `timeout`    | المهلة بالثواني (القيمة الافتراضية `tools.exec.timeoutSec`)؛ تُنهي العملية عند انقضائها. عيّن `timeout: 0` لتعطيل مهلة عملية exec لذلك الاستدعاء.                                  |
| `pty`        | التشغيل في طرفية زائفة عند توفرها (أدوات CLI التي تتطلب TTY، ووكلاء البرمجة).                                                                                                      |
| `elevated`   | التشغيل خارج بيئة العزل إذا كان الوضع المرتفع مفعّلًا/مسموحًا (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`).                                                      |
| `host`       | هدف exec:‏ `auto` أو `sandbox` أو `gateway` أو `node`.                                                                                                                             |
| `node`       | معرّف/اسم Node، ويُستخدم مع `host: "node"`.                                                                                                                                        |

السلوك:

- تعيد عمليات التشغيل في الواجهة الأمامية المخرجات مباشرةً.
- عند نقل التشغيل إلى الخلفية (صراحةً أو بسبب انقضاء مهلة `yieldMs`)، تعيد الأداة `status: "running"` مع `sessionId` ونهاية قصيرة من المخرجات.
- ترث عمليات التشغيل في الخلفية وعمليات `yieldMs` القيمة `tools.exec.timeoutSec` ما لم يمرّر الاستدعاء قيمة `timeout` صريحة.
- تبقى المخرجات في الذاكرة حتى يتم استطلاع الجلسة أو مسحها.
- إذا كانت أداة `process` غير مسموح بها، تعمل `exec` بشكل متزامن وتتجاهل `yieldMs` و`background`.
- تتلقى أوامر exec المنشأة المتغير `OPENCLAW_SHELL=exec` لتمكين قواعد الصدفة/ملف التعريف المدركة للسياق.
- للعمل طويل التشغيل الذي يبدأ الآن: ابدأه مرة واحدة واعتمد على إيقاظ الإكمال التلقائي (عند تمكينه) بمجرد أن يصدر الأمر مخرجات أو يفشل.
- إذا لم يكن إيقاظ الإكمال التلقائي متاحًا، أو كنت تحتاج إلى تأكيد نجاح صامت لأمر ينتهي بنجاح دون مخرجات، فاستطلع باستخدام `process`.
- لا تحاكِ التذكيرات أو المتابعات المؤجلة باستخدام حلقات `sleep` أو الاستطلاع المتكرر — استخدم Cron للعمل المستقبلي.

### تجاوزات متغيرات البيئة

| المتغير                                 | التأثير                                                                                                                          |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_BASH_YIELD_MS`                 | مهلة الانتظار الافتراضية قبل النقل إلى الخلفية (بالمللي ثانية). القيمة الافتراضية 10000، ومحصورة بين 10 و120000.                |
| `OPENCLAW_BASH_MAX_OUTPUT_CHARS`         | الحد الأقصى للمخرجات في الذاكرة (بالأحرف).                                                                                       |
| `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS` | الحد الأقصى لمخرجات stdout/stderr المعلّقة لكل تدفق (بالأحرف).                                                                   |
| `OPENCLAW_BASH_JOB_TTL_MS`               | مدة البقاء للجلسات المنتهية (بالمللي ثانية)، ومحصورة بين دقيقة واحدة و3 ساعات.                                                   |
| `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`    | عتبة خمول المخرجات قبل وسم جلسات الخلفية القابلة للكتابة بأنها تنتظر إدخالًا على الأرجح. القيمة الافتراضية 15000.              |

### الإعداد (مفضّل على تجاوزات متغيرات البيئة)

| المفتاح                               | القيمة الافتراضية | التأثير                                                                                     |
| ------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- |
| `tools.exec.backgroundMs`             | 10000             | مماثل لـ `OPENCLAW_BASH_YIELD_MS`.                                                          |
| `tools.exec.timeoutSec`               | 1800              | المهلة الافتراضية لكل استدعاء.                                                              |
| `tools.exec.cleanupMs`                | 1800000           | مماثل لـ `OPENCLAW_BASH_JOB_TTL_MS`.                                                        |
| `tools.exec.notifyOnExit`             | true              | يضع حدث نظام في قائمة الانتظار ويطلب Heartbeat عند انتهاء عملية exec تعمل في الخلفية.      |
| `tools.exec.notifyOnExitEmptySuccess` | false             | يضع أيضًا أحداث إكمال في قائمة الانتظار لعمليات الخلفية الناجحة التي لا تنتج مخرجات.       |

## ربط العمليات الفرعية

عند إنشاء عمليات فرعية طويلة التشغيل خارج أداتي exec/process (إعادة تشغيل CLI، ومساعدات Gateway)، أرفق مساعد جسر العمليات الفرعية لكي يعيد توجيه إشارات الإنهاء ويفصل المستمعين عند الخروج/الخطأ. يمنع ذلك بقاء عمليات يتيمة على systemd ويحافظ على اتساق الإيقاف عبر المنصات.

## أداة process

الإجراءات:

| الإجراء     | التأثير                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------- |
| `list`      | الجلسات قيد التشغيل والمنتهية.                                                                |
| `poll`      | استنزاف المخرجات الجديدة لجلسة (ويُبلغ أيضًا عن حالة الخروج).                                |
| `log`       | قراءة المخرجات المجمّعة وتلميحات استعادة الإدخال. يدعم `offset` و`limit`.                     |
| `write`     | إرسال stdin ‏(`data`، مع `eof` اختياريًا).                                                    |
| `send-keys` | إرسال رموز مفاتيح أو بايتات صريحة إلى جلسة مدعومة بطرفية PTY.                                |
| `submit`    | إرسال Enter/محرف إرجاع العربة إلى جلسة مدعومة بطرفية PTY.                                    |
| `paste`     | إرسال نص حرفي، مع إمكانية تغليفه في وضع اللصق المحدد بأقواس.                                 |
| `kill`      | إنهاء جلسة تعمل في الخلفية.                                                                   |
| `clear`     | إزالة جلسة منتهية من الذاكرة.                                                                 |
| `remove`    | إنهاء الجلسة إذا كانت قيد التشغيل، وإلا مسحها إذا كانت منتهية.                               |

ملاحظات:

- لا تُدرج أو تُحفظ إلا الجلسات التي تعمل في الخلفية — في الذاكرة فقط، وليس على القرص. تُفقد الجلسات عند إعادة تشغيل العملية.
- تمنع جلسة خلفية نشطة التعليق التعاوني للمضيف وإعادة التشغيل الآمنة لـ Gateway حتى يؤكد مالك العملية خروجها الفعلي.
- يمكن لـ `process remove` إخفاء جلسة قيد التشغيل فورًا بعد طلب إنهائها؛ يظل التعليق وإعادة التشغيل محظورين حتى تأكيد الخروج.
- لا تُحفظ سجلات الجلسة في سجل المحادثة إلا إذا شغّلت `process poll`/`log` وسُجلت نتيجة الأداة.
- يقتصر نطاق `process` على كل وكيل؛ ولا يرى إلا الجلسات التي بدأها ذلك الوكيل.
- استخدم `poll`/`log` لمعرفة الحالة أو السجلات أو تأكيد الإكمال عندما لا يكون إيقاظ الإكمال التلقائي متاحًا.
- استخدم `log` قبل استعادة جلسة CLI تفاعلية، لكي يظهر النص الحالي وحالة stdin وتلميح انتظار الإدخال معًا.
- استخدم `write`/`send-keys`/`submit`/`paste`/`kill` عندما تحتاج إلى إدخال أو تدخل.
- يتضمن `process list` قيمة `name` مشتقة (فعل الأمر مع الهدف) للمراجعة السريعة.
- لا تعرض `process list` و`poll` و`log` القيمة `waitingForInput` إلا عندما لا يزال للجلسة stdin قابلًا للكتابة وقد ظلت خاملة مدة تتجاوز عتبة انتظار الإدخال (القيمة الافتراضية 15000 مللي ثانية، `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`).
- يستخدم `process log` قيمتي `offset`/`limit` المستندتين إلى الأسطر. عند حذف كلتيهما، يعيد آخر 200 سطر مع تلميح للتنقل بين الصفحات. عند تعيين `offset` دون `limit`، يعيد المحتوى من `offset` إلى النهاية (دون حد أقصى قدره 200).
- تنتظر قيمة `timeout` في `poll` حتى ذلك العدد من المللي ثواني قبل العودة؛ وتُحصر القيم التي تتجاوز 30000 عند 30000.
- الاستطلاع مخصص لمعرفة الحالة عند الطلب، وليس لجدولة حلقات الانتظار. إذا كان ينبغي تنفيذ العمل لاحقًا، فاستخدم Cron.

## أمثلة

شغّل مهمة طويلة واستطلعها لاحقًا:

```json
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

افحص جلسة تفاعلية قبل إرسال الإدخال:

```json
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

ابدأ فورًا في الخلفية:

```json
{ "tool": "exec", "command": "npm run build", "background": true }
```

أرسل stdin:

```json
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

أرسل مفاتيح PTY:

```json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
```

أرسل السطر الحالي:

```json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

الصق نصًا حرفيًا:

```json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

## ذو صلة

- [أداة Exec](/ar/tools/exec)
- [موافقات Exec](/ar/tools/exec-approvals)