تأییدهای اجرا

تأییدهای اجرا محافظ برنامه همراه / میزبان Node برای اجازه‌دادن به یک عامل سندباکس‌شده جهت اجرای فرمان‌ها روی یک میزبان واقعی هستند (gateway یا node). فرمان‌ها فقط زمانی اجرا می‌شوند که خط‌مشی + فهرست مجاز + تأیید (اختیاری) کاربر همگی موافق باشند. تأییدها علاوه بر خط‌مشی ابزار و محدودسازی دسترسی ارتقایافته اعمال می‌شوند (حالت ارتقایافته full آن‌ها را نادیده می‌گیرد).

برای نمایی کلی با تمرکز بر حالت‌های deny، allowlist، ask، auto، full، نگاشت Codex Guardian و مجوزهای مهار ACPX، به حالت‌های مجوز مراجعه کنید.

محل اعمال

تأییدهای اجرا به‌صورت محلی روی میزبان اجرا اعمال می‌شوند:

• میزبان Gateway -> فرایند openclaw روی دستگاه Gateway.
• میزبان Node -> اجراکننده Node (برنامه همراه macOS یا میزبان Node بدون رابط گرافیکی).

مدل اعتماد

• فراخوان‌های احراز هویت‌شده توسط Gateway، اپراتورهای مورد اعتماد آن Gateway محسوب می‌شوند.
• Nodeهای جفت‌شده، قابلیت آن اپراتور مورد اعتماد را به میزبان Node گسترش می‌دهند.
• تأییدها خطر اجرای تصادفی را کاهش می‌دهند، اما مرز احراز هویت به‌ازای هر کاربر یا خط‌مشی فقط‌خواندنی سیستم فایل نیستند.
• پس از تأیید، یک فرمان می‌تواند مطابق مجوزهای سیستم فایل میزبان یا سندباکس انتخاب‌شده، فایل‌ها را تغییر دهد.
• اجراهای تأییدشده روی میزبان Node، زمینه اجرای متعارف را مقید می‌کنند: cwd، argv دقیق، اتصال env در صورت وجود، و مسیر سنجاق‌شده فایل اجرایی در صورت کاربرد.
• برای اسکریپت‌های پوسته و فراخوانی مستقیم فایل مفسر/محیط اجرا، OpenClaw همچنین تلاش می‌کند یک عملوند فایل محلی مشخص را مقید کند. اگر آن فایل پس از تأیید اما پیش از اجرا تغییر کند، به‌جای اجرای محتوای تغییرکرده، اجرا رد می‌شود.
• مقیدسازی فایل با حداکثر تلاش انجام می‌شود و مدل کاملی از تمام مسیرهای بارگذار مفسر/محیط اجرا نیست. اگر دقیقاً یک فایل محلی مشخص قابل شناسایی نباشد، OpenClaw به‌جای وانمودکردن پوشش کامل، از ایجاد اجرای مبتنی بر تأیید خودداری می‌کند.

تفکیک macOS

• سرویس میزبان Node، system.run را از طریق IPC محلی به برنامه macOS هدایت می‌کند.
• برنامه macOS تأییدها را اعمال می‌کند و فرمان را در زمینه رابط کاربری اجرا می‌کند.

بررسی خط‌مشی مؤثر

مرجع کامل CLI (پرچم‌ها، خروجی JSON، افزودن/حذف فهرست مجاز): CLI تأییدها.

وقتی یک دامنه محلی host=node را درخواست می‌کند، exec-policy show آن دامنه را در زمان اجرا به‌عنوان مدیریت‌شده توسط Node گزارش می‌کند، نه اینکه فایل تأییدهای محلی را منبع حقیقت در نظر بگیرد.

اگر رابط کاربری برنامه همراه در دسترس نباشد، هر درخواستی که در حالت عادی باعث نمایش درخواست تأیید می‌شود، با پس‌گرد پرسش حل می‌شود (پیش‌فرض: deny).

تنظیمات و ذخیره‌سازی

تأییدها در یک فایل JSON محلی روی میزبان اجرا نگهداری می‌شوند. وقتی OPENCLAW_STATE_DIR تنظیم شده باشد، فایل از همان دایرکتوری وضعیت پیروی می‌کند؛ در غیر این صورت از دایرکتوری وضعیت پیش‌فرض OpenClaw استفاده می‌کند:

$OPENCLAW_STATE_DIR/exec-approvals.json# در غیر این صورت~/.openclaw/exec-approvals.json

سوکت پیش‌فرض تأیید نیز از همان ریشه پیروی می‌کند: $OPENCLAW_STATE_DIR/exec-approvals.sock، یا ~/.openclaw/exec-approvals.sock وقتی متغیر تنظیم نشده باشد.

دایرکتوری‌های وضعیت دامنه‌های اعتماد مستقلی هستند. وقتی OPENCLAW_STATE_DIR به مکان دیگری اشاره کند، OpenClaw هرگز ~/.openclaw/exec-approvals.json را وارد یا بایگانی نمی‌کند؛ تأییدها را برای دایرکتوری وضعیت سفارشی جداگانه پیکربندی کنید. Doctor نیز plugin-binding-approvals.json قدیمی را فقط زمانی وارد می‌کند که متعلق به دایرکتوری وضعیت فعال باشد.

نمونه طرح‌واره:

{  "version": 1,  "socket": {    "path": "~/.openclaw/exec-approvals.sock",    "token": "base64url-token"  },  "defaults": {    "security": "deny",    "ask": "on-miss",    "askFallback": "deny",    "autoAllowSkills": false  },  "agents": {    "main": {      "security": "allowlist",      "ask": "on-miss",      "askFallback": "deny",      "autoAllowSkills": true,      "allowlist": [        {          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",          "pattern": "~/Projects/**/bin/rg",          "argPattern": "sha256:argv:...",          "source": "allow-always",          "lastUsedAt": 1737150000000,          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        },        {          "pattern": "~/Projects/**/bin/git"        }      ]    }  }}

کنترل‌های خط‌مشی

tools.exec.mode

tools.exec.mode سطح خط‌مشی نرمال‌شده ترجیحی برای اجرای میزبان است:

Doctor جفت ذخیره‌شده و کنارگذاشته‌شده tools.exec.security / tools.exec.ask را به tools.exec.mode مهاجرت می‌دهد.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

نمونه‌هایی که حالت سخت‌گیرانه شناسایی می‌کند: python -c، node -e/--eval/-p، ruby -e، perl -e/-E، php -r، lua -e، osascript -e (همچنین فرم‌های درون‌خطی awk، sed، make، find -exec و xargs).

در حالت سخت‌گیرانه، این فرمان‌ها به بازبین یا تأیید صریح نیاز دارند. با tools.exec.mode: "auto"، بازبین می‌تواند در صورتی که فرمان برنامه‌ای قابل‌اعمال داشته باشد، یک اجرای کم‌خطر را اجازه دهد؛ در غیر این صورت OpenClaw از انسان می‌پرسد. تأییدهای فرمان Codex app-server که به پس‌گرد بازبین می‌رسند، از انسان می‌پرسند، زیرا درخواست‌های تأیید آن‌ها فایل اجرایی حل‌شده و قابل‌اعمال را ارائه نمی‌کنند. allow-always برای فرمان‌های ارزیابی درون‌خطی، ورودی جدیدی در فهرست مجاز ذخیره نمی‌کند.

tools.exec.commandHighlighting

آن را به‌صورت سراسری زیر tools.exec.commandHighlighting یا به‌ازای هر عامل زیر agents.entries.*.tools.exec.commandHighlighting تنظیم کنید.

حالت YOLO (بدون تأیید)

برای اجرای میزبان بدون درخواست تأیید، هر دو لایه خط‌مشی را باز کنید: خط‌مشی اجرای درخواستی در پیکربندی OpenClaw (tools.exec.*) و خط‌مشی تأیید محلی میزبان در فایل تأییدهای میزبان اجرا.

مقدار حذف‌شده askFallback به‌طور پیش‌فرض deny است. وقتی درخواست تأیید بدون رابط کاربری باید با اجازه‌دادن حل شود، askFallback میزبان را صریحاً روی full تنظیم کنید.

ارائه‌دهندگان مبتنی بر CLI که حالت مجوز غیرتعاملی خود را ارائه می‌کنند، می‌توانند از این خط‌مشی پیروی کنند. Claude CLI زمانی که خط‌مشی مؤثر exec در OpenClaw برابر با YOLO باشد، --permission-mode bypassPermissions را اضافه می‌کند. برای نشست‌های زندهٔ Claude تحت مدیریت OpenClaw، خط‌مشی مؤثر exec در OpenClaw بر حالت مجوز بومی Claude اولویت دارد: YOLO اجراهای زنده را به --permission-mode bypassPermissions عادی‌سازی می‌کند و خط‌مشی مؤثر محدودکنندهٔ exec اجراهای زنده را به --permission-mode default عادی‌سازی می‌کند، حتی اگر آرگومان‌های خام بک‌اند Claude حالت دیگری را مشخص کنند.

اگر راه‌اندازی محافظه‌کارانه‌تری می‌خواهید، خط‌مشی exec در OpenClaw را دوباره به allowlist / on-miss یا deny محدود کنید.

راه‌اندازی پایدار «هرگز درخواست نکن» برای میزبان gateway

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.mode fullopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

میان‌بر محلی

openclaw exec-policy preset yolo

هم tools.exec.host/security/ask محلی و هم پیش‌فرض‌های فایل تأییدهای محلی (از جمله askFallback: "full") را به‌روزرسانی می‌کند. این میان‌بر عمداً فقط محلی است. برای تغییر تأییدهای میزبان gateway یا میزبان node از راه دور، از openclaw approvals set --gateway یا openclaw approvals set --node <id|name|ip> استفاده کنید.

سایر پیش‌تنظیم‌های داخلی: cautious (host=gateway، security=allowlist، ask=on-miss، askFallback=deny) و deny-all (host=gateway، security=deny، ask=off، askFallback=deny). آن‌ها را به همین روش اعمال کنید: openclaw exec-policy preset cautious.

برای تنظیم فیلدهای منفرد به‌جای یک پیش‌تنظیم کامل، از openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> با هر زیرمجموعه‌ای از آن پرچم‌ها استفاده کنید.

میزبان Node

همان فایل تأییدها را به‌جای آن روی node اعمال کنید:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

میان‌بر فقط برای نشست

• /exec security=full ask=off فقط نشست فعلی را تغییر می‌دهد.
• /elevated full یک میان‌بر اضطراری است که فقط زمانی تأییدهای exec را نادیده می‌گیرد که هم خط‌مشی درخواستی و هم فایل تأییدهای میزبان به security: "full" و ask: "off" منتهی شوند. یک فایل میزبان سخت‌گیرانه‌تر، مانند ask: "always"، همچنان درخواست تأیید می‌کند.

اگر فایل تأییدهای میزبان از پیکربندی سخت‌گیرانه‌تر باقی بماند، خط‌مشی سخت‌گیرانه‌تر میزبان همچنان اولویت دارد.

فهرست مجاز (برای هر عامل)

فهرست‌های مجاز برای هر عامل جداگانه‌اند. اگر چند عامل وجود دارد، در برنامهٔ macOS عاملی را که ویرایش می‌کنید تغییر دهید. الگوها با glob تطبیق داده می‌شوند.

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

ورودی‌های قدیمی agents.default هنگام بارگذاری به agents.main مهاجرت می‌کنند. زنجیره‌های پوسته مانند echo ok && pwd همچنان نیاز دارند که هر بخش سطح‌بالا قواعد فهرست مجاز را برآورده کند.

مثال‌ها:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

محدودکردن آرگومان‌ها با argPattern

هنگامی که یک ورودی فهرست مجاز باید با یک باینری و یک شکل مشخص آرگومان مطابقت داشته باشد، argPattern را اضافه کنید. OpenClaw در همهٔ میزبان‌ها از معناشناسی عبارت منظم ECMAScript (JavaScript) استفاده می‌کند و عبارت را در برابر آرگومان‌های تجزیه‌شدهٔ فرمان، بدون توکن اجرایی (argv[0])، ارزیابی می‌کند. برای ورودی‌هایی که دستی نوشته شده‌اند، آرگومان‌ها با یک فاصله به هم متصل می‌شوند، بنابراین هنگامی که به تطبیق دقیق نیاز دارید، الگو را مهار کنید.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

آن ورودی python3 safe.py را مجاز می‌کند؛ python3 other.py در فهرست مجاز تطبیق نمی‌یابد. اگر برای همان باینری یک ورودی فقط‌مسیر نیز وجود داشته باشد، آرگومان‌های نامطابق همچنان می‌توانند به آن ورودی فقط‌مسیر بازگردند. هنگامی که هدف محدودکردن باینری به آرگومان‌های اعلام‌شده است، ورودی فقط‌مسیر را حذف کنید.

ورودی‌هایی که جریان‌های تأیید ذخیره می‌کنند، برای تطبیق دقیق argv از قالب جداکنندهٔ داخلی استفاده می‌کنند. برای بازتولید آن ورودی‌ها، به‌جای ویرایش دستی مقدار کدگذاری‌شده، UI یا جریان تأیید را ترجیح دهید. اگر OpenClaw نتواند argv یک بخش فرمان را تجزیه کند، ورودی‌های دارای argPattern مطابقت نمی‌یابند.

ورودی‌های تولیدشدهٔ allow-always به argv مقید هستند. ورودی‌های تولیدشدهٔ جدید شامل argPattern هستند؛ ورودی‌های قدیمی تولیدشدهٔ فقط‌مسیر نادیده گرفته می‌شوند و به تأیید تازه نیاز دارند. برای یک قاعدهٔ دستی فقط‌مسیر، هم source و هم argPattern را حذف کنید.

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

مجازسازی خودکار CLIهای Skills

وقتی مجازسازی خودکار CLIهای Skills (autoAllowSkills) فعال باشد، فایل‌های اجرایی ارجاع‌شده توسط Skills شناخته‌شده در nodeها (node در macOS یا میزبان node بدون رابط گرافیکی) مجاز تلقی می‌شوند. این قابلیت برای دریافت فهرست باینری Skills از skills.bins روی RPC مربوط به Gateway استفاده می‌کند. اگر فهرست‌های مجاز دستی و سخت‌گیرانه می‌خواهید، آن را غیرفعال کنید.

باینری‌های امن و ارسال تأیید

برای باینری‌های امن (مسیر سریع فقط stdin)، جزئیات اتصال مفسر و نحوهٔ ارسال درخواست‌های تأیید به Slack/Discord/Telegram (یا اجرای آن‌ها به‌عنوان کلاینت‌های بومی تأیید)، به تأییدهای exec - پیشرفته مراجعه کنید.

ویرایش در Control UI

برای ویرایش پیش‌فرض‌ها، بازنویسی‌های هر عامل و فهرست‌های مجاز، از کارت Control UI -> Nodes -> Exec approvals استفاده کنید. یک دامنه (Defaults یا یک عامل) انتخاب کنید، خط‌مشی را تغییر دهید، الگوهای فهرست مجاز را اضافه/حذف کنید و سپس Save را بزنید. UI فرادادهٔ آخرین استفاده را برای هر الگو نشان می‌دهد تا بتوانید فهرست را مرتب نگه دارید.

انتخابگر هدف، Gateway (تأییدهای محلی) یا یک Node را انتخاب می‌کند. Nodeها باید system.execApprovals.get/set را اعلام کنند (برنامهٔ macOS یا میزبان node بدون رابط گرافیکی). اگر یک node هنوز تأییدهای exec را اعلام نمی‌کند، فایل تأییدهای محلی آن را مستقیماً ویرایش کنید.

برخی میزبان‌های node، از جمله برنامهٔ همراه Windows، قالب متفاوتی برای خط‌مشی تأیید دارند. Control UI این خط‌مشی‌های بومی میزبان را فقط‌خواندنی نشان می‌دهد. برای ویرایش آن‌ها از برنامهٔ همراه یا openclaw approvals set --node <id|name|ip> با شکل بومی خط‌مشی استفاده کنید؛ به CLI تأییدها مراجعه کنید.

CLI: ‏openclaw approvals از ویرایش gateway یا node پشتیبانی می‌کند ــ به CLI تأییدها مراجعه کنید.

جریان تأیید

وقتی درخواست تأیید لازم باشد، gateway رویداد exec.approval.requested را برای کلاینت‌های اپراتور پخش می‌کند. Control UI و برنامهٔ macOS آن را از طریق exec.approval.resolve حل می‌کنند و سپس gateway درخواست تأییدشده را به میزبان node می‌فرستد.

برای host=node، درخواست‌های تأیید شامل یک بار دادهٔ استاندارد systemRunPlan هستند. gateway هنگام ارسال درخواست‌های تأییدشدهٔ system.run، از آن طرح به‌عنوان زمینهٔ معتبر فرمان/cwd/نشست استفاده می‌کند:

• مسیر exec در node از ابتدا یک طرح استاندارد آماده می‌کند.
• رکورد تأیید، آن طرح و فرادادهٔ اتصال آن را ذخیره می‌کند.
• پس از تأیید، فراخوانی نهایی و ارسال‌شدهٔ system.run به‌جای اعتماد به ویرایش‌های بعدی فراخواننده، از طرح ذخیره‌شده دوباره استفاده می‌کند.
• اگر فراخواننده پس از ایجاد درخواست تأیید، command، rawCommand، cwd، agentId یا sessionKey را تغییر دهد، gateway اجرای ارسال‌شده را به‌دلیل عدم تطابق تأیید رد می‌کند.

رویدادهای سیستم و ردها

چرخهٔ حیات exec پس از گزارش تکمیل توسط node، یک پیام سیستمی Exec finished را در نشست عامل ارسال می‌کند. OpenClaw همچنین می‌تواند پس از اعطای تأیید و سپری‌شدن tools.exec.approvalRunningNoticeMs، یک اعلان در حال انجام ارسال کند (پیش‌فرض 10000 است و 0 آن را غیرفعال می‌کند). تأییدهای exec ردشده برای فرمان میزبان نهایی هستند: فرمان اجرا نمی‌شود.

• برای تأییدهای ناهمگام عامل اصلی که نشست مبدأ دارند، OpenClaw رد را به‌عنوان یک پیگیری داخلی به همان نشست ارسال می‌کند تا عامل بتواند انتظار برای فرمان ناهمگام را متوقف کند و از ترمیم نتیجهٔ مفقود جلوگیری کند.
• اگر نشستی وجود نداشته باشد یا ازسرگیری نشست ممکن نباشد، OpenClaw همچنان می‌تواند یک گزارش کوتاه از رد را به اپراتور یا مسیر گفت‌وگوی مستقیم ارائه کند.
• ردهای مربوط به نشست‌های عامل فرعی و Cron به همان نشست ارسال نمی‌شوند.

تأییدهای exec در میزبان Gateway همان رویداد چرخهٔ حیات تکمیل را منتشر می‌کنند. execهای مشروط به تأیید، شناسهٔ تأیید را دوباره استفاده می‌کنند تا درخواست در انتظار را با پیام تکمیل/رد آن مرتبط کنند (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

پیامدها

• full قدرتمند است؛ در صورت امکان فهرست‌های مجاز را ترجیح دهید.
• ask شما را در جریان نگه می‌دارد و در عین حال تأییدهای سریع را ممکن می‌کند.
• فهرست‌های مجاز هر عامل از نشت تأییدهای یک عامل به سایر عامل‌ها جلوگیری می‌کنند.
• تأییدها فقط برای درخواست‌های exec میزبان از فرستندگان مجاز اعمال می‌شوند. فرستندگان غیرمجاز نمی‌توانند /exec را صادر کنند.
• /exec security=full یک قابلیت ساده‌ساز در سطح نشست برای اپراتورهای مجاز است و بنا بر طراحی، تأییدها را نادیده می‌گیرد. برای مسدودکردن کامل exec میزبان، امنیت تأییدها را روی deny تنظیم کنید یا ابزار exec را از طریق خط‌مشی ابزار رد کنید.

مرتبط