openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh fa translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:56:57 +00:00
parent c234f580ff
commit ae03f8b44c
37 changed files with 5544 additions and 5086 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

252
docs/fa/automation/tasks.md
View File

@ -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
---
<Note>
دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار مناسب، [خودکارسازی و وظایف](/fa/automation) را ببینید. این صفحه دفتر ثبت فعالیت کارهای پس‌زمینه است، نه زمان‌بند.
دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار مناسب، [اتوماسیون و وظایف](/fa/automation) را ببینید. این صفحه دفتر فعالیت کارهای پس‌زمینه است، نه زمان‌بند.
</Note>
وظایف پس‌زمینه کارهایی را ردیابی می‌کنند که **خارج از نشست گفت‌وگوی اصلی شما** اجرا می‌شوند: اجراهای ACP، ایجاد عامل‌های فرعی، اجرای جداافتاده کارهای Cron، و عملیات‌هایی که از CLI آغاز شده‌اند.
وظایف پس‌زمینه کارهایی را ردیابی می‌کنند که **خارج از نشست گفت‌وگوی اصلی شما** اجرا می‌شوند: اجرای ACP، ایجاد زیرعامل‌ها، اجرای jobهای cron ایزوله، و عملیات آغازشده از CLI.
وظایف جایگزین نشست‌ها، کارهای Cron یا Heartbeatها نمی‌شوند — آن‌ها **دفتر ثبت فعالیت** هستند که ثبت می‌کند چه کار جداشده‌ای رخ داده، چه زمانی رخ داده و آیا موفق بوده است یا نه.
وظایف جایگزین نشست‌ها، jobهای cron یا heartbeats نیستند — آن‌ها **دفتر فعالیت** هستند که ثبت می‌کند چه کار جداشده‌ای انجام شده، چه زمانی، و آیا موفق بوده است یا نه.
<Note>
هر اجرای عامل یک وظیفه ایجاد نمی‌کند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی عادی این کار را نمی‌کنند. همه اجراهای Cron، ایجادهای ACP، ایجادهای عامل فرعی و فرمان‌های عامل CLI این کار را انجام می‌دهند.
هر اجرای عامل یک وظیفه ایجاد نمی‌کند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی معمولی این کار را نمی‌کنند. همه اجرای‌های cron، ایجادهای ACP، ایجادهای زیرعامل، و فرمان‌های عامل CLI این کار را می‌کنند.
</Note>
## خلاصه
## خلاصه سریع
- وظایف **رکورد** هستند، نه زمان‌بند — 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 برای ۷ روز نگه داشته می‌شوند، سپس به‌صورت خودکار پاک‌سازی می‌شوند.
## شروع سریع
<Tabs>
<Tab title="List and filter">
<Tab title="فهرست و فیلتر">
```bash
# List all tasks (newest first)
openclaw tasks list
@ -57,13 +57,13 @@ x-i18n:
```
</Tab>
<Tab title="Inspect">
<Tab title="بازبینی">
```bash
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>
```
</Tab>
<Tab title="Cancel and notify">
<Tab title="لغو و اعلان">
```bash
# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>
@ -73,7 +73,7 @@ x-i18n:
```
</Tab>
<Tab title="Audit and maintenance">
<Tab title="ممیزی و نگهداری">
```bash
# Run a health audit
openclaw tasks audit
@ -84,7 +84,7 @@ x-i18n:
```
</Tab>
<Tab title="Task flow">
<Tab title="جریان وظیفه">
```bash
# Inspect TaskFlow state
openclaw tasks flow list
@ -94,29 +94,29 @@ x-i18n:
</Tab>
</Tabs>
## چه چیزی یک وظیفه ایجاد می‌کند
## چه چیزی وظیفه ایجاد می‌کند
| منبع | نوع زمان‌اجرا | زمانی که رکورد وظیفه ایجاد می‌شود | سیاست اعلان پیش‌فرض |
| منبع | نوع 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` |
<AccordionGroup>
<Accordion title="Notify defaults for cron and media">
وظایف Cron نشست اصلی به‌صورت پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند — آن‌ها رکوردهایی برای ردیابی ایجاد می‌کنند، اما اعلان تولید نمی‌کنند. وظایف Cron جداافتاده نیز به‌صورت پیش‌فرض `silent` هستند، اما چون در نشست خودشان اجرا می‌شوند، نمایان‌ترند.
<Accordion title="پیش‌فرض‌های اعلان برای cron و رسانه">
وظایف cron نشست اصلی به‌طور پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند — آن‌ها برای ردیابی رکورد ایجاد می‌کنند اما اعلان تولید نمی‌کنند. وظایف cron ایزوله نیز به‌طور پیش‌فرض `silent` هستند، اما چون در نشست خودشان اجرا می‌شوند بیشتر دیده می‌شوند.
اجراهای مبتنی بر نشست `music_generate` و `video_generate` نیز از سیاست اعلان `silent` استفاده می‌کنند. آن‌ها همچنان رکوردهای وظیفه ایجاد می‌کنند، اما تکمیل به‌صورت یک بیدارسازی داخلی به نشست عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و رسانه تمام‌شده را خودش پیوست کند. اگر `tools.media.asyncCompletion.directSend` را فعال کنید، تکمیل‌های async `video_generate` می‌توانند ابتدا تحویل مستقیم به کانال را امتحان کنند؛ تکمیل‌های async `music_generate` در مسیر بیدارسازی نشست درخواست‌دهنده می‌مانند.
اجرای‌های مبتنی بر نشست `music_generate` و `video_generate` نیز از سیاست اعلان `silent` استفاده می‌کنند. آن‌ها همچنان رکورد وظیفه ایجاد می‌کنند، اما تکمیل به‌عنوان یک بیدارباش داخلی به نشست عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و رسانه تکمیل‌شده را خودش پیوست کند. تکمیل‌های گروه/کانال از سیاست معمول پاسخ قابل‌مشاهده پیروی می‌کنند، بنابراین وقتی تحویل منبع آن را لازم بداند، عامل از ابزار پیام استفاده می‌کند.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
وقتی یک وظیفه مبتنی بر نشست `video_generate` هنوز فعال است، ابزار همچنین مانند یک محافظ عمل می‌کند: فراخوانی‌های تکراری `video_generate` در همان نشست، به‌جای شروع یک تولید هم‌زمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل یک جست‌وجوی صریح پیشرفت/وضعیت می‌خواهید، از `action: "status"` استفاده کنید.
<Accordion title="حفاظت هم‌زمانی video_generate">
تا زمانی که یک وظیفه مبتنی بر نشست `video_generate` هنوز فعال است، ابزار نیز نقش حفاظتی دارد: فراخوانی‌های تکراری `video_generate` در همان نشست، به‌جای شروع تولید هم‌زمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل به جست‌وجوی صریح پیشرفت/وضعیت نیاز دارید از `action: "status"` استفاده کنید.
</Accordion>
<Accordion title="What does not create tasks">
<Accordion title="چه چیزی وظیفه ایجاد نمی‌کند">
- نوبت‌های Heartbeat — نشست اصلی؛ [Heartbeat](/fa/gateway/heartbeat) را ببینید
- نوبت‌های گفت‌وگوی تعاملی عادی
- نوبت‌های گفت‌وگوی تعاملی معمولی
- پاسخ‌های مستقیم `/command`
</Accordion>
@ -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 بعدی ظاهر می‌شود.
<Tip>
تکمیل وظیفه یک بیدارسازی فوری Heartbeat را فعال می‌کند تا نتیجه را سریع ببینید — لازم نیست تا تیک زمان‌بندی‌شده بعدی Heartbeat صبر کنید.
تکمیل وظیفه یک بیدارباش فوری Heartbeat را فعال می‌کند تا نتیجه را سریع ببینید — لازم نیست تا تیک زمان‌بندی‌شده بعدی Heartbeat صبر کنید.
</Tip>
این یعنی گردش کار معمول مبتنی بر ارسال است: کار جداشده را یک بار شروع کنید، سپس اجازه دهید زمان‌اجرا هنگام تکمیل شما را بیدار کند یا اطلاع دهد. وضعیت وظیفه را فقط زمانی 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 <lookup> state_changes
@ -203,7 +209,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
توکن جست‌وجو یک شناسه وظیفه، شناسه اجرا یا کلید نشست را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا و خلاصه پایانی را نشان می‌دهد.
توکن lookup یک شناسه وظیفه، شناسه اجرا، یا کلید نشست را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا، و خلاصه terminal را نشان می‌دهد.
</Accordion>
<Accordion title="tasks cancel">
@ -211,7 +217,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
برای وظایف ACP و عامل فرعی، این کار نشست فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (دسته زمان‌اجرای فرزند جداگانه‌ای وجود ندارد). وضعیت به `cancelled` گذار می‌کند و در صورت کاربرد، اعلان تحویل ارسال می‌شود.
برای وظایف ACP و زیرعامل، این کار نشست فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (هیچ handle جداگانه‌ای برای runtime فرزند وجود ندارد). وضعیت به `cancelled` منتقل می‌شود و در صورت کاربرد، اعلان تحویل ارسال می‌شود.
</Accordion>
<Accordion title="tasks notify">
@ -224,63 +230,63 @@ openclaw tasks notify <lookup> 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` | هشدار | نقض خط زمانی (برای مثال، پیش از شروع پایان یافته است) |
</Accordion>
<Accordion title="نگهداری وظایف">
<Accordion title="tasks maintenance">
```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 بازمی‌گردد، و اجراهای فراخوانی ابزار که فقط به پایان‌زمان رسیده‌اند می‌توانند به یک خلاصه کوتاه از پیشرفت جزئی فروکاسته شوند. اجراهای پایانی ناموفق، وضعیت شکست را بدون بازپخش متن پاسخ ضبط‌شده اعلام می‌کنند.
- شکست‌های پاک‌سازی نتیجه واقعی وظیفه را پنهان نمی‌کنند.
</Accordion>
<Accordion title="فهرست | نمایش | لغو جریان وظایف">
<Accordion title="tasks flow list | show | cancel">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
وقتی چیزی که برایتان مهم است Task Flow هماهنگ‌کننده است، نه یک رکورد تکی از وظیفه پس‌زمینه، از این‌ها استفاده کنید.
وقتی جریان هماهنگ‌کننده Task Flow چیزی است که برایتان مهم است، نه یک رکورد منفرد وظیفه پس‌زمینه، از این‌ها استفاده کنید.
</Accordion>
</AccordionGroup>
## تابلوی وظایف 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 ثانیه** اجرا می‌شود و چهار کار را انجام می‌دهد:
<Steps>
<Step title="همگام‌سازی مجدد">
بررسی می‌کند که آیا وظایف فعال هنوز پشتوانه runtime معتبر دارند یا نه. وظایف ACP/subagent از وضعیت نشست فرزند استفاده می‌کنند، وظایف کرون از مالکیت active-job استفاده می‌کنند، و وظایف CLI با پشتوانه chat از context اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از ۵ دقیقه از بین رفته باشد، وظیفه `lost` علامت‌گذاری می‌شود.
<Step title="Reconciliation">
بررسی می‌کند که آیا وظایف فعال هنوز پشتوانه معتبر زمان اجرا دارند یا نه. وظایف ACP/زیرعامل از وضعیت نشست فرزند استفاده می‌کنند، وظایف cron از مالکیت کار فعال استفاده می‌کنند، و وظایف CLI متکی به چت از زمینه اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از 5 دقیقه از بین رفته باشد، وظیفه `lost` علامت‌گذاری می‌شود.
</Step>
<Step title="ترمیم نشست ACP">
نشست‌های ACP یک‌باره پایانی یا orphaned با مالکیت والد را می‌بندد، و نشست‌های ACP پایدار stale پایانی یا orphaned را فقط وقتی می‌بندد که هیچ binding گفت‌وگوی فعالی باقی نمانده باشد.
<Step title="ACP session repair">
نشست‌های ACP یک‌باره پایانی یا یتیم متعلق به والد را می‌بندد، و نشست‌های ACP پایدار پایانی کهنه یا یتیم را فقط وقتی می‌بندد که هیچ پیوند گفت‌وگوی فعالی باقی نمانده باشد.
</Step>
<Step title="ثبت پاک‌سازی">
یک timestamp با نام `cleanupAfter` روی وظایف پایانی تنظیم می‌کند (endedAt + ۷ روز). در طول دوره نگهداری، وظایف گم‌شده هنوز در ممیزی به‌عنوان هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی metadata پاک‌سازی وجود ندارد، خطا هستند.
<Step title="Cleanup stamping">
یک زمان‌مهر `cleanupAfter` روی وظایف پایانی تنظیم می‌کند (endedAt + 7 روز). در طول دوره نگهداری، وظایف گم‌شده هنوز در ممیزی به‌عنوان هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی فراداده پاک‌سازی موجود نباشد، خطا هستند.
</Step>
<Step title="هرس کردن">
رکوردهایی را که از تاریخ `cleanupAfter` خود گذشته‌اند حذف می‌کند.
<Step title="Pruning">
رکوردهایی را که تاریخ `cleanupAfter` آن‌ها گذشته است حذف می‌کند.
</Step>
</Steps>
<Note>
**نگهداری:** رکوردهای وظیفه پایانی به مدت **۷ روز** نگه داشته می‌شوند و سپس به‌صورت خودکار هرس می‌شوند. نیازی به پیکربندی نیست.
**نگهداری:** رکوردهای وظیفه پایانی به مدت **7 روز** نگه داشته می‌شوند، سپس به‌طور خودکار هرس می‌شوند. پیکربندی لازم نیست.
</Note>
## ارتباط وظایف با سیستم‌های دیگر
## ارتباط وظایف با سامانه‌های دیگر
<AccordionGroup>
<Accordion title="وظایف و Task Flow">
[Task Flow](/fa/automation/taskflow) لایه هماهنگ‌سازی flow بالای وظایف پس‌زمینه است. یک flow واحد ممکن است در طول عمر خود چندین وظیفه را با استفاده از حالت‌های sync مدیریت‌شده یا mirrored هماهنگ کند. از `openclaw tasks` برای بازرسی رکوردهای وظیفه منفرد و از `openclaw tasks flow` برای بازرسی flow هماهنگ‌کننده استفاده کنید.
<Accordion title="Tasks and Task Flow">
[Task Flow](/fa/automation/taskflow) لایه هماهنگ‌سازی جریان بالای وظایف پس‌زمینه است. یک جریان منفرد ممکن است در طول عمر خود چندین وظیفه را با استفاده از حالت‌های همگام‌سازی مدیریت‌شده یا آینه‌شده هماهنگ کند. از `openclaw tasks` برای بررسی رکوردهای وظیفه منفرد و از `openclaw tasks flow` برای بررسی جریان هماهنگ‌کننده استفاده کنید.
برای جزئیات، [Task Flow](/fa/automation/taskflow) را ببینید.
</Accordion>
<Accordion title="وظایف و کرون">
**definition** یک job کرون در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای runtime کنار آن در `~/.openclaw/cron/jobs-state.json` قرار دارد. **هر** اجرای کرون یک رکورد وظیفه ایجاد می‌کند، چه main-session و چه ایزوله. وظایف کرون main-session به‌صورت پیش‌فرض سیاست اعلان `silent` دارند تا بدون تولید اعلان ردیابی شوند.
<Accordion title="Tasks and cron">
یک **تعریف** کار cron در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای زمان اجرا کنار آن در `~/.openclaw/cron/jobs-state.json` قرار دارد. **هر** اجرای cron یک رکورد وظیفه ایجاد می‌کند — هم نشست اصلی و هم ایزوله. وظایف cron نشست اصلی به‌طور پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند تا بدون تولید اعلان ردیابی شوند.
[Cron Jobs](/fa/automation/cron-jobs) را ببینید.
</Accordion>
<Accordion title="وظایف و heartbeat">
اجراهای Heartbeat نوبت‌های main-session هستند؛ آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه تکمیل می‌شود، می‌تواند یک wake در heartbeat راه‌اندازی کند تا نتیجه را بی‌درنگ ببینید.
<Accordion title="Tasks and heartbeat">
اجراهای Heartbeat نوبت‌های نشست اصلی هستند — آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه تکمیل می‌شود، می‌تواند بیدارسازی Heartbeat را فعال کند تا نتیجه را سریع ببینید.
[Heartbeat](/fa/gateway/heartbeat) را ببینید.
</Accordion>
<Accordion title="وظایف و نشست‌ها">
یک وظیفه ممکن است به `childSessionKey` (جایی که کار اجرا می‌شود) و `requesterSessionKey` (کسی که آن را شروع کرده) ارجاع دهد. نشست‌ها context گفت‌وگو هستند؛ وظایف ردیابی فعالیت روی آن هستند.
<Accordion title="Tasks and sessions">
یک وظیفه ممکن است به یک `childSessionKey` (جایی که کار اجرا می‌شود) و یک `requesterSessionKey` (کسی که آن را شروع کرده است) ارجاع دهد. نشست‌ها زمینه گفت‌وگو هستند؛ وظایف ردیابی فعالیت روی آن هستند.
</Accordion>
<Accordion title="وظایف و اجراهای agent">
`runId` یک وظیفه به اجرای agent که کار را انجام می‌دهد پیوند دارد. رویدادهای چرخه عمر agent (شروع، پایان، خطا) به‌صورت خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند؛ لازم نیست چرخه عمر را دستی مدیریت کنید.
<Accordion title="Tasks and agent runs">
`runId` یک وظیفه به اجرای عاملی که کار را انجام می‌دهد پیوند دارد. رویدادهای چرخه عمر عامل (شروع، پایان، خطا) به‌طور خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند — لازم نیست چرخه عمر را دستی مدیریت کنید.
</Accordion>
</AccordionGroup>
## مرتبط
- [اتوماسیون و وظایف](/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) — هماهنگ‌سازی جریان بالای وظایف

776
docs/fa/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

412
docs/fa/ci.md
View File

@ -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=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## اجراکننده‌ها
## 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/<tested-ref>/<run-id>-<attempt>/<lane>/` commit می‌کند. pointer فعلی ref آزموده‌شده به‌صورت `openclaw-performance/<tested-ref>/latest-<lane>.json` نوشته می‌شود.
هر lane artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/` commit می‌کند. اشاره‌گر فعلی tested-ref به‌صورت `openclaw-performance/<tested-ref>/latest-<lane>.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=<sha>` از helper استفاده کنید:
برای اثبات commit pinned روی یک branch سریع‌تغییر، به‌جای `gh workflow run ... --ref main -f ref=<sha>` از helper استفاده کنید:
```bash
pnpm ci:full-release --sha <full-sha>
```
dispatch refهای GitHub workflow باید branch یا tag باشند، نه commit SHA خام. helper یک branch موقت `release-ci/<sha>-...` را در 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/<sha>-...` را در 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:<sha>` استفاده می‌کنند. گردش‌کار انتشار 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:<sha>` برای هر 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 <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # 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 <tbx_id>
```
فقط وقتی استفادهٔ مجدد را به کار ببرید که عمداً به چند فرمان روی همان جعبهٔ آماده‌شده نیاز دارید:
فقط وقتی از استفادهٔ دوباره استفاده کنید که عمدا به چند فرمان روی همان box آماده‌شده نیاز دارید:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
اگر لایهٔ خراب 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 <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_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 <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.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 <cbx_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 <cbx_id>` است.
## مرتبط

19
docs/fa/cli/dashboard.md
View File

@ -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 بدون توکن و راهنمای اصلاح صریح چاپ می‌کند.
## مرتبط

76
docs/fa/cli/doctor.md
View File

@ -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.<timestamp>` به تأیید تعاملی نیاز دارد؛ `--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.<id>` و حذف 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.<provider>` مهاجرت می‌دهد.
- اجراهای تکراری `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.<skill>.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.<timestamp>` به تأیید تعاملی نیاز دارد؛ `--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.<id>` و حذف 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.<provider>` خودکار مهاجرت می‌دهد.
- اجراهای تکراری `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.<skill>.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)

293
docs/fa/cli/gateway.md
View File

@ -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 …` قرار دارند.
<CardGroup cols={3}>
<Card title="Bonjour discovery" href="/fa/gateway/bonjour">
راه‌اندازی mDNS محلی + DNS-SD گسترده.
</Card>
<Card title="Discovery overview" href="/fa/gateway/discovery">
اینکه OpenClaw چگونه gatewayها را معرفی و پیدا می‌کند.
اینکه OpenClaw چگونه Gatewayها را تبلیغ و پیدا می‌کند.
</Card>
<Card title="Configuration" href="/fa/gateway/configuration">
کلیدهای پیکربندی gateway در سطح بالا.
کلیدهای پیکربندی سطح‌بالای Gateway.
</Card>
</CardGroup>
@ -45,12 +45,12 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Startup behavior">
- به‌طور پیش‌فرض، 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 بسته‌بندی می‌کنید، پیش از خروج ترمینال را بازیابی کنید.
</Accordion>
</AccordionGroup>
@ -58,10 +58,10 @@ openclaw gateway run
### گزینه‌ها
<ParamField path="--port <port>" type="number">
پورت WebSocket (پیش‌فرض از پیکربندی/env می‌آید؛ معمولا `18789`).
پورت WebSocket (پیش‌فرض از پیکربندی/محیط می‌آید؛ معمولاً `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
حالت bind شنونده.
حالت اتصال شنونده.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
بازنویسی حالت احراز هویت.
@ -79,16 +79,16 @@ openclaw gateway run
Gateway را از طریق Tailscale در دسترس قرار دهید.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموش‌شدن بازنشانی کنید.
پیکربندی serve/funnel مربوط به Tailscale را هنگام خاموشی بازنشانی کنید.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
اجازه دهید gateway بدون `gateway.mode=local` در پیکربندی شروع شود. فقط برای bootstrap موقت/توسعه، guard شروع را دور می‌زند؛ فایل پیکربندی را نمی‌نویسد یا تعمیر نمی‌کند.
اجازه شروع gateway بدون `gateway.mode=local` در پیکربندی را بدهید. این فقط برای bootstrap موقت/توسعه، محافظ شروع را دور می‌زند؛ فایل پیکربندی را نمی‌نویسد یا تعمیر نمی‌کند.
</ParamField>
<ParamField path="--dev" type="boolean">
اگر وجود ندارد، پیکربندی توسعه + workspace بسازید (`BOOTSTRAP.md` را رد می‌کند).
اگر وجود نداشته باشد، یک پیکربندی توسعه + فضای کاری بسازید (`BOOTSTRAP.md` را رد می‌کند).
</ParamField>
<ParamField path="--reset" type="boolean">
پیکربندی توسعه + credentials + نشست‌ها + workspace را بازنشانی کنید (به `--dev` نیاز دارد).
پیکربندی توسعه + اعتبارنامه‌ها + نشست‌ها + فضای کاری را بازنشانی کنید (به `--dev` نیاز دارد).
</ParamField>
<ParamField path="--force" type="boolean">
پیش از شروع، هر شنونده موجود روی پورت انتخاب‌شده را بکشید.
@ -97,7 +97,7 @@ openclaw gateway run
لاگ‌های پرجزئیات.
</ParamField>
<ParamField path="--cli-backend-logs" type="boolean">
فقط لاگ‌های backend مربوط به CLI را در کنسول نشان دهید (و stdout/stderr را فعال کنید).
فقط لاگ‌های بک‌اند CLI را در کنسول نشان بده (و stdout/stderr را فعال کن).
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
سبک لاگ Websocket.
@ -106,10 +106,10 @@ openclaw gateway run
نام مستعار برای `--ws-log compact`.
</ParamField>
<ParamField path="--raw-stream" type="boolean">
رویدادهای خام stream مدل را در jsonl لاگ کنید.
رخدادهای خام جریان مدل را در jsonl لاگ کن.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
مسیر jsonl مربوط به stream خام.
مسیر jsonl جریان خام.
</ParamField>
## راه‌اندازی مجدد 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` استفاده کنید که صراحتاً مسیر بازنویسی فوری را می‌خواهید.
<Warning>
`--password` درون‌خطی می‌تواند در فهرست‌های فرایند محلی آشکار شود. `--password-file`، env، یا `gateway.auth.password` مبتنی بر SecretRef را ترجیح دهید.
`--password` درون‌خطی می‌تواند در فهرست فرایندهای محلی افشا شود. `--password-file`، محیط، یا `gateway.auth.password` متکی بر SecretRef را ترجیح دهید.
</Warning>
### پروفایل‌گیری شروع
- `OPENCLAW_GATEWAY_STARTUP_TRACE=1` را تنظیم کنید تا زمان‌بندی فازها هنگام شروع Gateway لاگ شود، از جمله تاخیر `eventLoopMax` برای هر فاز و زمان‌بندی‌های جدول lookup مربوط به Plugin برای installed-index، manifest registry، برنامه‌ریزی شروع، و کار owner-map.
- `OPENCLAW_DIAGNOSTICS=timeline` را همراه با `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<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=<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 استفاده می‌کنند.
<Tabs>
<Tab title="Output modes">
- پیش‌فرض: خوانا برای انسان (رنگی در TTY).
- `--json`: JSON خوانا برای ماشین (بدون سبک‌دهی/spinner).
- `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال می‌کند و چیدمان انسانی را نگه می‌دارد.
- پیش‌فرض: قابل‌خواندن برای انسان (رنگی در TTY).
- `--json`: JSON قابل‌خواندن برای ماشین (بدون استایل/اسپینر).
- `--no-color` (یا `NO_COLOR=1`): ANSI را غیرفعال کن و چیدمان انسانی را حفظ کن.
</Tab>
<Tab title="Shared options">
- `--url <url>`: URL WebSocket مربوط به Gateway.
- `--url <url>`: نشانی WebSocket متعلق به Gateway.
- `--token <token>`: توکن Gateway.
- `--password <password>`: گذرواژه Gateway.
- `--timeout <ms>`: timeout/budget (بسته به دستور متفاوت است).
- `--expect-final`: منتظر پاسخ "final" بمانید (فراخوانی‌های agent).
- `--timeout <ms>`: زمان‌انتظار/بودجه (بسته به فرمان متفاوت است).
- `--expect-final`: منتظر پاسخ "final" بمان (فراخوانی‌های عامل).
</Tab>
</Tabs>
<Note>
وقتی `--url` را تنظیم می‌کنید، CLI به credentials موجود در پیکربندی یا محیط fallback نمی‌کند. `--token` یا `--password` را صراحتا پاس دهید. نبودن credentials صریح یک خطاست.
وقتی `--url` را تنظیم می‌کنید، CLI به اعتبارنامه‌های پیکربندی یا محیط fallback نمی‌کند. `--token` یا `--password` را صریحاً بدهید. نبود اعتبارنامه‌های صریح یک خطاست.
</Note>
### `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
```
<ParamField path="--days <days>" type="number" default="30">
تعداد روزهایی که باید لحاظ شوند.
تعداد روزهایی که باید شامل شود.
</ParamField>
### `gateway stability`
recorder تشخیصی پایداری اخیر را از یک Gateway در حال اجرا دریافت کنید.
ضبط‌کننده پایداری تشخیصی اخیر را از یک Gateway در حال اجرا دریافت کن.
```bash
openclaw gateway stability
@ -192,19 +192,19 @@ openclaw gateway stability --json
```
<ParamField path="--limit <limit>" type="number" default="25">
حداکثر تعداد رویدادهای اخیر برای لحاظ کردن (حداکثر `1000`).
حداکثر تعداد رخدادهای اخیر که باید شامل شوند (حداکثر `1000`).
</ParamField>
<ParamField path="--type <type>" type="string">
فیلتر بر اساس نوع رویداد تشخیصی، مانند `payload.large` یا `diagnostic.memory.pressure`.
بر اساس نوع رخداد تشخیصی فیلتر کن، مانند `payload.large` یا `diagnostic.memory.pressure`.
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
فقط رویدادهای پس از یک شماره توالی تشخیصی را لحاظ کنید.
فقط رخدادهای پس از یک شماره توالی تشخیصی را شامل کن.
</ParamField>
<ParamField path="--bundle [path]" type="string">
به‌جای فراخوانی Gateway در حال اجرا، یک bundle پایداری persisted را بخوانید. برای جدیدترین bundle زیر دایرکتوری state از `--bundle latest` (یا فقط `--bundle`) استفاده کنید، یا مسیر JSON یک bundle را مستقیما پاس دهید.
به‌جای فراخوانی Gateway در حال اجرا، یک bundle پایداری ماندگارشده را بخوان. برای جدیدترین bundle زیر دایرکتوری state از `--bundle latest` (یا فقط `--bundle`) استفاده کن، یا مسیر JSON یک bundle را مستقیماً بده.
</ParamField>
<ParamField path="--export" type="boolean">
به‌جای چاپ جزئیات پایداری، یک zip تشخیصی قابل اشتراک‌گذاری برای پشتیبانی بنویسید.
به‌جای چاپ جزئیات پایداری، یک zip تشخیصی پشتیبانی قابل‌اشتراک بنویس.
</ParamField>
<ParamField path="--output <path>" type="string">
مسیر خروجی برای `--export`.
@ -212,15 +212,15 @@ openclaw gateway stability --json
<AccordionGroup>
<Accordion title="Privacy and bundle behavior">
- رکوردها 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 اعمال می‌شوند.
</Accordion>
</AccordionGroup>
### `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
```
<ParamField path="--output <path>" type="string">
مسیر zip خروجی. پیش‌فرض، یک export پشتیبانی زیر دایرکتوری state است.
مسیر zip خروجی. پیش‌فرض یک export پشتیبانی زیر دایرکتوری state است.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
حداکثر تعداد خطوط لاگ sanitize‌شده برای لحاظ کردن.
حداکثر خطوط لاگ پاک‌سازی‌شده که باید شامل شوند.
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
حداکثر بایت‌های لاگ برای بررسی.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket مربوط به Gateway برای snapshot سلامت.
نشانی WebSocket متعلق به Gateway برای snapshot سلامت.
</ParamField>
<ParamField path="--token <token>" type="string">
توکن Gateway برای snapshot سلامت.
@ -247,18 +247,18 @@ openclaw gateway diagnostics export --json
گذرواژه Gateway برای snapshot سلامت.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
timeout مربوط به snapshot وضعیت/سلامت.
زمان‌انتظار snapshot وضعیت/سلامت.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
lookup مربوط به bundle پایداری persisted را رد کنید.
جست‌وجوی bundle پایداری ماندگارشده را رد کن.
</ParamField>
<ParamField path="--json" type="boolean">
مسیر نوشته‌شده، اندازه، و manifest را به‌صورت JSON چاپ کنید.
مسیر نوشته‌شده، اندازه، و مانیفست را به‌صورت JSON چاپ کن.
</ParamField>
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
```
<ParamField path="--url <url>" type="string">
یک هدف پروب صریح اضافه کنید. راه دور پیکربندی‌شده + localhost همچنان پروب می‌شوند.
یک هدف کاوش صریح اضافه کنید. ریموت پیکربندی‌شده + localhost همچنان کاوش می‌شوند.
</ParamField>
<ParamField path="--token <token>" type="string">
احراز هویت با توکن برای پروب.
احراز هویت با توکن برای کاوش.
</ParamField>
<ParamField path="--password <password>" type="string">
احراز هویت با گذرواژه برای پروب.
احراز هویت با گذرواژه برای کاوش.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
مهلت زمانی پروب.
مهلت زمانی کاوش.
</ParamField>
<ParamField path="--no-probe" type="boolean">
پروب اتصال را رد کنید (نمای فقط سرویس).
از کاوش اتصال‌پذیری صرف‌نظر کنید (نمای فقط سرویس).
</ParamField>
<ParamField path="--deep" type="boolean">
سرویس‌های سطح سیستم را هم اسکن کنید.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
پروب اتصال پیش‌فرض را به پروب خواندن ارتقا دهید و وقتی آن پروب خواندن شکست می‌خورد با کد غیرصفر خارج شوید. نمی‌توان آن را با `--no-probe` ترکیب کرد.
کاوش اتصال‌پذیری پیش‌فرض را به کاوش خواندن ارتقا دهید و وقتی آن کاوش خواندن شکست می‌خورد با کد غیرصفر خارج شوید. نمی‌توان آن را با `--no-probe` ترکیب کرد.
</ParamField>
<AccordionGroup>
<Accordion title="معناشناسی وضعیت">
- `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 کمک کند.
</Accordion>
<Accordion title="بررسی‌های drift احراز هویت در systemd لینوکس">
- در نصب‌های systemd لینوکس، بررسی‌های drift احراز هویت سرویس مقدارهای `Environment=` و `EnvironmentFile=` را از unit می‌خوانند (از جمله `%h`، مسیرهای نقل‌قول‌شده، چند فایل، و فایل‌های اختیاری `-`).
- بررسی‌های drift، SecretRefهای `gateway.auth.token` را با استفاده از محیط زمان اجرای ادغام‌شده حل می‌کنند (ابتدا محیط فرمان سرویس، سپس محیط فرایند به‌عنوان جایگزین).
- اگر احراز هویت با توکن عملاً فعال نباشد (`gateway.auth.mode` صریحِ `password`/`none`/`trusted-proxy`، یا حالتی که تنظیم نشده و در آن گذرواژه می‌تواند انتخاب شود و هیچ نامزد توکنی نمی‌تواند انتخاب شود)، بررسی‌های drift توکن از حل توکن پیکربندی صرف‌نظر می‌کنند.
<Accordion title="بررسی‌های drift احراز هویت systemd در Linux">
- در نصب‌های 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 کردن توکن پیکربندی صرف‌نظر می‌کنند.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` فرمان «اشکال‌زدایی همه‌چیز» است. همیشه این موارد را پروب می‌کند:
`gateway probe` فرمان «عیب‌یابی همه‌چیز» است. همیشه موارد زیر را کاوش می‌کند:
- Gateway راه دور پیکربندی‌شده شما (اگر تنظیم شده باشد)، و
- localhost (loopback) **حتی اگر راه دور پیکربندی شده باشد**.
- gateway ریموت پیکربندی‌شده شما (اگر تنظیم شده باشد)، و
- localhost (loopback) **حتی اگر ریموت پیکربندی شده باشد**.
اگر `--url` را بدهید، آن هدف صریح پیش از هر دوی آن‌ها اضافه می‌شود. خروجی انسانی هدف‌ها را این‌گونه برچسب می‌زند:
اگر `--url` را پاس دهید، آن هدف صریح جلوتر از هر دو اضافه می‌شود. خروجی انسانی هدف‌ها را این‌گونه برچسب می‌زند:
- `URL (explicit)`
- `Remote (configured)` یا `Remote (configured, inactive)`
- `Local loopback`
<Note>
اگر چند Gateway در دسترس باشند، همه آن‌ها را چاپ می‌کند. چند Gateway وقتی از پروفایل‌ها/پورت‌های ایزوله استفاده می‌کنید (مثلاً یک ربات نجات) پشتیبانی می‌شوند، اما بیشتر نصب‌ها همچنان یک Gateway واحد اجرا می‌کنند.
اگر چند gateway قابل دسترس باشند، همه آن‌ها را چاپ می‌کند. وقتی از پروفایل‌ها/پورت‌های ایزوله استفاده می‌کنید (مثلا یک بات نجات)، چند gateway پشتیبانی می‌شود، اما بیشتر نصب‌ها همچنان یک Gateway واحد اجرا می‌کنند.
</Note>
```bash
@ -337,51 +337,51 @@ openclaw gateway probe --json
<AccordionGroup>
<Accordion title="تفسیر">
- `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`، کاوش از احراز هویت دستگاه کش‌شده موجود استفاده می‌کند اما هویت دستگاه بار اول یا وضعیت جفت‌سازی ایجاد نمی‌کند.
- کد خروج فقط وقتی غیرصفر است که هیچ هدف کاوش‌شده‌ای قابل دسترس نباشد.
</Accordion>
<Accordion title="خروجی JSON">
سطح بالا:
- `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`: طبقه‌بندی قابلیت احراز هویت ارائه‌شده برای آن هدف.
</Accordion>
<Accordion title="کدهای هشدار رایج">
- `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` محدود شد.
</Accordion>
</AccordionGroup>
#### راه دور از طریق SSH (هم‌ارزی با اپ Mac)
#### ریموت از طریق SSH (برابری با برنامه Mac)
حالت «راه دور از طریق SSH» در اپ macOS از یک فوروارد پورت محلی استفاده می‌کند تا Gateway راه دور (که ممکن است فقط به loopback متصل شده باشد) در `ws://127.0.0.1:<port>` در دسترس شود.
حالت "Remote over SSH" در برنامه macOS از یک port-forward محلی استفاده می‌کند تا gateway ریموت (که ممکن است فقط به loopback bind شده باشد) در `ws://127.0.0.1:<port>` قابل دسترس شود.
معادل CLI:
@ -390,23 +390,23 @@ openclaw gateway probe --ssh user@gateway-host
```
<ParamField path="--ssh <target>" type="string">
`user@host` یا `user@host:port` (پورت به‌طور پیش‌فرض `22` است).
`user@host` یا `user@host:port` (port به‌طور پیش‌فرض `22` است).
</ParamField>
<ParamField path="--ssh-identity <path>" type="string">
فایل هویت.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
اولین میزبان Gateway کشف‌شده را از نقطه پایانی کشف حل‌شده (`local.` به‌علاوه دامنه گستره‌وسیع پیکربندی‌شده، اگر وجود داشته باشد) به‌عنوان هدف SSH انتخاب کنید. راهنماهای فقط TXT نادیده گرفته می‌شوند.
نخستین میزبان gateway کشف‌شده را از endpoint کشف resolveشده (`local.` به‌علاوه دامنه wide-area پیکربندی‌شده، اگر وجود داشته باشد) به‌عنوان هدف SSH انتخاب کنید. راهنمایی‌های فقط TXT نادیده گرفته می‌شوند.
</ParamField>
پیکربندی (اختیاری، به‌عنوان پیش‌فرض استفاده می‌شود):
پیکربندی (اختیاری، استفاده‌شده به‌عنوان پیش‌فرض):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
کمک‌رسان سطح‌پایین RPC.
کمک‌کننده RPC سطح پایین.
```bash
openclaw gateway call status
@ -414,10 +414,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
<ParamField path="--params <json>" type="string" default="{}">
رشته شیء JSON برای پارامترها.
رشته شیء JSON برای params.
</ParamField>
<ParamField path="--url <url>" type="string">
URL وب‌سوکت Gateway.
URL مربوط به WebSocket برای Gateway.
</ParamField>
<ParamField path="--token <token>" type="string">
توکن Gateway.
@ -426,10 +426,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
گذرواژه Gateway.
</ParamField>
<ParamField path="--timeout <ms>" type="number">
بودجه مهلت زمانی.
بودجه timeout.
</ParamField>
<ParamField path="--expect-final" type="boolean">
عمدتاً برای RPCهای سبک عامل که رویدادهای میانی را پیش از محموله نهایی به‌صورت جریان ارسال می‌کنند.
عمدتا برای RPCهای سبک agent که پیش از payload نهایی eventهای میانی را stream می‌کنند.
</ParamField>
<ParamField path="--json" type="boolean">
خروجی 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
<AccordionGroup>
<Accordion title="گزینه‌های فرمان">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway status`: `--url`، `--token`، `--password`، `--timeout`، `--no-probe`، `--require-rpc`، `--deep`، `--json`
- `gateway install`: `--port`، `--runtime <node|bun>`، `--token`، `--wrapper <path>`، `--force`، `--json`
- `gateway restart`: `--safe`، `--force`، `--wait <duration>`، `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="رفتار چرخه عمر">
- برای 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` را برای اسکریپت‌نویسی می‌پذیرند.
</Accordion>
<Accordion title="احراز هویت و SecretRefها هنگام نصب">
- وقتی احراز هویت با توکن به توکن نیاز دارد و `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 صریحاً تنظیم شود مسدود می‌شود.
<Accordion title="احراز هویت و SecretRefs در زمان نصب">
- وقتی احراز هویت توکنی به یک توکن نیاز دارد و `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` تنظیم نشده باشد، نصب تا زمانی که حالت به‌صراحت تنظیم شود مسدود می‌شود.
</Accordion>
</AccordionGroup>
## کشف 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
```
<ParamField path="--timeout <ms>" type="number" default="2000">
مهلت زمانی هر فرمان (browse/resolve).
مهلت زمانی هر دستور (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
خروجی قابل خواندن توسط ماشین (همچنین استایل‌دهی/چرخنده را غیرفعال می‌کند).
خروجی قابل خواندن برای ماشین (همچنین سبک‌دهی/spinner را غیرفعال می‌کند).
</ParamField>
مثال‌ها:
@ -544,13 +545,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- 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` آنجا هم اختیاری می‌ماند.
</Note>
## مرتبط
- [مرجع CLI](/fa/cli)
- [راهنمای عملیاتی Gateway](/fa/gateway)
- [Runbook Gateway](/fa/gateway)

231
docs/fa/cli/plugins.md
View File

@ -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، و باندل‌های سازگار.
<CardGroup cols={2}>
<Card title="سیستم Plugin" href="/fa/tools/plugin">
راهنمای کاربر نهایی برای نصب، فعال‌سازی، و عیب‌یابی Pluginها.
</Card>
<Card title="مدیریت Pluginها" href="/fa/plugins/manage-plugins">
نمونه‌های سریع برای نصب، فهرست، به‌روزرسانی، حذف نصب، و انتشار.
نمونه‌های سریع برای نصب، فهرست‌کردن، به‌روزرسانی، حذف نصب، و انتشار.
</Card>
<Card title="bundleهای Plugin" href="/fa/plugins/bundles">
مدل سازگاری bundle.
<Card title="باندل‌های Plugin" href="/fa/plugins/bundles">
مدل سازگاری باندل.
</Card>
<Card title="manifest مربوط به Plugin" href="/fa/plugins/manifest">
فیلدهای manifest و طرح‌واره پیکربندی.
<Card title="مانیفست Plugin" href="/fa/plugins/manifest">
فیلدهای مانیفست و طرح‌واره پیکربندی.
</Card>
<Card title="امنیت" href="/fa/gateway/security">
سخت‌سازی امنیتی برای نصب Pluginها.
</Card>
</CardGroup>
## دستورها
## فرمان‌ها
```bash
openclaw plugins list
@ -62,100 +62,90 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --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) را ببینید.
<Note>
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`) به‌همراه قابلیت‌های باندل شناسایی‌شده را نشان می‌دهد.
</Note>
### نصب
```bash
openclaw plugins search "calendar" # جست‌وجوی Pluginهای ClawHub
openclaw plugins install <package> # npm به‌صورت پیش‌فرض
openclaw plugins install clawhub:<package> # فقط ClawHub
openclaw plugins install npm:<package> # فقط npm
openclaw plugins install git:github.com/<owner>/<repo> # مخزن git
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # npm by default
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force # بازنویسی نصب موجود
openclaw plugins install <package> --pin # سنجاق کردن نسخه
openclaw plugins install <package> --force # overwrite existing install
openclaw plugins install <package> --pin # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # مسیر محلی
openclaw plugins install <path> # local path
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (صریح)
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
<Warning>
در دوره انتقال راه‌اندازی، نام‌های خام package به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:<package>` استفاده کنید. نصب Pluginها را مانند اجرای کد در نظر بگیرید. نسخه‌های سنجاق‌شده را ترجیح دهید.
نام‌های بسته ساده در دوره گذار راه‌اندازی به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:<package>` استفاده کنید. نصب Pluginها را مانند اجرای کد در نظر بگیرید. نسخه‌های pin‌شده را ترجیح دهید.
</Warning>
`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` استفاده کنید.
<Note>
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 می‌کنند.
</Note>
<AccordionGroup>
<Accordion title="includeهای پیکربندی و تعمیر پیکربندی نامعتبر">
اگر بخش `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` را فعال کرده‌اند.
</Accordion>
<Accordion title="--force و نصب دوباره در برابر به‌روزرسانی">
`--force` هدف نصب موجود را دوباره استفاده می‌کند و یک Plugin یا بسته hook ازقبل‌نصب‌شده را درجا بازنویسی می‌کند. زمانی از آن استفاده کنید که عمداً همان id را از یک مسیر محلی جدید، archive، package در ClawHub، یا artifact در npm دوباره نصب می‌کنید. برای ارتقاهای معمول یک Plugin npm که از قبل رهگیری می‌شود، `openclaw plugins update <id-or-npm-spec>` را ترجیح دهید.
<Accordion title="--force و نصب مجدد در برابر به‌روزرسانی">
`--force` از هدف نصب موجود دوباره استفاده می‌کند و یک Plugin یا بسته hook از قبل نصب‌شده را در همان محل بازنویسی می‌کند. وقتی عمداً همان id را از یک مسیر محلی جدید، آرشیو، بسته ClawHub، یا artifact در npm دوباره نصب می‌کنید، از آن استفاده کنید. برای ارتقاهای روتین یک Plugin در npm که از قبل رهگیری می‌شود، `openclaw plugins update <id-or-npm-spec>` را ترجیح دهید.
اگر `plugins install` را برای یک id مربوط به Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update <id-or-npm-spec>` راهنمایی می‌کند، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید، به `plugins install <package> --force` اشاره می‌کند.
اگر `plugins install` را برای id یک Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update <id-or-npm-spec>`، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید به `plugins install <package> --force` راهنمایی می‌کند.
</Accordion>
<Accordion title="دامنه --pin">
`--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 را پایدار نگه می‌دارند.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--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) استفاده کنید.
</Accordion>
<Accordion title="بسته‌های hook و specهای npm">
`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:<package>` استفاده کنید. در دوره انتقال راه‌اندازی، specهای خام package نیز مستقیماً از npm نصب می‌شوند.
وقتی می‌خواهید resolution در npm را صریح کنید، از `npm:<package>` استفاده کنید. در دوره گذار راه‌اندازی، 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`).
</Accordion>
<Accordion title="مخزن‌های Git">
برای نصب مستقیم از یک مخزن git از `git:<repo>` استفاده کنید. شکل‌های پشتیبانی‌شده شامل `git:github.com/owner/repo`، `git:owner/repo`، نشانی‌های clone کامل `https://`، `ssh://`، `git://`، `file://`، و `git@host:owner/repo.git` هستند. برای check out کردن یک branch، tag، یا commit پیش از نصب، `@<ref>` یا `#<ref>` را اضافه کنید.
برای نصب مستقیم از یک مخزن git از `git:<repo>` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با الگوهای `git:github.com/owner/repo`، `git:owner/repo`، کامل `https://`، `ssh://`، `git://`، `file://`، و `git@host:owner/repo.git` هستند. برای checkout کردن یک branch، tag، یا commit پیش از نصب، `@<ref>` یا `#<ref>` اضافه کنید.
نصب‌های 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 <id> --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 <id> --runtime --json` استفاده کنید. اگر Plugin با `api.registerCli` یک ریشه CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archiveها">
archiveهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. archiveهای native Plugin در OpenClaw باید یک `openclaw.plugin.json` معتبر در ریشه Plugin استخراج‌شده داشته باشند؛ archiveهایی که فقط `package.json` دارند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند.
<Accordion title="آرشیوها">
آرشیوهای پشتیبانی‌شده: `.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 <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
وقتی می‌خواهید منبع marketplace را صریح ارسال کنید، از `--marketplace` استفاده کنید:
وقتی می‌خواهید منبع marketplace را صریحاً ارسال کنید، از `--marketplace` استفاده کنید:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -204,28 +194,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="منابع Marketplace">
<Tab title="Marketplace sources">
- نام marketplace شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json`
- ریشه marketplace محلی یا مسیر `marketplace.json`
- خلاصه مخزن GitHub مانند `owner/repo`
- کوتاه‌نوشت مخزن GitHub مانند `owner/repo`
- URL مخزن GitHub مانند `https://github.com/owner/repo`
- یک URL گیت
</Tab>
<Tab title="قواعد Marketplace راه‌دور">
برای marketplaceهای راه‌دور که از GitHub یا گیت بارگذاری می‌شوند، ورودی‌های plugin باید داخل مخزن marketplace شبیه‌سازی‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از همان مخزن می‌پذیرد و منابع Plugin از نوع HTTP(S)، مسیر مطلق، گیت، GitHub و دیگر منابع غیرمسیری را از manifestهای راه‌دور رد می‌کند.
<Tab title="Remote marketplace rules">
برای marketplaceهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از آن مخزن می‌پذیرد و منابع Plugin از نوع HTTP(S)، مسیر مطلق، git، GitHub و دیگر منابع غیرمسیر را از manifestهای راه‌دور رد می‌کند.
</Tab>
</Tabs>
برای مسیرها و آرشیوهای محلی، 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`)
<Note>
بسته‌های سازگار در ریشه معمول 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 وصل نشده‌اند.
</Note>
### فهرست
@ -241,48 +231,49 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
فقط pluginهای فعال‌شده را نشان بده.
فقط Pluginهای فعال‌شده را نشان بده.
</ParamField>
<ParamField path="--verbose" type="boolean">
از نمای جدول به خط‌های جزئیات جداگانه برای هر plugin با فراداده‌های منبع/خاستگاه/نسخه/فعال‌سازی جابه‌جا شو.
از نمای جدول به خطوط جزئیات جداگانه برای هر Plugin با فراداده منبع/خاستگاه/نسخه/فعال‌سازی جابه‌جا شو.
</ParamField>
<ParamField path="--json" type="boolean">
موجودی قابل‌خواندن برای ماشین به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های package.
موجودی قابل‌خواندن برای ماشین، به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های بسته.
</ParamField>
<Note>
`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 نمی‌کند، مدیر بسته اجرا نمی‌کند، و وابستگی‌های گم‌شده را تعمیر نمی‌کند.
</Note>
`plugins search` یک جست‌وجوی کاتالوگ راه‌دور ClawHub است. وضعیت محلی را بررسی نمی‌کند، config را تغییر نمی‌دهد، package نصب نمی‌کند، یا کد زمان اجرای plugin را بارگذاری نمی‌کند. نتایج جست‌وجو شامل نام package در ClawHub، خانواده، channel، نسخه، خلاصه، و راهنمای نصب مانند `openclaw plugins install clawhub:<package>` هستند.
`plugins search` یک lookup کاتالوگ راه‌دور ClawHub است. وضعیت محلی را بررسی نمی‌کند، config را تغییر نمی‌دهد، بسته نصب نمی‌کند، یا کد runtime مربوط به Plugin را بارگذاری نمی‌کند. نتایج جست‌وجو نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:<package>` را شامل می‌شوند.
برای کار روی 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 <id> --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.<id>.hooks.allowConversationAccess=true` نیاز دارند.
- `openclaw plugins inspect <id> --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.<id>.hooks.allowConversationAccess=true` نیاز دارند.
برای جلوگیری از کپی‌کردن یک دایرکتوری محلی، از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌شود):
برای جلوگیری از کپی‌کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` همراه با `--link` پشتیبانی نمی‌شود، چون نصب‌های لینک‌شده به‌جای کپی‌کردن روی یک هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند.
`--force` همراه با `--link` پشتیبانی نمی‌شود، زیرا نصب‌های لینک‌شده به‌جای کپی‌کردن روی هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند.
برای نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolveشده (`name@version`) در index plugin مدیریت‌شده ذخیره شود، درحالی‌که رفتار پیش‌فرض بدون pin باقی می‌ماند.
در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در index مدیریت‌شده Plugin ذخیره شود، درحالی‌که رفتار پیش‌فرض بدون pin باقی می‌ماند.
</Note>
### 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 <id> --dry-run
openclaw plugins uninstall <id> --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` بازنشانی می‌شود.
<Note>
`--keep-config` به‌عنوان alias منسوخ‌شده برای `--keep-files` پشتیبانی می‌شود.
`--keep-config` به‌عنوان alias منسوخ برای `--keep-files` پشتیبانی می‌شود.
</Note>
### به‌روزرسانی
@ -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` اعمال می‌شوند.
<AccordionGroup>
<Accordion title="Resolve کردن id plugin در برابر spec npm">
وقتی یک id plugin را پاس می‌دهید، OpenClaw از spec نصب ثبت‌شده برای همان plugin دوباره استفاده می‌کند. یعنی dist-tagهایی مانند `@beta` که قبلاً ذخیره شده‌اند و نسخه‌های دقیق pinشده در اجراهای بعدی `update <id>` همچنان استفاده می‌شوند.
<Accordion title="Resolving plugin id vs npm spec">
وقتی یک id مربوط به Plugin می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای قبلاً ذخیره‌شده مانند `@beta` و نسخه‌های دقیق pinشده در اجراهای بعدی `update <id>` همچنان استفاده می‌شوند.
برای نصب‌های 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 شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید.
</Accordion>
<Accordion title="به‌روزرسانی‌های channel بتا">
`openclaw plugins update` از spec ردیابی‌شده plugin دوباره استفاده می‌کند، مگر اینکه spec جدیدی پاس بدهید. `openclaw update` علاوه بر این channel فعال به‌روزرسانی OpenClaw را می‌شناسد: روی channel بتا، رکوردهای plugin npm و ClawHub از خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر هیچ انتشار بتایی برای plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده fallback می‌کنند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند.
<Accordion title="Beta channel updates">
`openclaw plugins update` از spec ردیابی‌شده Plugin دوباره استفاده می‌کند مگر اینکه spec جدیدی بدهید. `openclaw update` علاوه‌براین کانال فعال به‌روزرسانی OpenClaw را می‌شناسد: در کانال beta، رکوردهای Plugin مربوط به npm و ClawHub در خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار beta برای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده برمی‌گردند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند.
</Accordion>
<Accordion title="بررسی‌های نسخه و drift یکپارچگی">
پیش از یک به‌روزرسانی زنده npm، OpenClaw نسخه package نصب‌شده را در برابر فراداده رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolveشده مطابقت داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود.
<Accordion title="Version checks and integrity drift">
پیش از یک به‌روزرسانی زنده 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 عمل می‌کنند، مگر اینکه فراخواننده یک سیاست ادامه صریح ارائه دهد.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install در update">
`--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای مثبت‌های کاذب scan کد خطرناک داخلی هنگام به‌روزرسانی plugin در دسترس است. همچنان blockهای سیاست `before_install` مربوط به plugin یا مسدودسازی ناشی از شکست scan را دور نمی‌زند، و فقط برای به‌روزرسانی‌های plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack.
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای false positiveهای اسکن کد خطرناک داخلی هنگام به‌روزرسانی Pluginها در دسترس است. همچنان بلوک‌های سیاست `before_install` مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند، و فقط روی به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack.
</Accordion>
</AccordionGroup>
### Inspect
### بازرسی
```bash
openclaw plugins inspect <id>
@ -342,21 +333,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --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 <command> ...` اجرا کنید؛ برای نمونه pluginی که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود.
commandهای CLI تحت مالکیت Plugin به‌عنوان گروه‌های command ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک command را زیر `cliCommands` نشان داد، آن را به‌صورت `openclaw <command> ...` اجرا کنید؛ برای مثال 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) را ببینید.
<Note>
پرچم `--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` است.
</Note>
### 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.<id>` یا `plugins.allow`، diagnostic قبلی plugin مسدودشده، مانند مالکیت مسیر یا مجوزهای world-writable، را اصلاح کنید.
اگر یک Plugin پیکربندی‌شده روی دیسک وجود داشته باشد اما توسط بررسی‌های ایمنی مسیر loader مسدود شده باشد، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف `plugins.entries.<id>` یا 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 آن بسته کهنه را حذف می‌کند و رجیستری را بازسازی می‌کند تا راه‌اندازی در برابر مانیفست همراه اعتبارسنجی شود.
<Warning>
`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 محیط فقط برای بازیابی اضطراری راه‌اندازی هنگام عرضه تدریجی مهاجرت است.
</Warning>
### بازارچه
@ -396,7 +387,7 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
فهرست بازارچه یک مسیر بازارچهٔ محلی، یک مسیر `marketplace.json`، یک اختصار GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL گیت را می‌پذیرد. `--json` برچسب منبع حل‌شده به‌همراه manifest بازارچهٔ تجزیه‌شده و ورودی‌های Plugin را چاپ می‌کند.
فهرست بازارچه یک مسیر محلی بازارچه، یک مسیر `marketplace.json`، یک کوتاه‌نویسی GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL git را می‌پذیرد. `--json` برچسب منبع حل‌شده را به‌همراه مانیفست بازارچه تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند.
## مرتبط

89
docs/fa/cli/sessions.md
View File

@ -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 <n>` را بدهید یا وقتی عمداً به کل
ذخیره‌گاه نیاز دارید، از `--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 <id>`: یک مخزن عامل پیکربندی‌شده
- `--all-agents`: تجمیع همهٔ مخزن‌های عامل پیکربندی‌شده
- `--store <path>`: مسیر صریح مخزن (نمی‌توان آن را با `--agent` یا `--all-agents` ترکیب کرد)
- پیش‌فرض: ذخیره‌گاه عامل پیش‌فرض پیکربندی‌شده
- `--verbose`: ثبت گزارش مفصل
- `--agent <id>`: یک ذخیره‌گاه عامل پیکربندی‌شده
- `--all-agents`: تجمیع همه ذخیره‌گاه‌های عامل پیکربندی‌شده
- `--store <path>`: مسیر صریح ذخیره‌گاه (نمی‌تواند با `--agent` یا `--all-agents` ترکیب شود)
- `--limit <n|all>`: بیشینه ردیف‌ها برای خروجی (پیش‌فرض `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/<jobId>.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/<jobId>.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 <key>`: از یک کلید فعال مشخص در برابر تخلیهٔ بودجهٔ دیسک محافظت می‌کند. اشاره‌گرهای بادوام گفت‌وگوی خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگهداری سن/تعداد/بودجهٔ دیسک نگه داشته می‌شوند.
- `--agent <id>`: پاک‌سازی را برای یک مخزن عامل پیکربندی‌شده اجرا می‌کند.
- `--all-agents`: پاک‌سازی را برای همهٔ مخزن‌های عامل پیکربندی‌شده اجرا می‌کند.
- `--fix-missing`: ورودی‌هایی را که فایل‌های رونوشتشان موجود نیست حذف می‌کند، حتی اگر معمولاً هنوز بر اساس سن/تعداد حذف نمی‌شدند.
- `--active-key <key>`: یک کلید فعال مشخص را از حذف به‌دلیل بودجه دیسک محافظت می‌کند. اشاره‌گرهای پایدار مکالمه خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز در نگهداری مبتنی بر سن/تعداد/بودجه دیسک حفظ می‌شوند.
- `--agent <id>`: پاک‌سازی را برای یک ذخیره‌گاه عامل پیکربندی‌شده اجرا می‌کند.
- `--all-agents`: پاک‌سازی را برای همه ذخیره‌گاه‌های عامل پیکربندی‌شده اجرا می‌کند.
- `--store <path>`: روی یک فایل مشخص `sessions.json` اجرا می‌شود.
- `--json`: خلاصهٔ JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر مخزن است.
- `--json`: یک خلاصه JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر ذخیره‌گاه است.
وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای مخزن‌های عامل
پیکربندی‌شده از طریق Gateway ارسال می‌شود تا از همان نویسندهٔ مخزن نشستِ ترافیک
زمان اجرا استفاده کند. برای تعمیر آفلاین صریحِ یک فایل مخزن از `--store <path>`
استفاده کنید.
وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای ذخیره‌گاه‌های عامل پیکربندی‌شده
از طریق Gateway ارسال می‌شود تا همان نویسنده ذخیره‌گاه نشست را با ترافیک زمان اجرا
به اشتراک بگذارد. برای ترمیم آفلاین صریح یک فایل ذخیره‌گاه، از `--store <path>` استفاده کنید.
`openclaw sessions cleanup --all-agents --dry-run --json`:

183
docs/fa/cli/update.md
View File

@ -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 <stable|beta|dev>`: کانال به‌روزرسانی را تنظیم می‌کند (git + npm؛ در پیکربندی ماندگار می‌شود).
- `--tag <dist-tag|version|spec>`: هدف بسته را فقط برای همین به‌روزرسانی بازنویسی می‌کند. برای نصب‌های بسته‌ای، `main` به `github:openclaw/openclaw#main` نگاشت می‌شود.
- `--dry-run`: اقدام‌های به‌روزرسانی برنامه‌ریزی‌شده را (جریان کانال/برچسب/هدف/راه‌اندازی مجدد) بدون نوشتن پیکربندی، نصب، همگام‌سازی plugins یا راه‌اندازی مجدد پیش‌نمایش می‌کند.
- `--json`: JSON قابل‌خواندن برای ماشین `UpdateRunResult` را چاپ می‌کند، شامل
`postUpdate.plugins.integrityDrifts` وقتی در جریان همگام‌سازی Plugin پس از به‌روزرسانی، drift در artifact مربوط به npm plugin
- `--tag <dist-tag|version|spec>`: هدف بسته را فقط برای این به‌روزرسانی بازنویسی می‌کند. برای نصب‌های بسته‌ای، `main` به `github:openclaw/openclaw#main` نگاشت می‌شود.
- `--dry-run`: اقدام‌های برنامه‌ریزی‌شدهٔ به‌روزرسانی (جریان کانال/تگ/هدف/راه‌اندازی دوباره) را بدون نوشتن پیکربندی، نصب، همگام‌سازی Pluginها، یا راه‌اندازی دوباره پیش‌نمایش می‌کند.
- `--json`: JSON قابل‌خواندن برای ماشینِ `UpdateRunResult` را چاپ می‌کند، شامل
`postUpdate.plugins.integrityDrifts` وقتی در همگام‌سازی Plugin پس از به‌روزرسانی، انحراف آرتیفکت npm Plugin
شناسایی شود.
- `--timeout <seconds>`: مهلت زمانی هر مرحله (پیش‌فرض 1800s است).
- `--yes`: پیام‌های تأیید را رد می‌کند (برای مثال تأیید downgrade).
- `--timeout <seconds>`: مهلت زمانی برای هر مرحله (پیش‌فرض 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) را ببینید.
<Warning>
Downgradeها به تأیید نیاز دارند، چون نسخه‌های قدیمی‌تر می‌توانند پیکربندی را خراب کنند.
بازگشت به نسخه‌های قدیمی‌تر به تأیید نیاز دارد، زیرا نسخه‌های قدیمی‌تر می‌توانند پیکربندی را خراب کنند.
</Warning>
## `update status`
کانال به‌روزرسانی فعال + برچسب/شاخه/SHA مربوط به git (برای checkoutهای منبع)، به‌علاوه دسترس‌پذیری به‌روزرسانی را نشان می‌دهد.
کانال به‌روزرسانی فعال + تگ/شاخه/SHA git (برای checkoutهای منبع)، به‌همراه دسترس‌پذیری به‌روزرسانی را نشان می‌دهد.
```bash
openclaw update status
@ -75,128 +75,129 @@ openclaw update status --timeout 10
گزینه‌ها:
- `--json`: JSON وضعیت قابل‌خواندن برای ماشین را چاپ می‌کند.
- `--timeout <seconds>`: مهلت زمانی بررسی‌ها (پیش‌فرض 3s است).
- `--timeout <seconds>`: مهلت زمانی برای بررسی‌ها (پیش‌فرض 3s است).
## `update wizard`
جریان تعاملی برای انتخاب کانال به‌روزرسانی و تأیید اینکه آیا پس از به‌روزرسانی Gateway
راه‌اندازی مجدد شود یا نه (پیش‌فرض راه‌اندازی مجدد است). اگر بدون checkout از git گزینه `dev` را انتخاب کنید،
دوباره راه‌اندازی شود یا نه (پیش‌فرض راه‌اندازی دوباره است). اگر `dev` را بدون checkout git انتخاب کنید،
پیشنهاد می‌دهد یکی ایجاد کند.
گزینه‌ها:
- `--timeout <seconds>`: مهلت زمانی هر مرحله به‌روزرسانی (پیش‌فرض `1800`)
- `--timeout <seconds>`: مهلت زمانی برای هر مرحلهٔ به‌روزرسانی (پیش‌فرض `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 می‌کند.
### مراحل به‌روزرسانی
<Steps>
<Step title="بررسی پاک بودن worktree">
نیاز دارد هیچ تغییر commitنشده‌ای وجود نداشته باشد.
<Step title="بررسی worktree پاک">
نیازمند نبود تغییرات commitنشده است.
</Step>
<Step title="تغییر کانال">
به کانال انتخاب‌شده (برچسب یا شاخه) جابه‌جا می‌شود.
به کانال انتخاب‌شده (تگ یا شاخه) تغییر می‌کند.
</Step>
<Step title="واکشی upstream">
فقط برای dev.
<Step title="دریافت upstream">
فقط توسعه.
</Step>
<Step title="Build پیش‌پرواز (فقط dev)">
lint و build مربوط به TypeScript را در یک worktree موقت اجرا می‌کند. اگر tip شکست بخورد، تا 10 commit به عقب برمی‌گردد تا جدیدترین build پاک را پیدا کند.
<Step title="build پیش‌پرواز (فقط توسعه)">
lint و build TypeScript را در یک worktree موقت اجرا می‌کند. اگر نوک شاخه شکست بخورد، تا 10 commit به عقب برمی‌گردد تا جدیدترین build پاک را پیدا کند.
</Step>
<Step title="Rebase">
روی commit انتخاب‌شده rebase می‌کند (فقط dev).
روی commit انتخاب‌شده rebase می‌کند (فقط توسعه).
</Step>
<Step title="نصب وابستگی‌ها">
از مدیر بسته 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 اجرا کند.
</Step>
<Step title="Build کردن Control UI">
Gateway و Control UI را build می‌کند.
gateway و Control UI را build می‌کند.
</Step>
<Step title="اجرای doctor">
`openclaw doctor` به‌عنوان بررسی نهایی به‌روزرسانی ایمن اجرا می‌شود.
`openclaw doctor` به‌عنوان بررسی نهایی به‌روزرسانی امن اجرا می‌شود.
</Step>
<Step title="همگام‌سازی plugins">
plugins را با کانال فعال همگام می‌کند. dev از plugins همراه استفاده می‌کند؛ stable و beta از npm استفاده می‌کنند. نصب‌های Plugin ردیابی‌شده را به‌روزرسانی می‌کند.
<Step title="همگام‌سازی Pluginها">
Pluginها را با کانال فعال همگام می‌کند. توسعه از Pluginهای bundled استفاده می‌کند؛ پایدار و بتا از npm استفاده می‌کنند. نصب‌های Plugin ردیابی‌شده را به‌روزرسانی می‌کند.
</Step>
</Steps>
در کانال به‌روزرسانی 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 همچنین وقتی بستهٔ بتا وجود دارد اما بررسی نصب آن شکست می‌خورد
به عقب برمی‌گردد. نسخه‌های دقیق و تگ‌های صریح بازنویسی نمی‌شوند.
<Warning>
اگر به‌روزرسانی یک npm plugin دقیقاً pinشده به artifactای resolve شود که integrity آن با رکورد نصب ذخیره‌شده متفاوت است، `openclaw update` به‌جای نصب آن، به‌روزرسانی artifact مربوط به Plugin را abort می‌کند. فقط پس از بررسی اینکه به artifact جدید اعتماد دارید، Plugin را صراحتاً دوباره نصب یا به‌روزرسانی کنید.
اگر یک به‌روزرسانی دقیقاً pin‌شدهٔ npm Plugin به آرتیفکتی حل شود که یکپارچگی آن با رکورد نصب ذخیره‌شده فرق دارد، `openclaw update` به‌جای نصب آن، به‌روزرسانی آرتیفکت Plugin را متوقف می‌کند. فقط پس از اینکه بررسی کردید به آرتیفکت جدید اعتماد دارید، Plugin را دوباره نصب یا صریحاً به‌روزرسانی کنید.
</Warning>
<Note>
شکست‌های همگام‌سازی 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، زودتر با یک خطای ویژهٔ مدیر بسته متوقف می‌شود.
</Note>
## میان‌بر `--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)

193
docs/fa/concepts/models.md
View File

@ -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
---
<CardGroup cols={2}>
<Card title="جابه‌جایی اضطراری مدل" href="/fa/concepts/model-failover">
چرخش پروفایل احراز هویت، زمان‌های سردسازی، و نحوه تعامل آن با جایگزین‌ها.
<Card title="جایگزینی مدل هنگام خرابی" href="/fa/concepts/model-failover">
چرخش پروفایل احراز هویت، دوره‌های انتظار، و نحوه تعامل آن با مدل‌های جایگزین.
</Card>
<Card title="ارائه‌دهندگان مدل" href="/fa/concepts/model-providers">
مرور سریع ارائه‌دهنده و مثال‌ها.
مرور سریع ارائه‌دهنده‌ها و مثال‌ها.
</Card>
<Card title="زمان‌اجراهای عامل" href="/fa/concepts/agent-runtimes">
PI، Codex، و زمان‌اجراهای دیگر حلقه عامل.
PI، Codex، و دیگر زمان‌اجراهای حلقه عامل.
</Card>
<Card title="مرجع پیکربندی" href="/fa/gateway/config-agents#agent-defaults">
کلیدهای پیکربندی مدل.
</Card>
</CardGroup>
ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولا زمان‌اجرای سطح‌پایین عامل را انتخاب نمی‌کنند. برای مثال، `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 مدل‌ها را به این ترتیب انتخاب می‌کند:
<Step title="مدل اصلی">
`agents.defaults.model.primary` (یا `agents.defaults.model`).
</Step>
<Step title="جایگزین‌ها">
<Step title="مدل‌های جایگزین">
`agents.defaults.model.fallbacks` (به‌ترتیب).
</Step>
<Step title="جابه‌جایی اضطراری احراز هویت ارائه‌دهنده">
جابه‌جایی اضطراری احراز هویت، پیش از رفتن به مدل بعدی، داخل یک ارائه‌دهنده رخ می‌دهد.
<Step title="جایگزینی احراز هویت ارائه‌دهنده هنگام خرابی">
جایگزینی احراز هویت هنگام خرابی، پیش از رفتن به مدل بعدی، داخل یک ارائه‌دهنده انجام می‌شود.
</Step>
</Steps>
<AccordionGroup>
<Accordion title="سطح‌های مرتبط با مدل">
- `agents.defaults.models` فهرست مجاز/کاتالوگ مدل‌هایی است که OpenClaw می‌تواند استفاده کند (به‌علاوه نام‌های مستعار).
<Accordion title="سطوح مرتبط با مدل">
- `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) را ببینید).
</Accordion>
</AccordionGroup>
## منبع انتخاب و رفتار جایگزین
## منبع انتخاب و رفتار جایگزینی
همان `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`)
<Note>
ارجاع‌های مدل به حروف کوچک نرمال می‌شوند. نام‌های مستعار ارائه‌دهنده مانند `z.ai/*` به `zai/*` نرمال می‌شوند.
ارجاع‌های مدل به حروف کوچک نرمال‌سازی می‌شوند. aliasهای ارائه‌دهنده مانند `z.ai/*` به `zai/*` نرمال‌سازی می‌شوند.
نمونه‌های پیکربندی ارائه‌دهنده (از جمله OpenCode) در [OpenCode](/fa/providers/opencode) قرار دارند.
</Note>
@ -113,8 +113,8 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
```
<AccordionGroup>
<Accordion title="قواعد محافظت در برابر بازنویسی">
`openclaw config set` از نگاشت‌های مدل/ارائه‌دهنده در برابر بازنویسی‌های تصادفی محافظت می‌کند. انتساب یک شیء ساده به `agents.defaults.models`، `models.providers`، یا `models.providers.<id>.models` وقتی باعث حذف ورودی‌های موجود شود رد می‌شود. برای تغییرات افزایشی از `--merge` استفاده کنید؛ فقط وقتی مقدار ارائه‌شده باید به مقدار کامل هدف تبدیل شود از `--replace` استفاده کنید.
<Accordion title="قواعد محافظت در برابر بازنویسی ناخواسته">
`openclaw config set` از mapهای مدل/ارائه‌دهنده در برابر بازنویسی ناخواسته محافظت می‌کند. انتساب یک شیء ساده به `agents.defaults.models`، `models.providers`، یا `models.providers.<id>.models` وقتی که باعث حذف ورودی‌های موجود شود رد می‌شود. برای تغییرات افزایشی از `--merge` استفاده کنید؛ فقط وقتی از `--replace` استفاده کنید که مقدار ارائه‌شده باید مقدار کامل مقصد شود.
راه‌اندازی تعاملی ارائه‌دهنده و `openclaw configure --section model` نیز انتخاب‌های محدود به ارائه‌دهنده را با فهرست مجاز موجود ادغام می‌کنند، بنابراین افزودن Codex، Ollama، یا ارائه‌دهنده‌ای دیگر ورودی‌های مدل نامرتبط را حذف نمی‌کند. Configure هنگام اعمال دوباره احراز هویت ارائه‌دهنده، `agents.defaults.model.primary` موجود را حفظ می‌کند. فرمان‌های صریح تنظیم پیش‌فرض مانند `openclaw models auth login --provider <id> --set-default` و `openclaw models set <model>` همچنان `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 <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
این اتفاق **پیش از** تولید یک پاسخ عادی رخ می‌دهد، بنابراین پیام ممکن است این حس را بدهد که «پاسخ نداد». راه‌حل این است که یکی از این کارها را انجام دهید:
این اتفاق **پیش از** تولید پاسخ عادی رخ می‌دهد، بنابراین پیام می‌تواند این حس را بدهد که «پاسخ نداد». راه‌حل یکی از این موارد است:
- مدل را به `agents.defaults.models` اضافه کنید، یا
- فهرست مجاز را پاک کنید (`agents.defaults.models` را حذف کنید)، یا
@ -138,10 +139,12 @@ Model "provider/model" is not allowed. Use /model to list available models.
</Warning>
وقتی فرمان ردشده شامل یک بازنویسی زمان‌اجرا مانند `/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 <provider>` نشان داده می‌شود.
نام فایل‌های محلی بدون پیشوند یا نام‌های نمایشی وقتی فهرست مجاز
ارائه‌دهنده/مدل دقیقی که توسط `openclaw models list --provider <provider>` نمایش داده می‌شود.
نام فایل‌های محلی خام یا نام‌های نمایشی وقتی فهرست مجاز
فعال است کافی نیستند.
نمونه پیکربندی فهرست مجاز:
@ -172,33 +175,33 @@ Model "provider/model" is not allowed. Use /model to list available models.
<AccordionGroup>
<Accordion title="رفتار انتخابگر">
- `/model` (و `/model list`) یک انتخابگر فشرده و شماره‌دار است (خانواده مدل + ارائه‌دهندگان موجود).
- در Discord، `/model` و `/models` یک انتخابگر تعاملی با کشویی‌های ارائه‌دهنده و مدل به‌همراه گام Submit باز می‌کنند.
- `/model` (و `/model list`) یک انتخابگر فشرده و شماره‌گذاری‌شده است (خانواده مدل + ارائه‌دهندگان موجود).
- در Discord، `/model` و `/models` یک انتخابگر تعاملی با dropdownهای ارائه‌دهنده و مدل به‌همراه گام Submit باز می‌کنند.
- در Telegram، انتخاب‌های انتخابگر `/models` محدود به نشست هستند؛ آن‌ها پیش‌فرض پایدار عامل را در `openclaw.json` تغییر نمی‌دهند.
- `/models add` منسوخ شده است و اکنون به‌جای ثبت مدل‌ها از گفت‌وگو، پیام منسوخ‌شدن برمی‌گرداند.
- `/model <#>` از همان انتخابگر انتخاب می‌کند.
</Accordion>
<Accordion title="ماندگاری و تغییر زنده">
- `/model` انتخاب جدید نشست را بلافاصله پایدار می‌کند.
- اگر عامل بیکار باشد، اجرای بعدی فورا از مدل جدید استفاده می‌کند.
- اگر اجرایی از قبل فعال باشد، OpenClaw تغییر زنده را به‌عنوان در انتظار علامت‌گذاری می‌کند و فقط در یک نقطه تلاش مجدد تمیز با مدل جدید دوباره شروع می‌کند.
- اگر فعالیت ابزار یا خروجی پاسخ از قبل شروع شده باشد، تغییر در انتظار می‌تواند تا فرصت تلاش مجدد بعدی یا نوبت بعدی کاربر در صف بماند.
- ارجاع `/model` انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر ارائه‌دهنده/مدل انتخاب‌شده دسترس‌ناپذیر باشد، پاسخ به‌جای پاسخ‌دادن بی‌سروصدا از `agents.defaults.model.fallbacks`، آشکارا شکست می‌خورد. این با پیش‌فرض‌های پیکربندی‌شده و مدل‌های اصلی کار cron متفاوت است؛ آن‌ها همچنان می‌توانند از زنجیره‌های جایگزین استفاده کنند.
- `/model status` نمای جزئیات است (گزینه‌های احراز هویت و، وقتی پیکربندی شده باشد، نقطه پایانی ارائه‌دهنده `baseUrl` + حالت `api`).
<Accordion title="پایداری و تغییر زنده">
- `/model` انتخاب نشست جدید را فوراً پایدار می‌کند.
- اگر عامل بیکار باشد، اجرای بعدی بلافاصله از مدل جدید استفاده می‌کند.
- اگر یک اجرا از قبل فعال باشد، OpenClaw تغییر زنده را در حالت در انتظار علامت‌گذاری می‌کند و فقط در یک نقطه تلاش مجدد تمیز به مدل جدید راه‌اندازی دوباره می‌شود.
- اگر فعالیت ابزار یا خروجی پاسخ از قبل شروع شده باشد، تغییر در انتظار می‌تواند تا یک فرصت تلاش مجدد بعدی یا نوبت بعدی کاربر در صف بماند.
- ارجاع `/model` انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، پاسخ به‌جای پاسخ دادن بی‌صدا از `agents.defaults.model.fallbacks` به‌صورت آشکار شکست می‌خورد. این با پیش‌فرض‌های پیکربندی‌شده و مدل‌های اصلی کار cron متفاوت است، که همچنان می‌توانند از زنجیره‌های جایگزین استفاده کنند.
- `/model status` نمای جزئیات است (نامزدهای احراز هویت و، در صورت پیکربندی، endpoint ارائه‌دهنده `baseUrl` + حالت `api`).
</Accordion>
<Accordion title="تجزیه ارجاع">
- ارجاع‌های مدل با جداکردن روی **اولین** `/` تجزیه می‌شوند. هنگام تایپ `/model <ref>` از `provider/model` استفاده کنید.
- ارجاع‌های مدل با تقسیم روی **اولین** `/` تجزیه می‌شوند. هنگام تایپ `/model <ref>` از `provider/model` استفاده کنید.
- اگر خود شناسه مدل شامل `/` باشد (سبک OpenRouter)، باید پیشوند ارائه‌دهنده را وارد کنید (مثال: `/model openrouter/moonshotai/kimi-k2`).
- اگر ارائه‌دهنده را حذف کنید، OpenClaw ورودی را به این ترتیب حل می‌کند:
1. تطبیق نام مستعار
2. تطبیق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه مدل بدون پیشوند دقیق
3. بازگشت منسوخ به ارائه‌دهنده پیش‌فرض پیکربندی‌شده — اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را عرضه نکند، OpenClaw برای جلوگیری از نمایش پیش‌فرض کهنه مربوط به ارائه‌دهنده حذف‌شده، در عوض به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد.
1. تطابق alias
2. تطابق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه مدل بدون پیشوند دقیق
3. بازگشت منسوخ‌شده به ارائه‌دهنده پیش‌فرض پیکربندی‌شده — اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش پیش‌فرض کهنه ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده برمی‌گردد.
</Accordion>
</AccordionGroup>
رفتار/پیکربندی کامل فرمان: [فرمان‌های اسلش](/fa/tools/slash-commands).
رفتار/پیکربندی کامل فرمان: [فرمان‌های Slash](/fa/tools/slash-commands).
## فرمان‌های CLI
@ -227,41 +230,41 @@ openclaw models image-fallbacks clear
### `models list`
به‌طور پیش‌فرض مدل‌های پیکربندی‌شده/دارای احراز هویت در دسترس را نشان می‌دهد. پرچم‌های مفید:
مدل‌های پیکربندی‌شده/دارای احراز هویت موجود را به‌صورت پیش‌فرض نشان می‌دهد. پرچم‌های مفید:
<ParamField path="--all" type="boolean">
کاتالوگ کامل. شامل ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهنده‌های همراه، پیش از پیکربندی احراز هویت است؛ بنابراین نماهای فقط-کشف می‌توانند مدل‌هایی را نشان دهند که تا زمانی که اعتبارنامه‌های مطابق ارائه‌دهنده را اضافه نکنید در دسترس نیستند.
کاتالوگ کامل. ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهنده‌های همراه را پیش از پیکربندی احراز هویت شامل می‌شود، بنابراین نماهای صرفاً اکتشافی می‌توانند مدل‌هایی را نشان دهند که تا وقتی اعتبارنامه‌های ارائه‌دهنده متناظر را اضافه نکنید در دسترس نیستند.
</ParamField>
<ParamField path="--local" type="boolean">
فقط ارائه‌دهنده‌های محلی.
</ParamField>
<ParamField path="--provider <id>" type="string">
فیلتر بر اساس شناسهٔ ارائه‌دهنده، برای مثال `moonshot`. برچسب‌های نمایشی از انتخاب‌گرهای تعاملی پذیرفته نمی‌شوند.
فیلتر بر اساس شناسه ارائه‌دهنده، برای مثال `moonshot`. برچسب‌های نمایشی از انتخاب‌گرهای تعاملی پذیرفته نمی‌شوند.
</ParamField>
<ParamField path="--plain" type="boolean">
هر خط یک مدل.
هر مدل در یک خط.
</ParamField>
<ParamField path="--json" type="boolean">
خروجی قابل خواندن برای ماشین.
خروجی قابل خواندن توسط ماشین.
</ParamField>
### `models status`
مدل اصلی حل‌شده، جایگزین‌ها، مدل تصویر و نمای کلی احراز هویت ارائه‌دهنده‌های پیکربندی‌شده را نشان می‌دهد. همچنین وضعیت انقضای OAuth را برای پروفایل‌های یافت‌شده در ذخیره‌گاه احراز هویت نمایش می‌دهد (به‌طور پیش‌فرض در بازهٔ ۲۴ ساعت هشدار می‌دهد). `--plain` فقط مدل اصلی حل‌شده را چاپ می‌کند.
مدل اصلی حل‌شده، جایگزین‌ها، مدل تصویر، و نمای کلی احراز هویت ارائه‌دهنده‌های پیکربندی‌شده را نشان می‌دهد. همچنین وضعیت انقضای OAuth را برای پروفایل‌های موجود در ذخیره‌گاه احراز هویت نمایش می‌دهد (به‌صورت پیش‌فرض در بازه ۲۴ ساعت هشدار می‌دهد). `--plain` فقط مدل اصلی حل‌شده را چاپ می‌کند.
<AccordionGroup>
<Accordion title="رفتار احراز هویت و پروب">
- وضعیت OAuth همیشه نشان داده می‌شود (و در خروجی `--json` هم گنجانده می‌شود). اگر ارائه‌دهندهٔ پیکربندی‌شده اعتبارنامه نداشته باشد، `models status` بخشی با عنوان **احراز هویت موجود نیست** چاپ می‌کند.
- JSON شامل `auth.oauth` (بازهٔ هشدار + پروفایل‌ها) و `auth.providers` (احراز هویت مؤثر برای هر ارائه‌دهنده، شامل اعتبارنامه‌های مبتنی بر env) است. `auth.oauth` فقط سلامت پروفایل‌های ذخیره‌گاه احراز هویت است؛ ارائه‌دهنده‌های فقط-env در آن ظاهر نمی‌شوند.
- برای خودکارسازی از `--check` استفاده کنید (در صورت نبود یا انقضا، خروج با `1`؛ در صورت نزدیک بودن انقضا، خروج با `2`).
- برای بررسی‌های زندهٔ احراز هویت از `--probe` استفاده کنید؛ ردیف‌های پروب می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env، یا `models.json` بیایند.
- اگر `auth.order.<provider>` صریح یک پروفایل ذخیره‌شده را حذف کند، پروب به‌جای تلاش برای استفاده از آن، `excluded_by_auth_order` گزارش می‌کند. اگر احراز هویت وجود داشته باشد اما هیچ مدل قابل پروبی برای آن ارائه‌دهنده حل نشود، پروب `status: no_model` گزارش می‌کند.
<Accordion title="رفتار احراز هویت و آزمون">
- وضعیت OAuth همیشه نشان داده می‌شود (و در خروجی `--json` هم گنجانده می‌شود). اگر یک ارائه‌دهنده پیکربندی‌شده اعتبارنامه نداشته باشد، `models status` یک بخش **احراز هویت مفقود** چاپ می‌کند.
- JSON شامل `auth.oauth` (پنجره هشدار + پروفایل‌ها) و `auth.providers` (احراز هویت مؤثر برای هر ارائه‌دهنده، از جمله اعتبارنامه‌های مبتنی بر env) است. `auth.oauth` فقط سلامت پروفایل‌های ذخیره‌گاه احراز هویت است؛ ارائه‌دهنده‌های فقط env در آن ظاهر نمی‌شوند.
- برای خودکارسازی از `--check` استفاده کنید (کد خروج `1` هنگام فقدان/انقضا، `2` هنگام نزدیک بودن انقضا).
- برای بررسی‌های زنده احراز هویت از `--probe` استفاده کنید؛ ردیف‌های آزمون می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env، یا `models.json` بیایند.
- اگر `auth.order.<provider>` صریح یک پروفایل ذخیره‌شده را حذف کند، آزمون به‌جای تلاش برای آن، `excluded_by_auth_order` گزارش می‌دهد. اگر احراز هویت وجود داشته باشد اما هیچ مدل قابل آزمونی برای آن ارائه‌دهنده قابل حل نباشد، آزمون `status: no_model` گزارش می‌دهد.
</Accordion>
</AccordionGroup>
<Note>
انتخاب احراز هویت به ارائه‌دهنده/حساب وابسته است. برای میزبان‌های Gateway همیشه‌روشن، کلیدهای API معمولاً قابل پیش‌بینی‌ترین گزینه هستند؛ استفادهٔ دوباره از Claude CLI و پروفایل‌های OAuth/توکن موجود Anthropic نیز پشتیبانی می‌شود.
انتخاب احراز هویت به ارائه‌دهنده/حساب وابسته است. برای میزبان‌های Gateway همیشه‌روشن، کلیدهای API معمولاً قابل پیش‌بینی‌ترین گزینه‌اند؛ استفاده مجدد از Claude CLI و پروفایل‌های موجود OAuth/توکن Anthropic نیز پشتیبانی می‌شوند.
</Note>
مثال (Claude CLI):
@ -273,78 +276,78 @@ openclaw models status
## اسکن (مدل‌های رایگان OpenRouter)
`openclaw models scan` **کاتالوگ مدل‌های رایگان** OpenRouter را بررسی می‌کند و می‌تواند به‌صورت اختیاری مدل‌ها را برای پشتیبانی از ابزار و تصویر پروب کند.
`openclaw models scan` **کاتالوگ مدل رایگان** OpenRouter را بررسی می‌کند و می‌تواند به‌صورت اختیاری مدل‌ها را برای پشتیبانی از ابزار و تصویر بیازماید.
<ParamField path="--no-probe" type="boolean">
پروب‌های زنده را رد کنید (فقط فراداده).
آزمون‌های زنده را رد کن (فقط فراداده).
</ParamField>
<ParamField path="--min-params <b>" type="number">
حداقل اندازهٔ پارامتر (میلیارد).
حداقل اندازه پارامتر (میلیارد).
</ParamField>
<ParamField path="--max-age-days <days>" type="number">
مدل‌های قدیمی‌تر را رد کنید.
مدل‌های قدیمی‌تر را رد کن.
</ParamField>
<ParamField path="--provider <name>" type="string">
فیلتر پیشوند ارائه‌دهنده.
</ParamField>
<ParamField path="--max-candidates <n>" type="number">
اندازهٔ فهرست جایگزین‌ها.
اندازه فهرست جایگزین‌ها.
</ParamField>
<ParamField path="--set-default" type="boolean">
`agents.defaults.model.primary` را روی اولین انتخاب تنظیم کنید.
`agents.defaults.model.primary` را روی نخستین انتخاب تنظیم کن.
</ParamField>
<ParamField path="--set-image" type="boolean">
`agents.defaults.imageModel.primary` را روی اولین انتخاب تصویر تنظیم کنید.
`agents.defaults.imageModel.primary` را روی نخستین انتخاب تصویر تنظیم کن.
</ParamField>
<Note>
کاتالوگ `/models` در OpenRouter عمومی است، بنابراین اسکن‌های فقط-فراداده می‌توانند نامزدهای رایگان را بدون کلید فهرست کنند. پروب و استنتاج همچنان به یک کلید API برای OpenRouter نیاز دارند (از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY`). اگر کلیدی در دسترس نباشد، `openclaw models scan` به خروجی فقط-فراداده برمی‌گردد و پیکربندی را بدون تغییر می‌گذارد. برای درخواست صریح حالت فقط-فراداده از `--no-probe` استفاده کنید.
کاتالوگ `/models` در OpenRouter عمومی است، بنابراین اسکن‌های فقط فراداده می‌توانند گزینه‌های رایگان را بدون کلید فهرست کنند. آزمون و استنتاج همچنان به کلید API OpenRouter نیاز دارند (از پروفایل‌های احراز هویت یا `OPENROUTER_API_KEY`). اگر کلیدی در دسترس نباشد، `openclaw models scan` به خروجی فقط فراداده برمی‌گردد و پیکربندی را بدون تغییر می‌گذارد. برای درخواست صریح حالت فقط فراداده از `--no-probe` استفاده کنید.
</Note>
نتایج اسکن بر اساس این موارد رتبه‌بندی می‌شوند:
نتایج اسکن بر اساس موارد زیر رتبه‌بندی می‌شوند:
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/<agentId>/agent/models.json`). این فایل به‌طور پیش‌فرض ادغام می‌شود، مگر اینکه `models.mode` روی `replace` تنظیم شده باشد.
ارائه‌دهنده‌های سفارشی در `models.providers` در `models.json` زیر دایرکتوری عامل نوشته می‌شوند (پیش‌فرض `~/.openclaw/agents/<agentId>/agent/models.json`). این فایل به‌صورت پیش‌فرض ادغام می‌شود، مگر اینکه `models.mode` روی `replace` تنظیم شده باشد.
<AccordionGroup>
<Accordion title="اولویت حالت ادغام">
اولویت حالت ادغام برای شناسه‌های ارائه‌دهندهٔ مطابق:
<Accordion title="تقدم حالت ادغام">
تقدم حالت ادغام برای شناسه‌های ارائه‌دهنده مطابق:
- `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` در پیکربندی برمی‌گردد.
- فیلدهای دیگر ارائه‌دهنده از پیکربندی و داده‌های کاتالوگ نرمال‌شده تازه‌سازی می‌شوند.
</Accordion>
</AccordionGroup>
<Note>
پایداری نشانگرها مبتنی بر منبع مرجع است: OpenClaw نشانگرها را از snapshot پیکربندی منبع فعال (پیش از حل‌کردن) می‌نویسد، نه از مقدارهای راز حل‌شده در زمان اجرا. این رفتار هر زمان که OpenClaw دوباره `models.json` را تولید کند اعمال می‌شود، از جمله مسیرهای فرمان‌محور مانند `openclaw agent`.
ماندگاری نشانگر مبتنی بر منبع معتبر است: OpenClaw نشانگرها را از اسنپ‌شات پیکربندی منبع فعال (پیش از حل‌شدن)، نه از مقدارهای راز حل‌شده زمان اجرا، می‌نویسد. این موضوع هر زمان که OpenClaw، `models.json` را دوباره تولید کند اعمال می‌شود، از جمله مسیرهای مبتنی بر فرمان مثل `openclaw agent`.
</Note>
## مرتبط
- [زمان‌های اجرای عامل](/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) — پیکربندی مدل ویدئو

613
docs/fa/concepts/qa-e2e-automation.md
View File

@ -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 <subcommand>` اجرا می‌شود. بسیاری از آن‌ها نام‌های مستعار اسکریپتی `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-<timestamp>/` می‌نویسد.
مرجع کامل 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-<timestamp>/` می‌نویسد.
برای مسیرهای 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 <cbx_...>` را دوباره استفاده کنید. با `--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 <cbx_...>` دوباره استفاده کنید.
با `--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 <count>` برای تنظیم
تعداد workerها، یا از `--concurrency 1` برای اجرای سریالی استفاده کنید.
این فرمان یک مهمان تازه‌ی Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را
داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش و
خلاصه‌ی معمول QA را به `.artifacts/qa-e2e/...` روی میزبان کپی می‌کند.
این فرمان همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد دوباره استفاده می‌کند.
اجرای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی
با کارگرهای Gateway ایزوله اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض هم‌زمانی
4 دارد، که با تعداد سناریوهای انتخاب‌شده محدود می‌شود. برای تنظیم تعداد
کارگرها از `--concurrency <count>` استفاده کنید، یا برای اجرای ترتیبی از `--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 <id>` | — | فقط این سناریو را اجرا می‌کند. قابل تکرار است. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | محل نوشتن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. |
| `--repo-root <path>` | `process.cwd()` | ریشه repository هنگام فراخوانی از یک cwd خنثی. |
| `--sut-account <id>` | `sut` | id حساب موقت داخل پیکربندی Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` یا `live-frontier`؛ مقدار قدیمی `live-openai` همچنان کار می‌کند. |
| `--model <ref>` / `--alt-model <ref>` | پیش‌فرض provider | refهای model اصلی/جایگزین. |
| `--fast` | خاموش | حالت سریع provider در جاهایی که پشتیبانی می‌شود. |
| `--credential-source <env\|convex>` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. |
| `--credential-role <maintainer\|ci>` | `ci` در CI، در غیر این صورت `maintainer` | نقشی که هنگام `--credential-source convex` استفاده می‌شود. |
| پرچم | پیش‌فرض | توضیح |
| ------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | فقط همین سناریو را اجرا می‌کند. قابل تکرار است. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | جایی که گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی نوشته می‌شوند. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. |
| `--repo-root <path>` | `process.cwd()` | ریشه‌ی مخزن هنگام فراخوانی از یک cwd خنثی. |
| `--sut-account <id>` | `sut` | شناسه‌ی حساب موقت داخل پیکربندی Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` یا `live-frontier` (`live-openai` قدیمی همچنان کار می‌کند). |
| `--model <ref>` / `--alt-model <ref>` | پیش‌فرض ارائه‌دهنده | ارجاع‌های مدل اصلی/جایگزین. |
| `--fast` | خاموش | حالت سریع ارائه‌دهنده، در صورت پشتیبانی. |
| `--credential-source <env\|convex>` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. |
| `--credential-role <maintainer\|ci>` | در 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/<theme>/*.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 <runner>` چگونه زیر ریشه مشترک `qa` mount می‌شود
- اینکه Gateway برای آن انتقال چگونه پیکربندی می‌شود
- اینکه آمادگی چگونه بررسی می‌شود
- اینکه رویدادهای ورودی چگونه تزریق می‌شوند
- اینکه پیام‌های خروجی چگونه مشاهده می‌شوند
- اینکه transcriptها و وضعیت نرمال‌سازی‌شده انتقال چگونه عرضه می‌شوند
- اینکه اقدام‌های پشتوانه‌دار با انتقال چگونه اجرا می‌شوند
- اینکه بازنشانی یا پاک‌سازی ویژه انتقال چگونه انجام می‌شود
- اینکه `openclaw qa <runner>` چگونه زیر 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 <runner>` 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 <runner>` 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=<level>` override کنید. `--thinking <level>` همچنان یک
fallback سراسری تنظیم می‌کند، و فرم قدیمی‌تر `--model-thinking <provider/model=level>` برای
سازگاری نگه داشته شده است.
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=<level>` استفاده کنید. `--thinking <level>` همچنان یک fallback سراسری تنظیم می‌کند، و شکل قدیمی‌تر `--model-thinking <provider/model=level>` برای سازگاری حفظ شده است.
ارجاع‌های نامزد 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)

234
docs/fa/gateway/config-tools.md
View File

@ -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` تنظیم می‌کند:
<Note>
فرایند راه‌اندازی محلی، پیکربندی‌های محلی جدید را وقتی تنظیم نشده باشند به‌طور پیش‌فرض روی `tools.profile: "coding"` قرار می‌دهد (پروفایل‌های صریح موجود حفظ می‌شوند).
راه‌اندازی محلی، پیکربندی‌های محلی جدید را وقتی تنظیم نشده باشند به‌صورت پیش‌فرض روی `tools.profile: "coding"` قرار می‌دهد (پروفایل‌های صریح موجود حفظ می‌شوند).
</Note>
| پروفایل | شامل |
@ -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:
```
<ParamField path="historySize" type="number">
بیشینهٔ تاریخچهٔ فراخوانی ابزار که برای تحلیل حلقه نگه داشته می‌شود.
حداکثر تاریخچه فراخوانی ابزار که برای تحلیل حلقه نگه داشته می‌شود.
</ParamField>
<ParamField path="warningThreshold" type="number">
آستانهٔ الگوی تکراری بدون پیشرفت برای هشدارها.
آستانه الگوی تکراری بدون پیشرفت برای هشدارها.
</ParamField>
<ParamField path="criticalThreshold" type="number">
آستانهٔ تکرار بالاتر برای مسدود کردن حلقه‌های بحرانی.
آستانه تکرار بالاتر برای مسدود کردن حلقه‌های بحرانی.
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
آستانهٔ توقف قطعی برای هر اجرای بدون پیشرفت.
آستانه توقف قطعی برای هر اجرای بدون پیشرفت.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
هنگام فراخوانی‌های تکراری با همان ابزار/همان آرگومان‌ها هشدار بده.
هنگام تکرار فراخوانی‌های ابزار یکسان/آرگومان‌های یکسان هشدار می‌دهد.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
روی ابزارهای پیمایش شناخته‌شده (`process.poll`، `command_status`، و غیره) هشدار بده/مسدود کن.
در ابزارهای polling شناخته‌شده (`process.poll`, `command_status` و غیره) هشدار می‌دهد/مسدود می‌کند.
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
روی الگوهای جفتی متناوب بدون پیشرفت هشدار بده/مسدود کن.
در الگوهای جفتی متناوب بدون پیشرفت هشدار می‌دهد/مسدود می‌کند.
</ParamField>
<Warning>
اگر `warningThreshold >= criticalThreshold` یا `criticalThreshold >= globalCircuitBreakerThreshold` باشد، اعتبارسنجی ناموفق می‌شود.
اگر `warningThreshold >= criticalThreshold` یا `criticalThreshold >= globalCircuitBreakerThreshold` باشد، اعتبارسنجی شکست می‌خورد.
</Warning>
### `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:
<Accordion title="Media model entry fields">
**ورودی ارائه‌دهنده** (`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`: پرچم سازگاری منسوخ. وظایف رسانه‌ای ناهمگام تکمیل‌شده با واسطهٔ نشست درخواست‌کننده باقی می‌مانند تا عامل نتیجه را دریافت کند، تصمیم بگیرد چگونه به کاربر اطلاع دهد، و وقتی تحویل از مبدأ به آن نیاز دارد از ابزار پیام استفاده کند.
</Accordion>
</AccordionGroup>
@ -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:
<Accordion title="Visibility scopes">
- `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` می‌شود.
</Accordion>
</AccordionGroup>
### `tools.sessions_spawn`
پشتیبانی از پیوست درون‌خطی برای `sessions_spawn` را کنترل می‌کند.
پشتیبانی از پیوست درون‌خطی را برای `sessions_spawn` کنترل می‌کند.
```json5
{
@ -336,12 +336,12 @@ x-i18n:
```
<AccordionGroup>
<Accordion title="Attachment notes">
<Accordion title="یادداشت‌های پیوست">
- پیوست‌ها فقط برای `runtime: "subagent"` پشتیبانی می‌شوند. runtime مربوط به ACP آن‌ها را رد می‌کند.
- فایل‌ها در workspace فرزند در مسیر `.openclaw/attachments/<uuid>/` همراه با یک `.manifest.json` ساخته می‌شوند.
- محتوای پیوست به‌طور خودکار از پایداری transcript حذف محرمانه می‌شود.
- ورودی‌های Base64 با بررسی‌های سخت‌گیرانه حروف مجاز/پدینگ و یک محافظ اندازه پیش از decode اعتبارسنجی می‌شوند.
- مجوزهای فایل برای پوشه‌ها `0700` و برای فایل‌ها `0600` است.
- فایل‌ها در workspace فرزند در مسیر `.openclaw/attachments/<uuid>/` همراه با یک `.manifest.json` materialize می‌شوند.
- محتوای پیوست به‌طور خودکار از پایداری transcript حذف/پوشانده می‌شود.
- ورودی‌های Base64 با بررسی‌های سخت‌گیرانه alphabet/padding و یک محافظ اندازه پیش از decode اعتبارسنجی می‌شوند.
- مجوزهای فایل برای دایرکتوری‌ها `0700` و برای فایل‌ها `0600` است.
- پاک‌سازی از سیاست `cleanup` پیروی می‌کند: `delete` همیشه پیوست‌ها را حذف می‌کند؛ `keep` فقط وقتی `retainOnSessionKeep: true` باشد آن‌ها را نگه می‌دارد.
</Accordion>
@ -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 از کاتالوگ مدل داخلی استفاده می‌کند. ا
```
<AccordionGroup>
<Accordion title="Auth and merge precedence">
- برای نیازهای 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.
<Accordion title="اولویت احراز هویت و ادغام">
- برای نیازهای احراز هویت سفارشی از `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.
</Accordion>
</AccordionGroup>
### جزئیات فیلدهای provider
### جزئیات فیلدهای ارائه‌دهنده
<AccordionGroup>
<Accordion title="Top-level catalog">
- `models.mode`: رفتار کاتالوگ provider (`merge` یا `replace`).
- `models.providers`: نگاشت provider سفارشی که با شناسه provider کلیدگذاری شده است.
- ویرایش‌های ایمن: برای به‌روزرسانی‌های افزایشی از `openclaw config set models.providers.<id> '<json>' --strict-json --merge` یا `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌های مخرب را رد می‌کند، مگر اینکه `--replace` را ارسال کنید.
<Accordion title="کاتالوگ سطح بالا">
- `models.mode`: رفتار کاتالوگ ارائه‌دهنده (`merge` یا `replace`).
- `models.providers`: map ارائه‌دهنده سفارشی با کلید شناسه ارائه‌دهنده.
- ویرایش‌های امن: برای به‌روزرسانی‌های افزایشی از `openclaw config set models.providers.<id> '<json>' --strict-json --merge` یا `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌های مخرب را رد می‌کند مگر اینکه `--replace` را پاس بدهید.
</Accordion>
<Accordion title="Provider connection and auth">
- `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` را هنگام نیاز اجباری می‌کند.
<Accordion title="اتصال و احراز هویت ارائه‌دهنده">
- `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.
</Accordion>
<Accordion title="Request transport overrides">
`models.providers.*.request`: بازنویسی‌های transport برای درخواست‌های HTTP ارائه‌دهنده مدل.
<Accordion title="Overrideهای انتقال درخواست">
`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`.
</Accordion>
<Accordion title="Model catalog entries">
- `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 می‌کند.
<Accordion title="ورودی‌های کاتالوگ مدل">
- `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 می‌کند.
</Accordion>
<Accordion title="Amazon Bedrock discovery">
<Accordion title="کشف Amazon Bedrock">
- `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 برای مدل‌های کشف‌شده.
</Accordion>
</AccordionGroup>
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
### نمونه‌های ارائه‌دهنده
<AccordionGroup>
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
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 استفاده کنید.
</Accordion>
<Accordion title="Kimi Coding">
@ -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`.
</Accordion>
<Accordion title="Local models (LM Studio)">
[مدل‌های محلی](/fa/gateway/local-models) را ببینید. خلاصه: یک مدل محلی بزرگ را از طریق LM Studio Responses API روی سخت‌افزار جدی اجرا کنید؛ مدل‌های میزبانی‌شده را برای پشتیبان ادغام‌شده نگه دارید.
[مدل‌های محلی](/fa/gateway/local-models) را ببینید. خلاصه: یک مدل محلی بزرگ را از طریق LM Studio Responses API روی سخت‌افزار جدی اجرا کنید؛ مدل‌های میزبانی‌شده را برای fallback ادغام‌شده نگه دارید.
</Accordion>
<Accordion title="MiniMax M2.7 (direct)">
```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` بازنویسی می‌کند.
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -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 تعیین می‌کند، نه فقط بر اساس شناسه ارائه‌دهنده داخلی.
</Accordion>
<Accordion title="OpenCode">
@ -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`.
</Accordion>
<Accordion title="Synthetic (Anthropic-compatible)">
@ -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`.
</Accordion>
<Accordion title="Z.AI (GLM-4.7)">
@ -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 پایه تعریف کنید.
</Accordion>
</AccordionGroup>
@ -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)

713
docs/fa/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

156
docs/fa/gateway/diagnostics.md
View File

@ -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 <thread-id>` را به‌صورت محلی اجرا کنید. برای آن گردش‌کار بررسی، [harness Codex](/fa/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) را ببینید.
این کار حلقه رایج عیب‌یابی Codex را کوتاه می‌کند: رفتار بد را در Telegram،
Discord، یا کانالی دیگر مشاهده کنید، `/diagnostics` را اجرا کنید، یک بار تأیید
کنید، گزارش را با پشتیبانی به اشتراک بگذارید، سپس اگر می‌خواهید خودتان رشته
بومی Codex را بررسی کنید، فرمان چاپ‌شده `codex resume <thread-id>` را به‌صورت
محلی اجرا کنید. برای این گردش‌کار بررسی، [سازوکار 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 <path>`: نوشتن در یک مسیر zip مشخص.
- `--log-lines <count>`: بیشینه خطوط لاگ پاک‌سازی‌شده برای درج.
- `--log-bytes <bytes>`: بیشینه بایت‌های لاگ برای بررسی.
- `--url <url>`: URL WebSocket مربوط به Gateway برای snapshotهای وضعیت و سلامت.
- `--token <token>`: token مربوط به Gateway برای snapshotهای وضعیت و سلامت.
- `--password <password>`: گذرواژه Gateway برای snapshotهای وضعیت و سلامت.
- `--output <path>`: در یک مسیر zip مشخص بنویسید.
- `--log-lines <count>`: حداکثر خطوط لاگ پاک‌سازی‌شده برای گنجاندن.
- `--log-bytes <bytes>`: حداکثر بایت‌های لاگ برای بررسی.
- `--url <url>`: URL WebSocket Gateway برای snapshotهای وضعیت و سلامت.
- `--token <token>`: token Gateway برای snapshotهای وضعیت و سلامت.
- `--password <password>`: رمز عبور Gateway برای snapshotهای وضعیت و سلامت.
- `--timeout <ms>`: 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 عیب‌یابی‌ها به یک گردآورنده

454
docs/fa/gateway/doctor.md
View File

@ -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
```
### حالت‌های بدون سر و خودکارسازی
### حالت‌های بدون رابط تعاملی و خودکارسازی
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
پیش‌فرض‌ها را بدون پرسش بپذیر (از جمله گام‌های ترمیم راه‌اندازی مجدد/سرویس/سندباکس در صورت کاربرد).
پیش‌فرض‌ها را بدون درخواست تأیید بپذیر (از جمله گام‌های تعمیر راه‌اندازی دوباره/سرویس/sandbox در موارد قابل اعمال).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
ترمیم‌های پیشنهادی را بدون پرسش اعمال کن (ترمیم‌ها + راه‌اندازی‌های مجدد در موارد امن).
تعمیرهای پیشنهادی را بدون درخواست تأیید اعمال کن (تعمیرها + راه‌اندازی دوباره در موارد امن).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
ترمیم‌های تهاجمی را هم اعمال کن (پیکربندی‌های سفارشی ناظر را بازنویسی می‌کند).
تعمیرهای تهاجمی را هم اعمال کن (پیکربندی‌های سفارشی supervisor را بازنویسی می‌کند).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
بدون پرسش اجرا کن و فقط مهاجرت‌های امن را اعمال کن (عادی‌سازی پیکربندی + انتقال وضعیت روی دیسک). اقدام‌های راه‌اندازی مجدد/سرویس/سندباکس را که به تأیید انسانی نیاز دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند.
بدون درخواست‌های تعاملی اجرا کن و فقط مهاجرت‌های امن را اعمال کن (نرمال‌سازی پیکربندی + جابه‌جایی وضعیت روی دیسک). اقدامات راه‌اندازی دوباره/سرویس/sandbox را که به تأیید انسانی نیاز دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند.
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
سرویس‌های سیستم را برای نصب‌های Gateway اضافی اسکن کن (launchd/systemd/schtasks).
سرویس‌های سیستم را برای نصب‌های اضافی gateway اسکن کن (launchd/systemd/schtasks).
</Tab>
</Tabs>
اگر می‌خواهید تغییرات را پیش از نوشتن بازبینی کنید، ابتدا فایل پیکربندی را باز کنید:
اگر می‌خواهید تغییرات را پیش از نوشتن مرور کنید، ابتدا فایل پیکربندی را باز کنید:
```bash
cat ~/.openclaw/openclaw.json
@ -78,116 +78,119 @@ cat ~/.openclaw/openclaw.json
<AccordionGroup>
<Accordion title="سلامت، رابط کاربری، و به‌روزرسانی‌ها">
- به‌روزرسانی اختیاری پیش از اجرا برای نصب‌های git (فقط تعاملی).
- بررسی تازگی پروتکل رابط کاربری (وقتی شِمای پروتکل جدیدتر باشد Control UI را دوباره می‌سازد).
- بررسی سلامت + درخواست راه‌اندازی مجدد.
- خلاصه وضعیت Skills (واجد شرایط/ناموجود/مسدود) و وضعیت Plugin.
- بررسی تازگی پروتکل رابط کاربری (وقتی schema پروتکل جدیدتر باشد، Control UI را دوباره می‌سازد).
- بررسی سلامت + درخواست راه‌اندازی دوباره.
- خلاصه وضعیت Skills (واجد شرایط/مفقود/مسدود) و وضعیت plugin.
</Accordion>
<Accordion title="پیکربندی و مهاجرت‌ها">
- عادی‌سازی پیکربندی برای مقدارهای قدیمی.
- مهاجرت پیکربندی گفت‌وگو از فیلدهای تخت قدیمی `talk.*` به `talk.provider` + `talk.providers.<provider>`.
- نرمال‌سازی پیکربندی برای مقدارهای قدیمی.
- مهاجرت پیکربندی Talk از فیلدهای تخت قدیمی `talk.*` به `talk.provider` + `talk.providers.<provider>`.
- بررسی‌های مهاجرت مرورگر برای پیکربندی‌های قدیمی افزونه 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 بی‌اثر در نظر گرفته می‌شوند و حفظ می‌شوند.
</Accordion>
<Accordion title="وضعیت و یکپارچگی">
- بازرسی فایل قفل نشست و پاک‌سازی قفل‌های کهنه.
- ترمیم رونوشت نشست برای شاخه‌های تکراری بازنویسی پرامپت که توسط بیلدهای متأثر 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`).
</Accordion>
<Accordion title="Gateway، سرویس‌ها، و ناظرها">
- ترمیم تصویر سندباکس وقتی سندباکس‌کردن فعال است.
- مهاجرت سرویس قدیمی و شناسایی Gateway اضافی.
<Accordion title="Gateway، سرویس‌ها، و supervisorها">
- تعمیر تصویر 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`).
</Accordion>
<Accordion title="احراز هویت، امنیت، و جفت‌سازی">
- هشدارهای امنیتی برای سیاست‌های پیام مستقیم باز.
- بررسی‌های احراز هویت Gateway برای حالت توکن محلی (وقتی هیچ منبع توکنی وجود ندارد تولید توکن را پیشنهاد می‌کند؛ پیکربندی‌های SecretRef توکن را بازنویسی نمی‌کند).
- شناسایی مشکل جفت‌سازی دستگاه (درخواست‌های جفت‌سازی نخستین‌بار در انتظار، ارتقاهای نقش/دامنه در انتظار، انحراف کش کهنه توکن دستگاه محلی، و انحراف احراز هویت رکورد جفت‌شده).
<Accordion title="احراز هویت، امنیت، و pairing">
- هشدارهای امنیتی برای سیاست‌های DM باز.
- بررسی‌های احراز هویت Gateway برای حالت token محلی (وقتی منبع token وجود ندارد، تولید token را پیشنهاد می‌دهد؛ پیکربندی‌های token SecretRef را بازنویسی نمی‌کند).
- شناسایی مشکل pairing دستگاه (درخواست‌های pending برای first-time pair، ارتقاهای pending نقش/scope، drift در cache محلی device-token کهنه، و drift احراز هویت paired-record).
</Accordion>
<Accordion title="فضای کار و پوسته">
- بررسی linger در systemd روی Linux.
- بررسی اندازه فایل راه‌انداز فضای کار (هشدارهای برش/نزدیک‌بودن به حد برای فایل‌های زمینه).
- بررسی آمادگی Skills برای عامل پیش‌فرض؛ مهارت‌های مجاز با نیازمندی‌های ناموجود bin، محیط، پیکربندی، یا سیستم‌عامل را گزارش می‌دهد، و `--fix` می‌تواند مهارت‌های در دسترس نبودنی را در `skills.entries` غیرفعال کند.
- بررسی وضعیت تکمیل پوسته و نصب/ارتقای خودکار.
- بررسی آمادگی ارائه‌دهنده تعبیه جست‌وجوی حافظه (مدل محلی، کلید API راه‌دور، یا باینری QMD).
- بررسی‌های نصب از منبع (ناسازگاری فضای کار pnpm، دارایی‌های رابط کاربری ناموجود، باینری tsx ناموجود).
- پیکربندی به‌روزشده + فراداده جادوگر را می‌نویسد.
<Accordion title="Workspace و پوسته">
- بررسی 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 را می‌نویسد.
</Accordion>
</AccordionGroup>
## پس‌پرکردن و بازنشانی رابط کاربری رویاها
## بازپرکنی و بازنشانی 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` را به‌عنوان سطح مرور نگه می‌دارد.
## رفتار دقیق و منطق
<AccordionGroup>
<Accordion title="0. به‌روزرسانی اختیاری (نصب‌های git)">
اگر این یک checkout از git باشد و doctor به‌صورت تعاملی اجرا شود، پیش از اجرای doctor پیشنهاد به‌روزرسانی (fetch/rebase/build) می‌دهد.
اگر این یک git checkout باشد و doctor به‌صورت تعاملی اجرا شود، پیشنهاد می‌دهد پیش از اجرای doctor به‌روزرسانی انجام شود (fetch/rebase/build).
</Accordion>
<Accordion title="1. عادی‌سازی پیکربندی">
اگر پیکربندی شامل شکل‌های مقدار قدیمی باشد (برای مثال `messages.ackReaction` بدون بازنویسی ویژه کانال)، doctor آن‌ها را در شِمای فعلی عادی‌سازی می‌کند.
<Accordion title="1. نرمال‌سازی پیکربندی">
اگر پیکربندی شامل شکل‌های مقدار قدیمی باشد (برای مثال `messages.ackReaction` بدون override ویژه کانال)، doctor آن‌ها را به schema فعلی نرمال می‌کند.
این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.<provider>`. Doctor شکل‌های قدیمی `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` را در نقشه ارائه‌دهنده بازنویسی می‌کند.
این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.<provider>`. 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"` اشاره می‌کند.
</Accordion>
<Accordion title="2. مهاجرت‌های کلید پیکربندی قدیمی">
وقتی پیکربندی شامل کلیدهای منسوخ باشد، فرمان‌های دیگر از اجرا سر باز می‌زنند و از شما می‌خواهند `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.<provider>`
- میراثی `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -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.<id>.timeoutSeconds` استفاده کنید
- `agents.defaults.llm` را حذف کنید؛ برای زمان‌انقضای کند provider/model از `models.providers.<id>.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.<channel>.accounts` بدون `channels.<channel>.defaultAccount` یا `accounts.default` پیکربندی شده باشند، doctor هشدار می‌دهد که مسیریابی fallback می‌تواند حسابی غیرمنتظره را انتخاب کند.
- اگر دو یا چند ورودی `channels.<channel>.accounts` بدون `channels.<channel>.defaultAccount` یا `accounts.default` پیکربندی شده باشند، doctor هشدار می‌دهد که مسیریابی fallback می‌تواند حساب غیرمنتظره‌ای را انتخاب کند.
- اگر `channels.<channel>.defaultAccount` روی شناسه حساب ناشناخته تنظیم شده باشد، doctor هشدار می‌دهد و شناسه‌های حساب پیکربندی‌شده را فهرست می‌کند.
</Accordion>
<Accordion title="2b. بازنویسی‌های provider مربوط به OpenCode">
اگر `models.providers.opencode`، `opencode-zen`، یا `opencode-go` را دستی اضافه کرده باشید، کاتالوگ داخلی OpenCode از `@mariozechner/pi-ai` را بازنویسی می‌کند. این می‌تواند مدل‌ها را وادار کند از API نادرست استفاده کنند یا هزینه‌ها را صفر کند. Doctor هشدار می‌دهد تا بتوانید بازنویسی را حذف کنید و مسیریابی API به‌ازای هر مدل + هزینه‌ها را برگردانید.
<Accordion title="۲ب. بازنویسی‌های provider در OpenCode">
اگر `models.providers.opencode`، `opencode-zen` یا `opencode-go` را دستی اضافه کرده باشید، catalog داخلی OpenCode از `@mariozechner/pi-ai` را بازنویسی می‌کند. این کار می‌تواند مدل‌ها را به API اشتباه اجبار کند یا هزینه‌ها را صفر کند. Doctor هشدار می‌دهد تا بتوانید بازنویسی را حذف کنید و مسیریابی API به‌ازای هر مدل + هزینه‌ها را بازیابی کنید.
</Accordion>
<Accordion title="2c. مهاجرت مرورگر و آمادگی Chrome MCP">
اگر پیکربندی مرورگر شما هنوز به مسیر حذف‌شده Chrome extension اشاره می‌کند، doctor آن را به مدل فعلی اتصال Chrome MCP محلی روی میزبان نرمال‌سازی می‌کند:
<Accordion title="۲ج. مهاجرت مرورگر و آمادگی 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 خام استفاده می‌کنند.
</Accordion>
<Accordion title="2d. پیش‌نیازهای OAuth TLS">
وقتی یک پروفایل OpenAI Codex OAuth پیکربندی شده باشد، doctor نقطه پایانی مجوزدهی OpenAI را بررسی می‌کند تا مطمئن شود پشته TLS محلی Node/OpenSSL می‌تواند زنجیره گواهی را اعتبارسنجی کند. اگر بررسی با خطای گواهی شکست بخورد (برای مثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`، گواهی منقضی‌شده، یا گواهی خودامضاشده)، doctor راهنمای رفع مشکل مخصوص پلتفرم را چاپ می‌کند. در macOS با Node نصب‌شده از Homebrew، راه‌حل معمولا `brew postinstall ca-certificates` است. با `--deep`، این بررسی حتی اگر Gateway سالم باشد هم اجرا می‌شود.
<Accordion title="۲د. پیش‌نیازهای OAuth TLS">
وقتی یک پروفایل 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 سالم باشد اجرا می‌شود.
</Accordion>
<Accordion title="2e. بازنویسی‌های provider مربوط به Codex OAuth">
اگر قبلا تنظیمات انتقال قدیمی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر provider داخلی Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند تحت‌الشعاع قرار دهند. Doctor وقتی آن تنظیمات انتقال قدیمی را کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید بازنویسی انتقال کهنه را حذف یا بازنویسی کنید و رفتار داخلی مسیریابی/fallback را برگردانید. پراکسی‌های سفارشی و بازنویسی‌های فقط header همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند.
<Accordion title="۲ه. بازنویسی‌های provider در Codex OAuth">
اگر قبلاً تنظیمات انتقال میراثی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر داخلی provider در Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند پنهان کنند. Doctor وقتی آن تنظیمات انتقال قدیمی را در کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید بازنویسی انتقال کهنه را حذف یا بازنویسی کنید و رفتار مسیریابی/fallback داخلی را برگردانید. پراکسی‌های سفارشی و بازنویسی‌های فقط‌header همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند.
</Accordion>
<Accordion title="2f. هشدارهای مسیر Plugin مربوط به Codex">
وقتی 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`.
<Accordion title="۲و. هشدارهای مسیر Plugin در 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 عمدی است، هشدار را همان‌طور نگه دارید.
</Accordion>
<Accordion title="3. مهاجرت‌های وضعیت قدیمی (چیدمان دیسک)">
Doctor می‌تواند چیدمان‌های قدیمی روی دیسک را به ساختار فعلی مهاجرت دهد:
<Accordion title="۲ز. پاک‌سازی مسیر session">
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 کنید.
</Accordion>
<Accordion title="۳. مهاجرت‌های وضعیت میراثی (چیدمان دیسک)">
Doctor می‌تواند چیدمان‌های قدیمی‌تر روی دیسک را به ساختار فعلی مهاجرت دهد:
- Sessions store + transcriptها:
- از `~/.openclaw/sessions/` به `~/.openclaw/agents/<agentId>/sessions/`
- دایرکتوری عامل:
- دایرکتوری agent:
- از `~/.openclaw/agent/` به `~/.openclaw/agents/<agentId>/agent/`
- وضعیت احراز هویت WhatsApp (Baileys):
- از `~/.openclaw/credentials/*.json` قدیمی (به‌جز `oauth.json`)
- از میراثی `~/.openclaw/credentials/*.json` (به‌جز `oauth.json`)
- به `~/.openclaw/credentials/whatsapp/<accountId>/...` (شناسه حساب پیش‌فرض: `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` را فعال نمی‌کنند.
</Accordion>
<Accordion title="3a. مهاجرت‌های manifest قدیمی Plugin">
Doctor همه manifestهای Plugin نصب‌شده را برای کلیدهای capability سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل manifest را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقدارها را داشته باشد، کلید قدیمی بدون تکرار داده حذف می‌شود.
<Accordion title="۳الف. مهاجرت‌های manifest میراثی Plugin">
Doctor همه manifestهای Plugin نصب‌شده را برای کلیدهای capability سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل manifest را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقدارها را داشته باشد، کلید میراثی بدون تکثیر داده حذف می‌شود.
</Accordion>
<Accordion title="3b. مهاجرت‌های ذخیره‌گاه Cron قدیمی">
Doctor همچنین ذخیره‌گاه کارهای cron را (`~/.openclaw/cron/jobs.json` به‌صورت پیش‌فرض، یا `cron.store` وقتی بازنویسی شده باشد) برای شکل‌های قدیمی job که scheduler هنوز برای سازگاری می‌پذیرد بررسی می‌کند.
<Accordion title="۳ب. مهاجرت‌های cron store میراثی">
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` استفاده کنید.
</Accordion>
<Accordion title="3c. پاک‌سازی قفل نشست">
دکتر هر دایرکتوری نشست عامل را برای فایل‌های قفل نوشتن کهنه اسکن می‌کند — فایل‌هایی که وقتی یک نشست به‌طور غیرعادی خارج شده، باقی مانده‌اند. برای هر فایل قفل پیدا‌شده گزارش می‌دهد: مسیر، PID، اینکه آیا PID هنوز زنده است، سن قفل، و اینکه آیا کهنه در نظر گرفته می‌شود یا نه (PID مرده یا قدیمی‌تر از ۳۰ دقیقه). در حالت `--fix` / `--repair`، فایل‌های قفل کهنه را به‌طور خودکار حذف می‌کند؛ در غیر این صورت یادداشتی چاپ می‌کند و به شما دستور می‌دهد با `--fix` دوباره اجرا کنید.
Doctor همهٔ دایرکتوری‌های نشست عامل را برای فایل‌های write-lock مانده بررسی می‌کند — فایل‌هایی که وقتی یک نشست به‌صورت غیرعادی خارج شده باقی مانده‌اند. برای هر فایل قفل پیدا‌شده گزارش می‌دهد: مسیر، PID، اینکه PID هنوز زنده است یا نه، سن قفل، و اینکه آیا قدیمی محسوب می‌شود یا نه (PID مرده یا قدیمی‌تر از ۳۰ دقیقه). در حالت `--fix` / `--repair` فایل‌های قفل قدیمی را خودکار حذف می‌کند؛ در غیر این صورت یک یادداشت چاپ می‌کند و از شما می‌خواهد با `--fix` دوباره اجرا کنید.
</Accordion>
<Accordion title="3d. ترمیم شاخه رونوشت نشست">
دکتر فایل‌های JSONL نشست عامل را برای شکل شاخه تکراری ایجادشده توسط باگ بازنویسی رونوشت پرامپت 2026.4.24 اسکن می‌کند: یک نوبت کاربر رهاشده با زمینه زمان اجرای داخلی OpenClaw به‌همراه یک همزاد فعال که همان پرامپت قابل مشاهده کاربر را دارد. در حالت `--fix` / `--repair`، دکتر از هر فایل آسیب‌دیده در کنار نسخه اصلی پشتیبان می‌گیرد و رونوشت را به شاخه فعال بازنویسی می‌کند تا تاریخچه gateway و خواننده‌های حافظه دیگر نوبت‌های تکراری را نبینند.
<Accordion title="3d. ترمیم شاخهٔ رونوشت نشست">
Doctor فایل‌های JSONL نشست عامل را برای شکل شاخهٔ تکراری ایجادشده توسط باگ بازنویسی رونوشت پرامپت 2026.4.24 بررسی می‌کند: یک نوبت کاربر رهاشده با زمینهٔ runtime داخلی OpenClaw به‌همراه یک همتای فعال که همان پرامپت قابل‌مشاهدهٔ کاربر را دارد. در حالت `--fix` / `--repair`، Doctor از هر فایل آسیب‌دیده کنار فایل اصلی نسخهٔ پشتیبان می‌گیرد و رونوشت را به شاخهٔ فعال بازنویسی می‌کند تا تاریخچهٔ Gateway و خواننده‌های حافظه دیگر نوبت‌های تکراری نبینند.
</Accordion>
<Accordion title="4. بررسی‌های یکپارچگی وضعیت (ماندگاری نشست، مسیریابی، و ایمنی)">
دایرکتوری وضعیت، ساقه مغز عملیاتی است. اگر ناپدید شود، نشست‌ها، اعتبارنامه‌ها، لاگ‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه در جای دیگری پشتیبان داشته باشید).
دایرکتوری وضعیت ساقهٔ مغز عملیاتی است. اگر ناپدید شود، نشست‌ها، اعتبارنامه‌ها، گزارش‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه در جای دیگری نسخهٔ پشتیبان داشته باشید).
دکتر بررسی می‌کند:
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` را می‌دهد.
</Accordion>
<Accordion title="5. سلامت احراز هویت مدل (انقضای OAuth)">
دکتر پروفایل‌های 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/شکست‌های احراز هویت)
- غیرفعال‌سازی‌های طولانی‌تر (شکست‌های صورت‌حساب/اعتبار)
</Accordion>
<Accordion title="6. اعتبارسنجی مدل hooks">
اگر `hooks.gmail.model` تنظیم شده باشد، دکتر مرجع مدل را در برابر کاتالوگ و allowlist اعتبارسنجی می‌کند و وقتی حل نشود یا مجاز نباشد هشدار می‌دهد.
اگر `hooks.gmail.model` تنظیم شده باشد، Doctor مرجع مدل را در برابر catalog و allowlist اعتبارسنجی می‌کند و وقتی resolve نشود یا مجاز نباشد هشدار می‌دهد.
</Accordion>
<Accordion title="7. ترمیم تصویر sandbox">
وقتی sandboxing فعال باشد، دکتر تصویرهای Docker را بررسی می‌کند و اگر تصویر فعلی موجود نباشد، پیشنهاد ساخت یا تغییر به نام‌های قدیمی را می‌دهد.
وقتی sandboxing فعال باشد، Doctor تصویرهای Docker را بررسی می‌کند و اگر تصویر فعلی موجود نباشد پیشنهاد build کردن یا تغییر به نام‌های قدیمی را می‌دهد.
</Accordion>
<Accordion title="7b. پاک‌سازی نصب Plugin">
دکتر در حالت `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 باقی می‌مانند.
</Accordion>
<Accordion title="8. مهاجرت‌های سرویس Gateway و راهنمایی‌های پاک‌سازی">
دکتر سرویس‌های 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` را تنظیم کنید.
</Accordion>
<Accordion title="8b. مهاجرت Matrix هنگام شروع">
وقتی یک حساب کانال Matrix مهاجرت وضعیت قدیمی در انتظار یا قابل اقدام داشته باشد، دکتر (در حالت `--fix` / `--repair`) یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس مراحل مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت Matrix قدیمی و آماده‌سازی وضعیت رمزگذاری‌شده قدیمی. هر دو مرحله غیرکشنده هستند؛ خطاها ثبت می‌شوند و شروع ادامه پیدا می‌کند. در حالت فقط خواندنی (`openclaw doctor` بدون `--fix`) این بررسی به‌طور کامل رد می‌شود.
<Accordion title="8b. مهاجرت Matrix هنگام راه‌اندازی">
وقتی حساب کانال Matrix یک مهاجرت وضعیت قدیمی در انتظار یا قابل اقدام داشته باشد، Doctor (در حالت `--fix` / `--repair`) یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس گام‌های مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت قدیمی Matrix و آماده‌سازی وضعیت رمزگذاری‌شدهٔ قدیمی. هر دو گام غیرکشنده هستند؛ خطاها ثبت می‌شوند و راه‌اندازی ادامه پیدا می‌کند. در حالت read-only (`openclaw doctor` بدون `--fix`) این بررسی کاملاً رد می‌شود.
</Accordion>
<Accordion title="8c. جفت‌سازی دستگاه و انحراف احراز هویت">
دکتر اکنون وضعیت جفت‌سازی دستگاه را به‌عنوان بخشی از گذر سلامت عادی بررسی می‌کند.
<Accordion title="8c. جفت‌سازی دستگاه و drift احراز هویت">
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 <requestId>` تأیید کنید
- یک توکن تازه را با `openclaw devices rotate --device <deviceId> --role <role>` بچرخانید
- یک رکورد کهنه را با `openclaw devices remove <deviceId>` حذف و دوباره تأیید کنید
- یک توکن تازه را با `openclaw devices rotate --device <deviceId> --role <role>` rotate کنید
- یک رکورد قدیمی را با `openclaw devices remove <deviceId>` حذف و دوباره تأیید کنید
این شکاف رایج "از قبل جفت شده اما هنوز pairing required دریافت می‌کند" را می‌بندد: دکتر اکنون جفت‌سازی بار اول را از ارتقاهای نقش/scope در انتظار و از انحراف توکن/هویت دستگاه کهنه متمایز می‌کند.
این حفرهٔ رایج "از قبل جفت شده اما هنوز pairing required می‌گیرد" را می‌بندد: Doctor اکنون جفت‌سازی بار اول را از ارتقاهای نقش/scope در انتظار و از drift قدیمی توکن/هویت دستگاه متمایز می‌کند.
</Accordion>
<Accordion title="9. هشدارهای امنیتی">
دکتر وقتی یک ارائه‌دهنده بدون allowlist برای DMها باز باشد، یا وقتی یک policy به‌شکل خطرناک پیکربندی شده باشد، هشدار منتشر می‌کند.
Doctor وقتی یک ارائه‌دهنده بدون allowlist به روی DMها باز باشد، یا وقتی یک policy به روشی خطرناک پیکربندی شده باشد، هشدار صادر می‌کند.
</Accordion>
<Accordion title="10. linger در systemd (Linux)">
اگر به‌عنوان سرویس کاربر systemd اجرا شود، دکتر اطمینان می‌دهد lingering فعال باشد تا gateway پس از logout زنده بماند.
<Accordion title="10. systemd linger (Linux)">
اگر به‌عنوان سرویس کاربر systemd اجرا شود، Doctor اطمینان می‌دهد lingering فعال است تا gateway پس از خروج از سیستم زنده بماند.
</Accordion>
<Accordion title="11. وضعیت workspace (skills، Pluginها، و دایرکتوری‌های قدیمی)">
دکتر خلاصه‌ای از وضعیت workspace را برای عامل پیش‌فرض چاپ می‌کند:
<Accordion title="11. وضعیت workspace (Skills، Pluginها، و دایرکتوری‌های قدیمی)">
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 را نمایان می‌کند.
</Accordion>
<Accordion title="11b. اندازه فایل bootstrap">
دکتر بررسی می‌کند که آیا فایل‌های bootstrap workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا فایل‌های زمینه تزریق‌شده دیگر) نزدیک یا بالاتر از بودجه کاراکتر پیکربندی‌شده هستند یا نه. برای هر فایل شمار خام در برابر شمار کاراکترهای تزریق‌شده، درصد truncation، علت truncation (`max/file` یا `max/total`)، و کل کاراکترهای تزریق‌شده به‌عنوان کسری از بودجه کل را گزارش می‌دهد. وقتی فایل‌ها truncate شده باشند یا نزدیک حد باشند، دکتر نکته‌هایی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند.
<Accordion title="11b. اندازهٔ فایل bootstrap">
Doctor بررسی می‌کند که آیا فایل‌های bootstrap workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا دیگر فایل‌های زمینهٔ تزریق‌شده) نزدیک یا فراتر از بودجهٔ کاراکتر پیکربندی‌شده هستند یا نه. شمارش کاراکتر خام در برابر تزریق‌شده، درصد truncation، علت truncation (`max/file` یا `max/total`)، و مجموع کاراکترهای تزریق‌شده به‌عنوان کسری از بودجهٔ کل را برای هر فایل گزارش می‌دهد. وقتی فایل‌ها truncate شده باشند یا نزدیک حد باشند، Doctor نکته‌هایی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند.
</Accordion>
<Accordion title="11d. پاک‌سازی Plugin کانال کهنه">
وقتی `openclaw doctor --fix` یک Plugin کانال گم‌شده را حذف می‌کند، پیکربندی آویزانِ محدود به کانال را که به آن Plugin ارجاع داده بود نیز حذف می‌کند: ورودی‌های `channels.<id>`، هدف‌های Heartbeat که نام کانال را برده‌اند، و overrideهای `agents.*.models["<channel>/*"]`. این از loopهای boot در Gateway جلوگیری می‌کند که در آن runtime کانال از بین رفته اما پیکربندی هنوز از gateway می‌خواهد به آن bind شود.
<Accordion title="11d. پاک‌سازی Plugin کانال قدیمی">
وقتی `openclaw doctor --fix` یک Plugin کانال مفقود را حذف می‌کند، پیکربندی dangling محدود به کانال را هم که به آن Plugin ارجاع می‌داد حذف می‌کند: ورودی‌های `channels.<id>`، هدف‌های Heartbeat که کانال را نام برده بودند، و overrideهای `agents.*.models["<channel>/*"]`. این کار از حلقه‌های boot Gateway جلوگیری می‌کند که در آن runtime کانال رفته اما پیکربندی هنوز از gateway می‌خواهد به آن bind شود.
</Accordion>
<Accordion title="11c. تکمیل shell">
دکتر بررسی می‌کند آیا تکمیل 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` را اجرا کنید.
</Accordion>
<Accordion title="12. بررسی‌های احراز هویت Gateway (توکن محلی)">
دکتر آمادگی احراز هویت توکن 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 توکنی پیکربندی نشده باشد، تولید را اجباری می‌کند.
</Accordion>
<Accordion title="12b. ترمیم‌های فقط‌خواندنی آگاه از SecretRef">
برخی جریان‌های ترمیم باید اعتبارنامه‌های پیکربندی‌شده را بدون تضعیف رفتار fail-fast زمان اجرا بررسی کنند.
<Accordion title="12b. ترمیم‌های read-only آگاه از SecretRef">
برخی جریان‌های ترمیم باید اعتبارنامه‌های پیکربندی‌شده را بدون ضعیف کردن رفتار 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 گزارش می‌دهد که اعتبارنامه پیکربندی‌شده-اما-ناموجود است و به‌جای خرابی یا گزارش نادرستِ نبودن توکن، حل خودکار را رد می‌کند.
</Accordion>
<Accordion title="۱۳. بررسی سلامت Gateway + راه‌اندازی مجدد">
doctor یک بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد راه‌اندازی مجدد آن را می‌دهد.
Doctor یک بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد راه‌اندازی مجدد آن را می‌دهد.
</Accordion>
<Accordion title="۱۳ب. آمادگی جستجوی حافظه">
doctor بررسی می‌کند که آیا ارائه‌دهنده تعبیه‌سازی جستجوی حافظه پیکربندی‌شده برای عامل پیش‌فرض آماده است یا نه. رفتار به پشتیبان و ارائه‌دهنده پیکربندی‌شده بستگی دارد:
<Accordion title="۱۳ب. آمادگی جست‌وجوی حافظه">
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 در زمان اجرا استفاده کنید.
</Accordion>
<Accordion title="۱۴. هشدارهای وضعیت کانال">
اگر Gateway سالم باشد، doctor یک بررسی وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌دهد.
اگر Gateway سالم باشد، doctor یک probe وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌دهد.
</Accordion>
<Accordion title="۱۵. ممیزی + تعمیر پیکربندی ناظر">
doctor پیکربندی ناظر نصب‌شده (launchd/systemd/schtasks) را برای پیش‌فرض‌های جاافتاده یا قدیمی (برای مثال، وابستگی‌های systemd به network-online و تأخیر راه‌اندازی مجدد) بررسی می‌کند. وقتی ناهماهنگی پیدا کند، به‌روزرسانی را توصیه می‌کند و می‌تواند فایل سرویس/وظیفه را با پیش‌فرض‌های فعلی بازنویسی کند.
<Accordion title="۱۵. بازرسی + تعمیر پیکربندی supervisor">
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` یک بازنویسی کامل را اجبار کنید.
</Accordion>
<Accordion title="۱۶. تشخیص‌های زمان اجرای Gateway + درگاه">
doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و وقتی سرویس نصب شده اما واقعاً در حال اجرا نیست هشدار می‌دهد. همچنین تداخل‌های درگاه روی درگاه Gateway (پیش‌فرض `18789`) را بررسی می‌کند و علت‌های محتمل (Gateway از قبل در حال اجرا است، تونل SSH) را گزارش می‌دهد.
<Accordion title="۱۶. تشخیص‌های زمان اجرای Gateway + پورت">
Doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و وقتی سرویس نصب شده اما واقعاً در حال اجرا نیست، هشدار می‌دهد. همچنین برخوردهای port روی port مربوط به Gateway (پیش‌فرض `18789`) را بررسی می‌کند و علت‌های محتمل (Gateway از قبل در حال اجراست، SSH tunnel) را گزارش می‌دهد.
</Accordion>
<Accordion title="۱۷. بهترین رویه‌های زمان اجرای Gateway">
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 سرویس نوشته می‌شوند.
</Accordion>
<Accordion title="۱۸. نوشتن پیکربندی + فراداده جادوگر">
doctor هرگونه تغییر پیکربندی را ماندگار می‌کند و فراداده جادوگر را مهر می‌زند تا اجرای doctor ثبت شود.
<Accordion title="۱۸. نوشتن پیکربندی + فرادادهٔ wizard">
Doctor هر تغییر پیکربندی را پایدار می‌کند و فرادادهٔ wizard را برای ثبت اجرای doctor مهر می‌زند.
</Accordion>
<Accordion title="۱۹. نکته‌های فضای کاری (پشتیبان‌گیری + سیستم حافظه)">
doctor وقتی سیستم حافظه فضای کاری وجود ندارد آن را پیشنهاد می‌کند و اگر فضای کاری از قبل زیر git نباشد، یک نکته پشتیبان‌گیری چاپ می‌کند.
<Accordion title="۱۹. نکته‌های workspace (پشتیبان‌گیری + سامانهٔ حافظه)">
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) را ببینید.
</Accordion>
</AccordionGroup>
## مرتبط
- [دفترچه اجرای Gateway](/fa/gateway)
- [runbook مربوط به Gateway](/fa/gateway)
- [عیب‌یابی Gateway](/fa/gateway/troubleshooting)

126
docs/fa/gateway/logging.md
View File

@ -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)

179
docs/fa/help/debugging.md
View File

@ -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 <path>` استفاده کنید.
وقتی می‌خواهید فرزند بنچمارک‌شده پاک‌سازی پیش‌فرض پورت با `--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
```
<Note>
`--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
</Note>
`--reset` پیکربندی، اعتبارنامه‌ها، نشست‌ها، و workspace توسعه را پاک می‌کند (با
`trash`، نه `rm`)، سپس تنظیمات پیش‌فرض توسعه را دوباره می‌سازد.
`trash`، نه `rm`)، سپس چیدمان پیش‌فرض dev را دوباره می‌سازد.
<Tip>
اگر یک 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 را پاک‌سازی کنید.
## مرتبط

286
docs/fa/help/faq-models.md
View File

@ -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` را **صریح** تنظیم کنید.
</Accordion>
<Accordion title="چه مدلی را پیشنهاد می‌کنید؟">
**پیش‌فرض پیشنهادی:** از قوی‌ترین مدل نسل جدید موجود در مجموعه ارائه‌دهنده‌های خود استفاده کنید.
**برای عامل‌های دارای ابزار یا ورودی‌های نامطمئن:** قدرت مدل را بر هزینه اولویت دهید.
**پیش‌فرض پیشنهادی:** از قوی‌ترین مدل نسل جدید موجود در مجموعه ارائه‌دهندگان خود استفاده کنید.
**برای عامل‌های دارای ابزار یا ورودی نامطمئن:** قدرت مدل را به هزینه ترجیح دهید.
**برای گفت‌وگوی روزمره/کم‌ریسک:** از مدل‌های جایگزین ارزان‌تر استفاده کنید و بر اساس نقش عامل مسیریابی کنید.
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).
</Accordion>
<Accordion title="چگونه بدون پاک کردن پیکربندی، مدل‌ها را تغییر بدهم؟">
از **دستورهای مدل** استفاده کنید یا فقط فیلدهای **مدل** را ویرایش کنید. از جایگزینی کامل پیکربندی پرهیز کنید.
<Accordion title="چطور بدون پاک کردن پیکربندی، مدل‌ها را تغییر بدهم؟">
از **دستورهای مدل** استفاده کنید یا فقط فیلدهای **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).
</Accordion>
<Accordion title="آیا می‌توانم از مدل‌های خودمیزبان (llama.cpp، vLLM، Ollama) استفاده کنم؟">
<Accordion title="آیا می‌توانم از مدل‌های خودمیزبان‌شده (llama.cpp، vLLM، Ollama) استفاده کنم؟">
بله. 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/<model>` استفاده کنید
نکته امنیتی: مدل‌های کوچک‌تر یا به‌شدت کوانتیزه‌شده در برابر تزریق پرامپت
آسیب‌پذیرتر هستند. برای هر رباتی که می‌تواند از ابزارها استفاده کند، قویا **مدل‌های بزرگ** را پیشنهاد می‌کنیم.
اگر همچنان مدل‌های کوچک می‌خواهید، سندباکسینگ و allowlistهای سخت‌گیرانه ابزار را فعال کنید.
نکته امنیتی: مدل‌های کوچک‌تر یا شدیدا کوانتیزه‌شده در برابر تزریق پرامپت
آسیب‌پذیرتر هستند. برای هر رباتی که می‌تواند از ابزارها استفاده کند، **مدل‌های بزرگ** را قویا پیشنهاد می‌کنیم.
اگر همچنان مدل‌های کوچک می‌خواهید، sandboxing و فهرست‌های مجاز سخت‌گیرانه ابزار را فعال کنید.
مستندات: [Ollama](/fa/providers/ollama)، [مدل‌های محلی](/fa/gateway/local-models)،
[ارائه‌دهندگان مدل](/fa/concepts/model-providers)، [امنیت](/fa/gateway/security)،
[سندباکسینگ](/fa/gateway/sandboxing).
[Sandboxing](/fa/gateway/sandboxing).
</Accordion>
<Accordion title="OpenClaw، Flawd و Krill از چه مدل‌هایی استفاده می‌کنند؟">
- این استقرارها می‌توانند متفاوت باشند و ممکن است در طول زمان تغییر کنند؛ هیچ پیشنهاد ثابت ارائه‌دهنده‌ای وجود ندارد.
- تنظیم runtime فعلی را روی هر Gateway با `openclaw models status` بررسی کنید.
- این استقرارها می‌توانند متفاوت باشند و ممکن است با گذشت زمان تغییر کنند؛ هیچ پیشنهاد ثابت ارائه‌دهنده‌ای وجود ندارد.
- تنظیم runtime فعلی را روی هر gateway با `openclaw models status` بررسی کنید.
- برای عامل‌های حساس از نظر امنیت/دارای ابزار، از قوی‌ترین مدل نسل جدید موجود استفاده کنید.
</Accordion>
<Accordion title="چگونه مدل‌ها را در لحظه تغییر بدهم (بدون راه‌اندازی مجدد)؟">
از دستور `/model` به‌عنوان یک پیام مستقل استفاده کنید:
<Accordion title="چطور مدل‌ها را در لحظه تغییر بدهم (بدون راه‌اندازی مجدد)؟">
دستور `/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 <default provider/model>` را بفرستید).
از `/model status` برای تأیید پروفایل احراز هویت فعال استفاده کنید.
از `/model status` برای تایید نمایه احراز هویت فعال استفاده کنید.
</Accordion>
<Accordion title="آیا می‌توانم از GPT 5.5 برای کارهای روزانه و از Codex 5.5 برای کدنویسی استفاده کنم؟">
بله. انتخاب مدل و انتخاب 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) را ببینید.
</Accordion>
<Accordion title="چگونه حالت سریع را برای GPT 5.5 پیکربندی کنم؟">
<Accordion title="چطور حالت سریع را برای GPT 5.5 پیکربندی کنم؟">
از یک 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) را ببینید.
</Accordion>
<Accordion title='چرا "Model ... is not allowed" را می‌بینم و بعد پاسخی دریافت نمی‌کنم؟'>
اگر `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 <provider> 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` را دوباره امتحان کنید.
</Accordion>
<Accordion title='چرا "Unknown model: minimax/MiniMax-M2.7" را می‌بینم؟'>
این یعنی **ارائه‌دهنده پیکربندی نشده است** (هیچ پیکربندی ارائه‌دهنده 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) را ببینید.
</Accordion>
<Accordion title="آیا می‌توانم MiniMax را پیش‌فرض قرار دهم و از OpenAI برای کارهای پیچیده استفاده کنم؟">
بله. از **MiniMax به‌عنوان پیش‌فرض** استفاده کنید و در صورت نیاز مدل‌ها را **برای هر نشست** تغییر دهید.
fallbackها برای **خطاها** هستند، نه «کارهای سخت»، بنابراین از `/model` یا یک عامل جداگانه استفاده کنید.
<Accordion title="آیا می‌توانم MiniMax را به‌عنوان پیش‌فرض و OpenAI را برای کارهای پیچیده استفاده کنم؟">
بله. از **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).
</Accordion>
<Accordion title="آیا opus / sonnet / gpt میان‌برهای داخلی هستند؟">
بله. 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:
</Accordion>
<Accordion title="چگونه میان‌برهای مدل (نام‌های مستعار) را تعریف/بازنویسی کنم؟">
نام‌های مستعار از `agents.defaults.models.<modelId>.alias` می‌آیند. مثال:
<Accordion title="چطور میان‌برهای مدل (نام‌های مستعار) را تعریف/بازنویسی کنم؟">
نام‌های مستعار از `agents.defaults.models.<modelId>.alias` می‌آیند. نمونه:
```json5
{
@ -303,8 +310,8 @@ x-i18n:
</Accordion>
<Accordion title="چگونه مدل‌هایی از ارائه‌دهندگان دیگر مانند OpenRouter یا Z.AI اضافه کنم؟">
OpenRouter (پرداخت به‌ازای توکن؛ مدل‌های زیاد):
<Accordion title="چطور مدل‌هایی از ارائه‌دهندگان دیگر مانند OpenRouter یا Z.AI اضافه کنم؟">
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/<agentId>/agent/auth-profiles.json
@ -345,147 +351,145 @@ x-i18n:
گزینه‌های رفع مشکل:
- `openclaw agents add <id>` را اجرا کنید و احراز هویت را در طول راهنمای مرحله‌ای پیکربندی کنید.
- یا فقط پروفایل‌های ثابت و قابل‌انتقال `api_key` / `token` را از مخزن احراز هویت عامل اصلی به مخزن احراز هویت عامل جدید کپی کنید.
- برای پروفایل‌های OAuth، وقتی عامل جدید به حساب خودش نیاز دارد از همان عامل جدید وارد شوید؛ در غیر این صورت OpenClaw می‌تواند بدون کلون کردن توکن‌های تازه‌سازی، از عامل پیش‌فرض/اصلی بخواند.
- `openclaw agents add <id>` را اجرا کنید و احراز هویت را در جادوگر پیکربندی کنید.
- یا فقط پروفایل‌های ایستای قابل‌حمل `api_key` / `token` را از مخزن احراز هویت عامل اصلی به مخزن احراز هویت عامل جدید کپی کنید.
- برای پروفایل‌های OAuth، وقتی عامل جدید به حساب خودش نیاز دارد، از همان عامل جدید وارد شوید؛ در غیر این صورت OpenClaw می‌تواند بدون شبیه‌سازی توکن‌های تازه‌سازی، از عامل پیش‌فرض/اصلی بخواند.
از `agentDir` مشترک بین عامل‌ها استفاده **نکنید**؛ این کار باعث تداخل احراز هویت/نشست می‌شود.
از `agentDir` در چند عامل دوباره استفاده **نکنید**؛ این کار باعث تداخل احراز هویت/نشست می‌شود.
</Accordion>
</AccordionGroup>
## Failover مدل و «همه مدل‌ها ناموفق بودند»
## جابه‌جایی مدل هنگام خرابی و «همه مدل‌ها ناموفق بودند»
<AccordionGroup>
<Accordion title="Failover چگونه کار می‌کند؟">
Failover در دو مرحله انجام می‌شود:
<Accordion title="جابه‌جایی هنگام خرابی چگونه کار می‌کند؟">
جابه‌جایی هنگام خرابی در دو مرحله رخ می‌دهد:
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.` محافظه‌کارانه باقی می‌ماند و به‌تنهایی بازگشت به مدل جایگزین را فعال نمی‌کند.
</Accordion>
<Accordion title='«هیچ اعتبارنامه‌ای برای پروفایل anthropic:default پیدا نشد» یعنی چه؟'>
<Accordion title='«No credentials found for profile anthropic:default» یعنی چه؟'>
یعنی سیستم تلاش کرده از شناسه پروفایل احراز هویت `anthropic:default` استفاده کند، اما نتوانسته اعتبارنامه‌های آن را در مخزن احراز هویت مورد انتظار پیدا کند.
**چک‌لیست رفع مشکل:**
**فهرست بررسی رفع مشکل:**
- **تأیید کنید پروفایل‌های احراز هویت کجا قرار دارند** (مسیرهای جدید در برابر قدیمی)
- **تأیید کنید پروفایل‌های احراز هویت کجا قرار دارند** (مسیرهای جدید در برابر مسیرهای قدیمی)
- فعلی: `~/.openclaw/agents/<agentId>/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 قرار دارند، نه لپ‌تاپ شما.
</Accordion>
<Accordion title="چرا Google Gemini را هم امتحان کرد و ناموفق شد؟">
اگر پیکربندی مدل شما 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` را تنظیم کنید.
</Accordion>
</AccordionGroup>
## پروفایل‌های احراز هویت: چیستی آن‌ها و روش مدیریتشان
## پروفایل‌های احراز هویت: چه هستند و چگونه آن‌ها را مدیریت کنید
مرتبط: [/concepts/oauth](/fa/concepts/oauth) (جریان‌های OAuth، ذخیره‌سازی توکن، الگوهای چندحسابی)
<AccordionGroup>
<Accordion title="پروفایل احراز هویت چیست؟">
پروفایل احراز هویت یک رکورد اعتبارنامه نام‌گذاری‌شده (OAuth یا کلید API) است که به یک ارائه‌دهنده متصل است. پروفایل‌ها در این مسیر قرار دارند:
پروفایل احراز هویت یک رکورد اعتبارنامه نام‌گذاری‌شده (OAuth یا کلید API) است که به یک ارائه‌دهنده متصل است. پروفایل‌ها در اینجا قرار دارند:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
برای بررسی پروفایل‌های ذخیره‌شده بدون افشای اسرار، `openclaw models auth list` را اجرا کنید (در صورت نیاز با `--provider <id>` یا `--json`). برای جزئیات، [CLI مدل‌ها](/fa/cli/models#openclaw-models-auth-list) را ببینید.
</Accordion>
<Accordion title="شناسه‌های رایج پروفایل چه هستند؟">
OpenClaw از شناسه‌های دارای پیشوند ارائه‌دهنده استفاده می‌کند، مانند:
<Accordion title="شناسه‌های معمول پروفایل چه هستند؟">
OpenClaw از شناسه‌های دارای پیشوند ارائه‌دهنده مانند این‌ها استفاده می‌کند:
- `anthropic:default` (وقتی هویت ایمیلی وجود ندارد رایج است)
- `anthropic:default` (رایج وقتی هویت ایمیلی وجود ندارد)
- `anthropic:<email>` برای هویت‌های OAuth
- شناسه‌های سفارشی که خودتان انتخاب می‌کنید (برای مثال `anthropic:work`)
- شناسه‌های سفارشی که انتخاب می‌کنید (مثلاً `anthropic:work`)
</Accordion>
<Accordion title="آیا می‌توانم کنترل کنم کدام پروفایل احراز هویت اول امتحان شود؟">
بله. پیکربندی از فراداده اختیاری برای پروفایل‌ها و یک ترتیب برای هر ارائه‌دهنده (`auth.order.<provider>`) پشتیبانی می‌کند. این کار رازها را ذخیره **نمی‌کند**؛ شناسه‌ها را به ارائه‌دهنده/حالت نگاشت می‌کند و ترتیب چرخش را تنظیم می‌کند.
<Accordion title="آیا می‌توانم کنترل کنم کدام پروفایل احراز هویت ابتدا امتحان شود؟">
بله. پیکربندی از فراداده اختیاری برای پروفایل‌ها و ترتیب‌بندی برای هر ارائه‌دهنده (`auth.order.<provider>`) پشتیبانی می‌کند. این مورد اسرار را ذخیره نمی‌کند؛ شناسه‌ها را به ارائه‌دهنده/حالت نگاشت می‌کند و ترتیب چرخش را تنظیم می‌کند.
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` گزارش می‌دهد.
</Accordion>
<Accordion title="OAuth در برابر کلید API - تفاوت چیست؟">
OpenClaw از هر دو پشتیبانی می‌کند:
- **OAuth** اغلب از دسترسی اشتراک استفاده می‌کند (در موارد قابل‌اعمال).
- **کلیدهای API** از صورتحساب پرداخت به‌ازای توکن استفاده می‌کنند.
- **OAuth** اغلب از دسترسی اشتراکی استفاده می‌کند (در موارد قابل اعمال).
- **کلیدهای API** از صورت‌حساب پرداخت به‌ازای توکن استفاده می‌کنند.
راهنمای مرحله‌ای به‌طور صریح از Anthropic Claude CLI، OpenAI Codex OAuth، و کلیدهای API پشتیبانی می‌کند.
راه‌انداز به‌طور صریح از Anthropic Claude CLI، OpenAI Codex OAuth و کلیدهای API پشتیبانی می‌کند.
</Accordion>
</AccordionGroup>
## مرتبط
- [پرسش‌های متداول](/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)

214
docs/fa/help/testing-updates-plugins.md
View File

@ -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 ترجیح دهید.

874
docs/fa/help/testing.md
View File

File diff suppressed because it is too large Load Diff

218
docs/fa/plugins/bundles.md
View File

@ -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 نگاشت می‌کند.
<Info>
بسته‌ها با Pluginهای بومی OpenClaw یکسان نیستند. Pluginهای بومی
درون‌فرایندی اجرا می‌شوند و می‌توانند هر قابلیتی را ثبت کنند. بسته‌ها بسته‌های محتوایی با
نگاشت انتخابی قابلیت‌ها و مرز اعتماد محدودتر هستند.
باندل‌ها همان Pluginهای بومی OpenClaw **نیستند**. Pluginهای بومی درون پردازش اجرا می‌شوند و می‌توانند هر قابلیتی را ثبت کنند. باندل‌ها بسته‌های محتوا هستند با نگاشت گزینشی قابلیت‌ها و مرز اعتماد محدودتر.
</Info>
## چرا بسته‌ها وجود دارند
## چرا باندل‌ها وجود دارند
بسیاری از Pluginهای مفید در قالب Codex، Claude، یا Cursor منتشر می‌شوند. به‌جای
اینکه نویسندگان مجبور شوند آن‌ها را به‌صورت Pluginهای بومی OpenClaw بازنویسی کنند، OpenClaw
این قالب‌ها را تشخیص می‌دهد و محتوای پشتیبانی‌شده آن‌ها را به مجموعه قابلیت‌های بومی
نگاشت می‌کند. این یعنی می‌توانید یک بسته فرمان Claude یا یک بسته Skills مربوط به Codex را نصب کنید
و بی‌درنگ از آن استفاده کنید.
بسیاری از Pluginهای مفید در قالب Codex، Claude یا Cursor منتشر می‌شوند. OpenClaw به‌جای اینکه از نویسندگان بخواهد آن‌ها را به‌صورت Pluginهای بومی OpenClaw بازنویسی کنند، این قالب‌ها را تشخیص می‌دهد و محتوای پشتیبانی‌شده آن‌ها را به مجموعه قابلیت‌های بومی نگاشت می‌کند. یعنی می‌توانید یک بسته فرمان Claude یا یک باندل Skill برای Codex را نصب کنید و بلافاصله از آن استفاده کنید.
## نصب یک بسته
## نصب یک باندل
<Steps>
<Step title="نصب از یک دایرکتوری، آرشیو، یا بازارچه">
<Step title="نصب از یک پوشه، آرشیو یا marketplace">
```bash
# Local directory
openclaw plugins install ./my-bundle
@ -56,71 +48,63 @@ OpenClaw آن‌ها را به قابلیت‌های بومی مانند Skills
openclaw plugins inspect <id>
```
بسته‌ها به‌صورت `Format: bundle` با زیرنوع `codex`، `claude`، یا `cursor` نمایش داده می‌شوند.
باندل‌ها با `Format: bundle` و یک زیرنوع از `codex`، `claude` یا `cursor` نمایش داده می‌شوند.
</Step>
<Step title="راه‌اندازی مجدد و استفاده">
<Step title="راه‌اندازی دوباره و استفاده">
```bash
openclaw gateway restart
```
قابلیت‌های نگاشت‌شده (Skills، هوک‌ها، ابزارهای MCP، پیش‌فرض‌های LSP) در نشست بعدی در دسترس هستند.
قابلیت‌های نگاشت‌شده (Skills، hookها، ابزارهای MCP، پیش‌فرض‌های LSP) در نشست بعدی در دسترس هستند.
</Step>
</Steps>
## 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 <id>` نمایش داده می‌شوند
- باندل‌های فعال Claude می‌توانند در پیکربندی سرور LSP مشارکت کنند
- OpenClaw فایل `.lsp.json` به‌علاوه هر مسیر `lspServers` اعلام‌شده در manifest را بارگذاری می‌کند
- پیکربندی LSP باندل در پیش‌فرض‌های مؤثر LSP برای Pi تعبیه‌شده ادغام می‌شود
- امروز فقط سرورهای LSP پشتیبانی‌شده مبتنی بر stdio قابل اجرا هستند؛ انتقال‌های پشتیبانی‌نشده همچنان در `openclaw plugins inspect <id>` نمایش داده می‌شوند
### تشخیص داده شده اما اجرا نمی‌شود
### تشخیص داده می‌شود اما اجرا نمی‌شود
این موارد شناسایی می‌شوند و در عیب‌یابی‌ها نمایش داده می‌شوند، اما 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 فراتر از گزارش قابلیت
## قالب‌های بسته
## قالب‌های باندل
<AccordionGroup>
<Accordion title="بسته‌های Codex">
<Accordion title="باندل‌های 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 دارند.
</Accordion>
<Accordion title="بسته‌های Claude">
<Accordion title="باندل‌های Claude">
دو حالت تشخیص:
- **مبتنی بر مانیفست:** `.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 افزایشی هستند (پیش‌فرض‌ها را گسترش می‌دهند، نه اینکه جایگزین آن‌ها شوند)
</Accordion>
<Accordion title="بسته‌های Cursor">
<Accordion title="باندل‌های Cursor">
نشانگرها: `.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` فقط تشخیص داده می‌شوند
</Accordion>
</AccordionGroup>
## تقدم تشخیص
## اولویت تشخیص
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 راه‌اندازی شوند
این باعث می‌شود بسته‌ها به‌صورت پیش‌فرض امن‌تر باشند، اما همچنان باید بسته‌های شخص ثالث
را برای قابلیت‌هایی که ارائه می‌کنند به‌عنوان محتوای قابل اعتماد در نظر بگیرید.
این باعث می‌شود باندل‌ها به‌صورت پیش‌فرض امن‌تر باشند، اما همچنان باید باندل‌های شخص ثالث را برای قابلیت‌هایی که ارائه می‌کنند به‌عنوان محتوای مورد اعتماد در نظر بگیرید.
## عیب‌یابی
<AccordionGroup>
<Accordion title="بسته تشخیص داده می‌شود اما قابلیت‌ها اجرا نمی‌شوند">
`openclaw plugins inspect <id>` را اجرا کنید. اگر قابلیتی فهرست شده اما به‌عنوان
متصل‌نشده علامت‌گذاری شده باشد، این یک محدودیت محصول است — نه نصب خراب.
<Accordion title="باندل تشخیص داده می‌شود اما قابلیت‌ها اجرا نمی‌شوند">
`openclaw plugins inspect <id>` را اجرا کنید. اگر قابلیتی فهرست شده اما با عنوان متصل‌نشده علامت‌گذاری شده باشد، این یک محدودیت محصول است، نه نصب خراب.
</Accordion>
<Accordion title="فایل‌های فرمان Claude ظاهر نمی‌شوند">
مطمئن شوید بسته فعال است و فایل‌های markdown داخل یک ریشه
`commands/` یا `skills/` تشخیص‌داده‌شده قرار دارند.
مطمئن شوید باندل فعال است و فایل‌های markdown داخل یک ریشه تشخیص‌داده‌شده `commands/` یا `skills/` قرار دارند.
</Accordion>
<Accordion title="تنظیمات Claude اعمال نمی‌شوند">
فقط تنظیمات Pi تعبیه‌شده از `settings.json` پشتیبانی می‌شوند. OpenClaw
تنظیمات بسته را به‌عنوان وصله‌های خام پیکربندی در نظر نمی‌گیرد.
فقط تنظیمات Pi تعبیه‌شده از `settings.json` پشتیبانی می‌شوند. OpenClaw تنظیمات باندل را به‌عنوان patchهای خام config در نظر نمی‌گیرد.
</Accordion>
<Accordion title="هوک‌های Claude اجرا نمی‌شوند">
`hooks/hooks.json` فقط تشخیص داده می‌شود. اگر به هوک‌های قابل اجرا نیاز دارید، از
چیدمان بسته هوک OpenClaw استفاده کنید یا یک Plugin بومی ارائه دهید.
<Accordion title="hookهای Claude اجرا نمی‌شوند">
`hooks/hooks.json` فقط تشخیص داده می‌شود. اگر به hookهای قابل اجرا نیاز دارید، از چیدمان بسته hook در OpenClaw استفاده کنید یا یک Plugin بومی عرضه کنید.
</Accordion>
</AccordionGroup>
@ -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

809
docs/fa/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

120
docs/fa/plugins/dependency-resolution.md
View File

@ -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 <spec> --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 <source>
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/<id>` بارگذاری می‌شوند تا وابستگی‌های workspace
محلی بسته در دسترس باشند و ویرایش‌ها مستقیماً اعمال شوند. توسعه checkout منبع فقط با pnpm پشتیبانی می‌شود؛ اجرای ساده `npm install` در ریشه مخزن
روش پشتیبانی‌شده‌ای برای آماده‌سازی وابستگی‌های Plugin همراه نیست.
در checkoutهای منبع، OpenClaw مخزن را به‌عنوان یک مونورپوی pnpm در نظر می‌گیرد. پس از
`pnpm install`، Pluginهای همراه از `extensions/<id>` بارگذاری می‌شوند تا وابستگی‌های
workspace محلی بسته در دسترس باشند و ویرایش‌ها مستقیماً اعمال شوند. توسعه checkout منبع
فقط با pnpm انجام می‌شود؛ اجرای ساده `npm install` در ریشه مخزن راه پشتیبانی‌شده‌ای
برای آماده‌سازی وابستگی‌های Plugin همراه نیست.
| شکل نصب | محل Plugin همراه | مالک وابستگی |
| شکل نصب | مکان Plugin همراه | مالک وابستگی |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | درخت زمان اجرای ساخته‌شده داخل بسته | بسته OpenClaw و جریان‌های صریح نصب/به‌روزرسانی/doctor برای Plugin |
| checkout با git به‌علاوه `pnpm install` | بسته‌های workspace در `extensions/<id>` | workspace مبتنی بر pnpm، شامل وابستگی‌های خود هر بسته Plugin |
| `openclaw plugins install ...` | ریشه Plugin مدیریت‌شده npm/git/ClawHub | جریان نصب/به‌روزرسانی Plugin |
| `npm install -g openclaw` | درخت زمان اجرای ساخته‌شده داخل بسته | بسته OpenClaw و جریان‌های صریح نصب/به‌روزرسانی/doctor برای Plugin |
| checkout گیت به‌علاوه `pnpm install` | بسته‌های workspace در `extensions/<id>` | 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 هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند.
این مسیرها فقط بقایای قدیمی هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند.

85
docs/fa/plugins/manage-plugins.md
View File

@ -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 <plugin-id> --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 <npm-package-or-spec>
openclaw plugins update --all
```
اگر Plugin از یک dist-tag متعلق به npm مانند `@beta` نصب شده باشد، فراخوانی‌های بعدی
`update <plugin-id>` از همان tag ثبت‌شده دوباره استفاده می‌کنند. دادن یک spec صریح npm
نصبِ دنبال‌شده را برای به‌روزرسانی‌های آینده به همان spec تغییر می‌دهد.
اگر Plugin از یک dist-tag مربوط به npm مانند `@beta` نصب شده باشد، فراخوانی‌های بعدی
`update <plugin-id>` همان 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 <plugin-id> --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:<package>
@ -143,8 +144,8 @@ openclaw plugins install <package>
### انتشار در 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) - مانیفست و فراداده‌ی بسته

141
docs/fa/providers/openrouter.md
View File

@ -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 پایه کار می‌کنند.
## شروع به کار
<Steps>
<Step title="کلید API خود را بگیرید">
یک کلید API در [openrouter.ai/keys](https://openrouter.ai/keys) بسازید.
<Step title="دریافت کلید API">
یک کلید API در [openrouter.ai/keys](https://openrouter.ai/keys) ایجاد کنید.
</Step>
<Step title="onboarding را اجرا کنید">
<Step title="اجرای راه‌اندازی اولیه">
```bash
openclaw onboard --auth-choice openrouter-api-key
```
</Step>
<Step title="(اختیاری) به یک مدل مشخص تغییر دهید">
مقدار پیش‌فرض onboarding برابر `openrouter/auto` است. بعدا یک مدل مشخص انتخاب کنید:
<Step title="(اختیاری) جابه‌جایی به یک مدل مشخص">
راه‌اندازی اولیه به‌صورت پیش‌فرض از `openrouter/auto` استفاده می‌کند. بعداً یک مدل مشخص انتخاب کنید:
```bash
openclaw models set openrouter/<provider>/<model>
@ -39,7 +39,7 @@ endpoint و کلید API واحد به مدل‌های زیادی مسیریاب
</Step>
</Steps>
## نمونه پیکربندی
## نمونهٔ پیکربندی
```json5
{
@ -56,10 +56,10 @@ endpoint و کلید API واحد به مدل‌های زیادی مسیریاب
<Note>
ارجاع‌های مدل از الگوی `openrouter/<provider>/<model>` پیروی می‌کنند. برای فهرست کامل
providerها و مدل‌های در دسترس، [/concepts/model-providers](/fa/concepts/model-providers) را ببینید.
ارائه‌دهندگان و مدل‌های در دسترس، [/concepts/model-providers](/fa/concepts/model-providers) را ببینید.
</Note>
نمونه‌های 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` |
<Warning>
اگر provider OpenRouter را به proxy یا URL پایه دیگری تغییر دهید، OpenClaw
آن headerهای ویژه OpenRouter یا نشانگرهای cache متعلق به Anthropic را تزریق **نمی‌کند**.
اگر ارائه‌دهندهٔ OpenRouter را به پراکسی یا URL پایهٔ دیگری اشاره دهید، OpenClaw
آن سرآیندهای ویژهٔ OpenRouter یا نشانگرهای کش Anthropic را تزریق **نمی‌کند**.
</Warning>
## پیکربندی پیشرفته
<AccordionGroup>
<Accordion title="cache کردن پاسخ">
cache کردن پاسخ در OpenRouter اختیاری است. آن را برای هر مدل OpenRouter با
<Accordion title="کش‌کردن پاسخ">
کش‌کردن پاسخ در 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های پایهٔ پراکسی سفارشی.
</Accordion>
<Accordion title="نشانگرهای cache متعلق به Anthropic">
در مسیرهای تاییدشده OpenRouter، ارجاع‌های مدل Anthropic نشانگرهای
ویژه OpenRouter یعنی `cache_control` متعلق به Anthropic را نگه می‌دارند که OpenClaw برای
استفاده مجدد بهتر از cache prompt روی بلوک‌های prompt سیستم/توسعه‌دهنده استفاده می‌کند.
<Accordion title="نشانگرهای کش Anthropic">
در مسیرهای تأییدشدهٔ OpenRouter، ارجاع‌های مدل Anthropic نشانگرهای ویژهٔ OpenRouter
یعنی `cache_control` مربوط به Anthropic را نگه می‌دارند که OpenClaw برای
استفادهٔ بهتر از کش پرامپت روی بلوک‌های پرامپت سیستم/توسعه‌دهنده به کار می‌برد.
</Accordion>
<Accordion title="prefill استدلال Anthropic">
در مسیرهای تاییدشده OpenRouter، ارجاع‌های مدل Anthropic با استدلال فعال،
turnهای پایانی prefill دستیار را پیش از رسیدن درخواست به OpenRouter حذف می‌کنند،
تا با الزام Anthropic که گفت‌وگوهای استدلال باید با یک turn کاربر پایان یابند هماهنگ باشد.
<Accordion title="پیش‌پرکردن استدلال Anthropic">
در مسیرهای تأییدشدهٔ OpenRouter، ارجاع‌های مدل Anthropic که استدلال در آن‌ها فعال است
نوبت‌های پیش‌پرشدهٔ انتهایی assistant را پیش از رسیدن درخواست به OpenRouter حذف می‌کنند،
مطابق با الزام Anthropic که گفت‌وگوهای استدلالی باید با نوبت کاربر پایان یابند.
</Accordion>
<Accordion title="تزریق thinking / reasoning">
در مسیرهای غیر `auto` پشتیبانی‌شده، OpenClaw سطح thinking انتخاب‌شده را به
payloadهای استدلال proxy متعلق به OpenRouter نگاشت می‌کند. راهنمایی‌های مدل پشتیبانی‌نشده و
<Accordion title="تزریق تفکر / استدلال">
در مسیرهای پشتیبانی‌شدهٔ غیر `auto`، OpenClaw سطح تفکر انتخاب‌شده را به
محموله‌های استدلال پراکسی OpenRouter نگاشت می‌کند. راهنمایی‌های مدل پشتیبانی‌نشده و
`openrouter/auto` آن تزریق استدلال را رد می‌کنند. Hunter Alpha همچنین
استدلال proxy را برای ارجاع‌های مدل پیکربندی‌شده قدیمی رد می‌کند، زیرا OpenRouter ممکن است
برای ارجاع‌های مدل پیکربندی‌شدهٔ قدیمی، استدلال پراکسی را رد می‌کند، زیرا OpenRouter ممکن است
برای آن مسیر بازنشسته، متن پاسخ نهایی را در فیلدهای استدلال برگرداند.
</Accordion>
<Accordion title="بازپخش استدلال DeepSeek V4">
در مسیرهای تاییدشده 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` نگاشت می‌شوند.
</Accordion>
<Accordion title="شکل‌دهی درخواست فقط OpenAI">
OpenRouter همچنان از مسیر سازگار با OpenAI به سبک proxy عبور می‌کند، بنابراین
شکل‌دهی درخواست بومی و فقط OpenAI مانند `serviceTier`، `store` در Responses،
payloadهای سازگار با استدلال OpenAI، و راهنمایی‌های cache prompt ارسال نمی‌شوند.
<Accordion title="شکل‌دهی درخواست فقط مخصوص OpenAI">
OpenRouter همچنان از مسیر سازگار با OpenAI به سبک پراکسی عبور می‌کند، بنابراین
شکل‌دهی درخواست بومی و فقط مخصوص OpenAI مانند `serviceTier`، مقدار `store` در Responses،
محموله‌های سازگاری استدلال OpenAI و راهنمایی‌های کش پرامپت ارسال نمی‌شود.
</Accordion>
<Accordion title="مسیرهای مبتنی بر Gemini">
ارجاع‌های OpenRouter مبتنی بر Gemini روی مسیر proxy-Gemini باقی می‌مانند: OpenClaw پاک‌سازی
thought-signature متعلق به Gemini را در آنجا حفظ می‌کند، اما اعتبارسنجی بازپخش بومی Gemini
یا بازنویسی‌های bootstrap را فعال نمی‌کند.
<Accordion title="مسیرهای پشتوانه‌دار با Gemini">
ارجاع‌های OpenRouter که پشتوانهٔ Gemini دارند روی مسیر پراکسی-Gemini می‌مانند: OpenClaw
پاک‌سازی امضای تفکر Gemini را در آنجا نگه می‌دارد، اما اعتبارسنجی بازپخش بومی Gemini
یا بازنویسی‌های بوت‌استرپ را فعال نمی‌کند.
</Accordion>
<Accordion title="فراداده مسیریابی provider">
اگر مسیریابی provider متعلق به OpenRouter را زیر پارامترهای مدل پاس دهید، OpenClaw
پیش از اجرای wrapperهای stream مشترک، آن را به‌عنوان فراداده مسیریابی OpenRouter ارسال می‌کند.
<Accordion title="فرادادهٔ مسیریابی ارائه‌دهنده">
اگر مسیریابی ارائه‌دهندهٔ OpenRouter را زیر پارامترهای مدل ارسال کنید، OpenClaw
آن را پیش از اجرای wrapperهای جریان مشترک، به‌عنوان فرادادهٔ مسیریابی OpenRouter ارسال می‌کند.
</Accordion>
</AccordionGroup>
@ -238,9 +243,9 @@ headerهای مستندشده انتساب برنامه OpenRouter را اضاف
<CardGroup cols={2}>
<Card title="انتخاب مدل" href="/fa/concepts/model-providers" icon="layers">
انتخاب providerها، ارجاع‌های مدل، و رفتار failover.
انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover.
</Card>
<Card title="مرجع پیکربندی" href="/fa/gateway/configuration-reference" icon="gear">
مرجع کامل پیکربندی برای agentها، مدل‌ها، و providerها.
مرجع کامل پیکربندی برای عامل‌ها، مدل‌ها، و ارائه‌دهندگان.
</Card>
</CardGroup>

597
docs/fa/reference/RELEASING.md
View File

@ -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<package.json version>` را 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<package.json version>` را می‌سازد؛ انتشار واقعی همچنان به 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 <full-sha>
```
helper مقدار `release-ci/<sha>-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=<sha>` dispatch می‌کند، بررسی می‌کند که `headSha` هر workflow فرزند با هدف مطابقت داشته باشد، سپس branch موقت را حذف می‌کند. این کار از اثبات تصادفی یک اجرای فرزند جدیدتر روی `main` جلوگیری می‌کند.
این helper، `release-ci/<sha>-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=<sha>` 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=<release-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>` استفاده نکنید؛
SHAهای خام commit نمی‌توانند refهای workflow dispatch باشند، پس از
`pnpm ci:full-release --sha <sha>` برای ساخت شاخه‌ی موقت pinned استفاده کنید.
گردش‌کار ارجاع هدف را حل می‌کند، `CI` دستی را با
`target_ref=<release-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>` استفاده نکنید؛
SHAهای خام کامیت نمی‌توانند ارجاع dispatch گردش‌کار باشند، پس از
`pnpm ci:full-release --sha <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=<lane[,lane]>` استفاده کنید. دستورهای rerun تولیدشده وقتی موجود باشند شامل
`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده‌ی Docker هستند، تا یک
lane fail‌شده بتواند از همان tarball و imageهای GHCR دوباره استفاده کند.
پیش از اجرای دوباره، از آرتیفکت‌های Docker استفاده کنید. زمان‌بند مسیر انتشار
`.artifacts/docker-tests/` را با لاگ‌های مسیر، `summary.json`، `failures.json`،
زمان‌بندی فازها، JSON طرح زمان‌بند، و فرمان‌های اجرای دوباره بارگذاری می‌کند. برای بازیابی متمرکز،
به‌جای اجرای دوباره همه قطعه‌های انتشار، از `docker_lanes=<lane[,lane]>` روی گردش‌کار زنده/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=<release-sha>` 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)

194
docs/fa/reference/full-release-validation.md
View File

@ -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`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** شاخه انتشار، برچسب، یا SHA کامل commit را حل می‌کند و ورودی‌های انتخاب‌شده را ثبت می‌کند.<br />**بازاجرا:** اگر این مورد شکست خورد، چتر را بازاجرا کنید. |
| Vitest و CI عادی | **کار:** `Run normal full CI`<br />**گردش‌کار فرزند:** `CI`<br />**اثبات می‌کند:** گراف CI کامل دستی را در برابر ارجاع هدف، شامل مسیرهای Linux Node، شاردهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Skills پایتون، Windows، macOS، i18n رابط کاربری کنترل، و Android از طریق چتر.<br />**بازاجرا:** `rerun_group=ci`. |
| پیش‌انتشار Plugin | **کار:** `Run plugin prerelease validation`<br />**گردش‌کار فرزند:** `Plugin Prerelease`<br />**اثبات می‌کند:** بررسی‌های ایستای Plugin مخصوص انتشار، پوشش Plugin عاملی، شاردهای دسته‌ای کامل extension، و مسیرهای Docker پیش‌انتشار Plugin.<br />**بازاجرا:** `rerun_group=plugin-prerelease`. |
| بررسی‌های انتشار | **کار:** `Run release/live/Docker/QA validation`<br />**گردش‌کار فرزند:** `OpenClaw Release Checks`<br />**اثبات می‌کند:** smoke نصب، بررسی‌های بسته میان‌سیستمی، مجموعه‌های live/E2E، تکه‌های مسیر انتشار Docker، Package Acceptance، هم‌ارزی QA Lab، Matrix زنده، و Telegram زنده.<br />**بازاجرا:** `rerun_group=release-checks` یا یک handle محدودتر release-checks. |
| artifact بسته | **کار:** `Prepare release package artifact`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** tarball والد `release-package-under-test` را به‌اندازه کافی زود می‌سازد تا بررسی‌های بسته‌محور که نیازی به انتظار برای `OpenClaw Release Checks` ندارند اجرا شوند.<br />**بازاجرا:** چتر را بازاجرا کنید یا برای `rerun_group=npm-telegram` مقدار `npm_telegram_package_spec` را فراهم کنید. |
| بسته Telegram | **کار:** `Run package Telegram E2E`<br />**گردش‌کار فرزند:** `NPM Telegram Beta E2E`<br />**اثبات می‌کند:** اثبات بسته Telegram مبتنی بر artifact والد برای `rerun_group=all` همراه با `release_profile=full`، یا اثبات Telegram بسته منتشرشده وقتی `npm_telegram_package_spec` تنظیم شده باشد.<br />**بازاجرا:** `rerun_group=npm-telegram` همراه با `npm_telegram_package_spec`. |
| اعتبارسنج چتر | **کار:** `Verify full validation`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** نتیجه‌های ثبت‌شده اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کارها را از گردش‌کارهای فرزند پیوست می‌کند.<br />**بازاجرا:** پس از سبز کردن یک فرزند ناموفق، فقط همین کار را بازاجرا کنید. |
## مرحله‌های سطح بالا
| مرحله | جزئیات |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| حل هدف | **کار:** `Resolve target ref`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** شاخه انتشار، برچسب، یا SHA کامل commit را حل می‌کند و ورودی‌های انتخاب‌شده را ثبت می‌کند.<br />**اجرای دوباره:** اگر این مورد ناموفق شد، چتر را دوباره اجرا کنید. |
| Vitest و CI عادی | **کار:** `Run normal full CI`<br />**گردش‌کار فرزند:** `CI`<br />**اثبات می‌کند:** گراف CI کامل دستی را روی ارجاع هدف اجرا می‌کند، شامل مسیرهای Linux Node، shardهای Plugin همراه، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Python skills، Windows، macOS، i18n Control UI، و Android از طریق چتر.<br />**اجرای دوباره:** `rerun_group=ci`. |
| پیش‌انتشار Plugin | **کار:** `Run plugin prerelease validation`<br />**گردش‌کار فرزند:** `Plugin Prerelease`<br />**اثبات می‌کند:** بررسی‌های ایستای فقط انتشار برای Plugin، پوشش Plugin عاملی، shardهای دسته کامل extension، و مسیرهای Docker پیش‌انتشار Plugin.<br />**اجرای دوباره:** `rerun_group=plugin-prerelease`. |
| بررسی‌های انتشار | **کار:** `Run release/live/Docker/QA validation`<br />**گردش‌کار فرزند:** `OpenClaw Release Checks`<br />**اثبات می‌کند:** smoke نصب، بررسی‌های package میان‌سیستمی، Package Acceptance، هم‌ارزی QA Lab، Matrix زنده، و Telegram زنده. با `run_release_soak=true` یا `release_profile=full`، مجموعه‌های کامل زنده/E2E و قطعه‌های مسیر انتشار Docker را نیز اجرا می‌کند.<br />**اجرای دوباره:** `rerun_group=release-checks` یا یک handle محدودتر release-checks. |
| artifact مربوط به package | **کار:** `Prepare release package artifact`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** tarball والد `release-package-under-test` را آن‌قدر زود ایجاد می‌کند که بررسی‌های روبه‌package که نیاز ندارند منتظر `OpenClaw Release Checks` بمانند، بتوانند از آن استفاده کنند.<br />**اجرای دوباره:** چتر را دوباره اجرا کنید یا برای `rerun_group=npm-telegram` مقدار `npm_telegram_package_spec` را ارائه دهید. |
| Package Telegram | **کار:** `Run package Telegram E2E`<br />**گردش‌کار فرزند:** `NPM Telegram Beta E2E`<br />**اثبات می‌کند:** اثبات package Telegram مبتنی بر artifact والد برای `rerun_group=all` با `release_profile=full`، یا اثبات Telegram برای package منتشرشده وقتی `npm_telegram_package_spec` تنظیم شده باشد.<br />**اجرای دوباره:** `rerun_group=npm-telegram` با `npm_telegram_package_spec`. |
| تأییدکننده چتر | **کار:** `Verify full validation`<br />**گردش‌کار فرزند:** هیچ‌کدام<br />**اثبات می‌کند:** نتیجه‌های ثبت‌شده اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کارها را از گردش‌کارهای فرزند اضافه می‌کند.<br />**اجرای دوباره:** پس از اینکه یک فرزند ناموفق را دوباره اجرا کردید تا سبز شود، فقط همین کار را دوباره اجرا کنید. |
برای `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`<br />**گردش‌کار پشتیبان:** هیچ‌کدام<br />**آزمون‌ها:** ارجاع انتخاب‌شده، SHA مورد انتظار اختیاری، پروفایل، گروه بازاجرا، و فیلتر مجموعه live متمرکز.<br />**بازاجرا:** `rerun_group=release-checks`. |
| artifact بسته | **کار:** `Prepare release package artifact`<br />**گردش‌کار پشتیبان:** هیچ‌کدام<br />**آزمون‌ها:** یک tarball نامزد را بسته‌بندی یا حل می‌کند و `release-package-under-test` را برای بررسی‌های پایین‌دستی بسته‌محور بارگذاری می‌کند.<br />**بازاجرا:** گروه بسته، میان‌سیستمی، یا live/E2E تحت تأثیر. |
| smoke نصب | **کار:** `Run install smoke`<br />**گردش‌کار پشتیبان:** `Install Smoke`<br />**آزمون‌ها:** مسیر نصب کامل با استفاده دوباره از تصویر smoke ریشه Dockerfile، نصب بسته QR، smokeهای Docker ریشه و Gateway، آزمون‌های Docker نصب‌کننده، smoke ارائه‌دهنده تصویر نصب سراسری Bun، و E2E سریع نصب/حذف نصب Pluginهای بسته‌بندی‌شده.<br />**بازاجرا:** `rerun_group=install-smoke`. |
| میان‌سیستمی | **کار:** `cross_os_release_checks`<br />**گردش‌کار پشتیبان:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**آزمون‌ها:** مسیرهای تازه و ارتقا روی Linux، Windows، و macOS برای ارائه‌دهنده و حالت انتخاب‌شده، با استفاده از tarball نامزد به‌همراه یک بسته مبنا.<br />**بازاجرا:** `rerun_group=cross-os`. |
| مخزن و live E2E | **کار:** `Run repo/live E2E validation`<br />**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`<br />**آزمون‌ها:** E2E مخزن، cache زنده، streaming websocket OpenAI، شاردهای ارائه‌دهنده و Plugin زنده native، و ابزارهای مدل/backend/Gateway زنده مبتنی بر Docker که با `release_profile` انتخاب می‌شوند.<br />**بازاجرا:** `rerun_group=live-e2e`، به‌صورت اختیاری همراه با `live_suite_filter`. |
| مسیر انتشار Docker | **کار:** `Run Docker release-path validation`<br />**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`<br />**آزمون‌ها:** تکه‌های Docker مسیر انتشار در برابر artifact بسته مشترک.<br />**بازاجرا:** `rerun_group=live-e2e`. |
| Package Acceptance | **کار:** `Run package acceptance`<br />**گردش‌کار پشتیبان:** `Package Acceptance`<br />**آزمون‌ها:** fixtureهای بسته Plugin آفلاین، به‌روزرسانی Plugin، پذیرش بسته Telegram با mock-OpenAI، و بررسی‌های survivor ارتقای منتشرشده از هر انتشار npm پایدار در یا پس از `2026.4.23` در برابر همان tarball.<br />**بازاجرا:** `rerun_group=package`. |
| هم‌ارزی QA | **کار:** `Run QA Lab parity lane` و `Run QA Lab parity report`<br />**گردش‌کار پشتیبان:** کارهای مستقیم<br />**آزمون‌ها:** بسته‌های هم‌ارزی عاملی نامزد و مبنا، سپس گزارش هم‌ارزی.<br />**بازاجرا:** `rerun_group=qa-parity` یا `rerun_group=qa`. |
| QA live Matrix | **کار:** `Run QA Lab live Matrix lane`<br />**گردش‌کار پشتیبان:** کار مستقیم<br />**آزمون‌ها:** پروفایل QA سریع Matrix زنده در محیط `qa-live-shared`.<br />**بازاجرا:** `rerun_group=qa-live` یا `rerun_group=qa`. |
| QA live Telegram | **کار:** `Run QA Lab live Telegram lane`<br />**گردش‌کار پشتیبان:** کار مستقیم<br />**آزمون‌ها:** QA زنده Telegram با leaseهای اعتبارنامه Convex CI.<br />**بازاجرا:** `rerun_group=qa-live` یا `rerun_group=qa`. |
| اعتبارسنج انتشار | **کار:** `Verify release checks`<br />**گردش‌کار پشتیبان:** هیچ‌کدام<br />**آزمون‌ها:** کارهای الزامی release-check برای گروه بازاجرای انتخاب‌شده.<br />**بازاجرا:** پس از موفقیت کارهای فرزند متمرکز بازاجرا کنید. |
| مرحله | جزئیات |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| هدف انتشار | **Job:** `Resolve target ref`<br />**گردش‌کار پشتیبان:** ندارد<br />**آزمون‌ها:** ref انتخاب‌شده، SHA مورد انتظار اختیاری، نمایه، گروه اجرای دوباره، و فیلتر متمرکز مجموعه live.<br />**اجرای دوباره:** `rerun_group=release-checks`. |
| مصنوعه بسته | **Job:** `Prepare release package artifact`<br />**گردش‌کار پشتیبان:** ندارد<br />**آزمون‌ها:** یک tarball نامزد را بسته‌بندی یا حل می‌کند و `release-package-under-test` را برای بررسی‌های پایین‌دستیِ مرتبط با بسته بارگذاری می‌کند.<br />**اجرای دوباره:** گروه بسته، cross-OS، یا live/E2E متأثر. |
| smoke نصب | **Job:** `Run install smoke`<br />**گردش‌کار پشتیبان:** `Install Smoke`<br />**آزمون‌ها:** مسیر کامل نصب با استفاده مجدد از تصویر smoke در Dockerfile ریشه، نصب بسته QR، smokeهای Docker ریشه و Gateway، آزمون‌های Docker نصب‌کننده، smoke نصب سراسری Bun برای image-provider، و E2E سریع نصب/حذف Pluginهای همراه.<br />**اجرای دوباره:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**گردش‌کار پشتیبان:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**آزمون‌ها:** مسیرهای تازه و ارتقا روی Linux، Windows، و macOS برای provider و حالت انتخاب‌شده، با استفاده از tarball نامزد به‌همراه یک بسته مبنا.<br />**اجرای دوباره:** `rerun_group=cross-os`. |
| E2E مخزن و live | **Job:** `Run repo/live E2E validation`<br />**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`<br />**آزمون‌ها:** E2E مخزن، کش live، استریم websocket OpenAI، provider live بومی و shardهای Plugin، و harnessهای live مبتنی بر Docker برای model/backend/gateway که با `release_profile` انتخاب می‌شوند.<br />**اجراها:** `run_release_soak=true`، `release_profile=full`، یا `rerun_group=live-e2e` متمرکز.<br />**اجرای دوباره:** `rerun_group=live-e2e`، به‌صورت اختیاری با `live_suite_filter`. |
| مسیر انتشار Docker | **Job:** `Run Docker release-path validation`<br />**گردش‌کار پشتیبان:** `OpenClaw Live And E2E Checks (Reusable)`<br />**آزمون‌ها:** chunkهای Docker مسیر انتشار در برابر مصنوعه بسته مشترک.<br />**اجراها:** `run_release_soak=true`، `release_profile=full`، یا `rerun_group=live-e2e` متمرکز.<br />**اجرای دوباره:** `rerun_group=live-e2e`. |
| پذیرش بسته | **Job:** `Run package acceptance`<br />**گردش‌کار پشتیبان:** `Package Acceptance`<br />**آزمون‌ها:** fixtureهای آفلاین بسته Plugin، به‌روزرسانی Plugin، پذیرش بسته Telegram با mock-OpenAI، و بررسی‌های دوام ارتقای منتشرشده در برابر همان tarball. بررسی‌های مسدودکننده انتشار از مبنای پیش‌فرض آخرین نسخه منتشرشده استفاده می‌کنند؛ بررسی‌های soak به همه انتشارهای پایدار npm در یا بعد از `2026.4.23` به‌همراه fixtureهای مسئله گزارش‌شده گسترش می‌یابند.<br />**اجرای دوباره:** `rerun_group=package`. |
| همسانی QA | **Job:** `Run QA Lab parity lane` و `Run QA Lab parity report`<br />**گردش‌کار پشتیبان:** jobهای مستقیم<br />**آزمون‌ها:** بسته‌های همسانی agentic نامزد و مبنا، سپس گزارش همسانی.<br />**اجرای دوباره:** `rerun_group=qa-parity` یا `rerun_group=qa`. |
| Matrix live در QA | **Job:** `Run QA Lab live Matrix lane`<br />**گردش‌کار پشتیبان:** job مستقیم<br />**آزمون‌ها:** نمایه سریع QA live در Matrix در محیط `qa-live-shared`.<br />**اجرای دوباره:** `rerun_group=qa-live` یا `rerun_group=qa`. |
| Telegram live در QA | **Job:** `Run QA Lab live Telegram lane`<br />**گردش‌کار پشتیبان:** job مستقیم<br />**آزمون‌ها:** QA live در Telegram با leaseهای credential در Convex CI.<br />**اجرای دوباره:** `rerun_group=qa-live` یا `rerun_group=qa`. |
| تأییدکننده انتشار | **Job:** `Verify release checks`<br />**گردش‌کار پشتیبان:** ندارد<br />**آزمون‌ها:** jobهای ضروری release-check برای گروه اجرای دوباره انتخاب‌شده.<br />**اجرای دوباره:** پس از گذر 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=<lane[,lane]>` هدفمند استفاده کنید. artifactهای انتشار، در صورت در دسترس بودن، شامل دستورهای rerun به‌ازای هر lane همراه با ورودی‌های استفادهٔ دوباره از artifact بسته و image هستند.
وقتی فقط یک مسیر Docker شکست خورده است، از `docker_lanes=<lane[,lane]>` هدفمند روی گردش‌کار 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`

124
docs/fa/reference/test.md
View File

File diff suppressed because one or more lines are too long

206
docs/fa/reference/transcript-hygiene.md
View File

@ -1,215 +1,181 @@
---
read_when:
- در حال اشکال‌زدایی رد شدن درخواست‌های ارائه‌دهنده‌ی مرتبط با شکل رونوشت هستید
- شما در حال تغییر منطق پاک‌سازی رونوشت یا ترمیم فراخوانی ابزار هستید
- شما در حال بررسی ناهماهنگی‌های شناسهٔ فراخوانی ابزار در میان ارائه‌دهندگان هستید.
summary: 'مرجع: قواعد پاک‌سازی و ترمیم رونوشت مختص ارائه‌دهنده'
title: بهداشت رونوشت
- در حال اشکال‌زدایی رد شدن درخواست‌های ارائه‌دهنده مرتبط با شکل رونوشت هستید
- شما در حال تغییر پاک‌سازی رونوشت یا منطق ترمیم فراخوانی ابزار هستید
- شما در حال بررسی ناهماهنگی‌های شناسهٔ فراخوانی ابزار در میان ارائه‌دهندگان هستید
summary: 'مرجع: قواعد پاک‌سازی و ترمیم رونوشت ویژهٔ ارائه‌دهنده'
title: پاکیزگی رونوشت
x-i18n:
generated_at: "2026-05-03T11:45:07Z"
generated_at: "2026-05-05T01:51:57Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
OpenClaw پیش از اجرای یک run (ساختن context مدل)، **اصلاحات ویژه‌ی provider** را روی transcriptها اعمال می‌کند. بیشتر این‌ها تنظیمات **درون‌حافظه‌ای** هستند که برای برآورده کردن الزامات سخت‌گیرانه‌ی provider استفاده می‌شوند. یک گذر جداگانه‌ی repair برای فایل session نیز ممکن است JSONL ذخیره‌شده را پیش از بارگذاری session بازنویسی کند، اما فقط برای خط‌های بدشکل یا turnهای پایدارشده‌ای که رکوردهای durable نامعتبر هستند. پاسخ‌های تحویل‌داده‌شده‌ی assistant روی دیسک حفظ می‌شوند؛ حذف prefill ویژه‌ی provider برای assistant فقط هنگام ساخت payloadهای خروجی انجام می‌شود. وقتی repair رخ می‌دهد، فایل اصلی در کنار فایل session پشتیبان‌گیری می‌شود.
OpenClaw پیش از یک اجرا، هنگام ساختن بافت مدل، **اصلاحات مخصوص ارائه‌دهنده** را روی رونوشت‌ها اعمال می‌کند. بیشتر این موارد تنظیمات **در حافظه** هستند که برای برآورده کردن الزامات سخت‌گیرانهٔ ارائه‌دهنده استفاده می‌شوند. یک مرحلهٔ جداگانهٔ ترمیم فایل نشست نیز ممکن است پیش از بارگذاری نشست، JSONL ذخیره‌شده را بازنویسی کند، اما فقط برای خطوط بدشکل یا نوبت‌های ماندگاری که رکوردهای پایدار نامعتبر هستند. پاسخ‌های تحویل‌داده‌شدهٔ دستیار روی دیسک حفظ می‌شوند؛ حذف پیش‌پرکردن دستیار مخصوص ارائه‌دهنده فقط هنگام ساخت payloadهای خروجی انجام می‌شود. وقتی ترمیمی انجام شود، از فایل اصلی در کنار فایل نشست پشتیبان گرفته می‌شود.
دامنه شامل موارد زیر است:
دامنه شامل این موارد است:
- بیرون ماندن context فقط-زمان‌اجرا از turnهای transcript قابل‌مشاهده برای کاربر
- پاک‌سازی id فراخوانی ابزار
- بیرون ماندن بافت prompt فقط زمان اجرا از نوبت‌های رونوشت قابل مشاهده برای کاربر
- پاک‌سازی شناسهٔ فراخوانی ابزار
- اعتبارسنجی ورودی فراخوانی ابزار
- repair جفت‌سازی نتیجه‌ی ابزار
- اعتبارسنجی / ترتیب‌دهی turn
- پاک‌سازی امضای thought
- پاک‌سازی امضای thinking
- ترمیم جفت‌سازی نتیجهٔ ابزار
- اعتبارسنجی / ترتیب‌دهی نوبت‌ها
- پاک‌سازی امضای فکر
- پاک‌سازی امضای تفکر
- پاک‌سازی payload تصویر
- پاک‌سازی بلوک‌های متنی خالی پیش از replay توسط provider
- برچسب‌گذاری منشأ ورودی کاربر (برای promptهای مسیریابی‌شده بین sessionها)
- repair turn خطای assistant خالی برای replay در Bedrock Converse
- پاک‌سازی بلوک‌های متنی خالی پیش از بازپخش ارائه‌دهنده
- برچسب‌گذاری منشأ ورودی کاربر، برای promptهای مسیریابی‌شده بین نشست‌ها
- ترمیم نوبت خطای خالی دستیار برای بازپخش Bedrock Converse
اگر به جزئیات ذخیره‌سازی transcript نیاز دارید، ببینید:
اگر به جزئیات ذخیره‌سازی رونوشت نیاز دارید، ببینید:
- [بررسی عمیق مدیریت session](/fa/reference/session-management-compaction)
- [بررسی عمیق مدیریت نشست](/fa/reference/session-management-compaction)
---
## قاعده‌ی سراسری: context زمان‌اجرا transcript کاربر نیست
## قاعدهٔ سراسری: بافت زمان اجرا رونوشت کاربر نیست
context زمان‌اجرا/system می‌تواند برای یک turn به prompt مدل افزوده شود، اما
محتوای نوشته‌شده توسط کاربر نهایی نیست. OpenClaw یک بدنه‌ی prompt جداگانه‌ی
روبه‌transcript برای پاسخ‌های Gateway، followupهای صف‌شده، ACP، CLI، و runهای
Pi تعبیه‌شده نگه می‌دارد. turnهای کاربرِ قابل‌مشاهده‌ی ذخیره‌شده به‌جای prompt
غنی‌شده با زمان‌اجرا، از همان بدنه‌ی transcript استفاده می‌کنند.
بافت زمان اجرا/سیستم می‌تواند برای یک نوبت به prompt مدل اضافه شود، اما محتوایی نیست که کاربر نهایی نوشته باشد. OpenClaw برای پاسخ‌های Gateway، پیگیری‌های صف‌شده، ACP، CLI، و اجراهای Pi تعبیه‌شده، بدنهٔ prompt جداگانه‌ای مخصوص رونوشت نگه می‌دارد. نوبت‌های قابل مشاهدهٔ کاربر که ذخیره می‌شوند، به‌جای prompt غنی‌شده با زمان اجرا، از همان بدنهٔ رونوشت استفاده می‌کنند.
برای sessionهای قدیمی که از قبل wrapperهای زمان‌اجرا را پایدار کرده‌اند، سطح‌های
history در Gateway پیش از برگرداندن پیام‌ها به کلاینت‌های WebChat، TUI، REST، یا SSE
یک نمایش projection اعمال می‌کنند.
برای نشست‌های قدیمی که از قبل wrapperهای زمان اجرا را ذخیره کرده‌اند، سطح‌های تاریخچهٔ Gateway پیش از بازگرداندن پیام‌ها به کلاینت‌های WebChat، TUI، REST، یا SSE یک projection نمایشی اعمال می‌کنند.
---
## محل اجرای این فرایند
## محل اجرای این منطق
تمام بهداشت transcript در runner تعبیه‌شده متمرکز شده است:
تمام بهداشت رونوشت در runner تعبیه‌شده متمرکز شده است:
- انتخاب policy: `src/agents/transcript-policy.ts`
- اعمال پاک‌سازی/repair: `sanitizeSessionHistory` در `src/agents/pi-embedded-runner/replay-history.ts`
- اعمال پاک‌سازی/ترمیم: `sanitizeSessionHistory` در `src/agents/pi-embedded-runner/replay-history.ts`
policy از `provider`، `modelApi`، و `modelId` استفاده می‌کند تا تصمیم بگیرد چه چیزی اعمال شود.
این policy از `provider`، `modelApi`، و `modelId` برای تصمیم‌گیری دربارهٔ موارد قابل اعمال استفاده می‌کند.
جدا از بهداشت transcript، فایل‌های session پیش از load شدن repair می‌شوند (در صورت نیاز):
جدا از بهداشت رونوشت، فایل‌های نشست پیش از بارگذاری، در صورت نیاز، ترمیم می‌شوند:
- `repairSessionFileIfNeeded` در `src/agents/session-file-repair.ts`
- از `run/attempt.ts` و `compact.ts` فراخوانی می‌شود (runner تعبیه‌شده)
- فراخوانی‌شده از `run/attempt.ts` و `compact.ts`، در runner تعبیه‌شده
---
## قاعده‌ی سراسری: پاک‌سازی تصویر
## قاعدهٔ سراسری: پاک‌سازی تصویر
payloadهای تصویر همیشه پاک‌سازی می‌شوند تا به‌دلیل محدودیت‌های اندازه
(downscale/recompress تصاویر base64 بیش‌ازحد بزرگ)، از رد شدن در سمت provider جلوگیری شود.
payloadهای تصویر همیشه پاک‌سازی می‌شوند تا از رد شدن در سمت ارائه‌دهنده به‌دلیل محدودیت‌های اندازه جلوگیری شود، از جمله کوچک‌سازی/فشرده‌سازی دوبارهٔ تصویرهای base64 بیش‌ازحد بزرگ.
این کار همچنین به کنترل فشار token ناشی از تصویر برای مدل‌های دارای قابلیت vision کمک می‌کند.
ابعاد حداکثری پایین‌تر عموما مصرف token را کاهش می‌دهد؛ ابعاد بالاتر جزئیات را حفظ می‌کند.
این کار همچنین به کنترل فشار token ناشی از تصویر برای مدل‌های دارای قابلیت vision کمک می‌کند. ابعاد حداکثر پایین‌تر معمولاً مصرف token را کاهش می‌دهند؛ ابعاد بالاتر جزئیات را حفظ می‌کنند.
پیاده‌سازی:
- `sanitizeSessionMessagesImages` در `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` در `src/agents/tool-images.ts`
- بیشینه‌ی ضلع تصویر از طریق `agents.defaults.imageMaxDimensionPx` قابل پیکربندی است (پیش‌فرض: `1200`).
- درحالی‌که این گذر محتوای replay را پیمایش می‌کند، بلوک‌های متنی خالی حذف می‌شوند. turnهای assistant
که خالی می‌شوند از کپی replay حذف می‌شوند؛ turnهای user و tool-result
که خالی می‌شوند یک placeholder غیرخالی برای محتوای حذف‌شده دریافت می‌کنند.
- حداکثر ضلع تصویر از طریق `agents.defaults.imageMaxDimensionPx` قابل پیکربندی است، با مقدار پیش‌فرض `1200`.
- بلوک‌های متنی خالی هنگام پیمایش محتوای بازپخش در این مرحله حذف می‌شوند. نوبت‌های دستیار که خالی می‌شوند از نسخهٔ بازپخش حذف می‌شوند؛ نوبت‌های کاربر و نتیجهٔ ابزار که خالی می‌شوند یک placeholder غیرخالی برای محتوای حذف‌شده دریافت می‌کنند.
---
## قاعده‌ی سراسری: فراخوانی‌های ابزار بدشکل
## قاعدهٔ سراسری: فراخوانی‌های بدشکل ابزار
بلوک‌های فراخوانی ابزار assistant که هم `input` و هم `arguments` را ندارند، پیش از ساخته شدن
context مدل حذف می‌شوند. این کار از رد شدن توسط provider به‌خاطر فراخوانی‌های ابزار نیمه‌پایدارشده
جلوگیری می‌کند (برای مثال، پس از خطای rate limit).
بلوک‌های فراخوانی ابزار دستیار که هم `input` و هم `arguments` را ندارند، پیش از ساخته شدن بافت مدل حذف می‌شوند. این کار از رد شدن توسط ارائه‌دهنده به‌دلیل فراخوانی‌های ابزار نیمه‌ذخیره‌شده جلوگیری می‌کند، برای مثال پس از شکست ناشی از محدودیت نرخ.
پیاده‌سازی:
- `sanitizeToolCallInputs` در `src/agents/session-transcript-repair.ts`
- در `sanitizeSessionHistory` در `src/agents/pi-embedded-runner/replay-history.ts` اعمال می‌شود
- اعمال‌شده در `sanitizeSessionHistory` در `src/agents/pi-embedded-runner/replay-history.ts`
---
## قاعده‌ی سراسری: منشأ ورودی بین sessionها
## قاعدهٔ سراسری: منشأ ورودی بین نشست‌ها
وقتی یک agent از طریق `sessions_send` یک prompt را به session دیگری می‌فرستد (از جمله
گام‌های پاسخ/اعلان agent-to-agent)، OpenClaw turn کاربر ساخته‌شده را با این مقدار پایدار می‌کند:
وقتی یک agent از طریق `sessions_send` یک prompt را به نشست دیگری می‌فرستد، از جمله مراحل پاسخ/اعلان agent به agent، OpenClaw نوبت کاربر ایجادشده را با این مقدار ذخیره می‌کند:
- `message.provenance.kind = "inter_session"`
OpenClaw همچنین پیش از متن prompt مسیریابی‌شده، در همان turn یک نشانگر
`[Inter-session message ... isUser=false]` اضافه می‌کند تا فراخوانی مدل فعال بتواند
خروجی session خارجی را از دستورهای کاربر نهایی بیرونی تشخیص دهد. این نشانگر در صورت وجود
شامل session مبدأ، کانال، و ابزار است. transcript همچنان برای سازگاری با provider از
`role: "user"` استفاده می‌کند، اما هم متن قابل‌مشاهده و هم metadata منشأ
turn را به‌عنوان داده‌ی بین sessionها علامت‌گذاری می‌کنند.
OpenClaw همچنین پیش از متن prompt مسیریابی‌شده، در همان نوبت یک نشانگر `[Inter-session message ... isUser=false]` اضافه می‌کند تا فراخوانی فعال مدل بتواند خروجی نشست خارجی را از دستورهای کاربر نهایی بیرونی تشخیص دهد. این نشانگر، در صورت موجود بودن، نشست مبدأ، کانال، و ابزار را شامل می‌شود. رونوشت همچنان برای سازگاری با ارائه‌دهنده از `role: "user"` استفاده می‌کند، اما متن قابل مشاهده و metadata منشأ، هر دو نوبت را به‌عنوان دادهٔ بین‌نشستی علامت‌گذاری می‌کنند.
هنگام بازسازی context، OpenClaw همین نشانگر را روی turnهای کاربر بین sessionی قدیمی‌تر
که فقط metadata منشأ دارند نیز اعمال می‌کند.
هنگام بازسازی بافت، OpenClaw همین نشانگر را روی نوبت‌های کاربر بین‌نشستی ذخیره‌شدهٔ قدیمی‌تر که فقط metadata منشأ دارند نیز اعمال می‌کند.
---
## ماتریس provider (رفتار فعلی)
## ماتریس ارائه‌دهنده، رفتار فعلی
**OpenAI / OpenAI Codex**
- فقط پاک‌سازی تصویر.
- امضاهای reasoning یتیم (آیتم‌های reasoning مستقل بدون بلوک محتوای بعدی) برای transcriptهای OpenAI Responses/Codex حذف می‌شوند، و reasoning قابل replay مربوط به OpenAI پس از تغییر مسیر مدل حذف می‌شود.
- payloadهای آیتم reasoning قابل replay در OpenAI Responses، از جمله آیتم‌های encrypted empty-summary، حفظ می‌شوند تا replay دستی/WebSocket حالت الزامی `rs_*` را در کنار آیتم‌های خروجی assistant نگه دارد.
- پاک‌سازی id فراخوانی ابزار انجام نمی‌شود.
- repair جفت‌سازی نتیجه‌ی ابزار ممکن است خروجی‌های واقعیِ match شده را جابه‌جا کند و برای فراخوانی‌های ابزار گمشده خروجی‌های Codex-style `aborted` بسازد.
- اعتبارسنجی یا ترتیب‌دهی مجدد turn انجام نمی‌شود.
- خروجی‌های ابزار گمشده در خانواده‌ی OpenAI Responses به‌صورت `aborted` ساخته می‌شوند تا با نرمال‌سازی replay در Codex همخوان باشند.
- حذف امضای thought انجام نمی‌شود.
- حذف امضاهای reasoning یتیم، یعنی آیتم‌های standalone reasoning بدون بلوک محتوای بعدی، برای رونوشت‌های OpenAI Responses/Codex، و حذف reasoning قابل بازپخش OpenAI پس از تغییر مسیر مدل.
- حفظ payloadهای آیتم reasoning در OpenAI Responses که قابل بازپخش هستند، از جمله آیتم‌های رمزگذاری‌شدهٔ empty-summary، تا بازپخش دستی/WebSocket وضعیت لازم `rs_*` را همراه با آیتم‌های خروجی دستیار نگه دارد.
- Native ChatGPT Codex Responses با بازپخش payloadهای reasoning/message/function پیشین Responses بدون شناسهٔ آیتم قبلی و با حفظ `prompt_cache_key` نشست، از برابری سیمی Codex پیروی می‌کند.
- بدون پاک‌سازی شناسهٔ فراخوانی ابزار.
- ترمیم جفت‌سازی نتیجهٔ ابزار ممکن است خروجی‌های واقعی منطبق را جابه‌جا کند و خروجی‌های `aborted` به سبک Codex برای فراخوانی‌های ابزار گمشده بسازد.
- بدون اعتبارسنجی یا ترتیب‌دهی دوبارهٔ نوبت‌ها.
- خروجی‌های ابزار گمشده در خانوادهٔ OpenAI Responses به‌صورت `aborted` ساخته می‌شوند تا با نرمال‌سازی بازپخش Codex هماهنگ باشند.
- بدون حذف امضای فکر.
**OpenAI-compatible Gemma 4**
**Gemma 4 سازگار با OpenAI**
- بلوک‌های تاریخی thinking/reasoning مربوط به assistant پیش از replay حذف می‌شوند تا سرورهای محلی
سازگار با OpenAI برای Gemma 4 محتوای reasoning مربوط به turnهای قبلی را دریافت نکنند.
- ادامه‌های فراخوانی ابزار در همان turn فعلی، بلوک reasoning assistant را
تا زمانی که نتیجه‌ی ابزار replay شود به فراخوانی ابزار متصل نگه می‌دارند.
- بلوک‌های historical assistant thinking/reasoning پیش از بازپخش حذف می‌شوند تا سرورهای محلی Gemma 4 سازگار با OpenAI محتوای reasoning نوبت‌های قبلی را دریافت نکنند.
- ادامه‌های فراخوانی ابزار در همان نوبت فعلی، بلوک reasoning دستیار را تا زمانی که نتیجهٔ ابزار بازپخش شده باشد، متصل به فراخوانی ابزار نگه می‌دارند.
**Google (Generative AI / Gemini CLI / Antigravity)**
- پاک‌سازی id فراخوانی ابزار: alphanumeric سخت‌گیرانه.
- repair جفت‌سازی نتیجه‌ی ابزار و نتایج ابزار synthetic.
- اعتبارسنجی turn (تناوب turn به سبک Gemini).
- اصلاح ترتیب turn در Google (اگر history با assistant شروع شود، یک bootstrap کوچک user در ابتدا افزوده می‌شود).
- پاک‌سازی شناسهٔ فراخوانی ابزار: سخت‌گیرانه، فقط حروف و اعداد.
- ترمیم جفت‌سازی نتیجهٔ ابزار و نتایج synthetic ابزار.
- اعتبارسنجی نوبت‌ها، به سبک تناوب نوبت Gemini.
- اصلاح ترتیب نوبت Google، یعنی افزودن یک bootstrap بسیار کوچک کاربر در ابتدا اگر تاریخچه با دستیار شروع شود.
- Antigravity Claude: نرمال‌سازی امضاهای thinking؛ حذف بلوک‌های thinking بدون امضا.
**Anthropic / Minimax (سازگار با Anthropic)**
- repair جفت‌سازی نتیجه‌ی ابزار و نتایج ابزار synthetic.
- اعتبارسنجی turn (ادغام turnهای متوالی user برای برآورده کردن تناوب سخت‌گیرانه).
- turnهای prefill انتهایی assistant از payloadهای خروجی Anthropic Messages
وقتی thinking فعال است حذف می‌شوند، از جمله مسیرهای Cloudflare AI Gateway.
- بلوک‌های thinking با امضاهای replay گمشده، خالی، یا blank پیش از تبدیل provider حذف می‌شوند.
اگر این کار یک turn assistant را خالی کند، OpenClaw شکل turn را با متن omitted-reasoning غیرخالی نگه می‌دارد.
- turnهای قدیمی‌ترِ فقط-thinking مربوط به assistant که باید حذف شوند، با
متن omitted-reasoning غیرخالی جایگزین می‌شوند تا adapterهای provider، turn
replay را حذف نکنند.
- ترمیم جفت‌سازی نتیجهٔ ابزار و نتایج synthetic ابزار.
- اعتبارسنجی نوبت‌ها، یعنی ادغام نوبت‌های پیاپی کاربر برای برآورده کردن تناوب سخت‌گیرانه.
- نوبت‌های پیش‌پرکردن انتهایی دستیار از payloadهای خروجی Anthropic Messages هنگام فعال بودن thinking حذف می‌شوند، از جمله مسیرهای Cloudflare AI Gateway.
- بلوک‌های thinking با امضای بازپخش گمشده، خالی، یا blank، پیش از تبدیل ارائه‌دهنده حذف می‌شوند. اگر این کار یک نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالی omitted-reasoning حفظ می‌کند.
- نوبت‌های قدیمی‌تر دستیار که فقط thinking هستند و باید حذف شوند، با متن غیرخالی omitted-reasoning جایگزین می‌شوند تا adapterهای ارائه‌دهنده نوبت بازپخش را حذف نکنند.
**Amazon Bedrock (Converse API)**
- turnهای خطای stream assistant خالی پیش از replay به یک بلوک متن fallback غیرخالی
repair می‌شوند. Bedrock Converse پیام‌های assistant با `content: []` را رد می‌کند، بنابراین
turnهای assistant پایدارشده با `stopReason: "error"` و محتوای خالی نیز
پیش از load شدن روی دیسک repair می‌شوند.
- turnهای خطای stream assistant که فقط شامل بلوک‌های متنی blank هستند، به‌جای replay کردن یک بلوک blank نامعتبر،
از کپی replay درون‌حافظه‌ای حذف می‌شوند.
- بلوک‌های thinking مربوط به Claude با امضاهای replay گمشده، خالی، یا blank
پیش از replay در Converse حذف می‌شوند. اگر این کار یک turn assistant را خالی کند، OpenClaw
شکل turn را با متن omitted-reasoning غیرخالی نگه می‌دارد.
- turnهای قدیمی‌ترِ فقط-thinking مربوط به assistant که باید حذف شوند، با
متن omitted-reasoning غیرخالی جایگزین می‌شوند تا replay در Converse شکل turn سخت‌گیرانه را حفظ کند.
- replay، turnهای assistant مربوط به delivery-mirror در OpenClaw و تزریق‌شده توسط gateway را فیلتر می‌کند.
- پاک‌سازی تصویر از طریق قاعده‌ی سراسری اعمال می‌شود.
- نوبت‌های خطای stream خالی دستیار پیش از بازپخش به یک بلوک متن fallback غیرخالی ترمیم می‌شوند. Bedrock Converse پیام‌های دستیار با `content: []` را رد می‌کند، بنابراین نوبت‌های ذخیره‌شدهٔ دستیار با `stopReason: "error"` و محتوای خالی نیز پیش از بارگذاری روی دیسک ترمیم می‌شوند.
- نوبت‌های خطای stream دستیار که فقط بلوک‌های متنی blank دارند، به‌جای بازپخش یک بلوک blank نامعتبر، از نسخهٔ بازپخش در حافظه حذف می‌شوند.
- بلوک‌های thinking در Claude با امضای بازپخش گمشده، خالی، یا blank، پیش از بازپخش Converse حذف می‌شوند. اگر این کار یک نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالی omitted-reasoning حفظ می‌کند.
- نوبت‌های قدیمی‌تر دستیار که فقط thinking هستند و باید حذف شوند، با متن غیرخالی omitted-reasoning جایگزین می‌شوند تا بازپخش Converse شکل سخت‌گیرانهٔ نوبت را حفظ کند.
- بازپخش، نوبت‌های دستیار delivery-mirror در OpenClaw و تزریق‌شده توسط Gateway را فیلتر می‌کند.
- پاک‌سازی تصویر از طریق قاعدهٔ سراسری اعمال می‌شود.
**Mistral (از جمله تشخیص مبتنی بر model-id)**
**Mistral، از جمله تشخیص مبتنی بر model-id**
- پاک‌سازی id فراخوانی ابزار: strict9 (alphanumeric با طول 9).
- پاک‌سازی شناسهٔ فراخوانی ابزار: strict9، یعنی حروف و اعداد با طول 9.
**OpenRouter Gemini**
- پاک‌سازی امضای thought: مقدارهای `thought_signature` غیر-base64 حذف می‌شوند (base64 نگه داشته می‌شود).
- پاک‌سازی امضای فکر: حذف مقدارهای `thought_signature` غیر base64، و نگه داشتن base64.
**OpenRouter Anthropic**
- turnهای prefill انتهایی assistant از payloadهای مدل Anthropic سازگار با OpenAI و تأییدشده‌ی OpenRouter
وقتی reasoning فعال است حذف می‌شوند، مطابق با رفتار replay مستقیم Anthropic و Cloudflare Anthropic.
- نوبت‌های پیش‌پرکردن انتهایی دستیار از payloadهای مدل Anthropic سازگار با OpenAI و تأییدشدهٔ OpenRouter هنگام فعال بودن reasoning حذف می‌شوند، مطابق با رفتار بازپخش مستقیم Anthropic و Cloudflare Anthropic.
**همه‌ی موارد دیگر**
**هر چیز دیگر**
- فقط پاک‌سازی تصویر.
---
## رفتار تاریخی (پیش از 2026.1.22)
## رفتار تاریخی، پیش از 2026.1.22
پیش از انتشار 2026.1.22، OpenClaw چندین لایه بهداشت transcript اعمال می‌کرد:
پیش از انتشار 2026.1.22، OpenClaw چندین لایهٔ بهداشت رونوشت را اعمال می‌کرد:
- یک **افزونه‌ی transcript-sanitize** روی هر ساخت context اجرا می‌شد و می‌توانست:
- جفت‌سازی tool use/result را repair کند.
- idهای فراخوانی ابزار را پاک‌سازی کند (از جمله حالتی غیرسخت‌گیرانه که `_`/`-` را حفظ می‌کرد).
- runner نیز پاک‌سازی ویژه‌ی provider انجام می‌داد، که باعث تکرار کار می‌شد.
- جهش‌های اضافی بیرون از policy مربوط به provider رخ می‌دادند، از جمله:
- حذف tagهای `<final>` از متن assistant پیش از persistence.
- حذف turnهای خطای assistant خالی.
- کوتاه کردن محتوای assistant پس از فراخوانی‌های ابزار.
- یک **transcript-sanitize extension** روی هر ساخت بافت اجرا می‌شد و می‌توانست:
- جفت‌سازی tool use/result را ترمیم کند.
- شناسه‌های فراخوانی ابزار را پاک‌سازی کند، از جمله یک حالت غیرسخت‌گیرانه که `_`/`-` را حفظ می‌کرد.
- runner نیز پاک‌سازی مخصوص ارائه‌دهنده را انجام می‌داد، که باعث تکرار کار می‌شد.
- جهش‌های اضافی خارج از policy ارائه‌دهنده رخ می‌داد، از جمله:
- حذف تگ‌های `<final>` از متن دستیار پیش از ماندگارسازی.
- حذف نوبت‌های خطای خالی دستیار.
- کوتاه کردن محتوای دستیار پس از فراخوانی‌های ابزار.
این پیچیدگی باعث regressions بین‌providerها شد (به‌ویژه جفت‌سازی `call_id|fc_id` در
`openai-responses`). پاک‌سازی 2026.1.22 این افزونه را حذف کرد، منطق را در runner متمرکز کرد،
و OpenAI را فراتر از پاک‌سازی تصویر **دست‌نخورده** نگه داشت.
این پیچیدگی باعث regressionهای بین‌ارائه‌دهنده‌ای شد، به‌ویژه جفت‌سازی `call_id|fc_id` در `openai-responses`. پاک‌سازی 2026.1.22 این extension را حذف کرد، منطق را در runner متمرکز کرد، و OpenAI را فراتر از پاک‌سازی تصویر، **بدون دست‌کاری** کرد.
## مرتبط
- [مدیریت session](/fa/concepts/session)
- [هرس session](/fa/concepts/session-pruning)
- [مدیریت نشست](/fa/concepts/session)
- [هرس نشست](/fa/concepts/session-pruning)

151
docs/fa/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- شما به دفاع در عمق در برابر حملات SSRF و بازپیوند DNS نیاز دارید
- پیکربندی یک پروکسی فوروارد خارجی برای ترافیک زمان اجرای OpenClaw
summary: نحوه مسیریابی ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق یک پراکسی فیلترینگ مدیریت‌شده توسط اپراتور
- به دفاع در عمق در برابر حملات SSRF و بازاتصال DNS نیاز دارید
- پیکربندی یک پراکسی فوروارد خارجی برای ترافیک زمان اجرای OpenClaw
summary: نحوه مسیریابی ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق پروکسی فیلترینگ تحت مدیریت اپراتور
title: پروکسی شبکه
x-i18n:
generated_at: "2026-05-04T11:59:10Z"
generated_at: "2026-05-05T01:52:01Z"
model: gpt-5.5
provider: openai
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
source_path: security/network-proxy.md
workflow: 16
---
# پروکسی شبکه
# پراکسی شبکه
OpenClaw می‌تواند ترافیک runtime HTTP و WebSocket را از طریق یک پروکسی روبه‌جلو که توسط اپراتور مدیریت می‌شود، مسیریابی کند. این یک دفاع اختیاری و لایه‌ای برای استقرارهایی است که کنترل مرکزی خروجی، محافظت قوی‌تر در برابر SSRF و قابلیت ممیزی بهتر شبکه می‌خواهند.
OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پراکسی پیش‌روی مدیریت‌شده توسط اپراتور مسیریابی کند. این یک دفاع اختیاری در عمق برای استقرارهایی است که کنترل مرکزی خروجی، محافظت قوی‌تر در برابر SSRF، و قابلیت حسابرسی بهتر شبکه می‌خواهند.
OpenClaw هیچ پروکسی‌ای را همراه خود ارائه، دانلود، شروع، پیکربندی یا تأیید نمی‌کند. شما فناوری پروکسی مناسب محیط خود را اجرا می‌کنید و OpenClaw کلاینت‌های عادی HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند.
OpenClaw هیچ پراکسی‌ای را همراه خود ارائه، دانلود، شروع، پیکربندی یا تأیید نمی‌کند. شما فناوری پراکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های HTTP و WebSocket عادیِ محلیِ پردازش را از طریق آن مسیریابی می‌کند.
## چرا از پروکسی استفاده کنیم؟
## چرا از پراکسی استفاده کنیم؟
پروکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این حتی بیرون از سخت‌سازی SSRF هم می‌تواند مفید باشد:
یک پراکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این می‌تواند حتی خارج از سخت‌سازی SSRF نیز مفید باشد:
- سیاست مرکزی: به‌جای تکیه بر اینکه هر محل فراخوانی HTTP در برنامه قواعد شبکه را درست اعمال کند، یک سیاست خروجی واحد نگه دارید.
- بررسی‌های زمان اتصال: مقصد را پس از حل DNS و بلافاصله پیش از اینکه پروکسی اتصال بالادستی را باز کند، ارزیابی کنید.
- دفاع در برابر بازپیوند DNS: فاصله بین بررسی DNS در سطح برنامه و اتصال خروجی واقعی را کاهش دهید.
- پوشش گسترده‌تر JavaScript: کلاینت‌های معمول `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch و مشابه را از همان مسیر عبور دهید.
- قابلیت ممیزی: مقصدهای مجاز و ردشده را در مرز خروجی ثبت کنید.
- کنترل عملیاتی: قواعد مقصد، بخش‌بندی شبکه، محدودیت نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید.
- سیاست مرکزی: به‌جای تکیه بر اینکه هر محل فراخوانی HTTP در برنامه قواعد شبکه را درست اعمال کند، یک سیاست خروجی واحد را نگه‌داری کنید.
- بررسی‌های زمان اتصال: مقصد را پس از رفع DNS و بلافاصله پیش از اینکه پراکسی اتصال بالادستی را باز کند ارزیابی کنید.
- دفاع در برابر باز绑定 DNS: فاصله بین یک بررسی DNS در سطح برنامه و اتصال خروجی واقعی را کاهش دهید.
- پوشش گسترده‌تر JavaScript: کلاینت‌های معمولی `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch، و کلاینت‌های مشابه را از همان مسیر عبور دهید.
- قابلیت حسابرسی: مقصدهای مجاز و ردشده را در مرز خروجی ثبت کنید.
- کنترل عملیاتی: قواعد مقصد، بخش‌بندی شبکه، محدودیت‌های نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید.
مسیریابی پروکسی یک حفاظ در سطح فرایند برای خروجی عادی HTTP و WebSocket است. این به اپراتورها مسیری fail-closed می‌دهد تا کلاینت‌های HTTP پشتیبانی‌شده JavaScript را از طریق پروکسی فیلترکننده خودشان مسیریابی کنند، اما sandbox شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پروکسی را تأیید کند.
مسیریابی پراکسی یک حفاظ در سطح پردازش برای خروجی عادی HTTP و WebSocket است. این به اپراتورها مسیری fail-closed برای عبور دادن کلاینت‌های HTTP پشتیبانی‌شده JavaScript از پراکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پراکسی را تأیید کند.
## OpenClaw چگونه ترافیک را مسیریابی می‌کند
وقتی `proxy.enabled=true` است و یک URL پروکسی پیکربندی شده، فرایندهای runtime محافظت‌شده مانند `openclaw gateway run`، `openclaw node run` و `openclaw agent --local` خروجی عادی HTTP و WebSocket را از طریق پروکسی پیکربندی‌شده مسیریابی می‌کنند:
وقتی `proxy.enabled=true` باشد و URL پراکسی پیکربندی شده باشد، پردازش‌های زمان اجرای محافظت‌شده مانند `openclaw gateway run`، `openclaw node run`، و `openclaw agent --local` خروجی عادی HTTP و WebSocket را از طریق پراکسی پیکربندی‌شده مسیریابی می‌کنند:
```text
OpenClaw process
@ -43,27 +43,28 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
قرارداد عمومی، رفتار مسیریابی است، نه hookهای داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket صفحه کنترل OpenClaw Gateway برای ترافیک RPC مربوط به Gateway در مسیر local loopback، وقتی URL Gateway از `localhost` یا یک IP صریح loopback مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، از یک مسیر مستقیم محدود استفاده می‌کنند. این مسیر صفحه کنترل باید بتواند به Gatewayهای loopback برسد، حتی وقتی پروکسی اپراتور مقصدهای loopback را مسدود می‌کند. درخواست‌های عادی runtime HTTP و WebSocket همچنان از پروکسی پیکربندی‌شده استفاده می‌کنند.
قرارداد عمومی، رفتار مسیریابی است، نه hookهای داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket سطح کنترل OpenClaw Gateway برای ترافیک RPC ‏Gateway در local loopback، وقتی URL ‏Gateway از `localhost` یا یک IP loopback تحت‌اللفظی مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، از یک مسیر مستقیم محدود استفاده می‌کنند. آن مسیر سطح کنترل باید بتواند به Gatewayهای loopback برسد حتی وقتی پراکسی اپراتور مقصدهای loopback را مسدود می‌کند. درخواست‌های عادی HTTP و WebSocket زمان اجرا همچنان از پراکسی پیکربندی‌شده استفاده می‌کنند.
در داخل، OpenClaw برای این قابلیت از دو hook مسیریابی در سطح فرایند استفاده می‌کند:
در داخل، OpenClaw برای این قابلیت از دو hook مسیریابی در سطح پردازش استفاده می‌کند:
- مسیریابی dispatcher مربوط به Undici شامل `fetch`، کلاینت‌های مبتنی بر undici و transportهایی می‌شود که dispatcher اختصاصی undici خود را فراهم می‌کنند.
- مسیریابی `global-agent` شامل فراخوان‌های هسته Node یعنی `node:http` و `node:https` می‌شود، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get` و `https.get` ساخته شده‌اند. حالت پروکسی مدیریت‌شده آن agent سراسری را اجباری می‌کند تا agentهای صریح HTTP در Node به‌طور اتفاقی پروکسی اپراتور را دور نزنند.
- مسیریابی dispatcher در Undici، `fetch`، کلاینت‌های مبتنی بر undici، و انتقال‌هایی را پوشش می‌دهد که dispatcher خودشان را برای undici فراهم می‌کنند.
- مسیریابی `global-agent` فراخواننده‌های هسته Node یعنی `node:http` و `node:https` را پوشش می‌دهد، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get`، و `https.get` ساخته شده‌اند. حالت پراکسی مدیریت‌شده آن عامل سراسری را اجباری می‌کند تا عامل‌های صریح HTTP در Node به‌طور تصادفی پراکسی اپراتور را دور نزنند.
برخی Plugin‌ها transportهای سفارشی خود را دارند که حتی وقتی مسیریابی در سطح فرایند وجود دارد، به سیم‌کشی صریح پروکسی نیاز دارند. برای نمونه، transport مربوط به Bot API در Telegram از dispatcher اختصاصی HTTP/1 undici خود استفاده می‌کند و بنابراین در آن مسیر transport مالک‌محور، env پروکسی فرایند به‌علاوه fallback مدیریت‌شده `OPENCLAW_PROXY_URL` را رعایت می‌کند.
برخی Pluginها مالک انتقال‌های سفارشی هستند که حتی در صورت وجود مسیریابی در سطح پردازش نیز به اتصال صریح پراکسی نیاز دارند. برای مثال، انتقال Bot API در Telegram از dispatcher اختصاصی HTTP/1 در undici استفاده می‌کند و بنابراین env پراکسی پردازش به‌علاوه جایگزین مدیریت‌شده `OPENCLAW_PROXY_URL` را در همان مسیر انتقال مالک‌محور رعایت می‌کند.
خود URL پروکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پروکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک listener پروکسی روبه‌جلوی HTTP ساده مانند `http://127.0.0.1:3128` را دارد.
خود URL پراکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پراکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک شنونده پراکسی پیش‌روی HTTP ساده مانند `http://127.0.0.1:3128` را دارد.
وقتی پروکسی فعال است، OpenClaw مقدارهای `no_proxy`، `NO_PROXY` و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، پس باقی گذاشتن `localhost` یا `127.0.0.1` در آن‌ها باعث می‌شود مقصدهای پرخطر SSRF از پروکسی فیلترکننده عبور نکنند.
تا زمانی که پراکسی فعال است، OpenClaw مقادیر `no_proxy`، `NO_PROXY`، و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، پس باقی گذاشتن `localhost` یا `127.0.0.1` در آن‌ها به هدف‌های پرخطر SSRF اجازه می‌دهد پراکسی فیلترکننده را رد کنند.
هنگام خاموشی، OpenClaw محیط پروکسی قبلی را بازیابی می‌کند و وضعیت کش‌شده مسیریابی فرایند را بازنشانی می‌کند.
هنگام خاموشی، OpenClaw محیط پراکسی قبلی را بازیابی می‌کند و وضعیت مسیریابی پردازشِ cacheشده را بازنشانی می‌کند.
## اصطلاحات مرتبط با پروکسی
## اصطلاحات مرتبط با پراکسی
- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پروکسی روبه‌جلوی خروجی برای خروجی runtime OpenClaw. این صفحه این قابلیت را مستند می‌کند.
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت reverse-proxy ورودی و آگاه از هویت برای دسترسی به Gateway. [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.
- `openclaw proxy`: پروکسی اشکال‌زدایی محلی و بازرس capture برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید.
- تنظیمات پروکسی ویژه کانال یا provider: overrideهای مالک‌محور برای یک transport خاص. وقتی هدف، کنترل مرکزی خروجی در سراسر runtime است، پروکسی شبکه مدیریت‌شده را ترجیح دهید.
- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پراکسی پیش‌روی خروجی برای خروجی زمان اجرای OpenClaw. این صفحه همین قابلیت را مستند می‌کند.
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت ورودیِ پراکسی معکوسِ آگاه از هویت برای دسترسی به Gateway. [احراز هویت پراکسی معتمد](/fa/gateway/trusted-proxy-auth) را ببینید.
- `openclaw proxy`: پراکسی اشکال‌زدایی محلی و بازرس capture برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید.
- `tools.web.fetch.useTrustedEnvProxy`: انتخاب اختیاری برای `web_fetch` تا اجازه دهد یک پراکسی env ‏HTTP(S) تحت کنترل اپراتور DNS را رفع کند، در حالی که pinning سخت‌گیرانه DNS و سیاست نام میزبانِ پیش‌فرض حفظ می‌شود. [واکشی وب](/fa/tools/web-fetch#trusted-env-proxy) را ببینید.
- تنظیمات پراکسی ویژه کانال یا provider: overrideهای مالک‌محور برای یک انتقال خاص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجرا است، پراکسی شبکه مدیریت‌شده را ترجیح دهید.
## پیکربندی
@ -73,7 +74,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
همچنین می‌توانید URL را از طریق محیط فراهم کنید، درحالی‌که `proxy.enabled=true` را در پیکربندی نگه می‌دارید:
همچنین می‌توانید URL را از طریق محیط فراهم کنید، در حالی که `proxy.enabled=true` را در پیکربندی نگه می‌دارید:
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` بر `OPENCLAW_PROXY_URL` اولویت دارد.
اگر `enabled=true` باشد اما هیچ URL پروکسی معتبری پیکربندی نشده باشد، دستورهای محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، هنگام شروع شکست می‌خورند.
اگر `enabled=true` باشد اما هیچ URL معتبر پراکسی پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، در شروع شکست می‌خورند.
برای سرویس‌های Gateway مدیریت‌شده که با `openclaw gateway start` شروع می‌شوند، ذخیره URL در پیکربندی را ترجیح دهید:
برای سرویس‌های Gateway مدیریت‌شده که با `openclaw gateway start` شروع می‌شوند، ترجیح دهید URL را در پیکربندی ذخیره کنید:
```bash
openclaw config set proxy.enabled true
@ -92,63 +93,63 @@ openclaw gateway install --force
openclaw gateway start
```
fallback محیط برای اجراهای foreground مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env` قرار دهید، سپس سرویس را دوباره نصب کنید تا launchd، systemd یا Scheduled Tasks مقدار gateway را با آن مقدار شروع کند.
جایگزین محیطی برای اجراهای foreground مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env` قرار دهید، سپس سرویس را دوباره نصب کنید تا launchd، systemd، یا Scheduled Tasks گیت‌وی را با آن مقدار شروع کند.
برای دستورهای `openclaw --container ...`، OpenClaw وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد، آن را به CLI فرزند هدف‌گیری‌شده برای container ارسال می‌کند. URL باید از داخل container قابل دسترس باشد؛ `127.0.0.1` به خود container اشاره می‌کند، نه میزبان. OpenClaw URLهای پروکسی loopback را برای دستورهای هدف‌گیری‌شده برای container رد می‌کند، مگر اینکه صریحاً آن بررسی ایمنی را override کنید.
برای فرمان‌های `openclaw --container ...`، وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد، OpenClaw آن را به CLI فرزندِ هدف‌گیری‌شده برای container ارسال می‌کند. URL باید از داخل container قابل دسترسی باشد؛ `127.0.0.1` به خود container اشاره می‌کند، نه میزبان. OpenClaw برای فرمان‌های هدف‌گیری‌شده به container، URLهای پراکسی loopback را رد می‌کند مگر اینکه صراحتاً آن بررسی ایمنی را override کنید.
## الزامات پروکسی
## الزامات پراکسی
سیاست پروکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پروکسی مقصدهای درست را مسدود می‌کند.
سیاست پراکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پراکسی هدف‌های درست را مسدود می‌کند.
پروکسی را طوری پیکربندی کنید که:
پراکسی را طوری پیکربندی کنید که:
- فقط به loopback یا یک رابط خصوصی مورد اعتماد bind شود.
- دسترسی را محدود کند تا فقط فرایند، میزبان، container یا حساب سرویس OpenClaw بتواند از آن استفاده کند.
- مقصدها را خودش resolve کند و IPهای مقصد را پس از حل DNS مسدود کند.
- سیاست را در زمان اتصال، هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT` اعمال کند.
- دورزدن‌های مبتنی بر مقصد را برای بازه‌های loopback، خصوصی، link-local، metadata، multicast، reserved یا documentation رد کند.
- از allowlistهای hostname پرهیز کند مگر اینکه به مسیر حل DNS کاملاً اعتماد داشته باشید.
- مقصد، تصمیم، وضعیت و دلیل را بدون ثبت بدنه‌های درخواست، سرآیندهای authorization، کوکی‌ها یا سایر اسرار log کند.
- سیاست پروکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند.
- فقط به loopback یا یک واسط خصوصی مورد اعتماد bind شود.
- دسترسی را محدود کند تا فقط پردازش، میزبان، container، یا حساب سرویس OpenClaw بتواند از آن استفاده کند.
- مقصدها را خودش رفع کند و IPهای مقصد را پس از رفع DNS مسدود کند.
- سیاست را هنگام اتصال هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT` اعمال کند.
- دورزدن‌های مبتنی بر مقصد را برای محدوده‌های loopback، خصوصی، link-local، metadata، multicast، reserved، یا documentation رد کند.
- از فهرست‌های مجاز نام میزبان پرهیز کند، مگر اینکه به مسیر رفع DNS کاملاً اعتماد دارید.
- مقصد، تصمیم، وضعیت، و دلیل را بدون ثبت بدنه‌های درخواست، سرآیندهای authorization، کوکی‌ها، یا اسرار دیگر ثبت کند.
- سیاست پراکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس به امنیت بازبینی کند.
## مقصدهای مسدود پیشنهادی
## مقصدهای مسدودشده پیشنهادی
از این denylist به‌عنوان نقطه شروع برای هر پروکسی روبه‌جلو، firewall یا سیاست خروجی استفاده کنید.
از این denylist به‌عنوان نقطه شروع برای هر پراکسی پیش‌رو، فایروال، یا سیاست خروجی استفاده کنید.
منطق طبقه‌بندی در سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. hookهای parity مرتبط عبارت‌اند از `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX` و مدیریت sentinel تعبیه‌شده IPv4 برای NAT64، 6to4، Teredo، ISATAP و فرم‌های IPv4-mapped. هنگام نگه‌داری یک سیاست پروکسی خارجی، آن فایل‌ها مراجع مفیدی هستند، اما OpenClaw آن قواعد را به‌طور خودکار در پروکسی شما صادر یا اعمال نمی‌کند.
منطق دسته‌بندی در سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. hookهای parity مرتبط عبارت‌اند از `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX`، و مدیریت sentinel تعبیه‌شده IPv4 برای NAT64، 6to4، Teredo، ISATAP، و شکل‌های IPv4-mapped. این فایل‌ها هنگام نگه‌داری یک سیاست پراکسی خارجی مراجع مفیدی هستند، اما OpenClaw آن قواعد را به‌طور خودکار به پراکسی شما export یا در آن enforce نمی‌کند.
| بازه یا میزبان | دلیل مسدودسازی |
| محدوده یا میزبان | دلیل مسدودسازی |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | loopback در IPv4 |
| `::1/128` | loopback در IPv6 |
| `0.0.0.0/8`, `::/128` | آدرس‌های نامشخص و این-شبکه |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
| `::1/128` | IPv6 loopback |
| `0.0.0.0/8`, `::/128` | نشانی‌های نامشخص و این-شبکه |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبکه‌های خصوصی RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | آدرس‌های link-local و مسیرهای رایج metadata ابری |
| `169.254.0.0/16`, `fe80::/10` | نشانی‌های link-local و مسیرهای رایج metadata ابری |
| `169.254.169.254`, `metadata.google.internal` | سرویس‌های metadata ابری |
| `100.64.0.0/10` | فضای آدرس مشترک Carrier-grade NAT |
| `198.18.0.0/15`, `2001:2::/48` | بازه‌های benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | بازه‌های special-use و documentation |
| `224.0.0.0/4`, `ff00::/8` | multicast |
| `240.0.0.0/4` | IPv4 reserved |
| `fc00::/7`, `fec0::/10` | بازه‌های محلی/خصوصی IPv6 |
| `100::/64`, `2001:20::/28` | بازه‌های IPv6 discard و ORCHIDv2 |
| `100.64.0.0/10` | فضای نشانی مشترک NAT در سطح carrier |
| `198.18.0.0/15`, `2001:2::/48` | محدوده‌های benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | محدوده‌های special-use و documentation |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 رزروشده |
| `fc00::/7`, `fec0::/10` | محدوده‌های محلی/خصوصی IPv6 |
| `100::/64`, `2001:20::/28` | محدوده‌های discard و ORCHIDv2 در IPv6 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | پیشوندهای NAT64 با IPv4 تعبیه‌شده |
| `2002::/16`, `2001::/32` | 6to4 و Teredo با IPv4 تعبیه‌شده |
| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv6 از نوع IPv4-mapped |
| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv6 با نگاشت IPv4 |
اگر ارائه‌دهنده ابر یا پلتفرم شبکه شما میزبان‌های metadata یا بازه‌های reserved اضافی را مستند کرده است، آن‌ها را هم اضافه کنید.
اگر cloud provider یا پلتفرم شبکه شما میزبان‌های metadata یا محدوده‌های رزروشده بیشتری را مستند کرده است، آن‌ها را هم اضافه کنید.
## اعتبارسنجی
پروکسی را از همان میزبان، container یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید:
پراکسی را از همان میزبان، container، یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
به‌طور پیش‌فرض، وقتی مقصد سفارشی ارائه نشده باشد، دستور بررسی می‌کند که `https://example.com/` موفق شود و یک canary موقت loopback را شروع می‌کند که پروکسی نباید به آن برسد. بررسی ردشده پیش‌فرض وقتی قبول می‌شود که پروکسی یک پاسخ denial غیر 2xx برگرداند یا canary را با خطای transport مسدود کند؛ اگر یک پاسخ موفق به canary برسد، شکست می‌خورد. اگر هیچ پروکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. برای آزمودن انتظارهای ویژه استقرار از `--allowed-url` و `--denied-url` استفاده کنید. `--apns-reachable` را اضافه کنید تا همچنین تأیید شود تحویل مستقیم APNs HTTP/2 می‌تواند از طریق پروکسی یک تونل CONNECT باز کند و یک پاسخ sandbox APNs دریافت کند؛ probe عمداً از یک توکن provider نامعتبر استفاده می‌کند، بنابراین `403 InvalidProviderToken` انتظار می‌رود و به‌عنوان reachable حساب می‌شود. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پروکسی reachable بوده است، و هر خطای transport به‌عنوان inconclusive گزارش می‌شود، چون OpenClaw نمی‌تواند ثابت کند پروکسی یک origin reachable را مسدود کرده است. هنگام شکست اعتبارسنجی، دستور با کد 1 خارج می‌شود.
به‌طور پیش‌فرض، وقتی مقصد سفارشی‌ای ارائه نشده باشد، فرمان بررسی می‌کند که `https://example.com/` موفق شود و یک canary موقت loopback را شروع می‌کند که پراکسی نباید به آن برسد. بررسی ردشده پیش‌فرض وقتی موفق است که پراکسی یک پاسخ رد غیر 2xx برگرداند یا canary را با شکست انتقال مسدود کند؛ اگر یک پاسخ موفق به canary برسد شکست می‌خورد. اگر هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی را گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. از `--allowed-url` و `--denied-url` برای آزمودن انتظارهای ویژه استقرار استفاده کنید. `--apns-reachable` را اضافه کنید تا همچنین بررسی شود تحویل مستقیم HTTP/2 در APNs می‌تواند یک تونل CONNECT از طریق پراکسی باز کند و یک پاسخ sandbox از APNs دریافت کند؛ probe از یک توکن provider عمداً نامعتبر استفاده می‌کند، بنابراین `403 InvalidProviderToken` مورد انتظار است و به‌عنوان قابل‌دسترسی بودن حساب می‌شود. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پراکسی قابل دسترسی بوده است، و هر خطای انتقال به‌عنوان نامشخص گزارش می‌شود چون OpenClaw نمی‌تواند ثابت کند پراکسی یک origin قابل‌دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود.
برای automation از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پروکسی، هر خطای پیکربندی و هر بررسی مقصد است. credentialهای URL پروکسی در خروجی متنی و JSON redacted می‌شوند:
برای خودکارسازی از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پراکسی، هرگونه خطای پیکربندی، و بررسی هر مقصد است. اعتبارنامه‌های URL پراکسی در خروجی متنی و JSON پوشانده می‌شوند:
```json
{
@ -176,7 +177,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
}
```
همچنین می‌توانید با `curl` به‌صورت دستی اعتبارسنجی کنید:
همچنین می‌توانید به‌صورت دستی با `curl` اعتبارسنجی کنید:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
@ -184,7 +185,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
درخواست عمومی باید موفق شود. درخواست‌های لوپ‌بک و فراداده باید توسط پراکسی مسدود شوند. برای `openclaw proxy validate`، قناری لوپ‌بک داخلی می‌تواند رد شدن توسط پراکسی را از مبدا قابل دسترس تشخیص دهد. بررسی‌های سفارشی `--denied-url` این قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پراکسی شما سیگنال رد مختص استقرار را ارائه کند که بتوانید جداگانه آن را تأیید کنید.
درخواست عمومی باید موفق شود. درخواست‌های loopback و metadata باید توسط پراکسی مسدود شوند. برای `openclaw proxy validate`، قناری داخلی loopback می‌تواند انکار پراکسی را از مبدأ قابل‌دسترسی تشخیص دهد. بررسی‌های سفارشی `--denied-url` آن قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پراکسی شما سیگنال انکار ویژه استقرار را ارائه کند که بتوانید جداگانه آن را تأیید کنید.
سپس مسیریابی پراکسی OpenClaw را فعال کنید:
@ -205,10 +206,10 @@ proxy:
## محدودیت‌ها
- پراکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپت محلیِ فرایند بهبود می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست.
- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی و فرایندهای فرزند ممکن است از مسیریابی پراکسی در سطح Node عبور کنند، مگر اینکه متغیرهای محیطی پراکسی را به ارث ببرند و رعایت کنند.
- IRC یک کانال خام TCP/TLS خارج از مسیریابی پراکسی پیش‌برنده مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از آن پراکسی پیش‌برنده عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروجی مستقیم IRC صریحاً تأیید شده باشد.
- پراکسی اشکال‌زدایی محلی ابزار تشخیصی است و پیش‌برندگی مستقیم بالادست آن برای درخواست‌های پراکسی و تونل‌های CONNECT، هنگام فعال بودن حالت پراکسی مدیریت‌شده، به‌طور پیش‌فرض غیرفعال است؛ پیش‌برندگی مستقیم را فقط برای تشخیص‌های محلی تأییدشده فعال کنید.
- WebUIهای محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پراکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw گذر عمومی از شبکه محلی را برای آن‌ها در معرض دسترس قرار نمی‌دهد.
- گذر پراکسی صفحه کنترل Gateway عمداً به `localhost` و URLهای IP لوپ‌بک تحت‌اللفظی محدود شده است. برای اتصال‌های مستقیم محلی صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789` یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک عادی مبتنی بر نام میزبان مسیریابی می‌شوند.
- OpenClaw سیاست پراکسی شما را بررسی، آزمایش یا تأیید نمی‌کند.
- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی، و فرایندهای فرزند ممکن است مسیریابی پراکسی در سطح Node را دور بزنند، مگر اینکه متغیرهای محیطی پراکسی را به ارث ببرند و رعایت کنند.
- IRC یک کانال TCP/TLS خام خارج از مسیریابی پراکسی پیشروی مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از طریق آن پراکسی پیشرو عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروج مستقیم IRC صراحتاً تأیید شده باشد.
- پراکسی اشکال‌زدایی محلی ابزار تشخیصی است و ارسال مستقیم بالادستی آن برای درخواست‌های پراکسی و تونل‌های CONNECT به‌طور پیش‌فرض هنگام فعال بودن حالت پراکسی مدیریت‌شده غیرفعال است؛ ارسال مستقیم را فقط برای تشخیص‌های محلی تأییدشده فعال کنید.
- WebUIهای محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پراکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw یک دورزدن عمومی شبکه محلی برای آن‌ها ارائه نمی‌کند.
- دورزدن پراکسی صفحه کنترل Gateway عمداً به `localhost` و URLهای IP صریح loopback محدود شده است. برای اتصال‌های مستقیم محلی صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789`، یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمول مبتنی بر نام میزبان مسیریابی می‌شوند.
- OpenClaw سیاست پراکسی شما را بازرسی، آزمایش، یا گواهی نمی‌کند.
- تغییرات سیاست پراکسی را تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید.

83
docs/fa/tools/loop-detection.md
View File

@ -1,29 +1,29 @@
---
read_when:
- کاربری گزارش می‌دهد که عامل‌ها در تکرار فراخوانی‌های ابزار گیر می‌کنند
- باید محافظت در برابر فراخوانی‌های تکراری را تنظیم کنید.
- باید محافظت در برابر فراخوانی‌های تکراری را تنظیم کنید
- شما در حال ویرایش سیاست‌های ابزار/زمان اجرای عامل هستید
summary: نحوهٔ فعال‌سازی و تنظیم دقیق گاردریل‌هایی که حلقه‌های تکراری فراخوانی ابزار را شناسایی می‌کنند
summary: نحوهٔ فعال‌سازی و تنظیم سازوکارهای محافظتی که حلقه‌های تکراری فراخوانی ابزار را تشخیص می‌دهند
title: تشخیص حلقهٔ ابزار
x-i18n:
generated_at: "2026-05-03T21:42:16Z"
generated_at: "2026-05-05T01:52:30Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw می‌تواند از گیر کردن عامل‌ها در الگوهای تکراری فراخوانی ابزار جلوگیری کند.
این محافظ **به‌طور پیش‌فرض غیرفعال است**.
OpenClaw می‌تواند از گیرکردن عامل‌ها در الگوهای تکراری فراخوانی ابزار جلوگیری کند.
این محافظ به‌صورت **پیش‌فرض غیرفعال** است.
آن را فقط در جاهایی فعال کنید که لازم است، چون با تنظیمات سخت‌گیرانه می‌تواند فراخوانی‌های تکراریِ مشروع را مسدود کند.
آن را فقط در جاهایی که لازم است فعال کنید، چون با تنظیمات سخت‌گیرانه می‌تواند فراخوانی‌های تکراری مشروع را مسدود کند.
## چرا این وجود دارد
- شناسایی توالی‌های تکراری که پیشرفتی ایجاد نمی‌کنند.
- شناسایی حلقه‌های پرتکرارِ بدون نتیجه؛ مانند همان ابزار، همان ورودی‌ها، و خطاهای تکراری.
- شناسایی الگوهای مشخص فراخوانی تکراری برای ابزارهای شناخته‌شدهٔ پایش.
- شناسایی دنباله‌های تکراری که پیشرفتی ایجاد نمی‌کنند.
- شناسایی حلقه‌های پربسامد بدون نتیجه (همان ابزار، همان ورودی‌ها، خطاهای تکراری).
- شناسایی الگوهای مشخص فراخوانی تکراری برای ابزارهای نظرسنجی شناخته‌شده.
## بلوک پیکربندی
@ -71,44 +71,67 @@ OpenClaw می‌تواند از گیر کردن عامل‌ها در الگوه
### رفتار فیلدها
- `enabled`: کلید اصلی. `false` یعنی هیچ شناسایی حلقه‌ای انجام نمی‌شود.
- `enabled`: کلید اصلی. `false` یعنی هیچ تشخیص حلقه‌ای انجام نمی‌شود.
- `historySize`: تعداد فراخوانی‌های اخیر ابزار که برای تحلیل نگه داشته می‌شوند.
- `warningThreshold`: آستانهٔ پیش از دسته‌بندی یک الگو به‌عنوان فقط هشدار.
- `criticalThreshold`: آستانهٔ مسدود کردن الگوهای حلقه‌ای تکراری.
- `globalCircuitBreakerThreshold`: آستانهٔ قطع‌کنندهٔ سراسریِ بدون پیشرفت.
- `detectors.genericRepeat`: الگوهای تکراریِ همان ابزار + همان پارامترها را شناسایی می‌کند.
- `detectors.knownPollNoProgress`: الگوهای شناخته‌شدهٔ شبیه پایش را که تغییر وضعیت ندارند شناسایی می‌کند.
- `detectors.pingPong`: الگوهای رفت‌وبرگشتی متناوب را شناسایی می‌کند.
- `warningThreshold`: آستانه پیش از طبقه‌بندی یک الگو به‌عنوان فقط هشدار.
- `criticalThreshold`: آستانه مسدودسازی الگوهای حلقه تکراری.
- `globalCircuitBreakerThreshold`: آستانه قطع‌کننده سراسری برای نبود پیشرفت.
- `detectors.genericRepeat`: الگوهای تکراری ابزار یکسان + پارامترهای یکسان را شناسایی می‌کند.
- `detectors.knownPollNoProgress`: الگوهای شناخته‌شده شبیه نظرسنجی را که تغییر وضعیت ندارند شناسایی می‌کند.
- `detectors.pingPong`: الگوهای متناوب رفت‌وبرگشتی را شناسایی می‌کند.
برای `exec`، بررسی‌های بدون پیشرفت خروجی‌های پایدار فرمان را مقایسه می‌کنند و فرادادهٔ ناپایدار زمان اجرا مانند مدت‌زمان، PID، شناسهٔ نشست، و دایرکتوری کاری را نادیده می‌گیرند.
وقتی شناسهٔ اجرا در دسترس باشد، تاریخچهٔ اخیر فراخوانی ابزار فقط در همان اجرا ارزیابی می‌شود تا چرخه‌های Heartbeat زمان‌بندی‌شده و اجراهای تازه، شمارش‌های کهنهٔ حلقه را از اجراهای قبلی به ارث نبرند.
برای `exec`، بررسی‌های نبود پیشرفت خروجی‌های پایدار فرمان را مقایسه می‌کنند و فراداده‌های ناپایدار زمان اجرا مانند مدت‌زمان، PID، شناسه نشست و دایرکتوری کاری را نادیده می‌گیرند.
وقتی شناسه اجرا در دسترس باشد، تاریخچه اخیر فراخوانی ابزار فقط درون همان اجرا ارزیابی می‌شود تا چرخه‌های زمان‌بندی‌شده Heartbeat و اجراهای تازه شمارش‌های حلقه مانده از اجراهای قبلی را به ارث نبرند.
## راه‌اندازی پیشنهادی
- برای مدل‌های کوچک‌تر، با `enabled: true` و بدون تغییر پیش‌فرض‌ها شروع کنید. مدل‌های پرچم‌دار به‌ندرت به شناسایی حلقه نیاز دارند و می‌توانند آن را غیرفعال نگه دارند.
- برای مدل‌های کوچک‌تر، با `enabled: true` و بدون تغییر پیش‌فرض‌ها شروع کنید. مدل‌های پرچم‌دار به‌ندرت به تشخیص حلقه نیاز دارند و می‌توانند آن را غیرفعال نگه دارند.
- آستانه‌ها را به‌ترتیب `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold` نگه دارید.
- اگر مثبت‌های کاذب رخ داد:
- `warningThreshold` و/یا `criticalThreshold` را افزایش دهید
- در صورت تمایل، `globalCircuitBreakerThreshold` را افزایش دهید
- فقط همان آشکارسازی را که مشکل ایجاد می‌کند غیرفعال کنید
- برای بافت تاریخی کم‌سخت‌گیرانه‌تر، `historySize` را کاهش دهید
- (اختیاری) `globalCircuitBreakerThreshold` را افزایش دهید
- فقط آشکارسازی را که مشکل ایجاد می‌کند غیرفعال کنید
- برای زمینه تاریخی کمتر سخت‌گیرانه، `historySize` را کاهش دهید
## محافظ پس از Compaction
وقتی اجراکننده یک تلاش مجدد Compaction خودکار را کامل می‌کند (پس از سرریز زمینه)، یک محافظ با پنجره کوتاه فعال می‌کند که چند فراخوانی ابزار بعدی را زیر نظر می‌گیرد. اگر عامل سه‌تایی _یکسان_ `(toolName, args, result)` را چند بار در همان پنجره منتشر کند، محافظ نتیجه می‌گیرد که Compaction حلقه را نشکسته است و اجرا را با خطای `compaction_loop_persisted` متوقف می‌کند.
این مسیر کد از آشکارسازهای سراسری `tools.loopDetection` جداست. پیکربندی آن مستقل است:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: تعداد فراخوانی‌های ابزار پس از Compaction که در طول آن محافظ مسلح می‌ماند _و_ شمار سه‌تایی‌های یکسان (ابزار، آرگومان‌ها، نتیجه) که باعث توقف می‌شود.
محافظ هرگز وقتی نتایج در حال تغییر هستند اجرا را متوقف نمی‌کند، فقط وقتی نتایج در سراسر پنجره از نظر بایتی یکسان باشند. این عمدا محدود است: فقط بلافاصله پس از یک تلاش مجدد Compaction فعال می‌شود.
## گزارش‌ها و رفتار مورد انتظار
وقتی یک حلقه شناسایی شود، OpenClaw یک رویداد حلقه گزارش می‌کند و بسته به شدت، چرخهٔ ابزار بعدی را مسدود یا ملایم‌تر می‌کند.
این کار ضمن حفظ دسترسی عادی به ابزار، از کاربران در برابر مصرف بی‌رویهٔ توکن و قفل شدن محافظت می‌کند.
وقتی حلقه‌ای شناسایی می‌شود، OpenClaw یک رویداد حلقه گزارش می‌کند و بسته به شدت، چرخه ابزار بعدی را مسدود یا تضعیف می‌کند.
این کار ضمن حفظ دسترسی عادی به ابزارها، کاربران را از مصرف بی‌مهار توکن و قفل‌شدن محافظت می‌کند.
- ابتدا هشدار و سرکوب موقت را ترجیح دهید.
- فقط وقتی شواهد تکراری انباشته می‌شوند، شدت را افزایش دهید.
- فقط وقتی شواهد تکراری انباشته شد تشدید کنید.
## نکته‌ها
## نکات
- `tools.loopDetection` با بازنویسی‌های سطح عامل ادغام می‌شود.
- پیکربندی هر عامل، مقدارهای سراسری را به‌طور کامل بازنویسی یا گسترش می‌دهد.
- پیکربندی هر عامل، مقادیر سراسری را کاملا بازنویسی یا گسترش می‌دهد.
- اگر هیچ پیکربندی‌ای وجود نداشته باشد، محافظ‌ها خاموش می‌مانند.
## مرتبط
- [تأییدهای اجرا](/fa/tools/exec-approvals)
- [تأییدهای Exec](/fa/tools/exec-approvals)
- [سطوح تفکر](/fa/tools/thinking)
- [زیرعامل‌ها](/fa/tools/subagents)
- [عامل‌های فرعی](/fa/tools/subagents)

101
docs/fa/tools/media-overview.md
View File

@ -1,23 +1,23 @@
---
read_when:
- در جست‌وجوی نمایی کلی از قابلیت‌های رسانه‌ای OpenClaw
- تصمیم‌گیری دربارهٔ اینکه کدام ارائه‌دهندهٔ رسانه را پیکربندی کنید
- به‌دنبال نمای کلی از قابلیت‌های رسانه‌ای OpenClaw
- تصمیم‌گیری دربارهٔ ارائه‌دهندهٔ رسانه‌ای که باید پیکربندی شود
- درک نحوهٔ کار تولید رسانهٔ ناهمگام
sidebarTitle: Media overview
summary: قابلیت‌های تصویر، ویدئو، موسیقی، گفتار و درک رسانه در یک نگاه
title: نمای کلی رسانه
x-i18n:
generated_at: "2026-04-29T23:44:21Z"
generated_at: "2026-05-05T01:53:00Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
OpenClaw تصویر، ویدئو و موسیقی تولید می‌کند، رسانه‌های ورودی
(تصویر، صوت، ویدئو) را می‌فهمد و پاسخ‌ها را با تبدیل متن به گفتار بلند می‌خواند. همه
قابلیت‌های رسانه‌ای مبتنی بر ابزار هستند: عامل بر اساس
OpenClaw تصویر، ویدیو و موسیقی تولید می‌کند، رسانه‌های ورودی
(تصویر، صوت، ویدیو) را می‌فهمد، و پاسخ‌ها را با تبدیل متن به گفتار با صدای بلند بیان می‌کند. همه
قابلیت‌های رسانه‌ای ابزارمحور هستند: عامل بر اساس
گفت‌وگو تصمیم می‌گیرد چه زمانی از آن‌ها استفاده کند، و هر ابزار فقط زمانی ظاهر می‌شود که دست‌کم یک
ارائه‌دهنده پشتیبان پیکربندی شده باشد.
@ -25,34 +25,34 @@ OpenClaw تصویر، ویدئو و موسیقی تولید می‌کند، رس
<CardGroup cols={2}>
<Card title="Image generation" href="/fa/tools/image-generation" icon="image">
با استفاده از `image_generate` از اعلان‌های متنی یا تصاویر مرجع، تصویر ایجاد و ویرایش کنید.
همگام — درون پاسخ کامل می‌شود.
تصویرها را از اعلان‌های متنی یا تصویرهای مرجع از طریق
`image_generate` ایجاد و ویرایش کنید. همگام — درون‌خطی همراه با پاسخ کامل می‌شود.
</Card>
<Card title="Video generation" href="/fa/tools/video-generation" icon="video">
تبدیل متن به ویدئو، تصویر به ویدئو، و ویدئو به ویدئو با `video_generate`.
ناهمگام — در پس‌زمینه اجرا می‌شود و نتیجه را هنگام آماده شدن ارسال می‌کند.
متن‌به‌ویدیو، تصویر‌به‌ویدیو، و ویدیو‌به‌ویدیو از طریق `video_generate`.
ناهمگام — در پس‌زمینه اجرا می‌شود و وقتی آماده شد نتیجه را ارسال می‌کند.
</Card>
<Card title="Music generation" href="/fa/tools/music-generation" icon="music">
با استفاده از `music_generate` موسیقی یا ترک‌های صوتی تولید کنید. در ارائه‌دهندگان اشتراکی ناهمگام است؛
مسیر گردش‌کار ComfyUI به‌صورت همگام اجرا می‌شود.
موسیقی یا قطعه‌های صوتی را از طریق `music_generate` تولید کنید. در ارائه‌دهندگان اشتراکی
ناهمگام است؛ مسیر گردش‌کار ComfyUI به‌صورت همگام اجرا می‌شود.
</Card>
<Card title="Text-to-speech" href="/fa/tools/tts" icon="microphone">
پاسخ‌های خروجی را با ابزار `tts` به‌همراه پیکربندی
`messages.tts` به صوت گفتاری تبدیل کنید. همگام.
پاسخ‌های خروجی را از طریق ابزار `tts` به‌همراه پیکربندی
`messages.tts` به صدای گفتاری تبدیل کنید. همگام.
</Card>
<Card title="Media understanding" href="/fa/nodes/media-understanding" icon="eye">
تصاویر، صوت، و ویدئوهای ورودی را با استفاده از ارائه‌دهندگان مدل
دارای قابلیت بینایی و Pluginهای اختصاصی فهم رسانه خلاصه کنید.
تصویرها، صوت و ویدیوی ورودی را با استفاده از ارائه‌دهندگان مدل دارای قابلیت بینایی
و Pluginهای اختصاصی فهم رسانه خلاصه کنید.
</Card>
<Card title="Speech-to-text" href="/fa/nodes/audio" icon="ear-listen">
پیام‌های صوتی ورودی را از طریق STT دسته‌ای یا ارائه‌دهندگان
STT جریانی تماس صوتی رونویسی کنید.
پیام‌های صوتی ورودی را از طریق ارائه‌دهندگان STT دسته‌ای یا STT جریانی Voice Call
رونویسی کنید.
</Card>
</CardGroup>
## ماتریس قابلیت ارائه‌دهندگان
| ارائه‌دهنده | تصویر | ویدئو | موسیقی | TTS | STT | صدای بلادرنگ | فهم رسانه |
| ارائه‌دهنده | تصویر | ویدیو | موسیقی | TTS | STT | صدای بلادرنگ | فهم رسانه |
| ----------- | :---: | :---: | :---: | :-: | :-: | :------------: | :-----------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
@ -80,59 +80,60 @@ OpenClaw تصویر، ویدئو و موسیقی تولید می‌کند، رس
<Note>
فهم رسانه از هر مدل دارای قابلیت بینایی یا صوت که در پیکربندی ارائه‌دهنده شما ثبت شده باشد استفاده می‌کند.
ماتریس بالا ارائه‌دهندگانی را فهرست می‌کند که پشتیبانی اختصاصی
فهم رسانه دارند؛ بیشتر ارائه‌دهندگان LLM چندوجهی (Anthropic، Google،
OpenAI و غیره) نیز وقتی به‌عنوان مدل فعال پاسخ پیکربندی شوند می‌توانند رسانه ورودی را بفهمند.
از فهم رسانه دارند؛ بیشتر ارائه‌دهندگان LLM چندوجهی (Anthropic، Google،
OpenAI و غیره) نیز وقتی به‌عنوان مدل پاسخ فعال پیکربندی شوند می‌توانند رسانه ورودی را بفهمند.
</Note>
## ناهمگام در برابر همگام
| قابلیت | حالت | دلیل |
| --------------- | ------------ | ------------------------------------------------------------------ |
| تصویر | همگام | پاسخ‌های ارائه‌دهنده در چند ثانیه برمی‌گردند؛ درون پاسخ کامل می‌شود. |
| تبدیل متن به گفتار | همگام | پاسخ‌های ارائه‌دهنده در چند ثانیه برمی‌گردند؛ به صدای پاسخ پیوست می‌شوند. |
| ویدئو | ناهمگام | پردازش ارائه‌دهنده از ۳۰ ثانیه تا چند دقیقه طول می‌کشد. |
| موسیقی (اشتراکی) | ناهمگام | همان ویژگی پردازشی ارائه‌دهنده مانند ویدئو را دارد. |
| موسیقی (ComfyUI) | همگام | گردش‌کار محلی به‌صورت درون‌خطی در برابر سرور پیکربندی‌شده ComfyUI اجرا می‌شود. |
| تصویر | همگام | پاسخ‌های ارائه‌دهنده در چند ثانیه برمی‌گردند؛ درون‌خطی همراه با پاسخ کامل می‌شود. |
| تبدیل متن به گفتار | همگام | پاسخ‌های ارائه‌دهنده در چند ثانیه برمی‌گردند؛ به صدای پاسخ پیوست می‌شود. |
| ویدیو | ناهمگام | پردازش ارائه‌دهنده از ۳۰ ثانیه تا چند دقیقه طول می‌کشد. |
| موسیقی (اشتراکی) | ناهمگام | همان ویژگی پردازش ارائه‌دهنده مثل ویدیو را دارد. |
| موسیقی (ComfyUI) | همگام | گردش‌کار محلی به‌صورت درون‌خطی روی سرور ComfyUI پیکربندی‌شده اجرا می‌شود. |
برای ابزارهای ناهمگام، OpenClaw درخواست را به ارائه‌دهنده ارسال می‌کند، بلافاصله یک شناسه وظیفه
برمی‌گرداند، و کار را در دفتر وظایف پیگیری می‌کند. عامل در حالی که کار اجرا می‌شود به پاسخ‌گویی
به پیام‌های دیگر ادامه می‌دهد. وقتی ارائه‌دهنده کار را تمام کرد،
OpenClaw عامل را بیدار می‌کند تا بتواند رسانه تکمیل‌شده را دوباره در
کانال اصلی ارسال کند.
برای ابزارهای ناهمگام، OpenClaw درخواست را به ارائه‌دهنده ارسال می‌کند، یک شناسه وظیفه
را فوراً برمی‌گرداند، و کار را در دفترکل وظایف پیگیری می‌کند. عامل در حالی که کار اجرا می‌شود
به پاسخ‌دادن به پیام‌های دیگر ادامه می‌دهد. وقتی ارائه‌دهنده کار را تمام کرد،
OpenClaw عامل را با مسیرهای رسانه تولیدشده بیدار می‌کند تا بتواند به
کاربر اطلاع دهد و، وقتی سیاست تحویل منبع لازم بداند، نتیجه را از طریق
ابزار پیام بازپخش کند.
## تبدیل گفتار به متن و تماس صوتی
## گفتار به متن و Voice Call
Deepgram، DeepInfra، ElevenLabs، Mistral، OpenAI، SenseAudio، و xAI همگی می‌توانند
صوت ورودی را از طریق مسیر دسته‌ای `tools.media.audio` در صورت پیکربندی رونویسی کنند.
Pluginهای کانالی که یک یادداشت صوتی را برای دروازه‌گذاری ذکر یا
Deepgram، DeepInfra، ElevenLabs، Mistral، OpenAI، SenseAudio و xAI همگی می‌توانند
صوت ورودی را از طریق مسیر دسته‌ای `tools.media.audio` هنگام پیکربندی رونویسی کنند.
Pluginهای کانال که یک یادداشت صوتی را برای دروازه‌گذاری اشاره یا
تجزیه فرمان پیش‌بررسی می‌کنند، پیوست رونویسی‌شده را روی زمینه ورودی علامت‌گذاری می‌کنند، بنابراین گذر مشترک
فهم رسانه به‌جای انجام دومین فراخوانی
STT برای همان صوت، از همان رونویسی دوباره استفاده می‌کند.
فهم رسانه به‌جای انجام یک فراخوان STT دوم برای همان صوت،
از همان رونویسی دوباره استفاده می‌کند.
Deepgram، ElevenLabs، Mistral، OpenAI، و xAI همچنین ارائه‌دهندگان
STT جریانی تماس صوتی را ثبت می‌کنند، بنابراین صوت زنده تلفن می‌تواند بدون انتظار برای یک ضبط تکمیل‌شده
Deepgram، ElevenLabs، Mistral، OpenAI و xAI همچنین ارائه‌دهندگان STT جریانی Voice Call
را ثبت می‌کنند، بنابراین صدای زنده تلفن می‌تواند بدون انتظار برای ضبط کامل
به فروشنده انتخاب‌شده ارسال شود.
## نگاشت‌های ارائه‌دهنده (نحوه تقسیم فروشندگان بین سطوح)
## نگاشت ارائه‌دهندگان (نحوه تقسیم فروشندگان در سطح‌های مختلف)
<AccordionGroup>
<Accordion title="Google">
سطوح تصویر، ویدئو، موسیقی، TTS دسته‌ای، صدای بلادرنگ بک‌اند، و
سطح‌های تصویر، ویدیو، موسیقی، TTS دسته‌ای، صدای بلادرنگ بک‌اند، و
فهم رسانه.
</Accordion>
<Accordion title="OpenAI">
سطوح تصویر، ویدئو، TTS دسته‌ای، STT دسته‌ای، STT جریانی تماس صوتی،
صدای بلادرنگ بک‌اند، و تعبیه حافظه.
سطح‌های تصویر، ویدیو، TTS دسته‌ای، STT دسته‌ای، STT جریانی Voice Call، صدای
بلادرنگ بک‌اند، و جاسازی حافظه.
</Accordion>
<Accordion title="DeepInfra">
سطوح مسیریابی چت/مدل، تولید/ویرایش تصویر، تبدیل متن به ویدئو، TTS دسته‌ای،
STT دسته‌ای، فهم رسانه تصویر، و تعبیه حافظه.
مدل‌های بومی DeepInfra برای رتبه‌بندی مجدد/طبقه‌بندی/تشخیص شیء تا زمانی که OpenClaw قراردادهای اختصاصی ارائه‌دهنده برای آن
سطح‌های مسیریابی گفت‌وگو/مدل، تولید/ویرایش تصویر، متن‌به‌ویدیو، TTS دسته‌ای،
STT دسته‌ای، فهم رسانه تصویر، و جاسازی حافظه.
مدل‌های بازرتبه‌بندی/طبقه‌بندی/تشخیص شیء بومی DeepInfra تا زمانی که OpenClaw قراردادهای ارائه‌دهنده اختصاصی برای آن
دسته‌ها نداشته باشد ثبت نمی‌شوند.
</Accordion>
<Accordion title="xAI">
تصویر، ویدئو، جست‌وجو، اجرای کد، TTS دسته‌ای، STT دسته‌ای، و
STT جریانی تماس صوتی. صدای بلادرنگ xAI یک قابلیت بالادستی است اما تا زمانی که قرارداد مشترک صدای بلادرنگ بتواند
تصویر، ویدیو، جست‌وجو، اجرای کد، TTS دسته‌ای، STT دسته‌ای، و STT جریانی Voice
Call. صدای بلادرنگ xAI یک قابلیت بالادستی است اما تا زمانی که قرارداد مشترک صدای بلادرنگ بتواند
آن را نمایش دهد، در OpenClaw ثبت نمی‌شود.
</Accordion>
</AccordionGroup>
@ -140,7 +141,7 @@ STT جریانی تماس صوتی را ثبت می‌کنند، بنابرای
## مرتبط
- [تولید تصویر](/fa/tools/image-generation)
- [تولید ویدئو](/fa/tools/video-generation)
- [تولید ویدیو](/fa/tools/video-generation)
- [تولید موسیقی](/fa/tools/music-generation)
- [تبدیل متن به گفتار](/fa/tools/tts)
- [فهم رسانه](/fa/nodes/media-understanding)

191
docs/fa/tools/music-generation.md
View File

@ -1,26 +1,36 @@
---
read_when:
- تولید موسیقی یا صدا از طریق عامل
- تولید موسیقی یا صوت از طریق عامل
- پیکربندی ارائه‌دهندگان و مدل‌های تولید موسیقی
- درک پارامترهای ابزار music_generate
- آشنایی با پارامترهای ابزار music_generate
sidebarTitle: Music generation
summary: موسیقی را از طریق music_generate در گردش‌کارهای Google Lyria، MiniMax و ComfyUI تولید کنید
title: تولید موسیقی
x-i18n:
generated_at: "2026-05-02T12:06:04Z"
generated_at: "2026-05-05T01:53:22Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
ابزار `music_generate` به عامل اجازه می‌دهد از طریق قابلیت مشترک تولید موسیقی با ارائه‌دهندگان پیکربندی‌شده، موسیقی یا صدا بسازد — در حال حاضر Google، MiniMax، و ComfyUI پیکربندی‌شده با گردش‌کار.
ابزار `music_generate` به عامل امکان می‌دهد از طریق قابلیت مشترک
تولید موسیقی با ارائه‌دهنده‌های پیکربندی‌شده، موسیقی یا صدا ایجاد کند؛
امروز شامل Google، MiniMax و ComfyUI پیکربندی‌شده با گردش‌کار است.
برای اجراهای عاملِ پشتیبانی‌شده با نشست، OpenClaw تولید موسیقی را به‌عنوان یک وظیفه پس‌زمینه شروع می‌کند، آن را در دفتر وظایف پیگیری می‌کند، سپس وقتی قطعه آماده شد عامل را دوباره بیدار می‌کند تا عامل بتواند صدای نهایی را به کانال اصلی برگرداند.
برای اجراهای عامل مبتنی بر نشست، OpenClaw تولید موسیقی را به‌صورت یک
وظیفه پس‌زمینه شروع می‌کند، آن را در دفتر ثبت وظایف پیگیری می‌کند، سپس
وقتی ترک آماده شد عامل را دوباره بیدار می‌کند تا عامل بتواند به کاربر
اطلاع دهد و صدای نهایی را پیوست کند. در گفت‌وگوهای گروهی/کانالی که از
تحویل قابل‌مشاهده فقط از طریق ابزار پیام استفاده می‌کنند، عامل نتیجه را
از طریق ابزار پیام منتقل می‌کند.
<Note>
ابزار مشترک داخلی فقط وقتی ظاهر می‌شود که حداقل یک ارائه‌دهنده تولید موسیقی در دسترس باشد. اگر `music_generate` را در ابزارهای عامل خود نمی‌بینید، `agents.defaults.musicGenerationModel` را پیکربندی کنید یا کلید API یک ارائه‌دهنده را تنظیم کنید.
ابزار مشترک داخلی فقط وقتی ظاهر می‌شود که حداقل یک ارائه‌دهنده تولید
موسیقی در دسترس باشد. اگر `music_generate` را در ابزارهای عامل خود
نمی‌بینید، `agents.defaults.musicGenerationModel` را پیکربندی کنید یا
یک کلید API ارائه‌دهنده تنظیم کنید.
</Note>
## شروع سریع
@ -29,7 +39,7 @@ x-i18n:
<Tab title="پشتیبانی‌شده با ارائه‌دهنده مشترک">
<Steps>
<Step title="پیکربندی احراز هویت">
برای حداقل یک ارائه‌دهنده یک کلید API تنظیم کنید — برای نمونه
برای حداقل یک ارائه‌دهنده یک کلید API تنظیم کنید؛ برای مثال
`GEMINI_API_KEY` یا `MINIMAX_API_KEY`.
</Step>
<Step title="انتخاب مدل پیش‌فرض (اختیاری)">
@ -45,20 +55,25 @@ x-i18n:
}
```
</Step>
<Step title="از عامل درخواست کنید">
_"یک قطعه سینث‌پاپ پرانرژی درباره رانندگی شبانه در یک شهر نئونی بساز."_
<Step title="درخواست از عامل">
_«یک ترک synthpop پرانرژی درباره رانندگی شبانه در یک شهر نئونی
تولید کن.»_
عامل به‌صورت خودکار `music_generate` را فراخوانی می‌کند. نیازی به فهرست مجاز ابزار نیست.
عامل به‌طور خودکار `music_generate` را فراخوانی می‌کند. نیازی به
قرار دادن ابزار در فهرست مجاز نیست.
</Step>
</Steps>
برای زمینه‌های همگام مستقیم بدون اجرای عاملِ پشتیبانی‌شده با نشست، ابزار داخلی همچنان به تولید درون‌خطی بازمی‌گردد و مسیر رسانه نهایی را در نتیجه ابزار برمی‌گرداند.
برای زمینه‌های همگام مستقیم بدون اجرای عامل مبتنی بر نشست، ابزار
داخلی همچنان به تولید درون‌خطی بازمی‌گردد و مسیر رسانه نهایی را در
نتیجه ابزار برمی‌گرداند.
</Tab>
<Tab title="گردش‌کار ComfyUI">
<Steps>
<Step title="پیکربندی گردش‌کار">
`plugins.entries.comfy.config.music` را با JSON گردش‌کار و گره‌های اعلان/خروجی پیکربندی کنید.
`plugins.entries.comfy.config.music` را با JSON گردش‌کار و
گره‌های prompt/output پیکربندی کنید.
</Step>
<Step title="احراز هویت ابری (اختیاری)">
برای Comfy Cloud، `COMFY_API_KEY` یا `COMFY_CLOUD_API_KEY` را تنظیم کنید.
@ -72,7 +87,7 @@ x-i18n:
</Tab>
</Tabs>
نمونه اعلان‌ها:
نمونه promptها:
```text
Generate a cinematic piano track with soft strings and no vocals.
@ -82,31 +97,33 @@ Generate a cinematic piano track with soft strings and no vocals.
Generate an energetic chiptune loop about launching a rocket at sunrise.
```
## ارائه‌دهندگان پشتیبانی‌شده
## ارائه‌دهنده‌های پشتیبانی‌شده
| ارائه‌دهنده | مدل پیش‌فرض | ورودی‌های مرجع | کنترل‌های پشتیبانی‌شده | احراز هویت |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | تا 1 تصویر | موسیقی یا صدای تعریف‌شده با گردش‌کار | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | تا 10 تصویر | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | هیچ‌کدام | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` یا MiniMax OAuth |
| ComfyUI | `workflow` | حداکثر ۱ تصویر | موسیقی یا صدای تعریف‌شده توسط گردش‌کار | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | حداکثر ۱۰ تصویر | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | هیچ‌کدام | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` یا OAuth در MiniMax |
### ماتریس قابلیت
### ماتریس قابلیت‌ها
قرارداد حالت صریحی که `music_generate`، آزمون‌های قرارداد، و پیمایش زنده مشترک استفاده می‌کنند:
قرارداد حالت صریحی که توسط `music_generate`، آزمون‌های قرارداد و پیمایش
زنده مشترک استفاده می‌شود:
| ارائه‌دهنده | `generate` | `edit` | محدودیت ویرایش | مسیرهای زنده مشترک |
| ارائه‌دهنده | `generate` | `edit` | حد ویرایش | مسیرهای زنده مشترک |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 تصویر | در پیمایش مشترک نیست؛ با `extensions/comfy/comfy.live.test.ts` پوشش داده می‌شود |
| Google | ✓ | ✓ | 10 تصویر | `generate`, `edit` |
| ComfyUI | ✓ | ✓ | ۱ تصویر | در پیمایش مشترک نیست؛ توسط `extensions/comfy/comfy.live.test.ts` پوشش داده می‌شود |
| Google | ✓ | ✓ | ۱۰ تصویر | `generate`, `edit` |
| MiniMax | ✓ | — | هیچ‌کدام | `generate` |
برای بررسی ارائه‌دهندگان و مدل‌های مشترک در دسترس در زمان اجرا، از `action: "list"` استفاده کنید:
برای بررسی ارائه‌دهنده‌ها و مدل‌های مشترک موجود در زمان اجرا، از
`action: "list"` استفاده کنید:
```text
/tool music_generate action=list
```
برای بررسی وظیفه موسیقی فعالِ پشتیبانی‌شده با نشست، از `action: "status"` استفاده کنید:
برای بررسی وظیفه موسیقی فعال مبتنی بر نشست، از `action: "status"` استفاده کنید:
```text
/tool music_generate action=status
@ -121,29 +138,29 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## پارامترهای ابزار
<ParamField path="prompt" type="string" required>
اعلان تولید موسیقی. برای `action: "generate"` الزامی است.
prompt تولید موسیقی. برای `action: "generate"` الزامی است.
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` وظیفه نشست فعلی را برمی‌گرداند؛ `"list"` ارائه‌دهندگان را بررسی می‌کند.
`"status"` وظیفه نشست فعلی را برمی‌گرداند؛ `"list"` ارائه‌دهنده‌ها را بررسی می‌کند.
</ParamField>
<ParamField path="model" type="string">
بازنویسی ارائه‌دهنده/مدل (مانند `google/lyria-3-pro-preview`،
بازنویسی ارائه‌دهنده/مدل (مثلاً `google/lyria-3-pro-preview`،
`comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
متن ترانه اختیاری وقتی ارائه‌دهنده از ورودی صریح متن ترانه پشتیبانی می‌کند.
شعر اختیاری وقتی ارائه‌دهنده از ورودی صریح شعر پشتیبانی می‌کند.
</ParamField>
<ParamField path="instrumental" type="boolean">
وقتی ارائه‌دهنده پشتیبانی می‌کند، خروجی فقط‌سازی را درخواست کنید.
وقتی ارائه‌دهنده پشتیبانی می‌کند، خروجی فقط بی‌کلام درخواست کنید.
</ParamField>
<ParamField path="image" type="string">
مسیر یا URL یک تصویر مرجع.
</ParamField>
<ParamField path="images" type="string[]">
چند تصویر مرجع (تا 10 تصویر در ارائه‌دهندگان پشتیبان).
چند تصویر مرجع (تا ۱۰ مورد در ارائه‌دهنده‌های پشتیبانی‌کننده).
</ParamField>
<ParamField path="durationSeconds" type="number">
مدت زمان هدف بر حسب ثانیه وقتی ارائه‌دهنده از راهنمای مدت زمان پشتیبانی می‌کند.
مدت هدف بر حسب ثانیه وقتی ارائه‌دهنده از راهنمایی مدت پشتیبانی می‌کند.
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
راهنمای قالب خروجی وقتی ارائه‌دهنده از آن پشتیبانی می‌کند.
@ -152,30 +169,47 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
<ParamField path="timeoutMs" type="number">مهلت زمانی اختیاری درخواست ارائه‌دهنده بر حسب میلی‌ثانیه. مقدارهای کمتر از 10000ms به 10000ms افزایش داده می‌شوند و در نتیجه ابزار گزارش می‌شوند.</ParamField>
<Note>
همه ارائه‌دهندگان از همه پارامترها پشتیبانی نمی‌کنند. OpenClaw همچنان محدودیت‌های سخت مانند شمار ورودی‌ها را پیش از ارسال اعتبارسنجی می‌کند. وقتی ارائه‌دهنده از مدت زمان پشتیبانی می‌کند اما بیشینه‌ای کوتاه‌تر از مقدار درخواستی دارد، OpenClaw مقدار را به نزدیک‌ترین مدت زمان پشتیبانی‌شده محدود می‌کند. راهنمایی‌های اختیاری واقعا پشتیبانی‌نشده، وقتی ارائه‌دهنده یا مدل انتخاب‌شده نتواند آن‌ها را رعایت کند، با یک هشدار نادیده گرفته می‌شوند. نتایج ابزار تنظیمات اعمال‌شده را گزارش می‌کنند؛ `details.normalization` هر نگاشت از درخواستی به اعمال‌شده را ثبت می‌کند.
همه ارائه‌دهنده‌ها از همه پارامترها پشتیبانی نمی‌کنند. OpenClaw همچنان
حدهای سخت مانند تعداد ورودی‌ها را پیش از ارسال اعتبارسنجی می‌کند. وقتی
ارائه‌دهنده از مدت پشتیبانی می‌کند اما حداکثری کوتاه‌تر از مقدار
درخواست‌شده دارد، OpenClaw آن را به نزدیک‌ترین مدت پشتیبانی‌شده محدود
می‌کند. راهنمایی‌های اختیاری واقعاً پشتیبانی‌نشده، وقتی ارائه‌دهنده یا
مدل انتخاب‌شده نتواند آن‌ها را رعایت کند، با یک هشدار نادیده گرفته
می‌شوند. نتایج ابزار تنظیمات اعمال‌شده را گزارش می‌کنند؛
`details.normalization` هر نگاشت درخواست‌شده‌به‌اعمال‌شده را ثبت می‌کند.
</Note>
## رفتار ناهمگام
تولید موسیقی پشتیبانی‌شده با نشست به‌عنوان یک وظیفه پس‌زمینه اجرا می‌شود:
تولید موسیقی مبتنی بر نشست به‌صورت یک وظیفه پس‌زمینه اجرا می‌شود:
- **وظیفه پس‌زمینه:** `music_generate` یک وظیفه پس‌زمینه ایجاد می‌کند، بلافاصله یک پاسخ شروع‌شده/وظیفه برمی‌گرداند، و قطعه نهایی را بعدا در یک پیام پیگیری عامل ارسال می‌کند.
- **پیشگیری از تکرار:** وقتی یک وظیفه `queued` یا `running` است، فراخوانی‌های بعدی `music_generate` در همان نشست به‌جای شروع یک تولید دیگر، وضعیت وظیفه را برمی‌گردانند. برای بررسی صریح از `action: "status"` استفاده کنید.
- **جست‌وجوی وضعیت:** `openclaw tasks list` یا `openclaw tasks show <taskId>` وضعیت‌های در صف، در حال اجرا، و پایانی را بررسی می‌کند.
- **بیدارسازی تکمیل:** OpenClaw یک رویداد تکمیل داخلی را به همان نشست تزریق می‌کند تا مدل بتواند خودش پیام پیگیری کاربرمحور را بنویسد.
- **راهنمای اعلان:** نوبت‌های کاربر/دستی بعدی در همان نشست، وقتی یک وظیفه موسیقی از قبل در جریان است، یک راهنمای کوچک زمان اجرا دریافت می‌کنند تا مدل کورکورانه دوباره `music_generate` را فراخوانی نکند.
- **بازگشت بدون نشست:** زمینه‌های مستقیم/محلی بدون نشست واقعی عامل، درون‌خطی اجرا می‌شوند و نتیجه صدای نهایی را در همان نوبت برمی‌گردانند.
- **وظیفه پس‌زمینه:** `music_generate` یک وظیفه پس‌زمینه ایجاد می‌کند،
بلافاصله یک پاسخ شروع‌شده/وظیفه برمی‌گرداند، و ترک نهایی را بعداً در
یک پیام پیگیری عامل ارسال می‌کند.
- **جلوگیری از تکرار:** تا زمانی که یک وظیفه در حالت `queued` یا
`running` باشد، فراخوانی‌های بعدی `music_generate` در همان نشست به‌جای
شروع تولید دیگر، وضعیت وظیفه را برمی‌گردانند. برای بررسی صریح از
`action: "status"` استفاده کنید.
- **جست‌وجوی وضعیت:** `openclaw tasks list` یا `openclaw tasks show <taskId>`
وضعیت‌های در صف، در حال اجرا و پایانی را بررسی می‌کند.
- **بیدارسازی پس از تکمیل:** OpenClaw یک رویداد تکمیل داخلی را دوباره به
همان نشست تزریق می‌کند تا مدل بتواند خودش پیگیری رو به کاربر را بنویسد.
- **راهنمای prompt:** نوبت‌های بعدی کاربر/دستی در همان نشست، وقتی یک
وظیفه موسیقی از قبل در جریان باشد، یک راهنمای کوچک زمان اجرا دریافت
می‌کنند تا مدل کورکورانه دوباره `music_generate` را فراخوانی نکند.
- **بازگشت بدون نشست:** زمینه‌های مستقیم/محلی بدون نشست واقعی عامل به‌صورت
درون‌خطی اجرا می‌شوند و نتیجه صوتی نهایی را در همان نوبت برمی‌گردانند.
### چرخه عمر وظیفه
| وضعیت | معنی |
| وضعیت | معنا |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | وظیفه ایجاد شده و منتظر پذیرش از سوی ارائه‌دهنده است. |
| `running` | ارائه‌دهنده در حال پردازش است (معمولا 30 ثانیه تا 3 دقیقه بسته به ارائه‌دهنده و مدت زمان). |
| `succeeded` | قطعه آماده است؛ عامل بیدار می‌شود و آن را به گفت‌وگو ارسال می‌کند. |
| `failed` | خطای ارائه‌دهنده یا اتمام مهلت زمانی؛ عامل با جزئیات خطا بیدار می‌شود. |
| `queued` | وظیفه ایجاد شده و منتظر پذیرش توسط ارائه‌دهنده است. |
| `running` | ارائه‌دهنده در حال پردازش است (معمولاً ۳۰ ثانیه تا ۳ دقیقه بسته به ارائه‌دهنده و مدت). |
| `succeeded` | ترک آماده است؛ عامل بیدار می‌شود و آن را در گفت‌وگو ارسال می‌کند. |
| `failed` | خطای ارائه‌دهنده یا پایان مهلت زمانی؛ عامل با جزئیات خطا بیدار می‌شود. |
وضعیت را از CLI بررسی کنید:
بررسی وضعیت از CLI:
```bash
openclaw tasks list
@ -202,48 +236,59 @@ openclaw tasks cancel <taskId>
### ترتیب انتخاب ارائه‌دهنده
OpenClaw ارائه‌دهندگان را به این ترتیب امتحان می‌کند:
OpenClaw ارائه‌دهنده‌ها را به این ترتیب امتحان می‌کند:
1. پارامتر `model` از فراخوانی ابزار (اگر عامل یکی را مشخص کند).
1. پارامتر `model` از فراخوانی ابزار (اگر عامل یکی مشخص کند).
2. `musicGenerationModel.primary` از پیکربندی.
3. `musicGenerationModel.fallbacks` به‌ترتیب.
4. تشخیص خودکار فقط با استفاده از پیش‌فرض‌های ارائه‌دهنده دارای احراز هویت:
- ابتدا ارائه‌دهنده پیش‌فرض فعلی؛
- سپس سایر ارائه‌دهندگان ثبت‌شده تولید موسیقی به‌ترتیب شناسه ارائه‌دهنده.
- سپس سایر ارائه‌دهنده‌های ثبت‌شده تولید موسیقی به ترتیب provider-id.
اگر یک ارائه‌دهنده شکست بخورد، نامزد بعدی به‌صورت خودکار امتحان می‌شود. اگر همه شکست بخورند، خطا شامل جزئیات هر تلاش خواهد بود.
اگر یک ارائه‌دهنده شکست بخورد، نامزد بعدی به‌طور خودکار امتحان می‌شود.
اگر همه شکست بخورند، خطا شامل جزئیات هر تلاش خواهد بود.
برای استفاده فقط از ورودی‌های صریح `model`، `primary`، و `fallbacks`، `agents.defaults.mediaGenerationAutoProviderFallback: false` را تنظیم کنید.
برای استفاده فقط از ورودی‌های صریح `model`، `primary` و `fallbacks`،
`agents.defaults.mediaGenerationAutoProviderFallback: false` را تنظیم کنید.
## یادداشت‌های ارائه‌دهنده
<AccordionGroup>
<Accordion title="ComfyUI">
مبتنی بر گردش‌کار است و به گراف پیکربندی‌شده به‌همراه نگاشت گره‌ها برای فیلدهای اعلان/خروجی وابسته است. Plugin داخلی `comfy` از طریق رجیستری ارائه‌دهنده تولید موسیقی به ابزار مشترک `music_generate` متصل می‌شود.
مبتنی بر گردش‌کار است و به گراف پیکربندی‌شده به‌همراه نگاشت گره‌ها
برای فیلدهای prompt/output وابسته است. Plugin همراه `comfy` از طریق
رجیستری ارائه‌دهنده تولید موسیقی به ابزار مشترک `music_generate` متصل می‌شود.
</Accordion>
<Accordion title="Google (Lyria 3)">
از تولید دسته‌ای Lyria 3 استفاده می‌کند. جریان داخلی فعلی از اعلان، متن ترانه اختیاری، و تصاویر مرجع اختیاری پشتیبانی می‌کند.
از تولید دسته‌ای Lyria 3 استفاده می‌کند. جریان همراه فعلی از prompt،
متن اختیاری شعر و تصاویر مرجع اختیاری پشتیبانی می‌کند.
</Accordion>
<Accordion title="MiniMax">
از endpoint دسته‌ای `music_generation` استفاده می‌کند. از اعلان، متن ترانه اختیاری، حالت سازی، هدایت مدت زمان، و خروجی mp3 از طریق احراز هویت کلید API با `minimax` یا OAuth با `minimax-portal` پشتیبانی می‌کند.
از نقطه پایانی دسته‌ای `music_generation` استفاده می‌کند. از prompt،
شعر اختیاری، حالت بی‌کلام، هدایت مدت و خروجی mp3 از طریق احراز هویت
کلید API با `minimax` یا OAuth با `minimax-portal` پشتیبانی می‌کند.
</Accordion>
</AccordionGroup>
## انتخاب مسیر مناسب
## انتخاب مسیر درست
- **پشتیبانی‌شده با ارائه‌دهنده مشترک** وقتی انتخاب مدل، جایگزینی ارائه‌دهنده در صورت شکست، و جریان داخلی ناهمگام وظیفه/وضعیت را می‌خواهید.
- **مسیر Plugin (ComfyUI)** وقتی به یک گراف گردش‌کار سفارشی یا ارائه‌دهنده‌ای نیاز دارید که بخشی از قابلیت موسیقی مشترک داخلی نیست.
- **پشتیبانی‌شده با ارائه‌دهنده مشترک** وقتی انتخاب مدل، جایگزینی خودکار
ارائه‌دهنده هنگام شکست، و جریان داخلی ناهمگام وظیفه/وضعیت را می‌خواهید.
- **مسیر Plugin (ComfyUI)** وقتی به گراف گردش‌کار سفارشی یا ارائه‌دهنده‌ای
نیاز دارید که بخشی از قابلیت مشترک موسیقی همراه نیست.
اگر در حال اشکال‌زدایی رفتار ویژه ComfyUI هستید، [ComfyUI](/fa/providers/comfy) را ببینید. اگر در حال اشکال‌زدایی رفتار ارائه‌دهنده مشترک هستید، از [Google (Gemini)](/fa/providers/google) یا [MiniMax](/fa/providers/minimax) شروع کنید.
اگر رفتار مختص ComfyUI را اشکال‌زدایی می‌کنید، [ComfyUI](/fa/providers/comfy)
را ببینید. اگر رفتار ارائه‌دهنده مشترک را اشکال‌زدایی می‌کنید، با
[Google (Gemini)](/fa/providers/google) یا [MiniMax](/fa/providers/minimax) شروع کنید.
## حالت‌های قابلیت ارائه‌دهنده
قرارداد مشترک تولید موسیقی از اعلان‌های حالت صریح پشتیبانی می‌کند:
- `generate` برای تولید فقط با اعلان.
- `edit` وقتی درخواست شامل یک یا چند تصویر مرجع است.
- `generate` برای تولید فقط با prompt.
- `edit` وقتی درخواست شامل یک یا چند تصویر مرجع باشد.
پیاده‌سازی‌های جدید ارائه‌دهنده باید بلوک‌های حالت صریح را ترجیح دهند:
پیاده‌سازی‌های ارائه‌دهنده جدید باید بلوک‌های حالت صریح را ترجیح دهند:
```typescript
capabilities: {
@ -261,43 +306,49 @@ capabilities: {
}
```
فیلدهای تخت قدیمی مانند `maxInputImages`، `supportsLyrics`، و `supportsFormat` برای اعلام پشتیبانی ویرایش **کافی نیستند**. ارائه‌دهندگان باید `generate` و `edit` را صریح اعلام کنند تا آزمون‌های زنده، آزمون‌های قرارداد، و ابزار مشترک `music_generate` بتوانند پشتیبانی حالت را به‌صورت قطعی اعتبارسنجی کنند.
فیلدهای تخت قدیمی مانند `maxInputImages`، `supportsLyrics` و
`supportsFormat` برای اعلام پشتیبانی از ویرایش **کافی نیستند**.
ارائه‌دهنده‌ها باید `generate` و `edit` را به‌صراحت اعلام کنند تا
آزمون‌های زنده، آزمون‌های قرارداد و ابزار مشترک `music_generate` بتوانند
پشتیبانی از حالت را به‌صورت قطعی اعتبارسنجی کنند.
## آزمون‌های زنده
پوشش زنده اختیاری برای ارائه‌دهندگان داخلی مشترک:
پوشش زنده اختیاری برای ارائه‌دهنده‌های همراه مشترک:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```
پوشش repo:
wrapper مخزن:
```bash
pnpm test:live:media music
```
این فایل زنده متغیرهای محیطی ارائه‌دهنده مفقود را از `~/.profile` بارگذاری می‌کند، به‌صورت پیش‌فرض کلیدهای API زنده/محیطی را بر پروفایل‌های احراز هویت ذخیره‌شده ترجیح می‌دهد، و وقتی ارائه‌دهنده حالت ویرایش را فعال می‌کند، هم پوشش `generate` و هم پوشش اعلام‌شده `edit` را اجرا می‌کند. پوشش امروز:
این فایل زنده env varهای ارائه‌دهنده گمشده را از `~/.profile` بارگذاری
می‌کند، به‌طور پیش‌فرض کلیدهای API زنده/env را بر نمایه‌های احراز هویت
ذخیره‌شده ترجیح می‌دهد، و وقتی ارائه‌دهنده حالت ویرایش را فعال کرده باشد،
هم پوشش `generate` و هم پوشش `edit` اعلام‌شده را اجرا می‌کند. پوشش فعلی:
- `google`: `generate` به‌همراه `edit`
- `minimax`: فقط `generate`
- `comfy`: پوشش زنده جداگانه Comfy، نه پیمایش ارائه‌دهنده مشترک
پوشش زنده اختیاری برای مسیر موسیقی داخلی ComfyUI:
پوشش زنده اختیاری برای مسیر موسیقی ComfyUI همراه:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
فایل زندهٔ Comfy همچنین گردش‌کارهای تصویر و ویدئوی Comfy را پوشش می‌دهد، وقتی آن
بخش‌ها پیکربندی شده باشند.
فایل زندهٔ Comfy همچنین گردش‌کارهای تصویر و ویدیوی Comfy را وقتی آن بخش‌ها پیکربندی شده باشند پوشش می‌دهد.
## مرتبط
- [کارهای پس‌زمینه](/fa/automation/tasks) — رهگیری کار برای اجراهای جداشدهٔ `music_generate`
- [وظایف پس‌زمینه](/fa/automation/tasks) — ردیابی وظایف برای اجراهای جداشدهٔ `music_generate`
- [ComfyUI](/fa/providers/comfy)
- [مرجع پیکربندی](/fa/gateway/config-agents#agent-defaults) — پیکربندی `musicGenerationModel`
- [Google (Gemini)](/fa/providers/google)
- [MiniMax](/fa/providers/minimax)
- [مدل‌ها](/fa/concepts/models) — پیکربندی مدل و جابه‌جایی هنگام خرابی
- [مدل‌ها](/fa/concepts/models) — پیکربندی مدل و جابه‌جایی خودکار هنگام خطا
- [نمای کلی ابزارها](/fa/tools)

553
docs/fa/tools/plugin.md
View File

@ -1,41 +1,42 @@
---
read_when:
- نصب یا پیکربندی Plugin‌ها
- درک قواعد کشف و بارگذاری Plugin
- آشنایی با کشف Plugin و قواعد بارگذاری
- کار با بسته‌های Plugin سازگار با Codex/Claude
sidebarTitle: Install and Configure
summary: نصب، پیکربندی و مدیریت Pluginهای OpenClaw
summary: Plugin‌های OpenClaw را نصب، پیکربندی و مدیریت کنید
title: Plugin‌ها
x-i18n:
generated_at: "2026-05-03T21:42:36Z"
generated_at: "2026-05-05T01:53:36Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌دهند: کانال‌ها، ارائه‌دهندگان مدل،
مهارهای عامل، ابزارها، Skills، گفتار، رونویسی بی‌درنگ، صدای بی‌درنگ،
درک رسانه، تولید تصویر، تولید ویدئو، واکشی وب، جستجوی وب، و موارد بیشتر.
برخی Pluginها **هسته‌ای** هستند (همراه OpenClaw عرضه می‌شوند)، برخی دیگر
Pluginها OpenClaw را با قابلیت‌های تازه گسترش می‌دهند: کانال‌ها، ارائه‌دهندگان مدل،
هارنس‌های عامل، ابزارها، Skills، گفتار، رونویسی بی‌درنگ، صدای بی‌درنگ،
درک رسانه، تولید تصویر، تولید ویدیو، واکشی وب، جست‌وجوی وب، و موارد بیشتر.
برخی Pluginها **هسته‌ای** هستند (همراه OpenClaw عرضه می‌شوند)، و برخی دیگر
**خارجی** هستند. بیشتر Pluginهای خارجی از طریق
[ClawHub](/fa/tools/clawhub) منتشر و کشف می‌شوند. Npm همچنان برای نصب‌های مستقیم و برای
مجموعه‌ای موقت از بسته‌های Plugin متعلق به OpenClaw تا پایان این مهاجرت پشتیبانی می‌شود.
[ClawHub](/fa/tools/clawhub) منتشر و کشف می‌شوند. Npm همچنان برای نصب‌های مستقیم
و برای مجموعه‌ای موقت از بسته‌های Plugin متعلق به OpenClaw تا زمان پایان این
مهاجرت پشتیبانی می‌شود.
## شروع سریع
برای نمونه‌های آماده کپی‌کردن نصب، فهرست‌کردن، حذف نصب، به‌روزرسانی، و انتشار، ببینید
[مدیریت Pluginها](/fa/plugins/manage-plugins).
برای نمونه‌های آماده کپی‌کردن مربوط به نصب، فهرست‌کردن، حذف نصب، به‌روزرسانی،
و انتشار، [مدیریت Pluginها](/fa/plugins/manage-plugins) را ببینید.
<Steps>
<Step title="ببینید چه چیزی بارگذاری شده است">
<Step title="See what is loaded">
```bash
openclaw plugins list
```
</Step>
<Step title="نصب یک Plugin">
<Step title="Install a plugin">
```bash
# Search ClawHub plugins
openclaw plugins search "calendar"
@ -56,7 +57,7 @@ Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌
</Step>
<Step title="راه‌اندازی دوباره Gateway">
<Step title="Restart the Gateway">
```bash
openclaw gateway restart
```
@ -65,17 +66,18 @@ Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌
</Step>
<Step title="مدیریت بومی چت">
در یک Gateway در حال اجرا، `/plugins enable` و `/plugins disable` که فقط برای مالک هستند،
بارگذار مجدد پیکربندی Gateway را فعال می‌کنند. Gateway سطح‌های زمان اجرای Plugin را
در همان فرایند دوباره بارگذاری می‌کند، و نوبت‌های جدید عامل فهرست ابزار خود را از
رجیستری تازه‌سازی‌شده دوباره می‌سازند. `/plugins install` کد منبع Plugin را تغییر می‌دهد، بنابراین
Gateway به‌جای وانمودکردن به اینکه فرایند فعلی می‌تواند ماژول‌های ازقبل import‌شده را
به‌صورت ایمن دوباره بارگذاری کند، درخواست راه‌اندازی دوباره می‌دهد.
<Step title="Chat-native management">
در یک Gateway در حال اجرا، `/plugins enable` و `/plugins disable` که فقط
برای مالک هستند، بارگذار مجدد پیکربندی Gateway را فعال می‌کنند. Gateway
سطح‌های زمان اجرای Plugin را در همان فرایند دوباره بارگذاری می‌کند، و نوبت‌های
تازه عامل، فهرست ابزار خود را از رجیستری تازه‌سازی‌شده دوباره می‌سازند.
`/plugins install` کد منبع Plugin را تغییر می‌دهد، بنابراین Gateway به‌جای
وانمود کردن به اینکه فرایند فعلی می‌تواند ماژول‌های ازپیش واردشده را با ایمنی
دوباره بارگذاری کند، درخواست راه‌اندازی مجدد می‌کند.
</Step>
<Step title="تأیید Plugin">
<Step title="Verify the plugin">
```bash
openclaw plugins inspect <plugin-id> --runtime --json
@ -83,14 +85,16 @@ Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌
openclaw <plugin-command> --help
```
وقتی لازم است ابزارها، سرویس‌ها، متدهای Gateway، hookها، یا فرمان‌های CLI متعلق به Plugin
را اثبات کنید، از `--runtime` استفاده کنید. `inspect` ساده یک بررسی سرد
مانیفست/رجیستری است و عمداً از import کردن زمان اجرای Plugin پرهیز می‌کند.
وقتی لازم است ابزارهای ثبت‌شده، سرویس‌ها، متدهای Gateway، هوک‌ها، یا فرمان‌های
CLI متعلق به Plugin را اثبات کنید، از `--runtime` استفاده کنید. `inspect`
ساده یک بررسی سردِ مانیفست/رجیستری است و عمدا از وارد کردن زمان اجرای Plugin
اجتناب می‌کند.
</Step>
</Steps>
اگر کنترل بومی چت را ترجیح می‌دهید، `commands.plugins: true` را فعال کنید و استفاده کنید از:
اگر کنترل بومیِ چت را ترجیح می‌دهید، `commands.plugins: true` را فعال کنید و
از این‌ها استفاده کنید:
```text
/plugin install clawhub:<package>
@ -98,82 +102,88 @@ Pluginها OpenClaw را با قابلیت‌های جدید گسترش می‌
/plugin enable <plugin-id>
```
مسیر نصب از همان resolver که CLI استفاده می‌کند بهره می‌برد: مسیر/آرشیو محلی، مقدار صریح
`clawhub:<pkg>`، مقدار صریح `npm:<pkg>`، مقدار صریح `git:<repo>`، یا مشخصه بسته ساده
از طریق npm.
مسیر نصب از همان حل‌کننده‌ای استفاده می‌کند که CLI استفاده می‌کند: مسیر/آرشیو
محلی، `clawhub:<pkg>` صریح، `npm:<pkg>` صریح، `git:<repo>` صریح، یا مشخصه
بسته خام از طریق npm.
اگر پیکربندی نامعتبر باشد، نصب معمولاً بسته و ایمن شکست می‌خورد و شما را به
`openclaw doctor --fix` هدایت می‌کند. تنها استثنای بازیابی، مسیر محدود نصب مجدد Plugin همراه
برای Pluginهایی است که در
`openclaw.install.allowInvalidConfigRecovery` شرکت می‌کنند.
هنگام شروع به کار Gateway، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری
بسته و ایمن شکست می‌خورد. `openclaw doctor --fix` را اجرا کنید تا پیکربندی بد Plugin را با
غیرفعال‌کردن آن ورودی Plugin و حذف payload پیکربندی نامعتبر آن قرنطینه کنید؛ پشتیبان‌گیری معمول
پیکربندی مقادیر قبلی را نگه می‌دارد.
وقتی پیکربندی کانال به Pluginای ارجاع می‌دهد که دیگر قابل کشف نیست اما همان شناسه کهنه Plugin
در پیکربندی Plugin یا رکوردهای نصب باقی مانده است، شروع به کار Gateway هشدارها را ثبت می‌کند و
به‌جای مسدودکردن همه کانال‌های دیگر، آن کانال را رد می‌کند.
`openclaw doctor --fix` را اجرا کنید تا ورودی‌های کهنه کانال/Plugin حذف شوند؛ کلیدهای ناشناخته
کانال بدون شواهد Plugin کهنه همچنان در اعتبارسنجی شکست می‌خورند تا خطاهای تایپی قابل مشاهده بمانند.
اگر `plugins.enabled: false` تنظیم شده باشد، ارجاع‌های کهنه Plugin بی‌اثر تلقی می‌شوند:
شروع به کار Gateway کار کشف/بارگذاری Plugin را رد می‌کند و `openclaw doctor` به‌جای حذف خودکار آن،
پیکربندی غیرفعال Plugin را حفظ می‌کند. اگر می‌خواهید شناسه‌های کهنه Plugin حذف شوند، پیش از
اجرای پاک‌سازی doctor، Pluginها را دوباره فعال کنید.
اگر پیکربندی نامعتبر باشد، نصب معمولا به‌صورت بسته شکست می‌خورد و شما را به
`openclaw doctor --fix` راهنمایی می‌کند. تنها استثنای بازیابی، یک مسیر محدود
نصب مجدد Plugin همراه‌سازی‌شده برای Pluginهایی است که در
`openclaw.install.allowInvalidConfigRecovery` مشارکت می‌کنند.
هنگام شروع به کار Gateway، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر
دیگری به‌صورت بسته شکست می‌خورد. `openclaw doctor --fix` را اجرا کنید تا
پیکربندی بد Plugin را با غیرفعال کردن آن ورودی Plugin و حذف محتوای نامعتبر
پیکربندی آن قرنطینه کند؛ پشتیبان‌گیری عادی پیکربندی مقدارهای قبلی را نگه می‌دارد.
وقتی پیکربندی یک کانال به Pluginی ارجاع می‌دهد که دیگر قابل کشف نیست اما همان
شناسه کهنه Plugin همچنان در پیکربندی Plugin یا رکوردهای نصب باقی مانده است،
شروع به کار Gateway هشدارها را ثبت می‌کند و به‌جای مسدود کردن هر کانال دیگر، آن
کانال را رد می‌کند. `openclaw doctor --fix` را اجرا کنید تا ورودی‌های کهنه
کانال/Plugin حذف شوند؛ کلیدهای ناشناخته کانال بدون شواهد Plugin کهنه همچنان در
اعتبارسنجی شکست می‌خورند تا اشتباه‌های تایپی آشکار بمانند.
اگر `plugins.enabled: false` تنظیم شده باشد، ارجاع‌های کهنه Plugin بی‌اثر در نظر
گرفته می‌شوند: شروع به کار Gateway کار کشف/بارگذاری Plugin را رد می‌کند و
`openclaw doctor` به‌جای حذف خودکار، پیکربندی غیرفعال Plugin را حفظ می‌کند. اگر
می‌خواهید شناسه‌های کهنه Plugin حذف شوند، پیش از اجرای پاک‌سازی doctor، Pluginها
را دوباره فعال کنید.
نصب وابستگی Plugin فقط در جریان نصب/به‌روزرسانی صریح یا جریان‌های تعمیر doctor انجام می‌شود.
شروع به کار Gateway، بارگذاری مجدد پیکربندی، و بازرسی زمان اجرا
package managerها را اجرا نمی‌کنند و درخت‌های وابستگی را تعمیر نمی‌کنند. Pluginهای محلی باید از قبل
وابستگی‌های خود را نصب‌شده داشته باشند، در حالی که Pluginهای npm، git، و ClawHub
زیر ریشه‌های Plugin مدیریت‌شده OpenClaw نصب می‌شوند. وابستگی‌های npm ممکن است
درون ریشه npm مدیریت‌شده OpenClaw hoist شوند؛ نصب/به‌روزرسانی پیش از اعتماد، آن ریشه مدیریت‌شده را اسکن می‌کند
و حذف نصب بسته‌های مدیریت‌شده npm را از طریق npm حذف می‌کند. Pluginهای خارجی
و مسیرهای بارگذاری سفارشی همچنان باید از طریق `openclaw plugins install` نصب شوند.
از `openclaw plugins list --json` استفاده کنید تا `dependencyStatus` ایستای هر
Plugin قابل مشاهده را بدون import کردن کد زمان اجرا یا تعمیر وابستگی‌ها ببینید.
برای چرخه عمر زمان نصب، [حل وابستگی Plugin](/fa/plugins/dependency-resolution) را ببینید.
نصب وابستگی‌های Plugin فقط در جریان‌های نصب/به‌روزرسانی صریح یا تعمیر doctor
انجام می‌شود. شروع به کار Gateway، بارگذاری مجدد پیکربندی، و بازرسی زمان اجرا
مدیر بسته اجرا نمی‌کنند یا درخت‌های وابستگی را تعمیر نمی‌کنند. Pluginهای محلی
باید از قبل وابستگی‌های خود را نصب کرده باشند، درحالی‌که Pluginهای npm، git، و
ClawHub زیر ریشه‌های Plugin مدیریت‌شده OpenClaw نصب می‌شوند. وابستگی‌های npm
ممکن است درون ریشه npm مدیریت‌شده OpenClaw hoist شوند؛ نصب/به‌روزرسانی پیش از
اعتماد، آن ریشه مدیریت‌شده را اسکن می‌کند و حذف نصب، بسته‌های مدیریت‌شده با npm
را از طریق npm حذف می‌کند. Pluginهای خارجی و مسیرهای بارگذاری سفارشی همچنان
باید از طریق `openclaw plugins install` نصب شوند. برای دیدن `dependencyStatus`
ایستا برای هر Plugin قابل مشاهده، بدون وارد کردن کد زمان اجرا یا تعمیر وابستگی‌ها،
از `openclaw plugins list --json` استفاده کنید. برای چرخه عمر زمان نصب،
[حل وابستگی Plugin](/fa/plugins/dependency-resolution) را ببینید.
برای نصب‌های npm، selectorهای تغییرپذیر مانند `latest` یا یک dist-tag پیش از نصب resolve می‌شوند
و سپس به نسخه دقیق تأییدشده در ریشه npm مدیریت‌شده OpenClaw سنجاق می‌شوند.
پس از پایان npm، OpenClaw تأیید می‌کند ورودی نصب‌شده
`package-lock.json` همچنان با نسخه resolve‌شده و integrity مطابقت دارد. اگر
npm فراداده بسته متفاوتی بنویسد، نصب شکست می‌خورد و بسته مدیریت‌شده
به‌جای پذیرش یک artifact متفاوت Plugin، به حالت قبل برگردانده می‌شود.
برای نصب‌های npm، انتخابگرهای تغییرپذیر مانند `latest` یا یک dist-tag پیش از نصب
حل می‌شوند و سپس به نسخه دقیقِ تاییدشده در ریشه npm مدیریت‌شده OpenClaw سنجاق
می‌شوند. پس از پایان npm، OpenClaw بررسی می‌کند که ورودی نصب‌شده
`package-lock.json` همچنان با نسخه و یکپارچگی حل‌شده مطابقت داشته باشد. اگر npm
فراداده متفاوتی برای بسته بنویسد، نصب شکست می‌خورد و بسته مدیریت‌شده به حالت
قبلی برگردانده می‌شود، نه اینکه آرتیفکت متفاوت Plugin پذیرفته شود.
checkoutهای منبع، workspaceهای pnpm هستند. اگر OpenClaw را برای کار روی Pluginهای همراه clone می‌کنید،
`pnpm install` را اجرا کنید؛ سپس OpenClaw، Pluginهای همراه را از
`extensions/<id>` بارگذاری می‌کند تا ویرایش‌ها و وابستگی‌های محلی بسته مستقیماً استفاده شوند.
نصب‌های ریشه npm ساده برای OpenClaw بسته‌بندی‌شده هستند، نه توسعه
checkout منبع.
checkoutهای منبع، workspaceهای pnpm هستند. اگر OpenClaw را برای کار روی
Pluginهای همراه‌سازی‌شده clone می‌کنید، `pnpm install` را اجرا کنید؛ سپس OpenClaw
Pluginهای همراه‌سازی‌شده را از `extensions/<id>` بارگذاری می‌کند تا ویرایش‌ها و
وابستگی‌های محلی بسته مستقیما استفاده شوند. نصب‌های ساده ریشه npm برای OpenClaw
بسته‌بندی‌شده هستند، نه توسعه checkout منبع.
## انواع Plugin
OpenClaw دو قالب Plugin را می‌شناسد:
| قالب | نحوه کارکرد | نمونه‌ها |
| قالب | نحوه کار | نمونه‌ها |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + ماژول زمان اجرا؛ درون فرایند اجرا می‌شود | Pluginهای رسمی، بسته‌های npm جامعه |
| **Bundle** | چیدمان سازگار با Codex/Claude/Cursor؛ به قابلیت‌های OpenClaw نگاشت می‌شود | `.codex-plugin/`، `.claude-plugin/`، `.cursor-plugin/` |
| **بومی** | `openclaw.plugin.json` + ماژول زمان اجرا؛ درون‌فرایندی اجرا می‌شود | Pluginهای رسمی، بسته‌های npm جامعه |
| **باندل** | چیدمان سازگار با Codex/Claude/Cursor؛ به قابلیت‌های OpenClaw نگاشت می‌شود | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
هر دو زیر `openclaw plugins list` نمایش داده می‌شوند. برای جزئیات bundle، [Plugin Bundles](/fa/plugins/bundles) را ببینید.
هر دو زیر `openclaw plugins list` نمایش داده می‌شوند. برای جزئیات باندل،
[باندل‌های Plugin](/fa/plugins/bundles) را ببینید.
اگر در حال نوشتن یک Plugin بومی هستید، با [ساخت Pluginها](/fa/plugins/building-plugins)
و [نمای کلی Plugin SDK](/fa/plugins/sdk-overview) شروع کنید.
اگر یک Plugin بومی می‌نویسید، با [ساخت Pluginها](/fa/plugins/building-plugins)
و [نمای کلی SDK Plugin](/fa/plugins/sdk-overview) شروع کنید.
## نقطه‌های ورود بسته
بسته‌های npm مربوط به Plugin بومی باید `openclaw.extensions` را در `package.json` اعلام کنند.
هر ورودی باید داخل دایرکتوری بسته باقی بماند و به یک فایل زمان اجرای قابل خواندن
resolve شود، یا به یک فایل منبع TypeScript با یک همتای JavaScript ساخته‌شده استنتاج‌شده
مانند `src/index.ts` به `dist/index.js`.
نصب‌های بسته‌بندی‌شده باید آن خروجی زمان اجرای JavaScript را همراه داشته باشند. fallback منبع TypeScript
برای checkoutهای منبع و مسیرهای توسعه محلی است، نه برای
بسته‌های npm نصب‌شده در ریشه Plugin مدیریت‌شده OpenClaw.
بسته‌های npm برای Plugin بومی باید `openclaw.extensions` را در `package.json`
اعلام کنند. هر ورودی باید داخل دایرکتوری بسته باقی بماند و به یک فایل زمان
اجرای خواندنی، یا به یک فایل منبع TypeScript با همتای JavaScript ساخته‌شده
استنباط‌شده مانند `src/index.ts` تا `dist/index.js` حل شود.
نصب‌های بسته‌بندی‌شده باید آن خروجی زمان اجرای JavaScript را عرضه کنند. fallback
منبع TypeScript برای checkoutهای منبع و مسیرهای توسعه محلی است، نه برای بسته‌های
npm نصب‌شده در ریشه Plugin مدیریت‌شده OpenClaw.
وقتی فایل‌های زمان اجرای منتشرشده در همان مسیرهای ورودی‌های منبع قرار ندارند، از `openclaw.runtimeExtensions` استفاده کنید.
وقتی موجود باشد، `runtimeExtensions` باید دقیقاً برای هر ورودی `extensions`
یک ورودی داشته باشد. فهرست‌های ناهماهنگ به‌جای fallback بی‌صدا به مسیرهای منبع، نصب و
کشف Plugin را شکست می‌دهند. اگر `openclaw.setupEntry` را نیز
منتشر می‌کنید، برای همتای JavaScript ساخته‌شده آن از `openclaw.runtimeSetupEntry` استفاده کنید؛ آن فایل هنگام اعلام‌شدن الزامی است.
وقتی فایل‌های زمان اجرای منتشرشده در همان مسیرهای ورودی‌های منبع قرار ندارند،
از `openclaw.runtimeExtensions` استفاده کنید. وقتی وجود داشته باشد،
`runtimeExtensions` باید دقیقا برای هر ورودی `extensions` یک ورودی داشته باشد.
فهرست‌های ناهماهنگ به‌جای fallback بی‌صدا به مسیرهای منبع، باعث شکست نصب و کشف
Plugin می‌شوند. اگر `openclaw.setupEntry` را هم منتشر می‌کنید، برای همتای
JavaScript ساخته‌شده آن از `openclaw.runtimeSetupEntry` استفاده کنید؛ وقتی اعلام
شود، آن فایل الزامی است.
```json
{
@ -187,19 +197,20 @@ resolve شود، یا به یک فایل منبع TypeScript با یک همتا
## Pluginهای رسمی
### بسته‌های npm متعلق به OpenClaw در زمان مهاجرت
### بسته‌های npm متعلق به OpenClaw هنگام مهاجرت
ClawHub مسیر اصلی توزیع برای بیشتر Pluginها است. انتشارهای بسته‌بندی‌شده فعلی
OpenClaw از قبل بسیاری از Pluginهای رسمی را همراه دارند، بنابراین در راه‌اندازی‌های معمول به
نصب npm جداگانه نیاز ندارند. تا زمانی که همه Pluginهای متعلق به OpenClaw
به ClawHub مهاجرت کنند، OpenClaw همچنان برخی بسته‌های Plugin `@openclaw/*` را روی
npm برای نصب‌های قدیمی‌تر/سفارشی و workflowهای مستقیم npm عرضه می‌کند.
ClawHub مسیر اصلی توزیع برای بیشتر Pluginها است. نسخه‌های بسته‌بندی‌شده فعلی
OpenClaw از قبل بسیاری از Pluginهای رسمی را همراه دارند، بنابراین در راه‌اندازی‌های
عادی به نصب npm جداگانه برای آن‌ها نیاز نیست. تا زمانی که همه Pluginهای متعلق به
OpenClaw به ClawHub مهاجرت کنند، OpenClaw همچنان برخی بسته‌های Plugin با الگوی
`@openclaw/*` را برای نصب‌های قدیمی‌تر/سفارشی و جریان‌های کاری مستقیم npm روی
npm منتشر می‌کند.
اگر npm یک بسته Plugin `@openclaw/*` را منسوخ گزارش کند، آن نسخه بسته
از قطار بسته خارجی قدیمی‌تر است. تا زمانی که بسته npm جدیدتری منتشر شود، از Plugin همراه در
OpenClaw فعلی یا یک checkout محلی استفاده کنید.
اگر npm یک بسته Plugin با الگوی `@openclaw/*` را deprecated گزارش کند، آن نسخه
بسته از یک قطار قدیمی‌تر بسته خارجی است. تا زمانی که بسته npm جدیدتری منتشر شود،
از Plugin همراه نسخه فعلی OpenClaw یا یک checkout محلی استفاده کنید.
| Plugin | بسته | مستندات |
| Plugin | بسته | مستندات |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/fa/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/fa/channels/discord) |
@ -218,7 +229,7 @@ OpenClaw فعلی یا یک checkout محلی استفاده کنید.
### هسته (همراه OpenClaw عرضه می‌شود)
<AccordionGroup>
<Accordion title="ارائه‌دهندگان مدل (به‌صورت پیش‌فرض فعال)">
<Accordion title="Model providers (enabled by default)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@ -226,22 +237,22 @@ OpenClaw فعلی یا یک checkout محلی استفاده کنید.
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="Pluginهای حافظه">
- `memory-core` — جستجوی حافظه همراه (پیش‌فرض از طریق `plugins.slots.memory`)
- `memory-lancedb` — حافظه بلندمدت مبتنی بر LanceDB با فراخوانی/ثبت خودکار (تنظیم کنید `plugins.slots.memory = "memory-lancedb"`)
<Accordion title="Memory plugins">
- `memory-core` — جست‌وجوی حافظه همراه‌سازی‌شده (پیش‌فرض از طریق `plugins.slots.memory`)
- `memory-lancedb` — حافظه بلندمدت مبتنی بر LanceDB با یادآوری/ثبت خودکار (`plugins.slots.memory = "memory-lancedb"` را تنظیم کنید)
برای راه‌اندازی embedding سازگار با OpenAI، نمونه‌های Ollama، محدودیت‌های فراخوانی، و عیب‌یابی،
[Memory LanceDB](/fa/plugins/memory-lancedb) را ببینید.
برای راه‌اندازی embedding سازگار با OpenAI، نمونه‌های Ollama، محدودیت‌های
یادآوری، و عیب‌یابی، [Memory LanceDB](/fa/plugins/memory-lancedb) را ببینید.
</Accordion>
<Accordion title="ارائه‌دهندگان گفتار (به‌صورت پیش‌فرض فعال)">
<Accordion title="Speech providers (enabled by default)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="سایر">
- `browser` — Plugin مرورگر همراه برای ابزار مرورگر، CLI `openclaw browser`، متد Gateway `browser.request`، زمان اجرای مرورگر، و سرویس کنترل مرورگر پیش‌فرض (به‌صورت پیش‌فرض فعال؛ پیش از جایگزین‌کردن آن غیرفعالش کنید)
- `copilot-proxy` — پل VS Code Copilot Proxy (به‌صورت پیش‌فرض غیرفعال)
<Accordion title="Other">
- `browser` — Plugin مرورگر همراه‌سازی‌شده برای ابزار مرورگر، CLI `openclaw browser`، متد Gateway `browser.request`، زمان اجرای مرورگر، و سرویس پیش‌فرض کنترل مرورگر (به‌صورت پیش‌فرض فعال است؛ پیش از جایگزین کردن آن غیرفعالش کنید)
- `copilot-proxy` — پل VS Code Copilot Proxy (به‌صورت پیش‌فرض غیرفعال است)
</Accordion>
</AccordionGroup>
@ -264,51 +275,47 @@ OpenClaw فعلی یا یک checkout محلی استفاده کنید.
}
```
| فیلد | توضیح |
| ---------------- | --------------------------------------------------------- |
| `enabled` | کلید اصلی فعال‌سازی (پیش‌فرض: `true`) |
| `allow` | فهرست مجاز Plugin (اختیاری) |
| `deny` | فهرست مسدود Plugin (اختیاری؛ مسدودسازی اولویت دارد) |
| `load.paths` | فایل‌ها/دایرکتوری‌های اضافی Plugin |
| `slots` | انتخابگرهای اسلات انحصاری (مثلا `memory`، `contextEngine`) |
| `entries.\<id\>` | کلیدهای فعال‌سازی هر Plugin + پیکربندی |
| فیلد | توضیح |
| ------------------ | --------------------------------------------------------- |
| `enabled` | کلید اصلی فعال‌سازی/غیرفعال‌سازی (پیش‌فرض: `true`) |
| `allow` | فهرست مجاز Pluginها (اختیاری) |
| `bundledDiscovery` | حالت کشف Pluginهای همراه (`allowlist` به‌صورت پیش‌فرض) |
| `deny` | فهرست غیرمجاز Pluginها (اختیاری؛ deny غالب است) |
| `load.paths` | فایل‌ها/دایرکتوری‌های اضافی Plugin |
| `slots` | انتخابگرهای جایگاه انحصاری (مثلاً `memory`، `contextEngine`) |
| `entries.\<id\>` | کلیدهای فعال‌سازی/غیرفعال‌سازی هر Plugin + پیکربندی |
`plugins.allow` انحصاری است. وقتی خالی نباشد، فقط Pluginهای فهرست‌شده می‌توانند بارگذاری شوند
یا ابزارها را ارائه کنند، حتی اگر `tools.allow` شامل `"*"` یا نام یک ابزار مشخص
متعلق به Plugin باشد. اگر فهرست مجاز ابزار به ابزارهای Plugin اشاره می‌کند، شناسه‌های Plugin مالک
را به `plugins.allow` اضافه کنید یا `plugins.allow` را حذف کنید؛ `openclaw doctor` درباره این
یا ابزارها را در دسترس بگذارند، حتی اگر `tools.allow` شامل `"*"` یا نام یک ابزار مشخصِ متعلق به Plugin باشد. اگر فهرست مجاز ابزار به ابزارهای Plugin اشاره می‌کند، شناسه‌های Plugin مالک را
به `plugins.allow` اضافه کنید یا `plugins.allow` را حذف کنید؛ `openclaw doctor` درباره این
شکل هشدار می‌دهد.
تغییرات پیکربندی که از طریق `/plugins enable` یا `/plugins disable` انجام می‌شوند، باعث
بارگذاری مجدد درون‌فرایندی Plugin در Gateway می‌شوند. نوبت‌های جدید agent فهرست ابزارهای خود را از
رجیستری Plugin تازه‌سازی‌شده بازسازی می‌کنند. عملیات‌هایی که منبع را تغییر می‌دهند، مانند نصب،
به‌روزرسانی و حذف نصب، همچنان فرایند Gateway را دوباره راه‌اندازی می‌کنند، چون ماژول‌های Plugin
که قبلا import شده‌اند، به‌صورت ایمن درجا قابل جایگزینی نیستند.
`plugins.bundledDiscovery` برای پیکربندی‌های جدید به‌صورت پیش‌فرض `"allowlist"` است، بنابراین یک موجودی محدودکننده `plugins.allow` همچنین Pluginهای ارائه‌دهنده همراهِ حذف‌شده را مسدود می‌کند،
از جمله کشف ارائه‌دهنده وب‌جست‌وجوی زمان اجرا. Doctor هنگام مهاجرت، پیکربندی‌های قدیمیِ دارای فهرست مجاز محدودکننده را با `"compat"` مهر می‌زند تا ارتقاها رفتار قدیمی ارائه‌دهنده‌های همراه را نگه دارند تا زمانی که اپراتور حالت سخت‌گیرانه‌تر را انتخاب کند.
`plugins.allow` خالی همچنان تنظیم‌نشده/باز در نظر گرفته می‌شود.
`openclaw plugins list` یک snapshot محلی از رجیستری/پیکربندی Plugin است. یک Plugin با وضعیت
`enabled` در آنجا یعنی رجیستری پایدارشده و پیکربندی فعلی اجازه می‌دهند Plugin
مشارکت کند. این ثابت نمی‌کند که یک Gateway راه‌دور که از قبل در حال اجراست،
با همان کد Plugin بارگذاری مجدد یا راه‌اندازی مجدد شده است. در تنظیمات VPS/کانتینر
با فرایندهای wrapper، راه‌اندازی‌های مجدد یا نوشتن‌هایی را که باعث بارگذاری مجدد می‌شوند به فرایند واقعی
`openclaw gateway run` بفرستید، یا وقتی گزارش بارگذاری مجدد خطا می‌دهد، از
`openclaw gateway restart` روی Gateway در حال اجرا استفاده کنید.
تغییرات پیکربندی که از طریق `/plugins enable` یا `/plugins disable` انجام می‌شوند، باعث بارگذاری مجدد Pluginهای Gateway در همان فرایند می‌شوند. نوبت‌های جدید عامل، فهرست ابزارهای خود را از رجیستری Plugin تازه‌سازی‌شده بازسازی می‌کنند. عملیات‌هایی که منبع را تغییر می‌دهند، مانند نصب،
به‌روزرسانی و حذف نصب، همچنان فرایند Gateway را راه‌اندازی مجدد می‌کنند، چون ماژول‌های Plugin که قبلاً import شده‌اند را نمی‌توان با اطمینان درجا جایگزین کرد.
`openclaw plugins list` یک عکس فوری محلی از رجیستری/پیکربندی Plugin است. یک Plugin
`enabled` در آنجا یعنی رجیستری ذخیره‌شده و پیکربندی فعلی به Plugin اجازه مشارکت می‌دهند. این ثابت نمی‌کند که یک Gateway راه دورِ از قبل در حال اجرا، با همان کد Plugin دوباره بارگذاری یا راه‌اندازی مجدد شده است. در راه‌اندازی‌های VPS/کانتینر با فرایندهای wrapper، راه‌اندازی مجدد یا نوشتن‌های محرکِ بارگذاری مجدد را به فرایند واقعی `openclaw gateway run` بفرستید، یا وقتی بارگذاری مجدد شکست گزارش می‌کند، از `openclaw gateway restart` روی Gateway در حال اجرا استفاده کنید.
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **غیرفعال**: Plugin وجود دارد اما قواعد فعال‌سازی آن را خاموش کرده‌اند. پیکربندی حفظ می‌شود.
- **مفقود**: پیکربندی به شناسه Pluginای اشاره می‌کند که discovery پیدا نکرده است.
- **نامعتبر**: Plugin وجود دارد اما پیکربندی آن با schema اعلام‌شده همخوان نیست. راه‌اندازی Gateway فقط همان Plugin را رد می‌کند؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر را با غیرفعال‌کردن آن و حذف payload پیکربندی‌اش قرنطینه کند.
- **مفقود**: پیکربندی به شناسه Plugin اشاره می‌کند که کشف آن را پیدا نکرده است.
- **نامعتبر**: Plugin وجود دارد اما پیکربندی آن با schema اعلام‌شده مطابقت ندارد. راه‌اندازی Gateway فقط همان Plugin را رد می‌کند؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر را با غیرفعال‌کردن آن و حذف payload پیکربندی‌اش قرنطینه کند.
</Accordion>
## discovery و تقدم
## کشف و اولویت
OpenClaw به این ترتیب Pluginها را اسکن می‌کند (اولین تطابق برنده است):
OpenClaw به این ترتیب برای Pluginها اسکن می‌کند (اولین تطابق برنده است):
<Steps>
<Step title="Config paths">
`plugins.load.paths` — مسیرهای صریح فایل یا دایرکتوری. مسیرهایی که
به دایرکتوری‌های Plugin بسته‌بندی‌شده خود OpenClaw برمی‌گردند نادیده گرفته می‌شوند؛
برای حذف آن aliasهای کهنه `openclaw doctor --fix` را اجرا کنید.
دوباره به دایرکتوری‌های Plugin همراهِ بسته‌بندی‌شده خود OpenClaw اشاره می‌کنند نادیده گرفته می‌شوند؛
برای حذف آن aliasهای قدیمی `openclaw doctor --fix` را اجرا کنید.
</Step>
<Step title="Workspace plugins">
@ -320,63 +327,61 @@ OpenClaw به این ترتیب Pluginها را اسکن می‌کند (اولی
</Step>
<Step title="Bundled plugins">
همراه OpenClaw عرضه می‌شوند. بسیاری به‌صورت پیش‌فرض فعال هستند (ارائه‌دهندگان مدل، گفتار).
همراه OpenClaw عرضه می‌شوند. بسیاری به‌صورت پیش‌فرض فعال‌اند (ارائه‌دهندگان مدل، گفتار).
برخی دیگر به فعال‌سازی صریح نیاز دارند.
</Step>
</Steps>
نصب‌های بسته‌بندی‌شده و imageهای Docker معمولا Pluginهای bundled را از درخت کامپایل‌شده
`dist/extensions` resolve می‌کنند. اگر دایرکتوری منبع یک Plugin bundled
نصب‌های بسته‌بندی‌شده و imageهای Docker معمولاً Pluginهای همراه را از درخت کامپایل‌شده
`dist/extensions` resolve می‌کنند. اگر دایرکتوری منبع یک Plugin همراه
روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount شود، برای مثال
`/app/extensions/synology-chat`، OpenClaw آن دایرکتوری منبع mount‌شده
را به‌عنوان overlay منبع bundled در نظر می‌گیرد و آن را پیش از bundle بسته‌بندی‌شده
`/app/dist/extensions/synology-chat` کشف می‌کند. این باعث می‌شود loopهای کانتینری نگهدارندگان
بدون برگرداندن همه Pluginهای bundled به منبع TypeScript کار کنند.
برای اجبار به استفاده از bundleهای packaged dist حتی وقتی mountهای overlay منبع وجود دارند،
`/app/extensions/synology-chat`، OpenClaw آن دایرکتوری منبع mount‌شده را
به‌عنوان overlay منبع همراه در نظر می‌گیرد و آن را پیش از بسته
`/app/dist/extensions/synology-chat` کشف می‌کند. این باعث می‌شود loopهای کانتینری نگه‌دارنده
بدون برگرداندن هر Plugin همراه به منبع TypeScript کار کنند.
برای اجبار به استفاده از بسته‌های dist بسته‌بندی‌شده حتی وقتی mountهای overlay منبع وجود دارند،
`OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` را تنظیم کنید.
### قواعد فعال‌سازی
- `plugins.enabled: false` همه Pluginها را غیرفعال می‌کند و کار discovery/load Plugin را رد می‌کند
- `plugins.deny` همیشه بر allow اولویت دارد
- `plugins.enabled: false` همه Pluginها را غیرفعال می‌کند و کار کشف/بارگذاری Plugin را رد می‌کند
- `plugins.deny` همیشه بر allow غالب است
- `plugins.entries.\<id\>.enabled: false` آن Plugin را غیرفعال می‌کند
- Pluginهای با منشأ workspace به‌صورت **پیش‌فرض غیرفعال** هستند (باید صراحتا فعال شوند)
- Pluginهای bundled از مجموعه داخلی default-on پیروی می‌کنند مگر اینکه override شوند
- اسلات‌های انحصاری می‌توانند Plugin انتخاب‌شده برای آن اسلات را اجبارا فعال کنند
- برخی Pluginهای bundled opt-in وقتی پیکربندی یک سطح متعلق به Plugin را نام ببرد، خودکار فعال می‌شوند،
مانند ref مدل provider، پیکربندی کانال، یا runtime harness
- Pluginهایی با خاستگاه workspace **به‌صورت پیش‌فرض غیرفعال‌اند** (باید صریحاً فعال شوند)
- Pluginهای همراه از مجموعه داخلیِ پیش‌فرض فعال پیروی می‌کنند، مگر اینکه override شوند
- جایگاه‌های انحصاری می‌توانند Plugin انتخاب‌شده برای آن جایگاه را اجباری فعال کنند
- برخی Pluginهای همراهِ opt-in وقتی پیکربندی سطحی متعلق به Plugin را نام‌گذاری می‌کند، خودکار فعال می‌شوند، مانند یک ارجاع مدل ارائه‌دهنده، پیکربندی کانال، یا runtime harness
- پیکربندی کهنه Plugin تا زمانی که `plugins.enabled: false` فعال است حفظ می‌شود؛
اگر می‌خواهید شناسه‌های کهنه حذف شوند، پیش از اجرای پاک‌سازی doctor، Pluginها را دوباره فعال کنید
- مسیرهای خانواده OpenAI Codex مرزهای Plugin جداگانه را حفظ می‌کنند:
`openai-codex/*` متعلق به Plugin OpenAI است، در حالی که Plugin bundled سرور app مربوط به Codex
با `agentRuntime.id: "codex"` یا refهای مدل legacy
- مسیرهای Codex خانواده OpenAI مرزهای جداگانه Plugin را نگه می‌دارند:
`openai-codex/*` متعلق به Plugin OpenAI است، درحالی‌که Plugin همراه app-serverِ Codex
با `agentRuntime.id: "codex"` یا ارجاع‌های مدل قدیمی
`codex/*` انتخاب می‌شود
## عیب‌یابی hookهای runtime
اگر یک Plugin در `plugins list` ظاهر می‌شود اما side effectها یا hookهای `register(api)`
در ترافیک live chat اجرا نمی‌شوند، ابتدا این موارد را بررسی کنید:
اگر یک Plugin در `plugins list` ظاهر می‌شود اما اثرات جانبی یا hookهای
`register(api)` در ترافیک چت زنده اجرا نمی‌شوند، ابتدا این موارد را بررسی کنید:
- `openclaw gateway status --deep --require-rpc` را اجرا کنید و تأیید کنید URL،
profile، مسیر پیکربندی و فرایند Gateway فعال همان‌هایی هستند که ویرایش می‌کنید.
- پس از تغییرات نصب/پیکربندی/کد Plugin، Gateway زنده را دوباره راه‌اندازی کنید. در کانتینرهای wrapper،
- `openclaw gateway status --deep --require-rpc` را اجرا کنید و تأیید کنید URL فعال
Gateway، profile، مسیر پیکربندی، و فرایند همان‌هایی هستند که ویرایش می‌کنید.
- پس از تغییرات نصب/پیکربندی/کد Plugin، Gateway زنده را راه‌اندازی مجدد کنید. در کانتینرهای wrapper،
PID 1 ممکن است فقط یک supervisor باشد؛ فرایند فرزند
`openclaw gateway run` را دوباره راه‌اندازی یا signal کنید.
- از `openclaw plugins inspect <id> --runtime --json` برای تأیید ثبت hookها و
diagnostics استفاده کنید. hookهای conversation غیرباندل مانند `llm_input`،
`llm_output`، `before_agent_finalize` و `agent_end` به
`openclaw gateway run` را راه‌اندازی مجدد کنید یا به آن signal بفرستید.
- برای تأیید ثبت hookها و diagnostics از `openclaw plugins inspect <id> --runtime --json` استفاده کنید. hookهای مکالمه غیرهمراه مانند `llm_input`,
`llm_output`, `before_agent_finalize` و `agent_end` به
`plugins.entries.<id>.hooks.allowConversationAccess=true` نیاز دارند.
- برای تغییر مدل، `before_model_resolve` را ترجیح دهید. این hook پیش از resolution مدل
برای نوبت‌های agent اجرا می‌شود؛ `llm_output` فقط پس از آن اجرا می‌شود که یک تلاش مدل
خروجی assistant تولید کند.
- برای اثبات مدل مؤثر session، از `openclaw sessions` یا سطح‌های
session/status در Gateway استفاده کنید و هنگام debug کردن payloadهای provider،
Gateway را با `--raw-stream --raw-stream-path <path>` شروع کنید.
- برای تغییر مدل، `before_model_resolve` را ترجیح دهید. این پیش از resolve مدل
برای نوبت‌های عامل اجرا می‌شود؛ `llm_output` فقط پس از آن اجرا می‌شود که یک تلاش مدل
خروجی دستیار تولید کند.
- برای اثبات مدل مؤثر session، از `openclaw sessions` یا سطح‌های session/statusِ
Gateway استفاده کنید و، هنگام debug کردن payloadهای ارائه‌دهنده، Gateway را با
`--raw-stream --raw-stream-path <path>` شروع کنید.
### آماده‌سازی کند ابزار Plugin
### راه‌اندازی کند ابزار Plugin
اگر به نظر می‌رسد نوبت‌های agent هنگام آماده‌سازی ابزارها متوقف می‌شوند، trace logging را فعال کنید و
خطوط زمان‌بندی کارخانه ابزار Plugin را بررسی کنید:
اگر به نظر می‌رسد نوبت‌های عامل هنگام آماده‌سازی ابزارها متوقف می‌شوند، logging سطح trace را فعال کنید و
خطوط زمان‌بندی factory ابزار Plugin را بررسی کنید:
```bash
openclaw config set logging.level trace
@ -390,15 +395,15 @@ openclaw logs --follow
```
خلاصه، زمان کل factory و کندترین factoryهای ابزار Plugin را فهرست می‌کند،
از جمله شناسه Plugin، نام ابزارهای اعلام‌شده، شکل نتیجه و اینکه ابزار
از جمله شناسه Plugin، نام‌های ابزار اعلام‌شده، شکل نتیجه، و اینکه ابزار
اختیاری است یا نه. وقتی یک factory منفرد حداقل 1s طول بکشد
یا آماده‌سازی کل factory ابزار Plugin حداقل 5s طول بکشد، خطوط کند به هشدار ارتقا داده می‌شوند.
OpenClaw نتایج موفق factory ابزار Plugin را برای resolutionهای تکراری
با همان context مؤثر request cache می‌کند. کلید cache شامل پیکربندی مؤثر
runtime، workspace، شناسه‌های agent/session، سیاست sandbox، تنظیمات browser،
context تحویل، هویت requester و وضعیت ownership است، بنابراین factoryهایی که
به آن فیلدهای قابل اعتماد وابسته‌اند، هنگام تغییر context دوباره اجرا می‌شوند.
با همان context مؤثر درخواست cache می‌کند. کلید cache شامل پیکربندی مؤثر
runtime، workspace، شناسه‌های agent/session، سیاست sandbox، تنظیمات مرورگر،
context تحویل، هویت درخواست‌کننده، و وضعیت مالکیت است، بنابراین factoryهایی که
به آن فیلدهای مورد اعتماد وابسته‌اند، هنگام تغییر context دوباره اجرا می‌شوند.
اگر یک Plugin بر زمان‌بندی غالب است، ثبت‌های runtime آن را بررسی کنید:
@ -406,11 +411,11 @@ context تحویل، هویت requester و وضعیت ownership است، بنا
openclaw plugins inspect <plugin-id> --runtime --json
```
سپس آن Plugin را به‌روزرسانی، دوباره نصب یا غیرفعال کنید. نویسندگان Plugin باید
بارگذاری dependencyهای پرهزینه را پشت مسیر اجرای ابزار منتقل کنند، نه اینکه آن را
سپس آن Plugin را به‌روزرسانی، دوباره نصب، یا غیرفعال کنید. نویسندگان Plugin باید
بارگذاری وابستگی‌های پرهزینه را به پشت مسیر اجرای ابزار منتقل کنند، نه اینکه آن را
داخل factory ابزار انجام دهند.
### ownership تکراری کانال یا ابزار
### مالکیت تکراری کانال یا ابزار
نشانه‌ها:
@ -419,33 +424,32 @@ openclaw plugins inspect <plugin-id> --runtime --json
- `plugin tool name conflict (<plugin-id>): <tool-name>`
این‌ها یعنی بیش از یک Plugin فعال تلاش می‌کند مالک همان کانال،
flow راه‌اندازی، یا نام ابزار باشد. رایج‌ترین علت این است که یک Plugin کانال external
کنار یک Plugin bundled نصب شده که حالا همان شناسه کانال را ارائه می‌کند.
جریان setup، یا نام ابزار باشد. رایج‌ترین علت، نصب یک Plugin کانال خارجی
در کنار یک Plugin همراه است که اکنون همان شناسه کانال را ارائه می‌کند.
مراحل debug:
گام‌های debug:
- `openclaw plugins list --enabled --verbose` را اجرا کنید تا هر Plugin فعال
و منشأ آن را ببینید.
- برای دیدن هر Plugin فعال و خاستگاه آن، `openclaw plugins list --enabled --verbose` را اجرا کنید.
- برای هر Plugin مشکوک `openclaw plugins inspect <id> --runtime --json` را اجرا کنید و
`channels`، `channelConfigs`، `tools` و diagnostics را مقایسه کنید.
- پس از نصب یا حذف packageهای Plugin، `openclaw plugins registry --refresh` را اجرا کنید
تا metadata پایدارشده وضعیت نصب فعلی را منعکس کند.
- پس از تغییرات نصب، رجیستری یا پیکربندی، Gateway را دوباره راه‌اندازی کنید.
تا metadata ذخیره‌شده نصب فعلی را منعکس کند.
- پس از تغییرات نصب، رجیستری، یا پیکربندی، Gateway را راه‌اندازی مجدد کنید.
گزینه‌های رفع مشکل:
گزینه‌های رفع:
- اگر یک Plugin عمدا جایگزین Plugin دیگری برای همان شناسه کانال می‌شود، Plugin
ترجیحی باید `channelConfigs.<channel-id>.preferOver` را با شناسه Plugin
با اولویت پایین‌تر اعلام کند. [/plugins/manifest#replacing-another-channel-plugin](/fa/plugins/manifest#replacing-another-channel-plugin) را ببینید.
- اگر یک Plugin عمداً Plugin دیگری را برای همان شناسه کانال جایگزین می‌کند، Plugin
ترجیحی باید `channelConfigs.<channel-id>.preferOver` را با
شناسه Plugin دارای اولویت پایین‌تر اعلام کند. [/plugins/manifest#replacing-another-channel-plugin](/fa/plugins/manifest#replacing-another-channel-plugin) را ببینید.
- اگر تکرار تصادفی است، یک طرف را با
`plugins.entries.<plugin-id>.enabled: false` غیرفعال کنید یا نصب Plugin کهنه را حذف کنید.
- اگر هر دو Plugin را صراحتا فعال کرده‌اید، OpenClaw آن request را حفظ می‌کند و
conflict را گزارش می‌دهد. یک مالک برای کانال انتخاب کنید یا ابزارهای متعلق به Plugin را
rename کنید تا سطح runtime بدون ابهام باشد.
- اگر هر دو Plugin را صریحاً فعال کرده‌اید، OpenClaw آن درخواست را نگه می‌دارد و
تعارض را گزارش می‌کند. برای کانال یک مالک انتخاب کنید یا ابزارهای متعلق به Plugin را
تغییر نام دهید تا سطح runtime بدون ابهام باشد.
## اسلات‌های Plugin (دسته‌های انحصاری)
## جایگاه‌های Plugin (دسته‌های انحصاری)
برخی دسته‌ها انحصاری هستند (در هر زمان فقط یکی فعال است):
برخی دسته‌ها انحصاری‌اند (در هر زمان فقط یکی فعال است):
```json5
{
@ -458,10 +462,10 @@ flow راه‌اندازی، یا نام ابزار باشد. رایج‌تری
}
```
| اسلات | آنچه کنترل می‌کند | پیش‌فرض |
| جایگاه | چه چیزی را کنترل می‌کند | پیش‌فرض |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin حافظه فعال | `memory-core` |
| `contextEngine` | موتور context فعال | `legacy` (built-in) |
| `contextEngine` | موتور context فعال | `legacy` (داخلی) |
## مرجع CLI
@ -511,85 +515,35 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Plugin‌های همراه با OpenClaw عرضه می‌شوند. بسیاری از آن‌ها به‌صورت پیش‌فرض فعال هستند (برای مثال
ارائه‌دهندگان مدل همراه، ارائه‌دهندگان گفتار همراه، و Plugin مرورگر
همراه). دیگر Plugin‌های همراه همچنان به `openclaw plugins enable <id>` نیاز دارند.
Pluginهای همراه با OpenClaw عرضه می‌شوند. بسیاری از آن‌ها به‌صورت پیش‌فرض فعال هستند (برای نمونه، ارائه‌دهنده‌های مدل همراه، ارائه‌دهنده‌های گفتار همراه، و Plugin مرورگر همراه). سایر Pluginهای همراه همچنان به `openclaw plugins enable <id>` نیاز دارند.
`--force` یک Plugin نصب‌شده یا بستهٔ hook موجود را درجا بازنویسی می‌کند. برای
ارتقاهای معمول Plugin‌های npm ردیابی‌شده از
`openclaw plugins update <id-or-npm-spec>` استفاده کنید. این گزینه با `--link`
پشتیبانی نمی‌شود، چون `--link` به‌جای کپی کردن روی یک مقصد نصب مدیریت‌شده، از مسیر
مبدأ دوباره استفاده می‌کند.
`--force` یک Plugin نصب‌شده یا بسته hook موجود را در همان محل بازنویسی می‌کند. برای ارتقاهای معمول Pluginهای npm ردیابی‌شده از `openclaw plugins update <id-or-npm-spec>` استفاده کنید. این گزینه با `--link` پشتیبانی نمی‌شود، چون `--link` به‌جای کپی کردن روی یک مقصد نصب مدیریت‌شده، مسیر منبع را دوباره استفاده می‌کند.
وقتی `plugins.allow` از قبل تنظیم شده باشد، `openclaw plugins install` شناسهٔ
Plugin نصب‌شده را پیش از فعال‌سازی آن به آن فهرست مجاز اضافه می‌کند. اگر همان شناسهٔ
Plugin در `plugins.deny` وجود داشته باشد، نصب آن ورودی deny قدیمی را حذف می‌کند تا
نصب صریح پس از راه‌اندازی دوباره بلافاصله قابل بارگذاری باشد.
وقتی `plugins.allow` از قبل تنظیم شده باشد، `openclaw plugins install` شناسه Plugin نصب‌شده را پیش از فعال‌سازی آن به همان allowlist اضافه می‌کند. اگر همان شناسه Plugin در `plugins.deny` وجود داشته باشد، نصب آن ورودی deny قدیمی را حذف می‌کند تا نصب صریح بلافاصله پس از راه‌اندازی مجدد قابل بارگذاری باشد.
OpenClaw یک رجیستری محلی پایدار برای Plugin نگه می‌دارد که به‌عنوان مدل خواندن سرد
برای فهرست موجودی Plugin، مالکیت contribution، و برنامه‌ریزی راه‌اندازی استفاده می‌شود. جریان‌های نصب، به‌روزرسانی،
حذف نصب، فعال‌سازی، و غیرفعال‌سازی پس از تغییر وضعیت Plugin آن رجیستری را تازه‌سازی می‌کنند.
همان فایل `plugins/installs.json` فرادادهٔ نصب پایدار را در
`installRecords` سطح بالا و فرادادهٔ manifest قابل بازسازی را در `plugins` نگه می‌دارد. اگر
رجیستری وجود نداشته باشد، قدیمی باشد، یا نامعتبر باشد، `openclaw plugins registry
--refresh` نمای manifest آن را از رکوردهای نصب، سیاست پیکربندی، و
فرادادهٔ manifest/package بدون بارگذاری ماژول‌های runtime Plugin بازسازی می‌کند.
`openclaw plugins update <id-or-npm-spec>` روی نصب‌های ردیابی‌شده اعمال می‌شود. ارسال
یک spec بستهٔ npm با dist-tag یا نسخهٔ دقیق، نام بسته را
به رکورد Plugin ردیابی‌شده برمی‌گرداند و spec جدید را برای به‌روزرسانی‌های آینده ثبت می‌کند.
ارسال نام بسته بدون نسخه، یک نصب دقیقاً pin‌شده را به
خط انتشار پیش‌فرض رجیستری برمی‌گرداند. اگر Plugin نصب‌شدهٔ npm از قبل با
نسخهٔ resolve‌شده و هویت artifact ثبت‌شده مطابقت داشته باشد، OpenClaw به‌روزرسانی را
بدون دانلود، نصب دوباره، یا بازنویسی پیکربندی رد می‌کند.
وقتی `openclaw update` روی کانال beta اجرا می‌شود، رکوردهای Plugin خط پیش‌فرض npm و ClawHub
ابتدا `@beta` را امتحان می‌کنند و وقتی انتشار beta برای Plugin وجود نداشته باشد، به default/latest
برمی‌گردند. نسخه‌های دقیق و tagهای صریح pin‌شده باقی می‌مانند.
OpenClaw یک رجیستری محلی پایدار Plugin را به‌عنوان مدل خواندن سرد برای موجودی Plugin، مالکیت مشارکت‌ها، و برنامه‌ریزی راه‌اندازی نگه می‌دارد. جریان‌های نصب، به‌روزرسانی، حذف نصب، فعال‌سازی، و غیرفعال‌سازی پس از تغییر وضعیت Plugin آن رجیستری را تازه‌سازی می‌کنند. همان فایل `plugins/installs.json` فراداده نصب پایدار را در `installRecords` سطح بالا و فراداده manifest قابل بازسازی را در `plugins` نگه می‌دارد. اگر رجیستری وجود نداشته باشد، قدیمی باشد، یا نامعتبر باشد، `openclaw plugins registry --refresh` نمای manifest آن را از رکوردهای نصب، سیاست پیکربندی، و فراداده manifest/package بدون بارگذاری ماژول‌های runtime مربوط به Plugin بازسازی می‌کند.
`openclaw plugins update <id-or-npm-spec>` روی نصب‌های ردیابی‌شده اعمال می‌شود. دادن یک spec بسته npm همراه با یک dist-tag یا نسخه دقیق، نام بسته را به رکورد Plugin ردیابی‌شده برمی‌گرداند و spec جدید را برای به‌روزرسانی‌های آینده ثبت می‌کند. دادن نام بسته بدون نسخه، یک نصب پین‌شده دقیق را به خط انتشار پیش‌فرض رجیستری برمی‌گرداند. اگر Plugin نصب‌شده npm از قبل با نسخه resolveشده و هویت artifact ثبت‌شده مطابقت داشته باشد، OpenClaw به‌روزرسانی را بدون دانلود، نصب مجدد، یا بازنویسی پیکربندی رد می‌کند.
وقتی `openclaw update` روی کانال beta اجرا می‌شود، رکوردهای Plugin مربوط به npm در خط پیش‌فرض و ClawHub ابتدا `@beta` را امتحان می‌کنند و وقتی هیچ انتشار beta برای Plugin وجود نداشته باشد، به default/latest برمی‌گردند. نسخه‌های دقیق و tagهای صریح پین‌شده باقی می‌مانند.
`--pin` فقط مخصوص npm است. با `--marketplace` پشتیبانی نمی‌شود، چون
نصب‌های marketplace به‌جای spec مربوط به npm، فرادادهٔ منبع marketplace را پایدار نگه می‌دارند.
`--pin` فقط مخصوص npm است. این گزینه با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای یک spec مربوط به npm، فراداده منبع marketplace را پایدار می‌کنند.
`--dangerously-force-unsafe-install` یک override اضطراری برای مثبت‌های کاذب
اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب‌ها و به‌روزرسانی‌های Plugin
از findings داخلی `critical` عبور کنند، اما همچنان بلوک‌های سیاست `before_install` مربوط به Plugin
یا بلوک ناشی از شکست اسکن را دور نمی‌زند.
اسکن‌های نصب، فایل‌ها و دایرکتوری‌های رایج آزمون مانند `tests/`،
`__tests__/`، `*.test.*`، و `*.spec.*` را نادیده می‌گیرند تا mockهای آزمون بسته‌بندی‌شده را مسدود نکنند؛
entrypointهای runtime اعلام‌شدهٔ Plugin همچنان اسکن می‌شوند، حتی اگر از یکی از
آن نام‌ها استفاده کنند.
`--dangerously-force-unsafe-install` یک override اضطراری برای مثبت‌های کاذب اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب‌ها و به‌روزرسانی‌های Plugin از یافته‌های داخلی `critical` عبور کنند، اما همچنان بلوک‌های سیاست `before_install` مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند. اسکن‌های نصب فایل‌ها و دایرکتوری‌های رایج تست مانند `tests/`،‏ `__tests__/`،‏ `*.test.*`، و `*.spec.*` را نادیده می‌گیرند تا mockهای تست بسته‌بندی‌شده باعث مسدودسازی نشوند؛ entrypointهای runtime اعلام‌شده Plugin همچنان اسکن می‌شوند حتی اگر از یکی از آن نام‌ها استفاده کنند.
این پرچم CLI فقط روی جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skills
با پشتوانهٔ Gateway به‌جای آن از override درخواست متناظر `dangerouslyForceUnsafeInstall`
استفاده می‌کنند، در حالی که `openclaw skills install` همچنان جریان جداگانهٔ دانلود/نصب
Skill از ClawHub است.
این flag مربوط به CLI فقط برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب وابستگی‌های skill مبتنی بر Gateway در عوض از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کند، در حالی که `openclaw skills install` همچنان جریان جداگانه دانلود/نصب skill از ClawHub است.
اگر Pluginی که در ClawHub منتشر کرده‌اید توسط یک اسکن پنهان یا مسدود شده است، داشبورد
ClawHub را باز کنید یا `clawhub package rescan <name>` را اجرا کنید تا از ClawHub بخواهید
دوباره آن را بررسی کند. `--dangerously-force-unsafe-install` فقط روی نصب‌ها در دستگاه خودتان
اثر می‌گذارد؛ از ClawHub نمی‌خواهد Plugin را دوباره اسکن کند یا یک انتشار مسدودشده را
عمومی کند.
اگر Pluginی که در ClawHub منتشر کرده‌اید به‌دلیل یک اسکن پنهان یا مسدود شده است، داشبورد ClawHub را باز کنید یا `clawhub package rescan <name>` را اجرا کنید تا از ClawHub بخواهید دوباره آن را بررسی کند. `--dangerously-force-unsafe-install` فقط روی نصب‌ها در دستگاه خودتان اثر دارد؛ از ClawHub نمی‌خواهد Plugin را دوباره اسکن کند یا یک انتشار مسدودشده را عمومی کند.
bundleهای سازگار در همان جریان فهرست/بازرسی/فعال‌سازی/غیرفعال‌سازی Plugin
شرکت می‌کنند. پشتیبانی runtime فعلی شامل Skills مربوط به bundle، command-skillهای Claude،
پیش‌فرض‌های `settings.json` در Claude، پیش‌فرض‌های `.lsp.json` در Claude و
`lspServers` اعلام‌شده در manifest، command-skillهای Cursor، و دایرکتوری‌های hook
سازگار Codex است.
بسته‌های سازگار در همان جریان فهرست/بازرسی/فعال‌سازی/غیرفعال‌سازی Plugin مشارکت می‌کنند. پشتیبانی runtime فعلی شامل Skills بسته، command-skills مربوط به Claude، پیش‌فرض‌های `settings.json` مربوط به Claude، پیش‌فرض‌های `lspServers` اعلام‌شده در manifest و `.lsp.json` مربوط به Claude، command-skills مربوط به Cursor، و دایرکتوری‌های hook سازگار Codex است.
`openclaw plugins inspect <id>` همچنین قابلیت‌های شناسایی‌شدهٔ bundle به‌علاوهٔ
ورودی‌های سرور MCP و LSP پشتیبانی‌شده یا پشتیبانی‌نشده برای Plugin‌های مبتنی بر bundle را گزارش می‌دهد.
`openclaw plugins inspect <id>` همچنین قابلیت‌های بسته شناسایی‌شده به‌علاوه ورودی‌های پشتیبانی‌شده یا پشتیبانی‌نشده سرور MCP و LSP را برای Pluginهای مبتنی بر بسته گزارش می‌کند.
منابع marketplace می‌توانند یک نام marketplace شناخته‌شدهٔ Claude از
`~/.claude/plugins/known_marketplaces.json`، یک ریشهٔ marketplace محلی یا
مسیر `marketplace.json`، یک shorthand مربوط به GitHub مانند `owner/repo`، یک URL مخزن GitHub،
یا یک URL مربوط به git باشند. برای marketplaceهای remote، ورودی‌های Plugin باید داخل
مخزن marketplace کلون‌شده بمانند و فقط از منابع مسیر نسبی استفاده کنند.
منابع marketplace می‌توانند یک نام marketplace شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json`، یک ریشه marketplace محلی یا مسیر `marketplace.json`، یک کوتاه‌نویسی GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL git باشند. برای marketplaceهای راه‌دور، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند و فقط از منابع مسیر نسبی استفاده کنند.
برای جزئیات کامل، [مرجع CLI مربوط به `openclaw plugins`](/fa/cli/plugins) را ببینید.
## نمای کلی API Plugin
## نمای کلی API مربوط به Plugin
Plugin‌های native یک entry object صادر می‌کنند که `register(api)` را در دسترس می‌گذارد. Plugin‌های قدیمی‌تر
ممکن است همچنان از `activate(api)` به‌عنوان alias قدیمی استفاده کنند، اما Plugin‌های جدید باید
از `register` استفاده کنند.
Pluginهای بومی یک شیء entry صادر می‌کنند که `register(api)` را ارائه می‌دهد. Pluginهای قدیمی‌تر ممکن است همچنان از `activate(api)` به‌عنوان alias قدیمی استفاده کنند، اما Pluginهای جدید باید از `register` استفاده کنند.
```typescript
export default definePluginEntry({
@ -609,38 +563,28 @@ export default definePluginEntry({
});
```
OpenClaw در زمان فعال‌سازی Plugin، entry object را بارگذاری می‌کند و `register(api)` را
فراخوانی می‌کند. loader همچنان برای Plugin‌های قدیمی‌تر به `activate(api)` برمی‌گردد،
اما Plugin‌های همراه و Plugin‌های خارجی جدید باید `register` را به‌عنوان
قرارداد عمومی در نظر بگیرند.
OpenClaw شیء entry را بارگذاری می‌کند و در زمان فعال‌سازی Plugin، `register(api)` را فراخوانی می‌کند. loader همچنان برای Pluginهای قدیمی‌تر به `activate(api)` fallback می‌کند، اما Pluginهای همراه و Pluginهای خارجی جدید باید `register` را به‌عنوان قرارداد عمومی در نظر بگیرند.
`api.registrationMode` به یک Plugin می‌گوید چرا entry آن در حال بارگذاری است:
| حالت | معنا |
| حالت | معنی |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | فعال‌سازی runtime. ابزارها، hookها، سرویس‌ها، فرمان‌ها، routeها، و دیگر عوارض جانبی live را ثبت کنید. |
| `discovery` | کشف قابلیت فقط‌خواندنی. ارائه‌دهندگان و فراداده را ثبت کنید؛ کد entry مربوط به Plugin مورد اعتماد ممکن است بارگذاری شود، اما عوارض جانبی live را رد کنید. |
| `setup-only` | بارگذاری فرادادهٔ راه‌اندازی Channel از طریق یک entry سبک راه‌اندازی. |
| `setup-runtime` | بارگذاری راه‌اندازی Channel که به entry runtime نیز نیاز دارد. |
| `cli-metadata` | فقط گردآوری فرادادهٔ فرمان CLI. |
| `full` | فعال‌سازی runtime. ابزارها، hookها، سرویس‌ها، commandها، routeها، و سایر اثرات جانبی زنده را ثبت کنید. |
| `discovery` | کشف قابلیت فقط‌خواندنی. ارائه‌دهنده‌ها و فراداده را ثبت کنید؛ کد entry مربوط به Plugin مورد اعتماد ممکن است بارگذاری شود، اما اثرات جانبی زنده را رد کنید. |
| `setup-only` | بارگذاری فراداده راه‌اندازی کانال از طریق یک setup entry سبک. |
| `setup-runtime` | بارگذاری راه‌اندازی کانال که به entry مربوط به runtime هم نیاز دارد. |
| `cli-metadata` | فقط گردآوری فراداده command مربوط به CLI. |
entryهای Plugin که socket، پایگاه‌داده، workerهای پس‌زمینه، یا clientهای بلندعمر
باز می‌کنند باید آن عوارض جانبی را با `api.registrationMode === "full"` محافظت کنند.
بارگذاری‌های discovery جدا از بارگذاری‌های فعال‌سازی cache می‌شوند و
رجیستری Gateway در حال اجرا را جایگزین نمی‌کنند. discovery فعال‌کننده نیست، اما بدون import هم نیست:
OpenClaw ممکن است entry مورد اعتماد Plugin یا ماژول Plugin مربوط به channel را برای ساخت
snapshot ارزیابی کند. سطح بالای ماژول‌ها را سبک و بدون عوارض جانبی نگه دارید، و
clientهای شبکه، subprocessها، listenerها، خواندن credentialها، و راه‌اندازی سرویس را
پشت مسیرهای full-runtime منتقل کنید.
entryهای Plugin که socket، پایگاه‌داده، worker پس‌زمینه، یا clientهای بلندمدت باز می‌کنند باید آن اثرات جانبی را با `api.registrationMode === "full"` محافظت کنند. بارگذاری‌های discovery جدا از بارگذاری‌های فعال‌سازی cache می‌شوند و جایگزین رجیستری Gateway در حال اجرا نمی‌شوند. discovery غیرفعال‌ساز است، نه بدون import: OpenClaw ممکن است entry مربوط به Plugin مورد اعتماد یا ماژول Plugin کانال را برای ساخت snapshot ارزیابی کند. سطح بالای ماژول‌ها را سبک و بدون اثر جانبی نگه دارید، و clientهای شبکه، subprocessها، listenerها، خواندن credentialها، و راه‌اندازی سرویس را پشت مسیرهای full-runtime منتقل کنید.
روش‌های ثبت رایج:
روش‌های رایج ثبت:
| روش | آنچه ثبت می‌کند |
| --------------------------------------- | --------------------------- |
| `registerProvider` | ارائه‌دهندهٔ مدل (LLM) |
| `registerChannel` | کانال گفتگو |
| `registerTool` | ابزار agent |
| `registerHook` / `on(...)` | hookهای چرخهٔ عمر |
| `registerProvider` | ارائه‌دهنده مدل (LLM) |
| `registerChannel` | کانال chat |
| `registerTool` | ابزار عامل |
| `registerHook` / `on(...)` | hookهای چرخه حیات |
| `registerSpeechProvider` | تبدیل متن به گفتار / STT |
| `registerRealtimeTranscriptionProvider` | STT جریانی |
| `registerRealtimeVoiceProvider` | صدای realtime دوطرفه |
@ -648,36 +592,31 @@ clientهای شبکه، subprocessها، listenerها، خواندن credential
| `registerImageGenerationProvider` | تولید تصویر |
| `registerMusicGenerationProvider` | تولید موسیقی |
| `registerVideoGenerationProvider` | تولید ویدیو |
| `registerWebFetchProvider` | ارائه‌دهندهٔ دریافت / scrape وب |
| `registerWebFetchProvider` | ارائه‌دهنده واکشی وب / scrape |
| `registerWebSearchProvider` | جستجوی وب |
| `registerHttpRoute` | endpoint مربوط به HTTP |
| `registerCommand` / `registerCli` | فرمان‌های CLI |
| `registerCommand` / `registerCli` | commandهای CLI |
| `registerContextEngine` | موتور context |
| `registerService` | سرویس پس‌زمینه |
رفتار guard مربوط به hookهای چرخهٔ عمر typed:
رفتار guard مربوط به hookهای چرخه حیات typed:
- `before_tool_call`: `{ block: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `before_tool_call`: `{ block: false }` یک no-op است و block قبلی را پاک نمی‌کند.
- `before_install`: `{ block: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `before_install`: `{ block: false }` یک no-op است و block قبلی را پاک نمی‌کند.
- `message_sending`: `{ cancel: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `message_sending`: `{ cancel: false }` یک no-op است و cancel قبلی را پاک نمی‌کند.
- `before_tool_call`:‏ `{ block: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `before_tool_call`:‏ `{ block: false }` یک no-op است و block قبلی را پاک نمی‌کند.
- `before_install`:‏ `{ block: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `before_install`:‏ `{ block: false }` یک no-op است و block قبلی را پاک نمی‌کند.
- `message_sending`:‏ `{ cancel: true }` نهایی است؛ handlerهای با اولویت پایین‌تر رد می‌شوند.
- `message_sending`:‏ `{ cancel: false }` یک no-op است و cancel قبلی را پاک نمی‌کند.
app-server بومی Codex، رخدادهای ابزار بومی Codex را از طریق bridge دوباره به این
سطح hook برمی‌گرداند. Pluginها می‌توانند ابزارهای بومی Codex را از طریق `before_tool_call`
مسدود کنند، نتایج را از طریق `after_tool_call` مشاهده کنند، و در تأییدهای
`PermissionRequest` مربوط به Codex مشارکت داشته باشند. bridge هنوز آرگومان‌های ابزار بومی Codex
را بازنویسی نمی‌کند. مرز دقیق پشتیبانی runtime مربوط به Codex در
[قرارداد پشتیبانی v1 harness مربوط به Codex](/fa/plugins/codex-harness#v1-support-contract) قرار دارد.
app-server بومی Codex رویدادهای ابزار بومی Codex را به این سطح hook پل می‌زند. Pluginها می‌توانند ابزارهای بومی Codex را از طریق `before_tool_call` مسدود کنند، نتیجه‌ها را از طریق `after_tool_call` مشاهده کنند، و در تاییدهای `PermissionRequest` مربوط به Codex مشارکت کنند. bridge هنوز آرگومان‌های ابزار بومی Codex را بازنویسی نمی‌کند. مرز دقیق پشتیبانی runtime مربوط به Codex در [قرارداد پشتیبانی v1 برای harness مربوط به Codex](/fa/plugins/codex-harness#v1-support-contract) قرار دارد.
برای رفتار کامل hookهای typed، [نمای کلی SDK](/fa/plugins/sdk-overview#hook-decision-semantics) را ببینید.
## مرتبط
- [ساخت Pluginها](/fa/plugins/building-plugins) — Plugin خودتان را بسازید
- [bundleهای Plugin](/fa/plugins/bundles) — سازگاری bundleهای Codex/Claude/Cursor
- [manifest مربوط به Plugin](/fa/plugins/manifest) — schema مربوط به manifest
- [ثبت ابزارها](/fa/plugins/building-plugins#registering-agent-tools) — افزودن ابزارهای agent در یک Plugin
- [جزئیات داخلی Plugin](/fa/plugins/architecture) — مدل قابلیت و pipeline بارگذاری
- [Pluginهای جامعه](/fa/plugins/community) — فهرست‌های شخص ثالث
- [ساخت Plugin](/fa/plugins/building-plugins) — Plugin خود را بسازید
- [باندل‌های Plugin](/fa/plugins/bundles) — سازگاری باندل‌های Codex/Claude/Cursor
- [مانیفست Plugin](/fa/plugins/manifest) — طرح‌وارهٔ مانیفست
- [ثبت ابزارها](/fa/plugins/building-plugins#registering-agent-tools) — ابزارهای عامل را در یک Plugin اضافه کنید
- [درون‌ساخت Plugin](/fa/plugins/architecture) — مدل قابلیت و خط لولهٔ بارگذاری
- [Plugin‌های جامعه](/fa/plugins/community) — فهرست‌های شخص ثالث

171
docs/fa/tools/thinking.md
View File

@ -1,144 +1,145 @@
---
read_when:
- تنظیم تجزیه یا پیش‌فرض‌های دستورالعمل‌های تفکر، حالت سریع یا پرجزئیات
summary: نحو دستورالعمل‌ها برای /think، /fast، /verbose، /trace و قابلیت مشاهدهٔ استدلال
- تنظیم تجزیه یا مقادیر پیش‌فرضِ تفکر، حالت سریع یا دستورالعمل پرگویی
summary: نحو دایرکتیو برای /think، /fast، /verbose، /trace و قابلیت مشاهدهٔ استدلال
title: سطوح تفکر
x-i18n:
generated_at: "2026-05-04T18:23:34Z"
generated_at: "2026-05-05T01:53:29Z"
model: gpt-5.5
provider: openai
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
## چه کاری انجام می‌دهد
## کارکرد آن
- دستور درون‌خطی در هر بدنهٔ ورودی: `/t <level>`، `/think:<level>` یا `/thinking <level>`.
- دستور درون‌خطی در هر بدنه ورودی: `/t <level>`، `/think:<level>`، یا `/thinking <level>`.
- سطح‌ها (نام‌های مستعار): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → «فکر کن»
- low → «سخت فکر کن»
- medium → «سخت‌تر فکر کن»
- high → «بسیار عمیق فکر کن» (حداکثر بودجه)
- xhigh → «بسیار عمیق فکر کن+» (مدل‌های GPT-5.2+ و Codex، به‌علاوهٔ تلاش Anthropic Claude Opus 4.7)
- adaptive → تفکر تطبیقی مدیریت‌شده توسط ارائه‌دهنده (برای Claude 4.6 روی Anthropic/Bedrock، Anthropic Claude Opus 4.7 و تفکر پویا در Google Gemini پشتیبانی می‌شود)
- max → حداکثر استدلال ارائه‌دهنده (Anthropic Claude Opus 4.7؛ Ollama این را به بالاترین تلاش بومی `think` خود نگاشت می‌کند)
- minimal → «think»
- low → «think hard»
- medium → «think harder»
- high → «ultrathink» (حداکثر بودجه)
- xhigh → «ultrathink+» (مدل‌های GPT-5.2+ و Codex، به‌علاوه تلاش Anthropic Claude Opus 4.7)
- adaptive → تفکر تطبیقی مدیریت‌شده توسط ارائه‌دهنده (برای Claude 4.6 روی Anthropic/Bedrock، Anthropic Claude Opus 4.7 و تفکر پویای Google Gemini پشتیبانی می‌شود)
- max → استدلال حداکثری ارائه‌دهنده (Anthropic Claude Opus 4.7؛ Ollama این را به بالاترین تلاش بومی `think` خود نگاشت می‌کند)
- `x-high`، `x_high`، `extra-high`، `extra high` و `extra_high` به `xhigh` نگاشت می‌شوند.
- `highest` به `high` نگاشت می‌شود.
- یادداشت‌های ارائه‌دهنده:
- منوها و انتخاب‌گرهای تفکر بر اساس پروفایل ارائه‌دهنده هدایت می‌شوند. Pluginهای ارائه‌دهنده مجموعهٔ دقیق سطح‌ها را برای مدل انتخاب‌شده اعلام می‌کنند، از جمله برچسب‌هایی مانند `on` دودویی.
- `adaptive`، `xhigh` و `max` فقط برای پروفایل‌های ارائه‌دهنده/مدلی نمایش داده می‌شوند که از آن‌ها پشتیبانی می‌کنند. دستورهای تایپ‌شده برای سطح‌های پشتیبانی‌نشده با گزینه‌های معتبر همان مدل رد می‌شوند.
- سطح‌های پشتیبانی‌نشدهٔ ذخیره‌شدهٔ موجود بر اساس رتبهٔ پروفایل ارائه‌دهنده دوباره نگاشت می‌شوند. `adaptive` در مدل‌های غیرتطبیقی به `medium` برمی‌گردد، در حالی که `xhigh` و `max` به بزرگ‌ترین سطح غیر `off` پشتیبانی‌شده برای مدل انتخاب‌شده برمی‌گردند.
- مدل‌های Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد، به‌طور پیش‌فرض `adaptive` هستند.
- Anthropic Claude Opus 4.7 به‌طور پیش‌فرض از تفکر تطبیقی استفاده نمی‌کند. پیش‌فرض تلاش API آن متعلق به ارائه‌دهنده می‌ماند، مگر اینکه صراحتاً سطح تفکر تنظیم کنید.
- Anthropic Claude Opus 4.7 دستور `/think xhigh` را به تفکر تطبیقی به‌همراه `output_config.effort: "xhigh"` نگاشت می‌کند، چون `/think` یک دستور تفکر است و `xhigh` تنظیم تلاش Opus 4.7 است.
- Anthropic Claude Opus 4.7 همچنین `/think max` را ارائه می‌کند؛ این دستور به همان مسیر حداکثر تلاش متعلق به ارائه‌دهنده نگاشت می‌شود.
- مدل‌های DeepSeek V4 دستور `/think xhigh|max` را ارائه می‌کنند؛ هر دو به `reasoning_effort: "max"` در DeepSeek نگاشت می‌شوند، در حالی که سطح‌های پایین‌تر غیر `off` به `high` نگاشت می‌شوند.
- مدل‌های دارای قابلیت تفکر Ollama دستور `/think low|medium|high|max` را ارائه می‌کنند؛ `max` به `think: "high"` بومی نگاشت می‌شود، چون API بومی Ollama رشته‌های تلاش `low`، `medium` و `high` را می‌پذیرد.
- مدل‌های OpenAI GPT دستور `/think` را از طریق پشتیبانی تلاش مختص مدل در Responses API نگاشت می‌کنند. `/think off` فقط وقتی مدل هدف از آن پشتیبانی کند `reasoning.effort: "none"` را می‌فرستد؛ در غیر این صورت OpenClaw به‌جای فرستادن مقدار پشتیبانی‌نشده، بار دادهٔ استدلال غیرفعال‌شده را حذف می‌کند.
- ورودی‌های کاتالوگ سفارشی سازگار با OpenAI می‌توانند با تنظیم `models.providers.<provider>.models[].compat.supportedReasoningEfforts` برای شامل کردن `"xhigh"`، از `/think xhigh` پشتیبانی کنند. این از همان فرادادهٔ سازگاری استفاده می‌کند که بارهای دادهٔ تلاش استدلال خروجی OpenAI را نگاشت می‌کند، بنابراین منوها، اعتبارسنجی نشست، CLI عامل و `llm-task` با رفتار انتقال هم‌نظر می‌مانند.
- ارجاع‌های پیکربندی‌شدهٔ قدیمی OpenRouter Hunter Alpha تزریق استدلال پروکسی را رد می‌کنند، چون آن مسیر بازنشسته می‌توانست متن پاسخ نهایی را از طریق فیلدهای استدلال برگرداند.
- Google Gemini دستور `/think adaptive` را به تفکر پویای متعلق به ارائه‌دهندهٔ Gemini نگاشت می‌کند. درخواست‌های Gemini 3 یک `thinkingLevel` ثابت را حذف می‌کنند، در حالی که درخواست‌های Gemini 2.5 مقدار `thinkingBudget: -1` را می‌فرستند؛ سطح‌های ثابت همچنان به نزدیک‌ترین `thinkingLevel` یا بودجهٔ Gemini برای آن خانوادهٔ مدل نگاشت می‌شوند.
- MiniMax (`minimax/*`) در مسیر استریم سازگار با Anthropic به‌طور پیش‌فرض `thinking: { type: "disabled" }` است، مگر اینکه صراحتاً تفکر را در پارامترهای مدل یا پارامترهای درخواست تنظیم کنید. این کار از نشت دلتاهای `reasoning_content` از قالب استریم غیر بومی Anthropic در MiniMax جلوگیری می‌کند.
- منوها و انتخابگرهای تفکر بر اساس پروفایل ارائه‌دهنده هدایت می‌شوند. Provider plugins مجموعه دقیق سطح‌ها را برای مدل انتخاب‌شده، از جمله برچسب‌هایی مثل `on` دودویی، اعلام می‌کنند.
- `adaptive`، `xhigh` و `max` فقط برای پروفایل‌های ارائه‌دهنده/مدلی نمایش داده می‌شوند که از آن‌ها پشتیبانی می‌کنند. دستورهای تایپ‌شده برای سطح‌های پشتیبانی‌نشده با گزینه‌های معتبر آن مدل رد می‌شوند.
- سطح‌های پشتیبانی‌نشده ذخیره‌شده موجود بر اساس رتبه پروفایل ارائه‌دهنده دوباره نگاشت می‌شوند. `adaptive` روی مدل‌های غیرتطبیقی به `medium` برمی‌گردد، در حالی که `xhigh` و `max` به بزرگ‌ترین سطح غیر `off` پشتیبانی‌شده برای مدل انتخاب‌شده برمی‌گردند.
- مدل‌های Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد به‌طور پیش‌فرض از `adaptive` استفاده می‌کنند.
- Anthropic Claude Opus 4.7 به‌طور پیش‌فرض از تفکر تطبیقی استفاده نمی‌کند. پیش‌فرض تلاش API آن تحت مالکیت ارائه‌دهنده می‌ماند، مگر اینکه سطح تفکر را صریحاً تنظیم کنید.
- Anthropic Claude Opus 4.7 دستور `/think xhigh` را به تفکر تطبیقی به‌علاوه `output_config.effort: "xhigh"` نگاشت می‌کند، چون `/think` یک دستور تفکر است و `xhigh` تنظیم تلاش Opus 4.7 است.
- Anthropic Claude Opus 4.7 همچنین `/think max` را ارائه می‌کند؛ این دستور به همان مسیر تلاش حداکثری تحت مالکیت ارائه‌دهنده نگاشت می‌شود.
- مدل‌های مستقیم DeepSeek V4 دستور `/think xhigh|max` را ارائه می‌کنند؛ هر دو به `reasoning_effort: "max"` در DeepSeek نگاشت می‌شوند، در حالی که سطح‌های غیر `off` پایین‌تر به `high` نگاشت می‌شوند.
- مدل‌های DeepSeek V4 مسیر‌یابی‌شده از طریق OpenRouter دستور `/think xhigh` را ارائه می‌کنند و مقادیر `reasoning_effort` پشتیبانی‌شده توسط OpenRouter را ارسال می‌کنند. overrideهای ذخیره‌شده `max` به `xhigh` برمی‌گردند.
- مدل‌های Ollama با قابلیت تفکر دستور `/think low|medium|high|max` را ارائه می‌کنند؛ `max` به `think: "high"` بومی نگاشت می‌شود، چون API بومی Ollama رشته‌های تلاش `low`، `medium` و `high` را می‌پذیرد.
- مدل‌های OpenAI GPT دستور `/think` را از طریق پشتیبانی تلاش ویژه مدل در Responses API نگاشت می‌کنند. `/think off` فقط زمانی `reasoning.effort: "none"` را ارسال می‌کند که مدل هدف از آن پشتیبانی کند؛ در غیر این صورت OpenClaw به‌جای ارسال مقدار پشتیبانی‌نشده، بار داده استدلال غیرفعال را حذف می‌کند.
- ورودی‌های کاتالوگ سفارشی سازگار با OpenAI می‌توانند با تنظیم `models.providers.<provider>.models[].compat.supportedReasoningEfforts` برای شامل‌کردن `"xhigh"`، از `/think xhigh` پشتیبانی کنند. این از همان فراداده سازگاری استفاده می‌کند که بارهای داده تلاش استدلال خروجی OpenAI را نگاشت می‌کند، بنابراین منوها، اعتبارسنجی نشست، agent CLI و `llm-task` با رفتار انتقال هم‌راستا می‌مانند.
- ارجاع‌های پیکربندی‌شده قدیمی OpenRouter Hunter Alpha تزریق استدلال پروکسی را رد می‌کنند، چون آن مسیر بازنشسته می‌توانست متن پاسخ نهایی را از طریق فیلدهای استدلال برگرداند.
- Google Gemini دستور `/think adaptive` را به تفکر پویای تحت مالکیت ارائه‌دهنده Gemini نگاشت می‌کند. درخواست‌های Gemini 3 یک `thinkingLevel` ثابت را حذف می‌کنند، در حالی که درخواست‌های Gemini 2.5 مقدار `thinkingBudget: -1` را ارسال می‌کنند؛ سطح‌های ثابت همچنان به نزدیک‌ترین `thinkingLevel` یا بودجه Gemini برای آن خانواده مدل نگاشت می‌شوند.
- MiniMax (`minimax/*`) در مسیر جریان سازگار با Anthropic به‌طور پیش‌فرض از `thinking: { type: "disabled" }` استفاده می‌کند، مگر اینکه تفکر را صریحاً در پارامترهای مدل یا پارامترهای درخواست تنظیم کنید. این از نشت دلتاهای `reasoning_content` از قالب جریان غیر بومی Anthropic متعلق به MiniMax جلوگیری می‌کند.
- Z.AI (`zai/*`) فقط از تفکر دودویی (`on`/`off`) پشتیبانی می‌کند. هر سطح غیر `off` به‌عنوان `on` در نظر گرفته می‌شود (به `low` نگاشت می‌شود).
- Moonshot (`moonshot/*`) دستور `/think off` را به `thinking: { type: "disabled" }` و هر سطح غیر `off` را به `thinking: { type: "enabled" }` نگاشت می‌کند. وقتی تفکر فعال باشد، Moonshot فقط `tool_choice` با مقدار `auto|none` را می‌پذیرد؛ OpenClaw مقدارهای ناسازگار را به `auto` نرمال‌سازی می‌کند.
- Moonshot (`moonshot/*`) دستور `/think off` را به `thinking: { type: "disabled" }` و هر سطح غیر `off` را به `thinking: { type: "enabled" }` نگاشت می‌کند. وقتی تفکر فعال باشد، Moonshot فقط `tool_choice` با مقدار `auto|none` را می‌پذیرد؛ OpenClaw مقادیر ناسازگار را به `auto` عادی‌سازی می‌کند.
## ترتیب حل‌وفصل
## ترتیب حل
1. دستور درون‌خطی روی پیام (فقط روی همان پیام اعمال می‌شود).
2. بازنویسی نشست (با ارسال یک پیام فقط شامل دستور تنظیم می‌شود).
3. پیش‌فرض هر عامل (`agents.list[].thinkingDefault` در پیکربندی).
1. دستور درون‌خطی روی پیام (فقط برای همان پیام اعمال می‌شود).
2. override نشست (با ارسال پیام فقط شامل دستور تنظیم می‌شود).
3. پیش‌فرض برای هر عامل (`agents.list[].thinkingDefault` در پیکربندی).
4. پیش‌فرض سراسری (`agents.defaults.thinkingDefault` در پیکربندی).
5. پشتیبان: پیش‌فرض اعلام‌شده توسط ارائه‌دهنده، اگر موجود باشد؛ در غیر این صورت مدل‌های دارای قابلیت استدلال به `medium` یا نزدیک‌ترین سطح غیر `off` پشتیبانی‌شده برای آن مدل حل می‌شوند و مدل‌های بدون استدلال روی `off` می‌مانند.
5. بازگشت: پیش‌فرض اعلام‌شده توسط ارائه‌دهنده در صورت وجود؛ در غیر این صورت مدل‌های دارای قابلیت استدلال به `medium` یا نزدیک‌ترین سطح غیر `off` پشتیبانی‌شده برای آن مدل حل می‌شوند، و مدل‌های بدون استدلال روی `off` می‌مانند.
## تنظیم پیش‌فرض نشست
- پیامی بفرستید که **فقط** دستور باشد (فاصلهٔ سفید مجاز است)، برای مثال `/think:medium` یا `/t high`.
- این تنظیم برای نشست فعلی باقی می‌ماند (به‌طور پیش‌فرض برای هر فرستنده)؛ با `/think:off` یا بازنشانی نشست پس از بیکاری پاک می‌شود.
- پاسخ تأیید فرستاده می‌شود (`Thinking level set to high.` / `Thinking disabled.`). اگر سطح نامعتبر باشد (مثلاً `/thinking big`)، فرمان با یک راهنما رد می‌شود و وضعیت نشست بدون تغییر می‌ماند.
- برای دیدن سطح تفکر فعلی، `/think` (یا `/think:`) را بدون آرگومان بفرستید.
- پیامی بفرستید که **فقط** شامل دستور باشد (فاصله مجاز است)، مثلاً `/think:medium` یا `/t high`.
- این برای نشست فعلی پایدار می‌ماند (به‌طور پیش‌فرض برای هر فرستنده)؛ با `/think:off` یا بازنشانی نشست پس از بیکاری پاک می‌شود.
- پاسخ تأیید ارسال می‌شود (`Thinking level set to high.` / `Thinking disabled.`). اگر سطح نامعتبر باشد (مثلاً `/thinking big`)، فرمان با یک راهنما رد می‌شود و وضعیت نشست بدون تغییر می‌ماند.
- برای دیدن سطح تفکر فعلی، `/think` (یا `/think:`) را بدون آرگومان ارسال کنید.
## اعمال بر اساس عامل
- **Pi جاسازی‌شده**: سطح حل‌شده به زمان‌اجرای عامل Pi درون‌فرایندی پاس داده می‌شود.
- **بک‌اند Claude CLI**: سطح‌های غیر off هنگام استفاده از `claude-cli` به‌عنوان `--effort` به Claude Code پاس داده می‌شوند؛ [بک‌اندهای CLI](/fa/gateway/cli-backends) را ببینید.
- **Pi توکار**: سطح حل‌شده به runtime عامل Pi درون‌فرآیندی پاس داده می‌شود.
- **backend Claude CLI**: سطح‌های غیر off هنگام استفاده از `claude-cli` به‌صورت `--effort` به Claude Code پاس داده می‌شوند؛ [backendهای CLI](/fa/gateway/cli-backends) را ببینید.
## حالت سریع (/fast)
- سطح‌ها: `on|off`.
- پیام فقط شامل دستور، بازنویسی حالت سریع نشست را تغییر می‌دهد و پاسخ `Fast mode enabled.` / `Fast mode disabled.` می‌دهد.
- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون حالت بفرستید.
- پیام فقط شامل دستور، override حالت سریع نشست را تغییر می‌دهد و `Fast mode enabled.` / `Fast mode disabled.` پاسخ می‌دهد.
- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون حالت ارسال کنید.
- OpenClaw حالت سریع را به این ترتیب حل می‌کند:
1. `/fast on|off` درون‌خطی/فقط شامل دستور
2. بازنویسی نشست
3. پیش‌فرض هر عامل (`agents.list[].fastModeDefault`)
4. پیکربندی هر مدل: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. پشتیبان: `off`
- برای `openai/*`، حالت سریع با ارسال `service_tier=priority` روی درخواست‌های Responses پشتیبانی‌شده به پردازش اولویت‌دار OpenAI نگاشت می‌شود.
- برای `openai-codex/*`، حالت سریع همان پرچم `service_tier=priority` را روی Codex Responses می‌فرستد. OpenClaw یک کلید مشترک `/fast` را در هر دو مسیر احراز هویت نگه می‌دارد.
- برای درخواست‌های عمومی مستقیم `anthropic/*`، از جمله ترافیک احراز هویت‌شده با OAuth که به `api.anthropic.com` فرستاده می‌شود، حالت سریع به سطح‌های سرویس Anthropic نگاشت می‌شود: `/fast on` مقدار `service_tier=auto` را تنظیم می‌کند، `/fast off` مقدار `service_tier=standard_only` را تنظیم می‌کند.
2. override نشست
3. پیش‌فرض برای هر عامل (`agents.list[].fastModeDefault`)
4. پیکربندی برای هر مدل: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. بازگشت: `off`
- برای `openai/*`، حالت سریع با ارسال `service_tier=priority` در درخواست‌های Responses پشتیبانی‌شده به پردازش اولویت‌دار OpenAI نگاشت می‌شود.
- برای `openai-codex/*`، حالت سریع همان پرچم `service_tier=priority` را در Codex Responses ارسال می‌کند. OpenClaw یک toggle مشترک `/fast` را در هر دو مسیر احراز هویت حفظ می‌کند.
- برای درخواست‌های عمومی مستقیم `anthropic/*`، از جمله ترافیک احراز هویت‌شده با OAuth که به `api.anthropic.com` ارسال می‌شود، حالت سریع به رده‌های سرویس Anthropic نگاشت می‌شود: `/fast on` مقدار `service_tier=auto` را تنظیم می‌کند، `/fast off` مقدار `service_tier=standard_only` را تنظیم می‌کند.
- برای `minimax/*` در مسیر سازگار با Anthropic، `/fast on` (یا `params.fastMode: true`) مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی می‌کند.
- پارامترهای صریح مدل Anthropic با نام `serviceTier` / `service_tier` وقتی هر دو تنظیم باشند، پیش‌فرض حالت سریع را بازنویسی می‌کنند. OpenClaw همچنان تزریق سطح سرویس Anthropic را برای URLهای پایهٔ پروکسی غیر Anthropic رد می‌کند.
- پارامترهای مدل صریح Anthropic با نام `serviceTier` / `service_tier` وقتی هر دو تنظیم شده باشند، پیش‌فرض حالت سریع را override می‌کنند. OpenClaw همچنان تزریق رده سرویس Anthropic را برای URLهای پایه پروکسی غیر Anthropic رد می‌کند.
- `/status` فقط وقتی حالت سریع فعال باشد `Fast` را نشان می‌دهد.
## دستورهای پرجزئیات (/verbose یا /v)
- سطح‌ها: `on` (حداقلی) | `full` | `off` (پیش‌فرض).
- پیام فقط شامل دستور، حالت پرجزئیات نشست را تغییر می‌دهد و پاسخ `Verbose logging enabled.` / `Verbose logging disabled.` می‌دهد؛ سطح‌های نامعتبر بدون تغییر وضعیت، یک راهنما برمی‌گردانند.
- `/verbose off` یک بازنویسی صریح نشست ذخیره می‌کند؛ آن را از طریق رابط کاربری Sessions با انتخاب `inherit` پاک کنید.
- دستور درون‌خطی فقط روی همان پیام اثر می‌گذارد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند.
- برای دیدن سطح پرجزئیات فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان بفرستید.
- وقتی حالت پرجزئیات روشن است، عامل‌هایی که نتایج ابزار ساختاریافته منتشر می‌کنند (Pi، سایر عامل‌های JSON)، هر فراخوانی ابزار را به‌عنوان پیام جداگانهٔ فقط فراداده، با پیشوند `<emoji> <tool-name>: <arg>` در صورت وجود، برمی‌گردانند. این خلاصه‌های ابزار به‌محض شروع هر ابزار فرستاده می‌شوند (حباب‌های جداگانه)، نه به‌عنوان دلتاهای استریم.
- خلاصه‌های شکست ابزار در حالت عادی همچنان قابل مشاهده می‌مانند، اما پسوندهای جزئیات خطای خام پنهان می‌شوند مگر اینکه حالت پرجزئیات `on` یا `full` باشد.
- وقتی حالت پرجزئیات `full` باشد، خروجی‌های ابزار نیز پس از تکمیل ارسال می‌شوند (حباب جداگانه، کوتاه‌شده تا طول امن). اگر هنگام در جریان بودن یک اجرا `/verbose on|full|off` را تغییر دهید، حباب‌های ابزار بعدی از تنظیم جدید پیروی می‌کنند.
- `agents.defaults.toolProgressDetail` شکل خلاصه‌های ابزار `/verbose` و خطوط ابزار پیش‌نویس پیشرفت را کنترل می‌کند. از `"explain"` (پیش‌فرض) برای برچسب‌های انسانی فشرده مانند `🛠️ Exec: checking JS syntax` استفاده کنید؛ وقتی می‌خواهید فرمان/جزئیات خام نیز برای اشکال‌زدایی افزوده شود، از `"raw"` استفاده کنید. مقدار هر عامل در `agents.list[].toolProgressDetail` پیش‌فرض را بازنویسی می‌کند.
- پیام فقط شامل دستور، verbose نشست را تغییر می‌دهد و `Verbose logging enabled.` / `Verbose logging disabled.` پاسخ می‌دهد؛ سطح‌های نامعتبر بدون تغییر وضعیت یک راهنما برمی‌گردانند.
- `/verbose off` یک override صریح نشست ذخیره می‌کند؛ آن را از طریق UI نشست‌ها با انتخاب `inherit` پاک کنید.
- دستور درون‌خطی فقط بر همان پیام اثر می‌گذارد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند.
- برای دیدن سطح verbose فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان ارسال کنید.
- وقتی verbose روشن باشد، عامل‌هایی که نتایج ابزار ساختاریافته منتشر می‌کنند (Pi و عامل‌های JSON دیگر) هر فراخوانی ابزار را به‌صورت پیام جداگانه فقط-فراداده برمی‌گردانند و در صورت وجود با `<emoji> <tool-name>: <arg>` شروع می‌کنند. این خلاصه‌های ابزار به‌محض شروع هر ابزار ارسال می‌شوند (حباب‌های جداگانه)، نه به‌صورت دلتاهای جریانی.
- خلاصه‌های شکست ابزار در حالت عادی قابل مشاهده می‌مانند، اما پسوندهای جزئیات خطای خام پنهان می‌شوند مگر اینکه verbose برابر `on` یا `full` باشد.
- وقتی verbose برابر `full` باشد، خروجی‌های ابزار نیز پس از تکمیل فوروارد می‌شوند (حباب جداگانه، کوتاه‌شده تا طول امن). اگر هنگام اجرای یک کار `/verbose on|full|off` را تغییر دهید، حباب‌های ابزار بعدی تنظیم جدید را رعایت می‌کنند.
- `agents.defaults.toolProgressDetail` شکل خلاصه‌های ابزار `/verbose` و خطوط ابزار پیش‌نویس پیشرفت را کنترل می‌کند. برای برچسب‌های انسانی فشرده مثل `🛠️ Exec: checking JS syntax` از `"explain"` (پیش‌فرض) استفاده کنید؛ وقتی می‌خواهید فرمان/جزئیات خام نیز برای اشکال‌زدایی اضافه شود از `"raw"` استفاده کنید. `agents.list[].toolProgressDetail` برای هر عامل پیش‌فرض را override می‌کند.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## دستورهای رهگیری Plugin (/trace)
## دستورهای ردیابی Plugin (/trace)
- سطح‌ها: `on` | `off` (پیش‌فرض).
- پیام فقط شامل دستور، خروجی رهگیری Plugin نشست را تغییر می‌دهد و پاسخ `Plugin trace enabled.` / `Plugin trace disabled.` می‌دهد.
- دستور درون‌خطی فقط روی همان پیام اثر می‌گذارد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند.
- برای دیدن سطح رهگیری فعلی، `/trace` (یا `/trace:`) را بدون آرگومان بفرستید.
- `/trace` محدودتر از `/verbose` است: فقط خطوط رهگیری/اشکال‌زدایی متعلق به Plugin مانند خلاصه‌های اشکال‌زدایی Active Memory را آشکار می‌کند.
- خطوط رهگیری می‌توانند در `/status` و به‌عنوان پیام تشخیصی پیرو پس از پاسخ عادی دستیار ظاهر شوند.
- پیام فقط شامل دستور، خروجی ردیابی Plugin نشست را تغییر می‌دهد و `Plugin trace enabled.` / `Plugin trace disabled.` پاسخ می‌دهد.
- دستور درون‌خطی فقط بر همان پیام اثر می‌گذارد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند.
- برای دیدن سطح ردیابی فعلی، `/trace` (یا `/trace:`) را بدون آرگومان ارسال کنید.
- `/trace` از `/verbose` محدودتر است: فقط خطوط ردیابی/اشکال‌زدایی متعلق به Plugin مثل خلاصه‌های اشکال‌زدایی Active Memory را آشکار می‌کند.
- خطوط ردیابی می‌توانند در `/status` و به‌صورت پیام تشخیصی پیگیری پس از پاسخ عادی دستیار ظاهر شوند.
## نمایان بودن استدلال (/reasoning)
## نمایش استدلال (/reasoning)
- سطح‌ها: `on|off|stream`.
- پیام فقط شامل دستور تعیین می‌کند که بلوک‌های تفکر در پاسخ‌ها نشان داده شوند یا نه.
- وقتی فعال باشد، استدلال به‌عنوان یک **پیام جداگانه** با پیشوند `Reasoning:` فرستاده می‌شود.
- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را در حباب پیش‌نویس Telegram استریم می‌کند، سپس پاسخ نهایی را بدون استدلال می‌فرستد.
- وقتی فعال باشد، استدلال به‌صورت **پیام جداگانه** با پیشوند `Reasoning:` ارسال می‌شود.
- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را به حباب پیش‌نویس Telegram جریان می‌دهد، سپس پاسخ نهایی را بدون استدلال ارسال می‌کند.
- نام مستعار: `/reason`.
- برای دیدن سطح استدلال فعلی، `/reasoning` (یا `/reasoning:`) را بدون آرگومان بفرستید.
- ترتیب حل‌وفصل: دستور درون‌خطی، سپس بازنویسی نشست، سپس پیش‌فرض هر عامل (`agents.list[].reasoningDefault`)، سپس پشتیبان (`off`).
- برای دیدن سطح استدلال فعلی، `/reasoning` (یا `/reasoning:`) را بدون آرگومان ارسال کنید.
- ترتیب حل: دستور درون‌خطی، سپس override نشست، سپس پیش‌فرض برای هر عامل (`agents.list[].reasoningDefault`)، سپس بازگشت (`off`).
برچسب‌های استدلال مدل محلیِ بدشکل به‌صورت محافظه‌کارانه مدیریت می‌شوند. بلوک‌های بستهٔ `<think>...</think>` در پاسخ‌های عادی پنهان می‌مانند، و استدلال بسته‌نشده پس از متنِ از قبل قابل مشاهده نیز پنهان می‌شود. اگر پاسخی کاملاً در یک برچسب آغازینِ بسته‌نشدهٔ واحد پیچیده شده باشد و در غیر این صورت به‌عنوان متن خالی تحویل داده شود، OpenClaw برچسب آغازین بدشکل را حذف می‌کند و متن باقی‌مانده را تحویل می‌دهد.
تگ‌های استدلال مدل محلی بدشکل با احتیاط مدیریت می‌شوند. بلوک‌های بسته‌شده `<think>...</think>` در پاسخ‌های عادی پنهان می‌مانند، و استدلال بسته‌نشده پس از متن از قبل قابل مشاهده نیز پنهان می‌شود. اگر پاسخی کاملاً در یک تگ بازکننده بسته‌نشده واحد پیچیده شده باشد و در غیر این صورت به‌عنوان متن خالی تحویل داده شود، OpenClaw تگ بازکننده بدشکل را حذف می‌کند و متن باقی‌مانده را تحویل می‌دهد.
## مرتبط
- مستندات حالت ارتقایافته در [حالت ارتقایافته](/fa/tools/elevated) قرار دارد.
- مستندات حالت ارتقایافته در [حالت ارتقایافته](/fa/tools/elevated) قرار دارند.
## Heartbeatها
- بدنهٔ پروب Heartbeat همان پرامپت Heartbeat پیکربندی‌شده است (پیش‌فرض: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). دستورهای درون‌خطی در پیام Heartbeat طبق معمول اعمال می‌شوند (اما از تغییر پیش‌فرض‌های نشست از Heartbeatها خودداری کنید).
- تحویل Heartbeat به‌طور پیش‌فرض فقط شامل بار دادهٔ نهایی است. برای ارسال پیام جداگانهٔ `Reasoning:` نیز (در صورت وجود)، `agents.defaults.heartbeat.includeReasoning: true` یا مقدار هر عامل `agents.list[].heartbeat.includeReasoning: true` را تنظیم کنید.
- بدنه probe مربوط به Heartbeat همان prompt پیکربندی‌شده Heartbeat است (پیش‌فرض: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). دستورهای درون‌خطی در پیام Heartbeat طبق معمول اعمال می‌شوند (اما از تغییر پیش‌فرض‌های نشست از طریق Heartbeatها پرهیز کنید).
- تحویل Heartbeat به‌طور پیش‌فرض فقط به بار داده نهایی محدود است. برای ارسال پیام جداگانه `Reasoning:` نیز (در صورت وجود)، `agents.defaults.heartbeat.includeReasoning: true` یا `agents.list[].heartbeat.includeReasoning: true` برای هر عامل را تنظیم کنید.
## رابط کاربری چت وب
## UI چت وب
- انتخاب‌گر تفکر چت وب هنگام بارگذاری صفحه، سطح ذخیره‌شدهٔ نشست را از مخزن/پیکربندی نشست ورودی بازتاب می‌دهد.
- انتخاب سطحی دیگر، بازنویسی نشست را بلافاصله از طریق `sessions.patch` می‌نویسد؛ منتظر ارسال بعدی نمی‌ماند و یک بازنویسی یک‌بارهٔ `thinkingOnce` نیست.
- گزینهٔ اول همیشه `Default (<resolved level>)` است، که در آن پیش‌فرض حل‌شده از پروفایل تفکر ارائه‌دهندهٔ مدل نشست فعال به‌همراه همان منطق پشتیبانی‌ای می‌آید که `/status` و `session_status` استفاده می‌کنند.
- انتخاب‌گر از `thinkingLevels` برگشتی از ردیف/پیش‌فرض‌های نشست Gateway استفاده می‌کند، و `thinkingOptions` به‌عنوان فهرست برچسب قدیمی نگه داشته می‌شود. رابط کاربری مرورگر فهرست regex ارائه‌دهندهٔ خودش را نگه نمی‌دارد؛ Pluginها مالک مجموعه سطح‌های مختص مدل هستند.
- `/think:<level>` همچنان کار می‌کند و همان سطح نشست ذخیره‌شده را به‌روزرسانی می‌کند، بنابراین دستورهای چت و انتخاب‌گر همگام می‌مانند.
- انتخابگر تفکر چت وب هنگام بارگذاری صفحه، سطح ذخیره‌شده نشست را از store/پیکربندی نشست ورودی منعکس می‌کند.
- انتخاب سطح دیگر، override نشست را فوراً از طریق `sessions.patch` می‌نویسد؛ منتظر ارسال بعدی نمی‌ماند و override یک‌باره `thinkingOnce` نیست.
- گزینه اول همیشه `Default (<resolved level>)` است، که در آن پیش‌فرض حل‌شده از پروفایل تفکر ارائه‌دهنده مدل فعال نشست به‌علاوه همان منطق بازگشتی می‌آید که `/status` و `session_status` استفاده می‌کنند.
- انتخابگر از `thinkingLevels` برگشتی توسط ردیف/پیش‌فرض‌های نشست Gateway استفاده می‌کند، و `thinkingOptions` به‌عنوان فهرست برچسب legacy نگه داشته می‌شود. UI مرورگر فهرست regex ارائه‌دهنده مخصوص خود را نگه نمی‌دارد؛ Pluginها مالک مجموعه سطح‌های ویژه مدل هستند.
- `/think:<level>` همچنان کار می‌کند و همان سطح نشست ذخیره‌شده را به‌روزرسانی می‌کند، بنابراین دستورهای چت و انتخابگر همگام می‌مانند.
## پروفایل‌های ارائه‌دهنده
- Pluginهای ارائه‌دهنده می‌توانند `resolveThinkingProfile(ctx)` را در معرض دسترس قرار دهند تا سطوح پشتیبانی‌شده مدل و مقدار پیش‌فرض را تعریف کنند.
- Pluginهای ارائه‌دهنده‌ای که مدل‌های Claude را پروکسی می‌کنند باید از `resolveClaudeThinkingProfile(modelId)` از `openclaw/plugin-sdk/provider-model-shared` دوباره استفاده کنند تا کاتالوگ‌های مستقیم Anthropic و پروکسی هم‌تراز بمانند.
- هر سطح پروفایل یک `id` متعارف ذخیره‌شده دارد (`off`، `minimal`، `low`، `medium`، `high`، `xhigh`، `adaptive`، یا `max`) و می‌تواند یک `label` نمایشی داشته باشد. ارائه‌دهندگان دودویی از `{ id: "low", label: "on" }` استفاده می‌کنند.
- Pluginهای ابزار که نیاز دارند یک بازنویسی صریح تفکر را اعتبارسنجی کنند باید از `api.runtime.agent.resolveThinkingPolicy({ provider, model })` به‌همراه `api.runtime.agent.normalizeThinkingLevel(...)` استفاده کنند؛ آن‌ها نباید فهرست‌های سطح ارائه‌دهنده/مدل خودشان را نگه دارند.
- Pluginهای ابزار که به فراداده پیکربندی‌شده مدل سفارشی دسترسی دارند می‌توانند `catalog` را به `resolveThinkingPolicy` پاس بدهند تا opt-inهای `compat.supportedReasoningEfforts` در اعتبارسنجی سمت Plugin منعکس شوند.
- هوک‌های قدیمی منتشرشده (`supportsXHighThinking`، `isBinaryThinking`، و `resolveDefaultThinkingLevel`) به‌عنوان آداپترهای سازگاری باقی می‌مانند، اما مجموعه‌های سطح سفارشی جدید باید از `resolveThinkingProfile` استفاده کنند.
- ردیف‌ها/پیش‌فرض‌های Gateway، `thinkingLevels`، `thinkingOptions`، و `thinkingDefault` را در معرض دسترس قرار می‌دهند تا کلاینت‌های ACP/چت همان شناسه‌ها و برچسب‌های پروفایلی را رندر کنند که اعتبارسنجی زمان اجرا استفاده می‌کند.
- Plugin‌های ارائه‌دهنده می‌توانند `resolveThinkingProfile(ctx)` را ارائه کنند تا سطح‌های پشتیبانی‌شدهٔ مدل و مقدار پیش‌فرض را تعریف کنند.
- Plugin‌های ارائه‌دهنده‌ای که مدل‌های Claude را پراکسی می‌کنند باید از `resolveClaudeThinkingProfile(modelId)` از `openclaw/plugin-sdk/provider-model-shared` دوباره استفاده کنند تا کاتالوگ‌های مستقیم Anthropic و پراکسی هم‌تراز بمانند.
- هر سطح نمایه یک `id` کانونی ذخیره‌شده دارد (`off`، `minimal`، `low`، `medium`، `high`، `xhigh`، `adaptive` یا `max`) و ممکن است یک `label` نمایشی داشته باشد. ارائه‌دهنده‌های دودویی از `{ id: "low", label: "on" }` استفاده می‌کنند.
- Plugin‌های ابزار که باید یک بازنویسی صریح تفکر را اعتبارسنجی کنند، باید از `api.runtime.agent.resolveThinkingPolicy({ provider, model })` به‌همراه `api.runtime.agent.normalizeThinkingLevel(...)` استفاده کنند؛ آن‌ها نباید فهرست‌های سطح ارائه‌دهنده/مدل خودشان را نگه دارند.
- Plugin‌های ابزار که به فرادادهٔ پیکربندی‌شدهٔ مدل سفارشی دسترسی دارند، می‌توانند `catalog` را به `resolveThinkingPolicy` بدهند تا انتخاب‌های صریح `compat.supportedReasoningEfforts` در اعتبارسنجی سمت Plugin بازتاب داده شوند.
- هوک‌های قدیمی منتشرشده (`supportsXHighThinking`، `isBinaryThinking` و `resolveDefaultThinkingLevel`) به‌عنوان سازگارکننده‌های سازگاری باقی می‌مانند، اما مجموعه‌های سطح سفارشی جدید باید از `resolveThinkingProfile` استفاده کنند.
- ردیف‌ها/پیش‌فرض‌های Gateway، `thinkingLevels`، `thinkingOptions` و `thinkingDefault` را ارائه می‌کنند تا کلاینت‌های ACP/چت همان شناسه‌ها و برچسب‌های نمایه‌ای را رندر کنند که اعتبارسنجی زمان اجرا استفاده می‌کند.

368
docs/fa/tools/video-generation.md
View File

@ -4,21 +4,21 @@ read_when:
- پیکربندی ارائه‌دهندگان و مدل‌های تولید ویدئو
- درک پارامترهای ابزار video_generate
sidebarTitle: Video generation
summary: با استفاده از video_generate و بر پایه ارجاع‌های متنی، تصویری یا ویدیویی در 16 بک‌اند ارائه‌دهنده، ویدیو تولید کنید
summary: ویدیوها را از طریق video_generate، از مرجع‌های متنی، تصویری یا ویدیویی، در ۱۶ بک‌اند ارائه‌دهنده تولید کنید
title: تولید ویدئو
x-i18n:
generated_at: "2026-04-29T23:47:44Z"
generated_at: "2026-05-05T01:53:58Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
عامل‌های OpenClaw می‌توانند از اعلان‌های متنی، تصاویر مرجع، یا
ویدیوهای موجود ویدیو تولید کنند. شانزده پشتوانه ارائه‌دهنده پشتیبانی می‌شود که هرکدام
گزینه‌های مدل، حالت‌های ورودی، و مجموعه قابلیت‌های متفاوتی دارند. عامل
براساس پیکربندی شما و کلیدهای API موجود، ارائه‌دهنده مناسب را به‌صورت خودکار انتخاب می‌کند.
ویدیوهای موجود ویدیو تولید کنند. شانزده backend ارائه‌دهنده پشتیبانی می‌شوند که هرکدام
گزینه‌های مدل، حالت‌های ورودی، و مجموعه قابلیت‌های متفاوتی دارند. عامل بر اساس پیکربندی شما و کلیدهای API
در دسترس، ارائه‌دهنده مناسب را به‌طور خودکار انتخاب می‌کند.
<Note>
ابزار `video_generate` فقط زمانی ظاهر می‌شود که دست‌کم یک ارائه‌دهنده تولید ویدیو
@ -26,19 +26,19 @@ x-i18n:
کلید API ارائه‌دهنده تنظیم کنید یا `agents.defaults.videoGenerationModel` را پیکربندی کنید.
</Note>
OpenClaw تولید ویدیو را به‌عنوان سه حالت زمان اجرا در نظر می‌گیرد:
OpenClaw تولید ویدیو را به‌صورت سه حالت زمان اجرا در نظر می‌گیرد:
- `generate` — درخواست‌های متن به ویدیو بدون رسانه مرجع.
- `generate` — درخواست‌های متن‌به‌ویدیو بدون رسانه مرجع.
- `imageToVideo` — درخواست شامل یک یا چند تصویر مرجع است.
- `videoToVideo` — درخواست شامل یک یا چند ویدیوی مرجع است.
ارائه‌دهندگان می‌توانند هر زیرمجموعه‌ای از این حالت‌ها را پشتیبانی کنند. ابزار، حالت
ارائه‌دهندگان می‌توانند هر زیرمجموعه‌ای از این حالت‌ها را پشتیبانی کنند. ابزار حالت
فعال را پیش از ارسال اعتبارسنجی می‌کند و حالت‌های پشتیبانی‌شده را در `action=list` گزارش می‌دهد.
## شروع سریع
<Steps>
<Step title="پیکربندی احراز هویت">
<Step title="Configure auth">
برای هر ارائه‌دهنده پشتیبانی‌شده یک کلید API تنظیم کنید:
```bash
@ -46,15 +46,15 @@ OpenClaw تولید ویدیو را به‌عنوان سه حالت زمان ا
```
</Step>
<Step title="انتخاب مدل پیش‌فرض (اختیاری)">
<Step title="Pick a default model (optional)">
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
</Step>
<Step title="درخواست از عامل">
<Step title="Ask the agent">
> یک ویدیوی سینمایی ۵ ثانیه‌ای از یک خرچنگ دریایی دوستانه که هنگام غروب موج‌سواری می‌کند تولید کن.
عامل `video_generate` را به‌صورت خودکار فراخوانی می‌کند. نیازی به allowlist کردن
عامل به‌طور خودکار `video_generate` را فراخوانی می‌کند. نیازی به allowlist کردن
ابزار نیست.
</Step>
@ -62,36 +62,39 @@ OpenClaw تولید ویدیو را به‌عنوان سه حالت زمان ا
## تولید ناهمگام چگونه کار می‌کند
تولید ویدیو ناهمگام است. وقتی عامل `video_generate` را در یک
جلسه فراخوانی می‌کند:
تولید ویدیو ناهمگام است. وقتی عامل در یک
نشست `video_generate` را فراخوانی می‌کند:
1. OpenClaw درخواست را به ارائه‌دهنده ارسال می‌کند و بلافاصله یک شناسه کار برمی‌گرداند.
2. ارائه‌دهنده کار را در پس‌زمینه پردازش می‌کند (معمولا ۳۰ ثانیه تا ۵ دقیقه، بسته به ارائه‌دهنده و وضوح).
3. وقتی ویدیو آماده شد، OpenClaw همان جلسه را با یک رویداد تکمیل داخلی بیدار می‌کند.
4. عامل ویدیوی نهایی را به گفتگوی اصلی برمی‌گرداند.
1. OpenClaw درخواست را به ارائه‌دهنده ارسال می‌کند و بلافاصله یک شناسه وظیفه برمی‌گرداند.
2. ارائه‌دهنده کار را در پس‌زمینه پردازش می‌کند (معمولا بسته به ارائه‌دهنده و وضوح، ۳۰ ثانیه تا ۵ دقیقه).
3. وقتی ویدیو آماده شد، OpenClaw همان نشست را با یک رویداد تکمیل داخلی بیدار می‌کند.
4. عامل به کاربر اطلاع می‌دهد و ویدیوی نهایی را پیوست می‌کند. در گفت‌وگوهای گروهی/کانالی
که از تحویل قابل مشاهده فقط از طریق ابزار پیام استفاده می‌کنند، عامل نتیجه را
به‌جای اینکه OpenClaw آن را مستقیم ارسال کند، از طریق ابزار پیام بازپخش می‌کند.
تا زمانی که یک کار در حال انجام است، فراخوانی‌های تکراری `video_generate` در همان
جلسه به‌جای شروع تولیدی دیگر، وضعیت کار فعلی را برمی‌گردانند. برای
بررسی پیشرفت از CLI، از `openclaw tasks list` یا `openclaw tasks show <taskId>` استفاده کنید.
تا وقتی کاری در جریان است، فراخوانی‌های تکراری `video_generate` در همان
نشست به‌جای شروع یک تولید دیگر، وضعیت وظیفه فعلی را برمی‌گردانند. برای
بررسی پیشرفت از CLI از `openclaw tasks list` یا `openclaw tasks show <taskId>` استفاده کنید.
بیرون از اجراهای عامل دارای پشتوانه جلسه (برای مثال، فراخوانی مستقیم ابزار)،
ابزار به تولید درون‌خطی برمی‌گردد و مسیر رسانه نهایی را
خارج از اجراهای عاملِ دارای پشتوانه نشست (برای مثال، فراخوانی مستقیم ابزار)،
ابزار به تولید inline بازمی‌گردد و مسیر رسانه نهایی را
در همان نوبت برمی‌گرداند.
وقتی ارائه‌دهنده بایت برمی‌گرداند، فایل‌های ویدیوی تولیدشده در فضای ذخیره‌سازی رسانه‌ای مدیریت‌شده توسط OpenClaw ذخیره می‌شوند. سقف ذخیره پیش‌فرض ویدیوی تولیدشده از
محدودیت رسانه ویدیو پیروی می‌کند، و `agents.defaults.mediaMaxMb` آن را برای
رندرهای بزرگ‌تر افزایش می‌دهد. وقتی ارائه‌دهنده همچنین یک URL خروجی میزبانی‌شده برمی‌گرداند، OpenClaw
می‌تواند به‌جای ناموفق کردن کار در صورت رد شدن فایل بزرگ‌تر از حد توسط نگهداری محلی،
وقتی ارائه‌دهنده byte برمی‌گرداند، فایل‌های ویدیوی تولیدشده در فضای ذخیره‌سازی رسانه مدیریت‌شده توسط OpenClaw
ذخیره می‌شوند. سقف پیش‌فرض ذخیره ویدیوی تولیدشده از
محدودیت رسانه ویدیویی پیروی می‌کند، و `agents.defaults.mediaMaxMb` آن را برای
رندرهای بزرگ‌تر افزایش می‌دهد. وقتی ارائه‌دهنده یک URL خروجی میزبانی‌شده نیز برمی‌گرداند، OpenClaw
می‌تواند اگر پایداری محلی یک فایل بیش‌ازحد بزرگ را رد کند، به‌جای ناموفق کردن وظیفه
آن URL را تحویل دهد.
### چرخه عمر کار
### چرخه حیات وظیفه
| وضعیت | معنی |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | کار ایجاد شده و منتظر است تا ارائه‌دهنده آن را بپذیرد. |
| `running` | ارائه‌دهنده در حال پردازش است (معمولا ۳۰ ثانیه تا ۵ دقیقه، بسته به ارائه‌دهنده و وضوح). |
| `succeeded` | ویدیو آماده است؛ عامل بیدار می‌شود و آن را در گفتگو ارسال می‌کند. |
| `failed` | خطای ارائه‌دهنده یا پایان مهلت؛ عامل با جزئیات خطا بیدار می‌شود. |
| `queued` | وظیفه ایجاد شده و منتظر پذیرش توسط ارائه‌دهنده است. |
| `running` | ارائه‌دهنده در حال پردازش است (معمولا بسته به ارائه‌دهنده و وضوح، ۳۰ ثانیه تا ۵ دقیقه). |
| `succeeded` | ویدیو آماده است؛ عامل بیدار می‌شود و آن را در گفت‌وگو ارسال می‌کند. |
| `failed` | خطای ارائه‌دهنده یا timeout؛ عامل با جزئیات خطا بیدار می‌شود. |
وضعیت را از CLI بررسی کنید:
@ -101,189 +104,190 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
اگر یک کار ویدیو برای جلسه فعلی از قبل `queued` یا `running` باشد،
`video_generate` به‌جای شروع یک کار جدید، وضعیت کار موجود را برمی‌گرداند.
برای بررسی صریح بدون راه‌اندازی تولید جدید، از `action: "status"` استفاده کنید.
اگر یک وظیفه ویدیو برای نشست فعلی از قبل `queued` یا `running` باشد،
`video_generate` به‌جای شروع یک مورد جدید، وضعیت وظیفه موجود را برمی‌گرداند.
برای بررسی صریح بدون راه‌اندازی تولید جدید از `action: "status"` استفاده کنید.
## ارائه‌دهندگان پشتیبانی‌شده
| ارائه‌دهنده | مدل پیش‌فرض | متن | مرجع تصویر | مرجع ویدیو | احراز هویت |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | بله (URL راه دور) | بله (URL راه دور) | `MODELSTUDIO_API_KEY` |
| Alibaba | `wan2.6-t2v` | ✓ | بله (URL راه‌دور) | بله (URL راه‌دور) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | تا ۲ تصویر (فقط مدل‌های I2V؛ فریم اول + آخر) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | تا ۲ تصویر (فریم اول + آخر از طریق نقش) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | تا ۲ تصویر (فریم اول + آخر از طریق role) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | تا ۹ تصویر مرجع | تا ۳ ویدیو | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | ۱ تصویر | — | `COMFY_API_KEY` یا `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | ۱ تصویر؛ تا ۹ تصویر با Seedance reference-to-video | تا ۳ ویدیو با Seedance reference-to-video | `FAL_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | ۱ تصویر؛ تا ۹ مورد با Seedance reference-to-video | تا ۳ ویدیو با Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | ۱ تصویر | ۱ ویدیو | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | ۱ تصویر | — | `MINIMAX_API_KEY` یا MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | ۱ تصویر | ۱ ویدیو | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | تا ۴ تصویر (فریم اول/آخر یا مراجع) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | بله (URL راه دور) | بله (URL راه دور) | `QWEN_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | بله (URL راه‌دور) | بله (URL راه‌دور) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | ۱ تصویر | ۱ ویدیو | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | ۱ تصویر | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | ۱ تصویر (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | ۱ تصویر فریم اول یا تا ۷ `reference_image` | ۱ ویدیو | `XAI_API_KEY` |
برخی ارائه‌دهندگان متغیرهای محیطی کلید API اضافی یا جایگزین را می‌پذیرند. برای جزئیات، به
[صفحه‌های ارائه‌دهنده](#related) مربوطه مراجعه کنید.
برخی ارائه‌دهندگان متغیرهای env کلید API اضافی یا جایگزین می‌پذیرند. برای جزئیات،
[صفحه‌های ارائه‌دهنده](#related) جداگانه را ببینید.
برای بررسی ارائه‌دهندگان، مدل‌ها و حالت‌های زمان اجرای موجود در زمان اجرا، `video_generate action=list` را اجرا کنید.
برای بررسی ارائه‌دهندگان، مدل‌ها، و حالت‌های زمان اجرای در دسترس در زمان اجرا، `video_generate action=list` را اجرا کنید.
### ماتریس قابلیت‌ها
قرارداد حالت صریحی که توسط `video_generate`، آزمون‌های قرارداد، و
پیمایش live مشترک استفاده می‌شود:
sweep زنده مشترک استفاده می‌شود:
| ارائه‌دهنده | `generate` | `imageToVideo` | `videoToVideo` | مسیرهای live مشترک امروز |
| ارائه‌دهنده | `generate` | `imageToVideo` | `videoToVideo` | laneهای زنده مشترک امروز |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` نادیده گرفته می‌شود چون این ارائه‌دهنده به URLهای ویدیوی راه دور `http(s)` نیاز دارد |
| Alibaba | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` رد می‌شود چون این ارائه‌دهنده به URLهای ویدیویی راه‌دور `http(s)` نیاز دارد |
| BytePlus | ✓ | ✓ | — | `generate`، `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | در پیمایش مشترک نیست؛ پوشش اختصاصی workflow همراه آزمون‌های Comfy قرار دارد |
| DeepInfra | ✓ | — | — | `generate`؛ طرحواره‌های ویدیوی بومی DeepInfra در قرارداد همراه‌شده متن به ویدیو هستند |
| ComfyUI | ✓ | ✓ | — | در sweep مشترک نیست؛ پوشش اختصاصی workflow همراه با آزمون‌های Comfy قرار دارد |
| DeepInfra | ✓ | — | — | `generate`؛ schemaهای ویدیویی بومی DeepInfra در قرارداد bundled متن‌به‌ویدیو هستند |
| fal | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` فقط هنگام استفاده از Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` مشترک نادیده گرفته می‌شود چون پیمایش Gemini/Veo فعلی با پشتوانه بافر آن ورودی را نمی‌پذیرد |
| Google | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` مشترک رد می‌شود چون sweep فعلی Gemini/Veo با پشتوانه buffer آن ورودی را نمی‌پذیرد |
| MiniMax | ✓ | ✓ | — | `generate`، `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` مشترک نادیده گرفته می‌شود چون این سازمان/مسیر ورودی در حال حاضر به دسترسی inpaint/remix سمت ارائه‌دهنده نیاز دارد |
| OpenAI | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` مشترک رد می‌شود چون این org/مسیر ورودی در حال حاضر به دسترسی inpaint/remix سمت ارائه‌دهنده نیاز دارد |
| OpenRouter | ✓ | ✓ | — | `generate`، `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` نادیده گرفته می‌شود چون این ارائه‌دهنده به URLهای ویدیوی راه دور `http(s)` نیاز دارد |
| Runway | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` فقط وقتی اجرا می‌شود که مدل انتخاب‌شده `runway/gen4_aleph` باشد |
| Qwen | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` رد می‌شود چون این ارائه‌دهنده به URLهای ویدیویی راه‌دور `http(s)` نیاز دارد |
| Runway | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` فقط زمانی اجرا می‌شود که مدل انتخاب‌شده `runway/gen4_aleph` باشد |
| Together | ✓ | ✓ | — | `generate`، `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`؛ `imageToVideo` مشترک نادیده گرفته می‌شود چون `veo3` همراه‌شده فقط متنی است و `kling` همراه‌شده به URL تصویر راه دور نیاز دارد |
| xAI | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` نادیده گرفته می‌شود چون این ارائه‌دهنده در حال حاضر به یک URL راه دور MP4 نیاز دارد |
| Vydra | ✓ | ✓ | — | `generate`؛ `imageToVideo` مشترک رد می‌شود چون `veo3` bundled فقط متنی است و `kling` bundled به URL تصویر راه‌دور نیاز دارد |
| xAI | ✓ | ✓ | ✓ | `generate`، `imageToVideo`؛ `videoToVideo` رد می‌شود چون این ارائه‌دهنده در حال حاضر به URL راه‌دور MP4 نیاز دارد |
## پارامترهای ابزار
### الزامی
### ضروری
<ParamField path="prompt" type="string" required>
توصیف متنی ویدیویی که باید تولید شود. برای `action: "generate"` الزامی است.
توضیح متنی ویدیویی که باید تولید شود. برای `action: "generate"` ضروری است.
</ParamField>
### ورودی‌های محتوا
<ParamField path="image" type="string">یک تصویر مرجع (مسیر یا URL).</ParamField>
<ParamField path="images" type="string[]">چند تصویر مرجع (تا 9 مورد).</ParamField>
<ParamField path="images" type="string[]">چند تصویر مرجع (تا ۹ مورد).</ParamField>
<ParamField path="imageRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، موازی با فهرست ترکیبی تصاویر.
مقادیر استاندارد: `first_frame`، `last_frame`، `reference_image`.
راهنمای نقش اختیاری برای هر جایگاه، متناظر با فهرست ترکیبی تصاویر.
مقادیر متعارف: `first_frame`، `last_frame`، `reference_image`.
</ParamField>
<ParamField path="video" type="string">یک ویدیوی مرجع (مسیر یا URL).</ParamField>
<ParamField path="videos" type="string[]">چند ویدیوی مرجع (تا 4 مورد).</ParamField>
<ParamField path="video" type="string">یک ویدئوی مرجع (مسیر یا URL).</ParamField>
<ParamField path="videos" type="string[]">چند ویدئوی مرجع (تا ۴ مورد).</ParamField>
<ParamField path="videoRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، موازی با فهرست ترکیبی ویدیوها.
مقدار استاندارد: `reference_video`.
راهنمای نقش اختیاری برای هر جایگاه، متناظر با فهرست ترکیبی ویدئوها.
مقدار متعارف: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
یک صدای مرجع (مسیر یا URL). وقتی ارائه‌دهنده از ورودی‌های صوتی پشتیبانی کند،
برای موسیقی پس‌زمینه یا مرجع صدا استفاده می‌شود.
یک صدای مرجع (مسیر یا URL). برای موسیقی پس‌زمینه یا مرجع صدا استفاده می‌شود
وقتی ارائه‌دهنده از ورودی‌های صوتی پشتیبانی کند.
</ParamField>
<ParamField path="audioRefs" type="string[]">چند صدای مرجع (تا 3 مورد).</ParamField>
<ParamField path="audioRefs" type="string[]">چند صدای مرجع (تا ۳ مورد).</ParamField>
<ParamField path="audioRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، موازی با فهرست ترکیبی صداها.
مقدار استاندارد: `reference_audio`.
راهنمای نقش اختیاری برای هر جایگاه، متناظر با فهرست ترکیبی صداها.
مقدار متعارف: `reference_audio`.
</ParamField>
<Note>
راهنمای نقش‌ها همان‌طور که هستند به ارائه‌دهنده ارسال می‌شوند. مقادیر استاندارد از
اتحاد `VideoGenerationAssetRole` می‌آیند، اما ارائه‌دهنده‌ها ممکن است رشته‌های نقش
اضافی را هم بپذیرند. آرایه‌های `*Roles` نباید ورودی‌های بیشتری از فهرست مرجع
متناظر داشته باشند؛ خطاهای یک‌واحدی با خطایی روشن شکست می‌خورند.
برای خالی گذاشتن یک جایگاه از رشتهٔ خالی استفاده کنید. برای xAI، نقش همهٔ تصاویر را روی
`reference_image` بگذارید تا از حالت تولید `reference_images` آن استفاده شود؛ برای
تبدیل تصویر به ویدیو با یک تصویر، نقش را حذف کنید یا از `first_frame` استفاده کنید.
راهنماهای نقش همان‌طور که هستند به ارائه‌دهنده ارسال می‌شوند. مقادیر متعارف از
اتحاد `VideoGenerationAssetRole` می‌آیند، اما ارائه‌دهندگان ممکن است رشته‌های نقش
اضافی را بپذیرند. آرایه‌های `*Roles` نباید تعداد ورودی بیشتری از فهرست مرجع
متناظر داشته باشند؛ خطاهای یکی بیشتر یا کمتر با خطایی روشن شکست می‌خورند.
برای تنظیم‌نشدن یک جایگاه، از رشته خالی استفاده کنید. برای xAI، همه نقش‌های تصویر را روی
`reference_image` تنظیم کنید تا از حالت تولید `reference_images` آن استفاده شود؛
برای تصویر-به-ویدئو تک‌تصویری، نقش را حذف کنید یا از `first_frame` استفاده کنید.
</Note>
### کنترل‌های سبک
<ParamField path="aspectRatio" type="string">
`1:1`، `2:3`، `3:2`، `3:4`، `4:3`، `4:5`، `5:4`، `9:16`، `16:9`، `21:9` یا `adaptive`.
`1:1`، `2:3`، `3:2`، `3:4`، `4:3`، `4:5`، `5:4`، `9:16`، `16:9`، `21:9`، یا `adaptive`.
</ParamField>
<ParamField path="resolution" type="string">`480P`، `720P`، `768P` یا `1080P`.</ParamField>
<ParamField path="resolution" type="string">`480P`، `720P`، `768P`، یا `1080P`.</ParamField>
<ParamField path="durationSeconds" type="number">
مدت هدف بر حسب ثانیه (گردشده به نزدیک‌ترین مقدار پشتیبانی‌شده توسط ارائه‌دهنده).
مدت‌زمان هدف بر حسب ثانیه (گردشده به نزدیک‌ترین مقدار پشتیبانی‌شده توسط ارائه‌دهنده).
</ParamField>
<ParamField path="size" type="string">راهنمای اندازه وقتی ارائه‌دهنده از آن پشتیبانی کند.</ParamField>
<ParamField path="size" type="string">راهنمای اندازه، وقتی ارائه‌دهنده از آن پشتیبانی کند.</ParamField>
<ParamField path="audio" type="boolean">
در صورت پشتیبانی، صدای تولیدشده را در خروجی فعال کنید. از `audioRef*` (ورودی‌ها) جدا است.
وقتی پشتیبانی شود، صدای تولیدشده را در خروجی فعال می‌کند. متمایز از `audioRef*` (ورودی‌ها).
</ParamField>
<ParamField path="watermark" type="boolean">در صورت پشتیبانی، واترمارک ارائه‌دهنده را روشن یا خاموش کنید.</ParamField>
<ParamField path="watermark" type="boolean">وقتی پشتیبانی شود، واترمارک‌گذاری ارائه‌دهنده را تغییر می‌دهد.</ParamField>
`adaptive` یک نشانگر ویژهٔ وابسته به ارائه‌دهنده است: همان‌طور که هست به
ارائه‌دهنده‌هایی ارسال می‌شود که `adaptive` را در قابلیت‌های خود اعلام کرده‌اند
(مثلاً BytePlus Seedance از آن برای تشخیص خودکار نسبت از ابعاد تصویر ورودی استفاده می‌کند).
ارائه‌دهنده‌هایی که آن را اعلام نکرده‌اند، مقدار را در نتیجهٔ ابزار از طریق
`details.ignoredOverrides` نمایش می‌دهند تا کنارگذاشته‌شدن آن قابل مشاهده باشد.
`adaptive` یک نگهبان ویژه ارائه‌دهنده است: همان‌طور که هست به
ارائه‌دهندگانی ارسال می‌شود که `adaptive` را در قابلیت‌های خود اعلام کرده‌اند (مثلاً BytePlus
Seedance از آن برای تشخیص خودکار نسبت از ابعاد تصویر ورودی
استفاده می‌کند). ارائه‌دهندگانی که آن را اعلام نکرده‌اند، مقدار را از طریق
`details.ignoredOverrides` در نتیجه ابزار نشان می‌دهند تا حذف آن قابل مشاهده باشد.
### پیشرفته
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` وظیفهٔ فعلی جلسه را برمی‌گرداند؛ `"list"` ارائه‌دهنده‌ها را بررسی می‌کند.
`"status"` وظیفه فعلی نشست را برمی‌گرداند؛ `"list"` ارائه‌دهندگان را بررسی می‌کند.
</ParamField>
<ParamField path="model" type="string">بازنویسی ارائه‌دهنده/مدل (مثلاً `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">راهنمای نام فایل خروجی.</ParamField>
<ParamField path="timeoutMs" type="number">مهلت زمانی اختیاری درخواست ارائه‌دهنده بر حسب میلی‌ثانیه.</ParamField>
<ParamField path="timeoutMs" type="number">مهلت اختیاری درخواست ارائه‌دهنده بر حسب میلی‌ثانیه.</ParamField>
<ParamField path="providerOptions" type="object">
گزینه‌های ویژهٔ ارائه‌دهنده به‌صورت یک شیء JSON (مثلاً `{"seed": 42, "draft": true}`).
ارائه‌دهنده‌هایی که شِمای نوع‌دار اعلام می‌کنند، کلیدها و نوع‌ها را اعتبارسنجی می‌کنند؛
کلیدهای ناشناخته یا ناهماهنگی‌ها باعث می‌شوند نامزد هنگام fallback رد شود. ارائه‌دهنده‌های بدون
شِمای اعلام‌شده، گزینه‌ها را همان‌طور که هستند دریافت می‌کنند. برای دیدن اینکه هر ارائه‌دهنده چه چیزهایی را می‌پذیرد،
`video_generate action=list` را اجرا کنید.
گزینه‌های ویژه ارائه‌دهنده به‌صورت شیء JSON (مثلاً `{"seed": 42, "draft": true}`).
ارائه‌دهندگانی که یک اسکیمای تایپ‌شده اعلام می‌کنند، کلیدها و نوع‌ها را اعتبارسنجی می‌کنند؛ کلیدهای
ناشناخته یا عدم تطابق‌ها نامزد را هنگام fallback کنار می‌گذارند. ارائه‌دهندگان بدون
اسکیمای اعلام‌شده، گزینه‌ها را همان‌طور که هستند دریافت می‌کنند. `video_generate action=list` را اجرا کنید
تا ببینید هر ارائه‌دهنده چه چیزهایی را می‌پذیرد.
</ParamField>
<Note>
همهٔ ارائه‌دهنده‌ها از همهٔ پارامترها پشتیبانی نمی‌کنند. OpenClaw مدت را به
همه ارائه‌دهندگان از همه پارامترها پشتیبانی نمی‌کنند. OpenClaw مدت‌زمان را به
نزدیک‌ترین مقدار پشتیبانی‌شده توسط ارائه‌دهنده نرمال‌سازی می‌کند، و راهنماهای هندسی ترجمه‌شده
مانند اندازه به نسبت تصویر را، وقتی یک ارائه‌دهندهٔ fallback سطح کنترل متفاوتی ارائه می‌کند،
بازنگاشت می‌کند. بازنویسی‌های واقعاً پشتیبانی‌نشده به‌صورت best-effort نادیده گرفته می‌شوند
و در نتیجهٔ ابزار به‌عنوان هشدار گزارش می‌شوند. محدودیت‌های سخت قابلیت
مانند اندازه-به-نسبت-تصویر را وقتی ارائه‌دهنده fallback سطح کنترل متفاوتی ارائه دهد
بازنگاشت می‌کند. بازنویسی‌های واقعاً پشتیبانی‌نشده بر اساس بهترین تلاش
نادیده گرفته می‌شوند و به‌صورت هشدار در نتیجه ابزار گزارش می‌شوند. محدودیت‌های سخت قابلیت
(مانند تعداد بیش از حد ورودی‌های مرجع) پیش از ارسال شکست می‌خورند. نتایج ابزار
تنظیمات اعمال‌شده را گزارش می‌کنند؛ `details.normalization` هر ترجمهٔ
درخواست‌شده به اعمال‌شده را ثبت می‌کند.
تنظیمات اعمال‌شده را گزارش می‌کنند؛ `details.normalization` هر ترجمه
درخواستی-به-اعمال‌شده را ثبت می‌کند.
</Note>
ورودی‌های مرجع حالت زمان اجرا را انتخاب می‌کنند:
- بدون رسانهٔ مرجع → `generate`
- هر مرجع تصویری → `imageToVideo`
- هر مرجع ویدیویی → `videoToVideo`
- ورودی‌های صدای مرجع حالت حل‌شده را **تغییر نمی‌دهند**؛ آن‌ها روی
هر حالتی که مراجع تصویر/ویدیو انتخاب کرده‌اند اعمال می‌شوند، و فقط با
ارائه‌دهنده‌هایی کار می‌کنند که `maxInputAudios` را اعلام کرده‌اند.
- بدون رسانه مرجع → `generate`
- هر مرجع تصویر → `imageToVideo`
- هر مرجع ویدئو → `videoToVideo`
- ورودی‌های صدای مرجع **حالت حل‌شده را تغییر نمی‌دهند**؛ آن‌ها روی
هر حالتی که مراجع تصویر/ویدئو انتخاب کنند اعمال می‌شوند، و فقط با
ارائه‌دهندگانی کار می‌کنند که `maxInputAudios` را اعلام کرده‌اند.
ترکیب مراجع تصویر و ویدیو سطح قابلیت مشترک پایداری نیست.
ترکیب مراجع تصویر و ویدئو یک سطح قابلیت مشترک پایدار نیست.
در هر درخواست، یک نوع مرجع را ترجیح دهید.
#### Fallback و گزینه‌های نوع‌دار
#### fallback و گزینه‌های تایپ‌شده
برخی بررسی‌های قابلیت به‌جای مرز ابزار در لایهٔ fallback اعمال می‌شوند،
بنابراین درخواستی که از محدودیت‌های ارائه‌دهندهٔ اصلی فراتر می‌رود همچنان می‌تواند
روی یک fallback توانمند اجرا شود:
برخی بررسی‌های قابلیت در لایه fallback اعمال می‌شوند، نه در
مرز ابزار؛ بنابراین درخواستی که از محدودیت‌های ارائه‌دهنده اصلی فراتر می‌رود
هنوز می‌تواند روی یک fallback توانمند اجرا شود:
- نامزد فعالی که هیچ `maxInputAudios` اعلام نکرده است (یا `0` اعلام کرده) وقتی
درخواست شامل مراجع صوتی باشد رد می‌شود؛ نامزد بعدی امتحان می‌شود.
- نامزد فعالی که هیچ `maxInputAudios` اعلام نکرده (یا `0`) وقتی
درخواست شامل مراجع صوتی باشد کنار گذاشته می‌شود؛ نامزد بعدی امتحان می‌شود.
- `maxDurationSeconds` نامزد فعال کمتر از `durationSeconds` درخواستی باشد
و هیچ فهرست `supportedDurationSeconds` اعلام‌شده‌ای نداشته باشد → رد می‌شود.
- درخواست شامل `providerOptions` است و نامزد فعال صراحتاً یک شِمای نوع‌دار
`providerOptions` اعلام کرده است → اگر کلیدهای ارائه‌شده در شِما نباشند
یا نوع مقدارها مطابقت نداشته باشند، رد می‌شود. ارائه‌دهنده‌های بدون شِمای
اعلام‌شده گزینه‌ها را همان‌طور که هستند دریافت می‌کنند (عبور سازگار با نسخه‌های قبلی).
یک ارائه‌دهنده می‌تواند با اعلام یک شِمای خالی (`capabilities.providerOptions: {}`)
از همهٔ گزینه‌های ارائه‌دهنده انصراف دهد، که همان ردشدن ناشی از ناهماهنگی نوع را ایجاد می‌کند.
و هیچ فهرست `supportedDurationSeconds` اعلام‌شده‌ای نداشته باشد → کنار گذاشته می‌شود.
- درخواست شامل `providerOptions` است و نامزد فعال به‌صراحت
اسکیمای تایپ‌شده `providerOptions` را اعلام می‌کند → اگر کلیدهای ارائه‌شده
در اسکیما نباشند یا نوع مقدارها مطابقت نداشته باشند، کنار گذاشته می‌شود. ارائه‌دهندگان بدون
اسکیمای اعلام‌شده گزینه‌ها را همان‌طور که هستند دریافت می‌کنند (عبور سازگار با گذشته).
یک ارائه‌دهنده می‌تواند با اعلام اسکیمای خالی (`capabilities.providerOptions: {}`)
از همه گزینه‌های ارائه‌دهنده انصراف دهد، که همان کنارگذاری ناشی از عدم تطابق نوع را
ایجاد می‌کند.
اولین دلیل رد در یک درخواست با سطح `warn` ثبت می‌شود تا اپراتورها ببینند چه زمانی
ارائه‌دهندهٔ اصلی آن‌ها کنار گذاشته شده است؛ ردهای بعدی با سطح `debug` ثبت می‌شوند تا
زنجیره‌های طولانی fallback کم‌صدا بمانند. اگر همهٔ نامزدها رد شوند،
خطای تجمیع‌شده دلیل رد هرکدام را شامل می‌شود.
اولین دلیل کنارگذاری در یک درخواست در سطح `warn` ثبت می‌شود تا اپراتورها ببینند
چه زمانی ارائه‌دهنده اصلی آن‌ها کنار گذاشته شده است؛ کنارگذاری‌های بعدی در سطح `debug` ثبت می‌شوند تا
زنجیره‌های طولانی fallback ساکت بمانند. اگر همه نامزدها کنار گذاشته شوند، خطای
تجمیع‌شده دلیل کنارگذاری هرکدام را شامل می‌شود.
## کنش‌ها
| کنش | کاری که انجام می‌دهد |
| کنش | کاری که انجام می‌دهد |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | پیش‌فرض. یک ویدیو از prompt داده‌شده و ورودی‌های مرجع اختیاری می‌سازد. |
| `status` | وضعیت وظیفهٔ ویدیویی در حال اجرا برای جلسهٔ فعلی را بدون شروع یک تولید دیگر بررسی می‌کند. |
| `list` | ارائه‌دهنده‌ها، مدل‌ها و قابلیت‌های موجودشان را نشان می‌دهد. |
| `generate` | پیش‌فرض. از پرامپت داده‌شده و ورودی‌های مرجع اختیاری یک ویدئو ایجاد می‌کند. |
| `status` | وضعیت وظیفه ویدئوی در حال اجرا را برای نشست فعلی، بدون شروع تولیدی دیگر، بررسی می‌کند. |
| `list` | ارائه‌دهندگان، مدل‌ها، و قابلیت‌های موجود آن‌ها را نشان می‌دهد. |
## انتخاب مدل
@ -291,15 +295,14 @@ OpenClaw مدل را به این ترتیب حل می‌کند:
1. **پارامتر ابزار `model`** — اگر عامل یکی را در فراخوانی مشخص کند.
2. **`videoGenerationModel.primary`** از پیکربندی.
3. **`videoGenerationModel.fallbacks`** به ترتیب.
4. **تشخیص خودکار** — ارائه‌دهنده‌هایی که احراز هویت معتبر دارند، از
ارائه‌دهندهٔ پیش‌فرض فعلی شروع می‌شوند و سپس ارائه‌دهنده‌های باقی‌مانده به ترتیب
الفبایی بررسی می‌شوند.
3. **`videoGenerationModel.fallbacks`** به‌ترتیب.
4. **تشخیص خودکار** — ارائه‌دهندگانی که احراز هویت معتبر دارند، با شروع از
ارائه‌دهنده پیش‌فرض فعلی، سپس ارائه‌دهندگان باقی‌مانده به‌ترتیب الفبایی.
اگر یک ارائه‌دهنده شکست بخورد، نامزد بعدی به‌صورت خودکار امتحان می‌شود. اگر همهٔ
اگر یک ارائه‌دهنده شکست بخورد، نامزد بعدی به‌صورت خودکار امتحان می‌شود. اگر همه
نامزدها شکست بخورند، خطا جزئیات هر تلاش را شامل می‌شود.
برای استفاده فقط از ورودی‌های صریح `model`، `primary` و `fallbacks`،
برای استفاده فقط از ورودی‌های صریح `model`، `primary`، و `fallbacks`،
`agents.defaults.mediaGenerationAutoProviderFallback: false` را تنظیم کنید.
```json5
@ -319,11 +322,11 @@ OpenClaw مدل را به این ترتیب حل می‌کند:
<AccordionGroup>
<Accordion title="Alibaba">
از نقطهٔ پایانی ناهمگام DashScope / Model Studio استفاده می‌کند. تصاویر و
ویدیوهای مرجع باید URLهای راه‌دور `http(s)` باشند.
از نقطه پایانی ناهمگام DashScope / Model Studio استفاده می‌کند. تصاویر و
ویدئوهای مرجع باید URLهای راه‌دور `http(s)` باشند.
</Accordion>
<Accordion title="BytePlus (1.0)">
شناسهٔ ارائه‌دهنده: `byteplus`.
شناسه ارائه‌دهنده: `byteplus`.
مدل‌ها: `seedance-1-0-pro-250528` (پیش‌فرض)،
`seedance-1-0-pro-t2v-250528`، `seedance-1-0-pro-fast-251015`،
@ -332,22 +335,21 @@ OpenClaw مدل را به این ترتیب حل می‌کند:
مدل‌های T2V (`*-t2v-*`) ورودی تصویر را نمی‌پذیرند؛ مدل‌های I2V و
مدل‌های عمومی `*-pro-*` از یک تصویر مرجع (فریم اول) پشتیبانی می‌کنند.
تصویر را به‌صورت موقعیتی ارسال کنید یا `role: "first_frame"` را تنظیم کنید.
وقتی تصویری ارائه شود، شناسه‌های مدل T2V به‌صورت خودکار به گونهٔ متناظر I2V
تغییر داده می‌شوند.
وقتی تصویری ارائه شود، شناسه‌های مدل T2V به‌صورت خودکار به
گونه I2V متناظر تغییر داده می‌شوند.
کلیدهای پشتیبانی‌شدهٔ `providerOptions`: `seed` (عدد)، `draft` (بولی —
کلیدهای پشتیبانی‌شده `providerOptions`: `seed` (عدد)، `draft` (بولی —
اجبار به 480p)، `camera_fixed` (بولی).
</Accordion>
<Accordion title="BytePlus Seedance 1.5">
به Plugin
[`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
نیاز دارد. شناسهٔ ارائه‌دهنده: `byteplus-seedance15`. مدل:
به Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
نیاز دارد. شناسه ارائه‌دهنده: `byteplus-seedance15`. مدل:
`seedance-1-5-pro-251215`.
از API یکپارچهٔ `content[]` استفاده می‌کند. حداکثر از 2 تصویر ورودی
(`first_frame` + `last_frame`) پشتیبانی می‌کند. همهٔ ورودی‌ها باید URLهای راه‌دور
`https://` باشند. روی هر تصویر `role: "first_frame"` / `"last_frame"` را تنظیم کنید، یا
از API یکپارچه `content[]` استفاده می‌کند. حداکثر از ۲ تصویر ورودی
(`first_frame` + `last_frame`) پشتیبانی می‌کند. همه ورودی‌ها باید URLهای راه‌دور `https://`
باشند. روی هر تصویر `role: "first_frame"` / `"last_frame"` را تنظیم کنید، یا
تصاویر را به‌صورت موقعیتی ارسال کنید.
`aspectRatio: "adaptive"` نسبت را از تصویر ورودی به‌صورت خودکار تشخیص می‌دهد.
@ -356,14 +358,13 @@ OpenClaw مدل را به این ترتیب حل می‌کند:
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
به Plugin
[`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
نیاز دارد. شناسهٔ ارائه‌دهنده: `byteplus-seedance2`. مدل‌ها:
به Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
نیاز دارد. شناسه ارائه‌دهنده: `byteplus-seedance2`. مدل‌ها:
`dreamina-seedance-2-0-260128`،
`dreamina-seedance-2-0-fast-260128`.
از API یکپارچهٔ `content[]` استفاده می‌کند. تا 9 تصویر مرجع،
3 ویدیوی مرجع و 3 صدای مرجع را پشتیبانی می‌کند. همهٔ ورودی‌ها باید URLهای راه‌دور
از API یکپارچه `content[]` استفاده می‌کند. تا ۹ تصویر مرجع،
۳ ویدئوی مرجع، و ۳ صدای مرجع را پشتیبانی می‌کند. همه ورودی‌ها باید URLهای راه‌دور
`https://` باشند. روی هر دارایی `role` را تنظیم کنید — مقادیر پشتیبانی‌شده:
`"first_frame"`، `"last_frame"`، `"reference_image"`،
`"reference_video"`، `"reference_audio"`.
@ -374,59 +375,60 @@ OpenClaw مدل را به این ترتیب حل می‌کند:
</Accordion>
<Accordion title="ComfyUI">
اجرای محلی یا ابری مبتنی بر workflow. از تبدیل متن به ویدیو و
تصویر به ویدیو از طریق گراف پیکربندی‌شده پشتیبانی می‌کند.
اجرای محلی یا ابری مبتنی بر گردش‌کار. از متن-به-ویدئو و
تصویر-به-ویدئو از طریق گراف پیکربندی‌شده پشتیبانی می‌کند.
</Accordion>
<Accordion title="fal">
برای کارهای طولانی‌مدت از جریانی متکی به صف استفاده می‌کند. بیشتر مدل‌های ویدیویی fal
یک مرجع تصویری واحد را می‌پذیرند. مدل‌های مرجع‌به‌ویدیوی Seedance 2.0
تا 9 تصویر، 3 ویدیو و 3 مرجع صوتی را می‌پذیرند، با
حداکثر 12 فایل مرجع در مجموع.
برای کارهای طولانی‌مدت از جریان متکی به صف استفاده می‌کند. بیشتر مدل‌های ویدئویی fal
یک مرجع تصویر را می‌پذیرند. مدل‌های مرجع-به-ویدئو Seedance 2.0
تا ۹ تصویر، ۳ ویدئو، و ۳ مرجع صوتی را می‌پذیرند، با
حداکثر ۱۲ فایل مرجع در مجموع.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
از یک مرجع تصویر یا یک مرجع ویدیو پشتیبانی می‌کند.
از یک مرجع تصویر یا یک مرجع ویدئو پشتیبانی می‌کند.
</Accordion>
<Accordion title="MiniMax">
فقط یک مرجع تصویری واحد.
فقط یک مرجع تصویر.
</Accordion>
<Accordion title="OpenAI">
فقط بازنویسی `size` ارسال می‌شود. دیگر بازنویسی‌های سبک
(`aspectRatio`، `resolution`، `audio`، `watermark`) با یک هشدار نادیده گرفته می‌شوند.
فقط بازنویسی `size` ارسال می‌شود. بازنویسی‌های سبک دیگر
(`aspectRatio`، `resolution`، `audio`، `watermark`) با
یک هشدار نادیده گرفته می‌شوند.
</Accordion>
<Accordion title="OpenRouter">
از API ناهمگام `/videos` متعلق به OpenRouter استفاده می‌کند. OpenClaw
کار را ارسال می‌کند، `polling_url` را polling می‌کند و یا `unsigned_urls` یا
نقطهٔ پایانی مستندشدهٔ محتوای کار را دانلود می‌کند. پیش‌فرض همراه‌شدهٔ `google/veo-3.1-fast`
مدت‌های 4/6/8 ثانیه، وضوح‌های `720P`/`1080P` و
کار را ارسال می‌کند، `polling_url` را نظرسنجی می‌کند، و یا `unsigned_urls` یا
نقطه پایانی مستندشده محتوای کار را دانلود می‌کند. پیش‌فرض همراه `google/veo-3.1-fast`
مدت‌زمان‌های ۴/۶/۸ ثانیه، وضوح‌های `720P`/`1080P`، و
نسبت‌های تصویر `16:9`/`9:16` را اعلام می‌کند.
</Accordion>
<Accordion title="Qwen">
همان backend DashScope مثل Alibaba. ورودی‌های مرجع باید URLهای راه‌دور
همان پشتانه DashScope مثل Alibaba. ورودی‌های مرجع باید URLهای راه‌دور
`http(s)` باشند؛ فایل‌های محلی از ابتدا رد می‌شوند.
</Accordion>
<Accordion title="Runway">
از فایل‌های محلی از طریق data URI پشتیبانی می‌کند. تبدیل ویدیو به ویدیو به
`runway/gen4_aleph` نیاز دارد. اجراهای فقط متنی نسبت‌های تصویر `16:9` و `9:16` را
از فایل‌های محلی از طریق داده URI پشتیبانی می‌کند. ویدئو-به-ویدئو به
`runway/gen4_aleph` نیاز دارد. اجراهای فقط-متن نسبت‌های تصویر `16:9` و `9:16` را
ارائه می‌کنند.
</Accordion>
<Accordion title="Together">
فقط یک مرجع تصویری واحد.
فقط یک مرجع تصویر.
</Accordion>
<Accordion title="Vydra">
برای جلوگیری از تغییرمسیرهایی که احراز هویت را حذف می‌کنند، مستقیماً از
`https://www.vydra.ai/api/v1` استفاده می‌کند. `veo3` فقط به‌عنوان متن‌به‌ویدیو همراه شده است؛
`kling` به یک URL تصویر راه‌دور نیاز دارد.
برای جلوگیری از تغییرمسیرهایی که احراز هویت را حذف می‌کنند، مستقیماً از `https://www.vydra.ai/api/v1`
استفاده می‌کند. `veo3` فقط به‌عنوان متن-به-ویدئو همراه شده است؛ `kling` به
یک URL تصویر راه‌دور نیاز دارد.
</Accordion>
<Accordion title="xAI">
از متن‌به‌ویدیو، تبدیل تصویر به ویدیو با یک تصویر فریم اول، تا 7
ورودی `reference_image` از طریق `reference_images` در xAI، و جریان‌های ویرایش/گسترش ویدیوی راه‌دور
پشتیبانی می‌کند.
از متن-به-ویدئو، تصویر-به-ویدئو با یک فریم اول، تا ۷
ورودی `reference_image` از طریق `reference_images` متعلق به xAI، و جریان‌های ویرایش/گسترش
ویدئوی راه‌دور پشتیبانی می‌کند.
</Accordion>
</AccordionGroup>
## حالت‌های قابلیت ارائه‌دهنده
قرارداد مشترک تولید ویدئو به‌جای فقط محدودیت‌های تجمیعی تخت، از قابلیت‌های وابسته به حالت پشتیبانی می‌کند. پیاده‌سازی‌های جدید ارائه‌دهنده باید بلوک‌های حالت صریح را ترجیح دهند:
قرارداد مشترک تولید ویدئو به‌جای فقط محدودیت‌های تجمیعی مسطح، از قابلیت‌های اختصاصی هر حالت پشتیبانی می‌کند. پیاده‌سازی‌های جدید ارائه‌دهنده باید بلوک‌های حالت صریح را ترجیح دهند:
```typescript
capabilities: {
@ -451,13 +453,13 @@ capabilities: {
}
```
فیلدهای تجمیعی تخت مانند `maxInputImages` و `maxInputVideos` برای اعلام پشتیبانی از حالت تبدیل **کافی نیستند**. ارائه‌دهندگان باید `generate`، `imageToVideo` و `videoToVideo` را به‌صورت صریح اعلام کنند تا آزمون‌های زنده، آزمون‌های قرارداد و ابزار مشترک `video_generate` بتوانند پشتیبانی حالت را به‌صورت قطعی اعتبارسنجی کنند.
فیلدهای تجمیعی مسطح مانند `maxInputImages` و `maxInputVideos` برای اعلام پشتیبانی از حالت تبدیل **کافی نیستند**. ارائه‌دهندگان باید `generate`، `imageToVideo` و `videoToVideo` را به‌صراحت اعلام کنند تا آزمون‌های زنده، آزمون‌های قرارداد، و ابزار مشترک `video_generate` بتوانند پشتیبانی از حالت‌ها را به‌صورت قطعی اعتبارسنجی کنند.
وقتی یک مدل در یک ارائه‌دهنده پشتیبانی گسترده‌تری از ورودی مرجع نسبت به بقیه دارد، به‌جای افزایش محدودیت سراسری حالت، از `maxInputImagesByModel`، `maxInputVideosByModel` یا `maxInputAudiosByModel` استفاده کنید.
وقتی یک مدل در یک ارائه‌دهنده نسبت به بقیه پشتیبانی گسترده‌تری از ورودی مرجع دارد، به‌جای افزایش محدودیت کل حالت، از `maxInputImagesByModel`، `maxInputVideosByModel` یا `maxInputAudiosByModel` استفاده کنید.
## آزمون‌های زنده
پوشش زندهٔ انتخابی برای ارائه‌دهندگان مشترک بسته‌بندی‌شده:
پوشش زندهٔ اختیاری برای ارائه‌دهندگان بسته‌بندی‌شدهٔ مشترک:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -469,24 +471,24 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv
pnpm test:live:media video
```
این فایل زنده متغیرهای محیطی مفقود ارائه‌دهنده را از `~/.profile` بارگیری می‌کند، به‌صورت پیش‌فرض کلیدهای API زنده/محیطی را بر پروفایل‌های احراز هویت ذخیره‌شده ترجیح می‌دهد، و به‌صورت پیش‌فرض یک آزمون دود release-safe اجرا می‌کند:
این فایل زنده متغیرهای محیطی ارائه‌دهندهٔ جاافتاده را از `~/.profile` بارگذاری می‌کند، به‌صورت پیش‌فرض کلیدهای API زنده/محیطی را بر پروفایل‌های احراز هویت ذخیره‌شده ترجیح می‌دهد، و به‌صورت پیش‌فرض یک آزمون دود ایمن برای انتشار اجرا می‌کند:
- `generate` برای هر ارائه‌دهندهٔ غیر FAL در پیمایش.
- اعلان خرچنگ یک‌ثانیه‌ای.
- سقف عملیات به‌ازای هر ارائه‌دهنده از
- پرامپت خرچنگ یک‌ثانیه‌ای.
- سقف عملیات برای هر ارائه‌دهنده از
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` به‌صورت پیش‌فرض).
FAL انتخابی است، چون تأخیر صف سمت ارائه‌دهنده می‌تواند بر زمان انتشار غالب شود:
FAL اختیاری است چون تأخیر صف در سمت ارائه‌دهنده می‌تواند بر زمان انتشار غالب شود:
```bash
pnpm test:live:media video --video-providers fal
```
برای اجرای حالت‌های تبدیل اعلام‌شده که پیمایش مشترک می‌تواند با رسانهٔ محلی به‌صورت امن تمرین کند نیز `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` را تنظیم کنید:
برای اجرای حالت‌های تبدیل اعلام‌شده‌ای که پیمایش مشترک می‌تواند با رسانهٔ محلی به‌صورت ایمن اجرا کند نیز `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` را تنظیم کنید:
- `imageToVideo` وقتی `capabilities.imageToVideo.enabled`.
- `videoToVideo` وقتی `capabilities.videoToVideo.enabled` و
ارائه‌دهنده/مدل ورودی ویدئوی محلی مبتنی بر بافر را در پیمایش مشترک می‌پذیرد.
ارائه‌دهنده/مدل ورودی ویدئوی محلی مبتنی بر بافر را در پیمایش مشترک بپذیرد.
امروز مسیر زندهٔ مشترک `videoToVideo` فقط زمانی `runway` را پوشش می‌دهد که `runway/gen4_aleph` را انتخاب کنید.

145
docs/fa/web/dashboard.md
View File

@ -1,109 +1,98 @@
---
read_when:
- تغییر احراز هویت یا حالت‌های در معرض قرارگیری داشبورد
summary: دسترسی و احراز هویت داشبورد Gateway (رابط کاربری کنترل)
- تغییر حالت‌های احراز هویت یا در معرض قرارگیری داشبورد
summary: دسترسی و احراز هویت داشبورد Gateway (Control UI)
title: داشبورد
x-i18n:
generated_at: "2026-04-29T23:49:00Z"
generated_at: "2026-05-05T01:54:01Z"
model: gpt-5.5
provider: openai
source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
source_path: web/dashboard.md
workflow: 16
---
The Gateway dashboard is the browser Control UI served at `/` by default
(override with `gateway.controlUi.basePath`).
داشبورد Gateway همان رابط کاربری کنترل در مرورگر است که به‌طور پیش‌فرض در `/` ارائه می‌شود
(با `gateway.controlUi.basePath` بازنویسی کنید).
Quick open (local Gateway):
باز کردن سریع (Gateway محلی):
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/))
- With `gateway.tls.enabled: true`, use `https://127.0.0.1:18789/` and
`wss://127.0.0.1:18789` for the WebSocket endpoint.
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (یا [http://localhost:18789/](http://localhost:18789/))
- با `gateway.tls.enabled: true`، از `https://127.0.0.1:18789/` و
`wss://127.0.0.1:18789` برای نقطه پایانی WebSocket استفاده کنید.
Key references:
ارجاعات کلیدی:
- [Control UI](/fa/web/control-ui) for usage and UI capabilities.
- [Tailscale](/fa/gateway/tailscale) for Serve/Funnel automation.
- [Web surfaces](/fa/web) for bind modes and security notes.
- [رابط کاربری کنترل](/fa/web/control-ui) برای استفاده و قابلیت‌های رابط کاربری.
- [Tailscale](/fa/gateway/tailscale) برای خودکارسازی Serve/Funnel.
- [سطوح وب](/fa/web) برای حالت‌های bind و نکات امنیتی.
Authentication is enforced at the WebSocket handshake via the configured gateway
auth path:
احراز هویت در مرحله handshake مربوط به WebSocket و از طریق مسیر احراز هویت پیکربندی‌شده Gateway
اعمال می‌شود:
- `connect.params.auth.token`
- `connect.params.auth.password`
- Tailscale Serve identity headers when `gateway.auth.allowTailscale: true`
- trusted-proxy identity headers when `gateway.auth.mode: "trusted-proxy"`
- سرآیندهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` است
- سرآیندهای هویت trusted-proxy وقتی `gateway.auth.mode: "trusted-proxy"` است
See `gateway.auth` in [Gateway configuration](/fa/gateway/configuration).
`gateway.auth` را در [پیکربندی Gateway](/fa/gateway/configuration) ببینید.
Security note: the Control UI is an **admin surface** (chat, config, exec approvals).
Do not expose it publicly. The UI keeps dashboard URL tokens in sessionStorage
for the current browser tab session and selected gateway URL, and strips them from the URL after load.
Prefer localhost, Tailscale Serve, or an SSH tunnel.
نکته امنیتی: رابط کاربری کنترل یک **سطح مدیریتی** است (چت، پیکربندی، تأییدهای exec).
آن را عمومی در دسترس قرار ندهید. رابط کاربری توکن‌های URL داشبورد را برای نشست تب فعلی مرورگر و URL انتخاب‌شده Gateway در sessionStorage نگه می‌دارد و پس از بارگذاری آن‌ها را از URL حذف می‌کند.
localhost، Tailscale Serve یا تونل SSH را ترجیح دهید.
## Fast path (recommended)
## مسیر سریع (توصیه‌شده)
- After onboarding, the CLI auto-opens the dashboard and prints a clean (non-tokenized) link.
- Re-open anytime: `openclaw dashboard` (copies link, opens browser if possible, shows SSH hint if headless).
- If the UI prompts for shared-secret auth, paste the configured token or
password into Control UI settings.
- پس از onboarding، CLI داشبورد را خودکار باز می‌کند و یک لینک پاک (بدون توکن) چاپ می‌کند.
- باز کردن دوباره در هر زمان: `openclaw dashboard` (لینک را کپی می‌کند، اگر ممکن باشد مرورگر را باز می‌کند، و اگر headless باشد راهنمای SSH نشان می‌دهد).
- اگر تحویل از طریق clipboard و مرورگر شکست بخورد، `openclaw dashboard` همچنان URL پاک را چاپ می‌کند
و به شما می‌گوید از توکن `OPENCLAW_GATEWAY_TOKEN` یا
`gateway.auth.token` به‌عنوان کلید fragment URL یعنی `token` استفاده کنید؛ مقدار توکن‌ها را در لاگ‌ها چاپ نمی‌کند.
- اگر رابط کاربری برای احراز هویت با shared-secret درخواست داد، توکن یا
گذرواژه پیکربندی‌شده را در تنظیمات رابط کاربری کنترل جای‌گذاری کنید.
## Auth basics (local vs remote)
## مبانی احراز هویت (محلی در برابر راه‌دور)
- **Localhost**: open `http://127.0.0.1:18789/`.
- **Gateway TLS**: when `gateway.tls.enabled: true`, dashboard/status links use
`https://` and Control UI WebSocket links use `wss://`.
- **Shared-secret token source**: `gateway.auth.token` (or
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` can pass it via URL fragment
for one-time bootstrap, and the Control UI keeps it in sessionStorage for the
current browser tab session and selected gateway URL instead of localStorage.
- If `gateway.auth.token` is SecretRef-managed, `openclaw dashboard`
prints/copies/opens a non-tokenized URL by design. This avoids exposing
externally managed tokens in shell logs, clipboard history, or browser-launch
arguments.
- If `gateway.auth.token` is configured as a SecretRef and is unresolved in your
current shell, `openclaw dashboard` still prints a non-tokenized URL plus
actionable auth setup guidance.
- **Shared-secret password**: use the configured `gateway.auth.password` (or
`OPENCLAW_GATEWAY_PASSWORD`). The dashboard does not persist passwords across
reloads.
- **Identity-bearing modes**: Tailscale Serve can satisfy Control UI/WebSocket
auth via identity headers when `gateway.auth.allowTailscale: true`, and a
non-loopback identity-aware reverse proxy can satisfy
`gateway.auth.mode: "trusted-proxy"`. In those modes the dashboard does not
need a pasted shared secret for the WebSocket.
- **Not localhost**: use Tailscale Serve, a non-loopback shared-secret bind, a
non-loopback identity-aware reverse proxy with
`gateway.auth.mode: "trusted-proxy"`, or an SSH tunnel. HTTP APIs still use
shared-secret auth unless you intentionally run private-ingress
`gateway.auth.mode: "none"` or trusted-proxy HTTP auth. See
[Web surfaces](/fa/web).
- **Localhost**: `http://127.0.0.1:18789/` را باز کنید.
- **TLS مربوط به Gateway**: وقتی `gateway.tls.enabled: true` باشد، لینک‌های داشبورد/وضعیت از
`https://` و لینک‌های WebSocket رابط کاربری کنترل از `wss://` استفاده می‌کنند.
- **منبع توکن shared-secret**: `gateway.auth.token` (یا
`OPENCLAW_GATEWAY_TOKEN`)؛ `openclaw dashboard` می‌تواند آن را از طریق fragment URL برای bootstrap یک‌باره عبور دهد، و رابط کاربری کنترل آن را برای نشست تب فعلی مرورگر و URL انتخاب‌شده Gateway به‌جای localStorage در sessionStorage نگه می‌دارد.
- اگر `gateway.auth.token` با SecretRef مدیریت شود، `openclaw dashboard`
طبق طراحی یک URL بدون توکن چاپ/کپی/باز می‌کند. این کار از افشای توکن‌های مدیریت‌شده خارجی در لاگ‌های shell، تاریخچه clipboard یا آرگومان‌های راه‌اندازی مرورگر جلوگیری می‌کند.
- اگر `gateway.auth.token` به‌صورت SecretRef پیکربندی شده و در shell فعلی شما resolve نشده باشد، `openclaw dashboard` همچنان یک URL بدون توکن به‌همراه راهنمای عملی برای تنظیم احراز هویت چاپ می‌کند.
- **گذرواژه shared-secret**: از `gateway.auth.password` پیکربندی‌شده (یا
`OPENCLAW_GATEWAY_PASSWORD`) استفاده کنید. داشبورد گذرواژه‌ها را بین reloadها نگه نمی‌دارد.
- **حالت‌های دارای هویت**: Tailscale Serve می‌تواند احراز هویت رابط کاربری کنترل/WebSocket را از طریق سرآیندهای هویت وقتی `gateway.auth.allowTailscale: true` است برآورده کند، و یک reverse proxy غیر local loopback و آگاه از هویت می‌تواند
`gateway.auth.mode: "trusted-proxy"` را برآورده کند. در این حالت‌ها داشبورد برای WebSocket به shared secret جای‌گذاری‌شده نیاز ندارد.
- **غیر از localhost**: از Tailscale Serve، یک bind غیر local loopback با shared-secret، یک reverse proxy غیر local loopback و آگاه از هویت با
`gateway.auth.mode: "trusted-proxy"`، یا یک تونل SSH استفاده کنید. APIهای HTTP همچنان از احراز هویت shared-secret استفاده می‌کنند مگر اینکه عمداً
`gateway.auth.mode: "none"` برای private-ingress یا احراز هویت HTTP از نوع trusted-proxy را اجرا کنید. [سطوح وب](/fa/web) را ببینید.
<a id="if-you-see-unauthorized-1008"></a>
## If you see "unauthorized" / 1008
## اگر "unauthorized" / 1008 را می‌بینید
- Ensure the gateway is reachable (local: `openclaw status`; remote: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`).
- For `AUTH_TOKEN_MISMATCH`, clients may do one trusted retry with a cached device token when the gateway returns retry hints. That cached-token retry reuses the token's cached approved scopes; explicit `deviceToken` / explicit `scopes` callers keep their requested scope set. If auth still fails after that retry, resolve token drift manually.
- Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
- On the async Tailscale Serve Control UI path, failed attempts for the same
`{scope, ip}` are serialized before the failed-auth limiter records them, so
the second concurrent bad retry can already show `retry later`.
- For token drift repair steps, follow [Token drift recovery checklist](/fa/cli/devices#token-drift-recovery-checklist).
- Retrieve or supply the shared secret from the gateway host:
- Token: `openclaw config get gateway.auth.token`
- Password: resolve the configured `gateway.auth.password` or
`OPENCLAW_GATEWAY_PASSWORD`
- SecretRef-managed token: resolve the external secret provider or export
`OPENCLAW_GATEWAY_TOKEN` in this shell, then rerun `openclaw dashboard`
- No shared secret configured: `openclaw doctor --generate-gateway-token`
- In the dashboard settings, paste the token or password into the auth field,
then connect.
- The UI language picker is in **Overview -> Gateway Access -> Language**.
It is part of the access card, not the Appearance section.
- مطمئن شوید Gateway در دسترس است (محلی: `openclaw status`؛ راه‌دور: تونل SSH با `ssh -N -L 18789:127.0.0.1:18789 user@host` سپس `http://127.0.0.1:18789/` را باز کنید).
- برای `AUTH_TOKEN_MISMATCH`، کلاینت‌ها ممکن است وقتی Gateway راهنمای retry برمی‌گرداند، یک retry مورد اعتماد با توکن device ذخیره‌شده انجام دهند. آن retry با توکن ذخیره‌شده، scopeهای تأییدشده ذخیره‌شده توکن را دوباره استفاده می‌کند؛ فراخوان‌های دارای `deviceToken` صریح / `scopes` صریح مجموعه scope درخواستی خود را نگه می‌دارند. اگر احراز هویت پس از آن retry همچنان شکست خورد، drift توکن را دستی برطرف کنید.
- خارج از آن مسیر retry، تقدم احراز هویت اتصال ابتدا shared token/password صریح، سپس `deviceToken` صریح، سپس توکن device ذخیره‌شده، سپس توکن bootstrap است.
- در مسیر ناهمگام رابط کاربری کنترل Tailscale Serve، تلاش‌های ناموفق برای همان
`{scope, ip}` پیش از ثبت آن‌ها توسط محدودکننده failed-auth به‌صورت ترتیبی انجام می‌شوند، بنابراین
دومین retry بد هم‌زمان می‌تواند از قبل `retry later` را نشان دهد.
- برای مراحل ترمیم drift توکن، [چک‌لیست بازیابی drift توکن](/fa/cli/devices#token-drift-recovery-checklist) را دنبال کنید.
- shared secret را از میزبان Gateway بازیابی یا فراهم کنید:
- توکن: `openclaw config get gateway.auth.token`
- گذرواژه: `gateway.auth.password` پیکربندی‌شده یا
`OPENCLAW_GATEWAY_PASSWORD` را resolve کنید
- توکن مدیریت‌شده با SecretRef: ارائه‌دهنده secret خارجی را resolve کنید یا
`OPENCLAW_GATEWAY_TOKEN` را در این shell export کنید، سپس `openclaw dashboard` را دوباره اجرا کنید
- shared secret پیکربندی نشده است: `openclaw doctor --generate-gateway-token`
- در تنظیمات داشبورد، توکن یا گذرواژه را در فیلد احراز هویت جای‌گذاری کنید،
سپس وصل شوید.
- انتخاب‌گر زبان رابط کاربری در **نمای کلی -> دسترسی Gateway -> زبان** قرار دارد.
این بخش جزئی از کارت دسترسی است، نه بخش ظاهر.
## Related
## مرتبط
- [Control UI](/fa/web/control-ui)
- [رابط کاربری کنترل](/fa/web/control-ui)
- [WebChat](/fa/web/webchat)