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

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

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

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

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

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

حالت‌ها، دامنه و بک‌اند

سه تنظیم مستقل رفتار سندباکس را کنترل می‌کنند:

حالت تعیین می‌کند سندباکس‌سازی چه زمانی اعمال شود:

• off: بدون سندباکس‌سازی.
• non-main: همهٔ نشست‌ها به‌جز نشست اصلی عامل در سندباکس اجرا می‌شوند. کلید نشست اصلی همیشه agent:<agentId>:main است (یا وقتی session.scope برابر "global" باشد، global) و قابل پیکربندی نیست. نشست‌های گروهی/کانالی از کلیدهای خود استفاده می‌کنند، بنابراین همیشه غیر اصلی محسوب می‌شوند و در سندباکس اجرا خواهند شد.
• all: همهٔ نشست‌ها در سندباکس اجرا می‌شوند.

دامنه تعیین می‌کند چند کانتینر/محیط ایجاد شود:

• agent: یک کانتینر برای هر عامل.
• session: یک کانتینر برای هر نشست.
• shared: یک کانتینر مشترک میان همهٔ نشست‌های سندباکس‌شده (در این دامنه، بازنویسی‌های مختص هر عامل برای docker/ssh/browser نادیده گرفته می‌شوند).

بک‌اند تعیین می‌کند کدام محیط اجرا ابزارهای سندباکس‌شده را اجرا کند. پیکربندی مختص SSH زیر agents.defaults.sandbox.ssh و پیکربندی مختص OpenShell زیر plugins.entries.openshell.config قرار دارد.

بک‌اند Docker

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

پیش‌فرض‌ها: network: "none" (بدون دسترسی خروجی)، readOnlyRoot: true، capDrop: ["ALL"]، تصویر openclaw-sandbox:bookworm-slim.

برای در دسترس قرار دادن GPUهای میزبان، agents.defaults.sandbox.docker.gpus (یا بازنویسی مختص هر عامل) را روی مقداری مانند "all" یا "device=GPU-uuid" تنظیم کنید. این مقدار به پرچم --gpus در Docker منتقل می‌شود و به یک محیط اجرای سازگار روی میزبان، مانند NVIDIA Container Toolkit، نیاز دارد.

مرورگر سندباکس‌شده

• مرورگر سندباکس هنگامی که ابزار مرورگر به آن نیاز دارد به‌طور خودکار آغاز می‌شود (و اطمینان حاصل می‌کند CDP قابل‌دسترسی است). آن را از طریق agents.defaults.sandbox.browser.autoStart (پیش‌فرض true) و autoStartTimeoutMs (پیش‌فرض ۱۲ ثانیه) پیکربندی کنید.
• کانتینرهای مرورگر سندباکس به‌جای شبکهٔ سراسری bridge از یک شبکهٔ اختصاصی Docker با نام openclaw-sandbox-browser استفاده می‌کنند. آن را با agents.defaults.sandbox.browser.network پیکربندی کنید.
• agents.defaults.sandbox.browser.cdpSourceRange ورود CDP در لبهٔ کانتینر را با فهرست مجاز CIDR محدود می‌کند (برای مثال 172.21.0.1/32).
• دسترسی ناظر noVNC به‌طور پیش‌فرض با گذرواژه محافظت می‌شود؛ OpenClaw یک نشانی URL دارای توکن کوتاه‌عمر ایجاد می‌کند که یک صفحهٔ راه‌انداز محلی ارائه می‌دهد و noVNC را با گذرواژه در قطعهٔ URL باز می‌کند (نه در رشتهٔ پرس‌وجو یا گزارش‌های سربرگ).
• agents.defaults.sandbox.browser.allowHostControl (پیش‌فرض false) به نشست‌های سندباکس‌شده اجازه می‌دهد مرورگر میزبان را صراحتاً هدف قرار دهند.
• فهرست‌های مجاز اختیاری دسترسی به target: "custom" را کنترل می‌کنند: allowedControlUrls، allowedControlHosts، allowedControlPorts.

بک‌اند SSH

از backend: "ssh" برای اجرای سندباکس‌شدهٔ 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" },        },      },    },  },}

پیش‌فرض‌ها: command: "ssh"، workspaceRoot: "/tmp/openclaw-sandboxes"، strictHostKeyChecking: true، updateHostKeys: true.

• چرخهٔ حیات: OpenClaw زیر sandbox.ssh.workspaceRoot یک ریشهٔ راه‌دور برای هر دامنه ایجاد می‌کند. در نخستین استفاده پس از ایجاد یا بازآفرینی، فضای کاری راه‌دور را یک‌بار از فضای کاری محلی مقداردهی اولیه می‌کند. پس از آن، exec، read، write، edit، apply_patch، خواندن رسانه‌های اعلان و آماده‌سازی رسانه‌های ورودی، مستقیماً از طریق SSH روی فضای کاری راه‌دور اجرا می‌شوند. OpenClaw تغییرات راه‌دور را به‌طور خودکار با فضای کاری محلی همگام نمی‌کند.
• مواد احراز هویت: identityFile/certificateFile/knownHostsFile به فایل‌های محلی موجود اشاره می‌کنند. identityData/certificateData/knownHostsData رشته‌های درون‌خطی یا SecretRefها را می‌پذیرند؛ این موارد از طریق تصویر لحظه‌ای معمول محیط اجرای اسرار resolve می‌شوند، در فایل‌های موقت با حالت 0600 نوشته می‌شوند و با پایان نشست SSH حذف می‌شوند. اگر برای یک مورد، هم نوع *File و هم نوع *Data تنظیم شده باشد، *Data برای آن نشست اولویت دارد.
• پیامدهای مرجع‌بودن محیط راه‌دور: پس از مقداردهی اولیه، فضای کاری راه‌دور SSH به وضعیت واقعی سندباکس تبدیل می‌شود. ویرایش‌های محلی میزبان که پس از مرحلهٔ مقداردهی اولیه بیرون از OpenClaw انجام شوند، تا زمانی که سندباکس را بازآفرینی نکنید در محیط راه‌دور قابل مشاهده نیستند. openclaw sandbox recreate ریشهٔ راه‌دور مختص دامنه را حذف می‌کند و در استفادهٔ بعدی دوباره از محیط محلی مقداردهی اولیه می‌کند. سندباکس‌سازی مرورگر در این بک‌اند پشتیبانی نمی‌شود و تنظیمات sandbox.docker.* بر آن اعمال نمی‌شوند.

بک‌اند OpenShell

از backend: "openshell" برای اجرای سندباکس‌شدهٔ ابزارها در یک محیط راه‌دور مدیریت‌شده توسط OpenShell استفاده کنید. OpenShell از همان انتقال SSH و پل سیستم فایل راه‌دور بک‌اند عمومی SSH استفاده می‌کند و چرخهٔ حیات OpenShell (sandbox create/get/delete/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        },      },    },  },}

mode: "mirror" (پیش‌فرض) فضای کاری محلی را مرجع نگه می‌دارد: OpenClaw پیش از exec محیط محلی را با سندباکس همگام می‌کند و پس از آن تغییرات را بازمی‌گرداند. mode: "remote" فضای کاری راه‌دور را یک‌بار از محیط محلی مقداردهی اولیه می‌کند، سپس exec/read/write/edit/apply_patch را مستقیماً روی فضای کاری راه‌دور و بدون همگام‌سازی معکوس اجرا می‌کند؛ ویرایش‌های محلی پس از مقداردهی اولیه تا زمانی که openclaw sandbox recreate را اجرا نکنید قابل مشاهده نیستند. در scope: "agent" یا scope: "shared"، آن فضای کاری راه‌دور در همان دامنه مشترک است. محدودیت‌های فعلی: سندباکس مرورگر هنوز پشتیبانی نمی‌شود و sandbox.docker.binds بر این بک‌اند اعمال نمی‌شود.

دستورهای openclaw sandbox list/recreate/prune همگی با محیط‌های اجرای OpenShell همانند محیط‌های اجرای Docker رفتار می‌کنند؛ منطق هرس از نوع بک‌اند آگاه است.

برای پیش‌نیازهای کامل، مرجع پیکربندی، مقایسهٔ حالت‌های فضای کاری و جزئیات چرخهٔ حیات، به OpenShell مراجعه کنید.

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

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 دایرکتوری‌های میزبان بیشتری را فقط در کانتینر مرورگر جعبه‌شنی سوار می‌کند. وقتی تنظیم شده باشد (از جمله [])، برای کانتینر مرورگر جایگزین docker.binds می‌شود؛ وقتی حذف شده باشد، کانتینر مرورگر از 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-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

به‌طور پیش‌فرض، کانتینرهای جعبه‌شنی Docker هیچ شبکه‌ای ندارند. با agents.defaults.sandbox.docker.network این رفتار را تغییر دهید.

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

برای استقرارهای Gateway مبتنی بر Docker، 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 list کانتینرهای جعبه‌شنی، وضعیت، تطابق تصویر، عمر، زمان بیکاری و نشست/عامل مرتبط را نشان می‌دهد.
• openclaw sandbox explain [--session <key>] [--agent <id>] حالت مؤثر جعبه‌شنی، فضای کاری میزبان، دایرکتوری کاری زمان اجرا، سوارشدن‌های Docker، سیاست ابزار و کلیدهای پیکربندی اصلاح را بررسی می‌کند. فیلد workspaceRoot آن همان ریشه جعبه‌شنی پیکربندی‌شده باقی می‌ماند؛ effectiveHostWorkspaceRoot نشان می‌دهد فضای کاری فعال واقعاً کجا قرار دارد.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] کانتینرها/محیط‌ها را حذف می‌کند تا در استفاده بعدی با پیکربندی فعلی دوباره ایجاد شوند.
• برای مدل ذهنی «چرا این مسدود شده است؟»، به جعبه‌شنی در برابر سیاست ابزار در برابر اجرای ارتقایافته مراجعه کنید.

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

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

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

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

مرتبط

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