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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ما الذي يُعزل

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

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

​

الأوضاع

​

النطاق

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

​

الخلفية

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

​

اختيار خلفية

​

خلفية Docker

​

خلفية 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

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

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

​

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

​

دورة حياة OpenShell

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

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

​

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

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

​

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

• عند تعيينه (بما في ذلك [])، يستبدل 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"],
          },
        },
      },
    ],
  },
}

​

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

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 explain لفحص وضع Sandbox الفعال، وسياسة الأدوات، ومفاتيح تكوين الإصلاح.
• راجع Sandbox مقابل سياسة الأدوات مقابل Elevated للحصول على النموذج الذهني لسؤال “لماذا هذا محظور؟”.

​

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

​

مثال تفعيل أدنى

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

​

ذات صلة

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