​

OpenShell

​

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

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

​

البدء السريع

1. فعّل plugin واضبط واجهة sandbox الخلفية:

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

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

openclaw sandbox list
openclaw sandbox explain

​

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

​

mirror

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

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

​

remote

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

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

​

اختيار وضع

​

مرجع التكوين

​

أمثلة

​

إعداد remote بسيط

{
  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",
        },
      },
    },
  },
}

​

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

# عرض جميع بيئات sandbox runtime (Docker + OpenShell)
openclaw sandbox list

# فحص السياسة الفعلية
openclaw sandbox explain

# إعادة الإنشاء (يحذف مساحة العمل البعيدة، ويعيد التهيئة عند الاستخدام التالي)
openclaw sandbox recreate --all

​

متى تعيد الإنشاء

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

openclaw sandbox recreate --all

​

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

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

​

كيف يعمل

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

​

راجع أيضًا

• Sandboxing — الأوضاع، والنطاقات، ومقارنة الواجهات الخلفية
• Sandbox vs Tool Policy vs Elevated — تصحيح أخطاء الأدوات المحظورة
• Multi-Agent Sandbox and Tools — تجاوزات لكل وكيل
• Sandbox CLI — أوامر openclaw sandbox