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

يمكن لـ 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 (/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 يستخدم مساحة العمل المحلية كمصدر مرجعي بين أدوار التنفيذ
• يستخدم وضع 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-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

افتراضيًا، تعمل حاويات صندوق 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

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

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

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

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

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

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

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

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

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

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

# ذات صلة

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