ابزار اجرا

اجرای فرمان‌های پوسته در فضای کاری. exec یک سطح پوستهٔ تغییردهنده است: فرمان‌ها می‌توانند در هر جایی که فایل‌سیستم میزبان یا سندباکس انتخاب‌شده اجازه می‌دهد، فایل ایجاد، ویرایش یا حذف کنند. غیرفعال‌کردن ابزارهای فایل‌سیستم OpenClaw مانند write، edit یا apply_patch، exec را فقط‌خواندنی نمی‌کند.

از اجرای پیش‌زمینه و پس‌زمینه از طریق process پشتیبانی می‌کند. اگر process مجاز نباشد، exec به‌صورت همگام اجرا می‌شود و yieldMs/background را نادیده می‌گیرد. نشست‌های پس‌زمینه به هر عامل محدودند؛ process فقط نشست‌های همان عامل را می‌بیند.

پارامترها

نکته‌ها:

• host فقط auto، sandbox، gateway یا node را می‌پذیرد. این گزینه انتخاب‌کنندهٔ نام میزبان نیست؛ مقادیر شبیه نام میزبان پیش از اجرای فرمان رد می‌شوند.
• host=node هر فراخوانی از auto مجاز است؛ host=gateway هر فراخوانی فقط زمانی مجاز است که هیچ زمان‌اجرای سندباکسی فعال نباشد.
• بدون پیکربندی اضافه، host=auto همچنان «به‌سادگی کار می‌کند»: نبود سندباکس باعث می‌شود به gateway تبدیل شود؛ وجود سندباکس فعال باعث می‌شود در سندباکس باقی بماند.
• elevated از سندباکس خارج و وارد مسیر پیکربندی‌شدهٔ میزبان می‌شود: به‌طور پیش‌فرض gateway، یا وقتی tools.exec.host=node (یا مقدار پیش‌فرض نشست host=node است)، node. این گزینه فقط زمانی در دسترس است که دسترسی ارتقایافته برای نشست/ارائه‌دهندهٔ فعلی فعال باشد.
• تأییدهای gateway/node توسط فایل تأییدهای میزبان کنترل می‌شوند.
• node به یک Node جفت‌شده (برنامهٔ همراه یا میزبان Node بدون رابط) نیاز دارد. اگر چند Node در دسترس است، برای انتخاب یکی exec.node یا tools.exec.node را تنظیم کنید.
• exec host=node تنها مسیر اجرای پوسته برای Nodeها است؛ پوشش قدیمی nodes.run حذف شده است.
• در میزبان‌های غیر Windows، اگر SHELL تنظیم شده باشد، exec از آن استفاده می‌کند؛ اگر SHELL برابر با fish باشد، برای جلوگیری از ناسازگاری ساختارهای bash با fish، bash (یا sh) را از PATH ترجیح می‌دهد و اگر هیچ‌کدام وجود نداشته باشند، به SHELL برمی‌گردد.
• در میزبان‌های Windows، exec ابتدا کشف PowerShell 7 (pwsh) را ترجیح می‌دهد (Program Files، سپس ProgramW6432 و بعد PATH) و پس از آن به Windows PowerShell 5.1 برمی‌گردد.
• در میزبان‌های غیر Windows مربوط به Gateway، فرمان‌های exec در bash و zsh از یک تصویر لحظه‌ای راه‌اندازی استفاده می‌کنند. OpenClaw نام‌های مستعار/توابع قابل منبع‌دهی و مجموعهٔ کوچک و امنی از محیط را از فایل‌های راه‌اندازی پوسته در $OPENCLAW_STATE_DIR/cache/shell-snapshots/ ثبت می‌کند و سپس پیش از هر فرمان exec آن تصویر لحظه‌ای را منبع‌دهی می‌کند. متغیرهایی که شبیه اطلاعات محرمانه‌اند حذف می‌شوند؛ exec در سندباکس و Node از این تصویر لحظه‌ای استفاده نمی‌کند. برای غیرفعال‌کردن این مسیر تصویر لحظه‌ای، OPENCLAW_EXEC_SHELL_SNAPSHOT=0 را در محیط فرایند Gateway تنظیم کنید.
• اجرای میزبان (gateway/node) برای جلوگیری از ربایش فایل اجرایی یا تزریق کد، env.PATH و بازنویسی‌های بارگذار (LD_*/DYLD_*) را رد می‌کند.
• OpenClaw متغیر OPENCLAW_SHELL=exec را در محیط فرمان ایجادشده (از جمله اجرای PTY و سندباکس) تنظیم می‌کند تا قواعد پوسته/پروفایل بتوانند زمینهٔ ابزار exec را تشخیص دهند.
• برای اجراهای با منشأ کانال، اگر کانال آن شناسه‌ها را ارائه کرده باشد، OpenClaw همچنین یک بار JSON محدود شامل هویت فرستنده/گفت‌وگو را در OPENCLAW_CHANNEL_CONTEXT در دسترس قرار می‌دهد.
• exec نمی‌تواند فرمان‌های پوستهٔ openclaw channels login یا /approve را اجرا کند: openclaw channels login یک جریان تعاملی احراز هویت کانال است و /approve باید از کنترل‌کنندهٔ فرمان تأیید عبور کند، نه از پوسته. ورود کانال را در ترمینالی روی میزبان Gateway اجرا کنید، یا در صورت وجود از ابزار عامل ورود مختص کانال استفاده کنید (برای مثال whatsapp_login).
• مهم: سندباکس به‌طور پیش‌فرض غیرفعال است. اگر سندباکس غیرفعال باشد، host=auto ضمنی به gateway تبدیل می‌شود. host=sandbox صریح همچنان به‌صورت بسته و ایمن شکست می‌خورد و بی‌سروصدا روی میزبان Gateway اجرا نمی‌شود. سندباکس را فعال کنید یا از host=gateway همراه با تأییدها استفاده کنید.
• بررسی‌های پیش‌اجرای اسکریپت (برای اشتباهات رایج نحو پوسته در Python/Node) فقط فایل‌های داخل محدودهٔ مؤثر workdir را بررسی می‌کنند. اگر مسیر اسکریپت به خارج از workdir منتهی شود، پیش‌اجرا برای آن فایل رد می‌شود. همچنین وقتی host=gateway و سیاست مؤثر security=full همراه با ask=off باشد، پیش‌اجرا به‌طور کامل رد می‌شود.
• برای کار طولانی‌مدتی که اکنون آغاز می‌شود، آن را یک‌بار شروع کنید و در صورت فعال‌بودن بیدارسازی خودکار تکمیل و خروجی‌دادن یا شکست فرمان، به آن تکیه کنید. برای گزارش‌ها، وضعیت، ورودی یا مداخله از process استفاده کنید؛ زمان‌بندی را با حلقه‌های خواب، حلقه‌های مهلت یا نظرسنجی مکرر شبیه‌سازی نکنید.
• فرمان‌های پس‌زمینه‌ای که عامل آغاز می‌کند تا زمان پایان در نماهای وظایف پس‌زمینهٔ Web، iOS و Android نمایش داده می‌شوند. دفتر وظایف پیش از آنکه Heartbeat تکمیل دوباره عامل را بیدار کند، نهایی می‌شود.
• برای کاری که باید بعداً یا طبق برنامه انجام شود، به‌جای الگوهای خواب/تأخیر exec از Cron استفاده کنید.

پیکربندی

اجرای میزبان بدون تأیید برای Gateway و Node (mode=full) پیش‌فرض است — این رفتار از پیش‌فرض‌های سیاست میزبان می‌آید، نه از host=auto. اگر رفتار تأیید/فهرست مجاز را می‌خواهید، tools.exec.mode را تنظیم و فایل تأییدهای میزبان را سخت‌گیرانه‌تر کنید؛ تأییدهای Exec را ببینید. برای تحمیل مسیریابی Gateway یا Node بدون توجه به وضعیت سندباکس، tools.exec.host را تنظیم کنید یا از /exec host=... استفاده کنید.

مثال:

{  tools: {    exec: {      pathPrepend: ["~/bin", "/opt/oss/bin"],    },  },}

حالت‌ها

tools.exec.mode کنترل سیاست متعارف و ماندگار است. رفتار امنیت و تأیید زمان‌اجرا از آن به‌دست می‌آید.

مقدار مختص هر نشستِ /exec ask=always، صرف‌نظر از حالت ذخیره‌شده، همچنان هر بار از انسان می‌پرسد.

تأیید بازبینی خودکار یک‌بارمصرف است. در Gateway، OpenClaw مسیر اجرایی حل‌شده را به بازبین ارائه می‌کند و اجرا را به همان مسیر مقید می‌سازد. فرمان‌هایی که نتوان آن‌ها را به یک برنامه اجرایی قابل‌اعمال فروکاست—مانند heredocها، بسط‌های پوسته یا نقل‌قول‌گذاری پشتیبانی‌نشده در لفاف‌ها—حتی اگر مدل در حالت عادی آن‌ها را مجاز بداند، به تأیید انسانی بازمی‌گردند.

تأییدهای فرمان app-server در Codex که از پیش توسط سیاست صریح زمان اجرا یا سیاست بومی تعیین نشده‌اند، از مسیر تأیید انسانی استفاده می‌کنند. OpenClaw بازبین اجرای پیکربندی‌شده خود را برای این درخواست‌ها اجرا نمی‌کند، زیرا Codex یک فایل اجرایی حل‌شده و قابل‌اعمال ارائه نمی‌دهد که بتوان تصمیم بازبینی را به فرمانی که Codex اجرا می‌کند مقید ساخت.

ارزیابی درون‌خطی (strictInlineEval)

وقتی tools.exec.strictInlineEval برابر با true است، شکل‌های ارزیابی درون‌خطی مفسر به بازبین یا تأیید صریح نیاز دارند: python -c، node -e، ruby -e، perl -e، php -r، lua -e، osascript -e و شکل‌های مشابه در دیگر مفسرها و حامل‌های فرمان پشتیبانی‌شده (awk، find -exec، make، sed، xargs و موارد دیگر). در mode=auto، مسیر عادی تأیید اجرا ممکن است به بازبین خودکار بومی اجازه دهد یک فرمان یک‌باره و آشکارا کم‌خطر را مجاز کند؛ فراخوانی‌های مستقیم system.run در میزبان Node همچنان به تأیید صریح نیاز دارند، زیرا نمی‌توانند فرمان را به مسیر تأیید انسانی تحویل دهند. اگر بازبین درخواست تأیید کند، درخواست به انسان ارسال می‌شود. allow-always همچنان می‌تواند فراخوانی‌های بی‌خطر مفسر/اسکریپت را ماندگار کند، اما شکل‌های ارزیابی درون‌خطی به قواعد مجازسازی ماندگار تبدیل نمی‌شوند.

مدیریت PATH

• host=gateway: مقدار PATH پوسته ورود شما را در محیط اجرا ادغام می‌کند. بازنویسی‌های env.PATH برای اجرای میزبان رد می‌شوند. خود دیمن همچنان با یک PATH حداقلی اجرا می‌شود:
  • macOS: /opt/homebrew/bin، /usr/local/bin، /usr/bin، /bin
  • Linux: /usr/local/bin، /usr/bin، /bin
  • برای جلوگیری از اینکه پیکربندی پوسته کاربر (مانند ~/.zshenv یا /etc/zshenv) مسیرهای اولویت‌دار را هنگام راه‌اندازی بازنویسی کند، ورودی‌های tools.exec.pathPrepend درست پیش از اجرا، به‌صورت امن درون فرمان پوسته به ابتدای PATH نهایی افزوده می‌شوند.
• host=sandbox: مقدار sh -lc (پوسته ورود) را درون کانتینر اجرا می‌کند، بنابراین /etc/profile ممکن است PATH را بازنشانی کند. OpenClaw پس از بارگذاری پروفایل، env.PATH را از طریق یک متغیر محیطی داخلی به ابتدا می‌افزاید (بدون درون‌یابی پوسته)؛ tools.exec.pathPrepend در اینجا نیز اعمال می‌شود.
• host=node: فقط بازنویسی‌های محیطی مسدودنشده‌ای که ارسال می‌کنید به Node فرستاده می‌شوند. بازنویسی‌های env.PATH برای اجرای میزبان رد و توسط میزبان‌های Node نادیده گرفته می‌شوند. اگر در یک Node به ورودی‌های PATH بیشتری نیاز دارید، محیط سرویس میزبان Node را (در systemd/launchd) پیکربندی کنید یا ابزارها را در مکان‌های استاندارد نصب کنید.

اتصال Node به تفکیک عامل (از شناسه کلیددار عامل در پیکربندی استفاده کنید):

openclaw config get agents.entriesopenclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"

رابط کنترل: صفحه دستگاه‌ها شامل پنل کوچکی با عنوان «اتصال Node اجرا» برای همین تنظیمات است.

بازنویسی‌های نشست (/exec)

از /exec برای تنظیم پیش‌فرض‌های مختص هر نشست برای host، security، ask و node استفاده کنید. برای نمایش مقادیر کنونی، /exec را بدون آرگومان ارسال کنید.

مثال:

/exec host=auto security=allowlist ask=on-miss node=mac-1

/exec فقط برای فرستندگان مجاز از طریق فهرست‌های مجاز کانال/جفت‌سازی و گروه‌های دسترسی پذیرفته می‌شود. اعمال گروه دسترسی همیشه فعال است. این فرمان فقط وضعیت نشست را به‌روزرسانی می‌کند و چیزی در پیکربندی نمی‌نویسد. فرستندگان مجاز کانال‌های خارجی می‌توانند این پیش‌فرض‌های نشست را تنظیم کنند. کلاینت‌های داخلی Gateway/webchat برای ماندگار کردن آن‌ها به operator.admin نیاز دارند.

برای غیرفعال‌سازی کامل اجرا، آن را از طریق سیاست ابزار رد کنید (tools.deny: ["exec"] یا به تفکیک عامل). تأییدهای میزبان همچنان اعمال می‌شوند، مگر اینکه security=full و ask=off را صریحاً تنظیم کنید.

تأییدهای اجرا (برنامه همراه / میزبان Node)

عامل‌های سندباکس‌شده می‌توانند پیش از اجرای exec در Gateway یا میزبان Node، برای هر درخواست به تأیید نیاز داشته باشند. برای سیاست، فهرست مجاز و جریان رابط کاربری، تأییدهای اجرا را ببینید.

وقتی تأیید انسانی لازم باشد، جریان‌های میزبان Node و Gateway غیربومی بلافاصله با status: "approval-pending" و یک شناسه تأیید بازمی‌گردند. در عوض، جریان‌های چت بومی و رابط وب Gateway می‌توانند در همان‌جا منتظر بمانند و پس از تأیید، نتیجه نهایی فرمان را بازگردانند. نتیجه approval-pending به این معناست که فرمان آغاز نشده است؛ بنابراین هشدارهای بازگشت به حالت پیش‌زمینه فقط هنگامی ظاهر می‌شوند که فرمان تأییدشده واقعاً به‌صورت درون‌خطی اجرا شود. اجراهای ناهمگام تأییدشده، رویدادهای سیستمی پیشرفت و تکمیل فرمان را منتشر می‌کنند (Exec running / Exec finished)؛ تأییدهای ردشده یا مهلت‌منقضی نهایی هستند و نشست عامل را با رویداد سیستمی رد بیدار نمی‌کنند.

در کانال‌هایی که کارت‌ها/دکمه‌های بومی تأیید دارند، عامل باید ابتدا به همان رابط بومی تکیه کند و فقط زمانی فرمان دستی /approve را درج کند که نتیجه ابزار صریحاً اعلام کند تأییدهای چت در دسترس نیستند یا تأیید دستی تنها مسیر است.

فهرست مجاز + باینری‌های امن

اعمال دستی فهرست مجاز با الگوهای glob مسیر باینری حل‌شده و الگوهای glob نام ساده فرمان تطبیق می‌یابد. نام‌های ساده فقط با فرمان‌هایی منطبق می‌شوند که از طریق PATH فراخوانی شده‌اند؛ بنابراین rg می‌تواند هنگام rg بودن فرمان با /opt/homebrew/bin/rg منطبق شود، اما با ./rg یا /tmp/rg منطبق نمی‌شود.

وقتی security=allowlist است، فرمان‌های پوسته فقط در صورتی به‌طور خودکار مجاز می‌شوند که هر بخش پایپ‌لاین در فهرست مجاز باشد یا یک باینری امن باشد. زنجیره‌سازی (;، &&، ||) و تغییرمسیرها در حالت فهرست مجاز رد می‌شوند، مگر اینکه هر بخش سطح‌بالا شرایط فهرست مجاز را برآورده کند (از جمله باینری‌های امن). تغییرمسیرها همچنان پشتیبانی نمی‌شوند. اعتماد ماندگار allow-always این قاعده را دور نمی‌زند: یک فرمان زنجیره‌ای همچنان مستلزم تطبیق همه بخش‌های سطح‌بالا است.

autoAllowSkills یک مسیر تسهیل‌گر جداگانه در تأییدهای اجرا است و با ورودی‌های دستی فهرست مجاز مسیر یکسان نیست. برای اعتماد صریح و سخت‌گیرانه، autoAllowSkills را غیرفعال نگه دارید.

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

• tools.exec.safeBins: فیلترهای کوچک جریان که فقط از stdin استفاده می‌کنند.
• tools.exec.safeBinTrustedDirs: دایرکتوری‌های قابل‌اعتماد اضافی و صریح برای مسیر فایل‌های اجرایی باینری امن.
• tools.exec.safeBinProfiles: سیاست صریح argv برای باینری‌های امن سفارشی.
• فهرست مجاز: اعتماد صریح به مسیر فایل‌های اجرایی.

safeBins را یک فهرست مجاز عمومی در نظر نگیرید و باینری‌های مفسر/زمان اجرا (برای مثال python3، node، ruby، bash) را به آن اضافه نکنید. اگر به آن‌ها نیاز دارید، از ورودی‌های صریح فهرست مجاز استفاده کنید و اعلان‌های تأیید را فعال نگه دارید.

openclaw security audit وقتی ورودی‌های مفسر/زمان اجرای safeBins فاقد پروفایل صریح باشند هشدار می‌دهد و openclaw doctor --fix می‌تواند ورودی‌های سفارشی گم‌شده safeBinProfiles را چارچوب‌بندی کند. openclaw security audit و openclaw doctor همچنین وقتی باینری‌های دارای رفتار گسترده مانند jq را صریحاً دوباره به safeBins اضافه کنید هشدار می‌دهند (jq می‌تواند داده‌های محیطی را بخواند و کد jq را از ماژول‌ها یا فایل‌های راه‌اندازی بارگذاری کند؛ بنابراین به‌جای آن ورودی‌های صریح فهرست مجاز یا اجراهای مشروط به تأیید را ترجیح دهید). jq حتی در صورت درج صریح، به‌عنوان باینری امن رد می‌شود. اگر مفسرها را صریحاً در فهرست مجاز قرار می‌دهید، tools.exec.strictInlineEval را فعال کنید تا شکل‌های ارزیابی درون‌خطی کد همچنان به بازبین یا تأیید صریح نیاز داشته باشند.

برای جزئیات کامل سیاست و مثال‌ها، تأییدهای اجرا و باینری‌های امن در برابر فهرست مجاز را ببینید.

مثال‌ها

پیش‌زمینه:

{ "tool": "exec", "command": "ls -la" }

پس‌زمینه + نظرسنجی:

{"tool":"exec","command":"npm run build","yieldMs":1000}{"tool":"process","action":"poll","sessionId":"<id>"}

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

ارسال کلیدها (به سبک tmux):

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

ثبت (فقط ارسال CR):

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

جای‌گذاری (به‌طور پیش‌فرض محصور):

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch

apply_patch زیرابزاری از exec برای ویرایش‌های ساخت‌یافته چندفایلی است. به‌طور پیش‌فرض فعال است و برای هر ارائه‌دهنده مدل در دسترس قرار دارد؛ allowModels می‌تواند آن را محدود کند. فقط زمانی از پیکربندی استفاده کنید که می‌خواهید آن را غیرفعال یا به مدل‌های مشخصی محدود کنید:

{  tools: {    exec: {      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.6-sol"] },    },  },}

نکته‌ها:

• سیاست ابزار همچنان اعمال می‌شود؛ allow: ["write"] به‌طور ضمنی apply_patch را مجاز می‌کند.
• deny: ["write"]، apply_patch را رد نمی‌کند؛ apply_patch را صریحاً رد کنید یا وقتی نوشتن وصله نیز باید مسدود شود از deny: ["group:fs"] استفاده کنید.
• پیکربندی زیر tools.exec.applyPatch قرار دارد.
• مقدار پیش‌فرض tools.exec.applyPatch.enabled برابر با true است؛ برای غیرفعال‌سازی ابزار، آن را روی false تنظیم کنید.
• مقدار پیش‌فرض tools.exec.applyPatch.workspaceOnly برابر با true است (محدود به فضای کاری). فقط زمانی آن را روی false تنظیم کنید که عمداً می‌خواهید apply_patch خارج از دایرکتوری فضای کاری بنویسد/حذف کند.
• tools.exec.applyPatch.allowModels یک فهرست مجاز اختیاری از شناسه‌های مدل است (خام، مانند gpt-5.4، یا کامل، مانند openai/gpt-5.4). وقتی تنظیم شده باشد، فقط مدل‌های منطبق ابزار را دریافت می‌کنند؛ وقتی تنظیم نشده باشد، همه مدل‌ها آن را دریافت می‌کنند.

مرتبط

• تأییدهای اجرا — دروازه‌های تأیید برای فرمان‌های پوسته
• سندباکس‌سازی — اجرای فرمان‌ها در محیط‌های سندباکس‌شده
• فرایند پس‌زمینه — ابزارهای اجرا و فرایند برای کارهای طولانی‌مدت
• امنیت — سیاست ابزار و دسترسی ارتقایافته