أداة التنفيذ

شغّل أوامر الصدفة في مساحة العمل. exec هو سطح صدفة مُغيِّر: يمكن للأوامر إنشاء الملفات أو تحريرها أو حذفها في أي مكان يسمح به نظام ملفات المضيف أو وضع الحماية المحدد. لا يؤدي تعطيل أدوات نظام الملفات في OpenClaw مثل write أو edit أو apply_patch إلى جعل exec للقراءة فقط.

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

المعلمات

ملاحظات:

• لا يقبل host إلا auto أو sandbox أو gateway أو node. وهو ليس محددًا لاسم المضيف؛ إذ تُرفض القيم الشبيهة بأسماء المضيفين قبل تشغيل الأمر.
• يُسمح باستخدام host=node لكل استدعاء من auto؛ ولا يُسمح باستخدام host=gateway لكل استدعاء إلا عند عدم نشاط أي وقت تشغيل لوضع الحماية.
• من دون إعدادات إضافية، يظل host=auto «يعمل ببساطة»: عند عدم وجود وضع حماية، يُحل إلى gateway؛ وعند وجود وضع حماية نشط، يبقى داخل وضع الحماية.
• يخرج elevated من وضع الحماية إلى مسار المضيف المضبوط: gateway افتراضيًا، أو node عندما يكون tools.exec.host=node (أو القيمة الافتراضية للجلسة هي host=node). ولا يتوفر إلا عند تمكين الوصول المرتفع للجلسة/المزوّد الحالي.
• يتحكم ملف موافقات المضيف في موافقات gateway/node.
• يتطلب node جهاز Node مقترنًا (تطبيقًا مصاحبًا أو مضيف Node بلا واجهة رسومية). إذا توفرت عدة أجهزة Node، فاضبط exec.node أو tools.exec.node لتحديد أحدها.
• يمثل exec host=node المسار الوحيد لتنفيذ الصدفة على أجهزة Node؛ وقد أزيل الغلاف القديم nodes.run.
• على المضيفين غير العاملين بنظام Windows، يستخدم التنفيذ SHELL عند ضبطه؛ وإذا كان SHELL هو fish، فإنه يفضّل bash (أو sh) من PATH لتجنب تعبيرات bash غير المتوافقة مع fish، ثم يعود إلى SHELL إذا لم يكن أي منهما موجودًا.
• على مضيفي Windows، يفضّل التنفيذ اكتشاف PowerShell 7 ‏(pwsh) (Program Files ثم ProgramW6432 ثم PATH)، ثم يعود إلى Windows PowerShell 5.1.
• على مضيفي Gateway غير العاملين بنظام Windows، تستخدم أوامر تنفيذ bash وzsh لقطة بدء تشغيل. يلتقط OpenClaw الأسماء المستعارة/الدوال القابلة للاستيراد ومجموعة صغيرة وآمنة من متغيرات البيئة من ملفات بدء تشغيل الصدفة إلى $OPENCLAW_STATE_DIR/cache/shell-snapshots/، ثم يستورد تلك اللقطة قبل كل أمر تنفيذ. تُستبعد المتغيرات التي تبدو سرية؛ ولا يستخدم تنفيذ وضع الحماية وNode هذه اللقطة. اضبط OPENCLAW_EXEC_SHELL_SNAPSHOT=0 في بيئة عملية Gateway لتعطيل مسار اللقطة هذا.
• يرفض التنفيذ على المضيف (gateway/node) ‏env.PATH وتجاوزات المحمّل (LD_*/DYLD_*) لمنع اختطاف الملفات الثنائية أو حقن التعليمات البرمجية.
• يضبط OpenClaw ‏OPENCLAW_SHELL=exec في بيئة الأمر المنشأ (بما في ذلك تنفيذ PTY ووضع الحماية) بحيث يمكن لقواعد الصدفة/الملف الشخصي اكتشاف سياق أداة التنفيذ.
• بالنسبة إلى عمليات التشغيل الناشئة من القناة، يتيح OpenClaw أيضًا حمولة JSON محدودة لهوية المرسل/المحادثة في OPENCLAW_CHANNEL_CONTEXT عندما توفر القناة تلك المعرّفات.
• لا يمكن لـ exec تشغيل أوامر الصدفة openclaw channels login أو /approve: إذ إن openclaw channels login مسار تفاعلي لمصادقة القناة، ويجب أن يمر /approve عبر معالج أوامر الموافقة لا عبر الصدفة. شغّل تسجيل الدخول إلى القناة في طرفية على مضيف Gateway، أو استخدم أداة وكيل خاصة بتسجيل الدخول إلى القناة عند توفرها (مثل whatsapp_login).
• مهم: وضع الحماية معطّل افتراضيًا. إذا كان وضع الحماية معطلًا، فسيُحل host=auto الضمني إلى gateway. أما host=sandbox الصريح فيظل يفشل بأمان بدلًا من التشغيل بصمت على مضيف Gateway. فعّل وضع الحماية أو استخدم host=gateway مع الموافقات.
• لا تفحص عمليات التحقق المسبق للبرامج النصية (بحثًا عن أخطاء شائعة في صياغة صدفة Python/Node) إلا الملفات الموجودة داخل حدود workdir الفعلية. إذا حُل مسار برنامج نصي إلى خارج workdir، فسيُتخطى التحقق المسبق لذلك الملف. كما يُتخطى التحقق المسبق بالكامل عندما يكون host=gateway وتكون السياسة الفعلية security=full مع ask=off.
• بالنسبة إلى العمل طويل الأمد الذي يبدأ الآن، ابدأه مرة واحدة واعتمد على تنبيه الإكمال التلقائي عندما يكون مفعّلًا ويُصدر الأمر مخرجات أو يفشل. استخدم process للسجلات أو الحالة أو الإدخال أو التدخل؛ ولا تحاكِ الجدولة باستخدام حلقات السكون أو حلقات المهلة أو الاستقصاء المتكرر.
• بالنسبة إلى العمل الذي ينبغي تنفيذه لاحقًا أو وفق جدول زمني، استخدم Cron بدلًا من أنماط السكون/التأخير في exec.

الإعدادات

تنفيذ المضيف من دون موافقة هو الإعداد الافتراضي للـ Gateway والـ Node ‏(security=full، ask=off) — ويأتي ذلك من الإعدادات الافتراضية لسياسة المضيف، لا من host=auto. إذا أُريد سلوك الموافقات/قائمة السماح، فيجب تشديد كل من tools.exec.* وملف موافقات المضيف؛ راجع موافقات التنفيذ. لفرض التوجيه عبر Gateway أو Node بصرف النظر عن حالة صندوق الحماية، اضبط tools.exec.host أو استخدم /exec host=....

مثال:

{  tools: {    exec: {      pathPrepend: ["~/bin", "/opt/oss/bin"],    },  },}

الأوضاع

tools.exec.mode هو خيار السياسة الموحّد. يؤدي ضبطه إلى اشتقاق security/ask، ولا يمكن دمجه مع الضبط الصريح لـ tools.exec.security/tools.exec.ask.

يظل ask/ask=always يطلب من إنسان الموافقة في كل مرة بصرف النظر عن الوضع.

موافقة المراجعة التلقائية أحادية الاستخدام. في Gateway، يزوّد OpenClaw المراجع بمسار الملف التنفيذي الذي جرى حله ويثبّت التنفيذ على ذلك المسار نفسه. أما الأوامر التي لا يمكن اختزالها إلى خطة تنفيذ واحدة قابلة للإنفاذ—مثل مستندات heredoc أو توسعات الصدفة أو اقتباس الأغلفة غير المدعوم—فتعود إلى الموافقة البشرية حتى لو كان النموذج سيسمح بها بخلاف ذلك.

تستخدم موافقات أوامر خادم تطبيق Codex التي لم تُحسم بالفعل بسياسة صريحة لبيئة التشغيل أو بسياسة أصلية مسار الموافقة البشرية. لا يشغّل OpenClaw مراجع التنفيذ المُعَدّ لهذه الطلبات لأن Codex لا يكشف ملفًا تنفيذيًا محلولًا قابلًا للإنفاذ يمكن ربط قرار المراجعة به لضمان مطابقته للأمر الذي يشغّله Codex.

التقييم المضمّن (strictInlineEval)

عندما تكون tools.exec.strictInlineEval هي true، تتطلب صيغ تقييم المفسّر المضمّنة مراجعة أو موافقة صريحة: python -c، وnode -e، وruby -e، وperl -e، وphp -r، وlua -e، وosascript -e، والصيغ المشابهة عبر المفسّرات وناقلات الأوامر الأخرى المدعومة (awk، وfind -exec، وmake، وsed، وxargs، وغيرها). في mode=auto، قد يسمح مسار موافقة التنفيذ العادي للمراجع التلقائي الأصلي بقبول أمر واضح منخفض المخاطر لمرة واحدة؛ لكن استدعاءات system.run المباشرة على مضيف Node تظل تتطلب موافقة صريحة لأنها لا تستطيع تمرير الأمر إلى مسار موافقة بشرية. إذا طلب المراجع الموافقة، يُحال الطلب إلى إنسان. لا يزال بإمكان allow-always حفظ استدعاءات المفسّر/البرنامج النصي الآمنة، لكن صيغ التقييم المضمّن لا تتحول إلى قواعد سماح دائمة.

معالجة PATH

• host=gateway: يدمج PATH الخاص بصدفة تسجيل الدخول في بيئة التنفيذ. تُرفض تجاوزات env.PATH عند التنفيذ على المضيف. وتظل الخدمة الخفية نفسها تعمل بقيمة PATH محدودة:
  • macOS: /opt/homebrew/bin، /usr/local/bin، /usr/bin، /bin
  • Linux: /usr/local/bin، /usr/bin، /bin
  • لمنع إعدادات صدفة المستخدم (مثل ~/.zshenv أو /etc/zshenv) من تجاوز المسارات ذات الأولوية أثناء بدء التشغيل، تُضاف إدخالات tools.exec.pathPrepend بأمان إلى بداية PATH النهائية داخل أمر الصدفة قبل التنفيذ مباشرة.
• host=sandbox: يشغّل sh -lc (صدفة تسجيل الدخول) داخل الحاوية، لذلك قد يعيد /etc/profile ضبط PATH. يضيف OpenClaw القيمة env.PATH في البداية بعد تحميل ملفات التعريف عبر متغير بيئة داخلي (من دون استيفاء الصدفة)؛ وينطبق tools.exec.pathPrepend هنا أيضًا.
• host=node: لا تُرسل إلى Node إلا تجاوزات البيئة غير المحظورة التي تُمرَّر. تُرفض تجاوزات env.PATH عند التنفيذ على المضيف وتتجاهلها مضيفات Node. إذا لزم إضافة إدخالات إلى PATH على Node، فيجب إعداد بيئة خدمة مضيف Node ‏(systemd/launchd) أو تثبيت الأدوات في المواقع القياسية.

ربط Node لكل وكيل (استخدم فهرس الوكيل في القائمة ضمن الإعداد):

openclaw config get agents.listopenclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

واجهة التحكم: تتضمن صفحة الأجهزة لوحة صغيرة بعنوان «ربط Node للتنفيذ» للإعدادات نفسها.

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

استخدم /exec لضبط القيم الافتراضية لكل جلسة لـ host، وsecurity، وask، وnode. أرسل /exec من دون معاملات لعرض القيم الحالية.

مثال:

/exec host=auto security=allowlist ask=on-miss node=mac-1

لا يُعتد بـ /exec إلا للـ مرسلين المصرح لهم (قوائم سماح القنوات/الاقتران بالإضافة إلى commands.useAccessGroups). وهو يحدّث حالة الجلسة فقط ولا يكتب إلى الإعداد. يمكن لمرسلي القنوات الخارجية المصرح لهم ضبط هذه القيم الافتراضية للجلسة. تحتاج عملاء Gateway/webchat الداخلية إلى operator.admin للاحتفاظ بها.

لتعطيل التنفيذ نهائيًا، ارفضه عبر سياسة الأدوات (tools.deny: ["exec"] أو لكل وكيل). تظل موافقات المضيف مطبّقة ما لم تُضبط صراحةً security=full وask=off.

موافقات التنفيذ (التطبيق المصاحب / مضيف Node)

يمكن أن تتطلب الوكلاء العاملون داخل صندوق الحماية موافقة لكل طلب قبل تشغيل exec على Gateway أو مضيف Node. راجع موافقات التنفيذ لمعرفة السياسة وقائمة السماح وتدفق واجهة المستخدم.

عندما تكون الموافقة البشرية مطلوبة، تعيد تدفقات مضيف Node وتدفقات Gateway غير الأصلية فورًا القيمة status: "approval-pending" ومعرّف موافقة. أما تدفقات الدردشة الأصلية وتدفقات Gateway في واجهة الويب فيمكنها بدلًا من ذلك الانتظار ضمنيًا وإعادة النتيجة النهائية للأمر بعد الموافقة. تعني نتيجة approval-pending أن الأمر لم يبدأ، ولذلك لا تظهر تحذيرات الرجوع للتنفيذ الأمامي إلا إذا نُفّذ الأمر الموافق عليه ضمنيًا بالفعل. تُصدر عمليات التشغيل غير المتزامنة الموافق عليها أحداث نظام لتقدم الأمر وإكماله (Exec running / Exec finished)؛ أما الموافقات المرفوضة أو المنتهية مهلتها فهي نهائية ولا توقظ جلسة الوكيل بحدث نظام يفيد الرفض.

في القنوات التي تتضمن بطاقات/أزرار موافقة أصلية، ينبغي للوكيل الاعتماد أولًا على واجهة المستخدم الأصلية تلك، وألا يضمّن أمر /approve يدويًا إلا عندما تنص نتيجة الأداة صراحةً على أن الموافقات عبر الدردشة غير متاحة أو أن الموافقة اليدوية هي المسار الوحيد.

قائمة السماح + الأدوات التنفيذية الآمنة

تطابق آلية فرض قائمة السماح اليدوية أنماط المسارات العامة للمسار المحلول للملف التنفيذي وأنماط أسماء الأوامر المجرّدة. لا تطابق الأسماء المجرّدة إلا الأوامر المستدعاة عبر PATH، لذا يمكن أن يطابق rg‏ /opt/homebrew/bin/rg عندما يكون الأمر هو rg، لكن ليس ./rg أو /tmp/rg.

عندما يكون security=allowlist، لا يُسمح بأوامر الصدفة تلقائيًا إلا إذا كان كل مقطع من خط الأنابيب مدرجًا في قائمة السماح أو أداة تنفيذية آمنة. يُرفض التسلسل (; و&& و||) وإعادات التوجيه في وضع قائمة السماح ما لم يستوفِ كل مقطع من المستوى الأعلى قائمة السماح (بما في ذلك الأدوات التنفيذية الآمنة). تظل إعادات التوجيه غير مدعومة. لا تتجاوز ثقة allow-always الدائمة هذه القاعدة: يظل الأمر المتسلسل يتطلب مطابقة كل مقطع من المستوى الأعلى.

يمثّل autoAllowSkills مسار تسهيل منفصلًا في موافقات التنفيذ، وليس مماثلًا لإدخالات قائمة السماح اليدوية للمسارات. للحصول على ثقة صريحة صارمة، أبقِ 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 (يمكن لـ jq قراءة بيانات البيئة وتحميل شيفرة jq من الوحدات أو ملفات بدء التشغيل، لذا يُفضّل بدلًا من ذلك استخدام إدخالات صريحة في قائمة السماح أو عمليات تشغيل مقيّدة بالموافقة). يُرفض jq بوصفه أداة تنفيذية آمنة حتى عند إدراجه صراحةً. إذا أدرجت المفسرات صراحةً في قائمة السماح، ففعّل tools.exec.strictInlineEval كي تظل نماذج تقييم الشيفرة المضمّنة تتطلب مراجِعًا أو موافقة صريحة.

للاطلاع على تفاصيل السياسة الكاملة والأمثلة، راجع موافقات التنفيذ والأدوات التنفيذية الآمنة مقارنةً بقائمة السماح.

أمثلة

في المقدمة:

{ "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 لإجراء تعديلات منظّمة على ملفات متعددة. وهو مفعّل افتراضيًا ومتاح لأي موفّر نماذج؛ ويمكن لـ allowModels تقييده. استخدم الإعدادات فقط عندما تريد تعطيله أو قصره على نماذج محددة:

{  tools: {    exec: {      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.6-sol"] },    },  },}

ملاحظات:

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

ذو صلة

• موافقات التنفيذ — بوابات الموافقة لأوامر الصدفة
• العزل — تشغيل الأوامر في بيئات معزولة
• عملية الخلفية — أداتا التنفيذ والعمليات طويلة التشغيل
• الأمان — سياسة الأدوات والوصول بصلاحيات مرتفعة