العزل البرمجي

يمكن لـ 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 شيئًا لأن التنفيذ يعمل بالفعل على المضيف. راجع وضع الصلاحيات المرتفعة.

الأوضاع والنطاق والبيئة الخلفية

تتحكم ثلاثة إعدادات مستقلة في سلوك العزل:

يتحكم الوضع في وقت تطبيق العزل:

• off: لا يوجد عزل.
• non-main: اعزل كل جلسة باستثناء الجلسة الرئيسية للوكيل. يكون مفتاح الجلسة الرئيسية دائمًا agent:<agentId>:main (أو global عندما تكون قيمة session.scope هي "global")، ولا يمكن ضبطه. تستخدم جلسات المجموعات/القنوات مفاتيحها الخاصة، لذا تُعد دائمًا غير رئيسية وتخضع للعزل.
• all: تعمل كل جلسة داخل بيئة معزولة.

يتحكم النطاق في عدد الحاويات/البيئات التي تُنشأ:

• agent: حاوية واحدة لكل وكيل.
• session: حاوية واحدة لكل جلسة.
• shared: حاوية واحدة مشتركة بين جميع الجلسات المعزولة (يتم تجاهل تجاوزات docker وssh وbrowser الخاصة بكل وكيل ضمن هذا النطاق).

تتحكم البيئة الخلفية في بيئة التشغيل التي تنفّذ الأدوات المعزولة. يوجد الضبط الخاص بـ SSH ضمن agents.defaults.sandbox.ssh، ويوجد الضبط الخاص بـ OpenShell ضمن plugins.entries.openshell.config.

البيئة الخلفية Docker

تكون Docker البيئة الخلفية الافتراضية عند تمكين العزل. وهي تشغّل الأدوات ومتصفحات البيئة المعزولة محليًا عبر مقبس عفريت Docker ‏(/var/run/docker.sock)؛ ويأتي العزل من نطاقات أسماء Docker.

الإعدادات الافتراضية: network: "none" (لا اتصال صادر)، وreadOnlyRoot: true، وcapDrop: ["ALL"]، والصورة openclaw-sandbox:bookworm-slim.

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

المتصفح المعزول

• يبدأ متصفح البيئة المعزولة تلقائيًا (لضمان إمكانية الوصول إلى CDP) عندما تحتاج إليه أداة المتصفح. اضبطه عبر agents.defaults.sandbox.browser.autoStart (الافتراضي true) وautoStartTimeoutMs (الافتراضي 12 ثانية).
• تستخدم حاويات متصفح البيئة المعزولة شبكة Docker مخصصة (openclaw-sandbox-browser) بدلًا من شبكة bridge العامة. اضبطها عبر agents.defaults.sandbox.browser.network.
• يقيّد agents.defaults.sandbox.browser.cdpSourceRange دخول CDP عند حافة الحاوية بواسطة قائمة سماح CIDR (مثل 172.21.0.1/32).
• تكون إمكانية وصول المراقب عبر noVNC محمية بكلمة مرور افتراضيًا؛ يصدر OpenClaw عنوان URL برمز قصير العمر يعرض صفحة تمهيد محلية ويفتح noVNC مع كلمة المرور في جزء URL (وليس في سلسلة الاستعلام أو سجلات الترويسات).
• يسمح agents.defaults.sandbox.browser.allowHostControl (الافتراضي false) للجلسات المعزولة باستهداف متصفح المضيف صراحةً.
• تتحكم قوائم السماح الاختيارية في target: "custom":‏ allowedControlUrls وallowedControlHosts وallowedControlPorts.

البيئة الخلفية SSH

استخدم backend: "ssh" لعزل 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" },        },      },    },  },}

الإعدادات الافتراضية: command: "ssh" وworkspaceRoot: "/tmp/openclaw-sandboxes" وstrictHostKeyChecking: true وupdateHostKeys: true.

• دورة الحياة: ينشئ OpenClaw جذرًا بعيدًا لكل نطاق ضمن sandbox.ssh.workspaceRoot. عند أول استخدام بعد الإنشاء أو إعادة الإنشاء، يهيّئ مساحة العمل البعيدة هذه مرة واحدة من مساحة العمل المحلية. بعد ذلك، تعمل exec وread وwrite وedit وapply_patch وقراءة وسائط المطالبة وتجهيز الوسائط الواردة مباشرةً على مساحة العمل البعيدة عبر SSH. لا يزامن OpenClaw التغييرات البعيدة تلقائيًا إلى مساحة العمل المحلية.
• مواد المصادقة: تشير identityFile وcertificateFile وknownHostsFile إلى ملفات محلية موجودة. تقبل identityData وcertificateData وknownHostsData سلاسل مضمنة أو SecretRefs، ويجري حلها عبر لقطة بيئة تشغيل الأسرار العادية، ثم تُكتب في ملفات مؤقتة بالوضع 0600 وتُحذف عند انتهاء جلسة SSH. إذا ضُبط متغير من نوع *File وآخر من نوع *Data للعنصر نفسه، تكون الأولوية لـ *Data في تلك الجلسة.
• نتائج اعتبار النسخة البعيدة مرجعية: تصبح مساحة عمل SSH البعيدة حالة العزل الفعلية بعد التهيئة الأولية. لا تظهر التعديلات المحلية على المضيف التي تتم خارج OpenClaw بعد خطوة التهيئة في البيئة البعيدة حتى تعيد إنشاء البيئة المعزولة. يحذف openclaw sandbox recreate الجذر البعيد الخاص بالنطاق ويعيد تهيئته من النسخة المحلية عند الاستخدام التالي. لا يدعم هذا النظام الخلفي عزل المتصفح، ولا تنطبق عليه إعدادات sandbox.docker.*.

البيئة الخلفية OpenShell

استخدم backend: "openshell" لعزل الأدوات في بيئة بعيدة يديرها OpenShell. يعيد OpenShell استخدام نقل SSH وجسر نظام الملفات البعيد نفسيهما اللذين تستخدمهما البيئة الخلفية العامة SSH، ويضيف دورة حياة OpenShell ‏(sandbox create/get/delete/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        },      },    },  },}

يبقي mode: "mirror" (الافتراضي) مساحة العمل المحلية مرجعية: يزامن OpenClaw النسخة المحلية إلى البيئة المعزولة قبل exec ويعيد المزامنة منها بعده. أما mode: "remote" فيهيّئ مساحة العمل البعيدة مرة واحدة من النسخة المحلية، ثم يشغّل exec وread وwrite وedit وapply_patch مباشرةً على مساحة العمل البعيدة دون مزامنة عكسية؛ ولا تظهر التعديلات المحلية بعد التهيئة حتى تنفّذ openclaw sandbox recreate. ضمن scope: "agent" أو scope: "shared"، تكون مساحة العمل البعيدة هذه مشتركة على النطاق نفسه. القيود الحالية: متصفح البيئة المعزولة غير مدعوم بعد، ولا ينطبق sandbox.docker.binds على هذه البيئة الخلفية.

تتعامل أوامر openclaw sandbox list وrecreate وprune جميعها مع بيئات تشغيل OpenShell بالطريقة نفسها التي تتعامل بها مع بيئات تشغيل Docker؛ ويكون منطق التنظيف مدركًا للبيئة الخلفية.

للاطلاع على المتطلبات الأساسية الكاملة ومرجع الضبط ومقارنة أوضاع مساحة العمل وتفاصيل دورة الحياة، راجع OpenShell.

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

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

مع الواجهة الخلفية OpenShell، يظل وضع mirror يستخدم مساحة العمل المحلية بوصفها المصدر المعتمد بين أدوار التنفيذ، بينما يستخدم وضع 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 أدلة إضافية من المضيف داخل حاوية متصفح صندوق الحماية فقط. عند تعيينه (بما في ذلك [])، فإنه يستبدل docker.binds لحاوية المتصفح؛ وعند حذفه، تعود حاوية المتصفح إلى استخدام 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

بالنسبة إلى عمليات نشر Gateway عبر Docker، يمكن لـ 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

سياسة الأدوات ومنافذ الهروب

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

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

استكشاف الأخطاء وإصلاحها:

• يعرض openclaw sandbox list حاويات صندوق الحماية وحالتها ومدى تطابق الصورة وعمرها ومدة خمولها والجلسة أو الوكيل المرتبط بها.
• يفحص openclaw sandbox explain [--session <key>] [--agent <id>] وضع صندوق الحماية الفعلي ومساحة عمل المضيف ودليل عمل وقت التشغيل وعمليات تركيب Docker وسياسة الأدوات ومفاتيح الإعداد اللازمة للإصلاح. يظل الحقل workspaceRoot فيه هو جذر صندوق الحماية المُعدّ؛ بينما يوضح effectiveHostWorkspaceRoot المكان الفعلي لمساحة العمل النشطة.
• يزيل openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] الحاويات أو البيئات كي يُعاد إنشاؤها بالإعدادات الحالية عند الاستخدام التالي.
• راجع صندوق الحماية مقابل سياسة الأدوات مقابل التنفيذ بصلاحيات مرتفعة للنموذج الذهني الذي يجيب عن سؤال «لماذا هذا محظور؟».

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

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

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

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

ذو صلة

• صندوق الحماية متعدد الوكلاء والأدوات -- التجاوزات لكل وكيل وترتيب الأولوية
• OpenShell -- إعداد الواجهة الخلفية المُدارة لصندوق الحماية، وأوضاع مساحة العمل، ومرجع الإعدادات
• إعداد صندوق الحماية
• صندوق الحماية مقابل سياسة الأدوات مقابل الصلاحيات المرتفعة -- تصحيح مشكلة «لماذا تم حظر هذا؟»
• الأمان