English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Tools

تأییدهای اجرا — پیشرفته

موضوعات پیشرفتهٔ تأیید exec: مسیر سریع safeBins، اتصال مفسر/زمان اجرا، و بازارسال تأیید به کانال‌های چت (از جمله تحویل بومی). برای سیاست اصلی و جریان تأیید، تأییدهای Exec را ببینید.

باینری‌های امن (فقط stdin)

tools.exec.safeBins فهرست کوچکی از باینری‌های فقط stdin را تعریف می‌کند (برای مثال cut) که می‌توانند در حالت فهرست مجاز بدون ورودی‌های صریح فهرست مجاز اجرا شوند. باینری‌های امن آرگومان‌های فایلی موضعی و توکن‌های شبیه مسیر را رد می‌کنند، بنابراین فقط می‌توانند روی جریان ورودی عمل کنند. این را به‌عنوان یک مسیر سریع محدود برای فیلترهای جریان در نظر بگیرید، نه یک فهرست اعتماد عمومی.

باینری‌های امن پیش‌فرض:

cut, uniq, head, tail, tr, wc

grep و sort در فهرست پیش‌فرض نیستند. اگر آن‌ها را فعال می‌کنید، برای گردش‌کارهای غیر stdin آن‌ها ورودی‌های صریح فهرست مجاز را نگه دارید. برای grep در حالت باینری امن، الگو را با -e/--regexp ارائه کنید؛ شکل الگوی موضعی رد می‌شود تا عملوندهای فایل نتوانند به‌عنوان موضعی‌های مبهم پنهان شوند.

اعتبارسنجی Argv و پرچم‌های ردشده

اعتبارسنجی فقط از شکل argv قطعی است (بدون بررسی وجود فایل در سیستم فایل میزبان)، که از رفتار اوراکل وجود فایل ناشی از تفاوت‌های اجازه/رد جلوگیری می‌کند. گزینه‌های فایل‌محور برای باینری‌های امن پیش‌فرض رد می‌شوند؛ گزینه‌های بلند به‌صورت fail-closed اعتبارسنجی می‌شوند (پرچم‌های ناشناخته و اختصارهای مبهم رد می‌شوند).

پرچم‌های ردشده بر اساس پروفایل باینری امن:

  • grep: --dereference-recursive, --directories, --exclude-from, --file, --recursive, -R, -d, -f, -r
  • jq: --argfile, --from-file, --library-path, --rawfile, --slurpfile, -L, -f
  • sort: --compress-program, --files0-from, --output, --random-source, --temporary-directory, -T, -o
  • wc: --files0-from

باینری‌های امن همچنین توکن‌های argv را در زمان اجرا برای بخش‌های فقط stdin به‌صورت متن لفظی در نظر می‌گیرند (بدون globbing و بدون گسترش $VARS)، بنابراین الگوهایی مانند * یا $HOME/... نمی‌توانند برای پنهان‌کردن خواندن فایل استفاده شوند.

دایرکتوری‌های باینری مورد اعتماد

باینری‌های امن باید از دایرکتوری‌های باینری مورد اعتماد حل شوند (پیش‌فرض‌های سیستم به‌علاوه tools.exec.safeBinTrustedDirs اختیاری). ورودی‌های PATH هرگز به‌صورت خودکار مورد اعتماد نیستند. دایرکتوری‌های مورد اعتماد پیش‌فرض عمداً حداقلی هستند: /bin، /usr/bin. اگر اجرایی باینری امن شما در مسیرهای مدیر بسته/کاربر قرار دارد (برای مثال /opt/homebrew/bin، /usr/local/bin، /opt/local/bin، /snap/bin)، آن‌ها را به‌صراحت به tools.exec.safeBinTrustedDirs اضافه کنید.

زنجیره‌سازی Shell، wrapperها، و multiplexerها

زنجیره‌سازی Shell (&&، ||، ;) زمانی مجاز است که هر بخش سطح بالا فهرست مجاز را برآورده کند (از جمله باینری‌های امن یا مجوز خودکار skill). تغییرمسیرها در حالت فهرست مجاز همچنان پشتیبانی نمی‌شوند. جایگزینی دستور ($() / backticks) در هنگام تحلیل فهرست مجاز رد می‌شود، حتی داخل نقل‌قول‌های دوتایی؛ اگر به متن لفظی $() نیاز دارید از نقل‌قول تکی استفاده کنید.

در تأییدهای companion-app در macOS، متن خام shell که شامل کنترل shell یا نحو گسترش (&&، ||، ;، |، `، $، <، >، (، )) باشد به‌عنوان عدم تطابق با فهرست مجاز در نظر گرفته می‌شود، مگر اینکه خود باینری shell در فهرست مجاز باشد.

برای wrapperهای shell (bash|sh|zsh ... -c/-lc)، بازنویسی‌های env با دامنهٔ درخواست به یک فهرست مجاز صریح کوچک کاهش می‌یابند (TERM، LANG، LC_*، COLORTERM، NO_COLOR، FORCE_COLOR).

برای تصمیم‌های allow-always در حالت فهرست مجاز، wrapperهای dispatch شناخته‌شده (env، nice، nohup، stdbuf، timeout) مسیر اجرایی داخلی را به‌جای مسیر wrapper پایدار می‌کنند. Multiplexerهای shell (busybox، toybox) برای اپلت‌های shell (sh، ash و غیره) به همان شکل باز می‌شوند. اگر یک wrapper یا multiplexer را نتوان با ایمنی باز کرد، هیچ ورودی فهرست مجازی به‌صورت خودکار پایدار نمی‌شود.

اگر مفسرهایی مانند python3 یا node را در فهرست مجاز قرار می‌دهید، بهتر است tools.exec.strictInlineEval=true را فعال کنید تا eval درون‌خطی همچنان به یک تأیید صریح نیاز داشته باشد. در حالت سخت‌گیرانه، allow-always همچنان می‌تواند فراخوانی‌های بی‌خطر مفسر/اسکریپت را پایدار کند، اما حامل‌های eval درون‌خطی به‌صورت خودکار پایدار نمی‌شوند.

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

موضوع tools.exec.safeBins فهرست مجاز (exec-approvals.json)
هدف اجازهٔ خودکار به فیلترهای محدود stdin اعتماد صریح به اجرایی‌های مشخص
نوع تطابق نام اجرایی + سیاست argv باینری امن glob مسیر اجرایی حل‌شده، یا glob نام دستور خام برای دستورهایی که از PATH فراخوانی می‌شوند
دامنهٔ آرگومان محدودشده توسط پروفایل باینری امن و قواعد توکن لفظی تطابق مسیر به‌صورت پیش‌فرض؛ argPattern اختیاری می‌تواند argv تحلیل‌شده را محدود کند
نمونه‌های رایج head, tail, tr, wc jq, python3, node, ffmpeg, CLIهای سفارشی
بهترین کاربرد تبدیل‌های متنی کم‌ریسک در pipelineها هر ابزاری با رفتار یا اثرات جانبی گسترده‌تر

محل پیکربندی:

  • safeBins از پیکربندی می‌آید (tools.exec.safeBins یا agents.list[].tools.exec.safeBins مخصوص هر عامل).
  • safeBinTrustedDirs از پیکربندی می‌آید (tools.exec.safeBinTrustedDirs یا agents.list[].tools.exec.safeBinTrustedDirs مخصوص هر عامل).
  • safeBinProfiles از پیکربندی می‌آید (tools.exec.safeBinProfiles یا agents.list[].tools.exec.safeBinProfiles مخصوص هر عامل). کلیدهای پروفایل مخصوص هر عامل کلیدهای سراسری را بازنویسی می‌کنند.
  • ورودی‌های فهرست مجاز در ~/.openclaw/exec-approvals.json محلی میزبان، زیر agents.<id>.allowlist قرار دارند (یا از طریق Control UI / openclaw approvals allowlist ...).
  • openclaw security audit وقتی باینری‌های مفسر/زمان اجرا بدون پروفایل صریح در safeBins ظاهر شوند، با tools.exec.safe_bins_interpreter_unprofiled هشدار می‌دهد.
  • openclaw doctor --fix می‌تواند ورودی‌های سفارشیِ جاافتادهٔ safeBinProfiles.<bin> را به‌صورت {} بسازد (پس از آن بازبینی و سخت‌گیرانه‌تر کنید). باینری‌های مفسر/زمان اجرا به‌صورت خودکار ساخته نمی‌شوند.

نمونهٔ پروفایل سفارشی: OC_I18N_900000 اگر jq را صریحاً وارد safeBins کنید، OpenClaw همچنان builtin مربوط به env را در حالت باینری امن رد می‌کند تا jq -n env نتواند محیط فرایند میزبان را بدون مسیر صریح فهرست مجاز یا اعلان تأیید dump کند.

دستورهای مفسر/زمان اجرا

اجرای مفسر/زمان اجرا که پشتوانهٔ تأیید دارد عمداً محافظه‌کارانه است:

  • زمینهٔ دقیق argv/cwd/env همیشه متصل می‌شود.
  • شکل‌های مستقیم فایل runtime و اسکریپت shell مستقیم، در حد بهترین تلاش، به یک snapshot مشخص از یک فایل محلی متصل می‌شوند.
  • شکل‌های رایج wrapper مدیر بسته که همچنان به یک فایل محلی مستقیم حل می‌شوند (برای مثال pnpm exec، pnpm node، npm exec، npx) پیش از اتصال باز می‌شوند.
  • اگر OpenClaw نتواند دقیقاً یک فایل محلی مشخص را برای یک دستور مفسر/زمان اجرا شناسایی کند (برای مثال اسکریپت‌های بسته، شکل‌های eval، زنجیره‌های loader مخصوص runtime، یا شکل‌های چندفایلی مبهم)، اجرای پشتوانه‌دار با تأیید رد می‌شود، به‌جای اینکه پوشش معنایی‌ای را ادعا کند که ندارد.
  • برای آن گردش‌کارها، sandboxing، یک مرز میزبان جداگانه، یا یک فهرست مجاز/گردش‌کار کامل و مورد اعتماد صریح را ترجیح دهید که در آن operator معنای گسترده‌تر runtime را می‌پذیرد.

وقتی تأییدها لازم باشند، ابزار exec بلافاصله با یک شناسهٔ تأیید برمی‌گردد. از آن شناسه برای هم‌بسته‌سازی رویدادهای بعدی سیستم (Exec finished / Exec denied) استفاده کنید. اگر پیش از timeout هیچ تصمیمی نرسد، درخواست به‌عنوان timeout تأیید در نظر گرفته می‌شود و به‌عنوان دلیل رد نمایش داده می‌شود.

رفتار تحویل followup

پس از پایان یک exec ناهمگام تأییدشده، OpenClaw یک نوبت followup از نوع agent به همان session می‌فرستد.

  • اگر یک هدف تحویل خارجی معتبر وجود داشته باشد (کانال قابل تحویل به‌علاوه هدف to)، تحویل followup از همان کانال استفاده می‌کند.
  • در جریان‌های فقط webchat یا session داخلی بدون هدف خارجی، تحویل followup فقط در session می‌ماند (deliver: false).
  • اگر یک caller تحویل خارجی سخت‌گیرانه را صریحاً درخواست کند اما کانال خارجی قابل حل وجود نداشته باشد، درخواست با INVALID_REQUEST شکست می‌خورد.
  • اگر bestEffortDeliver فعال باشد و هیچ کانال خارجی‌ای قابل حل نباشد، تحویل به‌جای شکست به حالت فقط session تنزل می‌یابد.

بازارسال تأیید به کانال‌های چت

می‌توانید اعلان‌های تأیید exec را به هر کانال چت (از جمله کانال‌های Plugin) بازارسال کنید و آن‌ها را با /approve تأیید کنید. این کار از pipeline عادی تحویل خروجی استفاده می‌کند.

پیکربندی: OC_I18N_900001 پاسخ در چت: OC_I18N_900002 دستور /approve هم تأییدهای exec و هم تأییدهای Plugin را مدیریت می‌کند. اگر ID با تأیید exec در انتظار مطابقت نداشته باشد، به‌صورت خودکار تأییدهای Plugin را بررسی می‌کند.

بازارسال تأیید Plugin

بازارسال تأیید Plugin از همان pipeline تحویل تأییدهای exec استفاده می‌کند، اما پیکربندی مستقل خود را زیر approvals.plugin دارد. فعال یا غیرفعال‌کردن یکی روی دیگری اثر نمی‌گذارد. OC_I18N_900003 شکل پیکربندی با approvals.exec یکسان است: enabled، mode، agentFilter، sessionFilter و targets به همان روش کار می‌کنند.

کانال‌هایی که از پاسخ‌های تعاملی مشترک پشتیبانی می‌کنند، همان دکمه‌های تأیید را برای هر دو تأیید exec و Plugin نمایش می‌دهند. کانال‌های بدون UI تعاملی مشترک به متن ساده با دستورالعمل‌های /approve بازمی‌گردند. درخواست‌های تأیید Plugin ممکن است تصمیم‌های در دسترس را محدود کنند. سطوح تأیید از مجموعهٔ تصمیم‌های اعلام‌شدهٔ درخواست استفاده می‌کنند، و Gateway تلاش برای ارسال تصمیمی را که ارائه نشده بود رد می‌کند.

تأییدهای همان چت در هر کانال

وقتی یک درخواست تأیید exec یا Plugin از یک سطح چت قابل تحویل سرچشمه می‌گیرد، همان چت اکنون می‌تواند به‌صورت پیش‌فرض آن را با /approve تأیید کند. این علاوه بر جریان‌های موجود Web UI و terminal UI، برای کانال‌هایی مانند Slack، Matrix و Microsoft Teams نیز اعمال می‌شود.

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

Discord و Telegram نیز از /approve در همان چت پشتیبانی می‌کنند، اما این کانال‌ها حتی وقتی تحویل تأیید بومی غیرفعال باشد، همچنان از فهرست تأییدکنندگان حل‌شدهٔ خود برای مجوزدهی استفاده می‌کنند.

برای Telegram و دیگر مشتریان تأیید بومی که Gateway را مستقیماً فراخوانی می‌کنند، این fallback عمداً به شکست‌های «تأیید یافت نشد» محدود شده است. یک رد/خطای واقعی تأیید exec بی‌صدا به‌عنوان تأیید Plugin دوباره تلاش نمی‌شود.

تحویل تأیید بومی

برخی کانال‌ها می‌توانند به‌عنوان کلاینت‌های تأیید بومی نیز عمل کنند. کلاینت‌های بومی، DMهای تأییدکنندگان، انتشار به چت مبدأ، و تجربه کاربری تعاملی تأیید مخصوص کانال را روی جریان مشترک /approve در همان چت اضافه می‌کنند.

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

اگر یک کلاینت تأیید بومی پیکربندی شده باشد اما هیچ زمان‌اجرای بومی برای کانال مبدأ فعال نباشد، OpenClaw اعلان قطعی محلی /approve را قابل مشاهده نگه می‌دارد. اگر زمان‌اجرای بومی فعال باشد و ارسال را تلاش کند اما هیچ هدفی کارت را دریافت نکند، OpenClaw یک اعلان جایگزین در همان چت با دستور دقیق /approve <id> <decision> می‌فرستد تا درخواست همچنان قابل حل باشد.

مدل عمومی:

  • سیاست اجرای میزبان همچنان تعیین می‌کند که آیا تأیید exec لازم است یا نه
  • approvals.exec ارسال اعلان‌های تأیید به مقصدهای چتی دیگر را کنترل می‌کند
  • channels.<channel>.execApprovals کنترل می‌کند که آیا آن کانال به‌عنوان یک کلاینت تأیید بومی عمل می‌کند یا نه

کلاینت‌های تأیید بومی وقتی همه این موارد درست باشند، تحویل ابتدا-به-DM را خودکار فعال می‌کنند:

  • کانال از تحویل تأیید بومی پشتیبانی کند
  • تأییدکنندگان بتوانند از execApprovals.approvers صریح یا هویت مالک مانند commands.ownerAllowFrom تشخیص داده شوند
  • channels.<channel>.execApprovals.enabled تنظیم نشده باشد یا "auto" باشد

برای غیرفعال کردن صریح یک کلاینت تأیید بومی، enabled: false را تنظیم کنید. برای فعال‌سازی اجباری آن وقتی تأییدکنندگان تشخیص داده می‌شوند، enabled: true را تنظیم کنید. تحویل عمومی به چت مبدأ از طریق channels.<channel>.execApprovals.target همچنان صریح باقی می‌ماند.

پرسش متداول: چرا برای تأییدهای چتی دو پیکربندی تأیید exec وجود دارد؟

  • Discord: channels.discord.execApprovals.*
  • Slack: channels.slack.execApprovals.*
  • Telegram: channels.telegram.execApprovals.*

این کلاینت‌های تأیید بومی، مسیریابی DM و انتشار اختیاری به کانال را روی جریان مشترک /approve در همان چت و دکمه‌های تأیید مشترک اضافه می‌کنند.

رفتار مشترک:

  • Slack، Matrix، Microsoft Teams، و چت‌های قابل‌تحویل مشابه از مدل احراز هویت معمول کانال برای /approve در همان چت استفاده می‌کنند
  • وقتی یک کلاینت تأیید بومی خودکار فعال می‌شود، هدف پیش‌فرض تحویل بومی DMهای تأییدکنندگان است
  • برای Discord و Telegram، فقط تأییدکنندگان تشخیص‌داده‌شده می‌توانند تأیید یا رد کنند
  • تأییدکنندگان Discord می‌توانند صریح باشند (execApprovals.approvers) یا از commands.ownerAllowFrom استنباط شوند
  • تأییدکنندگان Telegram می‌توانند صریح باشند (execApprovals.approvers) یا از commands.ownerAllowFrom استنباط شوند
  • تأییدکنندگان Slack می‌توانند صریح باشند (execApprovals.approvers) یا از commands.ownerAllowFrom استنباط شوند
  • دکمه‌های بومی Slack نوع شناسه تأیید را حفظ می‌کنند، بنابراین شناسه‌های plugin: می‌توانند تأییدهای Plugin را بدون یک لایه جایگزین دوم محلیِ Slack حل کنند
  • مسیریابی بومی DM/کانال و میان‌برهای واکنش در Matrix هم تأییدهای exec و هم تأییدهای Plugin را مدیریت می‌کنند؛ مجوزدهی Plugin همچنان از channels.matrix.dm.allowFrom می‌آید
  • اعلان‌های بومی Matrix محتوای رویداد سفارشی com.openclaw.approval را در رویداد اعلان اول شامل می‌شوند تا کلاینت‌های Matrix آگاه از OpenClaw بتوانند وضعیت ساختاریافته تأیید را بخوانند، در حالی که کلاینت‌های معمولی جایگزین متنی ساده /approve را نگه می‌دارند
  • درخواست‌دهنده لازم نیست تأییدکننده باشد
  • چت مبدأ وقتی از قبل از دستورها و پاسخ‌ها پشتیبانی می‌کند، می‌تواند مستقیماً با /approve تأیید کند
  • دکمه‌های تأیید بومی Discord بر اساس نوع شناسه تأیید مسیریابی می‌کنند: شناسه‌های plugin: مستقیماً به تأییدهای Plugin می‌روند، و هر چیز دیگر به تأییدهای exec می‌رود
  • دکمه‌های تأیید بومی Telegram همان جایگزین محدود exec-به-Plugin را مانند /approve دنبال می‌کنند
  • وقتی target بومی تحویل به چت مبدأ را فعال می‌کند، اعلان‌های تأیید متن دستور را شامل می‌شوند
  • تأییدهای exec معلق به‌طور پیش‌فرض پس از ۳۰ دقیقه منقضی می‌شوند
  • اگر هیچ رابط کاربری اپراتور یا کلاینت تأیید پیکربندی‌شده‌ای نتواند درخواست را بپذیرد، اعلان به askFallback برمی‌گردد

دستورهای گروهی حساس و فقط-مالک مانند /diagnostics و /export-trajectory از مسیریابی خصوصی مالک برای اعلان‌های تأیید و نتایج نهایی استفاده می‌کنند. OpenClaw ابتدا یک مسیر خصوصی را روی همان سطحی امتحان می‌کند که مالک دستور را در آن اجرا کرده است. اگر آن سطح مسیر خصوصی مالک نداشته باشد، به اولین مسیر مالک در دسترس از commands.ownerAllowFrom برمی‌گردد، بنابراین یک دستور گروهی Discord همچنان می‌تواند تأیید و نتیجه را به DM مالک در Telegram بفرستد وقتی Telegram به‌عنوان رابط خصوصی اصلی پیکربندی شده باشد. چت گروهی فقط یک تأیید کوتاه دریافت می‌کند.

Telegram به‌طور پیش‌فرض از DMهای تأییدکنندگان استفاده می‌کند (target: "dm"). وقتی می‌خواهید اعلان‌های تأیید در چت/موضوع Telegram مبدأ نیز ظاهر شوند، می‌توانید به channel یا both تغییر دهید. برای موضوع‌های انجمن Telegram، OpenClaw موضوع را برای اعلان تأیید و پیگیری پس از تأیید حفظ می‌کند.

ببینید:

جریان IPC در macOS

OC_I18N_900004 یادداشت‌های امنیتی:

  • حالت سوکت یونیکس 0600، توکن ذخیره‌شده در exec-approvals.json.
  • بررسی همتای همان-UID.
  • چالش/پاسخ (nonce + توکن HMAC + هش درخواست) + TTL کوتاه.

مرتبط