OpenShell

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

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

# المتطلبات المسبقة

• تثبيت CLI الخاص بـ openshell وإتاحته على PATH (أو تعيين مسار مخصص عبر plugins.entries.openshell.config.command)
• حساب OpenShell لديه صلاحية الوصول إلى صناديق الحماية
• تشغيل OpenClaw Gateway على المضيف

# البدء السريع

1. فعّل Plugin واضبط الواجهة الخلفية لصندوق الحماية:

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

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

3. تحقّق:

openclaw sandbox list
openclaw sandbox explain

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

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

# mirror

استخدم plugins.entries.openshell.config.mode: "mirror" عندما تريد أن تبقى مساحة العمل المحلية هي المصدر المعتمد.

السلوك:

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

الأفضل لـ:

• تحرير الملفات محلياً خارج OpenClaw والرغبة في ظهور تلك التغييرات في صندوق الحماية تلقائياً.
• جعل صندوق حماية OpenShell يتصرف بأقرب قدر ممكن إلى واجهة Docker الخلفية.
• عكس كتابات صندوق الحماية في مساحة عمل المضيف بعد كل دور exec.

المفاضلة: تكلفة مزامنة إضافية قبل كل exec وبعده.

# remote

استخدم plugins.entries.openshell.config.mode: "remote" عندما تريد أن تصبح مساحة عمل OpenShell هي المصدر المعتمد.

السلوك:

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

الأفضل لـ:

• أن يعيش صندوق الحماية أساساً على الجانب البعيد.
• تقليل عبء المزامنة لكل دور.
• عدم رغبتك في أن تستبدل التعديلات المحلية على المضيف حالة صندوق الحماية البعيد بصمت.

# اختيار وضع

	mirror	remote
مساحة العمل المعتمدة	المضيف المحلي	OpenShell البعيد
اتجاه المزامنة	ثنائي الاتجاه (كل exec)	ملء لمرة واحدة
العبء لكل دور	أعلى (رفع + تنزيل)	أقل (عمليات بعيدة مباشرة)
هل تظهر التعديلات المحلية؟	نعم، عند exec التالي	لا، حتى إعادة الإنشاء
الأفضل لـ	سير عمل التطوير	الوكلاء طويلو التشغيل، CI

# مرجع التكوين

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

المفتاح	النوع	الافتراضي	الوصف
mode	"mirror" أو "remote"	"mirror"	وضع مزامنة مساحة العمل
command	string	"openshell"	مسار أو اسم CLI الخاص بـ openshell
from	string	"openclaw"	مصدر صندوق الحماية عند الإنشاء لأول مرة
gateway	string	—	اسم OpenShell gateway (--gateway)
gatewayEndpoint	string	—	عنوان URL لنقطة نهاية OpenShell gateway (--gateway-endpoint)
policy	string	—	معرّف سياسة OpenShell لإنشاء صندوق الحماية
providers	string[]	[]	أسماء المزوّدين المراد إرفاقها عند إنشاء صندوق الحماية
gpu	boolean	false	طلب موارد GPU
autoProviders	boolean	true	تمرير --auto-providers أثناء إنشاء صندوق الحماية
remoteWorkspaceDir	string	"/sandbox"	مساحة العمل الأساسية القابلة للكتابة داخل صندوق الحماية
remoteAgentWorkspaceDir	string	"/agent"	مسار تركيب مساحة عمل الوكيل (للوصول للقراءة فقط)
timeoutSeconds	number	120	مهلة عمليات CLI الخاص بـ openshell

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

# أمثلة

# إعداد بعيد بسيط

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

# وضع Mirror مع 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",
        },
      },
    },
  },
}

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

تُدار صناديق حماية OpenShell عبر CLI صندوق الحماية المعتاد:

# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw 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

openclaw sandbox recreate --all

# تقوية الأمان

يثبّت OpenShell واصف ملف جذر مساحة العمل ويعيد فحص هوية صندوق الحماية قبل كل قراءة، لذلك لا يمكن لتبديلات الروابط الرمزية أو إعادة تركيب مساحة العمل توجيه القراءات خارج مساحة العمل البعيدة المقصودة.

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

• متصفح صندوق الحماية غير مدعوم على واجهة OpenShell الخلفية.
• لا ينطبق sandbox.docker.binds على OpenShell.
• إعدادات وقت التشغيل الخاصة بـ Docker ضمن sandbox.docker.* تنطبق فقط على واجهة Docker الخلفية.

# كيف يعمل

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

# ذات صلة

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