---
read_when:
    - إضافة أو تعديل سلوك التنفيذ في الخلفية
    - تصحيح أخطاء مهام exec طويلة التشغيل
summary: تنفيذ exec في الخلفية وإدارة العمليات
title: أداة التنفيذ في الخلفية والعمليات
x-i18n:
    generated_at: "2026-06-27T17:34:58Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 5822c1e26b0144c5216ae6e59e279ccc506cf4c0a42b8cd6c386f535fe458bd3
    source_path: gateway/background-process.md
    workflow: 16
---

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

## أداة exec

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

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

السلوك:

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

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

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

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

- `OPENCLAW_BASH_YIELD_MS`: المهلة الافتراضية قبل الإرجاع (مللي ثانية)
- `OPENCLAW_BASH_MAX_OUTPUT_CHARS`: حد المخرجات المحفوظة في الذاكرة (أحرف)
- `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: حد stdout/stderr المعلّق لكل تدفق (أحرف)
- `OPENCLAW_BASH_JOB_TTL_MS`: TTL للجلسات المنتهية (مللي ثانية، محدودة بين 1m–3h)
- `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`: عتبة خمول المخرجات قبل تعليم الجلسات الخلفية القابلة للكتابة بأنها غالبًا تنتظر إدخالًا (الافتراضي 15000 مللي ثانية)

الإعداد (المفضّل):

- `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`: إرسال رموز مفاتيح صريحة أو بايتات إلى جلسة مدعومة بـ TTY
- `submit`: إرسال Enter / carriage return إلى جلسة مدعومة بـ TTY
- `paste`: إرسال نص حرفي، مع إمكانية تغليفه بوضع اللصق ذي الأقواس
- `kill`: إنهاء جلسة خلفية
- `clear`: إزالة جلسة منتهية من الذاكرة
- `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 قابلًا للكتابة وكانت خاملة لمدة أطول من
  عتبة انتظار الإدخال.
- يستخدم `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": "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" }
```

إرسال مفاتيح TTY:

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