OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

محیط ایزوله در برابر خط‌مشی ابزار در برابر دسترسی ارتقایافته

Status: active

OpenClaw سه کنترل مرتبط اما متفاوت دارد:

  1. سندباکس (agents.defaults.sandbox.* / agents.list[].sandbox.*) تعیین می‌کند ابزارها کجا اجرا شوند (بک‌اند سندباکس یا میزبان).
  2. سیاست ابزار (tools.*، tools.sandbox.tools.*، agents.list[].tools.*) تعیین می‌کند کدام ابزارها در دسترس/مجاز باشند.
  3. حالت ارتقایافته (tools.elevated.*، agents.list[].tools.elevated.*) یک راه گریز مختص exec برای اجرای خارج از سندباکس در هنگام اجرای سندباکسی است (به‌طور پیش‌فرض gateway، یا هنگامی که مقصد اجرای exec روی node تنظیم شده باشد، node).

اشکال‌زدایی سریع

برای دیدن اینکه OpenClaw در عمل چه می‌کند، از بازرس استفاده کنید:

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

این فرمان موارد زیر را نمایش می‌دهد:

  • حالت/دامنه/دسترسی مؤثر سندباکس به فضای کاری
  • اینکه نشست در حال حاضر سندباکسی است یا نه (اصلی در برابر غیراصلی)
  • مجوز/رد مؤثر ابزارهای سندباکس (و اینکه از عامل، تنظیم سراسری یا پیش‌فرض آمده است)
  • دروازه‌های حالت ارتقایافته و مسیر کلیدهای اصلاح

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

سندباکس‌سازی با agents.defaults.sandbox.mode کنترل می‌شود:

  • "off": همه‌چیز روی میزبان اجرا می‌شود.
  • "non-main": فقط نشست‌های غیراصلی سندباکسی می‌شوند (غافلگیری رایج در گروه‌ها/کانال‌ها).
  • "all": همه‌چیز سندباکسی می‌شود.

agents.defaults.sandbox.workspaceAccess تعیین می‌کند سندباکس چه چیزهایی را می‌تواند ببیند: "none"، "ro" یا "rw".

برای ماتریس کامل (دامنه، اتصال‌های فضای کاری، تصویرها) به سندباکس‌سازی مراجعه کنید.

اتصال‌های bind (بررسی سریع امنیتی)

  • docker.binds از سامانه فایل سندباکس عبور می‌کند: هرچه متصل کنید، با حالت تعیین‌شده (:ro یا :rw) داخل کانتینر قابل مشاهده است.
  • اگر حالت را حذف کنید، پیش‌فرض خواندن‌ونوشتن است؛ برای کد منبع/اسرار، :ro را ترجیح دهید.
  • scope: "shared" اتصال‌های مختص هر عامل را نادیده می‌گیرد (فقط اتصال‌های سراسری اعمال می‌شوند).
  • OpenClaw منابع اتصال را دو بار اعتبارسنجی می‌کند: نخست روی مسیر منبع نرمال‌شده و سپس دوباره پس از رفع مسیر از طریق عمیق‌ترین جد موجود. گریز از طریق والد پیوند نمادین نمی‌تواند بررسی مسیرهای مسدود یا ریشه‌های مجاز را دور بزند.
  • مسیرهای برگ ناموجود نیز به‌طور ایمن بررسی می‌شوند. اگر /workspace/alias-out/new-file از طریق یک والد دارای پیوند نمادین به مسیری مسدود یا خارج از ریشه‌های مجاز پیکربندی‌شده رفع شود، اتصال رد می‌شود.
  • اتصال /var/run/docker.sock عملاً کنترل میزبان را به سندباکس واگذار می‌کند؛ این کار را فقط آگاهانه انجام دهید.
  • دسترسی به فضای کاری (workspaceAccess) مستقل از حالت‌های اتصال است.

سیاست ابزار: کدام ابزارها وجود دارند/قابل فراخوانی هستند

دو لایه اهمیت دارند:

  • پروفایل ابزار: tools.profile و agents.list[].tools.profile (فهرست مجاز پایه)
  • پروفایل ابزار ارائه‌دهنده: tools.byProvider[provider].profile و agents.list[].tools.byProvider[provider].profile
  • سیاست ابزار سراسری/مختص عامل: tools.allow/tools.deny و agents.list[].tools.allow/agents.list[].tools.deny
  • سیاست ابزار ارائه‌دهنده: tools.byProvider[provider].allow/deny و agents.list[].tools.byProvider[provider].allow/deny
  • سیاست ابزار سندباکس (فقط هنگام اجرای سندباکسی اعمال می‌شود): tools.sandbox.tools.allow/tools.sandbox.tools.deny و agents.list[].tools.sandbox.tools.*

قواعد کلی:

  • deny همیشه اولویت دارد.
  • اگر allow خالی نباشد، هر چیز دیگری مسدود تلقی می‌شود.
  • سیاست ابزار مانع قطعی است: /exec نمی‌تواند ممنوعیت ابزار exec را نادیده بگیرد.
  • سیاست ابزار، دسترس‌پذیری ابزارها را بر اساس نام پالایش می‌کند؛ اثرات جانبی داخل exec را بررسی نمی‌کند. اگر exec مجاز باشد، ممنوع‌کردن write، edit یا apply_patch فرمان‌های پوسته را فقط‌خواندنی نمی‌کند.
  • /exec فقط پیش‌فرض‌های نشست را برای فرستندگان مجاز تغییر می‌دهد؛ دسترسی به ابزار اعطا نمی‌کند.
  • کلیدهای ابزار ارائه‌دهنده، هم provider (برای مثال google-antigravity) و هم provider/model (برای مثال openai/gpt-5.4) را می‌پذیرند.
  • وقتی یکی از مراحل سیاست ابزار، ابزارهایی را حذف کند یا سیاست ابزار سندباکس فراخوانی‌ای را مسدود کند، گزارش‌های Gateway شامل ورودی‌های ممیزی agents/tool-policy می‌شوند. برای دیدن برچسب قاعده، کلید پیکربندی و نام ابزارهای تحت‌تأثیر، از openclaw logs استفاده کنید.

گروه‌های ابزار (میان‌برها)

سیاست‌های ابزار (سراسری، عامل، سندباکس) از ورودی‌های group:* پشتیبانی می‌کنند که به چند ابزار گسترش می‌یابند:

json5
{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

گروه‌های موجود:

گروه ابزارها
group:runtime exec، process، code_execution (bash به‌عنوان نام مستعار exec پذیرفته می‌شود)
group:fs read، write، edit، apply_patch
group:sessions sessions_list، sessions_history، sessions_send، sessions_spawn، sessions_yield، subagents، session_status
group:memory memory_search، memory_get
group:web web_search، x_search، web_fetch
group:ui browser، canvas
group:automation heartbeat_respond، cron، gateway
group:messaging message
group:nodes nodes، computer
group:agents agents_list، get_goal، create_goal، update_goal، update_plan، skill_workshop
group:media image، image_generate، music_generate، video_generate، tts
group:openclaw بیشتر ابزارهای داخلی OpenClaw (به‌جز ابزارهای ابتدایی سامانه فایل و زمان اجرا یعنی read/write/edit/apply_patch/exec/process، همچنین canvas و Pluginهای ارائه‌دهنده)
group:plugins همه ابزارهای متعلق به Pluginهای بارگذاری‌شده، از جمله سرورهای MCP پیکربندی‌شده که از طریق bundle-mcp ارائه می‌شوند

برای عامل‌های فقط‌خواندنی، علاوه بر ابزارهای تغییردهنده سامانه فایل، group:runtime را نیز ممنوع کنید؛ مگر اینکه سیاست سامانه فایل سندباکس یا مرز میزبان جداگانه‌ای محدودیت فقط‌خواندنی را اعمال کند.

برای سرورهای MCP سندباکسی، سیاست ابزار سندباکس یک دروازه مجوز دوم است. اگر mcp.servers پیکربندی شده است اما نوبت‌های سندباکسی فقط ابزارهای داخلی را نشان می‌دهند، bundle-mcp، group:plugins یا نام/الگوی سراسری ابزار MCP با پیشوند سرور، مانند outlook__send_mail یا outlook__* را به tools.sandbox.tools.alsoAllow اضافه کنید؛ سپس Gateway را راه‌اندازی مجدد/بازبارگذاری کنید و فهرست ابزارها را دوباره ثبت کنید. الگوهای سراسری سرور از پیشوند سرور MCP ایمن برای ارائه‌دهنده استفاده می‌کنند: نویسه‌های غیر از [A-Za-z0-9_-] به - تبدیل می‌شوند، نام‌هایی که با حرف شروع نمی‌شوند پیشوند mcp- می‌گیرند و پیشوندهای طولانی یا تکراری ممکن است کوتاه شوند یا پسوند بگیرند.

openclaw doctor در حال حاضر این ساختار را برای سرورهای مدیریت‌شده توسط OpenClaw در mcp.servers بررسی می‌کند. سرورهای MCP بارگذاری‌شده از مانیفست‌های Plugin همراه یا فایل .mcp.json مربوط به Claude از همان دروازه سندباکس استفاده می‌کنند، اما این ابزار تشخیصی هنوز آن منابع را فهرست نمی‌کند؛ اگر ابزارهایشان در نوبت‌های سندباکسی ناپدید شدند، از همان ورودی‌های فهرست مجاز استفاده کنید.

حالت ارتقایافته: «اجرا روی میزبان» مختص exec

حالت ارتقایافته ابزارهای بیشتری اعطا نمی‌کند؛ فقط بر exec اثر می‌گذارد.

  • اگر در سندباکس هستید، /elevated on (یا exec با elevated: true) خارج از سندباکس اجرا می‌شود (ممکن است همچنان تأیید لازم باشد).
  • برای ردکردن تأییدهای exec در نشست، از /elevated full استفاده کنید.
  • اگر از قبل به‌طور مستقیم اجرا می‌کنید، حالت ارتقایافته عملاً بی‌اثر است (اما همچنان مشمول دروازه‌هاست).
  • حالت ارتقایافته به Skills محدود نیست و مجوز/رد ابزار را نادیده نمی‌گیرد.
  • حالت ارتقایافته از host=auto امکان نادیده‌گرفتن دلخواه میزبان‌های دیگر را نمی‌دهد؛ از قواعد عادی مقصد اجرای exec پیروی می‌کند و فقط زمانی node را حفظ می‌کند که مقصد پیکربندی‌شده/نشست از قبل node باشد.
  • /exec از حالت ارتقایافته جداست. این فرمان فقط پیش‌فرض‌های exec هر نشست را برای فرستندگان مجاز تنظیم می‌کند.

دروازه‌ها:

  • فعال‌سازی: tools.elevated.enabled (و در صورت نیاز agents.list[].tools.elevated.enabled)
  • فهرست‌های مجاز فرستندگان: tools.elevated.allowFrom.<provider> (و در صورت نیاز agents.list[].tools.elevated.allowFrom.<provider>)

به حالت ارتقایافته مراجعه کنید.

رفع مشکلات رایج «حبس سندباکس»

«ابزار X توسط سیاست ابزار سندباکس مسدود شده است»

کلیدهای اصلاح (یکی را انتخاب کنید):

  • سندباکس را غیرفعال کنید: agents.defaults.sandbox.mode=off (یا برای هر عامل agents.list[].sandbox.mode=off)
  • ابزار را داخل سندباکس مجاز کنید:
    • آن را از tools.sandbox.tools.deny حذف کنید (یا برای هر عامل از agents.list[].tools.sandbox.tools.deny)
    • یا آن را به tools.sandbox.tools.allow اضافه کنید (یا فهرست مجاز مختص عامل)
  • در openclaw logs ورودی agents/tool-policy را بررسی کنید. این ورودی حالت سندباکس و اینکه قاعده مجوز یا رد ابزار را مسدود کرده است ثبت می‌کند.

«فکر می‌کردم این نشست اصلی است؛ چرا سندباکسی شده است؟»

در حالت "non-main"، کلیدهای گروه/کانال، اصلی نیستند. از کلید نشست اصلی (نمایش‌داده‌شده توسط sandbox explain) استفاده کنید یا حالت را به "off" تغییر دهید.

مرتبط

Was this useful?
On this page

On this page