Gateway

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

يشغّل 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" }

ذو صلة

Was this useful?