سندباکس‌سازی

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

چه چیزهایی سندباکس می‌شوند

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

سندباکس نمی‌شوند:

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

حالت‌ها

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

دامنه

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

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

بک‌اند

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

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

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

انتخاب بک‌اند

بک‌اند Docker

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

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

بک‌اند SSH

وقتی می‌خواهید OpenClaw، exec، ابزارهای فایل، و خواندن رسانه‌ها را روی یک ماشین دلخواه قابل دسترسی با SSH سندباکس کند، از 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 سندباکس کند، از 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 همگام می‌کند و workspace راه‌دور را پس از exec برمی‌گرداند و همگام می‌کند.
• remote: workspace در OpenShell پس از ایجاد سندباکس مرجع است. OpenClaw یک بار workspace راه‌دور را از workspace محلی seed می‌کند، سپس ابزارهای فایل و exec مستقیما روی سندباکس راه‌دور اجرا می‌شوند، بدون اینکه تغییرات برگردانده و همگام شوند.

حالت‌های workspace

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

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

چرخه حیات OpenShell

sandboxهای OpenShell همچنان از طریق چرخه حیات عادی sandbox مدیریت می‌شوند:

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

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

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

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

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

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

با backend مربوط به OpenShell:

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

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

bind mountهای سفارشی

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

bindهای global و هر-agent ادغام می‌شوند (جایگزین نمی‌شوند). زیر scope: "shared"، bindهای هر-agent نادیده گرفته می‌شوند.

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

• وقتی تنظیم شود (شامل [])، برای container مرورگر جایگزین agents.defaults.sandbox.docker.binds می‌شود.
• وقتی حذف شود، container مرورگر به agents.defaults.sandbox.docker.binds fallback می‌کند (سازگار با گذشته).

نمونه (source فقط‌خواندنی + یک دایرکتوری داده اضافی):

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

Imageها و setup

Image پیش‌فرض 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

به‌صورت پیش‌فرض، containerهای sandbox مربوط به Docker با بدون شبکه اجرا می‌شوند. با agents.defaults.sandbox.docker.network بازنویسی کنید.

نصب‌های Docker و Gateway containerized اینجا قرار دارند: Docker

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

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

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

مسیرها:

• Global: agents.defaults.sandbox.docker.setupCommand
• هر-agent: agents.list[].sandbox.docker.setupCommand

سیاست ابزار و راه‌های خروج اضطراری

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

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

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

• از openclaw sandbox explain برای بررسی حالت مؤثر سندباکس، سیاست ابزار، و کلیدهای پیکربندی اصلاح استفاده کنید.
• برای مدل ذهنی «چرا این مسدود شده است؟» به سندباکس در برابر سیاست ابزار در برابر Elevated مراجعه کنید.

آن را قفل‌شده نگه دارید.

بازنویسی‌های چندعاملی

هر عامل می‌تواند سندباکس + ابزارها را بازنویسی کند: agents.list[].sandbox و agents.list[].tools (به‌علاوه agents.list[].tools.sandbox.tools برای سیاست ابزار سندباکس). برای ترتیب تقدم، به سندباکس و ابزارهای چندعاملی مراجعه کنید.

نمونه حداقلی فعال‌سازی

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

مرتبط

• سندباکس و ابزارهای چندعاملی — بازنویسی‌های هر عامل و ترتیب تقدم
• OpenShell — راه‌اندازی بک‌اند سندباکس مدیریت‌شده، حالت‌های فضای کاری، و مرجع پیکربندی
• پیکربندی سندباکس
• سندباکس در برابر سیاست ابزار در برابر Elevated — اشکال‌زدایی «چرا این مسدود شده است؟»
• امنیت