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

OpenClaw می‌تواند اجرای ابزار را درون یک بک‌اند سندباکس انجام دهد تا دامنهٔ آسیب احتمالی کاهش یابد. سندباکس به‌طور پیش‌فرض غیرفعال است و با agents.defaults.sandbox (سراسری) یا agents.entries.*.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 (پیش‌فرض 12s) پیکربندی کنید.
• کانتینرهای مرورگر سندباکس به‌جای شبکهٔ سراسری 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 را با گذرواژه در fragment نشانی URL باز می‌کند (نه در رشتهٔ پرس‌وجو یا گزارش‌های header).
• agents.defaults.sandbox.browser.allowHostControl (پیش‌فرض false) به نشست‌های سندباکس‌شده اجازه می‌دهد مرورگر میزبان را صراحتاً هدف بگیرند.
• فهرست‌های مجاز اختیاری دسترسی به target: "custom" را کنترل می‌کنند: allowedControlUrls، allowedControlHosts، allowedControlPorts.

بک‌اند SSH

برای اجرای سندباکس‌شدهٔ 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",          // یا به‌جای فایل‌های محلی از SecretRefs / محتوای درون‌خطی استفاده کنید:          // 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 رشته‌های درون‌خطی یا SecretRefs را می‌پذیرند که از طریق snapshot معمول محیط اجرای اسرار resolve می‌شوند، با حالت 0600 در فایل‌های موقت نوشته می‌شوند و با پایان نشست SSH حذف می‌شوند. اگر برای یک مورد هم گونهٔ *File و هم گونهٔ *Data تنظیم شده باشند، *Data در آن نشست اولویت دارد.
• پیامدهای راه‌دور به‌عنوان مرجع اصلی: پس از مقداردهی اولیه، فضای کاری SSH راه‌دور به وضعیت واقعی سندباکس تبدیل می‌شود. ویرایش‌های محلی میزبان که پس از مرحلهٔ مقداردهی اولیه خارج از OpenClaw انجام شوند، تا زمانی که سندباکس را دوباره ایجاد نکنید در راه‌دور قابل مشاهده نیستند. openclaw sandbox recreate ریشهٔ راه‌دور هر دامنه را حذف می‌کند و در استفادهٔ بعدی دوباره از فضای محلی مقداردهی اولیه می‌کند. سندباکس مرورگر در این بک‌اند پشتیبانی نمی‌شود و تنظیمات sandbox.docker.* برای آن اعمال نمی‌شوند.

بک‌اند OpenShell

برای اجرای سندباکس‌شدهٔ ابزارها در یک محیط راه‌دور مدیریت‌شده با OpenShell، از backend: "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", // آینه‌ای | راه‌دور        },      },    },  },}

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

openclaw sandbox list/recreate/هرس، همگی runtimeهای OpenShell را مانند runtimeهای Docker در نظر می‌گیرند؛ منطق هرس از backend آگاه است.

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

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

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

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

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

چند پوشه برای یک agent

وقتی یک agent درون sandbox به بیش از فضای کاری اصلی خود نیاز دارد، از bind mountهای Docker استفاده کنید. هر ورودی یک پوشه میزبان را با یک حالت دسترسی صریح به مسیری در کانتینر نگاشت می‌کند:

host-directory:container-directory:rohost-directory:container-directory:rw

• ro پوشه mountشده را درون sandbox فقط‌خواندنی می‌کند.
• rw به ابزارها و فرایندهای درون sandbox اجازه می‌دهد پوشه میزبان را تغییر دهند.
• مسیر کانتینر، مسیری است که agent استفاده می‌کند. مسیرهای میزبان به‌طور خودکار آشکار نمی‌شوند.

این نمونه به agent با شناسه research یک فضای کاری اصلی قابل‌نوشتن، منابع مرجع فقط‌خواندنی در /reference و یک پوشه خروجی قابل‌نوشتن مجزا در /drafts می‌دهد:

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // الزامی است، زیرا این منابع خارج از فضای کاری agent قرار دارند.            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess و حالت‌های bind مستقل از یکدیگرند:

تغییر workspaceAccess یک bind اضافی را از ro به rw یا برعکس تغییر نمی‌دهد. docker.binds سراسری و مختص هر agent با هم ادغام می‌شوند. برای bindهای مختص هر agent، scope: "agent" یا "session" را نگه دارید؛ scope: "shared" تمام overrideهای Docker مختص هر agent را نادیده می‌گیرد و فقط از bindهای سراسری استفاده می‌کند.

Bind mountها مرز پشتیبانی‌شده برای چند پوشه هستند، زیرا Docker نمای سیستم فایل کانتینر را با جداسازی mount می‌سازد و حالت ro/rw بر همه فرایندهای sandbox اعمال می‌شود. این مرز، exec، ابزارهای سیستم فایل، فرایندهای فرزند و کتابخانه‌ها را پوشش می‌دهد، بدون آنکه بررسی‌های مجوز مسیر در هر مسیر کد OpenClaw تکرار شوند. یک فهرست مجاز مسیر در سمت میزبان نمی‌تواند همان مرز کامل را فراهم کند، زیرا یک shell یا وابستگی مجاز می‌تواند مستقیماً به فایل‌ها دسترسی پیدا کند.

dangerouslyAllowExternalBindSources اختیاری فقط منابع خارج از ریشه‌های فضای کاری را مجاز می‌کند. این گزینه بررسی‌های OpenClaw برای سیستم مسدودشده، اعتبارنامه‌ها، socket مربوط به Docker، والد symlink یا مقصدهای رزروشده را غیرفعال نمی‌کند. کوچک‌ترین پوشه را ترجیح دهید، مگر زمانی که نوشتن لازم است از ro استفاده کنید و پس از تغییر mountها sandbox را دوباره ایجاد کنید:

openclaw sandbox recreate --agent research

سایر رفتارهای bind

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

agents.defaults.sandbox.browser.binds دایرکتوری‌های میزبان اضافی را فقط در کانتینر مرورگر sandbox mount می‌کند. وقتی تنظیم شده باشد (از جمله []) جایگزین 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"],          },        },      },    ],  },}

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

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

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

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

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

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

مسیرها:

• سراسری: agents.defaults.sandbox.docker.setupCommand
• برای هر عامل: agents.entries.*.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.entries.*.sandbox و agents.entries.*.tools (به‌علاوه agents.entries.*.tools.sandbox.tools برای سیاست ابزار سندباکس). برای تقدم، به سندباکس و ابزارهای چندعاملی مراجعه کنید.

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

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

مرتبط

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