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

​

ما الذي يخضع للعزل

• تنفيذ الأدوات: 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 الخاصة بكل وكيل ضمن هذا النطاق).

​

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

​

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

• يبدأ متصفح البيئة المعزولة تلقائيًا (لضمان إمكانية الوصول إلى 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

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

• دورة الحياة: ينشئ 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

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

​

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

​

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

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

​

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

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

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

​

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

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

​

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

​

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

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

​

ذو صلة

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