العزل في بيئة محمية

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

ما الذي يُعزل

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

غير معزول:

• عملية Gateway نفسها.
• أي أداة يُسمح لها صراحةً بالعمل خارج البيئة المعزولة (مثل tools.elevated).
  • يتجاوز تنفيذ exec المرتفع العزل ويستخدم مسار الخروج المضبوط (gateway افتراضيًا، أو node عندما يكون هدف exec هو 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 daemon (/var/run/docker.sock). يتحدد عزل حاوية البيئة المعزولة بواسطة namespaces الخاصة بـ 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/*).

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

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

تُدمج عمليات bind العامة والخاصة بكل وكيل ولا تُستبدل. تحت scope: "shared"، تُتجاهل عمليات bind الخاصة بكل وكيل.

يثبّت 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 تمهيد إعدادات صندوق الرمل. اضبط OPENCLAW_SANDBOX=1 (أو true/yes/on) لتمكين ذلك المسار. يمكنك تجاوز موقع المقبس باستخدام OPENCLAW_DOCKER_SOCKET. مرجع الإعداد الكامل والبيئة: Docker.

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

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

المسارات:

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

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

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

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 — تصحيح "لماذا هذا محظور؟"
• الأمان