ابزار اجرا

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

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

پارامترها

نکات:

• host به‌طور پیش‌فرض auto است: وقتی runtime مربوط به sandbox برای نشست فعال باشد sandbox، و در غیر این صورت gateway.
• host فقط auto، sandbox، gateway، یا node را می‌پذیرد. این گزینه انتخابگر نام میزبان نیست؛ مقدارهای شبیه نام میزبان پیش از اجرای فرمان رد می‌شوند.
• auto راهبرد مسیریابی پیش‌فرض است، نه یک wildcard. host=node در سطح هر فراخوانی از auto مجاز است؛ host=gateway در سطح هر فراخوانی فقط وقتی مجاز است که runtime مربوط به sandbox فعال نباشد.
• بدون پیکربندی اضافه، host=auto همچنان «فقط کار می‌کند»: نبود sandbox یعنی به gateway resolve می‌شود؛ sandbox زنده یعنی داخل sandbox می‌ماند.
• elevated از sandbox به مسیر میزبان پیکربندی‌شده خارج می‌شود: به‌طور پیش‌فرض gateway، یا وقتی tools.exec.host=node باشد (یا پیش‌فرض نشست host=node باشد) node. این قابلیت فقط وقتی در دسترس است که دسترسی elevated برای نشست/ارائه‌دهندهٔ فعلی فعال باشد.
• تأییدهای gateway/node توسط ~/.openclaw/exec-approvals.json کنترل می‌شوند.
• node به یک node جفت‌شده نیاز دارد (companion app یا میزبان node بدون رابط).
• اگر چند node در دسترس باشد، برای انتخاب یکی exec.node یا tools.exec.node را تنظیم کنید.
• exec host=node تنها مسیر اجرای شل برای nodeها است؛ wrapper قدیمی nodes.run حذف شده است.
• timeout برای اجرای پیش‌زمینه، پس‌زمینه، yieldMs، gateway، sandbox، و اجرای system.run مربوط به node اعمال می‌شود. اگر حذف شود، OpenClaw از tools.exec.timeoutSec استفاده می‌کند؛ timeout: 0 صریح مهلت زمانی فرایند exec را برای آن فراخوانی غیرفعال می‌کند.
• روی میزبان‌های غیر Windows، exec وقتی SHELL تنظیم شده باشد از آن استفاده می‌کند؛ اگر SHELL برابر fish باشد، برای پرهیز از اسکریپت‌های ناسازگار با fish، bash (یا sh) را از PATH ترجیح می‌دهد، سپس اگر هیچ‌کدام وجود نداشته باشند به SHELL برمی‌گردد.
• روی میزبان‌های Windows، exec کشف PowerShell 7 (pwsh) را ترجیح می‌دهد (Program Files، ProgramW6432، سپس PATH)، سپس به Windows PowerShell 5.1 برمی‌گردد.
• اجرای میزبان (gateway/node) مقدارهای override برای env.PATH و loader (LD_*/DYLD_*) را رد می‌کند تا از ربایش باینری یا کد تزریق‌شده جلوگیری شود.
• OpenClaw در محیط فرمان ایجادشده OPENCLAW_SHELL=exec را تنظیم می‌کند (از جمله اجرای PTY و sandbox) تا قواعد shell/profile بتوانند زمینهٔ ابزار exec را تشخیص دهند.
• openclaw channels login از exec مسدود شده است چون یک جریان تعاملی احراز هویت کانال است؛ آن را در ترمینالی روی میزبان gateway اجرا کنید، یا وقتی وجود دارد از ابزار ورود بومی کانال در چت استفاده کنید.
• مهم: sandboxing به‌طور پیش‌فرض خاموش است. اگر sandboxing خاموش باشد، host=auto ضمنی به gateway resolve می‌شود. host=sandbox صریح همچنان به‌صورت بسته شکست می‌خورد، نه اینکه بی‌صدا روی میزبان gateway اجرا شود. sandboxing را فعال کنید یا از host=gateway همراه با تأییدها استفاده کنید.
• بررسی‌های preflight اسکریپت (برای خطاهای رایج نحو شل Python/Node) فقط فایل‌های داخل مرز مؤثر workdir را بررسی می‌کنند. اگر مسیر اسکریپت بیرون از workdir resolve شود، preflight برای آن فایل رد می‌شود.
• برای کارهای طولانی‌مدتی که اکنون شروع می‌شوند، آن را یک‌بار شروع کنید و وقتی فعال است و فرمان خروجی می‌دهد یا شکست می‌خورد، به بیدارباش تکمیل خودکار تکیه کنید. از process برای لاگ‌ها، وضعیت، ورودی، یا مداخله استفاده کنید؛ زمان‌بندی را با حلقه‌های sleep، حلقه‌های timeout، یا polling تکراری شبیه‌سازی نکنید.
• برای کاری که باید بعداً یا طبق برنامه انجام شود، به‌جای الگوهای sleep/delay در exec از Cron استفاده کنید.

پیکربندی

• tools.exec.notifyOnExit (پیش‌فرض: true): وقتی true باشد، نشست‌های exec پس‌زمینه‌شده هنگام خروج یک رویداد سامانه را در صف می‌گذارند و یک Heartbeat درخواست می‌کنند.
• tools.exec.approvalRunningNoticeMs (پیش‌فرض: 10000): وقتی یک exec نیازمند تأیید بیش از این مدت اجرا شود، یک اعلان واحد «running» منتشر می‌کند (0 غیرفعال می‌کند).
• tools.exec.timeoutSec (پیش‌فرض: 1800): مهلت زمانی پیش‌فرض exec برای هر فرمان بر حسب ثانیه. timeout در سطح هر فراخوانی آن را بازنویسی می‌کند؛ timeout: 0 در سطح هر فراخوانی مهلت زمانی فرایند exec را غیرفعال می‌کند.
• tools.exec.host (پیش‌فرض: auto؛ وقتی runtime مربوط به sandbox فعال باشد به sandbox، و در غیر این صورت به gateway resolve می‌شود)
• tools.exec.security (پیش‌فرض: deny برای sandbox، و وقتی تنظیم نشده باشد full برای gateway + node)
• tools.exec.ask (پیش‌فرض: off)
• exec میزبان بدون تأیید، پیش‌فرض gateway + node است. اگر رفتار تأیید/allowlist می‌خواهید، هم tools.exec.* و هم ~/.openclaw/exec-approvals.json میزبان را سخت‌گیرانه‌تر کنید؛ تأییدهای Exec را ببینید.
• YOLO از پیش‌فرض‌های سیاست میزبان می‌آید (security=full، ask=off)، نه از host=auto. اگر می‌خواهید مسیریابی gateway یا node را اجبار کنید، tools.exec.host را تنظیم کنید یا از /exec host=... استفاده کنید.
• در حالت security=full به‌همراه ask=off، host exec مستقیماً از سیاست پیکربندی‌شده پیروی می‌کند؛ هیچ لایهٔ اضافی heuristic برای پیش‌فیلتر ابهام‌سازی فرمان یا رد script-preflight وجود ندارد.
• tools.exec.node (پیش‌فرض: تنظیم‌نشده)
• tools.exec.strictInlineEval (پیش‌فرض: false): وقتی true باشد، فرم‌های eval درون‌خطی مفسر مانند python -c، node -e، ruby -e، perl -e، php -r، lua -e، و osascript -e همیشه به تأیید صریح نیاز دارند. allow-always همچنان می‌تواند فراخوانی‌های بی‌ضرر مفسر/اسکریپت را ماندگار کند، اما فرم‌های inline-eval همچنان هر بار اعلان می‌دهند.
• tools.exec.commandHighlighting (پیش‌فرض: false): وقتی true باشد، اعلان‌های تأیید می‌توانند بخش‌های فرمان استخراج‌شده توسط parser را در متن فرمان برجسته کنند. برای فعال‌سازی برجسته‌سازی متن فرمان بدون تغییر سیاست تأیید exec، آن را به‌صورت سراسری یا برای هر عامل روی true تنظیم کنید.
• tools.exec.pathPrepend: فهرست دایرکتوری‌هایی که برای اجراهای exec به ابتدای PATH افزوده می‌شوند (فقط gateway + sandbox).
• tools.exec.safeBins: باینری‌های امن فقط-stdin که می‌توانند بدون ورودی‌های allowlist صریح اجرا شوند. برای جزئیات رفتار، باینری‌های امن را ببینید.
• tools.exec.safeBinTrustedDirs: دایرکتوری‌های صریح اضافی که برای بررسی مسیر safeBins مورد اعتمادند. ورودی‌های PATH هرگز خودکار مورد اعتماد قرار نمی‌گیرند. پیش‌فرض‌های داخلی /bin و /usr/bin هستند.
• tools.exec.safeBinProfiles: سیاست argv سفارشی اختیاری برای هر باینری امن (minPositional، maxPositional، allowedValueFlags، deniedFlags).

مثال:

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

مدیریت PATH

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

اتصال node در سطح هر عامل (از شاخص فهرست عامل در config استفاده کنید):

openclaw config get agents.listopenclaw config set agents.list[0].tools.exec.node "node-id-or-name"

رابط کاربری کنترل: زبانهٔ Nodes شامل یک پنل کوچک «Exec node binding» برای همین تنظیمات است.

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

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

مثال:

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

مدل مجوزدهی

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

تأییدهای Exec (companion app / میزبان node)

عامل‌های sandboxشده می‌توانند پیش از اجرای exec روی میزبان gateway یا node به تأیید برای هر درخواست نیاز داشته باشند. برای سیاست، allowlist، و جریان رابط کاربری، تأییدهای Exec را ببینید.

وقتی تأییدها لازم باشند، ابزار exec بلافاصله با status: "approval-pending" و یک شناسهٔ تأیید برمی‌گردد. پس از تأیید (یا رد / timeout)، Gateway رویدادهای سامانه را منتشر می‌کند (Exec finished / Exec denied). اگر فرمان پس از tools.exec.approvalRunningNoticeMs همچنان در حال اجرا باشد، یک اعلان واحد Exec running منتشر می‌شود. در کانال‌هایی با کارت‌ها/دکمه‌های تأیید بومی، عامل باید ابتدا به همان رابط کاربری بومی تکیه کند و فقط وقتی نتیجهٔ ابزار صراحتاً می‌گوید تأییدهای چت در دسترس نیستند یا تأیید دستی تنها مسیر است، یک فرمان دستی /approve درج کند.

Allowlist + باینری‌های امن

اعمال allowlist دستی با globهای مسیر باینری resolveشده و globهای نام فرمان خام تطبیق می‌دهد. نام‌های خام فقط فرمان‌هایی را تطبیق می‌دهند که از طریق PATH فراخوانی شده‌اند، بنابراین وقتی فرمان rg باشد، rg می‌تواند /opt/homebrew/bin/rg را تطبیق دهد، اما نه ./rg یا /tmp/rg. وقتی security=allowlist باشد، فرمان‌های شل فقط زمانی خودکار مجاز می‌شوند که هر segment در pipeline در allowlist باشد یا یک باینری امن باشد. زنجیره‌سازی (;، &&، ||) و redirectionها در حالت allowlist رد می‌شوند، مگر اینکه هر segment سطح‌بالا allowlist را برآورده کند (از جمله باینری‌های امن). Redirectionها همچنان پشتیبانی نمی‌شوند. اعتماد پایدار allow-always این قاعده را دور نمی‌زند: یک فرمان زنجیره‌شده همچنان نیاز دارد هر segment سطح‌بالا تطبیق داشته باشد.

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

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

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

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

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

مثال‌ها

پیش‌زمینه:

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

چسباندن (به‌طور پیش‌فرض bracketed):

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

apply_patch

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

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

نکات:

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

مرتبط

• تأییدهای Exec — دروازه‌های تأیید برای فرمان‌های shell
• Sandboxing — اجرای فرمان‌ها در محیط‌های sandbox‌شده
• فرایند پس‌زمینه — ابزار exec و process طولانی‌اجرا
• امنیت — سیاست ابزار و دسترسی ارتقایافته