ایزوله‌سازی

OpenClaw می‌تواند ابزارها را درون پشتوانه‌های sandbox اجرا کند تا دامنه اثر کاهش یابد. این کار اختیاری است و با پیکربندی کنترل می‌شود (agents.defaults.sandbox یا agents.list[].sandbox). اگر sandboxing خاموش باشد، ابزارها روی میزبان اجرا می‌شوند. Gateway روی میزبان باقی می‌ماند؛ اجرای ابزار، در صورت فعال بودن، در یک sandbox ایزوله اجرا می‌شود.

# چه چیزهایی sandbox می‌شوند

• اجرای ابزار (exec، read، write، edit، apply_patch، process و غیره).
• مرورگر sandbox اختیاری (agents.defaults.sandbox.browser).

sandbox نمی‌شوند:

• خود فرایند Gateway.
• هر ابزاری که صراحتا مجاز باشد خارج از sandbox اجرا شود (مثلا tools.elevated).
  • اجرای ارتقایافته از sandboxing عبور می‌کند و از مسیر خروج پیکربندی‌شده استفاده می‌کند (gateway به‌طور پیش‌فرض، یا node وقتی هدف اجرا node است).
  • اگر sandboxing خاموش باشد، tools.elevated اجرا را تغییر نمی‌دهد (از قبل روی میزبان است). حالت ارتقایافته را ببینید.

# حالت‌ها

agents.defaults.sandbox.mode کنترل می‌کند sandboxing چه زمانی استفاده شود:

# دامنه

agents.defaults.sandbox.scope کنترل می‌کند چند کانتینر ساخته شود:

• "agent" (پیش‌فرض): یک کانتینر برای هر agent.
• "session": یک کانتینر برای هر نشست.
• "shared": یک کانتینر مشترک میان همه نشست‌های sandbox شده.

# پشتوانه

agents.defaults.sandbox.backend کنترل می‌کند کدام runtime sandbox را فراهم کند:

• "docker" (پیش‌فرض وقتی sandboxing فعال است): runtime محلی sandbox مبتنی بر Docker.
• "ssh": runtime عمومی sandbox راه‌دور مبتنی بر SSH.
• "openshell": runtime sandbox مبتنی بر OpenShell.

پیکربندی مخصوص SSH زیر agents.defaults.sandbox.ssh قرار دارد. پیکربندی مخصوص OpenShell زیر plugins.entries.openshell.config قرار دارد.

# انتخاب یک پشتوانه

# پشتوانه Docker

sandboxing به‌طور پیش‌فرض خاموش است. اگر sandboxing را فعال کنید و پشتوانه‌ای انتخاب نکنید، OpenClaw از پشتوانه Docker استفاده می‌کند. ابزارها و مرورگرهای sandbox را به‌صورت محلی از طریق سوکت daemon Docker (/var/run/docker.sock) اجرا می‌کند. ایزولاسیون کانتینر sandbox توسط namespaceهای Docker تعیین می‌شود.

برای در معرض قرار دادن GPUهای میزبان برای sandboxهای Docker، agents.defaults.sandbox.docker.gpus یا override مخصوص هر agent یعنی agents.list[].sandbox.docker.gpus را تنظیم کنید. مقدار به‌عنوان یک آرگومان جداگانه به پرچم --gpus در Docker پاس داده می‌شود، برای مثال "all" یا "device=GPU-uuid"، و به runtime میزبان سازگار مانند NVIDIA Container Toolkit نیاز دارد.

# پشتوانه SSH

وقتی می‌خواهید OpenClaw اجرای exec، ابزارهای فایل، و خواندن رسانه را روی هر ماشین قابل‌دسترسی با SSH sandbox کند، از backend: "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

وقتی می‌خواهید OpenClaw ابزارها را در یک محیط راه‌دور مدیریت‌شده توسط OpenShell sandbox کند، از backend: "openshell" استفاده کنید. برای راهنمای کامل راه‌اندازی، مرجع پیکربندی، و مقایسه حالت‌های workspace، صفحه اختصاصی OpenShell را ببینید.

OpenShell همان انتقال SSH هسته و پل فایل‌سیستم راه‌دور پشتوانه عمومی SSH را دوباره استفاده می‌کند، و lifecycle مخصوص OpenShell (sandbox create/get/delete، sandbox ssh-config) به‌همراه حالت اختیاری workspace یعنی 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 (پیش‌فرض): workspace محلی مرجع باقی می‌ماند. OpenClaw پیش از exec فایل‌های محلی را به OpenShell همگام می‌کند و پس از exec، workspace راه‌دور را به عقب همگام می‌کند.
• remote: workspace در OpenShell پس از ایجاد sandbox مرجع است. OpenClaw یک‌بار workspace راه‌دور را از workspace محلی seed می‌کند، سپس ابزارهای فایل و exec مستقیما روی sandbox راه‌دور اجرا می‌شوند، بدون همگام‌سازی تغییرات به عقب.

# حالت‌های workspace

OpenShell دو مدل workspace دارد. این همان بخشی است که در عمل بیشترین اهمیت را دارد.

اگر سندباکس را یک محیط اجرای موقت در نظر می‌گیرید، mirror را انتخاب کنید. اگر سندباکس را فضای کاری واقعی در نظر می‌گیرید، remote را انتخاب کنید.

# چرخه عمر OpenShell

سندباکس‌های OpenShell همچنان از طریق چرخه عمر معمول سندباکس مدیریت می‌شوند:

• openclaw sandbox list زمان‌اجراهای OpenShell و همچنین زمان‌اجراهای Docker را نشان می‌دهد
• openclaw sandbox recreate زمان‌اجرای فعلی را حذف می‌کند و به OpenClaw اجازه می‌دهد در استفاده بعدی آن را دوباره بسازد
• منطق پاک‌سازی نیز از بک‌اند آگاه است

برای حالت remote، ساخت دوباره به‌ویژه مهم است:

• ساخت دوباره، فضای کاری راه‌دور مرجع را برای آن scope حذف می‌کند
• استفاده بعدی، یک فضای کاری راه‌دور تازه را از فضای کاری محلی مقداردهی اولیه می‌کند

برای حالت mirror، ساخت دوباره عمدتاً محیط اجرای راه‌دور را بازنشانی می‌کند، چون فضای کاری محلی در هر صورت مرجع باقی می‌ماند.

# دسترسی به فضای کاری

agents.defaults.sandbox.workspaceAccess کنترل می‌کند سندباکس چه چیزهایی را می‌تواند ببیند:

با بک‌اند OpenShell:

• حالت mirror همچنان از فضای کاری محلی به‌عنوان منبع مرجع بین نوبت‌های exec استفاده می‌کند
• حالت remote بعد از مقداردهی اولیه، از فضای کاری راه‌دور OpenShell به‌عنوان منبع مرجع استفاده می‌کند
• workspaceAccess: "ro" و "none" همچنان رفتار نوشتن را به همان شکل محدود می‌کنند

رسانه ورودی در فضای کاری فعال سندباکس کپی می‌شود (media/inbound/*).

# اتصال‌های bind سفارشی

agents.defaults.sandbox.docker.binds دایرکتوری‌های اضافی میزبان را در کانتینر mount می‌کند. قالب: host:container:mode (برای مثال، "/home/user/source:/source:rw").

bindهای سراسری و مختص هر عامل ادغام می‌شوند (جایگزین نمی‌شوند). تحت scope: "shared"، bindهای مختص هر عامل نادیده گرفته می‌شوند.

agents.defaults.sandbox.browser.binds دایرکتوری‌های اضافی میزبان را فقط در کانتینر مرورگر سندباکس mount می‌کند.

• وقتی تنظیم شود (از جمله [])، برای کانتینر مرورگر جایگزین 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 override کنید.

نصب‌های Docker و Gateway کانتینری‌شده اینجا هستند: Docker

برای استقرارهای Gateway Docker، scripts/docker/setup.sh می‌تواند پیکربندی سندباکس را bootstrap کند. برای فعال کردن آن مسیر، OPENCLAW_SANDBOX=1 (یا true/yes/on) را تنظیم کنید. می‌توانید محل socket را با OPENCLAW_DOCKER_SOCKET override کنید. راه‌اندازی کامل و مرجع env: Docker.

# setupCommand (راه‌اندازی یک‌باره کانتینر)

setupCommand بعد از ساخته شدن کانتینر سندباکس یک‌بار اجرا می‌شود (نه در هر اجرا). این فرمان داخل کانتینر از طریق sh -lc اجرا می‌شود.

مسیرها:

• سراسری: agents.defaults.sandbox.docker.setupCommand
• مختص هر عامل: agents.list[].sandbox.docker.setupCommand

# خط‌مشی ابزار و راه‌های خروج اضطراری

خط‌مشی‌های مجاز/غیرمجاز ابزار همچنان پیش از قواعد sandbox اعمال می‌شوند. اگر ابزاری به‌صورت سراسری یا برای هر عامل رد شده باشد، sandboxing آن را برنمی‌گرداند.

tools.elevated یک راه خروج اضطراری صریح است که exec را بیرون از sandbox اجرا می‌کند (به‌صورت پیش‌فرض gateway، یا وقتی هدف exec برابر node باشد، node). دستورهای /exec فقط برای فرستندگان مجاز اعمال می‌شوند و در هر جلسه پایدار می‌مانند؛ برای غیرفعال‌سازی کامل exec، از رد کردن در خط‌مشی ابزار استفاده کنید (نگاه کنید به Sandbox در برابر خط‌مشی ابزار در برابر Elevated).

اشکال‌زدایی:

• برای بررسی حالت sandbox مؤثر، خط‌مشی ابزار، و کلیدهای پیکربندی اصلاح، از openclaw sandbox explain استفاده کنید.
• برای مدل ذهنی «چرا این مسدود شده است؟» به 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 — راه‌اندازی backend مدیریت‌شده sandbox، حالت‌های workspace، و مرجع پیکربندی
• پیکربندی sandbox
• Sandbox در برابر خط‌مشی ابزار در برابر Elevated — اشکال‌زدایی «چرا این مسدود شده است؟»
• امنیت