ایزوله‌سازی

OpenClaw می‌تواند ابزارها را داخل backendهای 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).
  • اجرای elevated از sandboxing عبور می‌کند و از مسیر خروج پیکربندی‌شده استفاده می‌کند (gateway به‌طور پیش‌فرض، یا node وقتی هدف exec برابر node است).
  • اگر sandboxing خاموش باشد، tools.elevated اجرا را تغییر نمی‌دهد (از قبل روی میزبان است). حالت Elevated را ببینید.

حالت‌ها

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

دامنه

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

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

Backend

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 قرار دارد.

انتخاب backend

Docker backend

sandboxing به‌طور پیش‌فرض خاموش است. اگر sandboxing را فعال کنید و backend انتخاب نکنید، OpenClaw از Docker backend استفاده می‌کند. ابزارها و مرورگرهای 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 را تنظیم کنید. مقدار به‌عنوان یک آرگومان جداگانه به flag --gpus در Docker پاس داده می‌شود، برای مثال "all" یا "device=GPU-uuid"، و به یک runtime میزبان سازگار مانند NVIDIA Container Toolkit نیاز دارد.

SSH backend

وقتی می‌خواهید 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 backend

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

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

حالت‌های workspace

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

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

چرخه عمر OpenShell

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

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

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

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

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

دسترسی به workspace

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

با backend OpenShell:

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

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

mountهای bind سفارشی

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

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

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

• وقتی تنظیم شود (از جمله [])، برای container مرورگر جایگزین agents.defaults.sandbox.docker.binds می‌شود.
• وقتی حذف شود، container مرورگر به 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"],          },        },      },    ],  },}

imageها و راه‌اندازی

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 کانتینری اینجا هستند: Docker

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

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

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

مسیرها:

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

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

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

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

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

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

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

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

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

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

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

مرتبط

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