العزل الأمني

يمكن لـ OpenClaw تشغيل الأدوات داخل خلفيات بيئات معزولة لتقليل نطاق التأثير. هذا اختياري وتتحكم فيه الإعدادات (agents.defaults.sandbox أو agents.list[].sandbox). إذا كان العزل متوقفًا، تعمل الأدوات على المضيف. يبقى Gateway على المضيف؛ ويعمل تنفيذ الأدوات في بيئة معزولة عند تفعيله.

ما الذي يُعزل

• تنفيذ الأدوات (exec، read، write، edit، apply_patch، process، إلخ).
• المتصفح المعزول الاختياري (agents.defaults.sandbox.browser).

غير معزول:

• عملية Gateway نفسها.
• أي أداة يُسمح لها صراحةً بالعمل خارج البيئة المعزولة (مثل tools.elevated).
  • يتجاوز التنفيذ المرفوع العزل ويستخدم مسار الخروج المضبوط (gateway افتراضيًا، أو node عندما يكون هدف التنفيذ هو node).
  • إذا كان العزل متوقفًا، فإن tools.elevated لا يغير التنفيذ (فهو بالفعل على المضيف). راجع الوضع المرفوع.

الأوضاع

يتحكم agents.defaults.sandbox.mode في وقت استخدام العزل:

النطاق

يتحكم agents.defaults.sandbox.scope في عدد الحاويات التي تُنشأ:

• "agent" (الافتراضي): حاوية واحدة لكل وكيل.
• "session": حاوية واحدة لكل جلسة.
• "shared": حاوية واحدة مشتركة بين جميع الجلسات المعزولة.

الخلفية

يتحكم agents.defaults.sandbox.backend في بيئة التشغيل التي توفر العزل:

• "docker" (الافتراضي عند تفعيل العزل): بيئة تشغيل عزل محلية مدعومة بـ Docker.
• "ssh": بيئة تشغيل عزل بعيدة عامة مدعومة بـ SSH.
• "openshell": بيئة تشغيل عزل مدعومة بـ OpenShell.

توجد إعدادات SSH الخاصة تحت agents.defaults.sandbox.ssh. وتوجد إعدادات OpenShell الخاصة تحت plugins.entries.openshell.config.

اختيار خلفية

خلفية Docker

العزل متوقف افتراضيًا. إذا فعّلت العزل ولم تختر خلفية، يستخدم OpenClaw خلفية Docker. ينفذ الأدوات والمتصفحات المعزولة محليًا عبر مقبس عفريت Docker (/var/run/docker.sock). يتحدد عزل حاوية البيئة المعزولة بواسطة نطاقات أسماء Docker.

لإتاحة وحدات GPU الخاصة بالمضيف لبيئات Docker المعزولة، اضبط agents.defaults.sandbox.docker.gpus أو تجاوز كل وكيل agents.list[].sandbox.docker.gpus. تُمرر القيمة إلى علامة Docker --gpus كوسيط منفصل، مثل "all" أو "device=GPU-uuid"، وتتطلب بيئة تشغيل مضيف متوافقة مثل NVIDIA Container Toolkit.

خلفية SSH

استخدم backend: "ssh" عندما تريد من OpenClaw عزل exec، وأدوات الملفات، وقراءات الوسائط على جهاز عشوائي يمكن الوصول إليه عبر SSH.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

خلفية OpenShell

استخدم backend: "openshell" عندما تريد من OpenClaw عزل الأدوات في بيئة بعيدة مُدارة من OpenShell. للحصول على دليل الإعداد الكامل، ومرجع الإعدادات، ومقارنة أوضاع مساحة العمل، راجع صفحة OpenShell المخصصة.

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

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

أوضاع OpenShell:

• mirror (الافتراضي): تبقى مساحة العمل المحلية هي المرجع. يزامن OpenClaw الملفات المحلية إلى OpenShell قبل exec ويزامن مساحة العمل البعيدة مرة أخرى بعد exec.
• remote: تكون مساحة عمل OpenShell هي المرجع بعد إنشاء البيئة المعزولة. يبذر OpenClaw مساحة العمل البعيدة مرة واحدة من مساحة العمل المحلية، ثم تعمل أدوات الملفات وexec مباشرةً على البيئة المعزولة البعيدة دون مزامنة التغييرات مرة أخرى.

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

لدى OpenShell نموذجان لمساحة العمل. هذا هو الجزء الأكثر أهمية في الممارسة.

اختر mirror إذا كنت تعتبر بيئة العزل بيئة تنفيذ مؤقتة. اختر remote إذا كنت تعتبر بيئة العزل مساحة العمل الحقيقية.

دورة حياة OpenShell

ما زالت بيئات عزل OpenShell تدار عبر دورة حياة بيئة العزل العادية:

• يعرض openclaw sandbox list أوقات تشغيل OpenShell وكذلك أوقات تشغيل Docker
• يحذف openclaw sandbox recreate وقت التشغيل الحالي ويتيح لـ OpenClaw إعادة إنشائه عند الاستخدام التالي
• منطق التنظيف مدرك للواجهة الخلفية أيضًا

بالنسبة إلى وضع remote، فإن إعادة الإنشاء مهمة خصوصًا:

• تحذف إعادة الإنشاء مساحة العمل البعيدة المرجعية لذلك النطاق
• يهيئ الاستخدام التالي مساحة عمل بعيدة جديدة من مساحة العمل المحلية

بالنسبة إلى وضع mirror، تعيد إعادة الإنشاء أساسًا ضبط بيئة التنفيذ البعيدة لأن مساحة العمل المحلية تبقى مرجعية على أي حال.

الوصول إلى مساحة العمل

يتحكم agents.defaults.sandbox.workspaceAccess في ما يمكن لبيئة العزل رؤيته:

مع واجهة OpenShell الخلفية:

• ما زال وضع mirror يستخدم مساحة العمل المحلية كمصدر مرجعي بين أدوار exec
• يستخدم وضع remote مساحة عمل OpenShell البعيدة كمصدر مرجعي بعد التهيئة الأولية
• يظل workspaceAccess: "ro" و"none" يقيدان سلوك الكتابة بالطريقة نفسها

تُنسخ الوسائط الواردة إلى مساحة عمل بيئة العزل النشطة (media/inbound/*).

عمليات تثبيت الربط المخصصة

يثبت agents.defaults.sandbox.docker.binds أدلة مضيف إضافية داخل الحاوية. الصيغة: host:container:mode (مثل "/home/user/source:/source:rw").

تُدمج عمليات الربط العامة والخاصة بكل وكيل ولا تُستبدل. ضمن scope: "shared"، يتم تجاهل عمليات الربط الخاصة بكل وكيل.

يثبت agents.defaults.sandbox.browser.binds أدلة مضيف إضافية داخل حاوية متصفح بيئة العزل فقط.

• عند ضبطه (بما في ذلك [])، يستبدل agents.defaults.sandbox.docker.binds لحاوية المتصفح.
• عند حذفه، ترجع حاوية المتصفح إلى agents.defaults.sandbox.docker.binds (متوافق مع الإصدارات السابقة).

مثال (مصدر للقراءة فقط + دليل بيانات إضافي):

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

الصور والإعداد

صورة Docker الافتراضية: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

افتراضيًا، تعمل حاويات بيئة عزل Docker بلا شبكة. تجاوز ذلك باستخدام agents.defaults.sandbox.docker.network.

توجد تثبيتات Docker وGateway المعبأ في حاوية هنا: Docker

بالنسبة إلى عمليات نشر Docker Gateway، يمكن لـ scripts/docker/setup.sh تمهيد إعدادات sandbox. عيّن OPENCLAW_SANDBOX=1 (أو true/yes/on) لتمكين هذا المسار. يمكنك تجاوز موقع المقبس باستخدام OPENCLAW_DOCKER_SOCKET. مرجع الإعداد الكامل والبيئة: Docker.

setupCommand (إعداد الحاوية لمرة واحدة)

يعمل setupCommand مرة واحدة بعد إنشاء حاوية sandbox (وليس عند كل تشغيل). يتم تنفيذه داخل الحاوية عبر sh -lc.

المسارات:

• عام: agents.defaults.sandbox.docker.setupCommand
• لكل وكيل: agents.list[].sandbox.docker.setupCommand

سياسة الأدوات ومخارج التجاوز

تظل سياسات السماح/الرفض للأدوات مطبقة قبل قواعد sandbox. إذا رُفضت أداة عالمياً أو لكل وكيل، فلن يعيدها sandboxing.

tools.elevated هو مخرج تجاوز صريح يشغل exec خارج sandbox (gateway افتراضياً، أو node عندما يكون هدف التنفيذ هو node). لا تنطبق توجيهات /exec إلا على المرسلين المصرح لهم وتستمر لكل جلسة؛ لتعطيل exec بشكل صارم، استخدم رفض سياسة الأدوات (راجع Sandbox مقابل سياسة الأدوات مقابل Elevated).

تصحيح الأخطاء:

• استخدم openclaw sandbox explain لفحص وضع sandbox الفعال، وسياسة الأدوات، ومفاتيح إعداد الإصلاح.
• راجع Sandbox مقابل سياسة الأدوات مقابل Elevated للحصول على النموذج الذهني لسؤال "لماذا تم حظر هذا؟".

أبقِه مقفلاً بإحكام.

تجاوزات الوكلاء المتعددين

يمكن لكل وكيل تجاوز sandbox + الأدوات: agents.list[].sandbox وagents.list[].tools (بالإضافة إلى agents.list[].tools.sandbox.tools لسياسة أدوات sandbox). راجع Sandbox والأدوات للوكلاء المتعددين لمعرفة الأسبقية.

مثال تمكين بسيط

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

ذات صلة

• Sandbox والأدوات للوكلاء المتعددين — التجاوزات لكل وكيل والأسبقية
• OpenShell — إعداد واجهة sandbox الخلفية المُدارة، وأوضاع مساحة العمل، ومرجع الإعدادات
• إعدادات Sandbox
• Sandbox مقابل سياسة الأدوات مقابل Elevated — تصحيح "لماذا تم حظر هذا؟"
• الأمان