OpenShell

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

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

پیش‌نیازها

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

شروع سریع

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

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

openclaw sandbox listopenclaw sandbox explain

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

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

mirror (پیش‌فرض)

plugins.entries.openshell.config.mode: "mirror" فضای کاری محلی را مرجع اصلی نگه می‌دارد:

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

مناسب‌ترین گزینه برای جریان‌های کاری توسعه: ویرایش‌های محلی خارج از OpenClaw در اجرای بعدی ظاهر می‌شوند و رفتار سندباکس به بک‌اند Docker نزدیک است.

نقطه‌ضعف: هزینهٔ بارگذاری و بارگیری در هر نوبت اجرا.

remote

mode: "remote" فضای کاری OpenShell را مرجع اصلی می‌کند:

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

مناسب‌ترین گزینه برای عامل‌های طولانی‌مدت و CI: سربار کمتر در هر نوبت، و ویرایش‌های محلی میزبان نمی‌توانند بی‌سروصدا وضعیت راه‌دور را بازنویسی کنند.

انتخاب حالت

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

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

remoteWorkspaceDir و remoteAgentWorkspaceDir باید مسیرهای مطلق باشند و زیر ریشه‌های مدیریت‌شدهٔ /sandbox یا /agent باقی بمانند؛ سایر مسیرهای مطلق رد می‌شوند.

تنظیمات سطح سندباکس (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",        },      },    },  },}

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

# فهرست همهٔ محیط‌های اجرایی سندباکس (Docker + OpenShell)openclaw sandbox list # بررسی سیاست مؤثرopenclaw sandbox explain # ایجاد مجدد (فضای کاری راه‌دور را حذف می‌کند و در استفادهٔ بعدی دوباره مقداردهی می‌شود)openclaw sandbox recreate --all

در حالت remote، ایجاد مجدد اهمیت ویژه‌ای دارد: فضای کاری راه‌دورِ مرجع را برای آن دامنه حذف می‌کند و استفادهٔ بعدی، فضای تازه‌ای را از محیط محلی مقداردهی می‌کند. در حالت mirror، ایجاد مجدد عمدتاً محیط اجرای راه‌دور را بازنشانی می‌کند، زیرا محیط محلی مرجع باقی می‌ماند.

پس از تغییر هر یک از موارد زیر، سندباکس را دوباره ایجاد کنید:

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

مقاوم‌سازی امنیتی

پل سیستم فایل در حالت mirror، ریشهٔ فضای کاری محلی را ثابت نگه می‌دارد و پیش از هر خواندن، نوشتن، mkdir، حذف و تغییر نام، مسیرهای مرجع را (از طریق realpath) دوباره بررسی می‌کند و پیوندهای نمادین میان‌مسیر را رد می‌کند. تعویض پیوند نمادین یا اتصال مجدد فضای کاری نمی‌تواند دسترسی فایل را به خارج از درخت mirrorشده هدایت کند.

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

• مرورگر سندباکس در بک‌اند OpenShell پشتیبانی نمی‌شود.
• sandbox.docker.binds برای OpenShell اعمال نمی‌شود؛ اگر اتصال‌ها پیکربندی شده باشند، ایجاد سندباکس ناموفق خواهد بود.
• گزینه‌های زمان اجرای ویژهٔ Docker زیر sandbox.docker.* (به‌جز env) فقط برای بک‌اند Docker اعمال می‌شوند.

نحوهٔ کار

1. OpenClaw برای نام سندباکس، sandbox get را اجرا می‌کند (با هر --gateway/--gateway-endpoint پیکربندی‌شده)؛ اگر ناموفق باشد، با sandbox create یک سندباکس ایجاد می‌کند و --name، --from، --policy را در صورت تنظیم، --gpu را در صورت فعال بودن، --auto-providers/--no-auto-providers و برای هر ارائه‌دهندهٔ پیکربندی‌شده یک پرچم --provider ارسال می‌کند.
2. OpenClaw برای نام سندباکس، sandbox ssh-config را اجرا می‌کند تا جزئیات اتصال SSH را دریافت کند.
3. هسته پیکربندی SSH را در یک فایل موقت می‌نویسد و از طریق همان پل سیستم فایل راه‌دورِ بک‌اند SSH عمومی، یک نشست SSH باز می‌کند.
4. در حالت mirror: پیش از اجرا محیط محلی با راه‌دور همگام می‌شود، اجرا انجام می‌شود و سپس محیط راه‌دور با محلی همگام می‌شود.
5. در حالت remote: هنگام ایجاد فقط یک‌بار مقداردهی می‌شود و سپس عملیات مستقیماً روی فضای کاری راه‌دور انجام می‌شوند.

مرتبط

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