OpenShell

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• تثبيت 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

​

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

​

mirror

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

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

​

remote

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

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

​

اختيار وضع

​

مرجع التكوين

​

أمثلة

​

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

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

​

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

# 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

​

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

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

openclaw sandbox recreate --all

​

تقوية الأمان

​

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

• متصفح صندوق الحماية غير مدعوم على واجهة 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