---
read_when:
    - إضافة أو تعديل سلوك التنفيذ في الخلفية
    - تصحيح أخطاء مهام exec طويلة التشغيل
summary: تنفيذ exec في الخلفية وإدارة العمليات
title: أداة التنفيذ في الخلفية والعمليات
x-i18n:
    generated_at: "2026-05-10T19:37:06Z"
    model: gpt-5.5
    provider: openai
    source_hash: 95fb986cf0c07ef3d054189ce2838b441ae24f07703f8edc1ddb8aca3a58b300
    source_path: gateway/background-process.md
    workflow: 16
---

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

## أداة exec

المعاملات الرئيسية:

- `command` (مطلوب)
- `yieldMs` (الافتراضي 10000): النقل التلقائي إلى الخلفية بعد هذا التأخير
- `background` (bool): التشغيل في الخلفية فورًا
- `timeout` (بالثواني، الافتراضي `tools.exec.timeoutSec`): يقتل العملية بعد انتهاء هذه المهلة؛ اضبط `timeout: 0` فقط لتعطيل مهلة عملية exec لذلك الاستدعاء
- `elevated` (bool): التشغيل خارج صندوق العزل إذا كان الوضع المرتفع مفعّلًا/مسموحًا (`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 ويحافظ على اتساق سلوك الإيقاف عبر المنصات.

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

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

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

- `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` للحالة، أو السجلات، أو تأكيد النجاح الهادئ، أو
  تأكيد الإكمال عندما لا يكون تنبيه الإكمال التلقائي متاحًا.
- استخدم `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" }
```

أرسل مفاتيح 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)