diff --git a/docs/fa/automation/tasks.md b/docs/fa/automation/tasks.md index 5119e76d7..8e7559045 100644 --- a/docs/fa/automation/tasks.md +++ b/docs/fa/automation/tasks.md @@ -2,51 +2,51 @@ read_when: - بررسی کارهای پس‌زمینه در حال انجام یا اخیراً تکمیل‌شده - اشکال‌زدایی از شکست‌های تحویل در اجراهای جداشدهٔ عامل - - درک اینکه اجراهای پس‌زمینه چگونه با جلسه‌ها، Cron و Heartbeat ارتباط دارند + - درک اینکه اجراهای پس‌زمینه چگونه با نشست‌ها، Cron و Heartbeat ارتباط دارند sidebarTitle: Background tasks -summary: ردیابی کارهای پس‌زمینه برای اجراهای ACP، زیرعامل‌ها، کارهای Cron مجزا، و عملیات CLI +summary: ردیابی وظایف پس‌زمینه برای اجراهای ACP، زیرعامل‌ها، کارهای Cron ایزوله، و عملیات CLI title: وظایف پس‌زمینه x-i18n: - generated_at: "2026-05-01T11:42:31Z" + generated_at: "2026-05-05T01:44:27Z" model: gpt-5.5 provider: openai - source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 + source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 source_path: automation/tasks.md workflow: 16 --- -دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار مناسب، [خودکارسازی و وظایف](/fa/automation) را ببینید. این صفحه دفتر ثبت فعالیت کارهای پس‌زمینه است، نه زمان‌بند. +دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار مناسب، [اتوماسیون و وظایف](/fa/automation) را ببینید. این صفحه دفتر فعالیت کارهای پس‌زمینه است، نه زمان‌بند. -وظایف پس‌زمینه کارهایی را ردیابی می‌کنند که **خارج از نشست گفت‌وگوی اصلی شما** اجرا می‌شوند: اجراهای ACP، ایجاد عامل‌های فرعی، اجرای جداافتاده کارهای Cron، و عملیات‌هایی که از CLI آغاز شده‌اند. +وظایف پس‌زمینه کارهایی را ردیابی می‌کنند که **خارج از نشست گفت‌وگوی اصلی شما** اجرا می‌شوند: اجرای ACP، ایجاد زیرعامل‌ها، اجرای jobهای cron ایزوله، و عملیات آغازشده از CLI. -وظایف جایگزین نشست‌ها، کارهای Cron یا Heartbeatها نمی‌شوند — آن‌ها **دفتر ثبت فعالیت** هستند که ثبت می‌کند چه کار جداشده‌ای رخ داده، چه زمانی رخ داده و آیا موفق بوده است یا نه. +وظایف جایگزین نشست‌ها، jobهای cron یا heartbeats نیستند — آن‌ها **دفتر فعالیت** هستند که ثبت می‌کند چه کار جداشده‌ای انجام شده، چه زمانی، و آیا موفق بوده است یا نه. -هر اجرای عامل یک وظیفه ایجاد نمی‌کند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی عادی این کار را نمی‌کنند. همه اجراهای Cron، ایجادهای ACP، ایجادهای عامل فرعی و فرمان‌های عامل CLI این کار را انجام می‌دهند. +هر اجرای عامل یک وظیفه ایجاد نمی‌کند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی معمولی این کار را نمی‌کنند. همه اجرای‌های cron، ایجادهای ACP، ایجادهای زیرعامل، و فرمان‌های عامل CLI این کار را می‌کنند. -## خلاصه +## خلاصه سریع -- وظایف **رکورد** هستند، نه زمان‌بند — Cron و Heartbeat تصمیم می‌گیرند کار _چه زمانی_ اجرا شود، وظایف ردیابی می‌کنند _چه اتفاقی افتاده است_. -- ACP، عامل‌های فرعی، همه کارهای Cron و عملیات CLI وظیفه ایجاد می‌کنند. نوبت‌های Heartbeat این کار را نمی‌کنند. -- هر وظیفه از مسیر `queued → running → terminal` عبور می‌کند (succeeded، failed، timed_out، cancelled یا lost). -- وظایف Cron تا وقتی زنده می‌مانند که زمان‌اجرای Cron هنوز مالک کار باشد؛ اگر - وضعیت زمان‌اجرای درون‌حافظه‌ای از بین رفته باشد، نگهداشت وظیفه پیش از علامت‌گذاری یک وظیفه به‌عنوان lost، ابتدا تاریخچه پایدار اجرای Cron را بررسی می‌کند. -- تکمیل مبتنی بر ارسال است: کار جداشده می‌تواند مستقیما اطلاع دهد یا هنگام پایان، - نشست/Heartbeat درخواست‌دهنده را بیدار کند، بنابراین حلقه‌های polling وضعیت +- وظایف **رکورد** هستند، نه زمان‌بند — cron و heartbeat تصمیم می‌گیرند کار _چه زمانی_ اجرا شود، وظایف ردیابی می‌کنند _چه اتفاقی افتاده است_. +- ACP، زیرعامل‌ها، همه jobهای cron، و عملیات CLI وظیفه ایجاد می‌کنند. نوبت‌های Heartbeat این کار را نمی‌کنند. +- هر وظیفه از مسیر `queued → running → terminal` عبور می‌کند (succeeded، failed، timed_out، cancelled، یا lost). +- وظایف cron تا زمانی زنده می‌مانند که runtime کران همچنان مالک job باشد؛ اگر + وضعیت runtime درون‌حافظه‌ای از بین رفته باشد، نگهداری وظیفه پیش از علامت‌گذاری وظیفه به‌عنوان lost، ابتدا تاریخچه پایدار اجرای cron را بررسی می‌کند. +- تکمیل مبتنی بر push است: کار جداشده می‌تواند مستقیما اطلاع دهد یا پس از پایان، + نشست/heartbeat درخواست‌کننده را بیدار کند، بنابراین حلقه‌های polling وضعیت معمولا شکل درستی نیستند. -- اجراهای جداافتاده Cron و تکمیل‌های عامل فرعی به‌صورت best-effort زبانه‌ها/فرایندهای مرورگر ردیابی‌شده را برای نشست فرزندشان پیش از حسابداری پاک‌سازی نهایی پاک می‌کنند. -- تحویل جداافتاده Cron پاسخ‌های میانی قدیمی والد را تا زمانی که کار عامل فرعی نواده هنوز در حال تخلیه است سرکوب می‌کند، و وقتی خروجی نهایی نواده پیش از تحویل برسد، آن را ترجیح می‌دهد. -- اعلان‌های تکمیل مستقیما به یک کانال تحویل داده می‌شوند یا برای Heartbeat بعدی در صف قرار می‌گیرند. -- `openclaw tasks list` همه وظایف را نشان می‌دهد؛ `openclaw tasks audit` مشکلات را آشکار می‌کند. -- رکوردهای پایانی ۷ روز نگه داشته می‌شوند، سپس به‌صورت خودکار پاک‌سازی می‌شوند. +- اجرای‌های cron ایزوله و تکمیل‌های زیرعامل به‌صورت best-effort تب‌ها/فرایندهای مرورگر ردیابی‌شده را برای نشست فرزند خود پیش از حسابداری پاک‌سازی نهایی پاک می‌کنند. +- تحویل cron ایزوله پاسخ‌های میانی کهنه والد را تا زمانی که کار زیرعامل نواده هنوز در حال تخلیه است سرکوب می‌کند، و وقتی خروجی نهایی نواده پیش از تحویل برسد آن را ترجیح می‌دهد. +- اعلان‌های تکمیل مستقیما به یک کانال تحویل داده می‌شوند یا برای Heartbeat بعدی صف می‌شوند. +- `openclaw tasks list` همه وظایف را نشان می‌دهد؛ `openclaw tasks audit` مشکلات را نمایان می‌کند. +- رکوردهای terminal برای ۷ روز نگه داشته می‌شوند، سپس به‌صورت خودکار پاک‌سازی می‌شوند. ## شروع سریع - + ```bash # List all tasks (newest first) openclaw tasks list @@ -57,13 +57,13 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -73,7 +73,7 @@ x-i18n: ``` - + ```bash # Run a health audit openclaw tasks audit @@ -84,7 +84,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -94,29 +94,29 @@ x-i18n: -## چه چیزی یک وظیفه ایجاد می‌کند +## چه چیزی وظیفه ایجاد می‌کند -| منبع | نوع زمان‌اجرا | زمانی که رکورد وظیفه ایجاد می‌شود | سیاست اعلان پیش‌فرض | +| منبع | نوع runtime | زمان ایجاد رکورد وظیفه | سیاست اعلان پیش‌فرض | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| اجراهای پس‌زمینه ACP | `acp` | ایجاد یک نشست ACP فرزند | `done_only` | -| هماهنگ‌سازی عامل فرعی | `subagent` | ایجاد یک عامل فرعی از طریق `sessions_spawn` | `done_only` | -| کارهای Cron (همه انواع) | `cron` | هر اجرای Cron (نشست اصلی و جداافتاده) | `silent` | +| اجرای‌های پس‌زمینه ACP | `acp` | ایجاد نشست فرزند ACP | `done_only` | +| هماهنگ‌سازی زیرعامل | `subagent` | ایجاد زیرعامل از طریق `sessions_spawn` | `done_only` | +| jobهای cron (همه انواع) | `cron` | هر اجرای cron (نشست اصلی و ایزوله) | `silent` | | عملیات CLI | `cli` | فرمان‌های `openclaw agent` که از طریق Gateway اجرا می‌شوند | `silent` | -| کارهای رسانه عامل | `cli` | اجراهای مبتنی بر نشست `music_generate`/`video_generate` | `silent` | +| jobهای رسانه عامل | `cli` | اجرای‌های مبتنی بر نشست `music_generate`/`video_generate` | `silent` | - - وظایف Cron نشست اصلی به‌صورت پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند — آن‌ها رکوردهایی برای ردیابی ایجاد می‌کنند، اما اعلان تولید نمی‌کنند. وظایف Cron جداافتاده نیز به‌صورت پیش‌فرض `silent` هستند، اما چون در نشست خودشان اجرا می‌شوند، نمایان‌ترند. + + وظایف cron نشست اصلی به‌طور پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند — آن‌ها برای ردیابی رکورد ایجاد می‌کنند اما اعلان تولید نمی‌کنند. وظایف cron ایزوله نیز به‌طور پیش‌فرض `silent` هستند، اما چون در نشست خودشان اجرا می‌شوند بیشتر دیده می‌شوند. - اجراهای مبتنی بر نشست `music_generate` و `video_generate` نیز از سیاست اعلان `silent` استفاده می‌کنند. آن‌ها همچنان رکوردهای وظیفه ایجاد می‌کنند، اما تکمیل به‌صورت یک بیدارسازی داخلی به نشست عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و رسانه تمام‌شده را خودش پیوست کند. اگر `tools.media.asyncCompletion.directSend` را فعال کنید، تکمیل‌های async `video_generate` می‌توانند ابتدا تحویل مستقیم به کانال را امتحان کنند؛ تکمیل‌های async `music_generate` در مسیر بیدارسازی نشست درخواست‌دهنده می‌مانند. + اجرای‌های مبتنی بر نشست `music_generate` و `video_generate` نیز از سیاست اعلان `silent` استفاده می‌کنند. آن‌ها همچنان رکورد وظیفه ایجاد می‌کنند، اما تکمیل به‌عنوان یک بیدارباش داخلی به نشست عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و رسانه تکمیل‌شده را خودش پیوست کند. تکمیل‌های گروه/کانال از سیاست معمول پاسخ قابل‌مشاهده پیروی می‌کنند، بنابراین وقتی تحویل منبع آن را لازم بداند، عامل از ابزار پیام استفاده می‌کند. - - وقتی یک وظیفه مبتنی بر نشست `video_generate` هنوز فعال است، ابزار همچنین مانند یک محافظ عمل می‌کند: فراخوانی‌های تکراری `video_generate` در همان نشست، به‌جای شروع یک تولید هم‌زمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل یک جست‌وجوی صریح پیشرفت/وضعیت می‌خواهید، از `action: "status"` استفاده کنید. + + تا زمانی که یک وظیفه مبتنی بر نشست `video_generate` هنوز فعال است، ابزار نیز نقش حفاظتی دارد: فراخوانی‌های تکراری `video_generate` در همان نشست، به‌جای شروع تولید هم‌زمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل به جست‌وجوی صریح پیشرفت/وضعیت نیاز دارید از `action: "status"` استفاده کنید. - + - نوبت‌های Heartbeat — نشست اصلی؛ [Heartbeat](/fa/gateway/heartbeat) را ببینید - - نوبت‌های گفت‌وگوی تعاملی عادی + - نوبت‌های گفت‌وگوی تعاملی معمولی - پاسخ‌های مستقیم `/command` @@ -136,52 +136,58 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| وضعیت | معنی آن | +| وضعیت | معنای آن | | ----------- | -------------------------------------------------------------------------- | -| `queued` | ایجاد شده، در انتظار شروع عامل | -| `running` | نوبت عامل به‌صورت فعال در حال اجرا است | -| `succeeded` | با موفقیت کامل شد | -| `failed` | با خطا کامل شد | -| `timed_out` | از مهلت پیکربندی‌شده فراتر رفت | -| `cancelled` | توسط اپراتور از طریق `openclaw tasks cancel` متوقف شد | -| `lost` | زمان‌اجرا پس از یک دوره ارفاق ۵ دقیقه‌ای وضعیت پشتیبان معتبر را از دست داد | +| `queued` | ایجاد شده، در انتظار شروع عامل | +| `running` | نوبت عامل فعالانه در حال اجرا است | +| `succeeded` | با موفقیت کامل شد | +| `failed` | با خطا کامل شد | +| `timed_out` | از timeout پیکربندی‌شده عبور کرد | +| `cancelled` | توسط اپراتور از طریق `openclaw tasks cancel` متوقف شد | +| `lost` | runtime پس از یک مهلت ۵ دقیقه‌ای وضعیت پشتیبان معتبر را از دست داد | -گذارها به‌صورت خودکار رخ می‌دهند — وقتی اجرای عامل مرتبط پایان می‌یابد، وضعیت وظیفه برای مطابقت با آن به‌روزرسانی می‌شود. +انتقال‌ها به‌صورت خودکار رخ می‌دهند — وقتی اجرای عامل مرتبط پایان یابد، وضعیت وظیفه برای مطابقت با آن به‌روزرسانی می‌شود. -تکمیل اجرای عامل برای رکوردهای وظیفه فعال مرجع است. یک اجرای جداشده موفق به‌صورت `succeeded` نهایی می‌شود، خطاهای معمول اجرا به‌صورت `failed` نهایی می‌شوند، و نتایج timeout یا abort به‌صورت `timed_out` نهایی می‌شوند. اگر اپراتور از قبل وظیفه را لغو کرده باشد، یا زمان‌اجرا از قبل یک وضعیت پایانی قوی‌تر مانند `failed`، `timed_out` یا `lost` ثبت کرده باشد، سیگنال موفقیت بعدی آن وضعیت پایانی را پایین‌تر نمی‌آورد. +تکمیل اجرای عامل برای رکوردهای وظیفه فعال مرجع معتبر است. یک اجرای جداشده موفق به‌صورت `succeeded` نهایی می‌شود، خطاهای معمول اجرا به‌صورت `failed` نهایی می‌شوند، و پیامدهای timeout یا abort به‌صورت `timed_out` نهایی می‌شوند. اگر اپراتور قبلا وظیفه را لغو کرده باشد، یا runtime از قبل وضعیت terminal قوی‌تری مانند `failed`، `timed_out`، یا `lost` را ثبت کرده باشد، سیگنال موفقیت بعدی آن وضعیت terminal را کاهش نمی‌دهد. -`lost` از زمان‌اجرا آگاه است: +`lost` نسبت به runtime آگاه است: -- وظایف ACP: فراداده نشست ACP فرزند پشتیبان ناپدید شد. -- وظایف عامل فرعی: نشست فرزند پشتیبان از مخزن عامل هدف ناپدید شد. -- وظایف Cron: زمان‌اجرای Cron دیگر کار را به‌عنوان فعال ردیابی نمی‌کند و تاریخچه پایدار اجرای Cron برای آن اجرا نتیجه پایانی نشان نمی‌دهد. audit آفلاین CLI وضعیت خالی زمان‌اجرای Cron درون‌فرایندی خودش را مرجع در نظر نمی‌گیرد. -- وظایف CLI: وظایف نشست فرزند جداافتاده از نشست فرزند استفاده می‌کنند؛ وظایف CLI مبتنی بر چت به‌جای آن از زمینه اجرای زنده استفاده می‌کنند، بنابراین ردیف‌های نشست کانال/گروه/مستقیم باقی‌مانده آن‌ها را زنده نگه نمی‌دارند. اجراهای `openclaw agent` مبتنی بر Gateway نیز از نتیجه اجرای خود نهایی می‌شوند، بنابراین اجراهای کامل‌شده تا وقتی جاروبگر آن‌ها را `lost` علامت بزند فعال نمی‌مانند. +- وظایف ACP: فراداده نشست فرزند ACP پشتیبان ناپدید شد. +- وظایف زیرعامل: نشست فرزند پشتیبان از store عامل هدف ناپدید شد. +- وظایف cron: runtime کران دیگر job را به‌عنوان فعال ردیابی نمی‌کند و تاریخچه + پایدار اجرای cron نتیجه terminal برای آن اجرا نشان نمی‌دهد. ممیزی CLI آفلاین + وضعیت خالی runtime cron درون‌فرایندی خودش را به‌عنوان مرجع معتبر در نظر نمی‌گیرد. +- وظایف CLI: وظایف نشست فرزند ایزوله از نشست فرزند استفاده می‌کنند؛ وظایف CLI + مبتنی بر چت به‌جای آن از زمینه اجرای زنده استفاده می‌کنند، بنابراین ردیف‌های + ماندگار نشست کانال/گروه/مستقیم آن‌ها را زنده نگه نمی‌دارند. اجرای‌های + `openclaw agent` مبتنی بر Gateway نیز از نتیجه اجرای خود نهایی می‌شوند، بنابراین اجرای‌های کامل‌شده + تا زمانی که sweeper آن‌ها را `lost` علامت بزند فعال نمی‌مانند. ## تحویل و اعلان‌ها -وقتی یک وظیفه به وضعیت پایانی می‌رسد، OpenClaw به شما اطلاع می‌دهد. دو مسیر تحویل وجود دارد: +وقتی یک وظیفه به وضعیت terminal می‌رسد، OpenClaw به شما اطلاع می‌دهد. دو مسیر تحویل وجود دارد: -**تحویل مستقیم** — اگر وظیفه یک هدف کانال داشته باشد (`requesterOrigin`)، پیام تکمیل مستقیما به همان کانال می‌رود (Telegram، Discord، Slack و غیره). برای تکمیل‌های عامل فرعی، OpenClaw همچنین در صورت وجود، مسیریابی thread/topic متصل را حفظ می‌کند و می‌تواند پیش از رها کردن تحویل مستقیم، یک `to` / حساب مفقود را از مسیر ذخیره‌شده نشست درخواست‌دهنده (`lastChannel` / `lastTo` / `lastAccountId`) پر کند. +**تحویل مستقیم** — اگر وظیفه هدف کانال داشته باشد (`requesterOrigin`)، پیام تکمیل مستقیما به آن کانال می‌رود (Telegram، Discord، Slack، و غیره). برای تکمیل‌های زیرعامل، OpenClaw همچنین در صورت موجود بودن، مسیریابی thread/topic متصل را حفظ می‌کند و می‌تواند پیش از صرف‌نظر از تحویل مستقیم، مقدار `to` / account مفقود را از مسیر ذخیره‌شده نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر کند. -**تحویل صف‌شده در نشست** — اگر تحویل مستقیم شکست بخورد یا هیچ مبدا تنظیم نشده باشد، به‌روزرسانی به‌عنوان یک رویداد سیستم در نشست درخواست‌دهنده صف می‌شود و در Heartbeat بعدی ظاهر می‌شود. +**تحویل صف‌شده در نشست** — اگر تحویل مستقیم شکست بخورد یا هیچ origin تنظیم نشده باشد، به‌روزرسانی به‌عنوان یک رویداد سیستمی در نشست درخواست‌کننده صف می‌شود و در Heartbeat بعدی ظاهر می‌شود. -تکمیل وظیفه یک بیدارسازی فوری Heartbeat را فعال می‌کند تا نتیجه را سریع ببینید — لازم نیست تا تیک زمان‌بندی‌شده بعدی Heartbeat صبر کنید. +تکمیل وظیفه یک بیدارباش فوری Heartbeat را فعال می‌کند تا نتیجه را سریع ببینید — لازم نیست تا تیک زمان‌بندی‌شده بعدی Heartbeat صبر کنید. -این یعنی گردش کار معمول مبتنی بر ارسال است: کار جداشده را یک بار شروع کنید، سپس اجازه دهید زمان‌اجرا هنگام تکمیل شما را بیدار کند یا اطلاع دهد. وضعیت وظیفه را فقط زمانی polling کنید که به اشکال‌زدایی، مداخله یا audit صریح نیاز دارید. +این یعنی workflow معمول مبتنی بر push است: کار جداشده را یک‌بار شروع کنید، سپس اجازه دهید runtime پس از تکمیل شما را بیدار یا مطلع کند. وضعیت وظیفه را فقط زمانی poll کنید که به اشکال‌زدایی، مداخله، یا ممیزی صریح نیاز دارید. ### سیاست‌های اعلان -میزان اطلاع‌رسانی درباره هر وظیفه را کنترل کنید: +کنترل کنید درباره هر وظیفه چقدر بشنوید: -| سیاست | آنچه تحویل داده می‌شود | +| سیاست | آنچه تحویل داده می‌شود | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (پیش‌فرض) | فقط وضعیت پایانی (succeeded، failed و غیره) — **این حالت پیش‌فرض است** | -| `state_changes` | هر گذار وضعیت و به‌روزرسانی پیشرفت | -| `silent` | هیچ چیز | +| `done_only` (پیش‌فرض) | فقط وضعیت terminal (succeeded، failed، و غیره) — **این پیش‌فرض است** | +| `state_changes` | هر انتقال وضعیت و به‌روزرسانی پیشرفت | +| `silent` | هیچ چیز | -سیاست را در حین اجرای وظیفه تغییر دهید: +سیاست را در حالی که وظیفه در حال اجرا است تغییر دهید: ```bash openclaw tasks notify state_changes @@ -203,7 +209,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - توکن جست‌وجو یک شناسه وظیفه، شناسه اجرا یا کلید نشست را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا و خلاصه پایانی را نشان می‌دهد. + توکن lookup یک شناسه وظیفه، شناسه اجرا، یا کلید نشست را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا، و خلاصه terminal را نشان می‌دهد. @@ -211,7 +217,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - برای وظایف ACP و عامل فرعی، این کار نشست فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (دسته زمان‌اجرای فرزند جداگانه‌ای وجود ندارد). وضعیت به `cancelled` گذار می‌کند و در صورت کاربرد، اعلان تحویل ارسال می‌شود. + برای وظایف ACP و زیرعامل، این کار نشست فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (هیچ handle جداگانه‌ای برای runtime فرزند وجود ندارد). وضعیت به `cancelled` منتقل می‌شود و در صورت کاربرد، اعلان تحویل ارسال می‌شود. @@ -224,63 +230,63 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - مشکلات عملیاتی را آشکار می‌کند. یافته‌ها هنگام شناسایی مشکل‌ها در `openclaw status` نیز ظاهر می‌شوند. + مشکلات عملیاتی را نمایان می‌کند. وقتی مشکلات شناسایی شوند، یافته‌ها در `openclaw status` نیز ظاهر می‌شوند. - | یافته | شدت | محرک | + | یافته | شدت | محرک | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | - | `stale_queued` | هشدار | بیش از ۱۰ دقیقه در صف مانده است | - | `stale_running` | خطا | بیش از ۳۰ دقیقه در حال اجرا بوده است | - | `lost` | هشدار/خطا | مالکیت وظیفه با پشتوانه runtime ناپدید شد؛ وظایف گم‌شده حفظ‌شده تا `cleanupAfter` هشدار می‌دهند و سپس به خطا تبدیل می‌شوند | - | `delivery_failed` | هشدار | تحویل ناموفق بود و سیاست اعلان `silent` نیست | - | `missing_cleanup` | هشدار | وظیفه پایانی بدون timestamp پاک‌سازی | - | `inconsistent_timestamps` | هشدار | نقض خط زمانی (برای مثال، قبل از شروع پایان یافته است) | + | `stale_queued` | هشدار | بیش از 10 دقیقه در صف مانده است | + | `stale_running` | خطا | بیش از 30 دقیقه در حال اجرا بوده است | + | `lost` | هشدار/خطا | مالکیت وظیفه متکی به زمان اجرا ناپدید شده است؛ وظایف گم‌شده نگه‌داشته‌شده تا `cleanupAfter` هشدار می‌دهند، سپس به خطا تبدیل می‌شوند | + | `delivery_failed` | هشدار | تحویل ناموفق بوده و سیاست اعلان `silent` نیست | + | `missing_cleanup` | هشدار | وظیفه پایانی بدون زمان‌مهر پاک‌سازی | + | `inconsistent_timestamps` | هشدار | نقض خط زمانی (برای مثال، پیش از شروع پایان یافته است) | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - از این برای پیش‌نمایش یا اعمال همگام‌سازی مجدد، ثبت پاک‌سازی، و هرس کردن برای وظایف و وضعیت Task Flow استفاده کنید. + از این برای پیش‌نمایش یا اعمال همسوسازی، ثبت زمان‌مهر پاک‌سازی، و هرس کردن وظایف و وضعیت Task Flow استفاده کنید. - همگام‌سازی مجدد از runtime آگاه است: + همسوسازی از زمان اجرا آگاه است: - - وظایف ACP/subagent نشست فرزند پشتیبان خود را بررسی می‌کنند. - - وظایف subagent که نشست فرزندشان tombstone بازیابی پس از restart دارد، به‌جای اینکه به‌عنوان نشست‌های پشتیبان قابل بازیابی تلقی شوند، گم‌شده علامت‌گذاری می‌شوند. - - وظایف Cron بررسی می‌کنند که آیا runtime کرون هنوز مالک job است یا نه، سپس پیش از fallback به `lost`، وضعیت پایانی را از لاگ‌های پایدارشده اجرای کرون/وضعیت job بازیابی می‌کنند. فقط فرایند Gateway برای مجموعه active-job درون‌حافظه‌ای کرون مرجع معتبر است؛ ممیزی CLI آفلاین از تاریخچه پایدار استفاده می‌کند اما یک وظیفه کرون را صرفا چون آن Set محلی خالی است گم‌شده علامت‌گذاری نمی‌کند. - - وظایف CLI با پشتوانه chat، context اجرای زنده مالک را بررسی می‌کنند، نه فقط ردیف نشست chat. + - وظایف ACP/زیرعامل، نشست فرزند پشتیبان خود را بررسی می‌کنند. + - وظایف زیرعاملی که نشست فرزندشان سنگ‌قبر بازیابی پس از راه‌اندازی مجدد دارد، به‌جای اینکه به‌عنوان نشست‌های پشتیبان قابل بازیابی در نظر گرفته شوند، گم‌شده علامت‌گذاری می‌شوند. + - وظایف Cron بررسی می‌کنند که آیا زمان اجرای cron هنوز مالک کار است یا نه، سپس پیش از بازگشت به `lost`، وضعیت پایانی را از گزارش‌های اجرای cron/وضعیت کار پایدارشده بازیابی می‌کنند. فقط فرایند Gateway برای مجموعه درون‌حافظه‌ای کارهای فعال cron مرجع معتبر است؛ ممیزی CLI آفلاین از تاریخچه پایدار استفاده می‌کند اما صرفا به‌دلیل خالی بودن آن Set محلی، یک وظیفه cron را گم‌شده علامت‌گذاری نمی‌کند. + - وظایف CLI متکی به چت، زمینه اجرای زنده مالک را بررسی می‌کنند، نه فقط ردیف نشست چت را. - پاک‌سازی تکمیل نیز از runtime آگاه است: + پاک‌سازی تکمیل نیز از زمان اجرا آگاه است: - - تکمیل subagent با بهترین تلاش، پیش از ادامه پاک‌سازی اعلان، زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست فرزند را می‌بندد. - - تکمیل کرون ایزوله با بهترین تلاش، پیش از teardown کامل اجرا، زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست کرون را می‌بندد. - - تحویل کرون ایزوله در صورت نیاز منتظر follow-up مربوط به subagent فرزند می‌ماند و به‌جای اعلام متن تأیید والد stale، آن را سرکوب می‌کند. - - تحویل تکمیل subagent آخرین متن قابل مشاهده assistant را ترجیح می‌دهد؛ اگر خالی باشد به آخرین متن پاک‌سازی‌شده tool/toolResult برمی‌گردد، و اجراهای tool-call فقط- timeout می‌توانند به یک خلاصه کوتاه پیشرفت جزئی فروکاسته شوند. اجراهای پایانی ناموفق، وضعیت failure را بدون replay کردن متن پاسخ ضبط‌شده اعلام می‌کنند. + - تکمیل زیرعامل، پیش از ادامه پاک‌سازی اعلان، با بهترین تلاش زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست فرزند را می‌بندد. + - تکمیل cron ایزوله، پیش از اینکه اجرا کاملا جمع شود، با بهترین تلاش زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست cron را می‌بندد. + - تحویل cron ایزوله، در صورت نیاز منتظر پیگیری زیرعامل نوادگان می‌ماند و به‌جای اعلام آن، متن تأیید والد کهنه را سرکوب می‌کند. + - تحویل تکمیل زیرعامل، جدیدترین متن قابل مشاهده دستیار را ترجیح می‌دهد؛ اگر خالی باشد، به جدیدترین متن پاک‌سازی‌شده ابزار/toolResult بازمی‌گردد، و اجراهای فراخوانی ابزار که فقط به پایان‌زمان رسیده‌اند می‌توانند به یک خلاصه کوتاه از پیشرفت جزئی فروکاسته شوند. اجراهای پایانی ناموفق، وضعیت شکست را بدون بازپخش متن پاسخ ضبط‌شده اعلام می‌کنند. - شکست‌های پاک‌سازی نتیجه واقعی وظیفه را پنهان نمی‌کنند. - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - وقتی چیزی که برایتان مهم است Task Flow هماهنگ‌کننده است، نه یک رکورد تکی از وظیفه پس‌زمینه، از این‌ها استفاده کنید. + وقتی جریان هماهنگ‌کننده Task Flow چیزی است که برایتان مهم است، نه یک رکورد منفرد وظیفه پس‌زمینه، از این‌ها استفاده کنید. -## تابلوی وظایف chat (`/tasks`) +## تابلوی وظیفه چت (`/tasks`) -در هر نشست chat از `/tasks` استفاده کنید تا وظایف پس‌زمینه مرتبط با آن نشست را ببینید. این تابلو وظایف فعال و تازه تکمیل‌شده را همراه با runtime، وضعیت، زمان‌بندی، و جزئیات پیشرفت یا خطا نشان می‌دهد. +در هر نشست چت از `/tasks` استفاده کنید تا وظایف پس‌زمینه مرتبط با آن نشست را ببینید. تابلو وظایف فعال و اخیرا تکمیل‌شده را همراه با زمان اجرا، وضعیت، زمان‌بندی، و جزئیات پیشرفت یا خطا نشان می‌دهد. -وقتی نشست فعلی هیچ وظیفه مرتبط قابل مشاهده‌ای ندارد، `/tasks` به شمارش وظایف agent-local برمی‌گردد تا همچنان بدون نشت جزئیات نشست‌های دیگر، یک نمای کلی دریافت کنید. +وقتی نشست فعلی هیچ وظیفه مرتبط قابل مشاهده‌ای ندارد، `/tasks` به شمارش وظایف محلی عامل بازمی‌گردد تا همچنان بدون افشای جزئیات نشست‌های دیگر، یک نمای کلی دریافت کنید. -برای دفترکل کامل operator، از CLI استفاده کنید: `openclaw tasks list`. +برای دفترکل کامل اپراتور، از CLI استفاده کنید: `openclaw tasks list`. -## یکپارچه‌سازی وضعیت (فشار وظایف) +## یکپارچه‌سازی وضعیت (فشار وظیفه) `openclaw status` یک خلاصه سریع از وظایف را شامل می‌شود: @@ -292,79 +298,79 @@ Tasks: 3 queued · 2 running · 1 issues - **فعال** — شمار `queued` + `running` - **شکست‌ها** — شمار `failed` + `timed_out` + `lost` -- **بر پایه runtime** — تفکیک بر اساس `acp`، `subagent`، `cron`، `cli` +- **بر پایه زمان اجرا** — تفکیک بر پایه `acp`، `subagent`، `cron`، `cli` -هم `/status` و هم ابزار `session_status` از snapshot وظیفه آگاه از پاک‌سازی استفاده می‌کنند: وظایف فعال ترجیح داده می‌شوند، ردیف‌های تکمیل‌شده stale پنهان می‌شوند، و شکست‌های اخیر فقط وقتی نمایش داده می‌شوند که هیچ کار فعالی باقی نمانده باشد. این کار کارت وضعیت را روی آنچه همین حالا مهم است متمرکز نگه می‌دارد. +هر دو `/status` و ابزار `session_status` از یک عکس‌برداشت وظیفه آگاه به پاک‌سازی استفاده می‌کنند: وظایف فعال ترجیح داده می‌شوند، ردیف‌های تکمیل‌شده کهنه پنهان می‌شوند، و شکست‌های اخیر فقط وقتی نمایش داده می‌شوند که هیچ کار فعالی باقی نمانده باشد. این کار کارت وضعیت را روی آنچه همین حالا مهم است متمرکز نگه می‌دارد. ## ذخیره‌سازی و نگهداری ### وظایف کجا قرار دارند -رکوردهای وظیفه در SQLite در این مسیر پایدار می‌شوند: +رکوردهای وظیفه در SQLite در مسیر زیر پایدار می‌شوند: ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -registry هنگام شروع gateway در حافظه بارگذاری می‌شود و برای ماندگاری بین restartها، نوشتن‌ها را با SQLite همگام می‌کند. -Gateway با استفاده از آستانه پیش‌فرض autocheckpoint در SQLite به‌علاوه checkpointهای دوره‌ای و shutdown از نوع `TRUNCATE`، لاگ write-ahead در SQLite را محدود نگه می‌دارد. +رجیستری هنگام شروع Gateway در حافظه بارگذاری می‌شود و نوشتن‌ها را برای پایداری در برابر راه‌اندازی‌های مجدد با SQLite همگام می‌کند. +Gateway گزارش پیش‌نویس SQLite را با استفاده از آستانه autocheckpoint پیش‌فرض SQLite به‌علاوه checkpointهای دوره‌ای و زمان خاموشی `TRUNCATE` محدود نگه می‌دارد. ### نگهداری خودکار -یک sweeper هر **۶۰ ثانیه** اجرا می‌شود و چهار کار را انجام می‌دهد: +یک جاروبگر هر **60 ثانیه** اجرا می‌شود و چهار کار را انجام می‌دهد: - - بررسی می‌کند که آیا وظایف فعال هنوز پشتوانه runtime معتبر دارند یا نه. وظایف ACP/subagent از وضعیت نشست فرزند استفاده می‌کنند، وظایف کرون از مالکیت active-job استفاده می‌کنند، و وظایف CLI با پشتوانه chat از context اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از ۵ دقیقه از بین رفته باشد، وظیفه `lost` علامت‌گذاری می‌شود. + + بررسی می‌کند که آیا وظایف فعال هنوز پشتوانه معتبر زمان اجرا دارند یا نه. وظایف ACP/زیرعامل از وضعیت نشست فرزند استفاده می‌کنند، وظایف cron از مالکیت کار فعال استفاده می‌کنند، و وظایف CLI متکی به چت از زمینه اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از 5 دقیقه از بین رفته باشد، وظیفه `lost` علامت‌گذاری می‌شود. - - نشست‌های ACP یک‌باره پایانی یا orphaned با مالکیت والد را می‌بندد، و نشست‌های ACP پایدار stale پایانی یا orphaned را فقط وقتی می‌بندد که هیچ binding گفت‌وگوی فعالی باقی نمانده باشد. + + نشست‌های ACP یک‌باره پایانی یا یتیم متعلق به والد را می‌بندد، و نشست‌های ACP پایدار پایانی کهنه یا یتیم را فقط وقتی می‌بندد که هیچ پیوند گفت‌وگوی فعالی باقی نمانده باشد. - - یک timestamp با نام `cleanupAfter` روی وظایف پایانی تنظیم می‌کند (endedAt + ۷ روز). در طول دوره نگهداری، وظایف گم‌شده هنوز در ممیزی به‌عنوان هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی metadata پاک‌سازی وجود ندارد، خطا هستند. + + یک زمان‌مهر `cleanupAfter` روی وظایف پایانی تنظیم می‌کند (endedAt + 7 روز). در طول دوره نگهداری، وظایف گم‌شده هنوز در ممیزی به‌عنوان هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی فراداده پاک‌سازی موجود نباشد، خطا هستند. - - رکوردهایی را که از تاریخ `cleanupAfter` خود گذشته‌اند حذف می‌کند. + + رکوردهایی را که تاریخ `cleanupAfter` آن‌ها گذشته است حذف می‌کند. -**نگهداری:** رکوردهای وظیفه پایانی به مدت **۷ روز** نگه داشته می‌شوند و سپس به‌صورت خودکار هرس می‌شوند. نیازی به پیکربندی نیست. +**نگهداری:** رکوردهای وظیفه پایانی به مدت **7 روز** نگه داشته می‌شوند، سپس به‌طور خودکار هرس می‌شوند. پیکربندی لازم نیست. -## ارتباط وظایف با سیستم‌های دیگر +## ارتباط وظایف با سامانه‌های دیگر - - [Task Flow](/fa/automation/taskflow) لایه هماهنگ‌سازی flow بالای وظایف پس‌زمینه است. یک flow واحد ممکن است در طول عمر خود چندین وظیفه را با استفاده از حالت‌های sync مدیریت‌شده یا mirrored هماهنگ کند. از `openclaw tasks` برای بازرسی رکوردهای وظیفه منفرد و از `openclaw tasks flow` برای بازرسی flow هماهنگ‌کننده استفاده کنید. + + [Task Flow](/fa/automation/taskflow) لایه هماهنگ‌سازی جریان بالای وظایف پس‌زمینه است. یک جریان منفرد ممکن است در طول عمر خود چندین وظیفه را با استفاده از حالت‌های همگام‌سازی مدیریت‌شده یا آینه‌شده هماهنگ کند. از `openclaw tasks` برای بررسی رکوردهای وظیفه منفرد و از `openclaw tasks flow` برای بررسی جریان هماهنگ‌کننده استفاده کنید. برای جزئیات، [Task Flow](/fa/automation/taskflow) را ببینید. - - **definition** یک job کرون در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای runtime کنار آن در `~/.openclaw/cron/jobs-state.json` قرار دارد. **هر** اجرای کرون یک رکورد وظیفه ایجاد می‌کند، چه main-session و چه ایزوله. وظایف کرون main-session به‌صورت پیش‌فرض سیاست اعلان `silent` دارند تا بدون تولید اعلان ردیابی شوند. + + یک **تعریف** کار cron در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای زمان اجرا کنار آن در `~/.openclaw/cron/jobs-state.json` قرار دارد. **هر** اجرای cron یک رکورد وظیفه ایجاد می‌کند — هم نشست اصلی و هم ایزوله. وظایف cron نشست اصلی به‌طور پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند تا بدون تولید اعلان ردیابی شوند. [Cron Jobs](/fa/automation/cron-jobs) را ببینید. - - اجراهای Heartbeat نوبت‌های main-session هستند؛ آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه تکمیل می‌شود، می‌تواند یک wake در heartbeat راه‌اندازی کند تا نتیجه را بی‌درنگ ببینید. + + اجراهای Heartbeat نوبت‌های نشست اصلی هستند — آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه تکمیل می‌شود، می‌تواند بیدارسازی Heartbeat را فعال کند تا نتیجه را سریع ببینید. [Heartbeat](/fa/gateway/heartbeat) را ببینید. - - یک وظیفه ممکن است به `childSessionKey` (جایی که کار اجرا می‌شود) و `requesterSessionKey` (کسی که آن را شروع کرده) ارجاع دهد. نشست‌ها context گفت‌وگو هستند؛ وظایف ردیابی فعالیت روی آن هستند. + + یک وظیفه ممکن است به یک `childSessionKey` (جایی که کار اجرا می‌شود) و یک `requesterSessionKey` (کسی که آن را شروع کرده است) ارجاع دهد. نشست‌ها زمینه گفت‌وگو هستند؛ وظایف ردیابی فعالیت روی آن هستند. - - `runId` یک وظیفه به اجرای agent که کار را انجام می‌دهد پیوند دارد. رویدادهای چرخه عمر agent (شروع، پایان، خطا) به‌صورت خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند؛ لازم نیست چرخه عمر را دستی مدیریت کنید. + + `runId` یک وظیفه به اجرای عاملی که کار را انجام می‌دهد پیوند دارد. رویدادهای چرخه عمر عامل (شروع، پایان، خطا) به‌طور خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند — لازم نیست چرخه عمر را دستی مدیریت کنید. ## مرتبط - [اتوماسیون و وظایف](/fa/automation) — همه سازوکارهای اتوماسیون در یک نگاه -- [CLI: وظایف](/fa/cli/tasks) — مرجع دستور CLI -- [Heartbeat](/fa/gateway/heartbeat) — نوبت‌های دوره‌ای main-session +- [CLI: وظایف](/fa/cli/tasks) — مرجع فرمان CLI +- [Heartbeat](/fa/gateway/heartbeat) — نوبت‌های دوره‌ای نشست اصلی - [وظایف زمان‌بندی‌شده](/fa/automation/cron-jobs) — زمان‌بندی کار پس‌زمینه -- [Task Flow](/fa/automation/taskflow) — هماهنگ‌سازی flow بالای وظایف +- [Task Flow](/fa/automation/taskflow) — هماهنگ‌سازی جریان بالای وظایف diff --git a/docs/fa/channels/slack.md b/docs/fa/channels/slack.md index c9d10e77a..2ef419f5e 100644 --- a/docs/fa/channels/slack.md +++ b/docs/fa/channels/slack.md @@ -1,43 +1,200 @@ --- read_when: - راه‌اندازی Slack یا اشکال‌زدایی حالت سوکت/HTTP در Slack -summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت سوکت + URLهای درخواست HTTP) +summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت Socket + URLهای درخواست HTTP) title: Slack x-i18n: - generated_at: "2026-05-04T07:02:46Z" + generated_at: "2026-05-05T01:44:07Z" model: gpt-5.5 provider: openai - source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 + source_hash: 9a8e1cbfd3d99bfc24d79b56ee762d1ab399402391b241ff40698249b0828008 source_path: channels/slack.md workflow: 16 --- -آمادهٔ تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های اپلیکیشن Slack. حالت پیش‌فرض، حالت Socket است؛ URLهای درخواست HTTP نیز پشتیبانی می‌شوند. +آمادهٔ تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های Slack app. حالت پیش‌فرض Socket Mode است؛ HTTP Request URLs نیز پشتیبانی می‌شوند. - پیام‌های مستقیم Slack به‌طور پیش‌فرض از حالت جفت‌سازی استفاده می‌کنند. + پیام‌های مستقیم Slack به‌صورت پیش‌فرض در حالت جفت‌سازی هستند. - رفتار دستورهای بومی و فهرست دستورها. + رفتار دستوری بومی و کاتالوگ دستورها. - عیب‌یابی میان‌کانالی و راهنماهای عملیاتی تعمیر. + تشخیص‌های میان‌کانالی و راهنماهای عملیاتی تعمیر. +## انتخاب Socket Mode یا HTTP Request URLs + +هر دو انتقال برای تولید آماده‌اند و از نظر پیام‌رسانی، دستورهای اسلش، App Home و تعامل‌پذیری به برابری قابلیتی می‌رسند. انتخاب را بر اساس شکل استقرار انجام دهید، نه قابلیت‌ها. + +| ملاحظه | Socket Mode (پیش‌فرض) | HTTP Request URLs | +| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| URL عمومی Gateway | لازم نیست | لازم است (DNS، TLS، پراکسی معکوس یا تونل) | +| شبکهٔ خروجی | WSS خروجی به `wss-primary.slack.com` باید قابل دسترسی باشد | بدون WS خروجی؛ فقط HTTPS ورودی | +| توکن‌های لازم | توکن Bot (`xoxb-...`) + توکن سطح برنامه (`xapp-...`) با `connections:write` | توکن Bot (`xoxb-...`) + Signing Secret | +| لپ‌تاپ توسعه / پشت فایروال | بدون تغییر کار می‌کند | به یک تونل عمومی (ngrok، Cloudflare Tunnel، Tailscale Funnel) یا Gateway مرحله‌بندی نیاز دارد | +| مقیاس‌پذیری افقی | یک نشست Socket Mode برای هر برنامه روی هر میزبان؛ چند Gateway به Slack appهای جداگانه نیاز دارند | هندلر POST بی‌حالت؛ چند رپلیکای Gateway می‌توانند پشت یک بارمتعادل‌کننده یک برنامه را به اشتراک بگذارند | +| چند حساب روی یک Gateway | پشتیبانی می‌شود؛ هر حساب WS خودش را باز می‌کند | پشتیبانی می‌شود؛ هر حساب به `webhookPath` یکتا نیاز دارد (پیش‌فرض `/slack/events`) تا ثبت‌ها با هم تداخل نکنند | +| انتقال دستور اسلش | از طریق اتصال WS تحویل می‌شود؛ `slash_commands[].url` نادیده گرفته می‌شود | Slack به `slash_commands[].url` درخواست POST می‌فرستد؛ این فیلد برای ارسال دستور لازم است | +| امضای درخواست | استفاده نمی‌شود (احراز هویت همان توکن سطح برنامه است) | Slack هر درخواست را امضا می‌کند؛ OpenClaw با `signingSecret` بررسی می‌کند | +| بازیابی پس از قطع اتصال | Slack SDK به‌صورت خودکار دوباره متصل می‌شود؛ تنظیم انتقال pong-timeout مربوط به gateway اعمال می‌شود | اتصال پایداری برای قطع شدن وجود ندارد؛ تلاش‌های دوباره برای هر درخواست از سمت Slack انجام می‌شوند | + + + **Socket Mode را انتخاب کنید** برای میزبان‌های تک-Gateway، لپ‌تاپ‌های توسعه و شبکه‌های درون‌سازمانی که می‌توانند به `*.slack.com` خروجی داشته باشند اما نمی‌توانند HTTPS ورودی بپذیرند. + +**HTTP Request URLs را انتخاب کنید** وقتی چند رپلیکای Gateway را پشت یک بارمتعادل‌کننده اجرا می‌کنید، وقتی WSS خروجی مسدود است اما HTTPS ورودی مجاز است، یا وقتی Webhookهای Slack را از قبل در یک پراکسی معکوس خاتمه می‌دهید. + + ## راه‌اندازی سریع - + - - در تنظیمات اپلیکیشن Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: + + [api.slack.com/apps](https://api.slack.com/apps/new) را باز کنید → **Create New App** → **From a manifest** → فضای کاری خود را انتخاب کنید → یکی از مانیفست‌های زیر را جای‌گذاری کنید → **Next** → **Create**. - - گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید - - [نمونهٔ manifest](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید - - یک **توکن سطح اپلیکیشن** (`xapp-...`) با `connections:write` ایجاد کنید - - اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + } + } +} +``` + + + + + **Recommended** با مجموعهٔ کامل قابلیت‌های Plugin داخلی Slack مطابقت دارد: App Home، دستورهای اسلش، فایل‌ها، واکنش‌ها، پین‌ها، پیام‌های مستقیم گروهی، و خواندن ایموجی/گروه کاربری. وقتی سیاست فضای کاری scopeها را محدود می‌کند، **Minimal** را انتخاب کنید — این گزینه پیام‌های مستقیم، تاریخچهٔ کانال/گروه، اشاره‌ها و دستورهای اسلش را پوشش می‌دهد اما فایل‌ها، واکنش‌ها، پین‌ها، پیام مستقیم گروهی (`mpim:*`)، `emoji:read` و `usergroups:read` را حذف می‌کند. برای دلیل هر scope و گزینه‌های افزایشی مانند دستورهای اسلش اضافی، [چک‌لیست مانیفست و scope](#manifest-and-scope-checklist) را ببینید. + + + پس از اینکه Slack برنامه را ساخت: + + - **Basic Information → App-Level Tokens → Generate Token and Scopes**: `connections:write` را اضافه کنید، ذخیره کنید، مقدار `xapp-...` را کپی کنید. + - **Install App → Install to Workspace**: توکن OAuth کاربر Bot با مقدار `xoxb-...` را کپی کنید. @@ -73,7 +230,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,21 +241,172 @@ openclaw gateway - + - - در تنظیمات اپلیکیشن Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: + + [api.slack.com/apps](https://api.slack.com/apps/new) را باز کنید → **Create New App** → **From a manifest** → فضای کاری خود را انتخاب کنید → یکی از مانیفست‌های زیر را جای‌گذاری کنید → `https://gateway-host.example.com/slack/events` را با URL عمومی Gateway خود جایگزین کنید → **Next** → **Create**. - - گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید - - [نمونهٔ manifest](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید - - **راز امضا** را برای راستی‌آزمایی درخواست ذخیره کنید - - اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید + + +```json Recommended +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + +```json Minimal +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { "display_name": "OpenClaw", "always_online": true }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false, + "url": "https://gateway-host.example.com/slack/events" + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "users:read" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://gateway-host.example.com/slack/events", + "bot_events": [ + "app_home_opened", + "app_mention", + "message.channels", + "message.groups", + "message.im" + ] + }, + "interactivity": { + "is_enabled": true, + "request_url": "https://gateway-host.example.com/slack/events", + "message_menu_options_url": "https://gateway-host.example.com/slack/events" + } + } +} +``` + + + + + **Recommended** با مجموعه کامل قابلیت‌های Plugin داخلی Slack مطابقت دارد؛ **Minimal** فایل‌ها، واکنش‌ها، پین‌ها، پیام مستقیم گروهی (`mpim:*`)، `emoji:read` و `usergroups:read` را برای فضاهای کاری محدود حذف می‌کند. برای دلیل هر scope، [چک‌لیست manifest و scope](#manifest-and-scope-checklist) را ببینید. + + + + هر سه فیلد URL (`slash_commands[].url`، `event_subscriptions.request_url` و `interactivity.request_url` / `message_menu_options_url`) همگی به همان endpoint مربوط به OpenClaw اشاره می‌کنند. شِمای manifest در Slack الزام می‌کند که این‌ها جداگانه نام‌گذاری شوند، اما OpenClaw بر اساس نوع payload مسیریابی می‌کند، بنابراین یک `webhookPath` واحد (پیش‌فرض `/slack/events`) کافی است. فرمان‌های slash بدون `slash_commands[].url` در حالت HTTP بی‌صدا هیچ کاری انجام نمی‌دهند. + + + پس از اینکه Slack برنامه را ایجاد کرد: + + - **Basic Information → App Credentials**: برای راستی‌آزمایی درخواست، **Signing Secret** را کپی کنید. + - **Install App → Install to Workspace**: توکن OAuth کاربر Bot با قالب `xoxb-...` را کپی کنید. - + - راه‌اندازی پیشنهادی SecretRef: + پیکربندی SecretRef توصیه‌شده: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,14 +429,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - برای HTTP چندحسابی از مسیرهای webhook یکتا استفاده کنید + برای HTTP چندحسابی از مسیرهای Webhook یکتا استفاده کنید - به هر حساب یک `webhookPath` متمایز (پیش‌فرض `/slack/events`) بدهید تا ثبت‌ها با هم تداخل نکنند. + به هر حساب یک `webhookPath` متمایز (پیش‌فرض `/slack/events`) بدهید تا ثبت‌ها با هم تداخل نداشته باشند. - + ```bash openclaw gateway @@ -140,9 +448,9 @@ openclaw gateway -## تنظیم دقیق انتقال در حالت Socket +## تنظیم transport در Socket Mode -OpenClaw به‌طور پیش‌فرض زمان پایان انتظار pong کلاینت SDK Slack را برای حالت Socket روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط زمانی بازنویسی کنید که به تنظیم دقیق مخصوص فضای کاری یا میزبان نیاز دارید: +OpenClaw به‌طور پیش‌فرض زمان‌انتظار pong کلاینت Slack SDK را برای Socket Mode روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات transport را فقط زمانی بازنویسی کنید که به تنظیم‌های مخصوص فضای کاری یا میزبان نیاز دارید: ```json5 { @@ -159,13 +467,13 @@ OpenClaw به‌طور پیش‌فرض زمان پایان انتظار pong ک } ``` -این را فقط برای فضاهای کاری حالت Socket استفاده کنید که پایان زمان انتظار pong وب‌سوکت Slack یا server-ping را ثبت می‌کنند، یا روی میزبان‌هایی اجرا می‌شوند که گرسنگی حلقهٔ رویداد شناخته‌شده دارند. `clientPingTimeout` مدت انتظار برای pong پس از ارسال ping کلاینت توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای اپلیکیشن همچنان وضعیت اپلیکیشن هستند، نه سیگنال‌های زنده‌بودن انتقال. +این مورد را فقط برای فضاهای کاری Socket Mode استفاده کنید که زمان‌انتظار‌های pong یا server-ping در websocket مربوط به Slack را لاگ می‌کنند یا روی میزبان‌هایی اجرا می‌شوند که با کمبود چرخه event-loop شناخته‌شده مواجه‌اند. `clientPingTimeout` زمان انتظار برای pong پس از آن است که SDK یک ping کلاینت می‌فرستد؛ `serverPingTimeout` زمان انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای برنامه همچنان وضعیت برنامه هستند، نه سیگنال‌های زنده‌بودن transport. -## فهرست بررسی manifest و scope +## چک‌لیست manifest و scope -manifest پایهٔ اپلیکیشن Slack برای حالت Socket و URLهای درخواست HTTP یکسان است. فقط بلوک `settings` (و `url` دستور اسلش) متفاوت است. +manifest پایه برنامه Slack برای Socket Mode و URLهای درخواست HTTP یکسان است. فقط بلوک `settings` (و `url` فرمان slash) متفاوت است. -manifest پایه (پیش‌فرض حالت Socket): +manifest پایه (پیش‌فرض Socket Mode): ```json { @@ -240,7 +548,7 @@ manifest پایه (پیش‌فرض حالت Socket): } ``` -برای **حالت URLهای درخواست HTTP**، `settings` را با گونهٔ HTTP جایگزین کنید و به هر دستور اسلش `url` اضافه کنید. URL عمومی لازم است: +برای **حالت URLهای درخواست HTTP**، `settings` را با گونه HTTP جایگزین کنید و به هر فرمان slash مقدار `url` اضافه کنید. URL عمومی لازم است: ```json { @@ -282,24 +590,24 @@ manifest پایه (پیش‌فرض حالت Socket): } ``` -### تنظیمات تکمیلی manifest +### تنظیمات اضافی manifest -ویژگی‌های متفاوتی را که پیش‌فرض‌های بالا را گسترش می‌دهند، ارائه کنید. +قابلیت‌های متفاوتی را نمایش دهید که پیش‌فرض‌های بالا را گسترش می‌دهند. -manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی یکی از اعضای فضای کاری زبانهٔ Home را باز می‌کند، OpenClaw با `views.publish` یک نمای Home پیش‌فرض امن منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی در آن گنجانده نمی‌شود. زبانهٔ **Messages** برای پیام‌های مستقیم Slack همچنان فعال می‌ماند. +manifest پیش‌فرض، برگه **Home** در App Home مربوط به Slack را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی عضوی از فضای کاری برگه Home را باز می‌کند، OpenClaw یک نمای Home پیش‌فرض ایمن را با `views.publish` منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی در آن گنجانده نمی‌شود. برگه **Messages** برای پیام‌های مستقیم Slack همچنان فعال می‌ماند. - + - می‌توان به‌جای یک دستور پیکربندی‌شدهٔ واحد، از چندین [دستور اسلش بومی](#commands-and-slash-behavior) با جزئیات استفاده کرد: + می‌توان به‌جای یک فرمان پیکربندی‌شده واحد، از چند [فرمان slash بومی](#commands-and-slash-behavior) با جزئیات بیشتر استفاده کرد: - - از `/agentstatus` به‌جای `/status` استفاده کنید، چون دستور `/status` رزرو شده است. - - نمی‌توان بیش از ۲۵ دستور اسلش را هم‌زمان در دسترس قرار داد. + - از `/agentstatus` به‌جای `/status` استفاده کنید، چون فرمان `/status` رزرو شده است. + - بیش از ۲۵ فرمان slash را نمی‌توان هم‌زمان در دسترس قرار داد. - بخش `features.slash_commands` موجود خود را با زیرمجموعه‌ای از [دستورهای موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: + بخش فعلی `features.slash_commands` خود را با زیرمجموعه‌ای از [فرمان‌های موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: - + ```json { @@ -422,8 +730,8 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا ``` - - از همان فهرست `slash_commands` حالت Socket در بالا استفاده کنید و به هر ورودی `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: + + از همان فهرست `slash_commands` بالا برای Socket Mode استفاده کنید، و به هر ورودی `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: ```json { @@ -443,16 +751,16 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا } ``` - آن مقدار `url` را برای هر دستور در فهرست تکرار کنید. + همان مقدار `url` را برای هر فرمان در فهرست تکرار کنید. - اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت عامل فعال (نام کاربری و نماد سفارشی) استفاده کنند، دامنه ربات `chat:write.customize` را اضافه کنید. + اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت عامل فعال (نام کاربری و آیکن سفارشی) استفاده کنند، دامنه ربات `chat:write.customize` را اضافه کنید. - اگر از نماد ایموجی استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد. + اگر از آیکن ایموجی استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد. @@ -475,30 +783,30 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا - حالت HTTP به `botToken` + `signingSecret` نیاز دارد. - `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های متن ساده یا اشیای SecretRef را می‌پذیرند. -- توکن‌های پیکربندی، جایگزین بازگشت env می‌شوند. -- بازگشت env برای `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. -- `userToken` (`xoxp-...`) فقط از طریق پیکربندی است (بدون بازگشت env) و به‌طور پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`). +- توکن‌های پیکربندی، جایگزین پشتیبان env می‌شوند. +- پشتیبان env با `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. +- `userToken` (`xoxp-...`) فقط از پیکربندی می‌آید (بدون پشتیبان env) و به‌طور پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`). رفتار نمایه وضعیت: -- بازرسی حساب Slack فیلدهای `*Source` و `*Status` - را برای هر اعتبارنامه (`botToken`، `appToken`، `signingSecret`، `userToken`) رهگیری می‌کند. +- بازرسی حساب Slack برای هر اعتبارنامه، فیلدهای `*Source` و `*Status` + را ردیابی می‌کند (`botToken`، `appToken`، `signingSecret`، `userToken`). - وضعیت `available`، `configured_unavailable` یا `missing` است. - `configured_unavailable` یعنی حساب از طریق SecretRef - یا منبع راز غیرخطی دیگری پیکربندی شده است، اما مسیر فرمان/زمان اجرای فعلی - نتوانسته مقدار واقعی را resolve کند. + یا یک منبع راز غیرخطی دیگر پیکربندی شده است، اما مسیر فرمان/زمان‌اجرای فعلی + نتوانست مقدار واقعی را resolve کند. - در حالت HTTP، `signingSecretStatus` گنجانده می‌شود؛ در Socket Mode، جفت الزامی `botTokenStatus` + `appTokenStatus` است. -برای خواندن‌های اقدامات/فهرست، وقتی توکن کاربر پیکربندی شده باشد می‌توان آن را ترجیح داد. برای نوشتن‌ها، توکن ربات همچنان ترجیح داده می‌شود؛ نوشتن با توکن کاربر فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و توکن ربات در دسترس نباشد. +برای کنش‌ها/خواندن‌های فهرست، وقتی توکن کاربر پیکربندی شده باشد می‌تواند ترجیح داده شود. برای نوشتن‌ها، توکن ربات همچنان ترجیح داده می‌شود؛ نوشتن با توکن کاربر فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و توکن ربات در دسترس نباشد. -## اقدامات و گیت‌ها +## کنش‌ها و دروازه‌ها -اقدامات Slack با `channels.slack.actions.*` کنترل می‌شوند. +کنش‌های Slack با `channels.slack.actions.*` کنترل می‌شوند. -گروه‌های اقدام موجود در ابزار فعلی Slack: +گروه‌های کنش موجود در ابزار فعلی Slack: | گروه | پیش‌فرض | | ---------- | ------- | @@ -508,7 +816,7 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا | memberInfo | فعال | | emojiList | فعال | -اقدامات پیام فعلی Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info` و `emoji-list` است. `download-file` شناسه‌های فایل Slack را که در جای‌نگهدارهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصاویر پیش‌نمایش تصویر یا برای انواع دیگر فایل، فراداده فایل محلی را برمی‌گرداند. +کنش‌های فعلی پیام Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info` و `emoji-list` هستند. `download-file` شناسه‌های فایل Slack را که در جای‌نگهدارهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصویرها پیش‌نمایش تصویر یا برای انواع فایل دیگر فراداده فایل محلی برمی‌گرداند. ## کنترل دسترسی و مسیریابی @@ -526,8 +834,8 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا - `dm.enabled` (پیش‌فرض true) - `channels.slack.allowFrom` - `dm.allowFrom` (قدیمی) - - `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false هستند) - - `dm.groupChannels` (فهرست مجاز MPIM اختیاری) + - `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false) + - `dm.groupChannels` (فهرست مجاز اختیاری MPIM) تقدم چندحسابی: @@ -550,18 +858,18 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا فهرست مجاز کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای مثال `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند. - نکته زمان اجرا: اگر `channels.slack` کاملا وجود نداشته باشد (راه‌اندازی فقط با env)، زمان اجرا به `groupPolicy="allowlist"` برمی‌گردد و یک هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). + نکته زمان‌اجرا: اگر `channels.slack` کاملاً وجود نداشته باشد (راه‌اندازی فقط env)، زمان‌اجرا به `groupPolicy="allowlist"` برمی‌گردد و هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). - resolve نام/شناسه: + حل نام/شناسه: - ورودی‌های فهرست مجاز کانال و ورودی‌های فهرست مجاز DM هنگام راه‌اندازی، وقتی دسترسی توکن اجازه دهد، resolve می‌شوند - - ورودی‌های resolveنشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند + - ورودی‌های نام کانال resolveنشده همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند - مجوزدهی ورودی و مسیریابی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است؛ تطبیق مستقیم نام کاربری/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد - کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) تحت `groupPolicy: "allowlist"` تطبیق **نمی‌شوند**. جست‌وجوی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است، بنابراین یک کلید مبتنی بر نام هرگز با موفقیت مسیریابی نمی‌شود و همه پیام‌های آن کانال بی‌صدا مسدود خواهند شد. این با `groupPolicy: "open"` فرق دارد؛ در آنجا کلید کانال برای مسیریابی لازم نیست و به نظر می‌رسد یک کلید مبتنی بر نام کار می‌کند. + کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) زیر `groupPolicy: "allowlist"` تطبیق داده **نمی‌شوند**. جست‌وجوی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است، پس کلید مبتنی بر نام هرگز با موفقیت مسیریابی نمی‌شود و همه پیام‌ها در آن کانال بی‌صدا مسدود می‌شوند. این با `groupPolicy: "open"` متفاوت است، جایی که کلید کانال برای مسیریابی لازم نیست و به نظر می‌رسد کلید مبتنی بر نام کار می‌کند. - همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای یافتن آن: روی کانال در Slack راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. + همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای پیدا کردن آن: روی کانال در Slack راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. درست: @@ -596,48 +904,48 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا - - پیام‌های کانال به‌صورت پیش‌فرض با اشاره کنترل می‌شوند. + + پیام‌های کانال به‌طور پیش‌فرض با شرط منشن کنترل می‌شوند. - منابع اشاره: + منابع منشن: - - اشاره صریح به اپ (`<@botId>`) - - اشاره به گروه کاربری Slack (``) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد - - الگوهای regex اشاره (`agents.list[].groupChat.mentionPatterns`، جایگزین `messages.groupChat.mentionPatterns`) + - منشن صریح برنامه (`<@botId>`) + - منشن گروه کاربری Slack (``) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد + - الگوهای عبارت منظم منشن (`agents.list[].groupChat.mentionPatterns`، جایگزین `messages.groupChat.mentionPatterns`) - رفتار ضمنی پاسخ به رشته ربات (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود) - کنترل‌های هر کانال (`channels.slack.channels.`؛ نام‌ها فقط از طریق حل‌وفصل هنگام راه‌اندازی یا `dangerouslyAllowNameMatching`): + کنترل‌های هر کانال (`channels.slack.channels.`؛ نام‌ها فقط از طریق حل هنگام راه‌اندازی یا `dangerouslyAllowNameMatching`): - `requireMention` - - `users` (allowlist) + - `users` (فهرست مجاز) - `allowBots` - `skills` - `systemPrompt` - - `tools`، `toolsBySender` - - قالب کلید `toolsBySender`: `id:`، `e164:`، `username:`، `name:`، یا wildcard `"*"` + - `tools`, `toolsBySender` + - قالب کلید `toolsBySender`: `id:`, `e164:`, `username:`, `name:`، یا وایلدکارت `"*"` (کلیدهای قدیمی بدون پیشوند همچنان فقط به `id:` نگاشت می‌شوند) - `allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های اتاق که توسط ربات نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که ربات فرستنده به‌صراحت در allowlist `users` همان اتاق فهرست شده باشد، یا وقتی دست‌کم یک شناسه مالک صریح Slack از `channels.slack.allowFrom` در حال حاضر عضو اتاق باشد. wildcardها و ورودی‌های مالک با نام نمایشی، حضور مالک را برآورده نمی‌کنند. حضور مالک از `conversations.members` در Slack استفاده می‌کند؛ مطمئن شوید اپ scope خواندن متناظر با نوع اتاق را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر جست‌وجوی عضو شکست بخورد، OpenClaw پیام اتاق نوشته‌شده توسط ربات را حذف می‌کند. + `allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه عمل می‌کند: پیام‌های اتاق که توسط ربات نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که ربات فرستنده به‌صراحت در فهرست مجاز `users` همان اتاق آمده باشد، یا وقتی حداقل یک شناسه مالک صریح Slack از `channels.slack.allowFrom` در حال حاضر عضو اتاق باشد. وایلدکارت‌ها و مدخل‌های مالک با نام نمایشی، حضور مالک را احراز نمی‌کنند. حضور مالک از `conversations.members` در Slack استفاده می‌کند؛ مطمئن شوید برنامه دامنه خواندن متناظر با نوع اتاق را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر جست‌وجوی عضو شکست بخورد، OpenClaw پیام اتاقِ نوشته‌شده توسط ربات را کنار می‌گذارد. -## رشته‌ها، نشست‌ها، و برچسب‌های پاسخ +## رشته‌بندی، نشست‌ها، و برچسب‌های پاسخ -- DMها به‌صورت `direct` مسیر‌دهی می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`. -- اتصال‌های مسیر Slack شناسه‌های خام طرف مقابل به‌علاوه فرم‌های مقصد Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` را می‌پذیرند. -- با مقدار پیش‌فرض `session.dmScope=main`، DMهای Slack در نشست اصلی عامل ادغام می‌شوند. +- پیام‌های مستقیم به‌صورت `direct` مسیریابی می‌شوند؛ کانال‌ها به‌صورت `channel`؛ پیام‌های مستقیم چندنفره به‌صورت `group`. +- اتصال‌های مسیر Slack شناسه‌های خام همتا را به‌همراه قالب‌های هدف Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` می‌پذیرند. +- با `session.dmScope=main` پیش‌فرض، پیام‌های مستقیم Slack در نشست اصلی عامل ادغام می‌شوند. - نشست‌های کانال: `agent::slack:channel:`. -- پاسخ‌های رشته می‌توانند در صورت کاربرد پسوندهای نشست رشته (`:thread:`) بسازند. +- پاسخ‌های رشته می‌توانند در صورت امکان پسوندهای نشست رشته (`:thread:`) ایجاد کنند. - مقدار پیش‌فرض `channels.slack.thread.historyScope` برابر `thread` است؛ مقدار پیش‌فرض `thread.inheritParent` برابر `false` است. -- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع یک نشست رشته جدید چند پیام موجود رشته دریافت شود (پیش‌فرض `20`؛ برای غیرفعال‌سازی روی `0` تنظیم کنید). -- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، اشاره‌های ضمنی رشته را سرکوب می‌کند تا ربات فقط به اشاره‌های صریح `@bot` داخل رشته‌ها پاسخ دهد، حتی وقتی ربات قبلا در رشته مشارکت کرده باشد. بدون این، پاسخ‌ها در رشته‌ای که ربات در آن مشارکت داشته از کنترل `requireMention` عبور می‌کنند. +- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع یک نشست رشته جدید، چه تعداد از پیام‌های موجود رشته واکشی شوند (پیش‌فرض `20`؛ برای غیرفعال کردن روی `0` تنظیم کنید). +- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، منشن‌های ضمنی رشته را سرکوب می‌کند تا ربات فقط به منشن‌های صریح `@bot` داخل رشته‌ها پاسخ دهد، حتی وقتی ربات قبلاً در رشته مشارکت داشته است. بدون این، پاسخ‌ها در رشته‌ای که ربات در آن مشارکت داشته، شرط `requireMention` را دور می‌زنند. -کنترل‌های رشته پاسخ: +کنترل‌های رشته‌بندی پاسخ: - `channels.slack.replyToMode`: `off|first|all|batched` (پیش‌فرض `off`) - `channels.slack.replyToModeByChatType`: به‌ازای هر `direct|group|channel` -- جایگزین قدیمی برای چت‌های مستقیم: `channels.slack.dm.replyToMode` +- جایگزین قدیمی برای گفت‌وگوهای مستقیم: `channels.slack.dm.replyToMode` برچسب‌های پاسخ دستی پشتیبانی می‌شوند: @@ -645,37 +953,37 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا - `[[reply_to:]]` -`replyToMode="off"` **تمام** رشته‌سازی پاسخ در Slack را غیرفعال می‌کند، از جمله برچسب‌های صریح `[[reply_to_*]]`. این با Telegram متفاوت است، جایی که برچسب‌های صریح همچنان در حالت `"off"` رعایت می‌شوند. رشته‌های Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت درون‌خطی قابل مشاهده می‌مانند. +`replyToMode="off"` **همه** رشته‌بندی پاسخ را در Slack غیرفعال می‌کند، از جمله برچسب‌های صریح `[[reply_to_*]]`. این با Telegram متفاوت است، که در آن برچسب‌های صریح همچنان در حالت `"off"` رعایت می‌شوند. رشته‌های Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت درون‌خطی قابل مشاهده می‌مانند. -## واکنش‌های تایید +## واکنش‌های تأیید دریافت -`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw یک ایموجی تایید ارسال می‌کند. +`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw یک ایموجی تأیید دریافت می‌فرستد. -ترتیب حل‌وفصل: +ترتیب تعیین مقدار: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، وگرنه "👀") +- گزینه جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، در غیر این صورت "👀") نکته‌ها: -- Slack انتظار shortcode دارد (برای مثال `"eyes"`). -- برای غیرفعال کردن واکنش برای حساب Slack یا به‌صورت سراسری از `""` استفاده کنید. +- Slack انتظار کدهای کوتاه را دارد (برای مثال `"eyes"`). +- برای غیرفعال کردن واکنش برای حساب Slack یا به‌صورت سراسری، از `""` استفاده کنید. -## پخش جریانی متن +## جریان‌دهی متن `channels.slack.streaming` رفتار پیش‌نمایش زنده را کنترل می‌کند: -- `off`: پخش جریانی پیش‌نمایش زنده را غیرفعال می‌کند. +- `off`: جریان‌دهی پیش‌نمایش زنده را غیرفعال می‌کند. - `partial` (پیش‌فرض): متن پیش‌نمایش را با آخرین خروجی جزئی جایگزین می‌کند. -- `block`: به‌روزرسانی‌های پیش‌نمایش بخش‌بندی‌شده را اضافه می‌کند. -- `progress`: هنگام تولید، متن وضعیت پیشرفت را نشان می‌دهد، سپس متن نهایی را ارسال می‌کند. -- `streaming.preview.toolProgress`: وقتی پیش‌نمایش پیش‌نویس فعال است، به‌روزرسانی‌های ابزار/پیشرفت را به همان پیام پیش‌نمایش ویرایش‌شده مسیر‌دهی می‌کند (پیش‌فرض: `true`). برای نگه داشتن پیام‌های جداگانه ابزار/پیشرفت، روی `false` تنظیم کنید. -- `streaming.preview.commandText` / `streaming.progress.commandText`: برای حفظ خطوط فشرده پیشرفت ابزار هنگام پنهان کردن متن خام command/exec، روی `status` تنظیم کنید (پیش‌فرض: `raw`). +- `block`: به‌روزرسانی‌های پیش‌نمایش قطعه‌قطعه را اضافه می‌کند. +- `progress`: هنگام تولید، متن وضعیت پیشرفت را نشان می‌دهد، سپس متن نهایی را می‌فرستد. +- `streaming.preview.toolProgress`: وقتی پیش‌نمایش پیش‌نویس فعال است، به‌روزرسانی‌های ابزار/پیشرفت را به همان پیام پیش‌نمایش ویرایش‌شده هدایت می‌کند (پیش‌فرض: `true`). برای نگه‌داشتن پیام‌های جداگانه ابزار/پیشرفت، روی `false` تنظیم کنید. +- `streaming.preview.commandText` / `streaming.progress.commandText`: برای نگه‌داشتن خطوط فشرده پیشرفت ابزار در حالی که متن خام فرمان/اجرا پنهان می‌شود، روی `status` تنظیم کنید (پیش‌فرض: `raw`). -پنهان کردن متن خام command/exec در عین حفظ خطوط فشرده پیشرفت: +پنهان کردن متن خام فرمان/اجرا در حالی که خطوط فشرده پیشرفت حفظ می‌شوند: ```json { @@ -693,16 +1001,16 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا } ``` -`channels.slack.streaming.nativeTransport` پخش جریانی متن بومی Slack را وقتی `channels.slack.streaming.mode` برابر `partial` است کنترل می‌کند (پیش‌فرض: `true`). +`channels.slack.streaming.nativeTransport` جریان‌دهی متنی بومی Slack را وقتی `channels.slack.streaming.mode` برابر `partial` باشد کنترل می‌کند (پیش‌فرض: `true`). -- برای ظاهر شدن پخش جریانی متن بومی و وضعیت رشته دستیار Slack، باید یک رشته پاسخ در دسترس باشد. انتخاب رشته همچنان از `replyToMode` پیروی می‌کند. -- ریشه‌های کانال، چت گروهی، و DM سطح بالا همچنان می‌توانند وقتی پخش جریانی بومی در دسترس نیست یا رشته پاسخی وجود ندارد، از پیش‌نمایش پیش‌نویس معمول استفاده کنند. -- DMهای سطح بالای Slack به‌صورت پیش‌فرض خارج از رشته می‌مانند، بنابراین پیش‌نمایش جریان/وضعیت بومی به سبک رشته Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک پیش‌نمایش پیش‌نویس را در DM ارسال و ویرایش می‌کند. -- رسانه و payloadهای غیرمتنی به تحویل معمول بازمی‌گردند. -- نتیجه‌های نهایی رسانه/خطا ویرایش‌های پیش‌نمایش معلق را لغو می‌کنند؛ نتیجه‌های نهایی متن/block واجد شرایط فقط وقتی flush می‌شوند که بتوانند پیش‌نمایش را درجا ویرایش کنند. -- اگر پخش جریانی در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به تحویل معمول بازمی‌گردد. +- برای نمایش جریان‌دهی متنی بومی و وضعیت رشته دستیار Slack، باید یک رشته پاسخ در دسترس باشد. انتخاب رشته همچنان از `replyToMode` پیروی می‌کند. +- ریشه‌های کانال، گپ گروهی، و پیام مستقیم سطح بالا همچنان می‌توانند وقتی جریان‌دهی بومی در دسترس نیست یا هیچ رشته پاسخی وجود ندارد، از پیش‌نمایش پیش‌نویس عادی استفاده کنند. +- پیام‌های مستقیم سطح بالای Slack به‌طور پیش‌فرض خارج از رشته می‌مانند، بنابراین پیش‌نمایش جریان/وضعیت بومی سبک رشته‌ای Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک پیش‌نمایش پیش‌نویس را در پیام مستقیم ارسال و ویرایش می‌کند. +- رسانه و محموله‌های غیرمتنی به تحویل عادی برمی‌گردند. +- خروجی‌های نهایی رسانه/خطا ویرایش‌های معلق پیش‌نمایش را لغو می‌کنند؛ خروجی‌های نهایی متن/بلوکِ واجد شرایط فقط وقتی اعمال می‌شوند که بتوانند پیش‌نمایش را درجا ویرایش کنند. +- اگر جریان‌دهی در میانه پاسخ شکست بخورد، OpenClaw برای محموله‌های باقی‌مانده به تحویل عادی برمی‌گردد. -استفاده از پیش‌نمایش پیش‌نویس به‌جای پخش جریانی متن بومی Slack: +به‌جای جریان‌دهی متنی بومی Slack از پیش‌نمایش پیش‌نویس استفاده کنید: ```json5 { @@ -719,58 +1027,58 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا کلیدهای قدیمی: -- `channels.slack.streamMode` (`replace | status_final | append`) به‌صورت خودکار به `channels.slack.streaming.mode` مهاجرت داده می‌شود. -- مقدار boolean `channels.slack.streaming` به‌صورت خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. -- `channels.slack.nativeStreaming` قدیمی به‌صورت خودکار به `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. +- `channels.slack.streamMode` (`replace | status_final | append`) به‌طور خودکار به `channels.slack.streaming.mode` مهاجرت داده می‌شود. +- مقدار بولی `channels.slack.streaming` به‌طور خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. +- `channels.slack.nativeStreaming` قدیمی به‌طور خودکار به `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. -## جایگزین واکنش تایپ کردن +## گزینه جایگزین واکنش تایپ -`typingReaction` هنگامی که OpenClaw در حال پردازش یک پاسخ است، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس هنگام پایان اجرای کار آن را حذف می‌کند. این قابلیت بیشتر خارج از پاسخ‌های رشته‌ای مفید است؛ پاسخ‌های رشته‌ای از نشانگر وضعیت پیش‌فرض «در حال تایپ است...» استفاده می‌کنند. +`typingReaction` هنگام پردازش پاسخ توسط OpenClaw، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس وقتی اجرا تمام شد آن را حذف می‌کند. این کار بیرون از پاسخ‌های رشته‌ای بیشترین کاربرد را دارد، چون آن‌ها از نشانگر وضعیت پیش‌فرض «در حال تایپ...» استفاده می‌کنند. -ترتیب حل: +ترتیب تفکیک: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` نکته‌ها: -- Slack انتظار کدهای کوتاه دارد (برای مثال `"hourglass_flowing_sand"`). -- واکنش به‌صورت بهترین تلاش انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود. +- Slack انتظار shortcode دارد (برای مثال `"hourglass_flowing_sand"`). +- واکنش به‌صورت best-effort انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود. -## رسانه، بخش‌بندی، و تحویل +## رسانه، قطعه‌بندی، و تحویل - - پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احراز هویت‌شده با توکن) و وقتی واکشی موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جای‌نگهدارهای فایل شامل `fileId` مربوط به Slack هستند تا agentها بتوانند فایل اصلی را با `download-file` واکشی کنند. + + پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احرازهویت‌شده با توکن) و وقتی دریافت موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جایگزین‌های فایل شامل `fileId` مربوط به Slack هستند تا عامل‌ها بتوانند فایل اصلی را با `download-file` دریافت کنند. - دانلودها از timeoutهای محدود برای بیکاری و کل زمان استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جای‌نگهدار فایل برمی‌گردد. + دانلودها از مهلت‌های زمانی محدود برای بیکاری و کل عملیات استفاده می‌کنند. اگر دریافت فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جایگزین فایل fallback می‌کند. - سقف اندازه ورودی در زمان اجرا به‌طور پیش‌فرض `20MB` است، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود. + سقف اندازه ورودی در زمان اجرا، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود، به‌طور پیش‌فرض `20MB` است. - - - بخش‌های متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000) + + - قطعه‌های متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000) - `channels.slack.chunkMode="newline"` تقسیم‌بندی با اولویت پاراگراف را فعال می‌کند - - ارسال فایل‌ها از APIهای بارگذاری Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های رشته‌ای (`thread_ts`) باشد - - سقف رسانه خروجی هنگام پیکربندی از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در pipeline رسانه استفاده می‌کنند + - ارسال فایل از APIهای بارگذاری Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های رشته‌ای (`thread_ts`) باشد + - سقف رسانه خروجی، وقتی پیکربندی شده باشد، از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در پایپ‌لاین رسانه استفاده می‌کنند - - مقصدهای صریح ترجیحی: + + هدف‌های صریح ترجیحی: - `user:` برای DMها - `channel:` برای کانال‌ها - DMهای Slack فقط متنی/بلوکی می‌توانند مستقیماً به شناسه‌های کاربر ارسال شوند؛ بارگذاری فایل و ارسال‌های رشته‌ای ابتدا DM را از طریق APIهای گفت‌وگوی Slack باز می‌کنند، چون آن مسیرها به یک شناسه گفت‌وگوی مشخص نیاز دارند. + DMهای Slack که فقط متن/بلوک دارند می‌توانند مستقیماً به شناسه‌های کاربر ارسال شوند؛ بارگذاری فایل و ارسال‌های رشته‌ای ابتدا DM را از طریق APIهای مکالمه Slack باز می‌کنند، چون آن مسیرها به یک شناسه مکالمه مشخص نیاز دارند. -## دستورها و رفتار slash +## فرمان‌ها و رفتار slash -دستورهای slash در Slack یا به‌صورت یک دستور پیکربندی‌شده واحد ظاهر می‌شوند یا به‌صورت چند دستور native. برای تغییر پیش‌فرض‌های دستور، `channels.slack.slashCommand` را پیکربندی کنید: +فرمان‌های slash در Slack یا به‌صورت یک فرمان پیکربندی‌شده واحد ظاهر می‌شوند یا به‌صورت چند فرمان بومی. برای تغییر پیش‌فرض‌های فرمان، `channels.slack.slashCommand` را پیکربندی کنید: - `enabled: false` - `name: "openclaw"` @@ -781,32 +1089,32 @@ manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعا /openclaw /help ``` -دستورهای native به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و به‌جای آن با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. +فرمان‌های بومی به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و در عوض با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. -- حالت خودکار دستور native برای Slack **خاموش** است، بنابراین `commands.native: "auto"` دستورهای native Slack را فعال نمی‌کند. +- حالت خودکار فرمان بومی برای Slack **خاموش** است، بنابراین `commands.native: "auto"` فرمان‌های بومی Slack را فعال نمی‌کند. ```txt /help ``` -منوهای آرگومان native از یک راهبرد رندر تطبیقی استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد: +منوهای آرگومان بومی از راهبرد رندر سازگار استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد: - تا 5 گزینه: بلوک‌های دکمه - 6 تا 100 گزینه: منوی انتخاب ایستا -- بیش از 100 گزینه: انتخاب خارجی با فیلتر ناهمگام گزینه‌ها وقتی handlerهای گزینه‌های interactivity در دسترس باشند -- عبور از محدودیت‌های Slack: مقدارهای کدگذاری‌شده گزینه به دکمه‌ها برمی‌گردند +- بیش از 100 گزینه: انتخاب خارجی با فیلتر async گزینه‌ها وقتی handlerهای گزینه‌های interactivity در دسترس باشند +- عبور از محدودیت‌های Slack: مقدارهای گزینه کدگذاری‌شده به دکمه‌ها fallback می‌کنند ```txt /think ``` -نشست‌های slash از کلیدهای جداشده‌ای مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست گفت‌وگوی مقصد route می‌کنند. +جلسه‌های slash از کلیدهای ایزوله مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای فرمان‌ها را با `CommandTargetSessionKey` به جلسه مکالمه هدف route می‌کنند. ## پاسخ‌های تعاملی -Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط agent را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است. +Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط عامل را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است. -فعال‌سازی سراسری: +آن را به‌صورت سراسری فعال کنید: ```json5 { @@ -820,7 +1128,7 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌ } ``` -یا فقط برای یک حساب Slack فعال کنید: +یا آن را فقط برای یک حساب Slack فعال کنید: ```json5 { @@ -838,42 +1146,42 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌ } ``` -پس از فعال‌سازی، agentها می‌توانند دستورهای پاسخ فقط مخصوص Slack منتشر کنند: +وقتی فعال باشد، عامل‌ها می‌توانند directiveهای پاسخ فقط مخصوص Slack منتشر کنند: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -این دستورها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر موجود رویداد تعامل Slack برمی‌گردانند. +این directiveها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر رویداد تعامل موجود Slack بازمی‌گردانند. نکته‌ها: -- این UI مخصوص Slack است. کانال‌های دیگر دستورهای Slack Block Kit را به سیستم‌های دکمه خودشان ترجمه نمی‌کنند. -- مقدارهای callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط agent. -- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit فراتر بروند، OpenClaw به‌جای ارسال payload بلوک‌های نامعتبر، به پاسخ متنی اصلی برمی‌گردد. +- این UI مخصوص Slack است. کانال‌های دیگر directiveهای Slack Block Kit را به سامانه‌های دکمه خودشان ترجمه نمی‌کنند. +- مقدارهای callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط عامل. +- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit عبور کنند، OpenClaw به‌جای ارسال payload بلوک نامعتبر، به پاسخ متنی اصلی fallback می‌کند. ## تأییدهای exec در Slack -Slack می‌تواند به‌جای برگشت به Web UI یا ترمینال، با دکمه‌ها و تعامل‌های تعاملی به‌عنوان یک client تأیید native عمل کند. +Slack می‌تواند به‌جای fallback کردن به Web UI یا ترمینال، به‌عنوان یک کلاینت تأیید بومی با دکمه‌ها و تعامل‌های تعاملی عمل کند. -- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن native به DM/کانال استفاده می‌کنند. -- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمه native در Slack حل شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد. -- مجوز تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند درخواست‌ها را از طریق Slack تأیید یا رد کنند. +- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن بومی DM/کانال استفاده می‌کنند. +- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمه بومی Slack resolve شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد. +- مجوزدهی تأییدکننده همچنان enforce می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند از طریق Slack درخواست‌ها را تأیید یا رد کنند. -این از همان سطح مشترک دکمه تأیید مثل کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در گفت‌وگو به‌صورت دکمه‌های Block Kit رندر می‌شوند. -وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید همان‌ها هستند؛ OpenClaw -فقط وقتی باید دستور دستی `/approve` را اضافه کند که نتیجه ابزار بگوید تأییدهای chat +این از همان سطح دکمه تأیید مشترک مانند کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در مکالمه به‌صورت دکمه‌های Block Kit رندر می‌شوند. +وقتی این دکمه‌ها حاضر باشند، UX اصلی تأیید هستند؛ OpenClaw +فقط زمانی باید یک فرمان دستی `/approve` اضافه کند که نتیجه ابزار بگوید تأییدهای چت در دسترس نیستند یا تأیید دستی تنها مسیر است. مسیر پیکربندی: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (اختیاری؛ در صورت امکان به `commands.ownerAllowFrom` برمی‌گردد) +- `channels.slack.execApprovals.approvers` (اختیاری؛ وقتی ممکن باشد به `commands.ownerAllowFrom` fallback می‌کند) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`، پیش‌فرض: `dm`) - `agentFilter`, `sessionFilter` Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک -تأییدکننده حل شود، تأییدهای exec native را به‌طور خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان client تأیید native، `enabled: false` را تنظیم کنید. -برای اجبار به فعال‌سازی تأییدهای native وقتی تأییدکننده‌ها حل می‌شوند، `enabled: true` را تنظیم کنید. +تأییدکننده resolve شود، تأییدهای exec بومی را خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان کلاینت تأیید بومی، `enabled: false` را تنظیم کنید. +برای اجبار تأییدهای بومی وقتی تأییدکننده‌ها resolve می‌شوند، `enabled: true` را تنظیم کنید. رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec در Slack: @@ -885,8 +1193,8 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و } ``` -پیکربندی صریح native مربوط به Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، filter اضافه کنید، یا -تحویل به chat مبدأ را فعال کنید: +پیکربندی صریح بومی Slack فقط وقتی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، فیلتر اضافه کنید، یا +تحویل به چت مبدأ را فعال کنید: ```json5 { @@ -902,33 +1210,33 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و } ``` -forwarding مشترک `approvals.exec` جدا است. فقط وقتی از آن استفاده کنید که promptهای تأیید exec باید همچنین -به chatهای دیگر یا مقصدهای out-of-band صریح route شوند. forwarding مشترک `approvals.plugin` نیز -جدا است؛ دکمه‌های native Slack همچنان می‌توانند تأییدهای Plugin را حل کنند، وقتی آن درخواست‌ها از قبل +forward کردن مشترک `approvals.exec` جداست. فقط وقتی از آن استفاده کنید که promptهای تأیید exec باید همچنین +به چت‌های دیگر یا هدف‌های صریح out-of-band route شوند. forward کردن مشترک `approvals.plugin` نیز +جداست؛ دکمه‌های بومی Slack همچنان می‌توانند تأییدهای Plugin را resolve کنند، وقتی آن درخواست‌ها از قبل در Slack فرود آمده باشند. -`/approve` در همان chat نیز در کانال‌ها و DMهای Slack که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forwarding تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید. +`/approve` در همان چت نیز در کانال‌ها و DMهای Slack که از قبل از فرمان‌ها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forward کردن تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید. ## رویدادها و رفتار عملیاتی -- ویرایش/حذف پیام‌ها به رویدادهای سیستم نگاشت می‌شوند. -- پخش‌های رشته‌ای (پاسخ‌های رشته‌ای «Also send to channel») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند. -- رویدادهای افزودن/حذف واکنش به رویدادهای سیستم نگاشت می‌شوند. -- رویدادهای پیوستن/ترک عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به رویدادهای سیستم نگاشت می‌شوند. +- ویرایش‌ها/حذف‌های پیام به رویدادهای سیستمی نگاشت می‌شوند. +- پخش‌های رشته‌ای (پاسخ‌های رشته‌ای «همچنین به کانال ارسال شود») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند. +- رویدادهای افزودن/حذف واکنش به رویدادهای سیستمی نگاشت می‌شوند. +- رویدادهای پیوستن/خروج عضو، ایجاد/تغییر نام کانال، و افزودن/حذف pin به رویدادهای سیستمی نگاشت می‌شوند. - وقتی `configWrites` فعال باشد، `channel_id_changed` می‌تواند کلیدهای پیکربندی کانال را migrate کند. -- metadata موضوع/هدف کانال به‌عنوان context غیرقابل اعتماد در نظر گرفته می‌شود و می‌تواند به context route کردن inject شود. -- آغازکننده رشته و seed کردن context اولیه تاریخچه رشته، در صورت کاربرد، بر اساس allowlistهای فرستنده پیکربندی‌شده filter می‌شوند. -- کنش‌های بلوک و تعامل‌های modal رویدادهای ساخت‌یافته سیستم `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند: - - کنش‌های بلوک: مقدارهای انتخاب‌شده، labelها، مقدارهای picker، و metadata مربوط به `workflow_*` - - رویدادهای modal `view_submission` و `view_closed` با metadata کانال route‌شده و ورودی‌های فرم +- فراداده موضوع/هدف کانال به‌عنوان زمینه نامطمئن در نظر گرفته می‌شود و می‌تواند به زمینه routing تزریق شود. +- seed کردن شروع‌کننده رشته و زمینه اولیه تاریخچه رشته، وقتی قابل اعمال باشد، با allowlistهای فرستنده پیکربندی‌شده فیلتر می‌شود. +- کنش‌های بلوک و تعامل‌های modal رویدادهای سیستمی ساختاریافته `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند: + - کنش‌های بلوک: مقدارهای انتخاب‌شده، برچسب‌ها، مقدارهای picker، و فراداده `workflow_*` + - رویدادهای modal `view_submission` و `view_closed` با فراداده کانال route‌شده و ورودی‌های فرم ## مرجع پیکربندی مرجع اصلی: [مرجع پیکربندی - Slack](/fa/gateway/config-channels#slack). - + -- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- حالت/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (قدیمی: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - toggle سازگاری: `dangerouslyAllowNameMatching` (break-glass؛ مگر در صورت نیاز خاموش نگه دارید) - دسترسی کانال: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` @@ -941,15 +1249,15 @@ forwarding مشترک `approvals.exec` جدا است. فقط وقتی از آن ## عیب‌یابی - + به‌ترتیب بررسی کنید: - `groupPolicy` - - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام زیر `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون route کردن کانال به‌طور پیش‌فرض ID-first است. برای پیدا کردن یک ID: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است. + - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه‌های کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام زیر `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون routing کانال به‌طور پیش‌فرض اول بر اساس شناسه است. برای یافتن شناسه: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است. - `requireMention` - - allowlist کاربران در سطح هر کانال + - allowlist `users` برای هر کانال - دستورهای مفید: + فرمان‌های مفید: ```bash openclaw channels status --probe @@ -959,15 +1267,15 @@ openclaw doctor - + بررسی کنید: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (یا گزینه قدیمی `channels.slack.dm.policy`) + - `channels.slack.dmPolicy` (یا `channels.slack.dm.policy` قدیمی) - تأییدهای pairing / ورودی‌های allowlist - - رویدادهای DM مربوط به Slack Assistant: logهای verbose که `drop message_changed` را ذکر می‌کنند - معمولاً یعنی Slack یک رویداد ویرایش‌شده Assistant-thread بدون - فرستنده انسانی قابل بازیابی در metadata پیام فرستاده است + - رویدادهای DM دستیار Slack: لاگ‌های verbose که به `drop message_changed` اشاره می‌کنند + معمولاً یعنی Slack یک رویداد رشته دستیار ویرایش‌شده را بدون + فرستنده انسانی قابل بازیابی در فراداده پیام ارسال کرده است ```bash openclaw pairing list slack @@ -975,35 +1283,35 @@ openclaw pairing list slack - - توکن‌های bot + app و فعال بودن Socket Mode را در تنظیمات برنامه Slack اعتبارسنجی کنید. + + توکن‌های bot + app و فعال‌سازی Socket Mode را در تنظیمات برنامه Slack اعتبارسنجی کنید. اگر `openclaw channels status --probe --json` مقدار `botTokenStatus` یا - `appTokenStatus: "configured_unavailable"` را نشان می‌دهد، حساب Slack + `appTokenStatus: "configured_unavailable"` را نشان دهد، حساب Slack پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتیبانی‌شده با SecretRef را resolve کند. - + اعتبارسنجی کنید: - signing secret - مسیر Webhook - - URLهای درخواست Slack (Events + Interactivity + Slash Commands) + - URLهای درخواست Slack (رویدادها + Interactivity + Slash Commands) - `webhookPath` یکتا برای هر حساب HTTP اگر `signingSecretStatus: "configured_unavailable"` در snapshotهای حساب - ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته - signing secret پشتیبانی‌شده با SecretRef را resolve کند. + ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته signing secret + پشتیبانی‌شده با SecretRef را resolve کند. - - بررسی کنید که منظورتان کدام بوده است: + + بررسی کنید آیا منظورتان این بوده است: - - حالت دستور native (`channels.slack.commands.native: true`) با دستورهای slash متناظر ثبت‌شده در Slack - - یا حالت دستور slash واحد (`channels.slack.slashCommand.enabled: true`) + - حالت فرمان بومی (`channels.slack.commands.native: true`) با فرمان‌های slash متناظر ثبت‌شده در Slack + - یا حالت فرمان slash واحد (`channels.slack.slashCommand.enabled: true`) همچنین `commands.useAccessGroups` و allowlistهای کانال/کاربر را بررسی کنید. @@ -1012,88 +1320,88 @@ openclaw pairing list slack ## مرجع vision پیوست -Slack وقتی دانلود فایل‌های Slack موفق باشند و محدودیت‌های اندازه اجازه دهند، می‌تواند رسانه دانلودشده را به turn مربوط به agent پیوست کند. فایل‌های تصویر می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به مدل پاسخ دارای قابلیت vision داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌عنوان context فایل قابل دانلود نگه داشته می‌شوند. +وقتی دانلود فایل‌های Slack موفق باشد و محدودیت‌های اندازه اجازه دهند، Slack می‌تواند رسانه دانلودشده را به turn عامل پیوست کند. فایل‌های تصویر می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به مدل پاسخ دارای قابلیت vision داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌عنوان زمینه فایل قابل دانلود نگه داشته می‌شوند. -### انواع رسانه پشتیبانی‌شده +### نوع‌های رسانه پشتیبانی‌شده | نوع رسانه | منبع | رفتار فعلی | یادداشت‌ها | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود می‌شود و برای پردازش دارای قابلیت بینایی به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض 20 MB) | -| فایل‌های PDF | URL فایل Slack | دانلود می‌شود و به‌عنوان زمینهٔ فایل برای ابزارهایی مانند `download-file` یا `pdf` در دسترس قرار می‌گیرد | ورودی Slack به‌طور خودکار PDFها را به ورودی بینایی تصویر تبدیل نمی‌کند | -| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود می‌شود و به‌عنوان زمینهٔ فایل در دسترس قرار می‌گیرد | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | -| پاسخ‌های رشته | فایل‌های آغازگر رشته | فایل‌های پیام ریشه وقتی پاسخ رسانهٔ مستقیم ندارد می‌توانند به‌عنوان زمینه بارگذاری شوند | آغازگرهای فقط‌فایل از یک جای‌نگهدار پیوست استفاده می‌کنند | -| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌صورت مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است | +| تصاویر JPEG / PNG / GIF / WebP | نشانی فایل Slack | دانلود و به نوبت پیوست می‌شود تا با قابلیت‌های دارای بینایی پردازش شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض 20 MB) | +| فایل‌های PDF | نشانی فایل Slack | دانلود می‌شود و به‌عنوان زمینه فایل برای ابزارهایی مانند `download-file` یا `pdf` در دسترس قرار می‌گیرد | ورودی Slack به‌صورت خودکار PDFها را به ورودی بینایی تصویر تبدیل نمی‌کند | +| فایل‌های دیگر | نشانی فایل Slack | هرجا ممکن باشد دانلود می‌شود و به‌عنوان زمینه فایل در دسترس قرار می‌گیرد | فایل‌های دودویی به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | +| پاسخ‌های رشته | فایل‌های آغازگر رشته | فایل‌های پیام ریشه می‌توانند وقتی پاسخ رسانه مستقیم ندارد، به‌عنوان زمینه بارگذاری شوند | آغازگرهای فقط‌فایل از یک جانگهدار پیوست استفاده می‌کنند | +| پیام‌های چندتصویری | چندین فایل Slack | هر فایل به‌صورت مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است | -### خط لولهٔ ورودی +### خط لوله ورودی -وقتی یک پیام Slack با پیوست‌های فایل می‌رسد: +وقتی یک پیام Slack همراه با پیوست‌های فایل وارد می‌شود: -1. OpenClaw فایل را از URL خصوصی Slack با استفاده از توکن ربات (`xoxb-...`) دانلود می‌کند. -2. فایل در صورت موفقیت در انبار رسانه نوشته می‌شود. -3. مسیرهای رسانهٔ دانلودشده و نوع‌های محتوا به زمینهٔ ورودی افزوده می‌شوند. -4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویر موجود در آن زمینه استفاده کنند. -5. فایل‌های غیرتصویری همچنان به‌صورت فرادادهٔ فایل یا ارجاع‌های رسانه برای ابزارهایی که می‌توانند آن‌ها را پردازش کنند در دسترس می‌مانند. +1. OpenClaw فایل را از نشانی خصوصی Slack با استفاده از توکن ربات (`xoxb-...`) دانلود می‌کند. +2. در صورت موفقیت، فایل در ذخیره‌گاه رسانه نوشته می‌شود. +3. مسیرهای رسانه دانلودشده و نوع‌های محتوا به زمینه ورودی اضافه می‌شوند. +4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویر در آن زمینه استفاده کنند. +5. فایل‌های غیرتصویری برای ابزارهایی که می‌توانند آن‌ها را پردازش کنند، همچنان به‌صورت فراداده فایل یا ارجاع رسانه در دسترس می‌مانند. -### وراثت پیوست ریشهٔ رشته +### وراثت پیوست ریشه رشته -وقتی پیامی در یک رشته می‌رسد (یک والد `thread_ts` دارد): +وقتی پیامی در یک رشته وارد می‌شود (والد `thread_ts` دارد): -- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ گنجانده‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ آغازگر رشته بارگذاری کند. +- اگر خود پاسخ رسانه مستقیم نداشته باشد و پیام ریشه شامل فایل باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینه آغازگر رشته بارگذاری کند. - پیوست‌های مستقیم پاسخ بر پیوست‌های پیام ریشه اولویت دارند. -- پیام ریشه‌ای که فقط فایل دارد و متن ندارد با یک جای‌نگهدار پیوست نمایش داده می‌شود تا مسیر پشتیبان همچنان بتواند فایل‌های آن را شامل شود. +- پیام ریشه‌ای که فقط فایل دارد و متن ندارد، با یک جانگهدار پیوست نمایش داده می‌شود تا مسیر جایگزین همچنان بتواند فایل‌های آن را شامل کند. -### مدیریت چند پیوست +### پردازش چند پیوست -وقتی یک پیام Slack شامل چند پیوست فایل باشد: +وقتی یک پیام Slack چندین پیوست فایل دارد: -- هر پیوست به‌صورت مستقل از طریق خط لولهٔ رسانه پردازش می‌شود. -- ارجاع‌های رسانهٔ دانلودشده در زمینهٔ پیام تجمیع می‌شوند. +- هر پیوست به‌صورت مستقل از طریق خط لوله رسانه پردازش می‌شود. +- ارجاع‌های رسانه دانلودشده در زمینه پیام تجمیع می‌شوند. - ترتیب پردازش از ترتیب فایل‌های Slack در بار رویداد پیروی می‌کند. -- شکست در دانلود یک پیوست، سایر پیوست‌ها را مسدود نمی‌کند. +- شکست در دانلود یک پیوست، پیوست‌های دیگر را مسدود نمی‌کند. ### محدودیت‌های اندازه، دانلود و مدل - **سقف اندازه**: پیش‌فرض 20 MB برای هر فایل. از طریق `channels.slack.mediaMaxMb` قابل پیکربندی است. -- **شکست‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، URLهای منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بیش‌ازحد بزرگ، و پاسخ‌های HTML مربوط به احراز هویت/ورود Slack به‌جای اینکه به‌عنوان قالب‌های پشتیبانی‌نشده گزارش شوند، نادیده گرفته می‌شوند. -- **مدل بینایی**: تحلیل تصویر وقتی مدل پاسخ فعال از بینایی پشتیبانی کند از همان مدل استفاده می‌کند، یا از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel` استفاده می‌کند. +- **شکست‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، نشانی‌های منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بزرگ‌تر از سقف، و پاسخ‌های HTML احراز هویت/ورود Slack به‌جای گزارش شدن به‌عنوان قالب‌های پشتیبانی‌نشده، نادیده گرفته می‌شوند. +- **مدل بینایی**: تحلیل تصویر وقتی مدل پاسخ فعال از بینایی پشتیبانی کند از همان مدل استفاده می‌کند، یا از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel`. ### محدودیت‌های شناخته‌شده -| سناریو | رفتار فعلی | راه‌حل جایگزین | +| سناریو | رفتار فعلی | راهکار جایگزین | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| URL فایل Slack منقضی شده | فایل نادیده گرفته می‌شود؛ خطایی نمایش داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید | +| نشانی فایل منقضی‌شده Slack | فایل نادیده گرفته می‌شود؛ خطایی نشان داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید | | مدل بینایی پیکربندی نشده است | پیوست‌های تصویر به‌عنوان ارجاع‌های رسانه ذخیره می‌شوند، اما به‌عنوان تصویر تحلیل نمی‌شوند | `agents.defaults.imageModel` را پیکربندی کنید یا از یک مدل پاسخ دارای قابلیت بینایی استفاده کنید | -| تصاویر بسیار بزرگ (> 20 MB به‌صورت پیش‌فرض) | طبق سقف اندازه نادیده گرفته می‌شود | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید | -| پیوست‌های فورواردشده/اشتراک‌گذاری‌شده | متن و رسانهٔ تصویر/فایل میزبانی‌شده در Slack به‌صورت بهترین تلاش پردازش می‌شوند | مستقیماً در رشتهٔ OpenClaw دوباره به اشتراک بگذارید | -| پیوست‌های PDF | به‌عنوان زمینهٔ فایل/رسانه ذخیره می‌شوند، نه اینکه به‌طور خودکار از مسیر بینایی تصویر عبور کنند | از `download-file` برای فرادادهٔ فایل یا از ابزار `pdf` برای تحلیل PDF استفاده کنید | +| تصاویر بسیار بزرگ (> 20 MB به‌صورت پیش‌فرض) | بر اساس سقف اندازه نادیده گرفته می‌شوند | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید | +| پیوست‌های فورواردشده/اشتراک‌گذاری‌شده | متن و رسانه تصویر/فایل میزبانی‌شده در Slack در حد بهترین تلاش پردازش می‌شوند | مستقیماً در رشته OpenClaw دوباره به اشتراک بگذارید | +| پیوست‌های PDF | به‌عنوان زمینه فایل/رسانه ذخیره می‌شوند، نه اینکه به‌صورت خودکار از مسیر بینایی تصویر عبور داده شوند | برای فراداده فایل از `download-file` یا برای تحلیل PDF از ابزار `pdf` استفاده کنید | ### مستندات مرتبط -- [خط لولهٔ درک رسانه](/fa/nodes/media-understanding) +- [خط لوله درک رسانه](/fa/nodes/media-understanding) - [ابزار PDF](/fa/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست‌های Slack +- حماسه: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست Slack - آزمون‌های رگرسیون: [#51353](https://github.com/openclaw/openclaw/issues/51353) - راستی‌آزمایی زنده: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## مرتبط - - یک کاربر Slack را به Gateway جفت کنید. + + یک کاربر Slack را با Gateway جفت کنید. - - رفتار کانال و DM گروهی. + + رفتار کانال و گروه DM. - + پیام‌های ورودی را به عامل‌ها مسیریابی کنید. - - مدل تهدید و سخت‌سازی. + + مدل تهدید و مقاوم‌سازی. - - چیدمان پیکربندی و اولویت‌بندی. + + چیدمان پیکربندی و تقدم. - + فهرست فرمان‌ها و رفتار. diff --git a/docs/fa/ci.md b/docs/fa/ci.md index de17aee18..cd8026368 100644 --- a/docs/fa/ci.md +++ b/docs/fa/ci.md @@ -1,94 +1,94 @@ --- read_when: - - باید بفهمید چرا یک وظیفهٔ CI اجرا شد یا نشد + - باید بفهمید چرا یک کار CI اجرا شد یا اجرا نشد - شما در حال عیب‌یابی یک بررسی ناموفق GitHub Actions هستید - - شما در حال هماهنگی یک اجرای اعتبارسنجی انتشار یا اجرای مجدد آن هستید - - شما در حال تغییر ارسال ClawSweeper یا بازارسال فعالیت GitHub هستید -summary: گراف کارهای CI، گیت‌های دامنه، چترهای انتشار و معادل‌های فرمان‌های محلی -title: خط لولهٔ CI + - شما در حال هماهنگی برای اجرای اعتبارسنجی انتشار یا اجرای مجدد آن هستید + - شما در حال تغییر ارسال ClawSweeper یا انتقال فعالیت GitHub هستید +summary: نمودار کارهای CI، گیت‌های دامنه، چترهای انتشار، و معادل‌های فرمان‌های محلی +title: خط لوله CI x-i18n: - generated_at: "2026-05-04T07:03:13Z" + generated_at: "2026-05-05T01:44:36Z" model: gpt-5.5 provider: openai - source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d + source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66 source_path: ci.md workflow: 16 --- -OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job `preflight`، diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجراهای دستی `workflow_dispatch` عمداً از محدوده‌بندی هوشمند عبور می‌کنند و برای release candidateها و اعتبارسنجی گسترده، کل گراف را منشعب می‌کنند. laneهای Android از طریق `include_android` همچنان اختیاری می‌مانند. پوشش Plugin مخصوص انتشار در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود. +OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job مربوط به `preflight` diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجراهای دستی `workflow_dispatch` عمدا scopeبندی هوشمند را دور می‌زنند و برای release candidateها و اعتبارسنجی گسترده، کل graph را پخش می‌کنند. laneهای Android از طریق `include_android` همچنان opt-in می‌مانند. پوشش Plugin مختص انتشار در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود. ## نمای کلی pipeline | Job | هدف | زمان اجرا | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | تشخیص تغییرات فقط مستندات، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای غیر draft | -| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای غیر draft | -| `security-dependency-audit` | audit بدون وابستگی lockfile تولید در برابر advisoryهای npm | همیشه روی pushها و PRهای غیر draft | -| `security-fast` | aggregate الزامی برای jobهای امنیتی سریع | همیشه روی pushها و PRهای غیر draft | -| `check-dependencies` | گذر فقط وابستگی Knip تولید به‌علاوه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node | -| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های artifact ساخته‌شده، و artifactهای پایین‌دستی قابل استفاده مجدد | تغییرات مرتبط با Node | +| `preflight` | تشخیص تغییرات فقط-docs، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای غیر-draft | +| `security-scm-fast` | تشخیص private key و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای غیر-draft | +| `security-dependency-audit` | audit lockfile تولیدیِ بدون dependency در برابر advisories مربوط به npm | همیشه روی pushها و PRهای غیر-draft | +| `security-fast` | aggregate الزامی برای jobهای امنیتی سریع | همیشه روی pushها و PRهای غیر-draft | +| `check-dependencies` | گذر production Knip فقط برای dependencyها به‌همراه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node | +| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های artifact ساخته‌شده، و artifactهای قابل استفاده مجدد برای پایین‌دست | تغییرات مرتبط با Node | | `checks-fast-core` | laneهای صحت‌سنجی سریع Linux مانند بررسی‌های bundled/plugin-contract/protocol | تغییرات مرتبط با Node | -| `checks-fast-contracts-channels` | بررسی‌های sharded قرارداد channel با نتیجه بررسی aggregate پایدار | تغییرات مرتبط با Node | +| `checks-fast-contracts-channels` | بررسی‌های sharded مربوط به قرارداد channel با نتیجه aggregate پایدار | تغییرات مرتبط با Node | | `checks-node-core-test` | shardهای تست Core Node، به‌جز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node | -| `check` | معادل gate محلی اصلی sharded: typeهای تولید، lint، guardها، typeهای تست، و smoke سختگیرانه | تغییرات مرتبط با Node | -| `check-additional` | معماری، drift مرزی/prompt به‌صورت sharded، guardهای extension، مرز package، و gateway watch | تغییرات مرتبط با Node | -| `build-smoke` | تست‌های smoke مربوط به CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node | +| `check` | معادل gate محلی اصلیِ sharded: types تولیدی، lint، guardها، test types، و smoke سخت‌گیرانه | تغییرات مرتبط با Node | +| `check-additional` | معماری، drift مربوط به boundary/prompt به‌صورت sharded، guardهای extension، package boundary، و gateway watch | تغییرات مرتبط با Node | +| `build-smoke` | تست‌های smoke برای CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node | | `checks` | verifier برای تست‌های channel مربوط به artifact ساخته‌شده | تغییرات مرتبط با Node | -| `checks-node-compat-node22` | lane ساخت و smoke سازگاری Node 22 | dispatch دستی CI برای انتشارها | -| `check-docs` | قالب‌بندی مستندات، lint، و بررسی لینک‌های خراب | مستندات تغییر کرده باشند | -| `skills-python` | Ruff + pytest برای skills مبتنی بر Python | تغییرات مرتبط با Python-skill | -| `checks-windows` | تست‌های process/path مخصوص Windows به‌علاوه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows | +| `checks-node-compat-node22` | lane ساخت و smoke برای سازگاری با Node 22 | dispatch دستی CI برای انتشارها | +| `check-docs` | بررسی‌های قالب‌بندی docs، lint، و لینک‌های خراب | وقتی docs تغییر کرده باشد | +| `skills-python` | Ruff + pytest برای skills متکی بر Python | تغییرات مرتبط با skillهای Python | +| `checks-windows` | تست‌های اختصاصی Windows برای process/path به‌همراه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows | | `macos-node` | lane تست TypeScript در macOS با استفاده از artifactهای ساخته‌شده مشترک | تغییرات مرتبط با macOS | -| `macos-swift` | lint، build، و تست‌های Swift برای app macOS | تغییرات مرتبط با macOS | -| `android` | تست‌های unit Android برای هر دو flavor به‌علاوه یک build APK debug | تغییرات مرتبط با Android | -| `test-performance-agent` | بهینه‌سازی روزانه تست‌های کند Codex پس از فعالیت مورد اعتماد | موفقیت Main CI یا dispatch دستی | -| `openclaw-performance` | گزارش‌های عملکرد runtime روزانه/درخواستی Kova با laneهای mock-provider، deep-profile، و live GPT 5.4 | dispatch زمان‌بندی‌شده و دستی | +| `macos-swift` | Swift lint، build، و تست‌ها برای اپلیکیشن macOS | تغییرات مرتبط با macOS | +| `android` | تست‌های unit مربوط به Android برای هر دو flavor به‌همراه یک build از debug APK | تغییرات مرتبط با Android | +| `test-performance-agent` | بهینه‌سازی روزانه تست‌های کند Codex پس از فعالیت مورداعتماد | موفقیت Main CI یا dispatch دستی | +| `openclaw-performance` | گزارش‌های روزانه/درخواستی عملکرد runtime مربوط به Kova با laneهای mock-provider، deep-profile، و GPT 5.4 live | زمان‌بندی‌شده و dispatch دستی | ## ترتیب fail-fast -1. `preflight` تصمیم می‌گیرد اصلاً کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` مرحله‌هایی داخل این job هستند، نه jobهای مستقل. -2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگین‌تر artifact و matrix پلتفرم، سریع fail می‌شوند. -3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان پایین‌دستی به‌محض آماده شدن build مشترک شروع شوند. -4. پس از آن، laneهای سنگین‌تر پلتفرم و runtime منشعب می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`. +1. `preflight` تصمیم می‌گیرد اصلا کدام laneها وجود داشته باشند. منطق‌های `docs-scope` و `changed-scope` stepهایی داخل همین job هستند، نه jobهای مستقل. +2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون منتظر ماندن برای jobهای سنگین‌تر artifact و matrix پلتفرم، سریع fail می‌شوند. +3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان پایین‌دست به‌محض آماده شدن build مشترک شروع شوند. +4. laneهای سنگین‌تر پلتفرم و runtime بعد از آن پخش می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`. -GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref مربوط به `main` قرار می‌گیرد، jobهای جایگزین‌شده را به‌صورت `cancelled` علامت‌گذاری کند. این را noise مربوط به CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref نیز fail شده باشد. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند، بنابراین همچنان failureهای عادی shard را گزارش می‌کنند اما پس از اینکه کل workflow از قبل جایگزین شده باشد، در queue قرار نمی‌گیرند. کلید concurrency خودکار CI نسخه‌گذاری شده است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند اجراهای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و اجراهای در حال انجام را cancel نمی‌کنند. +وقتی push جدیدتری روی همان PR یا ref مربوط به `main` وارد شود، GitHub ممکن است jobهای superseded را با وضعیت `cancelled` علامت‌گذاری کند. مگر اینکه جدیدترین run برای همان ref هم در حال fail شدن باشد، این را نویز CI در نظر بگیرید. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند تا همچنان failهای عادی shard را گزارش کنند، اما پس از superseded شدن کل workflow در صف قرار نگیرند. concurrency key خودکار CI versioned است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند runهای جدیدتر main را نامحدود مسدود کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و runهای درحال اجرا را cancel نمی‌کنند. ## Scope و routing -منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تست‌های unit در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی، تشخیص changed-scope را رد می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه بخش‌های scoped تغییر کرده‌اند. +منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تست‌های unit در `src/scripts/ci-changed-scope.test.ts` پوشش داده می‌شود. dispatch دستی تشخیص changed-scope را رد می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه areaهای scoped تغییر کرده‌اند. -- **ویرایش‌های workflow مربوط به CI** گراف Node CI به‌علاوه linting workflow را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native Windows، Android، یا macOS را اجبار نمی‌کنند؛ آن laneهای پلتفرم همچنان به تغییرات source پلتفرم scoped می‌مانند. -- **ویرایش‌های فقط routing مربوط به CI، ویرایش‌های منتخب و کم‌هزینه fixture تست core، و ویرایش‌های محدود helper/test-routing قرارداد Plugin** از مسیر سریع manifest فقط Node استفاده می‌کنند: `preflight`، امنیت، و یک task واحد `checks-fast-core`. وقتی تغییر به سطح‌های routing یا helper محدود باشد که task سریع مستقیماً آن‌ها را اجرا می‌کند، آن مسیر artifactهای build، سازگاری Node 22، قراردادهای channel، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی را رد می‌کند. -- **بررسی‌های Windows Node** به wrapperهای process/path مخصوص Windows، helperهای runner مربوط به npm/pnpm/UI، config مدیر package، و سطح‌های workflow مربوط به CI که آن lane را اجرا می‌کنند scoped هستند؛ تغییرات نامرتبط source، Plugin، install-smoke، و فقط تست روی laneهای Linux Node باقی می‌مانند. +- **ویرایش‌های workflow مربوط به CI** graph مربوط به Node CI و linting workflow را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native مربوط به Windows، Android، یا macOS را اجبار نمی‌کنند؛ این laneهای پلتفرم همچنان به تغییرات source همان پلتفرم scope می‌شوند. +- **ویرایش‌های فقط routing در CI، ویرایش‌های انتخاب‌شده fixture تست core ارزان، و ویرایش‌های محدود helper/test-routing قرارداد Plugin** از مسیر manifest سریع فقط Node استفاده می‌کنند: `preflight`، امنیت، و یک task از `checks-fast-core`. وقتی تغییر به سطوح routing یا helper که task سریع مستقیما exercise می‌کند محدود باشد، آن مسیر artifactهای build، سازگاری Node 22، قراردادهای channel، shardهای کامل core، shardهای Pluginهای bundled، و matrixهای guard اضافی را رد می‌کند. +- **بررسی‌های Windows Node** به wrapperهای process/path اختصاصی Windows، helperهای runner مربوط به npm/pnpm/UI، config package manager، و سطوح workflow مربوط به CI که آن lane را اجرا می‌کنند scope می‌شوند؛ تغییرات نامرتبط source، Plugin، install-smoke، و فقط-test روی laneهای Linux Node باقی می‌مانند. -کندترین خانواده‌های تست Node تقسیم یا متعادل شده‌اند تا هر job بدون رزرو بیش‌ازحد runnerها کوچک بماند: قراردادهای channel به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای core unit fast/support جداگانه اجرا می‌شوند، زیرساخت runtime core بین shardهای state و process/config تقسیم شده است، auto-reply به‌صورت workerهای متعادل اجرا می‌شود (با تقسیم subtree مربوط به reply به shardهای agent-runner، dispatch، و commands/state-routing)، و configهای agentic gateway/server به‌جای انتظار برای artifactهای ساخته‌شده، میان laneهای chat/auth/model/http-plugin/runtime/startup تقسیم شده‌اند. تست‌های گسترده browser، QA، media، و Pluginهای متفرقه به‌جای catch-all مشترک Plugin، از configهای اختصاصی Vitest خود استفاده می‌کنند. shardهای include-pattern، entryهای timing را با نام shard مربوط به CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کارهای compile/canary مرز package را کنار هم نگه می‌دارد و معماری توپولوژی runtime را از پوشش gateway watch جدا می‌کند؛ فهرست guard مرزی روی چهار shard matrix stripe شده است، که هرکدام guardهای مستقل منتخب را هم‌زمان اجرا می‌کنند و timing هر بررسی را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift prompt مسیر موفق runtime مربوط به Codex به PRی که باعث آن شده pin شود. Gateway watch، تست‌های channel، و shard مرز support مربوط به core پس از اینکه `dist/` و `dist-runtime/` ساخته شدند، هم‌زمان داخل `build-artifacts` اجرا می‌شوند. +کندترین خانواده‌های تست Node split یا balance شده‌اند تا هر job بدون over-reserve کردن runnerها کوچک بماند: قراردادهای channel به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای fast/support مربوط به core unit جداگانه اجرا می‌شوند، infra مربوط به core runtime بین shardهای state و process/config تقسیم می‌شود، auto-reply به‌صورت workerهای متوازن اجرا می‌شود (با subtree مربوط به reply که به shardهای agent-runner، dispatch، و commands/state-routing تقسیم شده)، و configهای agentic gateway/server به laneهای chat/auth/model/http-plugin/runtime/startup تقسیم می‌شوند، به‌جای اینکه منتظر artifactهای ساخته‌شده بمانند. تست‌های broad browser، QA، media، و Pluginهای متفرقه به‌جای catch-all مشترک Plugin از configهای Vitest اختصاصی خودشان استفاده می‌کنند. shardهای include-pattern ورودی‌های timing را با نام shard در CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از shard فیلترشده تشخیص دهد. `check-additional` کار compile/canary مربوط به package-boundary را کنار هم نگه می‌دارد و معماری topology مربوط به runtime را از پوشش gateway watch جدا می‌کند؛ فهرست guardهای boundary بین چهار shard در matrix stripe شده است، که هرکدام guardهای مستقل انتخاب‌شده را همزمان اجرا می‌کنند و timing هر check را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift مربوط به prompt مسیر خوشحال runtime در Codex به همان PRی pin شود که باعث آن شده است. Gateway watch، تست‌های channel، و shard مربوط به core support-boundary داخل `build-artifacts` و پس از ساخته شدن `dist/` و `dist-runtime/` به‌صورت همزمان اجرا می‌شوند. -Android CI هم `testPlayDebugUnitTest` و هم `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس APK debug مربوط به Play را می‌سازد. flavor شخص ثالث هیچ source set یا manifest جداگانه‌ای ندارد؛ lane تست unit آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log کامپایل می‌کند، در حالی که از یک job تکراری package کردن APK debug در هر push مرتبط با Android جلوگیری می‌کند. +Android CI هم `testPlayDebugUnitTest` و هم `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس Play debug APK را می‌سازد. flavor مربوط به third-party source set یا manifest جداگانه‌ای ندارد؛ lane مربوط به unit-test آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log compile می‌کند، درحالی‌که از job تکراری package کردن debug APK روی هر push مرتبط با Android اجتناب می‌کند. -shard مربوط به `check-dependencies`، `pnpm deadcode:dependencies` (یک گذر فقط وابستگی Knip تولید که به آخرین نسخه Knip pin شده و minimum release age مربوط به pnpm برای نصب `dlx` غیرفعال است) و `pnpm deadcode:unused-files` را اجرا می‌کند، که یافته‌های فایل استفاده‌نشده تولیدی Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. guard فایل استفاده‌نشده زمانی fail می‌شود که یک PR فایل استفاده‌نشده جدید و بازبینی‌نشده‌ای اضافه کند یا یک entry قدیمی در allowlist باقی بگذارد، در حالی که سطح‌های intentional dynamic plugin، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت static resolve کند حفظ می‌کند. +shard مربوط به `check-dependencies`، `pnpm deadcode:dependencies` (یک گذر production Knip فقط برای dependencyها که به آخرین نسخه Knip pin شده و minimum release age مربوط به pnpm برای install با `dlx` غیرفعال است) و `pnpm deadcode:unused-files` را اجرا می‌کند، که یافته‌های production Knip برای فایل‌های استفاده‌نشده را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. وقتی یک PR فایل استفاده‌نشده جدید و بازبینی‌نشده‌ای اضافه کند یا یک ورودی stale در allowlist باقی بگذارد، guard فایل استفاده‌نشده fail می‌شود، درحالی‌که سطوح intentional مربوط به Plugin پویا، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت static resolve کند حفظ می‌کند. -## forwarding فعالیت ClawSweeper +## Forward کردن فعالیت ClawSweeper -`.github/workflows/clawsweeper-dispatch.yml` پل سمت هدف از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیرقابل اعتماد را checkout یا اجرا نمی‌کند. workflow یک token مربوط به GitHub App از `CLAWSWEEPER_APP_PRIVATE_KEY` ایجاد می‌کند، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند. +`.github/workflows/clawsweeper-dispatch.yml` bridge سمت target از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request نامطمئن را checkout یا اجرا نمی‌کند. workflow از `CLAWSWEEPER_APP_PRIVATE_KEY` یک token مربوط به GitHub App می‌سازد، سپس payloadهای compact از نوع `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند. این workflow چهار lane دارد: - `clawsweeper_item` برای درخواست‌های دقیق review مربوط به issue و pull request؛ - `clawsweeper_comment` برای commandهای صریح ClawSweeper در commentهای issue؛ - `clawsweeper_commit_review` برای درخواست‌های review در سطح commit روی pushهای `main`؛ -- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است بررسی کند. +- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است inspect کند. -lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها وقتی وجود داشته باشند. این lane عمداً از forward کردن کل body مربوط به webhook اجتناب می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper`، `.github/workflows/github-activity.yml` است، که event نرمال‌شده را برای agent مربوط به ClawSweeper به hook مربوط به OpenClaw Gateway ارسال می‌کند. +lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها وقتی وجود داشته باشند. این مسیر عمدا از forward کردن بدنه کامل Webhook اجتناب می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper` برابر `.github/workflows/github-activity.yml` است، که event نرمال‌شده را به hook مربوط به OpenClaw Gateway برای agent مربوط به ClawSweeper post می‌کند. -فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper مقصد Discord را در prompt خود دریافت می‌کند و فقط وقتی event غافلگیرکننده، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید باشد باید در `#clawsweeper` پست کند. openهای routine، editها، bot churn، noise تکراری Webhook، و ترافیک عادی review باید به `NO_REPLY` منجر شوند. +فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper مقصد Discord را در prompt خود دریافت می‌کند و فقط وقتی باید به `#clawsweeper` post کند که event غافلگیرکننده، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید باشد. openها، editها، bot churn، نویز تکراری Webhook، و ترافیک review عادی باید به `NO_REPLY` منتهی شوند. -در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و messageهای commit مربوط به GitHub را داده غیرقابل اعتماد در نظر بگیرید. آن‌ها input برای summarization و triage هستند، نه دستورالعمل برای workflow یا runtime agent. +titleها، commentها، bodyها، متن review، نام branchها، و پیام‌های commit در GitHub را در سراسر این مسیر داده نامطمئن در نظر بگیرید. آن‌ها ورودی summarization و triage هستند، نه instruction برای workflow یا runtime مربوط به agent. -## dispatchهای دستی +## Dispatchهای دستی -اجرای دستی CI همان گراف کارهای CI عادی را اجرا می‌کند، اما همه مسیرهای scoped غیر Android را اجباری فعال می‌کند: shardهای Linux Node، shardهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های مستندات، Python skills، Windows، macOS و Control UI i18n. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، shard فقط مخصوص انتشار `agentic-plugins`، sweep کامل دسته extension و مسیرهای Docker پیش‌انتشار Plugin از CI مستثنا هستند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation` workflow جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند. +اجرای دستی CI همان گراف کار عادی CI را اجرا می‌کند، اما همه laneهای محدوده‌بندی‌شده غیر Android را اجباری فعال می‌کند: shardهای Linux Node، shardهای Pluginهای همراه، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Python skills، Windows، macOS و بومی‌سازی Control UI. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، shard مخصوص انتشار `agentic-plugins`، sweep کامل دسته‌ای extension، و laneهای Docker پیش‌انتشار Plugin از CI حذف شده‌اند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation` گردش‌کار جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند. -اجراهای دستی از یک گروه concurrency یکتا استفاده می‌کنند تا مجموعه کامل release-candidate با یک اجرای push یا PR دیگر روی همان ref لغو نشود. ورودی اختیاری `target_ref` به فراخوان مورد اعتماد اجازه می‌دهد آن گراف را روی یک branch، tag یا commit SHA کامل اجرا کند، در حالی که از فایل workflow متعلق به dispatch ref انتخاب‌شده استفاده می‌شود. +اجراهای دستی از یک گروه هم‌روندی یکتا استفاده می‌کنند تا مجموعه کامل release-candidate با اجرای push یا PR دیگری روی همان ref لغو نشود. ورودی اختیاری `target_ref` به فراخوان مورد اعتماد اجازه می‌دهد آن گراف را روی یک branch، tag، یا commit SHA کامل اجرا کند، در حالی که از فایل workflow موجود در dispatch ref انتخاب‌شده استفاده می‌کند. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -96,14 +96,14 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## اجراکننده‌ها +## Runnerها -| اجراکننده | کارها | +| Runner | Jobها | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع protocol/contract/bundled، بررسی‌های sharded قرارداد کانال، shardهای `check` به‌جز lint، shardها و aggregateهای `check-additional`، verifierهای aggregate آزمون Node، بررسی‌های مستندات، Python skills، workflow-sanity، labeler، auto-response؛ install-smoke preflight نیز از Ubuntu میزبانی‌شده در GitHub استفاده می‌کند تا matrix Blacksmith زودتر بتواند queue شود | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، shardهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types` و `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، shardهای آزمون Linux Node، shardهای آزمون Plugin بسته‌بندی‌شده، `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به اندازه‌ای حساس به CPU که 8 vCPU بیش از آنکه صرفه‌جویی کند هزینه داشت)؛ buildهای Docker برای install-smoke (هزینه زمان queue برای 32-vCPU بیش از صرفه‌جویی آن بود) | +| `ubuntu-24.04` | `preflight`، jobهای امنیتی سریع و تجمیع‌کننده‌ها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع پروتکل/قرارداد/همراه، بررسی‌های shardشده قرارداد کانال، shardهای `check` به‌جز lint، shardها و تجمیع‌کننده‌های `check-additional`، verifierهای تجمیعی تست Node، بررسی‌های مستندات، Python skills، workflow-sanity، labeler، auto-response؛ preflight install-smoke نیز از Ubuntu میزبانی‌شده توسط GitHub استفاده می‌کند تا matrix Blacksmith زودتر بتواند در صف قرار گیرد | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، shardهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types`، و `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، shardهای تست Linux Node، shardهای تست Plugin همراه، `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به‌اندازه‌ای حساس به CPU است که 8 vCPU بیش از صرفه‌جویی، هزینه ایجاد کرد)؛ ساخت‌های Docker مربوط به install-smoke (زمان صف 32-vCPU بیش از صرفه‌جویی، هزینه ایجاد کرد) | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `macos-node` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند | | `blacksmith-12vcpu-macos-latest` | `macos-swift` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند | @@ -135,9 +135,9 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md ``` -## عملکرد OpenClaw +## کارایی OpenClaw -`OpenClaw Performance` workflow عملکرد محصول/runtime است. این workflow هر روز روی `main` اجرا می‌شود و می‌توان آن را به‌صورت دستی dispatch کرد: +`OpenClaw Performance` گردش‌کار کارایی محصول/runtime است. روزانه روی `main` اجرا می‌شود و می‌توان آن را دستی dispatch کرد: ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -145,25 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -dispatch دستی معمولاً benchmark را روی workflow ref اجرا می‌کند. برای benchmark گرفتن از یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و pointerهای latest بر اساس ref آزموده‌شده کلیدگذاری می‌شوند و هر `index.md`، ref/SHA آزموده‌شده، workflow ref/SHA، Kova ref، profile، حالت احراز هویت lane، model، تعداد تکرار و فیلترهای سناریو را ثبت می‌کند. +dispatch دستی معمولاً workflow ref را benchmark می‌کند. برای benchmark کردن یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و اشاره‌گرهای latest بر اساس ref تست‌شده کلیدگذاری می‌شوند، و هر `index.md`، ref/SHA تست‌شده، workflow ref/SHA، Kova ref، profile، حالت احراز هویت lane، مدل، تعداد تکرار، و فیلترهای سناریو را ثبت می‌کند. -این workflow، OCM را از یک انتشار pinشده و Kova را از `openclaw/Kova` در ورودی pinشده `kova_ref` نصب می‌کند، سپس سه lane را اجرا می‌کند: +workflow، OCM را از یک انتشار pinned و Kova را از `openclaw/Kova` در ورودی pinned `kova_ref` نصب می‌کند، سپس سه lane را اجرا می‌کند: -- `mock-provider`: سناریوهای diagnostic Kova در برابر runtime با local-build و احراز هویت fake سازگار با OpenAI به‌صورت deterministic. -- `mock-deep-profile`: profiling CPU/heap/trace برای hotspotهای startup، Gateway و agent-turn. +- `mock-provider`: سناریوهای diagnostic Kova در برابر runtime ساخت محلی با احراز هویت fake سازگار با OpenAI و قطعی. +- `mock-deep-profile`: profiling مربوط به CPU/heap/trace برای hotspotهای startup، Gateway و agent-turn. - `live-gpt54`: یک agent turn واقعی OpenAI `openai/gpt-5.4`، که وقتی `OPENAI_API_KEY` در دسترس نباشد skip می‌شود. -lane مربوط به mock-provider پس از عبور Kova، probeهای source بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی boot و حافظه Gateway در حالت‌های startup پیش‌فرض، hook و 50-Plugin؛ loopهای تکراری hello برای mock-OpenAI `channel-chat-baseline`؛ و فرمان‌های startup CLI در برابر Gateway بوت‌شده. خلاصه Markdown مربوط به source probe در bundle گزارش در `source/index.md` قرار دارد و JSON خام کنار آن است. +lane مربوط به mock-provider پس از عبور Kova، probeهای منبع بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی راه‌اندازی Gateway و حافظه در حالت‌های startup پیش‌فرض، hook و 50-Plugin؛ loopهای hello تکراری mock-OpenAI `channel-chat-baseline`؛ و فرمان‌های startup مربوط به CLI در برابر Gateway راه‌اندازی‌شده. خلاصه Markdown مربوط به source probe در bundle گزارش در `source/index.md` قرار دارد و JSON خام کنار آن است. -هر lane artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md` و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance//-//` commit می‌کند. pointer فعلی ref آزموده‌شده به‌صورت `openclaw-performance//latest-.json` نوشته می‌شود. +هر lane artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance//-//` commit می‌کند. اشاره‌گر فعلی tested-ref به‌صورت `openclaw-performance//latest-.json` نوشته می‌شود. ## اعتبارسنجی کامل انتشار -`Full Release Validation` workflow دستی چتری برای «اجرای همه چیز پیش از انتشار» است. این workflow یک branch، tag یا commit SHA کامل را می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای اثبات فقط مخصوص انتشار در حوزه Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های Docker release-path، live/E2E، OpenWebUI، QA Lab parity، Matrix و laneهای Telegram dispatch می‌کند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان lane package مربوط به Telegram در برابر package منتشرشده npm دوباره اجرا شود. +`Full Release Validation` گردش‌کار چتری دستی برای «اجرای همه‌چیز پیش از انتشار» است. یک branch، tag، یا commit SHA کامل را می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای اثبات مخصوص انتشار مربوط به Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، پذیرش package، بررسی‌های package میان‌سیستمی، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. اجراهای stable/default پوشش جامع live/E2E و مسیر انتشار Docker را پشت `run_release_soak=true` نگه می‌دارند؛ `release_profile=full` آن پوشش soak را اجباری فعال می‌کند تا اعتبارسنجی advisory گسترده، همچنان گسترده بماند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، برای اجرای دوباره همان lane package Telegram در برابر package منتشرشده npm، `npm_telegram_package_spec` را ارسال کنید. -برای matrix مرحله، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. +برای matrix مرحله‌ها، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. -`OpenClaw Release Publish` workflow دستی mutating انتشار است. پس از اینکه tag انتشار وجود داشت و preflight مربوط به npm برای OpenClaw موفق شد، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای Plugin قابل انتشار dispatch می‌کند، `Plugin ClawHub Release` را برای همان release SHA dispatch می‌کند، و فقط بعد از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند. +`OpenClaw Release Publish` گردش‌کار دستی تغییردهنده انتشار است. پس از وجود داشتن tag انتشار و پس از موفقیت preflight مربوط به npm در OpenClaw، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای قابل انتشار Plugin dispatch می‌کند، `Plugin ClawHub Release` را برای همان release SHA dispatch می‌کند، و فقط پس از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند. ```bash gh workflow run openclaw-release-publish.yml \ @@ -173,35 +173,39 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -برای اثبات commit pinشده روی یک branch که سریع حرکت می‌کند، به‌جای `gh workflow run ... --ref main -f ref=` از helper استفاده کنید: +برای اثبات commit pinned روی یک branch سریع‌تغییر، به‌جای `gh workflow run ... --ref main -f ref=` از helper استفاده کنید: ```bash pnpm ci:full-release --sha ``` -dispatch refهای GitHub workflow باید branch یا tag باشند، نه commit SHA خام. helper یک branch موقت `release-ci/-...` را در target SHA push می‌کند، `Full Release Validation` را از همان ref pinشده dispatch می‌کند، verify می‌کند که `headSha` هر child workflow با target مطابقت داشته باشد، و پس از کامل شدن run، branch موقت را حذف می‌کند. verifier چتری همچنین اگر هر child workflow در SHA متفاوتی اجرا شده باشد fail می‌شود. +dispatch refهای workflow در GitHub باید branch یا tag باشند، نه commit SHA خام. helper یک branch موقت `release-ci/-...` را در target SHA push می‌کند، `Full Release Validation` را از آن ref pinned dispatch می‌کند، verify می‌کند که `headSha` هر workflow فرزند با target مطابق است، و پس از تکمیل run، branch موقت را حذف می‌کند. verifier چتری همچنین اگر هر workflow فرزند با SHA متفاوتی اجرا شده باشد fail می‌شود. -`release_profile` گستره live/ارائه‌دهنده‌ای را کنترل می‌کند که به بررسی‌های انتشار پاس داده می‌شود. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط زمانی از `full` استفاده کنید که عمداً ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را می‌خواهید. +`release_profile` گسترهٔ زنده/ارائه‌دهنده‌ای را کنترل می‌کند که به بررسی‌های انتشار داده می‌شود. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط وقتی از `full` استفاده کنید که عمداً ماتریس گستردهٔ ارائه‌دهنده/رسانهٔ advisory را می‌خواهید. `run_release_soak` کنترل می‌کند که آیا بررسی‌های انتشار پایدار/پیش‌فرض، soak کامل مسیر انتشار زنده/E2E و Docker را اجرا کنند یا نه؛ `full` اجرای soak را اجباری می‌کند. -- `minimum` سریع‌ترین مسیرهای OpenAI/هسته‌ای حیاتی برای انتشار را نگه می‌دارد. -- `stable` مجموعه پایدار ارائه‌دهنده/پس‌زمینه را اضافه می‌کند. -- `full` ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را اجرا می‌کند. +- `minimum` سریع‌ترین laneهای حیاتی انتشار OpenAI/هسته را نگه می‌دارد. +- `stable` مجموعهٔ پایدار ارائه‌دهنده/بک‌اند را اضافه می‌کند. +- `full` ماتریس گستردهٔ ارائه‌دهنده/رسانهٔ advisory را اجرا می‌کند. -چتر، شناسه‌های اجرای فرزند ارسال‌شده را ثبت می‌کند، و کار نهایی `Verify full validation` نتیجه‌های فعلی اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کار را برای هر اجرای فرزند پیوست می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شود و سبز شود، فقط کار راستی‌آزمای والد را دوباره اجرا کنید تا نتیجه چتر و خلاصه زمان‌بندی تازه شود. +umbrella شناسه‌های اجرای فرزند dispatchشده را ثبت می‌کند، و job نهایی `Verify full validation` نتیجه‌های فعلی اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین jobها را برای هر اجرای فرزند اضافه می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شود و سبز شود، فقط job تأییدکنندهٔ والد را دوباره اجرا کنید تا نتیجهٔ umbrella و خلاصهٔ زمان‌بندی تازه‌سازی شود. -برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` ورودی `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all`، فقط برای فرزند CI کامل عادی از `ci`، فقط برای فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر استفاده کنید: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی چتر. این کار اجرای دوباره یک جعبه انتشار ناموفق را پس از یک اصلاح متمرکز، محدود نگه می‌دارد. +برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` مقدار `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all` استفاده کنید، برای فقط فرزند CI کامل معمولی از `ci`، برای فقط فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا یک گروه محدودتر: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی umbrella. این کار rerun جعبهٔ انتشار شکست‌خورده را پس از یک اصلاح متمرکز محدود نگه می‌دارد. برای یک lane شکست‌خوردهٔ cross-OS، `rerun_group=cross-os` را با `cross_os_suite_filter` ترکیب کنید، برای مثال `windows/packaged-upgrade`؛ فرمان‌های طولانی cross-OS خط‌های Heartbeat منتشر می‌کنند و خلاصه‌های packaged-upgrade شامل زمان‌بندی هر فاز هستند. laneهای QA release-check advisory هستند، بنابراین شکست‌های فقط-QA هشدار می‌دهند اما تأییدکنندهٔ release-check را مسدود نمی‌کنند. -`OpenClaw Release Checks` از ref گردش‌کار مورداعتماد استفاده می‌کند تا ref انتخاب‌شده را یک‌بار به یک tarball به نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردش‌کار Docker مسیر انتشار live/E2E و هم به shard پذیرش بسته پاس می‌دهد. این کار بایت‌های بسته را در سراسر جعبه‌های انتشار ثابت نگه می‌دارد و از بسته‌بندی دوباره همان نامزد در چندین کار فرزند جلوگیری می‌کند. +`OpenClaw Release Checks` از ref گردش‌کار مورد اعتماد استفاده می‌کند تا ref انتخاب‌شده را یک‌بار به یک tarball با نام `release-package-under-test` resolve کند، سپس آن artifact را به بررسی‌های cross-OS و Package Acceptance می‌دهد، به‌علاوهٔ گردش‌کار Docker مسیر انتشار زنده/E2E وقتی پوشش soak اجرا می‌شود. این کار byteهای package را در همهٔ جعبه‌های انتشار یکسان نگه می‌دارد و از بسته‌بندی دوبارهٔ همان نامزد در چند job فرزند جلوگیری می‌کند. -اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all` چتر قدیمی‌تر را منسوخ می‌کنند. پایشگر والد هر گردش‌کار فرزندی را که قبلاً ارسال کرده باشد هنگام لغو والد لغو می‌کند، بنابراین اعتبارسنجی جدیدتر main پشت یک اجرای قدیمی دوساعته بررسی انتشار منتظر نمی‌ماند. اعتبارسنجی شاخه/برچسب انتشار و گروه‌های اجرای دوباره متمرکز، `cancel-in-progress: false` را حفظ می‌کنند. +اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all` +umbrella قدیمی‌تر را supersede می‌کنند. مانیتور والد هر گردش‌کار فرزندی را که +قبلاً dispatch کرده، وقتی والد لغو می‌شود لغو می‌کند؛ بنابراین اعتبارسنجی جدیدتر main +پشت یک اجرای stale دوساعتهٔ release-check نمی‌ماند. اعتبارسنجی branch/tag +انتشار و گروه‌های rerun متمرکز `cancel-in-progress: false` را نگه می‌دارند. -## shardهای live و E2E +## shardهای زنده و E2E -فرزند live/E2E انتشار پوشش گسترده بومی `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک کار سریالی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند: +فرزند زنده/E2E انتشار، پوشش گستردهٔ native `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک job سریالی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند: - `native-live-src-agents` - `native-live-src-gateway-core` -- کارهای `native-live-src-gateway-profiles` فیلترشده بر اساس ارائه‌دهنده +- jobهای `native-live-src-gateway-profiles` فیلترشده بر اساس ارائه‌دهنده - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -209,61 +213,63 @@ dispatch refهای GitHub workflow باید branch یا tag باشند، نه co - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- shardهای جداشده صوت/ویدئوی رسانه و shardهای موسیقی فیلترشده بر اساس ارائه‌دهنده +- shardهای جداشدهٔ رسانهٔ صوت/ویدئو و shardهای موسیقی فیلترشده بر اساس ارائه‌دهنده -این کار همان پوشش فایل را حفظ می‌کند، در حالی که اجرای دوباره و تشخیص خرابی‌های کند ارائه‌دهنده live را آسان‌تر می‌کند. نام‌های shard تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media` و `native-live-extensions-media-music` همچنان برای اجرای دوباره دستی یک‌مرحله‌ای معتبر می‌مانند. +این کار همان پوشش فایل را حفظ می‌کند و در عین حال rerun و عیب‌یابی شکست‌های کند ارائه‌دهندهٔ زنده را آسان‌تر می‌کند. نام‌های shard تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media`، و `native-live-extensions-media-music` همچنان برای rerunهای دستی یک‌باره معتبر می‌مانند. -shardهای رسانه live بومی در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن image، `ffmpeg` و `ffprobe` را از پیش نصب می‌کند؛ کارهای رسانه فقط پیش از راه‌اندازی دودویی‌ها را راستی‌آزمایی می‌کنند. مجموعه‌های live متکی بر Docker را روی runnerهای معمول Blacksmith نگه دارید — کارهای کانتینری جای درستی برای راه‌اندازی آزمون‌های Docker تو‌در‌تو نیستند. +shardهای رسانهٔ زندهٔ native در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند، که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن image از قبل `ffmpeg` و `ffprobe` را نصب می‌کند؛ jobهای رسانه فقط قبل از setup، binaryها را تأیید می‌کنند. suiteهای زندهٔ متکی به Docker را روی runnerهای عادی Blacksmith نگه دارید — jobهای container جای نامناسبی برای راه‌اندازی تست‌های Docker تو در تو هستند. -shardهای live مدل/پس‌زمینه متکی بر Docker برای هر commit انتخاب‌شده از یک image مشترک جداگانه `ghcr.io/openclaw/openclaw-live-test:` استفاده می‌کنند. گردش‌کار انتشار live آن image را یک‌بار می‌سازد و push می‌کند، سپس shardهای مدل live Docker، Gateway شاردشده بر اساس ارائه‌دهنده، پس‌زمینه CLI، اتصال ACP و harness Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. shardهای Docker مربوط به Gateway سقف‌های `timeout` صریح در سطح اسکریپت دارند که پایین‌تر از timeout کار گردش‌کار است، تا یک کانتینر گیرکرده یا مسیر پاک‌سازی، به‌جای مصرف کل بودجه بررسی انتشار، سریع شکست بخورد. اگر آن shardها target کامل Docker منبع را مستقل دوباره بسازند، اجرای انتشار بد پیکربندی شده است و زمان دیواری را روی ساخت‌های تکراری image هدر خواهد داد. +shardهای مدل/بک‌اند زندهٔ متکی به Docker از یک image مشترک جداگانهٔ `ghcr.io/openclaw/openclaw-live-test:` برای هر commit انتخاب‌شده استفاده می‌کنند. گردش‌کار انتشار زنده آن image را یک‌بار می‌سازد و push می‌کند، سپس shardهای مدل زندهٔ Docker، Gateway sharded بر اساس ارائه‌دهنده، بک‌اند CLI، bind ACP، و harness Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. shardهای Docker مربوط به Gateway سقف‌های `timeout` صریح در سطح script دارند که زیر timeout job گردش‌کار هستند، تا یک container گیرکرده یا مسیر cleanup به‌جای مصرف کل بودجهٔ release-check سریع شکست بخورد. اگر آن shardها target کامل Docker منبع را مستقل دوباره بسازند، اجرای انتشار بد پیکربندی شده و زمان wall clock را صرف buildهای تکراری image خواهد کرد. -## پذیرش بسته +## پذیرش package -از `Package Acceptance` وقتی استفاده کنید که پرسش این است: «آیا این بسته قابل نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» این با CI عادی متفاوت است: CI عادی درخت منبع را اعتبارسنجی می‌کند، در حالی که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E اعتبارسنجی می‌کند که کاربران پس از نصب یا به‌روزرسانی تجربه می‌کنند. +از `Package Acceptance` وقتی استفاده کنید که پرسش این است: «آیا این package قابل‌نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» این با CI معمولی متفاوت است: CI معمولی درخت منبع را اعتبارسنجی می‌کند، در حالی که package acceptance یک tarball واحد را از طریق همان harness Docker E2E که کاربران پس از نصب یا به‌روزرسانی اجرا می‌کنند اعتبارسنجی می‌کند. -### کارها +### Jobها -1. `resolve_package`، `workflow_ref` را checkout می‌کند، یک نامزد بسته را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact به نام `package-under-test` بارگذاری می‌کند، و منبع، ref گردش‌کار، ref بسته، نسخه، SHA-256 و profile را در خلاصه گام GitHub چاپ می‌کند. -2. `docker_acceptance`، `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار قابل استفاده مجدد آن artifact را دانلود می‌کند، موجودی tarball را اعتبارسنجی می‌کند، در صورت نیاز imageهای Docker با digest بسته را آماده می‌کند، و مسیرهای انتخاب‌شده Docker را به‌جای بسته‌بندی checkout گردش‌کار، علیه همان بسته اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب می‌کند، گردش‌کار قابل استفاده مجدد بسته و imageهای مشترک را یک‌بار آماده می‌کند، سپس آن مسیرها را به‌صورت کارهای Docker هدفمند موازی با artifactهای یکتا پخش می‌کند. -3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. این کار وقتی اجرا می‌شود که `telegram_mode` برابر `none` نباشد و همان artifact به نام `package-under-test` را زمانی نصب می‌کند که پذیرش بسته یکی را resolve کرده باشد؛ ارسال مستقل Telegram همچنان می‌تواند یک مشخصه منتشرشده npm را نصب کند. -4. `summary` اگر resolve بسته، پذیرش Docker، یا مسیر اختیاری Telegram شکست خورده باشد، گردش‌کار را ناموفق می‌کند. +1. `resolve_package` مقدار `workflow_ref` را checkout می‌کند، یک نامزد package را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact با نام `package-under-test` upload می‌کند، و source، workflow ref، package ref، version، SHA-256، و profile را در خلاصهٔ step گیت‌هاب چاپ می‌کند. +2. `docker_acceptance` فایل `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار reusable آن artifact را download می‌کند، inventory tarball را اعتبارسنجی می‌کند، در صورت نیاز imageهای Docker با digest package را آماده می‌کند، و laneهای Docker انتخاب‌شده را به‌جای بسته‌بندی checkout گردش‌کار، علیه همان package اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب کند، گردش‌کار reusable package و imageهای مشترک را یک‌بار آماده می‌کند، سپس آن laneها را به jobهای Docker هدفمند موازی با artifactهای یکتا fan out می‌کند. +3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. وقتی `telegram_mode` مقدار `none` نباشد اجرا می‌شود و وقتی Package Acceptance یکی را resolve کرده باشد همان artifact با نام `package-under-test` را نصب می‌کند؛ dispatch مستقل Telegram همچنان می‌تواند یک spec منتشرشدهٔ npm را نصب کند. +4. `summary` اگر resolution package، Docker acceptance، یا lane اختیاری Telegram شکست خورده باشد، گردش‌کار را fail می‌کند. -### منابع نامزد +### منبع‌های نامزد -- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این برای پذیرش پیش‌انتشار/پایدار منتشرشده استفاده کنید. -- `source=ref` یک شاخه، برچسب، یا SHA کامل commit مورداعتماد `package_ref` را بسته‌بندی می‌کند. resolver شاخه‌ها/برچسب‌های OpenClaw را fetch می‌کند، راستی‌آزمایی می‌کند که commit انتخاب‌شده از تاریخچه شاخه مخزن یا یک برچسب انتشار قابل دسترسی باشد، وابستگی‌ها را در یک worktree جداشده نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند. -- `source=url` یک `.tgz` از HTTPS دانلود می‌کند؛ `package_sha256` الزامی است. -- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود می‌کند؛ `package_sha256` اختیاری است، اما برای artifactهای اشتراک‌گذاری‌شده خارجی باید ارائه شود. +- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخهٔ دقیق انتشار OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این گزینه برای پذیرش prerelease/stable منتشرشده استفاده کنید. +- `source=ref` یک branch، tag، یا SHA کامل commit مورد اعتماد `package_ref` را بسته‌بندی می‌کند. resolver branchها/tagهای OpenClaw را fetch می‌کند، تأیید می‌کند commit انتخاب‌شده از تاریخچهٔ branch مخزن یا یک tag انتشار قابل‌دسترسی است، dependencyها را در یک worktree detached نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند. +- `source=url` یک `.tgz` از HTTPS download می‌کند؛ `package_sha256` الزامی است. +- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` download می‌کند؛ `package_sha256` اختیاری است اما برای artifactهای به‌اشتراک‌گذاشته‌شدهٔ خارجی باید ارائه شود. -`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد مورداعتماد گردش‌کار/harness است که آزمون را اجرا می‌کند. `package_ref` commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این اجازه می‌دهد harness آزمون فعلی، commitهای منبع مورداعتماد قدیمی‌تر را بدون اجرای منطق گردش‌کار قدیمی اعتبارسنجی کند. +`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد گردش‌کار/harness مورد اعتمادی است که تست را اجرا می‌کند. `package_ref` commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این باعث می‌شود harness تست فعلی بتواند commitهای منبع مورد اعتماد قدیمی‌تر را بدون اجرای منطق قدیمی گردش‌کار اعتبارسنجی کند. -### profileهای مجموعه +### profileهای suite -- `smoke` — `npm-onboard-channel-agent`، `gateway-network`، `config-reload` -- `package` — `npm-onboard-channel-agent`، `doctor-switch`، `update-channel-switch`، `upgrade-survivor`، `published-upgrade-survivor`، `plugins-offline`، `plugin-update` -- `product` — `package` به‌علاوه `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui` -- `full` — chunkهای کامل Docker مسیر انتشار همراه با OpenWebUI -- `custom` — `docker_lanes` دقیق؛ وقتی `suite_profile=custom` باشد الزامی است +- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload` +- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update` +- `product` — `package` به‌علاوهٔ `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` +- `full` — chunkهای کامل Docker مسیر انتشار با OpenWebUI +- `custom` — مقدار دقیق `docker_lanes`؛ وقتی `suite_profile=custom` باشد الزامی است -profile به نام `package` از پوشش آفلاین Plugin استفاده می‌کند تا اعتبارسنجی بسته منتشرشده وابسته به دسترس‌پذیری live ClawHub نباشد. مسیر اختیاری Telegram در `NPM Telegram Beta E2E` از artifact به نام `package-under-test` دوباره استفاده می‌کند، در حالی که مسیر مشخصه npm منتشرشده برای ارسال‌های مستقل نگه داشته می‌شود. +profile با نام `package` از پوشش Plugin آفلاین استفاده می‌کند تا اعتبارسنجی package منتشرشده به دسترس‌بودن زندهٔ ClawHub وابسته نباشد. lane اختیاری Telegram از artifact با نام `package-under-test` در `NPM Telegram Beta E2E` دوباره استفاده می‌کند، و مسیر spec منتشرشدهٔ npm برای dispatchهای مستقل حفظ می‌شود. -برای سیاست اختصاصی آزمون به‌روزرسانی و Plugin، شامل فرمان‌های محلی، مسیرهای Docker، ورودی‌های پذیرش بسته، پیش‌فرض‌های انتشار، و تریاژ خرابی، [Testing updates and plugins](/fa/help/testing-updates-plugins) را ببینید. +برای سیاست اختصاصی تست به‌روزرسانی و Plugin، شامل فرمان‌های محلی، +laneهای Docker، ورودی‌های Package Acceptance، پیش‌فرض‌های انتشار، و triage شکست، +[تست به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) را ببینید. -بررسی‌های انتشار، پذیرش بسته را با `source=artifact`، artifact بسته انتشار آماده‌شده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues` و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار اثبات مهاجرت بسته، به‌روزرسانی، پاک‌سازی وابستگی Plugin کهنه، تعمیر نصب Plugin پیکربندی‌شده، Plugin آفلاین، به‌روزرسانی Plugin و Telegram را روی همان tarball بسته resolveشده نگه می‌دارد. برای اجرای همان ماتریس علیه یک بسته npm ارسال‌شده به‌جای artifact ساخته‌شده از SHA، `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسی‌های انتشار چندسیستمی همچنان onboarding، نصب‌کننده، و رفتار پلتفرمی خاص OS را پوشش می‌دهند؛ اعتبارسنجی محصول بسته/به‌روزرسانی باید از پذیرش بسته شروع شود. مسیر Docker به نام `published-upgrade-survivor` در هر اجرا یک baseline بسته منتشرشده را اعتبارسنجی می‌کند. در پذیرش بسته، tarball resolveشده `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline`، baseline منتشرشده fallback را انتخاب می‌کند که پیش‌فرض آن `openclaw@latest` است؛ فرمان‌های اجرای دوباره مسیر ناموفق آن baseline را حفظ می‌کنند. برای گسترش CI انتشار کامل روی هر انتشار پایدار npm از `2026.4.23` تا `latest`، `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` برای نمونه‌برداری دستی گسترده‌تر با لنگر پیشاتاریخ قدیمی‌تر همچنان در دسترس است. برای گسترش همان baselineها در fixtureهای مشابه issue برای پیکربندی Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های Plugin پیکربندی‌شده OpenClaw، مسیرهای log با tilde، و ریشه‌های وابستگی Plugin قدیمی و کهنه، `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردش‌کار جداگانه `Update Migration` وقتی پرسش، پاک‌سازی جامع به‌روزرسانی منتشرشده است و نه گستره عادی CI انتشار کامل، از مسیر Docker به نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده می‌کند. اجراهای تجمیعی محلی می‌توانند مشخصه‌های دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` پاس دهند، یک مسیر واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس سناریو تنظیم کنند. مسیر منتشرشده baseline را با یک دستور پخته‌شده `openclaw config set` پیکربندی می‌کند، گام‌های دستور را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz` و وضعیت RPC را probe می‌کند. مسیرهای تازه بسته‌بندی‌شده و نصب‌کننده Windows همچنین راستی‌آزمایی می‌کنند که یک بسته نصب‌شده بتواند override کنترل مرورگر را از یک مسیر مطلق خام Windows import کند. smoke چرخش agent چندسیستمی OpenAI وقتی `OPENCLAW_CROSS_OS_OPENAI_MODEL` تنظیم شده باشد به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی یک مدل آزمون GPT-5 بماند و از پیش‌فرض‌های GPT-4.x پرهیز شود. +بررسی‌های انتشار Package Acceptance را با `source=artifact`، artifact آماده‌شدهٔ package انتشار، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار proof مربوط به migration package، به‌روزرسانی، cleanup وابستگی Plugin stale، تعمیر نصب Plugin پیکربندی‌شده، Plugin آفلاین، plugin-update، و Telegram را روی همان tarball package resolveشده نگه می‌دارد. `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید تا همان matrix را به‌جای artifact ساخته‌شده از SHA، علیه یک package npm منتشرشده اجرا کند. بررسی‌های انتشار cross-OS همچنان onboarding، installer، و رفتار platform مختص OS را پوشش می‌دهند؛ اعتبارسنجی محصول package/update باید با Package Acceptance شروع شود. lane Docker با نام `published-upgrade-survivor` در مسیر انتشار blocking، در هر run یک baseline package منتشرشده را اعتبارسنجی می‌کند. در Package Acceptance، tarball resolveشدهٔ `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشدهٔ fallback را انتخاب می‌کند، با مقدار پیش‌فرض `openclaw@latest`؛ فرمان‌های rerun مربوط به lane شکست‌خورده آن baseline را حفظ می‌کنند. Full Release Validation با `run_release_soak=true` یا `release_profile=full` مقادیر `published_upgrade_survivor_baselines=all-since-2026.4.23` و `published_upgrade_survivor_scenarios=reported-issues` را تنظیم می‌کند تا در همهٔ انتشارهای پایدار npm از `2026.4.23` تا `latest` و fixtureهای شبیه issue برای config مربوط به Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های Plugin پیکربندی‌شدهٔ OpenClaw، مسیرهای log با tilde، و ریشه‌های dependency قدیمی stale Plugin گسترش یابد. گردش‌کار جداگانهٔ `Update Migration` وقتی استفاده می‌شود که پرسش cleanup کامل به‌روزرسانی منتشرشده باشد، نه گسترهٔ معمول Full Release CI؛ این گردش‌کار lane Docker با نام `update-migration` را با `all-since-2026.4.23` و `plugin-deps-cleanup` به کار می‌گیرد. runهای aggregate محلی می‌توانند specهای دقیق package را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` بدهند، با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` یک lane واحد را نگه دارند، مانند `openclaw@2026.4.15`، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای matrix سناریو تنظیم کنند. lane منتشرشده baseline را با یک دستورالعمل command پخته‌شدهٔ `openclaw config set` پیکربندی می‌کند، گام‌های دستورالعمل را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz`، به‌علاوهٔ وضعیت RPC را probe می‌کند. laneهای نصب تازهٔ Windows packaged و installer همچنین تأیید می‌کنند که یک package نصب‌شده می‌تواند override کنترل browser را از یک مسیر raw مطلق Windows import کند. smoke مربوط به agent-turn در OpenAI cross-OS وقتی `OPENCLAW_CROSS_OS_OPENAI_MODEL` تنظیم شده باشد به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا proof نصب و Gateway روی یک مدل تست GPT-5 بماند و از پیش‌فرض‌های GPT-4.x پرهیز شود. ### پنجره‌های سازگاری legacy -پذیرش بسته پنجره‌های سازگاری legacy محدود برای بسته‌هایی دارد که از قبل منتشر شده‌اند. بسته‌ها تا `2026.4.25`، شامل `2026.4.25-beta.*`، ممکن است از مسیر سازگاری استفاده کنند: +Package Acceptance برای packageهای از قبل منتشرشده پنجره‌های سازگاری legacy محدود دارد. packageها تا `2026.4.25`، شامل `2026.4.25-beta.*`، می‌توانند از مسیر سازگاری استفاده کنند: -- ورودی‌های خصوصی شناخته‌شده QA در `dist/postinstall-inventory.json` ممکن است به فایل‌های حذف‌شده از tarball اشاره کنند؛ -- `doctor-switch` ممکن است زیرمورد ماندگاری `gateway install --wrapper` را وقتی بسته آن flag را expose نمی‌کند رد کند؛ -- `update-channel-switch` ممکن است `pnpm.patchedDependencies` گمشده را از fixture جعلی git مشتق‌شده از tarball هرس کند و ممکن است `update.channel` ماندگار گمشده را log کند؛ -- smokeهای Plugin ممکن است مکان‌های legacy رکورد نصب را بخوانند یا نبود ماندگاری رکورد نصب marketplace را بپذیرند؛ -- `plugin-update` ممکن است مهاجرت metadata پیکربندی را مجاز بداند، در حالی که همچنان الزام می‌کند رکورد نصب و رفتار عدم نصب مجدد بدون تغییر بمانند. +- entryهای خصوصی QA شناخته‌شده در `dist/postinstall-inventory.json` ممکن است به فایل‌هایی اشاره کنند که از tarball حذف شده‌اند؛ +- وقتی package آن flag را expose نکند، `doctor-switch` ممکن است زیرمورد پایداری `gateway install --wrapper` را skip کند؛ +- `update-channel-switch` ممکن است `pnpm.patchedDependencies`های گمشده را از fixture جعلی git مشتق‌شده از tarball prune کند و ممکن است `update.channel` persistشدهٔ گمشده را log کند؛ +- smokeهای Plugin ممکن است مکان‌های legacy install-record را بخوانند یا persistence گمشدهٔ marketplace install-record را بپذیرند؛ +- `plugin-update` ممکن است migration metadata config را مجاز کند، در حالی که همچنان الزام دارد install record و رفتار no-reinstall بدون تغییر بمانند. -بسته منتشرشده `2026.4.26` نیز ممکن است برای فایل‌های stamp metadata ساخت محلی که از قبل ارسال شده بودند هشدار دهد. بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا رد شدن، شکست می‌خورند. +package منتشرشدهٔ `2026.4.26` نیز ممکن است برای فایل‌های stamp مربوط به metadata build محلی که قبلاً منتشر شده‌اند هشدار دهد. packageهای بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا skip، fail می‌شوند. -### نمونه‌ها +### مثال‌ها ```bash # Validate the current beta package with product-level coverage. @@ -304,110 +310,110 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -هنگام اشکال‌زدایی اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکت‌های Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، لاگ‌های lane، زمان‌بندی فازها و فرمان‌های اجرای دوباره. اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا laneهای دقیق Docker را به اجرای دوباره‌ی اعتبارسنجی کامل انتشار ترجیح دهید. +هنگام اشکال‌زدایی یک اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکت‌های Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، لاگ‌های مسیر، زمان‌بندی فازها و فرمان‌های اجرای دوباره. به‌جای اجرای دوباره‌ی اعتبارسنجی کامل انتشار، اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا مسیرهای دقیق Docker را ترجیح دهید. ## دودآزمایی نصب -Workflow جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق job مخصوص خود به نام `preflight` دوباره استفاده می‌کند. این workflow پوشش دودآزمایی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند. +Workflow جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق job خودش با نام `preflight` دوباره استفاده می‌کند. این Workflow پوشش دودآزمایی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند. -- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/manifest مربوط به Pluginهای همراه، یا سطح‌های Plugin/کانال/Gateway/Plugin SDK هسته را که jobهای دودآزمایی Docker اجرا می‌کنند، لمس کرده باشند. تغییرات فقط‌منبع در Pluginهای همراه، ویرایش‌های فقط‌تست، و ویرایش‌های فقط‌مستندات workerهای Docker را رزرو نمی‌کنند. مسیر سریع تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، دودآزمایی CLI حذف agentهای workspace مشترک را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک build arg برای extension همراه را تأیید می‌کند، و پروفایل Docker محدودِ Plugin همراه را با timeout تجمعی ۲۴۰ ثانیه‌ای برای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود). -- **مسیر کامل** پوشش نصب بسته‌ی QR و Docker/update مربوط به نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار با workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر دودآزمایی GHCR از Dockerfile ریشه برای target-SHA آماده می‌کند یا دوباره استفاده می‌کند، سپس نصب بسته‌ی QR، دودآزمایی‌های Dockerfile/Gateway ریشه، دودآزمایی‌های نصب‌کننده/update، و Docker E2E سریعِ Plugin همراه را به‌عنوان jobهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت دودآزمایی‌های تصویر ریشه منتظر نماند. +- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/مانیفست Pluginهای همراه، یا سطح‌های Plugin/کانال/Gateway/Plugin SDK هسته را لمس می‌کنند که jobهای دودآزمایی Docker آن‌ها را تمرین می‌دهند. تغییرات فقط-منبع در Pluginهای همراه، ویرایش‌های فقط-تست، و ویرایش‌های فقط-مستندات workerهای Docker را رزرو نمی‌کنند. مسیر سریع تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، دودآزمایی CLI حذف agentها از فضای‌کار مشترک را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک آرگومان build برای extension همراه را تأیید می‌کند، و پروفایل Docker محدودشده‌ی Plugin همراه را تحت timeout تجمیعی ۲۴۰ ثانیه‌ای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود). +- **مسیر کامل** نصب بسته‌ی QR و پوشش Docker/update نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار با workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر دودآزمایی Dockerfile ریشه‌ی GHCR با target-SHA آماده یا دوباره استفاده می‌کند، سپس نصب بسته‌ی QR، دودآزمایی‌های Dockerfile/Gateway ریشه، دودآزمایی‌های نصب‌کننده/update، و E2E سریع Docker برای Plugin همراه را به‌عنوان jobهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت دودآزمایی‌های تصویر ریشه منتظر نماند. -pushهای `main` (از جمله merge commitها) مسیر کامل را اجباری نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push پوشش کامل را درخواست کند، workflow دودآزمایی سریع Docker را نگه می‌دارد و دودآزمایی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند. +pushهای `main` (از جمله commitهای merge) مسیر کامل را اجباری نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push درخواست پوشش کامل کند، Workflow دودآزمایی سریع Docker را نگه می‌دارد و دودآزمایی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند. -دودآزمایی کندِ ارائه‌دهنده‌ی تصویر با نصب global در Bun به‌طور جداگانه با `run_bun_global_install_smoke` کنترل می‌شود. این دودآزمایی در زمان‌بندی شبانه و از workflow بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` این کار را نمی‌کنند. تست‌های Docker مربوط به QR و نصب‌کننده Dockerfileهای نصب‌محور خودشان را نگه می‌دارند. +دودآزمایی کند نصب سراسری Bun برای image-provider جداگانه با `run_bun_global_install_smoke` کنترل می‌شود. این دودآزمایی در زمان‌بندی شبانه و از Workflow بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` آن را اجرا نمی‌کنند. تست‌های Docker مربوط به QR و نصب‌کننده Dockerfileهای نصب‌محور خودشان را نگه می‌دارند. -## Docker E2E محلی +## E2E محلی Docker -`pnpm test:docker:all` یک تصویر live-test مشترک را از قبل می‌سازد، OpenClaw را یک‌بار به‌صورت tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` را می‌سازد: +`pnpm test:docker:all` یک تصویر live-test مشترک را از پیش می‌سازد، OpenClaw را یک‌بار به‌عنوان tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` می‌سازد: -- یک runner خام Node/Git برای laneهای نصب‌کننده/update/وابستگی Plugin؛ -- یک تصویر کاربردی که همان tarball را برای laneهای عملکرد عادی در `/app` نصب می‌کند. +- یک اجراکننده‌ی ساده‌ی Node/Git برای مسیرهای نصب‌کننده/update/وابستگی-Plugin؛ +- یک تصویر کاربردی که همان tarball را برای مسیرهای عملکردی عادی در `/app` نصب می‌کند. -تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و runner فقط طرح انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر هر lane را با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند. +تعریف‌های مسیر Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و اجراکننده فقط برنامه‌ی انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر هر مسیر را با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس مسیرها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند. ### تنظیم‌پذیرها -| متغیر | پیش‌فرض | هدف | +| متغیر | پیش‌فرض | هدف | | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای pool اصلی برای laneهای عادی. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای pool انتهایی حساس به provider. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live هم‌زمان تا providerها throttle نکنند. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | سقف laneهای نصب npm هم‌زمان. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی هم‌زمان. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌ی زمانی بین شروع laneها برای جلوگیری از هجوم create در daemon Docker؛ برای نبود فاصله `0` بگذارید. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | timeout پشتیبان برای هر lane (۱۲۰ دقیقه)؛ laneهای live/tail انتخاب‌شده سقف‌های سخت‌گیرانه‌تری دارند. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` طرح زمان‌بند را بدون اجرای laneها چاپ می‌کند. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکننده‌ی کاما؛ دودآزمایی پاک‌سازی را رد می‌کند تا agentها بتوانند یک lane ناموفق را بازتولید کنند. | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد اسلات‌های pool اصلی برای مسیرهای عادی. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد اسلات‌های pool انتهایی حساس به provider. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف مسیرهای live هم‌زمان تا providerها throttle نکنند. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | سقف مسیرهای نصب npm هم‌زمان. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف مسیرهای چندسرویسی هم‌زمان. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌گذاری بین شروع مسیرها برای جلوگیری از طوفان create در daemon Docker؛ برای حذف فاصله `0` بگذارید. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | timeout پشتیبان هر مسیر (۱۲۰ دقیقه)؛ مسیرهای live/tail انتخاب‌شده سقف‌های سخت‌گیرانه‌تری دارند. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` برنامه‌ی زمان‌بند را بدون اجرای مسیرها چاپ می‌کند. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق مسیرها با جداکننده‌ی کاما؛ دودآزمایی پاک‌سازی را رد می‌کند تا agentها بتوانند یک مسیر ناموفق را بازتولید کنند. | -laneای که از سقف مؤثر خود سنگین‌تر است همچنان می‌تواند از یک pool خالی شروع شود، سپس تا زمانی که ظرفیت را آزاد کند به‌تنهایی اجرا می‌شود. preflight تجمعی محلی Docker را بررسی می‌کند، کانتینرهای کهنه‌ی OpenClaw E2E را حذف می‌کند، وضعیت laneهای فعال را منتشر می‌کند، زمان‌بندی laneها را برای مرتب‌سازی طولانی‌ترین‌ها در ابتدا نگه می‌دارد، و به‌طور پیش‌فرض پس از نخستین شکست، زمان‌بندی laneهای pooled جدید را متوقف می‌کند. +مسیری که از سقف مؤثر خودش سنگین‌تر است همچنان می‌تواند از یک pool خالی شروع شود، سپس به‌تنهایی اجرا می‌شود تا ظرفیت را آزاد کند. preflightهای تجمیعی محلی Docker را بررسی می‌کنند، کانتینرهای stale مربوط به E2E OpenClaw را حذف می‌کنند، وضعیت مسیر فعال را منتشر می‌کنند، زمان‌بندی مسیرها را برای ترتیب‌دهی طولانی‌ترین-اول ذخیره می‌کنند، و به‌طور پیش‌فرض پس از نخستین شکست زمان‌بندی مسیرهای pooled جدید را متوقف می‌کنند. ### Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E -Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E از `scripts/test-docker-all.mjs --plan-json` می‌پرسد کدام بسته، نوع تصویر، تصویر live، lane و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن طرح را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این workflow یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا آرتیفکت بسته‌ی اجرای فعلی را دانلود می‌کند، یا یک آرتیفکت بسته را از `package_artifact_run_id` دانلود می‌کند؛ inventory tarball را اعتبارسنجی می‌کند؛ وقتی طرح به laneهای package-installed نیاز داشته باشد، تصاویر Docker E2E خام/کاربردی GHCR با tag مبتنی بر digest بسته را از طریق cache لایه‌ی Docker در Blacksmith می‌سازد و push می‌کند؛ و به‌جای ساخت دوباره، از ورودی‌های ارائه‌شده‌ی `docker_e2e_bare_image`/`docker_e2e_functional_image` یا تصاویر موجود مبتنی بر digest بسته دوباره استفاده می‌کند. pullهای تصویر Docker با timeout محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا جریان گیرکرده‌ی registry/cache به‌جای مصرف بخش بزرگی از مسیر بحرانی CI، سریع دوباره امتحان شود. +Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E از `scripts/test-docker-all.mjs --plan-json` می‌پرسد کدام بسته، نوع تصویر، تصویر live، مسیر، و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن برنامه را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این Workflow یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا آرتیفکت بسته‌ی current-run را دانلود می‌کند، یا آرتیفکت بسته را از `package_artifact_run_id` دانلود می‌کند؛ inventory مربوط به tarball را اعتبارسنجی می‌کند؛ وقتی برنامه به مسیرهای نصب‌شده-از-بسته نیاز دارد، تصویرهای bare/functional مربوط به GHCR Docker E2E با tag شامل digest بسته را از طریق cache لایه‌ی Docker مربوط به Blacksmith می‌سازد و push می‌کند؛ و به‌جای بازسازی، ورودی‌های `docker_e2e_bare_image`/`docker_e2e_functional_image` فراهم‌شده یا تصویرهای موجود با digest بسته را دوباره استفاده می‌کند. pullهای تصویر Docker با timeout محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا stream گیرکرده‌ی registry/cache به‌جای مصرف بخش بزرگی از مسیر بحرانی CI، سریع دوباره تلاش شود. ### تکه‌های مسیر انتشار -پوشش Docker انتشار jobهای تکه‌تکه‌ی کوچک‌تری را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویر موردنیاز خود را pull کند و چندین lane را از طریق همان زمان‌بند وزن‌دار اجرا کند: +پوشش Docker انتشار jobهای تکه‌ای کوچک‌تر را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویری را pull کند که لازم دارد و چند مسیر را از طریق همان زمان‌بند وزن‌دار اجرا کند: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime` و `plugins-integrations` همچنان aliasهای تجمعی Plugin/runtime هستند. alias مربوط به lane به نام `install-e2e` همچنان alias تجمعی اجرای دوباره‌ی دستی برای هر دو lane نصب‌کننده‌ی provider است. +تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime`، و `plugins-integrations` همچنان aliasهای تجمیعی Plugin/runtime می‌مانند. alias مسیر `install-e2e` همچنان alias تجمیعی اجرای دوباره‌ی دستی برای هر دو مسیر نصب‌کننده‌ی provider است. -وقتی پوشش کامل release-path آن را درخواست کند، OpenWebUI در `plugins-runtime-services` ادغام می‌شود، و فقط برای dispatchهای مختص OpenWebUI، یک تکه‌ی مستقل `openwebui` را نگه می‌دارد. laneهای update کانال‌های همراه برای شکست‌های گذرای شبکه‌ی npm یک‌بار دوباره تلاش می‌کنند. +وقتی پوشش کامل release-path آن را درخواست کند، OpenWebUI در `plugins-runtime-services` ادغام می‌شود، و فقط برای dispatchهای مختص OpenWebUI یک تکه‌ی مستقل `openwebui` نگه می‌دارد. مسیرهای update کانال همراه برای شکست‌های گذرای شبکه‌ی npm یک‌بار دوباره تلاش می‌کنند. -هر تکه `.artifacts/docker-tests/` را همراه با لاگ‌های lane، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON طرح زمان‌بند، جدول‌های laneهای کند، و فرمان‌های اجرای دوباره برای هر lane آپلود می‌کند. ورودی `docker_lanes` در workflow به‌جای jobهای تکه‌ای، laneهای انتخاب‌شده را روی تصاویر آماده‌شده اجرا می‌کند؛ این کار اشکال‌زدایی lane ناموفق را به یک job هدفمند Docker محدود نگه می‌دارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود یا دوباره استفاده می‌کند؛ اگر lane انتخاب‌شده یک lane زنده‌ی Docker باشد، job هدفمند تصویر live-test را برای آن اجرای دوباره به‌صورت محلی می‌سازد. فرمان‌های اجرای دوباره‌ی GitHub تولیدشده برای هر lane، وقتی آن مقادیر وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name` و ورودی‌های تصویر آماده هستند، تا یک lane ناموفق بتواند از همان بسته و تصاویر دقیق اجرای ناموفق دوباره استفاده کند. +هر تکه `.artifacts/docker-tests/` را با لاگ‌های مسیر، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON برنامه‌ی زمان‌بند، جدول‌های مسیرهای کند، و فرمان‌های اجرای دوباره برای هر مسیر upload می‌کند. ورودی `docker_lanes` در Workflow مسیرهای انتخاب‌شده را به‌جای jobهای تکه‌ای روی تصویرهای آماده‌شده اجرا می‌کند، که اشکال‌زدایی مسیر ناموفق را به یک job هدفمند Docker محدود نگه می‌دارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود، یا دوباره استفاده می‌کند؛ اگر یک مسیر انتخاب‌شده مسیر live Docker باشد، job هدفمند تصویر live-test را به‌صورت محلی برای آن اجرای دوباره می‌سازد. فرمان‌های GitHub تولیدشده برای اجرای دوباره‌ی هر مسیر، وقتی این مقدارها وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name`، و ورودی‌های تصویر آماده‌شده هستند، تا یک مسیر ناموفق بتواند دقیقاً همان بسته و تصویرهای اجرای ناموفق را دوباره استفاده کند. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -Workflow زمان‌بندی‌شده‌ی live/E2E مجموعه‌ی کامل Docker مربوط به release-path را روزانه اجرا می‌کند. +Workflow زمان‌بندی‌شده‌ی live/E2E مجموعه‌ی کامل Docker مربوط به release-path را هر روز اجرا می‌کند. ## پیش‌انتشار Plugin -`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین workflow جداگانه‌ای است که توسط `Full Release Validation` یا یک operator صریح dispatch می‌شود. pull requestهای عادی، pushهای `main` و dispatchهای دستی مستقل CI این مجموعه را خاموش نگه می‌دارند. این workflow تست‌های Plugin همراه را میان هشت worker مربوط به extension متعادل می‌کند؛ آن jobهای shard مربوط به extension تا دو گروه config Plugin را هم‌زمان با یک worker از Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا batchهای Plugin با import سنگین jobهای CI اضافی ایجاد نکنند. مسیر prerelease مخصوص انتشار در Docker، laneهای هدفمند Docker را در گروه‌های کوچک batch می‌کند تا برای jobهای یک تا سه دقیقه‌ای ده‌ها runner رزرو نشود. +`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین یک Workflow جداگانه است که توسط `Full Release Validation` یا یک operator صریح dispatch می‌شود. pull requestهای عادی، pushهای `main`، و dispatchهای دستی مستقل CI آن مجموعه را خاموش نگه می‌دارند. این Workflow تست‌های Plugin همراه را بین هشت worker extension متوازن می‌کند؛ آن jobهای shard مربوط به extension هر بار تا دو گروه پیکربندی Plugin را با یک worker Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا batchهای Plugin سنگین از نظر import، jobهای CI اضافی ایجاد نکنند. مسیر پیش‌انتشار Docker فقط-انتشار، مسیرهای Docker هدفمند را در گروه‌های کوچک batch می‌کند تا برای jobهای یک تا سه دقیقه‌ای ده‌ها runner رزرو نشود. ## آزمایشگاه QA -آزمایشگاه QA laneهای CI اختصاصی بیرون از workflow اصلی با دامنه‌ی هوشمند دارد. برابری agentic زیر harnessهای گسترده‌ی QA و انتشار قرار دارد، نه یک workflow مستقل PR. وقتی برابری باید همراه یک اجرای اعتبارسنجی گسترده باشد، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید. +QA Lab مسیرهای CI اختصاصی بیرون از Workflow اصلی با دامنه‌ی هوشمند دارد. برابری agentic زیر harnessهای گسترده‌ی QA و انتشار قرار گرفته است، نه به‌عنوان یک Workflow مستقل PR. وقتی برابری باید همراه یک اجرای اعتبارسنجی گسترده بیاید، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید. -- Workflow `QA-Lab - All Lanes` هر شب روی `main` و هنگام dispatch دستی اجرا می‌شود؛ این workflow lane برابری mock، lane زنده‌ی Matrix، و laneهای زنده‌ی Telegram و Discord را به‌صورت jobهای موازی fan out می‌کند. jobهای live از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند. +- Workflow `QA-Lab - All Lanes` هر شب روی `main` و در dispatch دستی اجرا می‌شود؛ این Workflow مسیر mock parity، مسیر live Matrix، و مسیرهای live Telegram و Discord را به‌صورت jobهای موازی پخش می‌کند. jobهای live از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند. -بررسی‌های انتشار، laneهای transport زنده‌ی Matrix و Telegram را با provider mock قطعی و مدل‌های دارای صلاحیت mock (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد کانال از latency مدل live و راه‌اندازی عادی provider-plugin جدا شود. Gateway مربوط به transport زنده، جست‌وجوی memory را غیرفعال می‌کند، زیرا برابری QA رفتار memory را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل live، provider بومی، و provider Docker پوشش داده می‌شود. +بررسی‌های انتشار مسیرهای live transport مربوط به Matrix و Telegram را با provider mock قطعی و مدل‌های واجد mock (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد کانال از latency مدل live و startup عادی provider-plugin جدا بماند. Gateway مربوط به live transport جست‌وجوی حافظه را غیرفعال می‌کند چون QA parity رفتار حافظه را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل live، provider بومی، و provider Docker پوشش داده می‌شود. -Matrix برای gateهای زمان‌بندی‌شده و انتشار از `--profile fast` استفاده می‌کند و فقط وقتی CLI checkoutشده از آن پشتیبانی کند، `--fail-fast` را اضافه می‌کند. پیش‌فرض CLI و ورودی workflow دستی همچنان `all` است؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep` و `e2ee-cli` shard می‌کند. +Matrix برای gateهای زمان‌بندی‌شده و انتشار از `--profile fast` استفاده می‌کند و فقط وقتی CLI checkout‌شده از آن پشتیبانی کند، `--fail-fast` را اضافه می‌کند. مقدار پیش‌فرض CLI و ورودی Workflow دستی همچنان `all` می‌ماند؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep`، و `e2ee-cli` shard می‌کند. -`OpenClaw Release Checks` همچنین laneهای حیاتی انتشارِ آزمایشگاه QA را پیش از تأیید انتشار اجرا می‌کند؛ gate برابری QA آن، بسته‌های candidate و baseline را به‌صورت jobهای lane موازی اجرا می‌کند، سپس هر دو آرتیفکت را در یک job گزارش کوچک برای مقایسه‌ی نهایی برابری دانلود می‌کند. +`OpenClaw Release Checks` همچنین مسیرهای QA Lab حیاتی برای انتشار را پیش از تأیید انتشار اجرا می‌کند؛ gate برابری QA آن بسته‌های candidate و baseline را به‌عنوان jobهای مسیر موازی اجرا می‌کند، سپس هر دو آرتیفکت را در یک job گزارش کوچک دانلود می‌کند تا مقایسه‌ی نهایی برابری انجام شود. -برای PRهای عادی، به‌جای اینکه برابری را یک status الزامی بدانید، از شواهد CI/check دامنه‌دار پیروی کنید. +برای PRهای عادی، به‌جای در نظر گرفتن برابری به‌عنوان یک وضعیت ضروری، شواهد scoped CI/check را دنبال کنید. ## CodeQL -گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی باریک برای گذر اول است، نه پایش کامل مخزن. اجراهای روزانه، دستی، و محافظ pull requestهای غیرپیش‌نویس، کد گردش‌کار Actions به‌علاوه پرریسک‌ترین سطوح JavaScript/TypeScript را با queryهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی فیلتر شده‌اند اسکن می‌کنند. +گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی اولیه و محدود است، نه جاروب کامل مخزن. اجراهای روزانه، دستی، و محافظ pull requestهای غیرپیش‌نویس، کد گردش‌کار Actions به‌علاوه پرریسک‌ترین سطوح JavaScript/TypeScript را با پرس‌وجوهای امنیتی با اطمینان بالا که بر اساس `security-severity` بالا/بحرانی فیلتر شده‌اند، اسکن می‌کنند. -محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود، و همان ماتریس امنیتی با اطمینان بالا را مثل گردش‌کار زمان‌بندی‌شده اجرا می‌کند. Android و macOS CodeQL خارج از پیش‌فرض‌های PR می‌مانند. +محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود، و همان ماتریس امنیتی با اطمینان بالا را که گردش‌کار زمان‌بندی‌شده اجرا می‌کند، اجرا می‌کند. Android و macOS CodeQL در پیش‌فرض‌های PR وارد نمی‌شوند. ### دسته‌های امنیتی -| دسته | سطح | +| دسته | سطح | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، Cron، و خط مبنای Gateway | -| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته به‌همراه runtime مربوط به channel plugin، Gateway، Plugin SDK، secrets، و نقاط تماس audit | -| `/codeql-security-high/network-ssrf-boundary` | سطوح SSRF هسته، تجزیه IP، نگهبان شبکه، web-fetch، و سیاست SSRF در Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، helperهای اجرای فرایند، تحویل خروجی، و gateهای اجرای ابزار agent | -| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، بارگذاری منبع، و قرارداد package در Plugin SDK | +| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، cron، و خط پایه gateway | +| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال اصلی به‌علاوه runtime کانال Plugin، gateway، Plugin SDK، secrets، و نقاط تماس audit | +| `/codeql-security-high/network-ssrf-boundary` | سطوح SSRF اصلی، پردازش IP، محافظ شبکه، web-fetch، و سیاست SSRF در Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، کمک‌گیرنده‌های اجرای پردازه، تحویل خروجی، و گیت‌های اجرای ابزار agent | +| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، source-loading، و قرارداد package در Plugin SDK | -### shardهای امنیتی مختص پلتفرم +### شاردهای امنیتی ویژه پلتفرم -- `CodeQL Android Critical Security` — shard امنیتی زمان‌بندی‌شده Android. برنامه Android را برای CodeQL روی کوچک‌ترین runner لینوکسی Blacksmith که sanity گردش‌کار می‌پذیرد به‌صورت دستی build می‌کند. خروجی را زیر `/codeql-critical-security/android` بارگذاری می‌کند. -- `CodeQL macOS Critical Security` — shard امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL روی Blacksmith macOS به‌صورت دستی build می‌کند، نتایج build وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و خروجی را زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده، چون build macOS حتی در حالت تمیز هم بر زمان اجرا غالب است. +- `CodeQL Android Critical Security` — شارد زمان‌بندی‌شده امنیتی Android. برنامه Android را برای CodeQL به‌صورت دستی روی کوچک‌ترین runner لینوکس Blacksmith که workflow sanity می‌پذیرد، می‌سازد. خروجی را زیر `/codeql-critical-security/android` بارگذاری می‌کند. +- `CodeQL macOS Critical Security` — شارد امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL به‌صورت دستی روی Blacksmith macOS می‌سازد، نتایج build وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده است چون build macOS حتی در حالت پاک هم runtime را غالب می‌کند. ### دسته‌های کیفیت بحرانی -`CodeQL Critical Quality` shard غیرامنیتی متناظر است. فقط queryهای کیفیت JavaScript/TypeScript غیرامنیتی با شدت خطا را روی سطوح باریک و باارزش بالا، روی runner لینوکسی کوچک‌تر Blacksmith اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از پروفایل زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط shardهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای کد اجرای فرمان/مدل/ابزار agent و dispatch پاسخ، schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، هسته کانال و runtime مربوط به channel plugin بسته‌بندی‌شده، پروتکل Gateway/server-method، چسب runtime/SDK حافظه، MCP/process/تحویل خروجی، runtime/provider catalog مدل، diagnostics جلسه/صف‌های تحویل، loader Plugin، قرارداد Plugin SDK/package، یا تغییرات runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات CodeQL config و گردش‌کار کیفیت هر دوازده shard کیفیت PR را اجرا می‌کنند. +`CodeQL Critical Quality` شارد غیرامنیتی متناظر است. فقط پرس‌وجوهای کیفیت JavaScript/TypeScript غیرامنیتی با severity خطا را روی سطوح محدود و باارزش بالا روی runner کوچک‌تر لینوکس Blacksmith اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از نمایه زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط شاردهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای تغییرات کد اجرای فرمان/مدل/ابزار agent و ارسال پاسخ، کد schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، runtime کانال اصلی و کانال Plugin همراه، protocol/server-method در gateway، glue مربوط به memory runtime/SDK، MCP/process/outbound delivery، runtime/provider model catalog، diagnostics/delivery queues نشست، loader مربوط به Plugin، قرارداد Plugin SDK/package، یا runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات پیکربندی CodeQL و گردش‌کار کیفیت، هر دوازده شارد کیفیت PR را اجرا می‌کنند. dispatch دستی می‌پذیرد: @@ -415,40 +421,40 @@ dispatch دستی می‌پذیرد: profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -پروفایل‌های باریک hookهای آموزش/تکرار برای اجرای یک shard کیفیت به‌صورت جداگانه هستند. +نمایه‌های محدود، قلاب‌های آموزش/تکرار برای اجرای یک شارد کیفیت به‌صورت جداگانه هستند. | دسته | سطح | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، Cron، و Gateway | -| `/codeql-critical-quality/config-boundary` | قراردادهای schema پیکربندی، migration، نرمال‌سازی، و IO | +| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، cron، و gateway | +| `/codeql-critical-quality/config-boundary` | قراردادهای schema، migration، normalization، و IO پیکربندی | | `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای پروتکل Gateway و قراردادهای server method | -| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته و channel pluginهای بسته‌بندی‌شده | -| `/codeql-critical-quality/agent-runtime-boundary` | اجرای فرمان، dispatch مدل/provider، dispatch و صف‌های auto-reply، و قراردادهای runtime صفحه کنترل ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، helperهای نظارت بر فرایند، و قراردادهای تحویل خروجی | -| `/codeql-critical-quality/memory-runtime-boundary` | SDK میزبان حافظه، facadeهای runtime حافظه، aliasهای Plugin SDK حافظه، چسب فعال‌سازی runtime حافظه، و فرمان‌های doctor حافظه | -| `/codeql-critical-quality/session-diagnostics-boundary` | بخش‌های داخلی صف پاسخ، صف‌های تحویل جلسه، helperهای اتصال/تحویل جلسه خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، helperهای payload/chunking/runtime پاسخ، گزینه‌های پاسخ کانال، صف‌های تحویل، و helperهای اتصال session/thread | -| `/codeql-critical-quality/provider-runtime-boundary` | نرمال‌سازی catalog مدل، auth و discovery provider، ثبت runtime provider، پیش‌فرض‌ها/catalogهای provider، و registryهای web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | راه‌اندازی Control UI، persistence محلی، جریان‌های کنترل Gateway، و قراردادهای runtime صفحه کنترل task | -| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب هسته، media IO، درک رسانه، تولید تصویر، و تولید رسانه | -| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع Plugin SDK سمت package منتشرشده و helperهای قرارداد package مربوط به plugin | +| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال اصلی و کانال Plugin همراه | +| `/codeql-critical-quality/agent-runtime-boundary` | اجرای فرمان، dispatch مدل/provider، dispatch و queueهای پاسخ خودکار، و قراردادهای runtime کنترل‌پلین ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، کمک‌گیرنده‌های نظارت پردازه، و قراردادهای تحویل خروجی | +| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK، facadeهای memory runtime، aliasهای memory Plugin SDK، glue فعال‌سازی memory runtime، و فرمان‌های memory doctor | +| `/codeql-critical-quality/session-diagnostics-boundary` | اجزای داخلی reply queue، queueهای تحویل نشست، کمک‌گیرنده‌های اتصال/تحویل نشست خروجی، سطوح diagnostic event/log bundle، و قراردادهای session doctor CLI | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، payload/chunking/runtime helperهای پاسخ، گزینه‌های پاسخ کانال، queueهای تحویل، و کمک‌گیرنده‌های اتصال session/thread | +| `/codeql-critical-quality/provider-runtime-boundary` | normalization کاتالوگ مدل، auth و discovery مربوط به provider، ثبت runtime مربوط به provider، defaults/catalogs مربوط به provider، و registryهای web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | bootstrap کنترل UI، ماندگاری محلی، جریان‌های کنترل Gateway، و قراردادهای runtime کنترل‌پلین task | +| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب اصلی، media IO، media understanding، image-generation، و media-generation | +| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypoint در Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع Plugin SDK سمت package منتشرشده و کمک‌گیرنده‌های قرارداد package مربوط به Plugin | -کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون پنهان‌کردن سیگنال امنیتی زمان‌بندی، اندازه‌گیری، غیرفعال، یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و pluginهای بسته‌بندی‌شده باید فقط پس از پایدار شدن runtime و سیگنال پروفایل‌های باریک، به‌صورت کار پیگیری scopeشده یا shardشده دوباره اضافه شود. +کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون پنهان‌کردن سیگنال امنیتی، زمان‌بندی، اندازه‌گیری، غیرفعال، یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و Plugin همراه باید فقط پس از پایدار شدن runtime و سیگنال نمایه‌های محدود، به‌عنوان کار پیگیری scoped یا sharded دوباره اضافه شود. -## گردش‌کارهای نگهداری +## گردش‌کارهای نگهداشت -### عامل مستندات +### Docs Agent -گردش‌کار `Docs Agent` یک مسیر نگهداری event-driven با Codex برای هم‌راستا نگه‌داشتن مستندات موجود با تغییراتی است که اخیراً landing شده‌اند. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. invocationهای workflow-run وقتی `main` جلو رفته باشد یا وقتی اجرای غیر skipشده دیگری از Docs Agent در ساعت گذشته ایجاد شده باشد skip می‌شوند. وقتی اجرا می‌شود، بازه commit از source SHA مربوط به Docs Agent غیر skipشده قبلی تا `main` فعلی را review می‌کند، بنابراین یک اجرای ساعتی می‌تواند همه تغییرات main انباشته‌شده از آخرین گذر مستندات را پوشش دهد. +گردش‌کار `Docs Agent` یک مسیر نگهداشت Codex مبتنی بر رویداد برای هم‌راستا نگه‌داشتن مستندات موجود با تغییرات تازه land شده است. زمان‌بندی خالص ندارد: اجرای موفق CI برای push غیرربات روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. فراخوانی‌های workflow-run وقتی `main` جلو رفته باشد یا وقتی یک اجرای غیر skipped دیگر از Docs Agent در ساعت گذشته ساخته شده باشد، skip می‌شوند. وقتی اجرا می‌شود، بازه commit از SHA منبع قبلی Docs Agent غیر skipped تا `main` فعلی را بازبینی می‌کند، بنابراین یک اجرای ساعتی می‌تواند همه تغییرات main انباشته‌شده از آخرین گذر مستندات را پوشش دهد. -### عامل عملکرد تست +### Test Performance Agent -گردش‌کار `Test Performance Agent` یک مسیر نگهداری event-driven با Codex برای تست‌های کند است. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، اما اگر invocation دیگری از workflow-run در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی آن gate فعالیت روزانه را دور می‌زند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شده برای کل suite می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست با حفظ پوشش انجام دهد نه refactorهای گسترده، سپس گزارش کل suite را دوباره اجرا می‌کند و تغییراتی را که تعداد baseline تست‌های موفق را کاهش دهند رد می‌کند. اگر baseline تست‌های ناموفق داشته باشد، Codex فقط می‌تواند failureهای بدیهی را اصلاح کند و گزارش کل suite پس از agent باید پیش از هر commit موفق شود. وقتی `main` پیش از landing شدن push ربات جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای stale دارای conflict skip می‌شوند. از GitHub-hosted Ubuntu استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل عامل مستندات حفظ کند. +گردش‌کار `Test Performance Agent` یک مسیر نگهداشت Codex مبتنی بر رویداد برای تست‌های کند است. زمان‌بندی خالص ندارد: اجرای موفق CI برای push غیرربات روی `main` می‌تواند آن را trigger کند، اما اگر فراخوانی workflow-run دیگری در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی از این گیت فعالیت روزانه عبور می‌کند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شده برای کل suite می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست با حفظ پوشش انجام دهد نه refactorهای گسترده، سپس گزارش کل suite را دوباره اجرا می‌کند و تغییراتی را که تعداد baseline تست‌های پاس‌شده را کاهش دهند رد می‌کند. اگر baseline تست‌های failing داشته باشد، Codex فقط می‌تواند شکست‌های واضح را اصلاح کند و گزارش کل suite پس از agent باید پیش از commit شدن هر چیزی پاس شود. وقتی `main` پیش از land شدن push ربات جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای قدیمی دارای conflict skip می‌شوند. از Ubuntu میزبانی‌شده توسط GitHub استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل docs agent حفظ کند. -### PRهای تکراری پس از ادغام +### PRهای تکراری پس از merge -گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی duplicate پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر دادن GitHub، تأیید می‌کند که PR landشده merge شده و هر duplicate یا issue ارجاع‌شده مشترک دارد یا hunkهای تغییر یافته هم‌پوشان دارد. +گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی تکراری‌ها پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر GitHub، تأیید می‌کند که PR land شده merge شده است و هر مورد تکراری یا issue ارجاعی مشترک دارد یا hunkهای تغییر یافته هم‌پوشان دارد. ```bash gh workflow run duplicate-after-merge.yml \ @@ -457,39 +463,39 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## gateهای check محلی و مسیریابی تغییرات +## گیت‌های بررسی محلی و routing تغییرات -منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن gate check محلی نسبت به scope گسترده پلتفرم CI درباره مرزهای معماری سخت‌گیرتر است: +منطق local changed-lane در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن گیت بررسی محلی نسبت به scope گسترده پلتفرم CI درباره مرزهای معماری سخت‌گیرتر است: -- تغییرات production هسته، typecheck مربوط به core prod و core test به‌علاوه lint/guardهای هسته را اجرا می‌کنند؛ -- تغییرات فقط-test هسته، فقط typecheck مربوط به core test به‌علاوه lint هسته را اجرا می‌کنند؛ -- تغییرات production extension، typecheck مربوط به extension prod و extension test به‌علاوه lint extension را اجرا می‌کنند؛ -- تغییرات فقط-test extension، typecheck مربوط به extension test به‌علاوه lint extension را اجرا می‌کنند؛ -- تغییرات Plugin SDK عمومی یا قرارداد plugin به typecheck extension گسترش می‌یابند، چون extensionها به آن قراردادهای هسته وابسته‌اند (پایش‌های Vitest extension همچنان کار تست صریح می‌مانند)؛ -- افزایش نسخه‌های فقط metadata انتشار، checkهای هدفمند version/config/root-dependency را اجرا می‌کنند؛ -- تغییرات ناشناخته root/config برای fail-safe به همه check laneها می‌روند. +- تغییرات production در core، typecheck مربوط به core prod و core test به‌علاوه lint/guardهای core را اجرا می‌کنند؛ +- تغییرات فقط تست در core، فقط typecheck مربوط به core test به‌علاوه lint core را اجرا می‌کنند؛ +- تغییرات production در extension، typecheck مربوط به extension prod و extension test به‌علاوه lint extension را اجرا می‌کنند؛ +- تغییرات فقط تست در extension، typecheck مربوط به extension test به‌علاوه lint extension را اجرا می‌کنند؛ +- تغییرات عمومی Plugin SDK یا plugin-contract به typecheck مربوط به extension گسترش پیدا می‌کنند چون extensionها به آن قراردادهای core وابسته‌اند (جاروب‌های Vitest برای extension همچنان کار تست صریح می‌مانند)؛ +- version bumpهای فقط metadata مربوط به release، بررسی‌های هدفمند version/config/root-dependency را اجرا می‌کنند؛ +- تغییرات ناشناخته root/config برای fail safe به همه check laneها می‌روند. -مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش مستقیم تست‌ها خودشان را اجرا می‌کنند، ویرایش‌های source ابتدا mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و وابستگان import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی visible-reply گروه، حالت تحویل پاسخ source، یا system prompt ابزار پیام، از طریق تست‌های پاسخ هسته به‌علاوه regressionهای تحویل Discord و Slack مسیر داده می‌شوند تا تغییر پیش‌فرض مشترک پیش از اولین push PR شکست بخورد. فقط وقتی از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید که تغییر آن‌قدر harness-wide باشد که مجموعه mapped ارزان نماینده قابل اعتمادی نباشد. +routing محلی changed-test در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش‌های مستقیم تست خودشان را اجرا می‌کنند، ویرایش‌های source mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و dependentهای import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی پاسخ visible برای گروه، حالت تحویل پاسخ source، یا prompt سیستمی message-tool از مسیر تست‌های پاسخ core به‌علاوه regressionهای تحویل Discord و Slack عبور می‌کنند تا تغییر پیش‌فرض shared پیش از اولین push به PR شکست بخورد. فقط وقتی تغییر آن‌قدر در سطح harness گسترده است که مجموعه mapped ارزان proxy قابل اعتمادی نیست، از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. ## اعتبارسنجی Testbox -Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات‌های گسترده، یک جعبهٔ تازه گرم‌شده را ترجیح دهید. پیش از صرف‌کردن یک گیت کند روی جعبه‌ای که دوباره استفاده شده، منقضی شده، یا همین حالا همگام‌سازیِ غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل جعبه اجرا کنید. +Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات گسترده، یک box تازه گرم‌شده را ترجیح دهید. پیش از صرف کردن یک gate کند روی boxای که دوباره استفاده شده، منقضی شده، یا همین حالا یک همگام‌سازی غیرمنتظره بزرگ گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل همان box اجرا کنید. -بررسی سلامت وقتی فایل‌های ضروری ریشه مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ ردیابی‌شده نشان دهد، سریع شکست می‌خورد. این معمولاً یعنی وضعیت همگام‌سازی راه‌دور، کپی قابل اعتمادی از PR نیست؛ به‌جای اشکال‌زدایی شکست آزمون محصول، آن جعبه را متوقف کنید و یک جعبهٔ تازه گرم کنید. برای PRهای بزرگ‌حذفِ عمدی، برای همان اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید. +بررسی سلامت وقتی فایل‌های ضروری ریشه مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ رهگیری‌شده نشان دهد، سریع شکست می‌خورد. این معمولا یعنی وضعیت همگام‌سازی remote یک کپی قابل اعتماد از PR نیست؛ به‌جای اشکال‌زدایی شکست تست محصول، آن box را متوقف کنید و یک box تازه گرم کنید. برای PRهایی که عمدا حذف‌های بزرگ دارند، برای آن اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید. -`pnpm testbox:run` همچنین فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در مرحلهٔ همگام‌سازی می‌ماند، پایان می‌دهد. برای غیرفعال‌کردن آن محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمولاً بزرگ، مقدار میلی‌ثانیه‌ای بزرگ‌تری به کار ببرید. +`pnpm testbox:run` همچنین اجرای محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در فاز sync می‌ماند، خاتمه می‌دهد. برای غیرفعال کردن این guard مقدار `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمول بزرگ از مقدار میلی‌ثانیه‌ای بزرگ‌تر استفاده کنید. -Crabbox پوشش جعبهٔ راه‌دورِ متعلق به مخزن برای اثبات لینوکس نگه‌دارندگان است. وقتی یک بررسی برای حلقهٔ ویرایش محلی بیش از حد گسترده است، وقتی هم‌ارزی CI مهم است، یا وقتی اثبات به secrets، Docker، مسیرهای بسته، جعبه‌های قابل استفادهٔ مجدد، یا گزارش‌های راه‌دور نیاز دارد، از آن استفاده کنید. backend عادی OpenClaw برابر `blacksmith-testbox` است؛ ظرفیت AWS/Hetzner تحت مالکیت، پشتیبانِ قطعی‌های Blacksmith، مشکلات سهمیه، یا آزمون صریح ظرفیت تحت مالکیت است. +Crabbox پوشش remote-box متعلق به مخزن برای اثبات Linux نگه‌دارندگان است. وقتی یک بررسی برای local edit loop بیش از حد گسترده است، وقتی هم‌ارزی با CI مهم است، یا وقتی اثبات به رازها، Docker، laneهای بسته، boxهای قابل استفاده‌مجدد، یا لاگ‌های remote نیاز دارد، از آن استفاده کنید. backend معمول OpenClaw برابر `blacksmith-testbox` است؛ ظرفیت AWS/Hetzner متعلق به پروژه fallbackای برای قطعی‌های Blacksmith، مشکلات سهمیه، یا تست صریح ظرفیت متعلق به پروژه است. -پیش از نخستین اجرا، پوشش را از ریشهٔ مخزن بررسی کنید: +پیش از اولین اجرا، wrapper را از ریشهٔ مخزن بررسی کنید: ```bash pnpm crabbox:run -- --help | sed -n '1,120p' ``` -پوشش مخزن، دودویی Crabbox کهنه‌ای را که `blacksmith-testbox` را اعلام نمی‌کند رد می‌کند. با اینکه `.crabbox.yaml` پیش‌فرض‌های ابرِ تحت مالکیت دارد، ارائه‌دهنده را صریحاً پاس دهید. +wrapper مخزن یک باینری Crabbox کهنه را که `blacksmith-testbox` را advertise نمی‌کند رد می‌کند. provider را صریح پاس بدهید، حتی با اینکه `.crabbox.yaml` پیش‌فرض‌های owned-cloud دارد. -گیت تغییرات: +gate تغییرات: ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -504,7 +510,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" ``` -اجرای دوبارهٔ آزمون متمرکز: +اجرای دوبارهٔ تست متمرکز: ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -534,21 +540,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` -خلاصهٔ نهایی JSON را بخوانید. فیلدهای مفید `provider`، `leaseId`، `syncDelegated`، `exitCode`، `commandMs` و `totalMs` هستند. اجراهای یک‌بارهٔ Crabbox با پشتوانهٔ Blacksmith باید Testbox را به‌طور خودکار متوقف کنند؛ اگر اجرا قطع شد یا پاک‌سازی نامشخص بود، جعبه‌های زنده را بررسی کنید و فقط جعبه‌هایی را که خودتان ساخته‌اید متوقف کنید: +خلاصهٔ JSON نهایی را بخوانید. فیلدهای مفید عبارت‌اند از `provider`، `leaseId`، `syncDelegated`، `exitCode`، `commandMs`، و `totalMs`. اجرای یک‌مرحله‌ای Crabbox مبتنی بر Blacksmith باید Testbox را به‌صورت خودکار متوقف کند؛ اگر اجرا قطع شد یا پاک‌سازی نامشخص بود، boxهای زنده را بررسی کنید و فقط boxهایی را که خودتان ساخته‌اید متوقف کنید: ```bash blacksmith testbox list blacksmith testbox stop --id ``` -فقط وقتی استفادهٔ مجدد را به کار ببرید که عمداً به چند فرمان روی همان جعبهٔ آماده‌شده نیاز دارید: +فقط وقتی از استفادهٔ دوباره استفاده کنید که عمدا به چند فرمان روی همان box آماده‌شده نیاز دارید: ```bash pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " pnpm crabbox:stop -- ``` -اگر لایهٔ خراب Crabbox است اما خود Blacksmith کار می‌کند، از Blacksmith مستقیم به‌عنوان پشتیبان محدود استفاده کنید: +اگر Crabbox لایهٔ خراب است اما خود Blacksmith کار می‌کند، از Blacksmith مستقیم به‌عنوان fallback محدود استفاده کنید: ```bash blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 @@ -556,7 +562,7 @@ blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --id ``` -فقط وقتی به ظرفیت Crabbox تحت مالکیت ارتقا دهید که Blacksmith از کار افتاده، با محدودیت سهمیه روبه‌رو است، محیط لازم را ندارد، یا ظرفیت تحت مالکیت صراحتاً هدف است: +فقط وقتی به ظرفیت Crabbox متعلق به پروژه escalate کنید که Blacksmith قطع است، با محدودیت سهمیه روبه‌روست، محیط لازم را ندارد، یا ظرفیت متعلق به پروژه صراحتا هدف است: ```bash pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m @@ -565,7 +571,7 @@ pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.crabbox.yaml` مالک پیش‌فرض‌های ارائه‌دهنده، همگام‌سازی، و آماده‌سازی GitHub Actions برای مسیرهای ابرِ تحت مالکیت است. این فایل `.git` محلی را مستثنی می‌کند تا checkout آماده‌شدهٔ Actions فرادادهٔ Git راه‌دور خودش را نگه دارد، نه اینکه remoteهای محلی نگه‌دارنده و انباره‌های object را همگام کند؛ همچنین artifactهای runtime/build محلی را که هرگز نباید منتقل شوند مستثنی می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانه برای فرمان‌های ابرِ تحت مالکیت `crabbox run --id ` است. +`.crabbox.yaml` مالک پیش‌فرض‌های provider، sync، و hydration در GitHub Actions برای laneهای owned-cloud است. این فایل `.git` محلی را مستثنا می‌کند تا checkout آماده‌شدهٔ Actions به‌جای همگام‌سازی remoteها و object storeهای محلی نگه‌دارنده، metadata ریموت Git خودش را نگه دارد، و artifactهای runtime/build محلی را که هرگز نباید منتقل شوند مستثنا می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، fetch کردن `origin/main`، و تحویل محیط غیرمحرمانه برای فرمان‌های owned-cloud `crabbox run --id ` است. ## مرتبط diff --git a/docs/fa/cli/dashboard.md b/docs/fa/cli/dashboard.md index 050fad7bf..59855db00 100644 --- a/docs/fa/cli/dashboard.md +++ b/docs/fa/cli/dashboard.md @@ -5,10 +5,10 @@ read_when: summary: مرجع CLI برای `openclaw dashboard` (باز کردن رابط کاربری کنترل) title: داشبورد x-i18n: - generated_at: "2026-04-29T22:34:44Z" + generated_at: "2026-05-05T01:44:18Z" model: gpt-5.5 provider: openai - source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c + source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f source_path: cli/dashboard.md workflow: 16 --- @@ -22,12 +22,17 @@ openclaw dashboard openclaw dashboard --no-open ``` -نکته‌ها: +یادداشت‌ها: -- `dashboard` در صورت امکان SecretRefs پیکربندی‌شده‌ی `gateway.auth.token` را resolve می‌کند. -- `dashboard` از `gateway.tls.enabled` پیروی می‌کند: Gatewayهایی که TLS در آن‌ها فعال است، URLهای رابط کاربری کنترل را با `https://` چاپ/باز می‌کنند و از طریق `wss://` متصل می‌شوند. -- برای توکن‌های مدیریت‌شده با SecretRef (resolve‌شده یا resolve‌نشده)، `dashboard` یک URL بدون توکن را چاپ/کپی/باز می‌کند تا از افشای اسرار خارجی در خروجی ترمینال، تاریخچه‌ی کلیپ‌بورد، یا آرگومان‌های راه‌اندازی مرورگر جلوگیری شود. -- اگر `gateway.auth.token` با SecretRef مدیریت می‌شود اما در این مسیر فرمان resolve نشده باشد، فرمان به‌جای جای‌دادن یک جای‌نگهدار نامعتبر توکن، یک URL بدون توکن و راهنمایی اصلاحی صریح چاپ می‌کند. +- `dashboard` در صورت امکان SecretRefهای پیکربندی‌شده‌ی `gateway.auth.token` را resolve می‌کند. +- `dashboard` از `gateway.tls.enabled` پیروی می‌کند: Gatewayهای دارای TLS فعال، URLهای رابط کاربری کنترل را با + `https://` چاپ/باز می‌کنند و از طریق `wss://` متصل می‌شوند. +- اگر تحویل از طریق کلیپ‌بورد/مرورگر برای URL داشبوردِ احراز هویت‌شده با توکن ناموفق باشد، + `dashboard` یک راهنمای امن برای احراز هویت دستی ثبت می‌کند که از `OPENCLAW_GATEWAY_TOKEN`، + `gateway.auth.token`، و کلید fragment یعنی `token` نام می‌برد، بدون آنکه مقدار توکن را + چاپ کند. +- برای توکن‌های مدیریت‌شده با SecretRef (resolve‌شده یا resolveنشده)، `dashboard` یک URL بدون توکن را چاپ/کپی/باز می‌کند تا از افشای اسرار خارجی در خروجی ترمینال، تاریخچه کلیپ‌بورد، یا آرگومان‌های اجرای مرورگر جلوگیری شود. +- اگر `gateway.auth.token` با SecretRef مدیریت می‌شود اما در این مسیر فرمان resolve نشده باشد، فرمان به‌جای جاسازی یک placeholder نامعتبر برای توکن، یک URL بدون توکن و راهنمای اصلاح صریح چاپ می‌کند. ## مرتبط diff --git a/docs/fa/cli/doctor.md b/docs/fa/cli/doctor.md index 150a5d2c9..48f6c2cc5 100644 --- a/docs/fa/cli/doctor.md +++ b/docs/fa/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - مشکلات اتصال/احراز هویت دارید و رفع‌های راهنمایی‌شده می‌خواهید - - به‌روزرسانی کرده‌اید و یک بررسی اولیهٔ صحت می‌خواهید + - مشکلات اتصال/احراز هویت دارید و راهکارهای هدایت‌شده می‌خواهید + - به‌روزرسانی کرده‌اید و یک بررسی سریع می‌خواهید summary: مرجع CLI برای `openclaw doctor` (بررسی‌های سلامت + تعمیرات هدایت‌شده) title: عیب‌یاب x-i18n: - generated_at: "2026-05-04T02:22:49Z" + generated_at: "2026-05-05T01:44:19Z" model: gpt-5.5 provider: openai - source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905 + source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5 source_path: cli/doctor.md workflow: 16 --- @@ -22,7 +22,7 @@ x-i18n: - عیب‌یابی: [عیب‌یابی](/fa/gateway/troubleshooting) - ممیزی امنیتی: [امنیت](/fa/gateway/security) -## مثال‌ها +## نمونه‌ها ```bash openclaw doctor @@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token ## گزینه‌ها -- `--no-workspace-suggestions`: پیشنهادهای حافظه/جست‌وجوی فضای کاری را غیرفعال می‌کند -- `--yes`: پذیرش پیش‌فرض‌ها بدون نمایش درخواست -- `--repair`: اصلاحات پیشنهادی غیرسرویسی را بدون نمایش درخواست اعمال می‌کند؛ نصب‌ها و بازنویسی‌های سرویس Gateway همچنان به تأیید تعاملی یا فرمان‌های صریح Gateway نیاز دارند +- `--no-workspace-suggestions`: پیشنهادهای حافظه/جست‌وجوی workspace را غیرفعال می‌کند +- `--yes`: پیش‌فرض‌ها را بدون درخواست تأیید می‌پذیرد +- `--repair`: تعمیرهای پیشنهادی غیرسرویسی را بدون درخواست تأیید اعمال می‌کند؛ نصب‌ها و بازنویسی‌های سرویس Gateway همچنان به تأیید تعاملی یا فرمان‌های صریح Gateway نیاز دارند - `--fix`: نام مستعار برای `--repair` -- `--force`: اصلاحات تهاجمی را اعمال می‌کند، از جمله بازنویسی پیکربندی سفارشی سرویس در صورت نیاز -- `--non-interactive`: بدون درخواست اجرا می‌کند؛ فقط مهاجرت‌های ایمن و اصلاحات غیرسرویسی +- `--force`: تعمیرهای تهاجمی را اعمال می‌کند، از جمله بازنویسی پیکربندی سفارشی سرویس در صورت نیاز +- `--non-interactive`: بدون prompt اجرا می‌شود؛ فقط مهاجرت‌های ایمن و تعمیرهای غیرسرویسی - `--generate-gateway-token`: یک توکن Gateway تولید و پیکربندی می‌کند - `--deep`: سرویس‌های سیستم را برای نصب‌های اضافی Gateway اسکن می‌کند -نکته‌ها: +نکات: -- درخواست‌های تعاملی (مانند اصلاحات keychain/OAuth) فقط زمانی اجرا می‌شوند که stdin یک TTY باشد و `--non-interactive` تنظیم **نشده** باشد. اجراهای بدون واسط (cron، Telegram، بدون ترمینال) درخواست‌ها را رد می‌کنند. -- کارایی: اجراهای غیرتعاملی `doctor` بارگذاری مشتاقانه Plugin را رد می‌کنند تا بررسی‌های سلامت بدون واسط سریع بمانند. نشست‌های تعاملی همچنان وقتی یک بررسی به مشارکت Pluginها نیاز داشته باشد، Pluginها را کامل بارگذاری می‌کنند. -- `--fix` (نام مستعار برای `--repair`) یک نسخه پشتیبان در `~/.openclaw/openclaw.json.bak` می‌نویسد و کلیدهای پیکربندی ناشناخته را حذف می‌کند و هر حذف را فهرست می‌کند. -- `doctor --fix --non-interactive` تعریف‌های سرویس Gateway گمشده یا کهنه را گزارش می‌کند اما خارج از حالت اصلاح به‌روزرسانی، آن‌ها را نصب یا بازنویسی نمی‌کند. برای سرویس گمشده `openclaw gateway install` را اجرا کنید، یا وقتی عمداً می‌خواهید راه‌انداز را جایگزین کنید از `openclaw gateway install --force` استفاده کنید. -- بررسی‌های یکپارچگی وضعیت اکنون فایل‌های رونوشت یتیم را در دایرکتوری نشست‌ها تشخیص می‌دهند. بایگانی کردن آن‌ها به‌صورت `.deleted.` به تأیید تعاملی نیاز دارد؛ `--fix`، `--yes` و اجراهای بدون واسط آن‌ها را سر جای خود باقی می‌گذارند. -- Doctor همچنین `~/.openclaw/cron/jobs.json` (یا `cron.store`) را برای شکل‌های قدیمی کار Cron اسکن می‌کند و می‌تواند پیش از آنکه زمان‌بند مجبور شود در زمان اجرا آن‌ها را خودکار نرمال‌سازی کند، آن‌ها را درجا بازنویسی کند. -- در Linux، Doctor وقتی crontab کاربر هنوز `~/.openclaw/bin/ensure-whatsapp.sh` قدیمی را اجرا می‌کند هشدار می‌دهد؛ آن اسکریپت دیگر نگهداری نمی‌شود و وقتی cron محیط systemd user-bus را ندارد، می‌تواند قطعی‌های کاذب Gateway واتساپ را ثبت کند. -- Doctor وضعیت مرحله‌بندی وابستگی Plugin قدیمی را که نسخه‌های قدیمی‌تر OpenClaw ایجاد کرده‌اند پاک‌سازی می‌کند. همچنین Pluginهای دانلودشدنی پیکربندی‌شده و گمشده را وقتی رجیستری بتواند آن‌ها را حل کند، اصلاح می‌کند، و گذر Doctor نسخه 2026.5.2 پیش از علامت‌گذاری پیکربندی به‌عنوان لمس‌شده برای آن انتشار، به‌طور خودکار Pluginهای دانلودشدنی را که یک پیکربندی قدیمی‌تر از قبل استفاده می‌کند نصب می‌کند. اگر دانلود شکست بخورد، Doctor خطای نصب را گزارش می‌کند و ورودی Plugin پیکربندی‌شده را برای تلاش اصلاح بعدی حفظ می‌کند. -- Doctor پیکربندی کهنه Plugin را با حذف شناسه‌های Plugin گمشده از `plugins.allow`/`plugins.entries`، به‌همراه پیکربندی کانال آویزان متناظر، اهداف Heartbeat و جایگزینی‌های مدل کانال وقتی کشف Plugin سالم است اصلاح می‌کند. -- Doctor پیکربندی نامعتبر Plugin را با غیرفعال کردن ورودی آسیب‌دیده `plugins.entries.` و حذف payload نامعتبر `config` آن قرنطینه می‌کند. راه‌اندازی Gateway از قبل فقط همان Plugin خراب را رد می‌کند تا Pluginها و کانال‌های دیگر بتوانند به کار ادامه دهند. -- وقتی سرپرست دیگری چرخه‌عمر Gateway را مالک است، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. Doctor همچنان سلامت Gateway/سرویس را گزارش می‌کند و اصلاحات غیرسرویسی را اعمال می‌کند، اما نصب/شروع/راه‌اندازی مجدد/bootstrap سرویس و پاک‌سازی سرویس قدیمی را رد می‌کند. -- در Linux، Doctor واحدهای systemd اضافی شبیه Gateway را که غیرفعال هستند نادیده می‌گیرد و هنگام اصلاح، فراداده فرمان/نقطه ورود را برای یک سرویس Gateway در حال اجرای systemd بازنویسی نمی‌کند. ابتدا سرویس را متوقف کنید یا وقتی عمداً می‌خواهید راه‌انداز فعال را جایگزین کنید از `openclaw gateway install --force` استفاده کنید. -- Doctor به‌طور خودکار پیکربندی تخت قدیمی Talk (`talk.voiceId`، `talk.modelId` و موارد مشابه) را به `talk.provider` + `talk.providers.` مهاجرت می‌دهد. -- اجراهای تکراری `doctor --fix` دیگر وقتی تنها تفاوت ترتیب کلیدهای شیء باشد، نرمال‌سازی Talk را گزارش/اعمال نمی‌کنند. -- Doctor شامل یک بررسی آمادگی جست‌وجوی حافظه است و وقتی اطلاعات ورود embedding گم شده باشد می‌تواند `openclaw configure --section model` را توصیه کند. -- Doctor وقتی هیچ مالک فرمانی پیکربندی نشده باشد هشدار می‌دهد. مالک فرمان حساب اپراتور انسانی است که مجاز است فرمان‌های فقط مالک را اجرا کند و اقدام‌های خطرناک را تأیید کند. جفت‌سازی DM فقط به کسی اجازه می‌دهد با bot صحبت کند؛ اگر پیش از وجود bootstrap مالک اول، فرستنده‌ای را تأیید کرده‌اید، `commands.ownerAllowFrom` را صریح تنظیم کنید. -- Doctor وقتی عامل‌های حالت Codex پیکربندی شده‌اند و دارایی‌های شخصی Codex CLI در خانه Codex اپراتور وجود دارد هشدار می‌دهد. راه‌اندازی‌های app-server محلی Codex از خانه‌های ایزوله برای هر عامل استفاده می‌کنند، بنابراین از `openclaw migrate codex --dry-run` برای فهرست کردن دارایی‌هایی استفاده کنید که باید آگاهانه ارتقا داده شوند. -- Doctor وقتی Skills مجاز برای عامل پیش‌فرض در محیط اجرای فعلی در دسترس نیستند، چون binها، متغیرهای محیطی، پیکربندی یا نیازمندی‌های سیستم‌عامل گم شده‌اند، هشدار می‌دهد. `doctor --fix` می‌تواند آن Skills در دسترس نبودنی را با `skills.entries..enabled=false` غیرفعال کند؛ وقتی می‌خواهید Skills فعال بماند، به‌جای آن نیازمندی گمشده را نصب/پیکربندی کنید. -- اگر حالت sandbox فعال باشد اما Docker در دسترس نباشد، Doctor یک هشدار پرسیگنال همراه با راهکار (`install Docker` یا `openclaw config set agents.defaults.sandbox.mode off`) گزارش می‌کند. -- اگر فایل‌های رجیستری sandbox قدیمی (`~/.openclaw/sandbox/containers.json` یا `~/.openclaw/sandbox/browsers.json`) وجود داشته باشند، Doctor آن‌ها را گزارش می‌کند؛ `openclaw doctor --fix` ورودی‌های معتبر را به دایرکتوری‌های رجیستری shardشده مهاجرت می‌دهد و فایل‌های قدیمی نامعتبر را قرنطینه می‌کند. -- اگر `gateway.auth.token`/`gateway.auth.password` توسط SecretRef مدیریت شوند و در مسیر فرمان فعلی در دسترس نباشند، Doctor یک هشدار فقط‌خواندنی گزارش می‌کند و اطلاعات ورود جایگزین plaintext نمی‌نویسد. -- اگر بازرسی SecretRef کانال در یک مسیر اصلاح شکست بخورد، Doctor ادامه می‌دهد و به‌جای خروج زودهنگام یک هشدار گزارش می‌کند. -- پس از مهاجرت‌های دایرکتوری وضعیت، Doctor وقتی حساب‌های پیش‌فرض فعال Telegram یا Discord به fallback محیط وابسته باشند و `TELEGRAM_BOT_TOKEN` یا `DISCORD_BOT_TOKEN` برای فرایند Doctor در دسترس نباشد هشدار می‌دهد. -- حل خودکار نام کاربری `allowFrom` در Telegram (`doctor --fix`) به یک توکن قابل‌حل Telegram در مسیر فرمان فعلی نیاز دارد. اگر بازرسی توکن در دسترس نباشد، Doctor یک هشدار گزارش می‌کند و حل خودکار را برای آن گذر رد می‌کند. +- promptهای تعاملی، مانند اصلاحات keychain/OAuth، فقط زمانی اجرا می‌شوند که stdin یک TTY باشد و `--non-interactive` تنظیم **نشده** باشد. اجراهای headless، مانند cron، Telegram و بدون ترمینال، promptها را نادیده می‌گیرند. +- کارایی: اجراهای غیرتعاملی `doctor` بارگذاری زودهنگام Plugin را رد می‌کنند تا بررسی‌های سلامت headless سریع بمانند. نشست‌های تعاملی همچنان وقتی یک بررسی به مشارکت Pluginها نیاز داشته باشد، Pluginها را کامل بارگذاری می‌کنند. +- `--fix`، نام مستعار `--repair`، یک نسخه پشتیبان در `~/.openclaw/openclaw.json.bak` می‌نویسد و کلیدهای پیکربندی ناشناخته را حذف می‌کند و هر حذف را فهرست می‌کند. +- `doctor --fix --non-interactive` تعریف‌های سرویس Gateway را که گم شده یا کهنه هستند گزارش می‌کند، اما بیرون از حالت تعمیر به‌روزرسانی آن‌ها را نصب یا بازنویسی نمی‌کند. برای سرویس گم‌شده `openclaw gateway install` را اجرا کنید، یا وقتی عمداً می‌خواهید launcher را جایگزین کنید `openclaw gateway install --force` را اجرا کنید. +- بررسی‌های یکپارچگی وضعیت اکنون فایل‌های transcript یتیم را در پوشه sessions شناسایی می‌کنند. آرشیو کردن آن‌ها با قالب `.deleted.` به تأیید تعاملی نیاز دارد؛ `--fix`، `--yes` و اجراهای headless آن‌ها را سر جای خود باقی می‌گذارند. +- Doctor همچنین `~/.openclaw/cron/jobs.json` یا `cron.store` را برای شکل‌های قدیمی cron job اسکن می‌کند و می‌تواند پیش از آنکه زمان‌بند مجبور شود آن‌ها را در runtime خودکار نرمال‌سازی کند، همان‌جا بازنویسی‌شان کند. +- در Linux، وقتی crontab کاربر هنوز `~/.openclaw/bin/ensure-whatsapp.sh` قدیمی را اجرا می‌کند، doctor هشدار می‌دهد؛ آن اسکریپت دیگر نگهداری نمی‌شود و وقتی cron محیط systemd user-bus را ندارد، می‌تواند قطعی‌های نادرست Gateway مربوط به WhatsApp را log کند. +- Doctor وضعیت staging وابستگی Plugin قدیمی را که نسخه‌های قدیمی‌تر OpenClaw ساخته‌اند پاک‌سازی می‌کند. همچنین Pluginهای قابل دانلود گم‌شده‌ای را که در پیکربندی ارجاع شده‌اند تعمیر می‌کند، مانند `plugins.entries`، کانال‌های پیکربندی‌شده، تنظیمات provider/search پیکربندی‌شده، یا runtimeهای agent پیکربندی‌شده. هنگام به‌روزرسانی package، doctor تعمیر Plugin توسط package-manager را تا تکمیل جابه‌جایی package رد می‌کند؛ اگر یک Plugin پیکربندی‌شده همچنان به بازیابی نیاز دارد، پس از آن `openclaw doctor --fix` را دوباره اجرا کنید. اگر دانلود شکست بخورد، doctor خطای نصب را گزارش می‌کند و ورودی Plugin پیکربندی‌شده را برای تلاش تعمیر بعدی حفظ می‌کند. +- Doctor پیکربندی کهنه Plugin را با حذف شناسه‌های Plugin گم‌شده از `plugins.allow`/`plugins.entries`، به‌همراه پیکربندی کانال آویزان متناظر، هدف‌های Heartbeat و overrideهای مدل کانال، وقتی discovery Plugin سالم باشد، تعمیر می‌کند. +- Doctor پیکربندی نامعتبر Plugin را با غیرفعال کردن ورودی آسیب‌دیده `plugins.entries.` و حذف payload نامعتبر `config` آن قرنطینه می‌کند. راه‌اندازی Gateway از قبل فقط همان Plugin خراب را رد می‌کند تا سایر Pluginها و کانال‌ها بتوانند به کار ادامه دهند. +- وقتی supervisor دیگری lifecycle Gateway را مالکیت می‌کند، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. Doctor همچنان سلامت Gateway/سرویس را گزارش می‌کند و تعمیرهای غیرسرویسی را اعمال می‌کند، اما نصب/شروع/راه‌اندازی مجدد/bootstrap سرویس و پاک‌سازی سرویس قدیمی را رد می‌کند. +- در Linux، doctor واحدهای systemd اضافی شبیه Gateway را که inactive هستند نادیده می‌گیرد و هنگام تعمیر، metadata فرمان/entrypoint را برای یک سرویس Gateway در حال اجرا تحت systemd بازنویسی نمی‌کند. ابتدا سرویس را متوقف کنید، یا وقتی عمداً می‌خواهید launcher فعال را جایگزین کنید از `openclaw gateway install --force` استفاده کنید. +- Doctor پیکربندی تخت قدیمی Talk، مانند `talk.voiceId`، `talk.modelId` و موارد مشابه، را به `talk.provider` + `talk.providers.` خودکار مهاجرت می‌دهد. +- اجراهای تکراری `doctor --fix` دیگر وقتی تنها تفاوت ترتیب کلیدهای object باشد، نرمال‌سازی Talk را گزارش/اعمال نمی‌کنند. +- Doctor یک بررسی آمادگی جست‌وجوی حافظه دارد و وقتی credentialهای embedding گم شده باشند، می‌تواند `openclaw configure --section model` را پیشنهاد کند. +- Doctor وقتی هیچ مالک فرمانی پیکربندی نشده باشد هشدار می‌دهد. مالک فرمان، حساب انسانی operator است که اجازه دارد فرمان‌های فقط-مالک را اجرا کند و اقدام‌های خطرناک را تأیید کند. جفت‌سازی DM فقط اجازه می‌دهد کسی با bot صحبت کند؛ اگر پیش از وجود bootstrap مالک اول، یک فرستنده را تأیید کرده‌اید، `commands.ownerAllowFrom` را صریح تنظیم کنید. +- Doctor وقتی agentهای حالت Codex پیکربندی شده‌اند و assetهای شخصی Codex CLI در خانه Codex متعلق به operator وجود دارند، هشدار می‌دهد. اجرای app-server محلی Codex از خانه‌های جداگانه برای هر agent استفاده می‌کند، پس از `openclaw migrate codex --dry-run` برای فهرست کردن assetهایی استفاده کنید که باید عامدانه ارتقا داده شوند. +- Doctor وقتی skills مجاز برای agent پیش‌فرض در محیط runtime فعلی در دسترس نیستند، چون binها، env varها، config یا نیازمندی‌های OS گم شده‌اند، هشدار می‌دهد. `doctor --fix` می‌تواند آن skills غیرقابل‌دسترس را با `skills.entries..enabled=false` غیرفعال کند؛ وقتی می‌خواهید skill فعال بماند، در عوض نیازمندی گم‌شده را نصب/پیکربندی کنید. +- اگر حالت sandbox فعال باشد اما Docker در دسترس نباشد، doctor یک هشدار پرسیگنال همراه با راهکار رفع مشکل گزارش می‌کند: `install Docker` یا `openclaw config set agents.defaults.sandbox.mode off`. +- اگر فایل‌های قدیمی registry مربوط به sandbox، یعنی `~/.openclaw/sandbox/containers.json` یا `~/.openclaw/sandbox/browsers.json`، وجود داشته باشند، doctor آن‌ها را گزارش می‌کند؛ `openclaw doctor --fix` ورودی‌های معتبر را به پوشه‌های registry شاردشده مهاجرت می‌دهد و فایل‌های قدیمی نامعتبر را قرنطینه می‌کند. +- اگر `gateway.auth.token`/`gateway.auth.password` توسط SecretRef مدیریت شوند و در مسیر فرمان فعلی در دسترس نباشند، doctor یک هشدار فقط-خواندنی گزارش می‌کند و credentialهای fallback متن ساده نمی‌نویسد. +- اگر بررسی SecretRef کانال در مسیر fix شکست بخورد، doctor به‌جای خروج زودهنگام ادامه می‌دهد و یک هشدار گزارش می‌کند. +- پس از مهاجرت‌های پوشه وضعیت، doctor وقتی حساب‌های پیش‌فرض فعال Telegram یا Discord به fallback محیط وابسته باشند و `TELEGRAM_BOT_TOKEN` یا `DISCORD_BOT_TOKEN` برای فرایند doctor در دسترس نباشد، هشدار می‌دهد. +- auto-resolution نام کاربری `allowFrom` در Telegram (`doctor --fix`) به یک توکن قابل resolve مربوط به Telegram در مسیر فرمان فعلی نیاز دارد. اگر بررسی توکن در دسترس نباشد، doctor یک هشدار گزارش می‌کند و auto-resolution را برای آن گذر رد می‌کند. -## macOS: بازنویسی‌های env در `launchctl` +## macOS: overrideهای env مربوط به `launchctl` -اگر قبلاً `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (یا `...PASSWORD`) را اجرا کرده‌اید، آن مقدار فایل پیکربندی شما را بازنویسی می‌کند و می‌تواند باعث خطاهای پایدار «unauthorized» شود. +اگر قبلاً `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` یا `...PASSWORD` را اجرا کرده‌اید، آن مقدار فایل پیکربندی شما را override می‌کند و می‌تواند باعث خطاهای پایدار «غیرمجاز» شود. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -85,4 +85,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## مرتبط - [مرجع CLI](/fa/cli) -- [Gateway doctor](/fa/gateway/doctor) +- [doctor مربوط به Gateway](/fa/gateway/doctor) diff --git a/docs/fa/cli/gateway.md b/docs/fa/cli/gateway.md index 4b26f4658..5222b5811 100644 --- a/docs/fa/cli/gateway.md +++ b/docs/fa/cli/gateway.md @@ -1,31 +1,31 @@ --- read_when: - - اجرای Gateway از CLI (توسعه یا سرورها) - - عیب‌یابی احراز هویت Gateway، حالت‌های bind، و اتصال‌پذیری - - کشف Gatewayها از طریق Bonjour (محلی + DNS-SD گسترده) + - اجرای Gateway از طریق CLI (توسعه یا سرورها) + - اشکال‌زدایی احراز هویت Gateway، حالت‌های bind و اتصال‌پذیری + - کشف Gatewayها از طریق Bonjour (DNS-SD محلی + گستره‌وسیع) sidebarTitle: Gateway -summary: OpenClaw Gateway CLI (`openclaw gateway`) — اجرای Gateway‌ها، پرس‌وجو از آن‌ها و کشف آن‌ها +summary: OpenClaw Gateway CLI (`openclaw gateway`) — اجرای Gatewayها، پرس‌وجو از آن‌ها و کشفشان title: Gateway x-i18n: - generated_at: "2026-05-04T18:23:43Z" + generated_at: "2026-05-05T01:44:26Z" model: gpt-5.5 provider: openai - source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d + source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 source_path: cli/gateway.md workflow: 16 --- -Gateway سرور WebSocket متعلق به OpenClaw است (کانال‌ها، Nodeها، نشست‌ها، hookها). زیر‌دستورهای این صفحه زیر `openclaw gateway …` قرار دارند. +Gateway سرور WebSocket متعلق به OpenClaw است (کانال‌ها، گره‌ها، نشست‌ها، قلاب‌ها). زیرفرمان‌های این صفحه زیر `openclaw gateway …` قرار دارند. راه‌اندازی mDNS محلی + DNS-SD گسترده. - اینکه OpenClaw چگونه gatewayها را معرفی و پیدا می‌کند. + اینکه OpenClaw چگونه Gatewayها را تبلیغ و پیدا می‌کند. - کلیدهای پیکربندی gateway در سطح بالا. + کلیدهای پیکربندی سطح‌بالای Gateway. @@ -45,12 +45,12 @@ openclaw gateway run - - به‌طور پیش‌فرض، Gateway شروع به کار نمی‌کند مگر اینکه `gateway.mode=local` در `~/.openclaw/openclaw.json` تنظیم شده باشد. برای اجراهای موقت/توسعه از `--allow-unconfigured` استفاده کنید. + - به‌صورت پیش‌فرض، Gateway از شروع خودداری می‌کند مگر اینکه `gateway.mode=local` در `~/.openclaw/openclaw.json` تنظیم شده باشد. برای اجراهای موقت/توسعه از `--allow-unconfigured` استفاده کنید. - انتظار می‌رود `openclaw onboard --mode local` و `openclaw setup` مقدار `gateway.mode=local` را بنویسند. اگر فایل وجود دارد اما `gateway.mode` وجود ندارد، آن را به‌عنوان پیکربندی خراب یا بازنویسی‌شده در نظر بگیرید و به‌جای فرض ضمنی حالت محلی، آن را تعمیر کنید. - - اگر فایل وجود دارد و `gateway.mode` وجود ندارد، Gateway این وضعیت را آسیب مشکوک به پیکربندی تلقی می‌کند و حاضر نیست برای شما «محلی را حدس بزند». - - اتصال فراتر از loopback بدون احراز هویت مسدود می‌شود (ریل ایمنی). - - `SIGUSR1` وقتی مجاز باشد یک راه‌اندازی مجدد درون‌فرایندی را فعال می‌کند (`commands.restart` به‌طور پیش‌فرض فعال است؛ برای مسدود کردن راه‌اندازی مجدد دستی، `commands.restart: false` را تنظیم کنید، در حالی که اعمال/به‌روزرسانی ابزار/پیکربندی gateway همچنان مجاز می‌ماند). - - handlerهای `SIGINT`/`SIGTERM` فرایند gateway را متوقف می‌کنند، اما هیچ وضعیت سفارشی ترمینال را بازیابی نمی‌کنند. اگر CLI را با TUI یا ورودی raw-mode بسته‌بندی می‌کنید، پیش از خروج ترمینال را بازیابی کنید. + - اگر فایل وجود دارد و `gateway.mode` وجود ندارد، Gateway این را آسیب مشکوک پیکربندی تلقی می‌کند و از «حدس زدن حالت محلی» برای شما خودداری می‌کند. + - اتصال فراتر از loopback بدون احراز هویت مسدود می‌شود (حفاظ ایمنی). + - `SIGUSR1` وقتی مجاز باشد یک راه‌اندازی مجدد درون‌فرایندی را فعال می‌کند (`commands.restart` به‌صورت پیش‌فرض فعال است؛ برای مسدود کردن راه‌اندازی مجدد دستی، `commands.restart: false` را تنظیم کنید، درحالی‌که اعمال/به‌روزرسانی ابزار/پیکربندی Gateway همچنان مجاز می‌ماند). + - هندلرهای `SIGINT`/`SIGTERM` فرایند gateway را متوقف می‌کنند، اما هیچ وضعیت سفارشی ترمینال را بازیابی نمی‌کنند. اگر CLI را با یک TUI یا ورودی raw-mode بسته‌بندی می‌کنید، پیش از خروج ترمینال را بازیابی کنید. @@ -58,10 +58,10 @@ openclaw gateway run ### گزینه‌ها - پورت WebSocket (پیش‌فرض از پیکربندی/env می‌آید؛ معمولا `18789`). + پورت WebSocket (پیش‌فرض از پیکربندی/محیط می‌آید؛ معمولاً `18789`). - حالت bind شنونده. + حالت اتصال شنونده. بازنویسی حالت احراز هویت. @@ -79,16 +79,16 @@ openclaw gateway run Gateway را از طریق Tailscale در دسترس قرار دهید. - پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموش‌شدن بازنشانی کنید. + پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموشی بازنشانی کنید. - اجازه دهید gateway بدون `gateway.mode=local` در پیکربندی شروع شود. فقط برای bootstrap موقت/توسعه، guard شروع را دور می‌زند؛ فایل پیکربندی را نمی‌نویسد یا تعمیر نمی‌کند. + اجازه شروع gateway بدون `gateway.mode=local` در پیکربندی را بدهید. این فقط برای bootstrap موقت/توسعه، محافظ شروع را دور می‌زند؛ فایل پیکربندی را نمی‌نویسد یا تعمیر نمی‌کند. - اگر وجود ندارد، پیکربندی توسعه + workspace بسازید (`BOOTSTRAP.md` را رد می‌کند). + اگر وجود نداشته باشد، یک پیکربندی توسعه + فضای کاری بسازید (`BOOTSTRAP.md` را رد می‌کند). - پیکربندی توسعه + credentials + نشست‌ها + workspace را بازنشانی کنید (به `--dev` نیاز دارد). + پیکربندی توسعه + اعتبارنامه‌ها + نشست‌ها + فضای کاری را بازنشانی کنید (به `--dev` نیاز دارد). پیش از شروع، هر شنونده موجود روی پورت انتخاب‌شده را بکشید. @@ -97,7 +97,7 @@ openclaw gateway run لاگ‌های پرجزئیات. - فقط لاگ‌های backend مربوط به CLI را در کنسول نشان دهید (و stdout/stderr را فعال کنید). + فقط لاگ‌های بک‌اند CLI را در کنسول نشان بده (و stdout/stderr را فعال کن). سبک لاگ Websocket. @@ -106,10 +106,10 @@ openclaw gateway run نام مستعار برای `--ws-log compact`. - رویدادهای خام stream مدل را در jsonl لاگ کنید. + رخدادهای خام جریان مدل را در jsonl لاگ کن. - مسیر jsonl مربوط به stream خام. + مسیر jsonl جریان خام. ## راه‌اندازی مجدد Gateway @@ -120,41 +120,41 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` از Gateway در حال اجرا می‌خواهد پیش از راه‌اندازی مجدد، کارهای فعال OpenClaw را پیش‌بررسی کند. اگر عملیات صف‌شده، تحویل پاسخ، اجراهای embedded، یا اجرای taskها فعال باشند، Gateway مسدودکننده‌ها را گزارش می‌کند، درخواست‌های تکراری راه‌اندازی مجدد امن را ادغام می‌کند، و پس از تخلیه کار فعال راه‌اندازی مجدد می‌شود. `restart` ساده برای سازگاری، رفتار موجود service-manager را نگه می‌دارد. فقط زمانی از `--force` استفاده کنید که صراحتا مسیر بازنویسی فوری را می‌خواهید. +`openclaw gateway restart --safe` از Gateway در حال اجرا می‌خواهد پیش از راه‌اندازی مجدد، کارهای فعال OpenClaw را پیش‌بررسی کند. اگر عملیات صف‌شده، تحویل پاسخ، اجراهای جاسازی‌شده، یا اجراهای کار فعال باشند، Gateway مسدودکننده‌ها را گزارش می‌کند، درخواست‌های تکراری راه‌اندازی مجدد امن را ادغام می‌کند، و پس از تخلیه کار فعال دوباره راه‌اندازی می‌شود. `restart` ساده برای سازگاری، رفتار مدیر سرویس موجود را حفظ می‌کند. فقط وقتی از `--force` استفاده کنید که صراحتاً مسیر بازنویسی فوری را می‌خواهید. -`--password` درون‌خطی می‌تواند در فهرست‌های فرایند محلی آشکار شود. `--password-file`، env، یا `gateway.auth.password` مبتنی بر SecretRef را ترجیح دهید. +`--password` درون‌خطی می‌تواند در فهرست فرایندهای محلی افشا شود. `--password-file`، محیط، یا `gateway.auth.password` متکی بر SecretRef را ترجیح دهید. ### پروفایل‌گیری شروع -- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` را تنظیم کنید تا زمان‌بندی فازها هنگام شروع Gateway لاگ شود، از جمله تاخیر `eventLoopMax` برای هر فاز و زمان‌بندی‌های جدول lookup مربوط به Plugin برای installed-index، manifest registry، برنامه‌ریزی شروع، و کار owner-map. -- `OPENCLAW_DIAGNOSTICS=timeline` را همراه با `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` تنظیم کنید تا یک timeline تشخیصی شروع JSONL به‌صورت best-effort برای harnessهای QA خارجی نوشته شود. همچنین می‌توانید این پرچم را با `diagnostics.flags: ["timeline"]` در پیکربندی فعال کنید؛ مسیر همچنان از env تامین می‌شود. برای افزودن نمونه‌های event-loop، `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` را اضافه کنید. -- برای benchmark کردن شروع Gateway، `pnpm test:startup:gateway -- --runs 5 --warmup 1` را اجرا کنید. benchmark نخستین خروجی فرایند، `/healthz`، `/readyz`، زمان‌بندی‌های trace شروع، تاخیر event-loop، و جزئیات زمان‌بندی جدول lookup مربوط به Plugin را ثبت می‌کند. +- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` را تنظیم کنید تا زمان‌بندی فازها هنگام شروع Gateway لاگ شود، شامل تأخیر `eventLoopMax` برای هر فاز و زمان‌بندی‌های جدول جست‌وجوی Plugin برای installed-index، رجیستری مانیفست، برنامه‌ریزی شروع، و کار owner-map. +- `OPENCLAW_DIAGNOSTICS=timeline` را با `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=` تنظیم کنید تا یک timeline تشخیصی شروع JSONL به‌صورت best-effort برای ابزارهای QA خارجی نوشته شود. همچنین می‌توانید این پرچم را با `diagnostics.flags: ["timeline"]` در پیکربندی فعال کنید؛ مسیر همچنان از محیط فراهم می‌شود. برای شامل کردن نمونه‌های حلقه رخداد، `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` را اضافه کنید. +- برای benchmark شروع Gateway، `pnpm test:startup:gateway -- --runs 5 --warmup 1` را اجرا کنید. benchmark نخستین خروجی فرایند، `/healthz`، `/readyz`، زمان‌بندی‌های ردگیری شروع، تأخیر حلقه رخداد، و جزئیات زمان‌بندی جدول جست‌وجوی Plugin را ثبت می‌کند. ## پرس‌وجو از یک Gateway در حال اجرا -همه دستورهای پرس‌وجو از RPC روی WebSocket استفاده می‌کنند. +همه فرمان‌های پرس‌وجو از RPC روی WebSocket استفاده می‌کنند. - - پیش‌فرض: خوانا برای انسان (رنگی در TTY). - - `--json`: JSON خوانا برای ماشین (بدون سبک‌دهی/spinner). - - `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال می‌کند و چیدمان انسانی را نگه می‌دارد. + - پیش‌فرض: قابل‌خواندن برای انسان (رنگی در TTY). + - `--json`: JSON قابل‌خواندن برای ماشین (بدون استایل/اسپینر). + - `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال کن و چیدمان انسانی را حفظ کن. - - `--url `: URL WebSocket مربوط به Gateway. + - `--url `: نشانی WebSocket متعلق به Gateway. - `--token `: توکن Gateway. - `--password `: گذرواژه Gateway. - - `--timeout `: timeout/budget (بسته به دستور متفاوت است). - - `--expect-final`: منتظر پاسخ "final" بمانید (فراخوانی‌های agent). + - `--timeout `: زمان‌انتظار/بودجه (بسته به فرمان متفاوت است). + - `--expect-final`: منتظر پاسخ "final" بمان (فراخوانی‌های عامل). -وقتی `--url` را تنظیم می‌کنید، CLI به credentials موجود در پیکربندی یا محیط fallback نمی‌کند. `--token` یا `--password` را صراحتا پاس دهید. نبودن credentials صریح یک خطاست. +وقتی `--url` را تنظیم می‌کنید، CLI به اعتبارنامه‌های پیکربندی یا محیط fallback نمی‌کند. `--token` یا `--password` را صریحاً بدهید. نبود اعتبارنامه‌های صریح یک خطاست. ### `gateway health` @@ -163,11 +163,11 @@ openclaw gateway restart --force openclaw gateway health --url ws://127.0.0.1:18789 ``` -endpoint ‏HTTP ‏`/healthz` یک liveness probe است: وقتی سرور بتواند به HTTP پاسخ دهد، خروجی برمی‌گرداند. endpoint ‏HTTP ‏`/readyz` سخت‌گیرتر است و تا زمانی که sidecarهای Plugin شروع، کانال‌ها، یا hookهای پیکربندی‌شده هنوز در حال پایدار شدن باشند، قرمز می‌ماند. پاسخ‌های detailed readiness محلی یا احراز هویت‌شده شامل یک بلوک diagnostic به نام `eventLoop` هستند که تاخیر event-loop، میزان استفاده event-loop، نسبت هسته CPU، و یک پرچم `degraded` را دارد. +نقطه پایانی HTTP `/healthz` یک probe زنده‌بودن است: وقتی سرور بتواند به HTTP پاسخ بدهد برمی‌گردد. نقطه پایانی HTTP `/readyz` سخت‌گیرانه‌تر است و تا وقتی sidecarهای Plugin شروع، کانال‌ها، یا hookهای پیکربندی‌شده هنوز در حال settle شدن هستند قرمز می‌ماند. پاسخ‌های آمادگی تفصیلی محلی یا احراز هویت‌شده شامل یک بلوک تشخیصی `eventLoop` با تأخیر حلقه رخداد، بهره‌وری حلقه رخداد، نسبت هسته CPU، و یک پرچم `degraded` هستند. ### `gateway usage-cost` -خلاصه‌های usage-cost را از لاگ‌های نشست دریافت کنید. +خلاصه‌های هزینه مصرف را از لاگ‌های نشست دریافت کن. ```bash openclaw gateway usage-cost @@ -176,12 +176,12 @@ openclaw gateway usage-cost --json ``` - تعداد روزهایی که باید لحاظ شوند. + تعداد روزهایی که باید شامل شود. ### `gateway stability` -recorder تشخیصی پایداری اخیر را از یک Gateway در حال اجرا دریافت کنید. +ضبط‌کننده پایداری تشخیصی اخیر را از یک Gateway در حال اجرا دریافت کن. ```bash openclaw gateway stability @@ -192,19 +192,19 @@ openclaw gateway stability --json ``` - حداکثر تعداد رویدادهای اخیر برای لحاظ کردن (حداکثر `1000`). + حداکثر تعداد رخدادهای اخیر که باید شامل شوند (حداکثر `1000`). - فیلتر بر اساس نوع رویداد تشخیصی، مانند `payload.large` یا `diagnostic.memory.pressure`. + بر اساس نوع رخداد تشخیصی فیلتر کن، مانند `payload.large` یا `diagnostic.memory.pressure`. - فقط رویدادهای پس از یک شماره توالی تشخیصی را لحاظ کنید. + فقط رخدادهای پس از یک شماره توالی تشخیصی را شامل کن. - به‌جای فراخوانی Gateway در حال اجرا، یک bundle پایداری persisted را بخوانید. برای جدیدترین bundle زیر دایرکتوری state از `--bundle latest` (یا فقط `--bundle`) استفاده کنید، یا مسیر JSON یک bundle را مستقیما پاس دهید. + به‌جای فراخوانی Gateway در حال اجرا، یک bundle پایداری ماندگارشده را بخوان. برای جدیدترین bundle زیر دایرکتوری state از `--bundle latest` (یا فقط `--bundle`) استفاده کن، یا مسیر JSON یک bundle را مستقیماً بده. - به‌جای چاپ جزئیات پایداری، یک zip تشخیصی قابل اشتراک‌گذاری برای پشتیبانی بنویسید. + به‌جای چاپ جزئیات پایداری، یک zip تشخیصی پشتیبانی قابل‌اشتراک بنویس. مسیر خروجی برای `--export`. @@ -212,15 +212,15 @@ openclaw gateway stability --json - - رکوردها metadata عملیاتی را نگه می‌دارند: نام رویدادها، شمارش‌ها، اندازه‌های بایتی، خوانش‌های حافظه، وضعیت صف/نشست، نام کانال/Plugin، و خلاصه‌های نشست redact‌شده. آن‌ها متن گفت‌وگو، بدنه‌های webhook، خروجی‌های ابزار، بدنه‌های خام درخواست یا پاسخ، توکن‌ها، کوکی‌ها، مقادیر محرمانه، hostnames، یا شناسه‌های خام نشست را نگه نمی‌دارند. برای غیرفعال کردن کامل recorder، `diagnostics.enabled: false` را تنظیم کنید. - - هنگام خروج‌های fatal از Gateway، timeoutهای خاموشی، و شکست‌های شروع پس از راه‌اندازی مجدد، وقتی recorder رویدادهایی داشته باشد، OpenClaw همان snapshot تشخیصی را در `~/.openclaw/logs/stability/openclaw-stability-*.json` می‌نویسد. جدیدترین bundle را با `openclaw gateway stability --bundle latest` بررسی کنید؛ `--limit`، `--type`، و `--since-seq` نیز روی خروجی bundle اعمال می‌شوند. + - رکوردها metadata عملیاتی را نگه می‌دارند: نام رخدادها، شمارش‌ها، اندازه‌های بایت، خوانش‌های حافظه، وضعیت صف/نشست، نام کانال/Plugin، و خلاصه‌های نشست redact‌شده. آن‌ها متن چت، بدنه‌های Webhook، خروجی‌های ابزار، بدنه‌های خام درخواست یا پاسخ، توکن‌ها، کوکی‌ها، مقدارهای محرمانه، نام میزبان‌ها، یا شناسه‌های خام نشست را نگه نمی‌دارند. برای غیرفعال کردن کامل ضبط‌کننده، `diagnostics.enabled: false` را تنظیم کنید. + - هنگام خروج‌های fatal Gateway، timeoutهای خاموشی، و شکست‌های شروع پس از restart، وقتی ضبط‌کننده رخداد داشته باشد OpenClaw همان snapshot تشخیصی را در `~/.openclaw/logs/stability/openclaw-stability-*.json` می‌نویسد. جدیدترین bundle را با `openclaw gateway stability --bundle latest` بررسی کنید؛ `--limit`، `--type`، و `--since-seq` نیز روی خروجی bundle اعمال می‌شوند. ### `gateway diagnostics export` -یک zip تشخیصی محلی بنویسید که برای پیوست کردن به گزارش‌های bug طراحی شده است. برای مدل حریم خصوصی و محتوای bundle، [Diagnostics Export](/fa/gateway/diagnostics) را ببینید. +یک zip تشخیصی محلی بنویس که برای پیوست کردن به گزارش‌های باگ طراحی شده است. برای مدل حریم خصوصی و محتوای bundle، [Diagnostics Export](/fa/gateway/diagnostics) را ببینید. ```bash openclaw gateway diagnostics export @@ -229,16 +229,16 @@ openclaw gateway diagnostics export --json ``` - مسیر zip خروجی. پیش‌فرض، یک export پشتیبانی زیر دایرکتوری state است. + مسیر zip خروجی. پیش‌فرض یک export پشتیبانی زیر دایرکتوری state است. - حداکثر تعداد خطوط لاگ sanitize‌شده برای لحاظ کردن. + حداکثر خطوط لاگ پاک‌سازی‌شده که باید شامل شوند. حداکثر بایت‌های لاگ برای بررسی. - URL WebSocket مربوط به Gateway برای snapshot سلامت. + نشانی WebSocket متعلق به Gateway برای snapshot سلامت. توکن Gateway برای snapshot سلامت. @@ -247,18 +247,18 @@ openclaw gateway diagnostics export --json گذرواژه Gateway برای snapshot سلامت. - timeout مربوط به snapshot وضعیت/سلامت. + زمان‌انتظار snapshot وضعیت/سلامت. - lookup مربوط به bundle پایداری persisted را رد کنید. + جست‌وجوی bundle پایداری ماندگارشده را رد کن. - مسیر نوشته‌شده، اندازه، و manifest را به‌صورت JSON چاپ کنید. + مسیر نوشته‌شده، اندازه، و مانیفست را به‌صورت JSON چاپ کن. -export شامل یک manifest، یک خلاصه Markdown، شکل پیکربندی، جزئیات پیکربندی sanitize‌شده، خلاصه‌های لاگ sanitize‌شده، snapshotهای وضعیت/سلامت Gateway به‌صورت sanitize‌شده، و در صورت وجود، جدیدترین bundle پایداری است. +این export شامل یک مانیفست، یک خلاصه Markdown، شکل پیکربندی، جزئیات پیکربندی پاک‌سازی‌شده، خلاصه‌های لاگ پاک‌سازی‌شده، snapshotهای وضعیت/سلامت Gateway پاک‌سازی‌شده، و جدیدترین bundle پایداری در صورت وجود است. -قرار است قابل اشتراک‌گذاری باشد. جزئیات عملیاتی کمک‌کننده به debugging را نگه می‌دارد، مانند فیلدهای امن لاگ OpenClaw، نام‌های subsystem، کدهای وضعیت، مدت‌زمان‌ها، حالت‌های پیکربندی‌شده، پورت‌ها، شناسه‌های Plugin، شناسه‌های provider، تنظیمات feature غیرمحرمانه، و پیام‌های لاگ عملیاتی redact‌شده. متن گفت‌وگو، بدنه‌های webhook، خروجی‌های ابزار، credentials، کوکی‌ها، شناسه‌های حساب/پیام، متن prompt/instruction، hostnames، و مقادیر محرمانه را حذف یا redact می‌کند. وقتی یک پیام سبک LogTape شبیه متن payload کاربر/گفت‌وگو/ابزار باشد، export فقط این را نگه می‌دارد که پیام حذف شده است، به‌همراه تعداد بایت آن. +برای اشتراک‌گذاری در نظر گرفته شده است. جزئیات عملیاتی کمک‌کننده به اشکال‌زدایی را نگه می‌دارد، مانند فیلدهای امن لاگ OpenClaw، نام‌های زیرسیستم، کدهای وضعیت، مدت‌زمان‌ها، حالت‌های پیکربندی‌شده، پورت‌ها، شناسه‌های Plugin، شناسه‌های provider، تنظیمات قابلیت غیرمحرمانه، و پیام‌های لاگ عملیاتی redact‌شده. متن چت، بدنه‌های Webhook، خروجی‌های ابزار، اعتبارنامه‌ها، کوکی‌ها، شناسه‌های حساب/پیام، متن prompt/instruction، نام میزبان‌ها، و مقدارهای محرمانه را حذف یا redact می‌کند. وقتی یک پیام به سبک LogTape شبیه متن payload کاربر/چت/ابزار باشد، export فقط این را نگه می‌دارد که یک پیام حذف شده است به‌همراه شمارش بایت آن. ### `gateway status` @@ -271,63 +271,63 @@ openclaw gateway status --require-rpc ``` - یک هدف پروب صریح اضافه کنید. راه دور پیکربندی‌شده + localhost همچنان پروب می‌شوند. + یک هدف کاوش صریح اضافه کنید. ریموت پیکربندی‌شده + localhost همچنان کاوش می‌شوند. - احراز هویت با توکن برای پروب. + احراز هویت با توکن برای کاوش. - احراز هویت با گذرواژه برای پروب. + احراز هویت با گذرواژه برای کاوش. - مهلت زمانی پروب. + مهلت زمانی کاوش. - پروب اتصال را رد کنید (نمای فقط سرویس). + از کاوش اتصال‌پذیری صرف‌نظر کنید (نمای فقط سرویس). سرویس‌های سطح سیستم را هم اسکن کنید. - پروب اتصال پیش‌فرض را به پروب خواندن ارتقا دهید و وقتی آن پروب خواندن شکست می‌خورد با کد غیرصفر خارج شوید. نمی‌توان آن را با `--no-probe` ترکیب کرد. + کاوش اتصال‌پذیری پیش‌فرض را به کاوش خواندن ارتقا دهید و وقتی آن کاوش خواندن شکست می‌خورد با کد غیرصفر خارج شوید. نمی‌توان آن را با `--no-probe` ترکیب کرد. - - `gateway status` حتی وقتی پیکربندی CLI محلی وجود ندارد یا نامعتبر است، برای تشخیص عیب در دسترس می‌ماند. - - `gateway status` پیش‌فرض وضعیت سرویس، اتصال وب‌سوکت، و قابلیت احراز هویت قابل مشاهده هنگام دست‌دهی را اثبات می‌کند. عملیات خواندن/نوشتن/مدیریت را اثبات نمی‌کند. - - پروب‌های تشخیصی برای احراز هویت دستگاه در نخستین استفاده تغییردهنده نیستند: وقتی توکن دستگاه کش‌شده‌ای وجود داشته باشد، همان را دوباره استفاده می‌کنند، اما صرفاً برای بررسی وضعیت، هویت جدید دستگاه CLI یا رکورد جفت‌سازی فقط‌خواندنی دستگاه ایجاد نمی‌کنند. - - `gateway status` در صورت امکان SecretRefهای احراز هویت پیکربندی‌شده را برای احراز هویت پروب حل می‌کند. - - اگر یک SecretRef احراز هویت الزامی در این مسیر فرمان حل‌نشده باشد، `gateway status --json` هنگام شکست اتصال/احراز هویت پروب، `rpc.authWarning` را گزارش می‌کند؛ `--token`/`--password` را صریحاً بدهید یا ابتدا منبع secret را حل کنید. - - اگر پروب موفق شود، هشدارهای ارجاع احراز هویت حل‌نشده برای جلوگیری از مثبت‌های کاذب سرکوب می‌شوند. - - وقتی سرویس در حال گوش دادن کافی نیست و لازم است فراخوانی‌های RPC با محدوده خواندن هم سالم باشند، در اسکریپت‌ها و خودکارسازی از `--require-rpc` استفاده کنید. - - `--deep` یک اسکن با بهترین تلاش برای نصب‌های اضافی launchd/systemd/schtasks اضافه می‌کند. وقتی چند سرویس شبیه Gateway شناسایی شوند، خروجی انسانی نکته‌های پاک‌سازی را چاپ می‌کند و هشدار می‌دهد که بیشتر راه‌اندازی‌ها باید روی هر دستگاه یک Gateway اجرا کنند. - - خروجی انسانی مسیر حل‌شده فایل لاگ به‌علاوه نمای لحظه‌ای مسیرها/اعتبار پیکربندی CLI در برابر سرویس را شامل می‌شود تا به تشخیص drift پروفایل یا دایرکتوری وضعیت کمک کند. + - `gateway status` حتی وقتی پیکربندی CLI محلی وجود ندارد یا نامعتبر است، برای عیب‌یابی در دسترس می‌ماند. + - `gateway status` پیش‌فرض وضعیت سرویس، اتصال WebSocket، و قابلیت احراز هویت قابل مشاهده در زمان دست‌دهی را اثبات می‌کند. عملیات خواندن/نوشتن/مدیریت را اثبات نمی‌کند. + - کاوش‌های عیب‌یابی برای احراز هویت بار اول دستگاه تغییردهنده نیستند: وقتی توکن دستگاه کش‌شده‌ای وجود داشته باشد از همان استفاده می‌کنند، اما فقط برای بررسی وضعیت، هویت دستگاه CLI جدید یا رکورد جفت‌سازی دستگاه فقط‌خواندنی ایجاد نمی‌کنند. + - `gateway status` در صورت امکان SecretRefهای احراز هویت پیکربندی‌شده را برای احراز هویت کاوش resolve می‌کند. + - اگر یک SecretRef احراز هویت الزامی در این مسیر فرمان resolve نشده باشد، `gateway status --json` هنگام شکست اتصال‌پذیری/احراز هویت کاوش، `rpc.authWarning` را گزارش می‌کند؛ `--token`/`--password` را صریح پاس دهید یا ابتدا منبع secret را resolve کنید. + - اگر کاوش موفق شود، هشدارهای auth-ref resolveنشده برای جلوگیری از مثبت‌های کاذب سرکوب می‌شوند. + - وقتی یک سرویس در حال گوش‌دادن کافی نیست و لازم دارید فراخوانی‌های RPC با محدوده خواندن نیز سالم باشند، در اسکریپت‌ها و خودکارسازی از `--require-rpc` استفاده کنید. + - `--deep` یک اسکن best-effort برای نصب‌های اضافی launchd/systemd/schtasks اضافه می‌کند. وقتی چند سرویس شبیه Gateway شناسایی شوند، خروجی انسانی راهنمای پاک‌سازی چاپ می‌کند و هشدار می‌دهد که بیشتر راه‌اندازی‌ها باید برای هر ماشین یک Gateway اجرا کنند. + - خروجی انسانی مسیر فایل لاگ resolveشده به‌همراه snapshot مسیرها/اعتبار پیکربندی CLI در برابر سرویس را شامل می‌شود تا به عیب‌یابی drift پروفایل یا state-dir کمک کند. - - - در نصب‌های systemd لینوکس، بررسی‌های drift احراز هویت سرویس مقدارهای `Environment=` و `EnvironmentFile=` را از unit می‌خوانند (از جمله `%h`، مسیرهای نقل‌قول‌شده، چند فایل، و فایل‌های اختیاری `-`). - - بررسی‌های drift، SecretRefهای `gateway.auth.token` را با استفاده از محیط زمان اجرای ادغام‌شده حل می‌کنند (ابتدا محیط فرمان سرویس، سپس محیط فرایند به‌عنوان جایگزین). - - اگر احراز هویت با توکن عملاً فعال نباشد (`gateway.auth.mode` صریحِ `password`/`none`/`trusted-proxy`، یا حالتی که تنظیم نشده و در آن گذرواژه می‌تواند انتخاب شود و هیچ نامزد توکنی نمی‌تواند انتخاب شود)، بررسی‌های drift توکن از حل توکن پیکربندی صرف‌نظر می‌کنند. + + - در نصب‌های systemd روی Linux، بررسی‌های drift احراز هویت سرویس هر دو مقدار `Environment=` و `EnvironmentFile=` را از unit می‌خوانند (شامل `%h`، مسیرهای نقل‌قول‌شده، چند فایل، و فایل‌های اختیاری `-`). + - بررسی‌های drift با استفاده از env زمان اجرای ادغام‌شده، SecretRefهای `gateway.auth.token` را resolve می‌کنند (ابتدا env فرمان سرویس، سپس fallback به env فرایند). + - اگر احراز هویت با توکن عملا فعال نباشد (`gateway.auth.mode` صریح با مقدار `password`/`none`/`trusted-proxy`، یا mode تنظیم نشده باشد، جایی که گذرواژه می‌تواند برنده شود و هیچ کاندید توکنی نمی‌تواند برنده شود)، بررسی‌های token-drift از resolve کردن توکن پیکربندی صرف‌نظر می‌کنند. ### `gateway probe` -`gateway probe` فرمان «اشکال‌زدایی همه‌چیز» است. همیشه این موارد را پروب می‌کند: +`gateway probe` فرمان «عیب‌یابی همه‌چیز» است. همیشه موارد زیر را کاوش می‌کند: -- Gateway راه دور پیکربندی‌شده شما (اگر تنظیم شده باشد)، و -- localhost (loopback) **حتی اگر راه دور پیکربندی شده باشد**. +- gateway ریموت پیکربندی‌شده شما (اگر تنظیم شده باشد)، و +- localhost (loopback) **حتی اگر ریموت پیکربندی شده باشد**. -اگر `--url` را بدهید، آن هدف صریح پیش از هر دوی آن‌ها اضافه می‌شود. خروجی انسانی هدف‌ها را این‌گونه برچسب می‌زند: +اگر `--url` را پاس دهید، آن هدف صریح جلوتر از هر دو اضافه می‌شود. خروجی انسانی هدف‌ها را این‌گونه برچسب می‌زند: - `URL (explicit)` - `Remote (configured)` یا `Remote (configured, inactive)` - `Local loopback` -اگر چند Gateway در دسترس باشند، همه آن‌ها را چاپ می‌کند. چند Gateway وقتی از پروفایل‌ها/پورت‌های ایزوله استفاده می‌کنید (مثلاً یک ربات نجات) پشتیبانی می‌شوند، اما بیشتر نصب‌ها همچنان یک Gateway واحد اجرا می‌کنند. +اگر چند gateway قابل دسترس باشند، همه آن‌ها را چاپ می‌کند. وقتی از پروفایل‌ها/پورت‌های ایزوله استفاده می‌کنید (مثلا یک بات نجات)، چند gateway پشتیبانی می‌شود، اما بیشتر نصب‌ها همچنان یک Gateway واحد اجرا می‌کنند. ```bash @@ -337,51 +337,51 @@ openclaw gateway probe --json - - `Reachable: yes` یعنی حداقل یک هدف اتصال وب‌سوکت را پذیرفته است. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` گزارش می‌کند که پروب درباره احراز هویت چه چیزی را توانسته اثبات کند. این از دسترس‌پذیری جداست. - - `Read probe: ok` یعنی فراخوانی‌های RPC جزئیات با محدوده خواندن (`health`/`status`/`system-presence`/`config.get`) نیز موفق شده‌اند. - - `Read probe: limited - missing scope: operator.read` یعنی اتصال موفق شده اما RPC با محدوده خواندن محدود است. این به‌عنوان دسترس‌پذیری **تنزل‌یافته** گزارش می‌شود، نه شکست کامل. - - `Read probe: failed` پس از `Connect: ok` یعنی Gateway اتصال وب‌سوکت را پذیرفته، اما تشخیص‌های خواندن بعدی timeout شده‌اند یا شکست خورده‌اند. این هم دسترس‌پذیری **تنزل‌یافته** است، نه Gateway غیرقابل دسترس. - - مانند `gateway status`، پروب از احراز هویت دستگاه کش‌شده موجود دوباره استفاده می‌کند اما هویت دستگاه یا وضعیت جفت‌سازی نخستین‌بار ایجاد نمی‌کند. - - کد خروج تنها زمانی غیرصفر است که هیچ هدف پروب‌شده‌ای در دسترس نباشد. + - `Reachable: yes` یعنی حداقل یک هدف اتصال WebSocket را پذیرفت. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` گزارش می‌دهد که کاوش درباره احراز هویت چه چیزی را توانسته اثبات کند. این از دسترس‌پذیری جدا است. + - `Read probe: ok` یعنی فراخوانی‌های RPC جزئیات با محدوده خواندن (`health`/`status`/`system-presence`/`config.get`) نیز موفق شدند. + - `Read probe: limited - missing scope: operator.read` یعنی اتصال موفق شد اما RPC با محدوده خواندن محدود است. این به‌عنوان دسترس‌پذیری **تنزل‌یافته** گزارش می‌شود، نه شکست کامل. + - `Read probe: failed` پس از `Connect: ok` یعنی Gateway اتصال WebSocket را پذیرفت، اما عیب‌یابی‌های خواندن بعدی timeout شدند یا شکست خوردند. این نیز دسترس‌پذیری **تنزل‌یافته** است، نه یک Gateway غیرقابل دسترس. + - مانند `gateway status`، کاوش از احراز هویت دستگاه کش‌شده موجود استفاده می‌کند اما هویت دستگاه بار اول یا وضعیت جفت‌سازی ایجاد نمی‌کند. + - کد خروج فقط وقتی غیرصفر است که هیچ هدف کاوش‌شده‌ای قابل دسترس نباشد. سطح بالا: - - `ok`: حداقل یک هدف در دسترس است. - - `degraded`: حداقل یک هدف اتصال را پذیرفته اما تشخیص‌های RPC جزئیات کامل را تکمیل نکرده است. - - `capability`: بهترین قابلیت دیده‌شده در میان اهداف در دسترس (`read_only`، `write_capable`، `admin_capable`، `pairing_pending`، `connected_no_operator_scope`، یا `unknown`). - - `primaryTargetId`: بهترین هدف برای در نظر گرفتن به‌عنوان برنده فعال با این ترتیب: URL صریح، تونل SSH، راه دور پیکربندی‌شده، سپس local loopback. - - `warnings[]`: رکوردهای هشدار با بهترین تلاش همراه با `code`، `message`، و `targetIds` اختیاری. - - `network`: راهنماهای URL برای local loopback/tailnet که از پیکربندی فعلی و شبکه‌بندی میزبان استخراج شده‌اند. - - `discovery.timeoutMs` و `discovery.count`: بودجه/تعداد نتیجه واقعی کشف که برای این گذر پروب استفاده شده است. + - `ok`: حداقل یک هدف قابل دسترس است. + - `degraded`: حداقل یک هدف اتصال را پذیرفت اما عیب‌یابی‌های RPC جزئیات کامل را تکمیل نکرد. + - `capability`: بهترین قابلیتی که بین هدف‌های قابل دسترس دیده شده است (`read_only`، `write_capable`، `admin_capable`، `pairing_pending`، `connected_no_operator_scope`، یا `unknown`). + - `primaryTargetId`: بهترین هدف برای در نظر گرفتن به‌عنوان برنده فعال با این ترتیب: URL صریح، تونل SSH، ریموت پیکربندی‌شده، سپس local loopback. + - `warnings[]`: رکوردهای هشدار best-effort با `code`، `message`، و `targetIds` اختیاری. + - `network`: راهنمایی‌های URL برای local loopback/tailnet مشتق‌شده از پیکربندی فعلی و شبکه میزبان. + - `discovery.timeoutMs` و `discovery.count`: بودجه/تعداد نتیجه واقعی discovery که برای این گذر کاوش استفاده شده است. برای هر هدف (`targets[].connect`): - - `ok`: دسترس‌پذیری پس از اتصال + طبقه‌بندی تنزل‌یافته. - - `rpcOk`: موفقیت کامل RPC جزئیات. - - `scopeLimited`: RPC جزئیات به دلیل نبود محدوده operator شکست خورده است. + - `ok`: دسترس‌پذیری پس از connect + طبقه‌بندی degraded. + - `rpcOk`: موفقیت RPC جزئیات کامل. + - `scopeLimited`: شکست RPC جزئیات به‌دلیل نبود محدوده operator. برای هر هدف (`targets[].auth`): - - `role`: نقش احراز هویت گزارش‌شده در `hello-ok`، وقتی موجود باشد. - - `scopes`: محدوده‌های اعطاشده گزارش‌شده در `hello-ok`، وقتی موجود باشد. - - `capability`: طبقه‌بندی قابلیت احراز هویت نمایش‌داده‌شده برای آن هدف. + - `role`: نقش احراز هویت گزارش‌شده در `hello-ok` وقتی در دسترس باشد. + - `scopes`: محدوده‌های اعطاشده گزارش‌شده در `hello-ok` وقتی در دسترس باشد. + - `capability`: طبقه‌بندی قابلیت احراز هویت ارائه‌شده برای آن هدف. - - `ssh_tunnel_failed`: راه‌اندازی تونل SSH شکست خورد؛ فرمان به پروب‌های مستقیم برگشت. - - `multiple_gateways`: بیش از یک هدف در دسترس بود؛ این غیرمعمول است مگر اینکه عمداً پروفایل‌های ایزوله، مانند یک ربات نجات، اجرا کنید. - - `auth_secretref_unresolved`: یک SecretRef احراز هویت پیکربندی‌شده برای یک هدف ناموفق قابل حل نبود. - - `probe_scope_limited`: اتصال وب‌سوکت موفق شد، اما پروب خواندن به دلیل نبود `operator.read` محدود شد. + - `ssh_tunnel_failed`: راه‌اندازی تونل SSH شکست خورد؛ فرمان به کاوش‌های مستقیم fallback کرد. + - `multiple_gateways`: بیش از یک هدف قابل دسترس بود؛ این غیرمعمول است مگر اینکه عمدا پروفایل‌های ایزوله اجرا کنید، مثل یک بات نجات. + - `auth_secretref_unresolved`: یک SecretRef احراز هویت پیکربندی‌شده برای یک هدف شکست‌خورده resolve نشد. + - `probe_scope_limited`: اتصال WebSocket موفق شد، اما کاوش خواندن به‌دلیل نبود `operator.read` محدود شد. -#### راه دور از طریق SSH (هم‌ارزی با اپ Mac) +#### ریموت از طریق SSH (برابری با برنامه Mac) -حالت «راه دور از طریق SSH» در اپ macOS از یک فوروارد پورت محلی استفاده می‌کند تا Gateway راه دور (که ممکن است فقط به loopback متصل شده باشد) در `ws://127.0.0.1:` در دسترس شود. +حالت "Remote over SSH" در برنامه macOS از یک port-forward محلی استفاده می‌کند تا gateway ریموت (که ممکن است فقط به loopback bind شده باشد) در `ws://127.0.0.1:` قابل دسترس شود. معادل CLI: @@ -390,23 +390,23 @@ openclaw gateway probe --ssh user@gateway-host ``` - `user@host` یا `user@host:port` (پورت به‌طور پیش‌فرض `22` است). + `user@host` یا `user@host:port` (port به‌طور پیش‌فرض `22` است). فایل هویت. - اولین میزبان Gateway کشف‌شده را از نقطه پایانی کشف حل‌شده (`local.` به‌علاوه دامنه گستره‌وسیع پیکربندی‌شده، اگر وجود داشته باشد) به‌عنوان هدف SSH انتخاب کنید. راهنماهای فقط TXT نادیده گرفته می‌شوند. + نخستین میزبان gateway کشف‌شده را از endpoint کشف resolveشده (`local.` به‌علاوه دامنه wide-area پیکربندی‌شده، اگر وجود داشته باشد) به‌عنوان هدف SSH انتخاب کنید. راهنمایی‌های فقط TXT نادیده گرفته می‌شوند. -پیکربندی (اختیاری، به‌عنوان پیش‌فرض استفاده می‌شود): +پیکربندی (اختیاری، استفاده‌شده به‌عنوان پیش‌فرض): - `gateway.remote.sshTarget` - `gateway.remote.sshIdentity` ### `gateway call ` -کمک‌رسان سطح‌پایین RPC. +کمک‌کننده RPC سطح پایین. ```bash openclaw gateway call status @@ -414,10 +414,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' ``` - رشته شیء JSON برای پارامترها. + رشته شیء JSON برای params. - URL وب‌سوکت Gateway. + URL مربوط به WebSocket برای Gateway. توکن Gateway. @@ -426,10 +426,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' گذرواژه Gateway. - بودجه مهلت زمانی. + بودجه timeout. - عمدتاً برای RPCهای سبک عامل که رویدادهای میانی را پیش از محموله نهایی به‌صورت جریان ارسال می‌کنند. + عمدتا برای RPCهای سبک agent که پیش از payload نهایی eventهای میانی را stream می‌کنند. خروجی JSON قابل خواندن توسط ماشین. @@ -449,9 +449,9 @@ openclaw gateway restart openclaw gateway uninstall ``` -### نصب با یک پوشش‌دهنده +### نصب با wrapper -وقتی سرویس مدیریت‌شده باید از طریق اجرایی دیگری شروع شود، از `--wrapper` استفاده کنید؛ برای مثال یک شیم مدیر اسرار یا کمک‌رسان اجرای با کاربر دیگر. پوشش‌دهنده آرگومان‌های عادی Gateway را دریافت می‌کند و مسئول است در نهایت `openclaw` یا Node را با آن آرگومان‌ها اجرا کند. +وقتی سرویس مدیریت‌شده باید از طریق یک executable دیگر شروع شود، مثلا یک shim مدیریت secrets یا یک کمک‌کننده run-as، از `--wrapper` استفاده کنید. wrapper آرگومان‌های عادی Gateway را دریافت می‌کند و مسئول است در نهایت `openclaw` یا Node را با همان آرگومان‌ها exec کند. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -465,14 +465,14 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -همچنین می‌توانید پوشش‌دهنده را از طریق محیط تنظیم کنید. `gateway install` اعتبارسنجی می‌کند که مسیر یک فایل اجرایی باشد، پوشش‌دهنده را در `ProgramArguments` سرویس می‌نویسد، و `OPENCLAW_WRAPPER` را در محیط سرویس برای نصب‌های اجباری دوباره، به‌روزرسانی‌ها، و تعمیرهای doctor بعدی پایدار می‌کند. +همچنین می‌توانید wrapper را از طریق environment تنظیم کنید. `gateway install` اعتبارسنجی می‌کند که مسیر یک فایل executable است، wrapper را در `ProgramArguments` سرویس می‌نویسد، و `OPENCLAW_WRAPPER` را در environment سرویس برای نصب‌های مجدد اجباری، به‌روزرسانی‌ها، و تعمیرهای doctor بعدی پایدار می‌کند. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force openclaw doctor ``` -برای حذف یک پوشش‌دهنده پایدارشده، هنگام نصب دوباره `OPENCLAW_WRAPPER` را پاک کنید: +برای حذف wrapper پایدارشده، هنگام نصب مجدد `OPENCLAW_WRAPPER` را پاک کنید: ```bash OPENCLAW_WRAPPER= openclaw gateway install --force @@ -481,47 +481,48 @@ openclaw gateway restart - - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` - - `gateway restart`: `--force`, `--wait `, `--json` + - `gateway status`: `--url`، `--token`، `--password`، `--timeout`، `--no-probe`، `--require-rpc`، `--deep`، `--json` + - `gateway install`: `--port`، `--runtime `، `--token`، `--wrapper `، `--force`، `--json` + - `gateway restart`: `--safe`، `--force`، `--wait `، `--json` - `gateway uninstall|start|stop`: `--json` - - برای restart کردن یک سرویس مدیریت‌شده از `gateway restart` استفاده کنید. `gateway stop` و `gateway start` را به‌عنوان جایگزین restart زنجیره نکنید؛ در macOS، `gateway stop` عمداً LaunchAgent را پیش از توقف آن غیرفعال می‌کند. - - `gateway restart --wait 30s` بودجه تخلیه restart پیکربندی‌شده را برای آن restart بازنویسی می‌کند. عددهای تنها میلی‌ثانیه هستند؛ واحدهایی مانند `s`، `m`، و `h` پذیرفته می‌شوند. `--wait 0` به‌طور نامحدود منتظر می‌ماند. - - `gateway restart --force` تخلیه کار فعال را رد می‌کند و فوراً restart می‌کند. وقتی یک اپراتور مسدودکننده‌های وظیفه فهرست‌شده را از قبل بررسی کرده و اکنون می‌خواهد gateway برگردد، از آن استفاده کنید. - - فرمان‌های چرخه عمر برای اسکریپت‌نویسی `--json` را می‌پذیرند. + - برای راه‌اندازی مجدد یک سرویس مدیریت‌شده از `gateway restart` استفاده کنید. `gateway stop` و `gateway start` را به‌عنوان جایگزین restart زنجیره نکنید؛ در macOS، `gateway stop` عمدا LaunchAgent را پیش از توقف آن غیرفعال می‌کند. + - `gateway restart --safe` از Gateway در حال اجرا می‌خواهد کار فعال OpenClaw را preflight کند و restart را تا تخلیه شدن تحویل پاسخ، اجراهای embedded، و اجراهای task به تعویق بیندازد. `--safe` را نمی‌توان با `--force` یا `--wait` ترکیب کرد. + - `gateway restart --wait 30s` بودجه drain پیکربندی‌شده برای آن restart را override می‌کند. اعداد بدون واحد میلی‌ثانیه هستند؛ واحدهایی مثل `s`، `m`، و `h` پذیرفته می‌شوند. `--wait 0` به‌طور نامحدود منتظر می‌ماند. + - `gateway restart --force` از drain کار فعال صرف‌نظر می‌کند و فورا restart می‌کند. وقتی operator پیش‌تر task blockerهای فهرست‌شده را بررسی کرده و اکنون gateway را دوباره می‌خواهد، از آن استفاده کنید. + - فرمان‌های چرخه عمر `--json` را برای اسکریپت‌نویسی می‌پذیرند. - - - وقتی احراز هویت با توکن به توکن نیاز دارد و `gateway.auth.token` با SecretRef مدیریت می‌شود، `gateway install` اعتبارسنجی می‌کند که SecretRef قابل حل باشد اما توکن حل‌شده را در فراداده محیط سرویس پایدار نمی‌کند. - - اگر احراز هویت با توکن به توکن نیاز داشته باشد و SecretRef توکن پیکربندی‌شده حل‌نشده باشد، نصب به‌صورت بسته شکست می‌خورد به جای اینکه متن ساده جایگزین را پایدار کند. - - برای احراز هویت با گذرواژه در `gateway run`، `OPENCLAW_GATEWAY_PASSWORD`، `--password-file`، یا `gateway.auth.password` مبتنی بر SecretRef را به `--password` درون‌خطی ترجیح دهید. - - در حالت احراز هویت استنباطی، `OPENCLAW_GATEWAY_PASSWORD` فقط در پوسته الزامات توکن نصب را کاهش نمی‌دهد؛ هنگام نصب یک سرویس مدیریت‌شده از پیکربندی پایدار (`gateway.auth.password` یا `env` پیکربندی) استفاده کنید. - - اگر هر دو `gateway.auth.token` و `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که mode صریحاً تنظیم شود مسدود می‌شود. + + - وقتی احراز هویت توکنی به یک توکن نیاز دارد و `gateway.auth.token` با SecretRef مدیریت می‌شود، `gateway install` بررسی می‌کند که SecretRef قابل resolve باشد، اما توکن resolveشده را در فرادادهٔ محیط سرویس ذخیره نمی‌کند. + - اگر احراز هویت توکنی به یک توکن نیاز داشته باشد و SecretRef توکن پیکربندی‌شده resolve نشده باشد، نصب به‌صورت بسته شکست می‌خورد و متن سادهٔ جایگزین ذخیره نمی‌شود. + - برای احراز هویت با رمز عبور در `gateway run`، به‌جای `--password` درون‌خطی، `OPENCLAW_GATEWAY_PASSWORD`، `--password-file`، یا `gateway.auth.password` پشتیبانی‌شده با SecretRef را ترجیح دهید. + - در حالت احراز هویت استنباط‌شده، `OPENCLAW_GATEWAY_PASSWORD` فقط در shell الزامات توکن نصب را سست نمی‌کند؛ هنگام نصب یک سرویس مدیریت‌شده، از پیکربندی پایدار (`gateway.auth.password` یا `env` پیکربندی) استفاده کنید. + - اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، نصب تا زمانی که حالت به‌صراحت تنظیم شود مسدود می‌شود. ## کشف Gatewayها (Bonjour) -`gateway discover` بیکن‌های Gateway (`_openclaw-gw._tcp`) را اسکن می‌کند. +`gateway discover` برای بیکن‌های Gateway (`_openclaw-gw._tcp`) اسکن می‌کند. - DNS-SD چندپخشی: `local.` -- DNS-SD تک‌پخشی (Wide-Area Bonjour): یک دامنه انتخاب کنید (مثال: `openclaw.internal.`) و split DNS + یک سرور DNS راه‌اندازی کنید؛ [Bonjour](/fa/gateway/bonjour) را ببینید. +- DNS-SD تک‌پخشی (Bonjour گسترده): یک دامنه انتخاب کنید (مثال: `openclaw.internal.`) و split DNS + یک سرور DNS را راه‌اندازی کنید؛ [Bonjour](/fa/gateway/bonjour) را ببینید. -فقط Gatewayهایی که کشف Bonjour در آن‌ها فعال است (پیش‌فرض) beacon را تبلیغ می‌کنند. +فقط Gatewayهایی که کشف Bonjour برای آن‌ها فعال است (پیش‌فرض)، بیکن را تبلیغ می‌کنند. -رکوردهای کشف Wide-Area شامل این موارد هستند (TXT): +رکوردهای کشف گسترده شامل این موارد هستند (TXT): - `role` (راهنمای نقش Gateway) -- `transport` (راهنمای transport، مثلاً `gateway`) +- `transport` (راهنمای transport، برای مثال `gateway`) - `gatewayPort` (پورت WebSocket، معمولاً `18789`) -- `sshPort` (اختیاری؛ وقتی وجود نداشته باشد، کلاینت‌ها هدف‌های پیش‌فرض SSH را `22` در نظر می‌گیرند) -- `tailnetDns` (نام میزبان MagicDNS، در صورت موجود بودن) -- `gatewayTls` / `gatewayTlsSha256` (TLS فعال + اثرانگشت گواهی) -- `cliPath` (راهنمای نصب از راه دور که در zone گسترده‌محدوده نوشته می‌شود) +- `sshPort` (اختیاری؛ وقتی وجود نداشته باشد، کلاینت‌ها اهداف SSH را به‌طور پیش‌فرض `22` می‌گذارند) +- `tailnetDns` (نام میزبان MagicDNS، وقتی در دسترس باشد) +- `gatewayTls` / `gatewayTlsSha256` (TLS فعال + اثر انگشت گواهی) +- `cliPath` (راهنمای نصب راه دور که در ناحیهٔ گسترده نوشته می‌شود) ### `gateway discover` @@ -530,10 +531,10 @@ openclaw gateway discover ``` - مهلت زمانی هر فرمان (browse/resolve). + مهلت زمانی هر دستور (browse/resolve). - خروجی قابل خواندن توسط ماشین (همچنین استایل‌دهی/چرخنده را غیرفعال می‌کند). + خروجی قابل خواندن برای ماشین (همچنین سبک‌دهی/spinner را غیرفعال می‌کند). مثال‌ها: @@ -544,13 +545,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- CLI علاوه بر `local.`، دامنه گسترده‌محدوده پیکربندی‌شده را نیز هنگام فعال بودن اسکن می‌کند. -- `wsUrl` در خروجی JSON از endpoint سرویس resolve‌شده مشتق می‌شود، نه از راهنماهای فقط-TXT مانند `lanHost` یا `tailnetDns`. -- در mDNS مربوط به `local.`، `sshPort` و `cliPath` فقط وقتی broadcast می‌شوند که `discovery.mdns.mode` برابر `full` باشد. DNS-SD گسترده‌محدوده همچنان `cliPath` را می‌نویسد؛ `sshPort` آنجا هم اختیاری می‌ماند. +- CLI وقتی یک دامنهٔ گستردهٔ پیکربندی‌شده فعال باشد، `local.` به‌علاوهٔ آن دامنه را اسکن می‌کند. +- `wsUrl` در خروجی JSON از نقطهٔ پایانی سرویس resolveشده مشتق می‌شود، نه از راهنماهای فقط TXT مانند `lanHost` یا `tailnetDns`. +- در mDNS مربوط به `local.`، `sshPort` و `cliPath` فقط وقتی broadcast می‌شوند که `discovery.mdns.mode` برابر `full` باشد. DNS-SD گسترده همچنان `cliPath` را می‌نویسد؛ `sshPort` آنجا هم اختیاری می‌ماند. ## مرتبط - [مرجع CLI](/fa/cli) -- [راهنمای عملیاتی Gateway](/fa/gateway) +- [Runbook Gateway](/fa/gateway) diff --git a/docs/fa/cli/plugins.md b/docs/fa/cli/plugins.md index 9fe0bee3d..07399c0d7 100644 --- a/docs/fa/cli/plugins.md +++ b/docs/fa/cli/plugins.md @@ -1,40 +1,40 @@ --- read_when: - - می‌خواهید Pluginهای Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید + - می‌خواهید Plugin‌های Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید - می‌خواهید خرابی‌های بارگذاری Plugin را اشکال‌زدایی کنید sidebarTitle: Plugins -summary: مرجع CLI برای `openclaw plugins` (فهرست، نصب، بازارچه، حذف نصب، فعال‌سازی/غیرفعال‌سازی، عیب‌یابی) -title: Plugin‌ها +summary: مرجع CLI برای `openclaw plugins` (list، install، marketplace، uninstall، enable/disable، doctor) +title: Pluginها x-i18n: - generated_at: "2026-05-04T09:37:15Z" + generated_at: "2026-05-05T01:44:26Z" model: gpt-5.5 provider: openai - source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4 + source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a source_path: cli/plugins.md workflow: 16 --- -مدیریت Pluginهای Gateway، بسته‌های hook، و bundleهای سازگار. +مدیریت Pluginهای Gateway، بسته‌های hook، و باندل‌های سازگار. راهنمای کاربر نهایی برای نصب، فعال‌سازی، و عیب‌یابی Pluginها. - نمونه‌های سریع برای نصب، فهرست، به‌روزرسانی، حذف نصب، و انتشار. + نمونه‌های سریع برای نصب، فهرست‌کردن، به‌روزرسانی، حذف نصب، و انتشار. - - مدل سازگاری bundle. + + مدل سازگاری باندل. - - فیلدهای manifest و طرح‌واره پیکربندی. + + فیلدهای مانیفست و طرح‌واره پیکربندی. سخت‌سازی امنیتی برای نصب Pluginها. -## دستورها +## فرمان‌ها ```bash openclaw plugins list @@ -62,100 +62,90 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -برای بررسی نصب، inspect، حذف نصب، یا تازه‌سازی registry که کند است، دستور را با -`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی مرحله‌ها را در -stderr می‌نویسد و خروجی JSON را قابل تجزیه نگه می‌دارد. [اشکال‌زدایی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید. +برای بررسی نصب، بازرسی، حذف نصب، یا تازه‌سازی رجیستری که کند انجام می‌شود، فرمان را با `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل parse نگه می‌دارد. [اشکال‌زدایی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید. -Pluginهای bundle‌شده همراه OpenClaw ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال هستند (برای مثال ارائه‌دهندگان مدل bundle‌شده، ارائه‌دهندگان گفتار bundle‌شده، و Plugin مرورگر bundle‌شده)؛ برخی دیگر به `plugins enable` نیاز دارند. +Pluginهای باندل‌شده همراه OpenClaw ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال‌اند (برای مثال ارائه‌دهنده‌های مدل باندل‌شده، ارائه‌دهنده‌های گفتار باندل‌شده، و Plugin مرورگر باندل‌شده)؛ برخی دیگر به `plugins enable` نیاز دارند. -Pluginهای native OpenClaw باید `openclaw.plugin.json` را همراه با یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. bundleهای سازگار به‌جای آن از manifestهای bundle خودشان استفاده می‌کنند. +Pluginهای بومی OpenClaw باید `openclaw.plugin.json` را همراه با یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. باندل‌های سازگار به‌جای آن از مانیفست‌های باندل خودشان استفاده می‌کنند. -`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی verbose فهرست/info همچنین زیرنوع bundle (`codex`، `claude`، یا `cursor`) و قابلیت‌های bundle شناسایی‌شده را نشان می‌دهد. +`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی مفصل list/info همچنین زیرنوع باندل (`codex`، `claude`، یا `cursor`) به‌همراه قابلیت‌های باندل شناسایی‌شده را نشان می‌دهد. ### نصب ```bash -openclaw plugins search "calendar" # جست‌وجوی Pluginهای ClawHub -openclaw plugins install # npm به‌صورت پیش‌فرض -openclaw plugins install clawhub: # فقط ClawHub -openclaw plugins install npm: # فقط npm -openclaw plugins install git:github.com// # مخزن git +openclaw plugins search "calendar" # search ClawHub plugins +openclaw plugins install # npm by default +openclaw plugins install clawhub: # ClawHub only +openclaw plugins install npm: # npm only +openclaw plugins install git:github.com// # git repo openclaw plugins install git:github.com//@ -openclaw plugins install --force # بازنویسی نصب موجود -openclaw plugins install --pin # سنجاق کردن نسخه +openclaw plugins install --force # overwrite existing install +openclaw plugins install --pin # pin version openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins install # مسیر محلی +openclaw plugins install # local path openclaw plugins install @ # marketplace -openclaw plugins install --marketplace # marketplace (صریح) +openclaw plugins install --marketplace # marketplace (explicit) openclaw plugins install --marketplace https://github.com// ``` -در دوره انتقال راه‌اندازی، نام‌های خام package به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:` استفاده کنید. نصب Pluginها را مانند اجرای کد در نظر بگیرید. نسخه‌های سنجاق‌شده را ترجیح دهید. +نام‌های بسته ساده در دوره گذار راه‌اندازی به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:` استفاده کنید. نصب Pluginها را مانند اجرای کد در نظر بگیرید. نسخه‌های pin‌شده را ترجیح دهید. -`plugins search` از ClawHub برای packageهای Plugin قابل نصب پرس‌وجو می‌کند و -نام packageهای آماده نصب را چاپ می‌کند. این دستور packageهای code-plugin و bundle-plugin را جست‌وجو می‌کند، -نه Skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید. +`plugins search` در ClawHub برای بسته‌های Plugin قابل نصب جست‌وجو می‌کند و نام بسته‌های آماده نصب را چاپ می‌کند. این فرمان بسته‌های code-plugin و bundle-plugin را جست‌وجو می‌کند، نه Skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید. -ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. Npm -همچنان به‌عنوان fallback پشتیبانی‌شده و مسیر نصب مستقیم باقی می‌ماند. packageهای Plugin متعلق به OpenClaw با نام -`@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در -[npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا -[موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. -نصب‌ها و به‌روزرسانی‌های کانال beta وقتی tag مربوطه موجود باشد، dist-tag مربوط به npm یعنی `beta` را ترجیح می‌دهند -و سپس به `latest` برمی‌گردند. +ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. npm همچنان یک مسیر fallback و نصب مستقیم پشتیبانی‌شده است. بسته‌های Plugin متعلق به OpenClaw با الگوی `@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا [موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. نصب‌ها و به‌روزرسانی‌های کانال بتا، وقتی تگ موجود باشد، dist-tag با نام `beta` در npm را ترجیح می‌دهند و سپس به `latest` fallback می‌کنند. - اگر بخش `plugins` شما با یک `$include` تک‌فایلی پشتیبانی شود، `plugins install/update/enable/disable/uninstall` تغییرات را در همان فایل include‌شده می‌نویسد و `openclaw.json` را دست‌نخورده می‌گذارد. includeهای ریشه، آرایه‌های include، و includeهایی با overrideهای هم‌سطح به‌جای flatten شدن، بسته و ناموفق می‌شوند. برای شکل‌های پشتیبانی‌شده، [includeهای پیکربندی](/fa/gateway/configuration) را ببینید. + اگر بخش `plugins` شما توسط یک `$include` تک‌فایلی پشتیبانی شود، `plugins install/update/enable/disable/uninstall` تغییرات را در همان فایل include‌شده می‌نویسد و `openclaw.json` را دست‌نخورده می‌گذارد. includeهای ریشه، آرایه‌های include، و includeهایی با overrideهای هم‌سطح، به‌جای flatten شدن، fail closed می‌شوند. برای شکل‌های پشتیبانی‌شده، [includeهای پیکربندی](/fa/gateway/configuration) را ببینید. - اگر پیکربندی هنگام نصب نامعتبر باشد، `plugins install` معمولاً بسته و ناموفق می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و reload داغ، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری بسته و ناموفق می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستند در زمان نصب، یک مسیر بازیابی محدود برای Pluginهای bundle‌شده است که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را فعال کرده‌اند. + اگر هنگام نصب، پیکربندی نامعتبر باشد، `plugins install` معمولاً fail closed می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و hot reload، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری fail closed می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستند در زمان نصب، یک مسیر بازیابی محدود برای Plugin باندل‌شده است، برای Pluginهایی که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را فعال کرده‌اند. - - `--force` هدف نصب موجود را دوباره استفاده می‌کند و یک Plugin یا بسته hook ازقبل‌نصب‌شده را درجا بازنویسی می‌کند. زمانی از آن استفاده کنید که عمداً همان id را از یک مسیر محلی جدید، archive، package در ClawHub، یا artifact در npm دوباره نصب می‌کنید. برای ارتقاهای معمول یک Plugin npm که از قبل رهگیری می‌شود، `openclaw plugins update ` را ترجیح دهید. + + `--force` از هدف نصب موجود دوباره استفاده می‌کند و یک Plugin یا بسته hook از قبل نصب‌شده را در همان محل بازنویسی می‌کند. وقتی عمداً همان id را از یک مسیر محلی جدید، آرشیو، بسته ClawHub، یا artifact در npm دوباره نصب می‌کنید، از آن استفاده کنید. برای ارتقاهای روتین یک Plugin در npm که از قبل رهگیری می‌شود، `openclaw plugins update ` را ترجیح دهید. - اگر `plugins install` را برای یک id مربوط به Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update ` راهنمایی می‌کند، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید، به `plugins install --force` اشاره می‌کند. + اگر `plugins install` را برای id یک Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update `، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید به `plugins install --force` راهنمایی می‌کند. - `--pin` فقط برای نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع سنجاق‌شده می‌خواهید، از ref صریح git مانند `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای spec مربوط به npm، فراداده منبع marketplace را پایدار می‌کنند. + `--pin` فقط روی نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع pin‌شده می‌خواهید، از یک ref صریح git مانند `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای spec در npm، فراداده منبع marketplace را پایدار نگه می‌دارند. - `--dangerously-force-unsafe-install` گزینه‌ای اضطراری برای مثبت‌های کاذب در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه یابد، اما بلوک‌های سیاست hook مربوط به `before_install` در Plugin را دور نمی‌زند و شکست‌های اسکن را نیز دور نمی‌زند. + `--dangerously-force-unsafe-install` گزینه break-glass برای false positiveها در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه یابد، اما مسدودسازی‌های سیاست hook با نام `before_install` در Plugin را دور نمی‌زند و failureهای اسکن را هم دور نمی‌زند. - این flag در CLI برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skills که از Gateway پشتیبانی می‌شوند از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کنند، درحالی‌که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skill از ClawHub است. + این پرچم CLI روی جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب وابستگی Skills مبتنی بر Gateway از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کند، در حالی‌که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skill از ClawHub است. - اگر Pluginی که در ClawHub منتشر کرده‌اید به‌دلیل اسکن registry مسدود شده است، از مراحل ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید. + اگر Pluginی که در ClawHub منتشر کرده‌اید توسط اسکن رجیستری مسدود شده، از گام‌های ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید. - `plugins install` سطح نصب برای بسته‌های hook نیز هست که `openclaw.hooks` را در `package.json` ارائه می‌کنند. برای نمایان‌سازی hookهای فیلترشده و فعال‌سازی هر hook از `openclaw hooks` استفاده کنید، نه برای نصب package. + `plugins install` همچنین سطح نصب برای بسته‌های hook است که `openclaw.hooks` را در `package.json` ارائه می‌کنند. برای مشاهده hookهای فیلترشده و فعال‌سازی هر hook، از `openclaw hooks` استفاده کنید، نه برای نصب بسته. - specهای npm **فقط registry** هستند (نام package + نسخه **دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و بازه‌های semver رد می‌شوند. نصب‌های وابستگی برای ایمنی به‌صورت project-local و با `--ignore-scripts` اجرا می‌شوند، حتی وقتی shell شما تنظیمات نصب سراسری npm دارد. + specهای npm **فقط رجیستری** هستند (نام بسته + **نسخه دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و بازه‌های semver رد می‌شوند. نصب‌های وابستگی برای ایمنی به‌صورت محلی در پروژه و با `--ignore-scripts` اجرا می‌شوند، حتی وقتی shell شما تنظیمات نصب سراسری npm دارد. - وقتی می‌خواهید resolution مربوط به npm را صریح کنید، از `npm:` استفاده کنید. در دوره انتقال راه‌اندازی، specهای خام package نیز مستقیماً از npm نصب می‌شوند. + وقتی می‌خواهید resolution در npm را صریح کنید، از `npm:` استفاده کنید. در دوره گذار راه‌اندازی، specهای بسته ساده نیز مستقیماً از npm نصب می‌شوند. - specهای خام و `@latest` روی مسیر پایدار می‌مانند. نسخه‌های اصلاحی تاریخ‌دار OpenClaw مانند `2026.5.3-1` برای این بررسی releaseهای پایدار هستند. اگر npm هرکدام از این‌ها را به یک prerelease resolve کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک tag مربوط به prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صراحتاً opt in کنید. + specهای ساده و `@latest` روی مسیر پایدار می‌مانند. نسخه‌های اصلاحی تاریخ‌دار OpenClaw مانند `2026.5.3-1` برای این بررسی releaseهای پایدار هستند. اگر npm هرکدام از آن‌ها را به یک prerelease resolve کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک تگ prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صراحتاً opt in کنید. - اگر یک spec نصب خام با id رسمی Plugin مطابقت داشته باشد (برای مثال `diffs`)، OpenClaw ورودی کاتالوگ را مستقیماً نصب می‌کند. برای نصب یک package در npm با همان نام، از spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`). + اگر یک spec نصب ساده با id یک Plugin رسمی مطابقت داشته باشد (برای مثال `diffs`)، OpenClaw ورودی کاتالوگ را مستقیماً نصب می‌کند. برای نصب یک بسته npm با همان نام، از یک spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`). - برای نصب مستقیم از یک مخزن git از `git:` استفاده کنید. شکل‌های پشتیبانی‌شده شامل `git:github.com/owner/repo`، `git:owner/repo`، نشانی‌های clone کامل `https://`، `ssh://`، `git://`، `file://`، و `git@host:owner/repo.git` هستند. برای check out کردن یک branch، tag، یا commit پیش از نصب، `@` یا `#` را اضافه کنید. + برای نصب مستقیم از یک مخزن git از `git:` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با الگوهای `git:github.com/owner/repo`، `git:owner/repo`، کامل `https://`، `ssh://`، `git://`، `file://`، و `git@host:owner/repo.git` هستند. برای checkout کردن یک branch، tag، یا commit پیش از نصب، `@` یا `#` اضافه کنید. - نصب‌های Git در یک دایرکتوری موقت clone می‌شوند، در صورت وجود ref درخواستی آن را check out می‌کنند، سپس از نصب‌کننده عادی دایرکتوری Plugin استفاده می‌کنند. یعنی اعتبارسنجی manifest، اسکن کد خطرناک، کار نصب package-manager، و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit resolve‌شده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند. + نصب‌های Git در یک دایرکتوری موقت clone می‌شوند، اگر ref درخواست‌شده وجود داشته باشد آن را check out می‌کنند، سپس از نصب‌کننده عادی دایرکتوری Plugin استفاده می‌کنند. یعنی اعتبارسنجی مانیفست، اسکن کد خطرناک، کار نصب package-manager، و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit resolve‌شده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند. - پس از نصب از git، از `openclaw plugins inspect --runtime --json` برای تأیید registrationهای runtime مانند متدهای gateway و دستورهای CLI استفاده کنید. اگر Plugin یک root در CLI با `api.registerCli` ثبت کرده است، آن دستور را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`. + پس از نصب از git، برای تأیید registrationهای runtime مانند متدهای gateway و فرمان‌های CLI از `openclaw plugins inspect --runtime --json` استفاده کنید. اگر Plugin با `api.registerCli` یک ریشه CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`. - - archiveهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. archiveهای native Plugin در OpenClaw باید یک `openclaw.plugin.json` معتبر در ریشه Plugin استخراج‌شده داشته باشند؛ archiveهایی که فقط `package.json` دارند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند. + + آرشیوهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. آرشیوهای Plugin بومی OpenClaw باید یک `openclaw.plugin.json` معتبر در ریشه Plugin استخراج‌شده داشته باشند؛ آرشیوهایی که فقط `package.json` دارند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند. نصب‌های marketplace مربوط به Claude نیز پشتیبانی می‌شوند. @@ -169,32 +159,32 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -در دوره انتقال راه‌اندازی، specهای Plugin سازگار با npm به‌صورت پیش‌فرض از npm نصب می‌شوند: +specهای Plugin ساده و امن برای npm در دوره گذار راه‌اندازی به‌صورت پیش‌فرض از npm نصب می‌شوند: ```bash openclaw plugins install openclaw-codex-app-server ``` -برای صریح کردن resolution فقط npm از `npm:` استفاده کنید: +برای صریح کردن resolution فقط از npm، از `npm:` استفاده کنید: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw پیش از نصب، API اعلام‌شده Plugin / حداقل سازگاری gateway را بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact مربوط به ClawPack منتشر می‌کند، OpenClaw فایل `.tgz` مربوط به npm-pack نسخه‌دار را دانلود می‌کند، header مربوط به digest در ClawHub و digest مربوط به artifact را تأیید می‌کند، سپس آن را از مسیر عادی archive نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون فراداده ClawPack همچنان از مسیر قدیمی اعتبارسنجی archive package نصب می‌شوند. نصب‌های ثبت‌شده فراداده منبع ClawHub، نوع artifact، integrity مربوط به npm، shasum مربوط به npm، نام tarball، و facts مربوط به digest در ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند. -نصب‌های بدون نسخه ClawHub یک spec ثبت‌شده بدون نسخه نگه می‌دارند تا `openclaw plugins update` بتواند releaseهای جدیدتر ClawHub را دنبال کند؛ selectorهای نسخه یا tag صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` به همان selector سنجاق‌شده باقی می‌مانند. +OpenClaw پیش از نصب، سازگاری API اعلام‌شده Plugin / حداقل gateway را بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact از نوع ClawPack منتشر کند، OpenClaw فایل `.tgz` نسخه‌دار npm-pack را دانلود می‌کند، header digest مربوط به ClawHub و digest مربوط به artifact را تأیید می‌کند، سپس آن را از مسیر عادی آرشیو نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون فراداده ClawPack همچنان از مسیر قدیمی تأیید آرشیو بسته نصب می‌شوند. نصب‌های ثبت‌شده فراداده منبع ClawHub، نوع artifact، integrity در npm، shasum در npm، نام tarball، و داده‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند. +نصب‌های ClawHub بدون نسخه، یک spec ثبت‌شده بدون نسخه نگه می‌دارند تا `openclaw plugins update` بتواند releaseهای جدیدتر ClawHub را دنبال کند؛ selectorهای نسخه یا تگ صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` همچنان به همان selector pin می‌مانند. #### shorthand مربوط به Marketplace -وقتی نام marketplace در cache محلی registry مربوط به Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از shorthand به‌شکل `plugin@marketplace` استفاده کنید: +وقتی نام marketplace در cache رجیستری محلی Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از shorthand با الگوی `plugin@marketplace` استفاده کنید: ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -وقتی می‌خواهید منبع marketplace را صریح ارسال کنید، از `--marketplace` استفاده کنید: +وقتی می‌خواهید منبع marketplace را صریحاً ارسال کنید، از `--marketplace` استفاده کنید: ```bash openclaw plugins install --marketplace @@ -204,28 +194,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - + - نام marketplace شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json` - ریشه marketplace محلی یا مسیر `marketplace.json` - - خلاصه مخزن GitHub مانند `owner/repo` + - کوتاه‌نوشت مخزن GitHub مانند `owner/repo` - URL مخزن GitHub مانند `https://github.com/owner/repo` - یک URL گیت - - برای marketplaceهای راه‌دور که از GitHub یا گیت بارگذاری می‌شوند، ورودی‌های plugin باید داخل مخزن marketplace شبیه‌سازی‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از همان مخزن می‌پذیرد و منابع Plugin از نوع HTTP(S)، مسیر مطلق، گیت، GitHub و دیگر منابع غیرمسیری را از manifestهای راه‌دور رد می‌کند. + + برای marketplaceهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از آن مخزن می‌پذیرد و منابع Plugin از نوع HTTP(S)، مسیر مطلق، git، GitHub و دیگر منابع غیرمسیر را از manifestهای راه‌دور رد می‌کند. -برای مسیرها و آرشیوهای محلی، OpenClaw به‌صورت خودکار تشخیص می‌دهد: +برای مسیرها و آرشیوهای محلی، OpenClaw به‌طور خودکار تشخیص می‌دهد: -- pluginهای بومی OpenClaw (`openclaw.plugin.json`) +- Pluginهای بومی OpenClaw (`openclaw.plugin.json`) - بسته‌های سازگار با Codex (`.codex-plugin/plugin.json`) -- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه Claude) +- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه‌های Claude) - بسته‌های سازگار با Cursor (`.cursor-plugin/plugin.json`) -بسته‌های سازگار در ریشه معمول plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. در حال حاضر، Skills بسته، command-skills کلود، پیش‌فرض‌های `settings.json` کلود، پیش‌فرض‌های `.lsp.json` کلود / `lspServers` اعلام‌شده در manifest، command-skills کِرسِر، و دایرکتوری‌های hook سازگار Codex پشتیبانی می‌شوند؛ قابلیت‌های دیگر بسته که تشخیص داده می‌شوند در diagnostics/info نمایش داده می‌شوند اما هنوز به اجرای زمان اجرا متصل نشده‌اند. +بسته‌های سازگار در ریشه عادی Plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. امروز، Skills بسته، command-skills مربوط به Claude، پیش‌فرض‌های `settings.json` مربوط به Claude، پیش‌فرض‌های `.lsp.json` مربوط به Claude / `lspServers` اعلام‌شده در manifest، command-skills مربوط به Cursor، و دایرکتوری‌های hook سازگار با Codex پشتیبانی می‌شوند؛ قابلیت‌های دیگر بسته که تشخیص داده می‌شوند در diagnostics/info نمایش داده می‌شوند اما هنوز به اجرای runtime وصل نشده‌اند. ### فهرست @@ -241,48 +231,49 @@ openclaw plugins search --json ``` - فقط pluginهای فعال‌شده را نشان بده. + فقط Pluginهای فعال‌شده را نشان بده. - از نمای جدول به خط‌های جزئیات جداگانه برای هر plugin با فراداده‌های منبع/خاستگاه/نسخه/فعال‌سازی جابه‌جا شو. + از نمای جدول به خطوط جزئیات جداگانه برای هر Plugin با فراداده منبع/خاستگاه/نسخه/فعال‌سازی جابه‌جا شو. - موجودی قابل‌خواندن برای ماشین به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های package. + موجودی قابل‌خواندن برای ماشین، به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های بسته. -`plugins list` ابتدا رجیستری plugin محلی پایدارشده را می‌خواند و وقتی رجیستری موجود نباشد یا نامعتبر باشد، از fallback مشتق‌شده فقط از manifest استفاده می‌کند. این دستور برای بررسی اینکه آیا یک plugin نصب، فعال و برای برنامه‌ریزی راه‌اندازی سرد قابل مشاهده است مفید است، اما یک probe زنده زمان اجرا از فرایند Gateway ازپیش‌درحال‌اجرا نیست. پس از تغییر کد plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار برای اجرای کد `register(api)` یا hookهای جدید، Gatewayی را که channel را سرویس می‌دهد راه‌اندازی مجدد کنید. برای استقرارهای راه‌دور/کانتینری، بررسی کنید که فرزند واقعی `openclaw gateway run` را راه‌اندازی مجدد می‌کنید، نه فقط یک فرایند wrapper. +`plugins list` ابتدا رجیستری Plugin محلی پایدارشده را می‌خواند و وقتی رجیستری موجود نباشد یا نامعتبر باشد از fallback مشتق‌شده فقط از manifest استفاده می‌کند. این دستور برای بررسی اینکه آیا یک Plugin نصب، فعال، و برای برنامه‌ریزی راه‌اندازی سرد قابل‌مشاهده است مفید است، اما یک probe زنده runtime از فرایند Gateway ازپیش‌درحال‌اجرا نیست. پس از تغییر کد Plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار برای اجرای کد `register(api)` یا hookهای جدید، Gatewayای را که به کانال سرویس می‌دهد بازراه‌اندازی کنید. برای استقرارهای راه‌دور/کانتینری، بررسی کنید که فرزند واقعی `openclaw gateway run` را بازراه‌اندازی می‌کنید، نه فقط یک فرایند wrapper. -`plugins list --json` شامل `dependencyStatus` هر plugin از `dependencies` و `optionalDependencies` در `package.json` است. OpenClaw بررسی می‌کند که آیا نام آن packageها در مسیر عادی lookup مربوط به `node_modules` در Node برای آن plugin وجود دارند یا نه؛ کد زمان اجرای plugin را import نمی‌کند، package manager اجرا نمی‌کند، و وابستگی‌های جاافتاده را repair نمی‌کند. +`plugins list --json` برای هر Plugin، `dependencyStatus` را از `package.json` +`dependencies` و `optionalDependencies` شامل می‌شود. OpenClaw بررسی می‌کند که آیا آن نام‌های بسته در مسیر lookup عادی `node_modules` مربوط به Node برای Plugin وجود دارند یا نه؛ کد runtime مربوط به Plugin را import نمی‌کند، مدیر بسته اجرا نمی‌کند، و وابستگی‌های گم‌شده را تعمیر نمی‌کند. -`plugins search` یک جست‌وجوی کاتالوگ راه‌دور ClawHub است. وضعیت محلی را بررسی نمی‌کند، config را تغییر نمی‌دهد، package نصب نمی‌کند، یا کد زمان اجرای plugin را بارگذاری نمی‌کند. نتایج جست‌وجو شامل نام package در ClawHub، خانواده، channel، نسخه، خلاصه، و راهنمای نصب مانند `openclaw plugins install clawhub:` هستند. +`plugins search` یک lookup کاتالوگ راه‌دور ClawHub است. وضعیت محلی را بررسی نمی‌کند، config را تغییر نمی‌دهد، بسته نصب نمی‌کند، یا کد runtime مربوط به Plugin را بارگذاری نمی‌کند. نتایج جست‌وجو نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:` را شامل می‌شوند. -برای کار روی plugin بسته‌بندی‌شده درون یک image پکیج‌شده Docker، دایرکتوری منبع plugin را روی مسیر منبع پکیج‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mountشده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع که صرفاً کپی شده باشد بی‌اثر می‌ماند تا نصب‌های پکیج‌شده عادی همچنان از dist کامپایل‌شده استفاده کنند. +برای کار روی Pluginهای بسته‌شده داخل یک تصویر Docker بسته‌بندی‌شده، دایرکتوری منبع Plugin را روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mount‌شده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع که صرفاً کپی شده باشد بی‌اثر می‌ماند تا نصب‌های بسته‌بندی‌شده عادی همچنان از dist کامپایل‌شده استفاده کنند. -برای اشکال‌زدایی hook زمان اجرا: +برای اشکال‌زدایی hookهای runtime: -- `openclaw plugins inspect --runtime --json` hookهای ثبت‌شده و diagnostics را از یک گذر inspection با module-loaded نشان می‌دهد. Runtime inspection هرگز وابستگی‌ها را نصب نمی‌کند؛ از `openclaw doctor --fix` برای پاک‌سازی وضعیت legacy وابستگی یا نصب pluginهای قابل‌دانلودِ تنظیم‌شده‌ای که جاافتاده‌اند استفاده کنید. -- `openclaw gateway status --deep --require-rpc` Gateway قابل‌دسترسی، راهنماهای سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند. -- hookهای مکالمه غیربسته‌بندی‌شده (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) به `plugins.entries..hooks.allowConversationAccess=true` نیاز دارند. +- `openclaw plugins inspect --runtime --json` hookهای ثبت‌شده و diagnostics را از یک گذر inspection با ماژول بارگذاری‌شده نشان می‌دهد. inspection مربوط به runtime هرگز وابستگی‌ها را نصب نمی‌کند؛ برای پاک‌سازی وضعیت وابستگی legacy یا بازیابی Pluginهای دانلودشدنی گم‌شده که در config ارجاع شده‌اند از `openclaw doctor --fix` استفاده کنید. +- `openclaw gateway status --deep --require-rpc` Gateway قابل‌دسترسی، نکته‌های سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند. +- hookهای مکالمه‌ای غیر‌باندل‌شده (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) به `plugins.entries..hooks.allowConversationAccess=true` نیاز دارند. -برای جلوگیری از کپی‌کردن یک دایرکتوری محلی، از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌شود): +برای جلوگیری از کپی‌کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` همراه با `--link` پشتیبانی نمی‌شود، چون نصب‌های لینک‌شده به‌جای کپی‌کردن روی یک هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند. +`--force` همراه با `--link` پشتیبانی نمی‌شود، زیرا نصب‌های لینک‌شده به‌جای کپی‌کردن روی هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند. -برای نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolveشده (`name@version`) در index plugin مدیریت‌شده ذخیره شود، درحالی‌که رفتار پیش‌فرض بدون pin باقی می‌ماند. +در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در index مدیریت‌شده Plugin ذخیره شود، درحالی‌که رفتار پیش‌فرض بدون pin باقی می‌ماند. -### Index plugin +### index مربوط به Plugin -فراداده نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. map سطح‌بالای `installRecords` منبع پایدار فراداده نصب است، از جمله رکوردهای مربوط به manifestهای plugin خراب یا جاافتاده. آرایه `plugins` cache رجیستری سرد مشتق‌شده از manifest است. فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، uninstall، diagnostics، و رجیستری سرد plugin استفاده می‌شود. +فراداده نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. map سطح بالای `installRecords` منبع پایدار فراداده نصب است، از جمله رکوردهای manifestهای خراب یا گم‌شده Plugin. آرایه `plugins` کش رجیستری سرد مشتق‌شده از manifest است. این فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، حذف نصب، diagnostics، و رجیستری سرد Plugin استفاده می‌شود. -وقتی OpenClaw رکوردهای legacy ارسال‌شده `plugins.installs` را در config ببیند، آن‌ها را به index plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از نوشتن‌ها شکست بخورد، رکوردهای config نگه داشته می‌شوند تا فراداده نصب از دست نرود. +وقتی OpenClaw رکوردهای legacy ارسالی `plugins.installs` را در config ببیند، آن‌ها را به index مربوط به Plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از writeها شکست بخورد، رکوردهای config نگه داشته می‌شوند تا فراداده نصب از دست نرود. ### حذف نصب @@ -292,10 +283,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` رکوردهای plugin را از `plugins.entries`، index پایدارشده plugin، ورودی‌های فهرست allow/deny برای plugin، و در صورت کاربرد، ورودی‌های لینک‌شده `plugins.load.paths` حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، uninstall همچنین دایرکتوری نصب مدیریت‌شده ردیابی‌شده را وقتی داخل ریشه extensions pluginهای OpenClaw باشد حذف می‌کند. برای pluginهای active memory، slot حافظه به `memory-core` بازنشانی می‌شود. +`uninstall` رکوردهای Plugin را از `plugins.entries`، index پایدار Plugin، ورودی‌های فهرست allow/deny مربوط به Plugin، و در صورت کاربرد ورودی‌های لینک‌شده `plugins.load.paths` حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، حذف نصب همچنین دایرکتوری نصب مدیریت‌شده ردیابی‌شده را وقتی داخل ریشه افزونه‌های Plugin مربوط به OpenClaw باشد حذف می‌کند. برای Pluginهای active memory، slot حافظه به `memory-core` بازنشانی می‌شود. -`--keep-config` به‌عنوان alias منسوخ‌شده برای `--keep-files` پشتیبانی می‌شود. +`--keep-config` به‌عنوان alias منسوخ برای `--keep-files` پشتیبانی می‌شود. ### به‌روزرسانی @@ -308,33 +299,33 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -به‌روزرسانی‌ها روی نصب‌های plugin ردیابی‌شده در index مدیریت‌شده plugin و نصب‌های hook-pack ردیابی‌شده در `hooks.internal.installs` اعمال می‌شوند. +به‌روزرسانی‌ها روی نصب‌های ردیابی‌شده Plugin در index مدیریت‌شده Plugin و نصب‌های ردیابی‌شده hook-pack در `hooks.internal.installs` اعمال می‌شوند. - - وقتی یک id plugin را پاس می‌دهید، OpenClaw از spec نصب ثبت‌شده برای همان plugin دوباره استفاده می‌کند. یعنی dist-tagهایی مانند `@beta` که قبلاً ذخیره شده‌اند و نسخه‌های دقیق pinشده در اجراهای بعدی `update ` همچنان استفاده می‌شوند. + + وقتی یک id مربوط به Plugin می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای قبلاً ذخیره‌شده مانند `@beta` و نسخه‌های دقیق pinشده در اجراهای بعدی `update ` همچنان استفاده می‌شوند. - برای نصب‌های npm، همچنین می‌توانید یک spec صریح package npm با dist-tag یا نسخه دقیق پاس بدهید. OpenClaw آن نام package را به رکورد plugin ردیابی‌شده برمی‌گرداند، آن plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های آینده مبتنی بر id ثبت می‌کند. + برای نصب‌های npm، می‌توانید یک spec صریح بسته npm با dist-tag یا نسخه دقیق نیز بدهید. OpenClaw آن نام بسته را به رکورد ردیابی‌شده Plugin برمی‌گرداند، آن Plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های آینده مبتنی بر id ثبت می‌کند. - پاس‌دادن نام package npm بدون نسخه یا tag نیز به رکورد plugin ردیابی‌شده برمی‌گردد. وقتی یک plugin به نسخه دقیق pin شده است و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید. + دادن نام بسته npm بدون نسخه یا tag نیز به رکورد ردیابی‌شده Plugin resolve می‌شود. وقتی یک Plugin به نسخه دقیق pin شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید. - - `openclaw plugins update` از spec ردیابی‌شده plugin دوباره استفاده می‌کند، مگر اینکه spec جدیدی پاس بدهید. `openclaw update` علاوه بر این channel فعال به‌روزرسانی OpenClaw را می‌شناسد: روی channel بتا، رکوردهای plugin npm و ClawHub از خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر هیچ انتشار بتایی برای plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده fallback می‌کنند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند. + + `openclaw plugins update` از spec ردیابی‌شده Plugin دوباره استفاده می‌کند مگر اینکه spec جدیدی بدهید. `openclaw update` علاوه‌براین کانال فعال به‌روزرسانی OpenClaw را می‌شناسد: در کانال beta، رکوردهای Plugin مربوط به npm و ClawHub در خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار beta برای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده برمی‌گردند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند. - - پیش از یک به‌روزرسانی زنده npm، OpenClaw نسخه package نصب‌شده را در برابر فراداده رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolveشده مطابقت داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود. + + پیش از یک به‌روزرسانی زنده npm، OpenClaw نسخه بسته نصب‌شده را با فراداده رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolve‌شده مطابقت داشته باشند، به‌روزرسانی بدون دانلود، نصب دوباره، یا بازنویسی `openclaw.json` نادیده گرفته می‌شود. - وقتی hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw آن را drift مربوط به artifact npm تلقی می‌کند. فرمان تعاملی `openclaw plugins update` hashهای مورد انتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی به‌صورت fail closed عمل می‌کنند، مگر اینکه فراخواننده یک سیاست ادامه صریح ارائه کند. + وقتی hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw این را drift artifact مربوط به npm تلقی می‌کند. دستور تعاملی `openclaw plugins update` hashهای موردانتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی به‌صورت fail closed عمل می‌کنند، مگر اینکه فراخواننده یک سیاست ادامه صریح ارائه دهد. - - `--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای مثبت‌های کاذب scan کد خطرناک داخلی هنگام به‌روزرسانی plugin در دسترس است. همچنان blockهای سیاست `before_install` مربوط به plugin یا مسدودسازی ناشی از شکست scan را دور نمی‌زند، و فقط برای به‌روزرسانی‌های plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack. + + `--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای false positiveهای اسکن کد خطرناک داخلی هنگام به‌روزرسانی Pluginها در دسترس است. همچنان بلوک‌های سیاست `before_install` مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند، و فقط روی به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack. -### Inspect +### بازرسی ```bash openclaw plugins inspect @@ -342,21 +333,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect هویت، وضعیت load، منبع، قابلیت‌های manifest، پرچم‌های سیاست، diagnostics، فراداده نصب، قابلیت‌های بسته، و هرگونه پشتیبانی تشخیص‌داده‌شده از سرور MCP یا LSP را به‌طور پیش‌فرض بدون import کردن زمان اجرای plugin نشان می‌دهد. `--runtime` را اضافه کنید تا module plugin بارگذاری شود و hookها، tools، commands، services، متدهای gateway، و مسیرهای HTTP ثبت‌شده نیز شامل شوند. Runtime inspection وابستگی‌های جاافتاده plugin را مستقیماً گزارش می‌کند؛ نصب‌ها و repairها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند. +Inspect هویت، وضعیت بارگذاری، منبع، قابلیت‌های manifest، پرچم‌های سیاست، diagnostics، فراداده نصب، قابلیت‌های بسته، و هر پشتیبانی تشخیص‌داده‌شده از سرور MCP یا LSP را بدون import کردن runtime مربوط به Plugin به‌صورت پیش‌فرض نشان می‌دهد. `--runtime` را اضافه کنید تا ماژول Plugin بارگذاری شود و hookها، ابزارها، commands، services، متدهای Gateway، و routeهای HTTP ثبت‌شده شامل شوند. inspection مربوط به runtime وابستگی‌های گم‌شده Plugin را مستقیماً گزارش می‌کند؛ نصب‌ها و تعمیرها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند. -فرمان‌های CLI متعلق به plugin به‌عنوان گروه‌های فرمان ریشه `openclaw` نصب می‌شوند. پس از آنکه `inspect --runtime` یک فرمان را زیر `cliCommands` نشان داد، آن را به‌صورت `openclaw ...` اجرا کنید؛ برای نمونه pluginی که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود. +commandهای CLI تحت مالکیت Plugin به‌عنوان گروه‌های command ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک command را زیر `cliCommands` نشان داد، آن را به‌صورت `openclaw ...` اجرا کنید؛ برای مثال Pluginای که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود. -هر plugin بر اساس چیزی که واقعاً در زمان اجرا ثبت می‌کند طبقه‌بندی می‌شود: +هر Plugin براساس چیزی که واقعاً در runtime ثبت می‌کند طبقه‌بندی می‌شود: -- **plain-capability** — یک نوع قابلیت (مثلاً یک plugin فقط-provider) -- **hybrid-capability** — چند نوع قابلیت (مثلاً متن + گفتار + تصویر) -- **hook-only** — فقط hookها، بدون قابلیت یا surface -- **non-capability** — tools/commands/services اما بدون قابلیت +- **plain-capability** — یک نوع capability (مثلاً یک Plugin فقط provider) +- **hybrid-capability** — چند نوع capability (مثلاً متن + گفتار + تصویر) +- **hook-only** — فقط hookها، بدون capability یا surface +- **non-capability** — ابزارها/commands/services اما بدون capability -برای اطلاعات بیشتر درباره مدل قابلیت، [شکل‌های Plugin](/fa/plugins/architecture#plugin-shapes) را ببینید. +برای اطلاعات بیشتر درباره مدل capability، [شکل‌های Plugin](/fa/plugins/architecture#plugin-shapes) را ببینید. -پرچم `--json` گزارشی قابل‌خواندن برای ماشین تولید می‌کند که برای scripting و auditing مناسب است. `inspect --all` یک جدول fleet-wide با ستون‌های shape، گونه‌های capability، compatibility notices، bundle capabilities، و hook summary رندر می‌کند. `info` alias برای `inspect` است. +پرچم `--json` گزارشی قابل‌خواندن برای ماشین تولید می‌کند که برای اسکریپت‌نویسی و audit مناسب است. `inspect --all` جدولی در سطح کل ناوگان با ستون‌های shape، گونه‌های capability، اعلان‌های سازگاری، قابلیت‌های بسته، و خلاصه hook نمایش می‌دهد. `info` alias برای `inspect` است. ### Doctor @@ -365,11 +356,11 @@ Inspect هویت، وضعیت load، منبع، قابلیت‌های manifest، openclaw plugins doctor ``` -`doctor` خطاهای load مربوط به plugin، diagnostics مربوط به manifest/discovery، و compatibility notices را گزارش می‌کند. وقتی همه‌چیز پاک باشد، `No plugin issues detected.` را چاپ می‌کند. +`doctor` خطاهای بارگذاری Plugin، diagnostics مربوط به manifest/discovery، و اعلان‌های سازگاری را گزارش می‌کند. وقتی همه‌چیز پاک باشد، `No plugin issues detected.` را چاپ می‌کند. -اگر یک plugin تنظیم‌شده روی دیسک حاضر باشد اما توسط بررسی‌های path-safety loader مسدود شود، اعتبارسنجی config ورودی plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف config مربوط به `plugins.entries.` یا `plugins.allow`، diagnostic قبلی plugin مسدودشده، مانند مالکیت مسیر یا مجوزهای world-writable، را اصلاح کنید. +اگر یک Plugin پیکربندی‌شده روی دیسک وجود داشته باشد اما توسط بررسی‌های ایمنی مسیر loader مسدود شده باشد، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف `plugins.entries.` یا config مربوط به `plugins.allow`، diagnostic قبلی مربوط به Plugin مسدودشده، مانند مالکیت مسیر یا مجوزهای world-writable، را رفع کنید. -برای شکست‌های module-shape مانند exportهای جاافتاده `register`/`activate`، دوباره با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` اجرا کنید تا یک خلاصه فشرده از export-shape در خروجی diagnostic درج شود. +برای شکست‌های شکل ماژول مانند exportهای گم‌شده `register`/`activate`، دوباره با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` اجرا کنید تا خلاصه فشرده‌ای از شکل export در خروجی diagnostic شامل شود. ### رجیستری @@ -379,14 +370,14 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -رجیستری plugin محلی مدل خواندن سرد پایدارشده OpenClaw برای هویت plugin نصب‌شده، فعال‌سازی، فراداده منبع، و مالکیت contribution است. راه‌اندازی عادی، lookup مالک provider، طبقه‌بندی تنظیم channel، و موجودی plugin می‌توانند آن را بدون import کردن moduleهای زمان اجرای plugin بخوانند. +رجیستری محلی Plugin مدل خواندنی سرد پایدارشده OpenClaw برای هویت Plugin نصب‌شده، فعال‌سازی، فراداده منبع، و مالکیت contribution است. راه‌اندازی عادی، lookup مالک provider، طبقه‌بندی راه‌اندازی channel، و موجودی Plugin می‌توانند آن را بدون import کردن ماژول‌های runtime مربوط به Plugin بخوانند. -از `plugins registry` برای بررسی اینکه رجیستری ماندگارشده موجود، به‌روز یا کهنه است استفاده کنید. از `--refresh` برای بازسازی آن از شاخص ماندگارشدهٔ Plugin، سیاست پیکربندی، و فرادادهٔ manifest/package استفاده کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی در زمان اجرا. +از `plugins registry` برای بررسی این استفاده کنید که آیا رجیستری پایدارشده وجود دارد، به‌روز است، یا کهنه شده است. از `--refresh` برای بازسازی آن از نمایه پایدارشده Plugin، سیاست پیکربندی، و فراداده مانیفست/بسته استفاده کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی زمان اجرا. -`openclaw doctor --fix` همچنین ناهماهنگی npm مدیریت‌شدهٔ مرتبط با رجیستری را تعمیر می‌کند: اگر یک بستهٔ یتیم یا بازیابی‌شدهٔ `@openclaw/*` زیر ریشهٔ npm مدیریت‌شدهٔ Plugin یک Plugin همراه‌شده را تحت‌الشعاع قرار دهد، doctor آن بستهٔ کهنه را حذف می‌کند و رجیستری را بازسازی می‌کند تا راه‌اندازی در برابر manifest همراه‌شده اعتبارسنجی شود. +`openclaw doctor --fix` همچنین انحراف npm مدیریت‌شده نزدیک به رجیستری را تعمیر می‌کند: اگر یک بسته یتیم یا بازیابی‌شده `@openclaw/*` زیر ریشه npm مدیریت‌شده Plugin یک Plugin همراه را پنهان کند، دستور doctor آن بسته کهنه را حذف می‌کند و رجیستری را بازسازی می‌کند تا راه‌اندازی در برابر مانیفست همراه اعتبارسنجی شود. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک سوییچ سازگاری اضطراری منسوخ برای شکست‌های خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ جایگزین env فقط برای بازیابی اضطراری راه‌اندازی در زمانی است که مهاجرت در حال عرضه است. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک کلید سازگاری منسوخ اضطراری برای خرابی‌های خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ fallback محیط فقط برای بازیابی اضطراری راه‌اندازی هنگام عرضه تدریجی مهاجرت است. ### بازارچه @@ -396,7 +387,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -فهرست بازارچه یک مسیر بازارچهٔ محلی، یک مسیر `marketplace.json`، یک اختصار GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL گیت را می‌پذیرد. `--json` برچسب منبع حل‌شده به‌همراه manifest بازارچهٔ تجزیه‌شده و ورودی‌های Plugin را چاپ می‌کند. +فهرست بازارچه یک مسیر محلی بازارچه، یک مسیر `marketplace.json`، یک کوتاه‌نویسی GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL git را می‌پذیرد. `--json` برچسب منبع حل‌شده را به‌همراه مانیفست بازارچه تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند. ## مرتبط diff --git a/docs/fa/cli/sessions.md b/docs/fa/cli/sessions.md index fe1c39f4d..65faa43c9 100644 --- a/docs/fa/cli/sessions.md +++ b/docs/fa/cli/sessions.md @@ -1,67 +1,70 @@ --- read_when: - می‌خواهید نشست‌های ذخیره‌شده را فهرست کنید و فعالیت‌های اخیر را ببینید -summary: مرجع CLI برای `openclaw sessions` (فهرست‌کردن نشست‌های ذخیره‌شده + نحوه استفاده) +summary: مرجع CLI برای `openclaw sessions` (فهرست نشست‌های ذخیره‌شده + نحوه استفاده) title: نشست‌ها x-i18n: - generated_at: "2026-05-04T07:02:44Z" + generated_at: "2026-05-05T01:44:08Z" model: gpt-5.5 provider: openai - source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e + source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7 source_path: cli/sessions.md workflow: 16 --- # `openclaw sessions` -نشست‌های گفت‌وگوی ذخیره‌شده را فهرست کنید. +نشست‌های مکالمه ذخیره‌شده را فهرست می‌کند. -فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های گفت‌وگوی -ماندگارشده از مخزن‌های نشست را نشان می‌دهند. یک Discord، Slack، Telegram یا -کانال دیگرِ ساکت می‌تواند بدون ایجاد ردیف نشست جدید با موفقیت دوباره وصل شود -تا زمانی که پیامی پردازش شود. وقتی به اتصال زندهٔ کانال نیاز دارید از -`openclaw channels status --probe`، `openclaw status --deep` یا -`openclaw health --verbose` استفاده کنید. +فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های +مکالمه پایدارشده از ذخیره‌گاه‌های نشست را نشان می‌دهند. یک کانال خاموش Discord، Slack، Telegram، یا +کانال دیگر می‌تواند بدون ایجاد ردیف نشست جدید، با موفقیت دوباره وصل شود +تا زمانی که پیامی پردازش شود. وقتی به اتصال زنده +کانال نیاز دارید، از `openclaw channels status --probe`، +`openclaw status --deep`، یا `openclaw health --verbose` استفاده کنید. -پاسخ‌های Gateway `sessions.list` به‌طور پیش‌فرض محدود هستند تا مخزن‌های بزرگ و -دیرپا نتوانند حلقهٔ رویداد Gateway را در انحصار بگیرند. وقتی بازهٔ نتیجهٔ -متفاوتی لازم است، از کلاینت‌های RPC یک `limit` مثبت و صریح ارسال کنید؛ پاسخ‌ها -وقتی فراخوان‌ها نیاز داشته باشند نشان دهند ردیف‌های بیشتری وجود دارد، شامل -`totalCount`، `limitApplied` و `hasMore` هستند. +پاسخ‌های `openclaw sessions` و Gateway `sessions.list` به‌طور پیش‌فرض محدود می‌شوند +تا ذخیره‌گاه‌های بزرگ و طولانی‌عمر نتوانند فرایند CLI یا حلقه رویداد Gateway +را در انحصار بگیرند. CLI به‌طور پیش‌فرض جدیدترین ۱۰۰ نشست را برمی‌گرداند؛ برای +پنجره‌ای کوچک‌تر/بزرگ‌تر `--limit ` را بدهید یا وقتی عمداً به کل +ذخیره‌گاه نیاز دارید، از `--limit all` استفاده کنید. پاسخ‌های JSON شامل `totalCount`، `limitApplied` و +`hasMore` هستند تا وقتی فراخوان‌ها نیاز دارند نشان دهند ردیف‌های بیشتری وجود دارد. ```bash openclaw sessions openclaw sessions --agent work openclaw sessions --all-agents openclaw sessions --active 120 +openclaw sessions --limit 25 openclaw sessions --verbose openclaw sessions --json ``` انتخاب دامنه: -- پیش‌فرض: مخزن عامل پیش‌فرض پیکربندی‌شده -- `--verbose`: گزارش‌گیری پرجزئیات -- `--agent `: یک مخزن عامل پیکربندی‌شده -- `--all-agents`: تجمیع همهٔ مخزن‌های عامل پیکربندی‌شده -- `--store `: مسیر صریح مخزن (نمی‌توان آن را با `--agent` یا `--all-agents` ترکیب کرد) +- پیش‌فرض: ذخیره‌گاه عامل پیش‌فرض پیکربندی‌شده +- `--verbose`: ثبت گزارش مفصل +- `--agent `: یک ذخیره‌گاه عامل پیکربندی‌شده +- `--all-agents`: تجمیع همه ذخیره‌گاه‌های عامل پیکربندی‌شده +- `--store `: مسیر صریح ذخیره‌گاه (نمی‌تواند با `--agent` یا `--all-agents` ترکیب شود) +- `--limit `: بیشینه ردیف‌ها برای خروجی (پیش‌فرض `100`؛ `all` خروجی کامل را برمی‌گرداند) -یک بستهٔ مسیر اجرا را برای یک نشست ذخیره‌شده صادر کنید: +صدور یک بسته trajectory برای یک نشست ذخیره‌شده: ```bash openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -این همان مسیر فرمانی است که فرمان اسلش `/export-trajectory` پس از تأیید درخواست -اجرایی توسط مالک استفاده می‌کند. پوشهٔ خروجی همیشه داخل -`.openclaw/trajectory-exports/` در فضای کاری انتخاب‌شده resolve می‌شود. +این همان مسیر فرمانی است که دستور اسلش `/export-trajectory` پس از +تأیید درخواست exec توسط مالک استفاده می‌کند. دایرکتوری خروجی همیشه +داخل `.openclaw/trajectory-exports/` زیر فضای کاری انتخاب‌شده resolve می‌شود. -`openclaw sessions --all-agents` مخزن‌های عامل پیکربندی‌شده را می‌خواند. کشف -نشست در Gateway و ACP گسترده‌تر است: آن‌ها مخزن‌های فقط-دیسکی پیدا‌شده زیر ریشهٔ -پیش‌فرض `agents/` یا یک ریشهٔ قالب‌بندی‌شدهٔ `session.store` را هم شامل می‌شوند. -آن مخزن‌های کشف‌شده باید به فایل‌های عادی `sessions.json` داخل ریشهٔ عامل resolve -شوند؛ symlinkها و مسیرهای بیرون از ریشه نادیده گرفته می‌شوند. +`openclaw sessions --all-agents` ذخیره‌گاه‌های عامل پیکربندی‌شده را می‌خواند. کشف نشست Gateway و ACP +گسترده‌تر است: آن‌ها ذخیره‌گاه‌های فقط‌دیسکی یافت‌شده زیر +ریشه پیش‌فرض `agents/` یا ریشه قالب‌دار `session.store` را نیز شامل می‌شوند. آن +ذخیره‌گاه‌های کشف‌شده باید به فایل‌های عادی `sessions.json` داخل +ریشه عامل resolve شوند؛ symlinkها و مسیرهای خارج از ریشه نادیده گرفته می‌شوند. نمونه‌های JSON: @@ -76,6 +79,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 ], "allAgents": true, "count": 2, + "totalCount": 2, + "limitApplied": 100, + "hasMore": false, "activeMinutes": null, "sessions": [ { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" }, @@ -86,7 +92,7 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 ## نگهداری پاک‌سازی -همین حالا نگهداری را اجرا کنید (به‌جای انتظار برای چرخهٔ نوشتن بعدی): +نگهداری را همین حالا اجرا کنید (به‌جای انتظار برای چرخه نوشتن بعدی): ```bash openclaw sessions cleanup --dry-run @@ -97,24 +103,23 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` از تنظیمات `session.maintenance` در پیکربندی استفاده می‌کند: +`openclaw sessions cleanup` از تنظیمات `session.maintenance` در config استفاده می‌کند: -- نکتهٔ دامنه: `openclaw sessions cleanup` مخزن‌های نشست، رونوشت‌ها و sidecarهای مسیر اجرا را نگهداری می‌کند. این فرمان گزارش‌های اجرای cron را (`cron/runs/.jsonl`) هرس نمی‌کند؛ این گزارش‌ها با `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگهداری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند. +- نکته دامنه: `openclaw sessions cleanup` ذخیره‌گاه‌های نشست، رونوشت‌ها، و sidecarهای trajectory را نگهداری می‌کند. لاگ‌های اجرای cron (`cron/runs/.jsonl`) را هرس نمی‌کند؛ آن‌ها با `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگهداری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند. -- `--dry-run`: پیش‌نمایش تعداد ورودی‌هایی که بدون نوشتن هرس/محدود می‌شوند. +- `--dry-run`: پیش‌نمایش اینکه چند ورودی بدون نوشتن هرس/محدود می‌شوند. - در حالت متنی، dry-run یک جدول اقدام برای هر نشست چاپ می‌کند (`Action`، `Key`، `Age`، `Model`، `Flags`) تا بتوانید ببینید چه چیزی نگه داشته می‌شود و چه چیزی حذف می‌شود. - `--enforce`: نگهداری را حتی وقتی `session.maintenance.mode` برابر `warn` است اعمال می‌کند. -- `--fix-missing`: ورودی‌هایی را که فایل‌های رونوشتشان وجود ندارد حذف می‌کند، حتی اگر معمولاً هنوز به دلیل سن/تعداد حذف نمی‌شدند. -- `--active-key `: از یک کلید فعال مشخص در برابر تخلیهٔ بودجهٔ دیسک محافظت می‌کند. اشاره‌گرهای بادوام گفت‌وگوی خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگهداری سن/تعداد/بودجهٔ دیسک نگه داشته می‌شوند. -- `--agent `: پاک‌سازی را برای یک مخزن عامل پیکربندی‌شده اجرا می‌کند. -- `--all-agents`: پاک‌سازی را برای همهٔ مخزن‌های عامل پیکربندی‌شده اجرا می‌کند. +- `--fix-missing`: ورودی‌هایی را که فایل‌های رونوشتشان موجود نیست حذف می‌کند، حتی اگر معمولاً هنوز بر اساس سن/تعداد حذف نمی‌شدند. +- `--active-key `: یک کلید فعال مشخص را از حذف به‌دلیل بودجه دیسک محافظت می‌کند. اشاره‌گرهای پایدار مکالمه خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز در نگهداری مبتنی بر سن/تعداد/بودجه دیسک حفظ می‌شوند. +- `--agent `: پاک‌سازی را برای یک ذخیره‌گاه عامل پیکربندی‌شده اجرا می‌کند. +- `--all-agents`: پاک‌سازی را برای همه ذخیره‌گاه‌های عامل پیکربندی‌شده اجرا می‌کند. - `--store `: روی یک فایل مشخص `sessions.json` اجرا می‌شود. -- `--json`: خلاصهٔ JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر مخزن است. +- `--json`: یک خلاصه JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر ذخیره‌گاه است. -وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای مخزن‌های عامل -پیکربندی‌شده از طریق Gateway ارسال می‌شود تا از همان نویسندهٔ مخزن نشستِ ترافیک -زمان اجرا استفاده کند. برای تعمیر آفلاین صریحِ یک فایل مخزن از `--store ` -استفاده کنید. +وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای ذخیره‌گاه‌های عامل پیکربندی‌شده +از طریق Gateway ارسال می‌شود تا همان نویسنده ذخیره‌گاه نشست را با ترافیک زمان اجرا +به اشتراک بگذارد. برای ترمیم آفلاین صریح یک فایل ذخیره‌گاه، از `--store ` استفاده کنید. `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/fa/cli/update.md b/docs/fa/cli/update.md index 71c1b2fd6..4a35dbca5 100644 --- a/docs/fa/cli/update.md +++ b/docs/fa/cli/update.md @@ -1,15 +1,15 @@ --- read_when: - - می‌خواهید نسخهٔ کاری کد منبع را با اطمینان به‌روزرسانی کنید - - شما در حال اشکال‌زدایی خروجی یا گزینه‌های `openclaw update` هستید - - باید رفتار کوتاه‌نویسی `--update` را درک کنید -summary: مرجع CLI برای `openclaw update` (به‌روزرسانی نسبتاً ایمن منبع + راه‌اندازی مجدد خودکار Gateway) + - می‌خواهید یک checkout کد منبع را به‌صورت ایمن به‌روزرسانی کنید + - در حال اشکال‌زدایی خروجی یا گزینه‌های `openclaw update` هستید + - باید رفتار اختصاری `--update` را درک کنید +summary: مرجع CLI برای `openclaw update` (به‌روزرسانی نسبتاً امن منبع + راه‌اندازی مجدد خودکار Gateway) title: به‌روزرسانی x-i18n: - generated_at: "2026-05-03T21:29:14Z" + generated_at: "2026-05-05T01:45:09Z" model: gpt-5.5 provider: openai - source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8 + source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f source_path: cli/update.md workflow: 16 --- @@ -18,10 +18,10 @@ x-i18n: OpenClaw را با ایمنی به‌روزرسانی کنید و بین کانال‌های پایدار/بتا/توسعه جابه‌جا شوید. -اگر از طریق **npm/pnpm/bun** نصب کرده‌اید (نصب سراسری، بدون فراداده git)، +اگر از طریق **npm/pnpm/bun** نصب کرده‌اید (نصب سراسری، بدون فرادادهٔ git)، به‌روزرسانی‌ها از طریق جریان مدیر بسته در [به‌روزرسانی](/fa/install/updating) انجام می‌شوند. -## استفاده +## کاربرد ```bash openclaw update @@ -40,31 +40,31 @@ openclaw --update ## گزینه‌ها -- `--no-restart`: پس از به‌روزرسانی موفق، راه‌اندازی مجدد سرویس Gateway را رد می‌کند. به‌روزرسانی‌های مدیر بسته که Gateway را راه‌اندازی مجدد می‌کنند، پیش از موفق شدن فرمان بررسی می‌کنند که سرویس راه‌اندازی‌شده نسخه به‌روزشده مورد انتظار را گزارش کند. +- `--no-restart`: پس از به‌روزرسانی موفق، از راه‌اندازی دوبارهٔ سرویس Gateway صرف‌نظر می‌کند. به‌روزرسانی‌های مدیر بسته که Gateway را دوباره راه‌اندازی می‌کنند، پیش از موفق شدن دستور، بررسی می‌کنند که سرویس راه‌اندازی‌شدهٔ دوباره نسخهٔ به‌روزرسانی‌شدهٔ مورد انتظار را گزارش می‌کند. - `--channel `: کانال به‌روزرسانی را تنظیم می‌کند (git + npm؛ در پیکربندی ماندگار می‌شود). -- `--tag `: هدف بسته را فقط برای همین به‌روزرسانی بازنویسی می‌کند. برای نصب‌های بسته‌ای، `main` به `github:openclaw/openclaw#main` نگاشت می‌شود. -- `--dry-run`: اقدام‌های به‌روزرسانی برنامه‌ریزی‌شده را (جریان کانال/برچسب/هدف/راه‌اندازی مجدد) بدون نوشتن پیکربندی، نصب، همگام‌سازی plugins یا راه‌اندازی مجدد پیش‌نمایش می‌کند. -- `--json`: JSON قابل‌خواندن برای ماشین `UpdateRunResult` را چاپ می‌کند، شامل - `postUpdate.plugins.integrityDrifts` وقتی در جریان همگام‌سازی Plugin پس از به‌روزرسانی، drift در artifact مربوط به npm plugin +- `--tag `: هدف بسته را فقط برای این به‌روزرسانی بازنویسی می‌کند. برای نصب‌های بسته‌ای، `main` به `github:openclaw/openclaw#main` نگاشت می‌شود. +- `--dry-run`: اقدام‌های برنامه‌ریزی‌شدهٔ به‌روزرسانی (جریان کانال/تگ/هدف/راه‌اندازی دوباره) را بدون نوشتن پیکربندی، نصب، همگام‌سازی Pluginها، یا راه‌اندازی دوباره پیش‌نمایش می‌کند. +- `--json`: JSON قابل‌خواندن برای ماشینِ `UpdateRunResult` را چاپ می‌کند، شامل + `postUpdate.plugins.integrityDrifts` وقتی در همگام‌سازی Plugin پس از به‌روزرسانی، انحراف آرتیفکت npm Plugin شناسایی شود. -- `--timeout `: مهلت زمانی هر مرحله (پیش‌فرض 1800s است). -- `--yes`: پیام‌های تأیید را رد می‌کند (برای مثال تأیید downgrade). +- `--timeout `: مهلت زمانی برای هر مرحله (پیش‌فرض 1800s است). +- `--yes`: اعلان‌های تأیید را رد می‌کند (برای مثال تأیید بازگشت به نسخهٔ قدیمی‌تر). -`openclaw update` پرچم `--verbose` ندارد. برای پیش‌نمایش -اقدام‌های برنامه‌ریزی‌شده کانال/برچسب/نصب/راه‌اندازی مجدد از `--dry-run`، برای نتایج -قابل‌خواندن برای ماشین از `--json`، و وقتی فقط به جزئیات کانال و -دسترس‌پذیری نیاز دارید از `openclaw update status --json` استفاده کنید. اگر در حال اشکال‌زدایی لاگ‌های Gateway پیرامون یک به‌روزرسانی هستید، -پرحرفی کنسول و سطح لاگ فایل جدا هستند: Gateway `--verbose` روی -خروجی ترمینال/WebSocket اثر می‌گذارد، در حالی که لاگ‌های فایل به `logging.level: "debug"` یا -`"trace"` در پیکربندی نیاز دارند. [لاگ‌گیری Gateway](/fa/gateway/logging) را ببینید. +`openclaw update` پرچم `--verbose` ندارد. از `--dry-run` برای پیش‌نمایش +اقدام‌های برنامه‌ریزی‌شدهٔ کانال/تگ/نصب/راه‌اندازی دوباره، از `--json` برای نتایج +قابل‌خواندن برای ماشین، و از `openclaw update status --json` وقتی فقط به جزئیات کانال و +دسترس‌پذیری نیاز دارید استفاده کنید. اگر در حال اشکال‌زدایی گزارش‌های Gateway پیرامون یک به‌روزرسانی هستید، +پرجزئیاتی کنسول و سطح گزارش فایل جدا هستند: `--verbose` در Gateway بر خروجی +ترمینال/WebSocket اثر می‌گذارد، در حالی که گزارش‌های فایل به `logging.level: "debug"` یا +`"trace"` در پیکربندی نیاز دارند. [گزارش‌گیری Gateway](/fa/gateway/logging) را ببینید. -Downgradeها به تأیید نیاز دارند، چون نسخه‌های قدیمی‌تر می‌توانند پیکربندی را خراب کنند. +بازگشت به نسخه‌های قدیمی‌تر به تأیید نیاز دارد، زیرا نسخه‌های قدیمی‌تر می‌توانند پیکربندی را خراب کنند. ## `update status` -کانال به‌روزرسانی فعال + برچسب/شاخه/SHA مربوط به git (برای checkoutهای منبع)، به‌علاوه دسترس‌پذیری به‌روزرسانی را نشان می‌دهد. +کانال به‌روزرسانی فعال + تگ/شاخه/SHA git (برای checkoutهای منبع)، به‌همراه دسترس‌پذیری به‌روزرسانی را نشان می‌دهد. ```bash openclaw update status @@ -75,128 +75,129 @@ openclaw update status --timeout 10 گزینه‌ها: - `--json`: JSON وضعیت قابل‌خواندن برای ماشین را چاپ می‌کند. -- `--timeout `: مهلت زمانی بررسی‌ها (پیش‌فرض 3s است). +- `--timeout `: مهلت زمانی برای بررسی‌ها (پیش‌فرض 3s است). ## `update wizard` جریان تعاملی برای انتخاب کانال به‌روزرسانی و تأیید اینکه آیا پس از به‌روزرسانی Gateway -راه‌اندازی مجدد شود یا نه (پیش‌فرض راه‌اندازی مجدد است). اگر بدون checkout از git گزینه `dev` را انتخاب کنید، +دوباره راه‌اندازی شود یا نه (پیش‌فرض راه‌اندازی دوباره است). اگر `dev` را بدون checkout git انتخاب کنید، پیشنهاد می‌دهد یکی ایجاد کند. گزینه‌ها: -- `--timeout `: مهلت زمانی هر مرحله به‌روزرسانی (پیش‌فرض `1800`) +- `--timeout `: مهلت زمانی برای هر مرحلهٔ به‌روزرسانی (پیش‌فرض `1800`) -## چه کاری انجام می‌دهد +## کاری که انجام می‌دهد -وقتی کانال‌ها را صراحتاً تغییر می‌دهید (`--channel ...`)، OpenClaw روش -نصب را نیز همسو نگه می‌دارد: +وقتی کانال‌ها را به‌صورت صریح عوض می‌کنید (`--channel ...`)، OpenClaw روش +نصب را نیز هم‌راستا نگه می‌دارد: -- `dev` → وجود یک checkout از git را تضمین می‌کند (پیش‌فرض: `~/openclaw`، قابل بازنویسی با `OPENCLAW_GIT_DIR`)، +- `dev` → وجود checkout git را تضمین می‌کند (پیش‌فرض: `~/openclaw`، قابل بازنویسی با `OPENCLAW_GIT_DIR`)، آن را به‌روزرسانی می‌کند و CLI سراسری را از همان checkout نصب می‌کند. - `stable` → با استفاده از `latest` از npm نصب می‌کند. -- `beta` → dist-tag مربوط به npm با نام `beta` را ترجیح می‌دهد، اما وقتی beta - موجود نباشد یا از انتشار پایدار فعلی قدیمی‌تر باشد، به `latest` برمی‌گردد. +- `beta` → برچسب توزیع npm با نام `beta` را ترجیح می‌دهد، اما وقتی بتا وجود ندارد یا از انتشار پایدار فعلی + قدیمی‌تر است، به `latest` برمی‌گردد. -به‌روزرسان خودکار هسته Gateway (وقتی از طریق پیکربندی فعال شده باشد) مسیر به‌روزرسانی CLI را -خارج از handler درخواست زنده Gateway اجرا می‌کند. به‌روزرسانی‌های مدیر بسته در control-plane `update.run` -پس از تعویض بسته، یک راه‌اندازی مجدد به‌روزرسانی بدون تعویق و بدون cooldown را اجبار می‌کنند، -چون پردازش Gateway قدیمی ممکن است هنوز chunkهای درون‌حافظه‌ای داشته باشد که به -فایل‌های حذف‌شده توسط بسته جدید اشاره می‌کنند. +به‌روزرسان خودکار هستهٔ Gateway (وقتی از طریق پیکربندی فعال باشد) مسیر به‌روزرسانی CLI را +بیرون از کنترل‌کنندهٔ درخواست زندهٔ Gateway اجرا می‌کند. به‌روزرسانی‌های مدیر بستهٔ +`update.run` در صفحهٔ کنترل، پس از تعویض بسته، یک راه‌اندازی دوبارهٔ به‌روزرسانیِ بدون تعویق و بدون دورهٔ خنک‌سازی را اجباری می‌کنند، +زیرا فرایند قدیمی Gateway ممکن است هنوز قطعه‌های درون‌حافظه‌ای داشته باشد که به +فایل‌های حذف‌شده توسط بستهٔ جدید اشاره می‌کنند. -برای نصب‌های مدیر بسته، `openclaw update` نسخه بسته هدف را -پیش از فراخوانی مدیر بسته resolve می‌کند. نصب‌های سراسری npm از نصب مرحله‌ای استفاده می‌کنند: -OpenClaw بسته جدید را در یک prefix موقت npm نصب می‌کند، inventory بسته‌بندی‌شده `dist` را -در آنجا بررسی می‌کند، سپس همان درخت بسته پاک را با prefix سراسری واقعی تعویض می‌کند. -اگر بررسی شکست بخورد، doctor پس از به‌روزرسانی، همگام‌سازی Plugin و -کار راه‌اندازی مجدد از درخت مشکوک اجرا نمی‌شوند. حتی وقتی نسخه نصب‌شده -از قبل با هدف یکی باشد، فرمان نصب بسته سراسری را تازه‌سازی می‌کند، -سپس همگام‌سازی Plugin، تازه‌سازی تکمیل فرمان هسته، و کار راه‌اندازی مجدد را اجرا می‌کند. این -sidecarهای بسته‌بندی‌شده و رکوردهای Plugin تحت مالکیت کانال را با build نصب‌شده OpenClaw -همسو نگه می‌دارد، در حالی که بازسازی کامل تکمیل فرمان‌های Plugin را به -اجرای صریح `openclaw completion --write-state` واگذار می‌کند. +برای نصب‌های مدیر بسته، `openclaw update` پیش از فراخوانی مدیر بسته، نسخهٔ بستهٔ هدف را +حل می‌کند. نصب‌های سراسری npm از نصب مرحله‌ای استفاده می‌کنند: +OpenClaw بستهٔ جدید را در یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده را +آنجا بررسی می‌کند، سپس آن درخت بستهٔ پاک را به پیشوند سراسری واقعی تعویض می‌کند. +اگر بررسی شکست بخورد، doctor پس از به‌روزرسانی، همگام‌سازی Plugin، و کار راه‌اندازی دوباره +از درخت مشکوک اجرا نمی‌شوند. حتی وقتی نسخهٔ نصب‌شده +از قبل با هدف مطابقت دارد، دستور نصب بستهٔ سراسری را تازه‌سازی می‌کند، +سپس همگام‌سازی Plugin، تازه‌سازی تکمیل فرمان هسته، و کار راه‌اندازی دوباره را اجرا می‌کند. این +کار sidecarهای بسته‌بندی‌شده و رکوردهای Plugin متعلق به کانال را با build نصب‌شدهٔ +OpenClaw هم‌راستا نگه می‌دارد و بازسازی‌های کامل تکمیل فرمان Plugin را به اجراهای +صریح `openclaw completion --write-state` واگذار می‌کند. -وقتی یک سرویس Gateway مدیریت‌شده محلی نصب شده باشد و راه‌اندازی مجدد فعال باشد، +وقتی یک سرویس Gateway مدیریت‌شدهٔ محلی نصب شده و راه‌اندازی دوباره فعال است، به‌روزرسانی‌های مدیر بسته پیش از جایگزینی درخت بسته، سرویس در حال اجرا را متوقف می‌کنند، -سپس فراداده سرویس را از نصب به‌روزشده تازه‌سازی می‌کنند، سرویس را راه‌اندازی مجدد می‌کنند، -و پیش از گزارش موفقیت بررسی می‌کنند که Gateway راه‌اندازی‌شده نسخه مورد انتظار را گزارش کند. -در macOS، بررسی پس از به‌روزرسانی همچنین تأیید می‌کند که LaunchAgent -برای profile فعال بارگذاری/در حال اجراست و پورت loopback پیکربندی‌شده سالم است. -اگر plist نصب شده باشد اما launchd آن را تحت نظارت نداشته باشد، OpenClaw -LaunchAgent را به‌طور خودکار دوباره bootstrap می‌کند، سپس -بررسی‌های آمادگی سلامت/نسخه/کانال را دوباره اجرا می‌کند. یک bootstrap تازه job مربوط به RunAtLoad را -مستقیماً بارگذاری می‌کند، بنابراین بازیابی به‌روزرسانی بلافاصله Gateway تازه -spawnشده را `kickstart -k` نمی‌کند. اگر Gateway همچنان سالم نشود، فرمان با -کد غیرصفر خارج می‌شود و مسیر لاگ راه‌اندازی مجدد به‌علاوه دستورالعمل‌های صریح راه‌اندازی مجدد، نصب مجدد، و -rollback بسته را چاپ می‌کند. با `--no-restart`، +سپس فرادادهٔ سرویس را از نصب به‌روزرسانی‌شده تازه‌سازی می‌کنند، سرویس را دوباره راه‌اندازی می‌کنند +و پیش از گزارش موفقیت بررسی می‌کنند که Gateway راه‌اندازی‌شدهٔ دوباره نسخهٔ مورد انتظار را گزارش می‌کند. +در macOS، بررسی پس از به‌روزرسانی همچنین بررسی می‌کند که LaunchAgent +برای نمایهٔ فعال بارگذاری/در حال اجرا است و درگاه loopback پیکربندی‌شده سالم است. +اگر plist نصب شده اما launchd آن را تحت نظارت ندارد، OpenClaw +LaunchAgent را به‌صورت خودکار دوباره bootstrap می‌کند، سپس بررسی‌های +آمادگی سلامت/نسخه/کانال را دوباره اجرا می‌کند. یک bootstrap تازه job مربوط به RunAtLoad +را مستقیم بارگذاری می‌کند، بنابراین بازیابی به‌روزرسانی بلافاصله Gateway تازه +ایجادشده را `kickstart -k` نمی‌کند. اگر Gateway همچنان سالم نشود، دستور +با وضعیت غیرصفر خارج می‌شود و مسیر گزارش راه‌اندازی دوباره به‌علاوهٔ دستورالعمل‌های صریح راه‌اندازی دوباره، نصب دوباره، و +بازگردانی بسته را چاپ می‌کند. با `--no-restart`، جایگزینی بسته همچنان اجرا می‌شود اما سرویس مدیریت‌شده متوقف یا -راه‌اندازی مجدد نمی‌شود، بنابراین Gateway در حال اجرا ممکن است تا وقتی آن را -دستی راه‌اندازی مجدد کنید کد قدیمی را نگه دارد. +دوباره راه‌اندازی نمی‌شود، بنابراین Gateway در حال اجرا ممکن است تا زمانی که آن را +دستی دوباره راه‌اندازی کنید، کد قدیمی را نگه دارد. -## جریان checkout از git +## جریان checkout git ### انتخاب کانال -- `stable`: آخرین برچسب غیر beta را checkout می‌کند، سپس build و doctor را اجرا می‌کند. -- `beta`: آخرین برچسب `-beta` را ترجیح می‌دهد، اما وقتی beta موجود نیست یا قدیمی‌تر باشد، به آخرین برچسب پایدار برمی‌گردد. -- `dev`: `main` را checkout می‌کند، سپس fetch و rebase انجام می‌دهد. +- `stable`: جدیدترین تگ غیر بتا را checkout می‌کند، سپس build و doctor را اجرا می‌کند. +- `beta`: جدیدترین تگ `-beta` را ترجیح می‌دهد، اما وقتی بتا وجود ندارد یا قدیمی‌تر است، به جدیدترین تگ پایدار برمی‌گردد. +- `dev`: `main` را checkout می‌کند، سپس fetch و rebase می‌کند. ### مراحل به‌روزرسانی - - نیاز دارد هیچ تغییر commitنشده‌ای وجود نداشته باشد. + + نیازمند نبود تغییرات commitنشده است. - به کانال انتخاب‌شده (برچسب یا شاخه) جابه‌جا می‌شود. + به کانال انتخاب‌شده (تگ یا شاخه) تغییر می‌کند. - - فقط برای dev. + + فقط توسعه. - - lint و build مربوط به TypeScript را در یک worktree موقت اجرا می‌کند. اگر tip شکست بخورد، تا 10 commit به عقب برمی‌گردد تا جدیدترین build پاک را پیدا کند. + + lint و build TypeScript را در یک worktree موقت اجرا می‌کند. اگر نوک شاخه شکست بخورد، تا 10 commit به عقب برمی‌گردد تا جدیدترین build پاک را پیدا کند. - روی commit انتخاب‌شده rebase می‌کند (فقط dev). + روی commit انتخاب‌شده rebase می‌کند (فقط توسعه). - از مدیر بسته repo استفاده می‌کند. برای checkoutهای pnpm، به‌روزرسان `pnpm` را به‌صورت درخواستی bootstrap می‌کند (ابتدا از طریق `corepack`، سپس fallback موقت `npm install pnpm@10`) به جای اینکه `npm run build` را داخل یک workspace مربوط به pnpm اجرا کند. + از مدیر بستهٔ repo استفاده می‌کند. برای checkoutهای pnpm، به‌روزرسان `pnpm` را در صورت نیاز bootstrap می‌کند (ابتدا از طریق `corepack`، سپس با fallback موقت `npm install pnpm@10`) به‌جای اینکه `npm run build` را داخل یک workspace pnpm اجرا کند. - Gateway و Control UI را build می‌کند. + gateway و Control UI را build می‌کند. - `openclaw doctor` به‌عنوان بررسی نهایی به‌روزرسانی ایمن اجرا می‌شود. + `openclaw doctor` به‌عنوان بررسی نهایی به‌روزرسانی امن اجرا می‌شود. - - plugins را با کانال فعال همگام می‌کند. dev از plugins همراه استفاده می‌کند؛ stable و beta از npm استفاده می‌کنند. نصب‌های Plugin ردیابی‌شده را به‌روزرسانی می‌کند. + + Pluginها را با کانال فعال همگام می‌کند. توسعه از Pluginهای bundled استفاده می‌کند؛ پایدار و بتا از npm استفاده می‌کنند. نصب‌های Plugin ردیابی‌شده را به‌روزرسانی می‌کند. -در کانال به‌روزرسانی beta، نصب‌های Plugin مربوط به npm و ClawHub که ردیابی می‌شوند و -از خط پیش‌فرض/latest پیروی می‌کنند، ابتدا انتشار Plugin با `@beta` را امتحان می‌کنند. اگر Plugin هیچ -انتشار beta نداشته باشد، OpenClaw به spec ثبت‌شده default/latest برمی‌گردد. نسخه‌های دقیق -و برچسب‌های صریح بازنویسی نمی‌شوند. +در کانال به‌روزرسانی بتا، نصب‌های npm و ClawHub Plugin ردیابی‌شده که خط +پیش‌فرض/latest را دنبال می‌کنند، ابتدا یک انتشار `@beta` Plugin را امتحان می‌کنند. اگر Plugin +انتشار بتا نداشته باشد، OpenClaw به spec پیش‌فرض/latest ثبت‌شده برمی‌گردد. برای npm +Pluginها، OpenClaw همچنین وقتی بستهٔ بتا وجود دارد اما بررسی نصب آن شکست می‌خورد +به عقب برمی‌گردد. نسخه‌های دقیق و تگ‌های صریح بازنویسی نمی‌شوند. -اگر به‌روزرسانی یک npm plugin دقیقاً pinشده به artifactای resolve شود که integrity آن با رکورد نصب ذخیره‌شده متفاوت است، `openclaw update` به‌جای نصب آن، به‌روزرسانی artifact مربوط به Plugin را abort می‌کند. فقط پس از بررسی اینکه به artifact جدید اعتماد دارید، Plugin را صراحتاً دوباره نصب یا به‌روزرسانی کنید. +اگر یک به‌روزرسانی دقیقاً pin‌شدهٔ npm Plugin به آرتیفکتی حل شود که یکپارچگی آن با رکورد نصب ذخیره‌شده فرق دارد، `openclaw update` به‌جای نصب آن، به‌روزرسانی آرتیفکت Plugin را متوقف می‌کند. فقط پس از اینکه بررسی کردید به آرتیفکت جدید اعتماد دارید، Plugin را دوباره نصب یا صریحاً به‌روزرسانی کنید. -شکست‌های همگام‌سازی Plugin پس از به‌روزرسانی باعث شکست نتیجه به‌روزرسانی می‌شوند و کارهای بعدی راه‌اندازی مجدد را متوقف می‌کنند. خطای نصب یا به‌روزرسانی Plugin را رفع کنید، سپس `openclaw update` را دوباره اجرا کنید. +شکست‌های همگام‌سازی Plugin پس از به‌روزرسانی نتیجهٔ به‌روزرسانی را ناموفق می‌کنند و کار پیگیری راه‌اندازی دوباره را متوقف می‌کنند. خطای نصب یا به‌روزرسانی Plugin را رفع کنید، سپس `openclaw update` را دوباره اجرا کنید. -وقتی Gateway به‌روزشده شروع به کار می‌کند، بارگذاری Plugin فقط در حالت بررسی است: startup مدیرهای بسته را اجرا نمی‌کند یا درخت‌های وابستگی را تغییر نمی‌دهد. راه‌اندازی‌های مجدد مدیر بسته `update.run` پس از تعویض درخت بسته، deferral عادی هنگام بیکاری و cooldown راه‌اندازی مجدد را دور می‌زنند، بنابراین پردازش قدیمی نمی‌تواند chunkهای حذف‌شده را به‌صورت lazy-load نگه دارد. +وقتی Gateway به‌روزرسانی‌شده شروع به کار می‌کند، بارگذاری Plugin فقط بررسی است: راه‌اندازی، مدیرهای بسته را اجرا نمی‌کند و درخت‌های وابستگی را تغییر نمی‌دهد. راه‌اندازی‌های دوبارهٔ `update.run` مدیر بسته پس از تعویض درخت بسته، تعویق عادی زمان بیکاری و دورهٔ خنک‌سازی راه‌اندازی دوباره را دور می‌زنند، بنابراین فرایند قدیمی نمی‌تواند به lazy-loading قطعه‌های حذف‌شده ادامه دهد. -اگر bootstrap مربوط به pnpm همچنان شکست بخورد، به‌روزرسان به‌جای تلاش برای `npm run build` داخل checkout، زودتر با خطای مخصوص مدیر بسته متوقف می‌شود. +اگر bootstrap مربوط به pnpm همچنان شکست بخورد، به‌روزرسان به‌جای تلاش برای اجرای `npm run build` داخل checkout، زودتر با یک خطای ویژهٔ مدیر بسته متوقف می‌شود. -## میان‌بر `--update` +## خلاصه‌نویسی `--update` -`openclaw --update` به `openclaw update` بازنویسی می‌شود (برای shellها و اسکریپت‌های launcher مفید است). +`openclaw --update` به `openclaw update` بازنویسی می‌شود (برای shellها و اسکریپت‌های اجراکننده مفید است). ## مرتبط -- `openclaw doctor` (روی checkoutهای git پیشنهاد می‌دهد ابتدا update اجرا شود) +- `openclaw doctor` (در checkoutهای git پیشنهاد می‌دهد ابتدا update اجرا شود) - [کانال‌های توسعه](/fa/install/development-channels) - [به‌روزرسانی](/fa/install/updating) - [مرجع CLI](/fa/cli) diff --git a/docs/fa/concepts/models.md b/docs/fa/concepts/models.md index 15b9e7f05..1328fc888 100644 --- a/docs/fa/concepts/models.md +++ b/docs/fa/concepts/models.md @@ -1,36 +1,36 @@ --- read_when: - افزودن یا تغییر CLI مدل‌ها (models list/set/scan/aliases/fallbacks) - - تغییر رفتار بازگشت به مدل جایگزین یا تجربهٔ کاربری انتخاب - - به‌روزرسانی پروب‌های اسکن مدل (ابزارها/تصاویر) + - تغییر رفتار جایگزینی مدل یا تجربهٔ کاربری انتخاب + - به‌روزرسانی کاوشگرهای پویش مدل (ابزارها/تصاویر) sidebarTitle: Models CLI summary: 'CLI مدل‌ها: فهرست، تنظیم، نام‌های مستعار، جایگزین‌ها، اسکن، وضعیت' title: CLI مدل‌ها x-i18n: - generated_at: "2026-05-02T11:43:16Z" + generated_at: "2026-05-05T01:45:11Z" model: gpt-5.5 provider: openai - source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f + source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f source_path: concepts/models.md workflow: 16 --- - - چرخش پروفایل احراز هویت، زمان‌های سردسازی، و نحوه تعامل آن با جایگزین‌ها. + + چرخش پروفایل احراز هویت، دوره‌های انتظار، و نحوه تعامل آن با مدل‌های جایگزین. - مرور سریع ارائه‌دهنده و مثال‌ها. + مرور سریع ارائه‌دهنده‌ها و مثال‌ها. - PI، Codex، و زمان‌اجراهای دیگر حلقه عامل. + PI، Codex، و دیگر زمان‌اجراهای حلقه عامل. کلیدهای پیکربندی مدل. -ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولا زمان‌اجرای سطح‌پایین عامل را انتخاب نمی‌کنند. برای مثال، `openai/gpt-5.5` بسته به `agents.defaults.agentRuntime.id` می‌تواند از مسیر عادی ارائه‌دهنده OpenAI یا از طریق زمان‌اجرای app-server در Codex اجرا شود. در حالت زمان‌اجرای Codex، ارجاع `openai/gpt-*` به معنای صورتحساب‌گیری با کلید API نیست؛ احراز هویت می‌تواند از حساب Codex یا پروفایل احراز هویت `openai-codex` بیاید. [زمان‌اجراهای عامل](/fa/concepts/agent-runtimes) را ببینید. +ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولاً زمان‌اجرای سطح پایین عامل را انتخاب نمی‌کنند. برای مثال، `openai/gpt-5.5` بسته به `agents.defaults.agentRuntime.id` می‌تواند از مسیر عادی ارائه‌دهنده OpenAI یا از طریق زمان‌اجرای app-server در Codex اجرا شود. در حالت زمان‌اجرای Codex، ارجاع `openai/gpt-*` به‌معنای صورتحساب API key نیست؛ احراز هویت می‌تواند از یک حساب Codex یا پروفایل احراز هویت `openai-codex` بیاید. [زمان‌اجراهای عامل](/fa/concepts/agent-runtimes) را ببینید. ## انتخاب مدل چگونه کار می‌کند @@ -40,45 +40,45 @@ OpenClaw مدل‌ها را به این ترتیب انتخاب می‌کند: `agents.defaults.model.primary` (یا `agents.defaults.model`). - + `agents.defaults.model.fallbacks` (به‌ترتیب). - - جابه‌جایی اضطراری احراز هویت، پیش از رفتن به مدل بعدی، داخل یک ارائه‌دهنده رخ می‌دهد. + + جایگزینی احراز هویت هنگام خرابی، پیش از رفتن به مدل بعدی، داخل یک ارائه‌دهنده انجام می‌شود. - - - `agents.defaults.models` فهرست مجاز/کاتالوگ مدل‌هایی است که OpenClaw می‌تواند استفاده کند (به‌علاوه نام‌های مستعار). + + - `agents.defaults.models` فهرست مجاز/کاتالوگ مدل‌هایی است که OpenClaw می‌تواند استفاده کند (به‌همراه aliasها). - `agents.defaults.imageModel` **فقط وقتی** استفاده می‌شود که مدل اصلی نتواند تصویر بپذیرد. - - `agents.defaults.pdfModel` توسط ابزار `pdf` استفاده می‌شود. اگر حذف شده باشد، ابزار ابتدا به `agents.defaults.imageModel` و سپس به مدل پیش‌فرض/نشست حل‌شده برمی‌گردد. - - `agents.defaults.imageGenerationModel` توسط قابلیت مشترک تولید تصویر استفاده می‌شود. اگر حذف شده باشد، `image_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنباط کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهندگان ثبت‌شده باقی‌مانده تولید تصویر را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر ارائه‌دهنده/مدل مشخصی تنظیم می‌کنید، احراز هویت/کلید API آن ارائه‌دهنده را هم پیکربندی کنید. - - `agents.defaults.musicGenerationModel` توسط قابلیت مشترک تولید موسیقی استفاده می‌شود. اگر حذف شده باشد، `music_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنباط کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهندگان ثبت‌شده باقی‌مانده تولید موسیقی را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر ارائه‌دهنده/مدل مشخصی تنظیم می‌کنید، احراز هویت/کلید API آن ارائه‌دهنده را هم پیکربندی کنید. - - `agents.defaults.videoGenerationModel` توسط قابلیت مشترک تولید ویدیو استفاده می‌شود. اگر حذف شده باشد، `video_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنباط کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهندگان ثبت‌شده باقی‌مانده تولید ویدیو را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر ارائه‌دهنده/مدل مشخصی تنظیم می‌کنید، احراز هویت/کلید API آن ارائه‌دهنده را هم پیکربندی کنید. - - پیش‌فرض‌های هر عامل می‌توانند `agents.defaults.model` را از طریق `agents.list[].model` به‌علاوه اتصال‌ها بازنویسی کنند ([مسیریابی چندعاملی](/fa/concepts/multi-agent) را ببینید). + - `agents.defaults.pdfModel` توسط ابزار `pdf` استفاده می‌شود. اگر حذف شود، ابزار ابتدا به `agents.defaults.imageModel` و سپس به مدل حل‌شده نشست/پیش‌فرض برمی‌گردد. + - `agents.defaults.imageGenerationModel` توسط قابلیت مشترک تولید تصویر استفاده می‌شود. اگر حذف شود، `image_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنتاج کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس سایر ارائه‌دهندگان ثبت‌شده تولید تصویر را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/API key آن ارائه‌دهنده را نیز پیکربندی کنید. + - `agents.defaults.musicGenerationModel` توسط قابلیت مشترک تولید موسیقی استفاده می‌شود. اگر حذف شود، `music_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنتاج کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس سایر ارائه‌دهندگان ثبت‌شده تولید موسیقی را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/API key آن ارائه‌دهنده را نیز پیکربندی کنید. + - `agents.defaults.videoGenerationModel` توسط قابلیت مشترک تولید ویدئو استفاده می‌شود. اگر حذف شود، `video_generate` همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنتاج کند. ابتدا ارائه‌دهنده پیش‌فرض فعلی را امتحان می‌کند، سپس سایر ارائه‌دهندگان ثبت‌شده تولید ویدئو را به‌ترتیب شناسه ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/API key آن ارائه‌دهنده را نیز پیکربندی کنید. + - پیش‌فرض‌های هر عامل می‌توانند `agents.defaults.model` را از طریق `agents.list[].model` به‌همراه bindingها بازنویسی کنند ([مسیریابی چندعامله](/fa/concepts/multi-agent) را ببینید). -## منبع انتخاب و رفتار جایگزین +## منبع انتخاب و رفتار جایگزینی -همان `provider/model` می‌تواند بسته به این‌که از کجا آمده است، معنی متفاوتی داشته باشد: +همان `provider/model` بسته به این‌که از کجا آمده است می‌تواند معنی‌های متفاوتی داشته باشد: -- پیش‌فرض‌های پیکربندی‌شده (`agents.defaults.model.primary` و مدل‌های اصلی ویژه عامل) نقطه شروع عادی هستند و از `agents.defaults.model.fallbacks` استفاده می‌کنند. -- انتخاب‌های جایگزین خودکار، وضعیت بازیابی موقت هستند. آن‌ها با `modelOverrideSource: "auto"` ذخیره می‌شوند تا نوبت‌های بعدی بتوانند بدون آزمودن دوباره یک مدل اصلی شناخته‌شده به‌عنوان بد، همچنان از زنجیره جایگزین استفاده کنند. -- انتخاب‌های نشست کاربر دقیق هستند. `/model`، انتخابگر مدل، `session_status(model=...)`، و `sessions.patch` مقدار `modelOverrideSource: "user"` را ذخیره می‌کنند؛ اگر آن ارائه‌دهنده/مدل انتخاب‌شده دسترس‌ناپذیر باشد، OpenClaw به‌جای افتادن روی مدل پیکربندی‌شده دیگر، خطا را آشکار نشان می‌دهد. -- `--model` در Cron / مقدار `model` در بار، مدل اصلی هر کار است. همچنان از جایگزین‌های پیکربندی‌شده استفاده می‌کند مگر این‌که کار، `fallbacks` صریح در بار فراهم کند (برای اجرای سخت‌گیرانه cron از `fallbacks: []` استفاده کنید). -- مدل پیش‌فرض CLI و انتخابگرهای فهرست مجاز با فهرست‌کردن `models.providers.*.models` صریح به‌جای بارگذاری کل کاتالوگ داخلی، به `models.mode: "replace"` احترام می‌گذارند. -- انتخابگر مدل در رابط کنترل، نمای مدل پیکربندی‌شده را از Gateway می‌خواهد: وقتی موجود باشد `agents.defaults.models`، در غیر این صورت `models.providers.*.models` صریح به‌علاوه ارائه‌دهندگانی با احراز هویت قابل استفاده. کل کاتالوگ داخلی برای نماهای مرور صریح مانند `models.list` با `view: "all"` یا `openclaw models list --all` نگه داشته می‌شود. +- پیش‌فرض‌های پیکربندی‌شده (`agents.defaults.model.primary` و مدل‌های اصلی مخصوص عامل) نقطه شروع عادی هستند و از `agents.defaults.model.fallbacks` استفاده می‌کنند. +- انتخاب‌های جایگزین خودکار، وضعیت بازیابی موقت هستند. آن‌ها با `modelOverrideSource: "auto"` ذخیره می‌شوند تا نوبت‌های بعدی بتوانند بدون بررسی اولیه‌ای که می‌دانیم خراب است، همچنان از زنجیره جایگزین استفاده کنند. +- انتخاب‌های نشست کاربر دقیق هستند. `/model`، انتخابگر مدل، `session_status(model=...)`، و `sessions.patch` مقدار `modelOverrideSource: "user"` را ذخیره می‌کنند؛ اگر آن ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، OpenClaw به‌جای افتادن به مدل پیکربندی‌شده دیگر، به‌صورت آشکار شکست می‌خورد. +- Cron `--model` / payload `model` مدل اصلی هر کار است. همچنان از مدل‌های جایگزین پیکربندی‌شده استفاده می‌کند، مگر این‌که کار payload `fallbacks` صریح ارائه کند (برای اجرای cron سخت‌گیرانه از `fallbacks: []` استفاده کنید). +- انتخابگرهای مدل پیش‌فرض و فهرست مجاز CLI با فهرست کردن `models.providers.*.models` صریح به‌جای بارگذاری کامل کاتالوگ داخلی، به `models.mode: "replace"` احترام می‌گذارند. +- انتخابگر مدل Control UI از Gateway نمای مدل پیکربندی‌شده‌اش را می‌خواهد: وقتی وجود داشته باشد `agents.defaults.models`، وگرنه `models.providers.*.models` صریح به‌همراه ارائه‌دهندگانی که احراز هویت قابل استفاده دارند. کاتالوگ کامل داخلی برای نماهای مرور صریح مانند `models.list` با `view: "all"` یا `openclaw models list --all` رزرو شده است. ## سیاست سریع مدل -- مدل اصلی خود را روی قوی‌ترین مدل نسل‌جدید در دسترس خود تنظیم کنید. -- برای کارهای حساس به هزینه/تاخیر و گفت‌وگوی کم‌ریسک‌تر از جایگزین‌ها استفاده کنید. -- برای عامل‌های دارای ابزار یا ورودی‌های نامطمئن، از رده‌های مدل قدیمی‌تر/ضعیف‌تر پرهیز کنید. +- مدل اصلی خود را روی قوی‌ترین مدل نسل جدیدی تنظیم کنید که در دسترس شماست. +- از مدل‌های جایگزین برای کارهای حساس به هزینه/تأخیر و گفت‌وگوهای کم‌ریسک‌تر استفاده کنید. +- برای عامل‌های دارای ابزار یا ورودی‌های غیرقابل اعتماد، از رده‌های مدل قدیمی‌تر/ضعیف‌تر پرهیز کنید. -## راه‌اندازی اولیه (پیشنهادی) +## راه‌اندازی اولیه (توصیه‌شده) اگر نمی‌خواهید پیکربندی را دستی ویرایش کنید، راه‌اندازی اولیه را اجرا کنید: @@ -86,20 +86,20 @@ OpenClaw مدل‌ها را به این ترتیب انتخاب می‌کند: openclaw onboard ``` -این می‌تواند مدل + احراز هویت را برای ارائه‌دهندگان رایج تنظیم کند، از جمله **اشتراک OpenAI Code (Codex)** (OAuth) و **Anthropic** (کلید API یا Claude CLI). +این می‌تواند مدل + احراز هویت را برای ارائه‌دهندگان رایج، از جمله **اشتراک OpenAI Code (Codex)** (OAuth) و **Anthropic** (API key یا Claude CLI)، تنظیم کند. -## کلیدهای پیکربندی (نمای کلی) +## کلیدهای پیکربندی (مرور کلی) - `agents.defaults.model.primary` و `agents.defaults.model.fallbacks` - `agents.defaults.imageModel.primary` و `agents.defaults.imageModel.fallbacks` - `agents.defaults.pdfModel.primary` و `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` و `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.videoGenerationModel.primary` و `agents.defaults.videoGenerationModel.fallbacks` -- `agents.defaults.models` (فهرست مجاز + نام‌های مستعار + پارامترهای ارائه‌دهنده) +- `agents.defaults.models` (فهرست مجاز + aliasها + پارامترهای ارائه‌دهنده) - `models.providers` (ارائه‌دهندگان سفارشی نوشته‌شده در `models.json`) -ارجاع‌های مدل به حروف کوچک نرمال می‌شوند. نام‌های مستعار ارائه‌دهنده مانند `z.ai/*` به `zai/*` نرمال می‌شوند. +ارجاع‌های مدل به حروف کوچک نرمال‌سازی می‌شوند. aliasهای ارائه‌دهنده مانند `z.ai/*` به `zai/*` نرمال‌سازی می‌شوند. نمونه‌های پیکربندی ارائه‌دهنده (از جمله OpenCode) در [OpenCode](/fa/providers/opencode) قرار دارند. @@ -113,8 +113,8 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json ``` - - `openclaw config set` از نگاشت‌های مدل/ارائه‌دهنده در برابر بازنویسی‌های تصادفی محافظت می‌کند. انتساب یک شیء ساده به `agents.defaults.models`، `models.providers`، یا `models.providers..models` وقتی باعث حذف ورودی‌های موجود شود رد می‌شود. برای تغییرات افزایشی از `--merge` استفاده کنید؛ فقط وقتی مقدار ارائه‌شده باید به مقدار کامل هدف تبدیل شود از `--replace` استفاده کنید. + + `openclaw config set` از mapهای مدل/ارائه‌دهنده در برابر بازنویسی ناخواسته محافظت می‌کند. انتساب یک شیء ساده به `agents.defaults.models`، `models.providers`، یا `models.providers..models` وقتی که باعث حذف ورودی‌های موجود شود رد می‌شود. برای تغییرات افزایشی از `--merge` استفاده کنید؛ فقط وقتی از `--replace` استفاده کنید که مقدار ارائه‌شده باید مقدار کامل مقصد شود. راه‌اندازی تعاملی ارائه‌دهنده و `openclaw configure --section model` نیز انتخاب‌های محدود به ارائه‌دهنده را با فهرست مجاز موجود ادغام می‌کنند، بنابراین افزودن Codex، Ollama، یا ارائه‌دهنده‌ای دیگر ورودی‌های مدل نامرتبط را حذف نمی‌کند. Configure هنگام اعمال دوباره احراز هویت ارائه‌دهنده، `agents.defaults.model.primary` موجود را حفظ می‌کند. فرمان‌های صریح تنظیم پیش‌فرض مانند `openclaw models auth login --provider --set-default` و `openclaw models set ` همچنان `agents.defaults.model.primary` را جایگزین می‌کنند. @@ -126,11 +126,12 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json اگر `agents.defaults.models` تنظیم شده باشد، به **فهرست مجاز** برای `/model` و برای بازنویسی‌های نشست تبدیل می‌شود. وقتی کاربر مدلی را انتخاب کند که در آن فهرست مجاز نیست، OpenClaw برمی‌گرداند: ``` -Model "provider/model" is not allowed. Use /model to list available models. +Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. +Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` -این اتفاق **پیش از** تولید یک پاسخ عادی رخ می‌دهد، بنابراین پیام ممکن است این حس را بدهد که «پاسخ نداد». راه‌حل این است که یکی از این کارها را انجام دهید: +این اتفاق **پیش از** تولید پاسخ عادی رخ می‌دهد، بنابراین پیام می‌تواند این حس را بدهد که «پاسخ نداد». راه‌حل یکی از این موارد است: - مدل را به `agents.defaults.models` اضافه کنید، یا - فهرست مجاز را پاک کنید (`agents.defaults.models` را حذف کنید)، یا @@ -138,10 +139,12 @@ Model "provider/model" is not allowed. Use /model to list available models. +وقتی فرمان ردشده شامل یک بازنویسی زمان‌اجرا مانند `/model openai/gpt-5.5 --runtime codex` بود، ابتدا فهرست مجاز را اصلاح کنید، سپس همان فرمان `/model ... --runtime ...` را دوباره امتحان کنید. برای اجرای بومی Codex، مدل انتخاب‌شده همچنان `openai/gpt-5.5` است؛ زمان‌اجرای `codex` harness را انتخاب می‌کند و احراز هویت Codex را جداگانه به‌کار می‌برد. + برای مدل‌های محلی/GGUF، ارجاع کامل دارای پیشوند ارائه‌دهنده را در فهرست مجاز ذخیره کنید، برای مثال `ollama/gemma4:26b`، `lmstudio/Gemma4-26b-a4-it-gguf`، یا -ارائه‌دهنده/مدل دقیقی که توسط `openclaw models list --provider ` نشان داده می‌شود. -نام فایل‌های محلی بدون پیشوند یا نام‌های نمایشی وقتی فهرست مجاز +ارائه‌دهنده/مدل دقیقی که توسط `openclaw models list --provider ` نمایش داده می‌شود. +نام فایل‌های محلی خام یا نام‌های نمایشی وقتی فهرست مجاز فعال است کافی نیستند. نمونه پیکربندی فهرست مجاز: @@ -172,33 +175,33 @@ Model "provider/model" is not allowed. Use /model to list available models. - - `/model` (و `/model list`) یک انتخابگر فشرده و شماره‌دار است (خانواده مدل + ارائه‌دهندگان موجود). - - در Discord، `/model` و `/models` یک انتخابگر تعاملی با کشویی‌های ارائه‌دهنده و مدل به‌همراه گام Submit باز می‌کنند. + - `/model` (و `/model list`) یک انتخابگر فشرده و شماره‌گذاری‌شده است (خانواده مدل + ارائه‌دهندگان موجود). + - در Discord، `/model` و `/models` یک انتخابگر تعاملی با dropdownهای ارائه‌دهنده و مدل به‌همراه گام Submit باز می‌کنند. - در Telegram، انتخاب‌های انتخابگر `/models` محدود به نشست هستند؛ آن‌ها پیش‌فرض پایدار عامل را در `openclaw.json` تغییر نمی‌دهند. - `/models add` منسوخ شده است و اکنون به‌جای ثبت مدل‌ها از گفت‌وگو، پیام منسوخ‌شدن برمی‌گرداند. - `/model <#>` از همان انتخابگر انتخاب می‌کند. - - - `/model` انتخاب جدید نشست را بلافاصله پایدار می‌کند. - - اگر عامل بیکار باشد، اجرای بعدی فورا از مدل جدید استفاده می‌کند. - - اگر اجرایی از قبل فعال باشد، OpenClaw تغییر زنده را به‌عنوان در انتظار علامت‌گذاری می‌کند و فقط در یک نقطه تلاش مجدد تمیز با مدل جدید دوباره شروع می‌کند. - - اگر فعالیت ابزار یا خروجی پاسخ از قبل شروع شده باشد، تغییر در انتظار می‌تواند تا فرصت تلاش مجدد بعدی یا نوبت بعدی کاربر در صف بماند. - - ارجاع `/model` انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر ارائه‌دهنده/مدل انتخاب‌شده دسترس‌ناپذیر باشد، پاسخ به‌جای پاسخ‌دادن بی‌سروصدا از `agents.defaults.model.fallbacks`، آشکارا شکست می‌خورد. این با پیش‌فرض‌های پیکربندی‌شده و مدل‌های اصلی کار cron متفاوت است؛ آن‌ها همچنان می‌توانند از زنجیره‌های جایگزین استفاده کنند. - - `/model status` نمای جزئیات است (گزینه‌های احراز هویت و، وقتی پیکربندی شده باشد، نقطه پایانی ارائه‌دهنده `baseUrl` + حالت `api`). + + - `/model` انتخاب نشست جدید را فوراً پایدار می‌کند. + - اگر عامل بیکار باشد، اجرای بعدی بلافاصله از مدل جدید استفاده می‌کند. + - اگر یک اجرا از قبل فعال باشد، OpenClaw تغییر زنده را در حالت در انتظار علامت‌گذاری می‌کند و فقط در یک نقطه تلاش مجدد تمیز به مدل جدید راه‌اندازی دوباره می‌شود. + - اگر فعالیت ابزار یا خروجی پاسخ از قبل شروع شده باشد، تغییر در انتظار می‌تواند تا یک فرصت تلاش مجدد بعدی یا نوبت بعدی کاربر در صف بماند. + - ارجاع `/model` انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، پاسخ به‌جای پاسخ دادن بی‌صدا از `agents.defaults.model.fallbacks` به‌صورت آشکار شکست می‌خورد. این با پیش‌فرض‌های پیکربندی‌شده و مدل‌های اصلی کار cron متفاوت است، که همچنان می‌توانند از زنجیره‌های جایگزین استفاده کنند. + - `/model status` نمای جزئیات است (نامزدهای احراز هویت و، در صورت پیکربندی، endpoint ارائه‌دهنده `baseUrl` + حالت `api`). - - ارجاع‌های مدل با جداکردن روی **اولین** `/` تجزیه می‌شوند. هنگام تایپ `/model ` از `provider/model` استفاده کنید. + - ارجاع‌های مدل با تقسیم روی **اولین** `/` تجزیه می‌شوند. هنگام تایپ `/model ` از `provider/model` استفاده کنید. - اگر خود شناسه مدل شامل `/` باشد (سبک OpenRouter)، باید پیشوند ارائه‌دهنده را وارد کنید (مثال: `/model openrouter/moonshotai/kimi-k2`). - اگر ارائه‌دهنده را حذف کنید، OpenClaw ورودی را به این ترتیب حل می‌کند: - 1. تطبیق نام مستعار - 2. تطبیق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه مدل بدون پیشوند دقیق - 3. بازگشت منسوخ به ارائه‌دهنده پیش‌فرض پیکربندی‌شده — اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را عرضه نکند، OpenClaw برای جلوگیری از نمایش پیش‌فرض کهنه مربوط به ارائه‌دهنده حذف‌شده، در عوض به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد. + 1. تطابق alias + 2. تطابق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه مدل بدون پیشوند دقیق + 3. بازگشت منسوخ‌شده به ارائه‌دهنده پیش‌فرض پیکربندی‌شده — اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش پیش‌فرض کهنه ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد. -رفتار/پیکربندی کامل فرمان: [فرمان‌های اسلش](/fa/tools/slash-commands). +رفتار/پیکربندی کامل فرمان: [فرمان‌های Slash](/fa/tools/slash-commands). ## فرمان‌های CLI @@ -227,41 +230,41 @@ openclaw models image-fallbacks clear ### `models list` -به‌طور پیش‌فرض مدل‌های پیکربندی‌شده/دارای احراز هویت در دسترس را نشان می‌دهد. پرچم‌های مفید: +مدل‌های پیکربندی‌شده/دارای احراز هویت موجود را به‌صورت پیش‌فرض نشان می‌دهد. پرچم‌های مفید: - کاتالوگ کامل. شامل ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهنده‌های همراه، پیش از پیکربندی احراز هویت است؛ بنابراین نماهای فقط-کشف می‌توانند مدل‌هایی را نشان دهند که تا زمانی که اعتبارنامه‌های مطابق ارائه‌دهنده را اضافه نکنید در دسترس نیستند. + کاتالوگ کامل. ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهنده‌های همراه را پیش از پیکربندی احراز هویت شامل می‌شود، بنابراین نماهای صرفاً اکتشافی می‌توانند مدل‌هایی را نشان دهند که تا وقتی اعتبارنامه‌های ارائه‌دهنده متناظر را اضافه نکنید در دسترس نیستند. فقط ارائه‌دهنده‌های محلی. - فیلتر بر اساس شناسهٔ ارائه‌دهنده، برای مثال `moonshot`. برچسب‌های نمایشی از انتخاب‌گرهای تعاملی پذیرفته نمی‌شوند. + فیلتر بر اساس شناسه ارائه‌دهنده، برای مثال `moonshot`. برچسب‌های نمایشی از انتخاب‌گرهای تعاملی پذیرفته نمی‌شوند. - هر خط یک مدل. + هر مدل در یک خط. - خروجی قابل خواندن برای ماشین. + خروجی قابل خواندن توسط ماشین. ### `models status` -مدل اصلی حل‌شده، جایگزین‌ها، مدل تصویر و نمای کلی احراز هویت ارائه‌دهنده‌های پیکربندی‌شده را نشان می‌دهد. همچنین وضعیت انقضای OAuth را برای پروفایل‌های یافت‌شده در ذخیره‌گاه احراز هویت نمایش می‌دهد (به‌طور پیش‌فرض در بازهٔ ۲۴ ساعت هشدار می‌دهد). `--plain` فقط مدل اصلی حل‌شده را چاپ می‌کند. +مدل اصلی حل‌شده، جایگزین‌ها، مدل تصویر، و نمای کلی احراز هویت ارائه‌دهنده‌های پیکربندی‌شده را نشان می‌دهد. همچنین وضعیت انقضای OAuth را برای پروفایل‌های موجود در ذخیره‌گاه احراز هویت نمایش می‌دهد (به‌صورت پیش‌فرض در بازه ۲۴ ساعت هشدار می‌دهد). `--plain` فقط مدل اصلی حل‌شده را چاپ می‌کند. - - - وضعیت OAuth همیشه نشان داده می‌شود (و در خروجی `--json` هم گنجانده می‌شود). اگر ارائه‌دهندهٔ پیکربندی‌شده اعتبارنامه نداشته باشد، `models status` بخشی با عنوان **احراز هویت موجود نیست** چاپ می‌کند. - - JSON شامل `auth.oauth` (بازهٔ هشدار + پروفایل‌ها) و `auth.providers` (احراز هویت مؤثر برای هر ارائه‌دهنده، شامل اعتبارنامه‌های مبتنی بر env) است. `auth.oauth` فقط سلامت پروفایل‌های ذخیره‌گاه احراز هویت است؛ ارائه‌دهنده‌های فقط-env در آن ظاهر نمی‌شوند. - - برای خودکارسازی از `--check` استفاده کنید (در صورت نبود یا انقضا، خروج با `1`؛ در صورت نزدیک بودن انقضا، خروج با `2`). - - برای بررسی‌های زندهٔ احراز هویت از `--probe` استفاده کنید؛ ردیف‌های پروب می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env، یا `models.json` بیایند. - - اگر `auth.order.` صریح یک پروفایل ذخیره‌شده را حذف کند، پروب به‌جای تلاش برای استفاده از آن، `excluded_by_auth_order` گزارش می‌کند. اگر احراز هویت وجود داشته باشد اما هیچ مدل قابل پروبی برای آن ارائه‌دهنده حل نشود، پروب `status: no_model` گزارش می‌کند. + + - وضعیت OAuth همیشه نشان داده می‌شود (و در خروجی `--json` هم گنجانده می‌شود). اگر یک ارائه‌دهنده پیکربندی‌شده اعتبارنامه نداشته باشد، `models status` یک بخش **احراز هویت مفقود** چاپ می‌کند. + - JSON شامل `auth.oauth` (پنجره هشدار + پروفایل‌ها) و `auth.providers` (احراز هویت مؤثر برای هر ارائه‌دهنده، از جمله اعتبارنامه‌های مبتنی بر env) است. `auth.oauth` فقط سلامت پروفایل‌های ذخیره‌گاه احراز هویت است؛ ارائه‌دهنده‌های فقط env در آن ظاهر نمی‌شوند. + - برای خودکارسازی از `--check` استفاده کنید (کد خروج `1` هنگام فقدان/انقضا، `2` هنگام نزدیک بودن انقضا). + - برای بررسی‌های زنده احراز هویت از `--probe` استفاده کنید؛ ردیف‌های آزمون می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env، یا `models.json` بیایند. + - اگر `auth.order.` صریح یک پروفایل ذخیره‌شده را حذف کند، آزمون به‌جای تلاش برای آن، `excluded_by_auth_order` گزارش می‌دهد. اگر احراز هویت وجود داشته باشد اما هیچ مدل قابل آزمونی برای آن ارائه‌دهنده قابل حل نباشد، آزمون `status: no_model` گزارش می‌دهد. -انتخاب احراز هویت به ارائه‌دهنده/حساب وابسته است. برای میزبان‌های Gateway همیشه‌روشن، کلیدهای API معمولاً قابل پیش‌بینی‌ترین گزینه هستند؛ استفادهٔ دوباره از Claude CLI و پروفایل‌های OAuth/توکن موجود Anthropic نیز پشتیبانی می‌شود. +انتخاب احراز هویت به ارائه‌دهنده/حساب وابسته است. برای میزبان‌های Gateway همیشه‌روشن، کلیدهای API معمولاً قابل پیش‌بینی‌ترین گزینه‌اند؛ استفاده مجدد از Claude CLI و پروفایل‌های موجود OAuth/توکن Anthropic نیز پشتیبانی می‌شوند. مثال (Claude CLI): @@ -273,78 +276,78 @@ openclaw models status ## اسکن (مدل‌های رایگان OpenRouter) -`openclaw models scan` **کاتالوگ مدل‌های رایگان** OpenRouter را بررسی می‌کند و می‌تواند به‌صورت اختیاری مدل‌ها را برای پشتیبانی از ابزار و تصویر پروب کند. +`openclaw models scan` **کاتالوگ مدل رایگان** OpenRouter را بررسی می‌کند و می‌تواند به‌صورت اختیاری مدل‌ها را برای پشتیبانی از ابزار و تصویر بیازماید. - پروب‌های زنده را رد کنید (فقط فراداده). + آزمون‌های زنده را رد کن (فقط فراداده). - حداقل اندازهٔ پارامتر (میلیارد). + حداقل اندازه پارامتر (میلیارد). - مدل‌های قدیمی‌تر را رد کنید. + مدل‌های قدیمی‌تر را رد کن. فیلتر پیشوند ارائه‌دهنده. - اندازهٔ فهرست جایگزین‌ها. + اندازه فهرست جایگزین‌ها. - `agents.defaults.model.primary` را روی اولین انتخاب تنظیم کنید. + `agents.defaults.model.primary` را روی نخستین انتخاب تنظیم کن. - `agents.defaults.imageModel.primary` را روی اولین انتخاب تصویر تنظیم کنید. + `agents.defaults.imageModel.primary` را روی نخستین انتخاب تصویر تنظیم کن. -کاتالوگ `/models` در OpenRouter عمومی است، بنابراین اسکن‌های فقط-فراداده می‌توانند نامزدهای رایگان را بدون کلید فهرست کنند. پروب و استنتاج همچنان به یک کلید API برای OpenRouter نیاز دارند (از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY`). اگر کلیدی در دسترس نباشد، `openclaw models scan` به خروجی فقط-فراداده برمی‌گردد و پیکربندی را بدون تغییر می‌گذارد. برای درخواست صریح حالت فقط-فراداده از `--no-probe` استفاده کنید. +کاتالوگ `/models` در OpenRouter عمومی است، بنابراین اسکن‌های فقط فراداده می‌توانند گزینه‌های رایگان را بدون کلید فهرست کنند. آزمون و استنتاج همچنان به کلید API OpenRouter نیاز دارند (از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY`). اگر کلیدی در دسترس نباشد، `openclaw models scan` به خروجی فقط فراداده برمی‌گردد و پیکربندی را بدون تغییر می‌گذارد. برای درخواست صریح حالت فقط فراداده از `--no-probe` استفاده کنید. -نتایج اسکن بر اساس این موارد رتبه‌بندی می‌شوند: +نتایج اسکن بر اساس موارد زیر رتبه‌بندی می‌شوند: -1. پشتیبانی از تصویر +1. پشتیبانی تصویر 2. تأخیر ابزار -3. اندازهٔ زمینه +3. اندازه زمینه 4. تعداد پارامترها ورودی: - فهرست `/models` در OpenRouter (فیلتر `:free`) -- پروب‌های زنده به کلید API برای OpenRouter از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY` نیاز دارند (نگاه کنید به [متغیرهای محیطی](/fa/help/environment)) +- آزمون‌های زنده به کلید API OpenRouter از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY` نیاز دارند (نگاه کنید به [متغیرهای محیطی](/fa/help/environment)) - فیلترهای اختیاری: `--max-age-days`، `--min-params`، `--provider`، `--max-candidates` -- کنترل‌های درخواست/پروب: `--timeout`، `--concurrency` +- کنترل‌های درخواست/آزمون: `--timeout`، `--concurrency` -وقتی پروب‌های زنده در یک TTY اجرا می‌شوند، می‌توانید جایگزین‌ها را به‌صورت تعاملی انتخاب کنید. در حالت غیرتعاملی، برای پذیرش پیش‌فرض‌ها `--yes` را پاس دهید. نتایج فقط-فراداده اطلاع‌رسانی هستند؛ `--set-default` و `--set-image` به پروب‌های زنده نیاز دارند تا OpenClaw یک مدل OpenRouter بدون کلید و غیرقابل استفاده را پیکربندی نکند. +وقتی آزمون‌های زنده در TTY اجرا می‌شوند، می‌توانید جایگزین‌ها را به‌صورت تعاملی انتخاب کنید. در حالت غیرتعاملی، برای پذیرش پیش‌فرض‌ها `--yes` را پاس دهید. نتایج فقط فراداده اطلاع‌رسانی هستند؛ `--set-default` و `--set-image` به آزمون‌های زنده نیاز دارند تا OpenClaw یک مدل OpenRouter بدون کلید و غیرقابل استفاده را پیکربندی نکند. ## رجیستری مدل‌ها (`models.json`) -ارائه‌دهنده‌های سفارشی در `models.providers` در `models.json` زیر پوشهٔ عامل نوشته می‌شوند (پیش‌فرض `~/.openclaw/agents//agent/models.json`). این فایل به‌طور پیش‌فرض ادغام می‌شود، مگر اینکه `models.mode` روی `replace` تنظیم شده باشد. +ارائه‌دهنده‌های سفارشی در `models.providers` در `models.json` زیر دایرکتوری عامل نوشته می‌شوند (پیش‌فرض `~/.openclaw/agents//agent/models.json`). این فایل به‌صورت پیش‌فرض ادغام می‌شود، مگر اینکه `models.mode` روی `replace` تنظیم شده باشد. - - اولویت حالت ادغام برای شناسه‌های ارائه‌دهندهٔ مطابق: + + تقدم حالت ادغام برای شناسه‌های ارائه‌دهنده مطابق: - - `baseUrl` غیرخالی که از قبل در `models.json` عامل وجود دارد برنده است. - - `apiKey` غیرخالی در `models.json` عامل فقط زمانی برنده است که آن ارائه‌دهنده در زمینهٔ پیکربندی/پروفایل احراز هویت فعلی با SecretRef مدیریت نشده باشد. - - مقدارهای `apiKey` ارائه‌دهنده‌های مدیریت‌شده با SecretRef به‌جای پایدارسازی رازهای حل‌شده، از نشانگرهای منبع (`ENV_VAR_NAME` برای ارجاع‌های env، و `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. - - مقدارهای header ارائه‌دهنده‌های مدیریت‌شده با SecretRef از نشانگرهای منبع (`secretref-env:ENV_VAR_NAME` برای ارجاع‌های env، و `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. - - `apiKey`/`baseUrl` خالی یا موجود نبودن آن‌ها در عامل به `models.providers` پیکربندی برمی‌گردد. - - سایر فیلدهای ارائه‌دهنده از پیکربندی و داده‌های کاتالوگ نرمال‌سازی‌شده تازه‌سازی می‌شوند. + - `baseUrl` غیرخالی که از قبل در `models.json` عامل وجود دارد برنده می‌شود. + - `apiKey` غیرخالی در `models.json` عامل فقط وقتی برنده می‌شود که آن ارائه‌دهنده در زمینه فعلی پیکربندی/پروفایل احراز هویت توسط SecretRef مدیریت نشده باشد. + - مقدارهای `apiKey` ارائه‌دهنده مدیریت‌شده توسط SecretRef به‌جای ماندگار کردن رازهای حل‌شده، از نشانگرهای منبع (`ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. + - مقدارهای هدر ارائه‌دهنده مدیریت‌شده توسط SecretRef از نشانگرهای منبع (`secretref-env:ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. + - `apiKey`/`baseUrl` خالی یا مفقود عامل به `models.providers` در پیکربندی برمی‌گردد. + - فیلدهای دیگر ارائه‌دهنده از پیکربندی و داده‌های کاتالوگ نرمال‌شده تازه‌سازی می‌شوند. -پایداری نشانگرها مبتنی بر منبع مرجع است: OpenClaw نشانگرها را از snapshot پیکربندی منبع فعال (پیش از حل‌کردن) می‌نویسد، نه از مقدارهای راز حل‌شده در زمان اجرا. این رفتار هر زمان که OpenClaw دوباره `models.json` را تولید کند اعمال می‌شود، از جمله مسیرهای فرمان‌محور مانند `openclaw agent`. +ماندگاری نشانگر مبتنی بر منبع معتبر است: OpenClaw نشانگرها را از اسنپ‌شات پیکربندی منبع فعال (پیش از حل‌شدن)، نه از مقدارهای راز حل‌شده زمان اجرا، می‌نویسد. این موضوع هر زمان که OpenClaw، `models.json` را دوباره تولید کند اعمال می‌شود، از جمله مسیرهای مبتنی بر فرمان مثل `openclaw agent`. ## مرتبط -- [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) — زمان‌های اجرای حلقهٔ عامل برای PI، Codex، و عامل‌های دیگر +- [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) — Pi، Codex، و دیگر زمان‌های اجرای حلقه عامل - [مرجع پیکربندی](/fa/gateway/config-agents#agent-defaults) — کلیدهای پیکربندی مدل - [تولید تصویر](/fa/tools/image-generation) — پیکربندی مدل تصویر -- [failover مدل](/fa/concepts/model-failover) — زنجیره‌های جایگزین +- [جابجایی خرابی مدل](/fa/concepts/model-failover) — زنجیره‌های جایگزین - [ارائه‌دهنده‌های مدل](/fa/concepts/model-providers) — مسیریابی و احراز هویت ارائه‌دهنده - [تولید موسیقی](/fa/tools/music-generation) — پیکربندی مدل موسیقی -- [تولید ویدیو](/fa/tools/video-generation) — پیکربندی مدل ویدیو +- [تولید ویدئو](/fa/tools/video-generation) — پیکربندی مدل ویدئو diff --git a/docs/fa/concepts/qa-e2e-automation.md b/docs/fa/concepts/qa-e2e-automation.md index 5b7369783..c9f728c94 100644 --- a/docs/fa/concepts/qa-e2e-automation.md +++ b/docs/fa/concepts/qa-e2e-automation.md @@ -1,82 +1,82 @@ --- read_when: - - درک نحوهٔ قرارگیری اجزای پشتهٔ QA در کنار هم - - گسترش qa-lab، qa-channel یا یک آداپتور انتقال - - افزودن سناریوهای تضمین کیفیت مبتنی بر مخزن - - ساخت اتوماسیون تضمین کیفیت واقع‌گرایانه‌تر برای داشبورد Gateway -summary: 'نمای کلی پشتهٔ تضمین کیفیت: qa-lab، qa-channel، سناریوهای مبتنی بر مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال، و گزارش‌دهی.' + - درک نحوهٔ هماهنگی اجزای پشتهٔ QA + - گسترش qa-lab، qa-channel، یا یک آداپتور انتقال + - افزودن سناریوهای QA مبتنی بر مخزن + - ساخت خودکارسازی تضمین کیفیت واقع‌گرایانه‌تر پیرامون داشبورد Gateway +summary: 'نمای کلی پشته QA: qa-lab، qa-channel، سناریوهای مبتنی بر مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال، و گزارش‌دهی.' title: نمای کلی تضمین کیفیت x-i18n: - generated_at: "2026-05-04T07:05:38Z" + generated_at: "2026-05-05T01:45:48Z" model: gpt-5.5 provider: openai - source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 + source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -استک خصوصی QA برای آن است که OpenClaw را به شکلی واقعی‌تر و -کانال‌محورتر از آنچه یک آزمون واحد می‌تواند انجام دهد، تمرین دهد. +پشتهٔ خصوصی QA برای اجرای OpenClaw به شکلی واقعی‌تر و +کانال‌محورتر از آنچه یک آزمون واحد می‌تواند پوشش دهد طراحی شده است. اجزای فعلی: -- `extensions/qa-channel`: کانال پیام مصنوعی با سطوح DM، کانال، رشته، - واکنش، ویرایش، و حذف. -- `extensions/qa-lab`: رابط کاربری اشکال‌زدا و گذرگاه QA برای مشاهده رونوشت، - تزریق پیام‌های ورودی، و صادر کردن گزارش Markdown. -- `extensions/qa-matrix`، Pluginهای اجراکننده آینده: آداپتورهای انتقال زنده که +- `extensions/qa-channel`: کانال پیام‌رسانی مصنوعی با سطوح پیام مستقیم، کانال، رشته، + واکنش، ویرایش و حذف. +- `extensions/qa-lab`: رابط کاربری اشکال‌زدایی و گذرگاه QA برای مشاهدهٔ رونوشت، + تزریق پیام‌های ورودی و صادر کردن گزارش Markdown. +- `extensions/qa-matrix` و Pluginهای اجرایی آینده: آداپتورهای انتقال زنده که یک کانال واقعی را داخل یک Gateway فرزند QA هدایت می‌کنند. -- `qa/`: دارایی‌های seed پشتیبانی‌شده با مخزن برای وظیفه آغازین و سناریوهای - پایه QA. -- [Mantis](/fa/concepts/mantis): راستی‌آزمایی زنده قبل و بعد برای باگ‌هایی که - به انتقال‌های واقعی، اسکرین‌شات‌های مرورگر، وضعیت VM، و شواهد PR نیاز دارند. +- `qa/`: دارایی‌های اولیهٔ مبتنی بر مخزن برای وظیفهٔ آغازین و سناریوهای + پایهٔ QA. +- [Mantis](/fa/concepts/mantis): راستی‌آزمایی زندهٔ قبل و بعد برای باگ‌هایی که + به انتقال‌های واقعی، نماگرفت‌های مرورگر، وضعیت VM و شواهد PR نیاز دارند. ## سطح فرمان هر جریان QA زیر `pnpm openclaw qa ` اجرا می‌شود. بسیاری از آن‌ها نام‌های مستعار اسکریپتی `pnpm qa:*` -دارند؛ هر دو شکل پشتیبانی می‌شوند. +دارند؛ هر دو فرم پشتیبانی می‌شوند. -| فرمان | هدف | -| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | خودآزمایی QA همراه بسته؛ یک گزارش Markdown می‌نویسد. | -| `qa suite` | سناریوهای پشتیبانی‌شده با مخزن را در برابر مسیر Gateway QA اجرا می‌کند. نام مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM یک‌بارمصرف Linux. | -| `qa coverage` | موجودی پوشش سناریو به صورت markdown را چاپ می‌کند (`--json` برای خروجی ماشینی). | -| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عامل‌محور را می‌نویسد. | -| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با گزارشی داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. | -| `qa manual` | یک اعلان یک‌باره را در برابر مسیر provider/model انتخاب‌شده اجرا می‌کند. | -| `qa ui` | رابط کاربری اشکال‌زدای QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | تصویر ازپیش‌آماده Docker QA را می‌سازد. | -| `qa docker-scaffold` | یک اسکفولد docker-compose برای داشبورد QA + مسیر Gateway می‌نویسد. | -| `qa up` | سایت QA را می‌سازد، استک پشتیبانی‌شده با Docker را شروع می‌کند، URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونه `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). | -| `qa aimock` | فقط سرور provider مربوط به AIMock را شروع می‌کند. | -| `qa mock-openai` | فقط سرور provider سناریوآگاه `mock-openai` را شروع می‌کند. | -| `qa credentials doctor` / `add` / `list` / `remove` | مخزن اعتبارنامه مشترک Convex را مدیریت می‌کند. | -| `qa matrix` | مسیر انتقال زنده در برابر یک homeserver یک‌بارمصرف Tuwunel. [Matrix QA](/fa/concepts/qa-matrix) را ببینید. | -| `qa telegram` | مسیر انتقال زنده در برابر یک گروه خصوصی واقعی Telegram. | -| `qa discord` | مسیر انتقال زنده در برابر یک کانال guild خصوصی واقعی Discord. | -| `qa slack` | مسیر انتقال زنده در برابر یک کانال خصوصی واقعی Slack. | -| `qa mantis` | اجراکننده راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord، smoke دسکتاپ/مرورگر Crabbox، و smoke مربوط به Slack در VNC. [Mantis](/fa/concepts/mantis) را ببینید. | +| فرمان | هدف | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | خودبررسی QA داخلی؛ یک گزارش Markdown می‌نویسد. | +| `qa suite` | سناریوهای مبتنی بر مخزن را روی مسیر QA Gateway اجرا می‌کند. نام مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM لینوکسی یک‌بارمصرف. | +| `qa coverage` | موجودی پوشش سناریو را در قالب markdown چاپ می‌کند (`--json` برای خروجی ماشینی). | +| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عاملی را می‌نویسد. | +| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با گزارش داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. | +| `qa manual` | یک prompt تک‌مرحله‌ای را روی مسیر provider/model انتخاب‌شده اجرا می‌کند. | +| `qa ui` | رابط کاربری اشکال‌زدایی QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | ایمیج Docker از پیش آماده‌شدهٔ QA را می‌سازد. | +| `qa docker-scaffold` | یک داربست docker-compose برای داشبورد QA و مسیر Gateway می‌نویسد. | +| `qa up` | سایت QA را می‌سازد، پشتهٔ مبتنی بر Docker را شروع می‌کند و URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونهٔ `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). | +| `qa aimock` | فقط سرور provider مربوط به AIMock را شروع می‌کند. | +| `qa mock-openai` | فقط سرور provider سناریوآگاه `mock-openai` را شروع می‌کند. | +| `qa credentials doctor` / `add` / `list` / `remove` | مخزن مشترک اعتبارنامه‌های Convex را مدیریت می‌کند. | +| `qa matrix` | مسیر انتقال زنده روی یک homeserver یک‌بارمصرف Tuwunel. [QA ماتریکس](/fa/concepts/qa-matrix) را ببینید. | +| `qa telegram` | مسیر انتقال زنده روی یک گروه خصوصی واقعی Telegram. | +| `qa discord` | مسیر انتقال زنده روی یک کانال صنف خصوصی واقعی Discord. | +| `qa slack` | مسیر انتقال زنده روی یک کانال خصوصی واقعی Slack. | +| `qa mantis` | اجراکنندهٔ راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord، smoke دسکتاپ/مرورگر Crabbox و smoke مربوط به Slack در VNC. [Mantis](/fa/concepts/mantis) را ببینید. | ## جریان اپراتور جریان فعلی اپراتور QA یک سایت QA دوپنجره‌ای است: -- چپ: داشبورد Gateway (Control UI) همراه عامل. -- راست: QA Lab، که رونوشت شبیه Slack و برنامه سناریو را نشان می‌دهد. +- چپ: داشبورد Gateway (رابط کاربری کنترل) همراه با عامل. +- راست: QA Lab، که رونوشت شبیه Slack و طرح سناریو را نشان می‌دهد. -آن را با این اجرا کنید: +آن را با این دستور اجرا کنید: ```bash pnpm qa:lab:up ``` -این فرمان سایت QA را می‌سازد، مسیر Gateway پشتیبانی‌شده با Docker را شروع می‌کند، و صفحه -QA Lab را در دسترس قرار می‌دهد؛ جایی که یک اپراتور یا حلقه خودکار می‌تواند به عامل یک مأموریت QA -بدهد، رفتار واقعی کانال را مشاهده کند، و ثبت کند چه چیزی کار کرد، شکست خورد، یا +این کار سایت QA را می‌سازد، مسیر Gateway مبتنی بر Docker را شروع می‌کند و صفحهٔ +QA Lab را در دسترس قرار می‌دهد؛ جایی که اپراتور یا حلقهٔ خودکارسازی می‌تواند به عامل یک مأموریت QA بدهد، +رفتار واقعی کانال را مشاهده کند و ثبت کند چه چیزی کار کرد، شکست خورد یا مسدود ماند. -برای تکرار سریع‌تر روی رابط کاربری QA Lab بدون ساخت دوباره تصویر Docker در هر بار، -استک را با یک بسته QA Lab متصل‌شده با bind mount شروع کنید: +برای تکرار سریع‌تر روی رابط کاربری QA Lab بدون ساخت دوبارهٔ ایمیج Docker در هر بار، +پشته را با یک بستهٔ QA Lab متصل‌شده با bind mount شروع کنید: ```bash pnpm openclaw qa docker-build-image @@ -85,39 +85,39 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` سرویس‌های Docker را روی یک تصویر ازپیش‌ساخته نگه می‌دارد و -`extensions/qa-lab/web/dist` را داخل کانتینر `qa-lab` با bind mount متصل می‌کند. `qa:lab:watch` -آن بسته را هنگام تغییر دوباره می‌سازد، و مرورگر وقتی hash دارایی QA Lab -تغییر کند به‌صورت خودکار بارگذاری مجدد می‌شود. +`qa:lab:up:fast` سرویس‌های Docker را روی یک ایمیج از پیش ساخته‌شده نگه می‌دارد و +`extensions/qa-lab/web/dist` را با bind mount داخل کانتینر `qa-lab` متصل می‌کند. `qa:lab:watch` +آن بسته را هنگام تغییر دوباره می‌سازد، و مرورگر وقتی هش دارایی QA Lab +تغییر کند به‌طور خودکار بازبارگذاری می‌شود. -برای یک smoke محلی OpenTelemetry trace، اجرا کنید: +برای یک smoke محلی ردگیری OpenTelemetry، اجرا کنید: ```bash pnpm qa:otel:smoke ``` -این اسکریپت یک گیرنده trace محلی OTLP/HTTP را شروع می‌کند، سناریوی QA -`otel-trace-smoke` را با Plugin فعال `diagnostics-otel` اجرا می‌کند، سپس -spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را assert می‌کند: +این اسکریپت یک گیرندهٔ محلی ردگیری OTLP/HTTP را شروع می‌کند، سناریوی QA +`otel-trace-smoke` را با Plugin `diagnostics-otel` فعال اجرا می‌کند، سپس +spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را بررسی می‌کند: `openclaw.run`، `openclaw.harness.run`، `openclaw.model.call`، -`openclaw.context.assembled`، و `openclaw.message.delivery` باید حاضر باشند؛ -فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام diagnostic و -attributeهای `openclaw.content.*` باید بیرون از trace بمانند. این اسکریپت -`otel-smoke-summary.json` را کنار artifactهای مجموعه QA می‌نویسد. +`openclaw.context.assembled` و `openclaw.message.delivery` باید وجود داشته باشند؛ +فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام تشخیصی و +ویژگی‌های `openclaw.content.*` باید بیرون از ردگیری بمانند. این اسکریپت +`otel-smoke-summary.json` را کنار دارایی‌های مجموعهٔ QA می‌نویسد. -QA مشاهده‌پذیری فقط مخصوص checkout منبع باقی می‌ماند. tarball مربوط به npm عمداً -QA Lab را حذف می‌کند، بنابراین مسیرهای انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر instrumentation تشخیصی، -از `pnpm qa:otel:smoke` در یک checkout منبع ساخته‌شده استفاده کنید. +QA مشاهده‌پذیری فقط برای checkout کد منبع می‌ماند. بستهٔ npm tarball عمداً +QA Lab را حذف می‌کند، بنابراین مسیرهای انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر ابزارگذاری تشخیصی، +از یک checkout ساخته‌شدهٔ کد منبع، `pnpm qa:otel:smoke` را اجرا کنید. -برای یک مسیر smoke مربوط به Matrix با انتقال واقعی، اجرا کنید: +برای یک مسیر smoke ماتریکس با انتقال واقعی، اجرا کنید: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -مرجع کامل CLI، کاتالوگ profile/scenario، env varها، و چیدمان artifact برای این مسیر در [Matrix QA](/fa/concepts/qa-matrix) قرار دارد. در یک نگاه: این مسیر یک homeserver یک‌بارمصرف Tuwunel را در Docker فراهم می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA محدود به همان انتقال اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصه JSON، artifact رویدادهای مشاهده‌شده، و log خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-/` می‌نویسد. +مرجع کامل CLI، کاتالوگ profile/scenario، متغیرهای محیطی و چیدمان artifact برای این مسیر در [QA ماتریکس](/fa/concepts/qa-matrix) آمده است. در یک نگاه: این مسیر یک homeserver یک‌بارمصرف Tuwunel را در Docker provision می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA که به همان انتقال محدود شده است اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصهٔ JSON، artifact رویدادهای مشاهده‌شده و گزارش خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-/` می‌نویسد. -برای مسیرهای smoke با انتقال واقعی Telegram، Discord، و Slack: +برای مسیرهای smoke انتقال واقعی Telegram، Discord و Slack: ```bash pnpm openclaw qa telegram @@ -125,9 +125,9 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -این مسیرها یک کانال واقعی ازپیش‌موجود با دو bot (driver + SUT) را هدف می‌گیرند. env varهای لازم، فهرست‌های سناریو، artifactهای خروجی، و مخزن اعتبارنامه Convex در [مرجع QA مربوط به Telegram، Discord، و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند. +آن‌ها یک کانال واقعی از پیش موجود را با دو ربات (driver + SUT) هدف می‌گیرند. متغیرهای محیطی لازم، فهرست سناریوها، artifactهای خروجی و مخزن اعتبارنامهٔ Convex در [مرجع QA برای Telegram، Discord و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند. -برای یک اجرای کامل Slack desktop VM همراه نجات VNC، اجرا کنید: +برای اجرای کامل VM دسکتاپ Slack همراه با نجات VNC، اجرا کنید: ```bash pnpm openclaw qa mantis slack-desktop-smoke \ @@ -136,78 +136,77 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -این فرمان یک ماشین دسکتاپ/مرورگر Crabbox را lease می‌کند، مسیر زنده Slack را -داخل VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، از دسکتاپ تصویر می‌گیرد، و -`slack-qa/` به‌همراه `slack-desktop-smoke.png` را به دایرکتوری artifact -Mantis برمی‌گرداند. پس از ورود دستی به Slack Web از طریق VNC، -`--lease-id ` را دوباره استفاده کنید. با `--gateway-setup`، Mantis یک Gateway پایدار OpenClaw Slack را -داخل VM روی پورت `38973` در حال اجرا باقی می‌گذارد؛ بدون آن، فرمان مسیر QA معمولی -bot-to-bot مربوط به Slack را اجرا می‌کند و پس از ضبط artifact خارج می‌شود. +این فرمان یک ماشین دسکتاپ/مرورگر Crabbox را اجاره می‌کند، مسیر زندهٔ Slack را +داخل VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، از دسکتاپ تصویر می‌گیرد و +`slack-qa/` به‌همراه `slack-desktop-smoke.png` را به دایرکتوری artifact مربوط به Mantis +کپی می‌کند. پس از ورود دستی به Slack Web از طریق VNC، از `--lease-id ` دوباره استفاده کنید. +با `--gateway-setup`، Mantis یک Gateway پایدار OpenClaw برای Slack را +داخل VM روی پورت `38973` در حال اجرا باقی می‌گذارد؛ بدون آن، فرمان مسیر معمول QA ربات‌به‌ربات Slack را اجرا می‌کند و پس از گرفتن artifact خارج می‌شود. -پیش از استفاده از اعتبارنامه‌های زنده pooled، اجرا کنید: +پیش از استفاده از اعتبارنامه‌های زندهٔ تجمیع‌شده، اجرا کنید: ```bash pnpm openclaw qa credentials doctor ``` -doctor محیط broker مربوط به Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند، و وقتی secret نگه‌دارنده حاضر باشد دسترسی admin/list را تأیید می‌کند. برای secretها فقط وضعیت set/missing را گزارش می‌دهد. +doctor محیط broker مربوط به Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند و وقتی secret نگه‌دارنده حاضر باشد دسترس‌پذیری admin/list را تأیید می‌کند. برای secretها فقط وضعیت تنظیم‌شده/غایب را گزارش می‌دهد. ## پوشش انتقال زنده -مسیرهای انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خودشان را بسازند، یک قرارداد مشترک دارند. `qa-channel` مجموعه گسترده رفتار محصول به‌صورت مصنوعی است و بخشی از ماتریس پوشش انتقال زنده نیست. +مسیرهای انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خود را بسازند، یک قرارداد مشترک دارند. `qa-channel` مجموعهٔ گستردهٔ رفتار محصول به‌صورت مصنوعی است و بخشی از ماتریس پوشش انتقال زنده نیست. -| مسیر | Canary | دروازه‌گذاری mention | Bot-to-bot | مسدودسازی allowlist | پاسخ سطح بالا | ازسرگیری پس از restart | پیگیری رشته | جداسازی رشته | مشاهده واکنش | فرمان help | ثبت فرمان بومی | -| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | -| Slack | x | x | x | | | | | | | | | +| مسیر | قناری | دروازه‌بانی منشن | ربات‌به‌ربات | مسدودسازی فهرست مجاز | پاسخ سطح بالا | ازسرگیری پس از راه‌اندازی مجدد | پیگیری رشته | جداسازی رشته | مشاهدهٔ واکنش | فرمان راهنما | ثبت فرمان بومی | +| -------- | ------ | ---------------- | ------------ | --------------------- | -------------- | ------------------------------- | ------------ | ------------- | -------------- | ------------ | ------------- | +| Matrix | x | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | x | | | | | | | x | | +| Discord | x | x | x | | | | | | | | x | +| Slack | x | x | x | | | | | | | | | -این کار `qa-channel` را به‌عنوان مجموعه گسترده رفتار محصول نگه می‌دارد، درحالی‌که Matrix، -Telegram، و انتقال‌های زنده آینده یک چک‌لیست صریح قرارداد انتقال مشترک دارند. +این کار `qa-channel` را به‌عنوان مجموعهٔ گستردهٔ رفتار محصول نگه می‌دارد، در حالی که Matrix، +Telegram و انتقال‌های زندهٔ آینده یک چک‌لیست صریح قرارداد انتقال مشترک دارند. -برای یک مسیر Linux VM یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید: +برای یک مسیر VM لینوکسی یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -این کار یک مهمان تازه Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را -داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش عادی QA و -خلاصه را به `.artifacts/qa-e2e/...` روی میزبان کپی می‌کند. -این همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد، دوباره استفاده می‌کند. -اجرای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌طور موازی -با workerهای Gateway ایزوله اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض هم‌روندی -4 دارد که به تعداد سناریوهای انتخاب‌شده محدود می‌شود. از `--concurrency ` برای تنظیم -تعداد workerها، یا از `--concurrency 1` برای اجرای سریالی استفاده کنید. +این فرمان یک مهمان تازه‌ی Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را +داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش و +خلاصه‌ی معمول QA را به `.artifacts/qa-e2e/...` روی میزبان کپی می‌کند. +این فرمان همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد دوباره استفاده می‌کند. +اجرای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی +با کارگرهای Gateway ایزوله اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض هم‌زمانی +4 دارد، که با تعداد سناریوهای انتخاب‌شده محدود می‌شود. برای تنظیم تعداد +کارگرها از `--concurrency ` استفاده کنید، یا برای اجرای ترتیبی از `--concurrency 1` استفاده کنید. وقتی هر سناریویی شکست بخورد، فرمان با کد غیرصفر خارج می‌شود. وقتی -artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. -اجرای زنده ورودی‌های پشتیبانی‌شده احراز هویت QA را که برای مهمان عملی هستند -forward می‌کند: کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و -`CODEX_HOME` در صورت وجود. `--output-dir` را زیر ریشه repo نگه دارید تا مهمان -بتواند از طریق workspace mountشده بنویسد. +مصنوعات را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. +اجراهای زنده ورودی‌های احراز هویت QA پشتیبانی‌شده‌ای را که برای +مهمان عملی هستند ارسال می‌کنند: کلیدهای ارائه‌دهنده مبتنی بر env، مسیر پیکربندی ارائه‌دهنده زنده QA، و +`CODEX_HOME` در صورت وجود. `--output-dir` را زیر ریشه‌ی repo نگه دارید تا مهمان +بتواند از طریق فضای کاری mount‌شده دوباره بنویسد. -## مرجع QA برای Telegram، Discord، و Slack +## مرجع QA برای Telegram، Discord و Slack -Matrix به‌دلیل تعداد سناریوها و آماده‌سازی homeserver مبتنی بر Docker یک [صفحه اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord، و Slack کوچک‌تر هستند — هرکدام چند سناریو، بدون سیستم profile، در برابر کانال‌های واقعی از پیش موجود — بنابراین مرجع آن‌ها اینجا قرار دارد. +Matrix به‌دلیل تعداد سناریوهایش و آماده‌سازی homeserver مبتنی بر Docker یک [صفحه‌ی اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord و Slack کوچک‌تر هستند — هرکدام چند سناریو، بدون سیستم پروفایل، در برابر کانال‌های واقعی از قبل موجود — بنابراین مرجع آن‌ها اینجا قرار دارد. ### پرچم‌های مشترک CLI -این laneها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند: +این مسیرها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند: -| پرچم | پیش‌فرض | توضیح | -| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | فقط این سناریو را اجرا می‌کند. قابل تکرار است. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | محل نوشتن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. | -| `--repo-root ` | `process.cwd()` | ریشه repository هنگام فراخوانی از یک cwd خنثی. | -| `--sut-account ` | `sut` | id حساب موقت داخل پیکربندی Gateway QA. | -| `--provider-mode ` | `live-frontier` | `mock-openai` یا `live-frontier`؛ مقدار قدیمی `live-openai` همچنان کار می‌کند. | -| `--model ` / `--alt-model ` | پیش‌فرض provider | refهای model اصلی/جایگزین. | -| `--fast` | خاموش | حالت سریع provider در جاهایی که پشتیبانی می‌شود. | -| `--credential-source ` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. | -| `--credential-role ` | `ci` در CI، در غیر این صورت `maintainer` | نقشی که هنگام `--credential-source convex` استفاده می‌شود. | +| پرچم | پیش‌فرض | توضیح | +| ------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | فقط همین سناریو را اجرا می‌کند. قابل تکرار است. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | جایی که گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی نوشته می‌شوند. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. | +| `--repo-root ` | `process.cwd()` | ریشه‌ی مخزن هنگام فراخوانی از یک cwd خنثی. | +| `--sut-account ` | `sut` | شناسه‌ی حساب موقت داخل پیکربندی Gateway QA. | +| `--provider-mode ` | `live-frontier` | `mock-openai` یا `live-frontier` (`live-openai` قدیمی همچنان کار می‌کند). | +| `--model ` / `--alt-model ` | پیش‌فرض ارائه‌دهنده | ارجاع‌های مدل اصلی/جایگزین. | +| `--fast` | خاموش | حالت سریع ارائه‌دهنده، در صورت پشتیبانی. | +| `--credential-source ` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. | +| `--credential-role ` | در CI مقدار `ci`، در غیر این صورت `maintainer` | نقشی که هنگام `--credential-source convex` استفاده می‌شود. | -هر lane در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` artifactها را بدون تنظیم کد خروج شکست‌خورده می‌نویسد. +هر مسیر در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` مصنوعات را بدون تنظیم کد خروج شکست‌خورده می‌نویسد. ### QA برای Telegram @@ -215,17 +214,17 @@ Matrix به‌دلیل تعداد سناریوها و آماده‌سازی home pnpm openclaw qa telegram ``` -یک گروه خصوصی واقعی Telegram را با دو bot متمایز (driver + SUT) هدف می‌گیرد. bot مربوط به SUT باید username در Telegram داشته باشد؛ مشاهده bot-to-bot وقتی بهتر کار می‌کند که هر دو bot **Bot-to-Bot Communication Mode** را در `@BotFather` فعال کرده باشند. +یک گروه خصوصی واقعی Telegram را با دو ربات متمایز هدف می‌گیرد (driver + SUT). ربات SUT باید نام کاربری Telegram داشته باشد؛ مشاهده‌ی ربات به ربات وقتی هر دو ربات **Bot-to-Bot Communication Mode** را در `@BotFather` فعال کرده باشند بهترین عملکرد را دارد. -envهای لازم هنگام `--credential-source env`: +env ضروری هنگام `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — chat id عددی (string). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — شناسه‌ی عددی چت (رشته). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` اختیاری: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد (پیش‌فرض redact می‌کند). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه‌ی پیام‌ها را در مصنوعات پیام‌های مشاهده‌شده نگه می‌دارد (پیش‌فرض آن‌ها را redact می‌کند). سناریوها (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -238,10 +237,10 @@ envهای لازم هنگام `--credential-source env`: - `telegram-whoami-command` - `telegram-context-command` -artifactهای خروجی: +مصنوعات خروجی: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — شامل RTT برای هر reply (ارسال driver → reply مشاهده‌شده SUT) از canary به بعد. +- `telegram-qa-summary.json` — شامل RTT هر پاسخ (ارسال driver → پاسخ مشاهده‌شده‌ی SUT) از canary به بعد. - `telegram-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` باشد. ### QA برای Discord @@ -250,28 +249,28 @@ artifactهای خروجی: pnpm openclaw qa discord ``` -یک کانال guild خصوصی واقعی Discord را با دو bot هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Discord راه‌اندازی می‌شود. مدیریت mention کانال، اینکه bot مربوط به SUT فرمان native `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد Mantis به‌صورت opt-in را بررسی می‌کند. +یک کانال guild خصوصی واقعی Discord را با دو ربات هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده‌ی Discord شروع می‌شود. مدیریت mention کانال، اینکه ربات SUT فرمان بومی `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد Mantis مبتنی بر opt-in را بررسی می‌کند. -envهای لازم هنگام `--credential-source env`: +env ضروری هنگام `--credential-source env`: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با id کاربر bot مربوط به SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت lane زود شکست می‌خورد). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با شناسه‌ی کاربر ربات SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت مسیر سریع شکست می‌خورد). اختیاری: -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد. +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه‌ی پیام‌ها را در مصنوعات پیام‌های مشاهده‌شده نگه می‌دارد. سناریوها (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`): - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — سناریوی opt-in Mantis. به‌تنهایی اجرا می‌شود چون SUT را به replyهای guild همیشه‌فعال و فقط ابزاری با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک timeline واکنش REST به‌همراه یک artifact بصری HTML/PNG ثبت می‌کند. +- `discord-status-reactions-tool-only` — سناریوی Mantis مبتنی بر opt-in. به‌تنهایی اجرا می‌شود چون SUT را به پاسخ‌های guild همیشه‌روشن و فقط ابزار با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک timeline واکنش REST به‌همراه یک مصنوع دیداری HTML/PNG را ضبط می‌کند. -سناریوی واکنش وضعیت Mantis را صراحتا اجرا کنید: +سناریوی واکنش وضعیت Mantis را صریح اجرا کنید: ```bash pnpm openclaw qa discord \ @@ -282,7 +281,7 @@ pnpm openclaw qa discord \ --fast ``` -artifactهای خروجی: +مصنوعات خروجی: - `discord-qa-report.md` - `discord-qa-summary.json` @@ -295,9 +294,9 @@ artifactهای خروجی: pnpm openclaw qa slack ``` -یک کانال خصوصی واقعی Slack را با دو bot متمایز هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Slack راه‌اندازی می‌شود. +یک کانال خصوصی واقعی Slack را با دو ربات متمایز هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده‌ی Slack شروع می‌شود. -envهای لازم هنگام `--credential-source env`: +env ضروری هنگام `--credential-source env`: - `OPENCLAW_QA_SLACK_CHANNEL_ID` - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` @@ -306,67 +305,235 @@ envهای لازم هنگام `--credential-source env`: اختیاری: -- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد. +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه‌ی پیام‌ها را در مصنوعات پیام‌های مشاهده‌شده نگه می‌دارد. سناریوها (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`): - `slack-canary` - `slack-mention-gating` -artifactهای خروجی: +مصنوعات خروجی: - `slack-qa-report.md` - `slack-qa-summary.json` - `slack-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` باشد. -### استخر اعتبارنامه Convex +#### راه‌اندازی فضای کاری Slack -laneهای Telegram، Discord، و Slack می‌توانند به‌جای خواندن env varهای بالا، اعتبارنامه‌ها را از یک استخر مشترک Convex اجاره کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک lease انحصاری دریافت می‌کند، در طول اجرا برای آن heartbeat می‌فرستد، و هنگام shutdown آن را آزاد می‌کند. انواع استخر `"telegram"`، `"discord"`، و `"slack"` هستند. +این مسیر به دو برنامه‌ی Slack متمایز در یک فضای کاری نیاز دارد، به‌علاوه‌ی کانالی که هر دو ربات عضو آن باشند: + +- `channelId` — شناسه‌ی `Cxxxxxxxxxx` کانالی که هر دو ربات به آن دعوت شده‌اند. از یک کانال اختصاصی استفاده کنید؛ این مسیر در هر اجرا پیام ارسال می‌کند. +- `driverBotToken` — توکن ربات (`xoxb-...`) برنامه‌ی **Driver**. +- `sutBotToken` — توکن ربات (`xoxb-...`) برنامه‌ی **SUT**، که باید یک برنامه‌ی Slack جدا از driver باشد تا شناسه‌ی کاربر ربات آن متمایز باشد. +- `sutAppToken` — توکن سطح برنامه (`xapp-...`) برنامه‌ی SUT با `connections:write`، که توسط Socket Mode استفاده می‌شود تا برنامه‌ی SUT بتواند رویدادها را دریافت کند. + +یک فضای کاری Slack اختصاصی برای QA را به استفاده‌ی دوباره از یک فضای کاری production ترجیح دهید. + +manifest زیر برای SUT نصب production مربوط به Plugin بسته‌بندی‌شده‌ی Slack را منعکس می‌کند (`extensions/slack/src/setup-shared.ts:10`). برای راه‌اندازی کانال production همان‌طور که کاربران آن را می‌بینند، [راه‌اندازی سریع کانال Slack](/fa/channels/slack#quick-setup) را ببینید؛ جفت Driver/SUT مربوط به QA عمداً جداست چون این مسیر به دو شناسه‌ی کاربر ربات متمایز در یک فضای کاری نیاز دارد. + +**1. برنامه‌ی Driver را ایجاد کنید** + +به [api.slack.com/apps](https://api.slack.com/apps) بروید → _Create New App_ → _From a manifest_ → فضای کاری QA را انتخاب کنید، manifest زیر را بچسبانید، سپس _Install to Workspace_ را بزنید: + +```json +{ + "display_information": { + "name": "OpenClaw QA Driver", + "description": "Test driver bot for OpenClaw QA Slack live lane" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA Driver", + "always_online": true + } + }, + "oauth_config": { + "scopes": { + "bot": ["chat:write", "channels:history", "groups:history", "users:read"] + } + }, + "settings": { + "socket_mode_enabled": false + } +} +``` + +_Bot User OAuth Token_ (`xoxb-...`) را کپی کنید — این مقدار `driverBotToken` می‌شود. driver فقط باید پیام ارسال کند و خودش را شناسایی کند؛ بدون رویداد و بدون Socket Mode. + +**2. برنامه‌ی SUT را ایجاد کنید** + +_Create New App → From a manifest_ را در همان فضای کاری تکرار کنید. مجموعه‌ی scope نصب production مربوط به Plugin بسته‌بندی‌شده‌ی Slack را منعکس می‌کند (`extensions/slack/src/setup-shared.ts:10`): + +```json +{ + "display_information": { + "name": "OpenClaw QA SUT", + "description": "OpenClaw QA SUT connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw QA SUT", + "always_online": true + }, + "app_home": { + "home_tab_enabled": true, + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "usergroups:read", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_home_opened", + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + +بعد از اینکه Slack برنامه را ایجاد کرد، دو کار را در صفحه‌ی تنظیمات آن انجام دهید: + +- _Install to Workspace_ → _Bot User OAuth Token_ را کپی کنید → این مقدار `sutBotToken` می‌شود. +- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → scope‏ `connections:write` را اضافه کنید → ذخیره کنید → مقدار `xapp-...` را کپی کنید → این مقدار `sutAppToken` می‌شود. + +با فراخوانی `auth.test` روی هر توکن، بررسی کنید که دو بات شناسه‌های کاربری متمایز داشته باشند. runtime درایور و SUT را با شناسهٔ کاربری از هم تشخیص می‌دهد؛ استفادهٔ دوباره از یک app برای هر دو، gating منشن را بلافاصله با شکست مواجه می‌کند. + +**3. کانال را ایجاد کنید** + +در فضای کاری QA، یک کانال ایجاد کنید (مثلاً `#openclaw-qa`) و هر دو بات را از داخل کانال دعوت کنید: + +``` +/invite @OpenClaw QA Driver +/invite @OpenClaw QA SUT +``` + +شناسهٔ `Cxxxxxxxxxx` را از _channel info → About → Channel ID_ کپی کنید؛ این مقدار به `channelId` تبدیل می‌شود. کانال عمومی کار می‌کند؛ اگر از کانال خصوصی استفاده کنید، هر دو app از قبل `groups:history` دارند، پس خواندن‌های history در harness همچنان موفق خواهند بود. + +**4. اعتبارنامه‌ها را ثبت کنید** + +دو گزینه وجود دارد. برای اشکال‌زدایی روی یک ماشین از env varها استفاده کنید (چهار متغیر `OPENCLAW_QA_SLACK_*` را تنظیم کنید و `--credential-source env` را پاس دهید)، یا مخزن مشترک Convex را seed کنید تا CI و سایر نگه‌دارندگان بتوانند آن‌ها را lease کنند. + +برای مخزن Convex، چهار فیلد را در یک فایل JSON بنویسید: + +```json +{ + "channelId": "Cxxxxxxxxxx", + "driverBotToken": "xoxb-...", + "sutBotToken": "xoxb-...", + "sutAppToken": "xapp-..." +} +``` + +در حالی که `OPENCLAW_QA_CONVEX_SITE_URL` و `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` در shell شما export شده‌اند، ثبت و بررسی کنید: + +```bash +pnpm openclaw qa credentials add \ + --kind slack \ + --payload-file slack-creds.json \ + --note "QA Slack pool seed" + +pnpm openclaw qa credentials list --kind slack --status all --json +``` + +انتظار داشته باشید `count: 1`، `status: "active"` و بدون فیلد `lease` باشد. + +**5. انتها به انتها بررسی کنید** + +lane را به‌صورت محلی اجرا کنید تا تأیید شود هر دو بات می‌توانند از طریق broker با هم صحبت کنند: + +```bash +pnpm openclaw qa slack \ + --credential-source convex \ + --credential-role maintainer \ + --output-dir .artifacts/qa-e2e/slack-local +``` + +یک اجرای سبز در بسیار کمتر از ۳۰ ثانیه کامل می‌شود و `slack-qa-report.md` هر دو `slack-canary` و `slack-mention-gating` را با وضعیت `pass` نشان می‌دهد. اگر lane حدود ۹۰ ثانیه متوقف بماند و با `Convex credential pool exhausted for kind "slack"` خارج شود، یا مخزن خالی است یا هر ردیف lease شده است؛ `qa credentials list --kind slack --status all --json` به شما می‌گوید کدام مورد است. + +### مخزن اعتبارنامهٔ Convex + +laneهای Telegram، Discord و Slack می‌توانند به‌جای خواندن env varهای بالا، اعتبارنامه‌ها را از یک مخزن مشترک Convex lease کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک lease اختصاصی می‌گیرد، در طول اجرا برای آن heartbeat می‌فرستد، و هنگام shutdown آن را آزاد می‌کند. kindهای مخزن `"telegram"`، `"discord"` و `"slack"` هستند. شکل payloadهایی که broker روی `admin/add` اعتبارسنجی می‌کند: -- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک string عددی chat-id باشد. +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک رشتهٔ chat-id عددی باشد. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. +- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` باید با `^[A-Z][A-Z0-9]+$` مطابقت داشته باشد (یک شناسهٔ Slack مانند `Cxxxxxxxxxx`). برای provision کردن app و scopeها، [راه‌اندازی فضای کاری Slack](#setting-up-the-slack-workspace) را ببینید. -env varهای عملیاتی و قرارداد endpoint مربوط به broker در Convex در [Testing → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش پیش از پشتیبانی Discord انتخاب شده است؛ معناشناسی broker برای هر دو نوع یکسان است). +env varهای عملیاتی و قرارداد endpoint broker در [آزمایش → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش مربوط به قبل از پشتیبانی Discord است؛ معناشناسی broker برای هر دو kind یکسان است). -## seedهای مبتنی بر repo +## seedهای پشتیبانی‌شده با repo assetهای seed در `qa/` قرار دارند: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -این‌ها عمدا در git هستند تا برنامه QA هم برای انسان‌ها و هم برای -agent قابل مشاهده باشد. +این‌ها عمداً در git هستند تا طرح QA هم برای انسان‌ها و هم برای agent قابل مشاهده باشد. -`qa-lab` باید یک runner عمومی markdown باقی بماند. هر فایل markdown سناریو -source of truth برای یک اجرای test است و باید موارد زیر را تعریف کند: +`qa-lab` باید یک runner عمومی markdown باقی بماند. هر فایل markdown سناریو منبع حقیقت برای یک اجرای test است و باید این موارد را تعریف کند: - metadata سناریو -- metadata اختیاری category، capability، lane، و risk -- refهای docs و code +- metadata اختیاری category، capability، lane و risk +- ارجاع‌های docs و code - نیازمندی‌های اختیاری Plugin -- patch اختیاری پیکربندی Gateway +- patch اختیاری config Gateway - `qa-flow` قابل اجرا -سطح runtime قابل استفاده مجدد که پشتوانه `qa-flow` است اجازه دارد عمومی -و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport را -با helperهای سمت browser ترکیب کنند که Control UI جاسازی‌شده را از طریق -درز `browser.request` در Gateway پیش می‌برند، بدون اینکه runner ویژه اضافه شود. +سطح runtime قابل استفادهٔ مجدد که از `qa-flow` پشتیبانی می‌کند، مجاز است عمومی و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport را با helperهای سمت browser ترکیب کنند که Control UI توکار را از طریق seam ‏`browser.request` در Gateway هدایت می‌کنند، بدون اینکه runner ویژه اضافه شود. -فایل‌های سناریو باید بر اساس قابلیت محصول گروه‌بندی شوند، نه بر اساس پوشه -source tree. وقتی فایل‌ها جابه‌جا می‌شوند، IDهای سناریو را پایدار نگه دارید؛ از `docsRefs` و `codeRefs` -برای traceability پیاده‌سازی استفاده کنید. +فایل‌های سناریو باید به‌جای پوشهٔ source tree بر اساس قابلیت محصول گروه‌بندی شوند. وقتی فایل‌ها جابه‌جا می‌شوند، شناسه‌های سناریو را پایدار نگه دارید؛ برای قابلیت ردیابی پیاده‌سازی از `docsRefs` و `codeRefs` استفاده کنید. -فهرست baseline باید به‌اندازه کافی گسترده بماند تا موارد زیر را پوشش دهد: +فهرست baseline باید به‌اندازه‌ای گسترده بماند که این موارد را پوشش دهد: -- chat در DM و کانال +- گفت‌وگوی DM و کانال - رفتار thread -- چرخه عمر action پیام +- چرخهٔ حیات action پیام - callbackهای cron -- recall حافظه -- تغییر model +- یادآوری memory +- تعویض model - تحویل به subagent - خواندن repo و خواندن docs - یک task کوچک build مانند Lobster Invaders @@ -375,77 +542,71 @@ source tree. وقتی فایل‌ها جابه‌جا می‌شوند، IDهای `qa suite` دو lane محلی mock provider دارد: -- `mock-openai` mock سناریوآگاه OpenClaw است. این lane همچنان lane پیش‌فرض - mock قطعی برای QA مبتنی بر repo و parity gateها باقی می‌ماند. -- `aimock` یک server provider مبتنی بر AIMock را برای پوشش آزمایشی protocol، - fixture، record/replay، و chaos شروع می‌کند. این مورد افزایشی است و - dispatcher سناریوی `mock-openai` را جایگزین نمی‌کند. +- `mock-openai`، mock سناریوآگاه OpenClaw است. این lane همچنان lane پیش‌فرض mock قطعی برای QA پشتیبانی‌شده با repo و gateهای parity است. +- `aimock` یک server provider پشتیبانی‌شده با AIMock را برای پوشش آزمایشی protocol، fixture، record/replay و chaos شروع می‌کند. این مورد افزایشی است و dispatcher سناریوی `mock-openai` را جایگزین نمی‌کند. -پیاده‌سازی provider-lane زیر `extensions/qa-lab/src/providers/` قرار دارد. -هر provider مالک پیش‌فرض‌ها، startup server محلی، پیکربندی model در Gateway، -نیازهای staging مربوط به auth-profile، و پرچم‌های capability زنده/mock خودش است. کد suite و -Gateway مشترک باید به‌جای branching بر اساس نام providerها، از registry provider عبور کند. +پیاده‌سازی provider-lane زیر `extensions/qa-lab/src/providers/` قرار دارد. هر provider مالک defaultهای خود، startup سرور محلی، config مدل Gateway، نیازهای staging مربوط به auth-profile و flagهای capability زنده/mock است. کد مشترک suite و gateway باید به‌جای branch زدن بر اساس نام provider، از طریق registry provider مسیریابی کند. ## adapterهای transport -`qa-lab` مالک یک درز عمومی transport برای سناریوهای markdown QA است. `qa-channel` اولین adapter روی آن درز است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا synthetic آینده باید به‌جای افزودن runner مخصوص transport برای QA، به همان runner مجموعه وصل شوند. +`qa-lab` مالک یک seam عمومی transport برای سناریوهای QA markdown است. `qa-channel` اولین adapter روی آن seam است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا synthetic آینده باید به‌جای افزودن runner مخصوص QA برای transport، به همان runner suite متصل شوند. -در سطح معماری، تقسیم به این صورت است: +در سطح معماری، تقسیم‌بندی چنین است: -- `qa-lab` مالک اجرای عمومی سناریو، هم‌روندی worker، نوشتن artifact، و reporting است. -- adapter transport مالک پیکربندی Gateway، readiness، مشاهده inbound و outbound، actionهای transport، و وضعیت normalized transport است. -- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای test را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفاده مجدد را فراهم می‌کند که آن‌ها را اجرا می‌کند. +- `qa-lab` مالک اجرای عمومی سناریو، هم‌روندی worker، نوشتن artifact و گزارش‌دهی است. +- adapter transport مالک config Gateway، readiness، مشاهدهٔ inbound و outbound، actionهای transport و state نرمال‌شدهٔ transport است. +- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای test را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفادهٔ مجدد را فراهم می‌کند که آن‌ها را اجرا می‌کند. -### افزودن کانال +### افزودن یک کانال -افزودن یک کانال به سیستم QA مبتنی بر markdown دقیقا به دو چیز نیاز دارد: +افزودن یک کانال به سیستم QA markdown دقیقاً به دو چیز نیاز دارد: 1. یک adapter transport برای کانال. -2. یک بسته سناریو که قرارداد کانال را تمرین دهد. +2. یک بستهٔ سناریو که قرارداد کانال را exercise کند. -وقتی host مشترک `qa-lab` می‌تواند مالک flow باشد، ریشه فرمان QA سطح‌بالای جدید اضافه نکنید. +وقتی host مشترک `qa-lab` می‌تواند مالک flow باشد، root command سطح‌بالای جدید QA اضافه نکنید. -`qa-lab` مکانیک‌های میزبان مشترک را در اختیار دارد: +`qa-lab` مالک مکانیک‌های host مشترک است: -- ریشه فرمان `openclaw qa` -- راه‌اندازی و پاک‌سازی مجموعه +- root command ‏`openclaw qa` +- startup و teardown مجموعه - هم‌روندی worker - نوشتن artifact - تولید گزارش - اجرای سناریو - aliasهای سازگاری برای سناریوهای قدیمی‌تر `qa-channel` -Pluginهای اجراکننده قرارداد انتقال را در اختیار دارند: +Runner Pluginها مالک قرارداد transport هستند: -- اینکه `openclaw qa ` چگونه زیر ریشه مشترک `qa` mount می‌شود -- اینکه Gateway برای آن انتقال چگونه پیکربندی می‌شود -- اینکه آمادگی چگونه بررسی می‌شود -- اینکه رویدادهای ورودی چگونه تزریق می‌شوند -- اینکه پیام‌های خروجی چگونه مشاهده می‌شوند -- اینکه transcriptها و وضعیت نرمال‌سازی‌شده انتقال چگونه عرضه می‌شوند -- اینکه اقدام‌های پشتوانه‌دار با انتقال چگونه اجرا می‌شوند -- اینکه بازنشانی یا پاک‌سازی ویژه انتقال چگونه انجام می‌شود +- اینکه `openclaw qa ` چگونه زیر root مشترک `qa` mount می‌شود +- اینکه Gateway چگونه برای آن transport پیکربندی می‌شود +- اینکه readiness چگونه بررسی می‌شود +- اینکه eventهای inbound چگونه تزریق می‌شوند +- اینکه پیام‌های outbound چگونه مشاهده می‌شوند +- اینکه transcriptها و state نرمال‌شدهٔ transport چگونه expose می‌شوند +- اینکه actionهای پشتیبانی‌شده با transport چگونه اجرا می‌شوند +- اینکه reset یا cleanup مخصوص transport چگونه مدیریت می‌شود -حداقل سطح پذیرش برای یک کانال جدید: +حداقل معیار پذیرش برای یک کانال جدید: -1. `qa-lab` را مالک ریشه مشترک `qa` نگه دارید. -2. اجراکننده انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید. -3. مکانیک‌های ویژه انتقال را داخل Plugin اجراکننده یا harness کانال نگه دارید. -4. اجراکننده را به‌صورت `openclaw qa ` mount کنید، نه با ثبت یک فرمان ریشه رقیب. Pluginهای اجراکننده باید `qaRunners` را در `openclaw.plugin.json` اعلام کنند و آرایه مطابق `qaRunnerCliRegistrations` را از `runtime-api.ts` صادر کنند. `runtime-api.ts` را سبک نگه دارید؛ CLI تنبل و اجرای runner باید پشت entrypointهای جداگانه بمانند. -5. سناریوهای Markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا سازگار کنید. -6. برای سناریوهای جدید از helperهای سناریوی عمومی استفاده کنید. -7. aliasهای سازگاری موجود را فعال نگه دارید، مگر اینکه repo در حال انجام یک مهاجرت عمدی باشد. +1. `qa-lab` را به‌عنوان مالک root مشترک `qa` نگه دارید. +2. runner transport را روی seam host مشترک `qa-lab` پیاده‌سازی کنید. +3. مکانیک‌های مخصوص transport را داخل runner Plugin یا harness کانال نگه دارید. +4. runner را به‌عنوان `openclaw qa ` mount کنید، نه با ثبت یک root command رقیب. Runner Pluginها باید `qaRunners` را در `openclaw.plugin.json` declare کنند و array متناظر `qaRunnerCliRegistrations` را از `runtime-api.ts` export کنند. `runtime-api.ts` را سبک نگه دارید؛ اجرای lazy CLI و runner باید پشت entrypointهای جدا بماند. +5. سناریوهای markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا تطبیق دهید. +6. برای سناریوهای جدید از helperهای عمومی سناریو استفاده کنید. +7. aliasهای سازگاری موجود را فعال نگه دارید، مگر اینکه repo در حال انجام یک migration عمدی باشد. -قاعده تصمیم‌گیری سخت‌گیرانه است: +قاعدهٔ تصمیم‌گیری سخت‌گیرانه است: -- اگر رفتاری را می‌توان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید. -- اگر رفتاری به انتقال یک کانال وابسته است، آن را در همان Plugin اجراکننده یا harness Plugin نگه دارید. -- اگر سناریویی به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای شاخه ویژه کانال در `suite.ts` یک helper عمومی اضافه کنید. -- اگر رفتاری فقط برای یک انتقال معنی‌دار است، سناریو را ویژه همان انتقال نگه دارید و این را در قرارداد سناریو صریح کنید. +- اگر رفتار را بتوان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید. +- اگر رفتار به یک transport کانال وابسته است، آن را در runner Plugin یا harness Plugin همان نگه دارید. +- اگر یک سناریو به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای branch مخصوص کانال در `suite.ts` یک helper عمومی اضافه کنید. +- اگر یک رفتار فقط برای یک transport معنادار است، سناریو را مخصوص همان transport نگه دارید و این را در قرارداد سناریو صریح کنید. ### نام‌های helper سناریو -helperهای عمومی پیشنهادی برای سناریوهای جدید: +helperهای عمومی ترجیحی برای سناریوهای جدید: - `waitForTransportReady` - `waitForChannelReady` @@ -460,22 +621,21 @@ helperهای عمومی پیشنهادی برای سناریوهای جدید: - `formatTransportTranscript` - `resetTransport` -aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس‌اند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نگارش سناریوهای جدید باید از نام‌های عمومی استفاده کند. این aliasها برای جلوگیری از یک مهاجرت یک‌باره وجود دارند، نه به‌عنوان الگوی آینده. +aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس هستند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نگارش سناریوهای جدید باید از نام‌های عمومی استفاده کند. aliasها برای اجتناب از migration یک‌باره وجود دارند، نه به‌عنوان الگوی آینده. ## گزارش‌دهی -`qa-lab` یک گزارش پروتکل Markdown را از timeline مشاهده‌شده bus صادر می‌کند. -گزارش باید پاسخ دهد: +`qa-lab` یک گزارش protocol به Markdown از timeline مشاهده‌شدهٔ bus export می‌کند. +گزارش باید به این پرسش‌ها پاسخ دهد: - چه چیزی کار کرد - چه چیزی شکست خورد -- چه چیزی مسدود ماند -- چه سناریوهای پیگیری ارزش اضافه‌شدن دارند +- چه چیزی همچنان blocked ماند +- چه سناریوهای follow-up ارزش افزودن دارند -برای inventory سناریوهای موجود — که هنگام اندازه‌گیری کار پیگیری یا وصل‌کردن یک انتقال جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (`--json` را برای خروجی قابل‌خواندن برای ماشین اضافه کنید). +برای موجودی سناریوهای در دسترس — که هنگام اندازه‌گیری کار follow-up یا اتصال یک transport جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (برای خروجی machine-readable، `--json` را اضافه کنید). -برای بررسی‌های کاراکتر و سبک، همان سناریو را روی چندین ref مدل زنده اجرا کنید -و یک گزارش Markdown داوری‌شده بنویسید: +برای بررسی‌های character و style، همان سناریو را روی چندین ref مدل زنده اجرا کنید و یک گزارش Markdown داوری‌شده بنویسید: ```bash pnpm openclaw qa character-eval \ @@ -494,42 +654,23 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -این فرمان فرایندهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی کاراکتر -باید persona را از طریق `SOUL.md` تنظیم کنند، سپس نوبت‌های عادی کاربر -مانند chat، کمک workspace و کارهای کوچک فایل را اجرا کنند. به مدل candidate نباید -گفته شود که در حال ارزیابی است. این فرمان هر transcript کامل را حفظ می‌کند، -آمار پایه اجرا را ثبت می‌کند، سپس از مدل‌های judge در حالت سریع با -استدلال `xhigh` در جاهایی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی‌بودن، حس‌وحال و شوخ‌طبعی رتبه‌بندی کنند. -هنگام مقایسه providerها از `--blind-judge-models` استفاده کنید: prompt داور همچنان -هر transcript و وضعیت اجرا را دریافت می‌کند، اما refهای candidate با -برچسب‌های خنثی مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از -parsing رتبه‌بندی‌ها را دوباره به refهای واقعی نگاشت می‌کند. -اجراهای candidate به‌صورت پیش‌فرض از thinking برابر `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh` -برای refهای ارزیابی قدیمی‌تر OpenAI که از آن پشتیبانی می‌کنند. یک candidate مشخص را به‌صورت inline با -`--model provider/model,thinking=` override کنید. `--thinking ` همچنان یک -fallback سراسری تنظیم می‌کند، و فرم قدیمی‌تر `--model-thinking ` برای -سازگاری نگه داشته شده است. -refهای candidate مربوط به OpenAI به‌صورت پیش‌فرض در حالت fast هستند تا در جاهایی که -provider پشتیبانی می‌کند از پردازش priority استفاده شود. وقتی یک -candidate یا judge تکی به override نیاز دارد، `,fast`، `,no-fast` یا `,fast=false` را inline اضافه کنید. فقط وقتی `--fast` را پاس بدهید که می‌خواهید -حالت fast را برای همه مدل‌های candidate اجباری کنید. مدت‌زمان‌های candidate و judge -برای تحلیل benchmark در گزارش ثبت می‌شوند، اما promptهای judge صراحتا می‌گویند -بر اساس سرعت رتبه‌بندی نکنند. -اجرای مدل‌های candidate و judge هر دو به‌صورت پیش‌فرض هم‌روندی 16 دارند. وقتی -محدودیت‌های provider یا فشار Gateway محلی باعث می‌شود یک اجرا بیش از حد noisy شود، -`--concurrency` یا `--judge-concurrency` را کاهش دهید. -وقتی هیچ candidateای با `--model` پاس داده نشود، character eval به‌صورت پیش‌فرض از +این فرمان فرایندهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی کاراکتر باید پرسونا را از طریق `SOUL.md` تنظیم کنند، سپس نوبت‌های عادی کاربر مانند چت، کمک درباره فضای کاری، و کارهای کوچک روی فایل‌ها را اجرا کنند. به مدل نامزد نباید گفته شود که در حال ارزیابی شدن است. این فرمان هر رونوشت کامل را حفظ می‌کند، آمار پایه اجرای آن را ثبت می‌کند، سپس از مدل‌های داور در حالت سریع و با استدلال `xhigh` در مواردی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی بودن، حس‌وحال، و شوخ‌طبعی رتبه‌بندی کنند. +هنگام مقایسه ارائه‌دهندگان از `--blind-judge-models` استفاده کنید: پرامپت داور همچنان هر رونوشت و وضعیت اجرا را دریافت می‌کند، اما ارجاع‌های نامزد با برچسب‌های خنثی مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از تجزیه، رتبه‌بندی‌ها را دوباره به ارجاع‌های واقعی نگاشت می‌کند. +اجراهای نامزد به‌طور پیش‌فرض از تفکر `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh` برای ارجاع‌های ارزیابی قدیمی‌تر OpenAI که از آن پشتیبانی می‌کنند. برای بازنویسی یک نامزد مشخص به‌صورت درون‌خطی از `--model provider/model,thinking=` استفاده کنید. `--thinking ` همچنان یک fallback سراسری تنظیم می‌کند، و شکل قدیمی‌تر `--model-thinking ` برای سازگاری حفظ شده است. +ارجاع‌های نامزد OpenAI به‌طور پیش‌فرض روی حالت سریع هستند تا در مواردی که ارائه‌دهنده پشتیبانی می‌کند از پردازش اولویتی استفاده شود. وقتی یک نامزد یا داور منفرد به بازنویسی نیاز دارد، `,fast`، `,no-fast`، یا `,fast=false` را به‌صورت درون‌خطی اضافه کنید. فقط زمانی `--fast` را ارسال کنید که می‌خواهید حالت سریع را برای هر مدل نامزد اجباراً فعال کنید. مدت‌زمان‌های نامزد و داور در گزارش برای تحلیل معیار ثبت می‌شوند، اما پرامپت‌های داور صراحتاً می‌گویند که بر اساس سرعت رتبه‌بندی نکنند. +اجراهای مدل نامزد و داور هر دو به‌طور پیش‌فرض از هم‌روندی 16 استفاده می‌کنند. وقتی محدودیت‌های ارائه‌دهنده یا فشار Gateway محلی باعث می‌شود یک اجرا بیش از حد پرنویز شود، `--concurrency` یا `--judge-concurrency` را کاهش دهید. +وقتی هیچ `--model` نامزدی ارسال نشود، ارزیابی کاراکتر به‌طور پیش‌فرض از `openai/gpt-5.5`، `openai/gpt-5.2`، `openai/gpt-5`، `anthropic/claude-opus-4-6`، `anthropic/claude-sonnet-4-6`، `zai/glm-5.1`، `moonshot/kimi-k2.5`، و -`google/gemini-3.1-pro-preview` استفاده می‌کند. -وقتی هیچ `--judge-model` پاس داده نشود، داورها به‌صورت پیش‌فرض +`google/gemini-3.1-pro-preview` استفاده می‌کند، وقتی هیچ `--model` ارسال نشده باشد. +وقتی هیچ `--judge-model` ارسال نشود، داورها به‌طور پیش‌فرض از `openai/gpt-5.5,thinking=xhigh,fast` و -`anthropic/claude-opus-4-6,thinking=high` هستند. +`anthropic/claude-opus-4-6,thinking=high` استفاده می‌کنند. ## مستندات مرتبط -- [QA ماتریسی](/fa/concepts/qa-matrix) +- [Matrix QA](/fa/concepts/qa-matrix) - [کانال QA](/fa/channels/qa-channel) - [آزمایش](/fa/help/testing) - [داشبورد](/fa/web/dashboard) diff --git a/docs/fa/gateway/config-tools.md b/docs/fa/gateway/config-tools.md index 3c1ce57d0..2ae8541bd 100644 --- a/docs/fa/gateway/config-tools.md +++ b/docs/fa/gateway/config-tools.md @@ -1,30 +1,30 @@ --- read_when: - - پیکربندی سیاست `tools.*`، فهرست‌های مجاز یا قابلیت‌های آزمایشی - - ثبت ارائه‌دهندگان سفارشی یا بازنویسی نشانی‌های پایه + - پیکربندی خط‌مشی `tools.*`، فهرست‌های مجاز، یا ویژگی‌های آزمایشی + - ثبت ارائه‌دهندگان سفارشی یا بازنویسی نشانی‌های URL پایه - راه‌اندازی نقاط پایانی خودمیزبان سازگار با OpenAI sidebarTitle: Tools and custom providers -summary: پیکربندی ابزارها (سیاست، تغییر وضعیت‌های آزمایشی، ابزارهای متکی به ارائه‌دهنده) و راه‌اندازی ارائه‌دهنده سفارشی/URL پایه +summary: پیکربندی ابزارها (سیاست، کلیدهای آزمایشی، ابزارهای پشتیبانی‌شده توسط ارائه‌دهنده) و راه‌اندازی ارائه‌دهنده/نشانی پایه سفارشی title: پیکربندی — ابزارها و ارائه‌دهندگان سفارشی x-i18n: - generated_at: "2026-05-03T21:33:05Z" + generated_at: "2026-05-05T01:46:42Z" model: gpt-5.5 provider: openai - source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da + source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883 source_path: gateway/config-tools.md workflow: 16 --- -کلیدهای پیکربندی `tools.*` و تنظیم ارائه‌دهندهٔ سفارشی / نشانی پایه. برای عامل‌ها، کانال‌ها، و دیگر کلیدهای پیکربندی سطح بالا، [مرجع پیکربندی](/fa/gateway/configuration-reference) را ببینید. +`tools.*` کلیدهای پیکربندی و راه‌اندازی ارائه‌دهنده سفارشی / base-URL. برای عامل‌ها، کانال‌ها و دیگر کلیدهای پیکربندی سطح بالا، [مرجع پیکربندی](/fa/gateway/configuration-reference) را ببینید. ## ابزارها ### پروفایل‌های ابزار -`tools.profile` پیش از `tools.allow`/`tools.deny` یک فهرست مجاز پایه تنظیم می‌کند: +`tools.profile` یک فهرست مجاز پایه را پیش از `tools.allow`/`tools.deny` تنظیم می‌کند: -فرایند راه‌اندازی محلی، پیکربندی‌های محلی جدید را وقتی تنظیم نشده باشند به‌طور پیش‌فرض روی `tools.profile: "coding"` قرار می‌دهد (پروفایل‌های صریح موجود حفظ می‌شوند). +راه‌اندازی محلی، پیکربندی‌های محلی جدید را وقتی تنظیم نشده باشند به‌صورت پیش‌فرض روی `tools.profile: "coding"` قرار می‌دهد (پروفایل‌های صریح موجود حفظ می‌شوند). | پروفایل | شامل | @@ -32,7 +32,7 @@ x-i18n: | `minimal` | فقط `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | بدون محدودیت (همانند حالت تنظیم‌نشده) | +| `full` | بدون محدودیت (همانند تنظیم‌نشده) | ### گروه‌های ابزار @@ -49,11 +49,11 @@ x-i18n: | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | همهٔ ابزارهای داخلی (Pluginهای ارائه‌دهنده را شامل نمی‌شود) | +| `group:openclaw` | همه ابزارهای داخلی (Pluginهای ارائه‌دهنده را شامل نمی‌شود) | ### `tools.allow` / `tools.deny` -سیاست سراسری مجاز/ممنوع کردن ابزارها (ممنوع‌سازی اولویت دارد). به بزرگی و کوچکی حروف حساس نیست و از نویسه‌های عام `*` پشتیبانی می‌کند. حتی وقتی سندباکس Docker خاموش است نیز اعمال می‌شود. +سیاست سراسری مجاز/غیرمجاز برای ابزارها (`deny` اولویت دارد). به بزرگی و کوچکی حروف حساس نیست، از وایلدکارت‌های `*` پشتیبانی می‌کند. حتی وقتی سندباکس Docker خاموش است نیز اعمال می‌شود. ```json5 { @@ -61,7 +61,7 @@ x-i18n: } ``` -`write` و `apply_patch` شناسه‌های ابزار جداگانه هستند. `allow: ["write"]` برای مدل‌های سازگار، `apply_patch` را نیز فعال می‌کند، اما `deny: ["write"]` باعث ممنوع شدن `apply_patch` نمی‌شود. برای مسدود کردن همهٔ تغییرات فایل، `group:fs` را ممنوع کنید یا هر ابزار تغییردهنده را صریحاً فهرست کنید: +`write` و `apply_patch` شناسه‌های ابزار جداگانه هستند. `allow: ["write"]` همچنین `apply_patch` را برای مدل‌های سازگار فعال می‌کند، اما `deny: ["write"]` باعث منع `apply_patch` نمی‌شود. برای مسدود کردن همه تغییرات فایل، `group:fs` را منع کنید یا هر ابزار تغییردهنده را صراحتاً فهرست کنید: ```json5 { @@ -71,7 +71,7 @@ x-i18n: ### `tools.byProvider` -ابزارها را برای ارائه‌دهنده‌ها یا مدل‌های مشخص بیشتر محدود کنید. ترتیب: پروفایل پایه → پروفایل ارائه‌دهنده → مجاز/ممنوع. +ابزارها را برای ارائه‌دهنده‌ها یا مدل‌های مشخص بیشتر محدود می‌کند. ترتیب: پروفایل پایه → پروفایل ارائه‌دهنده → allow/deny. ```json5 { @@ -103,9 +103,9 @@ x-i18n: } ``` -- بازنویسی در سطح هر عامل (`agents.list[].tools.elevated`) فقط می‌تواند محدودیت بیشتری اعمال کند. -- `/elevated on|off|ask|full` وضعیت را برای هر نشست ذخیره می‌کند؛ دستورهای درون‌خطی روی یک پیام واحد اعمال می‌شوند. -- `exec` ارتقایافته از سندباکس عبور می‌کند و از مسیر خروج پیکربندی‌شده استفاده می‌کند (به‌طور پیش‌فرض `gateway`، یا وقتی هدف اجرا `node` باشد، `node`). +- بازنویسی به‌ازای هر عامل (`agents.list[].tools.elevated`) فقط می‌تواند محدودتر کند. +- `/elevated on|off|ask|full` وضعیت را به‌ازای هر نشست ذخیره می‌کند؛ دستورهای درون‌خطی روی یک پیام واحد اعمال می‌شوند. +- `exec` ارتقایافته سندباکس را دور می‌زند و از مسیر خروج پیکربندی‌شده استفاده می‌کند (`gateway` به‌صورت پیش‌فرض، یا `node` وقتی هدف exec برابر `node` باشد). ### `tools.exec` @@ -129,7 +129,7 @@ x-i18n: ### `tools.loopDetection` -بررسی‌های ایمنی حلقهٔ ابزار به‌طور پیش‌فرض **غیرفعال هستند**. برای فعال کردن تشخیص، `enabled: true` را تنظیم کنید. تنظیمات را می‌توان به‌صورت سراسری در `tools.loopDetection` تعریف کرد و در سطح هر عامل در `agents.list[].tools.loopDetection` بازنویسی کرد. +بررسی‌های ایمنی حلقه ابزار به‌صورت پیش‌فرض **غیرفعال هستند**. برای فعال کردن تشخیص، `enabled: true` را تنظیم کنید. تنظیمات می‌توانند به‌صورت سراسری در `tools.loopDetection` تعریف شوند و به‌ازای هر عامل در `agents.list[].tools.loopDetection` بازنویسی شوند. ```json5 { @@ -151,29 +151,29 @@ x-i18n: ``` - بیشینهٔ تاریخچهٔ فراخوانی ابزار که برای تحلیل حلقه نگه داشته می‌شود. + حداکثر تاریخچه فراخوانی ابزار که برای تحلیل حلقه نگه داشته می‌شود. - آستانهٔ الگوی تکراری بدون پیشرفت برای هشدارها. + آستانه الگوی تکراری بدون پیشرفت برای هشدارها. - آستانهٔ تکرار بالاتر برای مسدود کردن حلقه‌های بحرانی. + آستانه تکرار بالاتر برای مسدود کردن حلقه‌های بحرانی. - آستانهٔ توقف قطعی برای هر اجرای بدون پیشرفت. + آستانه توقف قطعی برای هر اجرای بدون پیشرفت. - هنگام فراخوانی‌های تکراری با همان ابزار/همان آرگومان‌ها هشدار بده. + هنگام تکرار فراخوانی‌های ابزار یکسان/آرگومان‌های یکسان هشدار می‌دهد. - روی ابزارهای پیمایش شناخته‌شده (`process.poll`، `command_status`، و غیره) هشدار بده/مسدود کن. + در ابزارهای polling شناخته‌شده (`process.poll`, `command_status` و غیره) هشدار می‌دهد/مسدود می‌کند. - روی الگوهای جفتی متناوب بدون پیشرفت هشدار بده/مسدود کن. + در الگوهای جفتی متناوب بدون پیشرفت هشدار می‌دهد/مسدود می‌کند. -اگر `warningThreshold >= criticalThreshold` یا `criticalThreshold >= globalCircuitBreakerThreshold` باشد، اعتبارسنجی ناموفق می‌شود. +اگر `warningThreshold >= criticalThreshold` یا `criticalThreshold >= globalCircuitBreakerThreshold` باشد، اعتبارسنجی شکست می‌خورد. ### `tools.web` @@ -208,7 +208,7 @@ x-i18n: ### `tools.media` -درک رسانه ورودی (تصویر/صدا/ویدیو) را پیکربندی می‌کند: +درک رسانهٔ ورودی را پیکربندی می‌کند (تصویر/صدا/ویدیو): ```json5 { @@ -216,7 +216,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async video directly to the channel + directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, @@ -249,27 +249,27 @@ x-i18n: **ورودی ارائه‌دهنده** (`type: "provider"` یا حذف‌شده): - - `provider`: شناسه ارائه‌دهنده API (`openai`، `anthropic`، `google`/`gemini`، `groq` و غیره) - - `model`: بازنویسی شناسه مدل - - `profile` / `preferredProfile`: انتخاب نمایه `auth-profiles.json` + - `provider`: شناسهٔ ارائه‌دهندهٔ API (`openai`، `anthropic`، `google`/`gemini`، `groq` و غیره) + - `model`: بازنویسی شناسهٔ مدل + - `profile` / `preferredProfile`: انتخاب پروفایل `auth-profiles.json` **ورودی CLI** (`type: "cli"`): - `command`: فایل اجرایی برای اجرا - - `args`: آرگومان‌های قالبی (از `{{MediaPath}}`، `{{Prompt}}`، `{{MaxChars}}` و غیره پشتیبانی می‌کند؛ `openclaw doctor --fix` نگهدارنده‌های منسوخ `{input}` را به `{{MediaPath}}` مهاجرت می‌دهد) + - `args`: آرگومان‌های قالب‌بندی‌شده (از `{{MediaPath}}`، `{{Prompt}}`، `{{MaxChars}}` و غیره پشتیبانی می‌کند؛ `openclaw doctor --fix` جانگهدارهای منسوخ `{input}` را به `{{MediaPath}}` مهاجرت می‌دهد) **فیلدهای مشترک:** - `capabilities`: فهرست اختیاری (`image`، `audio`، `video`). پیش‌فرض‌ها: `openai`/`anthropic`/`minimax` → تصویر، `google` → تصویر+صدا+ویدیو، `groq` → صدا. - - `prompt`، `maxChars`، `maxBytes`، `timeoutSeconds`، `language`: بازنویسی‌های مخصوص هر ورودی. - - ورودی‌های `tools.media.image.timeoutSeconds` و `timeoutSeconds` مدل تصویر متناظر، هنگام فراخوانی ابزار صریح `image` توسط عامل نیز اعمال می‌شوند. - - شکست‌ها به ورودی بعدی بازمی‌گردند. + - `prompt`، `maxChars`، `maxBytes`، `timeoutSeconds`، `language`: بازنویسی‌های مختص هر ورودی. + - `tools.media.image.timeoutSeconds` و ورودی‌های متناظر `timeoutSeconds` در مدل تصویر نیز وقتی عامل ابزار صریح `image` را فراخوانی می‌کند اعمال می‌شوند. + - شکست‌ها به ورودی بعدی بازگشت می‌کنند. احراز هویت ارائه‌دهنده از ترتیب استاندارد پیروی می‌کند: `auth-profiles.json` → متغیرهای محیطی → `models.providers.*.apiKey`. **فیلدهای تکمیل ناهمگام:** - - `asyncCompletion.directSend`: وقتی `true` باشد، وظایف رسانه ناهمگام تکمیل‌شده که از تحویل مستقیم تکمیل پشتیبانی می‌کنند، ابتدا تحویل مستقیم به کانال را امتحان می‌کنند. پیش‌فرض: `false` (مسیر بیدارسازی نشست درخواست‌کننده/تحویل مدل). امروز این مورد برای `video_generate` ناهمگام اعمال می‌شود؛ تکمیل‌های `music_generate` ناهمگام حتی وقتی این گزینه فعال باشد، همچنان با میانجی‌گری نشست درخواست‌کننده انجام می‌شوند. + - `asyncCompletion.directSend`: پرچم سازگاری منسوخ. وظایف رسانه‌ای ناهمگام تکمیل‌شده با واسطهٔ نشست درخواست‌کننده باقی می‌مانند تا عامل نتیجه را دریافت کند، تصمیم بگیرد چگونه به کاربر اطلاع دهد، و وقتی تحویل از مبدأ به آن نیاز دارد از ابزار پیام استفاده کند. @@ -289,7 +289,7 @@ x-i18n: ### `tools.sessions` -کنترل می‌کند کدام نشست‌ها می‌توانند توسط ابزارهای نشست (`sessions_list`، `sessions_history`، `sessions_send`) هدف قرار گیرند. +کنترل می‌کند کدام نشست‌ها می‌توانند هدف ابزارهای نشست (`sessions_list`، `sessions_history`، `sessions_send`) قرار بگیرند. پیش‌فرض: `tree` (نشست فعلی + نشست‌هایی که توسط آن ایجاد شده‌اند، مانند زیرعامل‌ها). @@ -308,16 +308,16 @@ x-i18n: - `self`: فقط کلید نشست فعلی. - `tree`: نشست فعلی + نشست‌هایی که توسط نشست فعلی ایجاد شده‌اند (زیرعامل‌ها). - - `agent`: هر نشستی که متعلق به شناسه عامل فعلی باشد (اگر نشست‌های مخصوص هر فرستنده را زیر همان شناسه عامل اجرا کنید، می‌تواند شامل کاربران دیگر هم باشد). - - `all`: هر نشست. هدف‌گیری میان‌عاملی همچنان به `tools.agentToAgent` نیاز دارد. - - محدودسازی sandbox: وقتی نشست فعلی sandbox شده باشد و `agents.defaults.sandbox.sessionToolsVisibility="spawned"` باشد، قابلیت مشاهده حتی اگر `tools.sessions.visibility="all"` باشد، به‌اجبار روی `tree` قرار می‌گیرد. + - `agent`: هر نشستی که به شناسهٔ عامل فعلی تعلق دارد (اگر نشست‌های جداگانه برای هر فرستنده را زیر همان شناسهٔ عامل اجرا کنید، می‌تواند شامل کاربران دیگر هم بشود). + - `all`: هر نشستی. هدف‌گیری میان‌عاملی همچنان به `tools.agentToAgent` نیاز دارد. + - گیرهٔ سندباکس: وقتی نشست فعلی سندباکس‌شده است و `agents.defaults.sandbox.sessionToolsVisibility="spawned"`، حتی اگر `tools.sessions.visibility="all"` باشد، دامنهٔ دید به‌اجبار `tree` می‌شود. ### `tools.sessions_spawn` -پشتیبانی از پیوست درون‌خطی برای `sessions_spawn` را کنترل می‌کند. +پشتیبانی از پیوست درون‌خطی را برای `sessions_spawn` کنترل می‌کند. ```json5 { @@ -336,12 +336,12 @@ x-i18n: ``` - + - پیوست‌ها فقط برای `runtime: "subagent"` پشتیبانی می‌شوند. runtime مربوط به ACP آن‌ها را رد می‌کند. - - فایل‌ها در workspace فرزند در مسیر `.openclaw/attachments//` همراه با یک `.manifest.json` ساخته می‌شوند. - - محتوای پیوست به‌طور خودکار از پایداری transcript حذف محرمانه می‌شود. - - ورودی‌های Base64 با بررسی‌های سخت‌گیرانه حروف مجاز/پدینگ و یک محافظ اندازه پیش از decode اعتبارسنجی می‌شوند. - - مجوزهای فایل برای پوشه‌ها `0700` و برای فایل‌ها `0600` است. + - فایل‌ها در workspace فرزند در مسیر `.openclaw/attachments//` همراه با یک `.manifest.json` materialize می‌شوند. + - محتوای پیوست به‌طور خودکار از پایداری transcript حذف/پوشانده می‌شود. + - ورودی‌های Base64 با بررسی‌های سخت‌گیرانه alphabet/padding و یک محافظ اندازه پیش از decode اعتبارسنجی می‌شوند. + - مجوزهای فایل برای دایرکتوری‌ها `0700` و برای فایل‌ها `0600` است. - پاک‌سازی از سیاست `cleanup` پیروی می‌کند: `delete` همیشه پیوست‌ها را حذف می‌کند؛ `keep` فقط وقتی `retainOnSessionKeep: true` باشد آن‌ها را نگه می‌دارد. @@ -351,7 +351,7 @@ x-i18n: ### `tools.experimental` -پرچم‌های ابزار داخلی آزمایشی. پیش‌فرض خاموش است، مگر اینکه یک قاعده فعال‌سازی خودکار strict-agentic برای GPT-5 اعمال شود. +پرچم‌های ابزار داخلی آزمایشی. به‌صورت پیش‌فرض خاموش است، مگر اینکه یک قاعده فعال‌سازی خودکار سخت‌گیرانه agentic برای GPT-5 اعمال شود. ```json5 { @@ -363,9 +363,9 @@ x-i18n: } ``` -- `planTool`: ابزار ساختاریافته `update_plan` را برای رهگیری کارهای چندمرحله‌ای غیرساده فعال می‌کند. -- پیش‌فرض: `false` مگر اینکه `agents.defaults.embeddedPi.executionContract` (یا یک بازنویسی برای هر عامل) برای اجرای خانواده GPT-5 مربوط به OpenAI یا OpenAI Codex روی `"strict-agentic"` تنظیم شده باشد. برای اجبار به روشن بودن ابزار خارج از آن محدوده، `true` تنظیم کنید، یا برای خاموش نگه داشتن آن حتی در اجراهای strict-agentic GPT-5، `false` تنظیم کنید. -- وقتی فعال باشد، system prompt همچنین راهنمای استفاده اضافه می‌کند تا مدل فقط برای کارهای قابل‌توجه از آن استفاده کند و حداکثر یک گام را در وضعیت `in_progress` نگه دارد. +- `planTool`: ابزار ساختاریافته `update_plan` را برای ردیابی کارهای چندمرحله‌ای غیرساده فعال می‌کند. +- پیش‌فرض: `false` مگر اینکه `agents.defaults.embeddedPi.executionContract` (یا override مخصوص هر agent) برای اجرای خانواده GPT-5 مربوط به OpenAI یا OpenAI Codex روی `"strict-agentic"` تنظیم شده باشد. برای اجبار به روشن بودن ابزار خارج از آن محدوده، `true` بگذارید، یا برای خاموش نگه داشتن آن حتی در اجراهای GPT-5 strict-agentic، `false` بگذارید. +- وقتی فعال باشد، system prompt همچنین راهنمای استفاده را اضافه می‌کند تا مدل فقط برای کارهای قابل‌توجه از آن استفاده کند و حداکثر یک گام را در وضعیت `in_progress` نگه دارد. ### `agents.defaults.subagents` @@ -385,10 +385,10 @@ x-i18n: } ``` -- `model`: مدل پیش‌فرض برای زیرعامل‌های ایجادشده. اگر حذف شود، زیرعامل‌ها مدل فراخواننده را به ارث می‌برند. -- `allowAgents`: allowlist پیش‌فرض شناسه‌های عامل مقصد برای `sessions_spawn` وقتی عامل درخواست‌دهنده مقدار `subagents.allowAgents` خودش را تنظیم نکرده باشد (`["*"]` = هرکدام؛ پیش‌فرض: فقط همان عامل). -- `runTimeoutSeconds`: timeout پیش‌فرض (ثانیه) برای `sessions_spawn` وقتی فراخوانی ابزار `runTimeoutSeconds` را حذف کند. `0` یعنی بدون timeout. -- سیاست ابزار برای هر زیرعامل: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: مدل پیش‌فرض برای sub-agentهای spawn‌شده. اگر حذف شود، sub-agentها مدل فراخواننده را به ارث می‌برند. +- `allowAgents`: allowlist پیش‌فرض شناسه‌های agent هدف برای `sessions_spawn` وقتی agent درخواست‌کننده `subagents.allowAgents` خودش را تنظیم نکرده باشد (`["*"]` = هرکدام؛ پیش‌فرض: فقط همان agent). +- `runTimeoutSeconds`: timeout پیش‌فرض (برحسب ثانیه) برای `sessions_spawn` وقتی فراخوانی ابزار `runTimeoutSeconds` را حذف کند. `0` یعنی بدون timeout. +- سیاست ابزار مخصوص هر subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -424,84 +424,84 @@ OpenClaw از کاتالوگ مدل داخلی استفاده می‌کند. ا ``` - - - برای نیازهای auth سفارشی از `authHeader: true` + `headers` استفاده کنید. - - ریشه config عامل را با `OPENCLAW_AGENT_DIR` (یا `PI_CODING_AGENT_DIR`، یک alias قدیمی برای متغیر محیطی) بازنویسی کنید. - - اولویت merge برای شناسه‌های provider منطبق: - - مقدارهای غیرخالی `baseUrl` در `models.json` عامل برنده می‌شوند. - - مقدارهای غیرخالی `apiKey` عامل فقط وقتی برنده می‌شوند که آن provider در زمینه config/auth-profile فعلی با SecretRef مدیریت نشده باشد. - - مقدارهای `apiKey` برای provider مدیریت‌شده با SecretRef به‌جای پایدارسازی secretهای resolve‌شده، از markerهای منبع (`ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. - - مقدارهای header برای provider مدیریت‌شده با SecretRef از markerهای منبع (`secretref-env:ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. - - `apiKey`/`baseUrl` خالی یا غایب عامل به `models.providers` در config برمی‌گردد. - - مدل منطبق `contextWindow`/`maxTokens` مقدار بالاتر بین config صریح و مقدارهای ضمنی کاتالوگ را به‌کار می‌گیرد. - - مدل منطبق `contextTokens` وقتی وجود داشته باشد یک سقف runtime صریح را حفظ می‌کند؛ از آن برای محدود کردن context مؤثر بدون تغییر metadata بومی مدل استفاده کنید. - - وقتی می‌خواهید config به‌طور کامل `models.json` را بازنویسی کند، از `models.mode: "replace"` استفاده کنید. - - پایداری markerها منبع‌محور است: markerها از snapshot فعال config منبع (پیش از resolution) نوشته می‌شوند، نه از مقدارهای secret حل‌شده در runtime. + + - برای نیازهای احراز هویت سفارشی از `authHeader: true` + `headers` استفاده کنید. + - ریشه config agent را با `OPENCLAW_AGENT_DIR` (یا `PI_CODING_AGENT_DIR`، یک alias قدیمی برای متغیر محیطی) override کنید. + - اولویت ادغام برای شناسه‌های ارائه‌دهنده همسان: + - مقدارهای غیرخالی `baseUrl` در `models.json` مربوط به agent برنده می‌شوند. + - مقدارهای غیرخالی `apiKey` در agent فقط وقتی برنده می‌شوند که آن ارائه‌دهنده در زمینه config/auth-profile فعلی توسط SecretRef مدیریت نشود. + - مقدارهای `apiKey` ارائه‌دهنده مدیریت‌شده با SecretRef از markerهای منبع (`ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند، نه اینکه secretهای resolve‌شده پایدار شوند. + - مقدارهای header ارائه‌دهنده مدیریت‌شده با SecretRef از markerهای منبع (`secretref-env:ENV_VAR_NAME` برای ارجاع‌های env، `secretref-managed` برای ارجاع‌های file/exec) تازه‌سازی می‌شوند. + - `apiKey`/`baseUrl` خالی یا ناموجود در agent به `models.providers` در config fallback می‌کند. + - `contextWindow`/`maxTokens` مدل همسان از مقدار بالاتر بین config صریح و مقدارهای ضمنی کاتالوگ استفاده می‌کند. + - `contextTokens` مدل همسان وقتی یک سقف runtime صریح وجود داشته باشد آن را حفظ می‌کند؛ از آن برای محدود کردن context مؤثر بدون تغییر metadata بومی مدل استفاده کنید. + - وقتی می‌خواهید config کاملاً `models.json` را بازنویسی کند، از `models.mode: "replace"` استفاده کنید. + - پایداری marker وابسته به منبع و authoritative است: markerها از snapshot فعال config منبع (پیش از resolution) نوشته می‌شوند، نه از مقدارهای secret حل‌شده runtime. -### جزئیات فیلدهای provider +### جزئیات فیلدهای ارائه‌دهنده - - - `models.mode`: رفتار کاتالوگ provider (`merge` یا `replace`). - - `models.providers`: نگاشت provider سفارشی که با شناسه provider کلیدگذاری شده است. - - ویرایش‌های ایمن: برای به‌روزرسانی‌های افزایشی از `openclaw config set models.providers. '' --strict-json --merge` یا `openclaw config set models.providers..models '' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌های مخرب را رد می‌کند، مگر اینکه `--replace` را ارسال کنید. + + - `models.mode`: رفتار کاتالوگ ارائه‌دهنده (`merge` یا `replace`). + - `models.providers`: map ارائه‌دهنده سفارشی با کلید شناسه ارائه‌دهنده. + - ویرایش‌های امن: برای به‌روزرسانی‌های افزایشی از `openclaw config set models.providers. '' --strict-json --merge` یا `openclaw config set models.providers..models '' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌های مخرب را رد می‌کند مگر اینکه `--replace` را پاس بدهید. - - - `models.providers.*.api`: adapter درخواست (`openai-completions`، `openai-responses`، `anthropic-messages`، `google-generative-ai` و غیره). برای backendهای self-hosted در `/v1/chat/completions` مانند MLX، vLLM، SGLang و بیشتر سرورهای محلی سازگار با OpenAI، از `openai-completions` استفاده کنید. provider سفارشی با `baseUrl` اما بدون `api` به‌صورت پیش‌فرض `openai-completions` است؛ فقط وقتی backend از `/v1/responses` پشتیبانی می‌کند، `openai-responses` را تنظیم کنید. - - `models.providers.*.apiKey`: credential مربوط به provider (جایگزینی SecretRef/env ترجیح داده می‌شود). - - `models.providers.*.auth`: راهبرد auth (`api-key`، `token`، `oauth`، `aws-sdk`). - - `models.providers.*.contextWindow`: پنجره context بومی پیش‌فرض برای مدل‌های زیر این provider وقتی entry مدل `contextWindow` را تنظیم نکرده باشد. - - `models.providers.*.contextTokens`: سقف context مؤثر runtime پیش‌فرض برای مدل‌های زیر این provider وقتی entry مدل `contextTokens` را تنظیم نکرده باشد. - - `models.providers.*.maxTokens`: سقف token خروجی پیش‌فرض برای مدل‌های زیر این provider وقتی entry مدل `maxTokens` را تنظیم نکرده باشد. - - `models.providers.*.timeoutSeconds`: timeout اختیاری درخواست HTTP مدل برای هر provider بر حسب ثانیه، شامل مدیریت connect، headerها، body و abort کل درخواست. - - `models.providers.*.injectNumCtxForOpenAICompat`: برای Ollama + `openai-completions`، مقدار `options.num_ctx` را به درخواست‌ها تزریق می‌کند (پیش‌فرض: `true`). - - `models.providers.*.authHeader`: انتقال credential در header مربوط به `Authorization` را هنگام نیاز اجباری می‌کند. + + - `models.providers.*.api`: adapter درخواست (`openai-completions`، `openai-responses`، `anthropic-messages`، `google-generative-ai`، و غیره). برای backendهای self-hosted در مسیر `/v1/chat/completions` مانند MLX، vLLM، SGLang، و بیشتر سرورهای محلی سازگار با OpenAI، از `openai-completions` استفاده کنید. یک ارائه‌دهنده سفارشی با `baseUrl` اما بدون `api` به‌صورت پیش‌فرض از `openai-completions` استفاده می‌کند؛ `openai-responses` را فقط وقتی تنظیم کنید که backend از `/v1/responses` پشتیبانی کند. + - `models.providers.*.apiKey`: credential ارائه‌دهنده (جایگزینی SecretRef/env ترجیح دارد). + - `models.providers.*.auth`: راهبرد احراز هویت (`api-key`، `token`، `oauth`، `aws-sdk`). + - `models.providers.*.contextWindow`: پنجره context بومی پیش‌فرض برای مدل‌های زیر این ارائه‌دهنده وقتی ورودی مدل `contextWindow` را تنظیم نکند. + - `models.providers.*.contextTokens`: سقف context مؤثر runtime پیش‌فرض برای مدل‌های زیر این ارائه‌دهنده وقتی ورودی مدل `contextTokens` را تنظیم نکند. + - `models.providers.*.maxTokens`: سقف token خروجی پیش‌فرض برای مدل‌های زیر این ارائه‌دهنده وقتی ورودی مدل `maxTokens` را تنظیم نکند. + - `models.providers.*.timeoutSeconds`: timeout اختیاری درخواست HTTP مدل برای هر ارائه‌دهنده برحسب ثانیه، شامل connect، headers، body، و مدیریت abort کل درخواست. + - `models.providers.*.injectNumCtxForOpenAICompat`: برای Ollama + `openai-completions`، مقدار `options.num_ctx` را به درخواست‌ها inject می‌کند (پیش‌فرض: `true`). + - `models.providers.*.authHeader`: وقتی لازم باشد، انتقال credential را در header با نام `Authorization` اجبار می‌کند. - `models.providers.*.baseUrl`: URL پایه API بالادستی. - - `models.providers.*.headers`: headerهای static اضافی برای مسیریابی proxy/tenant. + - `models.providers.*.headers`: headerهای ثابت اضافی برای مسیریابی proxy/tenant. - - `models.providers.*.request`: بازنویسی‌های transport برای درخواست‌های HTTP ارائه‌دهنده مدل. + + `models.providers.*.request`: overrideهای انتقال برای درخواست‌های HTTP ارائه‌دهنده مدل. - - `request.headers`: headerهای اضافی (با پیش‌فرض‌های provider ادغام می‌شوند). مقدارها SecretRef را می‌پذیرند. - - `request.auth`: بازنویسی راهبرد auth. حالت‌ها: `"provider-default"` (استفاده از auth داخلی provider)، `"authorization-bearer"` (با `token`)، `"header"` (با `headerName`، `value`، و `prefix` اختیاری). - - `request.proxy`: بازنویسی HTTP proxy. حالت‌ها: `"env-proxy"` (استفاده از متغیرهای env مربوط به `HTTP_PROXY`/`HTTPS_PROXY`)، `"explicit-proxy"` (با `url`). هر دو حالت یک زیرشیء اختیاری `tls` را می‌پذیرند. - - `request.tls`: بازنویسی TLS برای اتصال‌های مستقیم. فیلدها: `ca`، `cert`، `key`، `passphrase` (همه SecretRef را می‌پذیرند)، `serverName`، `insecureSkipVerify`. - - `request.allowPrivateNetwork`: وقتی `true` باشد، اگر DNS به محدوده‌های private، CGNAT یا مشابه resolve شود، HTTPS به `baseUrl` را از طریق محافظ fetch HTTP مربوط به provider مجاز می‌کند (opt-in اپراتور برای endpointهای self-hosted سازگار با OpenAI و مورداعتماد). URLهای stream ارائه‌دهنده مدل روی loopback مانند `localhost`، `127.0.0.1` و `[::1]` به‌طور خودکار مجازند مگر اینکه این مقدار صراحتاً روی `false` تنظیم شده باشد؛ میزبان‌های LAN، tailnet و DNS خصوصی همچنان به opt-in نیاز دارند. WebSocket از همان `request` برای headerها/TLS استفاده می‌کند اما از آن gate مربوط به SSRF در fetch استفاده نمی‌کند. پیش‌فرض `false`. + - `request.headers`: headerهای اضافی (با پیش‌فرض‌های ارائه‌دهنده ادغام می‌شوند). مقدارها SecretRef را می‌پذیرند. + - `request.auth`: override راهبرد احراز هویت. حالت‌ها: `"provider-default"` (استفاده از احراز هویت داخلی ارائه‌دهنده)، `"authorization-bearer"` (با `token`)، `"header"` (با `headerName`، `value`، و `prefix` اختیاری). + - `request.proxy`: override مربوط به HTTP proxy. حالت‌ها: `"env-proxy"` (استفاده از متغیرهای env مربوط به `HTTP_PROXY`/`HTTPS_PROXY`)، `"explicit-proxy"` (با `url`). هر دو حالت یک زیربخش اختیاری `tls` را می‌پذیرند. + - `request.tls`: override مربوط به TLS برای اتصال‌های مستقیم. فیلدها: `ca`، `cert`، `key`، `passphrase` (همه SecretRef را می‌پذیرند)، `serverName`، `insecureSkipVerify`. + - `request.allowPrivateNetwork`: وقتی `true` باشد، در صورتی که DNS به محدوده‌های خصوصی، CGNAT، یا مشابه resolve شود، HTTPS به `baseUrl` را از طریق guard واکشی HTTP ارائه‌دهنده مجاز می‌کند (opt-in اپراتور برای endpointهای self-hosted سازگار با OpenAI و مورد اعتماد). URLهای stream ارائه‌دهنده مدل در loopback مانند `localhost`، `127.0.0.1`، و `[::1]` به‌صورت خودکار مجاز هستند مگر اینکه این مقدار صریحاً روی `false` تنظیم شود؛ میزبان‌های LAN، tailnet، و DNS خصوصی همچنان به opt-in نیاز دارند. WebSocket از همان `request` برای headers/TLS استفاده می‌کند اما از آن fetch SSRF gate استفاده نمی‌کند. پیش‌فرض `false`. - - - `models.providers.*.models`: entryهای صریح کاتالوگ مدل provider. - - `models.providers.*.models.*.input`: modalityهای ورودی مدل. برای مدل‌های فقط متن از `["text"]` و برای مدل‌های بومی image/vision از `["text", "image"]` استفاده کنید. پیوست‌های image فقط وقتی به turnهای عامل تزریق می‌شوند که مدل انتخاب‌شده image-capable علامت‌گذاری شده باشد. - - `models.providers.*.models.*.contextWindow`: metadata پنجره context بومی مدل. این مقدار `contextWindow` سطح provider را برای آن مدل بازنویسی می‌کند. - - `models.providers.*.models.*.contextTokens`: سقف اختیاری context در runtime. این مقدار `contextTokens` سطح provider را بازنویسی می‌کند؛ وقتی بودجه context مؤثر کوچک‌تری نسبت به `contextWindow` بومی مدل می‌خواهید، از آن استفاده کنید؛ `openclaw models list` وقتی این دو مقدار تفاوت داشته باشند، هر دو را نشان می‌دهد. - - `models.providers.*.models.*.compat.supportsDeveloperRole`: راهنمای اختیاری سازگاری. برای `api: "openai-completions"` با `baseUrl` غیرخالی و غیربومی (میزبانی که `api.openai.com` نیست)، OpenClaw در runtime این مقدار را به `false` اجبار می‌کند. `baseUrl` خالی/حذف‌شده رفتار پیش‌فرض OpenAI را حفظ می‌کند. - - `models.providers.*.models.*.compat.requiresStringContent`: راهنمای اختیاری سازگاری برای endpointهای chat سازگار با OpenAI که فقط string می‌پذیرند. وقتی `true` باشد، OpenClaw آرایه‌های pure text مربوط به `messages[].content` را پیش از ارسال درخواست به stringهای ساده flatten می‌کند. + + - `models.providers.*.models`: ورودی‌های صریح کاتالوگ مدل ارائه‌دهنده. + - `models.providers.*.models.*.input`: modalityهای ورودی مدل. برای مدل‌های فقط متنی از `["text"]` و برای مدل‌های تصویر/vision بومی از `["text", "image"]` استفاده کنید. پیوست‌های تصویر فقط وقتی به turnهای agent تزریق می‌شوند که مدل انتخاب‌شده به‌عنوان image-capable علامت‌گذاری شده باشد. + - `models.providers.*.models.*.contextWindow`: metadata پنجره context بومی مدل. این مقدار `contextWindow` سطح ارائه‌دهنده را برای آن مدل override می‌کند. + - `models.providers.*.models.*.contextTokens`: سقف اختیاری context در runtime. این مقدار `contextTokens` سطح ارائه‌دهنده را override می‌کند؛ وقتی می‌خواهید بودجه context مؤثر کوچک‌تری نسبت به `contextWindow` بومی مدل داشته باشید از آن استفاده کنید؛ `openclaw models list` وقتی این دو مقدار متفاوت باشند هر دو را نشان می‌دهد. + - `models.providers.*.models.*.compat.supportsDeveloperRole`: راهنمای سازگاری اختیاری. برای `api: "openai-completions"` با یک `baseUrl` غیرخالی و غیربومی (میزبانی که `api.openai.com` نیست)، OpenClaw در runtime این مقدار را به `false` اجبار می‌کند. `baseUrl` خالی/حذف‌شده رفتار پیش‌فرض OpenAI را نگه می‌دارد. + - `models.providers.*.models.*.compat.requiresStringContent`: راهنمای سازگاری اختیاری برای endpointهای chat سازگار با OpenAI که فقط string می‌پذیرند. وقتی `true` باشد، OpenClaw آرایه‌های صرفاً متنی `messages[].content` را پیش از ارسال درخواست به stringهای ساده flatten می‌کند. - + - `plugins.entries.amazon-bedrock.config.discovery`: ریشه تنظیمات auto-discovery مربوط به Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: روشن/خاموش کردن discovery ضمنی. - `plugins.entries.amazon-bedrock.config.discovery.region`: منطقه AWS برای discovery. - - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: فیلتر اختیاری شناسه provider برای discovery هدفمند. - - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: فاصله polling برای تازه‌سازی discovery. + - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: فیلتر اختیاری شناسه ارائه‌دهنده برای discovery هدفمند. + - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: بازه polling برای تازه‌سازی discovery. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: پنجره context fallback برای مدل‌های کشف‌شده. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: حداکثر tokenهای خروجی fallback برای مدل‌های کشف‌شده. -onboarding تعاملی provider سفارشی، ورودی image را برای شناسه‌های رایج مدل‌های vision مانند GPT-4o، Claude، Gemini، Qwen-VL، LLaVA، Pixtral، InternVL، Mllama، MiniCPM-V و GLM-4V استنتاج می‌کند و برای خانواده‌های شناخته‌شده فقط متن، پرسش اضافی را رد می‌کند. شناسه‌های ناشناخته مدل همچنان درباره پشتیبانی image پرسش می‌کنند. onboarding غیرتعاملی از همان استنتاج استفاده می‌کند؛ برای اجبار metadata مربوط به image-capable، `--custom-image-input` را ارسال کنید یا برای اجبار metadata فقط متن، `--custom-text-input` را ارسال کنید. +onboarding تعاملی ارائه‌دهنده سفارشی، ورودی تصویر را برای شناسه‌های رایج مدل vision مانند GPT-4o، Claude، Gemini، Qwen-VL، LLaVA، Pixtral، InternVL، Mllama، MiniCPM-V، و GLM-4V استنباط می‌کند و پرسش اضافی را برای خانواده‌های شناخته‌شده فقط متنی رد می‌کند. شناسه‌های مدل ناشناخته همچنان درباره پشتیبانی تصویر prompt می‌کنند. onboarding غیرتعاملی از همان استنباط استفاده می‌کند؛ برای اجبار metadata با قابلیت تصویر، `--custom-image-input` را پاس بدهید یا برای اجبار metadata فقط متنی، `--custom-text-input` را پاس بدهید. -### نمونه‌های provider +### نمونه‌های ارائه‌دهنده - Plugin ارائه‌دهنده همراه `cerebras` می‌تواند این را از طریق `openclaw onboard --auth-choice cerebras-api-key` پیکربندی کند. فقط هنگام بازنویسی پیش‌فرض‌ها از config صریح provider استفاده کنید. + Plugin ارائه‌دهنده bundled با نام `cerebras` می‌تواند این را از طریق `openclaw onboard --auth-choice cerebras-api-key` پیکربندی کند. فقط وقتی از config صریح ارائه‌دهنده استفاده کنید که defaultها را override می‌کنید. ```json5 { @@ -535,7 +535,7 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - برای Cerebras از `cerebras/zai-glm-4.7` استفاده کنید؛ برای دسترسی مستقیم Z.AI از `zai/glm-4.7` استفاده کنید. + از `cerebras/zai-glm-4.7` برای Cerebras استفاده کنید؛ از `zai/glm-4.7` برای اتصال مستقیم Z.AI استفاده کنید. @@ -551,11 +551,11 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - سازگار با Anthropic، ارائه‌دهنده داخلی. میان‌بر: `openclaw onboard --auth-choice kimi-code-api-key`. + ارائه‌دهنده داخلی سازگار با Anthropic. میانبر: `openclaw onboard --auth-choice kimi-code-api-key`. - [مدل‌های محلی](/fa/gateway/local-models) را ببینید. خلاصه: یک مدل محلی بزرگ را از طریق LM Studio Responses API روی سخت‌افزار جدی اجرا کنید؛ مدل‌های میزبانی‌شده را برای پشتیبان ادغام‌شده نگه دارید. + [مدل‌های محلی](/fa/gateway/local-models) را ببینید. خلاصه: یک مدل محلی بزرگ را از طریق LM Studio Responses API روی سخت‌افزار جدی اجرا کنید؛ مدل‌های میزبانی‌شده را برای fallback ادغام‌شده نگه دارید. ```json5 @@ -592,7 +592,7 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - `MINIMAX_API_KEY` را تنظیم کنید. میان‌برها: `openclaw onboard --auth-choice minimax-global-api` یا `openclaw onboard --auth-choice minimax-cn-api`. کاتالوگ مدل به‌صورت پیش‌فرض فقط روی M2.7 است. در مسیر استریم سازگار با Anthropic، OpenClaw به‌صورت پیش‌فرض تفکر MiniMax را غیرفعال می‌کند، مگر اینکه خودتان صراحتا `thinking` را تنظیم کنید. `/fast on` یا `params.fastMode: true` مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی می‌کند. + `MINIMAX_API_KEY` را تنظیم کنید. میانبرها: `openclaw onboard --auth-choice minimax-global-api` یا `openclaw onboard --auth-choice minimax-cn-api`. کاتالوگ مدل به‌طور پیش‌فرض فقط M2.7 است. در مسیر streaming سازگار با Anthropic، OpenClaw به‌طور پیش‌فرض thinking در MiniMax را غیرفعال می‌کند مگر اینکه خودتان صراحتا `thinking` را تنظیم کنید. `/fast on` یا `params.fastMode: true` مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی می‌کند. @@ -629,9 +629,9 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - برای نقطه پایانی چین: `baseUrl: "https://api.moonshot.cn/v1"` یا `openclaw onboard --auth-choice moonshot-api-key-cn`. + برای endpoint چین: `baseUrl: "https://api.moonshot.cn/v1"` یا `openclaw onboard --auth-choice moonshot-api-key-cn`. - نقاط پایانی بومی Moonshot سازگاری با مصرف استریم را روی انتقال مشترک `openai-completions` اعلام می‌کنند، و OpenClaw آن را بر اساس قابلیت‌های نقطه پایانی فعال می‌کند، نه فقط شناسه ارائه‌دهنده داخلی. + endpointهای بومی Moonshot سازگاری استفاده از streaming را روی transport مشترک `openai-completions` اعلام می‌کنند، و OpenClaw این را بر اساس قابلیت‌های endpoint تعیین می‌کند، نه فقط بر اساس شناسه ارائه‌دهنده داخلی. @@ -646,7 +646,7 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - `OPENCODE_API_KEY` (یا `OPENCODE_ZEN_API_KEY`) را تنظیم کنید. برای کاتالوگ Zen از ارجاع‌های `opencode/...` یا برای کاتالوگ Go از ارجاع‌های `opencode-go/...` استفاده کنید. میان‌بر: `openclaw onboard --auth-choice opencode-zen` یا `openclaw onboard --auth-choice opencode-go`. + `OPENCODE_API_KEY` (یا `OPENCODE_ZEN_API_KEY`) را تنظیم کنید. برای کاتالوگ Zen از ارجاع‌های `opencode/...` و برای کاتالوگ Go از ارجاع‌های `opencode-go/...` استفاده کنید. میانبر: `openclaw onboard --auth-choice opencode-zen` یا `openclaw onboard --auth-choice opencode-go`. @@ -683,7 +683,7 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - نشانی پایه نباید شامل `/v1` باشد (کلاینت Anthropic آن را اضافه می‌کند). میان‌بر: `openclaw onboard --auth-choice synthetic-api-key`. + URL پایه باید `/v1` را حذف کند (کلاینت Anthropic آن را اضافه می‌کند). میانبر: `openclaw onboard --auth-choice synthetic-api-key`. @@ -698,11 +698,11 @@ onboarding تعاملی provider سفارشی، ورودی image را برای } ``` - `ZAI_API_KEY` را تنظیم کنید. `z.ai/*` و `z-ai/*` به‌عنوان نام‌های مستعار پذیرفته می‌شوند. میان‌بر: `openclaw onboard --auth-choice zai-api-key`. + `ZAI_API_KEY` را تنظیم کنید. `z.ai/*` و `z-ai/*` به‌عنوان نام‌های مستعار پذیرفته می‌شوند. میانبر: `openclaw onboard --auth-choice zai-api-key`. - - نقطه پایانی عمومی: `https://api.z.ai/api/paas/v4` - - نقطه پایانی کدنویسی (پیش‌فرض): `https://api.z.ai/api/coding/paas/v4` - - برای نقطه پایانی عمومی، یک ارائه‌دهنده سفارشی با بازنویسی نشانی پایه تعریف کنید. + - endpoint عمومی: `https://api.z.ai/api/paas/v4` + - endpoint کدنویسی (پیش‌فرض): `https://api.z.ai/api/coding/paas/v4` + - برای endpoint عمومی، یک ارائه‌دهنده سفارشی با override کردن URL پایه تعریف کنید. @@ -711,7 +711,7 @@ onboarding تعاملی provider سفارشی، ورودی image را برای ## مرتبط -- [پیکربندی — agents](/fa/gateway/config-agents) -- [پیکربندی — channels](/fa/gateway/config-channels) +- [پیکربندی — agentها](/fa/gateway/config-agents) +- [پیکربندی — channelها](/fa/gateway/config-channels) - [مرجع پیکربندی](/fa/gateway/configuration-reference) — کلیدهای سطح بالای دیگر -- [ابزارها و plugins](/fa/tools) +- [ابزارها و pluginها](/fa/tools) diff --git a/docs/fa/gateway/configuration-reference.md b/docs/fa/gateway/configuration-reference.md index 8c8e9264d..a6f347916 100644 --- a/docs/fa/gateway/configuration-reference.md +++ b/docs/fa/gateway/configuration-reference.md @@ -1,74 +1,74 @@ --- read_when: - به معناشناسی دقیق پیکربندی در سطح فیلد یا مقادیر پیش‌فرض نیاز دارید - - در حال اعتبارسنجی بلوک‌های پیکربندی کانال، مدل، Gateway یا ابزار هستید -summary: مرجع پیکربندی Gateway برای کلیدهای اصلی OpenClaw، پیش‌فرض‌ها و پیوندها به مراجع اختصاصی زیرسامانه‌ها + - شما در حال اعتبارسنجی بلوک‌های پیکربندی کانال، مدل، Gateway یا ابزار هستید +summary: مرجع پیکربندی Gateway برای کلیدهای اصلی OpenClaw، پیش‌فرض‌ها، و پیوندها به مراجع اختصاصی زیرسامانه‌ها title: مرجع پیکربندی x-i18n: - generated_at: "2026-05-03T21:33:01Z" + generated_at: "2026-05-05T01:46:34Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- -مرجع پیکربندی هسته برای `~/.openclaw/openclaw.json`. برای نمای کلی مبتنی بر کار، [پیکربندی](/fa/gateway/configuration) را ببینید. +مرجع پیکربندی هسته برای `~/.openclaw/openclaw.json`. برای نمای کلی وظیفه‌محور، [پیکربندی](/fa/gateway/configuration) را ببینید. -سطوح اصلی پیکربندی OpenClaw را پوشش می‌دهد و هرجا یک زیرسامانه مرجع عمیق‌تری برای خود داشته باشد، به آن پیوند می‌دهد. کاتالوگ‌های دستور متعلق به کانال‌ها و Pluginها و تنظیمات عمیق حافظه/QMD در صفحه‌های خودشان قرار دارند، نه در این صفحه. +سطوح اصلی پیکربندی OpenClaw را پوشش می‌دهد و وقتی یک زیرسیستم مرجع عمیق‌تری برای خودش داشته باشد، به آن لینک می‌دهد. کاتالوگ‌های فرمان متعلق به کانال و Plugin و تنظیمات عمیق حافظه/QMD در صفحه‌های خودشان قرار دارند، نه در این صفحه. حقیقت کد: -- `openclaw config schema` شمای JSON زنده‌ای را که برای اعتبارسنجی و Control UI استفاده می‌شود چاپ می‌کند، همراه با فراداده‌های بسته‌شده/Plugin/کانال که در صورت وجود ادغام شده‌اند -- `config.schema.lookup` یک گره شمای محدود به مسیر را برای ابزارهای بررسی جزئی برمی‌گرداند -- `pnpm config:docs:check` / `pnpm config:docs:gen` هش مبنای مستندات پیکربندی را در برابر سطح شمای فعلی اعتبارسنجی می‌کنند +- `openclaw config schema` JSON Schema زنده‌ای را چاپ می‌کند که برای اعتبارسنجی و Control UI استفاده می‌شود، همراه با فراداده‌های بسته‌بندی‌شده/Plugin/کانال که در صورت وجود ادغام شده‌اند +- `config.schema.lookup` یک گره اسکیما با محدوده مسیر را برای ابزارهای بررسی جزئی برمی‌گرداند +- `pnpm config:docs:check` / `pnpm config:docs:gen` هش مبنای مستندات پیکربندی را در برابر سطح اسکیمای فعلی اعتبارسنجی می‌کنند -مسیر جست‌وجوی Agent: پیش از ویرایش، از کنش ابزار `gateway` یعنی `config.schema.lookup` برای -مستندات و محدودیت‌های دقیق در سطح فیلد استفاده کنید. برای راهنمایی مبتنی بر کار از -[پیکربندی](/fa/gateway/configuration) استفاده کنید و از این صفحه -برای نقشه گسترده‌تر فیلدها، پیش‌فرض‌ها، و پیوند به مراجع زیرسامانه‌ها استفاده کنید. +مسیر جست‌وجوی عامل: پیش از ویرایش‌ها، از کنش ابزار `gateway` یعنی `config.schema.lookup` برای +مستندات و محدودیت‌های دقیق در سطح فیلد استفاده کنید. از +[پیکربندی](/fa/gateway/configuration) برای راهنمایی وظیفه‌محور و از این صفحه +برای نقشه گسترده‌تر فیلدها، پیش‌فرض‌ها، و لینک‌ها به مراجع زیرسیستم استفاده کنید. مراجع عمیق اختصاصی: - [مرجع پیکربندی حافظه](/fa/reference/memory-config) برای `agents.defaults.memorySearch.*`، `memory.qmd.*`، `memory.citations`، و پیکربندی Dreaming زیر `plugins.entries.memory-core.config.dreaming` -- [دستورهای اسلش](/fa/tools/slash-commands) برای کاتالوگ فعلی دستورهای داخلی + بسته‌شده -- صفحه‌های کانال/Plugin مالک برای سطوح دستور ویژه کانال +- [فرمان‌های اسلش](/fa/tools/slash-commands) برای کاتالوگ فرمان داخلی + بسته‌بندی‌شده فعلی +- صفحه‌های کانال/Plugin مالک برای سطوح فرمان مخصوص کانال -قالب پیکربندی **JSON5** است (کامنت‌ها + ویرگول‌های انتهایی مجازند). همه فیلدها اختیاری‌اند — OpenClaw وقتی فیلدی حذف شود از پیش‌فرض‌های امن استفاده می‌کند. +قالب پیکربندی **JSON5** است (کامنت‌ها + کاماهای انتهایی مجازند). همه فیلدها اختیاری هستند — OpenClaw هنگام حذف شدن آن‌ها از پیش‌فرض‌های ایمن استفاده می‌کند. --- ## کانال‌ها -کلیدهای پیکربندی هر کانال به یک صفحه اختصاصی منتقل شده‌اند — برای `channels.*`، -از جمله Slack، Discord، Telegram، WhatsApp، Matrix، iMessage، و دیگر -کانال‌های بسته‌شده (احراز هویت، کنترل دسترسی، چندحسابی، دروازه‌گذاری اشاره)، +کلیدهای پیکربندی هر کانال به صفحه‌ای اختصاصی منتقل شده‌اند — برای `channels.*`، +از جمله Slack، Discord، Telegram، WhatsApp، Matrix، iMessage، و سایر +کانال‌های بسته‌بندی‌شده (احراز هویت، کنترل دسترسی، چندحسابی، دروازه‌گذاری منشن)، [پیکربندی — کانال‌ها](/fa/gateway/config-channels) را ببینید. -## پیش‌فرض‌های Agent، چند-Agent، نشست‌ها، و پیام‌ها +## پیش‌فرض‌های عامل، چندعاملی، نشست‌ها، و پیام‌ها -به یک صفحه اختصاصی منتقل شده است — برای موارد زیر -[پیکربندی — Agentها](/fa/gateway/config-agents) را ببینید: +به صفحه‌ای اختصاصی منتقل شده است — ببینید +[پیکربندی — عامل‌ها](/fa/gateway/config-agents) برای: -- `agents.defaults.*` (workspace، مدل، thinking، heartbeat، حافظه، رسانه، Skills، sandbox) -- `multiAgent.*` (مسیریابی و bindingهای چند-Agent) +- `agents.defaults.*` (فضای کاری، مدل، تفکر، Heartbeat، حافظه، رسانه، skills، sandbox) +- `multiAgent.*` (مسیریابی و اتصال‌های چندعاملی) - `session.*` (چرخه عمر نشست، Compaction، هرس) - `messages.*` (تحویل پیام، TTS، رندر markdown) - `talk.*` (حالت Talk) - `talk.speechLocale`: شناسه locale اختیاری BCP 47 برای تشخیص گفتار Talk در iOS/macOS - - `talk.silenceTimeoutMs`: وقتی تنظیم نشده باشد، Talk پیش از ارسال transcript پنجره مکث پیش‌فرض پلتفرم را نگه می‌دارد (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.silenceTimeoutMs`: وقتی تنظیم نشده باشد، Talk پیش از ارسال رونوشت، پنجره مکث پیش‌فرض پلتفرم را نگه می‌دارد (`700 ms on macOS and Android, 900 ms on iOS`) ## ابزارها و ارائه‌دهندگان سفارشی -سیاست ابزار، toggleهای آزمایشی، پیکربندی ابزارهای مبتنی بر ارائه‌دهنده، و راه‌اندازی -ارائه‌دهنده سفارشی / base-URL به یک صفحه اختصاصی منتقل شده‌اند — -[پیکربندی — ابزارها و ارائه‌دهندگان سفارشی](/fa/gateway/config-tools) را ببینید. +سیاست ابزار، سوییچ‌های آزمایشی، پیکربندی ابزارهای متکی بر ارائه‌دهنده، و تنظیم +ارائه‌دهنده سفارشی / URL پایه به صفحه‌ای اختصاصی منتقل شده است — ببینید +[پیکربندی — ابزارها و ارائه‌دهندگان سفارشی](/fa/gateway/config-tools). ## مدل‌ها -تعریف‌های ارائه‌دهنده، allowlistهای مدل، و راه‌اندازی ارائه‌دهنده سفارشی در +تعریف‌های ارائه‌دهنده، allowlistهای مدل، و تنظیم ارائه‌دهنده سفارشی در [پیکربندی — ابزارها و ارائه‌دهندگان سفارشی](/fa/gateway/config-tools#custom-providers-and-base-urls) قرار دارند. -ریشه `models` همچنین مالک رفتار جهانی کاتالوگ مدل است. +ریشه `models` همچنین رفتار سراسری کاتالوگ مدل را مالک است. ```json5 { @@ -80,18 +80,18 @@ x-i18n: ``` - `models.mode`: رفتار کاتالوگ ارائه‌دهنده (`merge` یا `replace`). -- `models.providers`: نگاشت ارائه‌دهنده سفارشی با کلید شناسه ارائه‌دهنده. -- `models.pricing.enabled`: بوت‌استرپ قیمت‌گذاری پس‌زمینه را کنترل می‌کند که +- `models.providers`: نقشه ارائه‌دهنده سفارشی که با شناسه ارائه‌دهنده کلیدگذاری شده است. +- `models.pricing.enabled`: bootstrap قیمت‌گذاری پس‌زمینه را کنترل می‌کند که پس از رسیدن sidecarها و کانال‌ها به مسیر آماده Gateway شروع می‌شود. وقتی `false` باشد، - Gateway واکشی‌های کاتالوگ قیمت‌گذاری OpenRouter و LiteLLM را رد می‌کند؛ مقادیر - پیکربندی‌شده `models.providers.*.models[].cost` همچنان برای برآوردهای هزینه محلی کار می‌کنند. + Gateway دریافت‌های کاتالوگ قیمت‌گذاری OpenRouter و LiteLLM را رد می‌کند؛ مقدارهای پیکربندی‌شده + `models.providers.*.models[].cost` همچنان برای برآورد هزینه محلی کار می‌کنند. ## MCP تعریف‌های سرور MCP مدیریت‌شده توسط OpenClaw زیر `mcp.servers` قرار دارند و توسط -Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف می‌شوند. دستورهای `openclaw mcp list`، +Pi جاسازی‌شده و سایر آداپترهای runtime مصرف می‌شوند. فرمان‌های `openclaw mcp list`، `show`، `set`، و `unset` این بلوک را بدون اتصال به -سرور هدف هنگام ویرایش پیکربندی مدیریت می‌کنند. +سرور هدف هنگام ویرایش‌های پیکربندی مدیریت می‌کنند. ```json5 { @@ -115,17 +115,17 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م } ``` -- `mcp.servers`: تعریف‌های نام‌دار سرور MCP از نوع stdio یا remote برای runtimeهایی که - ابزارهای MCP پیکربندی‌شده را در معرض استفاده قرار می‌دهند. +- `mcp.servers`: تعریف‌های نام‌گذاری‌شده سرور MCP از نوع stdio یا remote برای runtimeهایی که + ابزارهای MCP پیکربندی‌شده را ارائه می‌کنند. ورودی‌های remote از `transport: "streamable-http"` یا `transport: "sse"` استفاده می‌کنند؛ - `type: "http"` یک alias بومی CLI است که `openclaw mcp set` و - `openclaw doctor --fix` آن را به فیلد canonical `transport` نرمال‌سازی می‌کنند. -- `mcp.sessionIdleTtlMs`: TTL بیکاری برای runtimeهای MCP بسته‌شده و محدود به نشست. - اجرای‌های جاسازی‌شده یک‌باره، پاک‌سازی پایان اجرا را درخواست می‌کنند؛ این TTL پشتیبان - نشست‌های بلندمدت و فراخواننده‌های آینده است. -- تغییرات زیر `mcp.*` با dispose کردن runtimeهای MCP نشستِ cache‌شده به‌صورت hot-apply اعمال می‌شوند. - کشف/استفاده بعدی از ابزار آن‌ها را از پیکربندی جدید دوباره ایجاد می‌کند، بنابراین ورودی‌های - حذف‌شده `mcp.servers` به‌جای انتظار برای TTL بیکاری، بلافاصله جمع‌آوری می‌شوند. + `type: "http"` یک نام مستعار بومی CLI است که `openclaw mcp set` و + `openclaw doctor --fix` آن را به فیلد canonical یعنی `transport` نرمال‌سازی می‌کنند. +- `mcp.sessionIdleTtlMs`: TTL بیکاری برای runtimeهای MCP بسته‌بندی‌شده با محدوده نشست. + اجراهای جاسازی‌شده یک‌باره درخواست پاک‌سازی پایان اجرا می‌دهند؛ این TTL پشتوانه‌ای برای + نشست‌های بلندمدت و فراخوان‌های آینده است. +- تغییرات زیر `mcp.*` با dispose کردن runtimeهای MCP نشست cacheشده، به‌صورت hot-apply اعمال می‌شوند. + کشف/استفاده بعدی از ابزار آن‌ها را از پیکربندی جدید دوباره ایجاد می‌کند، بنابراین ورودی‌های حذف‌شده + `mcp.servers` به‌جای انتظار برای TTL بیکاری، بلافاصله جمع‌آوری می‌شوند. برای رفتار runtime، [MCP](/fa/cli/mcp#openclaw-as-an-mcp-client-registry) و [backendهای CLI](/fa/gateway/cli-backends#bundle-mcp-overlays) را ببینید. @@ -155,14 +155,14 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م } ``` -- `allowBundled`: allowlist اختیاری فقط برای skillهای بسته‌شده (Skills مدیریت‌شده/workspace بدون تاثیر). -- `load.extraDirs`: ریشه‌های skill اشتراکی اضافی (کمترین تقدم). -- `install.preferBrew`: وقتی true باشد، در صورت در دسترس بودن `brew`، - پیش از fallback به گونه‌های دیگر نصب‌کننده، نصب‌کننده‌های Homebrew ترجیح داده می‌شوند. -- `install.nodeManager`: ترجیح نصب‌کننده node برای مشخصات `metadata.openclaw.install` +- `allowBundled`: allowlist اختیاری فقط برای Skills بسته‌بندی‌شده (Skills مدیریت‌شده/فضای کاری بی‌تأثیر می‌مانند). +- `load.extraDirs`: ریشه‌های Skill مشترک اضافی (پایین‌ترین اولویت). +- `install.preferBrew`: وقتی true باشد، اگر `brew` در دسترس باشد، پیش از fallback به گونه‌های دیگر installer، + installerهای Homebrew ترجیح داده می‌شوند. +- `install.nodeManager`: ترجیح installer node برای مشخصات `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` یک skill را حتی اگر بسته‌شده/نصب‌شده باشد غیرفعال می‌کند. -- `entries..apiKey`: میانبر برای skillهایی که یک env var اصلی اعلام می‌کنند (رشته plaintext یا شی SecretRef). +- `entries..enabled: false` یک Skill را حتی اگر بسته‌بندی‌شده/نصب‌شده باشد غیرفعال می‌کند. +- `entries..apiKey`: میان‌بری برای Skillsای که یک env var اصلی اعلام می‌کنند (رشته plaintext یا شیء SecretRef). --- @@ -173,6 +173,7 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -191,40 +192,44 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م ``` - از `~/.openclaw/extensions`، `/.openclaw/extensions`، به‌علاوه `plugins.load.paths` بارگذاری می‌شود. -- کشف، Pluginهای بومی OpenClaw به‌علاوه بسته‌های سازگار Codex و بسته‌های Claude را می‌پذیرد، از جمله بسته‌های چیدمان پیش‌فرض Claude بدون manifest. -- **تغییرات پیکربندی به راه‌اندازی دوباره gateway نیاز دارند.** -- `allow`: allowlist اختیاری (فقط Pluginهای فهرست‌شده بارگذاری می‌شوند). `deny` اولویت دارد. -- `plugins.entries..apiKey`: فیلد میانبر کلید API در سطح Plugin (وقتی توسط Plugin پشتیبانی شود). -- `plugins.entries..env`: نگاشت env var محدود به Plugin. -- `plugins.entries..hooks.allowPromptInjection`: وقتی `false` باشد، هسته `before_prompt_build` را مسدود می‌کند و فیلدهای تغییر‌دهنده prompt از `before_agent_start` قدیمی را نادیده می‌گیرد، در حالی که `modelOverride` و `providerOverride` قدیمی را حفظ می‌کند. روی hookهای Plugin بومی و دایرکتوری‌های hook ارائه‌شده توسط bundleهای پشتیبانی‌شده اعمال می‌شود. -- `plugins.entries..hooks.allowConversationAccess`: وقتی `true` باشد، Pluginهای غیر بسته‌شده مورد اعتماد می‌توانند محتوای خام گفتگو را از hookهای typed مانند `llm_input`، `llm_output`، `before_agent_finalize`، و `agent_end` بخوانند. -- `plugins.entries..subagent.allowModelOverride`: به‌صراحت به این Plugin اعتماد می‌کند تا overrideهای `provider` و `model` در هر اجرا را برای اجرای‌های subagent پس‌زمینه درخواست کند. -- `plugins.entries..subagent.allowedModels`: allowlist اختیاری از هدف‌های canonical `provider/model` برای overrideهای subagent مورد اعتماد. فقط وقتی از `"*"` استفاده کنید که عمدا می‌خواهید هر مدلی را مجاز کنید. -- `plugins.entries..config`: شی پیکربندی تعریف‌شده توسط Plugin (در صورت وجود، با شمای Plugin بومی OpenClaw اعتبارسنجی می‌شود). -- تنظیمات حساب/runtime Plugin کانال زیر `channels.` قرار دارند و باید توسط فراداده `channelConfigs` در manifest Plugin مالک توصیف شوند، نه توسط رجیستری مرکزی گزینه‌های OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: تنظیمات ارائه‌دهنده web-fetch Firecrawl. - - `apiKey`: کلید API Firecrawl (SecretRef را می‌پذیرد). به `plugins.entries.firecrawl.config.webSearch.apiKey`، مقدار قدیمی `tools.web.fetch.firecrawl.apiKey`، یا env var `FIRECRAWL_API_KEY` fallback می‌کند. +- کشف، Pluginهای بومی OpenClaw به‌علاوه bundleهای سازگار Codex و bundleهای Claude، از جمله bundleهای layout پیش‌فرض Claude بدون manifest را می‌پذیرد. +- **تغییرات پیکربندی نیازمند راه‌اندازی مجدد gateway هستند.** +- `allow`: allowlist اختیاری (فقط Pluginهای فهرست‌شده بارگذاری می‌شوند). `deny` غالب است. +- `bundledDiscovery`: برای پیکربندی‌های جدید پیش‌فرضش `"allowlist"` است، بنابراین یک + `plugins.allow` غیرخالی، Pluginهای ارائه‌دهنده بسته‌بندی‌شده، از جمله ارائه‌دهندگان runtime جست‌وجوی وب را هم + gate می‌کند. Doctor برای پیکربندی‌های allowlist قدیمی مهاجرت‌داده‌شده `"compat"` می‌نویسد + تا رفتار موجود ارائه‌دهنده بسته‌بندی‌شده تا زمان opt in حفظ شود. +- `plugins.entries..apiKey`: فیلد میان‌بر کلید API در سطح Plugin (وقتی توسط Plugin پشتیبانی شود). +- `plugins.entries..env`: نقشه env var با محدوده Plugin. +- `plugins.entries..hooks.allowPromptInjection`: وقتی `false` باشد، هسته `before_prompt_build` را مسدود می‌کند و فیلدهای prompt-mutating را از `before_agent_start` قدیمی نادیده می‌گیرد، در حالی که `modelOverride` و `providerOverride` قدیمی را حفظ می‌کند. برای hookهای Plugin بومی و دایرکتوری‌های hook ارائه‌شده توسط bundle پشتیبانی‌شده اعمال می‌شود. +- `plugins.entries..hooks.allowConversationAccess`: وقتی `true` باشد، Pluginهای غیربسته‌بندی‌شده مورد اعتماد می‌توانند محتوای خام مکالمه را از hookهای typed مانند `llm_input`، `llm_output`، `before_agent_finalize`، و `agent_end` بخوانند. +- `plugins.entries..subagent.allowModelOverride`: به این Plugin صراحتا اعتماد می‌کند تا overrideهای `provider` و `model` هر اجرا را برای اجراهای subagent پس‌زمینه درخواست کند. +- `plugins.entries..subagent.allowedModels`: allowlist اختیاری از targetهای canonical `provider/model` برای overrideهای subagent مورد اعتماد. فقط وقتی عمدا می‌خواهید هر مدلی را مجاز کنید از `"*"` استفاده کنید. +- `plugins.entries..config`: شیء پیکربندی تعریف‌شده توسط Plugin (در صورت وجود، با اسکیمای Plugin بومی OpenClaw اعتبارسنجی می‌شود). +- تنظیمات حساب/runtime کانال Plugin زیر `channels.` قرار دارند و باید با فراداده `channelConfigs` در manifest Plugin مالک توصیف شوند، نه با یک رجیستری مرکزی گزینه‌های OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: تنظیمات ارائه‌دهنده web-fetch مربوط به Firecrawl. + - `apiKey`: کلید API Firecrawl (SecretRef را می‌پذیرد). به `plugins.entries.firecrawl.config.webSearch.apiKey`، مقدار قدیمی `tools.web.fetch.firecrawl.apiKey`، یا env var یعنی `FIRECRAWL_API_KEY` fallback می‌کند. - `baseUrl`: URL پایه API Firecrawl (پیش‌فرض: `https://api.firecrawl.dev`؛ overrideهای self-hosted باید endpointهای private/internal را هدف بگیرند). - `onlyMainContent`: فقط محتوای اصلی را از صفحه‌ها استخراج می‌کند (پیش‌فرض: `true`). - - `maxAgeMs`: حداکثر سن cache بر حسب میلی‌ثانیه (پیش‌فرض: `172800000` / ۲ روز). + - `maxAgeMs`: بیشینه عمر cache بر حسب میلی‌ثانیه (پیش‌فرض: `172800000` / ۲ روز). - `timeoutSeconds`: timeout درخواست scrape بر حسب ثانیه (پیش‌فرض: `60`). - `plugins.entries.xai.config.xSearch`: تنظیمات xAI X Search (جست‌وجوی وب Grok). - `enabled`: ارائه‌دهنده X Search را فعال می‌کند. - `model`: مدل Grok برای استفاده در جست‌وجو (مثلا `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: تنظیمات memory dreaming. برای فازها و thresholdها [Dreaming](/fa/concepts/dreaming) را ببینید. - - `enabled`: سوییچ اصلی dreaming (پیش‌فرض `false`). - - `frequency`: cadence کرون برای هر sweep کامل dreaming (به‌طور پیش‌فرض `"0 3 * * *"`). - - `model`: override اختیاری مدل subagent با نام Dream Diary. به `plugins.entries.memory-core.subagent.allowModelOverride: true` نیاز دارد؛ برای محدود کردن هدف‌ها با `allowedModels` همراه کنید. خطاهای model-unavailable یک بار با مدل پیش‌فرض نشست دوباره تلاش می‌شوند؛ خطاهای trust یا allowlist بی‌صدا fallback نمی‌کنند. - - سیاست فاز و thresholdها جزئیات پیاده‌سازی هستند (کلیدهای پیکربندی قابل مشاهده برای کاربر نیستند). +- `plugins.entries.memory-core.config.dreaming`: تنظیمات Dreaming حافظه. برای فازها و آستانه‌ها [Dreaming](/fa/concepts/dreaming) را ببینید. + - `enabled`: کلید اصلی Dreaming (پیش‌فرض `false`). + - `frequency`: cadence کرون برای هر sweep کامل Dreaming (به‌طور پیش‌فرض `"0 3 * * *"`). + - `model`: override اختیاری مدل subagent مربوط به Dream Diary. نیازمند `plugins.entries.memory-core.subagent.allowModelOverride: true` است؛ همراه با `allowedModels` استفاده کنید تا targetها محدود شوند. خطاهای model-unavailable یک‌بار با مدل پیش‌فرض نشست retry می‌شوند؛ شکست‌های trust یا allowlist بی‌صدا fallback نمی‌کنند. + - سیاست فاز و آستانه‌ها جزئیات پیاده‌سازی هستند (کلیدهای پیکربندی کاربرمحور نیستند). - پیکربندی کامل حافظه در [مرجع پیکربندی حافظه](/fa/reference/memory-config) قرار دارد: - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Pluginهای فعال‌شده بسته Claude می‌توانند پیش‌فرض‌های Pi جاسازی‌شده را نیز از `settings.json` ارائه کنند؛ OpenClaw آن‌ها را به‌عنوان تنظیمات agent پاک‌سازی‌شده اعمال می‌کند، نه patchهای خام پیکربندی OpenClaw. -- `plugins.slots.memory`: شناسه Plugin حافظه فعال را انتخاب کنید، یا برای غیرفعال کردن Pluginهای حافظه `"none"` را برگزینید. -- `plugins.slots.contextEngine`: شناسه Plugin موتور context فعال را انتخاب کنید؛ پیش‌فرض `"legacy"` است مگر اینکه موتور دیگری را نصب و انتخاب کنید. +- Pluginهای bundle فعال Claude همچنین می‌توانند پیش‌فرض‌های Pi جاسازی‌شده را از `settings.json` ارائه کنند؛ OpenClaw آن‌ها را به‌عنوان تنظیمات پاک‌سازی‌شده عامل اعمال می‌کند، نه patchهای خام پیکربندی OpenClaw. +- `plugins.slots.memory`: شناسه Plugin حافظه فعال را انتخاب می‌کند، یا برای غیرفعال کردن Pluginهای حافظه `"none"` را انتخاب کنید. +- `plugins.slots.contextEngine`: شناسه Plugin موتور context فعال را انتخاب می‌کند؛ مگر اینکه موتور دیگری را نصب و انتخاب کنید، پیش‌فرض `"legacy"` است. [Pluginها](/fa/tools/plugin) را ببینید. @@ -232,12 +237,12 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م ## تعهدها -`commitments` حافظه پیگیری inferred را کنترل می‌کند: OpenClaw می‌تواند check-inها را از نوبت‌های گفتگو تشخیص دهد و آن‌ها را از طریق اجرای‌های heartbeat تحویل دهد. +`commitments` حافظه پیگیری استنباط‌شده را کنترل می‌کند: OpenClaw می‌تواند check-inها را از turnهای مکالمه تشخیص دهد و آن‌ها را از طریق اجراهای Heartbeat تحویل دهد. -- `commitments.enabled`: استخراج پنهان LLM، ذخیره‌سازی، و تحویل heartbeat را برای تعهدهای پیگیری inferred فعال می‌کند. پیش‌فرض: `false`. -- `commitments.maxPerDay`: حداکثر تعهدهای پیگیری inferred که در یک روز rolling برای هر نشست agent تحویل داده می‌شوند. پیش‌فرض: `3`. +- `commitments.enabled`: استخراج LLM پنهان، ذخیره‌سازی، و تحویل Heartbeat را برای تعهدهای پیگیری استنباط‌شده فعال می‌کند. پیش‌فرض: `false`. +- `commitments.maxPerDay`: بیشینه تعهدهای پیگیری استنباط‌شده که در یک روز rolling برای هر نشست عامل تحویل داده می‌شوند. پیش‌فرض: `3`. -[تعهدهای inferred](/fa/concepts/commitments) را ببینید. +[تعهدهای استنباط‌شده](/fa/concepts/commitments) را ببینید. --- @@ -289,51 +294,55 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م - `evaluateEnabled: false`، `act:evaluate` و `wait --fn` را غیرفعال می‌کند. - `tabCleanup` زبانه‌های ردیابی‌شده‌ی عامل اصلی را پس از زمان بیکاری یا وقتی یک - نشست از سقف خود فراتر می‌رود، آزاد می‌کند. برای غیرفعال کردن هرکدام از این + نشست از سقف خود فراتر برود، بازپس می‌گیرد. برای غیرفعال کردن هرکدام از این حالت‌های پاک‌سازی، `idleMinutes: 0` یا `maxTabsPerSession: 0` را تنظیم کنید. - وقتی `ssrfPolicy.dangerouslyAllowPrivateNetwork` تنظیم نشده باشد غیرفعال است، بنابراین پیمایش مرورگر به‌صورت پیش‌فرض سخت‌گیرانه می‌ماند. -- فقط وقتی عمداً به پیمایش مرورگر در شبکه‌ی خصوصی اعتماد دارید، `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` را تنظیم کنید. -- در حالت سخت‌گیرانه، نقاط پایانی پروفایل CDP راه‌دور (`profiles.*.cdpUrl`) هنگام بررسی‌های دسترس‌پذیری/کشف، مشمول همان مسدودسازی شبکه‌ی خصوصی هستند. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` را فقط وقتی تنظیم کنید که عمداً به پیمایش مرورگر در شبکه‌ی خصوصی اعتماد دارید. +- در حالت سخت‌گیرانه، نقطه‌های پایانی پروفایل CDP راه‌دور (`profiles.*.cdpUrl`) هنگام بررسی‌های دسترسی‌پذیری/کشف، مشمول همان مسدودسازی شبکه‌ی خصوصی هستند. - `ssrfPolicy.allowPrivateNetwork` همچنان به‌عنوان نام مستعار قدیمی پشتیبانی می‌شود. - در حالت سخت‌گیرانه، برای استثناهای صریح از `ssrfPolicy.hostnameAllowlist` و `ssrfPolicy.allowedHostnames` استفاده کنید. -- پروفایل‌های راه‌دور فقط برای اتصال هستند (start/stop/reset غیرفعال است). +- پروفایل‌های راه‌دور فقط-اتصال هستند (شروع/توقف/بازنشانی غیرفعال است). - `profiles.*.cdpUrl` مقدارهای `http://`، `https://`، `ws://` و `wss://` را می‌پذیرد. وقتی می‌خواهید OpenClaw مسیر `/json/version` را کشف کند از HTTP(S) استفاده کنید؛ - وقتی ارائه‌دهنده‌ی شما یک URL مستقیم DevTools WebSocket می‌دهد از WS(S) استفاده کنید. -- `remoteCdpTimeoutMs` و `remoteCdpHandshakeTimeoutMs` برای دسترس‌پذیری CDP راه‌دور و - `attachOnly` به‌علاوه‌ی درخواست‌های باز کردن زبانه اعمال می‌شوند. پروفایل‌های + وقتی ارائه‌دهنده‌ی شما یک URL مستقیم WebSocket برای DevTools می‌دهد، از WS(S) + استفاده کنید. +- `remoteCdpTimeoutMs` و `remoteCdpHandshakeTimeoutMs` برای دسترسی‌پذیری CDP راه‌دور و + `attachOnly` و همچنین درخواست‌های باز کردن زبانه اعمال می‌شوند. پروفایل‌های loopback مدیریت‌شده، پیش‌فرض‌های CDP محلی را نگه می‌دارند. -- اگر یک سرویس CDP با مدیریت خارجی از طریق loopback در دسترس است، برای آن - پروفایل `attachOnly: true` را تنظیم کنید؛ در غیر این صورت OpenClaw درگاه loopback را به‌عنوان یک - پروفایل مرورگر محلی مدیریت‌شده در نظر می‌گیرد و ممکن است خطاهای مالکیت درگاه محلی گزارش کند. +- اگر یک سرویس CDP مدیریت‌شده‌ی بیرونی از طریق loopback در دسترس است، برای آن + پروفایل `attachOnly: true` را تنظیم کنید؛ در غیر این صورت OpenClaw پورت loopback را + به‌عنوان یک پروفایل مرورگر محلی مدیریت‌شده در نظر می‌گیرد و ممکن است خطاهای + مالکیت پورت محلی گزارش کند. - پروفایل‌های `existing-session` به‌جای CDP از Chrome MCP استفاده می‌کنند و می‌توانند روی - میزبان انتخاب‌شده یا از طریق یک گره مرورگر متصل، متصل شوند. -- پروفایل‌های `existing-session` می‌توانند `userDataDir` را برای هدف‌گیری یک - پروفایل مرورگر مبتنی بر Chromium مشخص، مانند Brave یا Edge، تنظیم کنند. -- پروفایل‌های `existing-session` محدودیت‌های فعلی مسیر Chrome MCP را نگه می‌دارند: - کنش‌های مبتنی بر snapshot/ref به‌جای هدف‌گیری با گزینشگر CSS، قلاب‌های بارگذاری یک‌فایلی، - نبود بازنویسی مهلت گفت‌وگو، نبود `wait --load networkidle`، و نبود - `responsebody`، خروجی PDF، رهگیری دانلود یا کنش‌های دسته‌ای. -- پروفایل‌های `openclaw` محلی مدیریت‌شده، `cdpPort` و `cdpUrl` را به‌صورت خودکار اختصاص می‌دهند؛ - فقط برای CDP راه‌دور، `cdpUrl` را صریح تنظیم کنید. -- پروفایل‌های محلی مدیریت‌شده می‌توانند `executablePath` را تنظیم کنند تا - `browser.executablePath` سراسری را برای آن پروفایل بازنویسی کنند. از این برای اجرای یک پروفایل در + میزبان انتخاب‌شده یا از طریق یک گره مرورگر متصل شوند. +- پروفایل‌های `existing-session` می‌توانند برای هدف گرفتن یک پروفایل مرورگر مشخص مبتنی بر + Chromium مانند Brave یا Edge، مقدار `userDataDir` را تنظیم کنند. +- پروفایل‌های `existing-session` محدودیت‌های مسیر فعلی Chrome MCP را نگه می‌دارند: + کنش‌های مبتنی بر snapshot/ref به‌جای هدف‌گیری با انتخابگر CSS، قلاب‌های بارگذاری + یک‌فایلی، بدون بازنویسی مهلت گفت‌وگو، بدون `wait --load networkidle`، و بدون + `responsebody`، خروجی PDF، رهگیری دانلود، یا کنش‌های دسته‌ای. +- پروفایل‌های محلی مدیریت‌شده‌ی `openclaw` مقدارهای `cdpPort` و `cdpUrl` را خودکار تخصیص می‌دهند؛ + `cdpUrl` را فقط برای CDP راه‌دور به‌صراحت تنظیم کنید. +- پروفایل‌های محلی مدیریت‌شده می‌توانند برای بازنویسی `browser.executablePath` سراسری + برای همان پروفایل، `executablePath` را تنظیم کنند. از این برای اجرای یک پروفایل در Chrome و پروفایلی دیگر در Brave استفاده کنید. -- پروفایل‌های محلی مدیریت‌شده برای کشف HTTP مربوط به Chrome CDP پس از شروع فرایند از `browser.localLaunchTimeoutMs` - و برای آمادگی websocket مربوط به CDP پس از راه‌اندازی از `browser.localCdpReadyTimeoutMs` استفاده می‌کنند. - روی میزبان‌های کندتر که Chrome با موفقیت شروع می‌شود اما بررسی‌های آمادگی با شروع رقابت می‌کنند، این مقادیر را افزایش دهید. - هر دو مقدار باید عدد صحیح مثبت تا `120000` ms باشند؛ مقدارهای پیکربندی نامعتبر رد می‌شوند. +- پروفایل‌های محلی مدیریت‌شده پس از شروع فرایند، برای کشف HTTP مربوط به Chrome CDP از + `browser.localLaunchTimeoutMs` و برای آمادگی websocket مربوط به CDP پس از اجرا از + `browser.localCdpReadyTimeoutMs` استفاده می‌کنند. روی میزبان‌های کندتر که Chrome با + موفقیت شروع می‌شود اما بررسی‌های آمادگی با راه‌اندازی رقابت می‌کنند، این مقدارها را + افزایش دهید. هر دو مقدار باید عدد صحیح مثبت تا `120000` میلی‌ثانیه باشند؛ + مقدارهای پیکربندی نامعتبر رد می‌شوند. - ترتیب تشخیص خودکار: مرورگر پیش‌فرض اگر مبتنی بر Chromium باشد → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` و `browser.profiles..executablePath` هر دو - `~` و `~/...` را برای پوشه‌ی خانه‌ی سیستم‌عامل شما پیش از راه‌اندازی Chromium می‌پذیرند. - `userDataDir` هر پروفایل در پروفایل‌های `existing-session` نیز با tilde گسترش می‌یابد. -- سرویس کنترل: فقط loopback (درگاه برگرفته از `gateway.port`، پیش‌فرض `18791`). -- `extraArgs` پرچم‌های راه‌اندازی اضافی را به شروع محلی Chromium اضافه می‌کند (برای مثال - `--disable-gpu`، اندازه‌گذاری پنجره، یا پرچم‌های اشکال‌زدایی). +- `browser.executablePath` و `browser.profiles..executablePath` هر دو پیش از اجرای + Chromium، `~` و `~/...` را برای پوشه‌ی خانگی سیستم‌عامل شما می‌پذیرند. + `userDataDir` در هر پروفایل برای پروفایل‌های `existing-session` نیز با tilde گسترش می‌یابد. +- سرویس کنترل: فقط loopback (پورت مشتق‌شده از `gateway.port`، پیش‌فرض `18791`). +- `extraArgs` پرچم‌های اجرای اضافی را به راه‌اندازی محلی Chromium اضافه می‌کند (برای نمونه + `--disable-gpu`، اندازه‌بندی پنجره، یا پرچم‌های اشکال‌زدایی). --- -## UI +## رابط کاربری ```json5 { @@ -347,8 +356,8 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م } ``` -- `seamColor`: رنگ تأکیدی برای پوسته‌ی UI برنامه‌ی بومی (رنگ حباب Talk Mode و مانند آن). -- `assistant`: بازنویسی هویت Control UI. در نبود آن، به هویت عامل فعال بازمی‌گردد. +- `seamColor`: رنگ تأکیدی برای chrome رابط کاربری برنامه‌ی بومی (رنگ حباب Talk Mode و غیره). +- `assistant`: بازنویسی هویت Control UI. در صورت نبود، به هویت عامل فعال بازمی‌گردد. --- @@ -424,74 +433,75 @@ Pi جاسازی‌شده و دیگر adapterهای زمان اجرا مصرف م } ``` - + -- `mode`: `local` (اجرای Gateway) یا `remote` (اتصال به Gateway راه‌دور). Gateway از شروع به کار خودداری می‌کند مگر اینکه `local` باشد. -- `port`: پورت واحد و چندمنظوره برای WS + HTTP. اولویت: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`، `loopback` (پیش‌فرض)، `lan` (`0.0.0.0`)، `tailnet` (فقط IP ‏Tailscale)، یا `custom`. -- **نام‌های مستعار bind قدیمی**: در `gateway.bind` از مقدارهای حالت bind استفاده کنید (`auto`، `loopback`، `lan`، `tailnet`، `custom`)، نه نام‌های مستعار میزبان (`0.0.0.0`، `127.0.0.1`، `localhost`، `::`، `::1`). -- **یادداشت Docker**: مقدار پیش‌فرض `loopback` روی `127.0.0.1` داخل کانتینر گوش می‌دهد. با شبکه‌بندی bridge در Docker (`-p 18789:18789`)، ترافیک روی `eth0` می‌رسد، بنابراین Gateway قابل دسترسی نیست. از `--network host` استفاده کنید، یا `bind: "lan"` (یا `bind: "custom"` همراه با `customBindHost: "0.0.0.0"`) را تنظیم کنید تا روی همه رابط‌ها گوش دهد. -- **احراز هویت**: به‌طور پیش‌فرض الزامی است. bindهای غیر loopback به احراز هویت Gateway نیاز دارند. در عمل یعنی یک توکن/گذرواژه مشترک یا یک reverse proxy آگاه از هویت با `gateway.auth.mode: "trusted-proxy"`. جادوگر راه‌اندازی به‌طور پیش‌فرض یک توکن تولید می‌کند. -- اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده‌اند (از جمله SecretRefs)، `gateway.auth.mode` را صراحتا روی `token` یا `password` تنظیم کنید. وقتی هر دو پیکربندی شده باشند و mode تنظیم نشده باشد، جریان‌های شروع به کار و نصب/تعمیر سرویس شکست می‌خورند. -- `gateway.auth.mode: "none"`: حالت صریح بدون احراز هویت. فقط برای راه‌اندازی‌های local loopback مورد اعتماد استفاده کنید؛ این گزینه عمدا در اعلان‌های راه‌اندازی ارائه نمی‌شود. -- `gateway.auth.mode: "trusted-proxy"`: احراز هویت مرورگر/کاربر را به یک reverse proxy آگاه از هویت واگذار می‌کند و به هدرهای هویتی از `gateway.trustedProxies` اعتماد می‌کند (نگاه کنید به [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth)). این حالت به‌طور پیش‌فرض انتظار یک منبع پراکسی **غیر loopback** را دارد؛ reverse proxyهای loopback روی همان میزبان به تنظیم صریح `gateway.auth.trustedProxy.allowLoopback = true` نیاز دارند. فراخوان‌های داخلی همان میزبان می‌توانند از `gateway.auth.password` به‌عنوان fallback مستقیم محلی استفاده کنند؛ `gateway.auth.token` همچنان با حالت trusted-proxy ناسازگار و متقابلا انحصاری است. -- `gateway.auth.allowTailscale`: وقتی `true` باشد، هدرهای هویت Tailscale Serve می‌توانند احراز هویت Control UI/WebSocket را برآورده کنند (از طریق `tailscale whois` تأیید می‌شود). نقاط پایانی HTTP API از آن احراز هویت هدر Tailscale استفاده **نمی‌کنند**؛ در عوض از حالت عادی احراز هویت HTTP خود Gateway پیروی می‌کنند. این جریان بدون توکن فرض می‌کند میزبان Gateway مورد اعتماد است. وقتی `tailscale.mode = "serve"` باشد، مقدار پیش‌فرض `true` است. -- `gateway.auth.rateLimit`: محدودکننده اختیاری شکست احراز هویت. برای هر IP مشتری و هر دامنه احراز هویت اعمال می‌شود (shared-secret و device-token جداگانه ردیابی می‌شوند). تلاش‌های مسدودشده `429` + `Retry-After` برمی‌گردانند. - - در مسیر async ‏Tailscale Serve ‏Control UI، تلاش‌های ناموفق برای همان `{scope, clientIp}` پیش از نوشتن شکست، سریالی می‌شوند. بنابراین تلاش‌های بد هم‌زمان از همان مشتری می‌توانند به‌جای اینکه هر دو مانند عدم‌تطابق ساده هم‌زمان عبور کنند، در درخواست دوم محدودکننده را فعال کنند. - - مقدار پیش‌فرض `gateway.auth.rateLimit.exemptLoopback` برابر `true` است؛ وقتی عمدا می‌خواهید ترافیک localhost نیز محدودسازی نرخ شود (برای راه‌اندازی‌های آزمایشی یا استقرارهای strict proxy)، آن را روی `false` تنظیم کنید. -- تلاش‌های احراز هویت WS با مبدا مرورگر همیشه با غیرفعال بودن معافیت loopback محدودسازی می‌شوند (دفاع چندلایه در برابر brute force مبتنی بر مرورگر روی localhost). -- روی loopback، آن قفل‌شدن‌های با مبدا مرورگر برای هر مقدار نرمال‌شده `Origin` - جدا می‌شوند، بنابراین شکست‌های تکراری از یک مبدا localhost به‌طور خودکار - مبدا دیگری را قفل نمی‌کند. -- `tailscale.mode`: `serve` (فقط tailnet، bind به loopback) یا `funnel` (عمومی، نیازمند احراز هویت). -- `controlUi.allowedOrigins`: فهرست مجاز صریح برای مبدا مرورگر جهت اتصال‌های WebSocket به Gateway. وقتی انتظار می‌رود مشتریان مرورگر از مبداهای غیر loopback باشند، الزامی است. -- `controlUi.chatMessageMaxWidth`: حداکثر عرض اختیاری برای پیام‌های چت گروه‌بندی‌شده Control UI. مقدارهای عرض CSS محدودشده مانند `960px`، `82%`، `min(1280px, 82%)` و `calc(100% - 2rem)` را می‌پذیرد. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: حالت خطرناک که fallback مبدا Host-header را برای استقرارهایی فعال می‌کند که عمدا به سیاست مبدا Host-header متکی هستند. +- `mode`: `local` (اجرای gateway) یا `remote` (اتصال به gateway راه‌دور). Gateway شروع به کار را رد می‌کند مگر اینکه `local` باشد. +- `port`: پورت multiplexed تکی برای WS + HTTP. اولویت: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `bind`: `auto`، `loopback` (پیش‌فرض)، `lan` (`0.0.0.0`)، `tailnet` (فقط IP مربوط به Tailscale)، یا `custom`. +- **نام‌های مستعار bind قدیمی**: در `gateway.bind` از مقادیر حالت bind استفاده کنید (`auto`، `loopback`، `lan`، `tailnet`، `custom`)، نه نام‌های مستعار host (`0.0.0.0`، `127.0.0.1`، `localhost`، `::`، `::1`). +- **نکته Docker**: bind پیش‌فرض `loopback` داخل container روی `127.0.0.1` گوش می‌دهد. با شبکه‌سازی Docker bridge (`-p 18789:18789`)، ترافیک روی `eth0` وارد می‌شود، بنابراین gateway دسترس‌ناپذیر است. برای گوش دادن روی همه interfaceها از `--network host` استفاده کنید، یا `bind: "lan"` (یا `bind: "custom"` همراه با `customBindHost: "0.0.0.0"`) را تنظیم کنید. +- **Auth**: به‌صورت پیش‌فرض لازم است. bindهای غیر-loopback به auth برای gateway نیاز دارند. در عمل یعنی یک token/password مشترک یا یک reverse proxy آگاه از هویت با `gateway.auth.mode: "trusted-proxy"`. جادوگر onboarding به‌صورت پیش‌فرض یک token ایجاد می‌کند. +- اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده‌اند (از جمله SecretRefها)، `gateway.auth.mode` را صراحتا روی `token` یا `password` تنظیم کنید. وقتی هر دو پیکربندی شده باشند و mode تنظیم نشده باشد، startup و جریان‌های نصب/repair سرویس شکست می‌خورند. +- `gateway.auth.mode: "none"`: حالت صریح بدون auth. فقط برای راه‌اندازی‌های مورداعتماد local loopback استفاده کنید؛ این حالت عمدا در promptهای onboarding ارائه نمی‌شود. +- `gateway.auth.mode: "trusted-proxy"`: auth مرورگر/کاربر را به یک reverse proxy آگاه از هویت واگذار می‌کند و به headerهای هویت از `gateway.trustedProxies` اعتماد می‌کند (ببینید [Auth با Trusted Proxy](/fa/gateway/trusted-proxy-auth)). این حالت به‌صورت پیش‌فرض یک منبع proxy **غیر-loopback** انتظار دارد؛ reverse proxyهای loopback روی همان host به `gateway.auth.trustedProxy.allowLoopback = true` صریح نیاز دارند. فراخوان‌های داخلی روی همان host می‌توانند از `gateway.auth.password` به‌عنوان fallback مستقیم محلی استفاده کنند؛ `gateway.auth.token` همچنان با حالت trusted-proxy ناسازگار است. +- `gateway.auth.allowTailscale`: وقتی `true` باشد، headerهای هویت Tailscale Serve می‌توانند auth مربوط به Control UI/WebSocket را برآورده کنند (از طریق `tailscale whois` تأیید می‌شود). endpointهای HTTP API از آن auth مبتنی بر header مربوط به Tailscale استفاده **نمی‌کنند**؛ در عوض از حالت auth معمول HTTP در gateway پیروی می‌کنند. این جریان بدون token فرض می‌کند host مربوط به gateway مورداعتماد است. وقتی `tailscale.mode = "serve"` باشد، پیش‌فرض `true` است. +- `gateway.auth.rateLimit`: محدودکننده اختیاری auth ناموفق. برای هر IP کلاینت و هر محدوده auth اعمال می‌شود (shared-secret و device-token جداگانه ردیابی می‌شوند). تلاش‌های مسدودشده `429` + `Retry-After` برمی‌گردانند. + - در مسیر async مربوط به Tailscale Serve Control UI، تلاش‌های ناموفق برای همان `{scope, clientIp}` پیش از نوشتن failure به‌صورت سریالی اجرا می‌شوند. بنابراین تلاش‌های بد هم‌زمان از همان client می‌توانند در درخواست دوم limiter را فعال کنند، به‌جای اینکه هر دو صرفا به‌عنوان mismatch ساده عبور کنند. + - مقدار پیش‌فرض `gateway.auth.rateLimit.exemptLoopback` برابر `true` است؛ وقتی عمدا می‌خواهید ترافیک localhost هم rate-limit شود (برای setupهای تست یا استقرارهای proxy سخت‌گیرانه)، آن را روی `false` تنظیم کنید. +- تلاش‌های auth مربوط به WS با origin مرورگر همیشه با غیرفعال بودن معافیت loopback محدودسازی می‌شوند (دفاع چندلایه در برابر brute force مبتنی بر مرورگر روی localhost). +- روی loopback، آن lockoutهای با origin مرورگر به ازای مقدار نرمال‌شده `Origin` + جدا می‌شوند، بنابراین شکست‌های تکراری از یک origin مربوط به localhost به‌صورت خودکار + origin متفاوتی را lock out نمی‌کنند. +- `tailscale.mode`: `serve` (فقط tailnet، bind روی loopback) یا `funnel` (عمومی، نیازمند auth). +- `controlUi.allowedOrigins`: allowlist صریح origin مرورگر برای اتصال‌های Gateway WebSocket. وقتی انتظار می‌رود clientهای مرورگر از originهای غیر-loopback باشند، لازم است. +- `controlUi.chatMessageMaxWidth`: max-width اختیاری برای پیام‌های chat گروه‌بندی‌شده در Control UI. مقادیر محدودشده width در CSS مانند `960px`، `82%`، `min(1280px, 82%)`، و `calc(100% - 2rem)` را می‌پذیرد. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: حالت خطرناکی که fallback origin مبتنی بر header مربوط به Host را برای استقرارهایی فعال می‌کند که عمدا به سیاست origin مبتنی بر Host-header متکی هستند. - `remote.transport`: `ssh` (پیش‌فرض) یا `direct` (ws/wss). برای `direct`، مقدار `remote.url` باید `ws://` یا `wss://` باشد. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override اضطراری در محیط فرایند سمت مشتری - که `ws://` متن ساده را به IPهای شبکه خصوصی مورد اعتماد مجاز می‌کند؛ مقدار پیش‌فرض برای متن ساده همچنان فقط loopback است. معادل `openclaw.json` - وجود ندارد، و پیکربندی شبکه خصوصی مرورگر مانند - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` روی مشتریان WebSocket ‏Gateway - اثری ندارد. -- `gateway.remote.token` / `.password` فیلدهای اعتبارنامه مشتری راه‌دور هستند. آن‌ها به‌تنهایی احراز هویت Gateway را پیکربندی نمی‌کنند. -- `gateway.push.apns.relay.baseUrl`: URL پایه HTTPS برای relay خارجی APNs که buildهای رسمی/TestFlight ‏iOS پس از انتشار ثبت‌نام‌های متکی بر relay به Gateway از آن استفاده می‌کنند. این URL باید با URL ‏relay که در build ‏iOS کامپایل شده است مطابقت داشته باشد. -- `gateway.push.apns.relay.timeoutMs`: زمان‌سنج ارسال از Gateway به relay بر حسب میلی‌ثانیه. مقدار پیش‌فرض `10000` است. -- ثبت‌نام‌های متکی بر relay به یک هویت Gateway مشخص واگذار می‌شوند. برنامه iOS جفت‌شده `gateway.identity.get` را دریافت می‌کند، آن هویت را در ثبت‌نام relay قرار می‌دهد، و یک مجوز ارسال در محدوده ثبت‌نام را به Gateway ارسال می‌کند. Gateway دیگری نمی‌تواند آن ثبت‌نام ذخیره‌شده را دوباره استفاده کند. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: overrideهای موقت env برای پیکربندی relay بالا. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: راه گریز فقط مخصوص توسعه برای URLهای relay ‏HTTP روی loopback. URLهای relay تولیدی باید روی HTTPS بمانند. -- `gateway.handshakeTimeoutMs`: زمان‌سنج handshake پیش از احراز هویت WebSocket ‏Gateway بر حسب میلی‌ثانیه. پیش‌فرض: `15000`. وقتی `OPENCLAW_HANDSHAKE_TIMEOUT_MS` تنظیم شده باشد اولویت دارد. این مقدار را روی میزبان‌های پرترافیک یا کم‌توان که مشتریان محلی می‌توانند در حالی که گرم‌کردن شروع به کار هنوز در حال پایدار شدن است وصل شوند، افزایش دهید. -- `gateway.channelHealthCheckMinutes`: بازه health-monitor کانال بر حسب دقیقه. برای غیرفعال کردن restartهای health-monitor در سطح سراسری، `0` تنظیم کنید. پیش‌فرض: `5`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override اضطراری در environment process سمت client + که اجازه می‌دهد `ws://` plaintext به IPهای private-network مورداعتماد استفاده شود؛ + پیش‌فرض برای plaintext همچنان فقط loopback است. معادل `openclaw.json` + وجود ندارد، و config شبکه خصوصی مرورگر مانند + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` روی clientهای Gateway + WebSocket اثری ندارد. +- `gateway.remote.token` / `.password` فیلدهای credential برای remote-client هستند. آن‌ها به‌تنهایی auth مربوط به gateway را پیکربندی نمی‌کنند. +- `gateway.push.apns.relay.baseUrl`: URL پایه HTTPS برای relay خارجی APNs که buildهای رسمی/TestFlight iOS پس از انتشار registrationهای متکی به relay در gateway از آن استفاده می‌کنند. این URL باید با relay URL کامپایل‌شده داخل build iOS مطابقت داشته باشد. +- `gateway.push.apns.relay.timeoutMs`: timeout ارسال gateway به relay بر حسب میلی‌ثانیه. مقدار پیش‌فرض `10000` است. +- registrationهای متکی به relay به یک هویت gateway مشخص واگذار می‌شوند. app جفت‌شده iOS مقدار `gateway.identity.get` را دریافت می‌کند، آن هویت را در registration مربوط به relay قرار می‌دهد، و یک grant ارسال scoped به همان registration را به gateway forward می‌کند. Gateway دیگری نمی‌تواند آن registration ذخیره‌شده را دوباره استفاده کند. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: overrideهای موقت env برای config مربوط به relay در بالا. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: راه گریز فقط مخصوص توسعه برای URLهای relay روی loopback HTTP. URLهای relay تولیدی باید روی HTTPS بمانند. +- `gateway.handshakeTimeoutMs`: timeout handshake مربوط به Gateway WebSocket پیش از auth بر حسب میلی‌ثانیه. پیش‌فرض: `15000`. وقتی `OPENCLAW_HANDSHAKE_TIMEOUT_MS` تنظیم شده باشد، اولویت دارد. روی hostهای پربار یا کم‌توان که clientهای محلی می‌توانند وصل شوند در حالی که warmup زمان startup هنوز در حال تثبیت است، این مقدار را افزایش دهید. +- `gateway.channelHealthCheckMinutes`: فاصله health-monitor مربوط به channel بر حسب دقیقه. برای غیرفعال کردن restartهای health-monitor به‌صورت سراسری، `0` تنظیم کنید. پیش‌فرض: `5`. - `gateway.channelStaleEventThresholdMinutes`: آستانه stale-socket بر حسب دقیقه. این مقدار را بزرگ‌تر یا مساوی `gateway.channelHealthCheckMinutes` نگه دارید. پیش‌فرض: `30`. -- `gateway.channelMaxRestartsPerHour`: بیشینه restartهای health-monitor برای هر کانال/حساب در یک ساعت rolling. پیش‌فرض: `10`. -- `channels..healthMonitor.enabled`: انصراف در سطح هر کانال از restartهای health-monitor در حالی که مانیتور سراسری فعال می‌ماند. -- `channels..accounts..healthMonitor.enabled`: override در سطح هر حساب برای کانال‌های چندحسابی. وقتی تنظیم شود، بر override سطح کانال اولویت دارد. -- مسیرهای فراخوانی Gateway محلی فقط وقتی می‌توانند از `gateway.remote.*` به‌عنوان fallback استفاده کنند که `gateway.auth.*` تنظیم نشده باشد. -- اگر `gateway.auth.token` / `gateway.auth.password` صراحتا از طریق SecretRef پیکربندی شده و unresolved باشد، resolve به‌شکل بسته و امن شکست می‌خورد (بدون پوشاندن با fallback راه‌دور). -- `trustedProxies`: IPهای reverse proxy که TLS را terminate می‌کنند یا هدرهای forwarded-client تزریق می‌کنند. فقط پراکسی‌هایی را فهرست کنید که کنترلشان می‌کنید. ورودی‌های loopback همچنان برای راه‌اندازی‌های proxy/local-detection روی همان میزبان معتبرند (برای مثال Tailscale Serve یا یک reverse proxy محلی)، اما درخواست‌های loopback را واجد شرایط `gateway.auth.mode: "trusted-proxy"` نمی‌کنند. -- `allowRealIpFallback`: وقتی `true` باشد، اگر `X-Forwarded-For` وجود نداشته باشد Gateway مقدار `X-Real-IP` را می‌پذیرد. مقدار پیش‌فرض `false` است تا رفتار fail-closed حفظ شود. -- `gateway.nodes.pairing.autoApproveCidrs`: فهرست مجاز CIDR/IP اختیاری برای تأیید خودکار جفت‌سازی نخستین‌بار دستگاه node بدون scopeهای درخواست‌شده. وقتی تنظیم نشده باشد غیرفعال است. این مورد جفت‌سازی operator/browser/Control UI/WebChat را خودکار تأیید نمی‌کند، و ارتقاهای role، scope، metadata یا public-key را نیز خودکار تأیید نمی‌کند. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: شکل‌دهی سراسری allow/deny برای فرمان‌های اعلام‌شده node پس از جفت‌سازی و ارزیابی فهرست مجاز platform. از `allowCommands` برای انتخاب صریح فرمان‌های خطرناک node مانند `camera.snap`، `camera.clip` و `screen.record` استفاده کنید؛ `denyCommands` حتی اگر پیش‌فرض platform یا allow صریح در حالت عادی فرمانی را شامل شود، آن فرمان را حذف می‌کند. پس از اینکه یک node فهرست فرمان‌های اعلام‌شده خود را تغییر داد، آن جفت‌سازی دستگاه را رد و دوباره تأیید کنید تا Gateway snapshot فرمان به‌روزشده را ذخیره کند. -- `gateway.tools.deny`: نام ابزارهای اضافی مسدودشده برای HTTP `POST /tools/invoke` (فهرست deny پیش‌فرض را گسترش می‌دهد). -- `gateway.tools.allow`: نام ابزارها را از فهرست deny پیش‌فرض HTTP حذف می‌کند. +- `gateway.channelMaxRestartsPerHour`: بیشینه restartهای health-monitor برای هر channel/account در یک ساعت rolling. پیش‌فرض: `10`. +- `channels..healthMonitor.enabled`: opt-out به ازای هر channel برای restartهای health-monitor در حالی که monitor سراسری فعال می‌ماند. +- `channels..accounts..healthMonitor.enabled`: override به ازای هر account برای channelهای چند-accountی. وقتی تنظیم شود، بر override سطح channel اولویت دارد. +- مسیرهای فراخوانی gateway محلی فقط وقتی `gateway.auth.*` تنظیم نشده باشد می‌توانند از `gateway.remote.*` به‌عنوان fallback استفاده کنند. +- اگر `gateway.auth.token` / `gateway.auth.password` به‌صورت صریح از طریق SecretRef پیکربندی شده و unresolved باشد، resolution به‌صورت بسته شکست می‌خورد (بدون masking توسط remote fallback). +- `trustedProxies`: IPهای reverse proxy که TLS را terminate می‌کنند یا headerهای forwarded-client را inject می‌کنند. فقط proxyهایی را فهرست کنید که کنترلشان می‌کنید. entryهای loopback همچنان برای setupهای proxy/local-detection روی همان host معتبرند (برای مثال Tailscale Serve یا یک reverse proxy محلی)، اما آن‌ها درخواست‌های loopback را برای `gateway.auth.mode: "trusted-proxy"` واجد شرایط نمی‌کنند. +- `allowRealIpFallback`: وقتی `true` باشد، اگر `X-Forwarded-For` وجود نداشته باشد، gateway مقدار `X-Real-IP` را می‌پذیرد. پیش‌فرض `false` برای رفتار fail-closed است. +- `gateway.nodes.pairing.autoApproveCidrs`: allowlist اختیاری CIDR/IP برای auto-approve کردن pairing نخستین‌بار device مربوط به node بدون scopeهای درخواست‌شده. وقتی تنظیم نشده باشد غیرفعال است. این کار pairing مربوط به operator/browser/Control UI/WebChat را auto-approve نمی‌کند، و role، scope، metadata، یا upgradeهای public-key را هم auto-approve نمی‌کند. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: شکل‌دهی allow/deny سراسری برای commandهای اعلام‌شده node پس از pairing و ارزیابی allowlist پلتفرم. از `allowCommands` برای opt in به commandهای خطرناک node مانند `camera.snap`، `camera.clip`، و `screen.record` استفاده کنید؛ `denyCommands` یک command را حتی اگر default پلتفرم یا allow صریح در غیر این صورت آن را شامل می‌شد، حذف می‌کند. پس از اینکه node فهرست commandهای اعلام‌شده خود را تغییر داد، pairing آن device را reject و دوباره approve کنید تا gateway snapshot به‌روزشده commandها را ذخیره کند. +- `gateway.tools.deny`: نام toolهای اضافی مسدودشده برای HTTP `POST /tools/invoke` (فهرست deny پیش‌فرض را گسترش می‌دهد). +- `gateway.tools.allow`: نام toolها را از فهرست deny پیش‌فرض HTTP حذف می‌کند. -### نقاط پایانی سازگار با OpenAI +### endpointهای سازگار با OpenAI -- Chat Completions: به‌طور پیش‌فرض غیرفعال است. با `gateway.http.endpoints.chatCompletions.enabled: true` فعال کنید. +- Chat Completions: به‌صورت پیش‌فرض غیرفعال است. با `gateway.http.endpoints.chatCompletions.enabled: true` فعال کنید. - Responses API: `gateway.http.endpoints.responses.enabled`. -- سخت‌سازی ورودی URL در Responses: +- سخت‌سازی URL-input در Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - فهرست‌های مجاز خالی مانند تنظیم‌نشده در نظر گرفته می‌شوند؛ برای غیرفعال کردن دریافت URL از `gateway.http.endpoints.responses.files.allowUrl=false` + allowlistهای خالی unset در نظر گرفته می‌شوند؛ برای غیرفعال کردن دریافت URL از `gateway.http.endpoints.responses.files.allowUrl=false` و/یا `gateway.http.endpoints.responses.images.allowUrl=false` استفاده کنید. -- هدر اختیاری سخت‌سازی پاسخ: - - `gateway.http.securityHeaders.strictTransportSecurity` (فقط برای مبداهای HTTPS که کنترلشان می‌کنید تنظیم کنید؛ نگاه کنید به [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth#tls-termination-and-hsts)) +- header اختیاری برای سخت‌سازی response: + - `gateway.http.securityHeaders.strictTransportSecurity` (فقط برای originهای HTTPS تحت کنترل خودتان تنظیم کنید؛ ببینید [Auth با Trusted Proxy](/fa/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### جداسازی چندنمونه‌ای +### جداسازی چند-instance -چند Gateway را روی یک میزبان با پورت‌ها و دایرکتوری‌های state یکتا اجرا کنید: +چند gateway را روی یک host با پورت‌ها و state dirهای یکتا اجرا کنید: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -499,9 +509,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -پرچم‌های کمکی: `--dev` (از `~/.openclaw-dev` + پورت `19001` استفاده می‌کند)، `--profile ` (از `~/.openclaw-` استفاده می‌کند). +flagهای راحتی: `--dev` (از `~/.openclaw-dev` + پورت `19001` استفاده می‌کند)، `--profile ` (از `~/.openclaw-` استفاده می‌کند). -نگاه کنید به [چند Gateway](/fa/gateway/multiple-gateways). +ببینید [چند Gateway](/fa/gateway/multiple-gateways). ### `gateway.tls` @@ -519,11 +529,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: TLS termination را روی listener ‏Gateway فعال می‌کند (HTTPS/WSS) (پیش‌فرض: `false`). -- `autoGenerate`: وقتی فایل‌های صریح پیکربندی نشده باشند، یک جفت گواهی/کلید self-signed محلی را خودکار تولید می‌کند؛ فقط برای استفاده محلی/dev. -- `certPath`: مسیر فایل‌سیستم به فایل گواهی TLS. -- `keyPath`: مسیر فایل‌سیستم به فایل کلید خصوصی TLS؛ دسترسی آن را محدود نگه دارید. -- `caPath`: مسیر اختیاری bundle ‏CA برای تأیید مشتری یا زنجیره‌های trust سفارشی. +- `enabled`: termination مربوط به TLS را در listener مربوط به gateway فعال می‌کند (HTTPS/WSS) (پیش‌فرض: `false`). +- `autoGenerate`: وقتی فایل‌های صریح پیکربندی نشده‌اند، یک جفت cert/key خودامضاشده محلی را خودکار تولید می‌کند؛ فقط برای استفاده local/dev. +- `certPath`: مسیر filesystem به فایل گواهی TLS. +- `keyPath`: مسیر filesystem به فایل private key مربوط به TLS؛ با permission محدود نگه دارید. +- `caPath`: مسیر اختیاری bundle مربوط به CA برای verification کلاینت یا trust chainهای سفارشی. ### `gateway.reload` @@ -539,17 +549,17 @@ openclaw gateway --port 19001 } ``` -- `mode`: کنترل می‌کند ویرایش‌های پیکربندی در زمان اجرا چگونه اعمال شوند. - - `"off"`: ویرایش‌های زنده را نادیده بگیر؛ تغییرات به restart صریح نیاز دارند. - - `"restart"`: همیشه فرایند Gateway را هنگام تغییر پیکربندی restart کن. - - `"hot"`: تغییرات را بدون restart در همان فرایند اعمال کن. - - `"hybrid"` (پیش‌فرض): ابتدا hot reload را امتحان کن؛ اگر لازم بود به restart برگرد. -- `debounceMs`: پنجره debounce بر حسب ms پیش از اعمال تغییرات پیکربندی (عدد صحیح نامنفی). -- `deferralTimeoutMs`: حداکثر زمان اختیاری بر حسب ms برای انتظار عملیات‌های در جریان پیش از اجبار به restart. برای استفاده از انتظار محدود پیش‌فرض (`300000`) آن را حذف کنید؛ برای انتظار نامحدود و ثبت هشدارهای دوره‌ای still-pending، `0` تنظیم کنید. +- `mode`: کنترل می‌کند editهای config چگونه در runtime اعمال شوند. + - `"off"`: editهای live را نادیده می‌گیرد؛ تغییرات به restart صریح نیاز دارند. + - `"restart"`: همیشه process مربوط به gateway را هنگام تغییر config restart می‌کند. + - `"hot"`: تغییرات را بدون restart در همان process اعمال می‌کند. + - `"hybrid"` (پیش‌فرض): ابتدا hot reload را امتحان می‌کند؛ در صورت نیاز به restart fallback می‌کند. +- `debounceMs`: پنجره debounce بر حسب ms پیش از اعمال تغییرات config (عدد صحیح نامنفی). +- `deferralTimeoutMs`: بیشینه زمان اختیاری بر حسب ms برای انتظار جهت پایان عملیات‌های in-flight پیش از forcing یک restart. برای استفاده از انتظار محدود پیش‌فرض (`300000`) آن را حذف کنید؛ برای انتظار نامحدود و ثبت هشدارهای دوره‌ای still-pending مقدار `0` تنظیم کنید. --- -## Hookها +## قلاب‌ها ```json5 { @@ -588,42 +598,42 @@ openclaw gateway --port 19001 نکات اعتبارسنجی و ایمنی: - `hooks.enabled=true` به یک `hooks.token` غیرخالی نیاز دارد. -- `hooks.token` باید با `gateway.auth.token` **متفاوت** باشد؛ استفادهٔ دوباره از توکن Gateway رد می‌شود. -- `hooks.path` نمی‌تواند `/` باشد؛ از یک زیرمسیر اختصاصی مثل `/hooks` استفاده کنید. +- `hooks.token` باید از `gateway.auth.token` **متمایز** باشد؛ استفادهٔ دوباره از توکن Gateway رد می‌شود. +- `hooks.path` نمی‌تواند `/` باشد؛ از یک زیرمسیر اختصاصی مانند `/hooks` استفاده کنید. - اگر `hooks.allowRequestSessionKey=true` است، `hooks.allowedSessionKeyPrefixes` را محدود کنید، برای مثال `["hook:"]`. -- اگر یک نگاشت یا preset از `sessionKey` قالب‌دار استفاده می‌کند، `hooks.allowedSessionKeyPrefixes` و `hooks.allowRequestSessionKey=true` را تنظیم کنید. کلیدهای نگاشت ایستا به این opt-in نیاز ندارند. +- اگر یک نگاشت یا preset از `sessionKey` قالبی استفاده می‌کند، `hooks.allowedSessionKeyPrefixes` و `hooks.allowRequestSessionKey=true` را تنظیم کنید. کلیدهای نگاشت ایستا به این opt-in نیاز ندارند. **نقاط پایانی:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` از payload درخواست فقط وقتی پذیرفته می‌شود که `hooks.allowRequestSessionKey=true` باشد (پیش‌فرض: `false`). -- `POST /hooks/` → از طریق `hooks.mappings` resolve می‌شود - - مقادیر `sessionKey` در نگاشت که با template رندر شده‌اند، به‌عنوان دادهٔ خارجی در نظر گرفته می‌شوند و آن‌ها هم به `hooks.allowRequestSessionKey=true` نیاز دارند. +- `POST /hooks/` → از طریق `hooks.mappings` حل می‌شود + - مقادیر `sessionKey` نگاشت که از قالب رندر شده‌اند به‌عنوان دادهٔ بیرونی تلقی می‌شوند و آن‌ها نیز به `hooks.allowRequestSessionKey=true` نیاز دارند. - + -- `match.path` با زیرمسیر پس از `/hooks` مطابقت می‌دهد (مثلاً `/hooks/gmail` → `gmail`). -- `match.source` با یک فیلد payload برای مسیرهای generic مطابقت می‌دهد. -- templateهایی مثل `{{messages[0].subject}}` از payload خوانده می‌شوند. +- `match.path` با زیرمسیر بعد از `/hooks` مطابقت می‌کند (مثلاً `/hooks/gmail` → `gmail`). +- `match.source` با یک فیلد payload برای مسیرهای عمومی مطابقت می‌کند. +- قالب‌هایی مانند `{{messages[0].subject}}` از payload می‌خوانند. - `transform` می‌تواند به یک ماژول JS/TS اشاره کند که یک کنش hook برمی‌گرداند. - - `transform.module` باید یک مسیر نسبی باشد و داخل `hooks.transformsDir` باقی بماند (مسیرهای مطلق و traversal رد می‌شوند). - - `hooks.transformsDir` را زیر `~/.openclaw/hooks/transforms` نگه دارید؛ دایرکتوری‌های skill در workspace رد می‌شوند. اگر `openclaw doctor` این مسیر را نامعتبر گزارش کرد، ماژول transform را به دایرکتوری transforms مربوط به hooks منتقل کنید یا `hooks.transformsDir` را حذف کنید. -- `agentId` به یک agent مشخص route می‌کند؛ شناسه‌های ناشناخته به مقدار پیش‌فرض برمی‌گردند. -- `allowedAgentIds`: route کردن صریح را محدود می‌کند (`*` یا حذف‌شده = همه مجاز، `[]` = همه رد). -- `defaultSessionKey`: کلید session ثابت اختیاری برای اجرای agent مربوط به hook بدون `sessionKey` صریح. -- `allowRequestSessionKey`: به فراخوان‌های `/hooks/agent` و کلیدهای session نگاشت template-driven اجازه می‌دهد `sessionKey` را تنظیم کنند (پیش‌فرض: `false`). -- `allowedSessionKeyPrefixes`: allowlist پیشوند اختیاری برای مقادیر صریح `sessionKey` (درخواست + نگاشت)، مثلاً `["hook:"]`. وقتی هر نگاشت یا preset از `sessionKey` قالب‌دار استفاده کند، این مورد الزامی می‌شود. -- `deliver: true` پاسخ نهایی را به یک channel می‌فرستد؛ مقدار پیش‌فرض `channel` برابر `last` است. -- `model` برای این اجرای hook، LLM را override می‌کند (اگر model catalog تنظیم شده باشد، باید مجاز باشد). + - `transform.module` باید یک مسیر نسبی باشد و داخل `hooks.transformsDir` بماند (مسیرهای مطلق و پیمایش مسیر رد می‌شوند). + - `hooks.transformsDir` را زیر `~/.openclaw/hooks/transforms` نگه دارید؛ دایرکتوری‌های skill فضای کاری رد می‌شوند. اگر `openclaw doctor` این مسیر را نامعتبر گزارش کرد، ماژول transform را به دایرکتوری transforms hooks منتقل کنید یا `hooks.transformsDir` را حذف کنید. +- `agentId` به یک agent مشخص مسیریابی می‌کند؛ شناسه‌های ناشناخته به حالت پیش‌فرض برمی‌گردند. +- `allowedAgentIds`: مسیریابی صریح را محدود می‌کند (`*` یا حذف‌شده = اجازه به همه، `[]` = رد همه). +- `defaultSessionKey`: کلید نشست ثابت اختیاری برای اجرای agent مربوط به hook بدون `sessionKey` صریح. +- `allowRequestSessionKey`: به فراخوان‌های `/hooks/agent` و کلیدهای نشست نگاشت مبتنی بر قالب اجازه می‌دهد `sessionKey` را تنظیم کنند (پیش‌فرض: `false`). +- `allowedSessionKeyPrefixes`: allowlist پیشوند اختیاری برای مقادیر `sessionKey` صریح (درخواست + نگاشت)، مثلاً `["hook:"]`. وقتی هر نگاشت یا preset از `sessionKey` قالبی استفاده کند، الزامی می‌شود. +- `deliver: true` پاسخ نهایی را به یک کانال می‌فرستد؛ مقدار پیش‌فرض `channel` برابر `last` است. +- `model` برای این اجرای hook، LLM را بازنویسی می‌کند (اگر کاتالوگ مدل تنظیم شده باشد، باید مجاز باشد). ### یکپارچه‌سازی Gmail - preset داخلی Gmail از `sessionKey: "hook:gmail:{{messages[0].id}}"` استفاده می‌کند. -- اگر این route کردن به‌ازای هر پیام را نگه می‌دارید، `hooks.allowRequestSessionKey: true` را تنظیم کنید و `hooks.allowedSessionKeyPrefixes` را به namespace مربوط به Gmail محدود کنید، برای مثال `["hook:", "hook:gmail:"]`. -- اگر به `hooks.allowRequestSessionKey: false` نیاز دارید، preset را با یک `sessionKey` ایستا به‌جای پیش‌فرض قالب‌دار override کنید. +- اگر آن مسیریابی به‌ازای هر پیام را نگه می‌دارید، `hooks.allowRequestSessionKey: true` را تنظیم کنید و `hooks.allowedSessionKeyPrefixes` را طوری محدود کنید که با فضای نام Gmail مطابقت داشته باشد، برای مثال `["hook:", "hook:gmail:"]`. +- اگر به `hooks.allowRequestSessionKey: false` نیاز دارید، preset را به‌جای مقدار پیش‌فرض قالبی، با یک `sessionKey` ایستا بازنویسی کنید. ```json5 { @@ -646,8 +656,8 @@ openclaw gateway --port 19001 } ``` -- Gateway هنگام boot، وقتی پیکربندی شده باشد، `gog gmail watch serve` را به‌صورت خودکار شروع می‌کند. برای غیرفعال کردن، `OPENCLAW_SKIP_GMAIL_WATCHER=1` را تنظیم کنید. -- یک `gog gmail watch serve` جداگانه را در کنار Gateway اجرا نکنید. +- Gateway هنگام راه‌اندازی، در صورت پیکربندی، `gog gmail watch serve` را به‌طور خودکار شروع می‌کند. برای غیرفعال‌سازی، `OPENCLAW_SKIP_GMAIL_WATCHER=1` را تنظیم کنید. +- یک `gog gmail watch serve` جداگانه را هم‌زمان با Gateway اجرا نکنید. --- @@ -663,17 +673,17 @@ openclaw gateway --port 19001 } ``` -- HTML/CSS/JS قابل ویرایش توسط agent و A2UI را روی HTTP زیر پورت Gateway سرو می‌کند: +- HTML/CSS/JS قابل ویرایش توسط agent و A2UI را از طریق HTTP زیر پورت Gateway سرو می‌کند: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - فقط محلی: `gateway.bind: "loopback"` را نگه دارید (پیش‌فرض). -- bindهای غیر loopback: مسیرهای canvas مانند سایر سطوح HTTP مربوط به Gateway به احراز هویت Gateway نیاز دارند (token/password/trusted-proxy). -- WebViewهای Node معمولاً headerهای احراز هویت نمی‌فرستند؛ پس از pair و connected شدن یک node، Gateway برای دسترسی canvas/A2UI، URLهای capability محدود به node را تبلیغ می‌کند. -- URLهای capability به session فعال WS مربوط به node متصل‌اند و سریع منقضی می‌شوند. fallback مبتنی بر IP استفاده نمی‌شود. -- کلاینت live-reload را به HTML سرو‌شده تزریق می‌کند. +- bindهای غیر loopback: مسیرهای canvas به احراز هویت Gateway نیاز دارند (توکن/رمز عبور/trusted-proxy)، همانند دیگر سطح‌های HTTP Gateway. +- WebViewهای Node معمولاً هدرهای احراز هویت نمی‌فرستند؛ پس از pair و وصل شدن یک node، Gateway برای دسترسی canvas/A2UI، URLهای قابلیت با دامنهٔ node را اعلام می‌کند. +- URLهای قابلیت به نشست WS فعال node متصل‌اند و سریع منقضی می‌شوند. fallback مبتنی بر IP استفاده نمی‌شود. +- کلاینت live-reload را در HTML سرو شده تزریق می‌کند. - وقتی خالی باشد، `index.html` آغازین را خودکار ایجاد می‌کند. - همچنین A2UI را در `/__openclaw__/a2ui/` سرو می‌کند. -- تغییرات به restart کردن gateway نیاز دارند. +- تغییرات به راه‌اندازی مجدد gateway نیاز دارند. - برای دایرکتوری‌های بزرگ یا خطاهای `EMFILE`، live reload را غیرفعال کنید. --- @@ -693,12 +703,12 @@ openclaw gateway --port 19001 ``` - `minimal` (پیش‌فرض وقتی Plugin بسته‌بندی‌شدهٔ `bonjour` فعال باشد): `cliPath` + `sshPort` را از رکوردهای TXT حذف می‌کند. -- `full`: `cliPath` + `sshPort` را شامل می‌شود؛ تبلیغ multicast در LAN همچنان نیاز دارد Plugin بسته‌بندی‌شدهٔ `bonjour` فعال باشد. +- `full`: `cliPath` + `sshPort` را شامل می‌کند؛ تبلیغ multicast در LAN همچنان نیاز دارد Plugin بسته‌بندی‌شدهٔ `bonjour` فعال باشد. - `off`: تبلیغ multicast در LAN را بدون تغییر فعال‌بودن Plugin سرکوب می‌کند. -- Plugin بسته‌بندی‌شدهٔ `bonjour` روی میزبان‌های macOS خودکار شروع می‌شود و روی Linux، Windows، و استقرارهای Gateway کانتینری opt-in است. -- نام میزبان وقتی یک برچسب DNS معتبر باشد، به‌صورت پیش‌فرض همان نام میزبان سیستم است و در غیر این صورت به `openclaw` fallback می‌کند. با `OPENCLAW_MDNS_HOSTNAME` override کنید. +- Plugin بسته‌بندی‌شدهٔ `bonjour` روی میزبان‌های macOS به‌طور خودکار شروع می‌شود و روی Linux، Windows، و استقرارهای Gateway کانتینری‌شده opt-in است. +- نام میزبان وقتی یک برچسب DNS معتبر باشد، به‌طور پیش‌فرض برابر نام میزبان سیستم است و در غیر این صورت به `openclaw` برمی‌گردد. با `OPENCLAW_MDNS_HOSTNAME` بازنویسی کنید. -### Wide-area (DNS-SD) +### ناحیهٔ گسترده (DNS-SD) ```json5 { @@ -708,7 +718,7 @@ openclaw gateway --port 19001 } ``` -یک zone مربوط به unicast DNS-SD را زیر `~/.openclaw/dns/` می‌نویسد. برای کشف cross-network، آن را با یک سرور DNS (CoreDNS توصیه می‌شود) + split DNS در Tailscale همراه کنید. +یک zone تک‌پخشی DNS-SD زیر `~/.openclaw/dns/` می‌نویسد. برای کشف بین شبکه‌ها، آن را با یک سرور DNS (CoreDNS توصیه می‌شود) + split DNS در Tailscale همراه کنید. راه‌اندازی: `openclaw dns setup --apply`. @@ -733,10 +743,10 @@ openclaw gateway --port 19001 } ``` -- متغیرهای محیطی درون‌خطی فقط زمانی اعمال می‌شوند که محیط فرایند آن کلید را نداشته باشد. -- فایل‌های `.env`: فایل `.env` در CWD + فایل `~/.openclaw/.env` (هیچ‌کدام متغیرهای موجود را بازنویسی نمی‌کنند). -- `shellEnv`: کلیدهای مورد انتظارِ موجودنبودن را از پروفایل پوسته ورود شما وارد می‌کند. -- برای تقدم کامل، [محیط](/fa/help/environment) را ببینید. +- متغیرهای محیطی درون‌خطی فقط زمانی اعمال می‌شوند که کلید در محیط فرایند وجود نداشته باشد. +- فایل‌های `.env`: فایل `.env` در دایرکتوری کاری جاری + `~/.openclaw/.env` (هیچ‌کدام متغیرهای موجود را بازنویسی نمی‌کنند). +- `shellEnv`: کلیدهای موردانتظارِ ناموجود را از پروفایل پوسته ورود شما وارد می‌کند. +- برای ترتیب تقدم کامل، [محیط](/fa/help/environment) را ببینید. ### جایگزینی متغیر محیطی @@ -751,15 +761,15 @@ openclaw gateway --port 19001 ``` - فقط نام‌های حروف بزرگ مطابق می‌شوند: `[A-Z_][A-Z0-9_]*`. -- متغیرهای موجودنبودن/خالی هنگام بارگذاری پیکربندی خطا ایجاد می‌کنند. -- برای مقدار تحت‌اللفظی `${VAR}` با `$${VAR}` فرار دهید. +- متغیرهای ناموجود/خالی هنگام بارگذاری پیکربندی خطا می‌دهند. +- برای مقدار لفظی `${VAR}` با `$${VAR}` escape کنید. - با `$include` کار می‌کند. --- -## اسرار +## رازها -ارجاع‌های راز افزایشی هستند: مقادیر متن ساده همچنان کار می‌کنند. +ارجاع‌های راز افزایشی‌اند: مقادیر متن ساده همچنان کار می‌کنند. ### `SecretRef` @@ -772,16 +782,16 @@ openclaw gateway --port 19001 اعتبارسنجی: - الگوی `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- الگوی شناسه `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- شناسه `source: "file"`: اشاره‌گر مطلق JSON (برای مثال `"/providers/openai/apiKey"`) -- الگوی شناسه `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- شناسه‌های `source: "exec"` نباید شامل بخش‌های مسیر جداشده با اسلش `.` یا `..` باشند (برای مثال `a/../b` رد می‌شود) +- الگوی id برای `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id برای `source: "file"`: اشاره‌گر JSON مطلق (برای نمونه `"/providers/openai/apiKey"`) +- الگوی id برای `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- idهای `source: "exec"` نباید شامل بخش‌های مسیر جداشده با اسلشِ `.` یا `..` باشند (برای نمونه `a/../b` رد می‌شود) ### سطح اعتبارنامه پشتیبانی‌شده - ماتریس مرجع: [سطح اعتبارنامه SecretRef](/fa/reference/secretref-credential-surface) - هدف‌های `secrets apply` مسیرهای اعتبارنامه پشتیبانی‌شده `openclaw.json` هستند. -- ارجاع‌های `auth-profiles.json` در حل‌وفصل زمان اجرا و پوشش حسابرسی گنجانده شده‌اند. +- ارجاع‌های `auth-profiles.json` در پوشش حل‌وفصل زمان اجرا و ممیزی گنجانده شده‌اند. ### پیکربندی ارائه‌دهندگان راز @@ -814,13 +824,13 @@ openclaw gateway --port 19001 نکته‌ها: - ارائه‌دهنده `file` از `mode: "json"` و `mode: "singleValue"` پشتیبانی می‌کند (`id` در حالت singleValue باید `"value"` باشد). -- مسیرهای ارائه‌دهنده فایل و exec وقتی راستی‌آزمایی ACL در Windows در دسترس نباشد بسته شکست می‌خورند. `allowInsecurePath: true` را فقط برای مسیرهای مورد اعتمادی تنظیم کنید که قابل راستی‌آزمایی نیستند. +- وقتی اعتبارسنجی ACL ویندوز در دسترس نباشد، مسیرهای ارائه‌دهنده فایل و exec به‌صورت بسته شکست می‌خورند. `allowInsecurePath: true` را فقط برای مسیرهای قابل‌اعتمادی تنظیم کنید که قابل اعتبارسنجی نیستند. - ارائه‌دهنده `exec` به مسیر مطلق `command` نیاز دارد و از payloadهای پروتکل روی stdin/stdout استفاده می‌کند. -- به‌صورت پیش‌فرض، مسیرهای فرمان symlink رد می‌شوند. برای مجازکردن مسیرهای symlink همراه با اعتبارسنجی مسیر هدف حل‌شده، `allowSymlinkCommand: true` را تنظیم کنید. -- اگر `trustedDirs` پیکربندی شده باشد، بررسی دایرکتوری مورد اعتماد روی مسیر هدف حل‌شده اعمال می‌شود. -- محیط فرزند `exec` به‌صورت پیش‌فرض حداقلی است؛ متغیرهای لازم را صریحا با `passEnv` عبور دهید. +- به‌طور پیش‌فرض، مسیرهای فرمان symlink رد می‌شوند. برای مجاز کردن مسیرهای symlink همراه با اعتبارسنجی مسیر هدف حل‌شده، `allowSymlinkCommand: true` را تنظیم کنید. +- اگر `trustedDirs` پیکربندی شده باشد، بررسی دایرکتوری مورداعتماد روی مسیر هدف حل‌شده اعمال می‌شود. +- محیط فرزند `exec` به‌طور پیش‌فرض حداقلی است؛ متغیرهای لازم را صراحتا با `passEnv` پاس بدهید. - ارجاع‌های راز در زمان فعال‌سازی به یک snapshot درون‌حافظه‌ای حل می‌شوند، سپس مسیرهای درخواست فقط snapshot را می‌خوانند. -- فیلترکردن سطح فعال هنگام فعال‌سازی اعمال می‌شود: ارجاع‌های حل‌نشده روی سطح‌های فعال باعث شکست راه‌اندازی/بارگذاری دوباره می‌شوند، در حالی که سطح‌های غیرفعال با تشخیص‌ها نادیده گرفته می‌شوند. +- فیلتر کردن سطح فعال هنگام فعال‌سازی اعمال می‌شود: ارجاع‌های حل‌نشده روی سطح‌های فعال باعث شکست راه‌اندازی/بارگذاری مجدد می‌شوند، درحالی‌که سطح‌های غیرفعال با diagnostics رد می‌شوند. --- @@ -842,14 +852,14 @@ openclaw gateway --port 19001 } ``` -- پروفایل‌های هر عامل در `/auth-profiles.json` ذخیره می‌شوند. +- پروفایل‌های هر agent در `/auth-profiles.json` ذخیره می‌شوند. - `auth-profiles.json` برای حالت‌های اعتبارنامه ایستا از ارجاع‌های سطح مقدار (`keyRef` برای `api_key`، `tokenRef` برای `token`) پشتیبانی می‌کند. - نگاشت‌های مسطح قدیمی `auth-profiles.json` مانند `{ "provider": { "apiKey": "..." } }` قالب زمان اجرا نیستند؛ `openclaw doctor --fix` آن‌ها را با پشتیبان `.legacy-flat.*.bak` به پروفایل‌های API-key مرجع `provider:default` بازنویسی می‌کند. -- پروفایل‌های حالت OAuth (`auth.profiles..mode = "oauth"`) از اعتبارنامه‌های پروفایل احراز هویت پشتیبانی‌شده با SecretRef پشتیبانی نمی‌کنند. -- اعتبارنامه‌های زمان اجرای ایستا از snapshotهای حل‌شده درون‌حافظه‌ای می‌آیند؛ ورودی‌های ایستای قدیمی `auth.json` هنگام کشف پاک‌سازی می‌شوند. +- پروفایل‌های حالت OAuth (`auth.profiles..mode = "oauth"`) از اعتبارنامه‌های auth-profile مبتنی بر SecretRef پشتیبانی نمی‌کنند. +- اعتبارنامه‌های ایستای زمان اجرا از snapshotهای حل‌شده درون‌حافظه‌ای می‌آیند؛ ورودی‌های ایستای قدیمی `auth.json` هنگام کشف پاک‌سازی می‌شوند. - واردسازی‌های OAuth قدیمی از `~/.openclaw/credentials/oauth.json`. - [OAuth](/fa/concepts/oauth) را ببینید. -- رفتار زمان اجرای اسرار و ابزارهای `audit/configure/apply`: [مدیریت اسرار](/fa/gateway/secrets). +- رفتار زمان اجرای رازها و ابزارهای `audit/configure/apply`: [مدیریت رازها](/fa/gateway/secrets). ### `auth.cooldowns` @@ -871,25 +881,26 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: عقب‌گرد پایه بر حسب ساعت، زمانی که یک پروفایل به‌دلیل خطاهای واقعی - صورتحساب/اعتبار ناکافی شکست می‌خورد (پیش‌فرض: `5`). متن صریح صورتحساب حتی در پاسخ‌های `401`/`403` - همچنان می‌تواند اینجا قرار بگیرد، اما تطبیق‌دهنده‌های متنِ ویژه هر ارائه‌دهنده در محدوده همان ارائه‌دهنده‌ای - می‌مانند که مالکشان است (برای مثال OpenRouter - `Key limit exceeded`). پیام‌های HTTP قابل تلاش مجدد `402` مربوط به پنجره مصرف یا - سقف هزینه سازمان/فضای کاری به‌جای آن در مسیر `rate_limit` +- `billingBackoffHours`: وقفهٔ پایه به ساعت وقتی یک پروفایل به‌دلیل خطاهای واقعی + صورت‌حساب/اعتبار ناکافی شکست می‌خورد (پیش‌فرض: `5`). متن صریح مربوط به صورت‌حساب + همچنان می‌تواند حتی در پاسخ‌های `401`/`403` به این مسیر برسد، اما + تطبیق‌دهنده‌های متن ویژهٔ ارائه‌دهنده فقط در محدودهٔ همان ارائه‌دهنده‌ای می‌مانند + که مالک آن‌هاست (برای نمونه OpenRouter + `Key limit exceeded`). پیام‌های قابل‌تلاش‌مجدد HTTP `402` مربوط به پنجرهٔ مصرف یا + سقف هزینهٔ سازمان/فضای کاری در عوض در مسیر `rate_limit` می‌مانند. -- `billingBackoffHoursByProvider`: بازنویسی‌های اختیاری برای هر ارائه‌دهنده برای ساعت‌های عقب‌گرد صورتحساب. -- `billingMaxHours`: سقف بر حسب ساعت برای رشد نمایی عقب‌گرد صورتحساب (پیش‌فرض: `24`). -- `authPermanentBackoffMinutes`: عقب‌گرد پایه بر حسب دقیقه برای شکست‌های با اطمینان بالا از نوع `auth_permanent` (پیش‌فرض: `10`). -- `authPermanentMaxMinutes`: سقف بر حسب دقیقه برای رشد عقب‌گرد `auth_permanent` (پیش‌فرض: `60`). -- `failureWindowHours`: پنجره غلتان بر حسب ساعت که برای شمارنده‌های عقب‌گرد استفاده می‌شود (پیش‌فرض: `24`). -- `overloadedProfileRotations`: حداکثر چرخش‌های پروفایل احراز هویت در همان ارائه‌دهنده برای خطاهای بارگذاری بیش‌ازحد، پیش از تغییر به جایگزین مدل (پیش‌فرض: `1`). شکل‌های مشغول‌بودن ارائه‌دهنده مانند `ModelNotReadyException` اینجا قرار می‌گیرند. -- `overloadedBackoffMs`: تاخیر ثابت پیش از تلاش دوباره برای چرخش ارائه‌دهنده/پروفایلِ بارگذاری‌شده بیش‌ازحد (پیش‌فرض: `0`). -- `rateLimitedProfileRotations`: حداکثر چرخش‌های پروفایل احراز هویت در همان ارائه‌دهنده برای خطاهای محدودیت نرخ، پیش از تغییر به جایگزین مدل (پیش‌فرض: `1`). آن سطل محدودیت نرخ شامل متن‌هایی با شکل ارائه‌دهنده مانند `Too many concurrent requests`، `ThrottlingException`، `concurrency limit reached`، `workers_ai ... quota limit exceeded`، و `resource exhausted` است. +- `billingBackoffHoursByProvider`: بازنویسی‌های اختیاری به‌ازای هر ارائه‌دهنده برای ساعت‌های وقفهٔ صورت‌حساب. +- `billingMaxHours`: سقف ساعت‌ها برای رشد نمایی وقفهٔ صورت‌حساب (پیش‌فرض: `24`). +- `authPermanentBackoffMinutes`: وقفهٔ پایه به دقیقه برای شکست‌های با اطمینان بالا از نوع `auth_permanent` (پیش‌فرض: `10`). +- `authPermanentMaxMinutes`: سقف دقیقه‌ها برای رشد وقفهٔ `auth_permanent` (پیش‌فرض: `60`). +- `failureWindowHours`: پنجرهٔ چرخان به ساعت که برای شمارنده‌های وقفه استفاده می‌شود (پیش‌فرض: `24`). +- `overloadedProfileRotations`: بیشینهٔ چرخش‌های پروفایل احراز هویت در همان ارائه‌دهنده برای خطاهای بارگذاری بیش‌ازحد، پیش از تغییر به مدل جایگزین (پیش‌فرض: `1`). شکل‌های مشغول‌بودن ارائه‌دهنده مانند `ModelNotReadyException` به اینجا می‌رسند. +- `overloadedBackoffMs`: تأخیر ثابت پیش از تلاش دوباره برای چرخش ارائه‌دهنده/پروفایل بارگذاری‌شدهٔ بیش‌ازحد (پیش‌فرض: `0`). +- `rateLimitedProfileRotations`: بیشینهٔ چرخش‌های پروفایل احراز هویت در همان ارائه‌دهنده برای خطاهای محدودیت نرخ، پیش از تغییر به مدل جایگزین (پیش‌فرض: `1`). آن سبد محدودیت نرخ شامل متن‌های شکل‌داده‌شده توسط ارائه‌دهنده مانند `Too many concurrent requests`، `ThrottlingException`، `concurrency limit reached`، `workers_ai ... quota limit exceeded`، و `resource exhausted` است. --- -## ثبت وقایع +## ثبت گزارش ```json5 { @@ -904,11 +915,11 @@ openclaw gateway --port 19001 } ``` -- فایل پیش‌فرض ثبت وقایع: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- فایل گزارش پیش‌فرض: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - برای یک مسیر پایدار، `logging.file` را تنظیم کنید. -- هنگام استفاده از `--verbose`، مقدار `consoleLevel` به `debug` افزایش می‌یابد. -- `maxFileBytes`: حداکثر اندازه فایل ثبت وقایع فعال بر حسب بایت پیش از چرخش (عدد صحیح مثبت؛ پیش‌فرض: `104857600` = 100 مگابایت). OpenClaw تا پنج آرشیو شماره‌گذاری‌شده را کنار فایل فعال نگه می‌دارد. -- `redactSensitive` / `redactPatterns`: پوشاندن با بهترین تلاش برای خروجی کنسول، فایل‌های ثبت وقایع، رکوردهای ثبت وقایع OTLP، و متن رونوشت نشست‌های ذخیره‌شده. `redactSensitive: "off"` فقط این سیاست عمومی ثبت وقایع/رونوشت را غیرفعال می‌کند؛ سطوح ایمنی UI/ابزار/تشخیصی همچنان پیش از انتشار، رازها را می‌پوشانند. +- وقتی `--verbose` باشد، `consoleLevel` به `debug` افزایش می‌یابد. +- `maxFileBytes`: بیشینهٔ اندازهٔ فایل گزارش فعال به بایت پیش از چرخش (عدد صحیح مثبت؛ پیش‌فرض: `104857600` = 100 مگابایت). OpenClaw تا پنج بایگانی شماره‌گذاری‌شده را کنار فایل فعال نگه می‌دارد. +- `redactSensitive` / `redactPatterns`: پوشاندن با بهترین تلاش برای خروجی کنسول، گزارش‌های فایل، رکوردهای گزارش OTLP، و متن رونوشت نشست ذخیره‌شده. `redactSensitive: "off"` فقط این سیاست عمومی گزارش/رونوشت را غیرفعال می‌کند؛ سطح‌های ایمنی UI/ابزار/عیب‌یابی همچنان رازها را پیش از انتشار می‌پوشانند. --- @@ -957,24 +968,24 @@ openclaw gateway --port 19001 ``` - `enabled`: کلید اصلی برای خروجی ابزاربندی (پیش‌فرض: `true`). -- `flags`: آرایه‌ای از رشته‌های پرچم که خروجی ثبت وقایع هدفمند را فعال می‌کند (از wildcardهایی مانند `"telegram.*"` یا `"*"` پشتیبانی می‌کند). -- `stuckSessionWarnMs`: آستانه سنِ بدون پیشرفت بر حسب میلی‌ثانیه برای دسته‌بندی نشست‌های پردازش طولانی‌مدت به‌عنوان `session.long_running`، `session.stalled`، یا `session.stuck`. پاسخ، ابزار، وضعیت، بلوک، و پیشرفت ACP زمان‌سنج را بازنشانی می‌کنند؛ عیب‌یابی‌های تکراری `session.stuck` تا زمانی که تغییری رخ ندهد عقب‌گرد می‌کنند. -- `otel.enabled`: خط لوله صدور OpenTelemetry را فعال می‌کند (پیش‌فرض: `false`). برای پیکربندی کامل، کاتالوگ سیگنال، و مدل حریم خصوصی، [صدور OpenTelemetry](/fa/gateway/opentelemetry) را ببینید. +- `flags`: آرایه‌ای از رشته‌های پرچم که خروجی گزارش هدفمند را فعال می‌کنند (از wildcardهایی مانند `"telegram.*"` یا `"*"` پشتیبانی می‌کند). +- `stuckSessionWarnMs`: آستانهٔ سن بدون پیشرفت به میلی‌ثانیه برای طبقه‌بندی نشست‌های پردازشی طولانی‌مدت به‌عنوان `session.long_running`، `session.stalled`، یا `session.stuck`. پاسخ، ابزار، وضعیت، بلوک، و پیشرفت ACP زمان‌سنج را بازنشانی می‌کنند؛ عیب‌یابی‌های تکراری `session.stuck` تا وقتی تغییری رخ نداده باشد با وقفهٔ افزایشی انجام می‌شوند. +- `otel.enabled`: خط لولهٔ صدور OpenTelemetry را فعال می‌کند (پیش‌فرض: `false`). برای پیکربندی کامل، فهرست سیگنال‌ها، و مدل حریم خصوصی، [صدور OpenTelemetry](/fa/gateway/opentelemetry) را ببینید. - `otel.endpoint`: URL گردآورنده برای صدور OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: endpointهای اختیاری OTLP ویژه سیگنال. وقتی تنظیم شوند، فقط برای همان سیگنال `otel.endpoint` را بازنویسی می‌کنند. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: نقطه‌های پایانی اختیاری OTLP ویژهٔ هر سیگنال. وقتی تنظیم شوند، فقط برای همان سیگنال `otel.endpoint` را بازنویسی می‌کنند. - `otel.protocol`: `"http/protobuf"` (پیش‌فرض) یا `"grpc"`. -- `otel.headers`: سرآیندهای فراداده HTTP/gRPC اضافی که همراه با درخواست‌های صدور OTel فرستاده می‌شوند. +- `otel.headers`: سرآیندهای فرادادهٔ اضافی HTTP/gRPC که همراه درخواست‌های صدور OTel فرستاده می‌شوند. - `otel.serviceName`: نام سرویس برای ویژگی‌های منبع. -- `otel.traces` / `otel.metrics` / `otel.logs`: صدور trace، metrics، یا log را فعال می‌کند. -- `otel.sampleRate`: نرخ نمونه‌برداری trace از `0` تا `1`. -- `otel.flushIntervalMs`: بازه flush دوره‌ای تله‌متری بر حسب میلی‌ثانیه. -- `otel.captureContent`: ضبط محتوای خام به‌صورت opt-in برای ویژگی‌های span در OTEL. به‌صورت پیش‌فرض خاموش است. مقدار بولی `true` محتوای پیام/ابزار غیرسیستمی را ضبط می‌کند؛ شکل شیء به شما اجازه می‌دهد `inputMessages`، `outputMessages`، `toolInputs`، `toolOutputs`، و `systemPrompt` را صراحتا فعال کنید. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: کلید محیطی برای تازه‌ترین ویژگی‌های آزمایشی ارائه‌دهنده span در GenAI. به‌صورت پیش‌فرض، spanها برای سازگاری ویژگی قدیمی `gen_ai.system` را نگه می‌دارند؛ metrics مربوط به GenAI از ویژگی‌های معنایی کران‌دار استفاده می‌کنند. -- `OPENCLAW_OTEL_PRELOADED=1`: کلید محیطی برای میزبان‌هایی که از پیش یک SDK سراسری OpenTelemetry ثبت کرده‌اند. در این حالت OpenClaw راه‌اندازی/خاموش‌سازی SDK متعلق به Plugin را نادیده می‌گیرد، در حالی که شنونده‌های عیب‌یابی را فعال نگه می‌دارد. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`، `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`، و `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: متغیرهای محیطی endpoint ویژه سیگنال که وقتی کلید پیکربندی متناظر تنظیم نشده باشد استفاده می‌شوند. -- `cacheTrace.enabled`: snapshotهای ردگیری cache را برای اجراهای embedded ثبت می‌کند (پیش‌فرض: `false`). -- `cacheTrace.filePath`: مسیر خروجی برای JSONL ردگیری cache (پیش‌فرض: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: کنترل می‌کند چه چیزی در خروجی ردگیری cache گنجانده شود (همه به‌صورت پیش‌فرض: `true`). +- `otel.traces` / `otel.metrics` / `otel.logs`: صدور ردگیری، سنجه‌ها، یا گزارش را فعال می‌کند. +- `otel.sampleRate`: نرخ نمونه‌برداری ردگیری `0`–`1`. +- `otel.flushIntervalMs`: بازهٔ تخلیهٔ دوره‌ای دورسنجی به میلی‌ثانیه. +- `otel.captureContent`: دریافت محتوای خام به‌صورت اختیاری برای ویژگی‌های span در OTEL. پیش‌فرض خاموش است. مقدار بولی `true` محتوای پیام/ابزار غیرسیستمی را دریافت می‌کند؛ شکل شیء به شما اجازه می‌دهد `inputMessages`، `outputMessages`، `toolInputs`، `toolOutputs`، و `systemPrompt` را صریحاً فعال کنید. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: کلید محیطی برای تازه‌ترین ویژگی‌های آزمایشی ارائه‌دهندهٔ span مربوط به GenAI. به‌طور پیش‌فرض spanها برای سازگاری ویژگی قدیمی `gen_ai.system` را نگه می‌دارند؛ سنجه‌های GenAI از ویژگی‌های معنایی کران‌دار استفاده می‌کنند. +- `OPENCLAW_OTEL_PRELOADED=1`: کلید محیطی برای میزبان‌هایی که از پیش یک SDK سراسری OpenTelemetry را ثبت کرده‌اند. سپس OpenClaw راه‌اندازی/خاموش‌سازی SDK متعلق به Plugin را رد می‌کند و شنونده‌های عیب‌یابی را فعال نگه می‌دارد. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`، `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`، و `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: متغیرهای محیطی نقطهٔ پایانی ویژهٔ سیگنال که وقتی کلید پیکربندی متناظر تنظیم نشده باشد استفاده می‌شوند. +- `cacheTrace.enabled`: ثبت عکس‌های لحظه‌ای ردگیری کش برای اجراهای جاسازی‌شده (پیش‌فرض: `false`). +- `cacheTrace.filePath`: مسیر خروجی برای JSONL ردگیری کش (پیش‌فرض: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: کنترل می‌کند چه چیزهایی در خروجی ردگیری کش گنجانده شود (همه به‌طور پیش‌فرض: `true`). --- @@ -999,9 +1010,9 @@ openclaw gateway --port 19001 - `channel`: کانال انتشار برای نصب‌های npm/git — `"stable"`، `"beta"`، یا `"dev"`. - `checkOnStart`: هنگام شروع Gateway، به‌روزرسانی‌های npm را بررسی می‌کند (پیش‌فرض: `true`). - `auto.enabled`: به‌روزرسانی خودکار پس‌زمینه را برای نصب‌های بسته فعال می‌کند (پیش‌فرض: `false`). -- `auto.stableDelayHours`: حداقل تاخیر بر حسب ساعت پیش از اعمال خودکار در کانال پایدار (پیش‌فرض: `6`؛ حداکثر: `168`). -- `auto.stableJitterHours`: پنجره پخش rollout اضافی برای کانال پایدار بر حسب ساعت (پیش‌فرض: `12`؛ حداکثر: `168`). -- `auto.betaCheckIntervalHours`: فاصله زمانی اجرای بررسی‌های کانال beta بر حسب ساعت (پیش‌فرض: `1`؛ حداکثر: `24`). +- `auto.stableDelayHours`: کمینهٔ تأخیر به ساعت پیش از اعمال خودکار در کانال پایدار (پیش‌فرض: `6`؛ بیشینه: `168`). +- `auto.stableJitterHours`: پنجرهٔ پخش انتشار اضافی کانال پایدار به ساعت (پیش‌فرض: `12`؛ بیشینه: `168`). +- `auto.betaCheckIntervalHours`: اینکه بررسی‌های کانال بتا هر چند ساعت اجرا شوند (پیش‌فرض: `1`؛ بیشینه: `24`). --- @@ -1034,23 +1045,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`: دروازه سراسری قابلیت ACP (پیش‌فرض: `true`؛ برای پنهان‌کردن dispatch و امکان‌های spawn در ACP، آن را روی `false` تنظیم کنید). -- `dispatch.enabled`: دروازه مستقل برای dispatch نوبت نشست ACP (پیش‌فرض: `true`). آن را روی `false` تنظیم کنید تا فرمان‌های ACP در دسترس بمانند اما اجرا مسدود شود. -- `backend`: شناسه backend پیش‌فرض runtime برای ACP (باید با یک runtime Plugin ثبت‌شده برای ACP مطابق باشد). - ابتدا Plugin مربوط به backend را نصب کنید، و اگر `plugins.allow` تنظیم شده است، شناسه Plugin مربوط به backend را وارد کنید (برای مثال `acpx`) وگرنه backend مربوط به ACP بارگذاری نخواهد شد. -- `defaultAgent`: شناسه عامل هدف جایگزین ACP زمانی که spawnها هدف صریحی مشخص نمی‌کنند. -- `allowedAgents`: allowlist شناسه‌های عامل مجاز برای نشست‌های runtime در ACP؛ خالی بودن یعنی هیچ محدودیت اضافی وجود ندارد. -- `maxConcurrentSessions`: حداکثر نشست‌های ACP فعال هم‌زمان. -- `stream.coalesceIdleMs`: پنجره flush بیکار بر حسب میلی‌ثانیه برای متن streamed. -- `stream.maxChunkChars`: حداکثر اندازه chunk پیش از تقسیم projection بلوک streamed. -- `stream.repeatSuppression`: خطوط وضعیت/ابزار تکراری را در هر نوبت سرکوب می‌کند (پیش‌فرض: `true`). -- `stream.deliveryMode`: `"live"` به‌صورت افزایشی stream می‌کند؛ `"final_only"` تا رویدادهای پایانی نوبت buffer می‌کند. -- `stream.hiddenBoundarySeparator`: جداکننده پیش از متن قابل مشاهده پس از رویدادهای ابزار پنهان (پیش‌فرض: `"paragraph"`). -- `stream.maxOutputChars`: حداکثر کاراکترهای خروجی دستیار که در هر نوبت ACP project می‌شوند. -- `stream.maxSessionUpdateChars`: حداکثر کاراکترها برای خطوط وضعیت/به‌روزرسانی ACP که project می‌شوند. -- `stream.tagVisibility`: رکوردی از نام tagها به بازنویسی‌های نمایانی بولی برای رویدادهای streamed. -- `runtime.ttlMinutes`: TTL بیکار بر حسب دقیقه برای workerهای نشست ACP پیش از واجد شرایط شدن برای پاک‌سازی. -- `runtime.installCommand`: فرمان نصب اختیاری برای اجرا هنگام bootstrap کردن محیط runtime در ACP. +- `enabled`: دروازهٔ قابلیت سراسری ACP (پیش‌فرض: `true`؛ برای پنهان‌کردن ارسال و امکانات ایجاد ACP، روی `false` تنظیم کنید). +- `dispatch.enabled`: دروازهٔ مستقل برای ارسال نوبت نشست ACP (پیش‌فرض: `true`). برای در دسترس نگه‌داشتن فرمان‌های ACP در حالی که اجرا مسدود می‌شود، روی `false` تنظیم کنید. +- `backend`: شناسهٔ پیش‌فرض backend زمان اجرای ACP (باید با یک Plugin زمان اجرای ACP ثبت‌شده مطابقت داشته باشد). + ابتدا Plugin backend را نصب کنید، و اگر `plugins.allow` تنظیم شده است، شناسهٔ Plugin backend را نیز اضافه کنید (برای نمونه `acpx`) وگرنه backend ACP بارگذاری نمی‌شود. +- `defaultAgent`: شناسهٔ عامل هدف جایگزین ACP وقتی ایجادها هدف صریحی مشخص نمی‌کنند. +- `allowedAgents`: فهرست مجاز شناسه‌های عامل که برای نشست‌های زمان اجرای ACP مجازند؛ خالی یعنی محدودیت اضافی وجود ندارد. +- `maxConcurrentSessions`: بیشینهٔ نشست‌های ACP فعال هم‌زمان. +- `stream.coalesceIdleMs`: پنجرهٔ تخلیهٔ بیکار به میلی‌ثانیه برای متن جریانی. +- `stream.maxChunkChars`: بیشینهٔ اندازهٔ قطعه پیش از تقسیم نمایش بلوک جریانی. +- `stream.repeatSuppression`: خط‌های وضعیت/ابزار تکراری را در هر نوبت سرکوب می‌کند (پیش‌فرض: `true`). +- `stream.deliveryMode`: `"live"` به‌صورت افزایشی جریان می‌دهد؛ `"final_only"` تا رخدادهای پایانی نوبت بافر می‌کند. +- `stream.hiddenBoundarySeparator`: جداکننده پیش از متن قابل‌مشاهده پس از رخدادهای ابزار پنهان (پیش‌فرض: `"paragraph"`). +- `stream.maxOutputChars`: بیشینهٔ نویسه‌های خروجی دستیار که در هر نوبت ACP نمایش داده می‌شود. +- `stream.maxSessionUpdateChars`: بیشینهٔ نویسه‌ها برای خط‌های وضعیت/به‌روزرسانی ACP نمایش‌داده‌شده. +- `stream.tagVisibility`: رکورد نام‌های برچسب به بازنویسی‌های نمایانی بولی برای رخدادهای جریانی. +- `runtime.ttlMinutes`: TTL بیکار به دقیقه برای workerهای نشست ACP پیش از واجدشرایط‌شدن برای پاک‌سازی. +- `runtime.installCommand`: فرمان نصب اختیاری برای اجرا هنگام بوت‌استرپ‌کردن محیط زمان اجرای ACP. --- @@ -1066,17 +1077,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` سبک tagline بنر را کنترل می‌کند: - - `"random"` (پیش‌فرض): taglineهای چرخشی طنز/فصلی. - - `"default"`: tagline ثابت و خنثی (`All your chats, one OpenClaw.`). - - `"off"`: بدون متن tagline (عنوان/نسخه بنر همچنان نشان داده می‌شود). -- برای پنهان‌کردن کل بنر (نه فقط taglineها)، env `OPENCLAW_HIDE_BANNER=1` را تنظیم کنید. +- `cli.banner.taglineMode` سبک شعار بنر را کنترل می‌کند: + - `"random"` (پیش‌فرض): شعارهای چرخشی بامزه/فصلی. + - `"default"`: شعار ثابت و خنثی (`All your chats, one OpenClaw.`). + - `"off"`: بدون متن شعار (عنوان/نسخهٔ بنر همچنان نشان داده می‌شود). +- برای پنهان‌کردن کل بنر (نه فقط شعارها)، env `OPENCLAW_HIDE_BANNER=1` را تنظیم کنید. --- -## راهنمای تنظیم +## راهنما -فراداده‌ای که توسط جریان‌های تنظیم هدایت‌شده CLI نوشته می‌شود (`onboard`، `configure`، `doctor`): +فراداده‌ای که توسط جریان‌های راه‌اندازی هدایت‌شدهٔ CLI (`onboard`، `configure`، `doctor`) نوشته می‌شود: ```json5 { @@ -1094,15 +1105,15 @@ openclaw gateway --port 19001 ## هویت -فیلدهای هویت `agents.list` را در [پیش‌فرض‌های عامل](/fa/gateway/config-agents#agent-defaults) ببینید. +فیلدهای هویت `agents.list` را زیر [پیش‌فرض‌های عامل](/fa/gateway/config-agents#agent-defaults) ببینید. --- -## پل (میراثی، حذف‌شده) +## پل (قدیمی، حذف‌شده) -buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها از طریق WebSocket مربوط به Gateway متصل می‌شوند. کلیدهای `bridge.*` دیگر بخشی از schema پیکربندی نیستند (اعتبارسنجی تا زمان حذف آن‌ها شکست می‌خورد؛ `openclaw doctor --fix` می‌تواند کلیدهای ناشناخته را حذف کند). +بیلدهای فعلی دیگر شامل پل TCP نیستند. Nodeها از طریق WebSocket در Gateway متصل می‌شوند. کلیدهای `bridge.*` دیگر بخشی از طرح‌وارهٔ پیکربندی نیستند (اعتبارسنجی تا زمان حذفشان شکست می‌خورد؛ `openclaw doctor --fix` می‌تواند کلیدهای ناشناخته را حذف کند). - + ```json { @@ -1140,11 +1151,11 @@ buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها } ``` -- `sessionRetention`: مدت‌زمان نگه‌داری نشست‌های اجرای Cron ایزوله تکمیل‌شده پیش از هرس از `sessions.json`. همچنین پاک‌سازی رونوشت‌های Cron حذف‌شده آرشیوشده را کنترل می‌کند. پیش‌فرض: `24h`؛ برای غیرفعال‌سازی روی `false` تنظیم کنید. -- `runLog.maxBytes`: حداکثر اندازه برای هر فایل ثبت اجرای (`cron/runs/.jsonl`) پیش از هرس. پیش‌فرض: `2_000_000` بایت. -- `runLog.keepLines`: جدیدترین خط‌هایی که هنگام فعال شدن هرس run-log نگه داشته می‌شوند. پیش‌فرض: `2000`. -- `webhookToken`: توکن bearer که برای تحویل POST مربوط به Webhook در Cron استفاده می‌شود (`delivery.mode = "webhook"`)، اگر حذف شود هیچ سرآیند احراز هویتی فرستاده نمی‌شود. -- `webhook`: URL میراثی منسوخ fallback برای Webhook (http/https) که فقط برای jobهای ذخیره‌شده‌ای استفاده می‌شود که هنوز `notify: true` دارند. +- `sessionRetention`: مدت نگهداری نشست‌های اجرای Cron ایزولهٔ تکمیل‌شده پیش از هرس از `sessions.json`. همچنین پاک‌سازی رونوشت‌های Cron حذف‌شدهٔ بایگانی‌شده را کنترل می‌کند. پیش‌فرض: `24h`؛ برای غیرفعال‌کردن روی `false` تنظیم کنید. +- `runLog.maxBytes`: بیشینهٔ اندازه برای هر فایل گزارش اجرا (`cron/runs/.jsonl`) پیش از هرس. پیش‌فرض: `2_000_000` بایت. +- `runLog.keepLines`: تازه‌ترین خط‌هایی که هنگام فعال‌شدن هرس گزارش اجرا نگه داشته می‌شوند. پیش‌فرض: `2000`. +- `webhookToken`: توکن حامل که برای تحویل POST Webhook مربوط به Cron استفاده می‌شود (`delivery.mode = "webhook"`)، اگر حذف شود هیچ سرآیند احرازی فرستاده نمی‌شود. +- `webhook`: URL Webhook جایگزین قدیمی منسوخ‌شده (http/https) که فقط برای کارهای ذخیره‌شده‌ای استفاده می‌شود که هنوز `notify: true` دارند. ### `cron.retry` @@ -1160,9 +1171,9 @@ buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها } ``` -- `maxAttempts`: بیشینه تعداد تلاش‌های دوباره برای کارهای یک‌باره در خطاهای گذرا (پیش‌فرض: `3`؛ بازه: `0`–`10`). -- `backoffMs`: آرایه‌ای از تأخیرهای backoff بر حسب ms برای هر تلاش دوباره (پیش‌فرض: `[30000, 60000, 300000]`؛ 1–10 ورودی). -- `retryOn`: انواع خطایی که تلاش دوباره را فعال می‌کنند — `"rate_limit"`، `"overloaded"`، `"network"`، `"timeout"`، `"server_error"`. برای تلاش دوباره روی همه انواع گذرا، آن را حذف کنید. +- `maxAttempts`: حداکثر تلاش‌های مجدد برای کارهای یک‌باره در خطاهای گذرا (پیش‌فرض: `3`؛ بازه: `0` تا `10`). +- `backoffMs`: آرایه‌ای از تاخیرهای backoff بر حسب ms برای هر تلاش مجدد (پیش‌فرض: `[30000, 60000, 300000]`؛ ۱ تا ۱۰ ورودی). +- `retryOn`: انواع خطایی که تلاش مجدد را فعال می‌کنند — `"rate_limit"`، `"overloaded"`، `"network"`، `"timeout"`، `"server_error"`. برای تلاش مجدد روی همه انواع گذرا، آن را حذف کنید. فقط برای کارهای Cron یک‌باره اعمال می‌شود. کارهای تکرارشونده از رسیدگی جداگانه به شکست استفاده می‌کنند. @@ -1183,12 +1194,12 @@ buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها } ``` -- `enabled`: هشدارهای شکست را برای کارهای Cron فعال کنید (پیش‌فرض: `false`). -- `after`: تعداد شکست‌های پیاپی پیش از فعال شدن هشدار (عدد صحیح مثبت، کمینه: `1`). +- `enabled`: هشدارهای شکست را برای کارهای Cron فعال می‌کند (پیش‌فرض: `false`). +- `after`: تعداد شکست‌های متوالی پیش از فعال‌شدن هشدار (عدد صحیح مثبت، حداقل: `1`). - `cooldownMs`: حداقل میلی‌ثانیه بین هشدارهای تکراری برای همان کار (عدد صحیح نامنفی). -- `includeSkipped`: اجراهای ردشده پیاپی را در آستانه هشدار حساب کنید (پیش‌فرض: `false`). اجراهای ردشده جداگانه ردیابی می‌شوند و بر backoff خطای اجرا تأثیر نمی‌گذارند. -- `mode`: حالت تحویل — `"announce"` از طریق پیام کانال ارسال می‌کند؛ `"webhook"` به Webhook پیکربندی‌شده پست می‌کند. -- `accountId`: شناسه اختیاری حساب یا کانال برای محدود کردن دامنه تحویل هشدار. +- `includeSkipped`: اجراهای ردشده متوالی را در آستانه هشدار حساب می‌کند (پیش‌فرض: `false`). اجراهای ردشده جداگانه ردیابی می‌شوند و بر backoff خطای اجرا اثری ندارند. +- `mode`: حالت تحویل — `"announce"` از طریق پیام کانال ارسال می‌کند؛ `"webhook"` به Webhook پیکربندی‌شده ارسال می‌کند. +- `accountId`: شناسه اختیاری حساب یا کانال برای محدودکردن دامنه تحویل هشدار. ### `cron.failureDestination` @@ -1208,46 +1219,46 @@ buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها - مقصد پیش‌فرض برای اعلان‌های شکست Cron در همه کارها. - `mode`: `"announce"` یا `"webhook"`؛ وقتی داده هدف کافی وجود داشته باشد، پیش‌فرض `"announce"` است. - `channel`: بازنویسی کانال برای تحویل announce. `"last"` آخرین کانال تحویل شناخته‌شده را دوباره استفاده می‌کند. -- `to`: هدف صریح announce یا URL وب‌هوک. برای حالت Webhook الزامی است. +- `to`: هدف صریح announce یا URL Webhook. برای حالت Webhook الزامی است. - `accountId`: بازنویسی اختیاری حساب برای تحویل. -- `delivery.failureDestination` مربوط به هر کار، این پیش‌فرض سراسری را بازنویسی می‌کند. -- وقتی نه مقصد شکست سراسری و نه مقصد شکست مربوط به هر کار تنظیم نشده باشد، کارهایی که از قبل از طریق `announce` تحویل می‌شوند، هنگام شکست به همان هدف اصلی announce بازمی‌گردند. -- `delivery.failureDestination` فقط برای کارهای sessionTarget="isolated" پشتیبانی می‌شود، مگر اینکه `delivery.mode` اصلی کار `"webhook"` باشد. +- `delivery.failureDestination` در سطح هر کار، این پیش‌فرض سراسری را بازنویسی می‌کند. +- وقتی نه مقصد شکست سراسری و نه مقصد شکست در سطح کار تنظیم شده باشد، کارهایی که از قبل از طریق `announce` تحویل می‌دهند، هنگام شکست به همان هدف announce اصلی برمی‌گردند. +- `delivery.failureDestination` فقط برای کارهای `sessionTarget="isolated"` پشتیبانی می‌شود، مگر اینکه `delivery.mode` اصلی کار `"webhook"` باشد. -[کارهای Cron](/fa/automation/cron-jobs) را ببینید. اجرای‌های Cron ایزوله به‌عنوان [کارهای پس‌زمینه](/fa/automation/tasks) ردیابی می‌شوند. +به [کارهای Cron](/fa/automation/cron-jobs) مراجعه کنید. اجراهای Cron ایزوله به‌عنوان [کارهای پس‌زمینه](/fa/automation/tasks) ردیابی می‌شوند. --- -## متغیرهای الگوی مدل رسانه +## متغیرهای قالب مدل رسانه -جای‌نگهدارهای الگو که در `tools.media.models[].args` گسترش می‌یابند: +جای‌نگهدارهای قالب در `tools.media.models[].args` گسترش داده می‌شوند: -| متغیر | توضیح | +| متغیر | توضیح | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | متن کامل پیام ورودی | -| `{{RawBody}}` | متن خام (بدون پوشش‌های تاریخچه/فرستنده) | -| `{{BodyStripped}}` | متن با حذف منشن‌های گروه | -| `{{From}}` | شناسه فرستنده | -| `{{To}}` | شناسه مقصد | -| `{{MessageSid}}` | شناسه پیام کانال | -| `{{SessionId}}` | UUID نشست فعلی | -| `{{IsNewSession}}` | `"true"` وقتی نشست جدید ایجاد شده باشد | -| `{{MediaUrl}}` | شبه‌URL رسانه ورودی | -| `{{MediaPath}}` | مسیر رسانه محلی | -| `{{MediaType}}` | نوع رسانه (تصویر/صدا/سند/…) | -| `{{Transcript}}` | رونوشت صوتی | -| `{{Prompt}}` | پرامپت رسانه حل‌شده برای ورودی‌های CLI | -| `{{MaxChars}}` | بیشینه نویسه‌های خروجی حل‌شده برای ورودی‌های CLI | +| `{{Body}}` | بدنه کامل پیام ورودی | +| `{{RawBody}}` | بدنه خام (بدون پوشش‌های تاریخچه/فرستنده) | +| `{{BodyStripped}}` | بدنه‌ای که اشاره‌های گروهی از آن حذف شده است | +| `{{From}}` | شناسه فرستنده | +| `{{To}}` | شناسه مقصد | +| `{{MessageSid}}` | شناسه پیام کانال | +| `{{SessionId}}` | UUID نشست فعلی | +| `{{IsNewSession}}` | وقتی نشست جدید ساخته شده باشد `"true"` | +| `{{MediaUrl}}` | شبه‌URL رسانه ورودی | +| `{{MediaPath}}` | مسیر رسانه محلی | +| `{{MediaType}}` | نوع رسانه (تصویر/صدا/سند/…) | +| `{{Transcript}}` | رونوشت صوت | +| `{{Prompt}}` | پرامپت رسانه حل‌شده برای ورودی‌های CLI | +| `{{MaxChars}}` | حداکثر نویسه‌های خروجی حل‌شده برای ورودی‌های CLI | | `{{ChatType}}` | `"direct"` یا `"group"` | -| `{{GroupSubject}}` | موضوع گروه (در حد امکان) | -| `{{GroupMembers}}` | پیش‌نمایش اعضای گروه (در حد امکان) | -| `{{SenderName}}` | نام نمایشی فرستنده (در حد امکان) | -| `{{SenderE164}}` | شماره تلفن فرستنده (در حد امکان) | -| `{{Provider}}` | راهنمای ارائه‌دهنده (WhatsApp، Telegram، Discord و غیره) | +| `{{GroupSubject}}` | موضوع گروه (در حد امکان) | +| `{{GroupMembers}}` | پیش‌نمایش اعضای گروه (در حد امکان) | +| `{{SenderName}}` | نام نمایشی فرستنده (در حد امکان) | +| `{{SenderE164}}` | شماره تلفن فرستنده (در حد امکان) | +| `{{Provider}}` | راهنمای Provider (whatsapp، telegram، discord و غیره) | --- -## شامل‌سازی‌های پیکربندی (`$include`) +## includeهای پیکربندی (`$include`) پیکربندی را به چند فایل تقسیم کنید: @@ -1264,14 +1275,14 @@ buildهای فعلی دیگر پل TCP را شامل نمی‌شوند. Nodeها **رفتار ادغام:** -- فایل تکی: شیء دربرگیرنده را جایگزین می‌کند. -- آرایه‌ای از فایل‌ها: به‌ترتیب به‌صورت عمیق ادغام می‌شوند (موارد بعدی موارد قبلی را بازنویسی می‌کنند). -- کلیدهای هم‌سطح: پس از شامل‌سازی‌ها ادغام می‌شوند (مقادیر شامل‌شده را بازنویسی می‌کنند). -- شامل‌سازی‌های تودرتو: تا عمق 10 سطح. -- مسیرها: نسبت به فایل شامل‌کننده حل می‌شوند، اما باید داخل دایرکتوری پیکربندی سطح بالا (`dirname` مربوط به `openclaw.json`) باقی بمانند. فرم‌های مطلق/`../` فقط وقتی مجازند که همچنان داخل همان مرز حل شوند. -- نوشتن‌های متعلق به OpenClaw که فقط یک بخش سطح بالا با پشتوانه یک شامل‌سازی تک‌فایلی را تغییر می‌دهند، در همان فایل شامل‌شده نوشته می‌شوند. برای مثال، `plugins install` مقدار `plugins: { $include: "./plugins.json5" }` را در `plugins.json5` به‌روزرسانی می‌کند و `openclaw.json` را دست‌نخورده می‌گذارد. -- شامل‌سازی‌های ریشه، آرایه‌های شامل‌سازی، و شامل‌سازی‌هایی با بازنویسی‌های هم‌سطح برای نوشتن‌های متعلق به OpenClaw فقط‌خواندنی هستند؛ این نوشتن‌ها به‌جای تخت کردن پیکربندی، بسته شکست می‌خورند. -- خطاها: پیام‌های روشن برای فایل‌های گم‌شده، خطاهای تجزیه، و شامل‌سازی‌های چرخه‌ای. +- فایل تکی: آبجکت دربرگیرنده را جایگزین می‌کند. +- آرایه فایل‌ها: به‌ترتیب به‌صورت عمیق ادغام می‌شود (موارد بعدی موارد قبلی را بازنویسی می‌کنند). +- کلیدهای هم‌سطح: پس از includeها ادغام می‌شوند (مقادیر includeشده را بازنویسی می‌کنند). +- includeهای تودرتو: تا عمق ۱۰ سطح. +- مسیرها: نسبت به فایل includeکننده حل می‌شوند، اما باید داخل دایرکتوری پیکربندی سطح بالا باقی بمانند (`dirname` از `openclaw.json`). شکل‌های مطلق/`../` فقط وقتی مجازند که همچنان داخل همان مرز حل شوند. +- نوشتن‌های متعلق به OpenClaw که فقط یک بخش سطح بالای پشتیبانی‌شده با include تک‌فایلی را تغییر می‌دهند، مستقیما در همان فایل includeشده نوشته می‌شوند. برای مثال، `plugins install` مقدار `plugins: { $include: "./plugins.json5" }` را در `plugins.json5` به‌روزرسانی می‌کند و `openclaw.json` را دست‌نخورده می‌گذارد. +- includeهای ریشه، آرایه‌های include، و includeهایی با بازنویسی هم‌سطح برای نوشتن‌های متعلق به OpenClaw فقط‌خواندنی هستند؛ این نوشتن‌ها به‌جای تخت‌کردن پیکربندی، به‌صورت بسته شکست می‌خورند. +- خطاها: پیام‌های روشن برای فایل‌های گم‌شده، خطاهای تجزیه، و includeهای چرخشی. --- diff --git a/docs/fa/gateway/diagnostics.md b/docs/fa/gateway/diagnostics.md index 804bf1576..b70813386 100644 --- a/docs/fa/gateway/diagnostics.md +++ b/docs/fa/gateway/diagnostics.md @@ -1,22 +1,27 @@ --- read_when: - آماده‌سازی گزارش اشکال یا درخواست پشتیبانی - - اشکال‌زدایی از ازکارافتادن‌ها، راه‌اندازی‌های مجدد، فشار حافظه یا بارهای دادهٔ بیش‌ازحد بزرگ در Gateway - - بررسی اینکه چه داده‌های تشخیصی ثبت یا پنهان‌سازی می‌شوند -summary: بسته‌های تشخیصی قابل اشتراک‌گذاری Gateway را برای گزارش‌های اشکال ایجاد کنید -title: برون‌بری عیب‌یابی + - اشکال‌زدایی خرابی‌ها، راه‌اندازی‌های مجدد، فشار حافظه یا بارهای داده‌ای بیش‌ازحد بزرگ Gateway + - بررسی اینکه چه داده‌های عیب‌یابی ثبت یا پنهان‌سازی می‌شوند +summary: بسته‌های عیب‌یابی Gateway قابل‌اشتراک‌گذاری برای گزارش‌های اشکال ایجاد کنید +title: خروجی عیب‌یابی x-i18n: - generated_at: "2026-05-03T21:34:19Z" + generated_at: "2026-05-05T01:47:14Z" model: gpt-5.5 provider: openai - source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b + source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382 source_path: gateway/diagnostics.md workflow: 16 --- -OpenClaw می‌تواند برای گزارش‌های باگ یک فایل zip عیب‌یابی محلی ایجاد کند. این فایل وضعیت، سلامت، لاگ‌ها، شکل پیکربندی و رویدادهای پایداری اخیرِ بدون payload مربوط به Gateway را، پس از پاک‌سازی داده‌های حساس، ترکیب می‌کند. +OpenClaw می‌تواند برای گزارش‌های باگ یک فایل zip عیب‌یابی محلی ایجاد کند. این فایل +وضعیت، سلامت، لاگ‌ها، شکل پیکربندی، و رویدادهای پایداری اخیر بدون محتوای +Gateway را به‌صورت پاک‌سازی‌شده ترکیب می‌کند. -تا وقتی بسته‌های عیب‌یابی را بازبینی نکرده‌اید، با آن‌ها مثل رازها رفتار کنید. این بسته‌ها طوری طراحی شده‌اند که payloadها و اعتبارنامه‌ها را حذف یا پوشانده کنند، اما همچنان لاگ‌های محلی Gateway و وضعیت زمان اجرای سطح میزبان را خلاصه می‌کنند. +تا زمانی که بسته‌های عیب‌یابی را بازبینی نکرده‌اید، با آن‌ها مثل اطلاعات محرمانه +برخورد کنید. این بسته‌ها طوری طراحی شده‌اند که محتواها و اعتبارنامه‌ها را حذف یا +سانسور کنند، اما همچنان لاگ‌های محلی Gateway و وضعیت اجرای سطح میزبان را +خلاصه می‌کنند. ## شروع سریع @@ -24,7 +29,7 @@ OpenClaw می‌تواند برای گزارش‌های باگ یک فایل zip openclaw gateway diagnostics export ``` -این دستور مسیر فایل zip نوشته‌شده را چاپ می‌کند. برای انتخاب مسیر: +این فرمان مسیر zip نوشته‌شده را چاپ می‌کند. برای انتخاب یک مسیر: ```bash openclaw gateway diagnostics export --output openclaw-diagnostics.zip @@ -36,57 +41,103 @@ openclaw gateway diagnostics export --output openclaw-diagnostics.zip openclaw gateway diagnostics export --json ``` -## دستور چت +## فرمان چت -مالکان می‌توانند در چت از `/diagnostics [note]` برای درخواست یک export محلی Gateway استفاده کنند. وقتی باگ در یک گفت‌وگوی واقعی رخ داده و یک گزارش قابل کپی‌کردن برای پشتیبانی می‌خواهید، از این استفاده کنید: +مالکان می‌توانند در چت از `/diagnostics [note]` برای درخواست یک خروجی محلی Gateway +استفاده کنند. وقتی باگ در یک گفت‌وگوی واقعی رخ داده و یک گزارش قابل کپی‌کردن +برای پشتیبانی می‌خواهید، از این روش استفاده کنید: -1. در گفت‌وگویی که مشکل را در آن دیدید، `/diagnostics` را ارسال کنید. اگر کمک می‌کند یک یادداشت کوتاه اضافه کنید، برای مثال `/diagnostics bad tool choice`. -2. OpenClaw مقدمه عیب‌یابی را ارسال می‌کند و یک تایید exec صریح درخواست می‌کند. این تایید، `openclaw gateway diagnostics export --json` را اجرا می‌کند. عیب‌یابی را از طریق یک قاعده allow-all تایید نکنید. -3. پس از تایید، OpenClaw با گزارشی قابل چسباندن پاسخ می‌دهد که شامل مسیر بسته محلی، خلاصه manifest، یادداشت‌های حریم خصوصی و شناسه‌های نشست مرتبط است. +1. در گفت‌وگویی که مشکل را در آن مشاهده کردید، `/diagnostics` را ارسال کنید. اگر + مفید است، یک یادداشت کوتاه اضافه کنید، برای مثال `/diagnostics bad tool choice`. +2. OpenClaw مقدمه عیب‌یابی را ارسال می‌کند و یک تأیید اجرای صریح می‌خواهد. این + تأیید، `openclaw gateway diagnostics export --json` را اجرا می‌کند. + عیب‌یابی را از طریق یک قاعده اجازه‌دادن به همه‌چیز تأیید نکنید. +3. پس از تأیید، OpenClaw با گزارشی قابل چسباندن پاسخ می‌دهد که شامل مسیر بسته + محلی، خلاصه manifest، نکات حریم خصوصی، و شناسه‌های نشست مرتبط است. -در چت‌های گروهی، مالک همچنان می‌تواند `/diagnostics` را اجرا کند، اما OpenClaw جزئیات عیب‌یابی را دوباره در چت مشترک منتشر نمی‌کند. مقدمه، درخواست‌های تایید، نتیجه export Gateway و تفکیک نشست/رشته Codex را از طریق مسیر تایید خصوصی برای مالک ارسال می‌کند. گروه فقط یک اعلان کوتاه دریافت می‌کند که جریان عیب‌یابی به‌صورت خصوصی ارسال شده است. اگر OpenClaw نتواند مسیر خصوصی مالک را پیدا کند، دستور به‌صورت بسته شکست می‌خورد و از مالک می‌خواهد آن را از یک DM اجرا کند. +در چت‌های گروهی، مالک همچنان می‌تواند `/diagnostics` را اجرا کند، اما OpenClaw +جزئیات عیب‌یابی را به چت مشترک برنمی‌گرداند. مقدمه، درخواست‌های تأیید، نتیجه +خروجی Gateway، و تفکیک نشست/رشته Codex را از مسیر خصوصی تأیید برای مالک +می‌فرستد. گروه فقط یک اعلان کوتاه دریافت می‌کند که جریان عیب‌یابی به‌صورت +خصوصی ارسال شده است. اگر OpenClaw نتواند مسیر خصوصی مالک را پیدا کند، فرمان +به‌صورت بسته شکست می‌خورد و از مالک می‌خواهد آن را از یک پیام مستقیم اجرا کند. -وقتی نشست فعال OpenClaw از harness بومی OpenAI Codex استفاده می‌کند، همان تایید exec یک آپلود بازخورد OpenAI را نیز برای رشته‌های زمان اجرای Codex که OpenClaw از آن‌ها خبر دارد پوشش می‌دهد. این آپلود از فایل zip محلی Gateway جداست و فقط برای نشست‌های harness Codex ظاهر می‌شود. پیش از تایید، prompt توضیح می‌دهد که تایید عیب‌یابی بازخورد Codex را هم ارسال می‌کند، اما شناسه‌های نشست یا رشته Codex را فهرست نمی‌کند. پس از تایید، پاسخ چت کانال‌ها، شناسه‌های نشست OpenClaw، شناسه‌های رشته Codex و دستورهای resume محلی را برای رشته‌هایی که به سرورهای OpenAI ارسال شده‌اند فهرست می‌کند. اگر تایید را رد یا نادیده بگیرید، OpenClaw export را اجرا نمی‌کند، بازخورد Codex را ارسال نمی‌کند و شناسه‌های Codex را چاپ نمی‌کند. +وقتی نشست فعال OpenClaw از سازوکار بومی OpenAI Codex استفاده می‌کند، +همان تأیید اجرا، بارگذاری بازخورد OpenAI را نیز برای رشته‌های اجرای Codex که +OpenClaw از آن‌ها اطلاع دارد پوشش می‌دهد. این بارگذاری جدا از zip محلی Gateway +است و فقط برای نشست‌های سازوکار Codex ظاهر می‌شود. پیش از تأیید، درخواست توضیح +می‌دهد که تأیید عیب‌یابی، بازخورد Codex را نیز ارسال می‌کند، اما شناسه‌های نشست +یا رشته Codex را فهرست نمی‌کند. پس از تأیید، پاسخ چت کانال‌ها، شناسه‌های نشست +OpenClaw، شناسه‌های رشته Codex، و فرمان‌های resume محلی را برای رشته‌هایی که +به سرورهای OpenAI ارسال شده‌اند فهرست می‌کند. اگر تأیید را رد یا نادیده بگیرید، +OpenClaw خروجی را اجرا نمی‌کند، بازخورد Codex را نمی‌فرستد، و شناسه‌های Codex را +چاپ نمی‌کند. -این کار حلقه رایج اشکال‌زدایی Codex را کوتاه می‌کند: رفتار بد را در Telegram، Discord یا کانالی دیگر ببینید، `/diagnostics` را اجرا کنید، یک‌بار تایید کنید، گزارش را با پشتیبانی به اشتراک بگذارید، سپس اگر می‌خواهید رشته بومی Codex را خودتان بررسی کنید، دستور چاپ‌شده `codex resume ` را به‌صورت محلی اجرا کنید. برای آن گردش‌کار بررسی، [harness Codex](/fa/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) را ببینید. +این کار حلقه رایج عیب‌یابی Codex را کوتاه می‌کند: رفتار بد را در Telegram، +Discord، یا کانالی دیگر مشاهده کنید، `/diagnostics` را اجرا کنید، یک بار تأیید +کنید، گزارش را با پشتیبانی به اشتراک بگذارید، سپس اگر می‌خواهید خودتان رشته +بومی Codex را بررسی کنید، فرمان چاپ‌شده `codex resume ` را به‌صورت +محلی اجرا کنید. برای این گردش‌کار بررسی، [سازوکار Codex](/fa/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) را ببینید. -## محتوای export چیست +## خروجی شامل چه چیزهایی است -فایل zip شامل موارد زیر است: +این zip شامل موارد زیر است: - `summary.md`: نمای کلی خوانا برای انسان جهت پشتیبانی. -- `diagnostics.json`: خلاصه قابل‌خواندن توسط ماشین از پیکربندی، لاگ‌ها، وضعیت، سلامت و داده‌های پایداری. -- `manifest.json`: فراداده export و فهرست فایل‌ها. +- `diagnostics.json`: خلاصه قابل خواندن توسط ماشین از پیکربندی، لاگ‌ها، وضعیت، سلامت، + و داده‌های پایداری. +- `manifest.json`: فراداده خروجی و فهرست فایل‌ها. - شکل پیکربندی پاک‌سازی‌شده و جزئیات غیرمحرمانه پیکربندی. -- خلاصه‌های لاگ پاک‌سازی‌شده و خطوط لاگ اخیرِ پوشانده‌شده. -- snapshotهای best-effort از وضعیت و سلامت Gateway. +- خلاصه‌های لاگ پاک‌سازی‌شده و خطوط لاگ اخیر سانسورشده. +- snapshotهای وضعیت و سلامت Gateway به‌صورت بهترین تلاش. - `stability/latest.json`: تازه‌ترین بسته پایداری ذخیره‌شده، در صورت وجود. -این export حتی وقتی Gateway ناسالم است هم مفید است. اگر Gateway نتواند به درخواست‌های وضعیت یا سلامت پاسخ دهد، لاگ‌های محلی، شکل پیکربندی و تازه‌ترین بسته پایداری همچنان در صورت وجود جمع‌آوری می‌شوند. +این خروجی حتی وقتی Gateway ناسالم است نیز مفید است. اگر Gateway نتواند به +درخواست‌های وضعیت یا سلامت پاسخ دهد، لاگ‌های محلی، شکل پیکربندی، و تازه‌ترین +بسته پایداری همچنان در صورت وجود جمع‌آوری می‌شوند. ## مدل حریم خصوصی -عیب‌یابی‌ها طوری طراحی شده‌اند که قابل اشتراک‌گذاری باشند. export داده‌های عملیاتی کمک‌کننده به اشکال‌زدایی را نگه می‌دارد، مانند: +عیب‌یابی‌ها طوری طراحی شده‌اند که قابل اشتراک‌گذاری باشند. خروجی داده‌های +عملیاتی کمک‌کننده به عیب‌یابی را نگه می‌دارد، مانند: -- نام‌های زیرسیستم، شناسه‌های Plugin، شناسه‌های provider، شناسه‌های کانال و حالت‌های پیکربندی‌شده -- کدهای وضعیت، مدت‌زمان‌ها، تعداد بایت‌ها، وضعیت صف و خوانش‌های حافظه -- فراداده لاگ پاک‌سازی‌شده و پیام‌های عملیاتی پوشانده‌شده +- نام‌های زیرسامانه، شناسه‌های Plugin، شناسه‌های ارائه‌دهنده، شناسه‌های کانال، و حالت‌های پیکربندی‌شده +- کدهای وضعیت، مدت‌زمان‌ها، شمارش بایت، وضعیت صف، و خوانش‌های حافظه +- فراداده لاگ پاک‌سازی‌شده و پیام‌های عملیاتی سانسورشده - شکل پیکربندی و تنظیمات ویژگی غیرمحرمانه -export موارد زیر را حذف یا پوشانده می‌کند: +خروجی موارد زیر را حذف یا سانسور می‌کند: -- متن چت، promptها، دستورالعمل‌ها، بدنه‌های Webhook و خروجی‌های ابزار -- اعتبارنامه‌ها، کلیدهای API، tokenها، cookieها و مقادیر محرمانه +- متن چت، promptها، دستورالعمل‌ها، بدنه‌های Webhook، و خروجی‌های ابزار +- اعتبارنامه‌ها، کلیدهای API، tokenها، cookieها، و مقادیر محرمانه - بدنه‌های خام درخواست یا پاسخ -- شناسه‌های حساب، شناسه‌های پیام، شناسه‌های خام نشست، نام‌های میزبان و نام‌های کاربری محلی +- شناسه‌های حساب، شناسه‌های پیام، شناسه‌های خام نشست، نام‌های میزبان، و نام‌های کاربری محلی -وقتی یک پیام لاگ شبیه متن payload کاربر، چت، prompt یا ابزار باشد، export فقط این را نگه می‌دارد که یک پیام حذف شده است و تعداد بایت آن را. +وقتی یک پیام لاگ شبیه متن کاربر، چت، prompt، یا محتوای ابزار باشد، خروجی فقط +این را نگه می‌دارد که پیامی حذف شده و شمارش بایت آن چقدر بوده است. ## ضبط‌کننده پایداری -وقتی عیب‌یابی‌ها فعال باشند، Gateway به‌صورت پیش‌فرض یک جریان پایداری محدود و بدون payload را ضبط می‌کند. این جریان برای واقعیت‌های عملیاتی است، نه محتوا. +وقتی عیب‌یابی فعال باشد، Gateway به‌صورت پیش‌فرض یک جریان پایداری محدود و بدون +محتوا را ثبت می‌کند. این جریان برای واقعیت‌های عملیاتی است، نه محتوا. -همان Heartbeat عیب‌یابی وقتی Gateway همچنان در حال اجراست اما event loop یا CPU در Node.js اشباع به نظر می‌رسد، نمونه‌های زنده‌بودن را ثبت می‌کند. این رویدادهای `diagnostic.liveness.warning` شامل تاخیر event-loop، بهره‌برداری event-loop، نسبت هسته CPU و تعداد نشست‌های فعال/درانتظار/صف‌شده هستند. نمونه‌های idle در سطح `info` در telemetry باقی می‌مانند. نمونه‌های زنده‌بودن فقط وقتی به هشدارهای Gateway تبدیل می‌شوند که کاری در انتظار یا صف باشد، یا وقتی کار فعال با تاخیر پایدار event-loop هم‌پوشانی داشته باشد. جهش‌های گذرای max-delay در طول کار پس‌زمینه‌ای که در غیر این صورت سالم است، در لاگ‌های debug باقی می‌مانند. آن‌ها به‌تنهایی Gateway را restart نمی‌کنند. +همان Heartbeat عیب‌یابی، وقتی Gateway همچنان در حال اجراست اما حلقه رویداد +Node.js یا CPU اشباع به نظر می‌رسد، نمونه‌های زنده‌بودن را ثبت می‌کند. این +رویدادهای `diagnostic.liveness.warning` شامل تأخیر حلقه رویداد، بهره‌برداری +حلقه رویداد، نسبت هسته CPU، تعداد نشست‌های فعال/در انتظار/صف‌شده، مرحله فعلی +راه‌اندازی/اجرا در صورت شناخته‌بودن، بازه‌های مرحله اخیر، و برچسب‌های محدود +کارهای فعال/صف‌شده هستند. نمونه‌های بیکار در سطح `info` در telemetry باقی +می‌مانند. نمونه‌های زنده‌بودن فقط وقتی به هشدارهای Gateway تبدیل می‌شوند که کاری +در انتظار یا صف‌شده باشد، یا وقتی کار فعال با تأخیر پایدار حلقه رویداد هم‌پوشانی +داشته باشد. جهش‌های گذرای حداکثر تأخیر هنگام کار پس‌زمینه‌ای که در غیر این صورت +سالم است، در لاگ‌های debug باقی می‌مانند. این موارد به‌تنهایی Gateway را +راه‌اندازی مجدد نمی‌کنند. + +مرحله‌های راه‌اندازی همچنین رویدادهای `diagnostic.phase.completed` را با زمان +دیوارساعت و زمان‌بندی CPU منتشر می‌کنند. عیب‌یابی‌های اجرای تعبیه‌شده متوقف‌شده +وقتی آخرین پیشرفت پل ترمینال به نظر برسد، مانند یک آیتم پاسخ خام یا رویداد تکمیل +پاسخ، اما Gateway همچنان اجرای تعبیه‌شده را فعال بداند، `terminalProgressStale=true` +را علامت‌گذاری می‌کنند. ضبط‌کننده زنده را بررسی کنید: @@ -96,19 +147,20 @@ openclaw gateway stability --type payload.large openclaw gateway stability --json ``` -پس از یک خروج fatal، timeout خاموشی یا شکست startup پس از restart، تازه‌ترین بسته پایداری ذخیره‌شده را بررسی کنید: +تازه‌ترین بسته پایداری ذخیره‌شده را پس از خروج مرگبار، timeout خاموشی، یا شکست +راه‌اندازی مجدد بررسی کنید: ```bash openclaw gateway stability --bundle latest ``` -از تازه‌ترین بسته ذخیره‌شده یک فایل zip عیب‌یابی بسازید: +از تازه‌ترین بسته ذخیره‌شده یک zip عیب‌یابی ایجاد کنید: ```bash openclaw gateway stability --bundle latest --export ``` -بسته‌های ذخیره‌شده وقتی رویدادها وجود داشته باشند، زیر `~/.openclaw/logs/stability/` قرار می‌گیرند. +بسته‌های ذخیره‌شده، وقتی رویدادها وجود داشته باشند، زیر `~/.openclaw/logs/stability/` قرار دارند. ## گزینه‌های مفید @@ -119,19 +171,20 @@ openclaw gateway diagnostics export \ --log-bytes 1000000 ``` -- `--output `: نوشتن در یک مسیر zip مشخص. -- `--log-lines `: بیشینه خطوط لاگ پاک‌سازی‌شده برای درج. -- `--log-bytes `: بیشینه بایت‌های لاگ برای بررسی. -- `--url `: URL WebSocket مربوط به Gateway برای snapshotهای وضعیت و سلامت. -- `--token `: token مربوط به Gateway برای snapshotهای وضعیت و سلامت. -- `--password `: گذرواژه Gateway برای snapshotهای وضعیت و سلامت. +- `--output `: در یک مسیر zip مشخص بنویسید. +- `--log-lines `: حداکثر خطوط لاگ پاک‌سازی‌شده برای گنجاندن. +- `--log-bytes `: حداکثر بایت‌های لاگ برای بررسی. +- `--url `: URL WebSocket Gateway برای snapshotهای وضعیت و سلامت. +- `--token `: token Gateway برای snapshotهای وضعیت و سلامت. +- `--password `: رمز عبور Gateway برای snapshotهای وضعیت و سلامت. - `--timeout `: timeout برای snapshot وضعیت و سلامت. -- `--no-stability-bundle`: رد کردن جست‌وجوی بسته پایداری ذخیره‌شده. -- `--json`: چاپ فراداده export قابل‌خواندن توسط ماشین. +- `--no-stability-bundle`: از جست‌وجوی بسته پایداری ذخیره‌شده صرف‌نظر کنید. +- `--json`: فراداده خروجی قابل خواندن توسط ماشین را چاپ کنید. -## غیرفعال کردن عیب‌یابی +## غیرفعال‌کردن عیب‌یابی -عیب‌یابی‌ها به‌صورت پیش‌فرض فعال هستند. برای غیرفعال کردن ضبط‌کننده پایداری و جمع‌آوری رویداد عیب‌یابی: +عیب‌یابی‌ها به‌صورت پیش‌فرض فعال هستند. برای غیرفعال‌کردن ضبط‌کننده پایداری و +جمع‌آوری رویدادهای عیب‌یابی: ```json5 { @@ -141,12 +194,13 @@ openclaw gateway diagnostics export \ } ``` -غیرفعال کردن عیب‌یابی جزئیات گزارش باگ را کاهش می‌دهد. بر لاگ‌گیری عادی Gateway اثری ندارد. +غیرفعال‌کردن عیب‌یابی، جزئیات گزارش باگ را کاهش می‌دهد. این کار بر لاگ‌گیری +عادی Gateway اثری ندارد. ## مرتبط - [بررسی‌های سلامت](/fa/gateway/health) -- [CLI مربوط به Gateway](/fa/cli/gateway#gateway-diagnostics-export) +- [CLI Gateway](/fa/cli/gateway#gateway-diagnostics-export) - [پروتکل Gateway](/fa/gateway/protocol#system-and-identity) - [لاگ‌گیری](/fa/logging) -- [export مربوط به OpenTelemetry](/fa/gateway/opentelemetry) — جریان جداگانه برای stream کردن عیب‌یابی‌ها به یک collector +- [خروجی OpenTelemetry](/fa/gateway/opentelemetry) — جریان جداگانه برای streaming عیب‌یابی‌ها به یک گردآورنده diff --git a/docs/fa/gateway/doctor.md b/docs/fa/gateway/doctor.md index 62b1263f1..241bd43b0 100644 --- a/docs/fa/gateway/doctor.md +++ b/docs/fa/gateway/doctor.md @@ -3,18 +3,18 @@ read_when: - افزودن یا اصلاح مهاجرت‌های doctor - معرفی تغییرات ناسازگار در پیکربندی sidebarTitle: Doctor -summary: 'فرمان Doctor: بررسی‌های سلامت، مهاجرت‌های پیکربندی و مراحل ترمیم' +summary: 'فرمان Doctor: بررسی‌های سلامت، مهاجرت‌های پیکربندی، و مراحل ترمیم' title: عیب‌یاب x-i18n: - generated_at: "2026-05-04T09:37:11Z" + generated_at: "2026-05-05T01:47:07Z" model: gpt-5.5 provider: openai - source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798 + source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` ابزار ترمیم + مهاجرت برای OpenClaw است. پیکربندی/وضعیت کهنه را اصلاح می‌کند، سلامت را بررسی می‌کند، و گام‌های ترمیمی قابل‌اقدام ارائه می‌دهد. +`openclaw doctor` ابزار تعمیر + مهاجرت برای OpenClaw است. این ابزار پیکربندی/وضعیت کهنه را اصلاح می‌کند، سلامت را بررسی می‌کند و گام‌های عملی برای تعمیر ارائه می‌دهد. ## شروع سریع @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### حالت‌های بدون سر و خودکارسازی +### حالت‌های بدون رابط تعاملی و خودکارسازی @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - پیش‌فرض‌ها را بدون پرسش بپذیر (از جمله گام‌های ترمیم راه‌اندازی مجدد/سرویس/سندباکس در صورت کاربرد). + پیش‌فرض‌ها را بدون درخواست تأیید بپذیر (از جمله گام‌های تعمیر راه‌اندازی دوباره/سرویس/sandbox در موارد قابل اعمال). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - ترمیم‌های پیشنهادی را بدون پرسش اعمال کن (ترمیم‌ها + راه‌اندازی‌های مجدد در موارد امن). + تعمیرهای پیشنهادی را بدون درخواست تأیید اعمال کن (تعمیرها + راه‌اندازی دوباره در موارد امن). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - ترمیم‌های تهاجمی را هم اعمال کن (پیکربندی‌های سفارشی ناظر را بازنویسی می‌کند). + تعمیرهای تهاجمی را هم اعمال کن (پیکربندی‌های سفارشی supervisor را بازنویسی می‌کند). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - بدون پرسش اجرا کن و فقط مهاجرت‌های امن را اعمال کن (عادی‌سازی پیکربندی + انتقال وضعیت روی دیسک). اقدام‌های راه‌اندازی مجدد/سرویس/سندباکس را که به تأیید انسانی نیاز دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند. + بدون درخواست‌های تعاملی اجرا کن و فقط مهاجرت‌های امن را اعمال کن (نرمال‌سازی پیکربندی + جابه‌جایی وضعیت روی دیسک). اقدامات راه‌اندازی دوباره/سرویس/sandbox را که به تأیید انسانی نیاز دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند. @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - سرویس‌های سیستم را برای نصب‌های Gateway اضافی اسکن کن (launchd/systemd/schtasks). + سرویس‌های سیستم را برای نصب‌های اضافی gateway اسکن کن (launchd/systemd/schtasks). -اگر می‌خواهید تغییرات را پیش از نوشتن بازبینی کنید، ابتدا فایل پیکربندی را باز کنید: +اگر می‌خواهید تغییرات را پیش از نوشتن مرور کنید، ابتدا فایل پیکربندی را باز کنید: ```bash cat ~/.openclaw/openclaw.json @@ -78,116 +78,119 @@ cat ~/.openclaw/openclaw.json - به‌روزرسانی اختیاری پیش از اجرا برای نصب‌های git (فقط تعاملی). - - بررسی تازگی پروتکل رابط کاربری (وقتی شِمای پروتکل جدیدتر باشد Control UI را دوباره می‌سازد). - - بررسی سلامت + درخواست راه‌اندازی مجدد. - - خلاصه وضعیت Skills (واجد شرایط/ناموجود/مسدود) و وضعیت Plugin. + - بررسی تازگی پروتکل رابط کاربری (وقتی schema پروتکل جدیدتر باشد، Control UI را دوباره می‌سازد). + - بررسی سلامت + درخواست راه‌اندازی دوباره. + - خلاصه وضعیت Skills (واجد شرایط/مفقود/مسدود) و وضعیت plugin. - - عادی‌سازی پیکربندی برای مقدارهای قدیمی. - - مهاجرت پیکربندی گفت‌وگو از فیلدهای تخت قدیمی `talk.*` به `talk.provider` + `talk.providers.`. + - نرمال‌سازی پیکربندی برای مقدارهای قدیمی. + - مهاجرت پیکربندی Talk از فیلدهای تخت قدیمی `talk.*` به `talk.provider` + `talk.providers.`. - بررسی‌های مهاجرت مرورگر برای پیکربندی‌های قدیمی افزونه Chrome و آمادگی Chrome MCP. - - هشدارهای بازنویسی ارائه‌دهنده OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - هشدارهای سایه‌افکنی OAuth کدکس (`models.providers.openai-codex`). - - بررسی پیش‌نیازهای OAuth TLS برای پروفایل‌های OAuth کدکس OpenAI. - - هشدارهای فهرست مجاز Plugin/ابزار وقتی `plugins.allow` محدودکننده است اما سیاست ابزار همچنان wildcard یا ابزارهای متعلق به Plugin را درخواست می‌کند. - - مهاجرت وضعیت قدیمی روی دیسک (نشست‌ها/دایرکتوری عامل/احراز هویت WhatsApp). - - مهاجرت کلید قرارداد مانیفست Plugin قدیمی (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - مهاجرت ذخیره‌گاه Cron قدیمی (`jobId`, `schedule.cron`, فیلدهای سطح‌بالای تحویل/بارمفید، بارمفید `provider`، کارهای جایگزین ساده Webhook با `notify: true`). - - مهاجرت سیاست زمان‌اجرای عامل قدیمی به `agents.defaults.agentRuntime` و `agents.list[].agentRuntime`. - - پاک‌سازی پیکربندی کهنه Plugin وقتی Pluginها فعال هستند؛ وقتی `plugins.enabled=false` باشد، ارجاع‌های کهنه Plugin به‌عنوان پیکربندی مهار بی‌اثر در نظر گرفته می‌شوند و حفظ می‌شوند. + - هشدارهای override ارائه‌دهنده OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). + - هشدارهای سایه‌اندازی OAuth در Codex (`models.providers.openai-codex`). + - بررسی پیش‌نیازهای TLS در OAuth برای پروفایل‌های OAuth متعلق به OpenAI Codex. + - هشدارهای allowlist مربوط به Plugin/ابزار وقتی `plugins.allow` محدودکننده است اما سیاست ابزار همچنان wildcard یا ابزارهای متعلق به plugin را درخواست می‌کند. + - مهاجرت وضعیت قدیمی روی دیسک (sessions/agent dir/احراز هویت WhatsApp). + - مهاجرت کلید contract قدیمی manifest مربوط به plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - مهاجرت cron store قدیمی (`jobId`, `schedule.cron`, فیلدهای سطح‌بالای delivery/payload، `provider` در payload، کارهای fallback ساده webhook با `notify: true`). + - مهاجرت runtime-policy قدیمی agent به `agents.defaults.agentRuntime` و `agents.list[].agentRuntime`. + - پاک‌سازی پیکربندی کهنه plugin وقتی pluginها فعال هستند؛ وقتی `plugins.enabled=false` باشد، ارجاع‌های کهنه plugin به‌عنوان پیکربندی containment بی‌اثر در نظر گرفته می‌شوند و حفظ می‌شوند. - - بازرسی فایل قفل نشست و پاک‌سازی قفل‌های کهنه. - - ترمیم رونوشت نشست برای شاخه‌های تکراری بازنویسی پرامپت که توسط بیلدهای متأثر 2026.4.24 ایجاد شده‌اند. - - شناسایی سنگ‌قبرهای بازیابی پس از راه‌اندازی مجدد زیرعامل گیرکرده، با پشتیبانی `--fix` برای پاک‌کردن پرچم‌های بازیابی لغوشده کهنه تا راه‌اندازی دیگر آن فرزند را همچنان لغوشده بر اثر راه‌اندازی مجدد تلقی نکند. - - بررسی‌های یکپارچگی وضعیت و مجوزها (نشست‌ها، رونوشت‌ها، دایرکتوری وضعیت). - - بررسی‌های مجوز فایل پیکربندی (chmod 600) هنگام اجرای محلی. - - سلامت احراز هویت مدل: انقضای OAuth را بررسی می‌کند، می‌تواند توکن‌های نزدیک به انقضا را نوسازی کند، و وضعیت‌های دوره انتظار/غیرفعال بودن پروفایل احراز هویت را گزارش می‌دهد. - - شناسایی دایرکتوری فضای کار اضافی (`~/openclaw`). + - بازرسی فایل قفل session و پاک‌سازی قفل‌های کهنه. + - تعمیر transcriptهای session برای شاخه‌های تکراری prompt-rewrite که توسط بیلدهای آسیب‌دیده 2026.4.24 ایجاد شده‌اند. + - شناسایی tombstoneهای restart-recovery برای subagentهای گیرکرده، با پشتیبانی `--fix` برای پاک‌سازی پرچم‌های stale aborted recovery تا startup همچنان child را restart-aborted در نظر نگیرد. + - بررسی‌های یکپارچگی وضعیت و مجوزها (sessions، transcripts، state dir). + - بررسی مجوزهای فایل پیکربندی (chmod 600) هنگام اجرای محلی. + - سلامت احراز هویت مدل: انقضای OAuth را بررسی می‌کند، می‌تواند tokenهای در آستانه انقضا را refresh کند، و وضعیت‌های cooldown/disabled در auth-profile را گزارش می‌دهد. + - شناسایی workspace dir اضافی (`~/openclaw`). - - - ترمیم تصویر سندباکس وقتی سندباکس‌کردن فعال است. - - مهاجرت سرویس قدیمی و شناسایی Gateway اضافی. + + - تعمیر تصویر sandbox وقتی sandboxing فعال است. + - مهاجرت سرویس قدیمی و شناسایی gateway اضافی. - مهاجرت وضعیت قدیمی کانال Matrix (در حالت `--fix` / `--repair`). - - بررسی‌های زمان‌اجرای Gateway (سرویس نصب شده اما اجرا نمی‌شود؛ برچسب launchd کش‌شده). - - هشدارهای وضعیت کانال (کاوش‌شده از Gateway در حال اجرا). - - ممیزی پیکربندی ناظر (launchd/systemd/schtasks) با ترمیم اختیاری. - - پاک‌سازی محیط پراکسی تعبیه‌شده برای سرویس‌های Gateway که مقدارهای پوسته `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` را هنگام نصب یا به‌روزرسانی گرفته‌اند. - - بررسی‌های بهترین‌رویه زمان‌اجرای Gateway (Node در برابر Bun، مسیرهای مدیر نسخه). - - عیب‌یابی برخورد پورت Gateway (پیش‌فرض `18789`). + - بررسی‌های runtime در Gateway (سرویس نصب شده اما اجرا نمی‌شود؛ label ذخیره‌شده launchd). + - هشدارهای وضعیت کانال (از Gateway در حال اجرا probe می‌شود). + - ممیزی پیکربندی supervisor (launchd/systemd/schtasks) با تعمیر اختیاری. + - پاک‌سازی محیط proxy تعبیه‌شده برای سرویس‌های Gateway که هنگام نصب یا به‌روزرسانی مقدارهای `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` پوسته را ثبت کرده‌اند. + - بررسی‌های بهترین‌روش runtime در Gateway (Node در برابر Bun، مسیرهای version-manager). + - تشخیص تداخل پورت Gateway (پیش‌فرض `18789`). - - - هشدارهای امنیتی برای سیاست‌های پیام مستقیم باز. - - بررسی‌های احراز هویت Gateway برای حالت توکن محلی (وقتی هیچ منبع توکنی وجود ندارد تولید توکن را پیشنهاد می‌کند؛ پیکربندی‌های SecretRef توکن را بازنویسی نمی‌کند). - - شناسایی مشکل جفت‌سازی دستگاه (درخواست‌های جفت‌سازی نخستین‌بار در انتظار، ارتقاهای نقش/دامنه در انتظار، انحراف کش کهنه توکن دستگاه محلی، و انحراف احراز هویت رکورد جفت‌شده). + + - هشدارهای امنیتی برای سیاست‌های DM باز. + - بررسی‌های احراز هویت Gateway برای حالت token محلی (وقتی منبع token وجود ندارد، تولید token را پیشنهاد می‌دهد؛ پیکربندی‌های token SecretRef را بازنویسی نمی‌کند). + - شناسایی مشکل pairing دستگاه (درخواست‌های pending برای first-time pair، ارتقاهای pending نقش/scope، drift در cache محلی device-token کهنه، و drift احراز هویت paired-record). - - - بررسی linger در systemd روی Linux. - - بررسی اندازه فایل راه‌انداز فضای کار (هشدارهای برش/نزدیک‌بودن به حد برای فایل‌های زمینه). - - بررسی آمادگی Skills برای عامل پیش‌فرض؛ مهارت‌های مجاز با نیازمندی‌های ناموجود bin، محیط، پیکربندی، یا سیستم‌عامل را گزارش می‌دهد، و `--fix` می‌تواند مهارت‌های در دسترس نبودنی را در `skills.entries` غیرفعال کند. - - بررسی وضعیت تکمیل پوسته و نصب/ارتقای خودکار. - - بررسی آمادگی ارائه‌دهنده تعبیه جست‌وجوی حافظه (مدل محلی، کلید API راه‌دور، یا باینری QMD). - - بررسی‌های نصب از منبع (ناسازگاری فضای کار pnpm، دارایی‌های رابط کاربری ناموجود، باینری tsx ناموجود). - - پیکربندی به‌روزشده + فراداده جادوگر را می‌نویسد. + + - بررسی systemd linger در Linux. + - بررسی اندازه فایل bootstrap مربوط به workspace (هشدارهای truncation/نزدیک به حد برای فایل‌های context). + - بررسی آمادگی Skills برای agent پیش‌فرض؛ skillهای مجاز با bin، env، config، یا نیازمندی‌های OS مفقود را گزارش می‌دهد، و `--fix` می‌تواند skillهای در دسترس نبودنی را در `skills.entries` غیرفعال کند. + - بررسی وضعیت shell completion و نصب/ارتقای خودکار. + - بررسی آمادگی ارائه‌دهنده embedding برای جست‌وجوی حافظه (مدل محلی، کلید remote API، یا binary مربوط به QMD). + - بررسی‌های نصب از source (ناسازگاری pnpm workspace، assetهای UI مفقود، binary مفقود tsx). + - پیکربندی به‌روزشده + metadata مربوط به wizard را می‌نویسد. -## پس‌پرکردن و بازنشانی رابط کاربری رویاها +## بازپرکنی و بازنشانی Dreams UI -صحنه رویاها در Control UI شامل اقدام‌های **پس‌پرکردن**، **بازنشانی**، و **پاک‌کردن زمینه‌مند** برای جریان کاری Dreaming زمینه‌مند است. این اقدام‌ها از روش‌های RPC شبیه doctor در Gateway استفاده می‌کنند، اما بخشی از ترمیم/مهاجرت CLI در `openclaw doctor` نیستند. +صحنه Dreams در Control UI شامل اقدام‌های **Backfill**، **Reset**، و **Clear Grounded** برای گردش‌کار grounded dreaming است. این اقدام‌ها از روش‌های RPC به سبک gateway doctor استفاده می‌کنند، اما بخشی از تعمیر/مهاجرت CLI مربوط به `openclaw doctor` نیستند. کاری که انجام می‌دهند: -- **پس‌پرکردن** فایل‌های تاریخی `memory/YYYY-MM-DD.md` را در فضای کار فعال اسکن می‌کند، گذر دفترچه REM زمینه‌مند را اجرا می‌کند، و ورودی‌های پس‌پرکردن برگشت‌پذیر را در `DREAMS.md` می‌نویسد. -- **بازنشانی** فقط همان ورودی‌های دفترچه پس‌پرکردنِ علامت‌گذاری‌شده را از `DREAMS.md` حذف می‌کند. -- **پاک‌کردن زمینه‌مند** فقط ورودی‌های کوتاه‌مدتِ فقط-زمینه‌مندِ آماده‌سازی‌شده را حذف می‌کند که از بازپخش تاریخی آمده‌اند و هنوز یادآوری زنده یا پشتیبانی روزانه انباشته نکرده‌اند. +- **Backfill** فایل‌های تاریخی `memory/YYYY-MM-DD.md` را در workspace فعال اسکن می‌کند، گذر grounded REM diary را اجرا می‌کند، و ورودی‌های backfill برگشت‌پذیر را در `DREAMS.md` می‌نویسد. +- **Reset** فقط همان ورودی‌های diary علامت‌گذاری‌شده backfill را از `DREAMS.md` حذف می‌کند. +- **Clear Grounded** فقط ورودی‌های کوتاه‌مدت staged و فقط grounded را حذف می‌کند که از بازپخش تاریخی آمده‌اند و هنوز live recall یا daily support انباشته نکرده‌اند. -کاری که به‌تنهایی انجام **نمی‌دهند**: +کاری که به‌خودی‌خود انجام **نمی‌دهند**: -- آن‌ها `MEMORY.md` را ویرایش نمی‌کنند -- آن‌ها مهاجرت‌های کامل doctor را اجرا نمی‌کنند -- آن‌ها نامزدهای زمینه‌مند را به‌طور خودکار وارد ذخیره‌گاه ترویج کوتاه‌مدت زنده نمی‌کنند، مگر اینکه ابتدا مسیر CLI آماده‌سازی‌شده را صراحتاً اجرا کنید +- `MEMORY.md` را ویرایش نمی‌کنند +- مهاجرت‌های کامل doctor را اجرا نمی‌کنند +- candidateهای grounded را به‌طور خودکار در live short-term promotion store stage نمی‌کنند، مگر اینکه ابتدا مسیر staged CLI را صریحاً اجرا کنید -اگر می‌خواهید بازپخش تاریخی زمینه‌مند روی مسیر عادی ترویج عمیق اثر بگذارد، به‌جای آن از جریان CLI استفاده کنید: +اگر می‌خواهید بازپخش تاریخی grounded بر مسیر عادی deep promotion اثر بگذارد، به‌جای آن از جریان CLI استفاده کنید: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -این کار نامزدهای پایدار زمینه‌مند را در ذخیره‌گاه Dreaming کوتاه‌مدت آماده می‌کند، در حالی که `DREAMS.md` را به‌عنوان سطح بازبینی نگه می‌دارد. +این کار candidateهای durable و grounded را در short-term dreaming store stage می‌کند، در حالی که `DREAMS.md` را به‌عنوان سطح مرور نگه می‌دارد. ## رفتار دقیق و منطق - اگر این یک checkout از git باشد و doctor به‌صورت تعاملی اجرا شود، پیش از اجرای doctor پیشنهاد به‌روزرسانی (fetch/rebase/build) می‌دهد. + اگر این یک git checkout باشد و doctor به‌صورت تعاملی اجرا شود، پیشنهاد می‌دهد پیش از اجرای doctor به‌روزرسانی انجام شود (fetch/rebase/build). - - اگر پیکربندی شامل شکل‌های مقدار قدیمی باشد (برای مثال `messages.ackReaction` بدون بازنویسی ویژه کانال)، doctor آن‌ها را در شِمای فعلی عادی‌سازی می‌کند. + + اگر پیکربندی شامل شکل‌های مقدار قدیمی باشد (برای مثال `messages.ackReaction` بدون override ویژه کانال)، doctor آن‌ها را به schema فعلی نرمال می‌کند. - این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.`. Doctor شکل‌های قدیمی `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` را در نقشه ارائه‌دهنده بازنویسی می‌کند. + این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.`. Doctor شکل‌های قدیمی `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` را به نقشه ارائه‌دهنده بازنویسی می‌کند. - Doctor همچنین وقتی `plugins.allow` غیرخالی است و سیاست ابزار از - ورودی‌های wildcard یا ابزار متعلق به Plugin استفاده می‌کند، هشدار می‌دهد. `tools.allow: ["*"]` فقط با ابزارهایی - از Pluginهایی که واقعاً بارگذاری می‌شوند تطبیق دارد؛ فهرست مجاز انحصاری Plugin را دور نمی‌زند. + Doctor همچنین وقتی `plugins.allow` خالی نیست و سیاست ابزار از ورودی‌های + wildcard یا ابزارهای متعلق به plugin استفاده می‌کند هشدار می‌دهد. `tools.allow: ["*"]` فقط با ابزارهایی + از pluginهایی match می‌شود که واقعاً load می‌شوند؛ از allowlist انحصاری plugin + عبور نمی‌کند. Doctor برای پیکربندی‌های allowlist قدیمی مهاجرت‌داده‌شده + `plugins.bundledDiscovery: "compat"` را می‌نویسد تا رفتار موجود ارائه‌دهنده bundled حفظ شود، و + سپس به تنظیم سخت‌گیرانه‌تر `"allowlist"` اشاره می‌کند. - وقتی پیکربندی شامل کلیدهای منسوخ باشد، فرمان‌های دیگر از اجرا سر باز می‌زنند و از شما می‌خواهند `openclaw doctor` را اجرا کنید. + وقتی پیکربندی شامل کلیدهای منسوخ باشد، فرمان‌های دیگر از اجرا خودداری می‌کنند و از شما می‌خواهند `openclaw doctor` را اجرا کنید. Doctor این کارها را انجام می‌دهد: - توضیح می‌دهد کدام کلیدهای قدیمی پیدا شده‌اند. - مهاجرتی را که اعمال کرده نشان می‌دهد. - - `~/.openclaw/openclaw.json` را با شِمای به‌روزشده بازنویسی می‌کند. + - `~/.openclaw/openclaw.json` را با schema به‌روزشده بازنویسی می‌کند. - Gateway نیز هنگام راه‌اندازی، وقتی قالب پیکربندی قدیمی را شناسایی کند، مهاجرت‌های doctor را به‌طور خودکار اجرا می‌کند، بنابراین پیکربندی‌های کهنه بدون مداخله دستی ترمیم می‌شوند. مهاجرت‌های ذخیره‌گاه کار Cron توسط `openclaw doctor --fix` مدیریت می‌شوند. + Gateway نیز هنگام startup، اگر فرمت پیکربندی قدیمی را شناسایی کند، مهاجرت‌های doctor را به‌طور خودکار اجرا می‌کند، بنابراین پیکربندی‌های کهنه بدون دخالت دستی تعمیر می‌شوند. مهاجرت‌های cron job store توسط `openclaw doctor --fix` انجام می‌شوند. مهاجرت‌های فعلی: @@ -195,11 +198,12 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention` - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - - پیکربندی‌های configured-channel که سیاست پاسخ قابل‌مشاهده ندارند → `messages.groupChat.visibleReplies: "message_tool"` + - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` + - پیکربندی‌های کانال پیکربندی‌شده که سیاست پاسخ قابل‌مشاهده ندارند → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - `routing.bindings` → `bindings` سطح بالا - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - - `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` قدیمی → `talk.provider` + `talk.providers.` + - میراثی `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -213,289 +217,295 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - برای کانال‌هایی که `accounts` نام‌دار دارند اما هنوز مقدارهای سطح بالای کانال تک‌حسابی باقی مانده است، آن مقدارهای دارای محدوده حساب را به حساب ارتقایافته انتخاب‌شده برای آن کانال منتقل کنید (`accounts.default` برای بیشتر کانال‌ها؛ Matrix می‌تواند یک هدف نام‌دار/پیش‌فرض منطبق موجود را حفظ کند) + - برای کانال‌هایی که `accounts` نام‌دار دارند اما هنوز مقدارهای سطح بالای کانال تک‌حسابی باقی مانده است، آن مقدارهای در محدوده حساب را به حساب ارتقایافته‌ای منتقل کنید که برای آن کانال انتخاب شده است (`accounts.default` برای بیشتر کانال‌ها؛ Matrix می‌تواند هدف نام‌دار/پیش‌فرض مطابق موجود را حفظ کند) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - `agents.defaults.llm` را حذف کنید؛ برای زمان‌انتظارهای طولانی provider/model از `models.providers..timeoutSeconds` استفاده کنید + - `agents.defaults.llm` را حذف کنید؛ برای زمان‌انقضای کند provider/model از `models.providers..timeoutSeconds` استفاده کنید - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - `browser.relayBindHost` را حذف کنید (تنظیم قدیمی رله extension) - - `models.providers.*.api: "openai"` قدیمی → `"openai-completions"` (راه‌اندازی Gateway همچنین providerهایی را که `api` آن‌ها روی یک مقدار enum آینده یا ناشناخته تنظیم شده باشد، به‌جای شکست بسته، رد می‌کند) + - `browser.relayBindHost` را حذف کنید (تنظیم میراثی رله افزونه) + - میراثی `models.providers.*.api: "openai"` → `"openai-completions"` (هنگام راه‌اندازی Gateway همچنین providerهایی را که `api` آن‌ها روی مقدار enum آینده یا ناشناخته تنظیم شده است، به‌جای شکست بسته، نادیده می‌گیرد) - هشدارهای doctor همچنین شامل راهنمایی حساب پیش‌فرض برای کانال‌های چندحسابی است: + هشدارهای Doctor همچنین شامل راهنمایی پیش‌فرض حساب برای کانال‌های چندحسابی است: - - اگر دو یا چند ورودی `channels..accounts` بدون `channels..defaultAccount` یا `accounts.default` پیکربندی شده باشند، doctor هشدار می‌دهد که مسیریابی fallback می‌تواند حسابی غیرمنتظره را انتخاب کند. + - اگر دو یا چند ورودی `channels..accounts` بدون `channels..defaultAccount` یا `accounts.default` پیکربندی شده باشند، doctor هشدار می‌دهد که مسیریابی fallback می‌تواند حساب غیرمنتظره‌ای را انتخاب کند. - اگر `channels..defaultAccount` روی شناسه حساب ناشناخته تنظیم شده باشد، doctor هشدار می‌دهد و شناسه‌های حساب پیکربندی‌شده را فهرست می‌کند. - - اگر `models.providers.opencode`، `opencode-zen`، یا `opencode-go` را دستی اضافه کرده باشید، کاتالوگ داخلی OpenCode از `@mariozechner/pi-ai` را بازنویسی می‌کند. این می‌تواند مدل‌ها را وادار کند از API نادرست استفاده کنند یا هزینه‌ها را صفر کند. Doctor هشدار می‌دهد تا بتوانید بازنویسی را حذف کنید و مسیریابی API به‌ازای هر مدل + هزینه‌ها را برگردانید. + + اگر `models.providers.opencode`، `opencode-zen` یا `opencode-go` را دستی اضافه کرده باشید، catalog داخلی OpenCode از `@mariozechner/pi-ai` را بازنویسی می‌کند. این کار می‌تواند مدل‌ها را به API اشتباه اجبار کند یا هزینه‌ها را صفر کند. Doctor هشدار می‌دهد تا بتوانید بازنویسی را حذف کنید و مسیریابی API به‌ازای هر مدل + هزینه‌ها را بازیابی کنید. - - اگر پیکربندی مرورگر شما هنوز به مسیر حذف‌شده Chrome extension اشاره می‌کند، doctor آن را به مدل فعلی اتصال Chrome MCP محلی روی میزبان نرمال‌سازی می‌کند: + + اگر پیکربندی مرورگر شما هنوز به مسیر افزونه حذف‌شده Chrome اشاره می‌کند، doctor آن را به مدل اتصال Chrome MCP میزبان-محلی فعلی نرمال‌سازی می‌کند: - `browser.profiles.*.driver: "extension"` به `"existing-session"` تبدیل می‌شود - `browser.relayBindHost` حذف می‌شود - Doctor همچنین وقتی از `defaultProfile: "user"` یا یک پروفایل `existing-session` پیکربندی‌شده استفاده می‌کنید، مسیر Chrome MCP محلی روی میزبان را بررسی می‌کند: + Doctor همچنین هنگام استفاده از `defaultProfile: "user"` یا پروفایل پیکربندی‌شده `existing-session`، مسیر Chrome MCP میزبان-محلی را بررسی می‌کند: - - بررسی می‌کند آیا Google Chrome روی همان میزبان برای پروفایل‌های اتصال خودکار پیش‌فرض نصب شده است یا نه - - نسخه شناسایی‌شده Chrome را بررسی می‌کند و وقتی پایین‌تر از Chrome 144 باشد هشدار می‌دهد - - یادآوری می‌کند که اشکال‌زدایی از راه دور را در صفحه inspect مرورگر فعال کنید (برای مثال `chrome://inspect/#remote-debugging`، `brave://inspect/#remote-debugging`، یا `edge://inspect/#remote-debugging`) + - بررسی می‌کند که آیا Google Chrome روی همان میزبان برای پروفایل‌های اتصال خودکار پیش‌فرض نصب شده است یا نه + - نسخه Chrome شناسایی‌شده را بررسی می‌کند و وقتی کمتر از Chrome 144 باشد هشدار می‌دهد + - یادآوری می‌کند که اشکال‌زدایی راه‌دور را در صفحه inspect مرورگر فعال کنید (برای مثال `chrome://inspect/#remote-debugging`، `brave://inspect/#remote-debugging` یا `edge://inspect/#remote-debugging`) - Doctor نمی‌تواند تنظیم سمت Chrome را برای شما فعال کند. Chrome MCP محلی روی میزبان همچنان نیاز دارد به: + Doctor نمی‌تواند تنظیم سمت Chrome را برای شما فعال کند. Chrome MCP میزبان-محلی همچنان به این موارد نیاز دارد: - - یک مرورگر مبتنی بر Chromium نسخه 144+ روی میزبان gateway/node - - اجرای محلی مرورگر - - فعال بودن اشکال‌زدایی از راه دور در آن مرورگر - - تأیید اولین درخواست رضایت اتصال در مرورگر + - یک مرورگر مبتنی بر Chromium نسخه ۱۴۴+ روی میزبان gateway/node + - اجرای مرورگر به‌صورت محلی + - فعال بودن اشکال‌زدایی راه‌دور در آن مرورگر + - تأیید نخستین درخواست رضایت اتصال در مرورگر - آمادگی در اینجا فقط درباره پیش‌نیازهای اتصال محلی است. Existing-session محدودیت‌های مسیر فعلی Chrome MCP را نگه می‌دارد؛ مسیرهای پیشرفته مانند `responsebody`، خروجی PDF، رهگیری دانلود، و عملیات دسته‌ای همچنان به مرورگر مدیریت‌شده یا پروفایل خام CDP نیاز دارند. + آمادگی در اینجا فقط درباره پیش‌نیازهای اتصال محلی است. Existing-session محدودیت‌های مسیر Chrome MCP فعلی را نگه می‌دارد؛ مسیرهای پیشرفته مانند `responsebody`، خروجی PDF، رهگیری دانلود و اقدامات دسته‌ای همچنان به مرورگر مدیریت‌شده یا پروفایل CDP خام نیاز دارند. - این بررسی برای Docker، sandbox، remote-browser، یا جریان‌های headless دیگر اعمال **نمی‌شود**. آن‌ها همچنان از CDP خام استفاده می‌کنند. + این بررسی برای Docker، sandbox، remote-browser یا دیگر جریان‌های headless اعمال نمی‌شود. آن‌ها همچنان از CDP خام استفاده می‌کنند. - - وقتی یک پروفایل OpenAI Codex OAuth پیکربندی شده باشد، doctor نقطه پایانی مجوزدهی OpenAI را بررسی می‌کند تا مطمئن شود پشته TLS محلی Node/OpenSSL می‌تواند زنجیره گواهی را اعتبارسنجی کند. اگر بررسی با خطای گواهی شکست بخورد (برای مثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`، گواهی منقضی‌شده، یا گواهی خودامضاشده)، doctor راهنمای رفع مشکل مخصوص پلتفرم را چاپ می‌کند. در macOS با Node نصب‌شده از Homebrew، راه‌حل معمولا `brew postinstall ca-certificates` است. با `--deep`، این بررسی حتی اگر Gateway سالم باشد هم اجرا می‌شود. + + وقتی یک پروفایل OpenAI Codex OAuth پیکربندی شده باشد، doctor endpoint مجوزدهی OpenAI را بررسی می‌کند تا تأیید کند پشته TLS محلی Node/OpenSSL می‌تواند زنجیره گواهی را اعتبارسنجی کند. اگر بررسی با خطای گواهی شکست بخورد (برای مثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`، گواهی منقضی‌شده یا گواهی خودامضاشده)، doctor راهنمای رفع مشکل مخصوص پلتفرم را چاپ می‌کند. در macOS با Node نصب‌شده از Homebrew، راه‌حل معمولاً `brew postinstall ca-certificates` است. با `--deep`، بررسی حتی اگر gateway سالم باشد اجرا می‌شود. - - اگر قبلا تنظیمات انتقال قدیمی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر provider داخلی Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند تحت‌الشعاع قرار دهند. Doctor وقتی آن تنظیمات انتقال قدیمی را کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید بازنویسی انتقال کهنه را حذف یا بازنویسی کنید و رفتار داخلی مسیریابی/fallback را برگردانید. پراکسی‌های سفارشی و بازنویسی‌های فقط header همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند. + + اگر قبلاً تنظیمات انتقال میراثی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر داخلی provider در Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند پنهان کنند. Doctor وقتی آن تنظیمات انتقال قدیمی را در کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید بازنویسی انتقال کهنه را حذف یا بازنویسی کنید و رفتار مسیریابی/fallback داخلی را برگردانید. پراکسی‌های سفارشی و بازنویسی‌های فقط‌header همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند. - - وقتی Plugin بسته‌بندی‌شده Codex فعال باشد، doctor همچنین بررسی می‌کند آیا refهای مدل اصلی `openai-codex/*` هنوز از طریق runner پیش‌فرض PI resolve می‌شوند یا نه. این ترکیب وقتی می‌خواهید احراز هویت Codex OAuth/subscription از طریق PI انجام شود معتبر است، اما به‌راحتی با harness بومی app-server مربوط به Codex اشتباه گرفته می‌شود. Doctor هشدار می‌دهد و به شکل صریح app-server اشاره می‌کند: `openai/*` به‌همراه `agentRuntime.id: "codex"` یا `OPENCLAW_AGENT_RUNTIME=codex`. + + وقتی Plugin بسته‌بندی‌شده Codex فعال باشد، doctor همچنین بررسی می‌کند که آیا ارجاع‌های مدل اصلی `openai-codex/*` هنوز از طریق runner پیش‌فرض PI resolve می‌شوند یا نه. وقتی احراز هویت Codex OAuth/subscription را از طریق PI می‌خواهید، این ترکیب معتبر است، اما به‌راحتی با harness بومی app-server در Codex اشتباه گرفته می‌شود. Doctor هشدار می‌دهد و به شکل صریح app-server اشاره می‌کند: `openai/*` به‌علاوه `agentRuntime.id: "codex"` یا `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor این را خودکار تعمیر نمی‌کند چون هر دو مسیر معتبر هستند: + Doctor این مورد را خودکار تعمیر نمی‌کند، چون هر دو مسیر معتبر هستند: - `openai-codex/*` + PI یعنی «از احراز هویت Codex OAuth/subscription از طریق runner عادی OpenClaw استفاده کن.» - - `openai/*` + `agentRuntime.id: "codex"` یعنی «turn تعبیه‌شده را از طریق app-server بومی Codex اجرا کن.» + - `openai/*` + `agentRuntime.id: "codex"` یعنی «نوبت جاسازی‌شده را از طریق app-server بومی Codex اجرا کن.» - `/codex ...` یعنی «یک گفت‌وگوی بومی Codex را از chat کنترل یا bind کن.» - `/acp ...` یا `runtime: "acp"` یعنی «از adapter خارجی ACP/acpx استفاده کن.» - اگر هشدار ظاهر شد، مسیری را که مدنظر داشتید انتخاب کنید و config را دستی ویرایش کنید. وقتی PI Codex OAuth عمدی است، هشدار را همان‌طور نگه دارید. + اگر هشدار ظاهر شد، مسیری را که قصد داشتید انتخاب کنید و پیکربندی را دستی ویرایش کنید. وقتی PI Codex OAuth عمدی است، هشدار را همان‌طور نگه دارید. - - Doctor می‌تواند چیدمان‌های قدیمی روی دیسک را به ساختار فعلی مهاجرت دهد: + + Doctor همچنین پس از اینکه مدل یا runtime پیش‌فرض/fallback پیکربندی‌شده را از مسیری متعلق به Plugin مانند Codex دور می‌کنید، active sessions store را برای وضعیت مسیر کهنه‌ای که خودکار ساخته شده است اسکن می‌کند. - - ذخیره‌گاه نشست‌ها + transcriptها: + `openclaw doctor --fix` می‌تواند وضعیت کهنه خودکارساخته‌شده مانند pinهای مدل `modelOverrideSource: "auto"`، metadata مدل runtime، شناسه‌های pinشده harness، bindingهای session در CLI و بازنویسی‌های خودکار auth-profile را وقتی مسیر مالک آن‌ها دیگر پیکربندی نشده است پاک کند. انتخاب‌های صریح کاربر یا مدل session میراثی برای بازبینی دستی گزارش می‌شوند و دست‌نخورده باقی می‌مانند؛ وقتی آن مسیر دیگر مدنظر نیست، آن‌ها را با `/model ...`، `/new` تغییر دهید یا session را reset کنید. + + + + Doctor می‌تواند چیدمان‌های قدیمی‌تر روی دیسک را به ساختار فعلی مهاجرت دهد: + + - Sessions store + transcriptها: - از `~/.openclaw/sessions/` به `~/.openclaw/agents//sessions/` - - دایرکتوری عامل: + - دایرکتوری agent: - از `~/.openclaw/agent/` به `~/.openclaw/agents//agent/` - وضعیت احراز هویت WhatsApp (Baileys): - - از `~/.openclaw/credentials/*.json` قدیمی (به‌جز `oauth.json`) + - از میراثی `~/.openclaw/credentials/*.json` (به‌جز `oauth.json`) - به `~/.openclaw/credentials/whatsapp//...` (شناسه حساب پیش‌فرض: `default`) - این مهاجرت‌ها best-effort و idempotent هستند؛ doctor وقتی هر پوشه قدیمی را به‌عنوان نسخه پشتیبان باقی بگذارد هشدار صادر می‌کند. Gateway/CLI همچنین نشست‌های قدیمی + دایرکتوری عامل را در زمان راه‌اندازی به‌صورت خودکار مهاجرت می‌کند تا history/auth/models بدون اجرای دستی doctor در مسیر به‌ازای هر عامل قرار بگیرند. احراز هویت WhatsApp عمدا فقط از طریق `openclaw doctor` مهاجرت داده می‌شود. نرمال‌سازی provider/provider-map مربوط به Talk اکنون با برابری ساختاری مقایسه می‌کند، بنابراین diffهایی که فقط مربوط به ترتیب کلیدها هستند دیگر باعث تغییرات تکراری بی‌اثر `doctor --fix` نمی‌شوند. + این مهاجرت‌ها با بهترین تلاش و idempotent هستند؛ وقتی doctor هر پوشه میراثی را به‌عنوان پشتیبان باقی بگذارد، هشدار منتشر می‌کند. Gateway/CLI همچنین در زمان راه‌اندازی، sessions + دایرکتوری agent میراثی را خودکار مهاجرت می‌دهد تا history/auth/models بدون اجرای دستی doctor در مسیر به‌ازای هر agent قرار گیرند. احراز هویت WhatsApp عمداً فقط از طریق `openclaw doctor` مهاجرت می‌شود. نرمال‌سازی provider/provider-map در Talk اکنون با برابری ساختاری مقایسه می‌کند، بنابراین diffهایی که فقط مربوط به ترتیب کلید هستند دیگر تغییرات تکراری بی‌اثر `doctor --fix` را فعال نمی‌کنند. - - Doctor همه manifestهای Plugin نصب‌شده را برای کلیدهای capability سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل manifest را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقدارها را داشته باشد، کلید قدیمی بدون تکرار داده حذف می‌شود. + + Doctor همه manifestهای Plugin نصب‌شده را برای کلیدهای capability سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل manifest را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقدارها را داشته باشد، کلید میراثی بدون تکثیر داده حذف می‌شود. - - Doctor همچنین ذخیره‌گاه کارهای cron را (`~/.openclaw/cron/jobs.json` به‌صورت پیش‌فرض، یا `cron.store` وقتی بازنویسی شده باشد) برای شکل‌های قدیمی job که scheduler هنوز برای سازگاری می‌پذیرد بررسی می‌کند. + + Doctor همچنین cron job store را (`~/.openclaw/cron/jobs.json` به‌صورت پیش‌فرض، یا `cron.store` وقتی بازنویسی شده باشد) برای شکل‌های قدیمی job که scheduler هنوز برای سازگاری می‌پذیرد بررسی می‌کند. - پاک‌سازی‌های فعلی cron شامل موارد زیر است: + پاک‌سازی‌های فعلی Cron شامل این موارد است: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - فیلدهای payload سطح بالا (`message`، `model`، `thinking`، ...) → `payload` - فیلدهای delivery سطح بالا (`deliver`، `channel`، `to`، `provider`، ...) → `delivery` - - aliasهای delivery مربوط به `provider` در payload → `delivery.channel` صریح - - jobهای fallback ساده webhook قدیمی با `notify: true` → `delivery.mode="webhook"` صریح با `delivery.to=cron.webhook` + - aliasهای delivery در payload `provider` → `delivery.channel` صریح + - jobهای fallback webhook میراثی ساده `notify: true` → `delivery.mode="webhook"` صریح با `delivery.to=cron.webhook` - Doctor فقط وقتی jobهای `notify: true` را خودکار مهاجرت می‌دهد که بتواند این کار را بدون تغییر رفتار انجام دهد. اگر یک job، fallback notify قدیمی را با یک حالت delivery غیر-webhook موجود ترکیب کند، doctor هشدار می‌دهد و آن job را برای بازبینی دستی رها می‌کند. + Doctor فقط jobهای `notify: true` را زمانی خودکار مهاجرت می‌دهد که بتواند بدون تغییر رفتار این کار را انجام دهد. اگر یک job، fallback notify میراثی را با حالت delivery غیر-webhook موجود ترکیب کند، doctor هشدار می‌دهد و آن job را برای بازبینی دستی باقی می‌گذارد. - در Linux، doctor همچنین وقتی crontab کاربر هنوز `~/.openclaw/bin/ensure-whatsapp.sh` قدیمی را فراخوانی کند هشدار می‌دهد. این اسکریپت محلی روی میزبان توسط OpenClaw فعلی نگهداری نمی‌شود و وقتی cron نتواند به گذرگاه کاربر systemd دسترسی پیدا کند می‌تواند پیام‌های نادرست `Gateway inactive` را در `~/.openclaw/logs/whatsapp-health.log` بنویسد. ورودی کهنه crontab را با `crontab -e` حذف کنید؛ برای بررسی‌های سلامت فعلی از `openclaw channels status --probe`، `openclaw doctor`، و `openclaw gateway status` استفاده کنید. + در Linux، Doctor همچنین زمانی هشدار می‌دهد که crontab کاربر هنوز `~/.openclaw/bin/ensure-whatsapp.sh` قدیمی را اجرا می‌کند. این اسکریپت محلی میزبان توسط OpenClaw فعلی نگهداری نمی‌شود و وقتی cron نتواند به گذرگاه کاربر systemd دسترسی پیدا کند، می‌تواند پیام‌های نادرست `Gateway inactive` را در `~/.openclaw/logs/whatsapp-health.log` بنویسد. ورودی قدیمی crontab را با `crontab -e` حذف کنید؛ برای بررسی‌های سلامت فعلی از `openclaw channels status --probe`، `openclaw doctor` و `openclaw gateway status` استفاده کنید. - دکتر هر دایرکتوری نشست عامل را برای فایل‌های قفل نوشتن کهنه اسکن می‌کند — فایل‌هایی که وقتی یک نشست به‌طور غیرعادی خارج شده، باقی مانده‌اند. برای هر فایل قفل پیدا‌شده گزارش می‌دهد: مسیر، PID، اینکه آیا PID هنوز زنده است، سن قفل، و اینکه آیا کهنه در نظر گرفته می‌شود یا نه (PID مرده یا قدیمی‌تر از ۳۰ دقیقه). در حالت `--fix` / `--repair`، فایل‌های قفل کهنه را به‌طور خودکار حذف می‌کند؛ در غیر این صورت یادداشتی چاپ می‌کند و به شما دستور می‌دهد با `--fix` دوباره اجرا کنید. + Doctor همهٔ دایرکتوری‌های نشست عامل را برای فایل‌های write-lock مانده بررسی می‌کند — فایل‌هایی که وقتی یک نشست به‌صورت غیرعادی خارج شده باقی مانده‌اند. برای هر فایل قفل پیدا‌شده گزارش می‌دهد: مسیر، PID، اینکه PID هنوز زنده است یا نه، سن قفل، و اینکه آیا قدیمی محسوب می‌شود یا نه (PID مرده یا قدیمی‌تر از ۳۰ دقیقه). در حالت `--fix` / `--repair` فایل‌های قفل قدیمی را خودکار حذف می‌کند؛ در غیر این صورت یک یادداشت چاپ می‌کند و از شما می‌خواهد با `--fix` دوباره اجرا کنید. - - دکتر فایل‌های JSONL نشست عامل را برای شکل شاخه تکراری ایجادشده توسط باگ بازنویسی رونوشت پرامپت 2026.4.24 اسکن می‌کند: یک نوبت کاربر رهاشده با زمینه زمان اجرای داخلی OpenClaw به‌همراه یک همزاد فعال که همان پرامپت قابل مشاهده کاربر را دارد. در حالت `--fix` / `--repair`، دکتر از هر فایل آسیب‌دیده در کنار نسخه اصلی پشتیبان می‌گیرد و رونوشت را به شاخه فعال بازنویسی می‌کند تا تاریخچه gateway و خواننده‌های حافظه دیگر نوبت‌های تکراری را نبینند. + + Doctor فایل‌های JSONL نشست عامل را برای شکل شاخهٔ تکراری ایجادشده توسط باگ بازنویسی رونوشت پرامپت 2026.4.24 بررسی می‌کند: یک نوبت کاربر رهاشده با زمینهٔ runtime داخلی OpenClaw به‌همراه یک همتای فعال که همان پرامپت قابل‌مشاهدهٔ کاربر را دارد. در حالت `--fix` / `--repair`، Doctor از هر فایل آسیب‌دیده کنار فایل اصلی نسخهٔ پشتیبان می‌گیرد و رونوشت را به شاخهٔ فعال بازنویسی می‌کند تا تاریخچهٔ Gateway و خواننده‌های حافظه دیگر نوبت‌های تکراری نبینند. - دایرکتوری وضعیت، ساقه مغز عملیاتی است. اگر ناپدید شود، نشست‌ها، اعتبارنامه‌ها، لاگ‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه در جای دیگری پشتیبان داشته باشید). + دایرکتوری وضعیت ساقهٔ مغز عملیاتی است. اگر ناپدید شود، نشست‌ها، اعتبارنامه‌ها، گزارش‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه در جای دیگری نسخهٔ پشتیبان داشته باشید). - دکتر بررسی می‌کند: + Doctor بررسی می‌کند: - - **دایرکتوری وضعیت موجود نیست**: درباره از دست رفتن فاجعه‌بار وضعیت هشدار می‌دهد، برای ایجاد دوباره دایرکتوری درخواست می‌کند، و یادآوری می‌کند که نمی‌تواند داده‌های ازدست‌رفته را بازیابی کند. - - **مجوزهای دایرکتوری وضعیت**: قابلیت نوشتن را تأیید می‌کند؛ پیشنهاد ترمیم مجوزها را می‌دهد (و وقتی عدم تطابق مالک/گروه تشخیص داده شود، راهنمایی `chown` منتشر می‌کند). - - **دایرکتوری وضعیت همگام‌شده با ابر در macOS**: وقتی وضعیت زیر iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) یا `~/Library/CloudStorage/...` حل شود هشدار می‌دهد، چون مسیرهای متکی بر همگام‌سازی می‌توانند باعث I/O کندتر و رقابت‌های قفل/همگام‌سازی شوند. - - **دایرکتوری وضعیت SD یا eMMC در Linux**: وقتی وضعیت به یک منبع mount از نوع `mmcblk*` حل شود هشدار می‌دهد، چون I/O تصادفی متکی بر SD یا eMMC می‌تواند زیر نوشتن‌های نشست و اعتبارنامه کندتر باشد و سریع‌تر فرسوده شود. - - **دایرکتوری‌های نشست موجود نیستند**: `sessions/` و دایرکتوری ذخیره نشست برای ماندگار کردن تاریخچه و جلوگیری از کرش‌های `ENOENT` لازم هستند. - - **عدم تطابق رونوشت**: وقتی ورودی‌های نشست اخیر فایل‌های رونوشت گم‌شده داشته باشند هشدار می‌دهد. - - **نشست اصلی "JSONL یک‌خطی"**: وقتی رونوشت اصلی فقط یک خط داشته باشد علامت‌گذاری می‌کند (تاریخچه در حال انباشته شدن نیست). - - **چند دایرکتوری وضعیت**: وقتی چند پوشه `~/.openclaw` در دایرکتوری‌های خانه وجود داشته باشد یا وقتی `OPENCLAW_STATE_DIR` به جای دیگری اشاره کند هشدار می‌دهد (تاریخچه می‌تواند بین نصب‌ها تقسیم شود). - - **یادآور حالت راه‌دور**: اگر `gateway.mode=remote` باشد، دکتر یادآوری می‌کند که آن را روی میزبان راه‌دور اجرا کنید (وضعیت آنجا قرار دارد). - - **مجوزهای فایل پیکربندی**: اگر `~/.openclaw/openclaw.json` برای گروه/جهان قابل خواندن باشد هشدار می‌دهد و پیشنهاد سخت‌گیرانه‌تر کردن به `600` را می‌دهد. + - **دایرکتوری وضعیت موجود نیست**: دربارهٔ از دست رفتن فاجعه‌بار وضعیت هشدار می‌دهد، برای ایجاد دوبارهٔ دایرکتوری درخواست می‌کند، و یادآوری می‌کند که نمی‌تواند داده‌های ازدست‌رفته را بازیابی کند. + - **مجوزهای دایرکتوری وضعیت**: قابلیت نوشتن را بررسی می‌کند؛ پیشنهاد ترمیم مجوزها را می‌دهد (و وقتی ناهماهنگی مالک/گروه شناسایی شود، راهنمایی `chown` صادر می‌کند). + - **دایرکتوری وضعیت همگام‌شده با ابر در macOS**: وقتی وضعیت زیر iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) یا `~/Library/CloudStorage/...` resolve شود هشدار می‌دهد، چون مسیرهای مبتنی بر همگام‌سازی می‌توانند باعث I/O کندتر و رقابت‌های قفل/همگام‌سازی شوند. + - **دایرکتوری وضعیت SD یا eMMC در Linux**: وقتی وضعیت به منبع mount از نوع `mmcblk*` resolve شود هشدار می‌دهد، چون I/O تصادفی مبتنی بر SD یا eMMC می‌تواند زیر نوشتن‌های نشست و اعتبارنامه کندتر شود و سریع‌تر فرسوده شود. + - **دایرکتوری‌های نشست موجود نیستند**: `sessions/` و دایرکتوری ذخیره‌گاه نشست برای ماندگار کردن تاریخچه و جلوگیری از crashهای `ENOENT` لازم هستند. + - **ناهماهنگی رونوشت**: وقتی ورودی‌های نشست اخیر فایل‌های رونوشت مفقود داشته باشند هشدار می‌دهد. + - **نشست اصلی "JSONL تک‌خطی"**: وقتی رونوشت اصلی فقط یک خط داشته باشد علامت‌گذاری می‌کند (تاریخچه انباشته نمی‌شود). + - **چند دایرکتوری وضعیت**: وقتی چند پوشهٔ `~/.openclaw` در دایرکتوری‌های home وجود داشته باشد یا وقتی `OPENCLAW_STATE_DIR` به جای دیگری اشاره کند هشدار می‌دهد (تاریخچه می‌تواند بین نصب‌ها تقسیم شود). + - **یادآوری حالت راه دور**: اگر `gateway.mode=remote` باشد، Doctor یادآوری می‌کند که آن را روی میزبان راه دور اجرا کنید (وضعیت آنجا زندگی می‌کند). + - **مجوزهای فایل پیکربندی**: اگر `~/.openclaw/openclaw.json` برای گروه/همه قابل خواندن باشد هشدار می‌دهد و پیشنهاد سخت‌کردن آن به `600` را می‌دهد. - دکتر پروفایل‌های OAuth را در ذخیره احراز هویت بررسی می‌کند، وقتی توکن‌ها در حال انقضا/منقضی‌شده باشند هشدار می‌دهد، و وقتی امن باشد می‌تواند آن‌ها را تازه‌سازی کند. اگر پروفایل OAuth/توکن Anthropic کهنه باشد، یک کلید API Anthropic یا مسیر setup-token Anthropic را پیشنهاد می‌کند. درخواست‌های تازه‌سازی فقط هنگام اجرای تعاملی (TTY) ظاهر می‌شوند؛ `--non-interactive` تلاش‌های تازه‌سازی را رد می‌کند. + Doctor پروفایل‌های OAuth را در ذخیره‌گاه احراز هویت بررسی می‌کند، وقتی توکن‌ها در حال انقضا/منقضی هستند هشدار می‌دهد، و وقتی امن باشد می‌تواند آن‌ها را refresh کند. اگر پروفایل OAuth/token مربوط به Anthropic قدیمی باشد، یک کلید API Anthropic یا مسیر setup-token Anthropic را پیشنهاد می‌کند. درخواست‌های refresh فقط هنگام اجرای تعاملی (TTY) ظاهر می‌شوند؛ `--non-interactive` تلاش‌های refresh را رد می‌کند. - وقتی تازه‌سازی OAuth به‌طور دائمی شکست بخورد (برای مثال `refresh_token_reused`، `invalid_grant`، یا ارائه‌دهنده‌ای که از شما می‌خواهد دوباره وارد شوید)، دکتر گزارش می‌دهد که احراز هویت دوباره لازم است و دستور دقیق `openclaw models auth login --provider ...` را برای اجرا چاپ می‌کند. + وقتی refresh مربوط به OAuth به‌طور دائمی شکست بخورد (برای مثال `refresh_token_reused`، `invalid_grant`، یا ارائه‌دهنده‌ای که به شما می‌گوید دوباره وارد شوید)، Doctor گزارش می‌دهد که احراز هویت دوباره لازم است و دستور دقیق `openclaw models auth login --provider ...` را برای اجرا چاپ می‌کند. - دکتر همچنین پروفایل‌های احراز هویتی را گزارش می‌دهد که به‌طور موقت به دلایل زیر غیرقابل استفاده هستند: + Doctor همچنین پروفایل‌های احراز هویتی را گزارش می‌دهد که به‌طور موقت به این دلایل قابل استفاده نیستند: - - cooldownهای کوتاه (محدودیت نرخ/timeoutها/شکست‌های احراز هویت) - - غیرفعال‌سازی‌های طولانی‌تر (شکست‌های صورتحساب/اعتبار) + - cooldownهای کوتاه (محدودیت نرخ/timeout/شکست‌های احراز هویت) + - غیرفعال‌سازی‌های طولانی‌تر (شکست‌های صورت‌حساب/اعتبار) - اگر `hooks.gmail.model` تنظیم شده باشد، دکتر مرجع مدل را در برابر کاتالوگ و allowlist اعتبارسنجی می‌کند و وقتی حل نشود یا مجاز نباشد هشدار می‌دهد. + اگر `hooks.gmail.model` تنظیم شده باشد، Doctor مرجع مدل را در برابر catalog و allowlist اعتبارسنجی می‌کند و وقتی resolve نشود یا مجاز نباشد هشدار می‌دهد. - وقتی sandboxing فعال باشد، دکتر تصویرهای Docker را بررسی می‌کند و اگر تصویر فعلی موجود نباشد، پیشنهاد ساخت یا تغییر به نام‌های قدیمی را می‌دهد. + وقتی sandboxing فعال باشد، Doctor تصویرهای Docker را بررسی می‌کند و اگر تصویر فعلی موجود نباشد پیشنهاد build کردن یا تغییر به نام‌های قدیمی را می‌دهد. - دکتر در حالت `openclaw doctor --fix` / `openclaw doctor --repair` وضعیت مرحله‌بندی وابستگی Plugin قدیمی تولیدشده توسط OpenClaw را حذف می‌کند. این شامل ریشه‌های وابستگی تولیدشده کهنه، دایرکتوری‌های install-stage قدیمی، پسماند محلی package از کد ترمیم وابستگی bundled-plugin قبلی، و کپی‌های npm مدیریت‌شده یتیم یا بازیابی‌شده از Pluginهای bundled `@openclaw/*` است که می‌توانند manifest bundled فعلی را تحت‌الشعاع قرار دهند. + Doctor وضعیت staging وابستگی Plugin تولیدشدهٔ قدیمی OpenClaw را در حالت `openclaw doctor --fix` / `openclaw doctor --repair` حذف می‌کند. این شامل ریشه‌های وابستگی تولیدشدهٔ قدیمی، دایرکتوری‌های مرحلهٔ نصب قدیمی، بقایای محلی package از کد ترمیم وابستگی bundled-plugin قبلی، و کپی‌های npm مدیریت‌شدهٔ orphan یا بازیابی‌شده از Pluginهای bundled `@openclaw/*` است که می‌توانند manifest bundled فعلی را پنهان کنند. - دکتر همچنین می‌تواند وقتی پیکربندی به Pluginهای قابل دانلود ارجاع می‌دهد اما رجیستری Plugin محلی نمی‌تواند آن‌ها را پیدا کند، Pluginهای قابل دانلود پیکربندی‌شده را دوباره نصب کند. برای externalization مربوط به bundled-plugin نسخه 2026.5.2، دکتر به‌طور خودکار Pluginهای قابل دانلودی را نصب می‌کند که پیکربندی موجود از قبل استفاده می‌کند و سپس به `meta.lastTouchedVersion` تکیه می‌کند تا آن گذر انتشار فقط یک‌بار اجرا شود. راه‌اندازی Gateway و بارگذاری دوباره پیکربندی package managerها را اجرا نمی‌کنند؛ نصب‌های Plugin همچنان کار صریح doctor/install/update باقی می‌مانند. + Doctor همچنین می‌تواند Pluginهای قابل دانلود مفقود را وقتی پیکربندی به آن‌ها ارجاع می‌دهد اما رجیستری Plugin محلی نمی‌تواند آن‌ها را پیدا کند، دوباره نصب کند. نمونه‌ها شامل `plugins.entries` مادی، تنظیمات پیکربندی‌شدهٔ کانال/ارائه‌دهنده/جست‌وجو، و runtimeهای عامل پیکربندی‌شده هستند. هنگام به‌روزرسانی package، Doctor از اجرای ترمیم Plugin توسط package-manager در حالی که package هسته جابه‌جا می‌شود خودداری می‌کند؛ اگر یک Plugin پیکربندی‌شده هنوز به بازیابی نیاز دارد، پس از به‌روزرسانی دوباره `openclaw doctor --fix` را اجرا کنید. راه‌اندازی Gateway و بارگذاری دوبارهٔ پیکربندی package managerها را اجرا نمی‌کنند؛ نصب‌های Plugin همچنان کار صریح doctor/install/update باقی می‌مانند. - دکتر سرویس‌های Gateway قدیمی (launchd/systemd/schtasks) را تشخیص می‌دهد و پیشنهاد حذف آن‌ها و نصب سرویس OpenClaw با استفاده از پورت Gateway فعلی را می‌دهد. همچنین می‌تواند سرویس‌های اضافی شبیه Gateway را اسکن کند و راهنمایی‌های پاک‌سازی چاپ کند. سرویس‌های Gateway مربوط به OpenClaw با نام پروفایل، درجه‌یک در نظر گرفته می‌شوند و به‌عنوان "اضافی" علامت‌گذاری نمی‌شوند. + Doctor سرویس‌های gateway قدیمی (launchd/systemd/schtasks) را شناسایی می‌کند و پیشنهاد حذف آن‌ها و نصب سرویس OpenClaw با پورت gateway فعلی را می‌دهد. همچنین می‌تواند سرویس‌های اضافهٔ شبیه gateway را اسکن کند و راهنمایی‌های پاک‌سازی چاپ کند. سرویس‌های gateway مربوط به OpenClaw که با نام پروفایل هستند، درجه‌یک محسوب می‌شوند و به‌عنوان "اضافی" علامت‌گذاری نمی‌شوند. - در Linux، اگر سرویس Gateway سطح کاربر موجود نباشد اما یک سرویس Gateway سطح سیستم OpenClaw وجود داشته باشد، دکتر به‌طور خودکار سرویس سطح کاربر دومی نصب نمی‌کند. با `openclaw gateway status --deep` یا `openclaw doctor --deep` بررسی کنید، سپس نسخه تکراری را حذف کنید یا وقتی یک supervisor سیستم مالک چرخه عمر Gateway است، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. + در Linux، اگر سرویس gateway سطح کاربر موجود نباشد اما یک سرویس gateway سطح سیستم OpenClaw وجود داشته باشد، Doctor سرویس سطح کاربر دومی را به‌صورت خودکار نصب نمی‌کند. با `openclaw gateway status --deep` یا `openclaw doctor --deep` بررسی کنید، سپس مورد تکراری را حذف کنید یا وقتی یک سرپرست سیستم چرخهٔ عمر gateway را مالک است، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. - - وقتی یک حساب کانال Matrix مهاجرت وضعیت قدیمی در انتظار یا قابل اقدام داشته باشد، دکتر (در حالت `--fix` / `--repair`) یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس مراحل مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت Matrix قدیمی و آماده‌سازی وضعیت رمزگذاری‌شده قدیمی. هر دو مرحله غیرکشنده هستند؛ خطاها ثبت می‌شوند و شروع ادامه پیدا می‌کند. در حالت فقط خواندنی (`openclaw doctor` بدون `--fix`) این بررسی به‌طور کامل رد می‌شود. + + وقتی حساب کانال Matrix یک مهاجرت وضعیت قدیمی در انتظار یا قابل اقدام داشته باشد، Doctor (در حالت `--fix` / `--repair`) یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس گام‌های مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت قدیمی Matrix و آماده‌سازی وضعیت رمزگذاری‌شدهٔ قدیمی. هر دو گام غیرکشنده هستند؛ خطاها ثبت می‌شوند و راه‌اندازی ادامه پیدا می‌کند. در حالت read-only (`openclaw doctor` بدون `--fix`) این بررسی کاملاً رد می‌شود. - - دکتر اکنون وضعیت جفت‌سازی دستگاه را به‌عنوان بخشی از گذر سلامت عادی بررسی می‌کند. + + Doctor اکنون وضعیت جفت‌سازی دستگاه را به‌عنوان بخشی از گذر سلامت عادی بررسی می‌کند. آنچه گزارش می‌دهد: - درخواست‌های جفت‌سازی بار اول در انتظار - - ارتقاهای نقش در انتظار برای دستگاه‌هایی که از قبل جفت شده‌اند - - ارتقاهای scope در انتظار برای دستگاه‌هایی که از قبل جفت شده‌اند - - ترمیم‌های عدم تطابق کلید عمومی که در آن id دستگاه هنوز مطابقت دارد اما هویت دستگاه دیگر با رکورد تأییدشده مطابقت ندارد + - ارتقاهای نقش در انتظار برای دستگاه‌های از قبل جفت‌شده + - ارتقاهای scope در انتظار برای دستگاه‌های از قبل جفت‌شده + - ترمیم‌های ناهماهنگی کلید عمومی که در آن‌ها id دستگاه هنوز مطابقت دارد اما هویت دستگاه دیگر با رکورد تأییدشده مطابقت ندارد - رکوردهای جفت‌شده‌ای که برای یک نقش تأییدشده توکن فعال ندارند - توکن‌های جفت‌شده‌ای که scopeهایشان از baseline جفت‌سازی تأییدشده منحرف شده است - - ورودی‌های cache محلی device-token برای ماشین فعلی که قبل از چرخش توکن سمت Gateway هستند یا metadata scope کهنه دارند + - ورودی‌های cache محلی device-token برای ماشین فعلی که پیش از چرخش توکن سمت gateway هستند یا metadata scope قدیمی دارند - دکتر درخواست‌های جفت‌سازی را به‌طور خودکار تأیید نمی‌کند و توکن‌های دستگاه را به‌طور خودکار نمی‌چرخاند. در عوض مراحل بعدی دقیق را چاپ می‌کند: + Doctor درخواست‌های جفت‌سازی را خودکار تأیید نمی‌کند و توکن‌های دستگاه را خودکار rotate نمی‌کند. در عوض گام‌های بعدی دقیق را چاپ می‌کند: - درخواست‌های در انتظار را با `openclaw devices list` بررسی کنید - درخواست دقیق را با `openclaw devices approve ` تأیید کنید - - یک توکن تازه را با `openclaw devices rotate --device --role ` بچرخانید - - یک رکورد کهنه را با `openclaw devices remove ` حذف و دوباره تأیید کنید + - یک توکن تازه را با `openclaw devices rotate --device --role ` rotate کنید + - یک رکورد قدیمی را با `openclaw devices remove ` حذف و دوباره تأیید کنید - این شکاف رایج "از قبل جفت شده اما هنوز pairing required دریافت می‌کند" را می‌بندد: دکتر اکنون جفت‌سازی بار اول را از ارتقاهای نقش/scope در انتظار و از انحراف توکن/هویت دستگاه کهنه متمایز می‌کند. + این حفرهٔ رایج "از قبل جفت شده اما هنوز pairing required می‌گیرد" را می‌بندد: Doctor اکنون جفت‌سازی بار اول را از ارتقاهای نقش/scope در انتظار و از drift قدیمی توکن/هویت دستگاه متمایز می‌کند. - دکتر وقتی یک ارائه‌دهنده بدون allowlist برای DMها باز باشد، یا وقتی یک policy به‌شکل خطرناک پیکربندی شده باشد، هشدار منتشر می‌کند. + Doctor وقتی یک ارائه‌دهنده بدون allowlist به روی DMها باز باشد، یا وقتی یک policy به روشی خطرناک پیکربندی شده باشد، هشدار صادر می‌کند. - - اگر به‌عنوان سرویس کاربر systemd اجرا شود، دکتر اطمینان می‌دهد lingering فعال باشد تا gateway پس از logout زنده بماند. + + اگر به‌عنوان سرویس کاربر systemd اجرا شود، Doctor اطمینان می‌دهد lingering فعال است تا gateway پس از خروج از سیستم زنده بماند. - - دکتر خلاصه‌ای از وضعیت workspace را برای عامل پیش‌فرض چاپ می‌کند: + + Doctor خلاصه‌ای از وضعیت workspace برای عامل پیش‌فرض چاپ می‌کند: - - **وضعیت Skills**: skills واجد شرایط، دارای نیازمندی‌های گم‌شده، و مسدودشده توسط allowlist را می‌شمارد. - - **دایرکتوری‌های workspace قدیمی**: وقتی `~/openclaw` یا دایرکتوری‌های workspace قدیمی دیگر در کنار workspace فعلی وجود داشته باشند هشدار می‌دهد. - - **وضعیت Plugin**: Pluginهای فعال/غیرفعال/دارای خطا را می‌شمارد؛ شناسه‌های Plugin را برای هر خطا فهرست می‌کند؛ قابلیت‌های Plugin بسته را گزارش می‌دهد. + - **وضعیت Skills**: Skills واجد شرایط، با الزامات مفقود، و مسدودشده توسط allowlist را می‌شمارد. + - **دایرکتوری‌های workspace قدیمی**: وقتی `~/openclaw` یا دایرکتوری‌های workspace قدیمی دیگر کنار workspace فعلی وجود داشته باشند هشدار می‌دهد. + - **وضعیت Plugin**: Pluginهای فعال/غیرفعال/خطادار را می‌شمارد؛ برای هر خطا idهای Plugin را فهرست می‌کند؛ قابلیت‌های bundle plugin را گزارش می‌دهد. - **هشدارهای سازگاری Plugin**: Pluginهایی را علامت‌گذاری می‌کند که با runtime فعلی مشکل سازگاری دارند. - - **عیب‌یابی Plugin**: هر هشدار یا خطای زمان بارگذاری منتشرشده توسط رجیستری Plugin را نمایان می‌کند. + - **تشخیص‌های Plugin**: هر هشدار یا خطای زمان بارگذاری صادرشده توسط رجیستری Plugin را نمایان می‌کند. - - دکتر بررسی می‌کند که آیا فایل‌های bootstrap workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا فایل‌های زمینه تزریق‌شده دیگر) نزدیک یا بالاتر از بودجه کاراکتر پیکربندی‌شده هستند یا نه. برای هر فایل شمار خام در برابر شمار کاراکترهای تزریق‌شده، درصد truncation، علت truncation (`max/file` یا `max/total`)، و کل کاراکترهای تزریق‌شده به‌عنوان کسری از بودجه کل را گزارش می‌دهد. وقتی فایل‌ها truncate شده باشند یا نزدیک حد باشند، دکتر نکته‌هایی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند. + + Doctor بررسی می‌کند که آیا فایل‌های bootstrap workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا دیگر فایل‌های زمینهٔ تزریق‌شده) نزدیک یا فراتر از بودجهٔ کاراکتر پیکربندی‌شده هستند یا نه. شمارش کاراکتر خام در برابر تزریق‌شده، درصد truncation، علت truncation (`max/file` یا `max/total`)، و مجموع کاراکترهای تزریق‌شده به‌عنوان کسری از بودجهٔ کل را برای هر فایل گزارش می‌دهد. وقتی فایل‌ها truncate شده باشند یا نزدیک حد باشند، Doctor نکته‌هایی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند. - - وقتی `openclaw doctor --fix` یک Plugin کانال گم‌شده را حذف می‌کند، پیکربندی آویزانِ محدود به کانال را که به آن Plugin ارجاع داده بود نیز حذف می‌کند: ورودی‌های `channels.`، هدف‌های Heartbeat که نام کانال را برده‌اند، و overrideهای `agents.*.models["/*"]`. این از loopهای boot در Gateway جلوگیری می‌کند که در آن runtime کانال از بین رفته اما پیکربندی هنوز از gateway می‌خواهد به آن bind شود. + + وقتی `openclaw doctor --fix` یک Plugin کانال مفقود را حذف می‌کند، پیکربندی dangling محدود به کانال را هم که به آن Plugin ارجاع می‌داد حذف می‌کند: ورودی‌های `channels.`، هدف‌های Heartbeat که کانال را نام برده بودند، و overrideهای `agents.*.models["/*"]`. این کار از حلقه‌های boot Gateway جلوگیری می‌کند که در آن runtime کانال رفته اما پیکربندی هنوز از gateway می‌خواهد به آن bind شود. - دکتر بررسی می‌کند آیا تکمیل tab برای shell فعلی نصب شده است یا نه (zsh، bash، fish، یا PowerShell): + Doctor بررسی می‌کند که آیا تکمیل tab برای shell فعلی (zsh، bash، fish، یا PowerShell) نصب شده است یا نه: - - اگر پروفایل shell از الگوی تکمیل پویای کند (`source <(openclaw completion ...)`) استفاده کند، دکتر آن را به گونه سریع‌تر فایل cache‌شده ارتقا می‌دهد. - - اگر تکمیل در پروفایل پیکربندی شده باشد اما فایل cache موجود نباشد، دکتر cache را به‌طور خودکار دوباره تولید می‌کند. - - اگر هیچ تکمیلی اصلاً پیکربندی نشده باشد، دکتر درخواست نصب آن را می‌دهد (فقط حالت تعاملی؛ با `--non-interactive` رد می‌شود). + - اگر پروفایل shell از الگوی تکمیل دینامیک کند (`source <(openclaw completion ...)`) استفاده کند، Doctor آن را به گونهٔ فایل cache‌شدهٔ سریع‌تر ارتقا می‌دهد. + - اگر تکمیل در پروفایل پیکربندی شده باشد اما فایل cache موجود نباشد، Doctor cache را خودکار دوباره تولید می‌کند. + - اگر هیچ تکمیلی اصلاً پیکربندی نشده باشد، Doctor درخواست نصب آن را می‌دهد (فقط حالت تعاملی؛ با `--non-interactive` رد می‌شود). - برای تولید دوباره cache به‌صورت دستی، `openclaw completion --write-state` را اجرا کنید. + برای تولید دوبارهٔ دستی cache، `openclaw completion --write-state` را اجرا کنید. - دکتر آمادگی احراز هویت توکن Gateway محلی را بررسی می‌کند. + Doctor آمادگی احراز هویت توکن محلی gateway را بررسی می‌کند. - - اگر حالت توکن به توکن نیاز داشته باشد و هیچ منبع توکنی وجود نداشته باشد، دکتر پیشنهاد تولید یکی را می‌دهد. - - اگر `gateway.auth.token` توسط SecretRef مدیریت شود اما در دسترس نباشد، دکتر هشدار می‌دهد و آن را با plaintext بازنویسی نمی‌کند. - - `openclaw doctor --generate-gateway-token` فقط وقتی هیچ token SecretRef پیکربندی نشده باشد، تولید را اجباری می‌کند. + - اگر حالت توکن به توکن نیاز داشته باشد و هیچ منبع توکنی وجود نداشته باشد، Doctor پیشنهاد تولید یکی را می‌دهد. + - اگر `gateway.auth.token` توسط SecretRef مدیریت شود اما در دسترس نباشد، Doctor هشدار می‌دهد و آن را با plaintext بازنویسی نمی‌کند. + - `openclaw doctor --generate-gateway-token` فقط وقتی هیچ SecretRef توکنی پیکربندی نشده باشد، تولید را اجباری می‌کند. - - برخی جریان‌های ترمیم باید اعتبارنامه‌های پیکربندی‌شده را بدون تضعیف رفتار fail-fast زمان اجرا بررسی کنند. + + برخی جریان‌های ترمیم باید اعتبارنامه‌های پیکربندی‌شده را بدون ضعیف کردن رفتار fail-fast زمان اجرا بررسی کنند. - - `openclaw doctor --fix` اکنون از همان مدل خلاصه فقط‌خواندنی SecretRef مانند دستورهای خانواده status برای ترمیم‌های هدفمند پیکربندی استفاده می‌کند. - - مثال: ترمیم `allowFrom` / `groupAllowFrom` `@username` در Telegram تلاش می‌کند وقتی اعتبارنامه‌های bot پیکربندی‌شده در دسترس باشند، از آن‌ها استفاده کند. - - اگر توکن bot در Telegram از طریق SecretRef پیکربندی شده باشد اما در مسیر دستور فعلی در دسترس نباشد، دکتر گزارش می‌دهد که اعتبارنامه پیکربندی‌شده-اما-در‌دسترس‌نیست است و به‌جای کرش کردن یا گزارش اشتباه توکن به‌عنوان گم‌شده، auto-resolution را رد می‌کند. + - `openclaw doctor --fix` اکنون برای تعمیرهای هدفمند پیکربندی از همان مدل خلاصهٔ SecretRef فقط-خواندنی استفاده می‌کند که دستورهای خانوادهٔ status استفاده می‌کنند. + - مثال: تعمیر Telegram `allowFrom` / `groupAllowFrom` `@username` در صورت وجود، تلاش می‌کند از اعتبارنامه‌های بات پیکربندی‌شده استفاده کند. + - اگر توکن بات Telegram از طریق SecretRef پیکربندی شده باشد اما در مسیر دستور فعلی در دسترس نباشد، doctor گزارش می‌دهد که اعتبارنامه پیکربندی‌شده-اما-ناموجود است و به‌جای خرابی یا گزارش نادرستِ نبودن توکن، حل خودکار را رد می‌کند. - doctor یک بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد راه‌اندازی مجدد آن را می‌دهد. + Doctor یک بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد راه‌اندازی مجدد آن را می‌دهد. - - doctor بررسی می‌کند که آیا ارائه‌دهنده تعبیه‌سازی جستجوی حافظه پیکربندی‌شده برای عامل پیش‌فرض آماده است یا نه. رفتار به پشتیبان و ارائه‌دهنده پیکربندی‌شده بستگی دارد: + + Doctor بررسی می‌کند که آیا ارائه‌دهندهٔ embedding جست‌وجوی حافظهٔ پیکربندی‌شده برای عامل پیش‌فرض آماده است یا نه. رفتار به backend و ارائه‌دهندهٔ پیکربندی‌شده بستگی دارد: - - **پشتیبان QMD**: بررسی می‌کند که آیا باینری `qmd` در دسترس و قابل شروع است یا نه. اگر نباشد، راهنمای رفع مشکل را شامل بسته npm و گزینه مسیر دستی باینری چاپ می‌کند. - - **ارائه‌دهنده محلی صریح**: وجود فایل مدل محلی یا URL مدل دوردست/قابل دانلود شناخته‌شده را بررسی می‌کند. اگر موجود نباشد، پیشنهاد می‌کند به یک ارائه‌دهنده دوردست تغییر دهید. - - **ارائه‌دهنده دوردست صریح** (`openai`، `voyage` و غیره): بررسی می‌کند که یک کلید API در محیط یا مخزن احراز هویت وجود داشته باشد. اگر موجود نباشد، راهنمایی‌های قابل اقدام برای رفع مشکل چاپ می‌کند. - - **ارائه‌دهنده خودکار**: ابتدا دسترس‌پذیری مدل محلی را بررسی می‌کند، سپس هر ارائه‌دهنده دوردست را به ترتیب انتخاب خودکار امتحان می‌کند. + - **backend QMD**: بررسی می‌کند که آیا باینری `qmd` موجود و قابل شروع است یا نه. اگر نباشد، راهنمایی رفع مشکل شامل بستهٔ npm و گزینهٔ مسیر دستی باینری را چاپ می‌کند. + - **ارائه‌دهندهٔ محلی صریح**: وجود یک فایل مدل محلی یا یک URL مدل راه‌دور/قابل‌دانلودِ شناخته‌شده را بررسی می‌کند. اگر موجود نباشد، پیشنهاد می‌کند به یک ارائه‌دهندهٔ راه‌دور تغییر دهید. + - **ارائه‌دهندهٔ راه‌دور صریح** (`openai`، `voyage` و غیره): وجود کلید API در محیط یا ذخیره‌گاه احراز هویت را تأیید می‌کند. اگر موجود نباشد، راهنمایی‌های عملی برای رفع مشکل چاپ می‌کند. + - **ارائه‌دهندهٔ خودکار**: ابتدا موجود بودن مدل محلی را بررسی می‌کند، سپس هر ارائه‌دهندهٔ راه‌دور را به‌ترتیب انتخاب خودکار امتحان می‌کند. - وقتی نتیجه بررسی Gateway در حافظه نهان موجود باشد (Gateway هنگام بررسی سالم بوده است)، doctor نتیجه آن را با پیکربندی قابل مشاهده برای CLI تطبیق می‌دهد و هرگونه مغایرت را یادآوری می‌کند. doctor در مسیر پیش‌فرض یک ping تازه برای تعبیه‌سازی شروع نمی‌کند؛ وقتی بررسی زنده ارائه‌دهنده را می‌خواهید، از فرمان وضعیت عمیق حافظه استفاده کنید. + وقتی نتیجهٔ probe کش‌شدهٔ Gateway موجود باشد (Gateway در زمان بررسی سالم بوده)، doctor نتیجهٔ آن را با پیکربندی قابل‌مشاهده برای CLI تطبیق می‌دهد و هرگونه ناهمخوانی را یادآوری می‌کند. Doctor در مسیر پیش‌فرض ping تازهٔ embedding را شروع نمی‌کند؛ وقتی بررسی زندهٔ ارائه‌دهنده می‌خواهید، از دستور وضعیت عمیق حافظه استفاده کنید. - از `openclaw memory status --deep` برای تأیید آمادگی تعبیه‌سازی در زمان اجرا استفاده کنید. + از `openclaw memory status --deep` برای تأیید آمادگی embedding در زمان اجرا استفاده کنید. - اگر Gateway سالم باشد، doctor یک بررسی وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌دهد. + اگر Gateway سالم باشد، doctor یک probe وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌دهد. - - doctor پیکربندی ناظر نصب‌شده (launchd/systemd/schtasks) را برای پیش‌فرض‌های جاافتاده یا قدیمی (برای مثال، وابستگی‌های systemd به network-online و تأخیر راه‌اندازی مجدد) بررسی می‌کند. وقتی ناهماهنگی پیدا کند، به‌روزرسانی را توصیه می‌کند و می‌تواند فایل سرویس/وظیفه را با پیش‌فرض‌های فعلی بازنویسی کند. + + Doctor پیکربندی supervisor نصب‌شده (launchd/systemd/schtasks) را برای پیش‌فرض‌های جاافتاده یا قدیمی (برای مثال وابستگی‌های network-online در systemd و تأخیر راه‌اندازی مجدد) بررسی می‌کند. وقتی ناهمخوانی پیدا کند، به‌روزرسانی را توصیه می‌کند و می‌تواند فایل service/task را مطابق پیش‌فرض‌های فعلی بازنویسی کند. نکته‌ها: - - `openclaw doctor` پیش از بازنویسی پیکربندی ناظر درخواست تأیید می‌کند. - - `openclaw doctor --yes` درخواست‌های تعمیر پیش‌فرض را می‌پذیرد. - - `openclaw doctor --repair` رفع‌های توصیه‌شده را بدون درخواست تأیید اعمال می‌کند. - - `openclaw doctor --repair --force` پیکربندی‌های سفارشی ناظر را بازنویسی می‌کند. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` برای چرخه عمر سرویس Gateway، doctor را فقط‌خواندنی نگه می‌دارد. همچنان سلامت سرویس را گزارش می‌دهد و تعمیرهای غیرسرویسی را اجرا می‌کند، اما نصب/شروع/راه‌اندازی مجدد/bootstrap سرویس، بازنویسی‌های پیکربندی ناظر، و پاک‌سازی سرویس قدیمی را رد می‌کند، چون یک ناظر خارجی مالک آن چرخه عمر است. - - در Linux، doctor تا زمانی که واحد systemd Gateway مطابق فعال است، فراداده فرمان/نقطه ورود را بازنویسی نمی‌کند. همچنین هنگام اسکن سرویس تکراری، واحدهای اضافی غیرفعال و غیرقدیمیِ شبیه Gateway را نادیده می‌گیرد تا فایل‌های سرویس همراه نویز پاک‌سازی ایجاد نکنند. - - اگر احراز هویت توکنی به توکن نیاز داشته باشد و `gateway.auth.token` توسط SecretRef مدیریت شود، نصب/تعمیر سرویس doctor، SecretRef را اعتبارسنجی می‌کند اما مقدارهای توکن متن ساده حل‌شده را در فراداده محیط سرویس ناظر ماندگار نمی‌کند. - - doctor مقدارهای محیط سرویس مدیریت‌شده و مبتنی بر `.env`/SecretRef را که نصب‌های قدیمی‌تر LaunchAgent، systemd، یا Windows Scheduled Task به‌صورت درون‌خطی جاسازی کرده‌اند شناسایی می‌کند و فراداده سرویس را بازنویسی می‌کند تا آن مقدارها به‌جای تعریف ناظر، از منبع زمان اجرا بارگذاری شوند. - - doctor تشخیص می‌دهد چه زمانی فرمان سرویس پس از تغییر `gateway.port` هنوز یک `--port` قدیمی را ثابت نگه داشته است و فراداده سرویس را به درگاه فعلی بازنویسی می‌کند. - - اگر احراز هویت توکنی به توکن نیاز داشته باشد و SecretRef توکن پیکربندی‌شده حل نشده باشد، doctor مسیر نصب/تعمیر را با راهنمایی قابل اقدام مسدود می‌کند. - - اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، doctor نصب/تعمیر را تا زمانی که mode به‌صورت صریح تنظیم شود مسدود می‌کند. - - برای واحدهای user-systemd در Linux، بررسی‌های انحراف توکن doctor اکنون هنگام مقایسه فراداده احراز هویت سرویس، هر دو منبع `Environment=` و `EnvironmentFile=` را شامل می‌شود. - - تعمیرهای سرویس doctor از بازنویسی، توقف، یا راه‌اندازی مجدد سرویس Gateway از یک باینری قدیمی‌تر OpenClaw خودداری می‌کنند وقتی پیکربندی آخرین بار توسط نسخه‌ای جدیدتر نوشته شده باشد. [عیب‌یابی Gateway](/fa/gateway/troubleshooting#split-brain-installs-and-newer-config-guard) را ببینید. - - همیشه می‌توانید بازنویسی کامل را از طریق `openclaw gateway install --force` اجباری کنید. + - `openclaw doctor` پیش از بازنویسی پیکربندی supervisor درخواست تأیید می‌کند. + - `openclaw doctor --yes` promptهای تعمیر پیش‌فرض را می‌پذیرد. + - `openclaw doctor --repair` رفع‌های پیشنهادی را بدون prompt اعمال می‌کند. + - `openclaw doctor --repair --force` پیکربندی‌های سفارشی supervisor را بازنویسی می‌کند. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` برای چرخهٔ حیات سرویس Gateway، doctor را فقط-خواندنی نگه می‌دارد. همچنان سلامت سرویس را گزارش می‌دهد و تعمیرهای غیرسرویسی را اجرا می‌کند، اما نصب/شروع/راه‌اندازی مجدد/bootstrap سرویس، بازنویسی پیکربندی supervisor، و پاک‌سازی سرویس قدیمی را رد می‌کند، چون یک supervisor خارجی مالک آن چرخهٔ حیات است. + - در Linux، تا وقتی unit مطابق Gateway در systemd فعال است، doctor فرادادهٔ command/entrypoint را بازنویسی نمی‌کند. همچنین هنگام اسکن سرویس تکراری، unitهای اضافی غیرفعالِ شبیه Gateway و غیرقدیمی را نادیده می‌گیرد تا فایل‌های سرویس همراه باعث نویز پاک‌سازی نشوند. + - اگر احراز هویت توکنی به توکن نیاز داشته باشد و `gateway.auth.token` با SecretRef مدیریت شود، نصب/تعمیر سرویس doctor، SecretRef را اعتبارسنجی می‌کند اما مقدارهای plaintext توکنِ حل‌شده را در فرادادهٔ محیط سرویس supervisor پایدار نمی‌کند. + - Doctor مقدارهای محیط سرویس مدیریت‌شدهٔ مبتنی بر `.env`/SecretRef را که نصب‌های قدیمی‌تر LaunchAgent، systemd، یا Windows Scheduled Task به‌صورت inline جاسازی کرده‌اند شناسایی می‌کند و فرادادهٔ سرویس را بازنویسی می‌کند تا آن مقدارها به‌جای تعریف supervisor از منبع زمان اجرا بارگیری شوند. + - Doctor تشخیص می‌دهد که دستور سرویس هنوز پس از تغییر `gateway.port` یک `--port` قدیمی را pin کرده است و فرادادهٔ سرویس را به port فعلی بازنویسی می‌کند. + - اگر احراز هویت توکنی به توکن نیاز داشته باشد و SecretRef توکن پیکربندی‌شده حل‌نشده باشد، doctor مسیر نصب/تعمیر را با راهنمایی عملی مسدود می‌کند. + - اگر هر دو `gateway.auth.token` و `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، doctor نصب/تعمیر را تا زمانی که mode صریحاً تنظیم شود مسدود می‌کند. + - برای unitهای user-systemd در Linux، بررسی‌های drift توکن در doctor اکنون هنگام مقایسهٔ فرادادهٔ احراز هویت سرویس، هر دو منبع `Environment=` و `EnvironmentFile=` را شامل می‌شود. + - تعمیرهای سرویس doctor از بازنویسی، توقف، یا راه‌اندازی مجدد سرویس Gateway از یک باینری قدیمی‌تر OpenClaw خودداری می‌کنند، وقتی پیکربندی آخرین بار با نسخه‌ای جدیدتر نوشته شده باشد. [عیب‌یابی Gateway](/fa/gateway/troubleshooting#split-brain-installs-and-newer-config-guard) را ببینید. + - همیشه می‌توانید از طریق `openclaw gateway install --force` یک بازنویسی کامل را اجبار کنید. - - doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و وقتی سرویس نصب شده اما واقعاً در حال اجرا نیست هشدار می‌دهد. همچنین تداخل‌های درگاه روی درگاه Gateway (پیش‌فرض `18789`) را بررسی می‌کند و علت‌های محتمل (Gateway از قبل در حال اجرا است، تونل SSH) را گزارش می‌دهد. + + Doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و وقتی سرویس نصب شده اما واقعاً در حال اجرا نیست، هشدار می‌دهد. همچنین برخوردهای port روی port مربوط به Gateway (پیش‌فرض `18789`) را بررسی می‌کند و علت‌های محتمل (Gateway از قبل در حال اجراست، SSH tunnel) را گزارش می‌دهد. - doctor وقتی سرویس Gateway روی Bun یا مسیر Node مدیریت‌شده با نسخه (`nvm`، `fnm`، `volta`، `asdf` و غیره) اجرا می‌شود هشدار می‌دهد. کانال‌های WhatsApp + Telegram به Node نیاز دارند، و مسیرهای مدیر نسخه می‌توانند پس از ارتقا خراب شوند چون سرویس راه‌انداز shell شما را بارگذاری نمی‌کند. doctor پیشنهاد می‌کند در صورت دسترس بودن نصب Node سیستمی (Homebrew/apt/choco)، به آن مهاجرت کنید. + Doctor وقتی سرویس Gateway روی Bun یا یک مسیر Node مدیریت‌شده با نسخه (`nvm`، `fnm`، `volta`، `asdf` و غیره) اجرا شود هشدار می‌دهد. کانال‌های WhatsApp + Telegram به Node نیاز دارند، و مسیرهای version-manager می‌توانند پس از ارتقا خراب شوند چون سرویس init شل شما را بارگیری نمی‌کند. Doctor پیشنهاد می‌کند در صورت موجود بودن، به نصب سیستمی Node مهاجرت کنید (Homebrew/apt/choco). - LaunchAgentهای macOS که تازه نصب یا تعمیر شده‌اند به‌جای کپی کردن PATH تعاملی shell، از یک PATH سیستمی کانونی (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) استفاده می‌کنند، بنابراین Volta، asdf، fnm، pnpm و دیگر دایرکتوری‌های مدیر نسخه تغییر نمی‌دهند که فرایندهای فرزند Node به کدام مورد resolve شوند. سرویس‌های Linux همچنان ریشه‌های محیطی صریح (`NVM_DIR`، `FNM_DIR`، `VOLTA_HOME`، `ASDF_DATA_DIR`، `BUN_INSTALL`، `PNPM_HOME`) و دایرکتوری‌های پایدار user-bin را نگه می‌دارند، اما دایرکتوری‌های fallback حدس‌زده‌شده مدیر نسخه فقط وقتی آن دایرکتوری‌ها روی دیسک وجود داشته باشند در PATH سرویس نوشته می‌شوند. + LaunchAgentهای macOS که تازه نصب یا تعمیر شده‌اند، به‌جای کپی کردن PATH شل تعاملی، از یک PATH سیستمی canonical (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) استفاده می‌کنند، بنابراین دایرکتوری‌های Volta، asdf، fnm، pnpm و سایر version-managerها اینکه کدام فرایندهای فرزند Node resolve شوند را تغییر نمی‌دهند. سرویس‌های Linux همچنان ریشه‌های محیطی صریح (`NVM_DIR`، `FNM_DIR`، `VOLTA_HOME`، `ASDF_DATA_DIR`، `BUN_INSTALL`، `PNPM_HOME`) و دایرکتوری‌های user-bin پایدار را نگه می‌دارند، اما دایرکتوری‌های fallback حدس‌زده‌شدهٔ version-manager فقط وقتی روی دیسک وجود داشته باشند در PATH سرویس نوشته می‌شوند. - - doctor هرگونه تغییر پیکربندی را ماندگار می‌کند و فراداده جادوگر را مهر می‌زند تا اجرای doctor ثبت شود. + + Doctor هر تغییر پیکربندی را پایدار می‌کند و فرادادهٔ wizard را برای ثبت اجرای doctor مهر می‌زند. - - doctor وقتی سیستم حافظه فضای کاری وجود ندارد آن را پیشنهاد می‌کند و اگر فضای کاری از قبل زیر git نباشد، یک نکته پشتیبان‌گیری چاپ می‌کند. + + Doctor وقتی سامانهٔ حافظهٔ workspace موجود نباشد آن را پیشنهاد می‌کند و اگر workspace از قبل زیر git نباشد، یک نکتهٔ پشتیبان‌گیری چاپ می‌کند. - برای راهنمای کامل ساختار فضای کاری و پشتیبان‌گیری git (GitHub یا GitLab خصوصی توصیه می‌شود)، [/concepts/agent-workspace](/fa/concepts/agent-workspace) را ببینید. + برای راهنمای کامل ساختار workspace و پشتیبان‌گیری git (GitHub یا GitLab خصوصی توصیه می‌شود)، [/concepts/agent-workspace](/fa/concepts/agent-workspace) را ببینید. ## مرتبط -- [دفترچه اجرای Gateway](/fa/gateway) +- [runbook مربوط به Gateway](/fa/gateway) - [عیب‌یابی Gateway](/fa/gateway/troubleshooting) diff --git a/docs/fa/gateway/logging.md b/docs/fa/gateway/logging.md index 223348f64..66fb17eb3 100644 --- a/docs/fa/gateway/logging.md +++ b/docs/fa/gateway/logging.md @@ -2,93 +2,117 @@ read_when: - تغییر خروجی یا قالب‌های لاگ‌گیری - اشکال‌زدایی خروجی CLI یا Gateway -summary: سطوح ثبت گزارش، گزارش‌های فایلی، سبک‌های گزارش WS، و قالب‌بندی کنسول -title: لاگ‌گیری Gateway +summary: سطوح لاگ‌گیری، لاگ‌های فایل، سبک‌های لاگ WS و قالب‌بندی کنسول +title: ثبت لاگ Gateway x-i18n: - generated_at: "2026-05-02T11:46:38Z" + generated_at: "2026-05-05T01:47:24Z" model: gpt-5.5 provider: openai - source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13 + source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246 source_path: gateway/logging.md workflow: 16 --- -# ثبت وقایع +# ثبت لاگ -برای نمای کلی کاربرمحور (CLI + رابط کاربری کنترل + پیکربندی)، به [/logging](/fa/logging) مراجعه کنید. +برای نمای کلیِ کاربرمحور (CLI + Control UI + پیکربندی)، [/logging](/fa/logging) را ببینید. -OpenClaw دو «سطح» ثبت وقایع دارد: +OpenClaw دو «سطح» ثبت لاگ دارد: -- **خروجی کنسول** (آنچه در ترمینال / رابط کاربری اشکال‌زدایی می‌بینید). -- **گزارش‌های فایلی** (خطوط JSON) که توسط ثبت‌کننده Gateway نوشته می‌شوند. +- **خروجی کنسول** (آنچه در ترمینال / Debug UI می‌بینید). +- **لاگ‌های فایل** (خطوط JSON) که توسط ثبت‌کنندهٔ لاگ Gateway نوشته می‌شوند. -## ثبت‌کننده مبتنی بر فایل +هنگام راه‌اندازی، Gateway مدل پیش‌فرض عاملِ حل‌شده را همراه با پیش‌فرض‌های +حالتی که روی نشست‌های جدید اثر می‌گذارند ثبت می‌کند، برای مثال: -- فایل گزارش چرخشی پیش‌فرض زیر `/tmp/openclaw/` است (یک فایل برای هر روز): `openclaw-YYYY-MM-DD.log` - - تاریخ از منطقه زمانی محلی میزبان Gateway استفاده می‌کند. -- فایل‌های گزارش فعال در `logging.maxFileBytes` (پیش‌فرض: 100 MB) چرخش می‌کنند، تا پنج آرشیو شماره‌گذاری‌شده نگه می‌دارند و نوشتن در یک فایل فعال تازه را ادامه می‌دهند. -- مسیر و سطح فایل گزارش را می‌توان از طریق `~/.openclaw/openclaw.json` پیکربندی کرد: +```text +agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on) +``` + +`thinking` از عامل پیش‌فرض، پارامترهای مدل، یا پیش‌فرض سراسری عامل می‌آید؛ +وقتی تنظیم نشده باشد، خلاصهٔ راه‌اندازی `medium` را نشان می‌دهد. `fast` از عامل +پیش‌فرض یا پارامترهای `fastMode` مدل می‌آید. + +## ثبت‌کنندهٔ لاگ مبتنی بر فایل + +- فایل لاگ چرخشی پیش‌فرض زیر `/tmp/openclaw/` است (یک فایل برای هر روز): `openclaw-YYYY-MM-DD.log` + - تاریخ از منطقهٔ زمانی محلی میزبان Gateway استفاده می‌کند. +- فایل‌های لاگ فعال در `logging.maxFileBytes` می‌چرخند (پیش‌فرض: 100 MB)، تا + پنج آرشیو شماره‌دار را نگه می‌دارند و نوشتن در یک فایل فعال تازه را ادامه می‌دهند. +- مسیر و سطح فایل لاگ را می‌توان از طریق `~/.openclaw/openclaw.json` پیکربندی کرد: - `logging.file` - `logging.level` قالب فایل، یک شیء JSON در هر خط است. -زبانه گزارش‌های رابط کاربری کنترل این فایل را از طریق Gateway دنبال می‌کند (`logs.tail`). -CLI هم می‌تواند همین کار را انجام دهد: +زبانهٔ Logs در Control UI این فایل را از طریق Gateway دنبال می‌کند (`logs.tail`). +CLI نیز می‌تواند همین کار را انجام دهد: ```bash openclaw logs --follow ``` -**جزئیات بیشتر در برابر سطح‌های گزارش** +**جزئیات بیشتر در برابر سطح‌های لاگ** -- **گزارش‌های فایلی** منحصراً با `logging.level` کنترل می‌شوند. -- `--verbose` فقط روی **پرحرفی کنسول** (و سبک گزارش WS) اثر می‌گذارد؛ سطح گزارش فایلی را بالا نمی‌برد. -- برای ثبت جزئیات فقط-verbose در گزارش‌های فایلی، `logging.level` را روی `debug` یا `trace` تنظیم کنید. -- ثبت وقایع Trace همچنین خلاصه‌های زمان‌بندی تشخیصی را برای مسیرهای داغ منتخب، مانند آماده‌سازی کارخانه ابزار Plugin، شامل می‌شود. [/tools/plugin#slow-plugin-tool-setup](/fa/tools/plugin#slow-plugin-tool-setup) را ببینید. +- **لاگ‌های فایل** منحصراً با `logging.level` کنترل می‌شوند. +- `--verbose` فقط روی **جزئیات خروجی کنسول** (و سبک لاگ WS) اثر می‌گذارد؛ سطح لاگ فایل را + افزایش **نمی‌دهد**. +- برای ثبت جزئیاتی که فقط در حالت verbose می‌آیند در لاگ‌های فایل، `logging.level` را روی `debug` یا + `trace` تنظیم کنید. +- ثبت لاگ Trace همچنین شامل خلاصه‌های زمان‌بندی تشخیصی برای مسیرهای داغ منتخب است، + مانند آماده‌سازی کارخانهٔ ابزار Plugin. ببینید: + [/tools/plugin#slow-plugin-tool-setup](/fa/tools/plugin#slow-plugin-tool-setup). -## ضبط کنسول +## گرفتن خروجی کنسول -CLI خروجی‌های `console.log/info/warn/error/debug/trace` را ضبط می‌کند و در گزارش‌های فایلی می‌نویسد، در حالی که همچنان در stdout/stderr چاپ می‌کند. +CLI خروجی‌های `console.log/info/warn/error/debug/trace` را می‌گیرد و در لاگ‌های فایل می‌نویسد، +در حالی که همچنان در stdout/stderr چاپ می‌کند. -می‌توانید پرحرفی کنسول را مستقل تنظیم کنید از طریق: +می‌توانید جزئیات خروجی کنسول را مستقل تنظیم کنید از طریق: - `logging.consoleLevel` (پیش‌فرض `info`) - `logging.consoleStyle` (`pretty` | `compact` | `json`) -## ویرایش محرمانه +## پوشاندن داده‌های حساس -OpenClaw می‌تواند توکن‌های حساس را پیش از خروجی گرفتن گزارش یا رونوشت از فرایند، پوشانده کند. این سیاست ویرایش محرمانه ثبت وقایع روی خروجی‌های کنسول، گزارش فایلی، رکورد گزارش OTLP، و متن رونوشت نشست اعمال می‌شود؛ بنابراین مقدارهای محرمانه منطبق پیش از نوشته شدن خطوط JSONL یا پیام‌ها روی دیسک پوشانده می‌شوند. +OpenClaw می‌تواند توکن‌های حساس را پیش از خروج لاگ یا متن رونوشت از +فرایند ماسک کند. این سیاست پوشاندن داده‌های حساس در ثبت لاگ روی مقصدهای متنی کنسول، +لاگ فایل، رکورد لاگ OTLP و رونوشت نشست اعمال می‌شود، بنابراین مقدارهای محرمانهٔ منطبق +پیش از نوشته‌شدن خطوط JSONL یا پیام‌ها روی دیسک ماسک می‌شوند. - `logging.redactSensitive`: `off` | `tools` (پیش‌فرض: `tools`) - `logging.redactPatterns`: آرایه‌ای از رشته‌های regex (پیش‌فرض‌ها را بازنویسی می‌کند) - - از رشته‌های regex خام (خودکار `gi`) استفاده کنید، یا اگر پرچم‌های سفارشی لازم دارید از `/pattern/flags` استفاده کنید. - - تطابق‌ها با نگه داشتن 6 نویسه اول + 4 نویسه آخر پوشانده می‌شوند (طول >= 18)، وگرنه `***`. - - پیش‌فرض‌ها انتساب‌های کلید رایج، پرچم‌های CLI، فیلدهای JSON، سربرگ‌های bearer، بلوک‌های PEM، پیشوندهای توکن محبوب، و نام فیلدهای اعتبارنامه پرداخت مانند شماره کارت، CVC/CVV، توکن پرداخت مشترک، و اعتبارنامه پرداخت را پوشش می‌دهند. + - از رشته‌های regex خام (به‌صورت خودکار `gi`) استفاده کنید، یا اگر به فلگ‌های سفارشی نیاز دارید از `/pattern/flags`. + - موارد منطبق با نگه‌داشتن 6 نویسهٔ اول + 4 نویسهٔ آخر ماسک می‌شوند (طول >= 18)، در غیر این صورت `***`. + - پیش‌فرض‌ها انتساب‌های رایج کلید، فلگ‌های CLI، فیلدهای JSON، سرآیندهای bearer، بلوک‌های PEM، پیشوندهای رایج توکن، و نام فیلدهای اطلاعات پرداخت مانند شمارهٔ کارت، CVC/CVV، توکن پرداخت مشترک، و اطلاعات پرداخت را پوشش می‌دهند. -برخی مرزهای ایمنی همیشه بدون توجه به `logging.redactSensitive` ویرایش محرمانه می‌شوند. -این شامل رویدادهای فراخوانی ابزار رابط کاربری کنترل، خروجی ابزار `sessions_history`، خروجی‌های پشتیبانی تشخیصی، مشاهده‌های خطای provider، نمایش فرمان تأیید exec، و گزارش‌های پروتکل WebSocket Gateway است. این سطح‌ها ممکن است همچنان از `logging.redactPatterns` به‌عنوان الگوهای اضافی استفاده کنند، اما `redactSensitive: "off"` باعث نمی‌شود محرمانه‌های خام را منتشر کنند. +برخی مرزهای ایمنی همیشه، فارغ از `logging.redactSensitive`، داده‌ها را می‌پوشانند. +این شامل رویدادهای فراخوانی ابزار در Control UI، خروجی ابزار `sessions_history`، +خروجی‌های پشتیبانی تشخیصی، مشاهده‌های خطای ارائه‌دهنده، نمایش فرمان تأیید exec، +و لاگ‌های پروتکل WebSocket در Gateway است. این سطوح همچنان ممکن است از +`logging.redactPatterns` به‌عنوان الگوهای اضافی استفاده کنند، اما `redactSensitive: "off"` +باعث نمی‌شود رازهای خام را منتشر کنند. -## گزارش‌های WebSocket Gateway +## لاگ‌های WebSocket در Gateway -Gateway گزارش‌های پروتکل WebSocket را در دو حالت چاپ می‌کند: +Gateway لاگ‌های پروتکل WebSocket را در دو حالت چاپ می‌کند: - **حالت عادی (بدون `--verbose`)**: فقط نتایج RPC «جالب» چاپ می‌شوند: - خطاها (`ok=false`) - - فراخوانی‌های کند (آستانه پیش‌فرض: `>= 50ms`) + - فراخوانی‌های کند (آستانهٔ پیش‌فرض: `>= 50ms`) - خطاهای parse -- **حالت verbose (`--verbose`)**: همه ترافیک درخواست/پاسخ WS را چاپ می‌کند. +- **حالت Verbose (`--verbose`)**: همهٔ ترافیک درخواست/پاسخ WS را چاپ می‌کند. -### سبک گزارش WS +### سبک لاگ WS `openclaw gateway` از یک سوییچ سبک برای هر Gateway پشتیبانی می‌کند: -- `--ws-log auto` (پیش‌فرض): حالت عادی بهینه‌سازی شده است؛ حالت verbose از خروجی فشرده استفاده می‌کند +- `--ws-log auto` (پیش‌فرض): حالت عادی بهینه است؛ حالت verbose از خروجی فشرده استفاده می‌کند - `--ws-log compact`: خروجی فشرده (درخواست/پاسخ جفت‌شده) هنگام verbose -- `--ws-log full`: خروجی کامل برای هر frame هنگام verbose +- `--ws-log full`: خروجی کامل برای هر فریم هنگام verbose - `--compact`: نام مستعار برای `--ws-log compact` -نمونه‌ها: +مثال‌ها: ```bash # optimized (only errors/slow) @@ -101,27 +125,27 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## قالب‌بندی کنسول (ثبت وقایع زیرسامانه) +## قالب‌بندی کنسول (ثبت لاگ زیرسامانه) -قالب‌ساز کنسول **آگاه به TTY** است و خط‌های سازگار و دارای پیشوند چاپ می‌کند. -ثبت‌کننده‌های زیرسامانه خروجی را گروه‌بندی‌شده و قابل اسکن نگه می‌دارند. +قالب‌بند کنسول **از TTY آگاه است** و خط‌های سازگار و پیشونددار چاپ می‌کند. +ثبت‌کننده‌های لاگ زیرسامانه خروجی را گروه‌بندی‌شده و قابل اسکن نگه می‌دارند. رفتار: -- **پیشوندهای زیرسامانه** روی هر خط (مثلاً `[gateway]`، `[canvas]`، `[tailscale]`) +- **پیشوندهای زیرسامانه** در هر خط (برای مثال `[gateway]`، `[canvas]`، `[tailscale]`) - **رنگ‌های زیرسامانه** (پایدار برای هر زیرسامانه) به‌همراه رنگ‌بندی سطح -- **رنگ زمانی که خروجی TTY است یا محیط شبیه یک ترمینال غنی به نظر می‌رسد** (`TERM`/`COLORTERM`/`TERM_PROGRAM`)، با رعایت `NO_COLOR` -- **پیشوندهای کوتاه‌شده زیرسامانه**: `gateway/` + `channels/` ابتدایی را حذف می‌کند، 2 بخش آخر را نگه می‌دارد (مثلاً `whatsapp/outbound`) -- **زیرثبت‌کننده‌ها بر اساس زیرسامانه** (پیشوند خودکار + فیلد ساخت‌یافته `{ subsystem }`) +- **رنگ وقتی خروجی TTY باشد یا محیط شبیه یک ترمینال غنی باشد** (`TERM`/`COLORTERM`/`TERM_PROGRAM`)، با رعایت `NO_COLOR` +- **پیشوندهای کوتاه‌شدهٔ زیرسامانه**: `gateway/` + `channels/` ابتدایی را حذف می‌کند، 2 بخش آخر را نگه می‌دارد (برای مثال `whatsapp/outbound`) +- **زیرثبت‌کننده‌ها بر اساس زیرسامانه** (پیشوند خودکار + فیلد ساختاریافتهٔ `{ subsystem }`) - **`logRaw()`** برای خروجی QR/UX (بدون پیشوند، بدون قالب‌بندی) -- **سبک‌های کنسول** (مثلاً `pretty | compact | json`) -- **سطح گزارش کنسول** جدا از سطح گزارش فایلی (وقتی `logging.level` روی `debug`/`trace` تنظیم شده باشد، فایل جزئیات کامل را نگه می‌دارد) -- **بدنه پیام‌های WhatsApp** در `debug` ثبت می‌شوند (برای دیدن آن‌ها از `--verbose` استفاده کنید) +- **سبک‌های کنسول** (برای مثال `pretty | compact | json`) +- **سطح لاگ کنسول** جدا از سطح لاگ فایل (وقتی `logging.level` روی `debug`/`trace` تنظیم شده باشد، فایل جزئیات کامل را نگه می‌دارد) +- **بدنه‌های پیام WhatsApp** در سطح `debug` ثبت می‌شوند (برای دیدن آن‌ها از `--verbose` استفاده کنید) -این کار گزارش‌های فایلی موجود را پایدار نگه می‌دارد و در عین حال خروجی تعاملی را قابل اسکن می‌کند. +این کار لاگ‌های فایل موجود را پایدار نگه می‌دارد و در عین حال خروجی تعاملی را قابل اسکن می‌کند. ## مرتبط -- [ثبت وقایع](/fa/logging) +- [ثبت لاگ](/fa/logging) - [خروجی OpenTelemetry](/fa/gateway/opentelemetry) - [خروجی تشخیصی](/fa/gateway/diagnostics) diff --git a/docs/fa/help/debugging.md b/docs/fa/help/debugging.md index b359ac675..c9788d186 100644 --- a/docs/fa/help/debugging.md +++ b/docs/fa/help/debugging.md @@ -1,26 +1,26 @@ --- read_when: - باید خروجی خام مدل را برای نشت استدلال بررسی کنید - - می‌خواهید هنگام تکرار و اصلاح، Gateway را در حالت پایش اجرا کنید - - به یک گردش‌کار اشکال‌زدایی تکرارپذیر نیاز دارید + - می‌خواهید هنگام تکرار و اصلاح، Gateway را در حالت watch اجرا کنید + - به یک گردش‌کار تکرارپذیر برای اشکال‌زدایی نیاز دارید summary: 'ابزارهای اشکال‌زدایی: حالت پایش، جریان‌های خام مدل، و ردیابی نشت استدلال' title: اشکال‌زدایی x-i18n: - generated_at: "2026-05-03T21:36:03Z" + generated_at: "2026-05-05T01:48:31Z" model: gpt-5.5 provider: openai - source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc + source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec source_path: help/debugging.md workflow: 16 --- -کمک‌کننده‌های اشکال‌زدایی برای خروجی جریان، به‌ویژه وقتی یک ارائه‌دهنده استدلال را با متن عادی مخلوط می‌کند. +راهنماهای اشکال‌زدایی برای خروجی جریانی، به‌ویژه وقتی یک ارائه‌دهنده استدلال را با متن عادی مخلوط می‌کند. -## بازنویسی‌های اشکال‌زدایی زمان اجرا +## بازنویسی‌های اشکال‌زدایی در زمان اجرا -از `/debug` در چت استفاده کنید تا بازنویسی‌های پیکربندی **فقط در زمان اجرا** را تنظیم کنید (حافظه، نه دیسک). -`/debug` به‌صورت پیش‌فرض غیرفعال است؛ با `commands.debug: true` فعالش کنید. -این زمانی مفید است که لازم دارید تنظیمات کمتر شناخته‌شده را بدون ویرایش `openclaw.json` تغییر دهید. +از `/debug` در چت برای تنظیم بازنویسی‌های پیکربندی **فقط در زمان اجرا** استفاده کنید (در حافظه، نه روی دیسک). +`/debug` به‌طور پیش‌فرض غیرفعال است؛ با `commands.debug: true` فعالش کنید. +این زمانی مفید است که لازم دارید تنظیمات مبهم را بدون ویرایش `openclaw.json` تغییر دهید. نمونه‌ها: @@ -33,9 +33,9 @@ x-i18n: `/debug reset` همه بازنویسی‌ها را پاک می‌کند و به پیکربندی روی دیسک برمی‌گردد. -## خروجی ردگیری نشست +## خروجی ردیابی نشست -وقتی می‌خواهید خط‌های ردگیری/اشکال‌زدایی متعلق به Plugin را در یک نشست ببینید، +وقتی می‌خواهید خطوط ردیابی/اشکال‌زدایی متعلق به Plugin را در یک نشست ببینید، بدون اینکه حالت کامل پرجزئیات را روشن کنید، از `/trace` استفاده کنید. نمونه‌ها: @@ -47,15 +47,14 @@ x-i18n: ``` از `/trace` برای عیب‌یابی‌های Plugin مانند خلاصه‌های اشکال‌زدایی Active Memory استفاده کنید. -برای خروجی معمول وضعیت/ابزار پرجزئیات همچنان از `/verbose` استفاده کنید، و برای +برای خروجی عادی وضعیت/ابزار پرجزئیات همچنان از `/verbose` استفاده کنید، و برای بازنویسی‌های پیکربندی فقط در زمان اجرا همچنان از `/debug` استفاده کنید. -## ردگیری چرخه عمر Plugin +## ردیابی چرخه عمر Plugin وقتی فرمان‌های چرخه عمر Plugin کند به نظر می‌رسند و به یک تفکیک مرحله‌ای داخلی برای -فراداده Plugin، کشف، رجیستری، آینه زمان اجرا، تغییر پیکربندی، و کارهای نوسازی نیاز دارید، -از `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` استفاده کنید. این ردگیری اختیاری است و در stderr -نوشته می‌شود، بنابراین خروجی فرمان JSON همچنان قابل تجزیه می‌ماند. +فراداده Plugin، کشف، رجیستری، آینه زمان اجرا، جهش پیکربندی، و کارهای تازه‌سازی نیاز دارید، از `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` استفاده کنید. ردیابی اختیاری است و +روی stderr می‌نویسد، بنابراین خروجی فرمان JSON همچنان قابل تجزیه می‌ماند. نمونه: @@ -71,12 +70,12 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force [plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed" ``` -پیش از رفتن سراغ پروفایلر CPU، از این برای بررسی چرخه عمر Plugin استفاده کنید. -اگر فرمان از یک checkout منبع اجرا می‌شود، بهتر است زمان اجرای ساخته‌شده را با -`node dist/entry.js ...` پس از `pnpm build` اندازه‌گیری کنید؛ `pnpm openclaw ...` -سربار اجراکننده منبع را نیز اندازه‌گیری می‌کند. +قبل از رفتن سراغ پروفایلر CPU، از این برای بررسی چرخه عمر Plugin استفاده کنید. +اگر فرمان از یک checkout منبع اجرا می‌شود، ترجیح دهید زمان اجرای ساخته‌شده را +با `node dist/entry.js ...` پس از `pnpm build` اندازه‌گیری کنید؛ `pnpm openclaw ...` +هم سربار اجراکننده منبع را اندازه‌گیری می‌کند. -## راه‌اندازی CLI و پروفایل‌گیری فرمان +## پروفایلینگ راه‌اندازی CLI و فرمان‌ها وقتی یک فرمان کند به نظر می‌رسد، از بنچمارک راه‌اندازی ثبت‌شده در مخزن استفاده کنید: @@ -86,17 +85,27 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3 pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu ``` -برای پروفایل‌گیری یک‌باره از مسیر اجراکننده معمول منبع، `OPENCLAW_RUN_NODE_CPU_PROF_DIR` -را تنظیم کنید: +برای پروفایلینگ موردی از مسیر اجراکننده عادی منبع، `OPENCLAW_RUN_NODE_CPU_PROF_DIR` را تنظیم کنید: ```bash OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status ``` -اجراکننده منبع پرچم‌های پروفایل CPU در Node را اضافه می‌کند و برای فرمان یک -`.cpuprofile` می‌نویسد. پیش از افزودن ابزارگذاری موقت به کد فرمان از این استفاده کنید. +اجراکننده منبع پرچم‌های پروفایل CPU مربوط به Node را اضافه می‌کند و برای فرمان +یک `.cpuprofile` می‌نویسد. پیش از افزودن ابزارگذاری موقت به کد فرمان، از این استفاده کنید. -## حالت پایش Gateway +برای توقف‌های راه‌اندازی که شبیه کار همزمان فایل‌سیستم یا بارگذار ماژول هستند، +پرچم ردیابی I/O همزمان Node را از طریق اجراکننده منبع اضافه کنید: + +```bash +OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force +``` + +`pnpm gateway:watch` این پرچم را به‌طور پیش‌فرض برای فرزند Gateway تحت مشاهده فعال می‌کند. +برای سرکوب خروجی ردیابی I/O همزمان Node در حالت watch، +`OPENCLAW_TRACE_SYNC_IO=0` را تنظیم کنید. + +## حالت watch برای Gateway برای تکرار سریع، Gateway را زیر file watcher اجرا کنید: @@ -104,23 +113,23 @@ OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status pnpm gateway:watch ``` -به‌صورت پیش‌فرض، این کار یک نشست tmux با نام `openclaw-gateway-watch-main` -(یا یک گونه مخصوص پروفایل/پورت مانند `openclaw-gateway-watch-dev-19001`) را -شروع یا بازراه‌اندازی می‌کند و از ترمینال‌های تعاملی به‌صورت خودکار attach می‌شود. -پوسته‌های غیرتعاملی، CI، و فراخوانی‌های exec عامل جدا می‌مانند و به‌جای آن دستورهای -attach را چاپ می‌کنند. هر زمان لازم بود دستی attach کنید: +به‌طور پیش‌فرض، این کار یک نشست tmux با نام +`openclaw-gateway-watch-main` (یا یک گونه ویژه پروفایل/پورت مانند +`openclaw-gateway-watch-dev-19001`) را شروع یا بازراه‌اندازی می‌کند و از ترمینال‌های تعاملی به‌طور خودکار متصل می‌شود. +پوسته‌های غیرتعاملی، CI، و فراخوانی‌های exec عامل جدا می‌مانند و به‌جای آن +دستورالعمل اتصال را چاپ می‌کنند. هر وقت لازم بود دستی متصل شوید: ```bash tmux attach -t openclaw-gateway-watch-main ``` -پنل tmux اجراکننده watcher خام را اجرا می‌کند: +پنجره tmux watcher خام را اجرا می‌کند: ```bash node scripts/watch-node.mjs gateway --force ``` -وقتی tmux را نمی‌خواهید، از حالت foreground استفاده کنید: +وقتی tmux مطلوب نیست، از حالت foreground استفاده کنید: ```bash pnpm gateway:watch:raw @@ -128,67 +137,65 @@ pnpm gateway:watch:raw OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch ``` -غیرفعال کردن auto-attach در حالی که مدیریت tmux حفظ می‌شود: +اتصال خودکار را با حفظ مدیریت tmux غیرفعال کنید: ```bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` -هنگام اشکال‌زدایی گلوگاه‌های راه‌اندازی/زمان اجرا، زمان CPU مربوط به Gateway تحت پایش را پروفایل کنید: +هنگام اشکال‌زدایی نقاط داغ راه‌اندازی/زمان اجرا، زمان CPU Gateway تحت مشاهده را پروفایل کنید: ```bash pnpm gateway:watch --benchmark ``` -پوشش watch قبل از فراخوانی Gateway، `--benchmark` را مصرف می‌کند و برای هر خروج -فرزند Gateway یک `.cpuprofile` متعلق به V8 را زیر `.artifacts/gateway-watch-profiles/` -می‌نویسد. Gateway تحت پایش را متوقف یا بازراه‌اندازی کنید تا پروفایل فعلی flush شود، -سپس آن را با Chrome DevTools یا Speedscope باز کنید: +پوشش watch پیش از فراخوانی Gateway، `--benchmark` را مصرف می‌کند و +به‌ازای هر خروج فرزند Gateway، یک `.cpuprofile` مربوط به V8 زیر +`.artifacts/gateway-watch-profiles/` می‌نویسد. برای flush کردن پروفایل فعلی، +Gateway تحت مشاهده را متوقف یا بازراه‌اندازی کنید، سپس آن را با Chrome DevTools یا Speedscope باز کنید: ```bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ``` وقتی پروفایل‌ها را در جای دیگری می‌خواهید، از `--benchmark-dir ` استفاده کنید. -وقتی می‌خواهید فرزند بنچمارک‌شده پاک‌سازی پیش‌فرض پورت با `--force` را رد کند و اگر -پورت Gateway از قبل در حال استفاده است سریع شکست بخورد، از `--benchmark-no-force` -استفاده کنید. +وقتی می‌خواهید فرزند بنچمارک‌شده از پاک‌سازی پورت پیش‌فرض `--force` بگذرد و اگر پورت Gateway از قبل در حال استفاده است سریع شکست بخورد، از `--benchmark-no-force` استفاده کنید. +حالت بنچمارک به‌طور پیش‌فرض هرزخروجی ردیابی sync-I/O را سرکوب می‌کند. وقتی صراحتا هم پروفایل‌های CPU و هم stack traceهای sync-I/O مربوط به Node را می‌خواهید، `OPENCLAW_TRACE_SYNC_IO=1` را همراه `--benchmark` تنظیم کنید. در حالت بنچمارک این بلوک‌های ردیابی +در `gateway-watch-output.log` زیر دایرکتوری بنچمارک نوشته می‌شوند و +از پنجره ترمینال فیلتر می‌شوند؛ لاگ‌های عادی Gateway همچنان قابل مشاهده می‌مانند. -پوشش tmux انتخابگرهای رایج غیرمحرمانه زمان اجرا مانند +پوشش tmux انتخابگرهای رایج و غیرمحرمانه زمان اجرا مانند `OPENCLAW_PROFILE`، `OPENCLAW_CONFIG_PATH`، `OPENCLAW_STATE_DIR`، -`OPENCLAW_GATEWAY_PORT`، و `OPENCLAW_SKIP_CHANNELS` را به پنل منتقل می‌کند. اعتبارنامه‌های -ارائه‌دهنده را در پروفایل/پیکربندی معمول خود بگذارید، یا برای محرمانه‌های موقتی یک‌باره -از حالت foreground خام استفاده کنید. -اگر Gateway تحت پایش هنگام راه‌اندازی خارج شود، watcher یک‌بار -`openclaw doctor --fix --non-interactive` را اجرا می‌کند و فرزند Gateway را بازراه‌اندازی -می‌کند. وقتی شکست اصلی راه‌اندازی را بدون گذر تعمیر فقط مخصوص توسعه می‌خواهید، از -`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` استفاده کنید. -پنل tmux مدیریت‌شده همچنین برای خوانایی، به‌صورت پیش‌فرض لاگ‌های رنگی Gateway را فعال -می‌کند؛ برای غیرفعال کردن خروجی ANSI هنگام شروع `pnpm gateway:watch` مقدار `FORCE_COLOR=0` -را تنظیم کنید. +`OPENCLAW_GATEWAY_PORT`، و `OPENCLAW_SKIP_CHANNELS` را به داخل پنجره منتقل می‌کند. اعتبارنامه‌های ارائه‌دهنده را در پروفایل/پیکربندی عادی خود قرار دهید، یا برای +رازهای موقتی موردی از حالت foreground خام استفاده کنید. +اگر Gateway تحت مشاهده هنگام راه‌اندازی خارج شود، watcher یک‌بار +`openclaw doctor --fix --non-interactive` را اجرا می‌کند و فرزند Gateway را بازراه‌اندازی می‌کند. +وقتی شکست راه‌اندازی اصلی را بدون گذر تعمیر فقط مخصوص توسعه می‌خواهید، +از `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` استفاده کنید. +پنجره tmux مدیریت‌شده همچنین برای خوانایی، به‌طور پیش‌فرض لاگ‌های رنگی Gateway دارد؛ +برای غیرفعال کردن خروجی ANSI هنگام شروع `pnpm gateway:watch`، `FORCE_COLOR=0` را تنظیم کنید. -watcher با تغییر فایل‌های مرتبط با build زیر `src/`، فایل‌های منبع افزونه، -فراداده‌های `package.json` و `openclaw.plugin.json` افزونه، `tsconfig.json`، +watcher روی فایل‌های مرتبط با build زیر `src/`، فایل‌های منبع افزونه‌ها، +فراداده `package.json` و `openclaw.plugin.json` افزونه‌ها، `tsconfig.json`، `package.json`، و `tsdown.config.ts` بازراه‌اندازی می‌شود. تغییرات فراداده افزونه -Gateway را بدون اجبار به rebuild با `tsdown` بازراه‌اندازی می‌کند؛ تغییرات منبع و -پیکربندی همچنان ابتدا `dist` را rebuild می‌کنند. +Gateway را بدون اجبار به بازسازی `tsdown` بازراه‌اندازی می‌کند؛ تغییرات منبع و پیکربندی همچنان +ابتدا `dist` را بازسازی می‌کنند. -هر پرچم CLI مربوط به Gateway را بعد از `gateway:watch` اضافه کنید تا در هر بازراه‌اندازی -عبور داده شود. اجرای دوباره همان فرمان watch پنل tmux نام‌گذاری‌شده را دوباره spawn -می‌کند، و watcher خام همچنان قفل تک-watcher خودش را نگه می‌دارد تا والدهای watcher -تکراری به‌جای انباشته شدن جایگزین شوند. +هر پرچم CLI مربوط به gateway را پس از `gateway:watch` اضافه کنید تا در هر +بازراه‌اندازی عبور داده شود. اجرای دوباره همان فرمان watch پنجره tmux نام‌گذاری‌شده را دوباره spawn می‌کند، و +watcher خام همچنان قفل تک-watcher خود را نگه می‌دارد تا والدهای watcher تکراری +به‌جای انباشته شدن جایگزین شوند. -## پروفایل توسعه + Gateway توسعه (`--dev`) +## پروفایل dev + Gateway توسعه (`--dev`) -از پروفایل توسعه استفاده کنید تا وضعیت را ایزوله کنید و یک تنظیمات امن و دورریختنی -برای اشکال‌زدایی بالا بیاورید. **دو** پرچم `--dev` وجود دارد: +از پروفایل dev برای جداسازی state و بالا آوردن یک چیدمان امن و دورریختنی برای +اشکال‌زدایی استفاده کنید. **دو** پرچم `--dev` وجود دارد: -- **`--dev` سراسری (پروفایل):** وضعیت را زیر `~/.openclaw-dev` ایزوله می‌کند و - پورت Gateway را به‌صورت پیش‌فرض `19001` قرار می‌دهد (پورت‌های مشتق‌شده همراه آن جابه‌جا می‌شوند). -- **`gateway --dev`: به Gateway می‌گوید هنگام نبودن پیکربندی + workspace پیش‌فرض را به‌صورت خودکار بسازد** - (و `BOOTSTRAP.md` را رد کند). +- **`--dev` سراسری (پروفایل):** state را زیر `~/.openclaw-dev` جدا می‌کند و + پورت پیش‌فرض Gateway را روی `19001` می‌گذارد (پورت‌های مشتق‌شده همراه آن جابه‌جا می‌شوند). +- **`gateway --dev`: به Gateway می‌گوید هنگام نبودن، یک پیکربندی + workspace پیش‌فرض را خودکار بسازد** (و از BOOTSTRAP.md بگذرد). -جریان پیشنهادی (پروفایل توسعه + bootstrap توسعه): +روند پیشنهادی (پروفایل dev + راه‌اندازی dev): ```bash pnpm gateway:dev @@ -199,29 +206,29 @@ OPENCLAW_PROFILE=dev openclaw tui این کار چه می‌کند: -1. **ایزوله‌سازی پروفایل** (`--dev` سراسری) +1. **جداسازی پروفایل** (`--dev` سراسری) - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001` (مرورگر/canvas متناسب با آن جابه‌جا می‌شوند) + - `OPENCLAW_GATEWAY_PORT=19001` (مرورگر/canvas نیز متناسب با آن جابه‌جا می‌شوند) -2. **bootstrap توسعه** (`gateway --dev`) - - اگر پیکربندی وجود نداشته باشد، یک پیکربندی حداقلی می‌نویسد (`gateway.mode=local`، bind روی loopback). +2. **راه‌اندازی dev** (`gateway --dev`) + - اگر پیکربندی وجود نداشته باشد، یک پیکربندی حداقلی می‌نویسد (`gateway.mode=local`، bind loopback). - `agent.workspace` را روی workspace توسعه تنظیم می‌کند. - - `agent.skipBootstrap=true` را تنظیم می‌کند (بدون `BOOTSTRAP.md`). + - `agent.skipBootstrap=true` را تنظیم می‌کند (بدون BOOTSTRAP.md). - اگر فایل‌های workspace وجود نداشته باشند، آن‌ها را seed می‌کند: `AGENTS.md`، `SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`. - هویت پیش‌فرض: **C3‑PO** (دروید پروتکل). - - ارائه‌دهندگان کانال را در حالت توسعه رد می‌کند (`OPENCLAW_SKIP_CHANNELS=1`). + - ارائه‌دهنده‌های کانال را در حالت dev رد می‌کند (`OPENCLAW_SKIP_CHANNELS=1`). -جریان reset (شروع تازه): +روند بازنشانی (شروع تازه): ```bash pnpm gateway:dev:reset ``` -`--dev` یک پرچم پروفایل **سراسری** است و توسط بعضی اجراکننده‌ها مصرف می‌شود. اگر لازم دارید آن را صریح بنویسید، از شکل env var استفاده کنید: +`--dev` یک پرچم پروفایل **سراسری** است و بعضی اجراکننده‌ها آن را مصرف می‌کنند. اگر لازم دارید صریح بنویسیدش، از شکل env var استفاده کنید: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset @@ -230,10 +237,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset `--reset` پیکربندی، اعتبارنامه‌ها، نشست‌ها، و workspace توسعه را پاک می‌کند (با -`trash`، نه `rm`)، سپس تنظیمات پیش‌فرض توسعه را دوباره می‌سازد. +`trash`، نه `rm`)، سپس چیدمان پیش‌فرض dev را دوباره می‌سازد. -اگر یک Gateway غیرتوسعه از قبل در حال اجراست (launchd یا systemd)، ابتدا آن را متوقف کنید: +اگر یک gateway غیر-dev از قبل در حال اجراست (launchd یا systemd)، ابتدا آن را متوقف کنید: ```bash openclaw gateway stop @@ -243,8 +250,8 @@ openclaw gateway stop ## لاگ‌گیری جریان خام (OpenClaw) -OpenClaw می‌تواند **جریان خام دستیار** را پیش از هر نوع فیلتر/قالب‌بندی لاگ کند. -این بهترین راه برای دیدن این است که آیا استدلال به‌صورت دلتاهای متن ساده می‌رسد +OpenClaw می‌تواند **جریان خام assistant** را پیش از هرگونه فیلتر/قالب‌بندی لاگ کند. +این بهترین راه برای دیدن این است که آیا استدلال به‌صورت deltaهای متن ساده می‌رسد (یا به‌صورت بلوک‌های thinking جداگانه). آن را از طریق CLI فعال کنید: @@ -272,8 +279,8 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl ## لاگ‌گیری chunk خام (pi-mono) -برای ثبت **chunkهای خام سازگار با OpenAI** پیش از اینکه به بلوک‌ها تجزیه شوند، -pi-mono یک logger جداگانه ارائه می‌کند: +برای گرفتن **chunkهای خام سازگار با OpenAI** پیش از اینکه به بلوک‌ها تجزیه شوند، +pi-mono یک لاگر جداگانه ارائه می‌کند: ```bash PI_RAW_STREAM=1 @@ -289,14 +296,14 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl `~/.pi-mono/logs/raw-openai-completions.jsonl` -> توجه: این فقط توسط فرایندهایی منتشر می‌شود که از ارائه‌دهنده -> `openai-completions` متعلق به pi-mono استفاده می‌کنند. +> نکته: این فقط توسط فرایندهایی منتشر می‌شود که از ارائه‌دهنده +> `openai-completions` مربوط به pi-mono استفاده می‌کنند. ## نکات ایمنی - لاگ‌های جریان خام می‌توانند شامل promptهای کامل، خروجی ابزار، و داده‌های کاربر باشند. - لاگ‌ها را محلی نگه دارید و پس از اشکال‌زدایی حذفشان کنید. -- اگر لاگ‌ها را به اشتراک می‌گذارید، ابتدا محرمانه‌ها و PII را پاک‌سازی کنید. +- اگر لاگ‌ها را به اشتراک می‌گذارید، ابتدا رازها و PII را پاک‌سازی کنید. ## مرتبط diff --git a/docs/fa/help/faq-models.md b/docs/fa/help/faq-models.md index 02819656f..a88b25a85 100644 --- a/docs/fa/help/faq-models.md +++ b/docs/fa/help/faq-models.md @@ -1,21 +1,21 @@ --- read_when: - انتخاب یا تغییر مدل‌ها، پیکربندی نام‌های مستعار - - اشکال‌زدایی جایگزینی اضطراری مدل / «همه مدل‌ها ناموفق بودند» - - درک پروفایل‌های احراز هویت و نحوهٔ مدیریت آن‌ها + - اشکال‌زدایی از جایگزینی خودکار مدل هنگام خرابی / «همهٔ مدل‌ها با شکست مواجه شدند» + - آشنایی با پروفایل‌های احراز هویت و نحوه مدیریت آن‌ها sidebarTitle: Models FAQ -summary: 'پرسش‌های متداول: پیش‌فرض‌های مدل، انتخاب، نام‌های مستعار، تغییر، جایگزینی هنگام خرابی، و پروفایل‌های احراز هویت' +summary: 'پرسش‌های متداول: پیش‌فرض‌های مدل، انتخاب، نام‌های مستعار، تغییر، بازیابی پس از خرابی، و پروفایل‌های احراز هویت' title: 'پرسش‌های متداول: مدل‌ها و احراز هویت' x-i18n: - generated_at: "2026-05-02T11:49:46Z" + generated_at: "2026-05-05T01:48:43Z" model: gpt-5.5 provider: openai - source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884 + source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54 source_path: help/faq-models.md workflow: 16 --- - پرسش‌وپاسخ مدل و پروفایل احراز هویت. برای راه‌اندازی، نشست‌ها، Gateway، کانال‌ها و + پرسش‌وپاسخ مدل و نمایه احراز هویت. برای راه‌اندازی، نشست‌ها، Gateway، کانال‌ها و عیب‌یابی، [پرسش‌های متداول](/fa/help/faq) اصلی را ببینید. ## مدل‌ها: پیش‌فرض‌ها، انتخاب، نام‌های مستعار، تغییر @@ -28,82 +28,84 @@ x-i18n: agents.defaults.model.primary ``` - مدل‌ها به‌صورت `provider/model` ارجاع داده می‌شوند (مثال: `openai/gpt-5.5` یا `openai-codex/gpt-5.5`). اگر ارائه‌دهنده را حذف کنید، OpenClaw ابتدا یک نام مستعار را امتحان می‌کند، سپس یک تطابق یکتای ارائه‌دهنده پیکربندی‌شده را برای همان شناسه دقیق مدل بررسی می‌کند، و فقط پس از آن به‌عنوان مسیر سازگاری منسوخ‌شده به ارائه‌دهنده پیش‌فرض پیکربندی‌شده برمی‌گردد. اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش یک پیش‌فرض قدیمی مربوط به ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد. با این حال همچنان باید `provider/model` را **صراحتا** تنظیم کنید. + مدل‌ها به‌صورت `provider/model` ارجاع داده می‌شوند (نمونه: `openai/gpt-5.5` یا `openai-codex/gpt-5.5`). اگر ارائه‌دهنده را حذف کنید، OpenClaw ابتدا یک نام مستعار را امتحان می‌کند، سپس یک تطبیق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه دقیق مدل را، و فقط بعد از آن به‌عنوان مسیر سازگاری منسوخ، به ارائه‌دهنده پیش‌فرض پیکربندی‌شده برمی‌گردد. اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نشان دادن یک پیش‌فرض کهنه مربوط به ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد. همچنان باید `provider/model` را **صریح** تنظیم کنید. - **پیش‌فرض پیشنهادی:** از قوی‌ترین مدل نسل جدید موجود در مجموعه ارائه‌دهنده‌های خود استفاده کنید. - **برای عامل‌های دارای ابزار یا ورودی‌های نامطمئن:** قدرت مدل را بر هزینه اولویت دهید. + **پیش‌فرض پیشنهادی:** از قوی‌ترین مدل نسل جدید موجود در مجموعه ارائه‌دهندگان خود استفاده کنید. + **برای عامل‌های دارای ابزار یا ورودی نامطمئن:** قدرت مدل را به هزینه ترجیح دهید. **برای گفت‌وگوی روزمره/کم‌ریسک:** از مدل‌های جایگزین ارزان‌تر استفاده کنید و بر اساس نقش عامل مسیریابی کنید. MiniMax مستندات خودش را دارد: [MiniMax](/fa/providers/minimax) و [مدل‌های محلی](/fa/gateway/local-models). - قاعده کلی: برای کارهای پرریسک از **بهترین مدلی که از عهده هزینه‌اش برمی‌آیید** استفاده کنید، و برای گفت‌وگوی روزمره یا خلاصه‌سازی از مدلی ارزان‌تر. می‌توانید مدل‌ها را برای هر عامل مسیریابی کنید و از زیرعامل‌ها برای موازی‌سازی کارهای طولانی استفاده کنید (هر زیرعامل توکن مصرف می‌کند). [مدل‌ها](/fa/concepts/models) و [زیرعامل‌ها](/fa/tools/subagents) را ببینید. + قاعده سرانگشتی: برای کارهای حساس از **بهترین مدلی که توان پرداختش را دارید** استفاده کنید، و برای گفت‌وگو یا خلاصه‌سازی روزمره از مدلی ارزان‌تر. می‌توانید مدل‌ها را برای هر عامل مسیریابی کنید و از زیرعامل‌ها برای + موازی‌سازی کارهای طولانی استفاده کنید (هر زیرعامل توکن مصرف می‌کند). [مدل‌ها](/fa/concepts/models) و + [زیرعامل‌ها](/fa/tools/subagents) را ببینید. هشدار جدی: مدل‌های ضعیف‌تر/بیش‌ازحد کوانتیزه‌شده در برابر تزریق پرامپت - و رفتار ناامن آسیب‌پذیرتر هستند. [امنیت](/fa/gateway/security) را ببینید. + و رفتار ناایمن آسیب‌پذیرتر هستند. [امنیت](/fa/gateway/security) را ببینید. زمینه بیشتر: [مدل‌ها](/fa/concepts/models). - - از **دستورهای مدل** استفاده کنید یا فقط فیلدهای **مدل** را ویرایش کنید. از جایگزینی کامل پیکربندی پرهیز کنید. + + از **دستورهای مدل** استفاده کنید یا فقط فیلدهای **model** را ویرایش کنید. از جایگزینی کامل پیکربندی پرهیز کنید. - گزینه‌های ایمن: + گزینه‌های امن: - `/model` در گفت‌وگو (سریع، برای هر نشست) - `openclaw models set ...` (فقط پیکربندی مدل را به‌روزرسانی می‌کند) - `openclaw configure --section model` (تعاملی) - ویرایش `agents.defaults.model` در `~/.openclaw/openclaw.json` - از `config.apply` با یک شیء جزئی استفاده نکنید، مگر اینکه قصد داشته باشید کل پیکربندی را جایگزین کنید. - برای ویرایش‌های RPC، ابتدا با `config.schema.lookup` بررسی کنید و ترجیحا از `config.patch` استفاده کنید. محموله lookup مسیر نرمال‌شده، مستندات/محدودیت‌های سطحی schema، و خلاصه‌های فرزند فوری را به شما می‌دهد. + از `config.apply` با یک شیء جزئی پرهیز کنید، مگر اینکه قصد داشته باشید کل پیکربندی را جایگزین کنید. + برای ویرایش‌های RPC، ابتدا با `config.schema.lookup` بررسی کنید و ترجیحا از `config.patch` استفاده کنید. بار داده lookup مسیر نرمال‌شده، مستندات/محدودیت‌های سطحی schema، و خلاصه‌های فرزند فوری را به شما می‌دهد. برای به‌روزرسانی‌های جزئی. - اگر پیکربندی را بازنویسی کردید، از پشتیبان بازیابی کنید یا دوباره `openclaw doctor` را برای تعمیر اجرا کنید. + اگر پیکربندی را بازنویسی کردید، از نسخه پشتیبان بازیابی کنید یا برای تعمیر دوباره `openclaw doctor` را اجرا کنید. مستندات: [مدل‌ها](/fa/concepts/models)، [پیکربندی](/fa/cli/configure)، [Config](/fa/cli/config)، [Doctor](/fa/gateway/doctor). - + بله. Ollama ساده‌ترین مسیر برای مدل‌های محلی است. سریع‌ترین راه‌اندازی: 1. Ollama را از `https://ollama.com/download` نصب کنید - 2. یک مدل محلی مانند `ollama pull gemma4` را دریافت کنید + 2. یک مدل محلی مانند `ollama pull gemma4` دریافت کنید 3. اگر مدل‌های ابری هم می‌خواهید، `ollama signin` را اجرا کنید 4. `openclaw onboard` را اجرا کنید و `Ollama` را انتخاب کنید 5. `Local` یا `Cloud + Local` را انتخاب کنید نکته‌ها: - - `Cloud + Local` مدل‌های ابری را به‌همراه مدل‌های محلی Ollama شما فراهم می‌کند + - `Cloud + Local` مدل‌های ابری را همراه با مدل‌های محلی Ollama شما فراهم می‌کند - مدل‌های ابری مانند `kimi-k2.5:cloud` به دریافت محلی نیاز ندارند - برای تغییر دستی، از `openclaw models list` و `openclaw models set ollama/` استفاده کنید - نکته امنیتی: مدل‌های کوچک‌تر یا به‌شدت کوانتیزه‌شده در برابر تزریق پرامپت - آسیب‌پذیرتر هستند. برای هر رباتی که می‌تواند از ابزارها استفاده کند، قویا **مدل‌های بزرگ** را پیشنهاد می‌کنیم. - اگر همچنان مدل‌های کوچک می‌خواهید، سندباکسینگ و allowlistهای سخت‌گیرانه ابزار را فعال کنید. + نکته امنیتی: مدل‌های کوچک‌تر یا شدیدا کوانتیزه‌شده در برابر تزریق پرامپت + آسیب‌پذیرتر هستند. برای هر رباتی که می‌تواند از ابزارها استفاده کند، **مدل‌های بزرگ** را قویا پیشنهاد می‌کنیم. + اگر همچنان مدل‌های کوچک می‌خواهید، sandboxing و فهرست‌های مجاز سخت‌گیرانه ابزار را فعال کنید. مستندات: [Ollama](/fa/providers/ollama)، [مدل‌های محلی](/fa/gateway/local-models)، [ارائه‌دهندگان مدل](/fa/concepts/model-providers)، [امنیت](/fa/gateway/security)، - [سندباکسینگ](/fa/gateway/sandboxing). + [Sandboxing](/fa/gateway/sandboxing). - - این استقرارها می‌توانند متفاوت باشند و ممکن است در طول زمان تغییر کنند؛ هیچ پیشنهاد ثابت ارائه‌دهنده‌ای وجود ندارد. - - تنظیم runtime فعلی را روی هر Gateway با `openclaw models status` بررسی کنید. + - این استقرارها می‌توانند متفاوت باشند و ممکن است با گذشت زمان تغییر کنند؛ هیچ پیشنهاد ثابت ارائه‌دهنده‌ای وجود ندارد. + - تنظیم runtime فعلی را روی هر gateway با `openclaw models status` بررسی کنید. - برای عامل‌های حساس از نظر امنیت/دارای ابزار، از قوی‌ترین مدل نسل جدید موجود استفاده کنید. - - از دستور `/model` به‌عنوان یک پیام مستقل استفاده کنید: + + دستور `/model` را به‌عنوان یک پیام مستقل استفاده کنید: ``` /model sonnet @@ -119,23 +121,23 @@ x-i18n: می‌توانید مدل‌های موجود را با `/model`، `/model list` یا `/model status` فهرست کنید. - `/model` (و `/model list`) یک انتخاب‌گر فشرده و شماره‌دار نشان می‌دهد. بر اساس شماره انتخاب کنید: + `/model` (و `/model list`) یک انتخاب‌گر فشرده و شماره‌دار نشان می‌دهد. با شماره انتخاب کنید: ``` /model 3 ``` - همچنین می‌توانید یک پروفایل احراز هویت مشخص را برای ارائه‌دهنده اجبار کنید (برای هر نشست): + همچنین می‌توانید یک نمایه احراز هویت مشخص را برای ارائه‌دهنده اجباری کنید (برای هر نشست): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - نکته: `/model status` نشان می‌دهد کدام عامل فعال است، از کدام فایل `auth-profiles.json` استفاده می‌شود، و کدام پروفایل احراز هویت بعدی امتحان خواهد شد. - همچنین در صورت موجود بودن، endpoint ارائه‌دهنده پیکربندی‌شده (`baseUrl`) و حالت API (`api`) را نشان می‌دهد. + نکته: `/model status` نشان می‌دهد کدام عامل فعال است، کدام فایل `auth-profiles.json` استفاده می‌شود، و کدام نمایه احراز هویت بعدا امتحان خواهد شد. + همچنین در صورت وجود، endpoint ارائه‌دهنده پیکربندی‌شده (`baseUrl`) و حالت API (`api`) را نشان می‌دهد. - **چگونه پروفایلی را که با @profile ثابت کرده‌ام آزاد کنم؟** + **چطور نمایه‌ای را که با @profile سنجاق کرده‌ام بردارم؟** `/model` را **بدون** پسوند `@profile` دوباره اجرا کنید: @@ -144,29 +146,29 @@ x-i18n: ``` اگر می‌خواهید به پیش‌فرض برگردید، آن را از `/model` انتخاب کنید (یا `/model ` را بفرستید). - از `/model status` برای تأیید پروفایل احراز هویت فعال استفاده کنید. + از `/model status` برای تایید نمایه احراز هویت فعال استفاده کنید. بله. انتخاب مدل و انتخاب runtime را جداگانه در نظر بگیرید: - - **عامل کدنویسی Native Codex:** مقدار `agents.defaults.model.primary` را روی `openai/gpt-5.5` و مقدار `agents.defaults.agentRuntime.id` را روی `"codex"` تنظیم کنید. وقتی احراز هویت اشتراک ChatGPT/Codex را می‌خواهید، با `openclaw models auth login --provider openai-codex` وارد شوید. + - **عامل کدنویسی بومی Codex:** `agents.defaults.model.primary` را روی `openai/gpt-5.5` و `agents.defaults.agentRuntime.id` را روی `"codex"` تنظیم کنید. وقتی احراز هویت اشتراک ChatGPT/Codex را می‌خواهید، با `openclaw models auth login --provider openai-codex` وارد شوید. - **کارهای مستقیم OpenAI API از طریق PI:** از `/model openai/gpt-5.5` بدون بازنویسی runtime مربوط به Codex استفاده کنید و `OPENAI_API_KEY` را پیکربندی کنید. - - **Codex OAuth از طریق PI:** فقط وقتی عمدا runner معمولی PI را با Codex OAuth می‌خواهید، از `/model openai-codex/gpt-5.5` استفاده کنید. - - **زیرعامل‌ها:** کارهای کدنویسی را به یک عامل فقط-Codex با مدل خودش و پیش‌فرض `agentRuntime` خودش مسیریابی کنید. + - **Codex OAuth از طریق PI:** فقط وقتی از `/model openai-codex/gpt-5.5` استفاده کنید که عمدا runner معمول PI را با Codex OAuth می‌خواهید. + - **زیرعامل‌ها:** کارهای کدنویسی را به یک عامل فقط Codex با مدل خودش و پیش‌فرض `agentRuntime` خودش مسیریابی کنید. [مدل‌ها](/fa/concepts/models) و [دستورهای Slash](/fa/tools/slash-commands) را ببینید. - + از یک toggle نشست یا یک پیش‌فرض پیکربندی استفاده کنید: - **برای هر نشست:** وقتی نشست از `openai/gpt-5.5` یا `openai-codex/gpt-5.5` استفاده می‌کند، `/fast on` را بفرستید. - - **پیش‌فرض برای هر مدل:** مقدار `agents.defaults.models["openai/gpt-5.5"].params.fastMode` یا `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` را روی `true` تنظیم کنید. + - **پیش‌فرض برای هر مدل:** `agents.defaults.models["openai/gpt-5.5"].params.fastMode` یا `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` را روی `true` تنظیم کنید. - مثال: + نمونه: ```json5 { @@ -184,53 +186,58 @@ x-i18n: } ``` - برای OpenAI، حالت سریع در درخواست‌های native Responses پشتیبانی‌شده به `service_tier = "priority"` نگاشت می‌شود. بازنویسی‌های `/fast` در نشست بر پیش‌فرض‌های پیکربندی اولویت دارند. + برای OpenAI، حالت سریع در درخواست‌های native Responses پشتیبانی‌شده به `service_tier = "priority"` نگاشت می‌شود. بازنویسی‌های `/fast` نشست بر پیش‌فرض‌های پیکربندی اولویت دارند. - [Thinking and fast mode](/fa/tools/thinking) و [حالت سریع OpenAI](/fa/providers/openai#fast-mode) را ببینید. + [Thinking و حالت سریع](/fa/tools/thinking) و [حالت سریع OpenAI](/fa/providers/openai#fast-mode) را ببینید. - اگر `agents.defaults.models` تنظیم شده باشد، برای `/model` و هر بازنویسی نشست به **allowlist** تبدیل می‌شود. انتخاب مدلی که در آن فهرست نیست، این را برمی‌گرداند: + اگر `agents.defaults.models` تنظیم شده باشد، به **فهرست مجاز** برای `/model` و هر + بازنویسی نشست تبدیل می‌شود. انتخاب مدلی که در آن فهرست نیست، این را برمی‌گرداند: ``` - Model "provider/model" is not allowed. Use /model to list available models. + Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. + Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` - آن خطا **به‌جای** پاسخ عادی برگردانده می‌شود. راه‌حل: مدل را به - `agents.defaults.models` اضافه کنید، allowlist را حذف کنید، یا مدلی را از `/model list` انتخاب کنید. + این خطا **به‌جای** یک پاسخ معمولی برگردانده می‌شود. راه‌حل: مدل را به + `agents.defaults.models` اضافه کنید، فهرست مجاز را حذف کنید، یا مدلی را از `/model list` انتخاب کنید. + اگر دستور همچنین شامل `--runtime codex` بود، ابتدا مدل را اضافه کنید و سپس همان دستور + `/model provider/model --runtime codex` را دوباره امتحان کنید. - این یعنی **ارائه‌دهنده پیکربندی نشده است** (هیچ پیکربندی ارائه‌دهنده MiniMax یا پروفایل احراز هویت پیدا نشده)، بنابراین مدل قابل resolve نیست. + این یعنی **ارائه‌دهنده پیکربندی نشده است** (هیچ پیکربندی ارائه‌دهنده MiniMax یا + نمایه احراز هویتی پیدا نشده)، بنابراین مدل قابل resolve نیست. چک‌لیست رفع مشکل: - 1. به نسخه فعلی OpenClaw ارتقا دهید (یا از سورس `main` اجرا کنید)، سپس Gateway را راه‌اندازی مجدد کنید. + 1. به یک انتشار فعلی OpenClaw ارتقا دهید (یا از source `main` اجرا کنید)، سپس gateway را راه‌اندازی مجدد کنید. 2. مطمئن شوید MiniMax پیکربندی شده است (wizard یا JSON)، یا اینکه احراز هویت MiniMax - در env/پروفایل‌های احراز هویت وجود دارد تا ارائه‌دهنده مطابق بتواند تزریق شود + در env/auth profiles وجود دارد تا ارائه‌دهنده متناظر بتواند تزریق شود (`MINIMAX_API_KEY` برای `minimax`، `MINIMAX_OAUTH_TOKEN` یا MiniMax OAuth ذخیره‌شده برای `minimax-portal`). - 3. از شناسه دقیق مدل (حساس به بزرگی و کوچکی حروف) برای مسیر احراز هویت خود استفاده کنید: - `minimax/MiniMax-M2.7` یا `minimax/MiniMax-M2.7-highspeed` برای راه‌اندازی با API-key، - یا `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` برای راه‌اندازی با OAuth. + 3. شناسه دقیق مدل (حساس به بزرگی و کوچکی حروف) را برای مسیر احراز هویت خود استفاده کنید: + `minimax/MiniMax-M2.7` یا `minimax/MiniMax-M2.7-highspeed` برای راه‌اندازی + API-key، یا `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` برای راه‌اندازی OAuth. 4. اجرا کنید: ```bash openclaw models list ``` - و از فهرست انتخاب کنید (یا در گفت‌وگو `/model list` را بزنید). + و از فهرست انتخاب کنید (یا `/model list` در گفت‌وگو). [MiniMax](/fa/providers/minimax) و [مدل‌ها](/fa/concepts/models) را ببینید. - - بله. از **MiniMax به‌عنوان پیش‌فرض** استفاده کنید و در صورت نیاز مدل‌ها را **برای هر نشست** تغییر دهید. - fallbackها برای **خطاها** هستند، نه «کارهای سخت»، بنابراین از `/model` یا یک عامل جداگانه استفاده کنید. + + بله. از **MiniMax به‌عنوان پیش‌فرض** استفاده کنید و هر وقت لازم بود مدل‌ها را **برای هر نشست** تغییر دهید. + جایگزین‌ها برای **خطاها** هستند، نه «کارهای سخت»، بنابراین از `/model` یا یک عامل جداگانه استفاده کنید. **گزینه A: تغییر برای هر نشست** @@ -259,14 +266,14 @@ x-i18n: - پیش‌فرض عامل A: MiniMax - پیش‌فرض عامل B: OpenAI - - بر اساس عامل مسیریابی کنید یا از `/agent` برای تغییر استفاده کنید + - بر اساس عامل مسیریابی کنید یا برای تغییر از `/agent` استفاده کنید مستندات: [مدل‌ها](/fa/concepts/models)، [مسیریابی چندعاملی](/fa/concepts/multi-agent)، [MiniMax](/fa/providers/minimax)، [OpenAI](/fa/providers/openai). - بله. OpenClaw چند کوتاه‌نویسی پیش‌فرض همراه خود دارد (فقط وقتی اعمال می‌شوند که مدل در `agents.defaults.models` وجود داشته باشد): + بله. OpenClaw چند کوتاه‌نویسی پیش‌فرض ارائه می‌کند (فقط وقتی اعمال می‌شوند که مدل در `agents.defaults.models` وجود داشته باشد): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -281,8 +288,8 @@ x-i18n: - - نام‌های مستعار از `agents.defaults.models..alias` می‌آیند. مثال: + + نام‌های مستعار از `agents.defaults.models..alias` می‌آیند. نمونه: ```json5 { @@ -303,8 +310,8 @@ x-i18n: - - OpenRouter (پرداخت به‌ازای توکن؛ مدل‌های زیاد): + + OpenRouter (پرداخت به‌ازای توکن؛ مدل‌های متعدد): ```json5 { @@ -332,12 +339,11 @@ x-i18n: } ``` - اگر به یک ارائه‌دهنده/مدل ارجاع دهید اما کلید لازم آن ارائه‌دهنده وجود نداشته باشد، یک خطای احراز هویت زمان اجرا دریافت می‌کنید (برای مثال `No API key found for provider "zai"`). + اگر به یک ارائه‌دهنده/مدل ارجاع دهید اما کلید موردنیاز ارائه‌دهنده وجود نداشته باشد، یک خطای احراز هویت زمان اجرا دریافت می‌کنید (مثلاً `No API key found for provider "zai"`). - **پس از افزودن عامل جدید، هیچ کلید API برای ارائه‌دهنده پیدا نشد** + **پس از افزودن یک عامل جدید، هیچ کلید API برای ارائه‌دهنده پیدا نشد** - این معمولاً یعنی **عامل جدید** یک مخزن احراز هویت خالی دارد. احراز هویت برای هر عامل جداگانه است و - در این مسیر ذخیره می‌شود: + این معمولاً یعنی **عامل جدید** یک مخزن احراز هویت خالی دارد. احراز هویت برای هر عامل جداگانه است و در این مسیر ذخیره می‌شود: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -345,147 +351,145 @@ x-i18n: گزینه‌های رفع مشکل: - - `openclaw agents add ` را اجرا کنید و احراز هویت را در طول راهنمای مرحله‌ای پیکربندی کنید. - - یا فقط پروفایل‌های ثابت و قابل‌انتقال `api_key` / `token` را از مخزن احراز هویت عامل اصلی به مخزن احراز هویت عامل جدید کپی کنید. - - برای پروفایل‌های OAuth، وقتی عامل جدید به حساب خودش نیاز دارد از همان عامل جدید وارد شوید؛ در غیر این صورت OpenClaw می‌تواند بدون کلون کردن توکن‌های تازه‌سازی، از عامل پیش‌فرض/اصلی بخواند. + - `openclaw agents add ` را اجرا کنید و احراز هویت را در جادوگر پیکربندی کنید. + - یا فقط پروفایل‌های ایستای قابل‌حمل `api_key` / `token` را از مخزن احراز هویت عامل اصلی به مخزن احراز هویت عامل جدید کپی کنید. + - برای پروفایل‌های OAuth، وقتی عامل جدید به حساب خودش نیاز دارد، از همان عامل جدید وارد شوید؛ در غیر این صورت OpenClaw می‌تواند بدون شبیه‌سازی توکن‌های تازه‌سازی، از عامل پیش‌فرض/اصلی بخواند. - از `agentDir` مشترک بین عامل‌ها استفاده **نکنید**؛ این کار باعث تداخل احراز هویت/نشست می‌شود. + از `agentDir` در چند عامل دوباره استفاده **نکنید**؛ این کار باعث تداخل احراز هویت/نشست می‌شود. -## Failover مدل و «همه مدل‌ها ناموفق بودند» +## جابه‌جایی مدل هنگام خرابی و «همه مدل‌ها ناموفق بودند» - - Failover در دو مرحله انجام می‌شود: + + جابه‌جایی هنگام خرابی در دو مرحله رخ می‌دهد: 1. **چرخش پروفایل احراز هویت** در همان ارائه‌دهنده. - 2. **جایگزینی مدل** با مدل بعدی در `agents.defaults.model.fallbacks`. + 2. **بازگشت به مدل جایگزین** بعدی در `agents.defaults.model.fallbacks`. - دوره‌های انتظار برای پروفایل‌های ناموفق اعمال می‌شوند (پس‌نشینی نمایی)، بنابراین OpenClaw حتی وقتی یک ارائه‌دهنده با محدودیت نرخ مواجه است یا موقتاً شکست می‌خورد هم می‌تواند پاسخ‌گویی را ادامه دهد. + دوره‌های سردشدن برای پروفایل‌های ناموفق اعمال می‌شوند (پس‌روی نمایی)، بنابراین OpenClaw می‌تواند حتی وقتی یک ارائه‌دهنده با محدودیت نرخ روبه‌رو است یا موقتاً خطا می‌دهد، همچنان پاسخ دهد. - سبد محدودیت نرخ فقط پاسخ‌های ساده `429` را شامل نمی‌شود. OpenClaw - پیام‌هایی مانند `Too many concurrent requests`، + سطل محدودیت نرخ فقط شامل پاسخ‌های ساده `429` نیست. OpenClaw + پیام‌هایی مثل `Too many concurrent requests`، `ThrottlingException`، `concurrency limit reached`، `workers_ai ... quota limit exceeded`، `resource exhausted`، و محدودیت‌های دوره‌ای - پنجره مصرف (`weekly/monthly limit reached`) را نیز محدودیت نرخِ شایسته Failover + پنجره مصرف (`weekly/monthly limit reached`) را نیز محدودیت نرخ شایسته جابه‌جایی هنگام خرابی در نظر می‌گیرد. - برخی پاسخ‌هایی که شبیه صورتحساب هستند `402` نیستند، و برخی پاسخ‌های HTTP `402` - نیز در همان سبد گذرا باقی می‌مانند. اگر ارائه‌دهنده‌ای روی `401` یا `403` - متن صریح مربوط به صورتحساب برگرداند، OpenClaw همچنان می‌تواند آن را در - مسیر صورتحساب نگه دارد، اما تطبیق‌دهنده‌های متنِ ویژه ارائه‌دهنده فقط در محدوده - همان ارائه‌دهنده‌ای می‌مانند که مالک آن‌هاست (برای مثال OpenRouter `Key limit exceeded`). اگر یک پیام `402` + بعضی پاسخ‌هایی که شبیه خطای پرداخت هستند `402` نیستند، و بعضی پاسخ‌های HTTP `402` + نیز در همان سطل گذرا باقی می‌مانند. اگر یک ارائه‌دهنده متن صریح پرداخت را در `401` یا `403` برگرداند، OpenClaw همچنان می‌تواند آن را در + مسیر پرداخت نگه دارد، اما تطبیق‌دهنده‌های متن ویژه ارائه‌دهنده در محدوده همان + ارائه‌دهنده‌ای می‌مانند که مالک آن‌هاست (برای مثال OpenRouter `Key limit exceeded`). اگر یک پیام `402` در عوض شبیه یک پنجره مصرف قابل‌تلاش‌مجدد یا محدودیت هزینه سازمان/فضای کاری باشد (`daily limit reached, resets tomorrow`، `organization spending limit exceeded`)، OpenClaw آن را - `rate_limit` در نظر می‌گیرد، نه یک غیرفعال‌سازی طولانی صورتحساب. + `rate_limit` در نظر می‌گیرد، نه یک غیرفعال‌سازی طولانی‌مدت پرداخت. خطاهای سرریز زمینه متفاوت هستند: امضاهایی مانند `request_too_large`، `input exceeds the maximum number of tokens`، `input token count exceeds the maximum number of input tokens`، `input is too long for the model`، یا `ollama error: context length - exceeded` به‌جای پیش بردن جایگزینی مدل، - در مسیر Compaction/تلاش‌مجدد باقی می‌مانند. + exceeded` به‌جای پیش‌بردن بازگشت به مدل جایگزین، در مسیر Compaction/تلاش‌مجدد باقی می‌مانند. - متن عمومی خطای سرور عمداً محدودتر از «هر چیزی که - ناشناخته/خطا در آن باشد» است. OpenClaw شکل‌های گذرای محدود به ارائه‌دهنده - مانند `An unknown error occurred` خام Anthropic، خطای خام - `Provider returned error` در OpenRouter، خطاهای دلیل توقف مانند `Unhandled stop reason: + متن عمومی خطای سرور عمداً محدودتر از «هر چیزی که unknown/error در آن باشد» است. OpenClaw + شکل‌های گذرای محدود به ارائه‌دهنده مانند `An unknown error occurred` خالی از Anthropic، `Provider returned error` خالی از OpenRouter، خطاهای دلیل توقف مثل `Unhandled stop reason: error`، محموله‌های JSON `api_error` با متن گذرای سرور (`internal server error`، `unknown error, 520`، `upstream error`، `backend - error`)، و خطاهای مشغول بودن ارائه‌دهنده مانند `ModelNotReadyException` را هنگام - تطابق زمینه ارائه‌دهنده، سیگنال‌های مهلت‌پایان‌یافته/بارگذاری‌زیادِ شایسته - Failover در نظر می‌گیرد. - متن عمومی جایگزینی داخلی مانند `LLM request failed with an unknown - error.` محافظه‌کارانه باقی می‌ماند و به‌تنهایی جایگزینی مدل را فعال نمی‌کند. + error`)، و خطاهای مشغول‌بودن ارائه‌دهنده مانند `ModelNotReadyException` را وقتی زمینه ارائه‌دهنده + مطابقت داشته باشد، سیگنال‌های مهلت‌پایان‌یافته/بارگذاری‌بیش‌ازحد شایسته جابه‌جایی هنگام خرابی + در نظر می‌گیرد. + متن عمومی بازگشت داخلی مثل `LLM request failed with an unknown + error.` محافظه‌کارانه باقی می‌ماند و به‌تنهایی بازگشت به مدل جایگزین را فعال نمی‌کند. - + یعنی سیستم تلاش کرده از شناسه پروفایل احراز هویت `anthropic:default` استفاده کند، اما نتوانسته اعتبارنامه‌های آن را در مخزن احراز هویت مورد انتظار پیدا کند. - **چک‌لیست رفع مشکل:** + **فهرست بررسی رفع مشکل:** - - **تأیید کنید پروفایل‌های احراز هویت کجا قرار دارند** (مسیرهای جدید در برابر قدیمی) + - **تأیید کنید پروفایل‌های احراز هویت کجا قرار دارند** (مسیرهای جدید در برابر مسیرهای قدیمی) - فعلی: `~/.openclaw/agents//agent/auth-profiles.json` - قدیمی: `~/.openclaw/agent/*` (با `openclaw doctor` مهاجرت داده می‌شود) - - **تأیید کنید متغیر محیطی شما توسط Gateway بارگذاری شده است** - - اگر `ANTHROPIC_API_KEY` را در شِل خود تنظیم کرده‌اید اما Gateway را از طریق systemd/launchd اجرا می‌کنید، ممکن است آن را به ارث نبرد. آن را در `~/.openclaw/.env` قرار دهید یا `env.shellEnv` را فعال کنید. + - **تأیید کنید متغیر محیطی شما توسط Gateway بارگذاری می‌شود** + - اگر `ANTHROPIC_API_KEY` را در پوسته خود تنظیم کرده‌اید اما Gateway را از طریق systemd/launchd اجرا می‌کنید، ممکن است آن را به ارث نبرد. آن را در `~/.openclaw/.env` قرار دهید یا `env.shellEnv` را فعال کنید. - **مطمئن شوید عامل درست را ویرایش می‌کنید** - - پیکربندی‌های چندعاملی یعنی ممکن است چند فایل `auth-profiles.json` وجود داشته باشد. - - **وضعیت مدل/احراز هویت را از نظر معقول بودن بررسی کنید** - - از `openclaw models status` استفاده کنید تا مدل‌های پیکربندی‌شده و وضعیت احراز هویت ارائه‌دهنده‌ها را ببینید. + - راه‌اندازی‌های چندعاملی یعنی ممکن است چندین فایل `auth-profiles.json` وجود داشته باشد. + - **وضعیت مدل/احراز هویت را برای اطمینان بررسی کنید** + - از `openclaw models status` استفاده کنید تا مدل‌های پیکربندی‌شده و احراز هویت بودن ارائه‌دهندگان را ببینید. - **چک‌لیست رفع مشکل برای «هیچ اعتبارنامه‌ای برای پروفایل anthropic پیدا نشد»** + **فهرست بررسی رفع مشکل برای «No credentials found for profile anthropic»** - این یعنی اجرا به یک پروفایل احراز هویت Anthropic سنجاق شده است، اما Gateway + این یعنی اجرا به یک پروفایل احراز هویت Anthropic سنجاق شده، اما Gateway نمی‌تواند آن را در مخزن احراز هویت خود پیدا کند. - **از Claude CLI استفاده کنید** - - روی میزبان gateway دستور `openclaw models auth login --provider anthropic --method cli --set-default` را اجرا کنید. - - **اگر می‌خواهید به‌جای آن از کلید API استفاده کنید** - - `ANTHROPIC_API_KEY` را در `~/.openclaw/.env` روی **میزبان gateway** قرار دهید. - - هر ترتیب سنجاق‌شده‌ای را که یک پروفایل گمشده را اجبار می‌کند پاک کنید: + - روی میزبان Gateway، `openclaw models auth login --provider anthropic --method cli --set-default` را اجرا کنید. + - **اگر می‌خواهید به‌جای آن از یک کلید API استفاده کنید** + - `ANTHROPIC_API_KEY` را در `~/.openclaw/.env` روی **میزبان Gateway** قرار دهید. + - هر ترتیب سنجاق‌شده‌ای را که یک پروفایل گمشده را اجباری می‌کند پاک کنید: ```bash openclaw models auth order clear --provider anthropic ``` - - **تأیید کنید فرمان‌ها را روی میزبان gateway اجرا می‌کنید** - - در حالت راه دور، پروفایل‌های احراز هویت روی ماشین gateway قرار دارند، نه لپ‌تاپ شما. + - **تأیید کنید فرمان‌ها را روی میزبان Gateway اجرا می‌کنید** + - در حالت راه دور، پروفایل‌های احراز هویت روی دستگاه Gateway قرار دارند، نه لپ‌تاپ شما. - اگر پیکربندی مدل شما Google Gemini را به‌عنوان جایگزین شامل کند (یا به یک صورت کوتاه Gemini تغییر کرده باشید)، OpenClaw آن را در طول جایگزینی مدل امتحان می‌کند. اگر اعتبارنامه‌های Google را پیکربندی نکرده باشید، `No API key found for provider "google"` را می‌بینید. + اگر پیکربندی مدل شما Google Gemini را به‌عنوان جایگزین شامل کند (یا به یک کوتاه‌نوشت Gemini تغییر داده باشید)، OpenClaw هنگام بازگشت به مدل جایگزین آن را امتحان می‌کند. اگر اعتبارنامه‌های Google را پیکربندی نکرده باشید، `No API key found for provider "google"` را خواهید دید. - رفع مشکل: یا احراز هویت Google را فراهم کنید، یا مدل‌های Google را از `agents.defaults.model.fallbacks` / نام‌های مستعار حذف کنید/اجتناب کنید تا جایگزینی به آن‌جا مسیریابی نشود. + اصلاح: یا احراز هویت Google را فراهم کنید، یا مدل‌های Google را در `agents.defaults.model.fallbacks` / aliases حذف کنید یا از آن‌ها پرهیز کنید تا fallback به آنجا هدایت نشود. - **درخواست LLM رد شد: امضای تفکر لازم است (Google Antigravity)** + **درخواست LLM رد شد: امضای thinking لازم است (Google Antigravity)** - علت: تاریخچه نشست شامل **بلوک‌های تفکر بدون امضا** است (اغلب از - یک جریان قطع‌شده/جزئی). Google Antigravity برای بلوک‌های تفکر به امضا نیاز دارد. + علت: تاریخچه نشست شامل **بلوک‌های thinking بدون امضا** است (اغلب از + یک جریان لغوشده/ناقص). Google Antigravity برای بلوک‌های thinking به امضا نیاز دارد. - رفع مشکل: OpenClaw اکنون بلوک‌های تفکر بدون امضا را برای Google Antigravity Claude حذف می‌کند. اگر همچنان ظاهر شد، یک **نشست جدید** شروع کنید یا برای آن عامل `/thinking off` را تنظیم کنید. + اصلاح: OpenClaw اکنون بلوک‌های thinking بدون امضا را برای Google Antigravity Claude حذف می‌کند. اگر هنوز ظاهر می‌شود، یک **نشست جدید** شروع کنید یا برای آن عامل `/thinking off` را تنظیم کنید. -## پروفایل‌های احراز هویت: چیستی آن‌ها و روش مدیریتشان +## پروفایل‌های احراز هویت: چه هستند و چگونه آن‌ها را مدیریت کنید مرتبط: [/concepts/oauth](/fa/concepts/oauth) (جریان‌های OAuth، ذخیره‌سازی توکن، الگوهای چندحسابی) - پروفایل احراز هویت یک رکورد اعتبارنامه نام‌گذاری‌شده (OAuth یا کلید API) است که به یک ارائه‌دهنده متصل است. پروفایل‌ها در این مسیر قرار دارند: + پروفایل احراز هویت یک رکورد اعتبارنامه نام‌گذاری‌شده (OAuth یا کلید API) است که به یک ارائه‌دهنده متصل است. پروفایل‌ها در اینجا قرار دارند: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` + برای بررسی پروفایل‌های ذخیره‌شده بدون افشای اسرار، `openclaw models auth list` را اجرا کنید (در صورت نیاز با `--provider ` یا `--json`). برای جزئیات، [CLI مدل‌ها](/fa/cli/models#openclaw-models-auth-list) را ببینید. + - - OpenClaw از شناسه‌های دارای پیشوند ارائه‌دهنده استفاده می‌کند، مانند: + + OpenClaw از شناسه‌های دارای پیشوند ارائه‌دهنده مانند این‌ها استفاده می‌کند: - - `anthropic:default` (وقتی هویت ایمیلی وجود ندارد رایج است) + - `anthropic:default` (رایج وقتی هویت ایمیلی وجود ندارد) - `anthropic:` برای هویت‌های OAuth - - شناسه‌های سفارشی که خودتان انتخاب می‌کنید (برای مثال `anthropic:work`) + - شناسه‌های سفارشی که انتخاب می‌کنید (مثلاً `anthropic:work`) - - بله. پیکربندی از فراداده اختیاری برای پروفایل‌ها و یک ترتیب برای هر ارائه‌دهنده (`auth.order.`) پشتیبانی می‌کند. این کار رازها را ذخیره **نمی‌کند**؛ شناسه‌ها را به ارائه‌دهنده/حالت نگاشت می‌کند و ترتیب چرخش را تنظیم می‌کند. + + بله. پیکربندی از فراداده اختیاری برای پروفایل‌ها و ترتیب‌بندی برای هر ارائه‌دهنده (`auth.order.`) پشتیبانی می‌کند. این مورد اسرار را ذخیره نمی‌کند؛ شناسه‌ها را به ارائه‌دهنده/حالت نگاشت می‌کند و ترتیب چرخش را تنظیم می‌کند. - OpenClaw ممکن است اگر یک پروفایل در **دوره انتظار** کوتاه (محدودیت‌های نرخ/مهلت‌پایان‌یافته/شکست‌های احراز هویت) یا وضعیت **غیرفعال** طولانی‌تر (صورتحساب/اعتبار ناکافی) باشد، موقتاً از آن بگذرد. برای بررسی این مورد، `openclaw models status --json` را اجرا کنید و `auth.unusableProfiles` را بررسی کنید. تنظیم: `auth.cooldowns.billingBackoffHours*`. + OpenClaw ممکن است اگر پروفایلی در یک **دوره انتظار** کوتاه باشد (محدودیت نرخ/مهلت‌های زمانی/شکست‌های احراز هویت) یا در وضعیت **غیرفعال** طولانی‌تر باشد (صورت‌حساب/اعتبار ناکافی)، آن را موقتاً رد کند. برای بررسی این موضوع، `openclaw models status --json` را اجرا کنید و `auth.unusableProfiles` را بررسی کنید. تنظیم: `auth.cooldowns.billingBackoffHours*`. - دوره‌های انتظار محدودیت نرخ می‌توانند محدود به مدل باشند. پروفایلی که برای یک مدل - در حال انتظار است، همچنان می‌تواند برای یک مدل خواهر روی همان ارائه‌دهنده قابل‌استفاده باشد، - در حالی که پنجره‌های صورتحساب/غیرفعال همچنان کل پروفایل را مسدود می‌کنند. + دوره‌های انتظار محدودیت نرخ می‌توانند به مدل محدود باشند. پروفایلی که + برای یک مدل در دوره انتظار است، همچنان می‌تواند برای مدل هم‌خانواده روی همان ارائه‌دهنده قابل استفاده باشد، + در حالی که بازه‌های صورت‌حساب/غیرفعال همچنان کل پروفایل را مسدود می‌کنند. - همچنین می‌توانید از طریق CLI یک بازنویسی ترتیب **برای هر عامل** تنظیم کنید (در `auth-state.json` همان عامل ذخیره می‌شود): + همچنین می‌توانید با CLI یک ترتیب بازنویسی **برای هر عامل** تنظیم کنید (که در `auth-state.json` همان عامل ذخیره می‌شود): ```bash # Defaults to the configured default agent (omit --agent) @@ -501,37 +505,37 @@ x-i18n: openclaw models auth order clear --provider anthropic ``` - برای هدف‌گیری یک عامل مشخص: + برای هدف‌گرفتن یک عامل مشخص: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - برای تأیید این‌که واقعاً چه چیزی امتحان خواهد شد، استفاده کنید از: + برای راستی‌آزمایی اینکه واقعاً چه چیزی امتحان خواهد شد، از این استفاده کنید: ```bash openclaw models status --probe ``` - اگر یک پروفایل ذخیره‌شده از ترتیب صریح حذف شده باشد، کاوشگر به‌جای امتحان بی‌سروصدای آن، - `excluded_by_auth_order` را برای آن پروفایل گزارش می‌کند. + اگر یک پروفایل ذخیره‌شده از ترتیب صریح حذف شده باشد، probe به‌جای اینکه آن را بی‌صدا امتحان کند، + برای آن پروفایل `excluded_by_auth_order` گزارش می‌دهد. OpenClaw از هر دو پشتیبانی می‌کند: - - **OAuth** اغلب از دسترسی اشتراک استفاده می‌کند (در موارد قابل‌اعمال). - - **کلیدهای API** از صورتحساب پرداخت به‌ازای توکن استفاده می‌کنند. + - **OAuth** اغلب از دسترسی اشتراکی استفاده می‌کند (در موارد قابل اعمال). + - **کلیدهای API** از صورت‌حساب پرداخت به‌ازای توکن استفاده می‌کنند. - راهنمای مرحله‌ای به‌طور صریح از Anthropic Claude CLI، OpenAI Codex OAuth، و کلیدهای API پشتیبانی می‌کند. + راه‌انداز به‌طور صریح از Anthropic Claude CLI، OpenAI Codex OAuth و کلیدهای API پشتیبانی می‌کند. ## مرتبط -- [پرسش‌های متداول](/fa/help/faq) — پرسش‌های متداول اصلی -- [پرسش‌های متداول — شروع سریع و راه‌اندازی اجرای نخست](/fa/help/faq-first-run) +- [FAQ](/fa/help/faq) — FAQ اصلی +- [FAQ — شروع سریع و راه‌اندازی اجرای اول](/fa/help/faq-first-run) - [انتخاب مدل](/fa/concepts/model-providers) -- [Failover مدل](/fa/concepts/model-failover) +- [failover مدل](/fa/concepts/model-failover) diff --git a/docs/fa/help/testing-updates-plugins.md b/docs/fa/help/testing-updates-plugins.md index eacf43296..39be4686e 100644 --- a/docs/fa/help/testing-updates-plugins.md +++ b/docs/fa/help/testing-updates-plugins.md @@ -1,49 +1,36 @@ --- read_when: - - تغییر رفتار به‌روزرسانی، doctor، پذیرش بسته، یا نصب Plugin در OpenClaw - - آماده‌سازی یا تأیید نامزد انتشار - - اشکال‌زدایی به‌روزرسانی بسته، پاک‌سازی وابستگی‌های Plugin، یا رگرسیون‌های نصب Plugin + - تغییر رفتار به‌روزرسانی OpenClaw، doctor، پذیرش بسته یا نصب Plugin + - آماده‌سازی یا تأیید یک نامزد انتشار + - اشکال‌زدایی از پسرفت‌های به‌روزرسانی بسته، پاک‌سازی وابستگی‌های Plugin، یا نصب Plugin sidebarTitle: Update and plugin tests -summary: نحوهٔ اعتبارسنجی مسیرهای به‌روزرسانی، مهاجرت‌های بسته، و رفتار نصب/به‌روزرسانی Plugin توسط OpenClaw -title: 'آزمون: به‌روزرسانی‌ها و Plugin‌ها' +summary: نحوه اعتبارسنجی مسیرهای به‌روزرسانی، مهاجرت‌های بسته، و رفتار نصب/به‌روزرسانی Plugin توسط OpenClaw +title: 'آزمایش: به‌روزرسانی‌ها و Pluginها' x-i18n: - generated_at: "2026-05-03T11:37:39Z" + generated_at: "2026-05-05T01:49:11Z" model: gpt-5.5 provider: openai - source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd + source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286 source_path: help/testing-updates-plugins.md workflow: 16 --- -این چک‌لیست اختصاصی برای اعتبارسنجی به‌روزرسانی و Plugin است. هدف -ساده است: ثابت کنیم بستهٔ قابل‌نصب می‌تواند وضعیت واقعی کاربر را به‌روزرسانی کند، وضعیت -قدیمی و ماندهٔ legacy را از طریق `doctor` ترمیم کند، و همچنان بتواند -Pluginها را از منابع پشتیبانی‌شده نصب، بارگذاری، به‌روزرسانی و حذف نصب کند. +این چک‌لیست اختصاصی برای اعتبارسنجی به‌روزرسانی و Plugin است. هدف ساده است: ثابت شود بستهٔ قابل نصب می‌تواند وضعیت واقعی کاربر را به‌روزرسانی کند، وضعیت قدیمی و کهنهٔ legacy را از طریق `doctor` تعمیر کند، و همچنان Pluginها را از منابع پشتیبانی‌شده نصب، بارگذاری، به‌روزرسانی و حذف کند. -برای نقشهٔ گسترده‌تر اجراکنندهٔ تست، [Testing](/fa/help/testing) را ببینید. برای کلیدهای ارائه‌دهندهٔ زنده -و مجموعه‌هایی که شبکه را لمس می‌کنند، [Testing live](/fa/help/testing-live) را ببینید. +برای نقشهٔ گسترده‌تر اجرای آزمون‌ها، [آزمون‌گیری](/fa/help/testing) را ببینید. برای کلیدهای provider زنده و مجموعه‌هایی که با شبکه سروکار دارند، [آزمون‌گیری زنده](/fa/help/testing-live) را ببینید. ## از چه چیزی محافظت می‌کنیم -تست‌های به‌روزرسانی و Plugin از این قراردادها محافظت می‌کنند: +آزمون‌های به‌روزرسانی و Plugin از این قراردادها محافظت می‌کنند: -- یک tarball بسته کامل است، `dist/postinstall-inventory.json` معتبر دارد، - و به فایل‌های بازنشدهٔ repo وابسته نیست. -- کاربر می‌تواند از یک بستهٔ منتشرشدهٔ قدیمی‌تر به بستهٔ candidate - بدون از دست دادن config، agentها، sessionها، workspaceها، allowlistهای Plugin، یا - channel config مهاجرت کند. -- `openclaw doctor --fix --non-interactive` مالک مسیرهای پاک‌سازی و ترمیم - legacy است. Startup نباید migrationهای سازگاری پنهان برای وضعیت ماندهٔ - Plugin اضافه کند. -- نصب Plugin از دایرکتوری‌های محلی، repoهای git، بسته‌های npm، و مسیر - registry در ClawHub کار می‌کند. -- وابستگی‌های npm مربوط به Plugin در ریشهٔ npm مدیریت‌شده نصب می‌شوند، پیش از - trust اسکن می‌شوند، و هنگام uninstall از طریق npm حذف می‌شوند تا وابستگی‌های hoistشده - باقی نمانند. -- به‌روزرسانی Plugin وقتی چیزی تغییر نکرده پایدار است: رکوردهای نصب، source - resolveشده، چیدمان وابستگی نصب‌شده، و وضعیت enabled دست‌نخورده می‌مانند. +- یک tarball بسته کامل است، `dist/postinstall-inventory.json` معتبر دارد، و به فایل‌های بازشدهٔ repo وابسته نیست. +- کاربر می‌تواند از یک بستهٔ منتشرشدهٔ قدیمی‌تر به بستهٔ candidate منتقل شود، بدون اینکه config، agentها، sessionها، workspaceها، allowlistهای Plugin، یا config کانال را از دست بدهد. +- `openclaw doctor --fix --non-interactive` مالک مسیرهای پاک‌سازی و تعمیر legacy است. startup نباید migrationهای compatibility پنهان برای وضعیت کهنهٔ Plugin ایجاد کند. +- نصب Plugin از directoryهای local، repoهای git، بسته‌های npm، و مسیر registry مربوط به ClawHub کار می‌کند. +- وابستگی‌های npm مربوط به Plugin در root مدیریت‌شدهٔ npm نصب می‌شوند، قبل از trust اسکن می‌شوند، و هنگام uninstall از طریق npm حذف می‌شوند تا وابستگی‌های hoist‌شده باقی نمانند. +- به‌روزرسانی Plugin وقتی چیزی تغییر نکرده پایدار است: recordهای نصب، source حل‌شده، layout وابستگی نصب‌شده، و وضعیت enabled دست‌نخورده می‌مانند. -## اثبات محلی هنگام توسعه +## اثبات local هنگام توسعه محدود شروع کنید: @@ -53,31 +40,25 @@ pnpm check:changed pnpm test:changed ``` -برای تغییرات install، uninstall، dependency یا package-inventory مربوط به Plugin، همچنین -تست‌های متمرکزی را اجرا کنید که seam ویرایش‌شده را پوشش می‌دهند: +برای تغییرات نصب، حذف، وابستگی، یا package-inventory مربوط به Plugin، آزمون‌های متمرکزی را هم اجرا کنید که seam ویرایش‌شده را پوشش می‌دهند: ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -پیش از آنکه هر lane مربوط به Package Docker یک tarball را مصرف کند، artifact بسته را اثبات کنید: +پیش از اینکه هر lane بستهٔ Docker یک tarball مصرف کند، artifact بسته را ثابت کنید: ```bash pnpm release:check ``` -`release:check` بررسی‌های drift مربوط به config/docs/API را اجرا می‌کند، موجودی dist بسته را -می‌نویسد، `npm pack --dry-run` را اجرا می‌کند، فایل‌های بسته‌بندی‌شدهٔ ممنوع را رد می‌کند، -tarball را در یک prefix موقت نصب می‌کند، postinstall را اجرا می‌کند، و entrypointهای channel -باندل‌شده را smoke می‌کند. +`release:check` بررسی‌های drift مربوط به config/docs/API را اجرا می‌کند، package dist inventory را می‌نویسد، `npm pack --dry-run` را اجرا می‌کند، فایل‌های packed ممنوع را رد می‌کند، tarball را در یک prefix موقت نصب می‌کند، postinstall را اجرا می‌کند، و entrypointهای کانال bundle‌شده را smoke می‌کند. ## laneهای Docker -laneهای Docker اثبات در سطح محصول هستند. آن‌ها یک بستهٔ واقعی را داخل containerهای -Linux نصب یا به‌روزرسانی می‌کنند و رفتار را از طریق فرمان‌های CLI، -راه‌اندازی Gateway، probeهای HTTP، وضعیت RPC، و وضعیت filesystem بررسی می‌کنند. +laneهای Docker اثبات سطح محصول هستند. آن‌ها یک بستهٔ واقعی را داخل containerهای Linux نصب یا به‌روزرسانی می‌کنند و رفتار را از طریق دستورهای CLI، راه‌اندازی Gateway، probeهای HTTP، وضعیت RPC، و وضعیت filesystem assert می‌کنند. -هنگام iteration از laneهای متمرکز استفاده کنید: +هنگام تکرار و اصلاح، از laneهای متمرکز استفاده کنید: ```bash pnpm test:docker:plugins @@ -90,33 +71,14 @@ pnpm test:docker:update-migration laneهای مهم: -- `test:docker:plugins` smoke نصب Plugin، نصب از پوشهٔ محلی، - رفتار skip در update پوشهٔ محلی، پوشه‌های محلی با وابستگی‌های ازپیش‌نصب‌شده، - نصب بسته‌های `file:`، نصب از git با اجرای CLI، به‌روزرسانی‌های moving-ref در git، نصب از - registry در npm با وابستگی‌های transitive هوist‌شده، no-opهای update در npm، نصب از fixture محلی - ClawHub و no-opهای update، رفتار update در marketplace، و enable/inspect بستهٔ Claude را - اعتبارسنجی می‌کند. برای hermetic/offline نگه داشتن بلوک ClawHub، - `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید. -- `test:docker:plugin-lifecycle-matrix` بستهٔ candidate را در یک container خام نصب می‌کند، - یک npm Plugin را از مسیر install، inspect، disable، enable، - upgrade صریح، downgrade صریح، و uninstall پس از حذف کد Plugin عبور می‌دهد. - برای هر فاز metricهای RSS و CPU را log می‌کند. -- `test:docker:plugin-update` اعتبارسنجی می‌کند که یک Plugin نصب‌شدهٔ بدون تغییر - هنگام `openclaw plugins update` دوباره نصب نشود یا metadata نصب را از دست ندهد. -- `test:docker:upgrade-survivor` tarball candidate را روی یک fixture کاربر قدیمی و آلوده - نصب می‌کند، update بسته به‌همراه doctor غیرتعاملی را اجرا می‌کند، سپس - یک Gateway روی loopback راه‌اندازی می‌کند و preservation وضعیت را بررسی می‌کند. -- `test:docker:published-upgrade-survivor` ابتدا یک baseline منتشرشده را نصب می‌کند، - آن را از طریق recipe پخته‌شدهٔ `openclaw config set` پیکربندی می‌کند، آن را به - tarball candidate به‌روزرسانی می‌کند، doctor را اجرا می‌کند، cleanup legacy را بررسی می‌کند، - Gateway را راه‌اندازی می‌کند، و `/healthz`، `/readyz` و وضعیت RPC را probe می‌کند. -- `test:docker:update-migration` lane منتشرشدهٔ update با تمرکز زیاد بر cleanup است. از - وضعیت کاربری پیکربندی‌شده به سبک Discord/Telegram شروع می‌کند، baseline - doctor را اجرا می‌کند تا وابستگی‌های Plugin پیکربندی‌شده فرصت materialize شدن داشته باشند، برای یک Plugin بسته‌بندی‌شدهٔ پیکربندی‌شده - debris وابستگی legacy Plugin را seed می‌کند، به tarball candidate - به‌روزرسانی می‌کند، و از doctor پس از update می‌خواهد ریشه‌های وابستگی legacy را حذف کند. +- `test:docker:plugins` smoke نصب Plugin، نصب از folderهای local، رفتار skip به‌روزرسانی folderهای local، folderهای local با وابستگی‌های ازپیش‌نصب‌شده، نصب بسته‌های `file:`، نصب‌های git همراه با اجرای CLI، به‌روزرسانی ref متحرک git، نصب‌های registry مربوط به npm با وابستگی‌های transitive هوist‌شده، no-opهای به‌روزرسانی npm، نصب‌های fixture local مربوط به ClawHub و no-opهای به‌روزرسانی، رفتار به‌روزرسانی marketplace، و enable/inspect مربوط به bundle کلود را اعتبارسنجی می‌کند. برای hermetic/offline نگه‌داشتن بلوک ClawHub، `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید. +- `test:docker:plugin-lifecycle-matrix` بستهٔ candidate را در یک container bare نصب می‌کند، یک Plugin از نوع npm را از مسیر install، inspect، disable، enable، upgrade صریح، downgrade صریح، و uninstall پس از حذف کد Plugin عبور می‌دهد. برای هر phase، metricهای RSS و CPU را log می‌کند. +- `test:docker:plugin-update` اعتبارسنجی می‌کند که یک Plugin نصب‌شدهٔ بدون تغییر هنگام `openclaw plugins update` دوباره نصب نشود یا metadata نصب را از دست ندهد. +- `test:docker:upgrade-survivor` tarball مربوط به candidate را روی یک fixture قدیمی و آلودهٔ کاربر نصب می‌کند، به‌روزرسانی بسته به‌همراه doctor غیرتعاملی را اجرا می‌کند، سپس یک Gateway از نوع loopback راه‌اندازی می‌کند و حفظ وضعیت را بررسی می‌کند. +- `test:docker:published-upgrade-survivor` ابتدا یک baseline منتشرشده را نصب می‌کند، آن را از طریق recipe پخته‌شدهٔ `openclaw config set` config می‌کند، به tarball مربوط به candidate به‌روزرسانی می‌کند، doctor را اجرا می‌کند، پاک‌سازی legacy را بررسی می‌کند، Gateway را راه‌اندازی می‌کند، و `/healthz`، `/readyz`، و وضعیت RPC را probe می‌کند. +- `test:docker:update-migration` lane به‌روزرسانی منتشرشده‌ای است که پاک‌سازی در آن سنگین است. از یک وضعیت کاربر config‌شده شبیه Discord/Telegram شروع می‌کند، baseline doctor را اجرا می‌کند تا وابستگی‌های Pluginهای config‌شده فرصت materialize شدن داشته باشند، debris مربوط به وابستگی‌های legacy Plugin را برای یک Plugin بسته‌بندی‌شدهٔ config‌شده seed می‌کند، به tarball مربوط به candidate به‌روزرسانی می‌کند، و از doctor پس از به‌روزرسانی می‌خواهد rootهای وابستگی legacy را حذف کند. -variantهای مفید برای published-upgrade survivor: +variantهای مفید published-upgrade survivor: ```bash OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \ @@ -128,15 +90,9 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \ pnpm test:docker:published-upgrade-survivor ``` -scenarioهای موجود عبارت‌اند از `base`، `feishu-channel`، `bootstrap-persona`، -`plugin-deps-cleanup`، `configured-plugin-installs`، `tilde-log-path`، و -`versioned-runtime-deps`. در اجرای تجمیعی، -`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` به همهٔ scenarioهای شبیه issue گزارش‌شده -گسترش می‌یابد، از جمله migration نصب Plugin پیکربندی‌شده. +scenarioهای موجود عبارت‌اند از `base`، `feishu-channel`، `bootstrap-persona`، `plugin-deps-cleanup`، `configured-plugin-installs`، `stale-source-plugin-shadow`، `tilde-log-path`، و `versioned-runtime-deps`. در اجراهای aggregate، `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` به همهٔ scenarioهای شبیه issue گزارش‌شده گسترش می‌یابد، از جمله migration نصب Plugin config‌شده. -update migration کامل عمداً از Full Release CI جداست. وقتی پرسش release این است که «آیا هر -release پایدار منتشرشده از 2026.4.23 به بعد می‌تواند به این candidate به‌روزرسانی شود و -debris وابستگی Plugin را پاک کند؟»، از workflow دستی `Update Migration` استفاده کنید: +migration کامل به‌روزرسانی عمداً از Full Release CI جداست. وقتی پرسش release این است که «آیا هر release پایدار منتشرشده از 2026.4.23 به بعد می‌تواند به این candidate به‌روزرسانی شود و debris وابستگی‌های Plugin را پاک کند؟»، از workflow دستی `Update Migration` استفاده کنید: ```bash gh workflow run update-migration.yml \ @@ -147,34 +103,26 @@ gh workflow run update-migration.yml \ -f scenarios=plugin-deps-cleanup ``` -## Package Acceptance +## پذیرش بسته -Package Acceptance gate بومی GitHub برای بسته است. یک بستهٔ candidate را به یک tarball -`package-under-test` resolve می‌کند، version و SHA-256 را ثبت می‌کند، سپس -laneهای Docker E2E قابل‌استفادهٔ مجدد را در برابر همان tarball دقیق اجرا می‌کند. harness -workflow ref جدا از package source ref است، پس منطق تست فعلی می‌تواند releaseهای مورداعتماد قدیمی‌تر را -اعتبارسنجی کند. +Package Acceptance گیت package بومی GitHub است. یک بستهٔ candidate را به یک tarball با نام `package-under-test` resolve می‌کند، version و SHA-256 را ثبت می‌کند، سپس laneهای reusable مربوط به Docker E2E را روی همان tarball دقیق اجرا می‌کند. ref مربوط به harness workflow از ref مربوط به source بسته جداست، بنابراین منطق آزمون فعلی می‌تواند releaseهای مورد اعتماد قدیمی‌تر را اعتبارسنجی کند. -منابع candidate: +sourceهای candidate: -- `source=npm`: اعتبارسنجی `openclaw@beta`، `openclaw@latest`، یا یک - version منتشرشدهٔ دقیق. -- `source=ref`: pack کردن یک branch، tag، یا commit مورداعتماد با harness فعلی انتخاب‌شده. -- `source=url`: اعتبارسنجی یک tarball HTTPS با `package_sha256` الزامی. -- `source=artifact`: استفادهٔ مجدد از tarball آپلودشده توسط یک اجرای دیگر Actions. +- `source=npm`: اعتبارسنجی `openclaw@beta`، `openclaw@latest`، یا یک version منتشرشدهٔ دقیق. +- `source=ref`: pack کردن یک branch، tag، یا commit مورد اعتماد با harness فعلی انتخاب‌شده. +- `source=url`: اعتبارسنجی یک tarball از نوع HTTPS با `package_sha256` الزامی. +- `source=artifact`: استفادهٔ دوباره از tarball آپلودشده توسط یک run دیگر از Actions. -Full Release Validation به‌صورت پیش‌فرض از `source=artifact` استفاده می‌کند، که از -SHA resolveشدهٔ release ساخته شده است. برای اثبات پس از publish، -`package_acceptance_package_spec=openclaw@YYYY.M.D` را پاس بدهید تا همان ماتریس upgrade -بستهٔ npm ارسال‌شده را هدف بگیرد. +Full Release Validation به‌صورت پیش‌فرض از `source=artifact` استفاده می‌کند، ساخته‌شده از SHA مربوط به release حل‌شده. برای اثبات پس از انتشار، `package_acceptance_package_spec=openclaw@YYYY.M.D` را pass کنید تا همان matrix ارتقا، بستهٔ npm ارسال‌شده را هدف بگیرد. -Release checkها Package Acceptance را با مجموعهٔ package/update/plugin فراخوانی می‌کنند: +بررسی‌های release، Package Acceptance را با مجموعهٔ package/update/plugin فراخوانی می‌کنند: ```text doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update ``` -همچنین این موارد را پاس می‌دهند: +آن‌ها همچنین این موارد را pass می‌کنند: ```text published_upgrade_survivor_baselines=all-since-2026.4.23 @@ -182,16 +130,11 @@ published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -این کار migration بسته، switching channel برای update، cleanup وابستگی ماندهٔ Plugin، -پوشش offline Plugin، رفتار update Plugin، و QA بستهٔ Telegram را روی همان artifact -resolveشده نگه می‌دارد. +این کار migration بسته، تغییر کانال به‌روزرسانی، پاک‌سازی وابستگی‌های کهنهٔ Plugin، پوشش offline Plugin، رفتار به‌روزرسانی Plugin، و QA بستهٔ Telegram را روی همان artifact حل‌شده نگه می‌دارد. -`all-since-2026.4.23` نمونهٔ upgrade در Full Release CI است: هر release پایدار منتشرشده در npm از `2026.4.23` تا `latest`. برای پوشش کامل -published update migration، به‌جای Full Release CI از `all-since-2026.4.23` در workflow جداگانهٔ Update -Migration استفاده کنید. `release-history` همچنان -برای نمونه‌گیری گسترده‌تر دستی در دسترس است، وقتی anchor legacy مربوط به پیش از آن تاریخ را هم می‌خواهید. +`all-since-2026.4.23` نمونهٔ upgrade مربوط به Full Release CI است: هر release پایدار منتشرشده در npm از `2026.4.23` تا `latest`. برای پوشش exhaustive migration به‌روزرسانی منتشرشده، به‌جای Full Release CI از `all-since-2026.4.23` در workflow جداگانهٔ Update Migration استفاده کنید. `release-history` برای نمونه‌برداری دستی گسترده‌تر، وقتی anchor قدیمی pre-date را هم می‌خواهید، همچنان در دسترس است. -هنگام اعتبارسنجی یک candidate پیش از release، یک profile بسته را دستی اجرا کنید: +هنگام اعتبارسنجی candidate پیش از release، یک profile بسته را دستی اجرا کنید: ```bash gh workflow run package-acceptance.yml \ @@ -205,68 +148,49 @@ gh workflow run package-acceptance.yml \ -f telegram_mode=mock-openai ``` -وقتی پرسش release شامل channelهای MCP، -cleanup مربوط به cron/subagent، جست‌وجوی وب OpenAI، یا OpenWebUI است، از `suite_profile=product` استفاده کنید. فقط وقتی به پوشش کامل -Docker برای مسیر release نیاز دارید از `suite_profile=full` استفاده کنید. +وقتی پرسش release شامل کانال‌های MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، یا OpenWebUI است، از `suite_profile=product` استفاده کنید. فقط وقتی به پوشش کامل مسیر release در Docker نیاز دارید، از `suite_profile=full` استفاده کنید. ## پیش‌فرض release برای release candidateها، stack اثبات پیش‌فرض این است: 1. `pnpm check:changed` و `pnpm test:changed` برای regressionهای سطح source. -2. `pnpm release:check` برای سلامت artifact بسته. -3. profile `package` در Package Acceptance یا laneهای سفارشی package مربوط به release-check - برای قراردادهای install/update/plugin. -4. Cross-OS release checkها برای installer، onboarding، و رفتار platform-specific. -5. مجموعه‌های live فقط وقتی سطح تغییریافته رفتار provider یا hosted-service را لمس می‌کند. +2. `pnpm release:check` برای یکپارچگی artifact بسته. +3. profile `package` مربوط به Package Acceptance یا laneهای custom package مربوط به release-check برای قراردادهای install/update/plugin. +4. بررسی‌های release میان‌سیستمی برای installer، onboarding، و رفتار platform مخصوص OS. +5. مجموعه‌های زنده فقط زمانی که سطح تغییر با رفتار provider یا سرویس hosted تماس دارد. -روی ماشین‌های maintainer، gateهای گسترده و اثبات محصول Docker/package باید در -Testbox اجرا شوند، مگر اینکه صراحتاً اثبات محلی انجام می‌دهید. +روی ماشین‌های maintainer، gateهای broad و اثبات محصول Docker/package باید در Testbox اجرا شوند، مگر اینکه اثبات local صراحتاً انجام شود. ## سازگاری legacy -leniency سازگاری محدود و دارای بازهٔ زمانی است: +نرمش compatibility محدود و زمان‌بندی‌شده است: -- بسته‌ها تا `2026.4.25`، از جمله `2026.4.25-beta.*`، ممکن است gapهای metadata بستهٔ ازپیش‌ارسال‌شده را - در Package Acceptance تحمل کنند. -- بستهٔ منتشرشدهٔ `2026.4.26` ممکن است برای فایل‌های stamp مربوط به local build metadata - که از قبل ارسال شده‌اند هشدار بدهد. -- بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند. همان gapها به‌جای - warning یا skip باعث failure می‌شوند. +- بسته‌ها تا `2026.4.25`، از جمله `2026.4.25-beta.*`، ممکن است gapهای metadata بسته را که قبلاً ارسال شده‌اند در Package Acceptance تحمل کنند. +- بستهٔ منتشرشدهٔ `2026.4.26` ممکن است برای فایل‌های stamp مربوط به metadata build local که قبلاً ارسال شده‌اند هشدار بدهد. +- بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند. همان gapها به‌جای warning یا skipping، fail می‌شوند. -برای این شکل‌های قدیمی، migration تازه‌ای در startup اضافه نکنید. یک ترمیم doctor -اضافه یا گسترش دهید، سپس آن را با `upgrade-survivor` یا `published-upgrade-survivor` اثبات کنید. +برای این شکل‌های قدیمی، startup migrationهای جدید اضافه نکنید. یک repair در doctor اضافه یا extend کنید، سپس آن را با `upgrade-survivor` یا `published-upgrade-survivor` ثابت کنید. ## افزودن پوشش -هنگام تغییر رفتار update یا Plugin، پوشش را در پایین‌ترین لایه‌ای اضافه کنید که -می‌تواند به دلیل درست fail شود: +هنگام تغییر رفتار به‌روزرسانی یا Plugin، پوشش را در پایین‌ترین لایه‌ای اضافه کنید که بتواند به دلیل درست fail شود: -- منطق pure path یا metadata: unit test کنار source. -- رفتار package inventory یا packed-file: تست `package-dist-inventory` یا tarball - checker. -- رفتار CLI install/update: assertion یا fixture در lane Docker. -- رفتار migration برای published-release: scenario در `published-upgrade-survivor`. -- رفتار registry/package source: fixture در `test:docker:plugins` یا server fixture - ClawHub. -- رفتار چیدمان یا cleanup وابستگی: هم اجرای runtime و هم مرز filesystem را assert کنید. وابستگی‌های npm ممکن است زیر ریشهٔ npm مدیریت‌شده hoist شوند، - بنابراین تست‌ها باید ثابت کنند ریشه اسکن/پاک می‌شود، نه اینکه یک درخت `node_modules` - محلی بسته را فرض کنند. +- منطق pure مربوط به path یا metadata: unit test کنار source. +- رفتار package inventory یا packed-file: آزمون `package-dist-inventory` یا checker مربوط به tarball. +- رفتار نصب/به‌روزرسانی CLI: assertion یا fixture در lane مربوط به Docker. +- رفتار migration مربوط به published-release: scenario در `published-upgrade-survivor`. +- رفتار registry/package source: fixture مربوط به `test:docker:plugins` یا server fixture مربوط به ClawHub. +- رفتار layout یا پاک‌سازی وابستگی: هم اجرای runtime و هم مرز filesystem را assert کنید. وابستگی‌های npm ممکن است زیر root مدیریت‌شدهٔ npm hoist شوند، بنابراین آزمون‌ها باید به‌جای فرض کردن یک tree از نوع `node_modules` در سطح package-local، ثابت کنند root اسکن/پاک‌سازی می‌شود. -fixtureهای Docker جدید را به‌صورت پیش‌فرض hermetic نگه دارید. از registryهای fixture محلی و -بسته‌های fake استفاده کنید، مگر اینکه هدف تست رفتار registry زنده باشد. +fixtureهای جدید Docker را به‌صورت پیش‌فرض hermetic نگه دارید. از registryهای fixture local و بسته‌های fake استفاده کنید، مگر اینکه نکتهٔ آزمون رفتار registry زنده باشد. -## تریاژ failure +## triage شکست -از هویت artifact شروع کنید: +با هویت artifact شروع کنید: -- summary مربوط به `resolve_package` در Package Acceptance: source، version، SHA-256، و - نام artifact. -- artifactهای Docker: `.artifacts/docker-tests/**/summary.json`, - `failures.json`، logهای lane، و فرمان‌های rerun. -- summary مربوط به Upgrade survivor: `.artifacts/upgrade-survivor/summary.json`, - شامل baseline version، candidate version، scenario، timingهای phase، و - recipe stepها. +- summary مربوط به Package Acceptance `resolve_package`: source، version، SHA-256، و نام artifact. +- artifactهای Docker: `.artifacts/docker-tests/**/summary.json`، `failures.json`، logهای lane، و دستورهای rerun. +- summary مربوط به Upgrade survivor: `.artifacts/upgrade-survivor/summary.json`، شامل version مربوط به baseline، version مربوط به candidate، scenario، timingهای phase، و stepهای recipe. -rerun همان lane دقیق failشده با همان artifact بسته را به -rerun کل چتر release ترجیح دهید. +rerun کردن lane دقیق fail‌شده با همان artifact بسته را به rerun کردن کل چتر release ترجیح دهید. diff --git a/docs/fa/help/testing.md b/docs/fa/help/testing.md index 5049c16b9..853bdadee 100644 --- a/docs/fa/help/testing.md +++ b/docs/fa/help/testing.md @@ -1,219 +1,176 @@ --- read_when: - اجرای آزمون‌ها به‌صورت محلی یا در CI - - افزودن آزمون‌های رگرسیون برای باگ‌های مدل/ارائه‌دهنده + - افزودن آزمون‌های رگرسیون برای اشکال‌های مدل/ارائه‌دهنده - اشکال‌زدایی رفتار Gateway + عامل -summary: 'کیت تست: مجموعه‌های unit/e2e/live، اجراکننده‌های Docker، و اینکه هر تست چه مواردی را پوشش می‌دهد' -title: آزمایش +summary: 'کیت آزمون: مجموعه‌های آزمون واحد/سرتاسری/زنده، اجراکننده‌های Docker، و اینکه هر آزمون چه چیزی را پوشش می‌دهد' +title: آزمون x-i18n: - generated_at: "2026-05-04T07:05:47Z" + generated_at: "2026-05-05T01:49:26Z" model: gpt-5.5 provider: openai - source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 + source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 source_path: help/testing.md workflow: 16 --- -OpenClaw سه مجموعه Vitest دارد (واحد/یکپارچه‌سازی، e2e، زنده) و مجموعه کوچکی -از اجراکننده‌های Docker. این سند راهنمای «ما چگونه آزمون می‌کنیم» است: +OpenClaw سه مجموعه Vitest دارد (واحد/یکپارچه‌سازی، e2e، زنده) و مجموعه‌ای کوچک +از اجراکننده‌های Docker. این سند راهنمای «چگونه آزمون می‌کنیم» است: -- هر مجموعه چه چیزهایی را پوشش می‌دهد (و عمداً چه چیزهایی را پوشش _نمی‌دهد_). -- برای جریان‌های کاری رایج (محلی، پیش از push، اشکال‌زدایی) کدام فرمان‌ها را اجرا کنید. -- آزمون‌های زنده چگونه اعتبارنامه‌ها را کشف می‌کنند و مدل‌ها/ارائه‌دهندگان را انتخاب می‌کنند. -- چگونه برای مشکلات واقعی مدل/ارائه‌دهنده، رگرسیون اضافه کنید. +- هر مجموعه چه چیزهایی را پوشش می‌دهد (و عمدا چه چیزهایی را پوشش _نمی‌دهد_). +- برای جریان‌های کاری رایج (محلی، پیش از push، اشکال‌زدایی) کدام دستورها را اجرا کنید. +- آزمون‌های زنده چگونه اعتبارنامه‌ها را کشف می‌کنند و مدل‌ها/ارائه‌دهنده‌ها را انتخاب می‌کنند. +- چگونه برای مشکلات واقعی مدل/ارائه‌دهنده آزمون‌های رگرسیون اضافه کنید. -**پشته QA (qa-lab، qa-channel، مسیرهای انتقال زنده)** به‌صورت جداگانه مستند شده است: +**پشته QA (qa-lab، qa-channel، مسیرهای انتقال زنده)** جداگانه مستند شده است: -- [نمای کلی QA](/fa/concepts/qa-e2e-automation) — معماری، سطح فرمان، نوشتن سناریو. -- [Matrix QA](/fa/concepts/qa-matrix) — مرجع `pnpm openclaw qa matrix`. +- [نمای کلی QA](/fa/concepts/qa-e2e-automation) — معماری، سطح دستورها، نگارش سناریو. +- [QA ماتریسی](/fa/concepts/qa-matrix) — مرجع برای `pnpm openclaw qa matrix`. - [کانال QA](/fa/channels/qa-channel) — Plugin انتقال مصنوعی که سناریوهای پشتیبانی‌شده با مخزن از آن استفاده می‌کنند. -این صفحه اجرای مجموعه‌های آزمون عادی و اجراکننده‌های Docker/Parallels را پوشش می‌دهد. بخش اجراکننده‌های ویژه QA در ادامه ([اجراکننده‌های ویژه QA](#qa-specific-runners)) فراخوانی‌های مشخص `qa` را فهرست می‌کند و دوباره به مراجع بالا ارجاع می‌دهد. +این صفحه اجرای مجموعه‌های آزمون معمول و اجراکننده‌های Docker/Parallels را پوشش می‌دهد. بخش اجراکننده‌های مخصوص QA در پایین ([اجراکننده‌های مخصوص QA](#qa-specific-runners)) فراخوانی‌های مشخص `qa` را فهرست می‌کند و دوباره به مراجع بالا ارجاع می‌دهد. ## شروع سریع در بیشتر روزها: -- دروازه کامل (پیش از push انتظار می‌رود): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- اجرای سریع‌تر مجموعه کامل محلی روی دستگاهی با منابع کافی: `pnpm test:max` +- گیت کامل (مورد انتظار پیش از push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- اجرای سریع‌تر کل مجموعه محلی روی ماشینی با منابع کافی: `pnpm test:max` - حلقه watch مستقیم Vitest: `pnpm test:watch` - هدف‌گیری مستقیم فایل اکنون مسیرهای افزونه/کانال را هم مسیریابی می‌کند: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- وقتی روی یک شکست واحد تکرار می‌کنید، ابتدا اجراهای هدفمند را ترجیح دهید. -- سایت QA پشتیبانی‌شده با Docker: `pnpm qa:lab:up` -- مسیر QA پشتیبانی‌شده با ماشین مجازی Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- وقتی روی یک شکست واحد کار می‌کنید، ابتدا اجرای هدفمند را ترجیح دهید. +- سایت QA با پشتوانه Docker: `pnpm qa:lab:up` +- مسیر QA با پشتوانه ماشین مجازی Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` وقتی آزمون‌ها را تغییر می‌دهید یا اطمینان بیشتری می‌خواهید: -- دروازه پوشش: `pnpm test:coverage` +- گیت پوشش: `pnpm test:coverage` - مجموعه E2E: `pnpm test:e2e` -هنگام اشکال‌زدایی ارائه‌دهندگان/مدل‌های واقعی (به اعتبارنامه واقعی نیاز دارد): +هنگام اشکال‌زدایی ارائه‌دهنده‌ها/مدل‌های واقعی (نیازمند اعتبارنامه‌های واقعی): -- مجموعه زنده (مدل‌ها + بررسی‌های ابزار/تصویر Gateway): `pnpm test:live` -- هدف‌گیری بی‌صدای یک فایل زنده: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- مجموعه زنده (مدل‌ها + پروب‌های ابزار/تصویر Gateway): `pnpm test:live` +- هدف‌گیری بی‌سروصدای یک فایل زنده: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - گزارش‌های عملکرد زمان اجرا: `OpenClaw Performance` را با `live_gpt54=true` برای یک نوبت عامل واقعی `openai/gpt-5.4` یا - `deep_profile=true` برای مصنوعات CPU/heap/trace مربوط به Kova dispatch کنید. اجراهای زمان‌بندی‌شده روزانه - وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، مصنوعات مسیر mock-provider، deep-profile، و GPT 5.4 را در - `openclaw/clawgrit-reports` منتشر می‌کنند. گزارش - mock-provider همچنین شامل اعداد بوت Gateway در سطح منبع، حافظه، - فشار Plugin، حلقه تکراری hello-loop مدل ساختگی، و راه‌اندازی CLI است. -- پیمایش مدل زنده Docker: `pnpm test:docker:live-models` - - هر مدل انتخاب‌شده اکنون یک نوبت متنی به‌علاوه یک بررسی کوچک به سبک خواندن فایل را اجرا می‌کند. - مدل‌هایی که فراداده آن‌ها ورودی `image` را اعلام می‌کند، یک نوبت تصویر کوچک هم اجرا می‌کنند. - هنگام جداسازی شکست‌های ارائه‌دهنده، بررسی‌های اضافی را با `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` یا + `deep_profile=true` برای مصنوعات CPU/heap/trace مربوط به Kova اجرا کنید. اجراهای زمان‌بندی‌شده روزانه + وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، مصنوعات مسیر ارائه‌دهنده ساختگی، پروفایل عمیق، و GPT 5.4 را در + `openclaw/clawgrit-reports` منتشر می‌کنند. گزارش ارائه‌دهنده ساختگی همچنین شامل اعداد راه‌اندازی Gateway در سطح منبع، حافظه، + فشار Plugin، حلقه سلام مدل ساختگی تکرارشونده، و شروع CLI است. +- جاروب مدل زنده Docker: `pnpm test:docker:live-models` + - هر مدل انتخاب‌شده اکنون یک نوبت متنی به‌علاوه یک پروب کوچک شبیه خواندن فایل را اجرا می‌کند. + مدل‌هایی که فراداده‌شان ورودی `image` را تبلیغ می‌کند، یک نوبت تصویر کوچک هم اجرا می‌کنند. + هنگام جداسازی شکست‌های ارائه‌دهنده، پروب‌های اضافی را با `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` یا `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` غیرفعال کنید. - - پوشش CI: `OpenClaw Scheduled Live And E2E Checks` روزانه و - `OpenClaw Release Checks` دستی هر دو گردش کار قابل استفاده مجدد live/E2E را با - `include_live_suites: true` فراخوانی می‌کنند، که شامل کارهای ماتریسی جداگانه مدل زنده Docker - است که بر اساس ارائه‌دهنده shard شده‌اند. + - پوشش CI: هر دو اجرای روزانه `OpenClaw Scheduled Live And E2E Checks` و دستی + `OpenClaw Release Checks` گردش‌کار زنده/E2E قابل استفاده مجدد را با + `include_live_suites: true` فراخوانی می‌کنند؛ این شامل jobهای جداگانه ماتریس مدل زنده Docker است + که بر اساس ارائه‌دهنده shard شده‌اند. - برای اجرای دوباره متمرکز در CI، `OpenClaw Live And E2E Checks (Reusable)` را - با `include_live_suites: true` و `live_models_only: true` dispatch کنید. - - رازهای ارائه‌دهنده جدید و با سیگنال بالا را به `scripts/ci-hydrate-live-auth.sh` + با `include_live_suites: true` و `live_models_only: true` اجرا کنید. + - رازهای جدید و پرسیگنال ارائه‌دهنده را به `scripts/ci-hydrate-live-auth.sh` به‌علاوه `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` و فراخوان‌های - زمان‌بندی‌شده/انتشار آن اضافه کنید. -- smoke گفت‌وگوی متصل بومی Codex: `pnpm test:docker:live-codex-bind` - - یک مسیر زنده Docker را در برابر مسیر app-server مربوط به Codex اجرا می‌کند، یک پیام مستقیم مصنوعی + زمان‌بندی‌شده/انتشاری آن اضافه کنید. +- اسموک چت متصل بومی Codex: `pnpm test:docker:live-codex-bind` + - یک مسیر زنده Docker را در برابر مسیر app-server مربوط به Codex اجرا می‌کند، یک DM مصنوعی Slack را با `/codex bind` متصل می‌کند، `/codex fast` و - `/codex permissions` را تمرین می‌کند، سپس تأیید می‌کند که یک پاسخ ساده و یک پیوست تصویر - به‌جای ACP از طریق اتصال بومی Plugin عبور می‌کنند. -- smoke ابزار app-server مربوط به Codex: `pnpm test:docker:live-codex-harness` - - نوبت‌های عامل Gateway را از طریق ابزار app-server مالکیت‌شده توسط Plugin مربوط به Codex اجرا می‌کند، - `/codex status` و `/codex models` را تأیید می‌کند، و به‌طور پیش‌فرض بررسی‌های تصویر، - MCP متعلق به cron، زیرعامل، و Guardian را تمرین می‌کند. هنگام جداسازی شکست‌های دیگر - app-server مربوط به Codex، بررسی زیرعامل را با - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` غیرفعال کنید. برای بررسی متمرکز زیرعامل، بررسی‌های دیگر را غیرفعال کنید: + `/codex permissions` را تمرین می‌دهد، سپس تأیید می‌کند که یک پاسخ ساده و یک پیوست تصویر + از مسیر اتصال بومی Plugin به‌جای ACP عبور می‌کنند. +- اسموک هارنس app-server مربوط به Codex: `pnpm test:docker:live-codex-harness` + - نوبت‌های عامل Gateway را از طریق هارنس app-server متعلق به Plugin مربوط به Codex اجرا می‌کند، + `/codex status` و `/codex models` را تأیید می‌کند، و به‌طور پیش‌فرض پروب‌های تصویر، + cron MCP، عامل فرعی، و Guardian را تمرین می‌دهد. هنگام جداسازی شکست‌های دیگر app-server مربوط به Codex، + پروب عامل فرعی را با + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` غیرفعال کنید. برای یک بررسی متمرکز عامل فرعی، پروب‌های دیگر را غیرفعال کنید: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - این پس از بررسی زیرعامل خارج می‌شود مگر اینکه + این پس از پروب عامل فرعی خارج می‌شود مگر اینکه `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` تنظیم شده باشد. -- smoke فرمان نجات Crestodian: `pnpm test:live:crestodian-rescue-channel` - - بررسی اختیاری و دو‌لایه برای سطح فرمان نجات کانال پیام. - `/crestodian status` را تمرین می‌کند، یک تغییر مدل پایدار را صف می‌کند، +- اسموک دستور نجات Crestodian: `pnpm test:live:crestodian-rescue-channel` + - بررسی اختیاری و چندلایه برای سطح دستور نجات کانال پیام. + `/crestodian status` را تمرین می‌دهد، یک تغییر پایدار مدل را در صف می‌گذارد، به `/crestodian yes` پاسخ می‌دهد، و مسیر نوشتن audit/config را تأیید می‌کند. -- smoke برنامه‌ریز Crestodian در Docker: `pnpm test:docker:crestodian-planner` - - Crestodian را در یک کانتینر بدون پیکربندی با یک Claude CLI ساختگی روی `PATH` - اجرا می‌کند و تأیید می‌کند که fallback برنامه‌ریز fuzzy به یک نوشتن پیکربندی typed و auditشده - ترجمه می‌شود. -- smoke اجرای نخست Crestodian در Docker: `pnpm test:docker:crestodian-first-run` - - از یک پوشه وضعیت خالی OpenClaw شروع می‌کند، `openclaw` خام را به - Crestodian مسیریابی می‌کند، نوشتن‌های setup/model/agent/Plugin متعلق به Discord + SecretRef را اعمال می‌کند، +- اسموک Docker برنامه‌ریز Crestodian: `pnpm test:docker:crestodian-planner` + - Crestodian را در یک کانتینر بدون پیکربندی با یک Claude CLI ساختگی روی `PATH` اجرا می‌کند + و تأیید می‌کند که fallback برنامه‌ریز fuzzy به یک نوشتن پیکربندی typed و audit‌شده تبدیل می‌شود. +- اسموک Docker اولین اجرای Crestodian: `pnpm test:docker:crestodian-first-run` + - از یک دایرکتوری وضعیت خالی OpenClaw شروع می‌کند، `openclaw` خام را به + Crestodian مسیریابی می‌کند، نوشتن‌های راه‌اندازی/مدل/عامل/Plugin مربوط به Discord + SecretRef را اعمال می‌کند، پیکربندی را اعتبارسنجی می‌کند، و ورودی‌های audit را تأیید می‌کند. همان مسیر راه‌اندازی Ring 0 در QA Lab نیز با - `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` پوشش داده می‌شود. -- smoke هزینه Moonshot/Kimi: با تنظیم `MOONSHOT_API_KEY`، فرمان - `openclaw models list --provider moonshot --json` را اجرا کنید، سپس یک + `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` پوشش داده شده است. +- اسموک هزینه Moonshot/Kimi: با تنظیم بودن `MOONSHOT_API_KEY`، اجرا کنید + `openclaw models list --provider moonshot --json`، سپس یک `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` ایزوله را در برابر `moonshot/kimi-k2.6` اجرا کنید. تأیید کنید که JSON، Moonshot/K2.6 را گزارش می‌کند و - رونوشت assistant مقدار نرمال‌شده `usage.cost` را ذخیره می‌کند. + رونوشت دستیار، `usage.cost` نرمال‌شده را ذخیره می‌کند. -وقتی فقط به یک مورد شکست‌خورده نیاز دارید، محدود کردن آزمون‌های زنده از طریق متغیرهای محیطی allowlist که در ادامه توصیف شده‌اند را ترجیح دهید. +وقتی فقط به یک مورد شکست‌خورده نیاز دارید، محدود کردن آزمون‌های زنده از طریق متغیرهای محیطی allowlist که پایین‌تر توضیح داده شده‌اند را ترجیح دهید. -## اجراکننده‌های ویژه QA +## اجراکننده‌های مخصوص QA -وقتی به واقع‌گرایی QA-lab نیاز دارید، این فرمان‌ها کنار مجموعه‌های آزمون اصلی قرار می‌گیرند: +وقتی به واقع‌گرایی QA-lab نیاز دارید، این دستورها کنار مجموعه‌های آزمون اصلی قرار می‌گیرند: -CI، QA Lab را در گردش‌کارهای اختصاصی اجرا می‌کند. برابری عاملی زیر -`QA-Lab - All Lanes` و اعتبارسنجی انتشار قرار دارد، نه یک گردش‌کار مستقل PR. +CI، QA Lab را در گردش‌کارهای اختصاصی اجرا می‌کند. برابری عامل‌محور زیر +`QA-Lab - All Lanes` و اعتبارسنجی انتشار قرار دارد، نه در یک گردش‌کار مستقل PR. اعتبارسنجی گسترده باید از `Full Release Validation` با -`rerun_group=qa-parity` یا گروه QA مربوط به release-checks استفاده کند. `QA-Lab - All Lanes` -هر شب روی `main` و از dispatch دستی با مسیر mock parity، مسیر زنده -Matrix، مسیر زنده Telegram مدیریت‌شده با Convex، و مسیر زنده Discord -مدیریت‌شده با Convex به‌عنوان کارهای موازی اجرا می‌شود. QA زمان‌بندی‌شده و بررسی‌های انتشار، Matrix -`--profile fast` را صراحتاً پاس می‌دهند، در حالی که مقدار پیش‌فرض Matrix CLI و ورودی گردش‌کار دستی -همچنان `all` می‌ماند؛ dispatch دستی می‌تواند `all` را به کارهای `transport`, -`media`, `e2ee-smoke`, `e2ee-deep`, و `e2ee-cli` shard کند. `OpenClaw Release -Checks` پیش از تأیید انتشار، parity به‌علاوه مسیرهای سریع Matrix و Telegram را اجرا می‌کند +`rerun_group=qa-parity` یا گروه QA مربوط به release-checks استفاده کند. بررسی‌های انتشار پایدار/پیش‌فرض، +soak کامل زنده/Docker را پشت `run_release_soak=true` نگه می‌دارند؛ پروفایل +`full`، soak را اجباری می‌کند. `QA-Lab - All Lanes` +هر شب روی `main` و از dispatch دستی با مسیر برابری ساختگی، مسیر زنده Matrix، +مسیر زنده Telegram مدیریت‌شده با Convex، و مسیر زنده Discord مدیریت‌شده با Convex +به‌صورت jobهای موازی اجرا می‌شود. QA زمان‌بندی‌شده و بررسی‌های انتشار، Matrix +`--profile fast` را صریحا پاس می‌دهند، در حالی که مقدار پیش‌فرض ورودی CLI ماتریس و گردش‌کار دستی +همچنان `all` است؛ dispatch دستی می‌تواند `all` را به jobهای `transport`، +`media`، `e2ee-smoke`، `e2ee-deep`، و `e2ee-cli` shard کند. `OpenClaw Release +Checks` پیش از تأیید انتشار، برابری به‌علاوه مسیرهای سریع Matrix و Telegram را اجرا می‌کند، و برای بررسی‌های انتقال انتشار از `mock-openai/gpt-5.5` استفاده می‌کند تا قطعی بمانند و از راه‌اندازی عادی Plugin ارائه‌دهنده پرهیز کنند. این Gatewayهای انتقال زنده -جست‌وجوی حافظه را غیرفعال می‌کنند؛ رفتار حافظه همچنان توسط مجموعه‌های QA parity +جست‌وجوی حافظه را غیرفعال می‌کنند؛ رفتار حافظه همچنان توسط مجموعه‌های برابری QA پوشش داده می‌شود. shardهای رسانه زنده انتشار کامل از -`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` استفاده می‌کنند، که از قبل +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` استفاده می‌کنند که از قبل `ffmpeg` و `ffprobe` را دارد. shardهای مدل/بک‌اند زنده Docker از تصویر مشترک `ghcr.io/openclaw/openclaw-live-test:` استفاده می‌کنند که یک‌بار برای commit انتخاب‌شده ساخته می‌شود، -سپس آن را با `OPENCLAW_SKIP_DOCKER_BUILD=1` pull می‌کنند، به‌جای اینکه داخل هر shard دوباره build شود. +سپس آن را با `OPENCLAW_SKIP_DOCKER_BUILD=1` pull می‌کنند، به‌جای اینکه داخل هر shard دوباره بسازند. - `pnpm openclaw qa suite` - - سناریوهای QA پشتوانه‌دار با مخزن را مستقیماً روی میزبان اجرا می‌کند. - - به‌طور پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی با workerهای - Gateway ایزوله اجرا می‌کند. `qa-channel` به‌طور پیش‌فرض هم‌زمانی ۴ دارد (محدود به - تعداد سناریوهای انتخاب‌شده). برای تنظیم تعداد workerها از `--concurrency ` استفاده کنید، - یا برای مسیر سریال قدیمی‌تر از `--concurrency 1` استفاده کنید. - - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی - artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. - - از حالت‌های provider به نام‌های `live-frontier`، `mock-openai` و `aimock` پشتیبانی می‌کند. - `aimock` یک سرور provider محلی با پشتوانه AIMock برای پوشش آزمایشی - fixture و protocol-mock راه‌اندازی می‌کند، بدون اینکه مسیر آگاه از سناریوی - `mock-openai` را جایگزین کند. + - سناریوهای QA متکی به مخزن را مستقیما روی میزبان اجرا می‌کند. + - چند سناریوی انتخاب‌شده را به‌طور پیش‌فرض، با کارگرهای Gateway ایزوله، به‌صورت موازی اجرا می‌کند. `qa-channel` به‌طور پیش‌فرض هم‌زمانی 4 دارد (محدود به تعداد سناریوهای انتخاب‌شده). از `--concurrency ` برای تنظیم تعداد کارگرها، یا از `--concurrency 1` برای مسیر سریال قدیمی‌تر استفاده کنید. + - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی آرتیفکت‌ها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. + - از حالت‌های تامین‌کننده `live-frontier`، `mock-openai`، و `aimock` پشتیبانی می‌کند. `aimock` یک سرور تامین‌کننده محلی مبتنی بر AIMock را برای پوشش آزمایشی fixture و mock پروتکل شروع می‌کند، بدون اینکه مسیر سناریوآگاه `mock-openai` را جایگزین کند. +- `pnpm test:plugins:kitchen-sink-live` + - آزمون چالشی زنده Plugin OpenAI Kitchen Sink را از طریق QA Lab اجرا می‌کند. بسته خارجی Kitchen Sink را نصب می‌کند، موجودی سطح plugin SDK را بررسی می‌کند، `/healthz` و `/readyz` را می‌آزماید، شواهد CPU/RSS Gateway را ثبت می‌کند، یک نوبت زنده OpenAI را اجرا می‌کند، و تشخیص‌های خصمانه را بررسی می‌کند. به احراز هویت زنده OpenAI مانند `OPENAI_API_KEY` نیاز دارد. در نشست‌های Testbox آماده‌شده، وقتی helper با نام `openclaw-testbox-env` حاضر باشد، به‌طور خودکار پروفایل live-auth مربوط به Testbox را بارگذاری می‌کند. - `pnpm test:gateway:cpu-scenarios` - - بنچ راه‌اندازی Gateway را همراه با یک بسته کوچک سناریوی mock QA Lab - (`channel-chat-baseline`، `memory-failure-fallback`، - `gateway-restart-inflight-run`) اجرا می‌کند و یک خلاصه ترکیبی از مشاهده CPU - زیر `.artifacts/gateway-cpu-scenarios/` می‌نویسد. - - به‌طور پیش‌فرض فقط مشاهده‌های پایدار CPU داغ را علامت‌گذاری می‌کند (`--cpu-core-warn` - به‌همراه `--hot-wall-warn-ms`)، بنابراین جهش‌های کوتاه زمان راه‌اندازی به‌عنوان metrics - ثبت می‌شوند بدون اینکه شبیه رگرسیون چنددقیقه‌ای قفل‌شدن Gateway به نظر برسند. - - از artifactهای ساخته‌شده `dist` استفاده می‌کند؛ وقتی checkout از قبل خروجی runtime تازه ندارد، - ابتدا یک build اجرا کنید. + - بنچ شروع Gateway را همراه با یک بسته کوچک سناریوی QA Lab mock (`channel-chat-baseline`، `memory-failure-fallback`، `gateway-restart-inflight-run`) اجرا می‌کند و یک خلاصه ترکیبی مشاهده CPU را زیر `.artifacts/gateway-cpu-scenarios/` می‌نویسد. + - به‌طور پیش‌فرض فقط مشاهده‌های CPU داغ پایدار را علامت‌گذاری می‌کند (`--cpu-core-warn` همراه با `--hot-wall-warn-ms`)، بنابراین جهش‌های کوتاه شروع به‌عنوان متریک ثبت می‌شوند بدون اینکه شبیه رگرسیون درگیری چنددقیقه‌ای Gateway به نظر برسند. + - از آرتیفکت‌های ساخته‌شده `dist` استفاده می‌کند؛ وقتی checkout از قبل خروجی runtime تازه ندارد، ابتدا build را اجرا کنید. - `pnpm openclaw qa suite --runner multipass` - - همان مجموعه QA را داخل یک VM لینوکسی disposable در Multipass اجرا می‌کند. - - همان رفتار انتخاب سناریو مثل `qa suite` روی میزبان را نگه می‌دارد. - - همان flagهای انتخاب provider/model مثل `qa suite` را دوباره استفاده می‌کند. - - اجراهای live ورودی‌های پشتیبانی‌شده auth برای QA را که برای guest عملی هستند forward می‌کنند: - کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و `CODEX_HOME` - وقتی حاضر باشد. - - مسیرهای خروجی باید زیر ریشه مخزن بمانند تا guest بتواند از طریق - workspace mount‌شده دوباره بنویسد. - - گزارش و خلاصه معمول QA به‌علاوه logهای Multipass را زیر - `.artifacts/qa-e2e/...` می‌نویسد. + - همان مجموعه QA را داخل یک VM یک‌بارمصرف Linux Multipass اجرا می‌کند. + - همان رفتار انتخاب سناریو در `qa suite` روی میزبان را حفظ می‌کند. + - همان فلگ‌های انتخاب تامین‌کننده/مدل در `qa suite` را دوباره استفاده می‌کند. + - اجراهای زنده، ورودی‌های احراز هویت QA پشتیبانی‌شده‌ای را که برای مهمان عملی هستند forward می‌کنند: کلیدهای تامین‌کننده مبتنی بر env، مسیر پیکربندی تامین‌کننده زنده QA، و `CODEX_HOME` وقتی حاضر باشد. + - دایرکتوری‌های خروجی باید زیر ریشه مخزن بمانند تا مهمان بتواند از طریق workspace mount‌شده دوباره بنویسد. + - گزارش + خلاصه عادی QA و همچنین لاگ‌های Multipass را زیر `.artifacts/qa-e2e/...` می‌نویسد. - `pnpm qa:lab:up` - - سایت QA با پشتوانه Docker را برای کار QA به سبک operator راه‌اندازی می‌کند. + - سایت QA مبتنی بر Docker را برای کار QA به سبک اپراتور شروع می‌کند. - `pnpm test:docker:npm-onboard-channel-agent` - - از checkout فعلی یک tarball مربوط به npm می‌سازد، آن را به‌صورت global در - Docker نصب می‌کند، onboarding غیرتعاملی کلید OpenAI API را اجرا می‌کند، به‌طور پیش‌فرض Telegram - را پیکربندی می‌کند، تأیید می‌کند runtime مربوط به Plugin بسته‌بندی‌شده بدون تعمیر وابستگی - در زمان راه‌اندازی load می‌شود، doctor را اجرا می‌کند، و یک نوبت agent محلی را در برابر یک - endpoint mock‌شده OpenAI اجرا می‌کند. - - برای اجرای همان مسیر نصب بسته‌بندی‌شده با Discord از `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` استفاده کنید. + - از checkout فعلی یک tarball npm می‌سازد، آن را در Docker به‌صورت سراسری نصب می‌کند، onboarding غیرتعاملی کلید API OpenAI را اجرا می‌کند، به‌طور پیش‌فرض Telegram را پیکربندی می‌کند، بررسی می‌کند runtime بسته‌بندی‌شده Plugin بدون تعمیر وابستگی در شروع بارگذاری شود، doctor را اجرا می‌کند، و یک نوبت agent محلی را در برابر یک endpoint شبیه‌سازی‌شده OpenAI اجرا می‌کند. + - از `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` برای اجرای همان مسیر نصب بسته‌بندی‌شده با Discord استفاده کنید. - `pnpm test:docker:session-runtime-context` - - یک smoke قطعی Docker از برنامه ساخته‌شده برای transcriptهای context runtime توکار - اجرا می‌کند. تأیید می‌کند context runtime پنهان OpenClaw به‌عنوان یک پیام سفارشی - غیرنمایشی persisted می‌شود، به‌جای اینکه به نوبت قابل‌مشاهده کاربر نشت کند، - سپس یک session JSONL خراب تحت‌تأثیر را seed می‌کند و تأیید می‌کند - `openclaw doctor --fix` آن را با یک backup به branch فعال بازنویسی می‌کند. + - یک smoke قطعی Docker برای transcriptهای embedded runtime context در برنامه ساخته‌شده اجرا می‌کند. بررسی می‌کند hidden OpenClaw runtime context به‌عنوان یک پیام سفارشی غیرنمایشی پایدار شده باشد، نه اینکه به نوبت کاربر قابل مشاهده نشت کند؛ سپس یک JSONL نشست خراب متاثر را seed می‌کند و بررسی می‌کند `openclaw doctor --fix` آن را همراه با backup به شاخه فعال بازنویسی کند. - `pnpm test:docker:npm-telegram-live` - - یک کاندید package از OpenClaw را در Docker نصب می‌کند، onboarding package نصب‌شده را - اجرا می‌کند، Telegram را از طریق CLI نصب‌شده پیکربندی می‌کند، سپس مسیر QA زنده Telegram - را با همان package نصب‌شده به‌عنوان Gateway تحت آزمون دوباره استفاده می‌کند. - - مقدار پیش‌فرض `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` است؛ برای آزمون یک tarball - محلی resolve‌شده به‌جای نصب از registry، `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` - یا `OPENCLAW_CURRENT_PACKAGE_TGZ` را تنظیم کنید. - - از همان credentials محیطی Telegram یا منبع credential Convex مثل - `pnpm openclaw qa telegram` استفاده می‌کند. برای automation در CI/release، - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` را به‌همراه - `OPENCLAW_QA_CONVEX_SITE_URL` و secret نقش تنظیم کنید. اگر - `OPENCLAW_QA_CONVEX_SITE_URL` و یک secret نقش Convex در CI حاضر باشند، - wrapper Docker به‌طور خودکار Convex را انتخاب می‌کند. - - wrapper پیش از کار build/install در Docker، env مربوط به credentialهای Telegram یا Convex - را روی میزبان validate می‌کند. فقط وقتی عمداً در حال debug تنظیمات پیش از credential هستید، - `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` را تنظیم کنید. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` فقط برای این مسیر، مقدار مشترک - `OPENCLAW_QA_CREDENTIAL_ROLE` را override می‌کند. - - GitHub Actions این مسیر را به‌عنوان workflow دستی maintainer با نام - `NPM Telegram Beta E2E` ارائه می‌کند. روی merge اجرا نمی‌شود. این workflow از - محیط `qa-live-shared` و leaseهای credential مربوط به Convex CI استفاده می‌کند. -- GitHub Actions همچنین `Package Acceptance` را برای اثبات محصول side-run - در برابر یک package کاندید ارائه می‌کند. یک ref قابل‌اعتماد، spec منتشرشده npm، - URL tarball از نوع HTTPS به‌همراه SHA-256، یا artifact tarball از اجرای دیگری را می‌پذیرد، - `openclaw-current.tgz` نرمال‌شده را به‌عنوان `package-under-test` upload می‌کند، سپس - scheduler موجود Docker E2E را با profileهای مسیر smoke، package، product، full، یا custom - اجرا می‌کند. برای اجرای workflow QA مربوط به Telegram در برابر همان artifact - `package-under-test`، `telegram_mode=mock-openai` یا `live-frontier` را تنظیم کنید. + - یک نامزد بسته OpenClaw را در Docker نصب می‌کند، onboarding بسته نصب‌شده را اجرا می‌کند، Telegram را از طریق CLI نصب‌شده پیکربندی می‌کند، سپس مسیر QA زنده Telegram را با همان بسته نصب‌شده به‌عنوان SUT Gateway دوباره استفاده می‌کند. + - به‌طور پیش‌فرض `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` است؛ برای آزمودن یک tarball محلی resolve‌شده به‌جای نصب از registry، `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` یا `OPENCLAW_CURRENT_PACKAGE_TGZ` را تنظیم کنید. + - از همان اعتبارنامه‌های env مربوط به Telegram یا منبع اعتبارنامه Convex مانند `pnpm openclaw qa telegram` استفاده می‌کند. برای خودکارسازی CI/release، `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` را همراه با `OPENCLAW_QA_CONVEX_SITE_URL` و secret نقش تنظیم کنید. اگر `OPENCLAW_QA_CONVEX_SITE_URL` و یک secret نقش Convex در CI حاضر باشند، wrapper Docker به‌طور خودکار Convex را انتخاب می‌کند. + - wrapper پیش از کار build/install در Docker، env اعتبارنامه Telegram یا Convex را روی میزبان اعتبارسنجی می‌کند. فقط وقتی عمدا در حال اشکال‌زدایی راه‌اندازی پیش از اعتبارنامه هستید، `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` را تنظیم کنید. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` فقط برای این مسیر، `OPENCLAW_QA_CREDENTIAL_ROLE` مشترک را override می‌کند. + - GitHub Actions این مسیر را به‌عنوان workflow دستی maintainer با نام `NPM Telegram Beta E2E` ارائه می‌کند. روی merge اجرا نمی‌شود. workflow از محیط `qa-live-shared` و اجاره‌های اعتبارنامه CI در Convex استفاده می‌کند. +- GitHub Actions همچنین `Package Acceptance` را برای اثبات محصول به‌صورت اجرای جانبی در برابر یک بسته نامزد ارائه می‌کند. یک ref مورد اعتماد، spec منتشرشده npm، URL tarball با HTTPS همراه با SHA-256، یا آرتیفکت tarball از اجرای دیگر را می‌پذیرد، `openclaw-current.tgz` نرمال‌شده را به‌عنوان `package-under-test` upload می‌کند، سپس زمان‌بند Docker E2E موجود را با پروفایل‌های مسیر smoke، package، product، full، یا custom اجرا می‌کند. برای اجرای workflow QA مربوط به Telegram در برابر همان آرتیفکت `package-under-test`، `telegram_mode=mock-openai` یا `live-frontier` را تنظیم کنید. - اثبات محصول آخرین beta: ```bash @@ -234,7 +191,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- اثبات artifact یک artifact مربوط به tarball را از اجرای Actions دیگری download می‌کند: +- اثبات آرتیفکت یک آرتیفکت tarball را از اجرای دیگری در Actions دانلود می‌کند: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -245,85 +202,60 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - build فعلی OpenClaw را در Docker pack و install می‌کند، Gateway را - با OpenAI پیکربندی‌شده راه‌اندازی می‌کند، سپس channel/pluginsهای bundled را از طریق ویرایش‌های config - فعال می‌کند. - - تأیید می‌کند discovery مربوط به setup، Pluginهای downloadable پیکربندی‌نشده را absent می‌گذارد، - نخستین repair پیکربندی‌شده doctor هر Plugin دانلودشدنی missing را صریحاً install می‌کند، - و restart دوم repair پنهان وابستگی را اجرا نمی‌کند. - - همچنین یک baseline قدیمی‌تر شناخته‌شده npm را install می‌کند، پیش از اجرای - `openclaw update --tag `، Telegram را فعال می‌کند، و تأیید می‌کند doctor پس از update - کاندید، بقایای legacy وابستگی Plugin را بدون repair مربوط به postinstall در سمت harness پاک می‌کند. + - build فعلی OpenClaw را در Docker بسته‌بندی و نصب می‌کند، Gateway را با OpenAI پیکربندی‌شده شروع می‌کند، سپس channel/Pluginهای bundle‌شده را از طریق ویرایش‌های config فعال می‌کند. + - بررسی می‌کند discovery راه‌اندازی، Pluginهای downloadable پیکربندی‌نشده را غایب بگذارد، اولین تعمیر doctor پیکربندی‌شده هر Plugin downloadable گم‌شده را صریحا نصب کند، و restart دوم تعمیر وابستگی پنهان را اجرا نکند. + - همچنین یک baseline قدیمی‌تر شناخته‌شده npm را نصب می‌کند، Telegram را پیش از اجرای `openclaw update --tag ` فعال می‌کند، و بررسی می‌کند doctor پس از update نامزد، باقی‌مانده‌های وابستگی Plugin قدیمی را بدون تعمیر postinstall سمت harness پاک کند. - `pnpm test:parallels:npm-update` - - smoke بومی update برای نصب package‌شده را روی guestهای Parallels اجرا می‌کند. هر - platform انتخاب‌شده ابتدا package baseline درخواست‌شده را install می‌کند، سپس - دستور نصب‌شده `openclaw update` را در همان guest اجرا می‌کند و version نصب‌شده، - status update، آمادگی Gateway، و یک نوبت agent محلی را verify می‌کند. - - هنگام iteration روی یک guest، از `--platform macos`، `--platform windows`، یا `--platform linux` استفاده کنید. - برای مسیر artifact خلاصه و وضعیت هر مسیر، از `--json` استفاده کنید. - - مسیر OpenAI به‌طور پیش‌فرض از `openai/gpt-5.5` برای اثبات نوبت agent live استفاده می‌کند. - وقتی عمداً یک model دیگر OpenAI را validate می‌کنید، `--model ` را pass کنید - یا `OPENCLAW_PARALLELS_OPENAI_MODEL` را تنظیم کنید. - - اجراهای محلی طولانی را در یک timeout میزبان wrap کنید تا stallهای transport در Parallels نتوانند - باقی پنجره testing را مصرف کنند: + - smoke به‌روزرسانی نصب بسته بومی را در مهمان‌های Parallels اجرا می‌کند. هر پلتفرم انتخاب‌شده ابتدا بسته baseline درخواست‌شده را نصب می‌کند، سپس فرمان نصب‌شده `openclaw update` را در همان مهمان اجرا می‌کند و نسخه نصب‌شده، وضعیت update، آمادگی Gateway، و یک نوبت agent محلی را بررسی می‌کند. + - هنگام تکرار روی یک مهمان، از `--platform macos`، `--platform windows`، یا `--platform linux` استفاده کنید. برای مسیر آرتیفکت خلاصه و وضعیت هر مسیر، از `--json` استفاده کنید. + - مسیر OpenAI به‌طور پیش‌فرض برای اثبات نوبت agent زنده از `openai/gpt-5.5` استفاده می‌کند. وقتی عمدا مدل OpenAI دیگری را اعتبارسنجی می‌کنید، `--model ` را پاس دهید یا `OPENCLAW_PARALLELS_OPENAI_MODEL` را تنظیم کنید. + - اجراهای محلی طولانی را در timeout میزبان بپیچید تا توقف‌های transport در Parallels نتوانند باقی پنجره آزمون را مصرف کنند: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - این script logهای تو در توی هر مسیر را زیر `/tmp/openclaw-parallels-npm-update.*` می‌نویسد. - پیش از اینکه فرض کنید wrapper بیرونی hang شده، `windows-update.log`، `macos-update.log`، یا `linux-update.log` - را inspect کنید. - - update ویندوز می‌تواند در guest سرد ۱۰ تا ۱۵ دقیقه در کار doctor پس از update و package - update زمان بگذارد؛ تا وقتی log debug تو در توی npm در حال پیشروی است، این وضعیت هنوز سالم است. - - این wrapper aggregate را به‌صورت موازی با مسیرهای smoke تکی Parallels - macOS، Windows، یا Linux اجرا نکنید. آن‌ها state مربوط به VM را share می‌کنند و می‌توانند در - restore snapshot، serving package، یا state مربوط به Gateway در guest تداخل کنند. - - اثبات پس از update سطح معمول Plugin bundled را اجرا می‌کند، زیرا - facadeهای capability مانند گفتار، تولید تصویر، و فهم رسانه - از طریق APIهای runtime bundled load می‌شوند، حتی وقتی خود نوبت agent - فقط یک پاسخ متنی ساده را بررسی می‌کند. + - script لاگ‌های تودرتوی مسیر را زیر `/tmp/openclaw-parallels-npm-update.*` می‌نویسد. پیش از فرض گرفتن اینکه wrapper بیرونی گیر کرده است، `windows-update.log`، `macos-update.log`، یا `linux-update.log` را بررسی کنید. + - update ویندوز روی یک مهمان سرد می‌تواند 10 تا 15 دقیقه در doctor پس از update و کار update بسته زمان صرف کند؛ وقتی لاگ debug تودرتوی npm در حال پیشروی است، این هنوز سالم است. + - این wrapper تجمیعی را هم‌زمان با مسیرهای smoke جداگانه Parallels برای macOS، Windows، یا Linux اجرا نکنید. آن‌ها وضعیت VM را مشترک استفاده می‌کنند و ممکن است در restore کردن snapshot، ارائه بسته، یا وضعیت Gateway مهمان تداخل کنند. + - اثبات پس از update سطح عادی Plugin bundle‌شده را اجرا می‌کند، چون facadeهای capability مانند speech، image generation، و media understanding از طریق APIهای runtime bundle‌شده بارگذاری می‌شوند، حتی وقتی خود نوبت agent فقط یک پاسخ متنی ساده را بررسی می‌کند. - `pnpm openclaw qa aimock` - - فقط سرور provider محلی AIMock را برای smoke testing مستقیم protocol - راه‌اندازی می‌کند. + - فقط سرور تامین‌کننده محلی AIMock را برای smoke testing مستقیم پروتکل شروع می‌کند. - `pnpm openclaw qa matrix` - - مسیر QA زنده Matrix را در برابر یک homeserver یک‌بارمصرف Tuwunel با پشتوانه Docker اجرا می‌کند. فقط source-checkout — نصب‌های package‌شده `qa-lab` را ship نمی‌کنند. - - CLI کامل، catalog مربوط به profile/scenario، env varها، و layout مربوط به artifact: [Matrix QA](/fa/concepts/qa-matrix). + - مسیر QA زنده Matrix را در برابر یک homeserver یک‌بارمصرف Tuwunel مبتنی بر Docker اجرا می‌کند. فقط source-checkout — نصب‌های بسته‌بندی‌شده `qa-lab` را ship نمی‌کنند. + - CLI کامل، کاتالوگ profile/scenario، env vars، و layout آرتیفکت: [QA Matrix](/fa/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - مسیر QA زنده Telegram را در برابر یک گروه private واقعی با استفاده از tokenهای driver و SUT bot از env اجرا می‌کند. + - مسیر QA زنده Telegram را با استفاده از driver و tokenهای bot مربوط به SUT از env، در برابر یک گروه خصوصی واقعی اجرا می‌کند. - به `OPENCLAW_QA_TELEGRAM_GROUP_ID`، `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`، و `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` نیاز دارد. group id باید chat id عددی Telegram باشد. - - از `--credential-source convex` برای credentialهای pooled مشترک پشتیبانی می‌کند. به‌طور پیش‌فرض از حالت env استفاده کنید، یا برای opt in به leaseهای pooled، `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید. - - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی - artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. - - به دو bot متمایز در همان گروه private نیاز دارد، در حالی که bot مربوط به SUT یک username مربوط به Telegram را expose می‌کند. - - برای مشاهده پایدار bot-to-bot، Bot-to-Bot Communication Mode را در `@BotFather` برای هر دو bot فعال کنید و مطمئن شوید driver bot می‌تواند traffic botهای گروه را observe کند. - - یک گزارش QA مربوط به Telegram، خلاصه، و artifact پیام‌های مشاهده‌شده را زیر `.artifacts/qa-e2e/...` می‌نویسد. سناریوهای reply شامل RTT از درخواست ارسال driver تا reply مشاهده‌شده SUT هستند. + - از `--credential-source convex` برای اعتبارنامه‌های pooled مشترک پشتیبانی می‌کند. به‌طور پیش‌فرض از حالت env استفاده کنید، یا برای ورود به اجاره‌های pooled، `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید. + - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی آرتیفکت‌ها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. + - به دو bot متمایز در همان گروه خصوصی نیاز دارد، و bot مربوط به SUT باید یک username در Telegram ارائه کند. + - برای مشاهده پایدار bot-to-bot، Bot-to-Bot Communication Mode را در `@BotFather` برای هر دو bot فعال کنید و مطمئن شوید driver bot می‌تواند ترافیک bot گروه را مشاهده کند. + - یک گزارش QA مربوط به Telegram، خلاصه، و آرتیفکت observed-messages را زیر `.artifacts/qa-e2e/...` می‌نویسد. سناریوهای پاسخ‌دهنده شامل RTT از درخواست ارسال driver تا پاسخ مشاهده‌شده SUT هستند. -مسیرهای transport زنده یک قرارداد استاندارد مشترک دارند تا transportهای جدید drift نکنند؛ matrix پوشش هر مسیر در [نمای کلی QA → پوشش transport زنده](/fa/concepts/qa-e2e-automation#live-transport-coverage) قرار دارد. `qa-channel` مجموعه synthetic گسترده است و بخشی از آن matrix نیست. +مسیرهای transport زنده یک قرارداد استاندارد مشترک دارند تا transportهای جدید دچار drift نشوند؛ ماتریس پوشش هر مسیر در [مرور کلی QA → پوشش transport زنده](/fa/concepts/qa-e2e-automation#live-transport-coverage) قرار دارد. `qa-channel` مجموعه synthetic گسترده است و بخشی از آن ماتریس نیست. -### credentialهای مشترک Telegram از طریق Convex (v1) +### اعتبارنامه‌های مشترک Telegram از طریق Convex (v1) -وقتی `--credential-source convex` (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) برای -`openclaw qa telegram` فعال باشد، QA lab یک lease انحصاری از pool با پشتوانه Convex می‌گیرد، هنگام اجرای مسیر -برای آن lease Heartbeat می‌فرستد، و هنگام shutdown آن lease را release می‌کند. +وقتی `--credential-source convex` (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) برای `openclaw qa telegram` فعال باشد، QA lab یک اجاره انحصاری از یک pool مبتنی بر Convex دریافت می‌کند، تا زمانی که مسیر در حال اجراست برای آن اجاره Heartbeat می‌فرستد، و هنگام shutdown اجاره را آزاد می‌کند. -scaffold مرجع پروژه Convex: +اسکلت مرجع پروژه Convex: - `qa/convex-credential-broker/` -env varهای لازم: +env vars الزامی: - `OPENCLAW_QA_CONVEX_SITE_URL` (برای مثال `https://your-deployment.convex.site`) - یک secret برای نقش انتخاب‌شده: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` برای `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` برای `ci` -- انتخاب نقش credential: +- انتخاب نقش اعتبارنامه: - CLI: `--credential-role maintainer|ci` - - پیش‌فرض env: `OPENCLAW_QA_CREDENTIAL_ROLE` (در CI به‌طور پیش‌فرض `ci`، در غیر این صورت `maintainer`) + - پیش‌فرض Env: `OPENCLAW_QA_CREDENTIAL_ROLE` (در CI به‌طور پیش‌فرض `ci`، و در غیر این صورت `maintainer`) -env varهای اختیاری: +env vars اختیاری: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (پیش‌فرض `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (پیش‌فرض `30000`) @@ -331,14 +263,14 @@ env varهای اختیاری: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (پیش‌فرض `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (پیش‌فرض `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (trace id اختیاری) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` اجازه URLهای Convex از نوع loopback `http://` را فقط برای توسعه محلی می‌دهد. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` به URLهای Convex با `http://` روی loopback برای توسعه فقط محلی اجازه می‌دهد. -`OPENCLAW_QA_CONVEX_SITE_URL` باید در عملیات عادی از `https://` استفاده کند. +`OPENCLAW_QA_CONVEX_SITE_URL` در عملیات عادی باید از `https://` استفاده کند. -دستورهای admin مربوط به maintainer (pool add/remove/list) مشخصاً به +دستورهای مدیریتی نگه‌دارنده‌ها (افزودن/حذف/فهرست‌کردن pool) به‌طور مشخص به `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` نیاز دارند. -helperهای CLI برای maintainerها: +کمک‌کننده‌های CLI برای نگه‌دارنده‌ها: ```bash pnpm openclaw qa credentials doctor @@ -347,9 +279,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -از `doctor` پیش از اجراهای زنده استفاده کنید تا URL سایت Convex، اسرار broker، -پیشوند endpoint، مهلت زمانی HTTP، و دسترسی‌پذیری admin/list را بدون چاپ -مقادیر محرمانه بررسی کنید. برای خروجی قابل خواندن توسط ماشین در اسکریپت‌ها و ابزارهای CI +پیش از اجراهای زنده از `doctor` استفاده کنید تا URL سایت Convex، اسرار broker، +پیشوند endpoint، مهلت HTTP، و دسترسی‌پذیری admin/list را بدون چاپ +مقادیر secret بررسی کند. برای خروجی قابل خواندن توسط ماشین در اسکریپت‌ها و ابزارهای CI از `--json` استفاده کنید. قرارداد endpoint پیش‌فرض (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -357,469 +289,471 @@ pnpm openclaw qa credentials remove --credential-id - `POST /acquire` - درخواست: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - موفقیت: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - تمام‌شده/قابل تلاش دوباره: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - تمام‌شده/قابل‌تلاش‌مجدد: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - درخواست: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - موفقیت: `{ status: "ok" }` (یا `2xx` خالی) - `POST /release` - درخواست: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - موفقیت: `{ status: "ok" }` (یا `2xx` خالی) -- `POST /admin/add` (فقط راز نگه‌دارنده) +- `POST /admin/add` (فقط secret نگه‌دارنده) - درخواست: `{ kind, actorId, payload, note?, status? }` - موفقیت: `{ status: "ok", credential }` -- `POST /admin/remove` (فقط راز نگه‌دارنده) +- `POST /admin/remove` (فقط secret نگه‌دارنده) - درخواست: `{ credentialId, actorId }` - موفقیت: `{ status: "ok", changed, credential }` - محافظ lease فعال: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (فقط راز نگه‌دارنده) +- `POST /admin/list` (فقط secret نگه‌دارنده) - درخواست: `{ kind?, status?, includePayload?, limit? }` - موفقیت: `{ status: "ok", credentials, count }` شکل payload برای نوع Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` باید یک رشته عددی شناسه چت Telegram باشد. +- `groupId` باید یک رشتهٔ عددی شناسهٔ چت Telegram باشد. - `admin/add` این شکل را برای `kind: "telegram"` اعتبارسنجی می‌کند و payloadهای بدشکل را رد می‌کند. ### افزودن یک کانال به QA -معماری و نام‌های helper سناریو برای adapterهای کانال جدید در [نمای کلی QA → افزودن یک کانال](/fa/concepts/qa-e2e-automation#adding-a-channel) قرار دارند. حداقل معیار: runner انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید، `qaRunners` را در manifest Plugin اعلام کنید، آن را به‌صورت `openclaw qa ` mount کنید، و سناریوها را زیر `qa/scenarios/` بنویسید. +معماری و نام‌های کمک‌کنندهٔ سناریو برای adapterهای کانال جدید در [نمای کلی QA ← افزودن یک کانال](/fa/concepts/qa-e2e-automation#adding-a-channel) قرار دارند. حداقل معیار: transport runner را روی درز میزبان مشترک `qa-lab` پیاده‌سازی کنید، `qaRunners` را در manifest Plugin اعلام کنید، آن را به‌صورت `openclaw qa ` mount کنید، و سناریوها را زیر `qa/scenarios/` بنویسید. -## مجموعه‌های آزمون (چه چیزی کجا اجرا می‌شود) +## مجموعه‌های آزمایش (چه چیزی کجا اجرا می‌شود) -این مجموعه‌ها را به‌عنوان «افزایش واقع‌گرایی» (و افزایش ناپایداری/هزینه) در نظر بگیرید: +به مجموعه‌ها به‌عنوان «واقع‌گرایی فزاینده» فکر کنید (و همچنین ناپایداری/هزینهٔ فزاینده): ### واحد / یکپارچه‌سازی (پیش‌فرض) -- فرمان: `pnpm test` -- پیکربندی: اجراهای بدون هدف از مجموعه shardهای `vitest.full-*.config.ts` استفاده می‌کنند و ممکن است shardهای چندپروژه‌ای را برای زمان‌بندی موازی به پیکربندی‌های per-project گسترش دهند -- فایل‌ها: inventoryهای core/unit زیر `src/**/*.test.ts`، `packages/**/*.test.ts`، و `test/**/*.test.ts`؛ آزمون‌های واحد UI در shard اختصاصی `unit-ui` اجرا می‌شوند +- دستور: `pnpm test` +- پیکربندی: اجراهای بدون هدف از مجموعهٔ shardهای `vitest.full-*.config.ts` استفاده می‌کنند و ممکن است shardهای چندپروژه‌ای را برای زمان‌بندی موازی به پیکربندی‌های جداگانهٔ هر پروژه گسترش دهند +- فایل‌ها: inventoryهای core/unit زیر `src/**/*.test.ts`، `packages/**/*.test.ts`، و `test/**/*.test.ts`؛ آزمایش‌های واحد UI در shard اختصاصی `unit-ui` اجرا می‌شوند - دامنه: - - آزمون‌های واحد خالص - - آزمون‌های یکپارچه‌سازی درون‌فرایندی (احراز هویت Gateway، مسیریابی، tooling، parsing، config) - - رگرسیون‌های قطعی برای باگ‌های شناخته‌شده + - آزمایش‌های واحد خالص + - آزمایش‌های یکپارچه‌سازی درون‌فرایندی (احراز هویت Gateway، مسیریابی، ابزارها، parsing، config) + - regressionهای قطعی برای bugهای شناخته‌شده - انتظارات: - در CI اجرا می‌شود - به کلیدهای واقعی نیاز ندارد - باید سریع و پایدار باشد - - آزمون‌های resolver و loader سطح عمومی باید رفتار fallback گسترده `api.js` و - `runtime-api.js` را با fixtureهای Plugin کوچک تولیدشده اثبات کنند، نه - APIهای منبع Plugin بسته‌بندی‌شده واقعی. بارگذاری API واقعی Plugin به - مجموعه‌های contract/integration متعلق به Plugin مربوط است. + - آزمایش‌های resolver و loader سطح عمومی باید رفتار fallback گستردهٔ `api.js` و + `runtime-api.js` را با fixtureهای کوچک تولیدشدهٔ Plugin ثابت کنند، نه با + APIهای منبع Pluginهای bundled واقعی. بارگذاری API واقعی Pluginها به + مجموعه‌های contract/integration تحت مالکیت Plugin تعلق دارد. - + - - `pnpm test` بدون هدف، به‌جای یک فرایند عظیم native root-project، دوازده پیکربندی shard کوچک‌تر (`core-unit-fast`، `core-unit-src`، `core-unit-security`، `core-unit-ui`، `core-unit-support`، `core-support-boundary`، `core-contracts`، `core-bundled`، `core-runtime`، `agentic`، `auto-reply`، `extensions`) را اجرا می‌کند. این کار peak RSS را روی ماشین‌های پربار کاهش می‌دهد و از گرسنه ماندن مجموعه‌های نامرتبط توسط کار auto-reply/extension جلوگیری می‌کند. - - `pnpm test --watch` همچنان از گراف پروژه native root در `vitest.config.ts` استفاده می‌کند، چون loop watch چند-shard عملی نیست. - - `pnpm test`، `pnpm test:watch`، و `pnpm test:perf:imports` هدف‌های صریح فایل/دایرکتوری را ابتدا از مسیر scoped laneها عبور می‌دهند، بنابراین `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` هزینه راه‌اندازی کامل root project را نمی‌پردازد. - - `pnpm test:changed` مسیرهای تغییرکرده git را به‌طور پیش‌فرض به laneهای scoped ارزان گسترش می‌دهد: ویرایش‌های مستقیم آزمون، فایل‌های هم‌جوار `*.test.ts`، نگاشت‌های صریح source، و وابسته‌های محلی import-graph. ویرایش‌های config/setup/package آزمون‌ها را به‌صورت گسترده اجرا نمی‌کنند مگر اینکه صریحاً از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. - - `pnpm check:changed` دروازه عادی بررسی هوشمند محلی برای کارهای محدود است. این دستور diff را به core، آزمون‌های core، extensions، آزمون‌های extension، apps، docs، metadata انتشار، ابزارهای live Docker، و tooling طبقه‌بندی می‌کند، سپس فرمان‌های typecheck، lint، و guard متناظر را اجرا می‌کند. آزمون‌های Vitest را اجرا نمی‌کند؛ برای اثبات آزمون، `pnpm test:changed` یا `pnpm test ` صریح را فراخوانی کنید. bumpهای نسخه فقط metadata انتشار، بررسی‌های هدفمند version/config/root-dependency را با guardی اجرا می‌کنند که تغییرات package خارج از فیلد نسخه سطح بالا را رد می‌کند. - - ویرایش‌های harness زنده Docker ACP بررسی‌های متمرکز اجرا می‌کنند: syntax shell برای اسکریپت‌های احراز هویت live Docker و dry-run scheduler زنده Docker. تغییرات `package.json` فقط وقتی شامل می‌شوند که diff به `scripts["test:docker:live-*"]` محدود باشد؛ ویرایش‌های dependency، export، version، و سایر package-surface همچنان از guardهای گسترده‌تر استفاده می‌کنند. - - آزمون‌های واحد import-light از agents، commands، plugins، helperهای auto-reply، `plugin-sdk`، و نواحی utility خالص مشابه از مسیر lane `unit-fast` عبور می‌کنند، که `test/setup-openclaw-runtime.ts` را رد می‌کند؛ فایل‌های stateful/runtime-heavy روی laneهای موجود باقی می‌مانند. - - برخی فایل‌های source helper در `plugin-sdk` و `commands` نیز اجراهای changed-mode را به آزمون‌های هم‌جوار صریح در همان laneهای سبک نگاشت می‌کنند، تا ویرایش‌های helper از اجرای دوباره کل مجموعه سنگین برای آن دایرکتوری پرهیز کنند. - - `auto-reply` bucketهای اختصاصی برای helperهای core سطح بالا، آزمون‌های یکپارچه‌سازی سطح بالای `reply.*`، و زیردرخت `src/auto-reply/reply/**` دارد. CI زیردرخت reply را بیشتر به shardهای agent-runner، dispatch، و commands/state-routing تقسیم می‌کند تا یک bucket با import سنگین مالک کل tail مربوط به Node نشود. - - CI عادی PR/main عمداً sweep دسته‌ای extension و shard فقط‌انتشار `agentic-plugins` را رد می‌کند. Full Release Validation workflow فرزند جداگانه `Plugin Prerelease` را برای آن مجموعه‌های سنگین plugin/extension روی release candidateها dispatch می‌کند. + - `pnpm test` بدون هدف، به‌جای یک فرایند عظیم native root-project، دوازده پیکربندی shard کوچک‌تر (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) را اجرا می‌کند. این کار RSS اوج را روی ماشین‌های تحت بار کاهش می‌دهد و مانع می‌شود کار auto-reply/extension مجموعه‌های نامرتبط را بی‌منبع بگذارد. + - `pnpm test --watch` همچنان از گراف پروژهٔ native root `vitest.config.ts` استفاده می‌کند، چون حلقهٔ watch چند-shard عملی نیست. + - `pnpm test`، `pnpm test:watch`، و `pnpm test:perf:imports` هدف‌های صریح فایل/دایرکتوری را ابتدا از مسیر laneهای scoped عبور می‌دهند، بنابراین `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` هزینهٔ startup کامل پروژهٔ root را نمی‌پردازد. + - `pnpm test:changed` مسیرهای git تغییریافته را به‌طور پیش‌فرض به laneهای scoped ارزان گسترش می‌دهد: ویرایش‌های مستقیم test، فایل‌های هم‌جوار `*.test.ts`، نگاشت‌های صریح source، و وابسته‌های local import-graph. ویرایش‌های config/setup/package باعث اجرای گستردهٔ tests نمی‌شوند مگر اینکه صریحا از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. + - `pnpm check:changed` گیت smart local check عادی برای کار محدود است. diff را به core، آزمایش‌های core، extensions، آزمایش‌های extension، apps، docs، release metadata، ابزارهای Docker زنده، و tooling طبقه‌بندی می‌کند، سپس دستورهای typecheck، lint، و guard متناظر را اجرا می‌کند. آزمایش‌های Vitest را اجرا نمی‌کند؛ برای proof آزمایشی، `pnpm test:changed` یا `pnpm test ` صریح را فراخوانی کنید. افزایش نسخه‌هایی که فقط release metadata را تغییر می‌دهند، checkهای هدفمند version/config/root-dependency را اجرا می‌کنند، همراه با guardی که تغییرات package خارج از فیلد version سطح بالا را رد می‌کند. + - ویرایش‌های harness زندهٔ Docker ACP checkهای متمرکز اجرا می‌کنند: syntax shell برای اسکریپت‌های احراز هویت Docker زنده و dry-run زمان‌بند Docker زنده. تغییرات `package.json` فقط زمانی لحاظ می‌شوند که diff به `scripts["test:docker:live-*"]` محدود باشد؛ ویرایش‌های dependency، export، version، و دیگر سطح‌های package همچنان از guardهای گسترده‌تر استفاده می‌کنند. + - آزمایش‌های واحد سبک از نظر import از agents، commands، plugins، کمک‌کننده‌های auto-reply، `plugin-sdk`، و نواحی utility خالص مشابه، از lane `unit-fast` عبور می‌کنند که `test/setup-openclaw-runtime.ts` را رد می‌کند؛ فایل‌های stateful/runtime-heavy روی laneهای موجود می‌مانند. + - برخی فایل‌های source کمک‌کنندهٔ `plugin-sdk` و `commands` نیز اجراهای changed-mode را به آزمایش‌های هم‌جوار صریح در آن laneهای سبک نگاشت می‌کنند، بنابراین ویرایش‌های helper از اجرای دوبارهٔ کل suite سنگین آن دایرکتوری اجتناب می‌کنند. + - `auto-reply` bucketهای اختصاصی برای کمک‌کننده‌های core سطح بالا، آزمایش‌های integration سطح بالای `reply.*`، و زیرشاخهٔ `src/auto-reply/reply/**` دارد. CI زیرشاخهٔ reply را بیشتر به shardهای agent-runner، dispatch، و commands/state-routing تقسیم می‌کند تا یک bucket سنگین از نظر import کل دنبالهٔ Node را مالک نشود. + - CI عادی PR/main عمدا sweep دسته‌ای extension و shard فقط-انتشار `agentic-plugins` را رد می‌کند. Full Release Validation workflow فرزند جداگانهٔ `Plugin Prerelease` را برای آن suiteهای سنگین از نظر plugin/extension روی release candidateها dispatch می‌کند. - + - وقتی ورودی‌های کشف message-tool یا context runtime مربوط به Compaction را تغییر می‌دهید، هر دو سطح پوشش را نگه دارید. - - برای مرزهای routing و normalization خالص، رگرسیون‌های helper متمرکز اضافه کنید. - - مجموعه‌های یکپارچه‌سازی embedded runner را سالم نگه دارید: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`، + - regressionهای helper متمرکز برای مرزهای مسیریابی و نرمال‌سازی خالص اضافه کنید. + - مجموعه‌های integration runner توکار را سالم نگه دارید: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - این مجموعه‌ها بررسی می‌کنند که شناسه‌های scoped و رفتار Compaction همچنان - از مسیرهای واقعی `run.ts` / `compact.ts` عبور می‌کنند؛ آزمون‌های - فقط-helper جایگزین کافی برای آن مسیرهای یکپارچه‌سازی نیستند. + - آن suiteها تأیید می‌کنند که شناسه‌های scoped و رفتار Compaction همچنان + از مسیرهای واقعی `run.ts` / `compact.ts` عبور می‌کنند؛ آزمایش‌های فقط-helper + جایگزین کافی برای آن مسیرهای integration نیستند. - + - - پیکربندی پایه Vitest به‌طور پیش‌فرض `threads` است. + - پیکربندی پایهٔ Vitest به‌طور پیش‌فرض `threads` است. - پیکربندی مشترک Vitest مقدار `isolate: false` را ثابت می‌کند و از runner - غیرایزوله در پروژه‌های root، e2e، و configهای live استفاده می‌کند. - - lane ریشه UI setup و optimizer مربوط به `jsdom` خود را نگه می‌دارد، اما آن هم روی - runner مشترک غیرایزوله اجرا می‌شود. + غیر-isolated در سراسر پروژه‌های root، e2e، و پیکربندی‌های live استفاده می‌کند. + - lane مربوط به UI ریشه setup و optimizer مخصوص `jsdom` خود را نگه می‌دارد، اما آن هم روی + runner مشترک غیر-isolated اجرا می‌شود. - هر shard مربوط به `pnpm test` همان پیش‌فرض‌های `threads` + `isolate: false` را از پیکربندی مشترک Vitest به ارث می‌برد. - - `scripts/run-vitest.mjs` به‌طور پیش‌فرض برای فرایندهای فرزند Node مربوط به Vitest - مقدار `--no-maglev` را اضافه می‌کند تا churn کامپایل V8 در اجراهای محلی بزرگ کاهش یابد. - برای مقایسه با رفتار stock V8 مقدار `OPENCLAW_VITEST_ENABLE_MAGLEV=1` را تنظیم کنید. + - `scripts/run-vitest.mjs` به‌طور پیش‌فرض `--no-maglev` را برای فرایندهای فرزند Node + مربوط به Vitest اضافه می‌کند تا churn کامپایل V8 در اجراهای بزرگ local کاهش یابد. + برای مقایسه با رفتار V8 stock مقدار `OPENCLAW_VITEST_ENABLE_MAGLEV=1` را تنظیم کنید. - + - `pnpm changed:lanes` نشان می‌دهد یک diff کدام laneهای معماری را فعال می‌کند. - - hook پیش از commit فقط formatting انجام می‌دهد. فایل‌های formatشده را دوباره stage می‌کند و - lint، typecheck، یا آزمون‌ها را اجرا نمی‌کند. - - وقتی به دروازه بررسی هوشمند محلی نیاز دارید، پیش از handoff یا push، - `pnpm check:changed` را صریحاً اجرا کنید. - - `pnpm test:changed` به‌طور پیش‌فرض از مسیر laneهای scoped ارزان عبور می‌کند. فقط وقتی از + - hook مربوط به pre-commit فقط formatting انجام می‌دهد. فایل‌های formatشده را دوباره stage می‌کند و + lint، typecheck، یا tests را اجرا نمی‌کند. + - زمانی که به گیت smart local check نیاز دارید، پیش از handoff یا push، + `pnpm check:changed` را صریح اجرا کنید. + - `pnpm test:changed` به‌طور پیش‌فرض از laneهای scoped ارزان عبور می‌کند. فقط زمانی از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید که agent - تصمیم بگیرد ویرایش harness، config، package، یا contract واقعاً به پوشش گسترده‌تر + تصمیم بگیرد ویرایش harness، config، package، یا contract واقعا به پوشش گسترده‌تر Vitest نیاز دارد. - - `pnpm test:max` و `pnpm test:changed:max` همان رفتار routing را نگه می‌دارند، + - `pnpm test:max` و `pnpm test:changed:max` همان رفتار مسیریابی را نگه می‌دارند، فقط با سقف worker بالاتر. - - auto-scaling محلی worker عمداً محافظه‌کار است و وقتی میانگین load میزبان از قبل بالا باشد - عقب‌نشینی می‌کند، بنابراین چند اجرای هم‌زمان Vitest به‌طور پیش‌فرض آسیب کمتری می‌زنند. - - پیکربندی پایه Vitest پروژه‌ها/فایل‌های config را به‌عنوان - `forceRerunTriggers` علامت‌گذاری می‌کند تا rerunهای changed-mode وقتی wiring آزمون - تغییر می‌کند صحیح بمانند. - - config مقدار `OPENCLAW_VITEST_FS_MODULE_CACHE` را روی میزبان‌های پشتیبانی‌شده فعال نگه می‌دارد؛ - اگر یک محل cache صریح برای profiling مستقیم می‌خواهید، `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` را تنظیم کنید. + - auto-scaling مربوط به workerهای local عمدا محافظه‌کارانه است و وقتی load average میزبان + از قبل بالا باشد عقب‌نشینی می‌کند، بنابراین چند اجرای همزمان Vitest به‌طور پیش‌فرض + آسیب کمتری وارد می‌کنند. + - پیکربندی پایهٔ Vitest پروژه‌ها/فایل‌های config را به‌عنوان + `forceRerunTriggers` علامت‌گذاری می‌کند تا rerunهای changed-mode هنگام تغییر + سیم‌کشی test درست بمانند. + - پیکربندی، `OPENCLAW_VITEST_FS_MODULE_CACHE` را روی میزبان‌های پشتیبانی‌شده فعال نگه می‌دارد؛ + اگر برای profiling مستقیم یک مکان cache صریح می‌خواهید، + `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` را تنظیم کنید. - + - - `pnpm test:perf:imports` گزارش duration مربوط به import در Vitest به‌همراه + - `pnpm test:perf:imports` گزارش مدت‌زمان import در Vitest به‌همراه خروجی import-breakdown را فعال می‌کند. - - `pnpm test:perf:imports:changed` همان نمای profiling را به فایل‌های تغییرکرده - از زمان `origin/main` محدود می‌کند. - - داده‌های زمان‌بندی shard در `.artifacts/vitest-shard-timings.json` نوشته می‌شود. - اجراهای whole-config از مسیر config به‌عنوان key استفاده می‌کنند؛ shardهای CI مبتنی بر include-pattern - نام shard را اضافه می‌کنند تا shardهای فیلترشده جداگانه قابل ردیابی باشند. - - وقتی یک آزمون داغ همچنان بیشتر زمان خود را در importهای startup می‌گذراند، - dependencyهای سنگین را پشت یک seam محلی محدود `*.runtime.ts` نگه دارید و - همان seam را مستقیماً mock کنید، به‌جای اینکه runtime helperها را فقط برای عبور دادن به - `vi.mock(...)` به‌صورت deep import وارد کنید. - - `pnpm test:perf:changed:bench -- --ref ` مسیر routed - `test:changed` را با مسیر native root-project برای آن diff commitشده مقایسه می‌کند + - `pnpm test:perf:imports:changed` همان نمای profiling را به + فایل‌های تغییریافته از زمان `origin/main` محدود می‌کند. + - داده‌های زمان‌بندی shard در `.artifacts/vitest-shard-timings.json` نوشته می‌شوند. + اجراهای whole-config از مسیر config به‌عنوان کلید استفاده می‌کنند؛ shardهای CI مبتنی بر + include-pattern نام shard را اضافه می‌کنند تا shardهای filtered جداگانه قابل ردیابی باشند. + - وقتی یک test داغ همچنان بیشتر زمان خود را در importهای startup صرف می‌کند، + dependencyهای سنگین را پشت یک درز local محدود `*.runtime.ts` نگه دارید و + به‌جای deep-import کردن helperهای runtime فقط برای عبور دادنشان از `vi.mock(...)`، + همان درز را مستقیما mock کنید. + - `pnpm test:perf:changed:bench -- --ref ` مسیر route‌شدهٔ + `test:changed` را با مسیر native root-project برای آن diff commit‌شده مقایسه می‌کند و wall time به‌همراه max RSS در macOS را چاپ می‌کند. - `pnpm test:perf:changed:bench -- --worktree` درخت dirty فعلی را با عبور دادن - فهرست فایل‌های تغییرکرده از مسیر `scripts/test-projects.mjs` و پیکربندی ریشه Vitest - benchmark می‌کند. + فهرست فایل‌های تغییریافته از + `scripts/test-projects.mjs` و پیکربندی root Vitest benchmark می‌کند. - `pnpm test:perf:profile:main` یک profile CPU مربوط به main-thread برای - سربار startup و transform در Vitest/Vite می‌نویسد. + overheadهای startup و transform در Vitest/Vite می‌نویسد. - `pnpm test:perf:profile:runner` profileهای CPU+heap مربوط به runner را برای - مجموعه واحد با file parallelism غیرفعال می‌نویسد. + suite واحد با parallelism فایل غیرفعال می‌نویسد. ### پایداری (Gateway) -- فرمان: `pnpm test:stability:gateway` -- پیکربندی: `vitest.gateway.config.ts`، اجبار به یک worker +- دستور: `pnpm test:stability:gateway` +- پیکربندی: `vitest.gateway.config.ts`، اجبارا با یک worker - دامنه: - یک Gateway واقعی روی local loopback را با diagnostics فعال به‌طور پیش‌فرض شروع می‌کند - - churn مصنوعی پیام، حافظه، و payload بزرگ Gateway را از مسیر رویداد diagnostic عبور می‌دهد + - churn پیام مصنوعی Gateway، memory، و payload بزرگ را از مسیر event تشخیصی عبور می‌دهد - `diagnostics.stability` را از طریق Gateway WS RPC query می‌کند - - helperهای persistence مربوط به bundle پایداری diagnostic را پوشش می‌دهد - - assert می‌کند که recorder محدود می‌ماند، نمونه‌های مصنوعی RSS زیر بودجه فشار باقی می‌مانند، و عمق صف‌های per-session دوباره به صفر تخلیه می‌شود + - helperهای persistence مربوط به bundle پایداری تشخیصی را پوشش می‌دهد + - assert می‌کند که recorder محدود می‌ماند، نمونه‌های مصنوعی RSS زیر بودجهٔ فشار می‌مانند، و عمق queue هر session دوباره به صفر تخلیه می‌شود - انتظارات: - - برای CI امن و بدون نیاز به کلید است - - lane محدود برای پیگیری رگرسیون پایداری، نه جایگزینی برای مجموعه کامل Gateway + - برای CI امن و بدون کلید است + - lane محدود برای پیگیری regression پایداری است، نه جایگزینی برای کل suite مربوط به Gateway -### E2E (gateway smoke) +### E2E (smoke مربوط به Gateway) - دستور: `pnpm test:e2e` - پیکربندی: `vitest.e2e.config.ts` -- فایل‌ها: `src/**/*.e2e.test.ts`، `test/**/*.e2e.test.ts`، و آزمون‌های E2E مربوط به Pluginهای همراه در `extensions/` +- فایل‌ها: `src/**/*.e2e.test.ts`، `test/**/*.e2e.test.ts`، و آزمون‌های E2E پلاگین‌های همراه در `extensions/` - پیش‌فرض‌های زمان اجرا: - - از `threads` در Vitest با `isolate: false` استفاده می‌کند، مطابق با بقیه مخزن. - - از کارگرهای تطبیقی استفاده می‌کند (CI: حداکثر ۲، محلی: به‌طور پیش‌فرض ۱). - - به‌طور پیش‌فرض در حالت بی‌صدا اجرا می‌شود تا سربار I/O کنسول کاهش یابد. + - از Vitest `threads` با `isolate: false` استفاده می‌کند که با بقیه مخزن هم‌خوان است. + - از workerهای تطبیقی استفاده می‌کند (CI: حداکثر 2، محلی: به‌طور پیش‌فرض 1). + - به‌طور پیش‌فرض در حالت بی‌صدا اجرا می‌شود تا سربار ورودی/خروجی کنسول کاهش یابد. - بازنویسی‌های مفید: - - `OPENCLAW_E2E_WORKERS=` برای اجبار تعداد کارگرها (با سقف ۱۶). + - `OPENCLAW_E2E_WORKERS=` برای اجبار تعداد workerها (با سقف 16). - `OPENCLAW_E2E_VERBOSE=1` برای فعال‌سازی دوباره خروجی مفصل کنسول. - دامنه: - رفتار سرتاسری Gateway چندنمونه‌ای - سطوح WebSocket/HTTP، جفت‌سازی Node، و شبکه‌سازی سنگین‌تر -- انتظارات: - - در CI اجرا می‌شود (وقتی در خط لوله فعال باشد) +- انتظارها: + - در CI اجرا می‌شود (وقتی در pipeline فعال باشد) - به کلیدهای واقعی نیاز ندارد - قطعات متحرک بیشتری نسبت به آزمون‌های واحد دارد (می‌تواند کندتر باشد) -### E2E: اسموک بک‌اند OpenShell +### E2E: دودآزمایی بک‌اند OpenShell - دستور: `pnpm test:e2e:openshell` - فایل: `extensions/openshell/src/backend.e2e.test.ts` - دامنه: - - یک Gateway ایزوله OpenShell را از طریق Docker روی میزبان راه‌اندازی می‌کند - - از یک Dockerfile محلی موقت یک sandbox می‌سازد - - بک‌اند OpenShell در OpenClaw را از طریق `sandbox ssh-config` واقعی + اجرای SSH تمرین می‌دهد - - رفتار سیستم فایلِ canonical راه‌دور را از طریق پل sandbox fs بررسی می‌کند -- انتظارات: - - فقط با انتخاب صریح؛ بخشی از اجرای پیش‌فرض `pnpm test:e2e` نیست - - به CLI محلی `openshell` به‌همراه یک Docker daemon فعال نیاز دارد + - یک Gateway ایزوله OpenShell را روی میزبان از طریق Docker شروع می‌کند + - یک sandbox را از یک Dockerfile محلی موقت ایجاد می‌کند + - بک‌اند OpenShell در OpenClaw را روی `sandbox ssh-config` واقعی + اجرای SSH تمرین می‌دهد + - رفتار فایل‌سیستم remote-canonical را از طریق پل sandbox fs راستی‌آزمایی می‌کند +- انتظارها: + - فقط opt-in است؛ بخشی از اجرای پیش‌فرض `pnpm test:e2e` نیست + - به یک CLI محلی `openshell` به‌همراه daemon فعال Docker نیاز دارد - از `HOME` / `XDG_CONFIG_HOME` ایزوله استفاده می‌کند، سپس Gateway و sandbox آزمون را نابود می‌کند - بازنویسی‌های مفید: - - `OPENCLAW_E2E_OPENSHELL=1` برای فعال‌کردن آزمون هنگام اجرای دستی مجموعه e2e گسترده‌تر - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` برای اشاره به باینری CLI یا اسکریپت wrapper غیرپیش‌فرض + - `OPENCLAW_E2E_OPENSHELL=1` برای فعال‌سازی آزمون هنگام اجرای دستی مجموعه e2e گسترده‌تر + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` برای اشاره به یک باینری CLI یا اسکریپت wrapper غیرپیش‌فرض -### زنده (ارائه‌دهندگان واقعی + مدل‌های واقعی) +### زنده (providerهای واقعی + مدل‌های واقعی) - دستور: `pnpm test:live` - پیکربندی: `vitest.live.config.ts` -- فایل‌ها: `src/**/*.live.test.ts`، `test/**/*.live.test.ts`، و آزمون‌های زنده Pluginهای همراه در `extensions/` +- فایل‌ها: `src/**/*.live.test.ts`، `test/**/*.live.test.ts`، و آزمون‌های زنده پلاگین‌های همراه در `extensions/` - پیش‌فرض: با `pnpm test:live` **فعال** است (`OPENCLAW_LIVE_TEST=1` را تنظیم می‌کند) - دامنه: - - «آیا این ارائه‌دهنده/مدل واقعاً _امروز_ با اعتبارنامه‌های واقعی کار می‌کند؟» - - تغییرات قالب ارائه‌دهنده، ویژگی‌های خاص فراخوانی ابزار، مشکلات احراز هویت، و رفتار محدودیت نرخ را می‌گیرد -- انتظارات: - - بنا به طراحی برای CI پایدار نیست (شبکه‌های واقعی، سیاست‌های واقعی ارائه‌دهنده، سهمیه‌ها، قطعی‌ها) - - هزینه دارد / از محدودیت‌های نرخ استفاده می‌کند + - «آیا این provider/model واقعاً _امروز_ با اعتبارنامه‌های واقعی کار می‌کند؟» + - گرفتن تغییرات قالب provider، ریزه‌کاری‌های tool-calling، مشکلات احراز هویت، و رفتار rate limit +- انتظارها: + - بنا بر طراحی در CI پایدار نیست (شبکه‌های واقعی، سیاست‌های واقعی provider، سهمیه‌ها، قطعی‌ها) + - هزینه دارد / از rate limitها استفاده می‌کند - اجرای زیرمجموعه‌های محدودشده را به‌جای «همه‌چیز» ترجیح دهید -- اجراهای زنده `~/.profile` را source می‌کنند تا کلیدهای API جاافتاده را بردارند. -- به‌طور پیش‌فرض، اجراهای زنده همچنان `HOME` را ایزوله می‌کنند و مواد پیکربندی/احراز هویت را در یک خانه آزمون موقت کپی می‌کنند تا fixtureهای واحد نتوانند `~/.openclaw` واقعی شما را تغییر دهند. -- فقط وقتی `OPENCLAW_LIVE_USE_REAL_HOME=1` را تنظیم کنید که عمداً نیاز دارید آزمون‌های زنده از دایرکتوری home واقعی شما استفاده کنند. -- `pnpm test:live` اکنون به‌طور پیش‌فرض از حالت کم‌سروصداتر استفاده می‌کند: خروجی پیشرفت `[live] ...` را نگه می‌دارد، اما اعلان اضافی `~/.profile` را سرکوب می‌کند و لاگ‌های bootstrap مربوط به Gateway/گفت‌وگوی Bonjour را بی‌صدا می‌کند. اگر می‌خواهید لاگ‌های کامل راه‌اندازی برگردند، `OPENCLAW_LIVE_TEST_QUIET=0` را تنظیم کنید. -- چرخش کلید API (ویژه هر ارائه‌دهنده): `*_API_KEYS` را با قالب کاما/نقطه‌ویرگول یا `*_API_KEY_1`، `*_API_KEY_2` تنظیم کنید (برای مثال `OPENAI_API_KEYS`، `ANTHROPIC_API_KEYS`، `GEMINI_API_KEYS`) یا بازنویسی مختص زنده را از طریق `OPENCLAW_LIVE_*_KEY` تنظیم کنید؛ آزمون‌ها هنگام پاسخ‌های محدودیت نرخ دوباره تلاش می‌کنند. +- اجراهای زنده `~/.profile` را source می‌کنند تا کلیدهای API گم‌شده را بردارند. +- به‌طور پیش‌فرض، اجراهای زنده همچنان `HOME` را ایزوله می‌کنند و مواد config/auth را به یک خانه آزمون موقت کپی می‌کنند تا fixtureهای واحد نتوانند `~/.openclaw` واقعی شما را تغییر دهند. +- `OPENCLAW_LIVE_USE_REAL_HOME=1` را فقط وقتی تنظیم کنید که عمداً لازم دارید آزمون‌های زنده از دایرکتوری خانه واقعی شما استفاده کنند. +- `pnpm test:live` اکنون به‌طور پیش‌فرض حالت کم‌صداتری دارد: خروجی پیشرفت `[live] ...` را نگه می‌دارد، اما اعلان اضافی `~/.profile` را پنهان می‌کند و لاگ‌های bootstrap Gateway/گفت‌وگوی Bonjour را بی‌صدا می‌کند. اگر می‌خواهید لاگ‌های کامل startup برگردند، `OPENCLAW_LIVE_TEST_QUIET=0` را تنظیم کنید. +- چرخش کلید API (مختص provider): `*_API_KEYS` را با قالب comma/semicolon یا `*_API_KEY_1`، `*_API_KEY_2` تنظیم کنید (برای مثال `OPENAI_API_KEYS`، `ANTHROPIC_API_KEYS`، `GEMINI_API_KEYS`) یا بازنویسی per-live را از طریق `OPENCLAW_LIVE_*_KEY` انجام دهید؛ آزمون‌ها در پاسخ‌های rate limit دوباره تلاش می‌کنند. - خروجی پیشرفت/Heartbeat: - - مجموعه‌های زنده اکنون خطوط پیشرفت را به stderr منتشر می‌کنند تا فراخوانی‌های طولانی ارائه‌دهنده حتی وقتی capture کنسول Vitest کم‌صداست، به‌صورت قابل مشاهده فعال باشند. - - `vitest.live.config.ts` رهگیری کنسول Vitest را غیرفعال می‌کند تا خطوط پیشرفت ارائه‌دهنده/Gateway بلافاصله در طول اجراهای زنده stream شوند. - - Heartbeatهای مدل مستقیم را با `OPENCLAW_LIVE_HEARTBEAT_MS` تنظیم کنید. + - مجموعه‌های زنده اکنون خط‌های پیشرفت را به stderr منتشر می‌کنند تا فراخوانی‌های طولانی provider حتی وقتی capture کنسول Vitest ساکت است، به‌صورت دیداری فعال باشند. + - `vitest.live.config.ts` رهگیری کنسول Vitest را غیرفعال می‌کند تا خط‌های پیشرفت provider/Gateway در طول اجراهای زنده فوراً stream شوند. + - Heartbeatهای direct-model را با `OPENCLAW_LIVE_HEARTBEAT_MS` تنظیم کنید. - Heartbeatهای Gateway/probe را با `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` تنظیم کنید. ## کدام مجموعه را اجرا کنم؟ از این جدول تصمیم استفاده کنید: -- ویرایش منطق/آزمون‌ها: `pnpm test` را اجرا کنید (و اگر چیزهای زیادی تغییر داده‌اید، `pnpm test:coverage`) -- لمس شبکه‌سازی Gateway / پروتکل WS / جفت‌سازی: `pnpm test:e2e` را اضافه کنید -- اشکال‌زدایی «بات من از کار افتاده است» / خرابی‌های ویژه ارائه‌دهنده / فراخوانی ابزار: یک `pnpm test:live` محدودشده را اجرا کنید +- ویرایش منطق/آزمون‌ها: `pnpm test` را اجرا کنید (و اگر زیاد تغییر داده‌اید، `pnpm test:coverage`) +- دست‌کاری شبکه‌سازی Gateway / پروتکل WS / جفت‌سازی: `pnpm test:e2e` را اضافه کنید +- اشکال‌زدایی «رباتم down است» / شکست‌های مختص provider / tool calling: یک `pnpm test:live` محدودشده اجرا کنید -## آزمون‌های زنده (دارای تماس شبکه) +## آزمون‌های زنده (دست‌زننده به شبکه) -برای ماتریس مدل زنده، اسموک‌های بک‌اند CLI، اسموک‌های ACP، harness سرور برنامه Codex، -و همه آزمون‌های زنده ارائه‌دهنده رسانه (Deepgram، BytePlus، ComfyUI، تصویر، -موسیقی، ویدئو، harness رسانه) — به‌علاوه مدیریت اعتبارنامه برای اجراهای زنده — ببینید +برای ماتریس مدل زنده، دودآزمایی‌های بک‌اند CLI، دودآزمایی‌های ACP، harness +app-server کدکس، و همه آزمون‌های زنده media-provider (Deepgram، BytePlus، ComfyUI، image، +music، video، media harness) — به‌علاوه مدیریت اعتبارنامه برای اجراهای زنده — ببینید [آزمون مجموعه‌های زنده](/fa/help/testing-live). برای چک‌لیست اختصاصی به‌روزرسانی و -اعتبارسنجی Plugin، ببینید -[آزمون به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins). +اعتبارسنجی پلاگین، ببینید +[آزمون به‌روزرسانی‌ها و پلاگین‌ها](/fa/help/testing-updates-plugins). ## اجراکننده‌های Docker (بررسی‌های اختیاری «در Linux کار می‌کند») این اجراکننده‌های Docker به دو دسته تقسیم می‌شوند: -- اجراکننده‌های مدل زنده: `test:docker:live-models` و `test:docker:live-gateway` فقط فایل زنده منطبق با کلید پروفایل خود را داخل image Docker مخزن اجرا می‌کنند (`src/agents/models.profiles.live.test.ts` و `src/gateway/gateway-models.profiles.live.test.ts`) و دایرکتوری پیکربندی محلی و workspace شما را mount می‌کنند (و اگر `~/.profile` mount شده باشد، آن را source می‌کنند). نقطه‌های ورود محلی منطبق `test:live:models-profiles` و `test:live:gateway-profiles` هستند. -- اجراکننده‌های زنده Docker به‌طور پیش‌فرض از سقف اسموک کوچک‌تری استفاده می‌کنند تا یک sweep کامل Docker عملی بماند: +- اجراکننده‌های live-model: `test:docker:live-models` و `test:docker:live-gateway` فقط فایل زنده profile-key متناظر خود را داخل image Docker مخزن اجرا می‌کنند (`src/agents/models.profiles.live.test.ts` و `src/gateway/gateway-models.profiles.live.test.ts`) و دایرکتوری config محلی و workspace شما را mount می‌کنند (و اگر `~/.profile` mount شده باشد، آن را source می‌کنند). entrypointهای محلی متناظر `test:live:models-profiles` و `test:live:gateway-profiles` هستند. +- اجراکننده‌های زنده Docker به‌طور پیش‌فرض سقف smoke کوچک‌تری دارند تا یک sweep کامل Docker عملی بماند: `test:docker:live-models` به‌طور پیش‌فرض `OPENCLAW_LIVE_MAX_MODELS=12` است، و `test:docker:live-gateway` به‌طور پیش‌فرض `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` است. وقتی صراحتاً اسکن جامع بزرگ‌تر را می‌خواهید، آن متغیرهای env را بازنویسی کنید. -- `test:docker:all` تصویر Docker زنده را یک‌بار از طریق `test:docker:live-build` می‌سازد، OpenClaw را یک‌بار از طریق `scripts/package-openclaw-for-docker.mjs` به‌صورت npm tarball بسته‌بندی می‌کند، سپس دو image مبتنی بر `scripts/e2e/Dockerfile` را می‌سازد/دوباره استفاده می‌کند. image ساده فقط اجراکننده Node/Git برای مسیرهای install/update/plugin-dependency است؛ آن مسیرها tarball از پیش ساخته‌شده را mount می‌کنند. image عملکردی همان tarball را برای مسیرهای عملکرد برنامه ساخته‌شده در `/app` نصب می‌کند. تعریف مسیرهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارد؛ منطق planner در `scripts/lib/docker-e2e-plan.mjs` قرار دارد؛ `scripts/test-docker-all.mjs` طرح انتخاب‌شده را اجرا می‌کند. تجمیع‌کننده از یک زمان‌بند محلی وزن‌دار استفاده می‌کند: `OPENCLAW_DOCKER_ALL_PARALLELISM` جایگاه‌های پردازه را کنترل می‌کند، در حالی که سقف‌های منبع مانع می‌شوند مسیرهای سنگین زنده، نصب npm، و چندسرویسی همگی هم‌زمان شروع شوند. اگر یک مسیر واحد از سقف‌های فعال سنگین‌تر باشد، زمان‌بند همچنان می‌تواند وقتی pool خالی است آن را شروع کند و سپس آن را تنها در حال اجرا نگه می‌دارد تا ظرفیت دوباره در دسترس شود. پیش‌فرض‌ها ۱۰ جایگاه، `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`، `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`، و `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` هستند؛ فقط وقتی میزبان Docker فضای بیشتری دارد، `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` یا `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` را تنظیم کنید. اجراکننده به‌طور پیش‌فرض preflight Docker را انجام می‌دهد، کانتینرهای E2E کهنه OpenClaw را حذف می‌کند، هر ۳۰ ثانیه وضعیت را چاپ می‌کند، زمان‌بندی‌های مسیر موفق را در `.artifacts/docker-tests/lane-timings.json` ذخیره می‌کند، و از آن زمان‌بندی‌ها برای شروع مسیرهای طولانی‌تر در اجراهای بعدی استفاده می‌کند. از `OPENCLAW_DOCKER_ALL_DRY_RUN=1` برای چاپ manifest مسیر وزن‌دار بدون ساخت یا اجرای Docker استفاده کنید، یا از `node scripts/test-docker-all.mjs --plan-json` برای چاپ طرح CI برای مسیرهای انتخاب‌شده، نیازهای package/image، و اعتبارنامه‌ها استفاده کنید. -- `Package Acceptance` دروازه بومی GitHub برای package است: «آیا این tarball قابل نصب به‌عنوان یک محصول کار می‌کند؟» یک package نامزد را از `source=npm`، `source=ref`، `source=url`، یا `source=artifact` resolve می‌کند، آن را به‌عنوان `package-under-test` بارگذاری می‌کند، سپس مسیرهای Docker E2E قابل استفاده مجدد را در برابر همان tarball دقیق اجرا می‌کند، به‌جای اینکه ref انتخاب‌شده را دوباره بسته‌بندی کند. پروفایل‌ها بر اساس گستردگی مرتب شده‌اند: `smoke`، `package`، `product`، و `full`. برای قرارداد package/update/plugin، ماتریس بازمانده ارتقای منتشرشده، پیش‌فرض‌های انتشار، و triage خرابی، ببینید [آزمون به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins). -- بررسی‌های build و انتشار بعد از tsdown، `scripts/check-cli-bootstrap-imports.mjs` را اجرا می‌کنند. این guard گراف ساخته‌شده ایستا را از `dist/entry.js` و `dist/cli/run-main.js` پیمایش می‌کند و اگر importهای راه‌اندازی پیش از dispatch وابستگی‌های package مانند Commander، UI پرامپت، undici، یا logging را قبل از dispatch فرمان وارد کنند، شکست می‌خورد؛ همچنین chunk اجرای Gateway همراه را زیر بودجه نگه می‌دارد و importهای ایستای مسیرهای سرد شناخته‌شده Gateway را رد می‌کند. اسموک CLI بسته‌بندی‌شده همچنین help ریشه، help onboarding، help doctor، status، schema پیکربندی، و یک فرمان فهرست مدل را پوشش می‌دهد. -- سازگاری legacy در Package Acceptance در `2026.4.25` سقف دارد (`2026.4.25-beta.*` هم شامل می‌شود). تا آن cutoff، harness فقط شکاف‌های metadata مربوط به packageهای shipped را تحمل می‌کند: ورودی‌های private QA inventory حذف‌شده، نبود `gateway install --wrapper`، نبود فایل‌های patch در fixture گیت مشتق‌شده از tarball، نبود `update.channel` پایدارشده، مکان‌های legacy رکورد نصب Plugin، نبود پایداری رکورد نصب marketplace، و مهاجرت metadata پیکربندی هنگام `plugins update`. برای packageهای بعد از `2026.4.25`، آن مسیرها خرابی سخت‌گیرانه هستند. -- اجراکننده‌های اسموک کانتینر: `test:docker:openwebui`، `test:docker:onboard`، `test:docker:npm-onboard-channel-agent`، `test:docker:update-channel-switch`، `test:docker:upgrade-survivor`، `test:docker:published-upgrade-survivor`، `test:docker:session-runtime-context`، `test:docker:agents-delete-shared-workspace`، `test:docker:gateway-network`، `test:docker:browser-cdp-snapshot`، `test:docker:mcp-channels`، `test:docker:pi-bundle-mcp-tools`، `test:docker:cron-mcp-cleanup`، `test:docker:plugins`، `test:docker:plugin-update`، `test:docker:plugin-lifecycle-matrix`، و `test:docker:config-reload` یک یا چند کانتینر واقعی را بوت می‌کنند و مسیرهای یکپارچه‌سازی سطح بالاتر را بررسی می‌کنند. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` است. وقتی صریحاً اسکن جامع بزرگ‌تر را می‌خواهید، آن متغیرهای محیطی را بازنویسی کنید. +- `test:docker:all` یک‌بار image زنده Docker را از طریق `test:docker:live-build` می‌سازد، OpenClaw را یک‌بار از طریق `scripts/package-openclaw-for-docker.mjs` به‌صورت tarball npm بسته‌بندی می‌کند، سپس دو image مبتنی بر `scripts/e2e/Dockerfile` را می‌سازد/بازاستفاده می‌کند. image bare فقط اجراکننده Node/Git برای laneهای install/update/plugin-dependency است؛ آن laneها tarball ازپیش‌ساخته را mount می‌کنند. image functional همان tarball را برای laneهای عملکرد built-app در `/app` نصب می‌کند. تعریف laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` است؛ منطق planner در `scripts/lib/docker-e2e-plan.mjs` است؛ `scripts/test-docker-all.mjs` طرح انتخاب‌شده را اجرا می‌کند. aggregate از یک scheduler محلی weighted استفاده می‌کند: `OPENCLAW_DOCKER_ALL_PARALLELISM` slotهای process را کنترل می‌کند، در حالی که سقف‌های منبع مانع می‌شوند laneهای سنگین live، npm-install، و multi-service همگی هم‌زمان شروع شوند. اگر یک lane منفرد از سقف‌های فعال سنگین‌تر باشد، scheduler همچنان می‌تواند وقتی pool خالی است آن را شروع کند و سپس آن را تنها در حال اجرا نگه می‌دارد تا ظرفیت دوباره در دسترس شود. پیش‌فرض‌ها 10 slot، `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`، `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`، و `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` هستند؛ فقط وقتی میزبان Docker فضای بیشتری دارد، `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` یا `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` را تنظیم کنید. اجراکننده به‌طور پیش‌فرض یک preflight Docker انجام می‌دهد، containerهای E2E قدیمی OpenClaw را حذف می‌کند، هر 30 ثانیه وضعیت را چاپ می‌کند، زمان‌بندی laneهای موفق را در `.artifacts/docker-tests/lane-timings.json` ذخیره می‌کند، و از آن زمان‌بندی‌ها استفاده می‌کند تا در اجراهای بعدی laneهای طولانی‌تر را زودتر شروع کند. از `OPENCLAW_DOCKER_ALL_DRY_RUN=1` برای چاپ manifest laneهای weighted بدون ساختن یا اجرای Docker استفاده کنید، یا از `node scripts/test-docker-all.mjs --plan-json` برای چاپ طرح CI برای laneهای انتخاب‌شده، نیازهای package/image، و اعتبارنامه‌ها استفاده کنید. +- `Package Acceptance` gate بومی GitHub برای package است: «آیا این tarball قابل نصب به‌عنوان محصول کار می‌کند؟» یک package نامزد را از `source=npm`، `source=ref`، `source=url`، یا `source=artifact` resolve می‌کند، آن را به‌عنوان `package-under-test` آپلود می‌کند، سپس laneهای reusable Docker E2E را در برابر همان tarball دقیق اجرا می‌کند به‌جای اینکه ref انتخاب‌شده را دوباره بسته‌بندی کند. profileها بر اساس گستردگی مرتب شده‌اند: `smoke`، `package`، `product`، و `full`. برای قرارداد package/update/plugin، ماتریس survivor ارتقای منتشرشده، پیش‌فرض‌های انتشار، و triage شکست، [آزمون به‌روزرسانی‌ها و پلاگین‌ها](/fa/help/testing-updates-plugins) را ببینید. +- بررسی‌های build و release پس از tsdown، `scripts/check-cli-bootstrap-imports.mjs` را اجرا می‌کنند. guard گراف ساخته‌شده ایستای `dist/entry.js` و `dist/cli/run-main.js` را پیمایش می‌کند و اگر importهای startup پیش از dispatch، وابستگی‌های package مانند Commander، prompt UI، undici، یا logging را پیش از dispatch فرمان وارد کنند، شکست می‌خورد؛ همچنین chunk اجرای Gateway همراه را زیر بودجه نگه می‌دارد و importهای ایستای مسیرهای cold شناخته‌شده Gateway را رد می‌کند. دودآزمایی CLI بسته‌بندی‌شده همچنین root help، onboard help، doctor help، status، config schema، و یک فرمان model-list را پوشش می‌دهد. +- سازگاری legacy در Package Acceptance در `2026.4.25` محدود شده است (`2026.4.25-beta.*` هم شامل می‌شود). تا آن cutoff، harness فقط شکاف‌های metadata مربوط به packageهای shipped را تحمل می‌کند: ورودی‌های private QA inventory حذف‌شده، `gateway install --wrapper` گم‌شده، فایل‌های patch گم‌شده در fixture git مشتق‌شده از tarball، `update.channel` persisted گم‌شده، محل‌های legacy برای plugin install-record، persistence گم‌شده install-record marketplace، و مهاجرت metadata پیکربندی هنگام `plugins update`. برای packageهای پس از `2026.4.25`، آن مسیرها شکست‌های سخت‌گیرانه هستند. +- اجراکننده‌های container smoke: `test:docker:openwebui`، `test:docker:onboard`، `test:docker:npm-onboard-channel-agent`، `test:docker:update-channel-switch`، `test:docker:upgrade-survivor`، `test:docker:published-upgrade-survivor`، `test:docker:session-runtime-context`، `test:docker:agents-delete-shared-workspace`، `test:docker:gateway-network`، `test:docker:browser-cdp-snapshot`، `test:docker:mcp-channels`، `test:docker:pi-bundle-mcp-tools`، `test:docker:cron-mcp-cleanup`، `test:docker:plugins`، `test:docker:plugin-update`، `test:docker:plugin-lifecycle-matrix`، و `test:docker:config-reload` یک یا چند container واقعی را boot می‌کنند و مسیرهای یکپارچه‌سازی سطح‌بالاتر را راستی‌آزمایی می‌کنند. -اجراکننده‌های Docker مدل زنده همچنین فقط خانه‌های احراز هویت CLI موردنیاز را bind-mount می‌کنند (یا وقتی اجرا محدود نشده باشد، همه خانه‌های پشتیبانی‌شده را)، سپس پیش از اجرا آن‌ها را در home کانتینر کپی می‌کنند تا OAuth مربوط به CLI خارجی بتواند tokenها را بدون تغییر دادن مخزن احراز هویت میزبان refresh کند: +اجراکننده‌های Docker مربوط به live-model همچنین فقط homeهای auth موردنیاز CLI را bind-mount می‌کنند (یا وقتی اجرا محدود نشده باشد، همه homeهای پشتیبانی‌شده را)، سپس آن‌ها را پیش از اجرا در home کانتینر کپی می‌کنند تا OAuth مربوط به CLI خارجی بتواند tokenها را بدون تغییر دادن store احراز هویت میزبان refresh کند: - مدل‌های مستقیم: `pnpm test:docker:live-models` (اسکریپت: `scripts/test-live-models-docker.sh`) -- دودآزمون اتصال ACP: `pnpm test:docker:live-acp-bind` (اسکریپت: `scripts/test-live-acp-bind-docker.sh`؛ به‌طور پیش‌فرض Claude، Codex و Gemini را پوشش می‌دهد، با پوشش سخت‌گیرانه Droid/OpenCode از طریق `pnpm test:docker:live-acp-bind:droid` و `pnpm test:docker:live-acp-bind:opencode`) -- دودآزمون بک‌اند CLI: `pnpm test:docker:live-cli-backend` (اسکریپت: `scripts/test-live-cli-backend-docker.sh`) -- دودآزمون هارنس کارساز برنامه Codex: `pnpm test:docker:live-codex-harness` (اسکریپت: `scripts/test-live-codex-harness-docker.sh`) +- دودسنجی اتصال ACP: `pnpm test:docker:live-acp-bind` (اسکریپت: `scripts/test-live-acp-bind-docker.sh`؛ به‌طور پیش‌فرض Claude، Codex و Gemini را پوشش می‌دهد، با پوشش سخت‌گیرانه Droid/OpenCode از طریق `pnpm test:docker:live-acp-bind:droid` و `pnpm test:docker:live-acp-bind:opencode`) +- دودسنجی backend مربوط به CLI: `pnpm test:docker:live-cli-backend` (اسکریپت: `scripts/test-live-cli-backend-docker.sh`) +- دودسنجی harness سرور برنامه Codex: `pnpm test:docker:live-codex-harness` (اسکریپت: `scripts/test-live-codex-harness-docker.sh`) - Gateway + عامل توسعه: `pnpm test:docker:live-gateway` (اسکریپت: `scripts/test-live-gateway-models-docker.sh`) -- دودآزمون مشاهده‌پذیری: `pnpm qa:otel:smoke` یک مسیر خصوصی QA برای checkout منبع است. این مورد عمداً بخشی از مسیرهای انتشار Docker بسته نیست، چون tarball مربوط به npm، QA Lab را حذف می‌کند. -- دودآزمون زنده Open WebUI: `pnpm test:docker:openwebui` (اسکریپت: `scripts/e2e/openwebui-docker.sh`) -- جادوگر آغازبه‌کار (TTY، داربست‌سازی کامل): `pnpm test:docker:onboard` (اسکریپت: `scripts/e2e/onboard-docker.sh`) -- دودآزمون آغازبه‌کار/کانال/عامل tarball مربوط به Npm: `pnpm test:docker:npm-onboard-channel-agent`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، OpenAI را از طریق آغازبه‌کار env-ref به‌همراه Telegram به‌طور پیش‌فرض پیکربندی می‌کند، doctor را اجرا می‌کند، و یک نوبت عامل OpenAI شبیه‌سازی‌شده را اجرا می‌کند. با `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` از tarball ازپیش‌ساخته استفاده کنید، با `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` بازسازی میزبان را رد کنید، یا با `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` کانال را تغییر دهید. -- دودآزمون تغییر کانال به‌روزرسانی: `pnpm test:docker:update-channel-switch`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، از بسته `stable` به git `dev` تغییر می‌دهد، کانال پایدارشده و عملکرد Plugin پس از به‌روزرسانی را راستی‌آزمایی می‌کند، سپس دوباره به بسته `stable` برمی‌گردد و وضعیت به‌روزرسانی را بررسی می‌کند. -- دودآزمون بازمانده ارتقا: `pnpm test:docker:upgrade-survivor`، tarball بسته‌بندی‌شده OpenClaw را روی یک fixture کثیف کاربر قدیمی با عامل‌ها، پیکربندی کانال، فهرست‌های مجاز Plugin، وضعیت کهنه وابستگی Plugin، و فایل‌های موجود workspace/session نصب می‌کند. به‌روزرسانی بسته به‌همراه doctor غیرتعاملی را بدون کلیدهای provider یا کانال زنده اجرا می‌کند، سپس یک Gateway حلقه‌بازگشتی را شروع می‌کند و حفظ پیکربندی/وضعیت به‌همراه بودجه‌های startup/status را بررسی می‌کند. -- دودآزمون بازمانده ارتقای منتشرشده: `pnpm test:docker:published-upgrade-survivor` به‌طور پیش‌فرض `openclaw@latest` را نصب می‌کند، فایل‌های واقع‌گرایانه کاربر موجود را seed می‌کند، آن مبنا را با یک recipe فرمان baked پیکربندی می‌کند، پیکربندی حاصل را اعتبارسنجی می‌کند، آن نصب منتشرشده را به tarball نامزد به‌روزرسانی می‌کند، doctor غیرتعاملی را اجرا می‌کند، `.artifacts/upgrade-survivor/summary.json` را می‌نویسد، سپس یک Gateway حلقه‌بازگشتی را شروع می‌کند و intentهای پیکربندی‌شده، حفظ وضعیت، startup، `/healthz`، `/readyz`، و بودجه‌های وضعیت RPC را بررسی می‌کند. یک مبنا را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` بازنویسی کنید، از زمان‌بند تجمیعی بخواهید مبناهای دقیق را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` مانند `all-since-2026.4.23` گسترش دهد، و fixtureهای مسئله‌محور را با `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` مانند `reported-issues` گسترش دهید؛ مجموعه reported-issues شامل `configured-plugin-installs` برای ترمیم خودکار نصب Plugin خارجی OpenClaw است. Package Acceptance این موارد را با نام‌های `published_upgrade_survivor_baseline`، `published_upgrade_survivor_baselines`، و `published_upgrade_survivor_scenarios` ارائه می‌کند. -- دودآزمون زمینه runtime نشست: `pnpm test:docker:session-runtime-context`، پایداری transcript زمینه runtime پنهان به‌همراه ترمیم doctor برای شاخه‌های تکراری متاثر prompt-rewrite را راستی‌آزمایی می‌کند. -- دودآزمون نصب سراسری Bun: `bash scripts/e2e/bun-global-install-smoke.sh` درخت فعلی را بسته‌بندی می‌کند، آن را با `bun install -g` در یک home ایزوله نصب می‌کند، و راستی‌آزمایی می‌کند که `openclaw infer image providers --json` به‌جای hang شدن، providerهای تصویر bundled را برمی‌گرداند. با `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` از tarball ازپیش‌ساخته استفاده کنید، با `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` build میزبان را رد کنید، یا با `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`، `dist/` را از یک تصویر Docker ساخته‌شده کپی کنید. -- دودآزمون Docker نصب‌کننده: `bash scripts/test-install-sh-docker.sh` یک cache مشترک npm را میان containerهای root، update، و direct-npm خود به‌اشتراک می‌گذارد. دودآزمون update پیش از ارتقا به tarball نامزد، به‌طور پیش‌فرض npm `latest` را به‌عنوان مبنای stable استفاده می‌کند. به‌صورت محلی با `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`، یا در GitHub با ورودی `update_baseline_version` گردش‌کار Install Smoke بازنویسی کنید. بررسی‌های نصب‌کننده غیر root، یک cache ایزوله npm نگه می‌دارند تا entryهای cache متعلق به root، رفتار نصب کاربر-محلی را پنهان نکنند. برای استفاده دوباره از cache مربوط به root/update/direct-npm در اجرای مجدد محلی، `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` را تنظیم کنید. -- CI مربوط به Install Smoke با `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` به‌روزرسانی تکراری direct-npm سراسری را رد می‌کند؛ وقتی پوشش مستقیم `npm install -g` لازم است، اسکریپت را به‌صورت محلی بدون آن env اجرا کنید. -- دودآزمون CLI حذف workspace مشترک عامل‌ها: `pnpm test:docker:agents-delete-shared-workspace` (اسکریپت: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) به‌طور پیش‌فرض تصویر Dockerfile ریشه را می‌سازد، دو عامل را با یک workspace در home ایزوله container seed می‌کند، `agents delete --json` را اجرا می‌کند، و JSON معتبر به‌همراه رفتار حفظ workspace را راستی‌آزمایی می‌کند. با `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` از تصویر install-smoke استفاده کنید. -- شبکه‌سازی Gateway (دو container، احراز هویت WS + health): `pnpm test:docker:gateway-network` (اسکریپت: `scripts/e2e/gateway-network-docker.sh`) -- دودآزمون snapshot مرورگر CDP: `pnpm test:docker:browser-cdp-snapshot` (اسکریپت: `scripts/e2e/browser-cdp-snapshot-docker.sh`) تصویر E2E منبع به‌همراه یک لایه Chromium را می‌سازد، Chromium را با CDP خام شروع می‌کند، `browser doctor --deep` را اجرا می‌کند، و راستی‌آزمایی می‌کند که snapshotهای نقش CDP شامل URLهای لینک، clickableهای ارتقایافته با cursor، ارجاع‌های iframe، و metadata فریم هستند. -- رگرسیون استدلال حداقلی OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (اسکریپت: `scripts/e2e/openai-web-search-minimal-docker.sh`) یک کارساز OpenAI شبیه‌سازی‌شده را از طریق Gateway اجرا می‌کند، راستی‌آزمایی می‌کند که `web_search` مقدار `reasoning.effort` را از `minimal` به `low` افزایش می‌دهد، سپس رد schema توسط provider را اجباری می‌کند و بررسی می‌کند که جزئیات خام در لاگ‌های Gateway ظاهر شده باشد. -- پل کانال MCP (Gateway seedشده + پل stdio + دودآزمون خام notification-frame مربوط به Claude): `pnpm test:docker:mcp-channels` (اسکریپت: `scripts/e2e/mcp-channels-docker.sh`) -- ابزارهای MCP بسته Pi (کارساز واقعی stdio MCP + دودآزمون allow/deny پروفایل Pi embedded): `pnpm test:docker:pi-bundle-mcp-tools` (اسکریپت: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- پاک‌سازی MCP مربوط به Cron/subagent (Gateway واقعی + teardown فرزند stdio MCP پس از اجرای cron ایزوله و subagent یک‌باره): `pnpm test:docker:cron-mcp-cleanup` (اسکریپت: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Pluginها (دودآزمون install/update برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، kitchen-sink مربوط به ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/inspect بسته Claude): `pnpm test:docker:plugins` (اسکریپت: `scripts/e2e/plugins-docker.sh`) - برای رد کردن بلوک ClawHub، `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید، یا جفت package/runtime پیش‌فرض kitchen-sink را با `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` و `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` بازنویسی کنید. بدون `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`، آزمون از یک کارساز fixture محلی hermetic مربوط به ClawHub استفاده می‌کند. -- دودآزمون بدون تغییر به‌روزرسانی Plugin: `pnpm test:docker:plugin-update` (اسکریپت: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- دودآزمون ماتریس چرخه عمر Plugin: `pnpm test:docker:plugin-lifecycle-matrix`، tarball بسته‌بندی‌شده OpenClaw را در یک container bare نصب می‌کند، یک Plugin مربوط به npm را نصب می‌کند، enable/disable را تغییر می‌دهد، آن را از طریق یک registry محلی npm ارتقا و تنزل می‌دهد، کد نصب‌شده را حذف می‌کند، سپس راستی‌آزمایی می‌کند که uninstall همچنان وضعیت کهنه را حذف می‌کند و هم‌زمان معیارهای RSS/CPU را برای هر فاز چرخه عمر ثبت می‌کند. -- دودآزمون metadata بارگذاری مجدد پیکربندی: `pnpm test:docker:config-reload` (اسکریپت: `scripts/e2e/config-reload-source-docker.sh`) -- Pluginها: `pnpm test:docker:plugins` دودآزمون install/update را برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، fixtureهای ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/inspect بسته Claude پوشش می‌دهد. `pnpm test:docker:plugin-update` رفتار update بدون تغییر برای Pluginهای نصب‌شده را پوشش می‌دهد. `pnpm test:docker:plugin-lifecycle-matrix` نصب، enable، disable، upgrade، downgrade، و uninstall در حالت نبود کد برای Plugin مربوط به npm با ردیابی منابع را پوشش می‌دهد. +- دودسنجی مشاهده‌پذیری: `pnpm qa:otel:smoke` یک مسیر خصوصی بررسی سورس QA است. عمداً بخشی از مسیرهای انتشار Docker بسته نیست، چون tarball مربوط به npm، QA Lab را حذف می‌کند. +- دودسنجی زنده Open WebUI: `pnpm test:docker:openwebui` (اسکریپت: `scripts/e2e/openwebui-docker.sh`) +- جادوگر onboarding (TTY، scaffold کامل): `pnpm test:docker:onboard` (اسکریپت: `scripts/e2e/onboard-docker.sh`) +- دودسنجی onboarding/کانال/عامل با tarball مربوط به npm: `pnpm test:docker:npm-onboard-channel-agent`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت global در Docker نصب می‌کند، OpenAI را از طریق onboarding مبتنی بر ارجاع env به‌همراه Telegram به‌صورت پیش‌فرض پیکربندی می‌کند، doctor را اجرا می‌کند، و یک نوبت عامل OpenAI شبیه‌سازی‌شده را اجرا می‌کند. یک tarball از پیش ساخته‌شده را با `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` دوباره استفاده کنید، بازسازی میزبان را با `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` رد کنید، یا کانال را با `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` یا `OPENCLAW_NPM_ONBOARD_CHANNEL=slack` تغییر دهید. +- دودسنجی تعویض کانال به‌روزرسانی: `pnpm test:docker:update-channel-switch`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت global در Docker نصب می‌کند، از package `stable` به git `dev` تغییر می‌دهد، کانال پایدارشده و کارکرد Plugin پس از به‌روزرسانی را تأیید می‌کند، سپس دوباره به package `stable` برمی‌گردد و وضعیت به‌روزرسانی را بررسی می‌کند. +- دودسنجی survivor ارتقا: `pnpm test:docker:upgrade-survivor`، tarball بسته‌بندی‌شده OpenClaw را روی یک fixture کاربر قدیمیِ کثیف با عامل‌ها، پیکربندی کانال، allowlistهای Plugin، وضعیت کهنه وابستگی Plugin، و فایل‌های workspace/session موجود نصب می‌کند. به‌روزرسانی بسته به‌همراه doctor غیرتعاملی را بدون کلیدهای ارائه‌دهنده زنده یا کانال اجرا می‌کند، سپس یک Gateway loopback را شروع می‌کند و حفظ پیکربندی/وضعیت به‌همراه بودجه‌های startup/status را بررسی می‌کند. +- دودسنجی survivor ارتقای منتشرشده: `pnpm test:docker:published-upgrade-survivor` به‌طور پیش‌فرض `openclaw@latest` را نصب می‌کند، فایل‌های واقع‌گرایانه کاربر موجود را seed می‌کند، آن baseline را با یک دستور پخته‌شده پیکربندی می‌کند، پیکربندی حاصل را اعتبارسنجی می‌کند، آن نصب منتشرشده را به tarball نامزد به‌روزرسانی می‌کند، doctor غیرتعاملی را اجرا می‌کند، `.artifacts/upgrade-survivor/summary.json` را می‌نویسد، سپس یک Gateway loopback را شروع می‌کند و intentهای پیکربندی‌شده، حفظ وضعیت، startup، `/healthz`، `/readyz`، و بودجه‌های وضعیت RPC را بررسی می‌کند. یک baseline را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` بازنویسی کنید، از زمان‌بند تجمیعی بخواهید baselineهای دقیق را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` مانند `all-since-2026.4.23` گسترش دهد، و fixtureهای شبیه issue را با `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` مانند `reported-issues` گسترش دهید؛ مجموعه reported-issues شامل `configured-plugin-installs` برای تعمیر خودکار نصب Plugin خارجی OpenClaw است. Package Acceptance این‌ها را به‌صورت `published_upgrade_survivor_baseline`، `published_upgrade_survivor_baselines` و `published_upgrade_survivor_scenarios` ارائه می‌کند؛ Full Release Validation از baseline پیش‌فرض latest در مسیر مسدودکننده استفاده می‌کند و فقط برای `run_release_soak=true` یا `release_profile=full` به all-since/reported-issues گسترش می‌دهد. +- دودسنجی context زمان اجرای session: `pnpm test:docker:session-runtime-context` پایداری رونوشت context زمان اجرای پنهان به‌همراه تعمیر doctor برای شاخه‌های تکراریِ prompt-rewrite تحت تأثیر را تأیید می‌کند. +- دودسنجی نصب global با Bun: `bash scripts/e2e/bun-global-install-smoke.sh` درخت فعلی را بسته‌بندی می‌کند، آن را با `bun install -g` در یک home ایزوله نصب می‌کند، و تأیید می‌کند که `openclaw infer image providers --json` به‌جای گیر کردن، ارائه‌دهندگان تصویر bundled را برمی‌گرداند. یک tarball از پیش ساخته‌شده را با `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` دوباره استفاده کنید، build میزبان را با `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` رد کنید، یا `dist/` را از یک image ساخته‌شده Docker با `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` کپی کنید. +- دودسنجی Docker نصب‌کننده: `bash scripts/test-install-sh-docker.sh` یک cache مشترک npm را بین containerهای root، update و direct-npm خود به‌اشتراک می‌گذارد. دودسنجی update به‌طور پیش‌فرض قبل از ارتقا به tarball نامزد، npm `latest` را به‌عنوان baseline stable استفاده می‌کند. به‌صورت محلی با `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` یا در GitHub با ورودی `update_baseline_version` در workflow نصب Smoke بازنویسی کنید. بررسی‌های نصب‌کننده غیر root یک cache ایزوله npm نگه می‌دارند تا entryهای cache متعلق به root رفتار نصب user-local را پنهان نکنند. برای استفاده دوباره از cache مربوط به root/update/direct-npm در اجرای مجدد محلی، `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` را تنظیم کنید. +- CI نصب Smoke، به‌روزرسانی global تکراری direct-npm را با `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` رد می‌کند؛ وقتی پوشش مستقیم `npm install -g` لازم است، اسکریپت را به‌صورت محلی بدون آن env اجرا کنید. +- دودسنجی CLI حذف workspace مشترک عامل‌ها: `pnpm test:docker:agents-delete-shared-workspace` (اسکریپت: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) به‌طور پیش‌فرض image Dockerfile ریشه را می‌سازد، دو عامل را با یک workspace در home ایزوله container seed می‌کند، `agents delete --json` را اجرا می‌کند، و JSON معتبر به‌همراه رفتار workspace حفظ‌شده را تأیید می‌کند. image install-smoke را با `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` دوباره استفاده کنید. +- شبکه‌سازی Gateway (دو container، احراز هویت WS + سلامت): `pnpm test:docker:gateway-network` (اسکریپت: `scripts/e2e/gateway-network-docker.sh`) +- دودسنجی snapshot مربوط به Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (اسکریپت: `scripts/e2e/browser-cdp-snapshot-docker.sh`) image سورس E2E به‌همراه یک لایه Chromium را می‌سازد، Chromium را با CDP خام شروع می‌کند، `browser doctor --deep` را اجرا می‌کند، و تأیید می‌کند که snapshotهای نقش CDP، URLهای لینک، clickables ارتقایافته توسط cursor، ارجاع‌های iframe، و metadata فریم را پوشش می‌دهند. +- رگرسیون استدلال حداقلی OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (اسکریپت: `scripts/e2e/openai-web-search-minimal-docker.sh`) یک سرور OpenAI شبیه‌سازی‌شده را از طریق Gateway اجرا می‌کند، تأیید می‌کند `web_search` مقدار `reasoning.effort` را از `minimal` به `low` افزایش می‌دهد، سپس رد schema ارائه‌دهنده را اجبار می‌کند و بررسی می‌کند جزئیات خام در logهای Gateway ظاهر می‌شود. +- bridge کانال MCP (Gateway seed شده + bridge stdio + دودسنجی frame اعلان خام Claude): `pnpm test:docker:mcp-channels` (اسکریپت: `scripts/e2e/mcp-channels-docker.sh`) +- ابزارهای MCP مربوط به bundle در Pi (سرور MCP واقعی stdio + دودسنجی allow/deny پروفایل Pi تعبیه‌شده): `pnpm test:docker:pi-bundle-mcp-tools` (اسکریپت: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- پاک‌سازی MCP مربوط به Cron/subagent (Gateway واقعی + teardown فرزند MCP stdio پس از اجرای cron ایزوله و subagent یک‌باره): `pnpm test:docker:cron-mcp-cleanup` (اسکریپت: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Pluginها (دودسنجی نصب/به‌روزرسانی برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist شده، refهای متحرک git، ClawHub kitchen-sink، به‌روزرسانی‌های marketplace، و فعال‌سازی/بازرسی bundle مربوط به Claude): `pnpm test:docker:plugins` (اسکریپت: `scripts/e2e/plugins-docker.sh`) + برای رد کردن بلوک ClawHub، `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید، یا زوج package/runtime پیش‌فرض kitchen-sink را با `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` و `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` بازنویسی کنید. بدون `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`، آزمون از یک سرور fixture محلی hermetic برای ClawHub استفاده می‌کند. +- دودسنجی بدون تغییر به‌روزرسانی Plugin: `pnpm test:docker:plugin-update` (اسکریپت: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- دودسنجی ماتریس چرخه عمر Plugin: `pnpm test:docker:plugin-lifecycle-matrix`، tarball بسته‌بندی‌شده OpenClaw را در یک container خالی نصب می‌کند، یک Plugin مربوط به npm را نصب می‌کند، enable/disable را toggle می‌کند، آن را از طریق یک registry محلی npm ارتقا و تنزل می‌دهد، کد نصب‌شده را حذف می‌کند، سپس تأیید می‌کند uninstall همچنان وضعیت stale را حذف می‌کند و در همان حال metricهای RSS/CPU را برای هر فاز چرخه عمر log می‌کند. +- دودسنجی metadata بازبارگذاری پیکربندی: `pnpm test:docker:config-reload` (اسکریپت: `scripts/e2e/config-reload-source-docker.sh`) +- Pluginها: `pnpm test:docker:plugins` دودسنجی نصب/به‌روزرسانی برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist شده، refهای متحرک git، fixtureهای ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/بازرسی bundle مربوط به Claude را پوشش می‌دهد. `pnpm test:docker:plugin-update` رفتار به‌روزرسانی بدون تغییر برای Pluginهای نصب‌شده را پوشش می‌دهد. `pnpm test:docker:plugin-lifecycle-matrix` نصب، enable، disable، upgrade، downgrade و uninstall در صورت نبود کد را برای Plugin مربوط به npm با ردیابی منابع پوشش می‌دهد. -برای پیش‌ساخت و استفاده دوباره دستی از تصویر کارکردی مشترک: +برای پیش‌ساخت و استفاده دوباره از image عملکردی مشترک به‌صورت دستی: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -بازنویسی‌های تصویر ویژه suite مانند `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` همچنان در صورت تنظیم، اولویت دارند. وقتی `OPENCLAW_SKIP_DOCKER_BUILD=1` به یک تصویر مشترک remote اشاره می‌کند، اگر از قبل local نباشد، اسکریپت‌ها آن را pull می‌کنند. آزمون‌های Docker مربوط به QR و نصب‌کننده، Dockerfileهای خودشان را نگه می‌دارند، چون رفتار package/install را اعتبارسنجی می‌کنند نه runtime برنامه ساخته‌شده مشترک. +بازنویسی‌های image ویژه suite مانند `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` همچنان در صورت تنظیم شدن اولویت دارند. وقتی `OPENCLAW_SKIP_DOCKER_BUILD=1` به یک image مشترک remote اشاره کند، اگر از قبل local نباشد، اسکریپت‌ها آن را pull می‌کنند. آزمون‌های Docker مربوط به QR و نصب‌کننده Dockerfileهای خودشان را نگه می‌دارند، چون به‌جای runtime برنامه ساخته‌شده مشترک، رفتار package/install را اعتبارسنجی می‌کنند. -اجراکننده‌های Docker مدل زنده همچنین checkout فعلی را به‌صورت read-only bind-mount می‌کنند و -آن را در یک workdir موقت داخل container stage می‌کنند. این کار runtime -image را سبک نگه می‌دارد، درحالی‌که همچنان Vitest را روی دقیقاً همان منبع/پیکربندی محلی شما اجرا می‌کند. -مرحله staging cacheهای بزرگ و فقط‌محلی و خروجی‌های build اپ مانند -`.pnpm-store`، `.worktrees`، `__openclaw_vitest__`، و دایرکتوری‌های خروجی `.build` محلی اپ یا +اجراکننده‌های Docker مدل زنده همچنین checkout فعلی را به‌صورت فقط‌خواندنی bind-mount می‌کنند و +آن را در یک workdir موقت داخل container آماده‌سازی می‌کنند. این کار image زمان اجرا را +کم‌حجم نگه می‌دارد و در عین حال Vitest را روی همان source/config محلی دقیق شما اجرا می‌کند. +مرحله آماده‌سازی cacheهای بزرگِ فقط محلی و خروجی‌های build برنامه، مانند +`.pnpm-store`، `.worktrees`، `__openclaw_vitest__` و دایرکتوری‌های خروجی `.build` محلی برنامه یا Gradle را رد می‌کند تا اجراهای زنده Docker چند دقیقه را صرف کپی کردن artifactهای مخصوص ماشین نکنند. -آن‌ها همچنین `OPENCLAW_SKIP_CHANNELS=1` را تنظیم می‌کنند تا probeهای زنده gateway -workerهای کانال واقعی Telegram/Discord/و غیره را داخل container شروع نکنند. -`test:docker:live-models` همچنان `pnpm test:live` را اجرا می‌کند، پس وقتی لازم است coverage زنده -gateway را از آن lane Docker محدود یا مستثنا کنید، `OPENCLAW_LIVE_GATEWAY_*` را نیز -pass through کنید. -`test:docker:openwebui` یک smoke سازگاری سطح‌بالاتر است: یک container -gateway OpenClaw را با endpointهای HTTP سازگار با OpenAI فعال‌شده شروع می‌کند، -یک container پین‌شده Open WebUI را در برابر آن gateway شروع می‌کند، از طریق -Open WebUI وارد می‌شود، بررسی می‌کند `/api/models` مدل `openclaw/default` را expose می‌کند، سپس یک +آن‌ها همچنین `OPENCLAW_SKIP_CHANNELS=1` را تنظیم می‌کنند تا probeهای زنده Gateway، +workerهای کانال واقعی Telegram/Discord/غیره را داخل container شروع نکنند. +`test:docker:live-models` همچنان `pnpm test:live` را اجرا می‌کند، بنابراین وقتی لازم است +پوشش زنده Gateway را از آن lane Docker محدود یا مستثنا کنید، `OPENCLAW_LIVE_GATEWAY_*` را نیز +عبور دهید. +`test:docker:openwebui` یک smoke سازگاری سطح‌بالاتر است: یک container Gateway +OpenClaw را با endpointهای HTTP سازگار با OpenAI فعال‌شده شروع می‌کند، +یک container Open WebUI pin‌شده را در برابر آن Gateway شروع می‌کند، از طریق +Open WebUI وارد می‌شود، بررسی می‌کند که `/api/models`، `openclaw/default` را expose می‌کند، سپس یک درخواست chat واقعی را از طریق proxy `/api/chat/completions` متعلق به Open WebUI ارسال می‌کند. -اجرای اول می‌تواند به‌طور محسوسی کندتر باشد، چون Docker ممکن است لازم باشد image -Open WebUI را pull کند و Open WebUI ممکن است لازم باشد setup شروع سرد خودش را تمام کند. -این lane انتظار یک key مدل زنده قابل‌استفاده دارد، و `OPENCLAW_PROFILE_FILE` -(به‌صورت پیش‌فرض `~/.profile`) روش اصلی برای فراهم کردن آن در اجراهای Dockerized است. +اجرای اول می‌تواند به‌طور محسوسی کندتر باشد، چون Docker ممکن است لازم داشته باشد image +Open WebUI را pull کند و Open WebUI ممکن است لازم داشته باشد راه‌اندازی سرد خودش را کامل کند. +این lane انتظار یک کلید مدل زنده قابل استفاده را دارد، و `OPENCLAW_PROFILE_FILE` +(به‌طور پیش‌فرض `~/.profile`) راه اصلی فراهم کردن آن در اجراهای Dockerized است. اجراهای موفق یک payload کوچک JSON مانند `{ "ok": true, "model": "openclaw/default", ... }` چاپ می‌کنند. -`test:docker:mcp-channels` عمداً deterministic است و به حساب واقعی -Telegram، Discord، یا iMessage نیاز ندارد. این lane یک container Gateway seed‌شده را boot می‌کند، -یک container دوم را شروع می‌کند که `openclaw mcp serve` را spawn می‌کند، سپس -کشف مکالمه routed، خواندن transcript، metadata پیوست، -رفتار live event queue، routing ارسال outbound، و اعلان‌های کانال + permission به سبک Claude را از طریق پل MCP واقعی stdio -بررسی می‌کند. بررسی اعلان، frameهای خام stdio MCP را مستقیماً inspect می‌کند تا smoke اعتبارسنجی کند که -bridge واقعاً چه چیزی emit می‌کند، نه فقط چیزی که یک SDK client خاص اتفاقاً surface می‌کند. -`test:docker:pi-bundle-mcp-tools` deterministic است و به key مدل زنده نیاز ندارد. -این lane image Docker repo را build می‌کند، یک probe server واقعی stdio MCP را -داخل container شروع می‌کند، آن server را از طریق runtime MCP bundle تعبیه‌شده Pi -materialize می‌کند، tool را اجرا می‌کند، سپس بررسی می‌کند `coding` و `messaging` -toolهای `bundle-mcp` را نگه می‌دارند درحالی‌که `minimal` و `tools.deny: ["bundle-mcp"]` آن‌ها را filter می‌کنند. -`test:docker:cron-mcp-cleanup` deterministic است و به key مدل زنده نیاز ندارد. -این lane یک Gateway seed‌شده را با یک probe server واقعی stdio MCP شروع می‌کند، یک -turn ایزوله cron و یک turn فرزند one-shot `/subagents spawn` را اجرا می‌کند، سپس بررسی می‌کند -process فرزند MCP پس از هر اجرا exit می‌کند. +`test:docker:mcp-channels` عمداً deterministic است و به یک حساب واقعی +Telegram، Discord، یا iMessage نیاز ندارد. یک container Gateway با داده seeded را boot می‌کند، +container دومی را شروع می‌کند که `openclaw mcp serve` را spawn می‌کند، سپس +کشف مکالمه routed، خواندن transcriptها، metadata پیوست‌ها، +رفتار صف رویداد زنده، مسیریابی ارسال outbound، و اعلان‌های کانال + permission به سبک Claude را روی bridge واقعی stdio MCP بررسی می‌کند. بررسی اعلان +frameهای خام stdio MCP را مستقیماً inspect می‌کند تا smoke همان چیزی را validate کند که +bridge واقعاً emit می‌کند، نه فقط چیزی را که یک client SDK مشخص اتفاقاً surface می‌کند. +`test:docker:pi-bundle-mcp-tools` deterministic است و به کلید مدل زنده نیاز ندارد. +image Docker repo را build می‌کند، یک server probe واقعی stdio MCP را +داخل container شروع می‌کند، آن server را از طریق runtime داخلی Pi bundle +MCP materialize می‌کند، tool را اجرا می‌کند، سپس بررسی می‌کند که `coding` و `messaging`، +toolهای `bundle-mcp` را نگه می‌دارند در حالی که `minimal` و `tools.deny: ["bundle-mcp"]` آن‌ها را فیلتر می‌کنند. +`test:docker:cron-mcp-cleanup` deterministic است و به کلید مدل زنده نیاز ندارد. +یک Gateway seeded با یک server probe واقعی stdio MCP را شروع می‌کند، یک +turn ایزوله cron و یک turn child یک‌باره `/subagents spawn` را اجرا می‌کند، سپس بررسی می‌کند +process child متعلق به MCP پس از هر اجرا خارج می‌شود. -smoke دستی thread زبان ساده ACP (نه CI): +smoke دستی رشته ACP با زبان ساده (نه CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- این script را برای workflowهای regression/debug نگه دارید. ممکن است دوباره برای اعتبارسنجی routing thread ACP لازم شود، پس آن را حذف نکنید. +- این script را برای workflowهای regression/debug نگه دارید. ممکن است دوباره برای اعتبارسنجی routing رشته ACP لازم شود، پس آن را حذف نکنید. env varهای مفید: - `OPENCLAW_CONFIG_DIR=...` (پیش‌فرض: `~/.openclaw`) که روی `/home/node/.openclaw` mount می‌شود - `OPENCLAW_WORKSPACE_DIR=...` (پیش‌فرض: `~/.openclaw/workspace`) که روی `/home/node/.openclaw/workspace` mount می‌شود - `OPENCLAW_PROFILE_FILE=...` (پیش‌فرض: `~/.profile`) که روی `/home/node/.profile` mount می‌شود و پیش از اجرای testها source می‌شود -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` برای بررسی فقط env varهایی که از `OPENCLAW_PROFILE_FILE` source شده‌اند، با استفاده از دایرکتوری‌های موقت config/workspace و بدون mountهای auth خارجی CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (پیش‌فرض: `~/.cache/openclaw/docker-cli-tools`) که برای نصب‌های CLI cache‌شده داخل Docker روی `/home/node/.npm-global` mount می‌شود -- دایرکتوری‌ها/فایل‌های auth خارجی CLI زیر `$HOME` به‌صورت read-only زیر `/host-auth...` mount می‌شوند، سپس پیش از شروع testها در `/home/node/...` کپی می‌شوند +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` برای بررسی فقط env varهایی که از `OPENCLAW_PROFILE_FILE` source شده‌اند، با استفاده از دایرکتوری‌های config/workspace موقت و بدون mountهای auth خارجی CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (پیش‌فرض: `~/.cache/openclaw/docker-cli-tools`) که برای installهای cache‌شده CLI داخل Docker روی `/home/node/.npm-global` mount می‌شود +- دایرکتوری‌ها/فایل‌های auth خارجی CLI زیر `$HOME` به‌صورت فقط‌خواندنی زیر `/host-auth...` mount می‌شوند، سپس پیش از شروع testها داخل `/home/node/...` کپی می‌شوند - دایرکتوری‌های پیش‌فرض: `.minimax` - فایل‌های پیش‌فرض: `~/.codex/auth.json`، `~/.codex/config.toml`، `.claude.json`، `~/.claude/.credentials.json`، `~/.claude/settings.json`، `~/.claude/settings.local.json` - - اجراهای provider محدودشده فقط دایرکتوری‌ها/فایل‌های لازم استنباط‌شده از `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` را mount می‌کنند - - override دستی با `OPENCLAW_DOCKER_AUTH_DIRS=all`، `OPENCLAW_DOCKER_AUTH_DIRS=none`، یا یک comma list مانند `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - اجراهای provider محدودشده فقط دایرکتوری‌ها/فایل‌های لازم را که از `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` استنتاج شده‌اند mount می‌کنند + - با `OPENCLAW_DOCKER_AUTH_DIRS=all`، `OPENCLAW_DOCKER_AUTH_DIRS=none`، یا یک فهرست comma مثل `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` به‌صورت دستی override کنید - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` برای محدود کردن اجرا -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` برای filter کردن providerها داخل container -- `OPENCLAW_SKIP_DOCKER_BUILD=1` برای reuse کردن image موجود `openclaw:local-live` برای rerunهایی که به rebuild نیاز ندارند -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` برای اطمینان از اینکه creds از profile store می‌آیند (نه env) -- `OPENCLAW_OPENWEBUI_MODEL=...` برای انتخاب مدلی که gateway برای smoke Open WebUI expose می‌کند -- `OPENCLAW_OPENWEBUI_PROMPT=...` برای override کردن prompt nonce-check استفاده‌شده توسط smoke Open WebUI -- `OPENWEBUI_IMAGE=...` برای override کردن tag image پین‌شده Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` برای فیلتر کردن providerها درون container +- `OPENCLAW_SKIP_DOCKER_BUILD=1` برای استفاده مجدد از image موجود `openclaw:local-live` در اجرای دوباره‌ای که به rebuild نیاز ندارد +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` برای اطمینان از اینکه credentialها از profile store می‌آیند (نه env) +- `OPENCLAW_OPENWEBUI_MODEL=...` برای انتخاب مدلی که Gateway برای smoke Open WebUI expose می‌کند +- `OPENCLAW_OPENWEBUI_PROMPT=...` برای override کردن prompt بررسی nonce که توسط smoke Open WebUI استفاده می‌شود +- `OPENWEBUI_IMAGE=...` برای override کردن tag image pin‌شده Open WebUI -## sanity اسناد +## صحت‌سنجی مستندات -پس از ویرایش اسناد، checkهای اسناد را اجرا کنید: `pnpm check:docs`. -وقتی به checkهای heading درون صفحه هم نیاز دارید، اعتبارسنجی کامل anchor در Mintlify را اجرا کنید: `pnpm docs:check-links:anchors`. +پس از ویرایش مستندات، checkهای docs را اجرا کنید: `pnpm check:docs`. +وقتی به بررسی headingهای درون‌صفحه‌ای هم نیاز دارید، validation کامل anchorهای Mintlify را اجرا کنید: `pnpm docs:check-links:anchors`. ## regression آفلاین (CI-safe) این‌ها regressionهای «pipeline واقعی» بدون providerهای واقعی هستند: -- فراخوانی tool در Gateway (mock OpenAI، gateway واقعی + agent loop): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- wizard Gateway (WS `wizard.start`/`wizard.next`، نوشتن config + auth enforced): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") +- tool calling مربوط به Gateway (OpenAI mock، Gateway واقعی + loop عامل): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- wizard مربوط به Gateway (WS `wizard.start`/`wizard.next`، نوشتن config + auth enforced): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") -## evalهای قابلیت‌اعتماد agent (skills) +## ارزیابی‌های قابلیت اعتماد عامل (Skills) -ما از قبل چند test CI-safe داریم که مانند «evalهای قابلیت‌اعتماد agent» رفتار می‌کنند: +ما از قبل چند test CI-safe داریم که مثل «ارزیابی‌های قابلیت اعتماد عامل» رفتار می‌کنند: -- فراخوانی mock tool از طریق gateway واقعی + agent loop (`src/gateway/gateway.test.ts`). -- جریان‌های wizard end-to-end که wiring session و اثرات config را اعتبارسنجی می‌کنند (`src/gateway/gateway.test.ts`). +- tool-calling mock از طریق Gateway واقعی + loop عامل (`src/gateway/gateway.test.ts`). +- flowهای wizard انتهابه‌انتها که wiring session و اثرهای config را validate می‌کنند (`src/gateway/gateway.test.ts`). -چیزی که هنوز برای skills کم است (ببینید [Skills](/fa/tools/skills)): +چیزی که هنوز برای Skills کم است (ببینید [Skills](/fa/tools/skills)): -- **تصمیم‌گیری:** وقتی skillها در prompt فهرست شده‌اند، آیا agent skill درست را انتخاب می‌کند (یا از موارد نامرتبط اجتناب می‌کند)؟ -- **انطباق:** آیا agent پیش از استفاده `SKILL.md` را می‌خواند و stepها/argهای الزامی را دنبال می‌کند؟ -- **قراردادهای workflow:** سناریوهای multi-turn که ترتیب tool، carryover تاریخچه session، و boundaryهای sandbox را assert می‌کنند. +- **تصمیم‌گیری:** وقتی skills در prompt فهرست شده‌اند، آیا عامل skill درست را انتخاب می‌کند (یا از موارد نامرتبط پرهیز می‌کند)؟ +- **تطابق:** آیا عامل پیش از استفاده `SKILL.md` را می‌خواند و steps/args لازم را دنبال می‌کند؟ +- **قراردادهای workflow:** سناریوهای چند-turn که ترتیب tool، carryover تاریخچه session، و boundaryهای sandbox را assert می‌کنند. -evalهای آینده باید ابتدا deterministic بمانند: +ارزیابی‌های آینده باید اول deterministic بمانند: - یک scenario runner با استفاده از providerهای mock برای assert کردن tool callها + ترتیب، خواندن فایل skill، و wiring session. - یک suite کوچک از سناریوهای متمرکز بر skill (استفاده در برابر اجتناب، gating، prompt injection). -- evalهای زنده اختیاری (opt-in، env-gated) فقط پس از آماده شدن suite CI-safe. +- ارزیابی‌های زنده اختیاری (opt-in، env-gated) فقط پس از آماده شدن suite CI-safe. -## testهای قرارداد (شکل plugin و channel) +## آزمون‌های قرارداد (شکل Plugin و کانال) -testهای قرارداد بررسی می‌کنند که هر plugin و channel ثبت‌شده با -قرارداد interface خودش مطابقت دارد. آن‌ها روی همه pluginهای کشف‌شده iterate می‌کنند و یک suite از +آزمون‌های قرارداد بررسی می‌کنند که هر Plugin و کانال ثبت‌شده با +قرارداد interface خودش منطبق است. آن‌ها روی همه Pluginهای کشف‌شده iterate می‌کنند و یک suite از assertionهای شکل و رفتار را اجرا می‌کنند. lane واحد پیش‌فرض `pnpm test` عمداً -این فایل‌های seam و smoke مشترک را skip می‌کند؛ وقتی سطح‌های channel یا provider مشترک را touch می‌کنید، -commandهای قرارداد را صراحتاً اجرا کنید. +این فایل‌های seam مشترک و smoke را رد می‌کند؛ وقتی سطح‌های مشترک کانال یا provider را لمس می‌کنید، +دستورهای contract را صریح اجرا کنید. -### Commandها +### دستورها - همه قراردادها: `pnpm test:contracts` -- فقط قراردادهای channel: `pnpm test:contracts:channels` +- فقط قراردادهای کانال: `pnpm test:contracts:channels` - فقط قراردادهای provider: `pnpm test:contracts:plugins` -### قراردادهای channel +### قراردادهای کانال در `src/channels/plugins/contracts/*.contract.test.ts` قرار دارند: -- **plugin** - شکل پایه plugin (id، name، capabilities) -- **setup** - قرارداد setup wizard -- **session-binding** - رفتار session binding +- **Plugin** - شکل پایه Plugin (id، name، capabilities) +- **setup** - قرارداد wizard راه‌اندازی +- **session-binding** - رفتار binding session - **outbound-payload** - ساختار payload پیام -- **inbound** - handling پیام inbound +- **inbound** - مدیریت پیام inbound - **actions** - handlerهای action کانال -- **threading** - handling Thread ID -- **directory** - API directory/roster -- **group-policy** - enforcement سیاست group +- **threading** - مدیریت thread ID +- **directory** - API دایرکتوری/roster +- **group-policy** - اعمال policy گروه ### قراردادهای status provider در `src/plugins/contracts/*.contract.test.ts` قرار دارند. -- **status** - probeهای status channel -- **registry** - شکل registry plugin +- **status** - probeهای status کانال +- **registry** - شکل registry Plugin ### قراردادهای provider در `src/plugins/contracts/*.contract.test.ts` قرار دارند: -- **auth** - قرارداد جریان auth -- **auth-choice** - انتخاب/گزینش auth +- **auth** - قرارداد flow احراز هویت +- **auth-choice** - انتخاب/گزینش احراز هویت - **catalog** - API catalog مدل - **discovery** - کشف Plugin -- **loader** - loading Plugin +- **loader** - بارگذاری Plugin - **runtime** - runtime provider - **shape** - شکل/interface Plugin -- **wizard** - Setup wizard +- **wizard** - wizard راه‌اندازی ### زمان اجرا - پس از تغییر exportها یا subpathهای plugin-sdk -- پس از افزودن یا تغییر یک channel یا provider plugin -- پس از refactor کردن registration یا discovery plugin +- پس از افزودن یا تغییر یک کانال یا provider Plugin +- پس از refactor کردن registration یا discovery مربوط به Plugin -testهای قرارداد در CI اجرا می‌شوند و به keyهای واقعی API نیاز ندارند. +آزمون‌های قرارداد در CI اجرا می‌شوند و به کلیدهای واقعی API نیاز ندارند. ## افزودن regressionها (راهنما) -وقتی issue مربوط به provider/model را که در live کشف شده fix می‌کنید: +وقتی یک issue مربوط به provider/model را که در live کشف شده fix می‌کنید: -- در صورت امکان یک regression CI-safe اضافه کنید (provider mock/stub، یا capture کردن transformation دقیق request-shape) -- اگر ذاتاً فقط live است (rate limitها، policyهای auth)، test زنده را محدود و opt-in از طریق env varها نگه دارید -- ترجیح دهید کوچک‌ترین layer را هدف بگیرید که bug را catch می‌کند: - - bug تبدیل/replay درخواست provider → test مستقیم models - - bug pipeline session/history/tool gateway → smoke زنده gateway یا test mock gateway CI-safe +- اگر ممکن است یک regression CI-safe اضافه کنید (provider mock/stub، یا capture کردن transformation دقیق request-shape) +- اگر ذاتاً فقط live است (rate limitها، policyهای auth)، test زنده را محدود و از طریق env varها opt-in نگه دارید +- کوچک‌ترین لایه‌ای را هدف بگیرید که bug را می‌گیرد: + - bug تبدیل/بازپخش request provider → test مستقیم models + - bug مربوط به pipeline Gateway session/history/tool → smoke زنده Gateway یا test mock CI-safe برای Gateway - guardrail پیمایش SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` یک target نمونه برای هر class از SecretRef را از metadata registry (`listSecretTargetRegistryEntries()`) derive می‌کند، سپس assert می‌کند exec idهای traversal-segment رد می‌شوند. - - اگر یک target family جدید SecretRef با `includeInPlan` در `src/secrets/target-registry-data.ts` اضافه می‌کنید، `classifyTargetClass` را در آن test update کنید. این test عمداً روی target idهای unclassified fail می‌شود تا classهای جدید نتوانند بی‌صدا skip شوند. + - `src/secrets/exec-secret-ref-id-parity.test.ts` از metadata registry (`listSecretTargetRegistryEntries()`) برای هر class از SecretRef یک target نمونه derive می‌کند، سپس assert می‌کند که exec idهای دارای traversal-segment رد می‌شوند. + - اگر یک خانواده target جدید `includeInPlan` برای SecretRef در `src/secrets/target-registry-data.ts` اضافه می‌کنید، `classifyTargetClass` را در آن test به‌روزرسانی کنید. این test عمداً روی target idهای class‌بندی‌نشده fail می‌شود تا classهای جدید بی‌صدا skip نشوند. ## مرتبط -- [Testing live](/fa/help/testing-live) -- [Testing updates and plugins](/fa/help/testing-updates-plugins) +- [آزمون زنده](/fa/help/testing-live) +- [آزمون updateها و Pluginها](/fa/help/testing-updates-plugins) - [CI](/fa/ci) diff --git a/docs/fa/plugins/bundles.md b/docs/fa/plugins/bundles.md index 8533db2ec..fe4bbb967 100644 --- a/docs/fa/plugins/bundles.md +++ b/docs/fa/plugins/bundles.md @@ -2,40 +2,32 @@ read_when: - می‌خواهید یک بستهٔ سازگار با Codex، Claude یا Cursor نصب کنید - باید بدانید OpenClaw چگونه محتوای باندل را به قابلیت‌های بومی نگاشت می‌کند - - شما در حال اشکال‌زداییِ تشخیص بسته یا توانمندی‌های مفقود هستید -summary: بسته‌های Codex، Claude و Cursor را به‌عنوان Pluginهای OpenClaw نصب کنید و به کار ببرید + - در حال اشکال‌زداییِ تشخیص باندل یا قابلیت‌های مفقود هستید +summary: بسته‌های Codex، Claude و Cursor را به‌عنوان Plugin‌های OpenClaw نصب کنید و به کار ببرید title: بسته‌های Plugin x-i18n: - generated_at: "2026-05-02T11:53:39Z" + generated_at: "2026-05-05T01:49:33Z" model: gpt-5.5 provider: openai - source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4 + source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157 source_path: plugins/bundles.md workflow: 16 --- -OpenClaw می‌تواند Pluginها را از سه زیست‌بوم خارجی نصب کند: **Codex**، **Claude**، -و **Cursor**. به این‌ها **بسته‌ها** گفته می‌شود — بسته‌های محتوا و فراداده که -OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills، هوک‌ها، و ابزارهای MCP نگاشت می‌کند. +OpenClaw می‌تواند Pluginها را از سه اکوسیستم خارجی نصب کند: **Codex**، **Claude** و **Cursor**. به این‌ها **باندل‌ها** گفته می‌شود، یعنی بسته‌های محتوا و فراداده‌ای که OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills، hookها و ابزارهای MCP نگاشت می‌کند. - بسته‌ها با Pluginهای بومی OpenClaw یکسان نیستند. Pluginهای بومی - درون‌فرایندی اجرا می‌شوند و می‌توانند هر قابلیتی را ثبت کنند. بسته‌ها بسته‌های محتوایی با - نگاشت انتخابی قابلیت‌ها و مرز اعتماد محدودتر هستند. + باندل‌ها همان Pluginهای بومی OpenClaw **نیستند**. Pluginهای بومی درون پردازش اجرا می‌شوند و می‌توانند هر قابلیتی را ثبت کنند. باندل‌ها بسته‌های محتوا هستند با نگاشت گزینشی قابلیت‌ها و مرز اعتماد محدودتر. -## چرا بسته‌ها وجود دارند +## چرا باندل‌ها وجود دارند -بسیاری از Pluginهای مفید در قالب Codex، Claude، یا Cursor منتشر می‌شوند. به‌جای -اینکه نویسندگان مجبور شوند آن‌ها را به‌صورت Pluginهای بومی OpenClaw بازنویسی کنند، OpenClaw -این قالب‌ها را تشخیص می‌دهد و محتوای پشتیبانی‌شده آن‌ها را به مجموعه قابلیت‌های بومی -نگاشت می‌کند. این یعنی می‌توانید یک بسته فرمان Claude یا یک بسته Skills مربوط به Codex را نصب کنید -و بی‌درنگ از آن استفاده کنید. +بسیاری از Pluginهای مفید در قالب Codex، Claude یا Cursor منتشر می‌شوند. OpenClaw به‌جای اینکه از نویسندگان بخواهد آن‌ها را به‌صورت Pluginهای بومی OpenClaw بازنویسی کنند، این قالب‌ها را تشخیص می‌دهد و محتوای پشتیبانی‌شده آن‌ها را به مجموعه قابلیت‌های بومی نگاشت می‌کند. یعنی می‌توانید یک بسته فرمان Claude یا یک باندل Skill برای Codex را نصب کنید و بلافاصله از آن استفاده کنید. -## نصب یک بسته +## نصب یک باندل - + ```bash # Local directory openclaw plugins install ./my-bundle @@ -56,71 +48,63 @@ OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills openclaw plugins inspect ``` - بسته‌ها به‌صورت `Format: bundle` با زیرنوع `codex`، `claude`، یا `cursor` نمایش داده می‌شوند. + باندل‌ها با `Format: bundle` و یک زیرنوع از `codex`، `claude` یا `cursor` نمایش داده می‌شوند. - + ```bash openclaw gateway restart ``` - قابلیت‌های نگاشت‌شده (Skills، هوک‌ها، ابزارهای MCP، پیش‌فرض‌های LSP) در نشست بعدی در دسترس هستند. + قابلیت‌های نگاشت‌شده (Skills، hookها، ابزارهای MCP، پیش‌فرض‌های LSP) در نشست بعدی در دسترس هستند. -## OpenClaw چه چیزهایی را از بسته‌ها نگاشت می‌کند +## OpenClaw چه چیزهایی را از باندل‌ها نگاشت می‌کند -امروز همه قابلیت‌های بسته‌ها در OpenClaw اجرا نمی‌شوند. در اینجا آمده است چه چیزهایی کار می‌کنند و چه چیزهایی -تشخیص داده می‌شوند اما هنوز متصل نشده‌اند. +امروز همه قابلیت‌های باندل در OpenClaw اجرا نمی‌شوند. اینجا آمده که چه چیزهایی کار می‌کنند و چه چیزهایی تشخیص داده می‌شوند اما هنوز متصل نشده‌اند. -### اکنون پشتیبانی می‌شود +### در حال حاضر پشتیبانی می‌شود -| قابلیت | نحوه نگاشت | اعمال‌شونده به | +| قابلیت | نحوه نگاشت | قابل اعمال به | | ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| محتوای Skill | ریشه‌های Skill بسته به‌صورت Skills معمول OpenClaw بارگذاری می‌شوند | همه قالب‌ها | +| محتوای Skill | ریشه‌های Skill باندل مانند Skills عادی OpenClaw بارگذاری می‌شوند | همه قالب‌ها | | فرمان‌ها | `commands/` و `.cursor/commands/` به‌عنوان ریشه‌های Skill در نظر گرفته می‌شوند | Claude، Cursor | -| بسته‌های هوک | چیدمان‌های OpenClaw-مانند `HOOK.md` + `handler.ts` | Codex | -| ابزارهای MCP | پیکربندی MCP بسته در تنظیمات Pi تعبیه‌شده ادغام می‌شود؛ سرورهای stdio و HTTP پشتیبانی‌شده بارگذاری می‌شوند | همه قالب‌ها | -| سرورهای LSP | فایل `.lsp.json` مربوط به Claude و `lspServers` اعلام‌شده در مانیفست در پیش‌فرض‌های LSP مربوط به Pi تعبیه‌شده ادغام می‌شوند | Claude | -| تنظیمات | فایل `settings.json` مربوط به Claude به‌عنوان پیش‌فرض‌های Pi تعبیه‌شده وارد می‌شود | Claude | +| بسته‌های hook | چیدمان‌های سبک OpenClaw شامل `HOOK.md` + `handler.ts` | Codex | +| ابزارهای MCP | پیکربندی MCP باندل در تنظیمات Pi تعبیه‌شده ادغام می‌شود؛ سرورهای stdio و HTTP پشتیبانی‌شده بارگذاری می‌شوند | همه قالب‌ها | +| سرورهای LSP | فایل Claude `.lsp.json` و `lspServers` اعلام‌شده در manifest در پیش‌فرض‌های LSP برای Pi تعبیه‌شده ادغام می‌شوند | Claude | +| تنظیمات | فایل Claude `settings.json` به‌عنوان پیش‌فرض‌های Pi تعبیه‌شده وارد می‌شود | Claude | #### محتوای Skill -- ریشه‌های Skill بسته به‌صورت ریشه‌های Skill معمول OpenClaw بارگذاری می‌شوند -- ریشه‌های `commands` مربوط به Claude به‌عنوان ریشه‌های Skill اضافه در نظر گرفته می‌شوند -- ریشه‌های `.cursor/commands` مربوط به Cursor به‌عنوان ریشه‌های Skill اضافه در نظر گرفته می‌شوند +- ریشه‌های Skill باندل مانند ریشه‌های Skill عادی OpenClaw بارگذاری می‌شوند +- ریشه‌های Claude `commands` به‌عنوان ریشه‌های Skill اضافی در نظر گرفته می‌شوند +- ریشه‌های Cursor `.cursor/commands` به‌عنوان ریشه‌های Skill اضافی در نظر گرفته می‌شوند -این یعنی فایل‌های فرمان markdown مربوط به Claude از طریق بارگذار عادی Skill در OpenClaw -کار می‌کنند. markdown فرمان Cursor نیز از همین مسیر کار می‌کند. +یعنی فایل‌های فرمان markdown مربوط به Claude از مسیر بارگذار عادی Skill در OpenClaw کار می‌کنند. markdown فرمان‌های Cursor نیز از همان مسیر کار می‌کند. -#### بسته‌های هوک +#### بسته‌های hook -- ریشه‌های هوک بسته‌ها **فقط** زمانی کار می‌کنند که از چیدمان عادی بسته هوک - OpenClaw استفاده کنند. امروز این عمدتاً حالت سازگار با Codex است: +- ریشه‌های hook باندل **فقط** زمانی کار می‌کنند که از چیدمان عادی بسته hook در OpenClaw استفاده کنند. امروز این عمدتاً حالت سازگار با Codex است: - `HOOK.md` - `handler.ts` یا `handler.js` #### MCP برای Pi -- بسته‌های فعال‌شده می‌توانند پیکربندی سرور MCP را فراهم کنند -- OpenClaw پیکربندی MCP بسته را به‌عنوان - `mcpServers` در تنظیمات مؤثر Pi تعبیه‌شده ادغام می‌کند -- OpenClaw ابزارهای MCP پشتیبانی‌شده بسته را هنگام نوبت‌های عامل Pi تعبیه‌شده با - راه‌اندازی سرورهای stdio یا اتصال به سرورهای HTTP ارائه می‌کند -- پروفایل‌های ابزار `coding` و `messaging` به‌صورت پیش‌فرض ابزارهای MCP بسته را شامل می‌شوند؛ - برای انصراف برای یک عامل یا Gateway از `tools.deny: ["bundle-mcp"]` استفاده کنید -- تنظیمات Pi محلی پروژه همچنان پس از پیش‌فرض‌های بسته اعمال می‌شوند، بنابراین تنظیمات - فضای کاری می‌توانند در صورت نیاز ورودی‌های MCP بسته را بازنویسی کنند -- کاتالوگ‌های ابزار MCP بسته پیش از ثبت، به‌صورت قطعی مرتب می‌شوند، بنابراین - تغییر ترتیب `listTools()` بالادستی باعث نوسان بلوک‌های ابزار در کش پرامپت نمی‌شود +- باندل‌های فعال می‌توانند در پیکربندی سرور MCP مشارکت کنند +- OpenClaw پیکربندی MCP باندل را به‌عنوان `mcpServers` در تنظیمات مؤثر Pi تعبیه‌شده ادغام می‌کند +- OpenClaw ابزارهای MCP پشتیبانی‌شده باندل را در طول نوبت‌های عامل Pi تعبیه‌شده، با راه‌اندازی سرورهای stdio یا اتصال به سرورهای HTTP، ارائه می‌کند +- پروفایل‌های ابزار `coding` و `messaging` به‌صورت پیش‌فرض شامل ابزارهای MCP باندل هستند؛ برای انصراف یک عامل یا Gateway از `tools.deny: ["bundle-mcp"]` استفاده کنید +- تنظیمات Pi محلی پروژه همچنان پس از پیش‌فرض‌های باندل اعمال می‌شوند، بنابراین تنظیمات workspace می‌توانند در صورت نیاز ورودی‌های MCP باندل را بازنویسی کنند +- کاتالوگ‌های ابزار MCP باندل پیش از ثبت، به‌صورت قطعی مرتب می‌شوند، بنابراین تغییر ترتیب `listTools()` در بالادست، بلوک‌های ابزار prompt-cache را بی‌ثبات نمی‌کند -##### ترابردها +##### انتقال‌ها -سرورهای MCP می‌توانند از ترابرد stdio یا HTTP استفاده کنند: +سرورهای MCP می‌توانند از انتقال stdio یا HTTP استفاده کنند: -**Stdio** یک فرایند فرزند را راه‌اندازی می‌کند: +**Stdio** یک فرایند فرزند راه‌اندازی می‌کند: ```json { @@ -136,7 +120,7 @@ OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills } ``` -**HTTP** به‌صورت پیش‌فرض از طریق `sse`، یا در صورت درخواست با `streamable-http`، به یک سرور MCP در حال اجرا متصل می‌شود: +**HTTP** به‌صورت پیش‌فرض از طریق `sse` به یک سرور MCP در حال اجرا وصل می‌شود، یا وقتی درخواست شده باشد از `streamable-http` استفاده می‌کند: ```json { @@ -156,155 +140,133 @@ OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills ``` - `transport` می‌تواند روی `"streamable-http"` یا `"sse"` تنظیم شود؛ وقتی حذف شود، OpenClaw از `sse` استفاده می‌کند -- `type: "http"` یک شکل پایین‌دستی بومی CLI است؛ در پیکربندی OpenClaw از `transport: "streamable-http"` استفاده کنید. `openclaw mcp set` و `openclaw doctor --fix` نام مستعار رایج را نرمال می‌کنند. +- `type: "http"` یک شکل پایین‌دستی بومی CLI است؛ در پیکربندی OpenClaw از `transport: "streamable-http"` استفاده کنید. `openclaw mcp set` و `openclaw doctor --fix` نام مستعار رایج را نرمال‌سازی می‌کنند. - فقط طرح‌های URL با `http:` و `https:` مجاز هستند -- مقادیر `headers` از درون‌یابی `${ENV_VAR}` پشتیبانی می‌کنند +- مقدارهای `headers` از درون‌یابی `${ENV_VAR}` پشتیبانی می‌کنند - ورودی سروری که هم `command` و هم `url` داشته باشد رد می‌شود -- اعتبارنامه‌های URL (userinfo و پارامترهای query) از توضیحات ابزار - و لاگ‌ها حذف می‌شوند -- `connectionTimeoutMs` زمان انتظار اتصال پیش‌فرض ۳۰ ثانیه‌ای را برای - هر دو ترابرد stdio و HTTP بازنویسی می‌کند +- اعتبارنامه‌های URL (userinfo و پارامترهای query) از توضیحات ابزار و logها حذف می‌شوند +- `connectionTimeoutMs` زمان انتظار اتصال پیش‌فرض ۳۰ ثانیه‌ای را برای هر دو انتقال stdio و HTTP بازنویسی می‌کند ##### نام‌گذاری ابزار -OpenClaw ابزارهای MCP بسته را با نام‌های امن برای ارائه‌دهنده در قالب -`serverName__toolName` ثبت می‌کند. برای نمونه، سروری با کلید `"vigil-harbor"` که یک -ابزار `memory_search` ارائه می‌کند، به‌صورت `vigil-harbor__memory_search` ثبت می‌شود. +OpenClaw ابزارهای MCP باندل را با نام‌های امن برای provider در قالب `serverName__toolName` ثبت می‌کند. برای مثال، سروری با کلید `"vigil-harbor"` که ابزار `memory_search` را ارائه می‌کند، با نام `vigil-harbor__memory_search` ثبت می‌شود. - نویسه‌های خارج از `A-Za-z0-9_-` با `-` جایگزین می‌شوند -- پیشوندهای سرور به ۳۰ نویسه محدود می‌شوند -- نام‌های کامل ابزار به ۶۴ نویسه محدود می‌شوند -- نام‌های خالی سرور به `mcp` بازمی‌گردند +- پیشوندهای سرور حداکثر ۳۰ نویسه هستند +- نام کامل ابزارها حداکثر ۶۴ نویسه است +- نام‌های خالی سرور به `mcp` برمی‌گردند - نام‌های پاک‌سازی‌شده متداخل با پسوندهای عددی متمایز می‌شوند -- ترتیب نهایی ابزارهای ارائه‌شده بر اساس نام امن قطعی است تا نوبت‌های تکراری Pi - از نظر کش پایدار بمانند -- فیلتر پروفایل همه ابزارهای یک سرور MCP بسته را به‌عنوان متعلق به Plugin - با کلید `bundle-mcp` در نظر می‌گیرد، بنابراین allowlistها و deny listهای پروفایل می‌توانند یا - نام‌های جداگانه ابزارهای ارائه‌شده یا کلید Plugin با نام `bundle-mcp` را شامل شوند +- ترتیب نهایی ابزارهای ارائه‌شده براساس نام امن قطعی است تا نوبت‌های تکراری Pi از نظر cache پایدار بمانند +- فیلتر کردن پروفایل، همه ابزارهای یک سرور MCP باندل را متعلق به Plugin با کلید `bundle-mcp` در نظر می‌گیرد، بنابراین allowlistها و deny listهای پروفایل می‌توانند نام‌های منفرد ابزار ارائه‌شده یا کلید Plugin یعنی `bundle-mcp` را شامل شوند #### تنظیمات Pi تعبیه‌شده -- فایل `settings.json` مربوط به Claude هنگامی که بسته فعال باشد به‌عنوان تنظیمات پیش‌فرض Pi تعبیه‌شده - وارد می‌شود -- OpenClaw پیش از اعمال کلیدهای override پوسته، آن‌ها را پاک‌سازی می‌کند +- فایل Claude `settings.json` وقتی باندل فعال باشد، به‌عنوان تنظیمات پیش‌فرض Pi تعبیه‌شده وارد می‌شود +- OpenClaw کلیدهای بازنویسی shell را پیش از اعمال پاک‌سازی می‌کند کلیدهای پاک‌سازی‌شده: - `shellPath` - `shellCommandPrefix` -#### LSP مربوط به Pi تعبیه‌شده +#### LSP برای Pi تعبیه‌شده -- بسته‌های Claude فعال‌شده می‌توانند پیکربندی سرور LSP را فراهم کنند -- OpenClaw فایل `.lsp.json` به‌همراه هر مسیر `lspServers` اعلام‌شده در مانیفست را بارگذاری می‌کند -- پیکربندی LSP بسته در پیش‌فرض‌های مؤثر LSP مربوط به Pi تعبیه‌شده ادغام می‌شود -- امروز فقط سرورهای LSP پشتیبانی‌شده با پشتوانه stdio قابل اجرا هستند؛ ترابردهای - پشتیبانی‌نشده همچنان در `openclaw plugins inspect ` نمایش داده می‌شوند +- باندل‌های فعال Claude می‌توانند در پیکربندی سرور LSP مشارکت کنند +- OpenClaw فایل `.lsp.json` به‌علاوه هر مسیر `lspServers` اعلام‌شده در manifest را بارگذاری می‌کند +- پیکربندی LSP باندل در پیش‌فرض‌های مؤثر LSP برای Pi تعبیه‌شده ادغام می‌شود +- امروز فقط سرورهای LSP پشتیبانی‌شده مبتنی بر stdio قابل اجرا هستند؛ انتقال‌های پشتیبانی‌نشده همچنان در `openclaw plugins inspect ` نمایش داده می‌شوند -### تشخیص داده شده اما اجرا نمی‌شود +### تشخیص داده می‌شود اما اجرا نمی‌شود -این موارد شناسایی می‌شوند و در عیب‌یابی‌ها نمایش داده می‌شوند، اما OpenClaw آن‌ها را اجرا نمی‌کند: +این موارد شناسایی می‌شوند و در diagnostics نمایش داده می‌شوند، اما OpenClaw آن‌ها را اجرا نمی‌کند: -- `agents` مربوط به Claude، خودکارسازی `hooks.json`، `outputStyles` -- `.cursor/agents`، `.cursor/hooks.json`، `.cursor/rules` مربوط به Cursor -- فراداده inline/app مربوط به Codex فراتر از گزارش قابلیت +- موارد Claude شامل `agents`، خودکارسازی `hooks.json` و `outputStyles` +- موارد Cursor شامل `.cursor/agents`، `.cursor/hooks.json` و `.cursor/rules` +- فراداده درون‌خطی/برنامه‌ای Codex فراتر از گزارش قابلیت -## قالب‌های بسته +## قالب‌های باندل - + نشانگرها: `.codex-plugin/plugin.json` محتوای اختیاری: `skills/`، `hooks/`، `.mcp.json`، `.app.json` - بسته‌های Codex زمانی بهترین تناسب را با OpenClaw دارند که از ریشه‌های Skill و دایرکتوری‌های - بسته هوک OpenClaw-مانند (`HOOK.md` + `handler.ts`) استفاده کنند. + باندل‌های Codex وقتی از ریشه‌های Skill و پوشه‌های بسته hook سبک OpenClaw (`HOOK.md` + `handler.ts`) استفاده کنند، بهترین سازگاری را با OpenClaw دارند. - + دو حالت تشخیص: - - **مبتنی بر مانیفست:** `.claude-plugin/plugin.json` - - **بدون مانیفست:** چیدمان پیش‌فرض Claude (`skills/`، `commands/`، `agents/`، `hooks/`، `.mcp.json`، `.lsp.json`، `settings.json`) + - **مبتنی بر manifest:** `.claude-plugin/plugin.json` + - **بدون manifest:** چیدمان پیش‌فرض Claude (`skills/`، `commands/`، `agents/`، `hooks/`، `.mcp.json`، `.lsp.json`، `settings.json`) - رفتار اختصاصی Claude: + رفتارهای ویژه Claude: - `commands/` به‌عنوان محتوای Skill در نظر گرفته می‌شود - - `settings.json` در تنظیمات Pi تعبیه‌شده وارد می‌شود (کلیدهای override پوسته پاک‌سازی می‌شوند) + - `settings.json` به تنظیمات Pi تعبیه‌شده وارد می‌شود (کلیدهای بازنویسی shell پاک‌سازی می‌شوند) - `.mcp.json` ابزارهای stdio پشتیبانی‌شده را برای Pi تعبیه‌شده ارائه می‌کند - - `.lsp.json` به‌همراه مسیرهای `lspServers` اعلام‌شده در مانیفست در پیش‌فرض‌های LSP مربوط به Pi تعبیه‌شده بارگذاری می‌شوند + - `.lsp.json` به‌علاوه مسیرهای `lspServers` اعلام‌شده در manifest در پیش‌فرض‌های LSP برای Pi تعبیه‌شده بارگذاری می‌شوند - `hooks/hooks.json` تشخیص داده می‌شود اما اجرا نمی‌شود - - مسیرهای مؤلفه سفارشی در مانیفست افزایشی هستند (پیش‌فرض‌ها را گسترش می‌دهند، جایگزین آن‌ها نمی‌شوند) + - مسیرهای مؤلفه سفارشی در manifest افزایشی هستند (پیش‌فرض‌ها را گسترش می‌دهند، نه اینکه جایگزین آن‌ها شوند) - + نشانگرها: `.cursor-plugin/plugin.json` محتوای اختیاری: `skills/`، `.cursor/commands/`، `.cursor/agents/`، `.cursor/rules/`، `.cursor/hooks.json`، `.mcp.json` - `.cursor/commands/` به‌عنوان محتوای Skill در نظر گرفته می‌شود - - `.cursor/rules/`، `.cursor/agents/`، و `.cursor/hooks.json` فقط تشخیص داده می‌شوند + - `.cursor/rules/`، `.cursor/agents/` و `.cursor/hooks.json` فقط تشخیص داده می‌شوند -## تقدم تشخیص +## اولویت تشخیص OpenClaw ابتدا قالب Plugin بومی را بررسی می‌کند: 1. `openclaw.plugin.json` یا `package.json` معتبر با `openclaw.extensions` — به‌عنوان **Plugin بومی** در نظر گرفته می‌شود -2. نشانگرهای بسته (`.codex-plugin/`، `.claude-plugin/`، یا چیدمان پیش‌فرض Claude/Cursor) — به‌عنوان **بسته** در نظر گرفته می‌شود +2. نشانگرهای باندل (`.codex-plugin/`، `.claude-plugin/` یا چیدمان پیش‌فرض Claude/Cursor) — به‌عنوان **باندل** در نظر گرفته می‌شود -اگر یک دایرکتوری هر دو را داشته باشد، OpenClaw از مسیر بومی استفاده می‌کند. این کار مانع می‌شود -بسته‌های دو‌قالبی به‌صورت ناقص به‌عنوان بسته نصب شوند. +اگر یک پوشه هر دو را داشته باشد، OpenClaw از مسیر بومی استفاده می‌کند. این کار از نصب ناقص بسته‌های دو‌قالبی به‌عنوان باندل جلوگیری می‌کند. ## وابستگی‌های زمان اجرا و پاک‌سازی -- بسته‌های سازگار شخص ثالث، ترمیم `npm install` هنگام راه‌اندازی دریافت نمی‌کنند. آن‌ها - باید از طریق `openclaw plugins install` نصب شوند و هرچه نیاز دارند را - در دایرکتوری Plugin نصب‌شده همراه داشته باشند. -- Pluginهای بسته‌بندی‌شده متعلق به OpenClaw یا به‌صورت سبک در هسته عرضه می‌شوند یا - از طریق نصب‌کننده Plugin قابل دانلود هستند. راه‌اندازی Gateway هرگز برای آن‌ها - مدیر بسته اجرا نمی‌کند. -- `openclaw doctor --fix` دایرکتوری‌های وابستگی مرحله‌بندی‌شده قدیمی را حذف می‌کند و می‌تواند - Pluginهای دانلودی پیکربندی‌شده را که در نمایه محلی - Plugin وجود ندارند نصب کند. +- باندل‌های سازگار شخص ثالث، repair مربوط به `npm install` هنگام راه‌اندازی دریافت نمی‌کنند. آن‌ها باید از طریق `openclaw plugins install` نصب شوند و هرآنچه نیاز دارند را در پوشه Plugin نصب‌شده همراه داشته باشند. +- Pluginهای باندل‌شده تحت مالکیت OpenClaw یا به‌صورت سبک در core عرضه می‌شوند یا از طریق نصب‌کننده Plugin قابل دانلود هستند. راه‌اندازی Gateway هرگز برای آن‌ها package manager اجرا نمی‌کند. +- `openclaw doctor --fix` پوشه‌های وابستگی staged قدیمی را حذف می‌کند و می‌تواند Pluginهای قابل دانلودی را که در index محلی Plugin وجود ندارند اما config به آن‌ها ارجاع می‌دهد بازیابی کند. ## امنیت -بسته‌ها نسبت به Pluginهای بومی مرز اعتماد محدودتری دارند: +باندل‌ها نسبت به Pluginهای بومی مرز اعتماد محدودتری دارند: -- OpenClaw ماژول‌های زمان اجرای دلخواه بسته را درون‌فرایندی بارگذاری نمی‌کند -- مسیرهای Skills و بسته هوک باید داخل ریشه Plugin باقی بمانند (با بررسی مرز) +- OpenClaw ماژول‌های دلخواه زمان اجرای باندل را درون پردازش بارگذاری **نمی‌کند** +- مسیرهای Skills و بسته hook باید داخل ریشه Plugin باقی بمانند (با بررسی مرز) - فایل‌های تنظیمات با همان بررسی‌های مرزی خوانده می‌شوند -- سرورهای MCP پشتیبانی‌شده از نوع stdio ممکن است به‌عنوان زیرفرایند راه‌اندازی شوند +- سرورهای MCP پشتیبانی‌شده مبتنی بر stdio ممکن است به‌عنوان subprocess راه‌اندازی شوند -این باعث می‌شود بسته‌ها به‌صورت پیش‌فرض امن‌تر باشند، اما همچنان باید بسته‌های شخص ثالث -را برای قابلیت‌هایی که ارائه می‌کنند به‌عنوان محتوای قابل اعتماد در نظر بگیرید. +این باعث می‌شود باندل‌ها به‌صورت پیش‌فرض امن‌تر باشند، اما همچنان باید باندل‌های شخص ثالث را برای قابلیت‌هایی که ارائه می‌کنند به‌عنوان محتوای مورد اعتماد در نظر بگیرید. ## عیب‌یابی - - `openclaw plugins inspect ` را اجرا کنید. اگر قابلیتی فهرست شده اما به‌عنوان - متصل‌نشده علامت‌گذاری شده باشد، این یک محدودیت محصول است — نه نصب خراب. + + `openclaw plugins inspect ` را اجرا کنید. اگر قابلیتی فهرست شده اما با عنوان متصل‌نشده علامت‌گذاری شده باشد، این یک محدودیت محصول است، نه نصب خراب. - مطمئن شوید بسته فعال است و فایل‌های markdown داخل یک ریشه - `commands/` یا `skills/` تشخیص‌داده‌شده قرار دارند. + مطمئن شوید باندل فعال است و فایل‌های markdown داخل یک ریشه تشخیص‌داده‌شده `commands/` یا `skills/` قرار دارند. - فقط تنظیمات Pi تعبیه‌شده از `settings.json` پشتیبانی می‌شوند. OpenClaw - تنظیمات بسته را به‌عنوان وصله‌های خام پیکربندی در نظر نمی‌گیرد. + فقط تنظیمات Pi تعبیه‌شده از `settings.json` پشتیبانی می‌شوند. OpenClaw تنظیمات باندل را به‌عنوان patchهای خام config در نظر نمی‌گیرد. - - `hooks/hooks.json` فقط تشخیص داده می‌شود. اگر به هوک‌های قابل اجرا نیاز دارید، از - چیدمان بسته هوک OpenClaw استفاده کنید یا یک Plugin بومی ارائه دهید. + + `hooks/hooks.json` فقط تشخیص داده می‌شود. اگر به hookهای قابل اجرا نیاز دارید، از چیدمان بسته hook در OpenClaw استفاده کنید یا یک Plugin بومی عرضه کنید. @@ -312,4 +274,4 @@ OpenClaw ابتدا قالب Plugin بومی را بررسی می‌کند: - [نصب و پیکربندی Pluginها](/fa/tools/plugin) - [ساخت Pluginها](/fa/plugins/building-plugins) — ایجاد یک Plugin بومی -- [مانیفست Plugin](/fa/plugins/manifest) — شِمای مانیفست بومی +- [manifest مربوط به Plugin](/fa/plugins/manifest) — schema بومی manifest diff --git a/docs/fa/plugins/codex-harness.md b/docs/fa/plugins/codex-harness.md index dad5b3e92..c238a427e 100644 --- a/docs/fa/plugins/codex-harness.md +++ b/docs/fa/plugins/codex-harness.md @@ -1,42 +1,63 @@ --- read_when: - - می‌خواهید از هارنس app-server همراه با Codex استفاده کنید - - به نمونه‌های پیکربندی هارنس برای Codex نیاز دارید - - شما می‌خواهید استقرارهای فقط Codex به‌جای بازگشت به PI با خطا مواجه شوند -summary: نوبت‌های عامل تعبیه‌شده OpenClaw را از طریق هارنس app-server همراه Codex اجرا کنید + - می‌خواهید از چارچوب آزمایشی app-server همراه Codex استفاده کنید + - به نمونه‌های پیکربندی هارنس Codex نیاز دارید + - می‌خواهید استقرارهای فقط Codex به‌جای بازگشت به PI شکست بخورند +summary: نوبت‌های عامل تعبیه‌شدهٔ OpenClaw را از طریق چارچوب اجرایی app-server همراه Codex اجرا کنید title: هارنس Codex x-i18n: - generated_at: "2026-05-03T21:37:55Z" + generated_at: "2026-05-05T01:49:46Z" model: gpt-5.5 provider: openai - source_hash: f5187e54e2dc94e511c0243227f741d3486669f595c2b15cf239b1c03ea466c8 + source_hash: 76302351e7e162e858dd6e3cffca84b3fd54497dd060104da9f90fe4c1a33f9b source_path: plugins/codex-harness.md workflow: 16 --- -Plugin همراه `codex` به OpenClaw اجازه می‌دهد نوبت‌های عامل تعبیه‌شده را به‌جای هارنس داخلی PI از طریق سرور برنامه Codex اجرا کند. +Plugin همراه `codex` به OpenClaw اجازه می‌دهد نوبت‌های عاملِ تعبیه‌شده را از طریق +سرور برنامه‌ی Codex به‌جای سازوکار داخلی PI اجرا کند. -وقتی می‌خواهید Codex مالک نشست سطح پایین عامل باشد از این استفاده کنید: کشف مدل، ازسرگیری بومی رشته، Compaction بومی، و اجرای سرور برنامه. OpenClaw همچنان مالک کانال‌های گفت‌وگو، فایل‌های نشست، انتخاب مدل، ابزارها، تأییدها، تحویل رسانه، و آینه رونوشت قابل مشاهده است. +وقتی می‌خواهید Codex مالک نشست سطح‌پایین عامل باشد، از این استفاده کنید: کشف +مدل، ازسرگیری بومی رشته، Compaction بومی، و اجرای سرور برنامه. OpenClaw همچنان +مالک کانال‌های چت، فایل‌های نشست، انتخاب مدل، ابزارها، تأییدها، تحویل رسانه، و +آینه‌ی قابل‌مشاهده‌ی رونوشت است. -وقتی یک نوبت گفت‌وگوی منبع از طریق هارنس Codex اجرا می‌شود، اگر استقرار به‌صورت صریح `messages.visibleReplies` را پیکربندی نکرده باشد، پاسخ‌های قابل مشاهده به‌طور پیش‌فرض از ابزار `message` در OpenClaw استفاده می‌کنند. عامل همچنان می‌تواند نوبت Codex خود را به‌صورت خصوصی تمام کند؛ فقط زمانی در کانال پست می‌کند که `message(action="send")` را فراخوانی کند. برای نگه داشتن پاسخ‌های نهایی گفت‌وگوی مستقیم روی مسیر تحویل خودکار قدیمی، `messages.visibleReplies: "automatic"` را تنظیم کنید. +وقتی یک نوبت چت مبدأ از طریق سازوکار Codex اجرا می‌شود، اگر استقرار به‌صراحت +`messages.visibleReplies` را پیکربندی نکرده باشد، پاسخ‌های قابل‌مشاهده به‌طور +پیش‌فرض از ابزار `message` در OpenClaw استفاده می‌کنند. عامل همچنان می‌تواند +نوبت Codex خود را به‌صورت خصوصی تمام کند؛ فقط زمانی در کانال پست می‌کند که +`message(action="send")` را فراخوانی کند. برای نگه‌داشتن پاسخ‌های نهایی چت +مستقیم روی مسیر تحویل خودکار قدیمی، `messages.visibleReplies: "automatic"` را +تنظیم کنید. -نوبت‌های Heartbeat در Codex نیز به‌طور پیش‌فرض ابزار `heartbeat_respond` را دریافت می‌کنند، بنابراین عامل می‌تواند بدون کدگذاری این جریان کنترل در متن نهایی، ثبت کند که بیدار شدن باید ساکت بماند یا اعلان بدهد. +نوبت‌های Heartbeat در Codex نیز به‌طور پیش‌فرض ابزار `heartbeat_respond` را +دریافت می‌کنند، تا عامل بتواند ثبت کند که بیدارباش باید بی‌صدا بماند یا بدون +کدگذاری آن جریان کنترل در متن نهایی، اعلان بدهد. -راهنمای ابتکار ویژه Heartbeat به‌عنوان دستور توسعه‌دهنده حالت همکاری Codex در خود نوبت Heartbeat ارسال می‌شود. نوبت‌های گفت‌وگوی عادی به‌جای حمل فلسفه Heartbeat در اعلان زمان اجرای معمول خود، حالت پیش‌فرض Codex را بازیابی می‌کنند. +راهنمای ابتکار مخصوص Heartbeat به‌عنوان یک دستور توسعه‌دهنده‌ی حالت همکاری +Codex روی خود نوبت Heartbeat ارسال می‌شود. نوبت‌های عادی چت به‌جای حمل فلسفه‌ی +Heartbeat در پرامپت زمان‌اجرای معمول خود، حالت پیش‌فرض Codex را بازیابی می‌کنند. -اگر می‌خواهید جهت‌گیری پیدا کنید، از [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) شروع کنید. نسخه کوتاه این است: `openai/gpt-5.5` مرجع مدل است، `codex` زمان اجرا است، و Telegram، Discord، Slack، یا کانالی دیگر سطح ارتباطی باقی می‌ماند. +اگر می‌خواهید جهت بگیرید، با +[زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) شروع کنید. نسخه‌ی کوتاه این +است: `openai/gpt-5.5` ارجاع مدل است، `codex` زمان‌اجرا است، و Telegram، +Discord، Slack، یا کانالی دیگر سطح ارتباطی باقی می‌ماند. ## پیکربندی سریع -بیشتر کاربرانی که «Codex در OpenClaw» می‌خواهند، این مسیر را می‌خواهند: با اشتراک ChatGPT/Codex وارد شوید، سپس نوبت‌های عامل تعبیه‌شده را از طریق زمان اجرای بومی سرور برنامه Codex اجرا کنید. مرجع مدل همچنان به‌صورت متعارف `openai/gpt-*` باقی می‌ماند؛ احراز هویت اشتراک از حساب/نمایه Codex می‌آید، نه از پیشوند مدل `openai-codex/*`. +بیشتر کاربرانی که «Codex در OpenClaw» می‌خواهند این مسیر را می‌خواهند: با یک +اشتراک ChatGPT/Codex وارد شوید، سپس نوبت‌های عامل تعبیه‌شده را از طریق +زمان‌اجرای بومی سرور برنامه‌ی Codex اجرا کنید. ارجاع مدل همچنان به‌شکل +استاندارد `openai/gpt-*` می‌ماند؛ احراز هویت اشتراک از حساب/نمایه‌ی Codex +می‌آید، نه از پیشوند مدل `openai-codex/*`. -اگر هنوز وارد نشده‌اید، ابتدا با OAuth مربوط به Codex وارد شوید: +اگر هنوز این کار را نکرده‌اید، ابتدا با OAuth در Codex وارد شوید: ```bash openclaw models auth login --provider openai-codex ``` -سپس Plugin همراه `codex` را فعال کنید و زمان اجرای Codex را اجباری کنید: +سپس Plugin همراه `codex` را فعال کنید و زمان‌اجرای Codex را اجباری کنید: ```json5 { @@ -58,7 +79,7 @@ openclaw models auth login --provider openai-codex } ``` -اگر پیکربندی شما از `plugins.allow` استفاده می‌کند، `codex` را هم آنجا اضافه کنید: +اگر پیکربندی شما از `plugins.allow` استفاده می‌کند، `codex` را آنجا هم قرار دهید: ```json5 { @@ -73,135 +94,192 @@ openclaw models auth login --provider openai-codex } ``` -وقتی منظورتان زمان اجرای بومی Codex است، از `openai-codex/gpt-*` استفاده نکنید. آن پیشوند مسیر صریح «OAuth مربوط به Codex از طریق PI» است. تغییرات پیکربندی روی نشست‌های جدید یا بازنشانی‌شده اعمال می‌شوند؛ نشست‌های موجود زمان اجرای ثبت‌شده خود را نگه می‌دارند. +وقتی منظورتان زمان‌اجرای بومی Codex است، از `openai-codex/gpt-*` استفاده نکنید. +آن پیشوند مسیر صریح «OAuth کدکس از طریق PI» است. تغییرات پیکربندی روی نشست‌های +جدید یا بازنشانی‌شده اعمال می‌شوند؛ نشست‌های موجود زمان‌اجرای ثبت‌شده‌ی خود را +نگه می‌دارند. ## این Plugin چه چیزی را تغییر می‌دهد Plugin همراه `codex` چند قابلیت جداگانه فراهم می‌کند: -| قابلیت | نحوه استفاده | کاری که انجام می‌دهد | +| قابلیت | نحوه‌ی استفاده | کاری که انجام می‌دهد | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| زمان اجرای بومی تعبیه‌شده | `agentRuntime.id: "codex"` | نوبت‌های عامل تعبیه‌شده OpenClaw را از طریق سرور برنامه Codex اجرا می‌کند. | -| فرمان‌های بومی کنترل گفت‌وگو | `/codex bind`, `/codex resume`, `/codex steer`, ... | رشته‌های سرور برنامه Codex را از یک مکالمه پیام‌رسانی متصل و کنترل می‌کند. | -| ارائه‌دهنده/کاتالوگ سرور برنامه Codex | بخش‌های داخلی `codex`، در معرض استفاده از طریق هارنس | به زمان اجرا اجازه می‌دهد مدل‌های سرور برنامه را کشف و اعتبارسنجی کند. | -| مسیر درک رسانه Codex | مسیرهای سازگاری مدل تصویر `codex/*` | نوبت‌های محدود سرور برنامه Codex را برای مدل‌های پشتیبانی‌شده درک تصویر اجرا می‌کند. | -| رله بومی hook | hookهای Plugin پیرامون رویدادهای بومی Codex | به OpenClaw اجازه می‌دهد رویدادهای پشتیبانی‌شده ابزار/نهایی‌سازی بومی Codex را مشاهده/مسدود کند. | +| زمان‌اجرای تعبیه‌شده‌ی بومی | `agentRuntime.id: "codex"` | نوبت‌های عامل تعبیه‌شده‌ی OpenClaw را از طریق سرور برنامه‌ی Codex اجرا می‌کند. | +| فرمان‌های بومی کنترل چت | `/codex bind`, `/codex resume`, `/codex steer`, ... | رشته‌های سرور برنامه‌ی Codex را از یک گفت‌وگوی پیام‌رسانی متصل و کنترل می‌کند. | +| ارائه‌دهنده/کاتالوگ سرور برنامه‌ی Codex | داخلی‌های `codex`، ارائه‌شده از طریق سازوکار | به زمان‌اجرا اجازه می‌دهد مدل‌های سرور برنامه را کشف و اعتبارسنجی کند. | +| مسیر درک رسانه‌ی Codex | مسیرهای سازگاری مدل تصویر `codex/*` | نوبت‌های محدود سرور برنامه‌ی Codex را برای مدل‌های پشتیبانی‌شده‌ی درک تصویر اجرا می‌کند. | +| رله‌ی Hook بومی | Hookهای Plugin پیرامون رویدادهای بومی Codex | به OpenClaw اجازه می‌دهد رویدادهای ابزار/نهایی‌سازی بومی Codex را مشاهده/مسدود کند. | -فعال کردن Plugin این قابلیت‌ها را در دسترس قرار می‌دهد. این کار **انجام نمی‌دهد**: +فعال‌کردن Plugin این قابلیت‌ها را در دسترس قرار می‌دهد. این کار **موارد زیر را انجام نمی‌دهد**: -- شروع استفاده از Codex برای هر مدل OpenAI -- تبدیل مراجع مدل `openai-codex/*` به زمان اجرای بومی -- پیش‌فرض کردن مسیر ACP/acpx برای Codex -- تعویض داغ نشست‌های موجودی که قبلاً زمان اجرای PI را ثبت کرده‌اند -- جایگزین کردن تحویل کانال OpenClaw، فایل‌های نشست، ذخیره‌سازی نمایه احراز هویت، یا مسیریابی پیام +- شروع به استفاده از Codex برای هر مدل OpenAI +- تبدیل ارجاع‌های مدل `openai-codex/*` به زمان‌اجرای بومی +- پیش‌فرض‌کردن مسیر Codex به ACP/acpx +- جابه‌جایی داغ نشست‌های موجودی که قبلاً زمان‌اجرای PI ثبت کرده‌اند +- جایگزین‌کردن تحویل کانال OpenClaw، فایل‌های نشست، ذخیره‌سازی نمایه‌ی احراز هویت، یا + مسیریابی پیام -همین Plugin همچنین مالک سطح فرمان کنترل گفت‌وگوی بومی `/codex` است. اگر Plugin فعال باشد و کاربر بخواهد رشته‌های Codex را از گفت‌وگو bind، resume، steer، stop، یا inspect کند، عامل‌ها باید `/codex ...` را به ACP ترجیح دهند. ACP زمانی fallback صریح باقی می‌ماند که کاربر ACP/acpx را بخواهد یا در حال آزمایش آداپتور ACP مربوط به Codex باشد. +همین Plugin همچنین مالک سطح فرمان کنترل چت بومی `/codex` است. اگر Plugin فعال +باشد و کاربر بخواهد رشته‌های Codex را از چت متصل، ازسرگیری، هدایت، متوقف، یا +بازرسی کند، عامل‌ها باید `/codex ...` را بر ACP ترجیح دهند. ACP زمانی پشتیبان +صریح باقی می‌ماند که کاربر ACP/acpx را درخواست کند یا در حال آزمایش آداپتور +Codex برای ACP باشد. -نوبت‌های بومی Codex، hookهای Plugin در OpenClaw را به‌عنوان لایه سازگاری عمومی نگه می‌دارند. این‌ها hookهای درون‌فرایندی OpenClaw هستند، نه hookهای فرمان `hooks.json` در Codex: +نوبت‌های بومی Codex، Hookهای Plugin در OpenClaw را به‌عنوان لایه‌ی سازگاری +عمومی نگه می‌دارند. این‌ها Hookهای درون‌فرایندی OpenClaw هستند، نه Hookهای +فرمانی `hooks.json` در Codex: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` - `before_message_write` برای رکوردهای رونوشت آینه‌شده -- `before_agent_finalize` از طریق رله `Stop` در Codex +- `before_agent_finalize` از طریق رله‌ی `Stop` در Codex - `agent_end` -Pluginها همچنین می‌توانند middleware نتیجه ابزار خنثی نسبت به زمان اجرا ثبت کنند تا پس از اجرای ابزار توسط OpenClaw و پیش از بازگرداندن نتیجه به Codex، نتایج ابزار پویای OpenClaw را بازنویسی کنند. این از hook عمومی Plugin با نام `tool_result_persist` جدا است، که نوشتن‌های نتیجه ابزارِ رونوشت تحت مالکیت OpenClaw را تبدیل می‌کند. +Pluginها همچنین می‌توانند میان‌افزار نتیجه‌ی ابزارِ مستقل از زمان‌اجرا ثبت کنند +تا نتایج ابزار پویای OpenClaw را پس از اجرای ابزار توسط OpenClaw و پیش از +برگرداندن نتیجه به Codex بازنویسی کنند. این از Hook عمومی Plugin با نام +`tool_result_persist` جداست، که نوشتن‌های نتیجه‌ی ابزار در رونوشت‌های متعلق به +OpenClaw را تبدیل می‌کند. -برای معنای خود hookهای Plugin، [hookهای Plugin](/fa/plugins/hooks) و [رفتار محافظ Plugin](/fa/tools/plugin) را ببینید. +برای خود معنای Hookهای Plugin، [Hookهای Plugin](/fa/plugins/hooks) +و [رفتار محافظ Plugin](/fa/tools/plugin) را ببینید. -هارنس به‌طور پیش‌فرض خاموش است. پیکربندی‌های جدید باید مراجع مدل OpenAI را به‌صورت متعارف `openai/gpt-*` نگه دارند و وقتی اجرای بومی سرور برنامه را می‌خواهند، به‌صورت صریح `agentRuntime.id: "codex"` یا `OPENCLAW_AGENT_RUNTIME=codex` را اجباری کنند. مراجع مدل قدیمی `codex/*` همچنان برای سازگاری هارنس را به‌صورت خودکار انتخاب می‌کنند، اما پیشوندهای ارائه‌دهنده قدیمیِ پشتوانه‌دار با زمان اجرا، به‌عنوان انتخاب‌های عادی مدل/ارائه‌دهنده نشان داده نمی‌شوند. +این سازوکار به‌طور پیش‌فرض خاموش است. پیکربندی‌های جدید باید ارجاع‌های مدل +OpenAI را به‌شکل استاندارد `openai/gpt-*` نگه دارند و زمانی که اجرای بومی +سرور برنامه را می‌خواهند، به‌صراحت `agentRuntime.id: "codex"` یا +`OPENCLAW_AGENT_RUNTIME=codex` را اجباری کنند. ارجاع‌های مدل قدیمی `codex/*` +هنوز برای سازگاری سازوکار را به‌طور خودکار انتخاب می‌کنند، اما پیشوندهای +ارائه‌دهنده‌ی قدیمیِ متکی به زمان‌اجرا به‌عنوان گزینه‌های عادی مدل/ارائه‌دهنده +نمایش داده نمی‌شوند. -اگر Plugin با نام `codex` فعال باشد اما مدل اصلی همچنان `openai-codex/*` باشد، `openclaw doctor` به‌جای تغییر مسیر هشدار می‌دهد. این عمدی است: `openai-codex/*` مسیر OAuth/اشتراک Codex از طریق PI باقی می‌ماند، و اجرای بومی سرور برنامه یک انتخاب صریح زمان اجرا می‌ماند. +اگر Plugin با نام `codex` فعال باشد اما مدل اصلی همچنان `openai-codex/*` باشد، +`openclaw doctor` به‌جای تغییر مسیر هشدار می‌دهد. این عمدی است: +`openai-codex/*` همچنان مسیر OAuth/اشتراک Codex از طریق PI باقی می‌ماند، و +اجرای بومی سرور برنامه یک انتخاب صریح زمان‌اجرا می‌ماند. -## نقشه مسیر +## نقشه‌ی مسیر پیش از تغییر پیکربندی از این جدول استفاده کنید: -| رفتار مورد نظر | مرجع مدل | پیکربندی زمان اجرا | مسیر احراز هویت/نمایه | برچسب وضعیت مورد انتظار | -| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | -| اشتراک ChatGPT/Codex با زمان اجرای بومی Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | OAuth مربوط به Codex یا حساب Codex | `Runtime: OpenAI Codex` | -| API مربوط به OpenAI از طریق runner عادی OpenClaw | `openai/gpt-*` | حذف‌شده یا `runtime: "pi"` | کلید API مربوط به OpenAI | `Runtime: OpenClaw Pi Default` | -| اشتراک ChatGPT/Codex از طریق PI | `openai-codex/gpt-*` | حذف‌شده یا `runtime: "pi"` | ارائه‌دهنده OAuth مربوط به OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| ارائه‌دهندگان ترکیبی با حالت خودکار محافظه‌کارانه | مراجع ویژه ارائه‌دهنده | `agentRuntime.id: "auto"` | به‌ازای ارائه‌دهنده انتخاب‌شده | وابسته به زمان اجرای انتخاب‌شده | -| نشست صریح آداپتور ACP مربوط به Codex | وابسته به اعلان/مدل ACP | `sessions_spawn` با `runtime: "acp"` | احراز هویت backend مربوط به ACP | وضعیت وظیفه/نشست ACP | +| رفتار مطلوب | ارجاع مدل | پیکربندی زمان‌اجرا | مسیر احراز هویت/نمایه | برچسب وضعیت مورد انتظار | +| ---------------------------------------------------- | -------------------------- | ----------------------------------- | ---------------------------- | ------------------------------ | +| اشتراک ChatGPT/Codex با زمان‌اجرای بومی Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | OAuth در Codex یا حساب Codex | `Runtime: OpenAI Codex` | +| API OpenAI از طریق اجراکننده‌ی معمول OpenClaw | `openai/gpt-*` | حذف‌شده یا `runtime: "pi"` | کلید API OpenAI | `Runtime: OpenClaw Pi Default` | +| اشتراک ChatGPT/Codex از طریق PI | `openai-codex/gpt-*` | حذف‌شده یا `runtime: "pi"` | ارائه‌دهنده‌ی OAuth کدکس در OpenAI | `Runtime: OpenClaw Pi Default` | +| ارائه‌دهندگان ترکیبی با حالت خودکار محافظه‌کارانه | ارجاع‌های مخصوص ارائه‌دهنده | `agentRuntime.id: "auto"` | برای هر ارائه‌دهنده‌ی انتخاب‌شده | وابسته به زمان‌اجرای انتخاب‌شده | +| نشست صریح آداپتور ACP برای Codex | وابسته به پرامپت/مدل ACP | `sessions_spawn` با `runtime: "acp"` | احراز هویت بک‌اند ACP | وضعیت وظیفه/نشست ACP | -تفکیک مهم، ارائه‌دهنده در برابر زمان اجرا است: +جداسازی مهم، ارائه‌دهنده در برابر زمان‌اجرا است: - `openai-codex/*` پاسخ می‌دهد «PI باید از کدام مسیر ارائه‌دهنده/احراز هویت استفاده کند؟» - `agentRuntime.id: "codex"` پاسخ می‌دهد «کدام حلقه باید این نوبت تعبیه‌شده را اجرا کند؟» -- `/codex ...` پاسخ می‌دهد «این گفت‌وگو باید به کدام مکالمه بومی Codex متصل شود یا آن را کنترل کند؟» -- ACP پاسخ می‌دهد «acpx باید کدام فرایند هارنس خارجی را راه‌اندازی کند؟» +- `/codex ...` پاسخ می‌دهد «این چت باید به کدام گفت‌وگوی بومی Codex متصل شود یا آن را کنترل کند؟» +- ACP پاسخ می‌دهد «acpx باید کدام فرایند سازوکار بیرونی را اجرا کند؟» -## انتخاب پیشوند مدل درست +## پیشوند مدل درست را انتخاب کنید -مسیرهای خانواده OpenAI به پیشوند وابسته‌اند. برای راه‌اندازی رایج اشتراک به‌همراه زمان اجرای بومی Codex، از `openai/*` با `agentRuntime.id: "codex"` استفاده کنید. فقط وقتی از `openai-codex/*` استفاده کنید که عمداً OAuth مربوط به Codex از طریق PI را می‌خواهید: +مسیرهای خانواده‌ی OpenAI به پیشوند وابسته‌اند. برای راه‌اندازی رایج اشتراک به‌علاوه‌ی +زمان‌اجرای بومی Codex، از `openai/*` با `agentRuntime.id: "codex"` استفاده کنید. +فقط زمانی از `openai-codex/*` استفاده کنید که عمداً OAuth در Codex از طریق PI +را می‌خواهید: -| مرجع مدل | مسیر زمان اجرا | زمان استفاده | -| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | ارائه‌دهنده OpenAI از طریق لوله‌کشی OpenClaw/PI | دسترسی فعلی مستقیم به API پلتفرم OpenAI را با `OPENAI_API_KEY` می‌خواهید. | -| `openai-codex/gpt-5.5` | OAuth مربوط به OpenAI Codex از طریق OpenClaw/PI | احراز هویت اشتراک ChatGPT/Codex را با runner پیش‌فرض PI می‌خواهید. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | هارنس سرور برنامه Codex | احراز هویت اشتراک ChatGPT/Codex را با اجرای بومی Codex می‌خواهید. | +| ارجاع مدل | مسیر زمان‌اجرا | زمان استفاده | +| --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | ارائه‌دهنده‌ی OpenAI از طریق لوله‌کشی OpenClaw/PI | دسترسی مستقیم فعلی به API پلتفرم OpenAI با `OPENAI_API_KEY` را می‌خواهید. | +| `openai-codex/gpt-5.5` | OAuth کدکس در OpenAI از طریق OpenClaw/PI | احراز هویت اشتراک ChatGPT/Codex با اجراکننده‌ی پیش‌فرض PI را می‌خواهید. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | سازوکار سرور برنامه‌ی Codex | احراز هویت اشتراک ChatGPT/Codex با اجرای بومی Codex را می‌خواهید. | -GPT-5.5 می‌تواند وقتی حساب شما آن‌ها را در دسترس قرار می‌دهد، هم روی مسیرهای کلید API مستقیم OpenAI و هم مسیرهای اشتراک Codex ظاهر شود. برای زمان اجرای بومی Codex از `openai/gpt-5.5` با هارنس سرور برنامه Codex استفاده کنید، برای OAuth مربوط به PI از `openai-codex/gpt-5.5`، یا برای ترافیک مستقیم کلید API از `openai/gpt-5.5` بدون override زمان اجرای Codex استفاده کنید. +GPT-5.5 زمانی که حساب شما آن‌ها را ارائه کند، می‌تواند هم روی مسیرهای مستقیم +کلید API در OpenAI و هم مسیرهای اشتراک Codex ظاهر شود. برای زمان‌اجرای بومی +Codex، از `openai/gpt-5.5` با سازوکار سرور برنامه‌ی Codex استفاده کنید؛ برای +OAuth از طریق PI از `openai-codex/gpt-5.5` استفاده کنید؛ یا برای ترافیک مستقیم +کلید API، از `openai/gpt-5.5` بدون بازنویسی زمان‌اجرای Codex استفاده کنید. -مراجع قدیمی `codex/gpt-*` همچنان به‌عنوان aliasهای سازگاری پذیرفته می‌شوند. مهاجرت سازگاری doctor مراجع قدیمی زمان اجرای اصلی را به مراجع متعارف مدل بازنویسی می‌کند و سیاست زمان اجرا را جداگانه ثبت می‌کند، درحالی‌که مراجع قدیمیِ فقط fallback بدون تغییر رها می‌شوند چون زمان اجرا برای کل کانتینر عامل پیکربندی می‌شود. پیکربندی‌های جدید OAuth مربوط به PI Codex باید از `openai-codex/gpt-*` استفاده کنند؛ پیکربندی‌های جدید هارنس بومی سرور برنامه باید از `openai/gpt-*` به‌همراه `agentRuntime.id: "codex"` استفاده کنند. +ارجاع‌های قدیمی `codex/gpt-*` همچنان به‌عنوان نام‌های مستعار سازگاری پذیرفته +می‌شوند. مهاجرت سازگاری Doctor، ارجاع‌های زمان‌اجرای اصلی قدیمی را به ارجاع‌های +مدل استاندارد بازنویسی می‌کند و سیاست زمان‌اجرا را جداگانه ثبت می‌کند، درحالی‌که +ارجاع‌های قدیمیِ فقط پشتیبان بدون تغییر می‌مانند، چون زمان‌اجرا برای کل محفظه‌ی +عامل پیکربندی می‌شود. پیکربندی‌های جدید OAuth کدکس از طریق PI باید از +`openai-codex/gpt-*` استفاده کنند؛ پیکربندی‌های جدید سازوکار بومی سرور برنامه +باید از `openai/gpt-*` به‌علاوه‌ی `agentRuntime.id: "codex"` استفاده کنند. -`agents.defaults.imageModel` از همان تفکیک پیشوند پیروی می‌کند. وقتی درک تصویر باید از مسیر ارائه‌دهنده OAuth مربوط به OpenAI Codex اجرا شود، از `openai-codex/gpt-*` استفاده کنید. وقتی درک تصویر باید از طریق یک نوبت محدود سرور برنامه Codex اجرا شود، از `codex/gpt-*` استفاده کنید. مدل سرور برنامه Codex باید پشتیبانی از ورودی تصویر را اعلام کند؛ مدل‌های فقط متنی Codex پیش از شروع نوبت رسانه شکست می‌خورند. +`agents.defaults.imageModel` از همین جداسازی پیشوند پیروی می‌کند. وقتی درک +تصویر باید از مسیر ارائه‌دهنده‌ی OAuth کدکس در OpenAI اجرا شود، از +`openai-codex/gpt-*` استفاده کنید. وقتی درک تصویر باید از طریق یک نوبت محدود +سرور برنامه‌ی Codex اجرا شود، از `codex/gpt-*` استفاده کنید. مدل سرور برنامه‌ی +Codex باید پشتیبانی ورودی تصویر را اعلام کند؛ مدل‌های Codex فقط‌متنی پیش از +شروع نوبت رسانه شکست می‌خورند. -برای تأیید هارنس مؤثر نشست فعلی از `/status` استفاده کنید. اگر انتخاب غیرمنتظره است، logging اشکال‌زدایی را برای زیرسامانه `agents/harness` فعال کنید و رکورد ساخت‌یافته `agent harness selected` در Gateway را بررسی کنید. این رکورد شامل شناسه هارنس انتخاب‌شده، دلیل انتخاب، سیاست زمان اجرا/fallback، و در حالت `auto`، نتیجه پشتیبانی هر نامزد Plugin است. +برای تأیید سازوکار مؤثر نشست فعلی از `/status` استفاده کنید. اگر انتخاب +غیرمنتظره است، ثبت اشکال‌زدایی را برای زیرسامانه‌ی `agents/harness` فعال کنید +و رکورد ساختاریافته‌ی `agent harness selected` در Gateway را بررسی کنید. این +رکورد شامل شناسه‌ی سازوکار انتخاب‌شده، دلیل انتخاب، سیاست زمان‌اجرا/پشتیبان، و +در حالت `auto`، نتیجه‌ی پشتیبانی هر نامزد Plugin است. -### هشدارهای doctor چه معنایی دارند +### معنای هشدارهای Doctor چیست -`openclaw doctor` زمانی هشدار می‌دهد که همه این‌ها درست باشند: +`openclaw doctor` زمانی هشدار می‌دهد که همه‌ی موارد زیر درست باشند: - Plugin همراه `codex` فعال یا مجاز باشد - مدل اصلی یک عامل `openai-codex/*` باشد -- زمان اجرای مؤثر آن عامل `codex` نباشد +- زمان‌اجرای مؤثر آن عامل `codex` نباشد -این هشدار وجود دارد چون کاربران اغلب انتظار دارند «Plugin مربوط به Codex فعال است» به معنی «زمان اجرای بومی سرور برنامه Codex» باشد. OpenClaw چنین جهشی انجام نمی‌دهد. معنی هشدار این است: +این هشدار وجود دارد چون کاربران اغلب انتظار دارند «Plugin کدکس فعال است» به +معنای «زمان‌اجرای بومی سرور برنامه‌ی Codex» باشد. OpenClaw چنین جهشی انجام +نمی‌دهد. معنای هشدار این است: -- اگر منظورتان OAuth مربوط به ChatGPT/Codex از طریق PI بوده است، **هیچ تغییری لازم نیست**. -- اگر منظورتان اجرای بومی سرور برنامه بوده است، مدل را به `openai/` تغییر دهید و `agentRuntime.id: "codex"` را تنظیم کنید. -- نشست‌های موجود پس از تغییر زمان اجرا همچنان به `/new` یا `/reset` نیاز دارند، چون pinهای زمان اجرای نشست چسبنده‌اند. +- اگر قصدتان OAuth در ChatGPT/Codex از طریق PI بوده است، **هیچ تغییری لازم نیست**. +- اگر قصدتان اجرای بومی سرور برنامه بوده است، مدل را به `openai/` تغییر دهید و + `agentRuntime.id: "codex"` را تنظیم کنید. +- نشست‌های موجود پس از تغییر زمان‌اجرا همچنان به `/new` یا `/reset` نیاز دارند، + چون پین‌های زمان‌اجرای نشست چسبنده‌اند. -انتخاب هارنس کنترل زنده نشست نیست. وقتی یک نوبت تعبیه‌شده اجرا می‌شود، OpenClaw شناسه هارنس انتخاب‌شده را روی آن نشست ثبت می‌کند و برای نوبت‌های بعدی با همان شناسه نشست به استفاده از آن ادامه می‌دهد. وقتی می‌خواهید نشست‌های آینده از هارنس دیگری استفاده کنند، پیکربندی `agentRuntime` یا `OPENCLAW_AGENT_RUNTIME` را تغییر دهید؛ برای شروع یک نشست تازه پیش از جابه‌جایی یک مکالمه موجود بین PI و Codex از `/new` یا `/reset` استفاده کنید. این کار از بازپخش یک رونوشت از طریق دو سیستم نشست بومی ناسازگار جلوگیری می‌کند. +انتخاب سازوکار یک کنترل نشست زنده نیست. وقتی یک نوبت تعبیه‌شده اجرا می‌شود، +OpenClaw شناسه‌ی سازوکار انتخاب‌شده را روی آن نشست ثبت می‌کند و برای نوبت‌های +بعدی در همان شناسه‌ی نشست از آن استفاده می‌کند. وقتی می‌خواهید نشست‌های آینده +از سازوکار دیگری استفاده کنند، پیکربندی `agentRuntime` یا +`OPENCLAW_AGENT_RUNTIME` را تغییر دهید؛ پیش از جابه‌جایی یک گفت‌وگوی موجود بین +PI و Codex، از `/new` یا `/reset` برای شروع یک نشست تازه استفاده کنید. این کار +از بازپخش یک رونوشت از طریق دو سامانه‌ی نشست بومی ناسازگار جلوگیری می‌کند. -نشست‌های قدیمی که پیش از پین‌های هارنس ایجاد شده‌اند، پس از اینکه -سابقهٔ رونوشت داشته باشند، به‌عنوان سنجاق‌شده به PI در نظر گرفته می‌شوند. پس از تغییر پیکربندی، از `/new` یا `/reset` استفاده کنید تا آن گفت‌وگو را وارد Codex کنید. +جلسه‌های قدیمی که پیش از pin شدن harness ایجاد شده‌اند، پس از داشتن تاریخچه transcript به‌عنوان PI-pinned در نظر گرفته می‌شوند. پس از تغییر پیکربندی، از `/new` یا `/reset` استفاده کنید تا آن گفت‌وگو به Codex وارد شود. -`/status` زمان‌اجرای مؤثر مدل را نشان می‌دهد. هارنس پیش‌فرض PI به‌صورت -`Runtime: OpenClaw Pi Default` نمایش داده می‌شود، و هارنس سرور برنامهٔ Codex به‌صورت -`Runtime: OpenAI Codex` نمایش داده می‌شود. +`/status` runtime مؤثر مدل را نشان می‌دهد. harness پیش‌فرض PI به‌صورت +`Runtime: OpenClaw Pi Default` نمایش داده می‌شود، و harness app-server مربوط به Codex به‌صورت +`Runtime: OpenAI Codex`. ## الزامات -- OpenClaw با Plugin بسته‌بندی‌شدهٔ `codex` در دسترس باشد. -- سرور برنامهٔ Codex نسخهٔ `0.125.0` یا جدیدتر. Plugin بسته‌بندی‌شده به‌طور پیش‌فرض یک باینری سازگار سرور برنامهٔ Codex را مدیریت می‌کند، بنابراین فرمان‌های محلی `codex` در `PATH` بر راه‌اندازی معمول هارنس اثر نمی‌گذارند. -- احراز هویت Codex برای فرایند سرور برنامه یا برای پل احراز هویت Codex در OpenClaw در دسترس باشد. راه‌اندازی‌های محلی سرور برنامه برای هر عامل از خانهٔ Codex مدیریت‌شده توسط OpenClaw و یک `HOME` فرزند ایزوله استفاده می‌کنند، بنابراین به‌طور پیش‌فرض حساب شخصی `~/.codex`، Skills، plugins، پیکربندی، وضعیت نخ، یا `$HOME/.agents/skills` بومی شما را نمی‌خوانند. +- OpenClaw با Plugin همراه `codex` در دسترس. +- app-server مربوط به Codex نسخه `0.125.0` یا جدیدتر. Plugin همراه به‌طور پیش‌فرض یک باینری app-server سازگار برای Codex را مدیریت می‌کند، بنابراین فرمان‌های محلی `codex` روی `PATH` بر راه‌اندازی عادی harness اثر نمی‌گذارند. +- احراز هویت Codex برای فرایند app-server یا برای پل احراز هویت Codex در OpenClaw در دسترس باشد. راه‌اندازی‌های app-server محلی برای هر agent از یک خانه Codex مدیریت‌شده توسط OpenClaw و یک `HOME` فرزند ایزوله استفاده می‌کنند، بنابراین به‌طور پیش‌فرض حساب شخصی `~/.codex`، Skills، Pluginها، پیکربندی، وضعیت thread، یا `$HOME/.agents/skills` بومی شما را نمی‌خوانند. -Plugin دست‌دهی‌های قدیمی‌تر یا بدون نسخهٔ سرور برنامه را مسدود می‌کند. این کار OpenClaw را روی سطح پروتکلی نگه می‌دارد که در برابر آن آزموده شده است. +Plugin handshakeهای app-server قدیمی‌تر یا بدون نسخه را مسدود می‌کند. این کار OpenClaw را روی سطح پروتکلی نگه می‌دارد که در برابر آن آزموده شده است. -برای آزمون‌های دود زنده و Docker، احراز هویت معمولاً از حساب CLI در Codex یا یک پروفایل احراز هویت `openai-codex` در OpenClaw می‌آید. راه‌اندازی‌های محلی سرور برنامهٔ stdio همچنین وقتی حسابی وجود نداشته باشد می‌توانند به `CODEX_API_KEY` / `OPENAI_API_KEY` بازگردند. +برای آزمون‌های smoke زنده و Docker، احراز هویت معمولاً از حساب Codex CLI یا یک پروفایل احراز هویت `openai-codex` در OpenClaw می‌آید. راه‌اندازی‌های app-server محلی stdio همچنین می‌توانند وقتی هیچ حسابی وجود ندارد به `CODEX_API_KEY` / `OPENAI_API_KEY` برگردند. -## فایل‌های راه‌اندازی فضای کاری +## فایل‌های bootstrap فضای کاری -Codex خودش `AGENTS.md` را از طریق کشف بومی مستندات پروژه مدیریت می‌کند. OpenClaw فایل‌های مستندات پروژهٔ مصنوعی Codex را نمی‌نویسد یا برای فایل‌های persona به نام‌های جایگزین Codex وابسته نیست، چون جایگزین‌های Codex فقط وقتی اعمال می‌شوند که `AGENTS.md` وجود نداشته باشد. +Codex خودش `AGENTS.md` را از طریق کشف بومی project-doc مدیریت می‌کند. OpenClaw فایل‌های project-doc ساختگی Codex نمی‌نویسد و برای فایل‌های persona به نام‌های fallback در Codex وابسته نیست، چون fallbackهای Codex فقط وقتی اعمال می‌شوند که +`AGENTS.md` وجود نداشته باشد. -برای هم‌ترازی فضای کاری OpenClaw، هارنس Codex فایل‌های راه‌اندازی دیگر (`SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، `BOOTSTRAP.md`، و `MEMORY.md` در صورت وجود) را resolve می‌کند و آن‌ها را از طریق دستورالعمل‌های پیکربندی Codex در `thread/start` و `thread/resume` ارسال می‌کند. این کار زمینهٔ persona/profile فضای کاری مانند `SOUL.md` و موارد مرتبط را بدون تکرار `AGENTS.md` قابل مشاهده نگه می‌دارد. +برای هم‌ترازی فضای کاری OpenClaw، harness مربوط به Codex فایل‌های bootstrap دیگر (`SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، +`BOOTSTRAP.md`، و `MEMORY.md` در صورت وجود) را resolve می‌کند و آن‌ها را از طریق دستورالعمل‌های پیکربندی Codex در `thread/start` و `thread/resume` ارسال می‌کند. این کار زمینه persona/profile فضای کاری مربوط به `SOUL.md` و فایل‌های مرتبط را بدون تکثیر `AGENTS.md` قابل مشاهده نگه می‌دارد. ## افزودن Codex در کنار مدل‌های دیگر -اگر همان عامل باید بتواند آزادانه بین Codex و مدل‌های ارائه‌دهندهٔ غیر Codex جابه‌جا شود، `agentRuntime.id: "codex"` را به‌صورت سراسری تنظیم نکنید. زمان‌اجرای اجباری برای هر نوبت تعبیه‌شدهٔ آن عامل یا نشست اعمال می‌شود. اگر در حالی که آن زمان‌اجرا اجباری است یک مدل Anthropic را انتخاب کنید، OpenClaw همچنان هارنس Codex را امتحان می‌کند و به‌جای مسیریابی بی‌صدا از طریق PI، بسته شکست می‌خورد. +اگر همان agent باید آزادانه بین Codex و مدل‌های provider غیر Codex جابه‌جا شود، `agentRuntime.id: "codex"` را به‌صورت سراسری تنظیم نکنید. runtime اجباری برای هر turn嵌ه‌شده آن agent یا session اعمال می‌شود. اگر در حالی که آن runtime اجباری است یک مدل Anthropic انتخاب کنید، OpenClaw همچنان harness مربوط به Codex را امتحان می‌کند و به‌جای route کردن بی‌صدا از طریق PI، به‌شکل fail-closed شکست می‌خورد. به‌جای آن از یکی از این شکل‌ها استفاده کنید: -- Codex را روی یک عامل اختصاصی با `agentRuntime.id: "codex"` قرار دهید. -- عامل پیش‌فرض را روی `agentRuntime.id: "auto"` و بازگشت جایگزین PI برای استفادهٔ معمول ترکیبی از ارائه‌دهندگان نگه دارید. -- از ارجاع‌های قدیمی `codex/*` فقط برای سازگاری استفاده کنید. پیکربندی‌های جدید باید `openai/*` به‌همراه یک سیاست صریح زمان‌اجرای Codex را ترجیح دهند. +- Codex را روی یک agent اختصاصی با `agentRuntime.id: "codex"` قرار دهید. +- agent پیش‌فرض را روی `agentRuntime.id: "auto"` و fallback مربوط به PI برای استفاده معمول mixed provider نگه دارید. +- از refهای قدیمی `codex/*` فقط برای سازگاری استفاده کنید. پیکربندی‌های جدید باید `openai/*` به‌همراه یک سیاست runtime صریح Codex را ترجیح دهند. -برای نمونه، این پیکربندی عامل پیش‌فرض را روی انتخاب خودکار معمول نگه می‌دارد و یک عامل جداگانهٔ Codex اضافه می‌کند: +برای نمونه، این پیکربندی agent پیش‌فرض را روی انتخاب خودکار عادی نگه می‌دارد و یک agent جداگانه برای Codex اضافه می‌کند: ```json5 { @@ -239,31 +317,31 @@ Codex خودش `AGENTS.md` را از طریق کشف بومی مستندات پ با این شکل: -- عامل پیش‌فرض `main` از مسیر معمول ارائه‌دهنده و بازگشت جایگزین سازگاری PI استفاده می‌کند. -- عامل `codex` از هارنس سرور برنامهٔ Codex استفاده می‌کند. -- اگر Codex برای عامل `codex` موجود یا پشتیبانی‌شده نباشد، نوبت شکست می‌خورد، نه اینکه بی‌سروصدا از PI استفاده کند. +- agent پیش‌فرض `main` از مسیر عادی provider و fallback سازگاری PI استفاده می‌کند. +- agent مربوط به `codex` از harness app-server مربوط به Codex استفاده می‌کند. +- اگر Codex برای agent مربوط به `codex` وجود نداشته باشد یا پشتیبانی نشود، turn به‌جای استفاده بی‌سروصدا از PI شکست می‌خورد. -## مسیریابی فرمان عامل +## مسیریابی فرمان‌های agent -عامل‌ها باید درخواست‌های کاربر را بر اساس نیت مسیریابی کنند، نه فقط بر اساس واژهٔ "Codex": +agentها باید درخواست‌های کاربر را بر اساس intent مسیریابی کنند، نه فقط بر اساس واژه "Codex": -| کاربر درخواست می‌کند... | عامل باید استفاده کند... | +| کاربر درخواست می‌کند... | agent باید استفاده کند از... | | ------------------------------------------------------ | ------------------------------------------------ | -| «این چت را به Codex متصل کن» | `/codex bind` | -| «نخ Codex با شناسهٔ `` را اینجا از سر بگیر» | `/codex resume ` | -| «نخ‌های Codex را نشان بده» | `/codex threads` | -| «برای یک اجرای بد Codex یک گزارش پشتیبانی ثبت کن» | `/diagnostics [note]` | -| «فقط برای این نخ پیوست‌شده بازخورد Codex بفرست» | `/codex diagnostics [note]` | -| «از اشتراک ChatGPT/Codex من با زمان‌اجرای Codex استفاده کن» | `openai/*` به‌همراه `agentRuntime.id: "codex"` | -| «از اشتراک ChatGPT/Codex من از طریق PI استفاده کن» | ارجاع‌های مدل `openai-codex/*` | -| «Codex را از طریق ACP/acpx اجرا کن» | ACP `sessions_spawn({ runtime: "acp", ... })` | -| «Claude Code/Gemini/OpenCode/Cursor را در یک نخ شروع کن» | ACP/acpx، نه `/codex` و نه زیرعامل‌های بومی | +| "Bind this chat to Codex" | `/codex bind` | +| "Resume Codex thread `` here" | `/codex resume ` | +| "Show Codex threads" | `/codex threads` | +| "File a support report for a bad Codex run" | `/diagnostics [note]` | +| "Only send Codex feedback for this attached thread" | `/codex diagnostics [note]` | +| "Use my ChatGPT/Codex subscription with Codex runtime" | `openai/*` به‌همراه `agentRuntime.id: "codex"` | +| "Use my ChatGPT/Codex subscription through PI" | refهای مدل `openai-codex/*` | +| "Run Codex through ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Start Claude Code/Gemini/OpenCode/Cursor in a thread" | ACP/acpx، نه `/codex` و نه sub-agentهای بومی | -OpenClaw فقط زمانی راهنمایی spawn در ACP را به عامل‌ها تبلیغ می‌کند که ACP فعال، قابل dispatch، و توسط یک backend زمان‌اجرای بارگذاری‌شده پشتیبانی شود. اگر ACP در دسترس نباشد، پرامپت سیستم و Skills مربوط به Plugin نباید به عامل دربارهٔ مسیریابی ACP آموزش دهند. +OpenClaw فقط وقتی راهنمایی spawn مربوط به ACP را به agentها تبلیغ می‌کند که ACP فعال، dispatchable، و با یک runtime backend بارگذاری‌شده پشتیبانی شده باشد. اگر ACP در دسترس نباشد، system prompt و plugin skills نباید به agent درباره مسیریابی ACP آموزش دهند. ## استقرارهای فقط Codex -وقتی لازم است ثابت کنید هر نوبت عامل تعبیه‌شده از Codex استفاده می‌کند، هارنس Codex را اجباری کنید. زمان‌اجراهای صریح Plugin بسته شکست می‌خورند و هرگز بی‌سروصدا از طریق PI دوباره امتحان نمی‌شوند: +وقتی باید ثابت کنید که هر turn嵌ه‌شده agent از Codex استفاده می‌کند، harness مربوط به Codex را اجباری کنید. runtimeهای صریح Plugin به‌شکل fail-closed شکست می‌خورند و هرگز بی‌سروصدا از طریق PI دوباره امتحان نمی‌شوند: ```json5 { @@ -284,11 +362,11 @@ override محیطی: OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -با اجباری شدن Codex، اگر Plugin Codex غیرفعال باشد، سرور برنامه بیش از حد قدیمی باشد، یا سرور برنامه نتواند شروع شود، OpenClaw زودهنگام شکست می‌خورد. +با اجباری شدن Codex، اگر Plugin مربوط به Codex غیرفعال باشد، app-server بیش از حد قدیمی باشد، یا app-server نتواند شروع شود، OpenClaw زود شکست می‌خورد. -## Codex برای هر عامل +## Codex به‌ازای هر agent -می‌توانید یک عامل را فقط Codex کنید، در حالی که عامل پیش‌فرض انتخاب خودکار معمول را نگه می‌دارد: +می‌توانید یک agent را فقط Codex کنید در حالی که agent پیش‌فرض انتخاب خودکار عادی را نگه می‌دارد: ```json5 { @@ -317,17 +395,17 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -برای جابه‌جایی عامل‌ها و مدل‌ها از فرمان‌های معمول نشست استفاده کنید. `/new` یک نشست تازهٔ OpenClaw ایجاد می‌کند و هارنس Codex در صورت نیاز نخ سرور برنامهٔ جانبی خود را ایجاد یا از سر می‌گیرد. `/reset` اتصال نشست OpenClaw برای آن نخ را پاک می‌کند و اجازه می‌دهد نوبت بعدی دوباره هارنس را از پیکربندی فعلی resolve کند. +برای جابه‌جایی agentها و مدل‌ها از فرمان‌های عادی session استفاده کنید. `/new` یک session تازه OpenClaw ایجاد می‌کند و harness مربوط به Codex در صورت نیاز thread جانبی app-server خود را ایجاد یا resume می‌کند. `/reset` binding مربوط به session OpenClaw را برای آن thread پاک می‌کند و اجازه می‌دهد turn بعدی دوباره harness را از پیکربندی فعلی resolve کند. ## کشف مدل -به‌طور پیش‌فرض، Plugin Codex از سرور برنامه مدل‌های موجود را می‌پرسد. اگر کشف شکست بخورد یا زمان آن تمام شود، از یک کاتالوگ جایگزین بسته‌بندی‌شده برای موارد زیر استفاده می‌کند: +به‌طور پیش‌فرض، Plugin مربوط به Codex از app-server مدل‌های در دسترس را می‌پرسد. اگر discovery شکست بخورد یا timeout شود، از یک کاتالوگ fallback همراه برای موارد زیر استفاده می‌کند: - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -می‌توانید کشف را زیر `plugins.entries.codex.config.discovery` تنظیم کنید: +می‌توانید discovery را زیر `plugins.entries.codex.config.discovery` تنظیم کنید: ```json5 { @@ -347,7 +425,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -وقتی می‌خواهید راه‌اندازی از probe کردن Codex پرهیز کند و به کاتالوگ جایگزین پایبند بماند، کشف را غیرفعال کنید: +وقتی می‌خواهید startup از probe کردن Codex پرهیز کند و به کاتالوگ fallback بچسبد، discovery را غیرفعال کنید: ```json5 { @@ -366,7 +444,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## اتصال و سیاست سرور برنامه +## اتصال و سیاست app-server به‌طور پیش‌فرض، Plugin باینری Codex مدیریت‌شده توسط OpenClaw را به‌صورت محلی با این فرمان شروع می‌کند: @@ -374,13 +452,13 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run codex app-server --listen stdio:// ``` -باینری مدیریت‌شده همراه با بستهٔ Plugin `codex` ارسال می‌شود. این کار نسخهٔ سرور برنامه را به Plugin بسته‌بندی‌شده گره می‌زند، نه به هر CLI جداگانهٔ Codex که تصادفاً به‌صورت محلی نصب شده باشد. فقط وقتی `appServer.command` را تنظیم کنید که عمداً می‌خواهید یک فایل اجرایی متفاوت را اجرا کنید. +باینری مدیریت‌شده با بسته Plugin مربوط به `codex` ارسال می‌شود. این کار نسخه app-server را به Plugin همراه گره می‌زند، نه به هر Codex CLI جداگانه‌ای که اتفاقاً به‌صورت محلی نصب شده باشد. فقط وقتی `appServer.command` را تنظیم کنید که عمداً می‌خواهید یک executable متفاوت اجرا کنید. -به‌طور پیش‌فرض، OpenClaw نشست‌های محلی هارنس Codex را در حالت YOLO شروع می‌کند: +به‌طور پیش‌فرض، OpenClaw جلسه‌های محلی harness مربوط به Codex را در حالت YOLO شروع می‌کند: `approvalPolicy: "never"`، `approvalsReviewer: "user"`، و -`sandbox: "danger-full-access"`. این وضعیت اپراتور محلی مورد اعتماد است که برای Heartbeatهای خودکار استفاده می‌شود: Codex می‌تواند از ابزارهای shell و شبکه استفاده کند، بدون اینکه روی پرامپت‌های تأیید بومی که کسی برای پاسخ دادن به آن‌ها حضور ندارد متوقف شود. +`sandbox: "danger-full-access"`. این وضعیت operator محلی مورد اعتماد است که برای Heartbeatهای خودمختار استفاده می‌شود: Codex می‌تواند از ابزارهای shell و network استفاده کند بدون اینکه روی promptهای approval بومی متوقف شود که کسی برای پاسخ‌دادن به آن‌ها حاضر نیست. -برای opt in به تأییدهای بازبینی‌شده توسط guardian در Codex، `appServer.mode: +برای ورود به approvalهای بازبینی‌شده توسط guardian مربوط به Codex، `appServer.mode: "guardian"` را تنظیم کنید: ```json5 @@ -401,14 +479,14 @@ codex app-server --listen stdio:// } ``` -حالت Guardian از مسیر تأیید auto-review بومی Codex استفاده می‌کند. وقتی Codex درخواست خروج از sandbox، نوشتن بیرون از فضای کاری، یا افزودن مجوزهایی مانند دسترسی شبکه را بدهد، Codex آن درخواست تأیید را به‌جای پرامپت انسانی به بازبین بومی مسیریابی می‌کند. بازبین چارچوب ریسک Codex را اعمال می‌کند و درخواست مشخص را تأیید یا رد می‌کند. وقتی به حفاظ‌های بیشتری نسبت به حالت YOLO نیاز دارید اما همچنان لازم است عامل‌های بدون نظارت پیشرفت کنند، از Guardian استفاده کنید. +حالت Guardian از مسیر approval بازبینی خودکار بومی Codex استفاده می‌کند. وقتی Codex درخواست خروج از sandbox، نوشتن بیرون از فضای کاری، یا افزودن permissionهایی مانند دسترسی network را می‌دهد، Codex آن درخواست approval را به‌جای prompt انسانی به reviewer بومی مسیریابی می‌کند. reviewer چارچوب ریسک Codex را اعمال می‌کند و درخواست مشخص را approve یا deny می‌کند. وقتی guardrailهای بیشتری نسبت به حالت YOLO می‌خواهید اما همچنان نیاز دارید agentهای بدون مراقبت پیشرفت کنند، از Guardian استفاده کنید. preset مربوط به `guardian` به `approvalPolicy: "on-request"`، `approvalsReviewer: "auto_review"`، و `sandbox: "workspace-write"` گسترش می‌یابد. -فیلدهای سیاست منفرد همچنان `mode` را override می‌کنند، بنابراین استقرارهای پیشرفته می‌توانند preset را با انتخاب‌های صریح ترکیب کنند. مقدار قدیمی‌تر بازبین `guardian_subagent` هنوز به‌عنوان alias سازگاری پذیرفته می‌شود، اما پیکربندی‌های جدید باید از +fieldهای policy جداگانه همچنان `mode` را override می‌کنند، بنابراین استقرارهای پیشرفته می‌توانند preset را با انتخاب‌های صریح ترکیب کنند. مقدار reviewer قدیمی‌تر `guardian_subagent` همچنان به‌عنوان alias سازگاری پذیرفته می‌شود، اما پیکربندی‌های جدید باید از `auto_review` استفاده کنند. -برای یک سرور برنامه که از قبل در حال اجراست، از انتقال WebSocket استفاده کنید: +برای یک app-server از قبل در حال اجرا، از transport مربوط به WebSocket استفاده کنید: ```json5 { @@ -430,28 +508,29 @@ preset مربوط به `guardian` به `approvalPolicy: "on-request"`، } ``` -راه‌اندازی‌های سرور برنامهٔ stdio به‌طور پیش‌فرض محیط فرایند OpenClaw را به ارث می‌برند، اما OpenClaw مالک پل حساب سرور برنامهٔ Codex است و هر دو `CODEX_HOME` و `HOME` را به دایرکتوری‌های مختص هر عامل زیر وضعیت OpenClaw همان عامل تنظیم می‌کند. loader بومی Skill در Codex مقدارهای `$CODEX_HOME/skills` و -`$HOME/.agents/skills` را می‌خواند، بنابراین هر دو مقدار برای راه‌اندازی‌های محلی سرور برنامه ایزوله هستند. این کار Skills، plugins، پیکربندی، حساب‌ها، و وضعیت نخ بومی Codex را به عامل OpenClaw محدود می‌کند، نه اینکه از خانهٔ شخصی CLI در Codex متعلق به اپراتور نشت کند. +راه‌اندازی‌های stdio app-server به‌طور پیش‌فرض محیط فرایند OpenClaw را به ارث می‌برند، اما OpenClaw مالک پل حساب app-server مربوط به Codex است و هر دو `CODEX_HOME` و `HOME` را روی دایرکتوری‌های مختص هر agent زیر state آن agent در OpenClaw تنظیم می‌کند. skill loader خود Codex از `$CODEX_HOME/skills` و +`$HOME/.agents/skills` می‌خواند، بنابراین هر دو مقدار برای راه‌اندازی‌های app-server محلی ایزوله هستند. این کار Skills، Pluginها، پیکربندی، حساب‌ها، و وضعیت thread بومی Codex را در محدوده agent OpenClaw نگه می‌دارد، به‌جای اینکه از خانه شخصی Codex CLI مربوط به operator نشت کنند. -OpenClaw plugins و snapshotهای Skill در OpenClaw همچنان از طریق registry مربوط به Plugin و loader مربوط به Skill خود OpenClaw جریان پیدا می‌کنند. دارایی‌های شخصی CLI در Codex چنین نمی‌کنند. اگر Skills یا plugins مفیدی در CLI مربوط به Codex دارید که باید بخشی از یک عامل OpenClaw شوند، آن‌ها را صریحاً inventory کنید: +Pluginهای OpenClaw و snapshotهای skill مربوط به OpenClaw همچنان از طریق registry Plugin و skill loader خود OpenClaw جریان پیدا می‌کنند. دارایی‌های شخصی Codex CLI این‌طور نیستند. اگر Skills یا Pluginهای مفید Codex CLI دارید که باید بخشی از یک agent در OpenClaw شوند، آن‌ها را صریحاً inventory کنید: ```bash openclaw migrate codex --dry-run openclaw migrate apply codex --yes ``` -ارائه‌دهندهٔ مهاجرت Codex، Skills را در فضای کاری عامل OpenClaw فعلی کپی می‌کند. plugins، hooks، و فایل‌های پیکربندی بومی Codex به‌جای فعال شدن خودکار، برای بازبینی دستی گزارش یا بایگانی می‌شوند، چون می‌توانند فرمان اجرا کنند، سرورهای MCP را در معرض قرار دهند، یا credentials حمل کنند. +provider مهاجرت Codex، Skills را به فضای کاری agent فعلی OpenClaw کپی می‌کند. Pluginهای بومی Codex، hookها، و فایل‌های پیکربندی به‌جای فعال‌شدن خودکار، برای بازبینی دستی گزارش یا archive می‌شوند، چون می‌توانند فرمان اجرا کنند، serverهای MCP را expose کنند، یا credential حمل کنند. احراز هویت به این ترتیب انتخاب می‌شود: -1. یک پروفایل صریح احراز هویت OpenClaw Codex برای عامل. -2. حساب موجود سرور برنامه در خانهٔ Codex همان عامل. -3. فقط برای راه‌اندازی‌های محلی سرور برنامهٔ stdio، `CODEX_API_KEY`، سپس - `OPENAI_API_KEY`، وقتی حساب سرور برنامه‌ای وجود ندارد و احراز هویت OpenAI هنوز لازم است. +1. یک پروفایل احراز هویت صریح OpenClaw Codex برای agent. +2. حساب موجود app-server در خانه Codex همان agent. +3. فقط برای راه‌اندازی‌های app-server محلی stdio، `CODEX_API_KEY`، سپس + `OPENAI_API_KEY`، وقتی هیچ حساب app-server وجود ندارد و احراز هویت OpenAI همچنان لازم است. -وقتی OpenClaw یک پروفایل احراز هویت Codex از نوع اشتراک ChatGPT ببیند، `CODEX_API_KEY` و `OPENAI_API_KEY` را از فرایند فرزند Codex که spawn شده حذف می‌کند. این کار کلیدهای API در سطح Gateway را برای embeddings یا مدل‌های مستقیم OpenAI در دسترس نگه می‌دارد، بدون اینکه نوبت‌های بومی سرور برنامهٔ Codex تصادفاً از طریق API صورت‌حساب شوند. پروفایل‌های صریح کلید API در Codex و بازگشت جایگزین کلید env در stdio محلی، به‌جای env ارث‌بری‌شدهٔ فرایند فرزند، از login سرور برنامه استفاده می‌کنند. اتصال‌های سرور برنامهٔ WebSocket بازگشت جایگزین کلید API env مربوط به Gateway را دریافت نمی‌کنند؛ از یک پروفایل احراز هویت صریح یا حساب خود سرور برنامهٔ راه‌دور استفاده کنید. +وقتی OpenClaw یک پروفایل احراز هویت Codex از نوع subscription مربوط به ChatGPT می‌بیند، `CODEX_API_KEY` و `OPENAI_API_KEY` را از فرایند فرزند Codex ایجادشده حذف می‌کند. این کار API keyهای سطح Gateway را برای embeddings یا مدل‌های مستقیم OpenAI در دسترس نگه می‌دارد، بدون اینکه turnهای app-server بومی Codex به‌اشتباه از طریق API صورت‌حساب شوند. پروفایل‌های Codex API-key صریح و fallback کلید محیطی stdio محلی، به‌جای env به‌ارث‌رسیده فرایند فرزند، از login app-server استفاده می‌کنند. اتصال‌های WebSocket app-server fallback مربوط به API-key محیط Gateway را دریافت نمی‌کنند؛ از یک پروفایل احراز هویت صریح یا حساب خود app-server remote استفاده کنید. -اگر یک استقرار به ایزوله‌سازی محیطی بیشتری نیاز دارد، آن متغیرها را به `appServer.clearEnv` اضافه کنید: +اگر یک استقرار به ایزوله‌سازی محیطی بیشتری نیاز دارد، آن متغیرها را به +`appServer.clearEnv` اضافه کنید: ```json5 { @@ -470,54 +549,53 @@ openclaw migrate apply codex --yes } ``` -`appServer.clearEnv` فقط بر فرایند فرزند app-server متعلق به Codex که ایجاد می‌شود اثر می‌گذارد. +`appServer.clearEnv` فقط بر فرایند فرزند app-server مربوط به Codex که اجرا می‌شود اثر می‌گذارد. -ابزارهای پویای Codex به‌طور پیش‌فرض از پروفایل `native-first` استفاده می‌کنند. در این حالت، -OpenClaw ابزارهای پویایی را که عملیات فضای کاری بومی Codex را تکرار می‌کنند -در معرض استفاده قرار نمی‌دهد: `read`، `write`، `edit`، `apply_patch`، `exec`، `process` و +ابزارهای پویای Codex به‌صورت پیش‌فرض از پروفایل `native-first` استفاده می‌کنند. در آن حالت، +OpenClaw ابزارهای پویایی را که عملیات workspace بومی Codex را تکرار می‌کنند +در دسترس قرار نمی‌دهد: `read`، `write`، `edit`، `apply_patch`، `exec`، `process`، و `update_plan`. ابزارهای یکپارچه‌سازی OpenClaw مانند پیام‌رسانی، نشست‌ها، رسانه، -cron، مرورگر، nodes، gateway، `heartbeat_respond` و `web_search` همچنان +cron، مرورگر، nodes، gateway، `heartbeat_respond`، و `web_search` همچنان در دسترس می‌مانند. -فیلدهای سطح بالای پشتیبانی‌شده برای Plugin کدکس: +فیلدهای سطح بالای پشتیبانی‌شده برای Plugin Codex: -| فیلد | پیش‌فرض | معنی | +| فیلد | پیش‌فرض | معنا | | -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -| `codexDynamicToolsProfile` | `"native-first"` | از `"openclaw-compat"` استفاده کنید تا مجموعه کامل ابزارهای پویای OpenClaw در اختیار app-server کدکس قرار گیرد. | -| `codexDynamicToolsExclude` | `[]` | نام ابزارهای پویای اضافی OpenClaw که باید از نوبت‌های app-server کدکس حذف شوند. | +| `codexDynamicToolsProfile` | `"native-first"` | برای در دسترس قرار دادن مجموعه کامل ابزارهای پویای OpenClaw برای Codex app-server از `"openclaw-compat"` استفاده کنید. | +| `codexDynamicToolsExclude` | `[]` | نام‌های اضافی ابزارهای پویای OpenClaw که باید از نوبت‌های Codex app-server حذف شوند. | فیلدهای پشتیبانی‌شده `appServer`: -| فیلد | پیش‌فرض | معنی | +| فیلد | پیش‌فرض | معنا | | ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` کدکس را ایجاد می‌کند؛ `"websocket"` به `url` متصل می‌شود. | -| `command` | باینری مدیریت‌شده Codex | فایل اجرایی برای انتقال stdio. برای استفاده از باینری مدیریت‌شده آن را تنظیم‌نشده بگذارید؛ فقط برای یک بازنویسی صریح آن را تنظیم کنید. | -| `args` | `["app-server", "--listen", "stdio://"]` | آرگومان‌های انتقال stdio. | -| `url` | تنظیم‌نشده | نشانی WebSocket برای app-server. | -| `authToken` | تنظیم‌نشده | توکن Bearer برای انتقال WebSocket. | +| `transport` | `"stdio"` | `"stdio"` Codex را اجرا می‌کند؛ `"websocket"` به `url` وصل می‌شود. | +| `command` | باینری مدیریت‌شده Codex | فایل اجرایی برای ترابری stdio. برای استفاده از باینری مدیریت‌شده آن را تنظیم‌نشده بگذارید؛ فقط برای بازنویسی صریح آن را تنظیم کنید. | +| `args` | `["app-server", "--listen", "stdio://"]` | آرگومان‌ها برای ترابری stdio. | +| `url` | تنظیم‌نشده | URL مربوط به WebSocket app-server. | +| `authToken` | تنظیم‌نشده | توکن Bearer برای ترابری WebSocket. | | `headers` | `{}` | هدرهای اضافی WebSocket. | -| `clearEnv` | `[]` | نام متغیرهای محیطی اضافی که پس از ساخت محیط موروثی توسط OpenClaw، از فرایند stdio app-server ایجادشده حذف می‌شوند. `CODEX_HOME` و `HOME` برای جداسازی Codex به‌ازای هر agent در راه‌اندازی‌های محلی OpenClaw رزرو شده‌اند. | -| `requestTimeoutMs` | `60000` | مهلت زمانی برای فراخوانی‌های control-plane مربوط به app-server. | -| `mode` | `"yolo"` | preset برای اجرای YOLO یا اجرای بازبینی‌شده توسط guardian. | -| `approvalPolicy` | `"never"` | سیاست تأیید بومی Codex که به شروع/ازسرگیری/نوبت thread ارسال می‌شود. | -| `sandbox` | `"danger-full-access"` | حالت sandbox بومی Codex که به شروع/ازسرگیری thread ارسال می‌شود. | -| `approvalsReviewer` | `"user"` | از `"auto_review"` استفاده کنید تا Codex اعلان‌های تأیید بومی را بازبینی کند. `guardian_subagent` همچنان یک نام مستعار قدیمی است. | -| `serviceTier` | تنظیم‌نشده | سطح سرویس اختیاری app-server کدکس: `"fast"`، `"flex"` یا `null`. مقادیر قدیمی نامعتبر نادیده گرفته می‌شوند. | +| `clearEnv` | `[]` | نام‌های اضافی متغیرهای محیطی که پس از ساخت محیط ارث‌بری‌شده توسط OpenClaw، از فرایند stdio app-server اجراشده حذف می‌شوند. `CODEX_HOME` و `HOME` برای جداسازی Codex به‌ازای هر عامل در اجرای محلی توسط OpenClaw رزرو شده‌اند. | +| `requestTimeoutMs` | `60000` | مهلت زمانی برای فراخوانی‌های control-plane مربوط به app-server. | +| `mode` | `"yolo"` | پیش‌تنظیم برای اجرای YOLO یا اجرای بازبینی‌شده توسط نگهبان. | +| `approvalPolicy` | `"never"` | سیاست تایید بومی Codex که به آغاز/ازسرگیری/نوبت thread فرستاده می‌شود. | +| `sandbox` | `"danger-full-access"` | حالت sandbox بومی Codex که به آغاز/ازسرگیری thread فرستاده می‌شود. | +| `approvalsReviewer` | `"user"` | برای اینکه Codex اعلان‌های تایید بومی را بازبینی کند از `"auto_review"` استفاده کنید. `guardian_subagent` همچنان یک نام مستعار قدیمی است. | +| `serviceTier` | تنظیم‌نشده | سطح سرویس اختیاری Codex app-server: `"fast"`، `"flex"`، یا `null`. مقادیر قدیمی نامعتبر نادیده گرفته می‌شوند. | -فراخوانی‌های ابزار پویا که متعلق به OpenClaw هستند مستقل از -`appServer.requestTimeoutMs` محدود می‌شوند: هر درخواست `item/tool/call` از Codex باید -در عرض ۳۰ ثانیه یک پاسخ OpenClaw دریافت کند. در صورت پایان مهلت، OpenClaw در جاهایی که پشتیبانی می‌شود -سیگنال ابزار را abort می‌کند و یک پاسخ ابزار پویای ناموفق به Codex برمی‌گرداند تا -نوبت بتواند ادامه یابد، به‌جای اینکه نشست در حالت `processing` باقی بماند. +فراخوانی‌های ابزار پویای متعلق به OpenClaw مستقل از +`appServer.requestTimeoutMs` محدود می‌شوند: هر درخواست Codex `item/tool/call` باید +ظرف ۳۰ ثانیه پاسخی از OpenClaw دریافت کند. هنگام timeout، OpenClaw در صورت پشتیبانی +سیگنال ابزار را لغو می‌کند و یک پاسخ ابزار پویا با شکست به Codex برمی‌گرداند تا +نوبت بتواند ادامه پیدا کند، به‌جای اینکه نشست در وضعیت `processing` باقی بماند. -پس از اینکه OpenClaw به یک درخواست app-server وابسته به نوبت Codex پاسخ می‌دهد، harness +پس از اینکه OpenClaw به یک درخواست app-server محدود به نوبت Codex پاسخ می‌دهد، harness همچنین انتظار دارد Codex نوبت بومی را با `turn/completed` تمام کند. اگر -app-server پس از آن پاسخ به مدت ۶۰ ثانیه بی‌صدا بماند، OpenClaw به‌صورت best-effort -نوبت Codex را interrupt می‌کند، یک timeout تشخیصی ثبت می‌کند، و lane نشست -OpenClaw را آزاد می‌کند تا پیام‌های گفت‌وگوی بعدی پشت یک نوبت بومی کهنه -در صف نمانند. +app-server پس از آن پاسخ برای ۶۰ ثانیه ساکت بماند، OpenClaw به‌شکل best-effort +نوبت Codex را قطع می‌کند، یک timeout تشخیصی ثبت می‌کند، و lane نشست +OpenClaw را آزاد می‌کند تا پیام‌های چت بعدی پشت یک نوبت بومی کهنه در صف نمانند. -بازنویسی‌های محیطی برای آزمایش محلی همچنان در دسترس‌اند: +بازنویسی‌های محیطی برای آزمون محلی همچنان در دسترس هستند: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -525,32 +603,30 @@ OpenClaw را آزاد می‌کند تا پیام‌های گفت‌وگوی ب - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` وقتی -`appServer.command` تنظیم‌نشده باشد، باینری مدیریت‌شده را دور می‌زند. +وقتی `appServer.command` تنظیم‌نشده باشد، `OPENCLAW_CODEX_APP_SERVER_BIN` باینری مدیریت‌شده را دور می‌زند. `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` حذف شده است. به‌جای آن از `plugins.entries.codex.config.appServer.mode: "guardian"` استفاده کنید، یا برای -آزمایش محلی یک‌باره از `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`. برای استقرارهای -تکرارپذیر، پیکربندی ترجیح داده می‌شود، چون رفتار Plugin را در همان فایل بازبینی‌شده‌ای نگه می‌دارد -که بقیه راه‌اندازی harness کدکس در آن قرار دارد. +آزمون محلی یک‌باره از `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` استفاده کنید. Config +برای استقرارهای تکرارپذیر ترجیح داده می‌شود، چون رفتار Plugin را در همان فایل +بازبینی‌شده‌ای نگه می‌دارد که بقیه راه‌اندازی harness مربوط به Codex در آن قرار دارد. ## استفاده از رایانه استفاده از رایانه در راهنمای راه‌اندازی خودش پوشش داده شده است: -[استفاده از رایانه با Codex](/fa/plugins/codex-computer-use). +[استفاده از رایانه در Codex](/fa/plugins/codex-computer-use). -نسخه کوتاه: OpenClaw برنامه کنترل دسکتاپ را vendor نمی‌کند و خودش -اقدام‌های دسکتاپ را اجرا نمی‌کند. app-server کدکس را آماده می‌کند، بررسی می‌کند که +خلاصه کوتاه: OpenClaw برنامه کنترل دسکتاپ را vendor نمی‌کند و خودش +اقدام‌های دسکتاپ را اجرا نمی‌کند. Codex app-server را آماده می‌کند، بررسی می‌کند که سرور MCP مربوط به `computer-use` در دسترس باشد، و سپس اجازه می‌دهد Codex در طول نوبت‌های حالت Codex فراخوانی‌های ابزار MCP بومی را مدیریت کند. -برای دسترسی مستقیم به درایور TryCua خارج از جریان marketplace کدکس، با -`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` -، `cua-driver mcp` را ثبت کنید. -برای تفاوت میان استفاده از رایانه تحت مالکیت Codex و ثبت مستقیم MCP، به -[استفاده از رایانه با Codex](/fa/plugins/codex-computer-use) مراجعه کنید. +برای دسترسی مستقیم به درایور TryCua خارج از جریان marketplace مربوط به Codex، +`cua-driver mcp` را با `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` ثبت کنید. +برای تفاوت میان استفاده از رایانه متعلق به Codex و ثبت مستقیم MCP، به +[استفاده از رایانه در Codex](/fa/plugins/codex-computer-use) مراجعه کنید. -پیکربندی حداقلی: +Config حداقلی: ```json5 { @@ -584,23 +660,24 @@ OpenClaw را آزاد می‌کند تا پیام‌های گفت‌وگوی ب - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -استفاده از رایانه مختص macOS است و ممکن است پیش از آنکه -سرور MCP کدکس بتواند برنامه‌ها را کنترل کند، به مجوزهای محلی OS نیاز داشته باشد. اگر `computerUse.enabled` برابر true باشد و سرور MCP -در دسترس نباشد، نوبت‌های حالت Codex پیش از شروع thread شکست می‌خورند، به‌جای اینکه -بی‌صدا بدون ابزارهای بومی استفاده از رایانه اجرا شوند. برای گزینه‌های marketplace، -محدودیت‌های کاتالوگ راه دور، دلایل وضعیت، و عیب‌یابی به -[استفاده از رایانه با Codex](/fa/plugins/codex-computer-use) مراجعه کنید. +استفاده از رایانه مختص macOS است و ممکن است قبل از اینکه سرور MCP مربوط به +Codex بتواند برنامه‌ها را کنترل کند، به مجوزهای محلی OS نیاز داشته باشد. اگر +`computerUse.enabled` برابر true باشد و سرور MCP در دسترس نباشد، نوبت‌های حالت +Codex پیش از شروع thread شکست می‌خورند، به‌جای اینکه بی‌صدا بدون ابزارهای بومی +استفاده از رایانه اجرا شوند. برای گزینه‌های marketplace، محدودیت‌های کاتالوگ +راه‌دور، دلایل وضعیت، و عیب‌یابی به +[استفاده از رایانه در Codex](/fa/plugins/codex-computer-use) مراجعه کنید. -وقتی `computerUse.autoInstall` برابر true باشد، اگر Codex -هنوز یک marketplace محلی را کشف نکرده باشد، OpenClaw می‌تواند marketplace استاندارد -باندل‌شده Codex Desktop را از -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` ثبت کند. پس از -تغییر پیکربندی runtime یا استفاده از رایانه، از `/new` یا `/reset` استفاده کنید تا -نشست‌های موجود binding قدیمی PI یا thread کدکس را نگه ندارند. +وقتی `computerUse.autoInstall` برابر true باشد، OpenClaw می‌تواند marketplace +استاندارد همراه Codex Desktop را از +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` ثبت کند، اگر Codex +هنوز یک marketplace محلی پیدا نکرده باشد. پس از تغییر config مربوط به runtime یا +استفاده از رایانه، از `/new` یا `/reset` استفاده کنید تا نشست‌های موجود یک اتصال +قدیمی PI یا thread مربوط به Codex را نگه ندارند. ## دستورالعمل‌های رایج -Codex محلی با انتقال stdio پیش‌فرض: +Codex محلی با ترابری stdio پیش‌فرض: ```json5 { @@ -636,7 +713,7 @@ Codex محلی با انتقال stdio پیش‌فرض: } ``` -تأییدهای Codex بازبینی‌شده توسط guardian: +تاییدهای Codex بازبینی‌شده توسط نگهبان: ```json5 { @@ -658,7 +735,7 @@ Codex محلی با انتقال stdio پیش‌فرض: } ``` -app-server راه دور با هدرهای صریح: +app-server راه‌دور با هدرهای صریح: ```json5 { @@ -681,222 +758,228 @@ app-server راه دور با هدرهای صریح: } ``` -تعویض مدل تحت کنترل OpenClaw باقی می‌ماند. وقتی یک نشست OpenClaw به یک -thread موجود Codex متصل است، نوبت بعدی مدل OpenAI، provider، سیاست تأیید، -sandbox و سطح سرویس انتخاب‌شده فعلی را دوباره به app-server ارسال می‌کند. -تعویض از `openai/gpt-5.5` به `openai/gpt-5.2` اتصال thread را نگه می‌دارد اما -از Codex می‌خواهد با مدل تازه انتخاب‌شده ادامه دهد. +تعویض مدل تحت کنترل OpenClaw باقی می‌ماند. وقتی یک نشست OpenClaw به یک thread +موجود Codex متصل باشد، نوبت بعدی دوباره مدل OpenAI، ارائه‌دهنده، سیاست تایید، +sandbox، و سطح سرویس انتخاب‌شده فعلی را به app-server می‌فرستد. تعویض از +`openai/gpt-5.5` به `openai/gpt-5.2` اتصال thread را نگه می‌دارد، اما از Codex +می‌خواهد با مدل تازه انتخاب‌شده ادامه دهد. ## فرمان Codex -Plugin باندل‌شده، `/codex` را به‌عنوان یک فرمان slash مجاز ثبت می‌کند. این فرمان -عمومی است و روی هر کانالی که از فرمان‌های متنی OpenClaw پشتیبانی می‌کند کار می‌کند. +Plugin همراه، `/codex` را به‌عنوان یک فرمان slash مجاز ثبت می‌کند. این فرمان +عمومی است و روی هر کانالی که از فرمان‌های متنی OpenClaw پشتیبانی کند کار می‌کند. شکل‌های رایج: -- `/codex status` اتصال زنده app-server، مدل‌ها، حساب، محدودیت‌های نرخ، سرورهای MCP، و Skills را نشان می‌دهد. -- `/codex models` مدل‌های زنده Codex app-server را فهرست می‌کند. +- `/codex status` اتصال زنده به سرور برنامه، مدل‌ها، حساب، محدودیت‌های نرخ، سرورهای MCP و skills را نشان می‌دهد. +- `/codex models` مدل‌های زنده سرور برنامه Codex را فهرست می‌کند. - `/codex threads [filter]` رشته‌های اخیر Codex را فهرست می‌کند. - `/codex resume ` نشست فعلی OpenClaw را به یک رشته موجود Codex متصل می‌کند. -- `/codex compact` از Codex app-server می‌خواهد رشته متصل‌شده را compact کند. +- `/codex compact` از سرور برنامه Codex می‌خواهد رشته متصل‌شده را فشرده کند. - `/codex review` بازبینی بومی Codex را برای رشته متصل‌شده آغاز می‌کند. -- `/codex diagnostics [note]` پیش از ارسال بازخورد تشخیصی Codex برای رشته متصل‌شده درخواست تأیید می‌کند. +- `/codex diagnostics [note]` پیش از ارسال بازخورد عیب‌یابی Codex برای رشته متصل‌شده سؤال می‌کند. - `/codex computer-use status` Plugin پیکربندی‌شده Computer Use و سرور MCP را بررسی می‌کند. - `/codex computer-use install` Plugin پیکربندی‌شده Computer Use را نصب می‌کند و سرورهای MCP را دوباره بارگذاری می‌کند. - `/codex account` وضعیت حساب و محدودیت نرخ را نشان می‌دهد. -- `/codex mcp` وضعیت سرور MCP مربوط به Codex app-server را فهرست می‌کند. -- `/codex skills` Skills مربوط به Codex app-server را فهرست می‌کند. +- `/codex mcp` وضعیت سرور MCP سرور برنامه Codex را فهرست می‌کند. +- `/codex skills` skills سرور برنامه Codex را فهرست می‌کند. -### گردش‌کار رایج عیب‌یابی +وقتی Codex یک شکست محدودیت مصرف را گزارش می‌کند، اگر Codex زمان بازنشانی بعدی +سرور برنامه را ارائه کرده باشد، OpenClaw آن را نیز درج می‌کند. از `/codex account` در همان +گفت‌وگو استفاده کنید تا حساب فعلی و بازه‌های محدودیت نرخ را بررسی کنید. -وقتی یک عامل پشتیبانی‌شده با Codex در Telegram، Discord، Slack، -یا کانالی دیگر کاری غیرمنتظره انجام می‌دهد، از همان گفت‌وگویی شروع کنید که مشکل در آن رخ داده است: +### روند رایج اشکال‌زدایی + +وقتی یک عامل مبتنی بر Codex در Telegram، Discord، Slack +یا کانالی دیگر رفتاری غیرمنتظره انجام می‌دهد، از گفت‌وگویی شروع کنید که مشکل در آن رخ داده است: 1. دستور `/diagnostics bad tool choice after image upload` یا یادداشت کوتاه دیگری را اجرا کنید - که آنچه دیده‌اید را توصیف کند. -2. درخواست تشخیص را یک‌بار تأیید کنید. این تأیید، فایل zip تشخیص محلی Gateway - را می‌سازد و چون نشست از هارنس Codex استفاده می‌کند، بسته بازخورد مرتبط Codex را نیز - به سرورهای OpenAI می‌فرستد. -3. پاسخ تکمیل‌شده تشخیص را در گزارش باگ یا رشته پشتیبانی کپی کنید. + که چیزی را که دیده‌اید توصیف کند. +2. درخواست عیب‌یابی را یک‌بار تأیید کنید. تأیید، فایل فشرده عیب‌یابی Gateway محلی + را ایجاد می‌کند و چون نشست از چارچوب اجرای Codex استفاده می‌کند، + بسته بازخورد مرتبط Codex را نیز به سرورهای OpenAI می‌فرستد. +3. پاسخ کامل‌شده عیب‌یابی را در گزارش باگ یا رشته پشتیبانی کپی کنید. این پاسخ شامل مسیر بسته محلی، خلاصه حریم خصوصی، شناسه‌های نشست OpenClaw، - شناسه‌های رشته Codex، و یک خط `Inspect locally` برای هر رشته Codex است. -4. اگر می‌خواهید خودتان اجرای برنامه را عیب‌یابی کنید، دستور چاپ‌شده `Inspect locally` - را در یک ترمینال اجرا کنید. این دستور شبیه `codex resume ` است و + شناسه‌های رشته Codex و یک خط `Inspect locally` برای هر رشته Codex است. +4. اگر می‌خواهید اجرا را خودتان اشکال‌زدایی کنید، دستور چاپ‌شده `Inspect locally` + را در ترمینال اجرا کنید. این دستور شبیه `codex resume ` است و رشته بومی Codex را باز می‌کند تا بتوانید گفت‌وگو را بررسی کنید، آن را به‌صورت محلی ادامه دهید، - یا از Codex بپرسید چرا ابزار یا برنامه خاصی را انتخاب کرده است. + یا از Codex بپرسید چرا ابزار یا طرح خاصی را انتخاب کرده است. -از `/codex diagnostics [note]` فقط زمانی استفاده کنید که مشخصاً بخواهید بازخورد Codex -برای رشته‌ای که هم‌اکنون متصل است بارگذاری شود، بدون بسته کامل تشخیص OpenClaw -Gateway. برای بیشتر گزارش‌های پشتیبانی، `/diagnostics [note]` -نقطه شروع بهتری است، چون وضعیت محلی Gateway و شناسه‌های رشته Codex را در یک پاسخ به هم وصل می‌کند. برای مدل کامل حریم خصوصی و رفتار چت گروهی، [صدور تشخیص](/fa/gateway/diagnostics) را ببینید. +فقط وقتی از `/codex diagnostics [note]` استفاده کنید که به‌طور مشخص بارگذاری بازخورد Codex +را برای رشته متصل‌شده فعلی بدون بسته کامل عیب‌یابی +Gateway مربوط به OpenClaw می‌خواهید. برای بیشتر گزارش‌های پشتیبانی، `/diagnostics [note]` +نقطه شروع بهتری است، چون وضعیت Gateway محلی و شناسه‌های رشته Codex +را در یک پاسخ به هم پیوند می‌دهد. برای مدل کامل حریم خصوصی و رفتار گروه‌گفت‌وگو، +[صادرات عیب‌یابی](/fa/gateway/diagnostics) را ببینید. -هسته OpenClaw همچنین دستور فقط‌مالک `/diagnostics [note]` را به‌عنوان فرمان عمومی -تشخیص Gateway در دسترس می‌گذارد. اعلان تأیید آن مقدمه داده‌های حساس را نشان می‌دهد، -به [صدور تشخیص](/fa/gateway/diagnostics) پیوند می‌دهد، و هر بار -`openclaw gateway diagnostics export --json` را از طریق تأیید صریح exec درخواست می‌کند. تشخیص را با یک قانون allow-all تأیید نکنید. پس از تأیید، -OpenClaw گزارشی قابل چسباندن با مسیر بسته محلی و خلاصه manifest ارسال می‌کند. وقتی نشست فعال OpenClaw از هارنس Codex استفاده می‌کند، -همان تأیید همچنین ارسال بسته‌های بازخورد مرتبط Codex به -سرورهای OpenAI را مجاز می‌کند. اعلان تأیید می‌گوید بازخورد Codex ارسال خواهد شد، اما +هسته OpenClaw همچنین دستور مالک‌محور `/diagnostics [note]` را به‌عنوان فرمان عمومی +عیب‌یابی Gateway ارائه می‌کند. اعلان تأیید آن مقدمه داده‌های حساس را نشان می‌دهد، +به [صادرات عیب‌یابی](/fa/gateway/diagnostics) پیوند می‌دهد و هر بار +از طریق تأیید صریح اجرا، درخواست `openclaw gateway diagnostics export --json` +می‌کند. عیب‌یابی را با قانون اجازه به همه تأیید نکنید. پس از تأیید، +OpenClaw گزارشی قابل چسباندن با مسیر بسته محلی و خلاصه مانیفست می‌فرستد. +وقتی نشست فعال OpenClaw از چارچوب اجرای Codex استفاده می‌کند، همان +تأیید همچنین ارسال بسته‌های بازخورد مرتبط Codex را به +سرورهای OpenAI مجاز می‌کند. اعلان تأیید می‌گوید که بازخورد Codex ارسال خواهد شد، اما پیش از تأیید، شناسه‌های نشست یا رشته Codex را فهرست نمی‌کند. -اگر `/diagnostics` توسط یک مالک در چت گروهی فراخوانی شود، OpenClaw کانال -مشترک را تمیز نگه می‌دارد: گروه فقط یک اعلان کوتاه دریافت می‌کند، در حالی که -مقدمه تشخیص، اعلان‌های تأیید، و شناسه‌های نشست/رشته Codex از طریق مسیر خصوصی تأیید برای -مالک ارسال می‌شوند. اگر مسیر خصوصی مالک وجود نداشته باشد، -OpenClaw درخواست گروهی را رد می‌کند و از مالک می‌خواهد آن را از یک DM اجرا کند. +اگر `/diagnostics` توسط یک مالک در گروه‌گفت‌وگو فراخوانی شود، OpenClaw +کانال مشترک را تمیز نگه می‌دارد: گروه فقط یک اعلان کوتاه دریافت می‌کند، درحالی‌که +مقدمه عیب‌یابی، اعلان‌های تأیید و شناسه‌های نشست/رشته Codex +از مسیر تأیید خصوصی برای مالک ارسال می‌شوند. اگر مسیر خصوصی مالک وجود نداشته باشد، +OpenClaw درخواست گروه را رد می‌کند و از مالک می‌خواهد آن را از یک پیام مستقیم اجرا کند. -بارگذاری تأییدشده Codex، مسیر `feedback/upload` در Codex app-server را فراخوانی می‌کند و از -app-server می‌خواهد در صورت امکان لاگ‌های هر رشته فهرست‌شده و زیررشته‌های Codex ایجادشده را شامل کند. بارگذاری از مسیر بازخورد عادی Codex به سرورهای OpenAI -می‌رود؛ اگر بازخورد Codex در آن app-server غیرفعال باشد، فرمان خطای -app-server را برمی‌گرداند. پاسخ تکمیل‌شده تشخیص، کانال‌ها، -شناسه‌های نشست OpenClaw، شناسه‌های رشته Codex، و فرمان‌های محلی `codex resume ` -را برای رشته‌هایی که ارسال شده‌اند فهرست می‌کند. اگر تأیید را رد یا نادیده بگیرید، -OpenClaw آن شناسه‌های Codex را چاپ نمی‌کند. این بارگذاری جایگزین صدور تشخیص محلی -Gateway نمی‌شود. +بارگذاری تأییدشده Codex، `feedback/upload` سرور برنامه Codex را فراخوانی می‌کند و از +سرور برنامه می‌خواهد در صورت امکان، گزارش‌ها را برای هر رشته فهرست‌شده و زیررشته‌های +ایجادشده Codex درج کند. این بارگذاری از مسیر عادی بازخورد Codex به سرورهای OpenAI +می‌رود؛ اگر بازخورد Codex در آن سرور برنامه غیرفعال باشد، فرمان +خطای سرور برنامه را برمی‌گرداند. پاسخ کامل‌شده عیب‌یابی، کانال‌ها، +شناسه‌های نشست OpenClaw، شناسه‌های رشته Codex و فرمان‌های محلی `codex resume ` +را برای رشته‌هایی که ارسال شدند فهرست می‌کند. اگر تأیید را رد یا نادیده بگیرید، +OpenClaw آن شناسه‌های Codex را چاپ نمی‌کند. این بارگذاری جایگزین صادرات عیب‌یابی +محلی Gateway نمی‌شود. -`/codex resume` همان فایل اتصال sidecar را می‌نویسد که هارنس برای نوبت‌های -عادی استفاده می‌کند. در پیام بعدی، OpenClaw آن رشته Codex را از سر می‌گیرد، مدل -فعلی انتخاب‌شده OpenClaw را به app-server می‌فرستد، و تاریخچه گسترده را +`/codex resume` همان فایل پیوند جانبی را می‌نویسد که چارچوب اجرا برای +نوبت‌های عادی استفاده می‌کند. در پیام بعدی، OpenClaw آن رشته Codex را از سر می‌گیرد، مدل +فعلاً انتخاب‌شده OpenClaw را به سرور برنامه می‌فرستد و تاریخچه گسترده را فعال نگه می‌دارد. ### بررسی یک رشته Codex از CLI -سریع‌ترین راه برای فهمیدن اجرای بد Codex اغلب این است که رشته بومی Codex -را مستقیماً باز کنید: +سریع‌ترین راه برای فهمیدن یک اجرای بد Codex اغلب باز کردن مستقیم رشته بومی Codex است: ```sh codex resume ``` -از این روش زمانی استفاده کنید که در یک گفت‌وگوی کانالی متوجه باگ می‌شوید و می‌خواهید نشست -مشکل‌دار Codex را بررسی کنید، آن را به‌صورت محلی ادامه دهید، یا از Codex بپرسید چرا -یک ابزار یا انتخاب استدلالی خاص انجام داده است. ساده‌ترین مسیر معمولاً این است که ابتدا -`/diagnostics [note]` را اجرا کنید: پس از تأیید شما، گزارش تکمیل‌شده -هر رشته Codex را فهرست می‌کند و یک فرمان `Inspect locally` چاپ می‌کند، مثلاً -`codex resume `. می‌توانید همان فرمان را مستقیماً در یک ترمینال کپی کنید. +وقتی در گفت‌وگوی یک کانال متوجه باگی می‌شوید و می‌خواهید نشست مشکل‌دار Codex را بررسی کنید، +آن را به‌صورت محلی ادامه دهید، یا از Codex بپرسید چرا یک انتخاب خاص ابزار یا استدلال انجام داده است، +از این استفاده کنید. ساده‌ترین مسیر معمولاً این است که ابتدا +`/diagnostics [note]` را اجرا کنید: پس از تأیید شما، گزارش کامل‌شده +هر رشته Codex را فهرست می‌کند و یک فرمان `Inspect locally` چاپ می‌کند، برای مثال +`codex resume `. می‌توانید آن فرمان را مستقیم در ترمینال کپی کنید. -همچنین می‌توانید شناسه رشته را از `/codex binding` برای چت فعلی یا -`/codex threads [filter]` برای رشته‌های اخیر Codex app-server بگیرید، سپس همان -فرمان `codex resume` را در shell خود اجرا کنید. +همچنین می‌توانید شناسه رشته را از `/codex binding` برای گفت‌وگوی فعلی یا +`/codex threads [filter]` برای رشته‌های اخیر سرور برنامه Codex بگیرید، سپس همان +فرمان `codex resume` را در پوسته خود اجرا کنید. -سطح فرمان به Codex app-server نسخه `0.125.0` یا جدیدتر نیاز دارد. اگر یک -app-server آینده یا سفارشی آن متد JSON-RPC را ارائه نکند، متدهای کنترلی جداگانه با پیام -`unsupported by this Codex app-server` گزارش می‌شوند. +سطح فرمان به سرور برنامه Codex نسخه `0.125.0` یا جدیدتر نیاز دارد. اگر یک +سرور برنامه سفارشی یا آینده آن روش JSON-RPC را ارائه نکند، روش‌های کنترلی +جداگانه با پیام `unsupported by this Codex app-server` گزارش می‌شوند. -## مرزهای hook +## مرزهای هوک -هارنس Codex سه لایه hook دارد: +چارچوب اجرای Codex سه لایه هوک دارد: | لایه | مالک | هدف | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| hookهای Plugin در OpenClaw | OpenClaw | سازگاری محصول/Plugin در سراسر هارنس‌های PI و Codex. | -| میان‌افزار extension در Codex app-server | Pluginهای همراه OpenClaw | رفتار آداپتور هر نوبت پیرامون ابزارهای پویای OpenClaw. | -| hookهای بومی Codex | Codex | چرخه حیات سطح پایین Codex و سیاست ابزار بومی از پیکربندی Codex. | +| هوک‌های Plugin در OpenClaw | OpenClaw | سازگاری محصول/Plugin در چارچوب‌های اجرای PI و Codex. | +| میان‌افزار افزونه سرور برنامه Codex | Pluginهای همراه OpenClaw | رفتار آداپتور در هر نوبت پیرامون ابزارهای پویای OpenClaw. | +| هوک‌های بومی Codex | Codex | چرخه عمر سطح پایین Codex و سیاست ابزار بومی از پیکربندی Codex. | -OpenClaw از فایل‌های پروژه یا سراسری Codex با نام `hooks.json` برای مسیریابی -رفتار Pluginهای OpenClaw استفاده نمی‌کند. برای پل ابزار بومی و مجوز پشتیبانی‌شده، -OpenClaw پیکربندی Codex را برای هر رشته برای `PreToolUse`، `PostToolUse`، -`PermissionRequest`، و `Stop` تزریق می‌کند. hookهای دیگر Codex مانند `SessionStart` و -`UserPromptSubmit` در سطح کنترل‌های Codex باقی می‌مانند؛ آن‌ها در قرارداد v1 به‌عنوان -hookهای Plugin در OpenClaw ارائه نمی‌شوند. +OpenClaw از فایل‌های پروژه یا سراسری Codex به نام `hooks.json` برای مسیریابی +رفتار Pluginهای OpenClaw استفاده نمی‌کند. برای ابزار بومی پشتیبانی‌شده و پل مجوز، +OpenClaw پیکربندی Codex را برای هر رشته به `PreToolUse`، `PostToolUse`، +`PermissionRequest` و `Stop` تزریق می‌کند. هوک‌های دیگر Codex مانند `SessionStart` و +`UserPromptSubmit` کنترل‌های سطح Codex باقی می‌مانند؛ آن‌ها در قرارداد v1 +به‌عنوان هوک‌های Plugin در OpenClaw ارائه نمی‌شوند. -برای ابزارهای پویای OpenClaw، OpenClaw پس از اینکه Codex درخواست فراخوانی می‌دهد، -ابزار را اجرا می‌کند؛ بنابراین OpenClaw رفتار Plugin و میان‌افزاری را که مالک آن است در -آداپتور هارنس اجرا می‌کند. برای ابزارهای بومی Codex، Codex مالک رکورد رسمی ابزار است. -OpenClaw می‌تواند رویدادهای منتخب را بازتاب دهد، اما نمی‌تواند رشته بومی Codex -را بازنویسی کند مگر اینکه Codex آن عملیات را از طریق app-server یا callbackهای hook بومی -ارائه دهد. +برای ابزارهای پویای OpenClaw، پس از اینکه Codex درخواست فراخوانی را می‌دهد، +OpenClaw ابزار را اجرا می‌کند؛ بنابراین OpenClaw رفتار Plugin و میان‌افزاری را که مالک آن است +در آداپتور چارچوب اجرا فعال می‌کند. برای ابزارهای بومی Codex، Codex رکورد معتبر ابزار را مالک است. +OpenClaw می‌تواند رویدادهای انتخاب‌شده را بازتاب دهد، اما نمی‌تواند رشته بومی Codex +را بازنویسی کند مگر اینکه Codex آن عملیات را از طریق سرور برنامه یا callbackهای هوک بومی ارائه کند. -پروژکشن‌های Compaction و چرخه حیات LLM از اعلان‌های Codex app-server -و وضعیت آداپتور OpenClaw می‌آیند، نه از فرمان‌های hook بومی Codex. -رویدادهای `before_compaction`، `after_compaction`، `llm_input`، و -`llm_output` در OpenClaw مشاهده‌های سطح آداپتور هستند، نه ضبط بایت‌به‌بایت -درخواست داخلی یا payloadهای Compaction در Codex. +پرتاب‌های Compaction و چرخه عمر LLM از اعلان‌های سرور برنامه Codex +و وضعیت آداپتور OpenClaw می‌آیند، نه از فرمان‌های هوک بومی Codex. +رویدادهای `before_compaction`، `after_compaction`، `llm_input` و +`llm_output` در OpenClaw مشاهده‌های سطح آداپتور هستند، نه برداشت‌های بایت‌به‌بایت +از درخواست داخلی یا بار Compaction در Codex. -اعلان‌های Codex app-server برای `hook/started` و `hook/completed` بومی Codex -به‌عنوان رویدادهای عامل `codex_app_server.hook` برای trajectory و عیب‌یابی -پروژه می‌شوند. آن‌ها hookهای Plugin در OpenClaw را فراخوانی نمی‌کنند. +اعلان‌های سرور برنامه بومی Codex به نام‌های `hook/started` و `hook/completed` +به‌عنوان رویدادهای عامل `codex_app_server.hook` برای مسیر حرکت و اشکال‌زدایی +بازتاب داده می‌شوند. آن‌ها هوک‌های Plugin در OpenClaw را فراخوانی نمی‌کنند. ## قرارداد پشتیبانی V1 -حالت Codex، PI با یک فراخوانی مدل متفاوت در زیر آن نیست. Codex مالک بخش بیشتری از -حلقه مدل بومی است، و OpenClaw سطح‌های Plugin و نشست خود را پیرامون آن مرز -سازگار می‌کند. +حالت Codex همان PI با یک فراخوانی مدل متفاوت در زیر آن نیست. Codex بخش بیشتری از +حلقه مدل بومی را مالک است، و OpenClaw سطح‌های Plugin و نشست خود را +پیرامون آن مرز تطبیق می‌دهد. -پشتیبانی‌شده در runtime v1 مربوط به Codex: +پشتیبانی‌شده در زمان اجرای Codex نسخه v1: -| سطح | پشتیبانی | دلیل | -| -------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| حلقه مدل OpenAI از طریق Codex | پشتیبانی می‌شود | Codex app-server مالک نوبت OpenAI، ازسرگیری رشته بومی، و ادامه ابزار بومی است. | -| مسیریابی و تحویل کانال OpenClaw | پشتیبانی می‌شود | Telegram، Discord، Slack، WhatsApp، iMessage، و کانال‌های دیگر بیرون از runtime مدل باقی می‌مانند. | -| ابزارهای پویای OpenClaw | پشتیبانی می‌شود | Codex از OpenClaw می‌خواهد این ابزارها را اجرا کند، بنابراین OpenClaw در مسیر اجرا باقی می‌ماند. | -| Pluginهای prompt و context | پشتیبانی می‌شود | OpenClaw overlayهای prompt را می‌سازد و پیش از شروع یا ازسرگیری رشته، context را در نوبت Codex پروژه می‌کند. | -| چرخه حیات موتور context | پشتیبانی می‌شود | assemble، ingest یا نگه‌داری پس از نوبت، و هماهنگی Compaction موتور context برای نوبت‌های Codex اجرا می‌شوند. | -| hookهای ابزار پویا | پشتیبانی می‌شود | `before_tool_call`، `after_tool_call`، و میان‌افزار نتیجه ابزار پیرامون ابزارهای پویای تحت مالکیت OpenClaw اجرا می‌شوند. | -| hookهای چرخه حیات | به‌عنوان مشاهده‌های آداپتور پشتیبانی می‌شود | `llm_input`، `llm_output`، `agent_end`، `before_compaction`، و `after_compaction` با payloadهای صادقانه حالت Codex اجرا می‌شوند. | -| gate بازبینی پاسخ نهایی | از طریق رله hook بومی پشتیبانی می‌شود | `Stop` در Codex به `before_agent_finalize` رله می‌شود؛ `revise` از Codex یک گذر مدل دیگر پیش از نهایی‌سازی درخواست می‌کند. | -| shell، patch، و MCP بومی برای مسدودسازی یا مشاهده | از طریق رله hook بومی پشتیبانی می‌شود | `PreToolUse` و `PostToolUse` در Codex برای سطح‌های ابزار بومی commit‌شده رله می‌شوند، از جمله payloadهای MCP روی Codex app-server نسخه `0.125.0` یا جدیدتر. مسدودسازی پشتیبانی می‌شود؛ بازنویسی آرگومان پشتیبانی نمی‌شود. | -| سیاست مجوز بومی | از طریق رله hook بومی پشتیبانی می‌شود | وقتی runtime آن را ارائه کند، `PermissionRequest` در Codex می‌تواند از طریق سیاست OpenClaw مسیریابی شود. اگر OpenClaw تصمیمی برنگرداند، Codex از مسیر عادی guardian یا تأیید کاربر ادامه می‌دهد. | -| ثبت trajectory در app-server | پشتیبانی می‌شود | OpenClaw درخواستی را که به app-server فرستاده و اعلان‌های app-server دریافتی را ثبت می‌کند. | +| سطح | پشتیبانی | دلیل | +| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| حلقه مدل OpenAI از طریق Codex | پشتیبانی‌شده | سرور برنامه Codex نوبت OpenAI، ازسرگیری رشته بومی و ادامه ابزار بومی را مالک است. | +| مسیریابی و تحویل کانال OpenClaw | پشتیبانی‌شده | Telegram، Discord، Slack، WhatsApp، iMessage و کانال‌های دیگر بیرون از زمان اجرای مدل می‌مانند. | +| ابزارهای پویای OpenClaw | پشتیبانی‌شده | Codex از OpenClaw می‌خواهد این ابزارها را اجرا کند، بنابراین OpenClaw در مسیر اجرا باقی می‌ماند. | +| Pluginهای اعلان و زمینه | پشتیبانی‌شده | OpenClaw لایه‌های اعلان را می‌سازد و پیش از شروع یا ازسرگیری رشته، زمینه را به نوبت Codex پرتاب می‌کند. | +| چرخه عمر موتور زمینه | پشتیبانی‌شده | سرهم‌بندی، دریافت یا نگهداری پس از نوبت، و هماهنگی Compaction موتور زمینه برای نوبت‌های Codex اجرا می‌شوند. | +| هوک‌های ابزار پویا | پشتیبانی‌شده | `before_tool_call`، `after_tool_call` و میان‌افزار نتیجه ابزار پیرامون ابزارهای پویای تحت مالکیت OpenClaw اجرا می‌شوند. | +| هوک‌های چرخه عمر | پشتیبانی‌شده به‌عنوان مشاهده‌های آداپتور | `llm_input`، `llm_output`، `agent_end`، `before_compaction` و `after_compaction` با بارهای صادقانه حالت Codex فعال می‌شوند. | +| دروازه بازبینی پاسخ نهایی | پشتیبانی‌شده از طریق رله هوک بومی | `Stop` در Codex به `before_agent_finalize` رله می‌شود؛ `revise` از Codex یک گذر مدل دیگر پیش از نهایی‌سازی درخواست می‌کند. | +| مسدودسازی یا مشاهده پوسته، وصله و MCP بومی | پشتیبانی‌شده از طریق رله هوک بومی | `PreToolUse` و `PostToolUse` در Codex برای سطح‌های ابزار بومی ثبت‌شده، از جمله بارهای MCP در سرور برنامه Codex نسخه `0.125.0` یا جدیدتر، رله می‌شوند. مسدودسازی پشتیبانی می‌شود؛ بازنویسی آرگومان نه. | +| سیاست مجوز بومی | پشتیبانی‌شده از طریق رله هوک بومی | `PermissionRequest` در Codex در جایی که زمان اجرا آن را ارائه کند، می‌تواند از مسیر سیاست OpenClaw عبور کند. اگر OpenClaw تصمیمی برنگرداند، Codex از مسیر عادی نگهبان یا تأیید کاربر خود ادامه می‌دهد. | +| ضبط مسیر حرکت سرور برنامه | پشتیبانی‌شده | OpenClaw درخواستی را که به سرور برنامه فرستاده و اعلان‌هایی را که از سرور برنامه دریافت می‌کند، ثبت می‌کند. | -پشتیبانی‌نشده در runtime v1 مربوط به Codex: +پشتیبانی‌نشده در زمان اجرای Codex نسخه v1: -| سطح | مرز V1 | مسیر آینده | +| سطح | مرز V1 | مسیر آینده | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| جهش آرگومان ابزار بومی | هوک‌های بومی پیشاابزار Codex می‌توانند مسدود کنند، اما OpenClaw آرگومان‌های ابزار بومی Codex را بازنویسی نمی‌کند. | نیازمند پشتیبانی هوک/اسکیمای Codex برای جایگزینی ورودی ابزار است. | -| تاریخچه قابل‌ویرایش رونوشت بومی Codex | Codex مالک تاریخچه بومی متعارف رشته است. OpenClaw مالک یک آینه است و می‌تواند زمینه آینده را تصویر کند، اما نباید بخش‌های داخلی پشتیبانی‌نشده را جهش دهد. | اگر جراحی رشته بومی لازم باشد، APIهای صریح app-server در Codex اضافه شود. | -| `tool_result_persist` برای رکوردهای ابزار بومی Codex | آن هوک نوشتن‌های رونوشت متعلق به OpenClaw را تبدیل می‌کند، نه رکوردهای ابزار بومی Codex را. | می‌تواند رکوردهای تبدیل‌شده را آینه کند، اما بازنویسی متعارف نیازمند پشتیبانی Codex است. | -| فراداده غنی Compaction بومی | OpenClaw شروع و پایان Compaction را مشاهده می‌کند، اما فهرست پایدار نگه‌داشته/حذف‌شده، دلتای توکن، یا بار خلاصه دریافت نمی‌کند. | نیازمند رویدادهای غنی‌تر Compaction در Codex است. | -| مداخله در Compaction | هوک‌های فعلی Compaction در OpenClaw در حالت Codex در سطح اعلان هستند. | اگر plugins باید Compaction بومی را وتو یا بازنویسی کنند، هوک‌های پیشا/پسا Compaction در Codex اضافه شود. | -| ضبط درخواست API مدل به‌صورت بایت‌به‌بایت | OpenClaw می‌تواند درخواست‌ها و اعلان‌های app-server را ضبط کند، اما هسته Codex درخواست نهایی API در OpenAI را به‌صورت داخلی می‌سازد. | نیازمند رویداد رهگیری درخواست مدل در Codex یا API اشکال‌زدایی است. | +| تغییر آرگومان ابزار بومی | قلاب‌های بومی پیش‌ابزار Codex می‌توانند مسدود کنند، اما OpenClaw آرگومان‌های ابزار بومی Codex را بازنویسی نمی‌کند. | به پشتیبانی قلاب/طرحواره Codex برای جایگزینی ورودی ابزار نیاز دارد. | +| تاریخچه قابل ویرایش رونوشت بومی Codex | Codex مالک تاریخچه رسمی رشته بومی است. OpenClaw مالک یک آینه است و می‌تواند زمینه آینده را تصویر کند، اما نباید داخلیات پشتیبانی‌نشده را تغییر دهد. | اگر جراحی رشته بومی لازم باشد، APIهای صریح سرور برنامه Codex را اضافه کنید. | +| `tool_result_persist` برای رکوردهای ابزار بومی Codex | آن قلاب نوشتن‌های رونوشتِ تحت مالکیت OpenClaw را تبدیل می‌کند، نه رکوردهای ابزار بومی Codex را. | می‌تواند رکوردهای تبدیل‌شده را آینه کند، اما بازنویسی رسمی به پشتیبانی Codex نیاز دارد. | +| فراداده غنی Compaction بومی | OpenClaw شروع و تکمیل Compaction را مشاهده می‌کند، اما فهرست پایدارِ نگه‌داشته/حذف‌شده، دلتای توکن، یا بار خلاصه دریافت نمی‌کند. | به رویدادهای غنی‌تر Compaction در Codex نیاز دارد. | +| مداخله در Compaction | قلاب‌های فعلی Compaction در OpenClaw در حالت Codex در سطح اعلان هستند. | اگر plugins باید بتوانند Compaction بومی را وتو یا بازنویسی کنند، قلاب‌های پیش/پس از Compaction در Codex را اضافه کنید. | +| ضبط درخواست API مدل به‌صورت بایت‌به‌بایت | OpenClaw می‌تواند درخواست‌ها و اعلان‌های سرور برنامه را ضبط کند، اما هسته Codex درخواست نهایی OpenAI API را به‌صورت داخلی می‌سازد. | به رویداد ردگیری درخواست مدل Codex یا API اشکال‌زدایی نیاز دارد. | ## ابزارها، رسانه، و Compaction -هارنس Codex فقط اجراکننده عامل تعبیه‌شده سطح پایین را تغییر می‌دهد. +مهار Codex فقط اجراکننده عامل تعبیه‌شده سطح پایین را تغییر می‌دهد. -OpenClaw همچنان فهرست ابزار را می‌سازد و نتایج ابزار پویا را از -هارنس دریافت می‌کند. متن، تصویر، ویدئو، موسیقی، TTS، تأییدها، و خروجی ابزار پیام‌رسانی +OpenClaw همچنان فهرست ابزارها را می‌سازد و نتایج ابزار پویا را از +مهار دریافت می‌کند. متن، تصویرها، ویدئو، موسیقی، TTS، تأییدها، و خروجی ابزار پیام‌رسانی از مسیر تحویل عادی OpenClaw ادامه پیدا می‌کنند. -رله هوک بومی عمداً عمومی است، اما قرارداد پشتیبانی v1 -به مسیرهای ابزار و مجوز بومی Codex محدود است که OpenClaw آن‌ها را آزمایش می‌کند. در -زمان‌اجرای Codex، این شامل payloadهای shell، patch، و MCP `PreToolUse`، -`PostToolUse`، و `PermissionRequest` است. فرض نکنید هر رویداد هوک آینده -Codex یک سطح Plugin در OpenClaw است، مگر اینکه قرارداد زمان‌اجرا -آن را نام ببرد. +رله قلاب بومی عمداً عمومی است، اما قرارداد پشتیبانی v1 +به مسیرهای ابزار و مجوز بومی Codex محدود است که OpenClaw آزمایش می‌کند. در +زمان اجرای Codex، این شامل بارهای shell، patch، و MCP `PreToolUse`، +`PostToolUse`، و `PermissionRequest` است. فرض نکنید هر رویداد قلاب آینده +Codex یک سطح Plugin در OpenClaw است، مگر اینکه قرارداد زمان اجرا آن را نام ببرد. -برای `PermissionRequest`، OpenClaw فقط زمانی تصمیم‌های صریح اجازه یا رد را برمی‌گرداند -که سیاست تصمیم بگیرد. نتیجه بدون تصمیم اجازه نیست. Codex آن را به‌عنوان نبود -تصمیم هوک در نظر می‌گیرد و به مسیر نگهبان یا تأیید کاربر خودش ادامه می‌دهد. +برای `PermissionRequest`، OpenClaw فقط وقتی سیاست تصمیم بگیرد، تصمیم‌های صریح اجازه یا رد را +برمی‌گرداند. نتیجه بدون تصمیم، اجازه نیست. Codex آن را به‌عنوان نبود تصمیم قلاب +در نظر می‌گیرد و به مسیر نگهبان خودش یا تأیید کاربر ادامه می‌دهد. -درخواست‌های تأیید ابزار MCP در Codex از مسیر جریان تأیید Plugin در OpenClaw -هدایت می‌شوند، وقتی Codex مقدار `_meta.codex_approval_kind` را برابر -`"mcp_tool_call"` علامت‌گذاری کند. اعلان‌های Codex `request_user_input` به گفت‌وگوی -مبدأ فرستاده می‌شوند، و پیام پیگیری بعدی در صف به آن درخواست سرور بومی -پاسخ می‌دهد، به‌جای اینکه به‌عنوان زمینه اضافی هدایت شود. سایر درخواست‌های elicitation در MCP +درخواست‌های تأیید ابزار Codex MCP از طریق جریان تأیید Plugin در OpenClaw +مسیریابی می‌شوند، وقتی Codex مقدار `_meta.codex_approval_kind` را +`"mcp_tool_call"` علامت‌گذاری کند. اعلان‌های Codex `request_user_input` به +گفت‌وگوی مبدأ بازفرستاده می‌شوند، و پیام پیگیری بعدی در صف به آن درخواست سرور بومی +پاسخ می‌دهد، به‌جای اینکه به‌عنوان زمینه اضافی هدایت شود. درخواست‌های دیگر MCP elicitation همچنان به‌صورت بسته شکست می‌خورند. -هدایت صف اجرای فعال روی Codex app-server `turn/steer` نگاشت می‌شود. با -پیش‌فرض `messages.queue.mode: "steer"`، OpenClaw پیام‌های گفت‌وگوی صف‌شده را -برای پنجره سکوت پیکربندی‌شده دسته‌بندی می‌کند و آن‌ها را به‌ترتیب ورود به‌عنوان یک درخواست `turn/steer` -می‌فرستد. حالت قدیمی `queue` درخواست‌های جداگانه `turn/steer` می‌فرستد. نوبت‌های بازبینی Codex -و Compaction دستی می‌توانند هدایت همان نوبت را رد کنند، که در این حالت -OpenClaw وقتی حالت انتخاب‌شده fallback را اجازه دهد از صف followup استفاده می‌کند. [صف هدایت](/fa/concepts/queue-steering) را ببینید. +هدایت صف اجرای فعال به Codex app-server `turn/steer` نگاشت می‌شود. با +پیش‌فرض `messages.queue.mode: "steer"`، OpenClaw پیام‌های گفت‌وگوی در صف را +برای پنجره سکوت پیکربندی‌شده دسته‌بندی می‌کند و آن‌ها را به‌ترتیب ورود به‌عنوان یک درخواست +`turn/steer` می‌فرستد. حالت قدیمی `queue` درخواست‌های جداگانه `turn/steer` می‌فرستد. نوبت‌های +بازبینی Codex و Compaction دستی می‌توانند هدایت همان نوبت را رد کنند، که در این حالت +OpenClaw وقتی حالت انتخاب‌شده اجازه جایگزین را بدهد از صف پیگیری استفاده می‌کند. ببینید +[صف هدایت](/fa/concepts/queue-steering). -وقتی مدل انتخاب‌شده از هارنس Codex استفاده می‌کند، Compaction رشته بومی به +وقتی مدل انتخاب‌شده از مهار Codex استفاده می‌کند، Compaction رشته بومی به Codex app-server واگذار می‌شود. OpenClaw یک آینه رونوشت برای تاریخچه کانال، -جست‌وجو، `/new`، `/reset`، و تغییر آینده مدل یا هارنس نگه می‌دارد. آینه -شامل اعلان کاربر، متن نهایی دستیار، و رکوردهای سبک استدلال یا برنامه Codex -است، وقتی app-server آن‌ها را منتشر کند. امروز، OpenClaw فقط -سیگنال‌های شروع و پایان Compaction بومی را ثبت می‌کند. هنوز خلاصه -خوانا برای انسان از Compaction یا فهرست قابل‌ممیزی از اینکه Codex کدام ورودی‌ها را -پس از Compaction نگه داشته است، ارائه نمی‌کند. +جست‌وجو، `/new`، `/reset`، و تغییر آینده مدل یا مهار نگه می‌دارد. آینه +شامل اعلان کاربر، متن نهایی دستیار، و رکوردهای سبک استدلال یا برنامه Codex است +وقتی app-server آن‌ها را منتشر کند. امروز، OpenClaw فقط سیگنال‌های شروع و تکمیل +Compaction بومی را ثبت می‌کند. هنوز خلاصه خوانای انسانی از Compaction یا فهرست قابل حسابرسی +از اینکه Codex کدام ورودی‌ها را پس از Compaction نگه داشته است ارائه نمی‌کند. -از آنجا که Codex مالک رشته بومی متعارف است، `tool_result_persist` در حال حاضر +چون Codex مالک رشته بومی رسمی است، `tool_result_persist` در حال حاضر رکوردهای نتیجه ابزار بومی Codex را بازنویسی نمی‌کند. فقط وقتی اعمال می‌شود که -OpenClaw در حال نوشتن نتیجه ابزار رونوشت نشست متعلق به OpenClaw باشد. +OpenClaw در حال نوشتن نتیجه ابزار رونوشت نشست تحت مالکیت OpenClaw باشد. -تولید رسانه به PI نیاز ندارد. تصویر، ویدئو، موسیقی، PDF، TTS، و درک رسانه +تولید رسانه به PI نیاز ندارد. تصویر، ویدئو، موسیقی، PDF، TTS، و فهم رسانه همچنان از تنظیمات provider/model متناظر مانند `agents.defaults.imageGenerationModel`، `videoGenerationModel`، `pdfModel`، و `messages.tts` استفاده می‌کنند. @@ -904,47 +987,47 @@ OpenClaw در حال نوشتن نتیجه ابزار رونوشت نشست مت ## عیب‌یابی **Codex به‌عنوان یک provider عادی `/model` ظاهر نمی‌شود:** این برای -پیکربندی‌های جدید مورد انتظار است. یک مدل `openai/gpt-*` را با -`agentRuntime.id: "codex"` (یا یک ارجاع قدیمی `codex/*`) انتخاب کنید، -`plugins.entries.codex.enabled` را فعال کنید، و بررسی کنید آیا `plugins.allow` مقدار -`codex` را مستثنا می‌کند یا نه. +پیکربندی‌های جدید مورد انتظار است. یک مدل `openai/gpt-*` با +`agentRuntime.id: "codex"` (یا یک مرجع قدیمی `codex/*`) انتخاب کنید، +`plugins.entries.codex.enabled` را فعال کنید، و بررسی کنید آیا `plugins.allow` +`codex` را مستثنی می‌کند یا نه. **OpenClaw به‌جای Codex از PI استفاده می‌کند:** `agentRuntime.id: "auto"` همچنان می‌تواند از PI به‌عنوان -backend سازگاری استفاده کند، وقتی هیچ هارنس Codex اجرای موردنظر را ادعا نکند. برای -اجبار انتخاب Codex هنگام آزمایش، `agentRuntime.id: "codex"` را تنظیم کنید. زمان‌اجرای -اجباری Codex به‌جای fallback به PI شکست می‌خورد. پس از انتخاب Codex app-server، -خرابی‌های آن مستقیماً ظاهر می‌شوند. +پس‌زمینه سازگاری استفاده کند، وقتی هیچ مهار Codex اجرای موردنظر را ادعا نکند. برای اجبار انتخاب +Codex هنگام آزمون، `agentRuntime.id: "codex"` را تنظیم کنید. زمان اجرای Codex اجباری +به‌جای برگشتن به PI شکست می‌خورد. پس از انتخاب Codex app-server، +شکست‌های آن مستقیماً نمایش داده می‌شوند. -**app-server رد می‌شود:** Codex را ارتقا دهید تا handshake در app-server -نسخه `0.125.0` یا جدیدتر را گزارش کند. پیش‌انتشارهای هم‌نسخه یا نسخه‌های دارای پسوند build -مانند `0.125.0-alpha.2` یا `0.125.0+custom` رد می‌شوند، زیرا کف پروتکل پایدار +**app-server رد می‌شود:** Codex را ارتقا دهید تا دست‌دهی app-server +نسخه `0.125.0` یا جدیدتر را گزارش کند. پیش‌انتشارهای هم‌نسخه یا نسخه‌های دارای پسوند ساخت +مانند `0.125.0-alpha.2` یا `0.125.0+custom` رد می‌شوند، چون کف پروتکل پایدار `0.125.0` همان چیزی است که OpenClaw آزمایش می‌کند. **کشف مدل کند است:** مقدار `plugins.entries.codex.config.discovery.timeoutMs` را کاهش دهید یا کشف را غیرفعال کنید. -**انتقال WebSocket فوراً شکست می‌خورد:** `appServer.url`، `authToken`، -و اینکه app-server راه‌دور همان نسخه پروتکل Codex app-server را صحبت می‌کند بررسی کنید. +**انتقال WebSocket بلافاصله شکست می‌خورد:** `appServer.url`، `authToken`، +و اینکه app-server دوردست همان نسخه پروتکل Codex app-server را صحبت می‌کند بررسی کنید. -**یک مدل غیر Codex از PI استفاده می‌کند:** این مورد انتظار است، مگر اینکه -`agentRuntime.id: "codex"` را برای آن عامل اجباری کرده باشید یا یک ارجاع قدیمی -`codex/*` انتخاب کرده باشید. ارجاع‌های ساده `openai/gpt-*` و سایر providerها در حالت -`auto` روی مسیر provider عادی خودشان می‌مانند. اگر `agentRuntime.id: "codex"` را اجباری کنید، هر نوبت تعبیه‌شده +**یک مدل غیر Codex از PI استفاده می‌کند:** این مورد انتظار است مگر اینکه برای آن عامل +`agentRuntime.id: "codex"` را اجبار کرده باشید یا یک مرجع قدیمی +`codex/*` را انتخاب کرده باشید. مراجع ساده `openai/gpt-*` و دیگر providerها در حالت +`auto` روی مسیر عادی provider خودشان می‌مانند. اگر `agentRuntime.id: "codex"` را اجبار کنید، هر نوبت تعبیه‌شده برای آن عامل باید یک مدل OpenAI پشتیبانی‌شده توسط Codex باشد. **Computer Use نصب است اما ابزارها اجرا نمی‌شوند:** از یک نشست تازه `/codex computer-use status` را بررسی کنید. اگر ابزاری -`Native hook relay unavailable` گزارش کرد، از `/new` یا `/reset` استفاده کنید؛ اگر ادامه داشت، gateway را بازراه‌اندازی کنید -تا ثبت‌های کهنه هوک بومی پاک شوند. اگر `computer-use.list_apps` -زمانش تمام شد، Codex Computer Use یا Codex Desktop را بازراه‌اندازی کنید و دوباره تلاش کنید. +`Native hook relay unavailable` گزارش کرد، از `/new` یا `/reset` استفاده کنید؛ اگر ادامه داشت، Gateway +را بازراه‌اندازی کنید تا ثبت‌نام‌های قلاب بومی کهنه پاک شوند. اگر `computer-use.list_apps` +زمان‌بر شد، Codex Computer Use یا Codex Desktop را بازراه‌اندازی کنید و دوباره تلاش کنید. ## مرتبط -- [Plugins هارنس عامل](/fa/plugins/sdk-agent-harness) -- [زمان‌اجراهای عامل](/fa/concepts/agent-runtimes) -- [Providerهای مدل](/fa/concepts/model-providers) -- [Provider در OpenAI](/fa/providers/openai) +- [plugins مهار عامل](/fa/plugins/sdk-agent-harness) +- [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) +- [providerهای مدل](/fa/concepts/model-providers) +- [provider OpenAI](/fa/providers/openai) - [وضعیت](/fa/cli/status) -- [هوک‌های Plugin](/fa/plugins/hooks) +- [قلاب‌های Plugin](/fa/plugins/hooks) - [مرجع پیکربندی](/fa/gateway/configuration-reference) -- [آزمایش](/fa/help/testing-live#live-codex-app-server-harness-smoke) +- [آزمون](/fa/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/fa/plugins/dependency-resolution.md b/docs/fa/plugins/dependency-resolution.md index 0f282bf9f..90853f3b7 100644 --- a/docs/fa/plugins/dependency-resolution.md +++ b/docs/fa/plugins/dependency-resolution.md @@ -1,24 +1,24 @@ --- read_when: - - در حال اشکال‌زدایی نصب بسته‌های Plugin هستید - - شما در حال تغییر رفتار راه‌اندازی Plugin، doctor، یا نصب مدیر بسته هستید - - در حال نگه‌داری از نصب‌های بسته‌بندی‌شدهٔ OpenClaw یا مانیفست‌های Plugin همراه هستید + - شما در حال اشکال‌زدایی نصب بسته‌های Plugin هستید + - در حال تغییر رفتار راه‌اندازی Plugin، doctor، یا نصب مدیر بسته هستید + - شما در حال نگهداری نصب‌های بسته‌بندی‌شدهٔ OpenClaw یا مانیفست‌های Plugin همراه هستید sidebarTitle: Dependencies -summary: چگونگی نصب بسته‌های Plugin و حل‌وفصل وابستگی‌های Plugin توسط OpenClaw +summary: OpenClaw چگونه بسته‌های Plugin را نصب و وابستگی‌های Plugin را حل می‌کند title: حل وابستگی‌های Plugin x-i18n: - generated_at: "2026-05-03T21:38:35Z" + generated_at: "2026-05-05T01:50:00Z" model: gpt-5.5 provider: openai - source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d + source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20 source_path: plugins/dependency-resolution.md workflow: 16 --- -# حل وابستگی‌های Plugin +# رفع وابستگی‌های Plugin -OpenClaw کار وابستگی‌های Plugin را در زمان نصب/به‌روزرسانی نگه می‌دارد. بارگذاری در زمان اجرا -مدیرهای بسته را اجرا نمی‌کند، درخت‌های وابستگی را ترمیم نمی‌کند، یا دایرکتوری بسته OpenClaw +OpenClaw کار وابستگی‌های Plugin را در زمان نصب/به‌روزرسانی نگه می‌دارد. بارگذاری زمان اجرا +مدیرهای بسته را اجرا نمی‌کند، درخت‌های وابستگی را تعمیر نمی‌کند، یا دایرکتوری بسته OpenClaw را تغییر نمی‌دهد. ## تفکیک مسئولیت @@ -26,26 +26,26 @@ OpenClaw کار وابستگی‌های Plugin را در زمان نصب/به‌ بسته‌های Plugin مالک گراف وابستگی خود هستند: - وابستگی‌های زمان اجرا در `dependencies` یا - `optionalDependencies` بسته Plugin قرار دارند -- importهای SDK/هسته peer هستند یا importهای تأمین‌شده توسط OpenClaw هستند -- Pluginهای توسعه محلی وابستگی‌های از پیش نصب‌شده خودشان را همراه دارند + `optionalDependencies` بسته Plugin قرار می‌گیرند +- واردسازی‌های SDK/هسته وابستگی‌های همتا یا واردسازی‌های تأمین‌شده توسط OpenClaw هستند +- Pluginهای توسعه محلی وابستگی‌های از پیش نصب‌شده خودشان را می‌آورند - Pluginهای npm و git در ریشه‌های بسته تحت مالکیت OpenClaw نصب می‌شوند OpenClaw فقط مالک چرخه عمر Plugin است: - کشف منبع Plugin -- نصب یا به‌روزرسانی بسته وقتی صراحتاً درخواست شود +- نصب یا به‌روزرسانی بسته هنگامی که صراحتاً درخواست شود - ثبت فراداده نصب - بارگذاری نقطه ورود Plugin -- شکست با خطایی قابل اقدام وقتی وابستگی‌ها موجود نیستند +- شکست با خطایی قابل اقدام وقتی وابستگی‌ها وجود ندارند ## ریشه‌های نصب -OpenClaw از ریشه‌های پایدار برای هر منبع استفاده می‌کند: +OpenClaw از ریشه‌های پایدار به‌ازای هر منبع استفاده می‌کند: - بسته‌های npm زیر `~/.openclaw/npm` نصب می‌شوند -- بسته‌های git زیر `~/.openclaw/git` clone می‌شوند -- نصب‌های محلی/مسیر/آرشیو بدون ترمیم وابستگی کپی یا ارجاع داده می‌شوند +- بسته‌های git زیر `~/.openclaw/git` کلون می‌شوند +- نصب‌های محلی/مسیر/آرشیو بدون تعمیر وابستگی کپی یا ارجاع داده می‌شوند نصب‌های npm در ریشه npm با این دستور اجرا می‌شوند: @@ -53,37 +53,36 @@ OpenClaw از ریشه‌های پایدار برای هر منبع استفاد npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -npm ممکن است وابستگی‌های گذرای Plugin را کنار -بسته Plugin به `~/.openclaw/npm/node_modules` بالا بکشد. OpenClaw پیش از اعتماد به -نصب، ریشه مدیریت‌شده npm را اسکن می‌کند و هنگام حذف نصب، از npm برای حذف بسته‌های مدیریت‌شده با npm استفاده می‌کند، بنابراین وابستگی‌های زمان اجرای بالاکشیده‌شده -داخل مرز پاک‌سازی مدیریت‌شده باقی می‌مانند. +npm ممکن است وابستگی‌های انتقالی را کنار بسته Plugin به `~/.openclaw/npm/node_modules` +بالا بکشد. OpenClaw پیش از اعتماد به نصب، ریشه npm مدیریت‌شده را اسکن می‌کند +و هنگام حذف نصب، از npm برای حذف بسته‌های مدیریت‌شده توسط npm استفاده می‌کند؛ بنابراین +وابستگی‌های زمان اجرا که بالا کشیده شده‌اند داخل مرز پاک‌سازی مدیریت‌شده باقی می‌مانند. -نصب‌های git مخزن را clone یا تازه‌سازی می‌کنند، سپس این دستور را اجرا می‌کنند: +نصب‌های git مخزن را کلون یا تازه‌سازی می‌کنند، سپس اجرا می‌کنند: ```bash npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` -سپس Plugin نصب‌شده از همان دایرکتوری بسته بارگذاری می‌شود، بنابراین resolution مربوط به `node_modules` محلی بسته -و والد همان‌طور کار می‌کند که برای یک بسته عادی -Node کار می‌کند. +سپس Plugin نصب‌شده از همان دایرکتوری بسته بارگذاری می‌شود، بنابراین رفع `node_modules` +محلی بسته و والد همان‌طور کار می‌کند که برای یک بسته معمولی Node کار می‌کند. ## Pluginهای محلی -Pluginهای محلی به‌عنوان دایرکتوری‌های تحت کنترل توسعه‌دهنده در نظر گرفته می‌شوند. OpenClaw برای آن‌ها -`npm install`، `pnpm install`، یا ترمیم وابستگی اجرا نمی‌کند. اگر یک -Plugin محلی وابستگی دارد، آن‌ها را پیش از بارگذاری Plugin در همان Plugin نصب کنید. +Pluginهای محلی به‌عنوان دایرکتوری‌های تحت کنترل توسعه‌دهنده در نظر گرفته می‌شوند. OpenClaw +برای آن‌ها `npm install`، `pnpm install` یا تعمیر وابستگی اجرا نمی‌کند. اگر یک +Plugin محلی وابستگی‌هایی دارد، پیش از بارگذاری آن Plugin، آن‌ها را در همان Plugin نصب کنید. Pluginهای محلی TypeScript شخص ثالث می‌توانند از مسیر اضطراری Jiti استفاده کنند. Pluginهای -JavaScript بسته‌بندی‌شده و Pluginهای داخلی همراه، به‌جای Jiti از طریق -import/require بومی بارگذاری می‌شوند. +JavaScript بسته‌بندی‌شده و Pluginهای داخلی همراه از طریق import/require بومی +به‌جای Jiti بارگذاری می‌شوند. ## راه‌اندازی و بارگذاری مجدد راه‌اندازی Gateway و بارگذاری مجدد پیکربندی هرگز وابستگی‌های Plugin را نصب نمی‌کنند. آن‌ها -رکوردهای نصب Plugin را می‌خوانند، نقطه ورود را محاسبه می‌کنند، و آن را بارگذاری می‌کنند. +رکوردهای نصب Plugin را می‌خوانند، نقطه ورود را محاسبه می‌کنند و آن را بارگذاری می‌کنند. -اگر وابستگی‌ای در زمان اجرا موجود نباشد، بارگذاری Plugin شکست می‌خورد و خطا +اگر وابستگی‌ای در زمان اجرا وجود نداشته باشد، Plugin بارگذاری نمی‌شود و خطا باید اپراتور را به یک رفع صریح هدایت کند: ```bash @@ -92,43 +91,44 @@ openclaw plugins install openclaw doctor --fix ``` -`doctor --fix` می‌تواند وضعیت وابستگی legacy تولیدشده توسط OpenClaw را پاک‌سازی کند و -Pluginهای قابل دانلود پیکربندی‌شده را که در رکوردهای نصب محلی موجود نیستند نصب کند. -این فرمان وابستگی‌های یک Plugin محلیِ از پیش نصب‌شده را ترمیم نمی‌کند. +`doctor --fix` می‌تواند وضعیت وابستگی قدیمی تولیدشده توسط OpenClaw را پاک کند و +Pluginهای قابل دانلودی را که هنگام ارجاع پیکربندی، در رکوردهای نصب محلی وجود ندارند +بازیابی کند. Doctor وابستگی‌های یک Plugin محلی از پیش نصب‌شده را تعمیر نمی‌کند. ## Pluginهای همراه -Pluginهای همراه سبک و حیاتی برای هسته به‌عنوان بخشی از OpenClaw ارسال می‌شوند. -آن‌ها باید یا درخت وابستگی زمان اجرای سنگینی نداشته باشند یا به یک +Pluginهای همراه سبک‌وزن و حیاتی برای هسته به‌عنوان بخشی از OpenClaw ارسال می‌شوند. +آن‌ها یا نباید درخت وابستگی زمان اجرای سنگینی داشته باشند، یا باید به یک بسته قابل دانلود در ClawHub/npm منتقل شوند. -برای فهرست تولیدشده فعلی Pluginهایی که در بسته هسته ارسال می‌شوند، به‌صورت خارجی نصب می‌شوند، -یا فقط در منبع باقی می‌مانند، [فهرست Plugin](/fa/plugins/plugin-inventory) را ببینید. +برای فهرست تولیدشده فعلی Pluginهایی که در بسته هسته ارسال می‌شوند، بیرونی نصب +می‌شوند، یا فقط در منبع باقی می‌مانند، [موجودی Plugin](/fa/plugins/plugin-inventory) را ببینید. -مانیفست‌های Plugin همراه نباید درخواست آماده‌سازی وابستگی کنند. قابلیت‌های بزرگ یا اختیاری -Plugin باید به‌عنوان یک Plugin عادی بسته‌بندی شوند و از طریق -همان مسیر npm/git/ClawHub مانند Pluginهای شخص ثالث نصب شوند. +مانیفست‌های Plugin همراه نباید مرحله‌بندی وابستگی درخواست کنند. قابلیت‌های بزرگ یا اختیاری +Plugin باید به‌عنوان یک Plugin معمولی بسته‌بندی و از همان مسیر npm/git/ClawHub +مانند Pluginهای شخص ثالث نصب شوند. -در checkoutهای منبع، OpenClaw مخزن را به‌عنوان یک monorepo مبتنی بر pnpm در نظر می‌گیرد. پس از -`pnpm install`، Pluginهای همراه از `extensions/` بارگذاری می‌شوند تا وابستگی‌های workspace -محلی بسته در دسترس باشند و ویرایش‌ها مستقیماً اعمال شوند. توسعه checkout منبع فقط با pnpm پشتیبانی می‌شود؛ اجرای ساده `npm install` در ریشه مخزن -روش پشتیبانی‌شده‌ای برای آماده‌سازی وابستگی‌های Plugin همراه نیست. +در checkoutهای منبع، OpenClaw مخزن را به‌عنوان یک مونورپوی pnpm در نظر می‌گیرد. پس از +`pnpm install`، Pluginهای همراه از `extensions/` بارگذاری می‌شوند تا وابستگی‌های +workspace محلی بسته در دسترس باشند و ویرایش‌ها مستقیماً اعمال شوند. توسعه checkout منبع +فقط با pnpm انجام می‌شود؛ اجرای ساده `npm install` در ریشه مخزن راه پشتیبانی‌شده‌ای +برای آماده‌سازی وابستگی‌های Plugin همراه نیست. -| شکل نصب | محل Plugin همراه | مالک وابستگی | +| شکل نصب | مکان Plugin همراه | مالک وابستگی | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | -| `npm install -g openclaw` | درخت زمان اجرای ساخته‌شده داخل بسته | بسته OpenClaw و جریان‌های صریح نصب/به‌روزرسانی/doctor برای Plugin | -| checkout با git به‌علاوه `pnpm install` | بسته‌های workspace در `extensions/` | workspace مبتنی بر pnpm، شامل وابستگی‌های خود هر بسته Plugin | -| `openclaw plugins install ...` | ریشه Plugin مدیریت‌شده npm/git/ClawHub | جریان نصب/به‌روزرسانی Plugin | +| `npm install -g openclaw` | درخت زمان اجرای ساخته‌شده داخل بسته | بسته OpenClaw و جریان‌های صریح نصب/به‌روزرسانی/doctor برای Plugin | +| checkout گیت به‌علاوه `pnpm install` | بسته‌های workspace در `extensions/` | workspace مربوط به pnpm، شامل وابستگی‌های خود هر بسته Plugin | +| `openclaw plugins install ...` | ریشه Plugin مدیریت‌شده npm/git/ClawHub | جریان نصب/به‌روزرسانی Plugin | -## پاک‌سازی legacy +## پاک‌سازی قدیمی -نسخه‌های قدیمی‌تر OpenClaw ریشه‌های وابستگی Pluginهای همراه را در زمان راه‌اندازی یا -هنگام ترمیم doctor تولید می‌کردند. پاک‌سازی فعلی doctor وقتی `--fix` استفاده شود آن دایرکتوری‌ها و -symlinkهای قدیمی را حذف می‌کند، از جمله ریشه‌های قدیمی `plugin-runtime-deps`، symlinkهای -بسته با پیشوند سراسری Node که به هدف‌های حذف‌شده `plugin-runtime-deps` اشاره می‌کنند، -مانیفست‌های `.openclaw-runtime-deps*`، `node_modules` تولیدشده Plugin، دایرکتوری‌های -مرحله نصب، و storeهای pnpm محلی بسته. postinstall بسته‌بندی‌شده نیز -پیش از حذف ریشه‌های هدف legacy آن symlinkهای سراسری را حذف می‌کند تا ارتقاها -importهای بسته ESM آویزان باقی نگذارند. +نسخه‌های قدیمی‌تر OpenClaw ریشه‌های وابستگی Plugin همراه را هنگام راه‌اندازی یا +در زمان تعمیر doctor تولید می‌کردند. پاک‌سازی doctor فعلی هنگام استفاده از `--fix` +آن دایرکتوری‌ها و symlinkهای کهنه را حذف می‌کند، از جمله ریشه‌های قدیمی +`plugin-runtime-deps`، symlinkهای بسته با پیشوند سراسری Node که به هدف‌های هرس‌شده +`plugin-runtime-deps` اشاره می‌کنند، مانیفست‌های `.openclaw-runtime-deps*`، `node_modules` +تولیدشده برای Plugin، دایرکتوری‌های مرحله نصب، و storeهای pnpm محلی بسته. postinstall +بسته‌بندی‌شده همچنین پیش از هرس کردن ریشه‌های هدف قدیمی، آن symlinkهای سراسری را حذف +می‌کند تا ارتقاها importهای بسته ESM آویزان باقی نگذارند. -این مسیرها فقط پسماندهای legacy هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند. +این مسیرها فقط بقایای قدیمی هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند. diff --git a/docs/fa/plugins/manage-plugins.md b/docs/fa/plugins/manage-plugins.md index 4a2badc06..f307927bd 100644 --- a/docs/fa/plugins/manage-plugins.md +++ b/docs/fa/plugins/manage-plugins.md @@ -1,24 +1,24 @@ --- read_when: - - نمونه‌های سریع نصب، فهرست‌کردن، به‌روزرسانی یا حذف Plugin را می‌خواهید + - شما نمونه‌های سریع نصب، فهرست کردن، به‌روزرسانی یا حذف Plugin را می‌خواهید - می‌خواهید بین ClawHub و توزیع Plugin از طریق npm انتخاب کنید - شما در حال انتشار یک بسته Plugin هستید sidebarTitle: Manage plugins -summary: نمونه‌های سریع برای نصب، فهرست‌کردن، حذف نصب، به‌روزرسانی و انتشار Plugin‌های OpenClaw -title: مدیریت Pluginها +summary: نمونه‌های سریع برای نصب، فهرست کردن، حذف نصب، به‌روزرسانی و انتشار Plugin‌های OpenClaw +title: مدیریت Plugin‌ها x-i18n: - generated_at: "2026-05-02T22:21:20Z" + generated_at: "2026-05-05T01:50:35Z" model: gpt-5.5 provider: openai - source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320 + source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c source_path: plugins/manage-plugins.md workflow: 16 --- -بیشتر گردش‌کارهای Plugin چند فرمان هستند: جست‌وجو، نصب، راه‌اندازی دوباره Gateway، -راستی‌آزمایی، و حذف نصب وقتی دیگر به Plugin نیاز ندارید. +بیشتر گردش‌کارهای Plugin چند فرمان هستند: جستجو، نصب، راه‌اندازی دوباره‌ی Gateway، +راستی‌آزمایی، و حذف نصب زمانی که دیگر به Plugin نیاز ندارید. -## فهرست کردن Pluginها +## فهرست‌کردن Pluginها ```bash openclaw plugins list @@ -28,8 +28,8 @@ openclaw plugins list --json ``` برای اسکریپت‌ها از `--json` استفاده کنید. این خروجی شامل عیب‌یابی‌های رجیستری و -`dependencyStatus` ایستای هر Plugin است، وقتی بسته Plugin، `dependencies` یا -`optionalDependencies` را اعلام کرده باشد. +`dependencyStatus` ایستای هر Plugin است، زمانی که بسته‌ی Plugin +`dependencies` یا `optionalDependencies` را اعلام کرده باشد. ```bash openclaw plugins list --json \ @@ -37,8 +37,8 @@ openclaw plugins list --json \ ``` `plugins list` یک بررسی موجودی سرد است. نشان می‌دهد OpenClaw چه چیزهایی را می‌تواند -از پیکربندی، manifestها و رجیستری Plugin کشف کند؛ اما ثابت نمی‌کند که یک فرایند -Gateway که از قبل در حال اجراست، runtime مربوط به Plugin را import کرده است. +از پیکربندی، مانیفست‌ها، و رجیستری Plugin کشف کند؛ اما ثابت نمی‌کند که یک فرایند +Gateway که از قبل در حال اجراست، زمان اجرای Plugin را import کرده است. ## نصب Pluginها @@ -65,16 +65,16 @@ openclaw plugins install ./my-plugin openclaw plugins install --link ./my-plugin ``` -پس از نصب کد Plugin، Gatewayای را که کانال‌های شما را ارائه می‌کند دوباره راه‌اندازی کنید: +پس از نصب کد Plugin، Gatewayای را که به کانال‌های شما سرویس می‌دهد دوباره راه‌اندازی کنید: ```bash openclaw gateway restart openclaw plugins inspect --runtime --json ``` -وقتی به مدرکی نیاز دارید که نشان دهد Plugin سطح‌های runtime مانند ابزارها، hookها، -سرویس‌ها، متدهای Gateway، یا فرمان‌های CLI متعلق به Plugin را ثبت کرده است، از -`inspect --runtime` استفاده کنید. +زمانی از `inspect --runtime` استفاده کنید که به مدرکی نیاز دارید مبنی بر اینکه Plugin +سطوح زمان اجرا مانند ابزارها، hookها، سرویس‌ها، متدهای Gateway، یا فرمان‌های CLI +متعلق به Plugin را ثبت کرده است. ## به‌روزرسانی Pluginها @@ -84,22 +84,23 @@ openclaw plugins update openclaw plugins update --all ``` -اگر Plugin از یک dist-tag متعلق به npm مانند `@beta` نصب شده باشد، فراخوانی‌های بعدی -`update ` از همان tag ثبت‌شده دوباره استفاده می‌کنند. دادن یک spec صریح npm -نصبِ دنبال‌شده را برای به‌روزرسانی‌های آینده به همان spec تغییر می‌دهد. +اگر Plugin از یک dist-tag مربوط به npm مانند `@beta` نصب شده باشد، فراخوانی‌های بعدی +`update ` همان tag ثبت‌شده را دوباره استفاده می‌کنند. عبور دادن یک spec +صریح npm، نصب ردیابی‌شده را برای به‌روزرسانی‌های آینده به همان spec تغییر می‌دهد. ```bash openclaw plugins update @scope/openclaw-plugin@beta openclaw plugins update @scope/openclaw-plugin ``` -فرمان دوم، وقتی Plugin قبلا به یک نسخه یا tag دقیق سنجاق شده باشد، آن را به خط انتشار +فرمان دوم یک Plugin را وقتی پیش‌تر به یک نسخه یا tag دقیق سنجاق شده بود، به خط انتشار پیش‌فرض رجیستری برمی‌گرداند. وقتی `openclaw update` روی کانال beta اجرا می‌شود، رکوردهای Plugin مربوط به npm خط -پیش‌فرض و ClawHub ابتدا تلاش می‌کنند نسخه Plugin `@beta` متناظر را بگیرند. اگر آن نسخه -beta وجود نداشته باشد، OpenClaw به spec پیش‌فرض/آخرینِ ثبت‌شده برمی‌گردد. نسخه‌های دقیق -و tagهای صریح مانند `@rc` یا `@beta` حفظ می‌شوند. +پیش‌فرض و ClawHub ابتدا انتشار `@beta` متناظر Plugin را امتحان می‌کنند. اگر آن انتشار +beta وجود نداشته باشد، OpenClaw به spec پیش‌فرض/آخرینِ ثبت‌شده برمی‌گردد. برای Pluginهای +npm، اگر بسته‌ی beta وجود داشته باشد اما در اعتبارسنجی نصب شکست بخورد، OpenClaw نیز +عقب‌گرد می‌کند. نسخه‌های دقیق و tagهای صریح مانند `@rc` یا `@beta` حفظ می‌شوند. ## حذف نصب Pluginها @@ -110,9 +111,9 @@ openclaw plugins uninstall --keep-files openclaw gateway restart ``` -حذف نصب، ورودی پیکربندی Plugin، رکورد index Plugin، ورودی‌های فهرست مجاز/مسدود، و در -صورت کاربرد، مسیرهای بارگذاری link‌شده را حذف می‌کند. دایرکتوری‌های نصب مدیریت‌شده -حذف می‌شوند مگر اینکه `--keep-files` را بدهید. +حذف نصب، ورودی پیکربندی Plugin، رکورد شاخص Plugin، ورودی‌های فهرست مجاز/ممنوع، +و مسیرهای بارگذاری پیوندشده را در صورت کاربرد حذف می‌کند. دایرکتوری‌های نصب مدیریت‌شده +حذف می‌شوند، مگر اینکه `--keep-files` را عبور دهید. ## انتشار Pluginها @@ -121,8 +122,8 @@ openclaw gateway restart ### انتشار در ClawHub -ClawHub سطح اصلی کشف عمومی برای Pluginهای OpenClaw است. پیش از نصب، metadata قابل -جست‌وجو، تاریخچه نسخه‌ها، و نتایج اسکن رجیستری را به کاربران می‌دهد. +ClawHub سطح اصلی کشف عمومی برای Pluginهای OpenClaw است. پیش از نصب، فراداده‌ی قابل +جستجو، تاریخچه‌ی نسخه، و نتایج اسکن رجیستری را به کاربران می‌دهد. ```bash npm i -g clawhub @@ -132,7 +133,7 @@ clawhub package publish your-org/your-plugin clawhub package publish your-org/your-plugin@v1.0.0 ``` -کاربران با این فرمان‌ها از ClawHub نصب می‌کنند: +کاربران از ClawHub با این فرمان نصب می‌کنند: ```bash openclaw plugins install clawhub: @@ -143,8 +144,8 @@ openclaw plugins install ### انتشار در npmjs.com -Pluginهای بومی npm باید یک manifest مربوط به Plugin و metadata نقطه ورود OpenClaw در -`package.json` داشته باشند. +Pluginهای بومی npm باید شامل یک مانیفست Plugin و فراداده‌ی نقطه ورود OpenClaw در +`package.json` باشند. ```json package.json { @@ -161,7 +162,7 @@ Pluginهای بومی npm باید یک manifest مربوط به Plugin و metad npm publish --access public ``` -کاربران فقط از npm با این فرمان‌ها نصب می‌کنند: +کاربران فقط با npm به این شکل نصب می‌کنند: ```bash openclaw plugins install npm:@acme/openclaw-plugin @@ -169,17 +170,17 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta openclaw plugins install npm:@acme/openclaw-plugin@1.0.0 ``` -اگر همان بسته در ClawHub نیز در دسترس باشد، `npm:` جست‌وجوی ClawHub را رد می‌کند و -resolve شدن از npm را اجباری می‌کند. +اگر همان بسته در ClawHub هم موجود باشد، `npm:` جستجوی ClawHub را رد می‌کند و +تفکیک npm را اجباری می‌کند. ## انتخاب منبع -- **ClawHub**: وقتی استفاده کنید که کشف بومی OpenClaw، خلاصه‌های اسکن، - نسخه‌ها و راهنمایی‌های نصب می‌خواهید. -- **npmjs.com**: وقتی استفاده کنید که از قبل بسته‌های JavaScript منتشر می‌کنید یا به - dist-tagهای npm/گردش‌کارهای رجیستری خصوصی نیاز دارید. -- **Git**: وقتی استفاده کنید که می‌خواهید مستقیما از یک branch، tag، یا commit نصب کنید. -- **مسیر محلی**: وقتی استفاده کنید که در حال توسعه یا آزمایش یک Plugin روی همان +- **ClawHub**: زمانی استفاده کنید که کشف بومی OpenClaw، خلاصه‌های اسکن، + نسخه‌ها، و راهنمایی‌های نصب را می‌خواهید. +- **npmjs.com**: زمانی استفاده کنید که از قبل بسته‌های JavaScript منتشر می‌کنید یا به گردش‌کارهای + dist-tag/رجیستری خصوصی npm نیاز دارید. +- **Git**: زمانی استفاده کنید که می‌خواهید مستقیماً از یک شاخه، tag، یا commit نصب کنید. +- **مسیر محلی**: زمانی استفاده کنید که در حال توسعه یا آزمایش یک Plugin روی همان دستگاه هستید. ## مرتبط @@ -187,5 +188,5 @@ resolve شدن از npm را اجباری می‌کند. - [Pluginها](/fa/tools/plugin) - نمای کلی و عیب‌یابی - [`openclaw plugins`](/fa/cli/plugins) - مرجع کامل CLI - [ClawHub](/fa/tools/clawhub) - عملیات انتشار و رجیستری -- [ساخت Pluginها](/fa/plugins/building-plugins) - ایجاد یک بسته Plugin -- [manifest مربوط به Plugin](/fa/plugins/manifest) - metadata مربوط به manifest و بسته +- [ساخت Pluginها](/fa/plugins/building-plugins) - ایجاد یک بسته‌ی Plugin +- [مانیفست Plugin](/fa/plugins/manifest) - مانیفست و فراداده‌ی بسته diff --git a/docs/fa/providers/openrouter.md b/docs/fa/providers/openrouter.md index 5cc493516..65da867a3 100644 --- a/docs/fa/providers/openrouter.md +++ b/docs/fa/providers/openrouter.md @@ -4,33 +4,33 @@ read_when: - می‌خواهید مدل‌ها را از طریق OpenRouter در OpenClaw اجرا کنید - می‌خواهید از OpenRouter برای تولید تصویر استفاده کنید - می‌خواهید از OpenRouter برای تولید ویدیو استفاده کنید -summary: از رابط برنامه‌نویسی یکپارچهٔ OpenRouter برای دسترسی به مدل‌های متعدد در OpenClaw استفاده کنید +summary: از API یکپارچهٔ OpenRouter برای دسترسی به مدل‌های متعدد در OpenClaw استفاده کنید title: OpenRouter x-i18n: - generated_at: "2026-05-04T02:27:06Z" + generated_at: "2026-05-05T01:51:06Z" model: gpt-5.5 provider: openai - source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc + source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244 source_path: providers/openrouter.md workflow: 16 --- -OpenRouter یک **API یکپارچه** ارائه می‌کند که درخواست‌ها را از پشت یک -endpoint و کلید API واحد به مدل‌های زیادی مسیریابی می‌کند. با OpenAI سازگار است، بنابراین بیشتر SDKهای OpenAI با تغییر URL پایه کار می‌کنند. +OpenRouter یک **API یکپارچه** ارائه می‌کند که درخواست‌ها را به مدل‌های زیادی پشت یک +نقطهٔ پایانی و کلید API واحد مسیریابی می‌کند. با OpenAI سازگار است، بنابراین بیشتر SDKهای OpenAI با تغییر URL پایه کار می‌کنند. ## شروع به کار - - یک کلید API در [openrouter.ai/keys](https://openrouter.ai/keys) بسازید. + + یک کلید API در [openrouter.ai/keys](https://openrouter.ai/keys) ایجاد کنید. - + ```bash openclaw onboard --auth-choice openrouter-api-key ``` - - مقدار پیش‌فرض onboarding برابر `openrouter/auto` است. بعدا یک مدل مشخص انتخاب کنید: + + راه‌اندازی اولیه به‌صورت پیش‌فرض از `openrouter/auto` استفاده می‌کند. بعداً یک مدل مشخص انتخاب کنید: ```bash openclaw models set openrouter// @@ -39,7 +39,7 @@ endpoint و کلید API واحد به مدل‌های زیادی مسیریاب -## نمونه پیکربندی +## نمونهٔ پیکربندی ```json5 { @@ -56,10 +56,10 @@ endpoint و کلید API واحد به مدل‌های زیادی مسیریاب ارجاع‌های مدل از الگوی `openrouter//` پیروی می‌کنند. برای فهرست کامل -providerها و مدل‌های در دسترس، [/concepts/model-providers](/fa/concepts/model-providers) را ببینید. +ارائه‌دهندگان و مدل‌های در دسترس، [/concepts/model-providers](/fa/concepts/model-providers) را ببینید. -نمونه‌های fallback همراه بسته: +نمونه‌های جایگزین همراه: | ارجاع مدل | یادداشت‌ها | | --------------------------------- | ---------------------------- | @@ -68,7 +68,7 @@ providerها و مدل‌های در دسترس، [/concepts/model-providers](/f ## تولید تصویر -OpenRouter همچنین می‌تواند پشتوانه ابزار `image_generate` باشد. از یک مدل تصویر OpenRouter زیر `agents.defaults.imageGenerationModel` استفاده کنید: +OpenRouter همچنین می‌تواند پشتوانهٔ ابزار `image_generate` باشد. از یک مدل تصویر OpenRouter زیر `agents.defaults.imageGenerationModel` استفاده کنید: ```json5 { @@ -84,11 +84,11 @@ OpenRouter همچنین می‌تواند پشتوانه ابزار `image_gener } ``` -OpenClaw درخواست‌های تصویر را با `modalities: ["image", "text"]` به API تصویر تکمیل‌های گفت‌وگوی OpenRouter می‌فرستد. مدل‌های تصویر Gemini راهنمایی‌های پشتیبانی‌شده `aspectRatio` و `resolution` را از طریق `image_config` متعلق به OpenRouter دریافت می‌کنند. برای مدل‌های تصویر کندتر OpenRouter از `agents.defaults.imageGenerationModel.timeoutMs` استفاده کنید؛ پارامتر `timeoutMs` در هر فراخوانی ابزار `image_generate` همچنان اولویت دارد. +OpenClaw درخواست‌های تصویر را با `modalities: ["image", "text"]` به API تصویر تکمیل‌های گفت‌وگوی OpenRouter می‌فرستد. مدل‌های تصویر Gemini راهنمایی‌های پشتیبانی‌شدهٔ `aspectRatio` و `resolution` را از طریق `image_config` در OpenRouter دریافت می‌کنند. برای مدل‌های تصویر کندتر OpenRouter از `agents.defaults.imageGenerationModel.timeoutMs` استفاده کنید؛ پارامتر `timeoutMs` در هر فراخوانی ابزار `image_generate` همچنان اولویت دارد. ## تولید ویدیو -OpenRouter همچنین می‌تواند از طریق API ناهمگام `/videos` پشتوانه ابزار `video_generate` باشد. از یک مدل ویدیوی OpenRouter زیر `agents.defaults.videoGenerationModel` استفاده کنید: +OpenRouter همچنین می‌تواند از طریق API ناهمگام `/videos` خود پشتوانهٔ ابزار `video_generate` باشد. از یک مدل ویدیوی OpenRouter زیر `agents.defaults.videoGenerationModel` استفاده کنید: ```json5 { @@ -103,16 +103,19 @@ OpenRouter همچنین می‌تواند از طریق API ناهمگام `/vid } ``` -OpenClaw کارهای تبدیل متن به ویدیو و تصویر به ویدیو را به OpenRouter ارسال می‌کند، `polling_url` برگشتی را polling می‌کند، و ویدیوی تکمیل‌شده را از -`unsigned_urls` متعلق به OpenRouter یا endpoint مستندشده محتوای کار دانلود می‌کند. -تصاویر مرجع به‌طور پیش‌فرض به‌عنوان تصاویر فریم اول/آخر فرستاده می‌شوند؛ تصاویر -برچسب‌خورده با `reference_image` به‌عنوان ارجاع‌های ورودی OpenRouter فرستاده می‌شوند. مقدار پیش‌فرض همراه بسته `google/veo-3.1-fast` مدت‌های 4/6/8 -ثانیه‌ای، وضوح‌های `720P`/`1080P`، و نسبت‌های تصویر `16:9`/`9:16` را که در حال حاضر پشتیبانی می‌شوند اعلام می‌کند. تبدیل ویدیو به ویدیو برای OpenRouter ثبت نشده است، زیرا API بالادستی تولید ویدیو در حال حاضر متن و ارجاع‌های تصویر را می‌پذیرد. +OpenClaw کارهای متن‌به‌ویدیو و تصویر‌به‌ویدیو را به OpenRouter ارسال می‌کند، `polling_url` +برگشتی را نظرسنجی می‌کند، و ویدیوی تکمیل‌شده را از `unsigned_urls` متعلق به OpenRouter +یا نقطهٔ پایانی مستندشدهٔ محتوای کار دانلود می‌کند. تصویرهای مرجع به‌صورت پیش‌فرض به‌عنوان +تصویرهای فریم اول/آخر فرستاده می‌شوند؛ تصویرهایی که با `reference_image` برچسب‌گذاری شده‌اند +به‌عنوان ارجاع‌های ورودی OpenRouter ارسال می‌شوند. پیش‌فرض همراه `google/veo-3.1-fast` +مدت‌های ۴/۶/۸ ثانیه‌ای، وضوح‌های `720P`/`1080P` و نسبت‌های تصویر `16:9`/`9:16` +را که در حال حاضر پشتیبانی می‌شوند اعلام می‌کند. ویدیو‌به‌ویدیو برای OpenRouter ثبت نشده است، +زیرا API بالادستی تولید ویدیو در حال حاضر متن و ارجاع‌های تصویری را می‌پذیرد. -## تبدیل متن به گفتار +## متن‌به‌گفتار -OpenRouter همچنین می‌تواند از طریق endpoint سازگار با OpenAI یعنی -`/audio/speech` به‌عنوان provider TTS استفاده شود. +OpenRouter همچنین می‌تواند از طریق نقطهٔ پایانی سازگار با OpenAI یعنی +`/audio/speech` به‌عنوان ارائه‌دهندهٔ TTS استفاده شود. ```json5 { @@ -135,29 +138,29 @@ OpenRouter همچنین می‌تواند از طریق endpoint سازگار ب اگر `messages.tts.providers.openrouter.apiKey` حذف شود، TTS دوباره از `models.providers.openrouter.apiKey` و سپس `OPENROUTER_API_KEY` استفاده می‌کند. -## احراز هویت و headerها +## احراز هویت و سرآیندها -OpenRouter در پشت صحنه از یک توکن Bearer همراه با کلید API شما استفاده می‌کند. +OpenRouter در پشت‌صحنه از توکن Bearer همراه با کلید API شما استفاده می‌کند. در درخواست‌های واقعی OpenRouter (`https://openrouter.ai/api/v1`)، OpenClaw همچنین -headerهای مستندشده انتساب برنامه OpenRouter را اضافه می‌کند: +سرآیندهای مستندشدهٔ OpenRouter برای انتساب برنامه را اضافه می‌کند: -| Header | مقدار | +| سرآیند | مقدار | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | `HTTP-Referer` | `https://openclaw.ai` | | `X-OpenRouter-Title` | `OpenClaw` | | `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | -اگر provider OpenRouter را به proxy یا URL پایه دیگری تغییر دهید، OpenClaw -آن headerهای ویژه OpenRouter یا نشانگرهای cache متعلق به Anthropic را تزریق **نمی‌کند**. +اگر ارائه‌دهندهٔ OpenRouter را به پراکسی یا URL پایهٔ دیگری اشاره دهید، OpenClaw +آن سرآیندهای ویژهٔ OpenRouter یا نشانگرهای کش Anthropic را تزریق **نمی‌کند**. ## پیکربندی پیشرفته - - cache کردن پاسخ در OpenRouter اختیاری است. آن را برای هر مدل OpenRouter با + + کش‌کردن پاسخ در OpenRouter اختیاری است. آن را برای هر مدل OpenRouter با پارامترهای مدل فعال کنید: ```json5 @@ -177,60 +180,62 @@ headerهای مستندشده انتساب برنامه OpenRouter را اضاف } ``` - OpenClaw مقدار `X-OpenRouter-Cache: true` را می‌فرستد و، وقتی پیکربندی شده باشد، - `X-OpenRouter-Cache-TTL` را نیز ارسال می‌کند. `responseCacheClear: true` برای - درخواست فعلی یک تازه‌سازی اجباری انجام می‌دهد و پاسخ جایگزین را ذخیره می‌کند. aliasهای snake_case - (`response_cache`، `response_cache_ttl_seconds`، و + OpenClaw مقدار `X-OpenRouter-Cache: true` و، در صورت پیکربندی، + `X-OpenRouter-Cache-TTL` را می‌فرستد. `responseCacheClear: true` برای + درخواست فعلی بازخوانی را اجباری می‌کند و پاسخ جایگزین را ذخیره می‌کند. نام‌های مستعار snake_case + (`response_cache`، `response_cache_ttl_seconds` و `response_cache_clear`) نیز پذیرفته می‌شوند. - این مورد از cache کردن prompt در provider و از نشانگرهای - `cache_control` متعلق به Anthropic در OpenRouter جداست. فقط روی مسیرهای - تاییدشده `openrouter.ai` اعمال می‌شود، نه URLهای پایه proxy سفارشی. + این مورد از کش‌کردن پرامپت ارائه‌دهنده و از نشانگرهای Anthropic + `cache_control` در OpenRouter جدا است. فقط روی مسیرهای تأییدشدهٔ + `openrouter.ai` اعمال می‌شود، نه URLهای پایهٔ پراکسی سفارشی. - - در مسیرهای تاییدشده OpenRouter، ارجاع‌های مدل Anthropic نشانگرهای - ویژه OpenRouter یعنی `cache_control` متعلق به Anthropic را نگه می‌دارند که OpenClaw برای - استفاده مجدد بهتر از cache prompt روی بلوک‌های prompt سیستم/توسعه‌دهنده استفاده می‌کند. + + در مسیرهای تأییدشدهٔ OpenRouter، ارجاع‌های مدل Anthropic نشانگرهای ویژهٔ OpenRouter + یعنی `cache_control` مربوط به Anthropic را نگه می‌دارند که OpenClaw برای + استفادهٔ بهتر از کش پرامپت روی بلوک‌های پرامپت سیستم/توسعه‌دهنده به کار می‌برد. - - در مسیرهای تاییدشده OpenRouter، ارجاع‌های مدل Anthropic با استدلال فعال، - turnهای پایانی prefill دستیار را پیش از رسیدن درخواست به OpenRouter حذف می‌کنند، - تا با الزام Anthropic که گفت‌وگوهای استدلال باید با یک turn کاربر پایان یابند هماهنگ باشد. + + در مسیرهای تأییدشدهٔ OpenRouter، ارجاع‌های مدل Anthropic که استدلال در آن‌ها فعال است + نوبت‌های پیش‌پرشدهٔ انتهایی assistant را پیش از رسیدن درخواست به OpenRouter حذف می‌کنند، + مطابق با الزام Anthropic که گفت‌وگوهای استدلالی باید با نوبت کاربر پایان یابند. - - در مسیرهای غیر `auto` پشتیبانی‌شده، OpenClaw سطح thinking انتخاب‌شده را به - payloadهای استدلال proxy متعلق به OpenRouter نگاشت می‌کند. راهنمایی‌های مدل پشتیبانی‌نشده و + + در مسیرهای پشتیبانی‌شدهٔ غیر `auto`، OpenClaw سطح تفکر انتخاب‌شده را به + محموله‌های استدلال پراکسی OpenRouter نگاشت می‌کند. راهنمایی‌های مدل پشتیبانی‌نشده و `openrouter/auto` آن تزریق استدلال را رد می‌کنند. Hunter Alpha همچنین - استدلال proxy را برای ارجاع‌های مدل پیکربندی‌شده قدیمی رد می‌کند، زیرا OpenRouter ممکن است + برای ارجاع‌های مدل پیکربندی‌شدهٔ قدیمی، استدلال پراکسی را رد می‌کند، زیرا OpenRouter ممکن است برای آن مسیر بازنشسته، متن پاسخ نهایی را در فیلدهای استدلال برگرداند. - در مسیرهای تاییدشده OpenRouter، `openrouter/deepseek/deepseek-v4-flash` و - `openrouter/deepseek/deepseek-v4-pro` مقدار `reasoning_content` گم‌شده را در - turnهای بازپخش‌شده دستیار پر می‌کنند تا گفت‌وگوهای thinking/tool شکل پیگیری - موردنیاز DeepSeek V4 را حفظ کنند. + در مسیرهای تأییدشدهٔ OpenRouter، `openrouter/deepseek/deepseek-v4-flash` و + `openrouter/deepseek/deepseek-v4-pro` مقدارهای گمشدهٔ `reasoning_content` را در + نوبت‌های assistant بازپخش‌شده پر می‌کنند تا گفت‌وگوهای تفکر/ابزار شکل پیگیری موردنیاز DeepSeek V4 + را حفظ کنند. OpenClaw مقدارهای پشتیبانی‌شدهٔ OpenRouter برای + `reasoning_effort` را برای این مسیرها می‌فرستد؛ `xhigh` بالاترین سطح اعلام‌شده است + و بازنویسی‌های قدیمی `max` به `xhigh` نگاشت می‌شوند. - - OpenRouter همچنان از مسیر سازگار با OpenAI به سبک proxy عبور می‌کند، بنابراین - شکل‌دهی درخواست بومی و فقط OpenAI مانند `serviceTier`، `store` در Responses، - payloadهای سازگار با استدلال OpenAI، و راهنمایی‌های cache prompt ارسال نمی‌شوند. + + OpenRouter همچنان از مسیر سازگار با OpenAI به سبک پراکسی عبور می‌کند، بنابراین + شکل‌دهی درخواست بومی و فقط مخصوص OpenAI مانند `serviceTier`، مقدار `store` در Responses، + محموله‌های سازگاری استدلال OpenAI و راهنمایی‌های کش پرامپت ارسال نمی‌شود. - - ارجاع‌های OpenRouter مبتنی بر Gemini روی مسیر proxy-Gemini باقی می‌مانند: OpenClaw پاک‌سازی - thought-signature متعلق به Gemini را در آنجا حفظ می‌کند، اما اعتبارسنجی بازپخش بومی Gemini - یا بازنویسی‌های bootstrap را فعال نمی‌کند. + + ارجاع‌های OpenRouter که پشتوانهٔ Gemini دارند روی مسیر پراکسی-Gemini می‌مانند: OpenClaw + پاک‌سازی امضای تفکر Gemini را در آنجا نگه می‌دارد، اما اعتبارسنجی بازپخش بومی Gemini + یا بازنویسی‌های بوت‌استرپ را فعال نمی‌کند. - - اگر مسیریابی provider متعلق به OpenRouter را زیر پارامترهای مدل پاس دهید، OpenClaw - پیش از اجرای wrapperهای stream مشترک، آن را به‌عنوان فراداده مسیریابی OpenRouter ارسال می‌کند. + + اگر مسیریابی ارائه‌دهندهٔ OpenRouter را زیر پارامترهای مدل ارسال کنید، OpenClaw + آن را پیش از اجرای wrapperهای جریان مشترک، به‌عنوان فرادادهٔ مسیریابی OpenRouter ارسال می‌کند. @@ -238,9 +243,9 @@ headerهای مستندشده انتساب برنامه OpenRouter را اضاف - انتخاب providerها، ارجاع‌های مدل، و رفتار failover. + انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover. - مرجع کامل پیکربندی برای agentها، مدل‌ها، و providerها. + مرجع کامل پیکربندی برای عامل‌ها، مدل‌ها، و ارائه‌دهندگان. diff --git a/docs/fa/reference/RELEASING.md b/docs/fa/reference/RELEASING.md index 64b46fd51..e7ac92861 100644 --- a/docs/fa/reference/RELEASING.md +++ b/docs/fa/reference/RELEASING.md @@ -2,172 +2,180 @@ read_when: - در حال جست‌وجوی تعاریف کانال‌های انتشار عمومی - اجرای اعتبارسنجی انتشار یا پذیرش بسته - - در حال جست‌وجوی نام‌گذاری نسخه‌ها و آهنگ انتشار -summary: مسیرهای انتشار، فهرست بررسی اپراتور، محیط‌های اعتبارسنجی، نام‌گذاری نسخه، و آهنگ انتشار -title: سیاست انتشار + - به‌دنبال نام‌گذاری نسخه‌ها و آهنگ انتشار +summary: مسیرهای انتشار، چک‌لیست اپراتور، باکس‌های اعتبارسنجی، نام‌گذاری نسخه‌ها، و ریتم انتشار +title: خط‌مشی انتشار x-i18n: - generated_at: "2026-05-04T07:07:47Z" + generated_at: "2026-05-05T01:51:10Z" model: gpt-5.5 provider: openai - source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 + source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3 source_path: reference/RELEASING.md workflow: 16 --- OpenClaw سه مسیر انتشار عمومی دارد: -- stable: انتشارهای برچسب‌خورده‌ای که به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند، یا وقتی صریحاً درخواست شود در npm با `latest` منتشر می‌شوند +- stable: انتشارهای برچسب‌گذاری‌شده‌ای که به‌طور پیش‌فرض در npm با `beta` منتشر می‌شوند، یا وقتی صراحتا درخواست شود در npm با `latest` منتشر می‌شوند - beta: برچسب‌های پیش‌انتشار که در npm با `beta` منتشر می‌شوند -- dev: سرِ در حال حرکتِ `main` +- dev: سر متحرک `main` ## نام‌گذاری نسخه -- نسخهٔ انتشار پایدار: `YYYY.M.D` +- نسخه انتشار پایدار: `YYYY.M.D` - برچسب Git: `vYYYY.M.D` -- نسخهٔ انتشار اصلاحی پایدار: `YYYY.M.D-N` +- نسخه انتشار اصلاحی پایدار: `YYYY.M.D-N` - برچسب Git: `vYYYY.M.D-N` -- نسخهٔ پیش‌انتشار بتا: `YYYY.M.D-beta.N` +- نسخه پیش‌انتشار بتا: `YYYY.M.D-beta.N` - برچسب Git: `vYYYY.M.D-beta.N` -- ماه یا روز را با صفر پر نکنید -- `latest` یعنی انتشار پایدار فعلی npm که ترویج شده است +- ماه یا روز را با صفر ابتدایی ننویسید +- `latest` یعنی انتشار پایدار npm که اکنون ترویج شده است - `beta` یعنی هدف نصب بتای فعلی -- انتشارهای پایدار و اصلاحی پایدار به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند؛ متصدیان انتشار می‌توانند صریحاً `latest` را هدف بگیرند، یا بعداً یک ساخت بتای بررسی‌شده را ترویج کنند -- هر انتشار پایدار OpenClaw بستهٔ npm و برنامهٔ macOS را با هم عرضه می‌کند؛ - انتشارهای بتا معمولاً ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر می‌کنند، و - ساخت/امضا/محضری‌سازی برنامهٔ mac برای نسخهٔ پایدار نگه داشته می‌شود مگر آنکه صریحاً درخواست شود +- انتشارهای پایدار و اصلاحی پایدار به‌طور پیش‌فرض در npm با `beta` منتشر می‌شوند؛ اپراتورهای انتشار می‌توانند صراحتا `latest` را هدف بگیرند، یا بعدا یک ساخت بتای بررسی‌شده را ترویج کنند +- هر انتشار پایدار OpenClaw بسته npm و برنامه macOS را با هم ارائه می‌کند؛ + انتشارهای بتا معمولا ابتدا مسیر npm/package را اعتبارسنجی و منتشر می‌کنند، و + ساخت/امضا/محضرسازی برنامه mac برای پایدار نگه داشته می‌شود مگر اینکه صراحتا درخواست شود -## چرخهٔ انتشار +## آهنگ انتشار - انتشارها ابتدا از بتا عبور می‌کنند - پایدار فقط پس از اعتبارسنجی آخرین بتا دنبال می‌شود -- نگه‌دارندگان معمولاً انتشارها را از شاخهٔ `release/YYYY.M.D` که از - `main` فعلی ساخته شده است جدا می‌کنند، تا اعتبارسنجی انتشار و رفع اشکال‌ها - توسعهٔ جدید روی `main` را مسدود نکند +- نگه‌دارندگان معمولا انتشارها را از شاخه `release/YYYY.M.D` که از + `main` فعلی ساخته شده است برش می‌دهند، تا اعتبارسنجی و اصلاحات انتشار مانع + توسعه جدید روی `main` نشود - اگر یک برچسب بتا push یا منتشر شده باشد و به اصلاح نیاز داشته باشد، نگه‌دارندگان - به‌جای حذف یا بازسازی برچسب بتای قدیمی، برچسب `-beta.N` بعدی را جدا می‌کنند -- رویهٔ تفصیلی انتشار، تأییدها، اعتبارنامه‌ها، و یادداشت‌های بازیابی - فقط مخصوص نگه‌داران است + به‌جای حذف یا ساخت دوباره برچسب بتای قدیمی، برچسب بعدی `-beta.N` را برش می‌دهند +- روند انتشار تفصیلی، تأییدها، اعتبارنامه‌ها و یادداشت‌های بازیابی + فقط مخصوص نگه‌دارندگان است -## چک‌لیست متصدی انتشار +## چک‌لیست اپراتور انتشار این چک‌لیست شکل عمومی جریان انتشار است. اعتبارنامه‌های خصوصی، -امضا، محضری‌سازی، بازیابی dist-tag، و جزئیات rollback اضطراری در -دستورالعمل اجرایی انتشارِ فقط مخصوص نگه‌داران باقی می‌ماند. +امضا، محضرسازی، بازیابی dist-tag و جزئیات بازگردانی اضطراری در +دفترچه اجرای انتشار مخصوص نگه‌دارندگان باقی می‌ماند. -1. از `main` فعلی شروع کنید: آخرین تغییرات را pull کنید، تأیید کنید commit هدف push شده است، - و تأیید کنید CI فعلی `main` به‌اندازهٔ کافی سبز است که بتوان از آن شاخه ساخت. -2. بخش بالایی `CHANGELOG.md` را از تاریخچهٔ واقعی commit با +1. از `main` فعلی شروع کنید: آخرین نسخه را pull کنید، تأیید کنید commit هدف push شده است، + و تأیید کنید CI فعلی `main` به‌اندازه کافی سبز است که بتوان از آن شاخه ساخت. +2. بخش بالایی `CHANGELOG.md` را با تاریخچه واقعی commit و با `/changelog` بازنویسی کنید، ورودی‌ها را کاربرمحور نگه دارید، آن را commit و push کنید، و - پیش از ساخت شاخه یک بار دیگر rebase/pull کنید. + پیش از شاخه‌سازی یک بار دیگر rebase/pull کنید. 3. رکوردهای سازگاری انتشار را در `src/plugins/compat/registry.ts` و - `src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضی‌شده را فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا - عمداً حفظ شده است. + `src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری + منقضی‌شده را فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا + عمدا حفظ شده است. 4. `release/YYYY.M.D` را از `main` فعلی بسازید؛ کار عادی انتشار را - مستقیماً روی `main` انجام ندهید. -5. همهٔ محل‌های نسخهٔ لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بسته‌های Plugin قابل انتشار نسخهٔ انتشار - و فرادادهٔ سازگاری مشترک داشته باشند، سپس پیش‌بررسی قطعی محلی را اجرا کنید: + مستقیما روی `main` انجام ندهید. +5. هر محل نسخه لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید + تا بسته‌های Plugin قابل انتشار نسخه انتشار + و فراداده سازگاری مشترک داشته باشند، سپس پیش‌پرواز قطعی محلی را اجرا کنید: `pnpm check:test-types`، `pnpm check:architecture`، `pnpm build && pnpm ui:build`، `pnpm plugins:sync:check`، و `pnpm release:check`. 6. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید. پیش از وجود برچسب، - یک SHA کامل ۴۰ نویسه‌ای از شاخهٔ انتشار برای پیش‌بررسی صرفاً اعتبارسنجی + یک SHA کامل ۴۰ کاراکتری شاخه انتشار برای پیش‌پرواز فقط اعتبارسنجی مجاز است. `preflight_run_id` موفق را ذخیره کنید. -7. همهٔ آزمون‌های پیش از انتشار را با `Full Release Validation` برای - شاخهٔ انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطهٔ ورود دستی - برای چهار جعبهٔ آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package. -8. اگر اعتبارسنجی شکست خورد، روی شاخهٔ انتشار اصلاح کنید و کوچک‌ترین - فایل، مسیر، job گردش‌کار، پروفایل بسته، provider، یا allowlist مدل شکست‌خورده‌ای را که - اصلاح را اثبات می‌کند دوباره اجرا کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییرکرده +7. همه آزمون‌های پیش از انتشار را با `Full Release Validation` برای + شاخه انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطه ورود دستی + برای چهار جعبه آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package. +8. اگر اعتبارسنجی شکست خورد، روی شاخه انتشار اصلاح کنید و کوچک‌ترین + فایل، مسیر، job گردش‌کار، پروفایل بسته، ارائه‌دهنده، یا allowlist مدل شکست‌خورده‌ای را + دوباره اجرا کنید که اصلاح را اثبات می‌کند. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییر شواهد قبلی را کهنه کند. 9. برای بتا، `vYYYY.M.D-beta.N` را برچسب بزنید، سپس `OpenClaw Release Publish` را از - شاخهٔ منطبق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تأیید می‌کند، - ابتدا همهٔ بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، سپس همان - مجموعه را به‌عنوان tarballهای ClawPack npm-pack در ClawHub منتشر می‌کند، و بعد - مصنوع پیش‌بررسی npm آمادهٔ OpenClaw را با dist-tag منطبق ترویج می‌کند. پس از - انتشار، پذیرش بستهٔ پس از انتشار را در برابر بستهٔ منتشرشدهٔ + شاخه متناظر `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تأیید می‌کند، + ابتدا همه بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، همان + مجموعه را در مرحله دوم به‌عنوان tarballهای ClawPack npm-pack در ClawHub منتشر می‌کند، و سپس + آرتیفکت پیش‌پرواز npm آماده‌شده OpenClaw را با dist-tag متناظر ترویج می‌کند. پس از + انتشار، پذیرش بسته پس از انتشار را در برابر بسته منتشرشده `openclaw@YYYY.M.D-beta.N` یا `openclaw@beta` اجرا کنید. اگر یک پیش‌انتشار push یا منتشرشده به اصلاح نیاز داشت، - شمارهٔ پیش‌انتشار منطبق بعدی را جدا کنید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید. -10. برای پایدار، فقط پس از آن ادامه دهید که بتا یا نامزد انتشار بررسی‌شده + شماره پیش‌انتشار متناظر بعدی را برش دهید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید. +10. برای پایدار، فقط پس از آن ادامه دهید که بتای بررسی‌شده یا نامزد انتشار شواهد اعتبارسنجی لازم را داشته باشد. انتشار پایدار npm نیز از طریق - `OpenClaw Release Publish` انجام می‌شود، با استفادهٔ دوباره از مصنوع پیش‌بررسی موفق از طریق - `preflight_run_id`؛ آمادگی انتشار پایدار macOS همچنین به + `OpenClaw Release Publish` انجام می‌شود و با استفاده از + `preflight_run_id` آرتیفکت پیش‌پرواز موفق را دوباره به کار می‌گیرد؛ آمادگی انتشار پایدار macOS نیز به `.zip`، `.dmg`، `.dSYM.zip` بسته‌بندی‌شده، و `appcast.xml` به‌روزشده روی `main` نیاز دارد. -11. پس از انتشار، تأییدگر پس از انتشار npm، E2E اختیاری Telegram برای - npm منتشرشدهٔ مستقل وقتی به اثبات کانال پس از انتشار نیاز دارید، +11. پس از انتشار، تأییدکننده پس از انتشار npm، E2E اختیاری Telegram + مستقل منتشرشده در npm را وقتی به اثبات کانال پس از انتشار نیاز دارید، ترویج dist-tag در صورت نیاز، یادداشت‌های انتشار/پیش‌انتشار GitHub از - بخش کامل و منطبق `CHANGELOG.md`، و گام‌های اعلام انتشار را اجرا کنید. + بخش کامل و متناظر `CHANGELOG.md`، و مراحل اعلام انتشار را اجرا کنید. -## پیش‌بررسی انتشار +## پیش‌پرواز انتشار -- پیش از بررسی مقدماتی انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript تست‌ها خارج از gate سریع‌تر محلی `pnpm check` همچنان پوشش داده شود -- پیش از بررسی مقدماتی انتشار، `pnpm check:architecture` را اجرا کنید تا بررسی‌های گسترده‌تر چرخه‌های import و مرزهای معماری خارج از gate سریع‌تر محلی سبز باشند -- پیش از `pnpm release:check`، `pnpm build && pnpm ui:build` را اجرا کنید تا artifactهای انتشار مورد انتظار `dist/*` و bundle رابط کاربری کنترل برای مرحله اعتبارسنجی pack موجود باشند -- پس از افزایش نسخه ریشه و پیش از tag زدن، `pnpm plugins:sync` را اجرا کنید. این دستور نسخه‌های packageهای Plugin قابل انتشار، فراداده سازگاری peer/API مربوط به OpenClaw، فراداده build، و stubهای changelog Plugin را به‌روزرسانی می‌کند تا با نسخه انتشار core هم‌خوان شوند. `pnpm plugins:sync:check` نگهبان غیرتغییردهنده انتشار است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد. -- پیش از تأیید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه test boxهای پیش از انتشار از یک entrypoint آغاز شوند. این workflow یک branch، tag، یا commit SHA کامل می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، suiteهای مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E package را روی artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، وقتی همان Telegram E2E باید package منتشرشده npm را هم اثبات کند، `npm_telegram_package_spec` را ارائه کنید. پس از انتشار، وقتی Package Acceptance باید matrix package/update خود را به‌جای artifact ساخته‌شده از SHA روی package ارسال‌شده npm اجرا کند، `package_acceptance_package_spec` را ارائه کنید. وقتی گزارش evidence خصوصی باید بدون اجبار Telegram E2E اثبات کند که اعتبارسنجی با یک package منتشرشده npm مطابقت دارد، `evidence_package_spec` را ارائه کنید. مثال: +- `pnpm check:test-types` را پیش از پیش‌پرواز انتشار اجرا کنید تا TypeScript آزمون‌ها بیرون از دروازه سریع‌تر محلی `pnpm check` همچنان پوشش داده شود +- `pnpm check:architecture` را پیش از پیش‌پرواز انتشار اجرا کنید تا بررسی‌های گسترده‌تر چرخه import و مرزهای معماری بیرون از دروازه سریع‌تر محلی سبز باشند +- `pnpm build && pnpm ui:build` را پیش از `pnpm release:check` اجرا کنید تا آرتیفکت‌های انتشار مورد انتظار `dist/*` و بسته Control UI برای گام اعتبارسنجی pack وجود داشته باشند +- `pnpm plugins:sync` را پس از افزایش نسخه ریشه و پیش از tagگذاری اجرا کنید. این دستور نسخه‌های بسته‌های plugin قابل انتشار، فراداده سازگاری peer/API با OpenClaw، فراداده build و stubهای changelog مربوط به plugin را برای تطبیق با نسخه انتشار هسته به‌روزرسانی می‌کند. `pnpm plugins:sync:check` نگهبان انتشار بدون تغییر است؛ اگر این گام فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد. +- workflow دستی `Full Release Validation` را پیش از تأیید انتشار اجرا کنید تا همه test boxهای پیش از انتشار از یک نقطه ورود آغاز شوند. این workflow یک branch، tag یا SHA کامل commit را می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، بررسی‌های بسته میان‌سیستمی، برابری QA Lab، Matrix و مسیرهای Telegram dispatch می‌کند. اجراهای stable/default، soak کامل live/E2E و مسیر انتشار Docker را پشت `run_release_soak=true` نگه می‌دارند؛ `release_profile=full` اجرای soak را اجباری می‌کند. با `release_profile=full` و `rerun_group=all`، E2E بسته Telegram را نیز در برابر آرتیفکت `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، زمانی `npm_telegram_package_spec` را ارائه کنید که همان Telegram E2E باید بسته منتشرشده npm را هم اثبات کند. پس از انتشار، زمانی `package_acceptance_package_spec` را ارائه کنید که Package Acceptance باید ماتریس package/update خود را به‌جای آرتیفکت ساخته‌شده از SHA، در برابر بسته npm ارسال‌شده اجرا کند. زمانی `evidence_package_spec` را ارائه کنید که گزارش خصوصی evidence باید اثبات کند اعتبارسنجی با یک بسته npm منتشرشده مطابقت دارد، بدون اینکه Telegram E2E اجباری شود. مثال: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- وقتی می‌خواهید در حالی که کار انتشار ادامه دارد برای یک candidate package اثبات جانبی بگیرید، workflow دستی `Package Acceptance` را اجرا کنید. برای `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق از `source=npm` استفاده کنید؛ برای pack کردن یک branch/tag/SHA قابل اعتماد `package_ref` با harness فعلی `workflow_ref` از `source=ref` استفاده کنید؛ برای یک tarball HTTPS با SHA-256 الزامی از `source=url` استفاده کنید؛ یا برای tarball آپلودشده توسط اجرای دیگری از GitHub Actions از `source=artifact` استفاده کنید. این workflow candidate را به `package-under-test` resolve می‌کند، scheduler انتشار Docker E2E را روی آن tarball بازاستفاده می‌کند، و می‌تواند QA Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` روی همان tarball اجرا کند. وقتی laneهای Docker انتخاب‌شده شامل `published-upgrade-survivor` باشند، artifact package همان candidate است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند. +- workflow دستی `Package Acceptance` را زمانی اجرا کنید که می‌خواهید هم‌زمان با ادامه کار انتشار، اثبات side-channel برای یک نامزد بسته داشته باشید. از `source=npm` برای `openclaw@beta`، `openclaw@latest` یا یک نسخه انتشار دقیق استفاده کنید؛ از `source=ref` برای pack کردن یک branch/tag/SHA مطمئن `package_ref` با harness فعلی `workflow_ref`؛ از `source=url` برای یک tarball HTTPS با SHA-256 الزامی؛ یا از `source=artifact` برای tarball بارگذاری‌شده توسط اجرای دیگری از GitHub Actions. این workflow نامزد را به `package-under-test` resolve می‌کند، زمان‌بند انتشار Docker E2E را در برابر همان tarball بازاستفاده می‌کند، و می‌تواند QA مربوط به Telegram را روی همان tarball با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` اجرا کند. وقتی laneهای انتخاب‌شده Docker شامل `published-upgrade-survivor` باشند، آرتیفکت بسته همان نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند. مثال: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - profileهای رایج: - - `smoke`: laneهای install/channel/agent، شبکه Gateway، و reload پیکربندی - - `package`: laneهای package/update/plugin بومی artifact بدون OpenWebUI یا ClawHub زنده - - `product`: profile package به‌علاوه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI + پروفایل‌های رایج: + - `smoke`: laneهای نصب/channel/agent، شبکه Gateway و بارگذاری دوباره config + - `package`: laneهای package/update/plugin بومی آرتیفکت، بدون OpenWebUI یا ClawHub زنده + - `product`: پروفایل package به‌همراه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI و OpenWebUI - `full`: بخش‌های مسیر انتشار Docker با OpenWebUI - `custom`: انتخاب دقیق `docker_lanes` برای rerun متمرکز -- وقتی فقط به پوشش کامل CI عادی برای candidate انتشار نیاز دارید، workflow دستی `CI` را مستقیم اجرا کنید. dispatchهای CI دستی scoping بر اساس تغییرات را دور می‌زنند و shardهای Linux Node، shardهای bundled-plugin، contractهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n رابط کاربری کنترل را اجباری می‌کنند. +- workflow دستی `CI` را زمانی مستقیم اجرا کنید که فقط به پوشش کامل CI عادی برای نامزد انتشار نیاز دارید. dispatchهای دستی CI از scoping بر اساس تغییرات عبور می‌کنند و shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Python skills، Windows، macOS، Android و laneهای i18n مربوط به Control UI را اجباری می‌کنند. مثال: `gh workflow run ci.yml --ref release/YYYY.M.D` -- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک receiver محلی OTLP/HTTP اجرا می‌کند و نام spanهای trace صادرشده، attributeهای محدود، و redact شدن content/identifier را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر بررسی می‌کند. -- پیش از هر انتشار tagشده، `pnpm release:check` را اجرا کنید -- پس از وجود tag، برای دنباله انتشار تغییردهنده `OpenClaw Release Publish` را اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید (یا هنگام انتشار tag قابل دسترسی از main، از `main`)، tag انتشار و `preflight_run_id` موفق OpenClaw npm را پاس بدهید، و scope پیش‌فرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً تعمیر متمرکز اجرا می‌کنید. این workflow انتشار npm مربوط به Plugin، انتشار Plugin در ClawHub، و انتشار OpenClaw در npm را سریالی می‌کند تا package core پیش از Pluginهای externalized خود منتشر نشود. -- اکنون release checks در یک workflow دستی جداگانه اجرا می‌شوند: +- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک گیرنده محلی OTLP/HTTP اجرا می‌کند و نام spanهای trace خروجی، attributeهای bounded و redaction محتوا/شناسه را بدون نیاز به Opik، Langfuse یا collector خارجی دیگر بررسی می‌کند. +- پیش از هر انتشار tagگذاری‌شده، `pnpm release:check` را اجرا کنید +- پس از وجود tag، `OpenClaw Release Publish` را برای توالی انتشار تغییردهنده اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید (یا وقتی tag قابل دسترسی از `main` را منتشر می‌کنید، از `main`)، tag انتشار و `preflight_run_id` موفق npm مربوط به OpenClaw را بدهید، و scope پیش‌فرض انتشار plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً یک repair متمرکز اجرا می‌کنید. این workflow انتشار npm مربوط به plugin، انتشار ClawHub مربوط به plugin و انتشار npm مربوط به OpenClaw را سریالی می‌کند تا بسته هسته پیش از pluginهای بیرونی‌شده‌اش منتشر نشود. +- بررسی‌های انتشار اکنون در یک workflow دستی جداگانه اجرا می‌شوند: `OpenClaw Release Checks` -- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock در QA Lab به‌علاوه profile سریع Matrix زنده و lane QA Telegram را اجرا می‌کند. laneهای زنده از environment `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از leaseهای credential مربوط به Convex CI استفاده می‌کند. وقتی inventory کامل transport، media، و E2EE مربوط به Matrix را به‌صورت موازی می‌خواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید. -- اعتبارسنجی runtime نصب و upgrade میان سیستم‌عامل‌ها بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است، که workflow قابل بازاستفاده `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی می‌کنند -- این تفکیک عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی، و متمرکز بر artifact نگه دارید، در حالی که بررسی‌های زنده کندتر در lane خودشان باقی می‌مانند تا انتشار را متوقف یا block نکنند -- release checkهایی که secret دارند باید از طریق `Full Release Validation` یا از workflow ref مربوط به `main`/release dispatch شوند تا logic workflow و secretها کنترل‌شده بمانند -- `OpenClaw Release Checks` یک branch، tag، یا commit SHA کامل را می‌پذیرد تا زمانی که commit resolveشده از یک branch یا tag انتشار OpenClaw قابل دسترسی باشد -- بررسی مقدماتی فقط-اعتبارسنجی `OpenClaw NPM Release` نیز commit SHA کامل ۴۰ کاراکتری branch workflow فعلی را بدون نیاز به tag pushشده می‌پذیرد -- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به یک انتشار واقعی promote شود -- در حالت SHA، workflow فقط برای بررسی فراداده package مقدار `v` را synthesize می‌کند؛ انتشار واقعی همچنان به tag واقعی انتشار نیاز دارد -- هر دو workflow مسیر واقعی انتشار و promotion را روی runnerهای GitHub-hosted نگه می‌دارند، در حالی که مسیر اعتبارسنجی غیرتغییردهنده می‌تواند از runnerهای بزرگ‌تر Blacksmith Linux استفاده کند -- آن workflow دستور `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` را با استفاده از هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا می‌کند -- بررسی مقدماتی انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند -- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` را اجرا کنید (یا tag متناظر beta/correction) -- پس از انتشار npm، برای بررسی مسیر نصب registry منتشرشده در یک temp prefix تازه، `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` را اجرا کنید (یا نسخه متناظر beta/correction) -- پس از انتشار beta، برای بررسی onboarding package نصب‌شده، راه‌اندازی Telegram، و Telegram E2E واقعی روی package منتشرشده npm با استفاده از pool مشترک credentialهای اجاره‌ای Telegram، `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` را اجرا کنید. اجرای موردی محلی توسط maintainer می‌تواند vars مربوط به Convex را حذف کند و سه credential env یعنی `OPENCLAW_QA_TELEGRAM_*` را مستقیم پاس بدهد. -- برای اجرای smoke کامل beta پس از انتشار از ماشین maintainer، از `pnpm release:beta-smoke -- --beta betaN` استفاده کنید. helper اعتبارسنجی Parallels برای npm update/fresh-target را اجرا می‌کند، `NPM Telegram Beta E2E` را dispatch می‌کند، اجرای دقیق workflow را poll می‌کند، artifact را دانلود می‌کند، و گزارش Telegram را چاپ می‌کند. -- maintainers می‌توانند همان بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود. -- automation انتشار maintainer اکنون از preflight-then-promote استفاده می‌کند: - - انتشار واقعی npm باید از یک `preflight_run_id` موفق npm عبور کند - - انتشار واقعی npm باید از همان branch `main` یا `release/YYYY.M.D` اجرا شود که preflight موفق از آن اجرا شده است - - انتشارهای stable npm به‌طور پیش‌فرض روی `beta` قرار می‌گیرند - - انتشار stable npm می‌تواند از طریق ورودی workflow صراحتاً `latest` را هدف بگیرد - - تغییر token-based در dist-tagهای npm اکنون برای امنیت در `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` قرار دارد، زیرا `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالی که repo عمومی انتشار فقط با OIDC را نگه می‌دارد - - `macOS Release` عمومی فقط اعتبارسنجی است؛ وقتی یک tag فقط روی branch انتشار وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید - - انتشار واقعی private mac باید از `preflight_run_id` و `validate_run_id` موفق private mac عبور کند - - مسیرهای واقعی انتشار artifactهای آماده‌شده را promote می‌کنند به‌جای اینکه دوباره آن‌ها را rebuild کنند -- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر upgrade با temp-prefix از `YYYY.M.D` به `YYYY.M.D-N` را بررسی می‌کند تا correctionهای انتشار نتوانند بی‌سروصدا نصب‌های global قدیمی‌تر را روی payload پایدار پایه باقی بگذارند -- بررسی مقدماتی انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball هم `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` را شامل شود تا دوباره dashboard مرورگر خالی ارسال نکنیم -- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای Plugin منتشرشده و فراداده package در layout نصب‌شده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند، verifier پس از انتشار را fail می‌کند و نمی‌تواند به `latest` promote شود. -- `pnpm test:install:smoke` همچنین budget مربوط به `unpackedSize` در npm pack را روی tarball candidate update اعمال می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، افزایش ناخواسته حجم pack را می‌گیرد -- اگر کار انتشار به برنامه‌ریزی CI، manifestهای زمان‌بندی extension، یا matrixهای تست extension دست زده است، پیش از تأیید، outputهای matrix مربوط به `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره generate و review کنید تا release notes layout کهنه CI را توصیف نکند -- آمادگی انتشار stable macOS همچنین شامل سطوح updater است: - - GitHub release باید در نهایت شامل `.zip`، `.dmg`، و `.dSYM.zip` packageشده باشد - - `appcast.xml` روی `main` باید پس از انتشار به zip پایدار جدید اشاره کند - - app بسته‌بندی‌شده باید bundle id غیر-debug، URL feed غیرخالی Sparkle، و `CFBundleVersion` در حداقل کف build canonical Sparkle یا بالاتر برای آن نسخه انتشار را حفظ کند +- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock مربوط به QA Lab به‌همراه پروفایل سریع live Matrix و lane QA مربوط به Telegram را اجرا می‌کند. laneهای live از محیط `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از اجاره credentialهای Convex CI استفاده می‌کند. وقتی inventory کامل transport، media و E2EE مربوط به Matrix را به‌صورت موازی می‌خواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید. +- اعتبارسنجی runtime نصب و ارتقای میان‌سیستمی بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است، که workflow قابل بازاستفاده `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی می‌کنند +- این جداسازی عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی و متمرکز بر آرتیفکت نگه دارید، در حالی که بررسی‌های live کندتر در lane خود می‌مانند تا انتشار را متوقف یا مسدود نکنند +- بررسی‌های انتشار دارای secret باید از طریق `Full Release +Validation` یا از ref workflow مربوط به `main`/release dispatch شوند تا منطق workflow و secretها کنترل‌شده بمانند +- `OpenClaw Release Checks` یک branch، tag یا SHA کامل commit را می‌پذیرد، تا زمانی که commit resolveشده از یک branch یا tag انتشار OpenClaw قابل دسترسی باشد +- پیش‌پرواز validation-only مربوط به `OpenClaw NPM Release` نیز SHA کامل ۴۰کاراکتری commit مربوط به branch فعلی workflow را بدون نیاز به tag pushشده می‌پذیرد +- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به انتشار واقعی promoted شود +- در حالت SHA، workflow فقط برای بررسی فراداده بسته، `v` را می‌سازد؛ انتشار واقعی همچنان به tag انتشار واقعی نیاز دارد +- هر دو workflow مسیر واقعی publish و promotion را روی runnerهای GitHub-hosted نگه می‌دارند، در حالی که مسیر اعتبارسنجی بدون تغییر می‌تواند از runnerهای بزرگ‌تر Blacksmith Linux استفاده کند +- آن workflow این دستور را اجرا می‌کند + `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` + با استفاده از هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` +- پیش‌پرواز انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند +- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + را اجرا کنید (یا tag متناظر beta/correction) +- پس از انتشار npm، برای بررسی مسیر نصب registry منتشرشده در یک prefix موقت تازه، این دستور را اجرا کنید + `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` + (یا نسخه متناظر beta/correction) +- پس از انتشار beta، برای بررسی onboarding بسته نصب‌شده، راه‌اندازی Telegram و E2E واقعی Telegram در برابر بسته npm منتشرشده با استفاده از pool مشترک credential اجاره‌ای Telegram، `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` را اجرا کنید. اجرای موردی محلی توسط maintainer می‌تواند متغیرهای Convex را حذف کند و سه credential محیطی `OPENCLAW_QA_TELEGRAM_*` را مستقیم بدهد. +- برای اجرای smoke کامل beta پس از انتشار از ماشین maintainer، از `pnpm release:beta-smoke -- --beta betaN` استفاده کنید. این helper اعتبارسنجی npm update/fresh-target مربوط به Parallels را اجرا می‌کند، `NPM Telegram Beta E2E` را dispatch می‌کند، اجرای دقیق workflow را poll می‌کند، آرتیفکت را دانلود می‌کند و گزارش Telegram را چاپ می‌کند. +- maintainerها می‌توانند همان بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود. +- automation انتشار maintainer اکنون از الگوی preflight-then-promote استفاده می‌کند: + - انتشار واقعی npm باید یک `preflight_run_id` موفق npm را گذرانده باشد + - انتشار واقعی npm باید از همان branch یعنی `main` یا `release/YYYY.M.D` dispatch شود که اجرای preflight موفق از آن بوده است + - انتشارهای stable npm به‌صورت پیش‌فرض به `beta` می‌روند + - انتشار stable npm می‌تواند به‌طور صریح از طریق ورودی workflow، `latest` را هدف بگیرد + - تغییر token-based مربوط به npm dist-tag اکنون برای امنیت در `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` قرار دارد، زیرا `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد، در حالی که repo عمومی انتشار OIDC-only را نگه می‌دارد + - `macOS Release` عمومی فقط برای اعتبارسنجی است؛ وقتی یک tag فقط روی branch انتشار وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید + - انتشار واقعی private mac باید `preflight_run_id` و `validate_run_id` موفق private mac را گذرانده باشد + - مسیرهای انتشار واقعی آرتیفکت‌های آماده‌شده را promote می‌کنند، به‌جای اینکه دوباره آن‌ها را build کنند +- برای انتشارهای correction stable مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر ارتقای temp-prefix از `YYYY.M.D` به `YYYY.M.D-N` را بررسی می‌کند تا correctionهای انتشار نتوانند بی‌صدا نصب‌های global قدیمی‌تر را روی payload پایه stable باقی بگذارند +- پیش‌پرواز انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball هم `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` را داشته باشد، تا دوباره dashboard مرورگر خالی ارسال نکنیم +- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای plugin منتشرشده و فراداده package در چیدمان registry نصب‌شده وجود داشته باشند. انتشاری که payloadهای runtime مربوط به plugin را ناقص ارسال کند، verifier پس از انتشار را fail می‌کند و نمی‌تواند به `latest` promoted شود. +- `pnpm test:install:smoke` همچنین بودجه `unpackedSize` مربوط به npm pack را روی tarball نامزد update enforce می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، افزایش ناخواسته حجم pack را می‌گیرد +- اگر کار انتشار به planning مربوط به CI، manifestهای timing افزونه، یا ماتریس‌های آزمون افزونه دست زده باشد، پیش از تأیید، خروجی‌های ماتریس `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` بازتولید و بازبینی کنید تا release notes چیدمان کهنه CI را توصیف نکنند +- آمادگی انتشار stable macOS همچنین شامل سطح‌های updater است: + - GitHub release باید در پایان `.zip`، `.dmg` و `.dSYM.zip` بسته‌بندی‌شده را داشته باشد + - `appcast.xml` روی `main` پس از انتشار باید به zip جدید stable اشاره کند + - app بسته‌بندی‌شده باید bundle id غیر-debug، URL غیرخالی Sparkle feed، و `CFBundleVersion` برابر یا بالاتر از کف canonical Sparkle build برای آن نسخه انتشار را نگه دارد ## test boxهای انتشار -`Full Release Validation` روشی است که operatorها با آن همه تست‌های پیش از انتشار را از یک entrypoint آغاز می‌کنند. برای اثبات commit pinشده روی branch پرتحرک، از helper استفاده کنید تا هر workflow فرزند از یک branch موقت ثابت‌شده روی SHA هدف اجرا شود: +`Full Release Validation` روشی است که operatorها با آن همه آزمون‌های پیش از انتشار را از یک نقطه ورود آغاز می‌کنند. برای اثبات commit پین‌شده روی branch پرتحرک، از helper استفاده کنید تا هر workflow فرزند از یک branch موقت ثابت‌شده روی SHA هدف اجرا شود: ```bash pnpm ci:full-release --sha ``` -helper مقدار `release-ci/-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=` dispatch می‌کند، بررسی می‌کند که `headSha` هر workflow فرزند با هدف مطابقت داشته باشد، سپس branch موقت را حذف می‌کند. این کار از اثبات تصادفی یک اجرای فرزند جدیدتر روی `main` جلوگیری می‌کند. +این helper، `release-ci/-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=` dispatch می‌کند، بررسی می‌کند که `headSha` هر workflow فرزند با هدف مطابقت داشته باشد، سپس branch موقت را حذف می‌کند. این کار جلوی اثبات تصادفی اجرای فرزند جدیدتر `main` را می‌گیرد. -برای اعتبارسنجی branch یا tag انتشار، آن را از workflow ref قابل اعتماد `main` اجرا کنید و branch یا tag انتشار را به‌عنوان `ref` پاس بدهید: +برای اعتبارسنجی branch یا tag انتشار، آن را از ref workflow مطمئن `main` اجرا کنید و branch یا tag انتشار را به‌عنوان `ref` بدهید: ```bash gh workflow run full-release-validation.yml \ @@ -179,47 +187,35 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -گردش‌کار، ref هدف را resolve می‌کند، `CI` دستی را با -`target_ref=` dispatch می‌کند، `OpenClaw Release Checks` را dispatch می‌کند، یک -artifact والد `release-package-under-test` را برای بررسی‌های مرتبط با بسته آماده می‌کند، و -وقتی `release_profile=full` با `rerun_group=all` باشد یا وقتی -`npm_telegram_package_spec` تنظیم شده باشد، E2E مستقل بسته Telegram را dispatch می‌کند. سپس `OpenClaw Release -Checks` بررسی‌های install smoke، بررسی‌های انتشار cross-OS، پوشش مسیر انتشار live/E2E Docker، -Package Acceptance با QA بسته Telegram، برابری QA Lab، -Matrix زنده، و Telegram زنده را fan out می‌کند. یک اجرای کامل فقط زمانی قابل قبول است که -خلاصه‌ی `Full Release Validation` -`normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all، -فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all، مگر اینکه -یک `npm_telegram_package_spec` منتشرشده ارائه شده باشد، skip می‌شود. خلاصه‌ی نهایی -verifier شامل جدول‌های کندترین job برای هر اجرای فرزند است، تا مدیر انتشار بتواند -مسیر بحرانی فعلی را بدون دانلود logها ببیند. -برای matrix کامل مرحله‌ها، نام دقیق jobهای workflow، تفاوت‌های پروفایل stable در برابر full، -artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. -workflowهای فرزند از ref مورد اعتماد که `Full Release -Validation` را اجرا می‌کند dispatch می‌شوند، معمولاً `--ref main`، حتی وقتی target `ref` به یک -شاخه یا tag انتشار قدیمی‌تر اشاره کند. ورودی جداگانه‌ای برای workflow-ref در Full Release Validation -وجود ندارد؛ harness مورد اعتماد را با انتخاب ref اجرای workflow انتخاب کنید. -برای اثبات commit دقیق روی `main` متحرک از `--ref main -f ref=` استفاده نکنید؛ -SHAهای خام commit نمی‌توانند refهای workflow dispatch باشند، پس از -`pnpm ci:full-release --sha ` برای ساخت شاخه‌ی موقت pinned استفاده کنید. +گردش‌کار ارجاع هدف را حل می‌کند، `CI` دستی را با +`target_ref=` راه‌اندازی می‌کند، `OpenClaw Release Checks` را راه‌اندازی می‌کند، یک آرتیفکت والد `release-package-under-test` برای بررسی‌های مرتبط با بسته آماده می‌کند، و E2E مستقل Telegram برای بسته را وقتی `release_profile=full` همراه با +`rerun_group=all` باشد یا وقتی `npm_telegram_package_spec` تنظیم شده باشد راه‌اندازی می‌کند. سپس `OpenClaw Release +Checks` تست اولیه نصب، بررسی‌های چندسیستم‌عاملی انتشار، پوشش Docker زنده/E2E در مسیر انتشار وقتی آزمون ماندگاری فعال باشد، پذیرش بسته با QA بسته Telegram، برابری QA Lab، Matrix زنده، و Telegram زنده را منشعب می‌کند. یک اجرای کامل فقط زمانی قابل‌قبول است که خلاصه‌ی +`Full Release Validation` +، `normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all، +فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all، مگر اینکه `npm_telegram_package_spec` منتشرشده‌ای ارائه شده باشد، رد می‌شود. خلاصه راستی‌آزمای نهایی شامل جدول‌های کندترین کار برای هر اجرای فرزند است، تا مدیر انتشار بتواند مسیر بحرانی فعلی را بدون دانلود لاگ‌ها ببیند. +برای ماتریس کامل مراحل، نام دقیق jobهای گردش‌کار، تفاوت‌های پروفایل پایدار و کامل، آرتیفکت‌ها، و دستگیره‌های اجرای دوباره متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. +گردش‌کارهای فرزند از ارجاع مورد اعتمادی راه‌اندازی می‌شوند که `Full Release +Validation` را اجرا می‌کند، معمولاً `--ref main`، حتی وقتی `ref` هدف به شاخه یا تگ انتشار قدیمی‌تری اشاره کند. هیچ ورودی جداگانه‌ای برای workflow-ref اعتبارسنجی کامل انتشار وجود ندارد؛ هارنس مورد اعتماد را با انتخاب ارجاع اجرای گردش‌کار انتخاب کنید. +برای اثبات کامیت دقیق روی `main` متحرک، از `--ref main -f ref=` استفاده نکنید؛ +SHAهای خام کامیت نمی‌توانند ارجاع dispatch گردش‌کار باشند، پس از +`pnpm ci:full-release --sha ` برای ساخت شاخه موقت پین‌شده استفاده کنید. -برای انتخاب گستره‌ی live/provider از `release_profile` استفاده کنید: +از `release_profile` برای انتخاب گستره زنده/ارائه‌دهنده استفاده کنید: -- `minimum`: سریع‌ترین مسیر live و Docker حیاتی برای انتشار OpenAI/core -- `stable`: minimum به‌علاوه‌ی پوشش provider/backend پایدار برای تأیید انتشار -- `full`: stable به‌علاوه‌ی پوشش گسترده‌ی advisory provider/media +- `minimum`: سریع‌ترین مسیر زنده OpenAI/هسته و Docker که برای انتشار حیاتی است +- `stable`: حداقل به‌همراه پوشش پایدار ارائه‌دهنده/بک‌اند برای تأیید انتشار +- `full`: پایدار به‌همراه پوشش گسترده مشورتی ارائه‌دهنده/رسانه -`OpenClaw Release Checks` از ref مورد اعتماد workflow استفاده می‌کند تا ref هدف را -یک‌بار به‌عنوان `release-package-under-test` resolve کند و همان artifact را هم در -بررسی‌های Docker مسیر انتشار و هم در Package Acceptance دوباره به کار ببرد. این کار همه‌ی -boxهای مرتبط با بسته را روی byteهای یکسان نگه می‌دارد و از ساخت‌های تکراری بسته جلوگیری می‌کند. -install smoke مربوط به cross-OS OpenAI وقتی متغیر repo/org تنظیم شده باشد از -`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، چون این lane در حال -اثبات نصب بسته، onboarding، راه‌اندازی Gateway، و یک نوبت agent زنده است -نه benchmark کردن کندترین مدل پیش‌فرض. matrix گسترده‌تر provider زنده همچنان محل -پوشش اختصاصی مدل‌ها باقی می‌ماند. +از `run_release_soak=true` همراه با `stable` زمانی استفاده کنید که مسیرهای مسدودکننده انتشار +موفق‌اند و می‌خواهید پیش از ارتقا، جاروب کامل زنده/E2E، مسیر انتشار Docker، و بازماندن از ارتقا برای همه نسخه‌ها از 2026.4.23 به بعد اجرا شود. `full` به‌طور ضمنی +`run_release_soak=true` را فعال می‌کند. -بسته به مرحله‌ی انتشار از این variantها استفاده کنید: +`OpenClaw Release Checks` از ارجاع گردش‌کار مورد اعتماد استفاده می‌کند تا ارجاع هدف را یک بار به‌عنوان +`release-package-under-test` حل کند و وقتی آزمون ماندگاری اجرا می‌شود، همان آرتیفکت را در بررسی‌های چندسیستم‌عاملی، پذیرش بسته، و بررسی‌های Docker مسیر انتشار دوباره به‌کار می‌برد. این کار همه محیط‌های مرتبط با بسته را روی بایت‌های یکسان نگه می‌دارد و از ساخت‌های تکراری بسته جلوگیری می‌کند. +تست اولیه نصب OpenAI در چند سیستم‌عامل وقتی متغیر مخزن/سازمان تنظیم شده باشد از `OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، چون این مسیر نصب بسته، آغازبه‌کار، راه‌اندازی Gateway، و یک نوبت زنده عامل را اثبات می‌کند، نه محک‌زدن کندترین مدل پیش‌فرض را. ماتریس گسترده‌تر ارائه‌دهنده زنده همچنان محل پوشش مختص مدل است. + +بسته به مرحله انتشار از این گونه‌ها استفاده کنید: ```bash # Validate an unpublished release candidate branch. @@ -249,41 +245,38 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -پس از یک fix متمرکز، از umbrella کامل به‌عنوان اولین rerun استفاده نکنید. اگر یک box -fail شود، برای اثبات بعدی از workflow فرزند fail‌شده، job، Docker lane، پروفایل بسته، provider مدل، -یا QA lane استفاده کنید. umbrella کامل را فقط وقتی دوباره اجرا کنید که -fix، orchestration مشترک انتشار را تغییر داده باشد یا شواهد قبلی همه‌ی boxها را -کهنه کرده باشد. verifier نهایی umbrella دوباره idهای ثبت‌شده‌ی اجرای workflow فرزند -را بررسی می‌کند، پس بعد از اینکه یک workflow فرزند با موفقیت rerun شد، فقط job والد fail‌شده‌ی -`Verify full validation` را rerun کنید. +از چتر کامل به‌عنوان نخستین اجرای دوباره پس از یک اصلاح متمرکز استفاده نکنید. اگر یک محیط +ناموفق شد، برای اثبات بعدی از گردش‌کار فرزند، کار، مسیر Docker، پروفایل بسته، ارائه‌دهنده مدل، یا مسیر QA ناموفق استفاده کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که +اصلاح، هماهنگ‌سازی مشترک انتشار را تغییر داده باشد یا شواهد قبلی همه محیط‌ها را کهنه کرده باشد. راستی‌آزمای نهایی چتر، شناسه‌های ثبت‌شده اجرای گردش‌کارهای فرزند را دوباره بررسی می‌کند، بنابراین پس از اینکه یک گردش‌کار فرزند با موفقیت دوباره اجرا شد، فقط کار والد ناموفق +`Verify full validation` را دوباره اجرا کنید. -برای بازیابی bounded، `rerun_group` را به umbrella پاس دهید. `all` اجرای واقعی -release-candidate است، `ci` فقط فرزند CI معمولی را اجرا می‌کند، `plugin-prerelease` -فقط فرزند مخصوص انتشار Plugin را اجرا می‌کند، `release-checks` همه‌ی boxهای انتشار -را اجرا می‌کند، و گروه‌های محدودتر انتشار عبارت‌اند از `install-smoke`، `cross-os`، +برای بازیابی محدود، `rerun_group` را به چتر بدهید. `all` اجرای واقعی +نامزد انتشار است، `ci` فقط فرزند CI معمول را اجرا می‌کند، `plugin-prerelease` +فقط فرزند Plugin مخصوص انتشار را اجرا می‌کند، `release-checks` همه محیط‌های انتشار را اجرا می‌کند، و گروه‌های انتشار باریک‌تر عبارت‌اند از `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، و `npm-telegram`. -rerunهای متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارند؛ اجراهای full/all -با `release_profile=full` از artifact بسته‌ی release-checks استفاده می‌کنند. +اجرای دوباره متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارد؛ اجراهای full/all +با `release_profile=full` از آرتیفکت بسته بررسی‌های انتشار استفاده می‌کنند. اجرای دوباره متمرکز چندسیستم‌عاملی می‌تواند `cross_os_suite_filter=windows/packaged-upgrade` یا +فیلتر OS/مجموعه دیگری اضافه کند. خرابی‌های QA در بررسی‌های انتشار مشورتی هستند؛ خرابی فقط QA +اعتبارسنجی انتشار را مسدود نمی‌کند. ### Vitest -box مربوط به Vitest همان workflow فرزند `CI` دستی است. CI دستی عمداً -scoping تغییرات را دور می‌زند و graph معمول test را برای release candidate اجبار می‌کند: -shardهای Linux Node، shardهای Pluginهای bundled، contractهای channel، سازگاری Node 22، -`check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، -macOS، Android، و Control UI i18n. +محیط Vitest همان گردش‌کار فرزند `CI` دستی است. CI دستی عمداً +دامنه‌بندی تغییرات را دور می‌زند و گراف تست معمول را برای نامزد انتشار اجباری می‌کند: +شاردهای Linux Node، شاردهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، +`check`، `check-additional`، تست اولیه ساخت، بررسی‌های مستندات، Skills پایتون، Windows، macOS، Android، و Control UI i18n. -از این box برای پاسخ به این پرسش استفاده کنید: «آیا source tree کل test suite معمول را پاس کرده است؟» +از این محیط برای پاسخ به «آیا درخت منبع کل مجموعه تست معمول را با موفقیت گذراند؟» استفاده کنید. این با اعتبارسنجی محصول در مسیر انتشار یکسان نیست. شواهدی که باید نگه دارید: -- خلاصه‌ی `Full Release Validation` که URL اجرای `CI` dispatch‌شده را نشان می‌دهد -- اجرای `CI` سبز روی SHA دقیق هدف -- نام shardهای fail‌شده یا کند از jobهای CI هنگام بررسی regressionها -- artifactهای timing Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی +- خلاصه‌ی `Full Release Validation` که URL اجرای `CI` راه‌اندازی‌شده را نشان می‌دهد +- موفق بودن اجرای `CI` روی SHA هدف دقیق +- نام شاردهای ناموفق یا کند از jobهای CI هنگام بررسی رگرسیون‌ها +- آرتیفکت‌های زمان‌بندی Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی یک اجرا به تحلیل کارایی نیاز دارد -CI دستی را مستقیماً فقط وقتی اجرا کنید که انتشار به CI معمول deterministic نیاز داشته باشد اما -به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز نداشته باشد: +CI دستی را فقط زمانی مستقیم اجرا کنید که انتشار به CI معمول قطعی نیاز دارد اما +به محیط‌های Docker، QA Lab، زنده، چندسیستم‌عاملی، یا بسته نیاز ندارد: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -291,106 +284,87 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -box مربوط به Docker درون `OpenClaw Release Checks` از طریق -`openclaw-live-and-e2e-checks-reusable.yml`، به‌علاوه‌ی workflow -`install-smoke` در حالت release قرار دارد. این box، release candidate را از طریق محیط‌های -Docker بسته‌بندی‌شده اعتبارسنجی می‌کند، نه فقط testهای سطح source. +محیط Docker در `OpenClaw Release Checks` از طریق +`openclaw-live-and-e2e-checks-reusable.yml`، به‌همراه گردش‌کار حالت انتشار +`install-smoke` قرار دارد. این محیط نامزد انتشار را از طریق محیط‌های Docker بسته‌بندی‌شده اعتبارسنجی می‌کند، نه فقط با تست‌های سطح منبع. -پوشش Docker انتشار شامل موارد زیر است: +پوشش Docker انتشار شامل این موارد است: -- install smoke کامل با فعال بودن smoke نصب global کند Bun -- آماده‌سازی/استفاده‌ی دوباره از image smoke ریشه‌ی Dockerfile براساس SHA هدف، با jobهای QR، - root/gateway، و installer/Bun smoke که به‌عنوان shardهای جداگانه‌ی install-smoke اجرا می‌شوند -- laneهای E2E repository -- chunkهای Docker مسیر انتشار: `core`، `package-update-openai`، +- تست اولیه کامل نصب با تست اولیه کند نصب سراسری Bun فعال +- آماده‌سازی/استفاده‌مجدد تصویر تست اولیه Dockerfile ریشه بر اساس SHA هدف، با کارهای تست اولیه QR، + root/gateway، و installer/Bun که به‌عنوان شاردهای جداگانه install-smoke اجرا می‌شوند +- مسیرهای E2E مخزن +- قطعه‌های Docker مسیر انتشار: `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، `plugins-runtime-install-a`، `plugins-runtime-install-b`، `plugins-runtime-install-c`، `plugins-runtime-install-d`، `plugins-runtime-install-e`، `plugins-runtime-install-f`، `plugins-runtime-install-g`، و `plugins-runtime-install-h` -- پوشش OpenWebUI داخل chunk `plugins-runtime-services` وقتی درخواست شده باشد -- laneهای جداشده‌ی نصب/حذف Plugin bundled +- پوشش OpenWebUI درون قطعه‌ی `plugins-runtime-services` هنگام درخواست +- مسیرهای جداشده نصب/حذف Plugin بسته‌بندی‌شده `bundled-plugin-install-uninstall-0` تا `bundled-plugin-install-uninstall-23` -- suiteهای provider زنده/E2E و پوشش مدل زنده‌ی Docker وقتی release checks - شامل suiteهای live باشند +- مجموعه‌های زنده/E2E ارائه‌دهنده و پوشش مدل زنده Docker وقتی بررسی‌های انتشار + مجموعه‌های زنده را شامل شوند -پیش از rerun از artifactهای Docker استفاده کنید. scheduler مسیر انتشار -`.artifacts/docker-tests/` را با logهای lane، `summary.json`، `failures.json`, -timingهای phase، JSON طرح scheduler، و دستورهای rerun upload می‌کند. برای بازیابی متمرکز، -به‌جای rerun کردن همه‌ی chunkهای انتشار، روی workflow live/E2E قابل استفاده‌مجدد از -`docker_lanes=` استفاده کنید. دستورهای rerun تولیدشده وقتی موجود باشند شامل -`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده‌ی Docker هستند، تا یک -lane fail‌شده بتواند از همان tarball و imageهای GHCR دوباره استفاده کند. +پیش از اجرای دوباره، از آرتیفکت‌های Docker استفاده کنید. زمان‌بند مسیر انتشار +`.artifacts/docker-tests/` را با لاگ‌های مسیر، `summary.json`، `failures.json`، +زمان‌بندی فازها، JSON طرح زمان‌بند، و فرمان‌های اجرای دوباره بارگذاری می‌کند. برای بازیابی متمرکز، +به‌جای اجرای دوباره همه قطعه‌های انتشار، از `docker_lanes=` روی گردش‌کار زنده/E2E قابل‌استفاده‌مجدد استفاده کنید. فرمان‌های تولیدشده اجرای دوباره، `package_artifact_run_id` قبلی و ورودی‌های تصویر Docker آماده‌شده را، در صورت وجود، شامل می‌شوند؛ بنابراین یک +مسیر ناموفق می‌تواند از همان آرشیو tar و تصاویر GHCR استفاده مجدد کند. ### QA Lab -box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate انتشار مربوط به -رفتار agentic و سطح channel است، جدا از Vitest و سازوکارهای package Docker. +محیط QA Lab نیز بخشی از `OpenClaw Release Checks` است. این دروازه انتشار برای +رفتار عامل‌محور و سطح کانال است و از Vitest و سازوکارهای بسته Docker جداست. -پوشش QA Lab انتشار شامل موارد زیر است: +پوشش QA Lab انتشار شامل این موارد است: -- lane برابری mock که lane candidate OpenAI را با baseline Opus 4.6 - با استفاده از agentic parity pack مقایسه می‌کند -- پروفایل سریع QA زنده‌ی Matrix با استفاده از محیط `qa-live-shared` -- lane QA زنده‌ی Telegram با استفاده از leaseهای credential مربوط به Convex CI -- `pnpm qa:otel:smoke` وقتی telemetry انتشار به اثبات محلی صریح نیاز داشته باشد +- مسیر برابری شبیه‌سازی‌شده که مسیر نامزد OpenAI را با خط مبنای Opus 4.6 + با استفاده از بسته برابری عامل‌محور مقایسه می‌کند +- پروفایل سریع QA زنده Matrix با استفاده از محیط `qa-live-shared` +- مسیر QA زنده Telegram با استفاده از اجاره‌های اعتبارنامه Convex CI +- `pnpm qa:otel:smoke` وقتی تله‌متری انتشار به اثبات محلی صریح نیاز دارد -از این box برای پاسخ به این پرسش استفاده کنید: «آیا انتشار در سناریوهای QA و -flowهای channel زنده درست رفتار می‌کند؟» هنگام تأیید انتشار، URLهای artifact برای laneهای برابری، -Matrix، و Telegram را نگه دارید. پوشش کامل Matrix همچنان به‌عنوان اجرای دستی sharded QA-Lab -در دسترس است، نه lane حیاتی پیش‌فرض برای انتشار. +از این محیط برای پاسخ به «آیا انتشار در سناریوهای QA و جریان‌های زنده کانال درست رفتار می‌کند؟» استفاده کنید. هنگام تأیید انتشار، URLهای آرتیفکت را برای مسیرهای برابری، Matrix، و Telegram نگه دارید. پوشش کامل Matrix همچنان به‌صورت اجرای دستی شاردشده QA-Lab در دسترس است، نه مسیر پیش‌فرض حیاتی برای انتشار. -### Package +### بسته -box مربوط به Package همان gate محصول قابل‌نصب است. این box با -`Package Acceptance` و resolver -`scripts/resolve-openclaw-package-candidate.mjs` پشتیبانی می‌شود. resolver یک -candidate را به tarball `package-under-test` مصرف‌شده توسط Docker E2E normalize می‌کند، -inventory بسته را اعتبارسنجی می‌کند، نسخه‌ی بسته و SHA-256 را ثبت می‌کند، و ref -harness workflow را از ref source بسته جدا نگه می‌دارد. +محیط بسته دروازه محصول قابل نصب است. پشتوانه آن +`Package Acceptance` و حل‌کننده +`scripts/resolve-openclaw-package-candidate.mjs` است. حل‌کننده یک نامزد را به آرشیو tar `package-under-test` مصرف‌شده توسط Docker E2E نرمال می‌کند، موجودی بسته را اعتبارسنجی می‌کند، نسخه بسته و SHA-256 را ثبت می‌کند، و ارجاع هارنس گردش‌کار را از ارجاع منبع بسته جدا نگه می‌دارد. -sourceهای candidate پشتیبانی‌شده: +منابع نامزد پشتیبانی‌شده: -- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه‌ی دقیق انتشار OpenClaw -- `source=ref`: بسته‌بندی یک شاخه، tag، یا SHA کامل commit مربوط به `package_ref` مورد اعتماد - با harness انتخاب‌شده‌ی `workflow_ref` -- `source=url`: دانلود یک `.tgz` از HTTPS با `package_sha256` الزامی -- `source=artifact`: استفاده‌ی دوباره از یک `.tgz` uploadشده توسط اجرای دیگری از GitHub Actions +- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار OpenClaw +- `source=ref`: یک شاخه، تگ، یا SHA کامل کامیتِ مورد اعتماد `package_ref` را + با هارنس منتخب `workflow_ref` بسته‌بندی کنید +- `source=url`: یک `.tgz` از HTTPS با `package_sha256` الزامی دانلود کنید +- `source=artifact`: از یک `.tgz` بارگذاری‌شده توسط اجرای دیگری از GitHub Actions دوباره استفاده کنید -`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`، artifact -بسته‌ی آماده‌شده‌ی انتشار، `suite_profile=custom`، +`OpenClaw Release Checks` پذیرش بسته را با `source=artifact`، آرتیفکت آماده بسته انتشار، +`suite_profile=custom`، `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`، -`published_upgrade_survivor_baselines=all-since-2026.4.23`، -`published_upgrade_survivor_scenarios=reported-issues`، و -`telegram_mode=mock-openai` اجرا می‌کند. Package Acceptance، migration، update، پاک‌سازی -وابستگی stale Plugin، fixtureهای Plugin offline، update Plugin، و QA بسته Telegram -را در برابر همان tarball resolve‌شده نگه می‌دارد. matrix upgrade هر baseline پایدار منتشرشده در npm را از `2026.4.23` تا `latest` پوشش می‌دهد؛ برای یک candidate که قبلاً منتشر شده است از -Package Acceptance با `source=npm` استفاده کنید، یا برای یک tarball محلی npm مبتنی بر SHA پیش از -publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین native در GitHub -برای بیشتر پوشش package/update است که قبلاً به Parallels نیاز داشت. -بررسی‌های انتشار cross-OS همچنان برای onboarding، installer، و رفتار platform خاص OS مهم‌اند، -اما اعتبارسنجی محصول package/update باید Package Acceptance را ترجیح دهد. +`telegram_mode=mock-openai` اجرا می‌کند. پذیرش بسته، مهاجرت، به‌روزرسانی، پاک‌سازی وابستگی‌های کهنه Plugin، فیکسچرهای آفلاین Plugin، به‌روزرسانی Plugin، و QA بسته Telegram را روی همان آرشیو tar حل‌شده نگه می‌دارد. بررسی‌های مسدودکننده انتشار از خط مبنای پیش‌فرضِ آخرین بسته منتشرشده استفاده می‌کنند؛ `run_release_soak=true` یا +`release_profile=full` این را به هر خط مبنای پایدار منتشرشده در npm از +`2026.4.23` تا `latest` به‌همراه فیکسچرهای issueهای گزارش‌شده گسترش می‌دهد. برای نامزدی که قبلاً منتشر شده است از پذیرش بسته با `source=npm` استفاده کنید، یا +پیش از انتشار، برای آرشیو tar محلی npm با پشتوانه SHA از `source=ref`/`source=artifact` استفاده کنید. این، جایگزین بومی GitHub برای بیشتر پوشش بسته/به‌روزرسانی است که پیش‌تر به +Parallels نیاز داشت. بررسی‌های چندسیستم‌عاملی انتشار همچنان برای آغازبه‌کار، نصب‌کننده، و رفتار پلتفرمی مختص OS مهم‌اند، اما اعتبارسنجی محصول بسته/به‌روزرسانی باید پذیرش بسته را ترجیح دهد. -checklist canonical برای اعتبارسنجی update و Plugin این است: -[آزمایش updateها و Pluginها](/fa/help/testing-updates-plugins). هنگام تصمیم‌گیری درباره‌ی اینکه -کدام lane محلی، Docker، Package Acceptance، یا release-check یک تغییر نصب/update Plugin، -پاک‌سازی doctor، یا migration بسته‌ی منتشرشده را اثبات می‌کند، از آن استفاده کنید. -migration کامل update منتشرشده از هر بسته‌ی پایدار `2026.4.23+` -یک workflow دستی جداگانه‌ی `Update Migration` است، نه بخشی از Full Release CI. +چک‌لیست مرجع برای اعتبارسنجی به‌روزرسانی و Plugin، +[تست به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) است. از آن هنگام +تصمیم‌گیری درباره اینکه کدام مسیر محلی، Docker، پذیرش بسته، یا بررسی انتشار، تغییر نصب/به‌روزرسانی Plugin، پاک‌سازی doctor، یا مهاجرت بسته منتشرشده را اثبات می‌کند، استفاده کنید. +مهاجرت کامل به‌روزرسانی منتشرشده از هر بسته پایدار `2026.4.23+` +یک گردش‌کار دستی جداگانه `Update Migration` است، نه بخشی از CI کامل انتشار. -leniency قدیمی package-acceptance عمداً time boxed است. بسته‌ها تا -`2026.4.25` می‌توانند برای gapهای metadata که قبلاً در npm منتشر شده‌اند -از مسیر compatibility استفاده کنند: entryهای private QA inventory که در tarball وجود ندارند، -نبود `gateway install --wrapper`، نبود patch fileها در fixture git مشتق‌شده از tarball، -نبود `update.channel` persisted، محل‌های قدیمی install-record مربوط به Plugin، -نبود persistence برای install-record marketplace، و migration metadata config -در طول `plugins update`. بسته‌ی منتشرشده‌ی `2026.4.26` ممکن است برای فایل‌های stamp -metadata ساخت محلی که قبلاً ship شده‌اند warning بدهد. بسته‌های بعدی باید -contractهای مدرن package را برآورده کنند؛ همان gapها باعث fail شدن اعتبارسنجی انتشار می‌شوند. +سهل‌گیری قدیمی پذیرش بسته عمداً محدود به بازه زمانی است. بسته‌ها تا +`2026.4.25` ممکن است از مسیر سازگاری برای شکاف‌های فراداده‌ای که قبلاً +در npm منتشر شده‌اند استفاده کنند: مدخل‌های خصوصی موجودی QA که در آرشیو tar نیستند، نبود +`gateway install --wrapper`، نبود فایل‌های patch در fixture git مشتق‌شده از آرشیو tar، مکان‌های قدیمی رکورد نصب Plugin، نبود ماندگاری رکورد نصب بازارچه، و مهاجرت فراداده پیکربندی هنگام `plugins update`. بسته منتشرشده `2026.4.26` ممکن است برای فایل‌های مهر فراداده ساخت محلی که قبلاً منتشر شده بودند هشدار دهد. بسته‌های بعدی +باید قراردادهای مدرن بسته را برآورده کنند؛ همان شکاف‌ها اعتبارسنجی انتشار را ناموفق می‌کنند. -وقتی پرسش انتشار درباره‌ی یک بسته‌ی واقعاً قابل‌نصب است، از پروفایل‌های گسترده‌تر Package Acceptance استفاده کنید: +وقتی پرسش انتشار درباره یک بسته قابل نصب واقعی است، از پروفایل‌های گسترده‌تر پذیرش بسته استفاده کنید: ```bash gh workflow run package-acceptance.yml \ @@ -402,33 +376,37 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -پروفایل‌های رایج package: +پروفایل‌های رایج بسته: -- `smoke`: مسیرهای سریع نصب package/channel/agent، شبکه Gateway، و بارگذاری دوباره config -- `package`: قراردادهای نصب/به‌روزرسانی/Plugin package بدون ClawHub زنده؛ این پیش‌فرض release-check است -- `product`: `package` به‌همراه channelهای MCP، پاک‌سازی Cron/زیرعامل، جست‌وجوی وب OpenAI، و OpenWebUI +- `smoke`: مسیرهای سریع نصب بسته/کانال/عامل، شبکه Gateway، و بارگذاری مجدد + پیکربندی +- `package`: قراردادهای نصب/به‌روزرسانی/بسته Plugin بدون ClawHub زنده؛ این پیش‌فرض + بررسی انتشار است +- `product`: `package` به‌علاوه کانال‌های MCP، پاک‌سازی Cron/زیرعامل، جست‌وجوی وب + OpenAI، و OpenWebUI - `full`: بخش‌های مسیر انتشار Docker با OpenWebUI - `custom`: فهرست دقیق `docker_lanes` برای اجرای دوباره متمرکز -برای اثبات Telegram نامزد package، `telegram_mode=mock-openai` یا -`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. workflow، فایل tarball حل‌شده -`package-under-test` را به مسیر Telegram می‌دهد؛ workflow مستقل -Telegram همچنان یک مشخصه منتشرشده npm را برای بررسی‌های پس از انتشار می‌پذیرد. +برای اثبات Telegram نامزد بسته، `telegram_mode=mock-openai` یا +`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. گردش‌کار، +tarball حل‌شده `package-under-test` را به مسیر Telegram پاس می‌دهد؛ گردش‌کار مستقل +Telegram همچنان یک مشخصه npm منتشرشده را برای بررسی‌های پس از انتشار می‌پذیرد. -## خودکارسازی انتشار release +## خودکارسازی انتشار -`OpenClaw Release Publish` نقطه ورود معمول انتشار تغییردهنده است. این workflowهای trusted-publisher را به ترتیبی که release نیاز دارد هماهنگ می‌کند: +`OpenClaw Release Publish` نقطه ورود عادی انتشار تغییردهنده است. این مورد +گردش‌کارهای trusted-publisher را به ترتیبی که انتشار نیاز دارد هماهنگ می‌کند: -1. تگ release را check out می‌کند و commit SHA آن را حل می‌کند. +1. تگ انتشار را checkout می‌کند و SHA کامیت آن را حل می‌کند. 2. بررسی می‌کند که تگ از `main` یا `release/*` قابل دسترسی باشد. 3. `pnpm plugins:sync:check` را اجرا می‌کند. 4. `Plugin NPM Release` را با `publish_scope=all-publishable` و `ref=` dispatch می‌کند. 5. `Plugin ClawHub Release` را با همان scope و SHA dispatch می‌کند. -6. `OpenClaw NPM Release` را با تگ release، dist-tag مربوط به npm، و +6. `OpenClaw NPM Release` را با تگ انتشار، dist-tag مربوط به npm، و `preflight_run_id` ذخیره‌شده dispatch می‌کند. -نمونه انتشار beta: +نمونه انتشار بتا: ```bash gh workflow run openclaw-release-publish.yml \ @@ -438,7 +416,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -انتشار پایدار به dist-tag پیش‌فرض beta: +انتشار پایدار به dist-tag بتای پیش‌فرض: ```bash gh workflow run openclaw-release-publish.yml \ @@ -448,7 +426,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -ارتقای پایدار مستقیما به `latest` صریح است: +ارتقای پایدار مستقیم به `latest` صریح است: ```bash gh workflow run openclaw-release-publish.yml \ @@ -458,70 +436,95 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -از workflowهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release` فقط برای کار تعمیر یا بازنشر متمرکز استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده، +از گردش‌کارهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release` +فقط برای تعمیر متمرکز یا انتشار دوباره استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده، `plugin_publish_scope=selected` و `plugins=@openclaw/name` را به -`OpenClaw Release Publish` بدهید، یا وقتی package مربوط به OpenClaw نباید منتشر شود، workflow فرزند را مستقیما dispatch کنید. +`OpenClaw Release Publish` بدهید، یا وقتی بسته OpenClaw نباید منتشر شود، +گردش‌کار فرزند را مستقیم dispatch کنید. -## ورودی‌های workflow مربوط به NPM +## ورودی‌های گردش‌کار NPM -`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: +`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: -- `tag`: تگ release الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا - `v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، برای preflight فقط اعتبارسنجی می‌تواند SHA کامل ۴۰ کاراکتری commit فعلی شاخه workflow هم باشد -- `preflight_only`: مقدار `true` فقط برای اعتبارسنجی/ساخت/package، و `false` برای مسیر انتشار واقعی -- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا workflow از tarball آماده‌شده اجرای preflight موفق دوباره استفاده کند -- `npm_dist_tag`: تگ هدف npm برای مسیر انتشار؛ پیش‌فرض آن `beta` است +- `tag`: تگ انتشار الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا + `v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، می‌تواند SHA کامل + ۴۰ نویسه‌ای کامیت شاخه گردش‌کار فعلی برای preflight فقط اعتبارسنجی نیز باشد +- `preflight_only`: مقدار `true` برای فقط اعتبارسنجی/ساخت/بسته، و `false` برای + مسیر انتشار واقعی +- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا گردش‌کار از tarball + آماده‌شده در اجرای preflight موفق دوباره استفاده کند +- `npm_dist_tag`: تگ هدف npm برای مسیر انتشار؛ مقدار پیش‌فرض `beta` است -`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: +`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: -- `tag`: تگ release الزامی؛ باید از قبل وجود داشته باشد +- `tag`: تگ انتشار الزامی؛ باید از قبل وجود داشته باشد - `preflight_run_id`: شناسه اجرای preflight موفق `OpenClaw NPM Release`؛ وقتی `publish_openclaw_npm=true` باشد الزامی است -- `npm_dist_tag`: تگ هدف npm برای package مربوط به OpenClaw -- `plugin_publish_scope`: پیش‌فرض آن `all-publishable` است؛ فقط برای کار تعمیر متمرکز از `selected` استفاده کنید -- `plugins`: نام‌های package با جداکننده ویرگول از نوع `@openclaw/*` وقتی +- `npm_dist_tag`: تگ هدف npm برای بسته OpenClaw +- `plugin_publish_scope`: پیش‌فرض `all-publishable` است؛ فقط برای کار تعمیر + متمرکز از `selected` استفاده کنید +- `plugins`: نام بسته‌های `@openclaw/*` که با کاما جدا شده‌اند، وقتی `plugin_publish_scope=selected` باشد -- `publish_openclaw_npm`: پیش‌فرض آن `true` است؛ فقط وقتی workflow را به‌عنوان هماهنگ‌کننده تعمیر صرفا Plugin استفاده می‌کنید، آن را `false` تنظیم کنید +- `publish_openclaw_npm`: پیش‌فرض `true` است؛ فقط وقتی گردش‌کار را به‌عنوان + هماهنگ‌کننده تعمیر فقط Plugin استفاده می‌کنید، آن را روی `false` بگذارید -`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: +`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: -- `ref`: شاخه، تگ، یا SHA کامل commit برای اعتبارسنجی. بررسی‌های دارای secret نیاز دارند commit حل‌شده از یک شاخه OpenClaw یا تگ release قابل دسترسی باشد. +- `ref`: شاخه، تگ، یا SHA کامل کامیت برای اعتبارسنجی. بررسی‌های دارای secret + نیاز دارند کامیت حل‌شده از یک شاخه OpenClaw یا تگ انتشار قابل دسترسی باشد. +- `run_release_soak`: در بررسی‌های انتشار پایدار/پیش‌فرض، soak کامل زنده/E2E، + مسیر انتشار Docker، و upgrade-survivor همه نسخه‌ها را فعال می‌کند. با + `release_profile=full` اجباری فعال می‌شود. قواعد: -- تگ‌های پایدار و اصلاحی می‌توانند در `beta` یا `latest` منتشر شوند -- تگ‌های پیش‌انتشار beta فقط می‌توانند در `beta` منتشر شوند -- برای `OpenClaw NPM Release`، ورودی SHA کامل commit فقط وقتی مجاز است که +- تگ‌های پایدار و اصلاحی می‌توانند به `beta` یا `latest` منتشر شوند +- تگ‌های پیش‌انتشار بتا فقط می‌توانند به `beta` منتشر شوند +- برای `OpenClaw NPM Release`، ورودی SHA کامل کامیت فقط وقتی مجاز است که `preflight_only=true` باشد - `OpenClaw Release Checks` و `Full Release Validation` همیشه فقط اعتبارسنجی هستند -- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که در preflight استفاده شده است؛ workflow پیش از ادامه انتشار، آن metadata را بررسی می‌کند +- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که در preflight + استفاده شده است؛ گردش‌کار پیش از ادامه انتشار، آن فراداده را بررسی می‌کند -## توالی release پایدار npm +## توالی انتشار پایدار npm -هنگام ایجاد یک release پایدار npm: +هنگام ساخت یک انتشار پایدار npm: 1. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید - - پیش از وجود تگ، می‌توانید از SHA کامل commit فعلی شاخه workflow برای اجرای آزمایشی فقط اعتبارسنجی workflow مربوط به preflight استفاده کنید -2. برای جریان عادی beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی عمدا انتشار پایدار مستقیم می‌خواهید `latest` را انتخاب کنید -3. وقتی می‌خواهید CI عادی به‌همراه پوشش live prompt cache، Docker، QA Lab، - Matrix، و Telegram را از یک workflow دستی داشته باشید، `Full Release Validation` را روی شاخه release، تگ release، یا SHA کامل commit اجرا کنید -4. اگر عمدا فقط به گراف تست عادی قطعی نیاز دارید، به‌جای آن workflow دستی `CI` را روی ref مربوط به release اجرا کنید + - پیش از وجود تگ، می‌توانید از SHA کامل کامیت شاخه گردش‌کار فعلی برای یک + اجرای آزمایشی فقط اعتبارسنجی از گردش‌کار preflight استفاده کنید +2. برای جریان عادی ابتدا-بتا، `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی + عمدا انتشار پایدار مستقیم می‌خواهید، `latest` را انتخاب کنید +3. وقتی CI عادی به‌علاوه پوشش کش prompt زنده، Docker، QA Lab، Matrix، و Telegram + را از یک گردش‌کار دستی می‌خواهید، `Full Release Validation` را روی شاخه انتشار، + تگ انتشار، یا SHA کامل کامیت اجرا کنید +4. اگر عمدا فقط به گراف تست عادی قطعی نیاز دارید، به‌جای آن گردش‌کار دستی `CI` + را روی ref انتشار اجرا کنید 5. `preflight_run_id` موفق را ذخیره کنید -6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`، - و `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را پیش از ارتقای package npm مربوط به OpenClaw در npm و ClawHub منتشر می‌کند -7. اگر release روی `beta` فرود آمد، از workflow خصوصی +6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`، و + `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را + پیش از ارتقای بسته npm OpenClaw به npm و ClawHub منتشر می‌کند +7. اگر انتشار روی `beta` قرار گرفت، از گردش‌کار خصوصی `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` برای ارتقای آن نسخه پایدار از `beta` به `latest` استفاده کنید -8. اگر release عمدا مستقیما روی `latest` منتشر شد و `beta` باید بلافاصله همان build پایدار را دنبال کند، از همان workflow خصوصی استفاده کنید تا هر دو dist-tag را به نسخه پایدار اشاره دهد، یا اجازه دهید همگام‌سازی خودترمیم زمان‌بندی‌شده آن بعدا `beta` را جابه‌جا کند +8. اگر انتشار عمدا مستقیم به `latest` منتشر شد و `beta` باید بلافاصله همان ساخت + پایدار را دنبال کند، از همان گردش‌کار خصوصی استفاده کنید تا هر دو dist-tag + به نسخه پایدار اشاره کنند، یا بگذارید همگام‌سازی self-healing زمان‌بندی‌شده + آن بعدا `beta` را جابه‌جا کند -تغییر dist-tag به دلایل امنیتی در repo خصوصی قرار دارد، چون همچنان به -`NPM_TOKEN` نیاز دارد، در حالی که repo عمومی انتشار فقط با OIDC را حفظ می‌کند. +تغییر dist-tag به دلایل امنیتی در مخزن خصوصی قرار دارد، چون هنوز به +`NPM_TOKEN` نیاز دارد، در حالی که مخزن عمومی انتشار فقط مبتنی بر OIDC را نگه می‌دارد. -این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای beta-first را مستند و برای operator قابل مشاهده نگه می‌دارد. +این کار مسیر انتشار مستقیم و مسیر ارتقای ابتدا-بتا را هر دو مستند و برای اپراتور +قابل مشاهده نگه می‌دارد. -اگر یک maintainer ناچار شود به احراز هویت محلی npm برگردد، هر دستور CLI مربوط به 1Password (`op`) را فقط داخل یک نشست tmux اختصاصی اجرا کنید. `op` را مستقیما از shell اصلی agent فراخوانی نکنید؛ نگه داشتن آن داخل tmux باعث می‌شود promptها، هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان جلوگیری می‌کند. +اگر یک نگه‌دارنده ناچار شود به احراز هویت محلی npm fallback کند، هر دستور CLI +مربوط به 1Password (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کنید. `op` را +مستقیم از shell عامل اصلی فراخوانی نکنید؛ نگه داشتن آن داخل tmux باعث می‌شود +promptها، هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان +جلوگیری می‌کند. -## ارجاع‌های عمومی +## مراجع عمومی - [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml) - [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml) @@ -533,10 +536,10 @@ gh workflow run openclaw-release-publish.yml \ - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -maintainerها برای runbook واقعی از مستندات خصوصی release در +نگه‌دارنده‌ها برای runbook واقعی از اسناد انتشار خصوصی در [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) استفاده می‌کنند. ## مرتبط -- [کانال‌های release](/fa/install/development-channels) +- [کانال‌های انتشار](/fa/install/development-channels) diff --git a/docs/fa/reference/full-release-validation.md b/docs/fa/reference/full-release-validation.md index 80d186ee1..e938fea13 100644 --- a/docs/fa/reference/full-release-validation.md +++ b/docs/fa/reference/full-release-validation.md @@ -1,25 +1,22 @@ --- read_when: - - اجرای اعتبارسنجی کامل انتشار یا اجرای مجدد آن - - مقایسهٔ پروفایل‌های اعتبارسنجی انتشار پایدار و کامل + - اجرای اعتبارسنجی کامل انتشار یا اجرای دوبارهٔ آن + - مقایسه پروفایل‌های اعتبارسنجی انتشار پایدار و کامل - اشکال‌زدایی از شکست‌های مرحلهٔ اعتبارسنجی انتشار -summary: مراحل اعتبارسنجی کامل انتشار، گردش‌کارهای فرزند، پروفایل‌های انتشار، شناسه‌های اجرای مجدد، و شواهد +summary: مراحل اعتبارسنجی کامل انتشار، گردش‌کارهای فرزند، شناسه‌های اجرای مجدد، و شواهد title: اعتبارسنجی کامل انتشار x-i18n: - generated_at: "2026-05-03T21:39:35Z" + generated_at: "2026-05-05T01:51:07Z" model: gpt-5.5 provider: openai - source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7 + source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d source_path: reference/full-release-validation.md workflow: 16 --- -`Full Release Validation` چتر انتشار است. این تنها نقطه ورود دستی -برای اثبات پیش از انتشار است، اما بیشتر کار در گردش‌کارهای فرزند انجام می‌شود تا -یک جعبه ناموفق بدون شروع دوباره کل انتشار بازاجرایی شود. +`Full Release Validation` چتر انتشار است. این تنها نقطه ورود دستی برای اثبات پیش از انتشار است، اما بیشتر کارها در گردش‌کارهای فرزند انجام می‌شود تا یک محیط ناموفق بتواند بدون شروع دوباره کل انتشار، دوباره اجرا شود. -آن را از یک ارجاع گردش‌کار مورد اعتماد، معمولاً `main`، اجرا کنید و شاخه انتشار، -برچسب، یا SHA کامل commit را به‌عنوان `ref` بدهید: +آن را از یک ارجاع گردش‌کار مورد اعتماد، معمولاً `main`، اجرا کنید و شاخه انتشار، برچسب، یا SHA کامل commit را به‌عنوان `ref` ارسال کنید: ```bash gh workflow run full-release-validation.yml \ @@ -30,140 +27,139 @@ gh workflow run full-release-validation.yml \ -f release_profile=stable ``` -گردش‌کارهای فرزند از ارجاع گردش‌کار مورد اعتماد برای ابزار اجرا و از ورودی -`ref` برای نامزد تحت آزمون استفاده می‌کنند. این باعث می‌شود منطق اعتبارسنجی جدید -هنگام اعتبارسنجی یک شاخه یا برچسب انتشار قدیمی‌تر در دسترس بماند. +گردش‌کارهای فرزند از ارجاع گردش‌کار مورد اعتماد برای چارچوب آزمون و از ورودی `ref` برای نامزد تحت آزمون استفاده می‌کنند. این کار باعث می‌شود هنگام اعتبارسنجی یک شاخه یا برچسب انتشار قدیمی‌تر، منطق اعتبارسنجی جدید در دسترس بماند. -Package Acceptance معمولاً tarball نامزد را از `ref` حل‌شده می‌سازد، از جمله -اجراهای SHA کامل که با `pnpm ci:full-release` dispatch شده‌اند. پس از انتشار، -`package_acceptance_package_spec=openclaw@YYYY.M.D` (یا -`openclaw@beta`/`openclaw@latest`) را بدهید تا همان ماتریس بسته/به‌روزرسانی را -در عوض روی بسته npm ارسال‌شده اجرا کند. +به‌طور پیش‌فرض، `release_profile=stable` مسیرهای مسدودکننده انتشار را اجرا می‌کند و soak کامل زنده/Docker را رد می‌کند. برای گنجاندن مسیرهای soak در یک اجرای پایدار، `run_release_soak=true` را ارسال کنید. `release_profile=full` همیشه مسیرهای soak را فعال می‌کند تا نمایه مشورتی گسترده هرگز پوشش را بی‌صدا از دست ندهد. -## مراحل سطح بالا +Package Acceptance معمولاً tarball نامزد را از `ref` حل‌شده می‌سازد، از جمله اجراهای SHA کامل که با `pnpm ci:full-release` dispatch شده‌اند. پس از انتشار، `package_acceptance_package_spec=openclaw@YYYY.M.D` (یا `openclaw@beta`/`openclaw@latest`) را ارسال کنید تا همان ماتریس package/update به‌جای آن روی package منتشرشده npm اجرا شود. -| مرحله | جزئیات | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| حل هدف | **کار:** `Resolve target ref`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** شاخه انتشار، برچسب، یا SHA کامل commit را حل می‌کند و ورودی‌های انتخاب‌شده را ثبت می‌کند.
**بازاجرا:** اگر این مورد شکست خورد، چتر را بازاجرا کنید. | -| Vitest و CI عادی | **کار:** `Run normal full CI`
**گردش‌کار فرزند:** `CI`
**اثبات می‌کند:** گراف CI کامل دستی را در برابر ارجاع هدف، شامل مسیرهای Linux Node، شاردهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Skills پایتون، Windows، macOS، i18n رابط کاربری کنترل، و Android از طریق چتر.
**بازاجرا:** `rerun_group=ci`. | -| پیش‌انتشار Plugin | **کار:** `Run plugin prerelease validation`
**گردش‌کار فرزند:** `Plugin Prerelease`
**اثبات می‌کند:** بررسی‌های ایستای Plugin مخصوص انتشار، پوشش Plugin عاملی، شاردهای دسته‌ای کامل extension، و مسیرهای Docker پیش‌انتشار Plugin.
**بازاجرا:** `rerun_group=plugin-prerelease`. | -| بررسی‌های انتشار | **کار:** `Run release/live/Docker/QA validation`
**گردش‌کار فرزند:** `OpenClaw Release Checks`
**اثبات می‌کند:** smoke نصب، بررسی‌های بسته میان‌سیستمی، مجموعه‌های live/E2E، تکه‌های مسیر انتشار Docker، Package Acceptance، هم‌ارزی QA Lab، Matrix زنده، و Telegram زنده.
**بازاجرا:** `rerun_group=release-checks` یا یک handle محدودتر release-checks. | -| artifact بسته | **کار:** `Prepare release package artifact`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** tarball والد `release-package-under-test` را به‌اندازه کافی زود می‌سازد تا بررسی‌های بسته‌محور که نیازی به انتظار برای `OpenClaw Release Checks` ندارند اجرا شوند.
**بازاجرا:** چتر را بازاجرا کنید یا برای `rerun_group=npm-telegram` مقدار `npm_telegram_package_spec` را فراهم کنید. | -| بسته Telegram | **کار:** `Run package Telegram E2E`
**گردش‌کار فرزند:** `NPM Telegram Beta E2E`
**اثبات می‌کند:** اثبات بسته Telegram مبتنی بر artifact والد برای `rerun_group=all` همراه با `release_profile=full`، یا اثبات Telegram بسته منتشرشده وقتی `npm_telegram_package_spec` تنظیم شده باشد.
**بازاجرا:** `rerun_group=npm-telegram` همراه با `npm_telegram_package_spec`. | -| اعتبارسنج چتر | **کار:** `Verify full validation`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** نتیجه‌های ثبت‌شده اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کارها را از گردش‌کارهای فرزند پیوست می‌کند.
**بازاجرا:** پس از سبز کردن یک فرزند ناموفق، فقط همین کار را بازاجرا کنید. | +## مرحله‌های سطح بالا + +| مرحله | جزئیات | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| حل هدف | **کار:** `Resolve target ref`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** شاخه انتشار، برچسب، یا SHA کامل commit را حل می‌کند و ورودی‌های انتخاب‌شده را ثبت می‌کند.
**اجرای دوباره:** اگر این مورد ناموفق شد، چتر را دوباره اجرا کنید. | +| Vitest و CI عادی | **کار:** `Run normal full CI`
**گردش‌کار فرزند:** `CI`
**اثبات می‌کند:** گراف CI کامل دستی را روی ارجاع هدف اجرا می‌کند، شامل مسیرهای Linux Node، shardهای Plugin همراه، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Python skills، Windows، macOS، i18n Control UI، و Android از طریق چتر.
**اجرای دوباره:** `rerun_group=ci`. | +| پیش‌انتشار Plugin | **کار:** `Run plugin prerelease validation`
**گردش‌کار فرزند:** `Plugin Prerelease`
**اثبات می‌کند:** بررسی‌های ایستای فقط انتشار برای Plugin، پوشش Plugin عاملی، shardهای دسته کامل extension، و مسیرهای Docker پیش‌انتشار Plugin.
**اجرای دوباره:** `rerun_group=plugin-prerelease`. | +| بررسی‌های انتشار | **کار:** `Run release/live/Docker/QA validation`
**گردش‌کار فرزند:** `OpenClaw Release Checks`
**اثبات می‌کند:** smoke نصب، بررسی‌های package میان‌سیستمی، Package Acceptance، هم‌ارزی QA Lab، Matrix زنده، و Telegram زنده. با `run_release_soak=true` یا `release_profile=full`، مجموعه‌های کامل زنده/E2E و قطعه‌های مسیر انتشار Docker را نیز اجرا می‌کند.
**اجرای دوباره:** `rerun_group=release-checks` یا یک handle محدودتر release-checks. | +| artifact مربوط به package | **کار:** `Prepare release package artifact`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** tarball والد `release-package-under-test` را آن‌قدر زود ایجاد می‌کند که بررسی‌های روبه‌package که نیاز ندارند منتظر `OpenClaw Release Checks` بمانند، بتوانند از آن استفاده کنند.
**اجرای دوباره:** چتر را دوباره اجرا کنید یا برای `rerun_group=npm-telegram` مقدار `npm_telegram_package_spec` را ارائه دهید. | +| Package Telegram | **کار:** `Run package Telegram E2E`
**گردش‌کار فرزند:** `NPM Telegram Beta E2E`
**اثبات می‌کند:** اثبات package Telegram مبتنی بر artifact والد برای `rerun_group=all` با `release_profile=full`، یا اثبات Telegram برای package منتشرشده وقتی `npm_telegram_package_spec` تنظیم شده باشد.
**اجرای دوباره:** `rerun_group=npm-telegram` با `npm_telegram_package_spec`. | +| تأییدکننده چتر | **کار:** `Verify full validation`
**گردش‌کار فرزند:** هیچ‌کدام
**اثبات می‌کند:** نتیجه‌های ثبت‌شده اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کارها را از گردش‌کارهای فرزند اضافه می‌کند.
**اجرای دوباره:** پس از اینکه یک فرزند ناموفق را دوباره اجرا کردید تا سبز شود، فقط همین کار را دوباره اجرا کنید. | برای `ref=main` و `rerun_group=all`، یک چتر جدیدتر جایگزین چتر قدیمی‌تر می‌شود. -وقتی والد لغو می‌شود، پایشگر آن هر گردش‌کار فرزندی را که قبلاً dispatch کرده -است لغو می‌کند. اجراهای اعتبارسنجی شاخه انتشار و برچسب به‌صورت پیش‌فرض یکدیگر -را لغو نمی‌کنند. +وقتی والد لغو می‌شود، پایشگر آن هر گردش‌کار فرزندی را که قبلاً dispatch کرده است لغو می‌کند. اجراهای اعتبارسنجی شاخه انتشار و برچسب به‌طور پیش‌فرض یکدیگر را لغو نمی‌کنند. -## مراحل بررسی‌های انتشار +## مرحله‌های بررسی انتشار -`OpenClaw Release Checks` بزرگ‌ترین گردش‌کار فرزند است. این گردش‌کار هدف را -یک‌بار حل می‌کند و وقتی مراحل بسته‌محور یا Dockerمحور به آن نیاز دارند، یک -artifact مشترک `release-package-under-test` آماده می‌کند. +`OpenClaw Release Checks` بزرگ‌ترین گردش‌کار فرزند است. هدف را یک‌بار حل می‌کند و هنگامی که مرحله‌های روبه‌package یا روبه‌Docker به آن نیاز دارند، یک artifact مشترک `release-package-under-test` آماده می‌کند. -| مرحله | جزئیات | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| هدف انتشار | **کار:** `Resolve target ref`
**گردش‌کار پشتیبان:** هیچ‌کدام
**آزمون‌ها:** ارجاع انتخاب‌شده، SHA مورد انتظار اختیاری، پروفایل، گروه بازاجرا، و فیلتر مجموعه live متمرکز.
**بازاجرا:** `rerun_group=release-checks`. | -| artifact بسته | **کار:** `Prepare release package artifact`
**گردش‌کار پشتیبان:** هیچ‌کدام
**آزمون‌ها:** یک tarball نامزد را بسته‌بندی یا حل می‌کند و `release-package-under-test` را برای بررسی‌های پایین‌دستی بسته‌محور بارگذاری می‌کند.
**بازاجرا:** گروه بسته، میان‌سیستمی، یا live/E2E تحت تأثیر. | -| smoke نصب | **کار:** `Run install smoke`
**گردش‌کار پشتیبان:** `Install Smoke`
**آزمون‌ها:** مسیر نصب کامل با استفاده دوباره از تصویر smoke ریشه Dockerfile، نصب بسته QR، smokeهای Docker ریشه و Gateway، آزمون‌های Docker نصب‌کننده، smoke ارائه‌دهنده تصویر نصب سراسری Bun، و E2E سریع نصب/حذف نصب Pluginهای بسته‌بندی‌شده.
**بازاجرا:** `rerun_group=install-smoke`. | -| میان‌سیستمی | **کار:** `cross_os_release_checks`
**گردش‌کار پشتیبان:** `OpenClaw Cross-OS Release Checks (Reusable)`
**آزمون‌ها:** مسیرهای تازه و ارتقا روی Linux، Windows، و macOS برای ارائه‌دهنده و حالت انتخاب‌شده، با استفاده از tarball نامزد به‌همراه یک بسته مبنا.
**بازاجرا:** `rerun_group=cross-os`. | -| مخزن و live E2E | **کار:** `Run repo/live E2E validation`
**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`
**آزمون‌ها:** E2E مخزن، cache زنده، streaming websocket OpenAI، شاردهای ارائه‌دهنده و Plugin زنده native، و ابزارهای مدل/backend/Gateway زنده مبتنی بر Docker که با `release_profile` انتخاب می‌شوند.
**بازاجرا:** `rerun_group=live-e2e`، به‌صورت اختیاری همراه با `live_suite_filter`. | -| مسیر انتشار Docker | **کار:** `Run Docker release-path validation`
**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`
**آزمون‌ها:** تکه‌های Docker مسیر انتشار در برابر artifact بسته مشترک.
**بازاجرا:** `rerun_group=live-e2e`. | -| Package Acceptance | **کار:** `Run package acceptance`
**گردش‌کار پشتیبان:** `Package Acceptance`
**آزمون‌ها:** fixtureهای بسته Plugin آفلاین، به‌روزرسانی Plugin، پذیرش بسته Telegram با mock-OpenAI، و بررسی‌های survivor ارتقای منتشرشده از هر انتشار npm پایدار در یا پس از `2026.4.23` در برابر همان tarball.
**بازاجرا:** `rerun_group=package`. | -| هم‌ارزی QA | **کار:** `Run QA Lab parity lane` و `Run QA Lab parity report`
**گردش‌کار پشتیبان:** کارهای مستقیم
**آزمون‌ها:** بسته‌های هم‌ارزی عاملی نامزد و مبنا، سپس گزارش هم‌ارزی.
**بازاجرا:** `rerun_group=qa-parity` یا `rerun_group=qa`. | -| QA live Matrix | **کار:** `Run QA Lab live Matrix lane`
**گردش‌کار پشتیبان:** کار مستقیم
**آزمون‌ها:** پروفایل QA سریع Matrix زنده در محیط `qa-live-shared`.
**بازاجرا:** `rerun_group=qa-live` یا `rerun_group=qa`. | -| QA live Telegram | **کار:** `Run QA Lab live Telegram lane`
**گردش‌کار پشتیبان:** کار مستقیم
**آزمون‌ها:** QA زنده Telegram با leaseهای اعتبارنامه Convex CI.
**بازاجرا:** `rerun_group=qa-live` یا `rerun_group=qa`. | -| اعتبارسنج انتشار | **کار:** `Verify release checks`
**گردش‌کار پشتیبان:** هیچ‌کدام
**آزمون‌ها:** کارهای الزامی release-check برای گروه بازاجرای انتخاب‌شده.
**بازاجرا:** پس از موفقیت کارهای فرزند متمرکز بازاجرا کنید. | +| مرحله | جزئیات | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| هدف انتشار | **Job:** `Resolve target ref`
**گردش‌کار پشتیبان:** ندارد
**آزمون‌ها:** ref انتخاب‌شده، SHA مورد انتظار اختیاری، نمایه، گروه اجرای دوباره، و فیلتر متمرکز مجموعه live.
**اجرای دوباره:** `rerun_group=release-checks`. | +| مصنوعه بسته | **Job:** `Prepare release package artifact`
**گردش‌کار پشتیبان:** ندارد
**آزمون‌ها:** یک tarball نامزد را بسته‌بندی یا حل می‌کند و `release-package-under-test` را برای بررسی‌های پایین‌دستیِ مرتبط با بسته بارگذاری می‌کند.
**اجرای دوباره:** گروه بسته، cross-OS، یا live/E2E متأثر. | +| smoke نصب | **Job:** `Run install smoke`
**گردش‌کار پشتیبان:** `Install Smoke`
**آزمون‌ها:** مسیر کامل نصب با استفاده مجدد از تصویر smoke در Dockerfile ریشه، نصب بسته QR، smokeهای Docker ریشه و Gateway، آزمون‌های Docker نصب‌کننده، smoke نصب سراسری Bun برای image-provider، و E2E سریع نصب/حذف Pluginهای همراه.
**اجرای دوباره:** `rerun_group=install-smoke`. | +| Cross-OS | **Job:** `cross_os_release_checks`
**گردش‌کار پشتیبان:** `OpenClaw Cross-OS Release Checks (Reusable)`
**آزمون‌ها:** مسیرهای تازه و ارتقا روی Linux، Windows، و macOS برای provider و حالت انتخاب‌شده، با استفاده از tarball نامزد به‌همراه یک بسته مبنا.
**اجرای دوباره:** `rerun_group=cross-os`. | +| E2E مخزن و live | **Job:** `Run repo/live E2E validation`
**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`
**آزمون‌ها:** E2E مخزن، کش live، استریم websocket OpenAI، provider live بومی و shardهای Plugin، و harnessهای live مبتنی بر Docker برای model/backend/gateway که با `release_profile` انتخاب می‌شوند.
**اجراها:** `run_release_soak=true`، `release_profile=full`، یا `rerun_group=live-e2e` متمرکز.
**اجرای دوباره:** `rerun_group=live-e2e`، به‌صورت اختیاری با `live_suite_filter`. | +| مسیر انتشار Docker | **Job:** `Run Docker release-path validation`
**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`
**آزمون‌ها:** chunkهای Docker مسیر انتشار در برابر مصنوعه بسته مشترک.
**اجراها:** `run_release_soak=true`، `release_profile=full`، یا `rerun_group=live-e2e` متمرکز.
**اجرای دوباره:** `rerun_group=live-e2e`. | +| پذیرش بسته | **Job:** `Run package acceptance`
**گردش‌کار پشتیبان:** `Package Acceptance`
**آزمون‌ها:** fixtureهای آفلاین بسته Plugin، به‌روزرسانی Plugin، پذیرش بسته Telegram با mock-OpenAI، و بررسی‌های دوام ارتقای منتشرشده در برابر همان tarball. بررسی‌های مسدودکننده انتشار از مبنای پیش‌فرض آخرین نسخه منتشرشده استفاده می‌کنند؛ بررسی‌های soak به همه انتشارهای پایدار npm در یا بعد از `2026.4.23` به‌همراه fixtureهای مسئله گزارش‌شده گسترش می‌یابند.
**اجرای دوباره:** `rerun_group=package`. | +| همسانی QA | **Job:** `Run QA Lab parity lane` و `Run QA Lab parity report`
**گردش‌کار پشتیبان:** jobهای مستقیم
**آزمون‌ها:** بسته‌های همسانی agentic نامزد و مبنا، سپس گزارش همسانی.
**اجرای دوباره:** `rerun_group=qa-parity` یا `rerun_group=qa`. | +| Matrix live در QA | **Job:** `Run QA Lab live Matrix lane`
**گردش‌کار پشتیبان:** job مستقیم
**آزمون‌ها:** نمایه سریع QA live در Matrix در محیط `qa-live-shared`.
**اجرای دوباره:** `rerun_group=qa-live` یا `rerun_group=qa`. | +| Telegram live در QA | **Job:** `Run QA Lab live Telegram lane`
**گردش‌کار پشتیبان:** job مستقیم
**آزمون‌ها:** QA live در Telegram با leaseهای credential در Convex CI.
**اجرای دوباره:** `rerun_group=qa-live` یا `rerun_group=qa`. | +| تأییدکننده انتشار | **Job:** `Verify release checks`
**گردش‌کار پشتیبان:** ندارد
**آزمون‌ها:** jobهای ضروری release-check برای گروه اجرای دوباره انتخاب‌شده.
**اجرای دوباره:** پس از گذر jobهای فرزند متمرکز دوباره اجرا کنید. | -## تکه‌های مسیر انتشار Docker +## chunkهای مسیر انتشار Docker -مرحله مسیر انتشار Docker این تکه‌ها را وقتی `live_suite_filter` خالی است اجرا -می‌کند: +مرحله مسیر انتشار Docker این chunkها را زمانی اجرا می‌کند که `live_suite_filter` +خالی باشد: -| تکه | پوشش | +| Chunk | پوشش | | --------------------------------------------------------------- | ----------------------------------------------------------------------- | | `core` | مسیرهای smoke مسیر انتشار Core Docker. | | `package-update-openai` | رفتار نصب و به‌روزرسانی بسته OpenAI. | | `package-update-anthropic` | رفتار نصب و به‌روزرسانی بسته Anthropic. | -| `package-update-core` | رفتار بسته و به‌روزرسانی مستقل از ارائه‌دهنده. | -| `plugins-runtime-plugins` | مسیرهای runtime Plugin که رفتار Plugin را تمرین می‌کنند. | -| `plugins-runtime-services` | مسیرهای runtime Plugin مبتنی بر سرویس؛ در صورت درخواست شامل OpenWebUI است. | -| `plugins-runtime-install-a` through `plugins-runtime-install-h` | دسته‌های نصب/runtime Plugin که برای اعتبارسنجی انتشار موازی تقسیم شده‌اند. | +| `package-update-core` | رفتار بسته و به‌روزرسانی بی‌طرف نسبت به provider. | +| `plugins-runtime-plugins` | مسیرهای runtime در Plugin که رفتار Plugin را اجرا می‌کنند. | +| `plugins-runtime-services` | مسیرهای runtime در Plugin که با سرویس پشتیبانی می‌شوند؛ هنگام درخواست شامل OpenWebUI است. | +| `plugins-runtime-install-a` تا `plugins-runtime-install-h` | دسته‌های نصب/runtime در Plugin که برای اعتبارسنجی موازی انتشار تقسیم شده‌اند. | -در workflow زنده/E2E قابل‌استفاده‌مجدد، زمانی که فقط یک lane مربوط به Docker شکست خورده است، از `docker_lanes=` هدفمند استفاده کنید. artifactهای انتشار، در صورت در دسترس بودن، شامل دستورهای rerun به‌ازای هر lane همراه با ورودی‌های استفادهٔ دوباره از artifact بسته و image هستند. +وقتی فقط یک مسیر Docker شکست خورده است، از `docker_lanes=` هدفمند روی گردش‌کار live/E2E قابل استفاده مجدد استفاده کنید. مصنوعه‌های انتشار شامل فرمان‌های اجرای دوباره برای هر مسیر با ورودی‌های مصنوعه بسته و استفاده مجدد از تصویر هستند، هرگاه در دسترس باشند. -## پروفایل‌های انتشار +## نمایه‌های انتشار -`release_profile` عمدتاً گسترهٔ زنده/provider را در بررسی‌های انتشار کنترل می‌کند. -این گزینه CI کامل عادی، پیش‌انتشار Plugin، install smoke، پذیرش بسته، QA Lab، یا بخش‌های مسیر انتشار Docker را حذف نمی‌کند. `full` همچنین باعث می‌شود umbrella run در حالت -`rerun_group=all`، package Telegram E2E را در برابر artifact بستهٔ انتشار والد اجرا کند، بنابراین یک کاندیدای کامل پیش از انتشار بی‌صدا آن lane بستهٔ Telegram را رد نمی‌کند. +`release_profile` عمدتاً گستره live/provider را درون بررسی‌های انتشار کنترل می‌کند. +این گزینه CI کامل عادی، Plugin Prerelease، smoke نصب، پذیرش بسته، یا QA Lab را حذف نمی‌کند. برای `stable`، E2E جامع مخزن/live و chunkهای مسیر انتشار Docker پوشش soak هستند و زمانی اجرا می‌شوند که `run_release_soak=true`. +`full` پوشش soak را اجباری می‌کند و همچنین باعث می‌شود اجرای umbrella، E2E بسته Telegram را در برابر مصنوعه بسته انتشار والد اجرا کند وقتی `rerun_group=all` باشد، بنابراین یک نامزد کامل پیش از انتشار آن مسیر بسته Telegram را بی‌صدا رد نمی‌کند. -| پروفایل | کاربرد موردنظر | پوشش زنده/provider شامل‌شده | +| نمایه | کاربرد مورد نظر | پوشش live/provider شامل‌شده | | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `minimum` | سریع‌ترین smoke حیاتی برای انتشار. | مسیر زنده OpenAI/هسته، مدل‌های زنده Docker برای OpenAI، هستهٔ native gateway، پروفایل native OpenAI gateway، Plugin native OpenAI، و Docker live gateway OpenAI. | -| `stable` | پروفایل پیش‌فرض تأیید انتشار. | `minimum` به‌علاوهٔ Anthropic smoke، Google، MiniMax، backend، native live test harness، Docker live CLI backend، Docker ACP bind، Docker Codex harness، و یک shard مربوط به OpenCode Go smoke. | -| `full` | پیمایش advisory گسترده. | `stable` به‌علاوهٔ providerهای advisory، shardهای زندهٔ plugin، و shardهای زندهٔ رسانه. | +| `minimum` | سریع‌ترین smoke حیاتی برای انتشار. | مسیر live OpenAI/core، مدل‌های live در Docker برای OpenAI، core بومی Gateway، نمایه بومی Gateway برای OpenAI، Plugin بومی OpenAI، و Gateway live در Docker برای OpenAI. | +| `stable` | نمایه پیش‌فرض تأیید انتشار. | `minimum` به‌علاوه smoke Anthropic، Google، MiniMax، backend، harness آزمون live بومی، backend زنده CLI در Docker، bind مربوط به Docker ACP، harness مربوط به Docker Codex، و یک shard smoke برای OpenCode Go. | +| `full` | پیمایش مشاوره‌ای گسترده. | `stable` به‌علاوه providerهای مشاوره‌ای، shardهای live در Plugin، و shardهای live رسانه. | -## افزوده‌های فقط مخصوص Full +## افزوده‌های فقط full -این suiteها توسط `stable` رد می‌شوند و توسط `full` شامل می‌شوند: +این مجموعه‌ها توسط `stable` رد می‌شوند و توسط `full` شامل می‌شوند: -| حوزه | پوشش فقط مخصوص Full | +| حوزه | پوشش فقط full | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| مدل‌های زنده Docker | OpenCode Go، OpenRouter، xAI، Z.ai، و Fireworks. | -| Docker live gateway | providerهای advisory که به shardهای DeepSeek/Fireworks، OpenCode Go/OpenRouter، و xAI/Z.ai تقسیم شده‌اند. | -| پروفایل‌های provider مربوط به Native gateway | shardهای کامل Anthropic Opus و Sonnet/Haiku، Fireworks، DeepSeek، shardهای کامل مدل OpenCode Go، OpenRouter، xAI، و Z.ai. | -| shardهای زندهٔ Native plugin | Plugins A-K، L-N، O-Z other، Moonshot، و xAI. | -| shardهای زندهٔ Native media | Audio، Google music، MiniMax music، و video groups A-D. | +| مدل‌های live در Docker | OpenCode Go، OpenRouter، xAI، Z.ai، و Fireworks. | +| Gateway live در Docker | providerهای مشاوره‌ای که به shardهای DeepSeek/Fireworks، OpenCode Go/OpenRouter، و xAI/Z.ai تقسیم شده‌اند. | +| نمایه‌های provider بومی Gateway | shardهای کامل Anthropic Opus و Sonnet/Haiku، Fireworks، DeepSeek، shardهای کامل مدل OpenCode Go، OpenRouter، xAI، و Z.ai. | +| shardهای live بومی Plugin | Plugins A-K، L-N، O-Z other، Moonshot، و xAI. | +| shardهای live بومی رسانه | گروه‌های صوت، موسیقی Google، موسیقی MiniMax، و ویدئو A-D. | `stable` شامل `native-live-src-gateway-profiles-anthropic-smoke` و -`native-live-src-gateway-profiles-opencode-go-smoke` است؛ `full` به‌جای آن از shardهای گسترده‌تر مدل Anthropic و OpenCode Go استفاده می‌کند. rerunهای متمرکز همچنان می‌توانند از handleهای تجمیعی `native-live-src-gateway-profiles-anthropic` یا +`native-live-src-gateway-profiles-opencode-go-smoke` است؛ `full` به‌جای آن از shardهای گسترده‌تر +مدل Anthropic و OpenCode Go استفاده می‌کند. اجراهای دوباره متمرکز همچنان می‌توانند از handleهای تجمیعی +`native-live-src-gateway-profiles-anthropic` یا `native-live-src-gateway-profiles-opencode-go` استفاده کنند. -## rerunهای متمرکز +## اجراهای دوباره متمرکز -برای پرهیز از تکرار boxهای انتشار نامرتبط، از `rerun_group` استفاده کنید: +برای جلوگیری از تکرار boxهای انتشار نامرتبط از `rerun_group` استفاده کنید: -| handle | دامنه | +| شناسه | دامنه | | ------------------- | --------------------------------------------------------------------- | -| `all` | همهٔ مرحله‌های Full Release Validation. | -| `ci` | فقط child مربوط به CI کامل دستی. | -| `plugin-prerelease` | فقط child مربوط به پیش‌انتشار Plugin. | -| `release-checks` | همهٔ مرحله‌های OpenClaw Release Checks. | +| `all` | همهٔ مراحل اعتبارسنجی کامل انتشار. | +| `ci` | فقط فرزند CI کامل دستی. | +| `plugin-prerelease` | فقط فرزند پیش‌انتشار Plugin. | +| `release-checks` | همهٔ مراحل بررسی‌های انتشار OpenClaw. | | `install-smoke` | Install Smoke از طریق بررسی‌های انتشار. | -| `cross-os` | بررسی‌های انتشار Cross-OS. | -| `live-e2e` | اعتبارسنجی Repo/live E2E و مسیر انتشار Docker. | -| `package` | Package Acceptance. | -| `qa` | برابری QA به‌علاوهٔ laneهای زندهٔ QA. | -| `qa-parity` | فقط laneهای برابری QA و گزارش. | -| `qa-live` | فقط Matrix زندهٔ QA و Telegram. | -| `npm-telegram` | Telegram E2E برای بستهٔ منتشرشده؛ به `npm_telegram_package_spec` نیاز دارد. | +| `cross-os` | بررسی‌های انتشار میان‌سیستم‌عاملی. | +| `live-e2e` | اعتبارسنجی E2E زنده/مخزن و مسیر انتشار Docker. | +| `package` | پذیرش بسته. | +| `qa` | برابری QA به‌علاوه مسیرهای زنده QA. | +| `qa-parity` | فقط مسیرهای برابری QA و گزارش. | +| `qa-live` | فقط ماتریس زنده QA و Telegram. | +| `npm-telegram` | E2E بستهٔ منتشرشدهٔ Telegram؛ به `npm_telegram_package_spec` نیاز دارد. | -وقتی یک suite زنده شکست خورده است، همراه با `rerun_group=live-e2e` از `live_suite_filter` استفاده کنید. -شناسه‌های معتبر filter در workflow زنده/E2E قابل‌استفاده‌مجدد تعریف شده‌اند، از جمله +وقتی یک مجموعهٔ زنده شکست خورد، از `live_suite_filter` همراه با `rerun_group=live-e2e` استفاده کنید. +شناسه‌های معتبر فیلتر در گردش‌کار قابل‌استفادهٔ مجدد زنده/E2E تعریف شده‌اند، از جمله `docker-live-models`، `live-gateway-docker`، `live-gateway-anthropic-docker`، `live-gateway-google-docker`، `live-gateway-minimax-docker`، `live-gateway-advisory-docker`، `live-cli-backend-docker`، `live-acp-bind-docker`، و `live-codex-harness-docker`. -handle مربوط به `live-gateway-advisory-docker` یک handle تجمیعی rerun برای سه shard provider خودش است، بنابراین همچنان به همهٔ jobهای advisory Docker gateway گسترش پیدا می‌کند. +شناسهٔ `live-gateway-advisory-docker` یک شناسهٔ اجرای دوبارهٔ تجمیعی برای سه شارد ارائه‌دهندهٔ آن است، بنابراین همچنان به همهٔ کارهای Gateway مشورتی Docker منشعب می‌شود. + +وقتی یک مسیر میان‌سیستم‌عاملی شکست خورد، از `cross_os_suite_filter` همراه با `rerun_group=cross-os` استفاده کنید. این فیلتر یک شناسهٔ سیستم‌عامل، یک شناسهٔ مجموعه، یا یک جفت سیستم‌عامل/مجموعه را می‌پذیرد، برای مثال `windows/packaged-upgrade`، `windows`، یا `packaged-fresh`. خلاصه‌های میان‌سیستم‌عاملی زمان‌بندی‌های هر فاز را برای مسیرهای ارتقای بسته‌بندی‌شده شامل می‌شوند، و فرمان‌های طولانی‌مدت خطوط Heartbeat چاپ می‌کنند تا به‌روزرسانی گیرکردهٔ Windows پیش از پایان مهلت کار قابل مشاهده باشد. + +مسیرهای بررسی انتشار QA مشورتی هستند. شکست فقط-QA به‌صورت هشدار گزارش می‌شود و راستی‌آزمای بررسی انتشار را مسدود نمی‌کند؛ وقتی به شواهد تازهٔ QA نیاز دارید، `rerun_group=qa`، +`qa-parity`، یا `qa-live` را دوباره اجرا کنید. ## شواهدی که باید نگه دارید -خلاصهٔ `Full Release Validation` را به‌عنوان شاخص سطح انتشار نگه دارید. این خلاصه به شناسه‌های run فرزند لینک می‌دهد و شامل جدول‌های کندترین jobهاست. برای failureها، ابتدا workflow فرزند را بررسی کنید، سپس کوچک‌ترین handle منطبق بالا را دوباره اجرا کنید. +خلاصهٔ `Full Release Validation` را به‌عنوان نمایهٔ سطح انتشار نگه دارید. این خلاصه به شناسه‌های اجرای فرزند پیوند می‌دهد و جدول‌های کندترین کارها را شامل می‌شود. برای شکست‌ها، ابتدا گردش‌کار فرزند را بررسی کنید، سپس کوچک‌ترین شناسهٔ منطبق بالا را دوباره اجرا کنید. -artifactهای مفید: +آرتیفکت‌های مفید: -- `release-package-under-test` از والد Full Release Validation و `OpenClaw Release Checks` -- artifactهای مسیر انتشار Docker زیر `.artifacts/docker-tests/` -- `package-under-test` مربوط به Package Acceptance و artifactهای پذیرش Docker -- artifactهای بررسی انتشار Cross-OS برای هر OS و suite -- artifactهای برابری QA، Matrix، و Telegram +- `release-package-under-test` از والد اعتبارسنجی کامل انتشار و `OpenClaw Release Checks` +- آرتیفکت‌های مسیر انتشار Docker زیر `.artifacts/docker-tests/` +- `package-under-test` پذیرش بسته و آرتیفکت‌های پذیرش Docker +- آرتیفکت‌های بررسی انتشار میان‌سیستم‌عاملی برای هر سیستم‌عامل و مجموعه +- آرتیفکت‌های برابری QA، Matrix، و Telegram -## فایل‌های workflow +## فایل‌های گردش‌کار - `.github/workflows/full-release-validation.yml` - `.github/workflows/openclaw-release-checks.yml` diff --git a/docs/fa/reference/test.md b/docs/fa/reference/test.md index c4243b087..d5783e4a4 100644 --- a/docs/fa/reference/test.md +++ b/docs/fa/reference/test.md @@ -1,61 +1,61 @@ --- read_when: - - اجرای آزمون‌ها یا رفع اشکال آن‌ها + - اجرای آزمون‌ها یا رفع مشکل آن‌ها summary: نحوهٔ اجرای آزمون‌ها به‌صورت محلی (vitest) و زمان استفاده از حالت‌های force/coverage title: آزمون‌ها x-i18n: - generated_at: "2026-05-02T20:59:18Z" + generated_at: "2026-05-05T01:51:20Z" model: gpt-5.5 provider: openai - source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f + source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605 source_path: reference/test.md workflow: 16 --- -- کیت کامل آزمایش (مجموعه‌ها، زنده، Docker): [آزمایش](/fa/help/testing) -- اعتبارسنجی به‌روزرسانی و بسته Plugin: [آزمایش به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) +- کیت کامل آزمون (مجموعه‌ها، زنده، Docker): [آزمون](/fa/help/testing) +- اعتبارسنجی به‌روزرسانی و بسته‌های Plugin: [آزمون به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) -- `pnpm test:force`: هر فرایند Gateway باقی‌مانده‌ای را که پورت کنترل پیش‌فرض را نگه داشته می‌کشد، سپس مجموعه کامل Vitest را با یک پورت Gateway ایزوله اجرا می‌کند تا تست‌های سرور با یک نمونه در حال اجرا تداخل نداشته باشند. وقتی اجرای قبلی Gateway پورت 18789 را اشغال‌شده باقی گذاشته است از این استفاده کنید. -- `pnpm test:coverage`: مجموعه واحد را با پوشش V8 اجرا می‌کند (از طریق `vitest.unit.config.ts`). این یک دروازه پوشش واحد برای فایل‌های بارگذاری‌شده است، نه پوشش همه فایل‌های کل مخزن. آستانه‌ها 70٪ برای خطوط/توابع/دستورات و 55٪ برای شاخه‌ها هستند. چون `coverage.all` برابر false است، این دروازه فایل‌هایی را اندازه‌گیری می‌کند که توسط مجموعه پوشش واحد بارگذاری شده‌اند، نه اینکه هر فایل منبعِ خط‌های جداشده را پوشش‌داده‌نشده در نظر بگیرد. -- `pnpm test:coverage:changed`: پوشش واحد را فقط برای فایل‌هایی اجرا می‌کند که از `origin/main` تغییر کرده‌اند. -- `pnpm test:changed`: اجرای تست تغییرات هوشمند و ارزان. هدف‌های دقیق را از ویرایش‌های مستقیم تست، فایل‌های خواهر `*.test.ts`، نگاشت‌های صریح منبع، و گراف import محلی اجرا می‌کند. تغییرات گسترده/پیکربندی/بسته رد می‌شوند مگر اینکه به تست‌های دقیق نگاشت شوند. -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: اجرای صریح تست تغییرات گسترده. وقتی ویرایش test harness/پیکربندی/بسته باید به رفتار گسترده‌تر تست‌های تغییریافته Vitest برگردد از آن استفاده کنید. -- `pnpm changed:lanes`: خط‌های معماری فعال‌شده توسط diff نسبت به `origin/main` را نشان می‌دهد. -- `pnpm check:changed`: دروازه بررسی تغییرات هوشمند را برای diff نسبت به `origin/main` اجرا می‌کند. typecheck، lint، و فرمان‌های نگهبان را برای خط‌های معماریِ تحت تأثیر اجرا می‌کند، اما تست‌های Vitest را اجرا نمی‌کند. برای اثبات تست از `pnpm test:changed` یا `pnpm test ` صریح استفاده کنید. -- `pnpm test`: هدف‌های صریح فایل/دایرکتوری را از مسیر خط‌های Vitest محدوده‌دار عبور می‌دهد. اجراهای بدون هدف از گروه‌های shard ثابت استفاده می‌کنند و برای اجرای موازی محلی به پیکربندی‌های برگ گسترش می‌یابند؛ گروه extension همیشه به‌جای یک فرایند بزرگ root-project، به پیکربندی‌های shard به‌ازای هر extension گسترش می‌یابد. -- اجراهای test wrapper با خلاصه کوتاه `[test] passed|failed|skipped ... in ...` پایان می‌یابند. خط مدت‌زمان خود Vitest به‌عنوان جزئیات به‌ازای هر shard باقی می‌ماند. -- وضعیت تست مشترک OpenClaw: وقتی یک تست به `HOME`، `OPENCLAW_STATE_DIR`، `OPENCLAW_CONFIG_PATH`، fixture پیکربندی، workspace، دایرکتوری agent، یا ذخیره auth-profile ایزوله نیاز دارد، از `src/test-utils/openclaw-test-state.ts` در Vitest استفاده کنید. -- کمک‌کننده‌های E2E فرایند: وقتی یک تست E2E در سطح فرایند Vitest به یک Gateway در حال اجرا، محیط CLI، ضبط لاگ، و پاک‌سازی در یک جا نیاز دارد، از `test/helpers/openclaw-test-instance.ts` استفاده کنید. -- کمک‌کننده‌های E2E Docker/Bash: خط‌هایی که `scripts/lib/docker-e2e-image.sh` را source می‌کنند می‌توانند `docker_e2e_test_state_shell_b64