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

يشغّل 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 بدلًا من ذلك.

أمثلة

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

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

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

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

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

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

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

إرسال stdin:

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

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

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

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

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

لصق نص حرفي:

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

ذات صلة

• أداة Exec
• موافقات Exec