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 در اجرای بعدی exec ظاهر می‌شوند و رفتار سندباکس به بک‌اند Docker نزدیک است.

هزینه: هزینهٔ بارگذاری و بارگیری در هر نوبت exec.

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) دوباره بررسی می‌کند و پیوندهای نمادین میانی را رد می‌کند. تعویض پیوند نمادین یا اتصال مجدد فضای کاری نمی‌تواند دسترسی فایل را به خارج از درخت آینه‌شده هدایت کند.

محدودیت‌های کنونی

• مرورگر سندباکس در بک‌اند 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: پیش از exec محیط محلی با راه‌دور همگام می‌شود، فرمان اجرا می‌شود و سپس تغییرات به محیط محلی بازگردانده می‌شوند.
5. در حالت remote: هنگام ایجاد فقط یک‌بار مقداردهی می‌شود و سپس عملیات مستقیماً روی فضای کاری راه‌دور انجام می‌شوند.

مرتبط

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