عملیات امن فایل‌ها

OpenClaw برای عملیات حساس امنیتیِ فایل‌های محلی از @openclaw/fs-safe استفاده می‌کند: خواندن/نوشتن محدودشده به ریشه، جایگزینی اتمی، استخراج بایگانی، فضاهای کاری موقت، وضعیت JSON و مدیریت فایل‌های محرمانه.

این یک محافظ در سطح کتابخانه برای کد مورداعتماد OpenClaw است که نام مسیرهای نامطمئن را دریافت می‌کند، نه یک محیط ایزوله. مجوزهای سامانه فایل میزبان، کاربران سیستم‌عامل، کانتینرها و خط‌مشی عامل/ابزار همچنان دامنه واقعی آسیب را تعیین می‌کنند.

پیش‌فرض: بدون ابزار کمکی Python

OpenClaw ابزار کمکی POSIX مبتنی بر Python در fs-safe را به‌طور پیش‌فرض خاموش می‌کند:

• 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، هنگامی که مسیر از پیام، خروجی مدل، پیکربندی یا ورودی Plugin می‌آید، باید به‌جای fs خام از ابزارهای کمکی openclaw/plugin-sdk/* عبور کند.
• کد هسته باید از پوشش‌دهنده‌های fs-safe زیر src/infra/* استفاده کند تا خط‌مشی فرایند OpenClaw به‌طور یکسان اعمال شود.
• استخراج بایگانی باید از ابزارهای کمکی بایگانیِ fs-safe با محدودیت‌های صریح برای اندازه، تعداد ورودی‌ها، پیوندها و مقصد استفاده کند.
• داده‌های محرمانه باید از ابزارهای کمکی اسرار OpenClaw یا ابزارهای کمکی داده‌های محرمانه/وضعیت خصوصی fs-safe استفاده کنند؛ بررسی حالت دسترسی پیرامون fs.writeFile را به‌صورت دستی پیاده‌سازی نکنید.
• برای جداسازی کاربران محلی متخاصم، تنها به fs-safe اتکا نکنید. Gatewayهای جداگانه را تحت کاربران یا میزبان‌های جداگانه سیستم‌عامل اجرا کنید، یا از محیط ایزوله استفاده کنید.

مطالب مرتبط: امنیت، محیط ایزوله، تأییدهای اجرا، داده‌های محرمانه.