OpenShell

OpenShell هي واجهة خلفية مُدارة لبيئة معزولة: فبدلًا من تشغيل حاويات Docker محليًا، يفوّض OpenClaw دورة حياة البيئة المعزولة إلى CLI ‏openshell، الذي يوفّر بيئات بعيدة وينفّذ الأوامر عبر SSH.

يعيد Plugin استخدام آلية نقل SSH نفسها وجسر نظام الملفات البعيد نفسيهما كما في واجهة SSH الخلفية العامة، ويضيف دورة حياة OpenShell ‏(sandbox create/get/delete/ssh-config) بالإضافة إلى وضع مزامنة اختياري لمساحة العمل باسم mirror.

المتطلبات الأساسية

• تثبيت Plugin ‏OpenShell ‏(openclaw plugins install @openclaw/openshell-sandbox)
• توفر CLI ‏openshell ضمن PATH (أو تحديد مسار مخصّص عبر plugins.entries.openshell.config.command)
• حساب OpenShell لديه صلاحية الوصول إلى البيئات المعزولة
• تشغيل OpenClaw Gateway على المضيف

البدء السريع

openclaw plugins install @openclaw/openshell-sandbox

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

أعد تشغيل Gateway. في دورة الوكيل التالية، ينشئ OpenClaw بيئة OpenShell معزولة ويوجّه تنفيذ الأدوات عبرها. تحقّق باستخدام:

openclaw sandbox listopenclaw sandbox explain

أوضاع مساحة العمل

هذا هو أهم قرار عند استخدام OpenShell.

mirror (الافتراضي)

يحافظ plugins.entries.openshell.config.mode: "mirror" على أن تكون مساحة العمل المحلية هي المرجع الأساسي:

• قبل exec، يزامن OpenClaw مساحة العمل المحلية إلى البيئة المعزولة.
• بعد exec، يزامن OpenClaw مساحة العمل البعيدة إلى البيئة المحلية.
• تمر أدوات الملفات عبر جسر البيئة المعزولة، لكن البيئة المحلية تظل مصدر الحقيقة بين الدورات.

هذا الوضع هو الأنسب لسير عمل التطوير: تظهر التعديلات المحلية التي تُجرى خارج OpenClaw عند تنفيذ exec التالي، وتتصرف البيئة المعزولة بطريقة مشابهة لواجهة Docker الخلفية.

المقابل: تكلفة الرفع والتنزيل عند كل دورة تنفيذ.

remote

يجعل mode: "remote" مساحة عمل OpenShell هي المرجع الأساسي:

• عند إنشاء البيئة المعزولة لأول مرة، ينسخ OpenClaw مساحة العمل المحلية إلى المساحة البعيدة مرة واحدة.
• بعد ذلك، تعمل exec وread وwrite وedit وapply_patch مباشرةً على مساحة العمل البعيدة. ولا يزامن OpenClaw التغييرات البعيدة إلى البيئة المحلية.
• تظل قراءة الوسائط في وقت إنشاء الموجّه متاحة (تقرأ أدوات الملفات والوسائط عبر جسر البيئة المعزولة).

هذا الوضع هو الأنسب للوكلاء طويلي التشغيل وبيئات CI: إذ يخفّض الحمل الإضافي لكل دورة، ولا يمكن للتعديلات المحلية على المضيف أن تستبدل الحالة البعيدة بصمت.

اختيار الوضع

مرجع الإعدادات

توجد جميع إعدادات OpenShell ضمن plugins.entries.openshell.config:

يجب أن يكون remoteWorkspaceDir وremoteAgentWorkspaceDir مسارين مطلقين وأن يبقيا ضمن الجذرين المُدارين /sandbox أو /agent؛ وتُرفض المسارات المطلقة الأخرى.

توجد إعدادات مستوى البيئة المعزولة (mode وscope وworkspaceAccess) ضمن agents.defaults.sandbox كما هو الحال مع أي واجهة خلفية. راجع العزل للاطلاع على المصفوفة الكاملة.

أمثلة

إعداد بعيد بالحد الأدنى

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

وضع النسخ المتطابق مع GPU

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "agent",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "mirror",          gpu: true,          providers: ["openai"],          timeoutSeconds: 180,        },      },    },  },}

OpenShell لكل وكيل مع Gateway مخصّص

{  agents: {    defaults: {      sandbox: { mode: "off" },    },    list: [      {        id: "researcher",        sandbox: {          mode: "all",          backend: "openshell",          scope: "agent",          workspaceAccess: "rw",        },      },    ],  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",          gateway: "lab",          gatewayEndpoint: "https://lab.example",          policy: "strict",        },      },    },  },}

إدارة دورة الحياة

# List all sandbox runtimes (Docker + OpenShell)openclaw sandbox list # Inspect effective policyopenclaw sandbox explain # Recreate (deletes remote workspace, re-seeds on next use)openclaw sandbox recreate --all

في وضع remote، تكون إعادة الإنشاء مهمة بصفة خاصة: فهي تحذف مساحة العمل البعيدة الأساسية لذلك النطاق، وينسخ الاستخدام التالي مساحة جديدة من البيئة المحلية. أما في وضع mirror، فتعيد عملية الإنشاء أساسًا ضبط بيئة التنفيذ البعيدة لأن البيئة المحلية تظل المرجع الأساسي.

أعد الإنشاء بعد تغيير أي مما يلي:

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

تعزيز الأمان

يثبّت جسر نظام الملفات في وضع النسخ المتطابق جذر مساحة العمل المحلية، ويعيد التحقق من المسارات الأساسية (عبر realpath) قبل كل عملية قراءة وكتابة وإنشاء دليل وإزالة وإعادة تسمية، مع رفض الروابط الرمزية الواقعة في منتصف المسار. ولا يمكن لتبديل رابط رمزي أو إعادة تركيب مساحة العمل إعادة توجيه الوصول إلى الملفات خارج الشجرة المنسوخة.

القيود الحالية

• متصفح البيئة المعزولة غير مدعوم في واجهة OpenShell الخلفية.
• لا ينطبق sandbox.docker.binds على OpenShell؛ ويفشل إنشاء البيئة المعزولة إذا جرى إعداد عمليات ربط.
• لا تنطبق خيارات وقت التشغيل الخاصة بـ Docker ضمن sandbox.docker.* (باستثناء env) إلا على واجهة Docker الخلفية.

آلية العمل

1. يشغّل OpenClaw الأمر sandbox get لاسم البيئة المعزولة (مع أي من --gateway أو --gateway-endpoint جرى إعداده)؛ وإذا فشل ذلك، ينشئ بيئة باستخدام sandbox create، مع تمرير --name و--from و--policy عند تعيينها، و--gpu عند تمكينه، و--auto-providers أو --no-auto-providers، وعلامة --provider واحدة لكل مزوّد جرى إعداده.
2. يشغّل OpenClaw الأمر sandbox ssh-config لاسم البيئة المعزولة لجلب تفاصيل اتصال SSH.
3. يكتب النظام الأساسي إعدادات SSH في ملف مؤقت ويفتح جلسة SSH عبر جسر نظام الملفات البعيد نفسه المستخدم في واجهة SSH الخلفية العامة.
4. في وضع mirror: يزامن البيئة المحلية إلى البعيدة قبل التنفيذ، ثم ينفّذ، ثم يزامنها عكسيًا بعده.
5. في وضع remote: ينسخ مساحة العمل مرة واحدة عند الإنشاء، ثم يعمل مباشرةً على مساحة العمل البعيدة.

موضوعات ذات صلة

• العزل - الأوضاع والنطاقات ومقارنة الواجهات الخلفية
• البيئة المعزولة مقابل سياسة الأدوات مقابل الصلاحيات المرتفعة - تصحيح أخطاء الأدوات المحظورة
• البيئة المعزولة والأدوات متعددة الوكلاء - تجاوزات الإعداد لكل وكيل
• CLI للبيئة المعزولة - أوامر openclaw sandbox