> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# أداة التنفيذ في الخلفية والعمليات

يشغّل 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

إرسال stdin:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

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

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

لصق نص حرفي:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

## ذات صلة

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