عمليات الملفات الآمنة

يستخدم OpenClaw مكتبة @openclaw/fs-safe لعمليات الملفات المحلية الحساسة أمنيًا: عمليات القراءة والكتابة المقيّدة بالجذر، والاستبدال الذري، واستخراج الأرشيفات، ومساحات العمل المؤقتة، وحالة JSON، والتعامل مع ملفات الأسرار.

وهي آلية حماية على مستوى المكتبة لشيفرة OpenClaw الموثوقة التي تتلقى أسماء مسارات غير موثوقة، وليست بيئة عزل. تظل أذونات نظام ملفات المضيف، ومستخدمو نظام التشغيل، والحاويات، وسياسة الوكيل/الأداة هي التي تحدد النطاق الفعلي للتأثير.

الإعداد الافتراضي: بلا أداة Python مساعدة

يضبط OpenClaw أداة Python المساعدة الخاصة بـ fs-safe على أنظمة POSIX على وضع الإيقاف افتراضيًا:

• ينبغي ألا يشغّل Gateway عملية Python جانبية دائمة ما لم يفعّلها المشغّل صراحةً؛
• لا تحتاج معظم عمليات التثبيت إلى التحصين الإضافي لعمليات تعديل الأدلة الأصلية؛
• يؤدي تعطيل Python إلى إبقاء سلوك وقت التشغيل متوقعًا عبر بيئات سطح المكتب وDocker وCI والتطبيقات المضمّنة.

لا يغيّر OpenClaw سوى الإعداد الافتراضي. ويسود دائمًا أي إعداد صريح:

# سلوك OpenClaw الافتراضي: بدائل fs-safe المعتمدة على Node فقط.OPENCLAW_FS_SAFE_PYTHON_MODE=off # تفعيل الأداة المساعدة عند توفرها، مع الرجوع إلى البديل عند عدم توفرها.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # التوقف الآمن إذا تعذر تشغيل الأداة المساعدة.OPENCLAW_FS_SAFE_PYTHON_MODE=require # مسار صريح اختياري للمفسّر.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

تعمل أيضًا أسماء متغيرات البيئة العامة الخاصة بـ fs-safe: FS_SAFE_PYTHON_MODE وFS_SAFE_PYTHON.

استخدم require (وليس auto) عندما تكون الأداة المساعدة جزءًا من وضعك الأمني؛ إذ يرجع auto بصمت إلى السلوك المعتمد على Node فقط إذا تعذر تشغيل الأداة المساعدة.

ما يظل محميًا دون Python

عند إيقاف الأداة المساعدة، يظل OpenClaw مستفيدًا من آليات الحماية المعتمدة على Node فقط في fs-safe:

• يرفض محاولات الإفلات من المسار النسبي (..)، والمسارات المطلقة، وفواصل المسارات عندما لا يُسمح إلا بالأسماء المجرّدة؛
• ينفّذ العمليات عبر مقبض جذر موثوق بدلًا من فحوصات مخصّصة مثل path.resolve(...).startsWith(...)؛
• يرفض أنماط الروابط الرمزية والروابط الصلبة في واجهات API التي تتطلب هذه السياسة؛
• يفتح الملفات مع إجراء فحوصات للهوية عندما تعيد واجهة API محتويات الملفات أو تستهلكها؛
• يكتب ملفات الحالة/الإعداد عبر ملف مؤقت مجاور ثم إعادة تسمية ذرية؛
• يفرض حدودًا للبايتات على عمليات القراءة واستخراج الأرشيفات؛
• يطبّق أوضاع ملفات خاصة على الأسرار وملفات الحالة عندما تتطلب واجهة API ذلك.

يغطي هذا نموذج التهديد المعتاد في OpenClaw: شيفرة Gateway موثوقة تتعامل مع مدخلات مسارات غير موثوقة واردة من النموذج أو Plugin أو القناة، ضمن حدود مشغّل موثوق واحد.

ما الذي يضيفه Python

على أنظمة POSIX، تُبقي الأداة المساعدة الاختيارية عملية Python دائمة واحدة، وتستخدم عمليات نظام ملفات نسبية إلى واصف ملف لتعديلات الأدلة الأصلية: إعادة التسمية، والإزالة، وإنشاء الأدلة، وجلب البيانات الوصفية/سرد المحتويات، وبعض مسارات الكتابة.

يضيّق ذلك نوافذ حالات التسابق للعمليات التي تعمل بالمعرّف نفسه للمستخدم، حيث قد تستبدل عملية أخرى دليلًا أصليًا بين التحقق والتعديل — وهو دفاع متعدد الطبقات على المضيفات التي يمكن فيها لعمليات محلية غير موثوقة تعديل الأدلة نفسها التي يعمل فيها OpenClaw.

إذا كان نشرك عرضة لهذا الخطر وكان وجود Python مضمونًا، فاضبط:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

إرشادات Plugin والنواة

• ينبغي أن يمر وصول Plugin إلى الملفات عبر أدوات openclaw/plugin-sdk/* المساعدة، لا عبر fs مباشرةً، عندما يأتي المسار من رسالة أو مخرجات نموذج أو إعداد أو مدخل Plugin.
• ينبغي لشيفرة النواة استخدام أغلفة fs-safe الموجودة ضمن src/infra/* حتى تُطبّق سياسة عملية OpenClaw باتساق.
• ينبغي أن يستخدم استخراج الأرشيفات أدوات أرشيف fs-safe المساعدة مع حدود صريحة للحجم، وعدد الإدخالات، والروابط، والوجهة.
• ينبغي أن تستخدم الأسرار أدوات OpenClaw المساعدة للأسرار أو أدوات fs-safe المساعدة للأسرار/الحالة الخاصة؛ لا تنشئ يدويًا فحوصات الأوضاع حول fs.writeFile.
• للعزل عن المستخدمين المحليين العدائيين، لا تعتمد على fs-safe وحده. شغّل بوابات منفصلة تحت مستخدمين أو مضيفات منفصلة لنظام التشغيل، أو استخدم العزل.

ذات صلة: الأمان، العزل، موافقات التنفيذ، الأسرار.