---
read_when:
    - إضافة سلوك exec في الخلفية أو تعديله
    - تصحيح مشكلات مهام exec طويلة التشغيل
summary: تنفيذ exec في الخلفية وإدارة العمليات
title: Background Exec وأداة Process
x-i18n:
    generated_at: "2026-04-05T12:42:12Z"
    model: gpt-5.4
    provider: openai
    source_hash: 4398e2850f6f050944f103ad637cd9f578e9cc7fb478bc5cd5d972c92289b831
    source_path: gateway/background-process.md
    workflow: 15
---

# Background Exec + أداة Process

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

## أداة exec

المعلمات الأساسية:

- `command` (مطلوب)
- `yieldMs` (الافتراضي 10000): التحويل التلقائي إلى الخلفية بعد هذا التأخير
- `background` (منطقي): التشغيل في الخلفية فورًا
- `timeout` (بالثواني، الافتراضي 1800): إنهاء العملية بعد هذه المهلة
- `elevated` (منطقي): التشغيل خارج sandbox إذا كان الوضع المرتفع ممكّنًا/مسموحًا (`gateway` افتراضيًا، أو `node` عندما يكون هدف exec هو `node`)
- هل تحتاج إلى TTY حقيقي؟ اضبط `pty: true`.
- `workdir` و`env`

السلوك:

- تعيد عمليات التشغيل الأمامية المخرجات مباشرة.
- عند تشغيلها في الخلفية (صراحةً أو بسبب المهلة)، تعيد الأداة `status: "running"` + `sessionId` وذيلًا قصيرًا.
- يتم الاحتفاظ بالمخرجات في الذاكرة حتى يتم استطلاع الجلسة أو مسحها.
- إذا كانت أداة `process` غير مسموح بها، يعمل `exec` بشكل متزامن ويتجاهل `yieldMs`/`background`.
- تتلقى أوامر exec التي تم إنشاؤها المتغير `OPENCLAW_SHELL=exec` لاستخدامه في قواعد shell/profile المعتمدة على السياق.
- بالنسبة إلى العمل طويل التشغيل الذي يبدأ الآن، ابدأه مرة واحدة واعتمد على
  تنبيه الإكمال التلقائي عند تمكينه وعندما يصدر الأمر مخرجات أو يفشل.
- إذا لم يكن تنبيه الإكمال التلقائي متاحًا، أو كنت تحتاج إلى
  تأكيد نجاح صامت لأمر انتهى بنجاح من دون مخرجات، فاستخدم `process`
  لتأكيد الاكتمال.
- لا تحاكِ التذكيرات أو المتابعات المؤجلة باستخدام حلقات `sleep` أو الاستطلاع
  المتكرر؛ استخدم cron للأعمال المستقبلية.

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

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

تجاوزات البيئة:

- `PI_BASH_YIELD_MS`: مهلة yield الافتراضية (مللي ثانية)
- `PI_BASH_MAX_OUTPUT_CHARS`: الحد الأقصى للمخرجات في الذاكرة (أحرف)
- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: الحد الأقصى المعلق لـ stdout/stderr لكل تدفق (أحرف)
- `PI_BASH_JOB_TTL_MS`: مدة بقاء الجلسات المكتملة (مللي ثانية، ومقيدة بين 1m–3h)

الإعدادات (المفضلة):

- `tools.exec.backgroundMs` (الافتراضي 10000)
- `tools.exec.timeoutSec` (الافتراضي 1800)
- `tools.exec.cleanupMs` (الافتراضي 1800000)
- `tools.exec.notifyOnExit` (الافتراضي true): يضيف حدث نظام إلى الطابور + يطلب heartbeat عند خروج exec الذي يعمل في الخلفية.
- `tools.exec.notifyOnExitEmptySuccess` (الافتراضي false): عند ضبطه على true، يضيف أيضًا أحداث اكتمال لعمليات الخلفية الناجحة التي لم تنتج أي مخرجات.

## أداة process

الإجراءات:

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

ملاحظات:

- يتم عرض/الاحتفاظ في الذاكرة فقط بالجلسات التي تعمل في الخلفية.
- تُفقد الجلسات عند إعادة تشغيل العملية (لا يوجد حفظ على القرص).
- لا تُحفَظ سجلات الجلسة في سجل الدردشة إلا إذا شغّلت `process poll/log` وتم تسجيل نتيجة الأداة.
- يكون `process` ضمن نطاق كل وكيل؛ فهو لا يرى إلا الجلسات التي بدأها ذلك الوكيل.
- استخدم `poll` / `log` للحالة، والسجلات، وتأكيد النجاح الصامت، أو
  تأكيد الاكتمال عندما لا يكون تنبيه الإكمال التلقائي متاحًا.
- استخدم `write` / `send-keys` / `submit` / `paste` / `kill` عندما تحتاج إلى إدخال
  أو تدخل.
- يتضمن `process list` حقل `name` مشتقًا (فعل الأمر + الهدف) للفحص السريع.
- يستخدم `process log` القيمتين `offset`/`limit` على أساس الأسطر.
- عند حذف كل من `offset` و`limit`، يعيد آخر 200 سطر ويتضمن تلميحًا للتصفح.
- عند توفير `offset` وحذف `limit`، يعيد من `offset` حتى النهاية (ولا يُقيد بـ 200).
- الاستطلاع مخصص للحالة عند الطلب، وليس لجدولة حلقات الانتظار. إذا كان العمل يجب
  أن يحدث لاحقًا، فاستخدم cron بدلًا من ذلك.

## أمثلة

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

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

```json
{ "tool": "process", "action": "poll", "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" }
```
