الانتقال إلى المحتوى الرئيسي

​
أداة Exec

شغّل أوامر shell في مساحة العمل. تدعم التنفيذ في المقدمة + الخلفية عبر process. إذا كان process غير مسموح، فإن exec يعمل بشكل متزامن ويتجاهل yieldMs/background. نطاق جلسات الخلفية يكون لكل وكيل؛ ولا يرى process إلا الجلسات الخاصة بالوكيل نفسه.

​
المعلمات

  • command (مطلوب)
  • workdir (الافتراضي هو cwd)
  • env (تجاوزات مفتاح/قيمة)
  • yieldMs (الافتراضي 10000): التحويل التلقائي إلى الخلفية بعد تأخير
  • background (قيمة منطقية): التشغيل في الخلفية فورًا
  • timeout (بالثواني، الافتراضي 1800): الإنهاء عند انتهاء المهلة
  • pty (قيمة منطقية): التشغيل في pseudo-terminal عندما يكون متاحًا (CLI التي تعمل فقط مع TTY، ووكلاء البرمجة، وواجهات الطرفية)
  • host (auto | sandbox | gateway | node): مكان التنفيذ
  • security (deny | allowlist | full): وضع الفرض لـ gateway/node
  • ask (off | on-miss | always): مطالبات الموافقة لـ gateway/node
  • node (سلسلة نصية): معرّف/اسم العقدة عند host=node
  • elevated (قيمة منطقية): طلب الوضع المرتفع (الخروج من الصندوق المعزول إلى مسار المضيف المضبوط)؛ لا يتم فرض security=full إلا عندما يُحل elevated إلى full
ملاحظات:
  • القيمة الافتراضية لـ host هي auto: الصندوق المعزول عندما يكون وقت تشغيل الصندوق المعزول نشطًا للجلسة، وإلا gateway.
  • auto هو إستراتيجية التوجيه الافتراضية، وليس بدلًا عامًا. يُسمح لكل استدعاء على حدة بـ host=node انطلاقًا من auto؛ ولا يُسمح لكل استدعاء على حدة بـ host=gateway إلا عندما لا يكون وقت تشغيل الصندوق المعزول نشطًا.
  • من دون أي إعدادات إضافية، يظل host=auto “يعمل ببساطة”: إذا لم يوجد صندوق معزول فإنه يُحل إلى gateway؛ وإذا كان هناك صندوق معزول نشط فإنه يبقى داخله.
  • يقوم elevated بالخروج من الصندوق المعزول إلى مسار المضيف المضبوط: gateway افتراضيًا، أو node عندما تكون tools.exec.host=node (أو يكون الافتراضي للجلسة هو host=node). ولا يكون متاحًا إلا عندما يكون الوصول المرتفع مفعّلًا للجلسة/المزوّد الحالي.
  • تتحكم ~/.openclaw/exec-approvals.json في موافقات gateway/node.
  • يتطلب node عقدة مقترنة (تطبيق مصاحب أو مضيف عقدة headless).
  • إذا كانت هناك عدة عقد متاحة، فاضبط exec.node أو tools.exec.node لاختيار واحدة منها.
  • exec host=node هو مسار تنفيذ shell الوحيد للعقد؛ وقد أُزيل المغلف القديم nodes.run.
  • على المضيفات غير Windows، تستخدم exec القيمة SHELL عند تعيينها؛ وإذا كانت SHELL هي fish، فإنها تفضّل bash (أو sh) من PATH لتجنب السكربتات غير المتوافقة مع fish، ثم تعود إلى SHELL إذا لم يوجد أي منهما.
  • على مضيفات Windows، تفضّل exec اكتشاف PowerShell 7 (pwsh) ‏(Program Files، ثم ProgramW6432، ثم PATH)، ثم تعود إلى Windows PowerShell 5.1.
  • يرفض التنفيذ على المضيف (gateway/node) القيم env.PATH وتجاوزات المحمّل (LD_*/DYLD_*) لمنع اختطاف الملفات التنفيذية أو حقن الشيفرة.
  • يضبط OpenClaw القيمة OPENCLAW_SHELL=exec في بيئة الأمر المُشغَّل (بما في ذلك تنفيذ PTY والتنفيذ داخل الصندوق المعزول) حتى تتمكن قواعد shell/profile من اكتشاف سياق أداة exec.
  • مهم: الصندوق المعزول معطل افتراضيًا. إذا كان الصندوق المعزول معطلًا، فإن host=auto الضمني يُحل إلى gateway. أما host=sandbox الصريح فلا يزال يفشل بشكل مغلق بدلًا من التشغيل بصمت على مضيف gateway. فعّل الصندوق المعزول أو استخدم host=gateway مع الموافقات.
  • لا تفحص تحققات ما قبل تشغيل السكربتات (للأخطاء الشائعة في صياغة shell الخاصة بـ Python/Node) إلا الملفات الموجودة داخل حدود workdir الفعّالة. وإذا كان مسار السكربت يُحل خارج workdir، فيتم تخطي الفحص المسبق لذلك الملف.
  • بالنسبة إلى الأعمال طويلة التشغيل التي تبدأ الآن، ابدأها مرة واحدة واعتمد على الاستيقاظ التلقائي عند الاكتمال عندما يكون مفعّلًا ويُصدر الأمر مخرجات أو يفشل. استخدم process للسجلات أو الحالة أو الإدخال أو التدخل؛ ولا تحاكِ الجدولة بحلقات sleep أو حلقات timeout أو الاستقصاء المتكرر.
  • بالنسبة إلى الأعمال التي يجب أن تحدث لاحقًا أو وفق جدول زمني، استخدم cron بدلًا من أنماط sleep/delay في exec.

​
الإعدادات

  • tools.exec.notifyOnExit (الافتراضي: true): عند تفعيله، تضع جلسات exec التي تعمل في الخلفية حدث نظام في الطابور وتطلب نبضة عند الخروج.
  • tools.exec.approvalRunningNoticeMs (الافتراضي: 10000): يصدر إشعارًا واحدًا “قيد التشغيل” عندما يستمر exec الخاضع للموافقة أكثر من هذه المدة (تعطيل عند 0).
  • tools.exec.host (الافتراضي: auto؛ ويُحل إلى sandbox عندما يكون وقت تشغيل الصندوق المعزول نشطًا، وإلا إلى gateway)
  • tools.exec.security (الافتراضي: deny للصندوق المعزول، وfull لـ gateway + node عند عدم التعيين)
  • tools.exec.ask (الافتراضي: off)
  • تنفيذ المضيف من دون موافقة هو الافتراضي لـ gateway + node. إذا كنت تريد سلوك الموافقات/قائمة السماح، فشدّد كلًا من tools.exec.* وملف سياسة المضيف ~/.openclaw/exec-approvals.json؛ راجع موافقات Exec.
  • يأتي وضع YOLO من إعدادات سياسة المضيف الافتراضية (security=full، ask=off)، وليس من host=auto. إذا كنت تريد فرض التوجيه إلى gateway أو node، فاضبط tools.exec.host أو استخدم /exec host=....
  • tools.exec.node (الافتراضي: غير معيّن)
  • tools.exec.strictInlineEval (الافتراضي: false): عند تفعيله، تتطلب دائمًا صيغ eval المضمنة للمفسرات مثل python -c وnode -e وruby -e وperl -e وphp -r وlua -e وosascript -e موافقة صريحة. لا يزال بإمكان allow-always حفظ الثقة في استدعاءات المفسرات/السكربتات غير الضارة، لكن صيغ inline-eval ستظل تطلب الموافقة في كل مرة.
  • tools.exec.pathPrepend: قائمة بالأدلة التي تسبق PATH في تشغيلات exec (gateway + sandbox فقط).
  • tools.exec.safeBins: ملفات تنفيذية آمنة تعمل فقط مع stdin ويمكنها العمل من دون إدخالات صريحة في قائمة السماح. لتفاصيل السلوك، راجع الملفات التنفيذية الآمنة.
  • tools.exec.safeBinTrustedDirs: أدلة إضافية صريحة موثوقة لفحوصات مسار الملفات التنفيذية في safeBins. لا تُعتبر إدخالات PATH موثوقة تلقائيًا أبدًا. القيم الافتراضية المضمنة هي /bin و/usr/bin.
  • tools.exec.safeBinProfiles: سياسة argv مخصصة اختيارية لكل ملف تنفيذي آمن (minPositional وmaxPositional وallowedValueFlags وdeniedFlags).
مثال: 
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​
التعامل مع PATH

  • host=gateway: يدمج PATH الخاص بـ login-shell في بيئة exec. ويتم رفض تجاوزات env.PATH في تنفيذ المضيف. ومع ذلك، يظل daemon نفسه يعمل بحد أدنى من PATH:
    • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: يشغّل sh -lc (login shell) داخل الحاوية، لذلك قد يعيد /etc/profile تعيين PATH. يسبق OpenClaw القيمة env.PATH بعد جلب profile عبر متغير بيئة داخلي (من دون إدراج shell)؛ وينطبق tools.exec.pathPrepend هنا أيضًا.
  • host=node: لا تُرسل إلى العقدة إلا تجاوزات البيئة غير المحظورة التي تمررها. وتُرفض تجاوزات env.PATH في تنفيذ المضيف ويتم تجاهلها من مضيفات العقد. وإذا كنت تحتاج إلى إدخالات PATH إضافية على عقدة، فاضبط بيئة خدمة مضيف العقدة (systemd/launchd) أو ثبّت الأدوات في المواقع القياسية.
ربط العقدة لكل وكيل (استخدم فهرس قائمة الوكلاء في الإعدادات): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
واجهة التحكم: تتضمن علامة تبويب Nodes لوحة صغيرة باسم “Exec node binding” للإعدادات نفسها.

​
تجاوزات الجلسة (/exec)

استخدم /exec لتعيين القيم الافتراضية لكل جلسة لكل من host وsecurity وask وnode. أرسل /exec بدون وسائط لعرض القيم الحالية. مثال: 
/exec host=auto security=allowlist ask=on-miss node=mac-1

​
نموذج التفويض

لا يتم قبول /exec إلا من المرسلين المصرّح لهم (قوائم السماح/الإقران الخاصة بالقنوات بالإضافة إلى commands.useAccessGroups). وهو يحدّث حالة الجلسة فقط ولا يكتب إلى الإعدادات. لتعطيل exec بشكل صارم، ارفضه عبر سياسة الأدوات (tools.deny: ["exec"] أو لكل وكيل). تظل موافقات المضيف مطبقة ما لم تضبط صراحةً security=full وask=off.

​
موافقات Exec (التطبيق المصاحب / مضيف العقدة)

يمكن للوكلاء داخل الصندوق المعزول أن يتطلبوا موافقة لكل طلب قبل تشغيل exec على مضيف gateway أو node. راجع موافقات Exec للاطلاع على السياسة وقائمة السماح وتدفق واجهة المستخدم. عندما تكون الموافقات مطلوبة، تعيد أداة exec فورًا النتيجة status: "approval-pending" ومعرّف موافقة. وبمجرد الموافقة (أو الرفض / انتهاء المهلة)، تصدر Gateway أحداث نظام (Exec finished / Exec denied). وإذا ظل الأمر قيد التشغيل بعد tools.exec.approvalRunningNoticeMs، فسيصدر إشعار واحد Exec running. على القنوات التي تدعم بطاقات/أزرار الموافقة الأصلية، يجب أن يعتمد الوكيل على واجهة المستخدم الأصلية أولًا وألا يضمّن أمر /approve يدويًا إلا عندما توضح نتيجة الأداة صراحةً أن الموافقات عبر الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد.

​
قائمة السماح + الملفات التنفيذية الآمنة

يطابق فرض قائمة السماح اليدوية مسارات الملفات التنفيذية المحلولة فقط (من دون مطابقة الاسم الأساسي). عندما تكون security=allowlist، لا يُسمح تلقائيًا بأوامر shell إلا إذا كان كل جزء من pipeline مدرجًا في قائمة السماح أو ملفًا تنفيذيًا آمنًا. وتُرفض السلاسل (;, &&, ||) وعمليات إعادة التوجيه في وضع قائمة السماح ما لم يستوفِ كل جزء من المستوى الأعلى قائمة السماح (بما في ذلك الملفات التنفيذية الآمنة). ولا تزال عمليات إعادة التوجيه غير مدعومة. ولا تتجاوز الثقة الدائمة allow-always هذه القاعدة: إذ يظل الأمر المتسلسل يتطلب أن يطابق كل جزء من المستوى الأعلى القاعدة. يمثل autoAllowSkills مسار تسهيل منفصلًا في موافقات exec. وهو ليس نفسه إدخالات قائمة السماح اليدوية للمسارات. وللحصول على ثقة صارمة وصريحة، أبقِ autoAllowSkills معطّلًا. استخدم عنصري التحكم للوظيفتين المختلفتين:
  • tools.exec.safeBins: مرشحات تدفق صغيرة تعمل فقط مع stdin.
  • tools.exec.safeBinTrustedDirs: أدلة إضافية صريحة موثوقة لمسارات الملفات التنفيذية الآمنة.
  • tools.exec.safeBinProfiles: سياسة argv صريحة للملفات التنفيذية الآمنة المخصصة.
  • قائمة السماح: ثقة صريحة لمسارات الملفات التنفيذية.
لا تتعامل مع safeBins على أنها قائمة سماح عامة، ولا تضف ملفات تنفيذية للمفسرات/أوقات التشغيل (مثل python3 أو node أو ruby أو bash). وإذا كنت بحاجة إلى هذه الملفات، فاستخدم إدخالات صريحة في قائمة السماح وأبقِ مطالبات الموافقة مفعلة. يحذّر openclaw security audit عندما تفتقد إدخالات safeBins الخاصة بالمفسرات/أوقات التشغيل إلى ملفات تعريف صريحة، ويمكن لـ openclaw doctor --fix إنشاء إدخالات safeBinProfiles المخصصة المفقودة. كما يحذّر openclaw security audit وopenclaw doctor أيضًا عندما تضيف صراحةً ملفات تنفيذية ذات سلوك واسع مثل jq مرة أخرى إلى safeBins. إذا أضفت المفسرات صراحةً إلى قائمة السماح، ففعّل tools.exec.strictInlineEval حتى تظل صيغ تقييم الشيفرة المضمنة تتطلب موافقة جديدة. للاطلاع على تفاصيل السياسة الكاملة والأمثلة، راجع موافقات Exec والملفات التنفيذية الآمنة مقابل قائمة السماح.

​
أمثلة

التنفيذ في المقدمة: 
{ "tool": "exec", "command": "ls -la" }
الخلفية + الاستقصاء: 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
الاستقصاء مخصص لمعرفة الحالة عند الطلب، وليس لحلقات الانتظار. إذا كان الاستيقاظ التلقائي عند الاكتمال مفعّلًا، فيمكن للأمر أن يوقظ الجلسة عندما يُصدر مخرجات أو يفشل. إرسال مفاتيح (بأسلوب tmux): 
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
إرسال (CR فقط): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
لصق (محاط افتراضيًا): 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch

يمثل apply_patch أداة فرعية من exec لإجراء تعديلات منظمة على عدة ملفات. وهو مفعّل افتراضيًا لنماذج OpenAI وOpenAI Codex. استخدم الإعدادات فقط عندما تريد تعطيله أو قصره على نماذج محددة: 
{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.4"] },
    },
  },
}
ملاحظات:
  • متاح فقط لنماذج OpenAI/OpenAI Codex.
  • تظل سياسة الأدوات مطبقة؛ حيث إن allow: ["write"] تسمح ضمنيًا بـ apply_patch.
  • توجد الإعدادات ضمن tools.exec.applyPatch.
  • القيمة الافتراضية لـ tools.exec.applyPatch.enabled هي true؛ اضبطها على false لتعطيل الأداة لنماذج OpenAI.
  • القيمة الافتراضية لـ tools.exec.applyPatch.workspaceOnly هي true (محصور داخل مساحة العمل). اضبطها على false فقط إذا كنت تقصد عمدًا أن يقوم apply_patch بالكتابة/الحذف خارج دليل مساحة العمل.

​
ذو صلة