التكوين والعمليات

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

تقوم OpenClaw بتشغيل أوامر shell من خلال أداة exec وتحتفظ بالمهام طويلة الأمد في الذاكرة. تدير أداة process جلسات الخلفية تلك.

أداة exec

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

  • command (مطلوب)
  • yieldMs (الافتراضي 10000): التحويل إلى الخلفية تلقائياً بعد هذا التأخير
  • background (منطقي): الانتقال إلى الخلفية فوراً
  • timeout (بالثواني، الافتراضي 1800): إنهاء العملية بعد هذه المهلة الزمنية
  • elevated (منطقي): التشغيل على المضيف إذا كان الوضع المرفوع مفعلاً/مسموحاً
  • هل تحتاج إلى TTY حقيقي؟ عيّن pty: true.
  • workdir, env

السلوك:

  • تعيد عمليات التشغيل في المقدمة المخرجات مباشرة.
  • عند الانتقال إلى الخلفية (صريح أو بسبب المهلة الزمنية)، تعيد الأداة status: "running" + sessionId وذيلاً قصيراً من المخرجات.
  • يتم الاحتفاظ بالمخرجات في الذاكرة حتى يتم استطلاع الجلسة أو مسحها.
  • إذا كانت أداة process غير مسموح بها، تعمل exec بشكل متزامن وتتجاهل yieldMs/background.
  • تتلقى أوامر exec المنشأة OPENCLAW_SHELL=exec لقواعد shell/profile الواعية بالسياق.

جسر العمليات الفرعية

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

  • PI_BASH_YIELD_MS: المهلة الافتراضية (مللي ثانية)
  • PI_BASH_MAX_OUTPUT_CHARS: الحد الأقصى للمخرجات في الذاكرة (حرف)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: الحد الأقصى لـ stdout/stderr المعلق لكل دفق (حرف)
  • PI_BASH_JOB_TTL_MS: مدة صلاحية الجلسات المنتهية (مللي ثانية، محصورة بين 1 دقيقة و3 ساعات)

التكوين (مفضل):

  • tools.exec.backgroundMs (الافتراضي 10000)
  • tools.exec.timeoutSec (الافتراضي 1800)
  • tools.exec.cleanupMs (الافتراضي 1800000)
  • tools.exec.notifyOnExit (الافتراضي true): قم بإدراج حدث نظام + طلب نبضة قلب عندما يخرج exec في الخلفية.
  • tools.exec.notifyOnExitEmptySuccess (الافتراضي false): عندما تكون true، قم أيضاً بإدراج أحداث اكتمال لعمليات التشغيل في الخلفية الناجحة التي لم تنتج أي مخرجات.

أداة process

الإجراءات:

  • list: الجلسات الجارية + المنتهية
  • poll: استنزاف المخرجات الجديدة لجلسة (تقر أيضاً بحالة الخروج)
  • log: قراءة المخرجات المجمعة (تدعم offset + limit)
  • write: إرسال stdin (data، اختياري eof)
  • kill: إنهاء جلسة خلفية
  • clear: إزالة جلسة منتهية من الذاكرة
  • remove: إنهاء إذا كانت جارية، وإلا مسحها إذا كانت منتهية

ملاحظات:

  • فقط الجلسات التي تم تحويلها إلى الخلفية مدرجة/مستمرة في الذاكرة.
  • تضيع الجلسات عند إعادة تشغيل العملية (لا يوجد استمرارية على القرص).
  • يتم حفظ سجلات الجلسات في سجل المحادثة فقط إذا قمت بتشغيل process poll/log وتم تسجيل نتيجة الأداة.
  • process محددة النطاق لكل وكيل؛ فهي ترى فقط الجلسات التي بدأها ذلك الوكيل.
  • تتضمن process list name مشتقاً (فعل الأمر + الهدف) للمسح السريع.
  • تستخدم process log offset/limit قائم على الأسطر.
  • عند حذف كل من offset و limit، تعيد آخر 200 سطر وتتضمن تلميحاً للترقيم.
  • عند توفير offset وحذف limit، تعيد من offset إلى النهاية (غير محدودة بـ 200).

أمثلة

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

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

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

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

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

إرسال stdin:

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

قفل البوابةبوابات متعددة