OpenShell

OpenShell یک بک‌اند سندباکس مدیریت‌شده برای OpenClaw است. به‌جای اجرای کانتینرهای Docker به‌صورت محلی، OpenClaw چرخه عمر سندباکس را به CLI openshell واگذار می‌کند؛ این CLI محیط‌های راه دور را با اجرای فرمان مبتنی بر SSH فراهم می‌کند.

Plugin مربوط به OpenShell همان انتقال SSH هسته و پل سیستم فایل راه دوری را بازاستفاده می‌کند که بک‌اند عمومی SSH از آن استفاده می‌کند. این Plugin چرخه عمر اختصاصی OpenShell (sandbox create/get/delete, sandbox ssh-config) و یک حالت اختیاری فضای کاری mirror را اضافه می‌کند.

پیش‌نیازها

• Plugin مربوط به OpenShell نصب شده باشد (openclaw plugins install @openclaw/openshell-sandbox)
• CLI مربوط به openshell نصب شده و در PATH باشد (یا مسیر سفارشی را از طریق plugins.entries.openshell.config.command تنظیم کنید)
• یک حساب OpenShell با دسترسی به سندباکس
• OpenClaw Gateway روی میزبان در حال اجرا باشد

شروع سریع

1. Plugin را نصب و فعال کنید، سپس بک‌اند سندباکس را تنظیم کنید:

openclaw plugins install @openclaw/openshell-sandbox

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

2. Gateway را راه‌اندازی مجدد کنید. در نوبت بعدی عامل، OpenClaw یک سندباکس OpenShell ایجاد می‌کند و اجرای ابزارها را از طریق آن مسیریابی می‌کند.

3. راستی‌آزمایی:

openclaw sandbox listopenclaw sandbox explain

حالت‌های فضای کاری

این مهم‌ترین تصمیم هنگام استفاده از OpenShell است.

mirror

وقتی می‌خواهید فضای کاری محلی مرجع باقی بماند، از plugins.entries.openshell.config.mode: "mirror" استفاده کنید.

رفتار:

• پیش از exec، OpenClaw فضای کاری محلی را در سندباکس OpenShell همگام‌سازی می‌کند.
• پس از exec، OpenClaw فضای کاری راه دور را دوباره با فضای کاری محلی همگام‌سازی می‌کند.
• ابزارهای فایل همچنان از طریق پل سندباکس عمل می‌کنند، اما فضای کاری محلی بین نوبت‌ها منبع حقیقت باقی می‌ماند.

مناسب برای:

• فایل‌ها را بیرون از OpenClaw به‌صورت محلی ویرایش می‌کنید و می‌خواهید آن تغییرات به‌طور خودکار در سندباکس دیده شوند.
• می‌خواهید سندباکس OpenShell تا جای ممکن شبیه بک‌اند Docker رفتار کند.
• می‌خواهید فضای کاری میزبان پس از هر نوبت exec، نوشتن‌های سندباکس را منعکس کند.

مصالحه: هزینه همگام‌سازی بیشتر پیش و پس از هر exec.

remote

وقتی می‌خواهید فضای کاری OpenShell مرجع شود، از plugins.entries.openshell.config.mode: "remote" استفاده کنید.

رفتار:

• وقتی سندباکس برای نخستین بار ایجاد می‌شود، OpenClaw یک بار فضای کاری راه دور را از فضای کاری محلی بذرگذاری می‌کند.
• پس از آن، exec، read، write، edit و apply_patch مستقیماً روی فضای کاری راه دور OpenShell عمل می‌کنند.
• OpenClaw تغییرات راه دور را به فضای کاری محلی همگام‌سازی نمی‌کند.
• خواندن رسانه در زمان پرامپت همچنان کار می‌کند، چون ابزارهای فایل و رسانه از طریق پل سندباکس می‌خوانند.

مناسب برای:

• سندباکس باید عمدتاً در سمت راه دور زندگی کند.
• می‌خواهید سربار همگام‌سازی در هر نوبت کمتر باشد.
• نمی‌خواهید ویرایش‌های محلی میزبان بی‌صدا وضعیت سندباکس راه دور را بازنویسی کنند.

انتخاب حالت

مرجع پیکربندی

همه پیکربندی OpenShell زیر plugins.entries.openshell.config قرار دارد:

تنظیمات سطح سندباکس (mode، scope، workspaceAccess) مانند هر بک‌اند دیگری زیر agents.defaults.sandbox پیکربندی می‌شوند. برای ماتریس کامل، سندباکس‌گذاری را ببینید.

نمونه‌ها

راه‌اندازی راه دور حداقلی

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

حالت Mirror با GPU

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "agent",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "mirror",          gpu: true,          providers: ["openai"],          timeoutSeconds: 180,        },      },    },  },}

OpenShell برای هر عامل با Gateway سفارشی

{  agents: {    defaults: {      sandbox: { mode: "off" },    },    list: [      {        id: "researcher",        sandbox: {          mode: "all",          backend: "openshell",          scope: "agent",          workspaceAccess: "rw",        },      },    ],  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",          gateway: "lab",          gatewayEndpoint: "https://lab.example",          policy: "strict",        },      },    },  },}

مدیریت چرخه عمر

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

# List all sandbox runtimes (Docker + OpenShell)openclaw sandbox list # Inspect effective policyopenclaw sandbox explain # Recreate (deletes remote workspace, re-seeds on next use)openclaw sandbox recreate --all

برای حالت remote، recreate اهمیت ویژه‌ای دارد: این کار فضای کاری راه دور مرجع را برای آن دامنه حذف می‌کند. استفاده بعدی یک فضای کاری راه دور تازه را از فضای کاری محلی بذرگذاری می‌کند.

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

چه زمانی recreate کنیم

پس از تغییر هرکدام از موارد زیر recreate کنید:

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

سخت‌سازی امنیتی

OpenShell ریشه فضای کاری fd را ثابت نگه می‌دارد و پیش از هر read هویت سندباکس را دوباره بررسی می‌کند، بنابراین جابه‌جایی symlink یا mount دوباره فضای کاری نمی‌تواند خواندن‌ها را به بیرون از فضای کاری راه دور موردنظر هدایت کند.

محدودیت‌های فعلی

• مرورگر سندباکس در بک‌اند OpenShell پشتیبانی نمی‌شود.
• sandbox.docker.binds روی OpenShell اعمال نمی‌شود.
• تنظیمات runtime اختصاصی Docker زیر sandbox.docker.* فقط روی بک‌اند Docker اعمال می‌شوند.

نحوه کار

1. OpenClaw فرمان openshell sandbox create را فراخوانی می‌کند (با پرچم‌های --from، --gateway، --policy، --providers، --gpu مطابق پیکربندی).
2. OpenClaw برای دریافت جزئیات اتصال SSH سندباکس، openshell sandbox ssh-config <name> را فراخوانی می‌کند.
3. هسته پیکربندی SSH را در یک فایل موقت می‌نویسد و با استفاده از همان پل سیستم فایل راه دورِ بک‌اند عمومی SSH، یک نشست SSH باز می‌کند.
4. در حالت mirror: پیش از exec از محلی به راه دور همگام‌سازی می‌کند، اجرا می‌کند، و پس از exec دوباره همگام می‌کند.
5. در حالت remote: هنگام ایجاد یک بار بذرگذاری می‌کند، سپس مستقیماً روی فضای کاری راه دور عمل می‌کند.

مرتبط

• سندباکس‌گذاری -- حالت‌ها، دامنه‌ها و مقایسه بک‌اندها
• سندباکس در برابر خط‌مشی ابزار در برابر Elevated -- اشکال‌زدایی ابزارهای مسدودشده
• سندباکس و ابزارهای چندعاملی -- بازنویسی‌های هر عامل
• CLI سندباکس -- فرمان‌های openclaw sandbox