---
read_when:
- پیکربندی تأییدهای exec یا فهرستهای مجاز
- پیادهسازی تجربه کاربری تأیید اجرا در برنامه macOS
- بررسی پرامپتهای گریز از سندباکس و پیامدهای آنها
sidebarTitle: Exec approvals
summary: 'تأییدهای اجرای میزبان: تنظیمات سیاست، فهرستهای مجاز، و گردشکار YOLO/سختگیرانه'
title: تأییدهای اجرا
x-i18n:
generated_at: "2026-05-11T20:45:06Z"
model: gpt-5.5
provider: openai
source_hash: 2966a6f4633046941a9ef3267bad10f3a153956361b9f088fb3e29fcd3fcb99d
source_path: tools/exec-approvals.md
workflow: 16
---
تأییدهای exec همان **محافظ برنامهٔ همراه / میزبان Node** هستند که اجازه میدهند
یک عامل سندباکسشده فرمانها را روی یک میزبان واقعی (`gateway` یا `node`) اجرا کند. یک
قفل ایمنی: فرمانها فقط زمانی مجازند که سیاست + فهرست مجاز +
تأیید کاربر (اختیاری) همگی موافق باشند. تأییدهای exec **روی**
سیاست ابزار و دروازهبانی elevated انباشته میشوند (مگر اینکه elevated روی `full` تنظیم شده باشد، که
تأییدها را رد میکند).
سیاست مؤثر، مورد **سختگیرانهتر** بین پیشفرضهای `tools.exec.*` و تأییدهاست؛ اگر یک فیلد تأییدها حذف شود، مقدار `tools.exec`
استفاده میشود. اجرای میزبان همچنین از وضعیت تأییدهای محلی همان ماشین استفاده میکند - یک
`ask: "always"` محلیِ میزبان در `~/.openclaw/exec-approvals.json` همچنان
درخواست تأیید میکند، حتی اگر پیشفرضهای نشست یا پیکربندی `ask: "on-miss"` را درخواست کنند.
## بررسی سیاست مؤثر
| فرمان | چه چیزی را نشان میدهد |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `openclaw approvals get` / `--gateway` / `--node ` | سیاست درخواستی، منابع سیاست میزبان، و نتیجهٔ مؤثر. |
| `openclaw exec-policy show` | نمای ادغامشدهٔ ماشین محلی. |
| `openclaw exec-policy set` / `preset` | همگامسازی سیاست درخواستی محلی با فایل تأییدهای میزبان محلی در یک مرحله. |
وقتی یک محدودهٔ محلی `host=node` را درخواست میکند، `exec-policy show` آن
محدوده را در زمان اجرا بهعنوان مدیریتشده توسط Node گزارش میکند، بهجای اینکه وانمود کند فایل
تأییدهای محلی منبع حقیقت است.
اگر رابط کاربری برنامهٔ همراه **در دسترس نباشد**، هر درخواستی که
معمولاً اعلان تأیید ایجاد میکند، با **جایگزین ask** حل میشود (پیشفرض: `deny`).
کلاینتهای تأیید چت بومی میتوانند امکانات ویژهٔ کانال را روی
پیام تأیید در انتظار قرار دهند. برای نمونه، Matrix میانبرهای واکنش را قرار میدهد
(`✅` اجازه برای یک بار، `❌` رد، `♾️` همیشه اجازه بده) و همچنان
فرمانهای `/approve ...` را بهعنوان گزینهٔ جایگزین در پیام باقی میگذارد.
## محل اعمال
تأییدهای exec بهصورت محلی روی میزبان اجرا اعمال میشوند:
- **میزبان Gateway** ← فرایند `openclaw` روی ماشین Gateway.
- **میزبان Node** ← اجراکنندهٔ Node (برنامهٔ همراه macOS یا میزبان Node بدون رابط گرافیکی).
### مدل اعتماد
- فراخوانهایی که توسط Gateway احراز هویت شدهاند، برای آن Gateway اپراتورهای مورد اعتماد هستند.
- Nodeهای جفتشده آن قابلیت اپراتور مورد اعتماد را به میزبان Node گسترش میدهند.
- تأییدهای exec خطر اجرای تصادفی را کاهش میدهند، اما **نه** یک مرز احراز هویت برای هر کاربر هستند و نه سیاست فقطخواندنی فایلسیستم.
- پس از تأیید، یک فرمان میتواند فایلها را مطابق مجوزهای فایلسیستمِ میزبان یا سندباکس انتخابشده تغییر دهد.
- اجراهای تأییدشدهٔ میزبان Node زمینهٔ اجرای canonical را مقید میکنند: cwd canonical، argv دقیق، اتصال env در صورت وجود، و مسیر اجرایی پینشده در موارد قابل اعمال.
- برای اسکریپتهای shell و فراخوانی مستقیم فایلهای مفسر/زمان اجرا، OpenClaw همچنین تلاش میکند یک عملوند فایل محلی مشخص را مقید کند. اگر آن فایل مقیدشده پس از تأیید اما پیش از اجرا تغییر کند، اجرا بهجای اجرای محتوای جابهجاشده رد میشود.
- مقیدسازی فایل عمداً با بهترین تلاش انجام میشود، **نه** یک مدل معنایی کامل از مسیر بارگذار هر مفسر/زمان اجرا. اگر حالت تأیید نتواند دقیقاً یک فایل محلی مشخص را برای مقیدسازی شناسایی کند، بهجای وانمود کردن به پوشش کامل، از صادر کردن اجرای پشتوانهدار با تأیید خودداری میکند.
### تفکیک macOS
- **سرویس میزبان Node**، `system.run` را از طریق IPC محلی به **برنامهٔ macOS** ارسال میکند.
- **برنامهٔ macOS** تأییدها را اعمال میکند و فرمان را در زمینهٔ رابط کاربری اجرا میکند.
## تنظیمات و ذخیرهسازی
تأییدها در یک فایل JSON محلی روی میزبان اجرا قرار دارند:
```text
~/.openclaw/exec-approvals.json
```
نمونهٔ schema:
```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",
"source": "allow-always",
"commandText": "rg -n TODO",
"lastUsedAt": 1737150000000,
"lastUsedCommand": "rg -n TODO",
"lastResolvedPath": "/Users/user/Projects/.../bin/rg"
}
]
}
}
}
```
## دکمههای سیاست
### `exec.security`
- `deny` - همهٔ درخواستهای اجرای میزبان را مسدود میکند.
- `allowlist` - فقط فرمانهای موجود در فهرست مجاز را اجازه میدهد.
- `full` - همه چیز را اجازه میدهد (معادل elevated).
### `exec.ask`
- `off` - هرگز اعلان تأیید نده.
- `on-miss` - فقط وقتی فهرست مجاز مطابقت ندارد اعلان بده.
- `always` - برای هر فرمان اعلان بده. اعتماد پایدار `allow-always` وقتی حالت ask مؤثر `always` است، اعلانها را **سرکوب نمیکند**.
### `askFallback`
حلوفصل وقتی اعلان لازم است اما هیچ رابط کاربری قابل دسترسی نیست.
- `deny` - مسدود کن.
- `allowlist` - فقط اگر فهرست مجاز مطابقت دارد اجازه بده.
- `full` - اجازه بده.
### `tools.exec.strictInlineEval`
وقتی `true` باشد، OpenClaw فرمهای ارزیابی کد درونخطی را فقط با تأیید مجاز میداند،
حتی اگر خود باینری مفسر در فهرست مجاز باشد. دفاع در عمق
برای بارگذارهای مفسری که بهصورت تمیز به یک عملوند فایل پایدار
نگاشت نمیشوند.
نمونههایی که حالت سختگیرانه میگیرد:
- `python -c`
- `node -e`, `node --eval`, `node -p`
- `ruby -e`
- `perl -e`, `perl -E`
- `php -r`
- `lua -e`
- `osascript -e`
در حالت سختگیرانه، این فرمانها همچنان به تأیید صریح نیاز دارند، و
`allow-always` ورودیهای جدید فهرست مجاز را بهصورت خودکار برای آنها
پایدار نمیکند.
### `tools.exec.commandHighlighting`
فقط نمایش در اعلانهای تأیید exec را کنترل میکند. وقتی فعال باشد،
OpenClaw میتواند بازههای فرمان مشتقشده از parser را ضمیمه کند تا اعلانهای تأیید Web
بتوانند توکنهای فرمان را برجسته کنند. برای فعال کردن
برجستهسازی متن فرمان، آن را روی `true` تنظیم کنید.
این تنظیم `security`، `ask`، تطبیق فهرست مجاز،
رفتار سختگیرانهٔ inline-eval، ارسال تأیید، یا اجرای فرمان را تغییر **نمیدهد**.
میتوان آن را بهصورت سراسری زیر `tools.exec.commandHighlighting` یا برای هر
عامل زیر `agents.list[].tools.exec.commandHighlighting` تنظیم کرد.
## حالت YOLO (بدون تأیید)
اگر میخواهید اجرای میزبان بدون اعلانهای تأیید انجام شود، باید
**هر دو** لایهٔ سیاست را باز کنید - سیاست exec درخواستی در پیکربندی OpenClaw
(`tools.exec.*`) **و** سیاست تأییدهای محلی میزبان در
`~/.openclaw/exec-approvals.json`.
YOLO رفتار پیشفرض میزبان است مگر اینکه آن را صراحتاً سختگیرانهتر کنید:
| لایه | تنظیم YOLO |
| --------------------- | -------------------------- |
| `tools.exec.security` | `full` روی `gateway`/`node` |
| `tools.exec.ask` | `off` |
| Host `askFallback` | `full` |
**تمایزهای مهم:**
- `tools.exec.host=auto` انتخاب میکند exec **کجا** اجرا شود: سندباکس وقتی در دسترس است، وگرنه Gateway.
- YOLO انتخاب میکند اجرای میزبان **چگونه** تأیید شود: `security=full` بهعلاوهٔ `ask=off`.
- در حالت YOLO، OpenClaw یک دروازهٔ تأیید جداگانهٔ ابهامسازی فرمان مبتنی بر heuristic یا لایهٔ رد پیشبررسی اسکریپت را روی سیاست اجرای میزبان پیکربندیشده اضافه **نمیکند**.
- `auto` مسیریابی Gateway را به یک override آزاد از یک نشست سندباکسشده تبدیل نمیکند. یک درخواست هر-فراخوانی `host=node` از `auto` مجاز است؛ `host=gateway` فقط زمانی از `auto` مجاز است که هیچ زمان اجرای سندباکس فعالی وجود نداشته باشد. برای یک پیشفرض پایدار غیر auto، `tools.exec.host` را تنظیم کنید یا صراحتاً از `/exec host=...` استفاده کنید.
ارائهدهندگان پشتوانهٔ CLI که حالت مجوز غیرتعاملی خودشان را ارائه میکنند
میتوانند این سیاست را دنبال کنند. Claude CLI وقتی سیاست exec درخواستی OpenClaw
برابر YOLO باشد، `--permission-mode bypassPermissions` را اضافه میکند.
این رفتار backend را با آرگومانهای صریح Claude زیر
`agents.defaults.cliBackends.claude-cli.args` / `resumeArgs` بازنویسی کنید -
برای مثال `--permission-mode default`، `acceptEdits`، یا
`bypassPermissions`.
اگر راهاندازی محافظهکارانهتری میخواهید، هر یک از لایهها را دوباره به
`allowlist` / `on-miss` یا `deny` سختگیرانهتر کنید.
### راهاندازی پایدار «هرگز اعلان نده» برای میزبان Gateway
```bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart
```
```bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
### میانبر محلی
```bash
openclaw exec-policy preset yolo
```
آن میانبر محلی هر دو مورد را بهروزرسانی میکند:
- `tools.exec.host/security/ask` محلی.
- پیشفرضهای محلی `~/.openclaw/exec-approvals.json`.
این عمداً فقط محلی است. برای تغییر تأییدهای میزبان Gateway یا میزبان Node
از راه دور، از `openclaw approvals set --gateway` یا
`openclaw approvals set --node ` استفاده کنید.
### میزبان Node
برای یک میزبان Node، همان فایل تأییدها را بهجای آن روی همان Node اعمال کنید:
```bash
openclaw approvals set --node --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
**محدودیتهای فقط محلی:**
- `openclaw exec-policy` تأییدهای Node را همگامسازی نمیکند.
- `openclaw exec-policy set --host node` رد میشود.
- تأییدهای exec در Node در زمان اجرا از Node دریافت میشوند، بنابراین بهروزرسانیهای هدفگیریشده برای Node باید از `openclaw approvals --node ...` استفاده کنند.
### میانبر فقط نشست
- `/exec security=full ask=off` فقط نشست فعلی را تغییر میدهد.
- `/elevated full` یک میانبر اضطراری است که تأییدهای exec را نیز برای آن نشست رد میکند.
اگر فایل تأییدهای میزبان از پیکربندی سختگیرانهتر بماند، سیاست سختگیرانهتر میزبان
همچنان برنده است.
## فهرست مجاز (برای هر عامل)
فهرستهای مجاز **برای هر عامل** هستند. اگر چند عامل وجود دارد، در برنامهٔ macOS مشخص کنید در حال ویرایش کدام عامل هستید. الگوها تطبیقهای glob هستند.
الگوها میتوانند globهای مسیر باینری حلشده یا globهای نام فرمانِ تنها باشند.
نامهای تنها فقط با فرمانهایی مطابقت دارند که از طریق `PATH` فراخوانی شدهاند، بنابراین `rg` میتواند با
`/opt/homebrew/bin/rg` وقتی فرمان `rg` است مطابقت داشته باشد، اما **نه** با `./rg` یا
`/tmp/rg`. وقتی میخواهید به یک محل باینری مشخص اعتماد کنید، از glob مسیر استفاده کنید.
ورودیهای قدیمی `agents.default` هنگام بارگذاری به `agents.main` مهاجرت میکنند.
زنجیرههای shell مانند `echo ok && pwd` همچنان نیاز دارند هر قطعهٔ سطح بالای آنها
قوانین فهرست مجاز را برآورده کند.
نمونهها:
- `rg`
- `~/Projects/**/bin/peekaboo`
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`
### محدود کردن آرگومانها با argPattern
وقتی یک ورودی فهرست مجاز باید با یک باینری و یک شکل آرگومان
مشخص مطابقت کند، `argPattern` را اضافه کنید. OpenClaw عبارت منظم را
روی آرگومانهای فرمانِ parseشده ارزیابی میکند، بدون توکن اجرایی
(`argv[0]`). برای ورودیهای دستنویس، آرگومانها با یک
فاصلهٔ واحد به هم متصل میشوند، بنابراین وقتی به تطبیق دقیق نیاز دارید الگو را anchor کنید.
```json
{
"version": 1,
"agents": {
"main": {
"allowlist": [
{
"pattern": "python3",
"argPattern": "^safe\\.py$"
}
]
}
}
}
```
آن ورودی به `python3 safe.py` اجازه میدهد؛ `python3 other.py` یک عدمتطابق فهرست مجاز است. اگر یک ورودی فقط-مسیر برای همان باینری نیز وجود داشته باشد، آرگومانهای نامطابق
میتوانند همچنان به آن ورودی فقط-مسیر fallback کنند. وقتی هدف محدود کردن باینری به آرگومانهای اعلامشده است،
ورودی فقط-مسیر را حذف کنید.
ورودیهایی که توسط جریانهای تأیید ذخیره میشوند میتوانند برای تطبیق دقیق argv از قالب جداکننده داخلی استفاده کنند. ترجیح دهید بهجای ویرایش دستی مقدار رمزگذاریشده، آن ورودیها را از طریق UI یا جریان تأیید دوباره تولید کنید. اگر OpenClaw نتواند argv را برای یک بخش فرمان تجزیه کند، ورودیهای دارای `argPattern` تطبیق داده نمیشوند.
هر ورودی فهرست مجاز از این موارد پشتیبانی میکند:
| فیلد | معنا |
| ------------------ | ------------------------------------------------------------- |
| `pattern` | glob مسیر باینری resolveشده یا glob نام فرمان خام |
| `argPattern` | regex اختیاری argv؛ ورودیهای حذفشده فقط مبتنی بر مسیر هستند |
| `id` | UUID پایدار که برای هویت UI استفاده میشود |
| `source` | منبع ورودی، مانند `allow-always` |
| `commandText` | متن فرمانی که هنگام ایجاد ورودی توسط جریان تأیید ثبت شده است |
| `lastUsedAt` | مُهر زمانی آخرین استفاده |
| `lastUsedCommand` | آخرین فرمانی که تطبیق داده شد |
| `lastResolvedPath` | آخرین مسیر باینری resolveشده |
## CLIهای Skills مجاز خودکار
وقتی **CLIهای Skills مجاز خودکار** فعال باشد، فایلهای اجراییای که توسط Skills شناختهشده ارجاع داده شدهاند، روی Nodeها (Node macOS یا میزبان Node بدون رابط گرافیکی) بهعنوان مجاز در نظر گرفته میشوند. این کار از `skills.bins` روی Gateway RPC برای واکشی فهرست bin مهارت استفاده میکند. اگر فهرستهای مجاز دستی سختگیرانه میخواهید، این گزینه را غیرفعال کنید.
- این یک **فهرست مجاز ضمنی برای راحتی** است، جدا از ورودیهای دستی فهرست مجاز مسیر.
- برای محیطهای اپراتور قابل اعتماد در نظر گرفته شده است که در آن Gateway و Node در یک مرز اعتماد قرار دارند.
- اگر به اعتماد صریح و سختگیرانه نیاز دارید، `autoAllowSkills: false` را نگه دارید و فقط از ورودیهای دستی فهرست مجاز مسیر استفاده کنید.
## binهای امن و هدایت تأیید
برای binهای امن (مسیر سریع فقط stdin)، جزئیات اتصال مفسر، و نحوه هدایت promptهای تأیید به Slack/Discord/Telegram (یا اجرای آنها بهعنوان کلاینتهای تأیید بومی)، ببینید
[تأییدهای exec - پیشرفته](/fa/tools/exec-approvals-advanced).
## ویرایش UI کنترل
از کارت **Control UI → Nodes → Exec approvals** برای ویرایش پیشفرضها، overrideهای هر agent، و فهرستهای مجاز استفاده کنید. یک scope انتخاب کنید (Defaults یا یک agent)، policy را تنظیم کنید، الگوهای فهرست مجاز را اضافه/حذف کنید، سپس **Save** را بزنید. UI فراداده آخرین استفاده را برای هر الگو نشان میدهد تا بتوانید فهرست را مرتب نگه دارید.
انتخابگر مقصد، **Gateway** (تأییدهای محلی) یا یک **Node** را انتخاب میکند. Nodeها باید `system.execApprovals.get/set` را اعلام کنند (اپ macOS یا میزبان Node بدون رابط گرافیکی). اگر یک Node هنوز exec approvals را اعلام نمیکند، فایل محلی `~/.openclaw/exec-approvals.json` آن را مستقیماً ویرایش کنید.
CLI: `openclaw approvals` از ویرایش gateway یا node پشتیبانی میکند - ببینید
[CLI تأییدها](/fa/cli/approvals).
## جریان تأیید
وقتی یک prompt لازم باشد، gateway رویداد
`exec.approval.requested` را برای کلاینتهای اپراتور broadcast میکند. Control UI و اپ macOS آن را از طریق `exec.approval.resolve` resolve میکنند، سپس gateway درخواست تأییدشده را به میزبان node ارسال میکند.
برای `host=node`، درخواستهای تأیید شامل payload استاندارد `systemRunPlan` هستند. gateway هنگام هدایت درخواستهای تأییدشده `system.run` از آن plan بهعنوان زمینه معتبر command/cwd/session استفاده میکند.
این موضوع برای تأخیر تأیید async اهمیت دارد:
- مسیر exec در node از ابتدا یک plan استاندارد آماده میکند.
- رکورد تأیید آن plan و فراداده اتصال آن را ذخیره میکند.
- پس از تأیید، فراخوانی نهایی و هدایتشده `system.run` بهجای اعتماد به ویرایشهای بعدی فراخواننده، از plan ذخیرهشده استفاده میکند.
- اگر فراخواننده پس از ایجاد درخواست تأیید، `command`، `rawCommand`، `cwd`، `agentId`، یا `sessionKey` را تغییر دهد، gateway اجرای هدایتشده را بهعنوان عدم تطابق تأیید رد میکند.
## رویدادهای سیستم
چرخه عمر exec بهصورت پیامهای سیستم نمایش داده میشود:
- `Exec running` (فقط اگر فرمان از آستانه اعلان در حال اجرا فراتر رود).
- `Exec finished`.
- `Exec denied`.
اینها پس از گزارش رویداد توسط node، در session مربوط به agent ارسال میشوند. exec approvals با میزبان Gateway نیز هنگام پایان فرمان همان رویدادهای چرخه عمر را emit میکنند (و بهصورت اختیاری، وقتی اجرا طولانیتر از آستانه شود). execهای gated با تأیید، برای همبستگی آسان، از شناسه تأیید بهعنوان `runId` در این پیامها استفاده میکنند.
## رفتار تأیید ردشده
وقتی یک exec approval async رد شود، OpenClaw از استفاده دوباره agent از خروجی هر اجرای قبلی همان فرمان در session جلوگیری میکند. دلیل رد با راهنمایی صریح ارسال میشود که هیچ خروجی فرمانی در دسترس نیست؛ این باعث میشود agent ادعا نکند خروجی جدیدی وجود دارد یا فرمان ردشده را با نتایج قدیمی از یک اجرای موفق قبلی تکرار نکند.
## پیامدها
- **`full`** قدرتمند است؛ هرجا ممکن است فهرستهای مجاز را ترجیح دهید.
- **`ask`** شما را در جریان نگه میدارد، در حالی که همچنان تأییدهای سریع را ممکن میکند.
- فهرستهای مجاز هر agent از نشت تأییدهای یک agent به دیگران جلوگیری میکنند.
- تأییدها فقط برای درخواستهای exec میزبان از **فرستندههای مجاز** اعمال میشوند. فرستندههای غیرمجاز نمیتوانند `/exec` صادر کنند.
- `/exec security=full` یک قابلیت راحتی در سطح session برای اپراتورهای مجاز است و عمداً تأییدها را رد میکند. برای مسدود کردن سختگیرانه exec میزبان، امنیت تأییدها را روی `deny` تنظیم کنید یا ابزار `exec` را از طریق tool policy رد کنید.
## مرتبط
binهای امن، اتصال مفسر، و هدایت تأیید به chat.
ابزار اجرای فرمان shell.
مسیر break-glass که تأییدها را نیز رد میکند.
حالتهای sandbox و دسترسی workspace.
مدل امنیتی و سختسازی.
چه زمانی سراغ هر کنترل بروید.
رفتار مجازسازی خودکار با پشتوانه Skills.