الانتقال إلى المحتوى الرئيسي
يشغّل 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 بدلًا من ذلك.

​
أمثلة

شغّل مهمة طويلة واستطلع لاحقًا: 
{ "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" }
أرسل مفاتيح PTY: 
{ "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" }

​
ذو صلة