diff --git a/docs/fa/automation/tasks.md b/docs/fa/automation/tasks.md index 823597ba1..1fe5fab5e 100644 --- a/docs/fa/automation/tasks.md +++ b/docs/fa/automation/tasks.md @@ -1,48 +1,48 @@ --- read_when: - - بررسی کار پس‌زمینهٔ در حال انجام یا به‌تازگی تکمیل‌شده - - اشکال‌زدایی از خطاهای تحویل برای اجراهای عامل جداشده - - درک ارتباط اجراهای پس‌زمینه با نشست‌ها، Cron و Heartbeat + - بررسی کارهای پس‌زمینه در حال انجام یا اخیراً تکمیل‌شده + - اشکال‌زدایی از شکست‌های تحویل در اجراهای جداشدهٔ عامل + - درک اینکه اجراهای پس‌زمینه چه ارتباطی با جلسه‌ها، Cron و Heartbeat دارند sidebarTitle: Background tasks -summary: ردیابی کارهای پس‌زمینه برای اجراهای ACP، زیرعامل‌ها، کارهای Cron ایزوله، و عملیات CLI +summary: ردیابی وظایف پس‌زمینه برای اجراهای ACP، زیرعامل‌ها، کارهای Cron مجزا، و عملیات CLI title: وظایف پس‌زمینه x-i18n: - generated_at: "2026-04-29T22:24:05Z" + generated_at: "2026-04-30T16:28:04Z" model: gpt-5.5 provider: openai - source_hash: 4bbf74f3aeea532738b56b83cd2e1a0a3734bfd453da6636b8be985a28ccc027 + source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34 source_path: automation/tasks.md workflow: 16 --- -به دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار مناسب، [اتوماسیون و وظایف](/fa/automation) را ببینید. این صفحه دفتر فعالیت برای کارهای پس‌زمینه است، نه زمان‌بند. +به‌دنبال زمان‌بندی هستید؟ برای انتخاب سازوکار درست، [اتوماسیون و وظایف](/fa/automation) را ببینید. این صفحه دفتر فعالیت کارهای پس‌زمینه است، نه زمان‌بند. -وظایف پس‌زمینه کارهایی را ردیابی می‌کنند که **بیرون از نشست گفت‌وگوی اصلی شما** اجرا می‌شوند: اجراهای ACP، ایجاد زیرعامل‌ها، اجرای کارهای cron ایزوله، و عملیات آغازشده از CLI. +وظایف پس‌زمینه کارهایی را دنبال می‌کنند که **بیرون از جلسه گفت‌وگوی اصلی شما** اجرا می‌شوند: اجراهای ACP، ایجاد زیرعامل‌ها، اجرای جداافتاده کارهای cron، و عملیات آغازشده با CLI. -وظایف جایگزین نشست‌ها، کارهای cron، یا heartbeatها نمی‌شوند — آن‌ها **دفتر فعالیتی** هستند که ثبت می‌کند چه کار جداشده‌ای رخ داده، چه زمانی، و آیا موفق بوده است یا نه. +وظایف جایگزین جلسه‌ها، کارهای cron، یا heartbeatها نمی‌شوند — آن‌ها **دفتر فعالیت** هستند که ثبت می‌کند چه کار جداشده‌ای انجام شده، چه زمانی، و آیا موفق بوده است یا نه. -همه اجراهای عامل یک وظیفه ایجاد نمی‌کنند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی عادی این کار را نمی‌کنند. همه اجراهای cron، ایجادهای ACP، ایجادهای زیرعامل، و فرمان‌های عامل CLI این کار را می‌کنند. +هر اجرای عامل یک وظیفه ایجاد نمی‌کند. نوبت‌های Heartbeat و گفت‌وگوی تعاملی معمولی این کار را نمی‌کنند. همه اجرای cron، ایجادهای ACP، ایجادهای زیرعامل، و فرمان‌های عامل CLI این کار را می‌کنند. -## خلاصه +## خلاصه سریع -- وظایف **رکورد** هستند، نه زمان‌بند — cron و heartbeat تعیین می‌کنند کار _چه زمانی_ اجرا شود، وظایف ردیابی می‌کنند _چه اتفاقی افتاده است_. +- وظایف **رکورد** هستند، نه زمان‌بند — cron و heartbeat تعیین می‌کنند کار _چه زمانی_ اجرا شود، وظایف پیگیری می‌کنند _چه اتفاقی افتاده است_. - ACP، زیرعامل‌ها، همه کارهای cron، و عملیات CLI وظیفه ایجاد می‌کنند. نوبت‌های Heartbeat این کار را نمی‌کنند. -- هر وظیفه از مسیر `queued → running → terminal` عبور می‌کند (succeeded، failed، timed_out، cancelled، یا lost). -- وظایف cron تا زمانی که runtime مربوط به cron هنوز مالک کار است زنده می‌مانند؛ اگر - وضعیت runtime درون‌حافظه‌ای از بین رفته باشد، نگهداری وظیفه ابتدا تاریخچه پایدار اجرای cron را بررسی می‌کند - و بعد وظیفه را lost علامت‌گذاری می‌کند. -- تکمیل به‌صورت push-driven است: کار جداشده می‌تواند مستقیما اطلاع دهد یا - نشست/heartbeat درخواست‌کننده را هنگام پایان بیدار کند، بنابراین حلقه‌های polling وضعیت +- هر وظیفه از مسیر `queued → running → terminal` حرکت می‌کند (succeeded، failed، timed_out، cancelled، یا lost). +- وظایف Cron تا زمانی که runtime کرون هنوز مالک کار باشد زنده می‌مانند؛ اگر + وضعیت runtime درون‌حافظه‌ای از بین رفته باشد، نگه‌داری وظیفه پیش از علامت‌گذاری یک وظیفه به‌عنوان lost، + ابتدا تاریخچه پایدار اجرای cron را بررسی می‌کند. +- تکمیل به‌صورت push-driven است: کار جداشده می‌تواند مستقیما اطلاع دهد یا هنگام پایان، + جلسه/heartbeat درخواست‌کننده را بیدار کند، بنابراین حلقه‌های status polling معمولا شکل درستی نیستند. -- اجراهای cron ایزوله و تکمیل‌های زیرعامل به‌صورت best-effort تب‌ها/فرایندهای مرورگر ردیابی‌شده را برای نشست فرزند خود پیش از bookkeeping پاک‌سازی نهایی پاک می‌کنند. -- تحویل cron ایزوله پاسخ‌های موقت و کهنه والد را در حالی که کار زیرعاملِ نواده هنوز در حال تخلیه است سرکوب می‌کند، و وقتی خروجی نهایی نواده پیش از تحویل برسد آن را ترجیح می‌دهد. +- اجراهای جداافتاده cron و تکمیل‌های زیرعامل با بهترین تلاش تب‌ها/فرایندهای مرورگر ردیابی‌شده برای جلسه فرزند خود را پیش از ثبت پاک‌سازی نهایی پاک می‌کنند. +- تحویل جداافتاده cron پاسخ‌های میانی کهنه والد را تا زمانی که کار زیرعاملِ نواده هنوز در حال تخلیه است سرکوب می‌کند، و اگر خروجی نهایی نواده پیش از تحویل برسد آن را ترجیح می‌دهد. - اعلان‌های تکمیل مستقیما به یک کانال تحویل داده می‌شوند یا برای heartbeat بعدی در صف قرار می‌گیرند. - `openclaw tasks list` همه وظایف را نشان می‌دهد؛ `openclaw tasks audit` مشکلات را آشکار می‌کند. -- رکوردهای پایانی ۷ روز نگه داشته می‌شوند و سپس به‌طور خودکار هرس می‌شوند. +- رکوردهای نهایی ۷ روز نگه داشته می‌شوند، سپس به‌طور خودکار پاک‌سازی می‌شوند. ## شروع سریع @@ -58,13 +58,13 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -74,7 +74,7 @@ x-i18n: ``` - + ```bash # Run a health audit openclaw tasks audit @@ -97,27 +97,27 @@ x-i18n: ## چه چیزی یک وظیفه ایجاد می‌کند -| منبع | نوع runtime | زمانی که رکورد وظیفه ایجاد می‌شود | سیاست اعلان پیش‌فرض | +| منبع | نوع runtime | زمانی که رکورد وظیفه ایجاد می‌شود | سیاست اطلاع‌رسانی پیش‌فرض | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| اجراهای پس‌زمینه ACP | `acp` | ایجاد یک نشست فرزند ACP | `done_only` | -| هماهنگ‌سازی زیرعامل | `subagent` | ایجاد زیرعامل از طریق `sessions_spawn` | `done_only` | -| کارهای cron (همه انواع) | `cron` | هر اجرای cron (نشست اصلی و ایزوله) | `silent` | -| عملیات CLI | `cli` | فرمان‌های `openclaw agent` که از طریق Gateway اجرا می‌شوند | `silent` | -| کارهای رسانه عامل | `cli` | اجراهای `video_generate` پشتیبانی‌شده با نشست | `silent` | +| اجراهای پس‌زمینه ACP | `acp` | ایجاد یک جلسه فرزند ACP | `done_only` | +| هماهنگ‌سازی زیرعامل | `subagent` | ایجاد یک زیرعامل از طریق `sessions_spawn` | `done_only` | +| کارهای Cron (همه انواع) | `cron` | هر اجرای cron (جلسه اصلی و جداافتاده) | `silent` | +| عملیات CLI | `cli` | فرمان‌های `openclaw agent` که از طریق gateway اجرا می‌شوند | `silent` | +| کارهای رسانه عامل | `cli` | اجراهای `video_generate` مبتنی بر جلسه | `silent` | - - وظایف cron نشست اصلی به‌طور پیش‌فرض از سیاست اعلان `silent` استفاده می‌کنند — آن‌ها برای ردیابی رکورد ایجاد می‌کنند اما اعلان تولید نمی‌کنند. وظایف cron ایزوله نیز به‌طور پیش‌فرض `silent` هستند، اما چون در نشست خودشان اجرا می‌شوند قابل‌مشاهده‌ترند. + + وظایف cron جلسه اصلی به‌طور پیش‌فرض از سیاست اطلاع‌رسانی `silent` استفاده می‌کنند — آن‌ها برای پیگیری رکورد ایجاد می‌کنند اما اعلان تولید نمی‌کنند. وظایف cron جداافتاده نیز به‌طور پیش‌فرض `silent` هستند، اما چون در جلسه خودشان اجرا می‌شوند بیشتر دیده می‌شوند. - اجراهای `video_generate` پشتیبانی‌شده با نشست نیز از سیاست اعلان `silent` استفاده می‌کنند. آن‌ها همچنان رکوردهای وظیفه ایجاد می‌کنند، اما تکمیل به‌عنوان یک بیدارسازی داخلی به نشست عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و ویدیوی پایان‌یافته را خودش پیوست کند. اگر `tools.media.asyncCompletion.directSend` را فعال کنید، تکمیل‌های async مربوط به `music_generate` و `video_generate` ابتدا تحویل مستقیم کانال را امتحان می‌کنند و سپس به مسیر بیدارسازی نشست درخواست‌کننده برمی‌گردند. + اجراهای `video_generate` مبتنی بر جلسه نیز از سیاست اطلاع‌رسانی `silent` استفاده می‌کنند. آن‌ها همچنان رکوردهای وظیفه ایجاد می‌کنند، اما تکمیل به‌صورت یک بیدارسازی داخلی به جلسه عامل اصلی برگردانده می‌شود تا عامل بتواند پیام پیگیری را بنویسد و ویدیوی تکمیل‌شده را خودش پیوست کند. اگر `tools.media.asyncCompletion.directSend` را فعال کنید، تکمیل‌های async `music_generate` و `video_generate` ابتدا تحویل مستقیم کانال را امتحان می‌کنند و سپس به مسیر بیدارسازی جلسه درخواست‌کننده برمی‌گردند. - - در حالی که یک وظیفه `video_generate` پشتیبانی‌شده با نشست هنوز فعال است، این ابزار همچنین به‌عنوان یک گاردریل عمل می‌کند: فراخوانی‌های تکراری `video_generate` در همان نشست، به‌جای شروع یک تولید همزمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل به جست‌وجوی صریح پیشرفت/وضعیت نیاز دارید، از `action: "status"` استفاده کنید. + + تا زمانی که یک وظیفه `video_generate` مبتنی بر جلسه هنوز فعال است، ابزار نقش محافظ را هم دارد: فراخوانی‌های تکراری `video_generate` در همان جلسه، به‌جای شروع یک تولید هم‌زمان دوم، وضعیت وظیفه فعال را برمی‌گردانند. وقتی از سمت عامل به یک جست‌وجوی پیشرفت/وضعیت صریح نیاز دارید، از `action: "status"` استفاده کنید. - - نوبت‌های Heartbeat — نشست اصلی؛ [Heartbeat](/fa/gateway/heartbeat) را ببینید - - نوبت‌های گفت‌وگوی تعاملی عادی + - نوبت‌های Heartbeat — جلسه اصلی؛ [Heartbeat](/fa/gateway/heartbeat) را ببینید + - نوبت‌های گفت‌وگوی تعاملی معمولی - پاسخ‌های مستقیم `/command` @@ -137,58 +137,58 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| وضعیت | معنای آن | +| وضعیت | معنی آن | | ----------- | -------------------------------------------------------------------------- | -| `queued` | ایجاد شده، در انتظار شروع عامل | -| `running` | نوبت عامل فعالانه در حال اجراست | -| `succeeded` | با موفقیت تکمیل شده است | -| `failed` | با خطا تکمیل شده است | -| `timed_out` | از timeout پیکربندی‌شده عبور کرده است | -| `cancelled` | توسط اپراتور از طریق `openclaw tasks cancel` متوقف شده است | -| `lost` | runtime پس از یک دوره مهلت ۵ دقیقه‌ای، وضعیت پشتیبان معتبر را از دست داده است | +| `queued` | ایجاد شده، در انتظار شروع عامل | +| `running` | نوبت عامل به‌طور فعال در حال اجرا است | +| `succeeded` | با موفقیت تکمیل شد | +| `failed` | با خطا تکمیل شد | +| `timed_out` | از مهلت پیکربندی‌شده فراتر رفت | +| `cancelled` | توسط اپراتور از طریق `openclaw tasks cancel` متوقف شد | +| `lost` | runtime پس از یک دوره ارفاق ۵ دقیقه‌ای وضعیت پشتیبان معتبر را از دست داد | -انتقال‌ها به‌طور خودکار رخ می‌دهند — وقتی اجرای عامل مرتبط پایان یابد، وضعیت وظیفه متناسب با آن به‌روزرسانی می‌شود. +گذارها به‌طور خودکار رخ می‌دهند — وقتی اجرای عامل مرتبط پایان می‌یابد، وضعیت وظیفه برای مطابقت به‌روزرسانی می‌شود. -تکمیل اجرای عامل برای رکوردهای وظیفه فعال مرجع معتبر است. یک اجرای جداشده موفق با `succeeded` نهایی می‌شود، خطاهای معمول اجرا با `failed` نهایی می‌شوند، و نتایج timeout یا abort با `timed_out` نهایی می‌شوند. اگر اپراتور قبلا وظیفه را لغو کرده باشد، یا runtime از قبل وضعیت پایانی قوی‌تری مانند `failed`، `timed_out`، یا `lost` ثبت کرده باشد، سیگنال موفقیت بعدی آن وضعیت پایانی را پایین‌تر نمی‌آورد. +تکمیل اجرای عامل برای رکوردهای وظیفه فعال مرجع است. یک اجرای جداشده موفق به‌صورت `succeeded` نهایی می‌شود، خطاهای معمول اجرا به‌صورت `failed` نهایی می‌شوند، و نتایج timeout یا abort به‌صورت `timed_out` نهایی می‌شوند. اگر یک اپراتور قبلا وظیفه را لغو کرده باشد، یا runtime از قبل یک وضعیت نهایی قوی‌تر مانند `failed`، `timed_out`، یا `lost` را ثبت کرده باشد، سیگنال موفقیت بعدی آن وضعیت نهایی را تنزل نمی‌دهد. -`lost` از runtime آگاه است: +`lost` نسبت به runtime آگاه است: -- وظایف ACP: فراداده نشست فرزند ACP پشتیبان ناپدید شده است. -- وظایف زیرعامل: نشست فرزند پشتیبان از store عامل هدف ناپدید شده است. -- وظایف cron: runtime مربوط به cron دیگر کار را به‌عنوان فعال ردیابی نمی‌کند و تاریخچه پایدار - اجرای cron نتیجه پایانی برای آن اجرا نشان نمی‌دهد. ممیزی CLI آفلاین - وضعیت خالی runtime درون‌فرایندی خودش را مرجع معتبر تلقی نمی‌کند. -- وظایف CLI: وظایف نشست فرزند ایزوله از نشست فرزند استفاده می‌کنند؛ وظایف CLI - پشتیبانی‌شده با chat در عوض از بافت اجرای زنده استفاده می‌کنند، بنابراین ردیف‌های ماندگار - نشست channel/group/direct آن‌ها را زنده نگه نمی‌دارند. اجراهای - `openclaw agent` پشتیبانی‌شده با Gateway نیز از نتیجه اجرای خود نهایی می‌شوند، بنابراین اجراهای تکمیل‌شده - تا زمانی که sweeper آن‌ها را `lost` علامت‌گذاری کند فعال نمی‌مانند. +- وظایف ACP: فراداده جلسه فرزند ACP پشتیبان ناپدید شده است. +- وظایف زیرعامل: جلسه فرزند پشتیبان از مخزن عامل هدف ناپدید شده است. +- وظایف Cron: runtime کرون دیگر کار را به‌عنوان فعال ردیابی نمی‌کند و تاریخچه پایدار اجرای + cron نتیجه نهایی برای آن اجرا نشان نمی‌دهد. ممیزی CLI آفلاین + وضعیت خالی runtime کرون درون‌فرایندی خودش را مرجع تلقی نمی‌کند. +- وظایف CLI: وظایف جلسه فرزند جداافتاده از جلسه فرزند استفاده می‌کنند؛ وظایف CLI + مبتنی بر چت به‌جای آن از زمینه اجرای زنده استفاده می‌کنند، بنابراین ردیف‌های جلسه + کانال/گروه/مستقیمِ باقی‌مانده آن‌ها را زنده نگه نمی‌دارند. اجراهای + `openclaw agent` مبتنی بر Gateway نیز از نتیجه اجرای خود نهایی می‌شوند، بنابراین اجراهای تکمیل‌شده + تا زمانی که پاک‌ساز آن‌ها را `lost` علامت‌گذاری کند فعال نمی‌مانند. ## تحویل و اعلان‌ها -وقتی یک وظیفه به وضعیت پایانی می‌رسد، OpenClaw به شما اطلاع می‌دهد. دو مسیر تحویل وجود دارد: +وقتی یک وظیفه به وضعیت نهایی می‌رسد، OpenClaw به شما اطلاع می‌دهد. دو مسیر تحویل وجود دارد: -**تحویل مستقیم** — اگر وظیفه هدف کانال داشته باشد (`requesterOrigin`)، پیام تکمیل مستقیما به همان کانال می‌رود (Telegram، Discord، Slack، و غیره). برای تکمیل‌های زیرعامل، OpenClaw همچنین در صورت وجود، مسیریابی thread/topic متصل را حفظ می‌کند و می‌تواند پیش از منصرف‌شدن از تحویل مستقیم، `to` / حسابِ گمشده را از مسیر ذخیره‌شده نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر کند. +**تحویل مستقیم** — اگر وظیفه هدف کانال داشته باشد (`requesterOrigin`)، پیام تکمیل مستقیما به آن کانال می‌رود (Telegram، Discord، Slack، و غیره). برای تکمیل‌های زیرعامل، OpenClaw همچنین مسیریابی thread/topic متصل را در صورت وجود حفظ می‌کند و می‌تواند پیش از صرف‌نظر از تحویل مستقیم، مقدار `to` / حسابِ گمشده را از مسیر ذخیره‌شده جلسه درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر کند. -**تحویل صف‌شده در نشست** — اگر تحویل مستقیم شکست بخورد یا هیچ origin تنظیم نشده باشد، به‌روزرسانی به‌عنوان رویداد سیستمی در نشست درخواست‌کننده در صف قرار می‌گیرد و در heartbeat بعدی ظاهر می‌شود. +**تحویل صف‌شده در جلسه** — اگر تحویل مستقیم شکست بخورد یا هیچ مبدا تنظیم نشده باشد، به‌روزرسانی به‌عنوان یک رویداد سیستمی در جلسه درخواست‌کننده در صف قرار می‌گیرد و در heartbeat بعدی ظاهر می‌شود. -تکمیل وظیفه یک بیدارسازی فوری heartbeat را تحریک می‌کند تا نتیجه را سریع ببینید — لازم نیست منتظر tick زمان‌بندی‌شده بعدی heartbeat بمانید. +تکمیل وظیفه یک بیدارسازی فوری heartbeat را فعال می‌کند تا نتیجه را سریع ببینید — لازم نیست منتظر تیک heartbeat زمان‌بندی‌شده بعدی بمانید. -یعنی جریان کاری معمول push-based است: کار جداشده را یک‌بار شروع کنید، سپس اجازه دهید runtime هنگام تکمیل شما را بیدار کند یا به شما اطلاع دهد. وضعیت وظیفه را فقط وقتی poll کنید که به اشکال‌زدایی، مداخله، یا یک ممیزی صریح نیاز دارید. +یعنی گردش کار معمول push-based است: کار جداشده را یک بار شروع کنید، سپس اجازه دهید runtime هنگام تکمیل شما را بیدار یا مطلع کند. وضعیت وظیفه را فقط زمانی poll کنید که به اشکال‌زدایی، مداخله، یا ممیزی صریح نیاز دارید. ### سیاست‌های اعلان -کنترل کنید درباره هر وظیفه چقدر بشنوید: +کنترل کنید از هر وظیفه چه مقدار خبر دریافت کنید: -| سیاست | آنچه تحویل داده می‌شود | +| سیاست | آنچه تحویل داده می‌شود | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (پیش‌فرض) | فقط وضعیت پایانی (succeeded، failed، و غیره) — **این پیش‌فرض است** | -| `state_changes` | هر انتقال وضعیت و به‌روزرسانی پیشرفت | -| `silent` | هیچ‌چیز | +| `done_only` (پیش‌فرض) | فقط وضعیت نهایی (succeeded، failed، و غیره) — **این پیش‌فرض است** | +| `state_changes` | هر گذار وضعیت و به‌روزرسانی پیشرفت | +| `silent` | هیچ چیز | -سیاست را هنگام اجرای یک وظیفه تغییر دهید: +سیاست را هنگام اجرای وظیفه تغییر دهید: ```bash openclaw tasks notify state_changes @@ -202,7 +202,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - ستون‌های خروجی: شناسه وظیفه، نوع، وضعیت، تحویل، شناسه اجرا، نشست فرزند، خلاصه. + ستون‌های خروجی: شناسه وظیفه، نوع، وضعیت، تحویل، شناسه اجرا، جلسه فرزند، خلاصه. @@ -210,7 +210,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - توکن lookup یک شناسه وظیفه، شناسه اجرا، یا کلید نشست را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا، و خلاصه پایانی را نشان می‌دهد. + توکن جست‌وجو یک شناسه وظیفه، شناسه اجرا، یا کلید جلسه را می‌پذیرد. رکورد کامل شامل زمان‌بندی، وضعیت تحویل، خطا، و خلاصه نهایی را نشان می‌دهد. @@ -218,7 +218,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - برای وظایف ACP و زیرعامل، این کار نشست فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (handle runtime فرزند جداگانه‌ای وجود ندارد). وضعیت به `cancelled` منتقل می‌شود و در صورت کاربرد، اعلان تحویل ارسال می‌شود. + برای وظایف ACP و زیرعامل، این کار جلسه فرزند را می‌کشد. برای وظایف ردیابی‌شده با CLI، لغو در رجیستری وظیفه ثبت می‌شود (هیچ handle جداگانه‌ای برای runtime فرزند وجود ندارد). وضعیت به `cancelled` گذار می‌کند و در صورت کاربرد، اعلان تحویل ارسال می‌شود. @@ -231,16 +231,16 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - مشکلات عملیاتی را آشکار می‌کند. یافته‌ها وقتی مشکل شناسایی شود در `openclaw status` نیز ظاهر می‌شوند. + مشکلات عملیاتی را آشکار می‌کند. یافته‌ها هنگام شناسایی مشکل در `openclaw status` نیز ظاهر می‌شوند. - | یافته | شدت | محرک | + | یافته | شدت | محرک | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | `stale_queued` | warn | بیش از ۱۰ دقیقه در صف مانده است | | `stale_running` | error | بیش از ۳۰ دقیقه در حال اجرا بوده است | - | `lost` | warn/error | مالکیت وظیفهٔ پشتیبانی‌شده با زمان اجرا ناپدید شده است؛ وظایف ازدست‌رفتهٔ نگه‌داشته‌شده تا `cleanupAfter` هشدار می‌دهند، سپس به خطا تبدیل می‌شوند | - | `delivery_failed` | warn | تحویل ناموفق بود و سیاست اطلاع‌رسانی `silent` نیست | - | `missing_cleanup` | warn | وظیفهٔ پایانی بدون زمان‌سنج پاک‌سازی | - | `inconsistent_timestamps` | warn | نقض خط زمانی (برای مثال، پایان پیش از شروع) | + | `lost` | warn/error | مالکیت وظیفهٔ پشتیبانی‌شده توسط زمان اجرا ناپدید شده است؛ وظایف گم‌شدهٔ نگه‌داری‌شده تا `cleanupAfter` هشدار می‌دهند و سپس به خطا تبدیل می‌شوند | + | `delivery_failed` | warn | تحویل ناموفق بوده و سیاست اعلان `silent` نیست | + | `missing_cleanup` | warn | وظیفهٔ پایانی بدون مهر زمانی پاک‌سازی | + | `inconsistent_timestamps` | warn | نقض خط زمانی (برای مثال، پایان قبل از شروع) | @@ -249,20 +249,21 @@ openclaw tasks notify state_changes openclaw tasks maintenance --apply [--json] ``` - از این برای پیش‌نمایش یا اعمال همگام‌سازی، ثبت زمان پاک‌سازی، و هرس کردن وظایف و وضعیت Task Flow استفاده کنید. + از این برای پیش‌نمایش یا اعمال سازگارسازی، ثبت مهر پاک‌سازی، و هرس کردن وظایف و وضعیت گردش وظیفه استفاده کنید. - همگام‌سازی از زمان اجرا آگاه است: + سازگارسازی از زمان اجرا آگاه است: - وظایف ACP/زیرعامل، نشست فرزند پشتیبان خود را بررسی می‌کنند. - - وظایف Cron بررسی می‌کنند که آیا زمان اجرای cron هنوز مالک job است یا نه، سپس پیش از عقب‌نشینی به `lost`، وضعیت پایانی را از گزارش‌های اجرای cron/وضعیت job پایدارشده بازیابی می‌کنند. فقط فرایند Gateway مرجع معتبر برای مجموعهٔ درون‌حافظه‌ای jobهای فعال cron است؛ حسابرسی آفلاین CLI از تاریخچهٔ پایدار استفاده می‌کند، اما صرفاً به این دلیل که آن Set محلی خالی است، یک وظیفهٔ cron را ازدست‌رفته علامت‌گذاری نمی‌کند. + - وظایف زیرعاملی که نشست فرزندشان سنگ‌قبر بازیابی پس از راه‌اندازی دوباره دارد، به‌جای این‌که به‌عنوان نشست‌های پشتیبان قابل بازیابی در نظر گرفته شوند، گم‌شده علامت‌گذاری می‌شوند. + - وظایف Cron بررسی می‌کنند که آیا زمان اجرای cron هنوز مالک کار است یا نه، سپس پیش از بازگشت به `lost`، وضعیت پایانی را از گزارش‌های اجرای cron/وضعیت کارِ پایدارشده بازیابی می‌کنند. تنها فرایند Gateway برای مجموعهٔ کارهای فعال cron در حافظه مرجع معتبر است؛ ممیزی آفلاین CLI از تاریخچهٔ بادوام استفاده می‌کند اما یک وظیفهٔ cron را صرفا به‌دلیل خالی بودن آن Set محلی گم‌شده علامت‌گذاری نمی‌کند. - وظایف CLI پشتیبانی‌شده با چت، زمینهٔ اجرای زندهٔ مالک را بررسی می‌کنند، نه فقط ردیف نشست چت را. پاک‌سازی تکمیل نیز از زمان اجرا آگاه است: - - تکمیل زیرعامل، پیش از ادامهٔ پاک‌سازی اعلان، با بیشترین تلاش زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست فرزند را می‌بندد. - - تکمیل cron ایزوله، پیش از اینکه اجرا کاملاً از بین برود، با بیشترین تلاش زبانه‌ها/فرایندهای مرورگر ردیابی‌شده برای نشست cron را می‌بندد. - - تحویل cron ایزوله، در صورت نیاز منتظر پیگیری زیرعامل‌های نواده می‌ماند و به‌جای اعلام متن تأیید والد کهنه، آن را سرکوب می‌کند. - - تحویل تکمیل زیرعامل، آخرین متن قابل‌مشاهدهٔ دستیار را ترجیح می‌دهد؛ اگر خالی باشد، به آخرین متن پاک‌سازی‌شدهٔ tool/toolResult عقب‌نشینی می‌کند، و اجراهای فراخوانی ابزار که فقط به مهلت زمانی رسیده‌اند می‌توانند به یک خلاصهٔ کوتاه از پیشرفت جزئی فشرده شوند. اجراهای پایانی ناموفق، وضعیت شکست را بدون پخش دوبارهٔ متن پاسخ ضبط‌شده اعلام می‌کنند. + - تکمیل زیرعامل، تا حد امکان زبانه‌ها/فرایندهای مرورگرِ ردیابی‌شده برای نشست فرزند را پیش از ادامهٔ پاک‌سازی اعلان می‌بندد. + - تکمیل cron ایزوله، تا حد امکان زبانه‌ها/فرایندهای مرورگرِ ردیابی‌شده برای نشست cron را پیش از برچیده شدن کامل اجرا می‌بندد. + - تحویل cron ایزوله، در صورت نیاز منتظر پیگیری زیرعامل‌های فرزند می‌ماند و به‌جای اعلام آن، متن تأیید والدِ مانده را سرکوب می‌کند. + - تحویل تکمیل زیرعامل، تازه‌ترین متن دستیارِ قابل مشاهده را ترجیح می‌دهد؛ اگر خالی باشد، به تازه‌ترین متن پاک‌سازی‌شدهٔ tool/toolResult برمی‌گردد، و اجراهای صرفا دارای فراخوانی ابزار که فقط با پایان مهلت متوقف شده‌اند می‌توانند به یک خلاصهٔ کوتاه از پیشرفت جزئی فروکاسته شوند. اجراهای پایانی ناموفق، وضعیت شکست را بدون بازپخش متن پاسخِ ضبط‌شده اعلام می‌کنند. - شکست‌های پاک‌سازی، نتیجهٔ واقعی وظیفه را پنهان نمی‌کنند. @@ -273,18 +274,18 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - وقتی چیزی که برایتان مهم است Task Flow هماهنگ‌کننده است، نه یک رکورد منفرد از وظیفهٔ پس‌زمینه، از این‌ها استفاده کنید. + وقتی چیزی که برایتان مهم است گردش وظیفهٔ هماهنگ‌کننده است، نه یک رکورد منفرد از وظیفهٔ پس‌زمینه، از این‌ها استفاده کنید. ## تابلوی وظایف چت (`/tasks`) -برای دیدن وظایف پس‌زمینهٔ مرتبط با هر نشست چت، از `/tasks` استفاده کنید. این تابلو وظایف فعال و تازه‌تکمیل‌شده را همراه با زمان اجرا، وضعیت، زمان‌بندی، و جزئیات پیشرفت یا خطا نشان می‌دهد. +در هر نشست چت از `/tasks` استفاده کنید تا وظایف پس‌زمینهٔ پیوندخورده به آن نشست را ببینید. تابلو وظایف فعال و وظایف اخیرا تکمیل‌شده را همراه با زمان اجرا، وضعیت، زمان‌بندی، و جزئیات پیشرفت یا خطا نشان می‌دهد. -وقتی نشست فعلی هیچ وظیفهٔ پیوندخوردهٔ قابل‌مشاهده‌ای ندارد، `/tasks` به شمارش وظایف محلی عامل عقب‌نشینی می‌کند تا همچنان بدون افشای جزئیات نشست‌های دیگر، یک نمای کلی دریافت کنید. +وقتی نشست فعلی هیچ وظیفهٔ پیوندخوردهٔ قابل مشاهده‌ای ندارد، `/tasks` به شمارش وظایف محلی عامل برمی‌گردد تا همچنان بدون افشای جزئیات نشست‌های دیگر، یک نمای کلی دریافت کنید. -برای دفترکل کامل اپراتور، از CLI استفاده کنید: `openclaw tasks list`. +برای دفتر کل کامل اپراتور، از CLI استفاده کنید: `openclaw tasks list`. ## یکپارچه‌سازی وضعیت (فشار وظیفه) @@ -294,17 +295,17 @@ openclaw tasks notify state_changes Tasks: 3 queued · 2 running · 1 issues ``` -این خلاصه گزارش می‌دهد: +خلاصه گزارش می‌دهد: -- **فعال** — شمار `queued` + `running` -- **شکست‌ها** — شمار `failed` + `timed_out` + `lost` -- **بر اساس زمان اجرا** — تفکیک بر پایهٔ `acp`، `subagent`، `cron`، `cli` +- **فعال** — تعداد `queued` + `running` +- **شکست‌ها** — تعداد `failed` + `timed_out` + `lost` +- **بر اساس زمان اجرا** — تفکیک بر اساس `acp`، `subagent`، `cron`، `cli` -هر دو `/status` و ابزار `session_status` از یک نمای فوری آگاه از پاک‌سازیِ وظایف استفاده می‌کنند: وظایف فعال ترجیح داده می‌شوند، ردیف‌های تکمیل‌شدهٔ کهنه پنهان می‌شوند، و شکست‌های اخیر فقط وقتی نمایش داده می‌شوند که هیچ کار فعالی باقی نمانده باشد. این باعث می‌شود کارت وضعیت روی چیزی متمرکز بماند که همین حالا مهم است. +هم `/status` و هم ابزار `session_status` از یک تصویر فوریِ آگاه از پاک‌سازی برای وظایف استفاده می‌کنند: وظایف فعال ترجیح داده می‌شوند، ردیف‌های تکمیل‌شدهٔ مانده پنهان می‌شوند، و شکست‌های اخیر فقط وقتی نمایش داده می‌شوند که هیچ کار فعالی باقی نمانده باشد. این باعث می‌شود کارت وضعیت بر آنچه همین حالا مهم است متمرکز بماند. ## ذخیره‌سازی و نگه‌داری -### محل نگه‌داری وظایف +### وظایف کجا نگه‌داری می‌شوند رکوردهای وظیفه در SQLite در این مسیر پایدار می‌شوند: @@ -312,22 +313,22 @@ Tasks: 3 queued · 2 running · 1 issues $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -رجیستری هنگام شروع Gateway در حافظه بارگذاری می‌شود و برای دوام در میان راه‌اندازی‌های دوباره، نوشتن‌ها را با SQLite همگام می‌کند. -Gateway با استفاده از آستانهٔ پیش‌فرض autocheckpoint در SQLite به‌همراه checkpointهای دوره‌ای و هنگام خاموشی از نوع `TRUNCATE`، گزارش write-ahead SQLite را محدود نگه می‌دارد. +رجیستری هنگام شروع Gateway در حافظه بارگذاری می‌شود و برای دوام در راه‌اندازی‌های دوباره، نوشتن‌ها را با SQLite همگام می‌کند. +Gateway با استفاده از آستانهٔ پیش‌فرض autocheckpoint در SQLite به‌همراه checkpointهای دوره‌ای و هنگام خاموشی از نوع `TRUNCATE`، گزارش write-ahead در SQLite را محدود نگه می‌دارد. ### نگه‌داری خودکار -یک جاروبگر هر **۶۰ ثانیه** اجرا می‌شود و چهار کار را انجام می‌دهد: +یک پاک‌روب هر **۶۰ ثانیه** اجرا می‌شود و چهار کار را انجام می‌دهد: - بررسی می‌کند که آیا وظایف فعال هنوز پشتیبانی معتبر زمان اجرا دارند یا نه. وظایف ACP/زیرعامل از وضعیت نشست فرزند استفاده می‌کنند، وظایف cron از مالکیت job فعال استفاده می‌کنند، و وظایف CLI پشتیبانی‌شده با چت از زمینهٔ اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از ۵ دقیقه از بین رفته باشد، وظیفه با `lost` علامت‌گذاری می‌شود. + بررسی می‌کند که آیا وظایف فعال هنوز پشتیبان معتبر زمان اجرا دارند یا نه. وظایف ACP/زیرعامل از وضعیت نشست فرزند استفاده می‌کنند، وظایف cron از مالکیت کار فعال استفاده می‌کنند، و وظایف CLI پشتیبانی‌شده با چت از زمینهٔ اجرای مالک استفاده می‌کنند. اگر آن وضعیت پشتیبان بیش از ۵ دقیقه از بین رفته باشد، وظیفه `lost` علامت‌گذاری می‌شود. - نشست‌های ACP یک‌مرحله‌ایِ پایانی یا یتیمِ تحت مالکیت والد را می‌بندد، و نشست‌های ACP پایدارِ پایانی یا یتیم کهنه را فقط وقتی می‌بندد که هیچ اتصال گفت‌وگوی فعالی باقی نمانده باشد. + نشست‌های ACP یک‌بارهٔ پایانی یا یتیمِ متعلق به والد را می‌بندد، و نشست‌های ACP پایدارِ پایانیِ مانده یا یتیم را فقط وقتی می‌بندد که هیچ اتصال گفت‌وگوی فعالی باقی نمانده باشد. - روی وظایف پایانی یک زمان‌سنج `cleanupAfter` تنظیم می‌کند (endedAt + ۷ روز). در طول نگه‌داری، وظایف ازدست‌رفته همچنان در حسابرسی به‌عنوان هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی فرادادهٔ پاک‌سازی وجود نداشته باشد، آن‌ها خطا هستند. + روی وظایف پایانی یک مهر زمانی `cleanupAfter` تنظیم می‌کند (endedAt + ۷ روز). در طول دورهٔ نگه‌داری، وظایف گم‌شده همچنان در ممیزی به‌صورت هشدار ظاهر می‌شوند؛ پس از انقضای `cleanupAfter` یا وقتی فرادادهٔ پاک‌سازی موجود نباشد، خطا هستند. رکوردهایی را که از تاریخ `cleanupAfter` خود گذشته‌اند حذف می‌کند. @@ -335,42 +336,42 @@ Gateway با استفاده از آستانهٔ پیش‌فرض autocheckpoint -**نگه‌داری:** رکوردهای وظایف پایانی به مدت **۷ روز** نگه داشته می‌شوند و سپس به‌طور خودکار هرس می‌شوند. به هیچ پیکربندی‌ای نیاز نیست. +**نگه‌داری:** رکوردهای وظایف پایانی به‌مدت **۷ روز** نگه داشته می‌شوند و سپس به‌صورت خودکار هرس می‌شوند. هیچ پیکربندی‌ای لازم نیست. -## ارتباط وظایف با سامانه‌های دیگر +## وظایف چگونه با سامانه‌های دیگر ارتباط دارند - [Task Flow](/fa/automation/taskflow) لایهٔ هماهنگ‌سازی جریان بالای وظایف پس‌زمینه است. یک جریان منفرد می‌تواند در طول عمر خود چندین وظیفه را با استفاده از حالت‌های همگام‌سازی مدیریت‌شده یا آینه‌ای هماهنگ کند. از `openclaw tasks` برای بررسی رکوردهای تک‌وظیفه‌ای و از `openclaw tasks flow` برای بررسی جریان هماهنگ‌کننده استفاده کنید. + [گردش وظیفه](/fa/automation/taskflow) لایهٔ هماهنگ‌سازی جریان بالای وظایف پس‌زمینه است. یک جریان منفرد ممکن است در طول عمر خود با استفاده از حالت‌های همگام‌سازی مدیریت‌شده یا آینه‌ای، چندین وظیفه را هماهنگ کند. از `openclaw tasks` برای بررسی رکوردهای وظیفهٔ منفرد و از `openclaw tasks flow` برای بررسی جریان هماهنگ‌کننده استفاده کنید. - برای جزئیات، [Task Flow](/fa/automation/taskflow) را ببینید. + برای جزئیات، [گردش وظیفه](/fa/automation/taskflow) را ببینید. - **تعریف** یک job مربوط به cron در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای زمان اجرا کنار آن در `~/.openclaw/cron/jobs-state.json` قرار دارد. **هر** اجرای cron یک رکورد وظیفه ایجاد می‌کند — هم نشست اصلی و هم ایزوله. وظایف cron نشست اصلی به‌طور پیش‌فرض سیاست اطلاع‌رسانی `silent` دارند تا بدون ایجاد اعلان ردیابی شوند. + یک **تعریف** کار cron در `~/.openclaw/cron/jobs.json` قرار دارد؛ وضعیت اجرای زمان اجرا کنار آن در `~/.openclaw/cron/jobs-state.json` قرار می‌گیرد. **هر** اجرای cron یک رکورد وظیفه ایجاد می‌کند — چه نشست اصلی و چه ایزوله. وظایف cron نشست اصلی به‌طور پیش‌فرض سیاست اعلان `silent` دارند تا بدون ایجاد اعلان، ردیابی شوند. - [Cron Jobs](/fa/automation/cron-jobs) را ببینید. + [کارهای Cron](/fa/automation/cron-jobs) را ببینید. - اجراهای Heartbeat نوبت‌های نشست اصلی هستند — آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه کامل می‌شود، می‌تواند یک بیدارباش Heartbeat را فعال کند تا نتیجه را بی‌درنگ ببینید. + اجراهای Heartbeat نوبت‌های نشست اصلی هستند — آن‌ها رکورد وظیفه ایجاد نمی‌کنند. وقتی یک وظیفه تکمیل می‌شود، می‌تواند یک بیدارباش Heartbeat را تحریک کند تا نتیجه را بی‌درنگ ببینید. [Heartbeat](/fa/gateway/heartbeat) را ببینید. - یک وظیفه ممکن است به یک `childSessionKey` (جایی که کار اجرا می‌شود) و یک `requesterSessionKey` (کسی که آن را شروع کرده است) اشاره کند. نشست‌ها زمینهٔ گفت‌وگو هستند؛ وظایف لایهٔ ردیابی فعالیت روی آن هستند. + یک وظیفه ممکن است به `childSessionKey` (جایی که کار اجرا می‌شود) و `requesterSessionKey` (کسی که آن را شروع کرده است) ارجاع دهد. نشست‌ها زمینهٔ گفت‌وگو هستند؛ وظایف، ردیابی فعالیت روی آن هستند. - `runId` یک وظیفه به اجرای عاملی که کار را انجام می‌دهد پیوند می‌خورد. رویدادهای چرخهٔ عمر عامل (شروع، پایان، خطا) به‌طور خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند — نیازی نیست چرخهٔ عمر را به‌صورت دستی مدیریت کنید. + `runId` یک وظیفه به اجرای عاملی که کار را انجام می‌دهد پیوند می‌خورد. رویدادهای چرخهٔ عمر عامل (شروع، پایان، خطا) به‌صورت خودکار وضعیت وظیفه را به‌روزرسانی می‌کنند — نیازی نیست چرخهٔ عمر را دستی مدیریت کنید. ## مرتبط - [اتوماسیون و وظایف](/fa/automation) — همهٔ سازوکارهای اتوماسیون در یک نگاه -- [CLI: وظایف](/fa/cli/tasks) — مرجع فرمان CLI +- [CLI: وظایف](/fa/cli/tasks) — مرجع فرمان‌های CLI - [Heartbeat](/fa/gateway/heartbeat) — نوبت‌های دوره‌ای نشست اصلی -- [وظایف زمان‌بندی‌شده](/fa/automation/cron-jobs) — زمان‌بندی کارهای پس‌زمینه -- [Task Flow](/fa/automation/taskflow) — هماهنگ‌سازی جریان بالای وظایف +- [وظایف زمان‌بندی‌شده](/fa/automation/cron-jobs) — زمان‌بندی کار پس‌زمینه +- [گردش وظیفه](/fa/automation/taskflow) — هماهنگ‌سازی جریان بالای وظایف diff --git a/docs/fa/channels/groups.md b/docs/fa/channels/groups.md index 8dadb0187..704236ea9 100644 --- a/docs/fa/channels/groups.md +++ b/docs/fa/channels/groups.md @@ -1,38 +1,38 @@ --- read_when: - - تغییر رفتار چت گروهی یا محدودسازی بر اساس منشن + - تغییر رفتار گفت‌وگوی گروهی یا محدودسازی بر اساس منشن sidebarTitle: Groups summary: رفتار گفت‌وگوی گروهی در سطوح مختلف (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: گروه‌ها x-i18n: - generated_at: "2026-04-29T22:25:52Z" + generated_at: "2026-04-30T16:27:40Z" model: gpt-5.5 provider: openai - source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998 + source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e source_path: channels/groups.md workflow: 16 --- -OpenClaw با چت‌های گروهی در همه سطح‌ها به‌صورت یکسان رفتار می‌کند: Discord، iMessage، Matrix، Microsoft Teams، Signal، Slack، Telegram، WhatsApp، Zalo. +OpenClaw چت‌های گروهی را در همهٔ سطوح به‌صورت یکسان مدیریت می‌کند: Discord، iMessage، Matrix، Microsoft Teams، Signal، Slack، Telegram، WhatsApp، Zalo. -## معرفی مقدماتی (۲ دقیقه) +## مقدمهٔ مبتدیان (۲ دقیقه) -OpenClaw روی حساب‌های پیام‌رسان خودتان «زندگی می‌کند». کاربر ربات جداگانه‌ای برای WhatsApp وجود ندارد. اگر **شما** در یک گروه باشید، OpenClaw می‌تواند آن گروه را ببیند و همان‌جا پاسخ دهد. +OpenClaw روی حساب‌های پیام‌رسانی خودتان «زندگی می‌کند». کاربر بات جداگانه‌ای برای WhatsApp وجود ندارد. اگر **شما** در یک گروه باشید، OpenClaw می‌تواند آن گروه را ببیند و همان‌جا پاسخ دهد. رفتار پیش‌فرض: - گروه‌ها محدود هستند (`groupPolicy: "allowlist"`). -- پاسخ‌ها به اشاره نیاز دارند، مگر اینکه صریحا دروازه‌بانی اشاره را غیرفعال کنید. -- پاسخ‌های نهایی معمولی در گروه‌ها/کانال‌ها به‌طور پیش‌فرض خصوصی هستند. خروجی قابل مشاهده در اتاق از ابزار `message` استفاده می‌کند. +- پاسخ‌ها به منشن نیاز دارند، مگر اینکه gate منشن را صریحاً غیرفعال کنید. +- پاسخ‌های نهایی عادی در گروه‌ها/کانال‌ها به‌طور پیش‌فرض خصوصی هستند. خروجی قابل‌مشاهدهٔ اتاق از ابزار `message` استفاده می‌کند. -ترجمه: فرستندگان فهرست‌مجاز می‌توانند با اشاره به OpenClaw آن را فعال کنند. +ترجمه: فرستندگان allowlist‌شده می‌توانند با منشن کردن OpenClaw آن را فعال کنند. **خلاصه** -- **دسترسی پیام مستقیم** با `*.allowFrom` کنترل می‌شود. -- **دسترسی گروه** با `*.groupPolicy` + فهرست‌های مجاز (`*.groups`, `*.groupAllowFrom`) کنترل می‌شود. -- **فعال‌سازی پاسخ** با دروازه‌بانی اشاره (`requireMention`, `/activation`) کنترل می‌شود. +- **دسترسی DM** با `*.allowFrom` کنترل می‌شود. +- **دسترسی گروه** با `*.groupPolicy` + allowlistها (`*.groups`، `*.groupAllowFrom`) کنترل می‌شود. +- **فعال‌سازی پاسخ** با gate منشن (`requireMention`، `/activation`) کنترل می‌شود. @@ -45,18 +45,18 @@ requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` -## پاسخ‌های قابل مشاهده +## پاسخ‌های قابل‌مشاهده -برای اتاق‌های گروهی/کانالی، مقدار پیش‌فرض OpenClaw برای `messages.groupChat.visibleReplies` برابر `"message_tool"` است. -یعنی عامل همچنان نوبت را پردازش می‌کند و می‌تواند وضعیت حافظه/نشست را به‌روزرسانی کند، اما پاسخ نهایی معمولی آن به‌طور خودکار در اتاق منتشر نمی‌شود. برای گفتار قابل مشاهده، عامل از `message(action=send)` استفاده می‌کند. +برای اتاق‌های گروه/کانال، OpenClaw به‌طور پیش‌فرض از `messages.groupChat.visibleReplies: "message_tool"` استفاده می‌کند. +یعنی agent همچنان turn را پردازش می‌کند و می‌تواند وضعیت memory/session را به‌روزرسانی کند، اما پاسخ نهایی عادی آن به‌صورت خودکار در اتاق منتشر نمی‌شود. برای صحبت کردن به‌شکل قابل‌مشاهده، agent از `message(action=send)` استفاده می‌کند. -برای چت‌های مستقیم و هر نوبت منبع دیگر، از `messages.visibleReplies: "message_tool"` استفاده کنید تا همان رفتار پاسخ قابل مشاهده فقط از طریق ابزار به‌صورت سراسری اعمال شود. `messages.groupChat.visibleReplies` همچنان بازنویسی مشخص‌تر برای اتاق‌های گروهی/کانالی باقی می‌ماند. +برای چت‌های مستقیم و هر turn منبع دیگر، از `messages.visibleReplies: "message_tool"` استفاده کنید تا همین رفتار پاسخ قابل‌مشاهدهٔ فقط‌ابزاری به‌صورت سراسری اعمال شود. `messages.groupChat.visibleReplies` همچنان override اختصاصی‌تر برای اتاق‌های گروه/کانال باقی می‌ماند. -این جایگزین الگوی قدیمیِ مجبور کردن مدل به پاسخ `NO_REPLY` برای بیشتر نوبت‌های حالت کمین می‌شود. در حالت فقط-ابزار، انجام ندادن هیچ کار قابل مشاهده صرفا یعنی ابزار پیام فراخوانی نشود. +این جایگزین الگوی قدیمی مجبور کردن مدل به پاسخ `NO_REPLY` برای بیشتر turnهای حالت کمین می‌شود. در حالت فقط‌ابزاری، انجام ندادن هیچ کار قابل‌مشاهده‌ای فقط یعنی ابزار message فراخوانی نشود. -نشانگرهای تایپ همچنان هنگام کار عامل در حالت فقط-ابزار ارسال می‌شوند. حالت تایپ پیش‌فرض گروه برای این نوبت‌ها از "message" به "instant" ارتقا داده می‌شود، چون ممکن است پیش از تصمیم عامل برای فراخوانی ابزار پیام، هرگز متن پیام معمول دستیار وجود نداشته باشد. پیکربندی صریح حالت تایپ همچنان اولویت دارد. +در حالت فقط‌ابزاری، هنگام کار کردن agent همچنان نشانگرهای تایپ ارسال می‌شوند. حالت پیش‌فرض تایپ گروه برای این turnها از "message" به "instant" ارتقا داده می‌شود، چون ممکن است پیش از اینکه agent تصمیم بگیرد آیا ابزار message را فراخوانی کند یا نه، هرگز متن پیام عادی assistant وجود نداشته باشد. پیکربندی صریح حالت تایپ همچنان اولویت دارد. -برای بازگرداندن پاسخ‌های نهایی خودکار قدیمی برای اتاق‌های گروهی/کانالی: +برای بازگرداندن پاسخ‌های نهایی خودکار قدیمی برای اتاق‌های گروه/کانال: ```json5 { @@ -68,7 +68,10 @@ otherwise -> reply } ``` -برای اینکه خروجی قابل مشاهده در هر چت منبعی حتما از ابزار پیام عبور کند: +Gateway پس از ذخیره شدن فایل، پیکربندی `messages` را hot-reload می‌کند. فقط زمانی restart کنید +که file watching یا reload پیکربندی در deployment غیرفعال باشد. + +برای اینکه خروجی قابل‌مشاهده در هر چت منبعی از ابزار message عبور کند: ```json5 { @@ -78,29 +81,29 @@ otherwise -> reply } ``` -فرمان‌های اسلش بومی (Discord، Telegram، و سطح‌های دیگری با پشتیبانی فرمان بومی) از `visibleReplies: "message_tool"` عبور می‌کنند و همیشه به‌صورت قابل مشاهده پاسخ می‌دهند تا رابط فرمان بومی کانال پاسخی را که انتظار دارد دریافت کند. این فقط برای نوبت‌های فرمان بومی اعتبارسنجی‌شده اعمال می‌شود؛ فرمان‌های `/...` تایپ‌شده به‌صورت متن و نوبت‌های چت معمولی همچنان از پیش‌فرض گروه پیکربندی‌شده پیروی می‌کنند. +دستورهای slash بومی (Discord، Telegram و سطوح دیگر با پشتیبانی از دستور بومی) `visibleReplies: "message_tool"` را دور می‌زنند و همیشه به‌شکل قابل‌مشاهده پاسخ می‌دهند تا UI دستور بومی کانال پاسخی را که انتظار دارد دریافت کند. این فقط برای turnهای دستور بومی اعتبارسنجی‌شده اعمال می‌شود؛ دستورهای `/...` تایپ‌شده به‌صورت متن و turnهای چت عادی همچنان از پیش‌فرض گروه پیکربندی‌شده پیروی می‌کنند. -## مشاهده‌پذیری زمینه و فهرست‌های مجاز +## دیدپذیری context و allowlistها دو کنترل متفاوت در ایمنی گروه دخیل هستند: -- **مجوز فعال‌سازی**: چه کسی می‌تواند عامل را فعال کند (`groupPolicy`, `groups`, `groupAllowFrom`, فهرست‌های مجاز مختص کانال). -- **مشاهده‌پذیری زمینه**: چه زمینه تکمیلی به مدل تزریق می‌شود (متن پاسخ، نقل‌قول‌ها، تاریخچه رشته، فراداده فورواردشده). +- **مجوز trigger**: چه کسی می‌تواند agent را trigger کند (`groupPolicy`، `groups`، `groupAllowFrom`، allowlistهای اختصاصی کانال). +- **دیدپذیری context**: چه context تکمیلی به مدل تزریق می‌شود (متن پاسخ، نقل‌قول‌ها، تاریخچهٔ thread، metadata فورواردشده). -به‌طور پیش‌فرض، OpenClaw رفتار عادی چت را در اولویت قرار می‌دهد و زمینه را عمدتا همان‌طور که دریافت شده نگه می‌دارد. یعنی فهرست‌های مجاز در درجه نخست تعیین می‌کنند چه کسی می‌تواند اقدام‌ها را فعال کند، نه یک مرز حذف سراسری برای هر قطعه نقل‌شده یا تاریخی. +به‌طور پیش‌فرض، OpenClaw رفتار عادی چت را در اولویت می‌گذارد و context را عمدتاً همان‌طور که دریافت شده نگه می‌دارد. یعنی allowlistها در درجهٔ اول تعیین می‌کنند چه کسی می‌تواند actions را trigger کند، نه اینکه مرز redaction همگانی برای هر قطعهٔ نقل‌شده یا تاریخی باشند. - - - بعضی کانال‌ها از قبل برای زمینه تکمیلی در مسیرهای مشخص، پالایش مبتنی بر فرستنده اعمال می‌کنند (برای مثال بذرگذاری رشته Slack، جست‌وجوهای پاسخ/رشته Matrix). - - کانال‌های دیگر همچنان زمینه نقل‌قول/پاسخ/فوروارد را همان‌طور که دریافت شده عبور می‌دهند. + + - برخی کانال‌ها از قبل در مسیرهای خاص، فیلتر sender-based را برای context تکمیلی اعمال می‌کنند (برای مثال seeding thread در Slack، lookupهای reply/thread در Matrix). + - کانال‌های دیگر همچنان context نقل‌قول/پاسخ/فوروارد را همان‌طور که دریافت شده عبور می‌دهند. - - `contextVisibility: "all"` (پیش‌فرض) رفتار فعلیِ همان‌طور که دریافت شده را نگه می‌دارد. - - `contextVisibility: "allowlist"` زمینه تکمیلی را به فرستندگان فهرست‌مجاز محدود می‌کند. - - `contextVisibility: "allowlist_quote"` همان `allowlist` به‌علاوه یک استثنای صریح برای نقل‌قول/پاسخ است. + - `contextVisibility: "all"` (پیش‌فرض) رفتار فعلیِ همان‌طور-دریافت‌شده را حفظ می‌کند. + - `contextVisibility: "allowlist"` context تکمیلی را به فرستندگان allowlist‌شده فیلتر می‌کند. + - `contextVisibility: "allowlist_quote"` همان `allowlist` به‌همراه یک استثنای صریح برای نقل‌قول/پاسخ است. - تا زمانی که این مدل سخت‌سازی به‌صورت یکپارچه در همه کانال‌ها پیاده‌سازی شود، انتظار تفاوت بین سطح‌ها را داشته باشید. + تا زمانی که این مدل سخت‌سازی به‌صورت سازگار در همهٔ کانال‌ها پیاده‌سازی شود، انتظار تفاوت بین سطوح را داشته باشید. @@ -109,39 +112,39 @@ otherwise -> reply اگر می‌خواهید... -| هدف | چه چیزی را تنظیم کنید | +| هدف | چه چیزی تنظیم شود | | -------------------------------------------- | ---------------------------------------------------------- | -| همه گروه‌ها مجاز باشند، اما فقط روی @اشاره‌ها پاسخ داده شود | `groups: { "*": { requireMention: true } }` | -| همه پاسخ‌های گروهی غیرفعال شوند | `groupPolicy: "disabled"` | +| همهٔ گروه‌ها مجاز باشند اما فقط روی @mentions پاسخ داده شود | `groups: { "*": { requireMention: true } }` | +| همهٔ پاسخ‌های گروهی غیرفعال شوند | `groupPolicy: "disabled"` | | فقط گروه‌های مشخص | `groups: { "": { ... } }` (بدون کلید `"*"` ) | -| فقط شما بتوانید در گروه‌ها فعال‌سازی کنید | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| فقط شما بتوانید در گروه‌ها trigger کنید | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | -## کلیدهای نشست +## کلیدهای session -- نشست‌های گروهی از کلیدهای نشست `agent:::group:` استفاده می‌کنند (اتاق‌ها/کانال‌ها از `agent:::channel:` استفاده می‌کنند). -- موضوعات انجمن Telegram مقدار `:topic:` را به شناسه گروه اضافه می‌کنند تا هر موضوع نشست خودش را داشته باشد. -- چت‌های مستقیم از نشست اصلی استفاده می‌کنند (یا اگر پیکربندی شده باشد، به‌ازای هر فرستنده). -- Heartbeatها برای نشست‌های گروهی نادیده گرفته می‌شوند. +- sessionهای گروه از کلیدهای session با قالب `agent:::group:` استفاده می‌کنند (اتاق‌ها/کانال‌ها از `agent:::channel:` استفاده می‌کنند). +- topicهای forum در Telegram، `:topic:` را به group id اضافه می‌کنند تا هر topic session خودش را داشته باشد. +- چت‌های مستقیم از session اصلی استفاده می‌کنند (یا اگر پیکربندی شده باشد، به‌ازای هر فرستنده). +- Heartbeatها برای sessionهای گروه نادیده گرفته می‌شوند. -## الگو: پیام‌های مستقیم شخصی + گروه‌های عمومی (یک عامل) +## الگو: DMهای شخصی + گروه‌های عمومی (یک agent) -بله، اگر ترافیک «شخصی» شما **پیام‌های مستقیم** و ترافیک «عمومی» شما **گروه‌ها** باشد، این خوب کار می‌کند. +بله — اگر ترافیک «شخصی» شما **DMها** و ترافیک «عمومی» شما **گروه‌ها** باشد، این به‌خوبی کار می‌کند. -چرا: در حالت تک‌عامل، پیام‌های مستقیم معمولا در کلید نشست **اصلی** (`agent:main:main`) قرار می‌گیرند، در حالی که گروه‌ها همیشه از کلیدهای نشست **غیراصلی** (`agent:main::group:`) استفاده می‌کنند. اگر سندباکس‌سازی را با `mode: "non-main"` فعال کنید، آن نشست‌های گروهی در پشتانه سندباکس پیکربندی‌شده اجرا می‌شوند، در حالی که نشست اصلی پیام مستقیم شما روی میزبان باقی می‌ماند. اگر پشتانه‌ای انتخاب نکنید، Docker پشتانه پیش‌فرض است. +چرا: در حالت تک‌agent، DMها معمولاً وارد کلید session **اصلی** (`agent:main:main`) می‌شوند، در حالی‌که گروه‌ها همیشه از کلیدهای session **غیراصلی** (`agent:main::group:`) استفاده می‌کنند. اگر sandboxing را با `mode: "non-main"` فعال کنید، آن sessionهای گروه در sandbox backend پیکربندی‌شده اجرا می‌شوند، در حالی که session اصلی DM شما روی host باقی می‌ماند. اگر backend انتخاب نکنید، Docker backend پیش‌فرض است. -این به شما یک «مغز» عامل می‌دهد (فضای کاری + حافظه مشترک)، اما دو وضعیت اجرایی: +این به شما یک «مغز» agent می‌دهد (workspace + memory مشترک)، اما با دو وضعیت اجرا: -- **پیام‌های مستقیم**: ابزارهای کامل (میزبان) -- **گروه‌ها**: سندباکس + ابزارهای محدودشده +- **DMها**: ابزارهای کامل (host) +- **گروه‌ها**: sandbox + ابزارهای محدود -اگر به فضاهای کاری/شخصیت‌های واقعا جدا نیاز دارید («شخصی» و «عمومی» هرگز نباید مخلوط شوند)، از عامل دوم + اتصال‌ها استفاده کنید. [مسیریابی چندعاملی](/fa/concepts/multi-agent) را ببینید. +اگر به workspaceها/personaهای واقعاً جدا نیاز دارید («شخصی» و «عمومی» هرگز نباید با هم مخلوط شوند)، از agent دوم + bindings استفاده کنید. [Multi-Agent Routing](/fa/concepts/multi-agent) را ببینید. - + ```json5 { agents: { @@ -165,8 +168,8 @@ otherwise -> reply } ``` - - به‌جای «بدون دسترسی میزبان»، می‌خواهید «گروه‌ها فقط بتوانند پوشه X را ببینند»؟ `workspaceAccess: "none"` را نگه دارید و فقط مسیرهای فهرست‌مجاز را داخل سندباکس mount کنید: + + به‌جای «بدون دسترسی host»، می‌خواهید «گروه‌ها فقط پوشهٔ X را ببینند»؟ `workspaceAccess: "none"` را نگه دارید و فقط مسیرهای allowlist‌شده را در sandbox mount کنید: ```json5 { @@ -194,17 +197,17 @@ otherwise -> reply مرتبط: - کلیدهای پیکربندی و پیش‌فرض‌ها: [پیکربندی Gateway](/fa/gateway/config-agents#agentsdefaultssandbox) -- اشکال‌زدایی اینکه چرا یک ابزار مسدود شده است: [سندباکس در برابر سیاست ابزار در برابر ارتقایافته](/fa/gateway/sandbox-vs-tool-policy-vs-elevated) -- جزئیات bind mountها: [سندباکس‌سازی](/fa/gateway/sandboxing#custom-bind-mounts) +- عیب‌یابی اینکه چرا یک ابزار مسدود شده است: [Sandbox در برابر Tool Policy در برابر Elevated](/fa/gateway/sandbox-vs-tool-policy-vs-elevated) +- جزئیات bind mountها: [Sandboxing](/fa/gateway/sandboxing#custom-bind-mounts) ## برچسب‌های نمایش -- برچسب‌های رابط کاربری وقتی `displayName` موجود باشد از آن استفاده می‌کنند، با قالب `:`. +- برچسب‌های UI، وقتی `displayName` موجود باشد، از آن استفاده می‌کنند و به‌شکل `:` قالب‌بندی می‌شوند. - `#room` برای اتاق‌ها/کانال‌ها رزرو شده است؛ چت‌های گروهی از `g-` استفاده می‌کنند (حروف کوچک، فاصله‌ها -> `-`، حفظ `#@+._-`). ## سیاست گروه -کنترل کنید پیام‌های گروه/اتاق برای هر کانال چگونه مدیریت شوند: +کنترل کنید پیام‌های گروه/اتاق در هر کانال چگونه مدیریت شوند: ```json5 { @@ -253,22 +256,23 @@ otherwise -> reply | سیاست | رفتار | | ------------- | ------------------------------------------------------------ | -| `"open"` | گروه‌ها از فهرست‌های مجاز عبور می‌کنند؛ دروازه‌بانی اشاره همچنان اعمال می‌شود. | -| `"disabled"` | همه پیام‌های گروهی را کاملا مسدود می‌کند. | -| `"allowlist"` | فقط گروه‌ها/اتاق‌هایی را مجاز می‌کند که با فهرست مجاز پیکربندی‌شده مطابقت دارند. | +| `"open"` | گروه‌ها allowlistها را دور می‌زنند؛ mention-gating همچنان اعمال می‌شود. | +| `"disabled"` | همهٔ پیام‌های گروهی را کاملاً مسدود می‌کند. | +| `"allowlist"` | فقط گروه‌ها/اتاق‌هایی را مجاز می‌کند که با allowlist پیکربندی‌شده مطابقت دارند. | - - - `groupPolicy` از دروازه‌بانی اشاره جداست (که به @اشاره‌ها نیاز دارد). - - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: از `groupAllowFrom` استفاده کنید (جایگزین: `allowFrom` صریح). - - تاییدهای جفت‌سازی پیام مستقیم (ورودی‌های ذخیره `*-allowFrom`) فقط برای دسترسی پیام مستقیم اعمال می‌شوند؛ مجوز فرستنده گروه برای فهرست‌های مجاز گروه صریح باقی می‌ماند. - - Discord: فهرست مجاز از `channels.discord.guilds..channels` استفاده می‌کند. - - Slack: فهرست مجاز از `channels.slack.channels` استفاده می‌کند. - - Matrix: فهرست مجاز از `channels.matrix.groups` استفاده می‌کند. شناسه‌های اتاق یا نام‌های مستعار را ترجیح دهید؛ جست‌وجوی نام اتاق‌های پیوسته‌شده best-effort است و نام‌های حل‌نشده در زمان اجرا نادیده گرفته می‌شوند. برای محدود کردن فرستندگان از `channels.matrix.groupAllowFrom` استفاده کنید؛ فهرست‌های مجاز `users` به‌ازای هر اتاق نیز پشتیبانی می‌شوند. - - پیام‌های مستقیم گروهی جداگانه کنترل می‌شوند (`channels.discord.dm.*`, `channels.slack.dm.*`). - - فهرست مجاز Telegram می‌تواند با شناسه‌های کاربر (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) یا نام‌های کاربری (`"@alice"` یا `"alice"`) مطابقت داشته باشد؛ پیشوندها به بزرگی/کوچکی حروف حساس نیستند. - - پیش‌فرض `groupPolicy: "allowlist"` است؛ اگر فهرست مجاز گروه شما خالی باشد، پیام‌های گروهی مسدود می‌شوند. - - ایمنی زمان اجرا: وقتی بلوک ارائه‌دهنده کاملا وجود ندارد (`channels.` غایب است)، سیاست گروه به‌جای به‌ارث بردن `channels.defaults.groupPolicy` به حالت بسته-در-برابر-خطا برمی‌گردد (معمولا `allowlist`). + + - `groupPolicy` از mention-gating (که به @mentions نیاز دارد) جداست. + - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: از `groupAllowFrom` استفاده کنید (fallback: `allowFrom` صریح). + - Signal: `groupAllowFrom` می‌تواند هم با inbound Signal group id و هم با تلفن/UUID فرستنده مطابقت داشته باشد. + - تأییدهای pairing در DM (ورودی‌های store مربوط به `*-allowFrom`) فقط برای دسترسی DM اعمال می‌شوند؛ مجوز فرستندهٔ گروه برای allowlistهای گروه صریح باقی می‌ماند. + - Discord: allowlist از `channels.discord.guilds..channels` استفاده می‌کند. + - Slack: allowlist از `channels.slack.channels` استفاده می‌کند. + - Matrix: allowlist از `channels.matrix.groups` استفاده می‌کند. room IDها یا aliasها را ترجیح دهید؛ lookup نام اتاق‌های joined به‌صورت best-effort است و نام‌های resolveنشده در runtime نادیده گرفته می‌شوند. برای محدود کردن فرستندگان از `channels.matrix.groupAllowFrom` استفاده کنید؛ allowlistهای `users` به‌ازای هر اتاق نیز پشتیبانی می‌شوند. + - DMهای گروهی جداگانه کنترل می‌شوند (`channels.discord.dm.*`، `channels.slack.dm.*`). + - allowlist در Telegram می‌تواند با user IDها (`"123456789"`، `"telegram:123456789"`، `"tg:123456789"`) یا usernameها (`"@alice"` یا `"alice"`) مطابقت داشته باشد؛ prefixها به بزرگی/کوچکی حروف حساس نیستند. + - پیش‌فرض `groupPolicy: "allowlist"` است؛ اگر allowlist گروه شما خالی باشد، پیام‌های گروهی مسدود می‌شوند. + - ایمنی runtime: وقتی یک provider block کاملاً وجود ندارد (`channels.` غایب است)، سیاست گروه به‌جای ارث‌بری از `channels.defaults.groupPolicy` به حالت fail-closed برمی‌گردد (معمولاً `allowlist`). @@ -279,19 +283,19 @@ otherwise -> reply `groupPolicy` (open/disabled/allowlist). - - فهرست‌های مجاز گروه (`*.groups`, `*.groupAllowFrom`, فهرست مجاز مختص کانال). + + allowlistهای گروه (`*.groups`، `*.groupAllowFrom`، allowlist اختصاصی کانال). - - دروازه‌بانی اشاره (`requireMention`, `/activation`). + + Mention gating (`requireMention`، `/activation`). -## دروازه‌بانی اشاره (پیش‌فرض) +## Mention gating (پیش‌فرض) -پیام‌های گروهی به اشاره نیاز دارند، مگر اینکه به‌ازای هر گروه بازنویسی شده باشد. پیش‌فرض‌ها در هر زیرسیستم زیر `*.groups."*"` قرار دارند. +پیام‌های گروهی به منشن نیاز دارند، مگر اینکه به‌ازای هر گروه override شده باشد. پیش‌فرض‌ها برای هر subsystem زیر `*.groups."*"` قرار دارند. -پاسخ دادن به پیام بات وقتی کانال از فراداده پاسخ پشتیبانی کند، به‌عنوان اشاره ضمنی محسوب می‌شود. نقل‌قول کردن پیام بات نیز در کانال‌هایی که فراداده نقل‌قول را ارائه می‌کنند، می‌تواند به‌عنوان اشاره ضمنی محسوب شود. موارد داخلی فعلی شامل Telegram، WhatsApp، Slack، Discord، Microsoft Teams، و ZaloUser هستند. +پاسخ دادن به پیام ربات، زمانی که کانال از فرادادهٔ پاسخ پشتیبانی کند، به‌عنوان اشارهٔ ضمنی محسوب می‌شود. نقل‌قول کردن پیام ربات نیز در کانال‌هایی که فرادادهٔ نقل‌قول را ارائه می‌کنند می‌تواند به‌عنوان اشارهٔ ضمنی محسوب شود. موارد داخلی فعلی شامل Telegram، WhatsApp، Slack، Discord، Microsoft Teams و ZaloUser هستند. ```json5 { @@ -330,44 +334,45 @@ otherwise -> reply ``` - - - `mentionPatterns` الگوهای regex امن و غیرحساس به حروف بزرگ و کوچک هستند؛ الگوهای نامعتبر و شکل‌های ناامن با تکرارهای تودرتو نادیده گرفته می‌شوند. - - سطح‌هایی که اشاره‌های صریح ارائه می‌کنند همچنان عبور می‌کنند؛ الگوها یک گزینه پشتیبان هستند. - - بازنویسی به‌ازای هر عامل: `agents.list[].groupChat.mentionPatterns` (زمانی مفید است که چند عامل یک گروه مشترک داشته باشند). + + - `mentionPatterns` الگوهای regex ایمن و بدون حساسیت به حروف کوچک و بزرگ هستند؛ الگوهای نامعتبر و شکل‌های تکرار تودرتوی ناامن نادیده گرفته می‌شوند. + - سطح‌هایی که اشاره‌های صریح ارائه می‌کنند همچنان عبور می‌کنند؛ الگوها نقش پشتیبان دارند. + - بازنویسی برای هر عامل: `agents.list[].groupChat.mentionPatterns` (زمانی مفید است که چند عامل یک گروه را به‌اشتراک می‌گذارند). - دروازه‌گذاری اشاره فقط زمانی اعمال می‌شود که تشخیص اشاره ممکن باشد (اشاره‌های بومی یا `mentionPatterns` پیکربندی شده باشند). - - زمینه پرامپت چت گروهی در هر نوبت دستور پاسخ بی‌صدای حل‌شده را حمل می‌کند؛ فایل‌های workspace نباید سازوکارهای `NO_REPLY` را تکرار کنند. - - گروه‌هایی که در آن‌ها پاسخ‌های بی‌صدا مجاز هستند، نوبت‌های پاکِ خالی یا فقط-استدلالی مدل را بی‌صدا در نظر می‌گیرند، معادل `NO_REPLY`. چت‌های مستقیم همین کار را فقط زمانی انجام می‌دهند که پاسخ‌های بی‌صدای مستقیم به‌صراحت مجاز شده باشند؛ در غیر این صورت پاسخ‌های خالی همچنان نوبت‌های ناموفق عامل باقی می‌مانند. - - پیش‌فرض‌های Discord در `channels.discord.guilds."*"` قرار دارند (قابل بازنویسی به‌ازای هر guild/channel). - - زمینه تاریخچه گروه در همه کانال‌ها به‌شکل یکنواخت بسته‌بندی می‌شود و **فقط در انتظار** است (پیام‌هایی که به‌دلیل دروازه‌گذاری اشاره رد شده‌اند)؛ برای پیش‌فرض سراسری از `messages.groupChat.historyLimit` و برای بازنویسی‌ها از `channels..historyLimit` (یا `channels..accounts.*.historyLimit`) استفاده کنید. برای غیرفعال‌سازی، `0` را تنظیم کنید. + - قرار دادن یک گروه یا فرستنده در فهرست مجاز، دروازه‌گذاری اشاره را غیرفعال نمی‌کند؛ وقتی همهٔ پیام‌ها باید فعال‌سازی کنند، `requireMention` آن گروه را روی `false` تنظیم کنید. + - زمینهٔ اعلان گفت‌وگوی گروهی در هر نوبت دستور پاسخ بی‌صدای حل‌شده را حمل می‌کند؛ فایل‌های workspace نباید سازوکار `NO_REPLY` را تکرار کنند. + - گروه‌هایی که در آن‌ها پاسخ‌های بی‌صدا مجاز است، نوبت‌های مدل خالی تمیز یا فقط شامل استدلال را بی‌صدا تلقی می‌کنند، معادل `NO_REPLY`. گفت‌وگوهای مستقیم فقط زمانی همین کار را می‌کنند که پاسخ‌های مستقیم بی‌صدا صریحا مجاز شده باشند؛ در غیر این صورت پاسخ‌های خالی همچنان نوبت‌های ناموفق عامل باقی می‌مانند. + - پیش‌فرض‌های Discord در `channels.discord.guilds."*"` قرار دارند (برای هر guild/channel قابل بازنویسی). + - زمینهٔ تاریخچهٔ گروه در همهٔ کانال‌ها به‌شکل یکنواخت بسته‌بندی می‌شود و **فقط معلق** است (پیام‌هایی که به‌دلیل دروازه‌گذاری اشاره رد شده‌اند)؛ برای پیش‌فرض سراسری از `messages.groupChat.historyLimit` و برای بازنویسی‌ها از `channels..historyLimit` (یا `channels..accounts.*.historyLimit`) استفاده کنید. برای غیرفعال کردن، `0` تنظیم کنید. ## محدودیت‌های ابزار گروه/کانال (اختیاری) -برخی پیکربندی‌های کانال از محدود کردن ابزارهایی پشتیبانی می‌کنند که **داخل یک گروه/اتاق/کانال مشخص** در دسترس هستند. +برخی پیکربندی‌های کانال از محدود کردن ابزارهای در دسترس **داخل یک گروه/اتاق/کانال مشخص** پشتیبانی می‌کنند. -- `tools`: مجاز/غیرمجاز کردن ابزارها برای کل گروه. -- `toolsBySender`: بازنویسی‌های به‌ازای هر فرستنده در گروه. از پیشوندهای صریح کلید استفاده کنید: `id:`، `e164:`، `username:`، `name:`، و wildcard `"*"`. کلیدهای قدیمی بدون پیشوند همچنان پذیرفته می‌شوند و فقط به‌عنوان `id:` تطبیق داده می‌شوند. +- `tools`: اجازه/رد کردن ابزارها برای کل گروه. +- `toolsBySender`: بازنویسی‌های هر فرستنده درون گروه. از پیشوندهای کلید صریح استفاده کنید: `id:`، `e164:`، `username:`، `name:`، و wildcard `"*"`. کلیدهای قدیمی بدون پیشوند همچنان پذیرفته می‌شوند و فقط به‌عنوان `id:` تطبیق داده می‌شوند. -ترتیب حل (مشخص‌ترین مورد برنده است): +ترتیب حل‌وفصل (خاص‌ترین مورد برنده است): - `toolsBySender` گروه/کانال تطبیق می‌یابد. + `toolsBySender` گروه/کانال تطبیق می‌خورد. - + `tools` گروه/کانال. - `toolsBySender` پیش‌فرض (`"*"`) تطبیق می‌یابد. + تطبیق `toolsBySender` پیش‌فرض (`"*"`). - - `tools` پیش‌فرض (`"*"`) + + `tools` پیش‌فرض (`"*"`). -مثال (Telegram): +نمونه (Telegram): ```json5 { @@ -388,28 +393,28 @@ otherwise -> reply ``` -محدودیت‌های ابزار گروه/کانال علاوه بر سیاست ابزار سراسری/عامل اعمال می‌شوند (deny همچنان برنده است). برخی کانال‌ها برای اتاق‌ها/کانال‌ها از تودرتوسازی متفاوتی استفاده می‌کنند (برای مثال، Discord `guilds.*.channels.*`، Slack `channels.*`، Microsoft Teams `teams.*.channels.*`). +محدودیت‌های ابزار گروه/کانال علاوه بر خط‌مشی ابزار سراسری/عامل اعمال می‌شوند (رد کردن همچنان برنده است). برخی کانال‌ها از تودرتویی متفاوتی برای اتاق‌ها/کانال‌ها استفاده می‌کنند (مثلا Discord `guilds.*.channels.*`، Slack `channels.*`، Microsoft Teams `teams.*.channels.*`). ## فهرست‌های مجاز گروه -وقتی `channels.whatsapp.groups`، `channels.telegram.groups`، یا `channels.imessage.groups` پیکربندی شود، کلیدها به‌عنوان فهرست مجاز گروه عمل می‌کنند. از `"*"` برای مجاز کردن همه گروه‌ها استفاده کنید، در حالی که همچنان رفتار پیش‌فرض اشاره را تنظیم می‌کنید. +وقتی `channels.whatsapp.groups`، `channels.telegram.groups`، یا `channels.imessage.groups` پیکربندی شده باشد، کلیدها مانند فهرست مجاز گروه عمل می‌کنند. از `"*"` برای مجاز کردن همهٔ گروه‌ها استفاده کنید و هم‌زمان رفتار پیش‌فرض اشاره را تنظیم کنید. -سوءبرداشت رایج: تأیید جفت‌سازی DM با مجوزدهی گروه یکسان نیست. برای کانال‌هایی که از جفت‌سازی DM پشتیبانی می‌کنند، ذخیره جفت‌سازی فقط DMها را باز می‌کند. فرمان‌های گروه همچنان به مجوز صریح فرستنده گروه از فهرست‌های مجاز پیکربندی مانند `groupAllowFrom` یا fallback پیکربندی مستندشده برای آن کانال نیاز دارند. +ابهام رایج: تایید جفت‌سازی DM با مجوز گروه یکسان نیست. برای کانال‌هایی که از جفت‌سازی DM پشتیبانی می‌کنند، ذخیره‌گاه جفت‌سازی فقط DMها را باز می‌کند. فرمان‌های گروه همچنان به مجوز صریح فرستندهٔ گروه از فهرست‌های مجاز پیکربندی مانند `groupAllowFrom` یا پشتیبان پیکربندی مستند همان کانال نیاز دارند. نیت‌های رایج (کپی/پیست): - + ```json5 { channels: { whatsapp: { groupPolicy: "disabled" } }, } ``` - + ```json5 { channels: { @@ -423,7 +428,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -434,7 +439,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -451,42 +456,42 @@ otherwise -> reply ## فعال‌سازی (فقط مالک) -مالکان گروه می‌توانند فعال‌سازی به‌ازای هر گروه را تغییر دهند: +مالکان گروه می‌توانند فعال‌سازی هر گروه را تغییر دهند: - `/activation mention` - `/activation always` -مالک با `channels.whatsapp.allowFrom` تعیین می‌شود (یا E.164 خود بات وقتی تنظیم نشده باشد). فرمان را به‌عنوان یک پیام مستقل ارسال کنید. سطح‌های دیگر در حال حاضر `/activation` را نادیده می‌گیرند. +مالک با `channels.whatsapp.allowFrom` تعیین می‌شود (یا E.164 خود ربات وقتی تنظیم نشده باشد). فرمان را به‌صورت یک پیام مستقل ارسال کنید. سطح‌های دیگر در حال حاضر `/activation` را نادیده می‌گیرند. ## فیلدهای زمینه -payloadهای ورودی گروه این موارد را تنظیم می‌کنند: +payloadهای ورودی گروه تنظیم می‌کنند: - `ChatType=group` - `GroupSubject` (اگر شناخته شده باشد) - `GroupMembers` (اگر شناخته شده باشد) -- `WasMentioned` (نتیجه دروازه‌گذاری اشاره) -- موضوع‌های انجمن Telegram همچنین شامل `MessageThreadId` و `IsForum` هستند. +- `WasMentioned` (نتیجهٔ دروازه‌گذاری اشاره) +- موضوعات تالار Telegram همچنین شامل `MessageThreadId` و `IsForum` هستند. -نکات ویژه کانال: +یادداشت‌های ویژهٔ کانال: -- BlueBubbles می‌تواند به‌صورت اختیاری شرکت‌کنندگان بی‌نام گروه macOS را پیش از پر کردن `GroupMembers` از پایگاه داده Contacts محلی غنی کند. این قابلیت به‌صورت پیش‌فرض خاموش است و فقط پس از عبور دروازه‌گذاری معمول گروه اجرا می‌شود. +- BlueBubbles می‌تواند به‌صورت اختیاری، پیش از پر کردن `GroupMembers`، شرکت‌کنندگان بی‌نام گروه macOS را از پایگاه‌دادهٔ Contacts محلی غنی‌سازی کند. این قابلیت به‌صورت پیش‌فرض خاموش است و فقط پس از عبور دروازه‌گذاری عادی گروه اجرا می‌شود. -پرامپت سیستمی عامل در اولین نوبت یک نشست گروهی جدید شامل یک مقدمه گروهی است. این مقدمه به مدل یادآوری می‌کند مانند انسان پاسخ دهد، از جدول‌های Markdown پرهیز کند، خطوط خالی را به حداقل برساند و فاصله‌گذاری عادی چت را دنبال کند، و از تایپ دنباله‌های لفظی `\n` خودداری کند. نام‌های گروه و برچسب‌های شرکت‌کنندگان که از کانال می‌آیند، به‌عنوان فراداده غیرقابل‌اعتماد در قالب fenced رندر می‌شوند، نه به‌عنوان دستورهای سیستمی inline. +اعلان سیستمی عامل در اولین نوبت یک نشست گروهی جدید، یک مقدمهٔ گروهی دارد. این مقدمه به مدل یادآوری می‌کند مثل انسان پاسخ دهد، از جدول‌های Markdown پرهیز کند، خط‌های خالی را به حداقل برساند و فاصله‌گذاری عادی گفت‌وگو را رعایت کند، و از تایپ دنباله‌های لفظی `\n` خودداری کند. نام‌های گروه و برچسب‌های شرکت‌کنندگان که از کانال می‌آیند به‌صورت فرادادهٔ نامطمئن حصارگذاری‌شده رندر می‌شوند، نه دستورهای سیستمی درون‌خطی. ## جزئیات iMessage -- هنگام مسیریابی یا allowlist کردن، `chat_id:` را ترجیح دهید. -- فهرست کردن چت‌ها: `imsg chats --limit 20`. +- هنگام مسیریابی یا قرار دادن در فهرست مجاز، `chat_id:` را ترجیح دهید. +- فهرست گفت‌وگوها: `imsg chats --limit 20`. - پاسخ‌های گروه همیشه به همان `chat_id` برمی‌گردند. -## پرامپت‌های سیستمی WhatsApp +## اعلان‌های سیستمی WhatsApp -برای قوانین مرجع پرامپت سیستمی WhatsApp، از جمله حل پرامپت گروه و مستقیم، رفتار wildcard، و معناشناسی بازنویسی حساب، به [WhatsApp](/fa/channels/whatsapp#system-prompts) مراجعه کنید. +برای قواعد مرجع اعلان سیستمی WhatsApp، از جمله حل اعلان گروهی و مستقیم، رفتار wildcard، و معناشناسی بازنویسی حساب، به [WhatsApp](/fa/channels/whatsapp#system-prompts) مراجعه کنید. ## جزئیات WhatsApp -برای رفتار فقط-WhatsApp (تزریق تاریخچه، جزئیات مدیریت اشاره)، به [پیام‌های گروهی](/fa/channels/group-messages) مراجعه کنید. +برای رفتار مختص WhatsApp (تزریق تاریخچه، جزئیات مدیریت اشاره) به [پیام‌های گروهی](/fa/channels/group-messages) مراجعه کنید. ## مرتبط diff --git a/docs/fa/channels/signal.md b/docs/fa/channels/signal.md index 15021edbc..66e5957ca 100644 --- a/docs/fa/channels/signal.md +++ b/docs/fa/channels/signal.md @@ -1,14 +1,14 @@ --- read_when: - - راه‌اندازی پشتیبانی از Signal + - راه‌اندازی پشتیبانی Signal - اشکال‌زدایی ارسال/دریافت Signal -summary: پشتیبانی از Signal از طریق signal-cli (JSON-RPC + SSE)، مسیرهای راه‌اندازی و مدل شماره +summary: پشتیبانی از Signal از طریق signal-cli (JSON-RPC + SSE)، مسیرهای راه‌اندازی، و مدل شماره title: Signal x-i18n: - generated_at: "2026-04-29T22:29:22Z" + generated_at: "2026-04-30T16:27:45Z" model: gpt-5.5 provider: openai - source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee + source_hash: 111b6ebe3bde4e03c7ed432f52d663f0b471f0fc4a4bf835c1ac1972467e0b96 source_path: channels/signal.md workflow: 16 --- @@ -17,19 +17,19 @@ x-i18n: ## پیش‌نیازها -- OpenClaw روی سرور شما نصب شده باشد (جریان Linux زیر روی Ubuntu 24 آزمایش شده است). -- `signal-cli` روی میزبانی که Gateway اجرا می‌شود در دسترس باشد. +- OpenClaw روی سرور شما نصب شده باشد (روند Linux زیر روی Ubuntu 24 آزمایش شده است). +- `signal-cli` روی میزبانی که gateway روی آن اجرا می‌شود در دسترس باشد. - یک شماره تلفن که بتواند یک پیامک تأیید دریافت کند (برای مسیر ثبت‌نام با SMS). - دسترسی مرورگر برای کپچای Signal (`signalcaptchas.org`) هنگام ثبت‌نام. ## راه‌اندازی سریع (مبتدی) -1. از یک **شماره Signal جداگانه** برای بات استفاده کنید (توصیه می‌شود). -2. `signal-cli` را نصب کنید (اگر از ساخت JVM استفاده می‌کنید، Java لازم است). -3. یک مسیر راه‌اندازی را انتخاب کنید: +1. برای ربات از یک **شماره Signal جداگانه** استفاده کنید (توصیه می‌شود). +2. `signal-cli` را نصب کنید (اگر از نسخه JVM استفاده می‌کنید، Java لازم است). +3. یک مسیر راه‌اندازی انتخاب کنید: - **مسیر A (پیوند QR):** `signal-cli link -n "OpenClaw"` و با Signal اسکن کنید. - **مسیر B (ثبت‌نام SMS):** یک شماره اختصاصی را با کپچا + تأیید SMS ثبت کنید. -4. OpenClaw را پیکربندی کنید و Gateway را دوباره راه‌اندازی کنید. +4. OpenClaw را پیکربندی کنید و gateway را بازراه‌اندازی کنید. 5. اولین DM را بفرستید و جفت‌سازی را تأیید کنید (`openclaw pairing approve signal `). پیکربندی حداقلی: @@ -52,12 +52,12 @@ x-i18n: | فیلد | توضیح | | ----------- | ------------------------------------------------- | -| `account` | شماره تلفن بات در قالب E.164 (`+15551234567`) | -| `cliPath` | مسیر `signal-cli` (`signal-cli` اگر روی `PATH` باشد) | +| `account` | شماره تلفن ربات با قالب E.164 (`+15551234567`) | +| `cliPath` | مسیر `signal-cli` (`signal-cli` اگر در `PATH` باشد) | | `dmPolicy` | سیاست دسترسی DM (`pairing` توصیه می‌شود) | -| `allowFrom` | شماره‌های تلفن یا مقادیر `uuid:` که مجاز به DM هستند | +| `allowFrom` | شماره‌های تلفن یا مقدارهای `uuid:` که مجاز به ارسال DM هستند | -## چیست +## چیستی آن - کانال Signal از طریق `signal-cli` (نه libsignal تعبیه‌شده). - مسیریابی قطعی: پاسخ‌ها همیشه به Signal برمی‌گردند. @@ -65,7 +65,7 @@ x-i18n: ## نوشتن پیکربندی -به‌صورت پیش‌فرض، Signal مجاز است به‌روزرسانی‌های پیکربندی را که با `/config set|unset` فعال می‌شوند بنویسد (به `commands.config: true` نیاز دارد). +به‌طور پیش‌فرض، Signal مجاز است به‌روزرسانی‌های پیکربندی را که با `/config set|unset` آغاز می‌شوند بنویسد (به `commands.config: true` نیاز دارد). غیرفعال‌سازی با: @@ -77,16 +77,16 @@ x-i18n: ## مدل شماره (مهم) -- Gateway به یک **دستگاه Signal** متصل می‌شود (حساب `signal-cli`). -- اگر بات را روی **حساب Signal شخصی خودتان** اجرا کنید، پیام‌های خودتان را نادیده می‌گیرد (محافظت حلقه). -- برای «من به بات پیام می‌دهم و جواب می‌دهد»، از یک **شماره بات جداگانه** استفاده کنید. +- Gateway به یک **دستگاه Signal** وصل می‌شود (حساب `signal-cli`). +- اگر ربات را روی **حساب شخصی Signal خودتان** اجرا کنید، پیام‌های خودتان را نادیده می‌گیرد (محافظت در برابر حلقه). +- برای «من به ربات پیام می‌دهم و پاسخ می‌دهد»، از یک **شماره ربات جداگانه** استفاده کنید. -## مسیر راه‌اندازی A: پیوند دادن حساب Signal موجود (QR) +## مسیر راه‌اندازی A: پیوند حساب Signal موجود (QR) -1. `signal-cli` را نصب کنید (ساخت JVM یا native). -2. یک حساب بات را پیوند دهید: +1. `signal-cli` را نصب کنید (نسخه JVM یا native). +2. یک حساب ربات را پیوند دهید: - `signal-cli link -n "OpenClaw"` سپس QR را در Signal اسکن کنید. -3. Signal را پیکربندی کنید و Gateway را راه‌اندازی کنید. +3. Signal را پیکربندی کنید و gateway را شروع کنید. مثال: @@ -104,15 +104,15 @@ x-i18n: } ``` -پشتیبانی چندحسابی: از `channels.signal.accounts` با پیکربندی جداگانه برای هر حساب و `name` اختیاری استفاده کنید. برای الگوی مشترک، [`gateway/configuration`](/fa/gateway/config-channels#multi-account-all-channels) را ببینید. +پشتیبانی از چند حساب: از `channels.signal.accounts` همراه با پیکربندی برای هر حساب و `name` اختیاری استفاده کنید. برای الگوی مشترک، [`gateway/configuration`](/fa/gateway/config-channels#multi-account-all-channels) را ببینید. -## مسیر راه‌اندازی B: ثبت شماره بات اختصاصی (SMS، Linux) +## مسیر راه‌اندازی B: ثبت شماره ربات اختصاصی (SMS، Linux) -وقتی می‌خواهید به‌جای پیوند دادن یک حساب موجود در برنامه Signal، یک شماره بات اختصاصی داشته باشید، از این روش استفاده کنید. +وقتی به‌جای پیوند دادن یک حساب برنامه Signal موجود، یک شماره ربات اختصاصی می‌خواهید، از این روش استفاده کنید. 1. شماره‌ای بگیرید که بتواند SMS دریافت کند (یا تأیید صوتی برای خطوط ثابت). - - برای جلوگیری از تداخل حساب/نشست، از یک شماره بات اختصاصی استفاده کنید. -2. `signal-cli` را روی میزبان Gateway نصب کنید: + - برای جلوگیری از تداخل حساب/نشست، از یک شماره ربات اختصاصی استفاده کنید. +2. `signal-cli` را روی میزبان gateway نصب کنید: ```bash VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') @@ -122,8 +122,8 @@ sudo ln -sf /opt/signal-cli /usr/local/bin/ signal-cli --version ``` -اگر از ساخت JVM (`signal-cli-${VERSION}.tar.gz`) استفاده می‌کنید، ابتدا JRE 25+ را نصب کنید. -`signal-cli` را به‌روز نگه دارید؛ بالادست اشاره می‌کند که نسخه‌های قدیمی ممکن است با تغییر APIهای سرور Signal از کار بیفتند. +اگر از نسخه JVM (`signal-cli-${VERSION}.tar.gz`) استفاده می‌کنید، ابتدا JRE 25+ را نصب کنید. +`signal-cli` را به‌روز نگه دارید؛ upstream یادآوری می‌کند که نسخه‌های قدیمی ممکن است با تغییر APIهای سرور Signal از کار بیفتند. 3. شماره را ثبت و تأیید کنید: @@ -134,7 +134,7 @@ signal-cli -a + register اگر کپچا لازم است: 1. `https://signalcaptchas.org/registration/generate.html` را باز کنید. -2. کپچا را کامل کنید، هدف لینک `signalcaptcha://...` را از "Open Signal" کپی کنید. +2. کپچا را کامل کنید، هدف پیوند `signalcaptcha://...` را از "Open Signal" کپی کنید. 3. در صورت امکان، از همان IP خارجی نشست مرورگر اجرا کنید. 4. ثبت‌نام را بلافاصله دوباره اجرا کنید (توکن‌های کپچا سریع منقضی می‌شوند): @@ -143,7 +143,7 @@ signal-cli -a + register --captcha '' signal-cli -a + verify ``` -4. OpenClaw را پیکربندی کنید، Gateway را دوباره راه‌اندازی کنید، کانال را تأیید کنید: +4. OpenClaw را پیکربندی کنید، gateway را بازراه‌اندازی کنید، کانال را تأیید کنید: ```bash # If you run the gateway as a user systemd service: @@ -155,23 +155,23 @@ openclaw channels status --probe ``` 5. فرستنده DM خود را جفت کنید: - - هر پیامی را به شماره بات بفرستید. + - هر پیامی را به شماره ربات بفرستید. - کد را روی سرور تأیید کنید: `openclaw pairing approve signal `. - - شماره بات را به‌عنوان مخاطب روی تلفن خود ذخیره کنید تا از "Unknown contact" جلوگیری شود. + - شماره ربات را روی تلفن خود به‌عنوان مخاطب ذخیره کنید تا از "Unknown contact" جلوگیری شود. -ثبت یک حساب شماره تلفن با `signal-cli` می‌تواند نشست اصلی برنامه Signal را برای آن شماره از اعتبار خارج کند. یک شماره بات اختصاصی را ترجیح دهید، یا اگر لازم است تنظیمات برنامه تلفن موجود خود را حفظ کنید از حالت پیوند QR استفاده کنید. +ثبت یک حساب شماره تلفن با `signal-cli` می‌تواند نشست اصلی برنامه Signal را برای آن شماره از احراز خارج کند. یک شماره ربات اختصاصی را ترجیح دهید، یا اگر لازم است تنظیمات برنامه تلفن موجود خود را نگه دارید از حالت پیوند QR استفاده کنید. -ارجاع‌های بالادست: +مراجع upstream: - README مربوط به `signal-cli`: `https://github.com/AsamK/signal-cli` -- جریان کپچا: `https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` -- جریان پیوند دادن: `https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` +- روند کپچا: `https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` +- روند پیوند: `https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` ## حالت daemon خارجی (httpUrl) -اگر می‌خواهید خودتان `signal-cli` را مدیریت کنید (شروع سرد کند JVM، init کانتینر، یا CPUهای مشترک)، daemon را جداگانه اجرا کنید و OpenClaw را به آن اشاره دهید: +اگر می‌خواهید خودتان `signal-cli` را مدیریت کنید (شروع سرد کند JVM، مقداردهی اولیه کانتینر، یا CPUهای مشترک)، daemon را جداگانه اجرا کنید و OpenClaw را به آن اشاره دهید: ```json5 { @@ -191,48 +191,49 @@ openclaw channels status --probe DMها: - پیش‌فرض: `channels.signal.dmPolicy = "pairing"`. -- فرستندگان ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ پیام‌ها تا زمان تأیید نادیده گرفته می‌شوند (کدها پس از 1 ساعت منقضی می‌شوند). +- فرستنده‌های ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ پیام‌ها تا زمان تأیید نادیده گرفته می‌شوند (کدها پس از 1 ساعت منقضی می‌شوند). - تأیید از طریق: - `openclaw pairing list signal` - `openclaw pairing approve signal ` -- جفت‌سازی، تبادل توکن پیش‌فرض برای DMهای Signal است. جزئیات: [جفت‌سازی](/fa/channels/pairing) -- فرستندگان فقط-UUID (از `sourceUuid`) به‌صورت `uuid:` در `channels.signal.allowFrom` ذخیره می‌شوند. +- جفت‌سازی تبادل توکن پیش‌فرض برای DMهای Signal است. جزئیات: [جفت‌سازی](/fa/channels/pairing) +- فرستنده‌های فقط UUID (از `sourceUuid`) به‌صورت `uuid:` در `channels.signal.allowFrom` ذخیره می‌شوند. گروه‌ها: - `channels.signal.groupPolicy = open | allowlist | disabled`. -- `channels.signal.groupAllowFrom` کنترل می‌کند وقتی `allowlist` تنظیم شده است چه کسی می‌تواند در گروه‌ها فعال‌سازی کند. +- `channels.signal.groupAllowFrom` کنترل می‌کند وقتی `allowlist` تنظیم شده است، کدام گروه‌ها یا فرستنده‌ها می‌توانند پاسخ‌های گروهی را فعال کنند؛ ورودی‌ها می‌توانند شناسه‌های گروه Signal (خام، `group:`، یا `signal:group:`)، شماره‌های تلفن فرستنده، مقدارهای `uuid:`، یا `*` باشند. - `channels.signal.groups["" | "*"]` می‌تواند رفتار گروه را با `requireMention`، `tools`، و `toolsBySender` بازنویسی کند. -- برای بازنویسی‌های جداگانه هر حساب در راه‌اندازی‌های چندحسابی، از `channels.signal.accounts..groups` استفاده کنید. -- نکته زمان اجرا: اگر `channels.signal` کاملاً وجود نداشته باشد، زمان اجرا برای بررسی‌های گروه به `groupPolicy="allowlist"` برمی‌گردد (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). +- برای بازنویسی‌های هر حساب در تنظیمات چندحسابی، از `channels.signal.accounts..groups` استفاده کنید. +- قراردادن یک گروه Signal در allowlist از طریق `groupAllowFrom` به‌تنهایی گیت mention را غیرفعال نمی‌کند. یک ورودی مشخصاً پیکربندی‌شده `channels.signal.groups[""]` همه پیام‌های گروه را پردازش می‌کند مگر اینکه `requireMention=true` تنظیم شده باشد. +- نکته زمان اجرا: اگر `channels.signal` کاملاً وجود نداشته باشد، runtime برای بررسی‌های گروهی به `groupPolicy="allowlist"` برمی‌گردد (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). -## چگونه کار می‌کند (رفتار) +## نحوه کارکرد (رفتار) -- `signal-cli` به‌صورت daemon اجرا می‌شود؛ Gateway رویدادها را از طریق SSE می‌خواند. +- `signal-cli` به‌عنوان daemon اجرا می‌شود؛ gateway رویدادها را از طریق SSE می‌خواند. - پیام‌های ورودی به پاکت مشترک کانال نرمال‌سازی می‌شوند. - پاسخ‌ها همیشه به همان شماره یا گروه برمی‌گردند. ## رسانه + محدودیت‌ها -- متن خروجی تا `channels.signal.textChunkLimit` تکه‌تکه می‌شود (پیش‌فرض 4000). -- تکه‌تکه‌سازی اختیاری بر اساس خط جدید: `channels.signal.chunkMode="newline"` را تنظیم کنید تا قبل از تکه‌تکه‌سازی بر اساس طول، روی خطوط خالی (مرزهای پاراگراف) تقسیم شود. +- متن خروجی به `channels.signal.textChunkLimit` تکه‌تکه می‌شود (پیش‌فرض 4000). +- تکه‌بندی اختیاری بر اساس خط جدید: `channels.signal.chunkMode="newline"` را تنظیم کنید تا قبل از تکه‌بندی بر اساس طول، روی خطوط خالی (مرزهای پاراگراف) تقسیم شود. - پیوست‌ها پشتیبانی می‌شوند (base64 از `signal-cli` دریافت می‌شود). -- پیوست‌های یادداشت صوتی وقتی `contentType` وجود ندارد، از نام فایل `signal-cli` به‌عنوان fallback نوع MIME استفاده می‌کنند، بنابراین رونویسی صوت همچنان می‌تواند یادداشت‌های صوتی AAC را طبقه‌بندی کند. -- سقف رسانه پیش‌فرض: `channels.signal.mediaMaxMb` (پیش‌فرض 8). -- برای رد کردن دانلود رسانه از `channels.signal.ignoreAttachments` استفاده کنید. -- زمینه تاریخچه گروه از `channels.signal.historyLimit` (یا `channels.signal.accounts.*.historyLimit`) استفاده می‌کند و به `messages.groupChat.historyLimit` fallback می‌کند. برای غیرفعال‌سازی `0` را تنظیم کنید (پیش‌فرض 50). +- پیوست‌های voice-note وقتی `contentType` وجود ندارد، از نام فایل `signal-cli` به‌عنوان fallback برای MIME استفاده می‌کنند، بنابراین رونویسی صدا همچنان می‌تواند یادداشت‌های صوتی AAC را دسته‌بندی کند. +- سقف پیش‌فرض رسانه: `channels.signal.mediaMaxMb` (پیش‌فرض 8). +- برای رد کردن دانلود رسانه، از `channels.signal.ignoreAttachments` استفاده کنید. +- زمینه تاریخچه گروه از `channels.signal.historyLimit` (یا `channels.signal.accounts.*.historyLimit`) استفاده می‌کند و به `messages.groupChat.historyLimit` برمی‌گردد. برای غیرفعال‌سازی، `0` را تنظیم کنید (پیش‌فرض 50). ## تایپ کردن + رسیدهای خواندن - **نشانگرهای تایپ**: OpenClaw سیگنال‌های تایپ را از طریق `signal-cli sendTyping` می‌فرستد و هنگام اجرای پاسخ آن‌ها را تازه‌سازی می‌کند. -- **رسیدهای خواندن**: وقتی `channels.signal.sendReadReceipts` برابر true باشد، OpenClaw رسیدهای خواندن را برای DMهای مجاز فوروارد می‌کند. -- signal-cli رسیدهای خواندن را برای گروه‌ها در معرض نمی‌گذارد. +- **رسیدهای خواندن**: وقتی `channels.signal.sendReadReceipts` برابر true باشد، OpenClaw رسیدهای خواندن را برای DMهای مجاز ارسال می‌کند. +- Signal-cli رسیدهای خواندن را برای گروه‌ها ارائه نمی‌کند. ## واکنش‌ها (ابزار پیام) - از `message action=react` با `channel=signal` استفاده کنید. -- هدف‌ها: فرستنده E.164 یا UUID (از `uuid:` در خروجی جفت‌سازی استفاده کنید؛ UUID تنها نیز کار می‌کند). -- `messageId` همان timestamp مربوط به Signal برای پیامی است که به آن واکنش می‌دهید. +- هدف‌ها: E.164 فرستنده یا UUID (از `uuid:` خروجی جفت‌سازی استفاده کنید؛ UUID خام هم کار می‌کند). +- `messageId` همان timestamp پیام Signal است که به آن واکنش می‌دهید. - واکنش‌های گروهی به `targetAuthor` یا `targetAuthorUuid` نیاز دارند. مثال‌ها: @@ -249,12 +250,12 @@ message action=react channel=signal target=signal:group: targetAuthor=u - `channels.signal.reactionLevel`: `off | ack | minimal | extensive`. - `off`/`ack` واکنش‌های عامل را غیرفعال می‌کند (ابزار پیام `react` خطا می‌دهد). - `minimal`/`extensive` واکنش‌های عامل را فعال می‌کند و سطح راهنمایی را تنظیم می‌کند. -- بازنویسی‌های جداگانه هر حساب: `channels.signal.accounts..actions.reactions`، `channels.signal.accounts..reactionLevel`. +- بازنویسی‌های هر حساب: `channels.signal.accounts..actions.reactions`، `channels.signal.accounts..reactionLevel`. ## هدف‌های تحویل (CLI/cron) - DMها: `signal:+15551234567` (یا E.164 ساده). -- DMهای UUID: `uuid:` (یا UUID تنها). +- DMهای UUID: `uuid:` (یا UUID خام). - گروه‌ها: `signal:group:`. - نام‌های کاربری: `username:` (اگر حساب Signal شما پشتیبانی کند). @@ -278,11 +279,11 @@ openclaw pairing list signal خرابی‌های رایج: -- daemon در دسترس است اما پاسخی وجود ندارد: تنظیمات حساب/daemon (`httpUrl`، `account`) و حالت دریافت را بررسی کنید. +- Daemon در دسترس است اما پاسخی وجود ندارد: تنظیمات حساب/daemon (`httpUrl`، `account`) و حالت دریافت را بررسی کنید. - DMها نادیده گرفته می‌شوند: فرستنده در انتظار تأیید جفت‌سازی است. -- پیام‌های گروهی نادیده گرفته می‌شوند: دروازه‌گذاری فرستنده/mention گروه تحویل را مسدود می‌کند. +- پیام‌های گروه نادیده گرفته می‌شوند: گیت فرستنده/mention گروه مانع تحویل می‌شود. - خطاهای اعتبارسنجی پیکربندی پس از ویرایش‌ها: `openclaw doctor --fix` را اجرا کنید. -- Signal در عیب‌یابی دیده نمی‌شود: تأیید کنید `channels.signal.enabled: true`. +- Signal در diagnostics وجود ندارد: تأیید کنید `channels.signal.enabled: true`. بررسی‌های اضافی: @@ -292,54 +293,54 @@ pgrep -af signal-cli grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 ``` -برای جریان تریاژ: [/channels/troubleshooting](/fa/channels/troubleshooting). +برای روند triage: [/channels/troubleshooting](/fa/channels/troubleshooting). ## نکات امنیتی - `signal-cli` کلیدهای حساب را به‌صورت محلی ذخیره می‌کند (معمولاً `~/.local/share/signal-cli/data/`). - پیش از مهاجرت یا بازسازی سرور، از وضعیت حساب Signal نسخه پشتیبان بگیرید. -- `channels.signal.dmPolicy: "pairing"` را نگه دارید مگر اینکه صراحتاً دسترسی گسترده‌تر DM بخواهید. -- تأیید SMS فقط برای جریان‌های ثبت‌نام یا بازیابی لازم است، اما از دست دادن کنترل شماره/حساب می‌تواند ثبت‌نام دوباره را پیچیده کند. +- `channels.signal.dmPolicy: "pairing"` را حفظ کنید مگر اینکه صریحاً دسترسی گسترده‌تر DM را بخواهید. +- تأیید SMS فقط برای روندهای ثبت‌نام یا بازیابی لازم است، اما از دست دادن کنترل شماره/حساب می‌تواند ثبت‌نام دوباره را پیچیده کند. ## مرجع پیکربندی (Signal) پیکربندی کامل: [پیکربندی](/fa/gateway/configuration) -گزینه‌های ارائه‌دهنده: +گزینه‌های provider: -- `channels.signal.enabled`: فعال/غیرفعال کردن راه‌اندازی کانال. -- `channels.signal.account`: قالب E.164 برای حساب ربات. +- `channels.signal.enabled`: راه‌اندازی کانال را فعال/غیرفعال می‌کند. +- `channels.signal.account`: E.164 برای حساب ربات. - `channels.signal.cliPath`: مسیر `signal-cli`. -- `channels.signal.httpUrl`: URL کامل دیمون (میزبان/درگاه را نادیده می‌گیرد). -- `channels.signal.httpHost`, `channels.signal.httpPort`: اتصال دیمون (پیش‌فرض 127.0.0.1:8080). -- `channels.signal.autoStart`: ایجاد خودکار دیمون (اگر `httpUrl` تنظیم نشده باشد، پیش‌فرض true است). -- `channels.signal.startupTimeoutMs`: مهلت انتظار راه‌اندازی بر حسب میلی‌ثانیه (حداکثر 120000). +- `channels.signal.httpUrl`: URL کامل دیمون (host/port را بازنویسی می‌کند). +- `channels.signal.httpHost`, `channels.signal.httpPort`: bind دیمون (پیش‌فرض 127.0.0.1:8080). +- `channels.signal.autoStart`: دیمون را به‌صورت خودکار اجرا می‌کند (اگر `httpUrl` تنظیم نشده باشد، پیش‌فرض true است). +- `channels.signal.startupTimeoutMs`: مهلت انتظار راه‌اندازی بر حسب ms (حداکثر 120000). - `channels.signal.receiveMode`: `on-start | manual`. -- `channels.signal.ignoreAttachments`: از دانلود پیوست‌ها صرف‌نظر می‌کند. +- `channels.signal.ignoreAttachments`: بارگیری پیوست‌ها را رد می‌کند. - `channels.signal.ignoreStories`: استوری‌های دیمون را نادیده می‌گیرد. -- `channels.signal.sendReadReceipts`: رسیدهای خواندن را ارسال می‌کند. +- `channels.signal.sendReadReceipts`: رسیدهای خوانده‌شدن را بازفرست می‌کند. - `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (پیش‌فرض: pairing). - `channels.signal.allowFrom`: فهرست مجاز DM (E.164 یا `uuid:`). `open` به `"*"` نیاز دارد. Signal نام کاربری ندارد؛ از شناسه‌های تلفن/UUID استفاده کنید. - `channels.signal.groupPolicy`: `open | allowlist | disabled` (پیش‌فرض: allowlist). -- `channels.signal.groupAllowFrom`: فهرست مجاز فرستنده‌های گروه. -- `channels.signal.groups`: بازنویسی‌های به‌ازای هر گروه که با شناسه گروه Signal (یا `"*"`) کلیدگذاری شده‌اند. فیلدهای پشتیبانی‌شده: `requireMention`, `tools`, `toolsBySender`. -- `channels.signal.accounts..groups`: نسخه به‌ازای هر حساب از `channels.signal.groups` برای تنظیمات چندحسابی. -- `channels.signal.historyLimit`: حداکثر پیام‌های گروهی که به‌عنوان زمینه شامل می‌شوند (0 غیرفعال می‌کند). -- `channels.signal.dmHistoryLimit`: حد تاریخچه DM بر حسب نوبت‌های کاربر. بازنویسی‌های به‌ازای هر کاربر: `channels.signal.dms[""].historyLimit`. -- `channels.signal.textChunkLimit`: اندازه قطعه خروجی (کاراکتر). -- `channels.signal.chunkMode`: `length` (پیش‌فرض) یا `newline` برای تقسیم بر اساس خطوط خالی (مرزهای پاراگراف) پیش از قطعه‌بندی بر اساس طول. -- `channels.signal.mediaMaxMb`: سقف رسانه ورودی/خروجی (مگابایت). +- `channels.signal.groupAllowFrom`: فهرست مجاز گروه؛ شناسه‌های گروه Signal (خام، `group:`، یا `signal:group:`)، شماره‌های E.164 فرستنده، یا مقدارهای `uuid:` را می‌پذیرد. +- `channels.signal.groups`: بازنویسی‌های هر گروه که با شناسه گروه Signal (یا `"*"`) کلیدگذاری شده‌اند. فیلدهای پشتیبانی‌شده: `requireMention`، `tools`، `toolsBySender`. +- `channels.signal.accounts..groups`: نسخه هر حساب از `channels.signal.groups` برای راه‌اندازی‌های چندحسابی. +- `channels.signal.historyLimit`: حداکثر پیام‌های گروه که به‌عنوان زمینه گنجانده می‌شوند (0 غیرفعال می‌کند). +- `channels.signal.dmHistoryLimit`: محدودیت تاریخچه DM بر حسب نوبت‌های کاربر. بازنویسی‌های هر کاربر: `channels.signal.dms[""].historyLimit`. +- `channels.signal.textChunkLimit`: اندازه قطعه خروجی (نویسه). +- `channels.signal.chunkMode`: `length` (پیش‌فرض) یا `newline` برای تقسیم بر اساس خط‌های خالی (مرزهای پاراگراف) پیش از قطعه‌بندی بر اساس طول. +- `channels.signal.mediaMaxMb`: سقف رسانه ورودی/خروجی (MB). گزینه‌های سراسری مرتبط: - `agents.list[].groupChat.mentionPatterns` (Signal از منشن‌های بومی پشتیبانی نمی‌کند). -- `messages.groupChat.mentionPatterns` (پشتیبان سراسری). +- `messages.groupChat.mentionPatterns` (جایگزین سراسری). - `messages.responsePrefix`. ## مرتبط - [نمای کلی کانال‌ها](/fa/channels) — همه کانال‌های پشتیبانی‌شده - [جفت‌سازی](/fa/channels/pairing) — احراز هویت DM و جریان جفت‌سازی -- [گروه‌ها](/fa/channels/groups) — رفتار گفتگوی گروهی و کنترل مبتنی بر منشن +- [گروه‌ها](/fa/channels/groups) — رفتار گفت‌وگوی گروهی و gating منشن - [مسیریابی کانال](/fa/channels/channel-routing) — مسیریابی نشست برای پیام‌ها -- [امنیت](/fa/gateway/security) — مدل دسترسی و مقاوم‌سازی +- [امنیت](/fa/gateway/security) — مدل دسترسی و سخت‌سازی diff --git a/docs/fa/channels/slack.md b/docs/fa/channels/slack.md index 03e0ab6ca..4d6a7acd8 100644 --- a/docs/fa/channels/slack.md +++ b/docs/fa/channels/slack.md @@ -1,49 +1,49 @@ --- read_when: - - راه‌اندازی Slack یا اشکال‌زدایی از حالت سوکت/HTTP در Slack -summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت سوکت + URLهای درخواست HTTP) + - راه‌اندازی Slack یا اشکال‌زدایی حالت سوکت/HTTP در Slack +summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت سوکت + نشانی‌های URL درخواست HTTP) title: Slack x-i18n: - generated_at: "2026-04-29T22:29:18Z" + generated_at: "2026-04-30T16:27:40Z" model: gpt-5.5 provider: openai - source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127 + source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6 source_path: channels/slack.md workflow: 16 --- -آماده برای تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های اپ Slack. حالت پیش‌فرض Socket Mode است؛ HTTP Request URLs نیز پشتیبانی می‌شوند. +آمادهٔ تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های اپ Slack. حالت پیش‌فرض، حالت سوکت است؛ URLهای درخواست HTTP نیز پشتیبانی می‌شوند. پیام‌های مستقیم Slack به‌طور پیش‌فرض از حالت جفت‌سازی استفاده می‌کنند. - - رفتار دستورهای بومی و کاتالوگ دستورها. + + رفتار فرمان بومی و کاتالوگ فرمان‌ها. - عیب‌یابی بین‌کانالی و راهنماهای تعمیر. + عیب‌یابی‌های میان‌کانالی و راهنماهای ترمیم. ## راه‌اندازی سریع - + - - در تنظیمات اپ Slack، دکمه **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: + + در تنظیمات اپ Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: - - **from a manifest** را انتخاب کنید و یک workspace برای اپ خود برگزینید - - [مانیفست نمونه](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید + - گزینهٔ **from a manifest** را انتخاب کنید و یک workspace برای اپ خود برگزینید + - [مانیفست نمونه](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ساخت ادامه دهید - یک **App-Level Token** (`xapp-...`) با `connections:write` تولید کنید - اپ را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید - + - راه‌اندازی پیشنهادی SecretRef: + راه‌اندازی SecretRef پیشنهادی: ```bash export SLACK_APP_TOKEN=xapp-... @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,21 +84,21 @@ openclaw gateway - + - - در تنظیمات اپ Slack، دکمه **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: + + در تنظیمات اپ Slack دکمهٔ **[Create New App](https://api.slack.com/apps/new)** را فشار دهید: - - **from a manifest** را انتخاب کنید و یک workspace برای اپ خود برگزینید - - [مانیفست نمونه](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید - - **Signing Secret** را برای راستی‌آزمایی درخواست ذخیره کنید + - گزینهٔ **from a manifest** را انتخاب کنید و یک workspace برای اپ خود برگزینید + - [مانیفست نمونه](#manifest-and-scope-checklist) را جای‌گذاری کنید و URLها را پیش از ساخت به‌روزرسانی کنید + - **Signing Secret** را برای تأیید درخواست ذخیره کنید - اپ را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید - + - راه‌اندازی پیشنهادی SecretRef: + راه‌اندازی SecretRef پیشنهادی: ```bash export SLACK_BOT_TOKEN=xoxb-... @@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5 ``` - برای HTTP چندحسابی از مسیرهای webhook یکتا استفاده کنید + برای HTTP چندحسابی از مسیرهای Webhook یکتا استفاده کنید - به هر حساب یک `webhookPath` متمایز (پیش‌فرض `/slack/events`) بدهید تا ثبت‌ها با هم تداخل نداشته باشند. + به هر حساب یک `webhookPath` متمایز بدهید (پیش‌فرض `/slack/events`) تا ثبت‌ها با هم تداخل نداشته باشند. - + ```bash openclaw gateway @@ -140,9 +140,9 @@ openclaw gateway -## تنظیم انتقال Socket Mode +## تنظیم انتقال در حالت سوکت -OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت Slack SDK را برای Socket Mode روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط زمانی بازنویسی کنید که به تنظیم ویژه workspace یا میزبان نیاز دارید: +OpenClaw به‌طور پیش‌فرض مهلت pong کلاینت SDK Slack را برای حالت سوکت روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط زمانی بازنویسی کنید که به تنظیمات ویژهٔ workspace یا میزبان نیاز دارید: ```json5 { @@ -159,13 +159,13 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت } ``` -این را فقط برای workspaceهای Socket Mode استفاده کنید که timeoutهای websocket pong/server-ping مربوط به Slack را ثبت می‌کنند یا روی میزبان‌هایی با گرسنگی شناخته‌شده event-loop اجرا می‌شوند. `clientPingTimeout` زمان انتظار برای pong پس از ارسال ping کلاینت توسط SDK است؛ `serverPingTimeout` زمان انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای اپ وضعیت برنامه هستند، نه سیگنال‌های زنده‌بودن انتقال. +این را فقط برای workspaceهای حالت سوکتی استفاده کنید که مهلت‌های Slack websocket pong/server-ping را ثبت می‌کنند یا روی میزبان‌هایی اجرا می‌شوند که گرسنگی event-loop شناخته‌شده دارند. `clientPingTimeout` مدت انتظار pong پس از ارسال ping کلاینت توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای اپ، وضعیت برنامه باقی می‌مانند، نه سیگنال‌های زنده‌بودن انتقال. ## چک‌لیست مانیفست و scope -مانیفست پایه اپ Slack برای Socket Mode و HTTP Request URLs یکسان است. فقط بلوک `settings` (و `url` دستور اسلش) متفاوت است. +مانیفست پایهٔ اپ Slack برای حالت سوکت و URLهای درخواست HTTP یکسان است. فقط بلوک `settings` (و `url` فرمان اسلش) متفاوت است. -مانیفست پایه (پیش‌فرض Socket Mode): +مانیفست پایه (پیش‌فرض حالت سوکت): ```json { @@ -237,7 +237,7 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت } ``` -برای حالت **HTTP Request URLs**، `settings` را با گونه HTTP جایگزین کنید و به هر دستور اسلش `url` اضافه کنید. URL عمومی لازم است: +برای **حالت URLهای درخواست HTTP**، `settings` را با نوع HTTP جایگزین کنید و به هر فرمان اسلش `url` اضافه کنید. URL عمومی لازم است: ```json { @@ -267,22 +267,22 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت } ``` -### تنظیمات مانیفست اضافی +### تنظیمات تکمیلی مانیفست قابلیت‌های متفاوتی را ارائه کنید که پیش‌فرض‌های بالا را گسترش می‌دهند. - + - می‌توان به‌جای یک دستور پیکربندی‌شده واحد، از چندین [دستور اسلش بومی](#commands-and-slash-behavior) با جزئیات بیشتر استفاده کرد: + چندین [فرمان اسلش بومی](#commands-and-slash-behavior) می‌توانند به‌جای یک فرمان پیکربندی‌شدهٔ واحد با جزئیات بیشتر استفاده شوند: - - از `/agentstatus` به‌جای `/status` استفاده کنید، چون دستور `/status` رزرو شده است. - - در هر زمان نمی‌توان بیش از ۲۵ دستور اسلش را در دسترس قرار داد. + - از `/agentstatus` به‌جای `/status` استفاده کنید، چون فرمان `/status` رزرو شده است. + - بیش از ۲۵ فرمان اسلش را نمی‌توان هم‌زمان در دسترس قرار داد. - بخش موجود `features.slash_commands` خود را با زیرمجموعه‌ای از [دستورهای موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: + بخش `features.slash_commands` فعلی خود را با زیرمجموعه‌ای از [فرمان‌های موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: - + ```json "slash_commands": [ @@ -398,8 +398,8 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت ``` - - از همان فهرست `slash_commands` مانند Socket Mode بالا استفاده کنید و به هر مورد `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: + + از همان فهرست `slash_commands` حالت سوکت بالا استفاده کنید، و به هر ورودی `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: ```json "slash_commands": [ @@ -422,14 +422,14 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت - - اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض اپ Slack از هویت عامل فعال (نام کاربری و آیکون سفارشی) استفاده کنند، scope ربات `chat:write.customize` را اضافه کنید. + + اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض اپ Slack از هویت عامل فعال (نام کاربری و نماد سفارشی) استفاده کنند، scope ربات `chat:write.customize` را اضافه کنید. - اگر از آیکون emoji استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد. + اگر از نماد ایموجی استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد. - - اگر `channels.slack.userToken` را پیکربندی می‌کنید، scopeهای معمول خواندن عبارت‌اند از: + + اگر `channels.slack.userToken` را پیکربندی می‌کنید، scopeهای خواندن معمول عبارت‌اند از: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -437,7 +437,7 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (اگر به خواندن جست‌وجوی Slack وابسته هستید) + - `search:read` (اگر به خواندن‌های جستجوی Slack وابسته هستید) @@ -446,34 +446,34 @@ OpenClaw به‌طور پیش‌فرض timeout مربوط به pong کلاینت - `botToken` + `appToken` برای Socket Mode الزامی هستند. - حالت HTTP به `botToken` + `signingSecret` نیاز دارد. -- `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های متنی ساده +- `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های متن ساده یا اشیای SecretRef را می‌پذیرند. -- توکن‌های پیکربندی جایگزین env fallback می‌شوند. -- env fallback مربوط به `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. -- `userToken` (`xoxp-...`) فقط در پیکربندی تنظیم می‌شود (env fallback ندارد) و به‌طور پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`). +- توکن‌های پیکربندی، جایگزین fallback محیطی می‌شوند. +- fallback محیطی `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. +- `userToken` (`xoxp-...`) فقط از طریق پیکربندی است (بدون fallback محیطی) و به‌صورت پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`). رفتار نمای وضعیت: -- بازرسی حساب Slack برای هر credential فیلدهای `*Source` و `*Status` - را ردیابی می‌کند (`botToken`، `appToken`، `signingSecret`، `userToken`). -- وضعیت `available`، `configured_unavailable` یا `missing` است. +- بازرسی حساب Slack، فیلدهای `*Source` و `*Status` را برای هر اعتبارنامه + دنبال می‌کند (`botToken`، `appToken`، `signingSecret`، `userToken`). +- وضعیت یکی از `available`، `configured_unavailable` یا `missing` است. - `configured_unavailable` یعنی حساب از طریق SecretRef - یا منبع secret غیرخطی دیگری پیکربندی شده است، اما مسیر فرمان/runtime فعلی + یا منبع secret غیر درون‌خطی دیگری پیکربندی شده، اما مسیر فرمان/زمان اجرای فعلی نتوانسته مقدار واقعی را resolve کند. - در حالت HTTP، `signingSecretStatus` گنجانده می‌شود؛ در Socket Mode، جفت الزامی `botTokenStatus` + `appTokenStatus` است. -برای actionها/خواندن directory، در صورت پیکربندی، user token می‌تواند ترجیح داده شود. برای نوشتن‌ها، bot token همچنان ترجیح داده می‌شود؛ نوشتن با user-token فقط زمانی مجاز است که `userTokenReadOnly: false` باشد و bot token در دسترس نباشد. +برای کنش‌ها/خواندن‌های فهرست، وقتی user token پیکربندی شده باشد می‌تواند ترجیح داده شود. برای نوشتن‌ها، bot token همچنان ترجیح داده می‌شود؛ نوشتن با user-token فقط زمانی مجاز است که `userTokenReadOnly: false` باشد و bot token در دسترس نباشد. -## Actionها و gateها +## کنش‌ها و gateها -Actionهای Slack با `channels.slack.actions.*` کنترل می‌شوند. +کنش‌های Slack با `channels.slack.actions.*` کنترل می‌شوند. -گروه‌های action در ابزارهای فعلی Slack: +گروه‌های کنش موجود در ابزار فعلی Slack: -| گروه | پیش‌فرض | +| گروه | پیش‌فرض | | ---------- | ------- | | messages | فعال | | reactions | فعال | @@ -481,60 +481,60 @@ Actionهای Slack با `channels.slack.actions.*` کنترل می‌شوند. | memberInfo | فعال | | emojiList | فعال | -Actionهای فعلی پیام Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info` و `emoji-list` هستند. `download-file` شناسه‌های فایل Slack را که در placeholderهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصاویر، preview تصویر یا برای انواع فایل دیگر metadata فایل محلی برمی‌گرداند. +کنش‌های پیام فعلی Slack شامل `send`، `upload-file`، `download-file`، `read`، `edit`، `delete`، `pin`، `unpin`، `list-pins`، `member-info` و `emoji-list` هستند. `download-file` شناسه‌های فایل Slack را که در placeholderهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصویرها پیش‌نمایش تصویر یا برای انواع فایل دیگر metadata فایل محلی برمی‌گرداند. -## کنترل دسترسی و routing +## کنترل دسترسی و مسیریابی - `channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` allowlist canonical برای DM است. + `channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` allowlist رسمی DM است. - `pairing` (پیش‌فرض) - `allowlist` - - `open` (نیاز دارد `channels.slack.allowFrom` شامل `"*"` باشد) + - `open` (نیازمند این است که `channels.slack.allowFrom` شامل `"*"` باشد) - `disabled` flagهای DM: - `dm.enabled` (پیش‌فرض true) - `channels.slack.allowFrom` - - `dm.allowFrom` (legacy) - - `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false) + - `dm.allowFrom` (قدیمی) + - `dm.groupEnabled` (DMهای گروهی به‌صورت پیش‌فرض false) - `dm.groupChannels` (allowlist اختیاری MPIM) تقدم چندحسابی: - `channels.slack.accounts.default.allowFrom` فقط برای حساب `default` اعمال می‌شود. - - حساب‌های نام‌گذاری‌شده وقتی `allowFrom` خودشان تنظیم نشده باشد، `channels.slack.allowFrom` را به ارث می‌برند. - - حساب‌های نام‌گذاری‌شده `channels.slack.accounts.default.allowFrom` را به ارث نمی‌برند. + - حساب‌های نام‌دار وقتی `allowFrom` خودشان تنظیم نشده باشد، `channels.slack.allowFrom` را به ارث می‌برند. + - حساب‌های نام‌دار `channels.slack.accounts.default.allowFrom` را به ارث نمی‌برند. - `channels.slack.dm.policy` و `channels.slack.dm.allowFrom` مربوط به legacy همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` منتقل می‌کند. + `channels.slack.dm.policy` و `channels.slack.dm.allowFrom` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` migrate می‌کند. - Pairing در DMها از `openclaw pairing approve slack ` استفاده می‌کند. + pairing در DMها از `openclaw pairing approve slack ` استفاده می‌کند. - - `channels.slack.groupPolicy` نحوه مدیریت channel را کنترل می‌کند: + + `channels.slack.groupPolicy` نحوه مدیریت کانال را کنترل می‌کند: - `open` - `allowlist` - `disabled` - allowlist مربوط به channel زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار channel در Slack** (برای مثال `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند. + allowlist کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای مثال `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند. - نکته runtime: اگر `channels.slack` کاملاً وجود نداشته باشد (راه‌اندازی فقط با env)، runtime به `groupPolicy="allowlist"` fallback می‌کند و یک هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). + نکته زمان اجرا: اگر `channels.slack` کاملا وجود نداشته باشد (راه‌اندازی فقط با env)، زمان اجرا به `groupPolicy="allowlist"` برمی‌گردد و هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). - Resolve نام/شناسه: + resolve نام/شناسه: - - entryهای allowlist مربوط به channel و entryهای allowlist مربوط به DM هنگام startup و وقتی دسترسی token اجازه دهد resolve می‌شوند - - entryهای resolve‌نشده با نام channel همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای routing نادیده گرفته می‌شوند - - authorization ورودی و routing channel به‌طور پیش‌فرض ID-first هستند؛ تطبیق مستقیم username/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد + - ورودی‌های allowlist کانال و allowlist DM هنگام راه‌اندازی، وقتی دسترسی token اجازه دهد، resolve می‌شوند + - ورودی‌های حل‌نشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند اما به‌صورت پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند + - authorization ورودی و مسیریابی کانال به‌صورت پیش‌فرض شناسه‌محور هستند؛ تطبیق مستقیم username/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد - کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) زیر `groupPolicy: "allowlist"` match نمی‌شوند. lookup مربوط به channel به‌طور پیش‌فرض ID-first است، بنابراین یک کلید مبتنی بر نام هرگز با موفقیت route نمی‌شود و همه پیام‌ها در آن channel بی‌صدا مسدود می‌شوند. این با `groupPolicy: "open"` متفاوت است؛ در آن حالت کلید channel برای routing لازم نیست و یک کلید مبتنی بر نام ظاهراً کار می‌کند. + کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) زیر `groupPolicy: "allowlist"` match نمی‌شوند. جست‌وجوی کانال به‌صورت پیش‌فرض شناسه‌محور است، بنابراین یک کلید مبتنی بر نام هرگز با موفقیت مسیریابی نمی‌شود و همه پیام‌ها در آن کانال بی‌صدا مسدود می‌شوند. این با `groupPolicy: "open"` متفاوت است؛ در آن حالت کلید کانال برای مسیریابی لازم نیست و یک کلید مبتنی بر نام ظاهرا کار می‌کند. - همیشه از شناسه channel در Slack به‌عنوان کلید استفاده کنید. برای یافتن آن: روی channel در Slack راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. + همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای پیدا کردن آن: در Slack روی کانال راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. درست: @@ -569,16 +569,16 @@ Actionهای فعلی پیام Slack شامل `send`، `upload-file`، `download - - پیام‌های channel به‌طور پیش‌فرض mention-gated هستند. + + پیام‌های کانال به‌صورت پیش‌فرض با mention gate می‌شوند. منابع mention: - mention صریح app (`<@botId>`) - - الگوهای regex مربوط به mention (`agents.list[].groupChat.mentionPatterns`، fallback `messages.groupChat.mentionPatterns`) - - رفتار thread ضمنی reply-to-bot (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود) + - الگوهای regex برای mention (`agents.list[].groupChat.mentionPatterns`، fallback `messages.groupChat.mentionPatterns`) + - رفتار thread ضمنی reply-to-bot (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال است) - کنترل‌های هر channel (`channels.slack.channels.`؛ نام‌ها فقط از طریق startup resolution یا `dangerouslyAllowNameMatching`): + کنترل‌های هر کانال (`channels.slack.channels.`؛ نام‌ها فقط از طریق resolve هنگام راه‌اندازی یا `dangerouslyAllowNameMatching`): - `requireMention` - `users` (allowlist) @@ -586,73 +586,75 @@ Actionهای فعلی پیام Slack شامل `send`، `upload-file`، `download - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - قالب کلید `toolsBySender`: `id:`، `e164:`، `username:`، `name:`، یا wildcard `"*"` - (کلیدهای legacy بدون prefix همچنان فقط به `id:` map می‌شوند) + - قالب کلید `toolsBySender`: `id:`، `e164:`، `username:`، `name:` یا wildcard `"*"` + (کلیدهای قدیمی بدون پیشوند همچنان فقط به `id:` map می‌شوند) + + `allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های اتاق که توسط bot نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که bot فرستنده به‌صراحت در allowlist `users` همان اتاق فهرست شده باشد، یا وقتی دست‌کم یک شناسه مالک صریح Slack از `channels.slack.allowFrom` در حال حاضر عضو اتاق باشد. wildcardها و ورودی‌های مالک با display-name حضور مالک را تامین نمی‌کنند. حضور مالک از `conversations.members` در Slack استفاده می‌کند؛ مطمئن شوید app دارای scope خواندن متناظر برای نوع اتاق است (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر جست‌وجوی عضو شکست بخورد، OpenClaw پیام اتاق نوشته‌شده توسط bot را drop می‌کند. -## Threading، sessionها و tagهای reply +## Threading، sessionها و tagهای پاسخ -- DMها به‌صورت `direct` route می‌شوند؛ channelها به‌صورت `channel`؛ MPIMها به‌صورت `group`. -- با مقدار پیش‌فرض `session.dmScope=main`، DMهای Slack به session اصلی agent collapse می‌شوند. -- sessionهای channel: `agent::slack:channel:`. -- replyهای thread در صورت کاربرد می‌توانند suffixهای session مخصوص thread بسازند (`:thread:`). -- مقدار پیش‌فرض `channels.slack.thread.historyScope` برابر `thread` است؛ مقدار پیش‌فرض `thread.inheritParent` برابر `false` است. -- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع session جدید thread چند پیام موجود در thread fetch شوند (پیش‌فرض `20`؛ برای غیرفعال کردن روی `0` تنظیم کنید). -- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، mentionهای ضمنی thread را suppress می‌کند تا bot فقط به mentionهای صریح `@bot` داخل threadها پاسخ دهد، حتی وقتی bot قبلاً در thread مشارکت داشته است. بدون این، replyها در threadی که bot در آن مشارکت داشته، gate مربوط به `requireMention` را دور می‌زنند. +- DMها به‌صورت `direct` مسیریابی می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`. +- با مقدار پیش‌فرض `session.dmScope=main`، DMهای Slack به session اصلی agent ادغام می‌شوند. +- sessionهای کانال: `agent::slack:channel:`. +- پاسخ‌های thread می‌توانند در صورت قابل‌اعمال بودن، suffixهای session thread بسازند (`:thread:`). +- پیش‌فرض `channels.slack.thread.historyScope` برابر `thread` است؛ پیش‌فرض `thread.inheritParent` برابر `false` است. +- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع یک session thread جدید چند پیام thread موجود واکشی شود (پیش‌فرض `20`؛ برای غیرفعال‌سازی `0` تنظیم کنید). +- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، mentionهای ضمنی thread را سرکوب می‌کند تا bot فقط به mentionهای صریح `@bot` داخل threadها پاسخ دهد، حتی وقتی bot قبلا در thread مشارکت داشته است. بدون این، پاسخ‌ها در threadی که bot در آن مشارکت داشته، gating مربوط به `requireMention` را دور می‌زنند. -کنترل‌های threading برای reply: +کنترل‌های reply threading: - `channels.slack.replyToMode`: `off|first|all|batched` (پیش‌فرض `off`) - `channels.slack.replyToModeByChatType`: برای هر `direct|group|channel` -- fallback مربوط به legacy برای chatهای مستقیم: `channels.slack.dm.replyToMode` +- fallback قدیمی برای chatهای مستقیم: `channels.slack.dm.replyToMode` -tagهای reply دستی پشتیبانی می‌شوند: +tagهای پاسخ دستی پشتیبانی می‌شوند: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` **همه** threadingهای reply را در Slack غیرفعال می‌کند، از جمله tagهای صریح `[[reply_to_*]]`. این با Telegram متفاوت است؛ در آنجا tagهای صریح همچنان در حالت `"off"` رعایت می‌شوند. threadهای Slack پیام‌ها را از channel پنهان می‌کنند، در حالی که replyهای Telegram به‌صورت inline قابل مشاهده می‌مانند. +`replyToMode="off"` **همه** reply threading را در Slack غیرفعال می‌کند، از جمله tagهای صریح `[[reply_to_*]]`. این با Telegram متفاوت است؛ در Telegram، tagهای صریح همچنان در حالت `"off"` رعایت می‌شوند. threadهای Slack پیام‌ها را از کانال پنهان می‌کنند، درحالی‌که پاسخ‌های Telegram به‌صورت inline قابل مشاهده می‌مانند. -## واکنش‌های ack +## واکنش‌های Ack -`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw، یک emoji تأیید ارسال می‌کند. +`ackReaction` هنگامی که OpenClaw در حال پردازش یک پیام ورودی است، یک emoji تایید دریافت می‌فرستد. -ترتیب resolution: +ترتیب resolve: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback emoji هویت agent (`agents.list[].identity.emoji`، در غیر این صورت "👀") +- fallback emoji هویت agent (`agents.list[].identity.emoji`، وگرنه "👀") نکات: - Slack انتظار shortcode دارد (برای مثال `"eyes"`). -- برای غیرفعال کردن reaction برای حساب Slack یا به‌صورت سراسری، از `""` استفاده کنید. +- برای غیرفعال کردن واکنش برای حساب Slack یا به‌صورت سراسری، از `""` استفاده کنید. -## Streaming متن +## پخش جریانی متن -`channels.slack.streaming` رفتار preview زنده را کنترل می‌کند: +`channels.slack.streaming` رفتار پیش‌نمایش زنده را کنترل می‌کند: -- `off`: streaming مربوط به preview زنده را غیرفعال کنید. -- `partial` (پیش‌فرض): متن preview را با آخرین خروجی partial جایگزین کنید. -- `block`: به‌روزرسانی‌های preview را به‌صورت chunk اضافه کنید. -- `progress`: هنگام تولید، متن وضعیت progress را نشان دهید، سپس متن نهایی را ارسال کنید. -- `streaming.preview.toolProgress`: وقتی draft preview فعال است، به‌روزرسانی‌های tool/progress را به همان پیام preview ویرایش‌شده route کنید (پیش‌فرض: `true`). برای نگه داشتن پیام‌های tool/progress جداگانه، روی `false` تنظیم کنید. +- `off`: پخش جریانی پیش‌نمایش زنده را غیرفعال می‌کند. +- `partial` (پیش‌فرض): متن پیش‌نمایش را با آخرین خروجی جزئی جایگزین می‌کند. +- `block`: به‌روزرسانی‌های پیش‌نمایش قطعه‌قطعه را append می‌کند. +- `progress`: هنگام تولید، متن وضعیت پیشرفت را نشان می‌دهد و سپس متن نهایی را می‌فرستد. +- `streaming.preview.toolProgress`: وقتی پیش‌نمایش draft فعال است، به‌روزرسانی‌های tool/progress را به همان پیام پیش‌نمایش ویرایش‌شده مسیریابی می‌کند (پیش‌فرض: `true`). برای نگه داشتن پیام‌های جداگانه tool/progress، `false` تنظیم کنید. -`channels.slack.streaming.nativeTransport` streaming متن native در Slack را وقتی `channels.slack.streaming.mode` برابر `partial` است کنترل می‌کند (پیش‌فرض: `true`). +`channels.slack.streaming.nativeTransport` پخش جریانی متن native Slack را وقتی `channels.slack.streaming.mode` برابر `partial` است کنترل می‌کند (پیش‌فرض: `true`). -- برای اینکه streaming متن native و وضعیت thread مربوط به assistant در Slack ظاهر شوند، باید یک reply thread در دسترس باشد. انتخاب thread همچنان از `replyToMode` پیروی می‌کند. -- rootهای channel و group-chat وقتی native streaming در دسترس نیست همچنان می‌توانند از draft preview معمول استفاده کنند. -- DMهای سطح‌بالای Slack به‌طور پیش‌فرض خارج از thread می‌مانند، بنابراین preview به سبک thread را نشان نمی‌دهند؛ اگر آنجا progress قابل مشاهده می‌خواهید، از replyهای thread یا `typingReaction` استفاده کنید. -- payloadهای media و غیرمتنی به delivery معمول fallback می‌کنند. -- finalهای media/error ویرایش‌های preview معلق را cancel می‌کنند؛ finalهای واجد شرایط text/block فقط وقتی flush می‌شوند که بتوانند preview را درجا ویرایش کنند. -- اگر streaming در میانه reply شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به delivery معمول fallback می‌کند. +- یک thread پاسخ باید برای نمایش پخش جریانی متن native و وضعیت thread دستیار Slack در دسترس باشد. انتخاب thread همچنان از `replyToMode` پیروی می‌کند. +- ریشه‌های channel و group-chat همچنان وقتی native streaming در دسترس نیست می‌توانند از پیش‌نمایش draft معمولی استفاده کنند. +- DMهای سطح‌بالای Slack به‌صورت پیش‌فرض خارج از thread می‌مانند، بنابراین پیش‌نمایش سبک thread را نشان نمی‌دهند؛ اگر می‌خواهید پیشرفت قابل مشاهده در آنجا داشته باشید، از پاسخ‌های thread یا `typingReaction` استفاده کنید. +- payloadهای رسانه و غیرمتنی به تحویل معمولی fallback می‌کنند. +- نتیجه‌های نهایی رسانه/خطا ویرایش‌های pending پیش‌نمایش را لغو می‌کنند؛ نتیجه‌های نهایی text/block واجد شرایط فقط وقتی flush می‌شوند که بتوانند پیش‌نمایش را درجا ویرایش کنند. +- اگر streaming در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به تحویل معمولی fallback می‌کند. -به‌جای streaming متن native در Slack از draft preview استفاده کنید: +به‌جای پخش جریانی متن native Slack از پیش‌نمایش draft استفاده کنید: ```json5 { @@ -667,17 +669,17 @@ tagهای reply دستی پشتیبانی می‌شوند: } ``` -کلیدهای legacy: +کلیدهای قدیمی: -- `channels.slack.streamMode` (`replace | status_final | append`) به‌طور خودکار به `channels.slack.streaming.mode` migrate می‌شود. -- مقدار boolean مربوط به `channels.slack.streaming` به‌طور خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` migrate می‌شود. -- `channels.slack.nativeStreaming` مربوط به legacy به‌طور خودکار به `channels.slack.streaming.nativeTransport` migrate می‌شود. +- `channels.slack.streamMode` (`replace | status_final | append`) به‌صورت خودکار به `channels.slack.streaming.mode` migrate می‌شود. +- مقدار boolean `channels.slack.streaming` به‌صورت خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` migrate می‌شود. +- `channels.slack.nativeStreaming` قدیمی به‌صورت خودکار به `channels.slack.streaming.nativeTransport` migrate می‌شود. -## Fallback واکنش typing +## fallback واکنش تایپ -`typingReaction` هنگام پردازش reply توسط OpenClaw، یک reaction موقت به پیام ورودی Slack اضافه می‌کند و سپس وقتی run تمام شد آن را حذف می‌کند. این بیشتر خارج از replyهای thread مفید است؛ replyهای thread از نشانگر وضعیت پیش‌فرض "is typing..." استفاده می‌کنند. +`typingReaction` هنگامی که OpenClaw در حال پردازش یک پاسخ است، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس پس از پایان run آن را حذف می‌کند. این بیرون از پاسخ‌های thread بیشترین کاربرد را دارد؛ پاسخ‌های thread از نشانگر وضعیت پیش‌فرض "is typing..." استفاده می‌کنند. -ترتیب resolution: +ترتیب resolve: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` @@ -685,42 +687,42 @@ tagهای reply دستی پشتیبانی می‌شوند: نکات: - Slack انتظار shortcode دارد (برای مثال `"hourglass_flowing_sand"`). -- reaction best-effort است و پس از تکمیل reply یا مسیر failure، cleanup به‌طور خودکار تلاش می‌شود. +- واکنش best-effort است و پس از تکمیل مسیر پاسخ یا شکست، cleanup به‌صورت خودکار تلاش می‌شود. -## Media، chunking و delivery +## رسانه، قطعه‌بندی و تحویل - پیوست‌های فایل Slack از URLهای private میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست token-authenticated) و وقتی fetch موفق باشد و محدودیت‌های اندازه اجازه دهند، در media store نوشته می‌شوند. placeholderهای فایل شامل `fileId` در Slack هستند تا agentها بتوانند فایل اصلی را با `download-file` fetch کنند. + پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احرازشده با token) و وقتی fetch موفق باشد و محدودیت‌های اندازه اجازه دهند، در media store نوشته می‌شوند. placeholderهای فایل شامل `fileId` مربوط به Slack هستند تا agentها بتوانند فایل اصلی را با `download-file` واکشی کنند. - دانلودها از timeoutهای idle و total محدود استفاده می‌کنند. اگر retrieval فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به placeholder فایل fallback می‌کند. + دانلودها از timeoutهای محدود برای idle و کل زمان استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به placeholder فایل fallback می‌کند. - سقف اندازه ورودی runtime به‌طور پیش‌فرض `20MB` است مگر اینکه با `channels.slack.mediaMaxMb` override شود. + سقف اندازه ورودی زمان اجرا به‌صورت پیش‌فرض `20MB` است مگر اینکه با `channels.slack.mediaMaxMb` override شود. - - chunkهای متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000) - - `channels.slack.chunkMode="newline"` splitting پاراگراف‌محور را فعال می‌کند - - ارسال‌های فایل از APIهای upload در Slack استفاده می‌کنند و می‌توانند replyهای thread (`thread_ts`) را شامل شوند - - سقف media خروجی وقتی پیکربندی شده باشد از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های channel از پیش‌فرض‌های MIME-kind در media pipeline استفاده می‌کنند + - قطعه‌های متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000) + - `channels.slack.chunkMode="newline"` تقسیم‌بندی با اولویت پاراگراف را فعال می‌کند + - ارسال فایل‌ها از APIهای بارگذاری Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های رشته‌ای (`thread_ts`) باشد + - سقف رسانهٔ خروجی، وقتی پیکربندی شده باشد، از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در خط لولهٔ رسانه استفاده می‌کنند - - هدف‌های صریح ترجیحی: + + مقصدهای صریح ترجیحی: - - `user:` برای DMها - - `channel:` برای channelها + - `user:` برای پیام‌های مستقیم + - `channel:` برای کانال‌ها - DMهای Slack هنگام ارسال به هدف‌های user از طریق APIهای conversation در Slack باز می‌شوند. + پیام‌های مستقیم Slack هنگام ارسال به مقصدهای کاربر، از طریق APIهای گفت‌وگوی Slack باز می‌شوند. -## Commandها و رفتار slash +## فرمان‌ها و رفتار اسلش -Commandهای slash در Slack یا به‌صورت یک command پیکربندی‌شده واحد ظاهر می‌شوند یا چند command native. برای تغییر پیش‌فرض‌های command، `channels.slack.slashCommand` را پیکربندی کنید: +فرمان‌های اسلش در Slack یا به‌صورت یک فرمان پیکربندی‌شدهٔ واحد یا چند فرمان بومی ظاهر می‌شوند. برای تغییر پیش‌فرض‌های فرمان، `channels.slack.slashCommand` را پیکربندی کنید: - `enabled: false` - `name: "openclaw"` @@ -731,30 +733,30 @@ Commandهای slash در Slack یا به‌صورت یک command پیکربند /openclaw /help ``` -دستورهای بومی به [تنظیمات اضافی manifest](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و در عوض با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. +فرمان‌های بومی به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامهٔ Slack شما نیاز دارند و در عوض با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. -- حالت خودکار دستور بومی برای Slack **خاموش** است، بنابراین `commands.native: "auto"` دستورهای بومی Slack را فعال نمی‌کند. +- حالت خودکار فرمان بومی برای Slack **خاموش** است، بنابراین `commands.native: "auto"` فرمان‌های بومی Slack را فعال نمی‌کند. ```txt /help ``` -منوهای آرگومان بومی از راهبرد رندر تطبیقی استفاده می‌کنند که پیش از ارسال مقدار گزینه انتخاب‌شده، یک مودال تأیید نشان می‌دهد: +منوهای آرگومان بومی از راهبرد نمایش تطبیقی استفاده می‌کنند که پیش از ارسال مقدار گزینهٔ انتخاب‌شده، یک modal تأیید نشان می‌دهد: -- تا ۵ گزینه: بلوک‌های دکمه -- ۶ تا ۱۰۰ گزینه: منوی انتخاب ایستا -- بیش از ۱۰۰ گزینه: انتخاب خارجی با فیلتر ناهمگام گزینه‌ها، وقتی هندلرهای گزینه‌های تعاملی در دسترس باشند -- فراتر از محدودیت‌های Slack: مقدارهای گزینه کدگذاری‌شده به دکمه‌ها برمی‌گردند +- تا 5 گزینه: بلوک‌های دکمه +- 6 تا 100 گزینه: منوی انتخاب ایستا +- بیش از 100 گزینه: انتخاب خارجی با فیلترکردن ناهمگام گزینه‌ها، وقتی handlerهای گزینه‌های interactivity در دسترس باشند +- فراتر از محدودیت‌های Slack: مقدارهای گزینهٔ کدگذاری‌شده به دکمه‌ها برمی‌گردند ```txt /think ``` -نشست‌های slash از کلیدهای ایزوله مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست مکالمه هدف مسیریابی می‌کنند. +نشست‌های اسلش از کلیدهای ایزوله‌ای مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای فرمان‌ها را با استفاده از `CommandTargetSessionKey` به نشست گفت‌وگوی مقصد هدایت می‌کنند. ## پاسخ‌های تعاملی -Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط عامل را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است. +Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط agent را نمایش دهد، اما این قابلیت به‌صورت پیش‌فرض غیرفعال است. فعال‌سازی سراسری آن: @@ -788,30 +790,30 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌ } ``` -وقتی فعال باشد، عامل‌ها می‌توانند دستورالعمل‌های پاسخ مخصوص Slack صادر کنند: +وقتی فعال باشد، agentها می‌توانند دستورهای پاسخ فقط مخصوص Slack صادر کنند: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -این دستورالعمل‌ها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر رویداد تعامل موجود Slack بازمی‌گردانند. +این دستورها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر رویداد تعامل موجود Slack برمی‌گردانند. -نکته‌ها: +نکات: -- این UI مخصوص Slack است. کانال‌های دیگر دستورالعمل‌های Slack Block Kit را به سامانه‌های دکمه خودشان ترجمه نمی‌کنند. -- مقدارهای callback تعاملی، توکن‌های مات تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط عامل. -- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit فراتر بروند، OpenClaw به‌جای ارسال payload نامعتبر بلوک‌ها، به پاسخ متنی اصلی برمی‌گردد. +- این UI مخصوص Slack است. کانال‌های دیگر دستورهای Slack Block Kit را به سیستم‌های دکمهٔ خودشان ترجمه نمی‌کنند. +- مقدارهای callback تعاملی توکن‌های مبهم تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط agent. +- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit فراتر بروند، OpenClaw به‌جای ارسال payload بلوک‌های نامعتبر، به پاسخ متنی اصلی برمی‌گردد. -## تأییدهای exec در Slack +## تأییدهای اجرا در Slack -Slack می‌تواند به‌جای بازگشت به Web UI یا ترمینال، به‌عنوان یک کلاینت تأیید بومی با دکمه‌ها و تعامل‌های تعاملی عمل کند. +Slack می‌تواند به‌جای بازگشت به رابط کاربری وب یا terminal، با دکمه‌ها و تعامل‌های تعاملی به‌عنوان یک کلاینت تأیید بومی عمل کند. -- تأییدهای exec از `channels.slack.execApprovals.*` برای مسیریابی بومی DM/کانال استفاده می‌کنند. -- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمه بومی Slack حل شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد. -- مجوزدهی تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند درخواست‌ها را از طریق Slack تأیید یا رد کنند. +- تأییدهای اجرا برای مسیریابی بومی پیام مستقیم/کانال از `channels.slack.execApprovals.*` استفاده می‌کنند. +- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمهٔ بومی Slack حل شوند، وقتی درخواست از قبل در Slack قرار گرفته باشد و نوع شناسهٔ تأیید `plugin:` باشد. +- مجوز تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند درخواست‌ها را از طریق Slack تأیید یا رد کنند. -این از همان سطح دکمه تأیید مشترک مانند کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، اعلان‌های تأیید مستقیماً در مکالمه به‌صورت دکمه‌های Block Kit رندر می‌شوند. -وقتی این دکمه‌ها حاضر باشند، UX اصلی تأیید هستند؛ OpenClaw -فقط زمانی باید دستور دستی `/approve` را اضافه کند که نتیجه ابزار بگوید تأییدهای chat +این از همان سطح مشترک دکمهٔ تأیید مثل کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامهٔ Slack شما فعال باشد، promptهای تأیید مستقیماً در گفت‌وگو به‌صورت دکمه‌های Block Kit نمایش داده می‌شوند. +وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید هستند؛ OpenClaw +باید فقط وقتی یک فرمان دستی `/approve` را شامل کند که نتیجهٔ ابزار بگوید تأییدهای چت در دسترس نیستند یا تأیید دستی تنها مسیر است. مسیر پیکربندی: @@ -821,11 +823,11 @@ Slack می‌تواند به‌جای بازگشت به Web UI یا ترمینا - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`، پیش‌فرض: `dm`) - `agentFilter`, `sessionFilter` -Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک -تأییدکننده resolve شود، تأییدهای exec بومی را به‌طور خودکار فعال می‌کند. برای غیرفعال‌کردن صریح Slack به‌عنوان کلاینت تأیید بومی، `enabled: false` را تنظیم کنید. -برای اجباری‌کردن تأییدهای بومی وقتی تأییدکننده‌ها resolve می‌شوند، `enabled: true` را تنظیم کنید. +Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و حداقل یک +تأییدکننده resolve شود، تأییدهای اجرای بومی را خودکار فعال می‌کند. برای غیرفعال‌کردن صریح Slack به‌عنوان کلاینت تأیید بومی، `enabled: false` را تنظیم کنید. +برای اجبار فعال‌شدن تأییدهای بومی وقتی تأییدکننده‌ها resolve می‌شوند، `enabled: true` را تنظیم کنید. -رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec در Slack: +رفتار پیش‌فرض بدون پیکربندی صریح تأیید اجرای Slack: ```json5 { @@ -835,8 +837,8 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و } ``` -پیکربندی صریح بومی Slack فقط وقتی لازم است که بخواهید تأییدکننده‌ها را override کنید، فیلتر اضافه کنید، یا -تحویل به chat مبدأ را انتخاب کنید: +پیکربندی صریح بومی Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را override کنید، فیلتر اضافه کنید، یا +تحویل به چت مبدأ را انتخاب کنید: ```json5 { @@ -852,25 +854,24 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و } ``` -ارسال مشترک `approvals.exec` جدا است. فقط وقتی از آن استفاده کنید که اعلان‌های تأیید exec باید همچنین -به chatهای دیگر یا هدف‌های out-of-band صریح مسیریابی شوند. ارسال مشترک `approvals.plugin` نیز -جدا است؛ دکمه‌های بومی Slack همچنان می‌توانند تأییدهای Plugin را حل کنند، وقتی آن درخواست‌ها از قبل -در Slack فرود آمده باشند. +هدایت مشترک `approvals.exec` جداست. فقط زمانی از آن استفاده کنید که promptهای تأیید اجرا باید به چت‌های دیگر یا مقصدهای صریح خارج از باند نیز +مسیریابی شوند. هدایت مشترک `approvals.plugin` نیز +جداست؛ دکمه‌های بومی Slack همچنان می‌توانند تأییدهای Plugin را وقتی آن درخواست‌ها از قبل در Slack قرار گرفته‌اند resolve کنند. -`/approve` در همان chat نیز در کانال‌های Slack و DMهایی که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل ارسال تأیید، [تأییدهای Exec](/fa/tools/exec-approvals) را ببینید. +`/approve` در همان چت نیز در کانال‌ها و پیام‌های مستقیم Slack که از قبل از فرمان‌ها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل هدایت تأیید، [تأییدهای اجرا](/fa/tools/exec-approvals) را ببینید. ## رویدادها و رفتار عملیاتی -- ویرایش‌ها/حذف‌های پیام به رویدادهای سیستمی نگاشت می‌شوند. -- پخش‌های thread (پاسخ‌های thread با «همچنین به کانال بفرست») به‌عنوان پیام‌های معمول کاربر پردازش می‌شوند. +- ویرایش/حذف پیام‌ها به رویدادهای سیستمی نگاشت می‌شوند. +- پخش‌های رشته‌ای (پاسخ‌های رشته‌ای «همچنین به کانال ارسال کن») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند. - رویدادهای افزودن/حذف واکنش به رویدادهای سیستمی نگاشت می‌شوند. - رویدادهای پیوستن/ترک عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به رویدادهای سیستمی نگاشت می‌شوند. -- `channel_id_changed` می‌تواند وقتی `configWrites` فعال است کلیدهای پیکربندی کانال را migrate کند. -- فراداده موضوع/هدف کانال به‌عنوان زمینه نامطمئن در نظر گرفته می‌شود و می‌تواند به زمینه مسیریابی تزریق شود. -- starter thread و seeding زمینه تاریخچه اولیه thread، در صورت کاربرد، بر اساس allowlistهای فرستنده پیکربندی‌شده فیلتر می‌شوند. -- کنش‌های بلوک و تعامل‌های مودال رویدادهای سیستمی ساختاریافته `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند: - - کنش‌های بلوک: مقدارهای انتخاب‌شده، برچسب‌ها، مقدارهای picker، و فراداده `workflow_*` - - رویدادهای مودال `view_submission` و `view_closed` با فراداده کانال مسیریابی‌شده و ورودی‌های فرم +- وقتی `configWrites` فعال باشد، `channel_id_changed` می‌تواند کلیدهای پیکربندی کانال را مهاجرت دهد. +- فرادادهٔ موضوع/هدف کانال به‌عنوان context غیرقابل‌اعتماد در نظر گرفته می‌شود و می‌تواند به context مسیریابی تزریق شود. +- آغازگر رشته و کاشت context تاریخچهٔ اولیهٔ رشته، در صورت کاربرد، بر اساس allowlistهای فرستندهٔ پیکربندی‌شده فیلتر می‌شوند. +- کنش‌های بلوک و تعامل‌های modal رویدادهای سیستمی ساخت‌یافتهٔ `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند: + - کنش‌های بلوک: مقدارهای انتخاب‌شده، برچسب‌ها، مقدارهای picker، و فرادادهٔ `workflow_*` + - رویدادهای modal `view_submission` و `view_closed` با فرادادهٔ کانال مسیریابی‌شده و ورودی‌های فرم ## مرجع پیکربندی @@ -878,11 +879,11 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و -- حالت/احراز هویت: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` -- دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (میراثی: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` -- تغییر وضعیت سازگاری: `dangerouslyAllowNameMatching` (گزینه اضطراری؛ مگر در صورت نیاز خاموش نگه دارید) +- حالت/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` +- دسترسی پیام مستقیم: `dm.enabled`, `dmPolicy`, `allowFrom` (قدیمی: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` +- کلید سازگاری: `dangerouslyAllowNameMatching` (break-glass؛ مگر در صورت نیاز خاموش نگه دارید) - دسترسی کانال: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- thread کردن/تاریخچه: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- رشته‌بندی/تاریخچه: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - تحویل: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - عملیات/قابلیت‌ها: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -891,15 +892,15 @@ Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و ## عیب‌یابی - + به‌ترتیب بررسی کنید: - `groupPolicy` - - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه‌های کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام در `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون مسیریابی کانال به‌طور پیش‌فرض ابتدا بر اساس ID است. برای یافتن ID: در Slack روی کانال راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL همان ID کانال است. + - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسهٔ کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام زیر `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون مسیریابی کانال به‌صورت پیش‌فرض اول بر اساس شناسه است. برای یافتن شناسه: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسهٔ کانال است. - `requireMention` - - allowlist `users` برای هر کانال + - allowlist کاربران هر کانال - دستورهای مفید: + فرمان‌های مفید: ```bash openclaw channels status --probe @@ -909,15 +910,15 @@ openclaw doctor - + بررسی کنید: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (یا نسخه میراثی `channels.slack.dm.policy`) + - `channels.slack.dmPolicy` (یا مقدار قدیمی `channels.slack.dm.policy`) - تأییدهای pairing / ورودی‌های allowlist - - رویدادهای DM دستیار Slack: لاگ‌های verbose که به `drop message_changed` اشاره می‌کنند - معمولاً یعنی Slack یک رویداد thread دستیار ویرایش‌شده را بدون - فرستنده انسانی قابل‌بازیابی در فراداده پیام فرستاده است + - رویدادهای پیام مستقیم Slack Assistant: لاگ‌های verbose که به `drop message_changed` اشاره می‌کنند + معمولاً یعنی Slack یک رویداد رشتهٔ Assistant ویرایش‌شده فرستاده است، بدون + فرستندهٔ انسانی قابل بازیابی در فرادادهٔ پیام ```bash openclaw pairing list slack @@ -925,34 +926,35 @@ openclaw pairing list slack - - توکن‌های bot و app و فعال‌بودن Socket Mode را در تنظیمات برنامه Slack اعتبارسنجی کنید. + + توکن‌های bot + app و فعال‌بودن Socket Mode را در تنظیمات برنامهٔ Slack اعتبارسنجی کنید. اگر `openclaw channels status --probe --json` مقدار `botTokenStatus` یا - `appTokenStatus: "configured_unavailable"` را نشان دهد، حساب Slack - پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتیبانی‌شده با SecretRef را resolve کند. - - - - - اعتبارسنجی کنید: - - - secret امضا - - مسیر Webhook - - URLهای درخواست Slack (Events + Interactivity + Slash Commands) - - `webhookPath` یکتا برای هر حساب HTTP - - اگر `signingSecretStatus: "configured_unavailable"` در snapshotهای حساب ظاهر شود، - حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته secret امضای پشتیبانی‌شده با SecretRef را + `appTokenStatus: "configured_unavailable"` را نشان می‌دهد، حساب Slack + پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتیبانی‌شده با SecretRef را resolve کند. - - بررسی کنید که قصد شما کدام بوده است: + + اعتبارسنجی کنید: - - حالت دستور بومی (`channels.slack.commands.native: true`) با دستورهای slash متناظر ثبت‌شده در Slack - - یا حالت تک‌دستور slash (`channels.slack.slashCommand.enabled: true`) + - signing secret + - مسیر Webhook + - URLهای درخواست Slack (رویدادها + Interactivity + فرمان‌های اسلش) + - `webhookPath` یکتا برای هر حساب HTTP + + اگر `signingSecretStatus: "configured_unavailable"` در snapshotهای حساب ظاهر شود، + حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته signing secret پشتیبانی‌شده با SecretRef را + resolve کند. + + + + + بررسی کنید که منظورتان کدام بوده است: + + - حالت فرمان بومی (`channels.slack.commands.native: true`) با فرمان‌های اسلش متناظر ثبت‌شده در Slack + - یا حالت فرمان اسلش واحد (`channels.slack.slashCommand.enabled: true`) همچنین `commands.useAccessGroups` و allowlistهای کانال/کاربر را بررسی کنید. @@ -961,88 +963,88 @@ openclaw pairing list slack ## مرجع vision پیوست -Slack می‌تواند وقتی دانلود فایل‌های Slack موفق باشد و محدودیت‌های اندازه اجازه دهند، رسانه دانلودشده را به نوبت عامل پیوست کند. فایل‌های تصویر می‌توانند از مسیر درک رسانه عبور کنند یا مستقیماً به مدل پاسخ vision-capable داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌صورت زمینه فایل قابل‌دانلود نگه داشته می‌شوند. +Slack وقتی دانلود فایل‌های Slack موفق شود و محدودیت‌های اندازه اجازه دهند، می‌تواند رسانهٔ دانلودشده را به turn agent پیوست کند. فایل‌های تصویری می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به یک مدل پاسخ سازگار با vision داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌عنوان context فایل قابل دانلود نگه داشته می‌شوند. -### انواع رسانه پشتیبانی‌شده +### انواع رسانهٔ پشتیبانی‌شده -| نوع رسانه | منبع | رفتار فعلی | نکته‌ها | +| نوع رسانه | منبع | رفتار فعلی | نکات | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود شده و برای پردازش vision-capable به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض ۲۰ MB) | -| فایل‌های PDF | URL فایل Slack | دانلود شده و به‌عنوان زمینه فایل برای ابزارهایی مانند `download-file` یا `pdf` ارائه می‌شود | ورودی Slack به‌طور خودکار PDFها را به ورودی image-vision تبدیل نمی‌کند | -| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود شده و به‌عنوان زمینه فایل ارائه می‌شود | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | -| پاسخ‌های thread | فایل‌های starter thread | وقتی پاسخ رسانه مستقیم ندارد، فایل‌های پیام ریشه می‌توانند به‌عنوان زمینه hydrate شوند | starterهای فقط‌فایل از placeholder پیوست استفاده می‌کنند | -| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌طور مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است | +| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود و برای پردازش سازگار با vision به turn پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض 20 MB) | +| فایل‌های PDF | URL فایل Slack | دانلود و به‌عنوان context فایل برای ابزارهایی مانند `download-file` یا `pdf` ارائه می‌شود | ورودی Slack به‌صورت خودکار PDFها را به ورودی image-vision تبدیل نمی‌کند | +| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود و به‌عنوان context فایل ارائه می‌شود | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | +| پاسخ‌های رشته‌ای | فایل‌های آغازگر رشته | وقتی پاسخ رسانهٔ مستقیم ندارد، فایل‌های پیام ریشه می‌توانند به‌عنوان context hydrate شوند | آغازگرهای فقط‌فایل از placeholder پیوست استفاده می‌کنند | +| پیام‌های چندتصویری | چند فایل Slack | هر فایل مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل در هر پیام محدود می‌شود | -### pipeline ورودی +### خط لولهٔ ورودی -وقتی یک پیام Slack با پیوست‌های فایل می‌رسد: +وقتی یک پیام Slack با پیوست‌های فایل برسد: -1. OpenClaw فایل را از URL خصوصی Slack با استفاده از توکن bot (`xoxb-...`) دانلود می‌کند. -2. فایل در صورت موفقیت در media store نوشته می‌شود. -3. مسیرهای رسانه دانلودشده و نوع‌های محتوا به زمینه ورودی اضافه می‌شوند. -4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویر آن زمینه استفاده کنند. -5. فایل‌های غیرتصویری به‌عنوان فراداده فایل یا ارجاع‌های رسانه برای ابزارهایی که می‌توانند آن‌ها را مدیریت کنند، در دسترس می‌مانند. +1. OpenClaw فایل را با استفاده از توکن ربات (`xoxb-...`) از URL خصوصی Slack دانلود می‌کند. +2. در صورت موفقیت، فایل در ذخیره‌گاه رسانه نوشته می‌شود. +3. مسیرهای رسانهٔ دانلودشده و نوع‌های محتوا به زمینهٔ ورودی افزوده می‌شوند. +4. مسیرهای مدل/ابزاری که قابلیت تصویر دارند می‌توانند از پیوست‌های تصویری آن زمینه استفاده کنند. +5. فایل‌های غیرتصویری همچنان به‌صورت فرادادهٔ فایل یا ارجاع‌های رسانه برای ابزارهایی که می‌توانند آن‌ها را مدیریت کنند در دسترس می‌مانند. -### وراثت پیوست ریشه thread +### وراثت پیوست از ریشهٔ رشته‌گفت‌وگو -وقتی پیامی در یک thread می‌رسد (دارای والد `thread_ts` است): +وقتی پیامی در یک رشته‌گفت‌وگو می‌رسد (والد `thread_ts` دارد): -- اگر خود پاسخ رسانه مستقیم نداشته باشد و پیام ریشه واردشده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینه starter thread hydrate کند. +- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ گنجانده‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ آغازگر رشته‌گفت‌وگو بارگذاری کند. - پیوست‌های مستقیم پاسخ بر پیوست‌های پیام ریشه اولویت دارند. -- پیام ریشه‌ای که فقط فایل دارد و متن ندارد با یک placeholder پیوست نمایش داده می‌شود تا fallback همچنان بتواند فایل‌های آن را شامل شود. +- پیام ریشه‌ای که فقط فایل دارد و متن ندارد با یک جانگه‌دار پیوست نمایش داده می‌شود تا مسیر جایگزین همچنان بتواند فایل‌های آن را شامل شود. ### مدیریت چند پیوست -وقتی یک پیام Slack واحد شامل چند پیوست فایل باشد: +وقتی یک پیام Slack شامل چند پیوست فایل باشد: -- هر پیوست به‌طور مستقل از طریق مسیر پردازش رسانه پردازش می‌شود. -- ارجاع‌های رسانه‌ای دانلودشده در زمینهٔ پیام تجمیع می‌شوند. -- ترتیب پردازش از ترتیب فایل‌های Slack در محمولهٔ رویداد پیروی می‌کند. -- خرابی در دانلود یک پیوست، پیوست‌های دیگر را مسدود نمی‌کند. +- هر پیوست به‌طور مستقل از طریق خط لولهٔ رسانه پردازش می‌شود. +- ارجاع‌های رسانهٔ دانلودشده در زمینهٔ پیام تجمیع می‌شوند. +- ترتیب پردازش از ترتیب فایل‌های Slack در payload رویداد پیروی می‌کند. +- شکست در دانلود یک پیوست، پیوست‌های دیگر را مسدود نمی‌کند. -### محدودیت‌های اندازه، دانلود، و مدل +### محدودیت‌های اندازه، دانلود و مدل -- **سقف اندازه**: پیش‌فرض 20 MB برای هر فایل. از طریق `channels.slack.mediaMaxMb` قابل پیکربندی است. -- **خرابی‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، URLهای منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بیش‌ازحد بزرگ، و پاسخ‌های HTML احراز هویت/ورود Slack به‌جای اینکه به‌عنوان قالب‌های پشتیبانی‌نشده گزارش شوند، نادیده گرفته می‌شوند. -- **مدل بینایی**: تحلیل تصویر از مدل پاسخ فعال استفاده می‌کند اگر از بینایی پشتیبانی کند، یا از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel`. +- **سقف اندازه**: پیش‌فرض 20 MB برای هر فایل. از طریق `channels.slack.mediaMaxMb` قابل تنظیم است. +- **شکست‌های دانلود**: فایل‌هایی که Slack نمی‌تواند ارائه کند، URLهای منقضی‌شده، فایل‌های غیرقابل‌دسترسی، فایل‌های بیش‌ازحد بزرگ، و پاسخ‌های HTML احراز هویت/ورود Slack به‌جای گزارش‌شدن به‌عنوان قالب‌های پشتیبانی‌نشده، نادیده گرفته می‌شوند. +- **مدل بینایی**: تحلیل تصویر وقتی مدل پاسخ فعال از بینایی پشتیبانی کند از همان مدل استفاده می‌کند، یا از مدل تصویر پیکربندی‌شده در `agents.defaults.imageModel`. ### محدودیت‌های شناخته‌شده -| سناریو | رفتار فعلی | راهکار جایگزین | -| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| URL فایل Slack منقضی‌شده | فایل نادیده گرفته می‌شود؛ خطایی نشان داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید | -| مدل بینایی پیکربندی نشده است | پیوست‌های تصویری به‌عنوان ارجاع‌های رسانه‌ای ذخیره می‌شوند، اما به‌عنوان تصویر تحلیل نمی‌شوند | `agents.defaults.imageModel` را پیکربندی کنید یا از یک مدل پاسخ دارای قابلیت بینایی استفاده کنید | -| تصاویر بسیار بزرگ (> 20 MB به‌طور پیش‌فرض) | طبق سقف اندازه نادیده گرفته می‌شوند | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید | -| پیوست‌های فورواردشده/اشتراک‌گذاری‌شده | متن و رسانه‌های تصویر/فایل میزبانی‌شده در Slack به‌صورت بهترین تلاش پردازش می‌شوند | مستقیماً در رشتهٔ OpenClaw دوباره به اشتراک بگذارید | -| پیوست‌های PDF | به‌عنوان زمینهٔ فایل/رسانه ذخیره می‌شوند، نه اینکه به‌طور خودکار از مسیر بینایی تصویر عبور داده شوند | برای فرادادهٔ فایل از `download-file` یا برای تحلیل PDF از ابزار `pdf` استفاده کنید | +| سناریو | رفتار فعلی | راه‌حل جایگزین | +| --------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| URL فایل Slack منقضی‌شده | فایل نادیده گرفته می‌شود؛ خطایی نمایش داده نمی‌شود | فایل را دوباره در Slack بارگذاری کنید | +| مدل بینایی پیکربندی نشده است | پیوست‌های تصویری به‌عنوان ارجاع‌های رسانه ذخیره می‌شوند، اما به‌عنوان تصویر تحلیل نمی‌شوند | `agents.defaults.imageModel` را پیکربندی کنید یا از مدل پاسخ دارای قابلیت بینایی استفاده کنید | +| تصاویر بسیار بزرگ (> 20 MB به‌صورت پیش‌فرض) | طبق سقف اندازه نادیده گرفته می‌شوند | اگر Slack اجازه می‌دهد، `channels.slack.mediaMaxMb` را افزایش دهید | +| پیوست‌های بازارسال‌شده/اشتراک‌گذاری‌شده | متن و رسانه‌های تصویر/فایل میزبانی‌شده در Slack به‌صورت بهترین تلاش پردازش می‌شوند | مستقیماً در رشته‌گفت‌وگوی OpenClaw دوباره به اشتراک بگذارید | +| پیوست‌های PDF | به‌عنوان زمینهٔ فایل/رسانه ذخیره می‌شوند، نه اینکه به‌طور خودکار از مسیر بینایی تصویر عبور کنند | برای فرادادهٔ فایل از `download-file` یا برای تحلیل PDF از ابزار `pdf` استفاده کنید | ### مستندات مرتبط -- [مسیر پردازش فهم رسانه](/fa/nodes/media-understanding) +- [خط لولهٔ درک رسانه](/fa/nodes/media-understanding) - [ابزار PDF](/fa/tools/pdf) -- حماسه: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست Slack +- حماسه: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست‌های Slack - آزمون‌های رگرسیون: [#51353](https://github.com/openclaw/openclaw/issues/51353) - راستی‌آزمایی زنده: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## مرتبط - - یک کاربر Slack را با Gateway جفت کنید. + + یک کاربر Slack را به Gateway جفت کنید. - - رفتار کانال و پیام خصوصی گروهی. + + رفتار کانال و پیام مستقیم گروهی. - + پیام‌های ورودی را به عامل‌ها مسیریابی کنید. - + مدل تهدید و سخت‌سازی. - + چیدمان پیکربندی و تقدم. - - کاتالوگ دستورها و رفتار. + + کاتالوگ فرمان‌ها و رفتار. diff --git a/docs/fa/channels/telegram.md b/docs/fa/channels/telegram.md index 94247b11e..d00be25cd 100644 --- a/docs/fa/channels/telegram.md +++ b/docs/fa/channels/telegram.md @@ -4,22 +4,22 @@ read_when: summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Telegram title: Telegram x-i18n: - generated_at: "2026-04-29T22:29:34Z" + generated_at: "2026-04-30T16:27:41Z" model: gpt-5.5 provider: openai - source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7 + source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd source_path: channels/telegram.md workflow: 16 --- -آمادهٔ استفادهٔ production برای DMهای ربات و گروه‌ها از طریق grammY. حالت پیش‌فرض، long polling است؛ حالت webhook اختیاری است. +آمادهٔ تولید برای پیام‌های مستقیم ربات و گروه‌ها از طریق grammY. Long polling حالت پیش‌فرض است؛ حالت webhook اختیاری است. - سیاست پیش‌فرض DM برای Telegram جفت‌سازی است. + سیاست پیش‌فرض پیام مستقیم برای Telegram، جفت‌سازی است. - عیب‌یابی‌های بین‌کانالی و راهنماهای تعمیر. + تشخیص‌ها و دستورالعمل‌های تعمیر بین‌کانالی. الگوها و نمونه‌های کامل پیکربندی کانال. @@ -30,13 +30,13 @@ x-i18n: - Telegram را باز کنید و با **@BotFather** گفتگو کنید (مطمئن شوید handle دقیقاً `@BotFather` است). + Telegram را باز کنید و با **@BotFather** گفت‌وگو کنید (تأیید کنید که شناسه دقیقاً `@BotFather` است). - `/newbot` را اجرا کنید، اعلان‌ها را دنبال کنید، و توکن را ذخیره کنید. + `/newbot` را اجرا کنید، اعلان‌ها را دنبال کنید و توکن را ذخیره کنید. - + ```json5 { @@ -52,11 +52,11 @@ x-i18n: ``` جایگزین env: `TELEGRAM_BOT_TOKEN=...` (فقط حساب پیش‌فرض). - Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در config/env پیکربندی کنید، سپس gateway را راه‌اندازی کنید. + Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در پیکربندی/env تنظیم کنید، سپس gateway را شروع کنید. - + ```bash openclaw gateway @@ -74,35 +74,35 @@ openclaw pairing approve telegram -ترتیب تشخیص توکن، حساب‌آگاه است. در عمل، مقادیر config بر جایگزین env اولویت دارند، و `TELEGRAM_BOT_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. +ترتیب تشخیص توکن از حساب آگاه است. در عمل، مقدارهای پیکربندی بر جایگزین env اولویت دارند و `TELEGRAM_BOT_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. ## تنظیمات سمت Telegram - - ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند، که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند. + + ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند. اگر ربات باید همهٔ پیام‌های گروه را ببیند، یکی از این کارها را انجام دهید: - - حالت حریم خصوصی را با `/setprivacy` غیرفعال کنید، یا + - حالت حریم خصوصی را از طریق `/setprivacy` غیرفعال کنید، یا - ربات را مدیر گروه کنید. - هنگام تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند. + هنگام تغییر حالت حریم خصوصی، ربات را از هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند. وضعیت مدیر در تنظیمات گروه Telegram کنترل می‌شود. - ربات‌های مدیر همهٔ پیام‌های گروه را دریافت می‌کنند، که برای رفتار گروهی همیشه‌فعال مفید است. + ربات‌های مدیر همهٔ پیام‌های گروه را دریافت می‌کنند، که برای رفتار همیشه‌فعال گروه مفید است. - + - - `/setjoingroups` برای اجازه/رد کردن افزودن به گروه‌ها - - `/setprivacy` برای رفتار دیده‌شدن در گروه + - `/setjoingroups` برای مجاز/غیرمجاز کردن افزودن به گروه + - `/setprivacy` برای رفتار نمایش‌پذیری گروه @@ -110,35 +110,35 @@ openclaw pairing approve telegram ## کنترل دسترسی و فعال‌سازی - + `channels.telegram.dmPolicy` دسترسی پیام مستقیم را کنترل می‌کند: - `pairing` (پیش‌فرض) - - `allowlist` (به حداقل یک شناسهٔ فرستنده در `allowFrom` نیاز دارد) + - `allowlist` (حداقل به یک شناسهٔ فرستنده در `allowFrom` نیاز دارد) - `open` (نیاز دارد `allowFrom` شامل `"*"` باشد) - `disabled` - `dmPolicy: "open"` همراه با `allowFrom: ["*"]` به هر حساب Telegram که نام کاربری ربات را پیدا یا حدس بزند اجازه می‌دهد به ربات فرمان بدهد. فقط برای ربات‌های عمداً عمومی با ابزارهای بسیار محدود از آن استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` با شناسه‌های عددی کاربر استفاده کنند. + `dmPolicy: "open"` همراه با `allowFrom: ["*"]` اجازه می‌دهد هر حساب Telegram که نام کاربری ربات را پیدا یا حدس می‌زند، به ربات فرمان بدهد. فقط برای ربات‌های عمداً عمومی با ابزارهای بسیار محدود از آن استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` با شناسه‌های عددی کاربر استفاده کنند. `channels.telegram.allowFrom` شناسه‌های عددی کاربر Telegram را می‌پذیرد. پیشوندهای `telegram:` / `tg:` پذیرفته و نرمال‌سازی می‌شوند. - در پیکربندی‌های چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا به‌عنوان مرز ایمنی در نظر گرفته می‌شود: ورودی‌های `allowFrom: ["*"]` در سطح حساب، آن حساب را عمومی نمی‌کنند مگر اینکه allowlist مؤثر حساب پس از ادغام هنوز شامل یک wildcard صریح باشد. - `dmPolicy: "allowlist"` با `allowFrom` خالی همهٔ DMها را مسدود می‌کند و توسط اعتبارسنجی config رد می‌شود. + در پیکربندی‌های چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا به‌عنوان مرز ایمنی در نظر گرفته می‌شود: ورودی‌های سطح حساب `allowFrom: ["*"]` آن حساب را عمومی نمی‌کنند، مگر اینکه allowlist مؤثر حساب پس از ادغام همچنان شامل wildcard صریح باشد. + `dmPolicy: "allowlist"` با `allowFrom` خالی همهٔ پیام‌های مستقیم را مسدود می‌کند و توسط اعتبارسنجی پیکربندی رد می‌شود. راه‌اندازی فقط شناسه‌های عددی کاربر را درخواست می‌کند. - اگر ارتقا داده‌اید و config شما شامل ورودی‌های allowlist از نوع `@username` است، `openclaw doctor --fix` را اجرا کنید تا آن‌ها را resolve کند (best-effort؛ به توکن ربات Telegram نیاز دارد). - اگر قبلاً به فایل‌های allowlist در pairing-store متکی بودید، `openclaw doctor --fix` می‌تواند در جریان‌های allowlist ورودی‌ها را به `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز شناسهٔ صریحی ندارد). + اگر ارتقا داده‌اید و پیکربندی شما شامل ورودی‌های allowlist به‌شکل `@username` است، `openclaw doctor --fix` را اجرا کنید تا آن‌ها را رفع کند (بهترین تلاش؛ به توکن ربات Telegram نیاز دارد). + اگر قبلاً به فایل‌های allowlist فروشگاه جفت‌سازی متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را در جریان‌های allowlist به `channels.telegram.allowFrom` بازیابی کند (برای نمونه وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسهٔ صریحی ندارد). - برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` را همراه با شناسه‌های عددی صریح `allowFrom` ترجیح دهید تا سیاست دسترسی در config پایدار بماند (به‌جای وابستگی به تأییدهای جفت‌سازی قبلی). + برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` را با شناسه‌های عددی صریح `allowFrom` ترجیح دهید تا سیاست دسترسی در پیکربندی ماندگار بماند (به‌جای وابستگی به تأییدهای قبلی جفت‌سازی). - سردرگمی رایج: تأیید جفت‌سازی DM به معنی «این فرستنده همه‌جا مجاز است» نیست. - جفت‌سازی دسترسی DM می‌دهد. اگر هنوز مالک فرمانی وجود نداشته باشد، نخستین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند. - مجوز فرستنده در گروه همچنان از allowlistهای صریح config می‌آید. - اگر می‌خواهید «یک بار مجاز شوم و هم DMها و هم فرمان‌های گروهی کار کنند»، شناسهٔ عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:` است. + ابهام رایج: تأیید جفت‌سازی پیام مستقیم به این معنا نیست که «این فرستنده همه‌جا مجاز است». + جفت‌سازی دسترسی پیام مستقیم را اعطا می‌کند. اگر هنوز مالک فرمانی وجود نداشته باشد، نخستین جفت‌سازی تأییدشده `commands.ownerAllowFrom` را هم تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند. + مجوز فرستندهٔ گروه همچنان از allowlistهای صریح پیکربندی می‌آید. + اگر می‌خواهید «یک بار مجاز شوم و هم پیام‌های مستقیم و هم فرمان‌های گروه کار کنند»، شناسهٔ عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:` است. - ### پیدا کردن شناسهٔ کاربر Telegram شما + ### پیدا کردن شناسهٔ کاربر Telegram خود - امن‌تر (بدون ربات شخص ثالث): + ایمن‌تر (بدون ربات شخص ثالث): - 1. به ربات خود DM بدهید. + 1. به ربات خود پیام مستقیم بدهید. 2. `openclaw logs --follow` را اجرا کنید. 3. `from.id` را بخوانید. @@ -148,7 +148,7 @@ openclaw pairing approve telegram curl "https://api.telegram.org/bot/getUpdates" ``` - روش شخص ثالث (با حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`. + روش شخص ثالث (حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`. @@ -156,27 +156,27 @@ curl "https://api.telegram.org/bot/getUpdates" دو کنترل با هم اعمال می‌شوند: 1. **کدام گروه‌ها مجاز هستند** (`channels.telegram.groups`) - - بدون config برای `groups`: - - با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسهٔ گروه را بگذراند - - با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه کنید مسدود می‌مانند - - `groups` پیکربندی شده: مثل allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`) + - بدون پیکربندی `groups`: + - با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسهٔ گروه را پشت سر بگذارد + - با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها مسدود می‌شوند تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه کنید + - `groups` پیکربندی شده: به‌عنوان allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`) 2. **کدام فرستنده‌ها در گروه‌ها مجاز هستند** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (پیش‌فرض) - `disabled` - `groupAllowFrom` برای فیلتر فرستندهٔ گروه استفاده می‌شود. اگر تنظیم نشده باشد، Telegram به `allowFrom` fallback می‌کند. + `groupAllowFrom` برای فیلتر کردن فرستندهٔ گروه استفاده می‌شود. اگر تنظیم نشده باشد، Telegram به `allowFrom` بازمی‌گردد. ورودی‌های `groupAllowFrom` باید شناسه‌های عددی کاربر Telegram باشند (پیشوندهای `telegram:` / `tg:` نرمال‌سازی می‌شوند). - شناسه‌های گفتگوی گروه یا supergroup در Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های منفی گفتگو باید زیر `channels.telegram.groups` باشند. + شناسه‌های گفت‌وگوی گروه یا ابرگروه Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های منفی گفت‌وگو باید زیر `channels.telegram.groups` باشند. ورودی‌های غیرعددی برای مجوز فرستنده نادیده گرفته می‌شوند. - مرز امنیتی (`2026.2.25+`): احراز هویت فرستندهٔ گروه تأییدهای DM در pairing-store را به ارث **نمی‌برد**. - جفت‌سازی فقط برای DM باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر موضوع را تنظیم کنید. - اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به `allowFrom` در config fallback می‌کند، نه pairing store. - الگوی عملی برای ربات‌های تک‌مالک: شناسهٔ کاربر خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده بگذارید، و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید. - نکتهٔ runtime: اگر `channels.telegram` کاملاً وجود نداشته باشد، پیش‌فرض‌های runtime به‌صورت fail-closed روی `groupPolicy="allowlist"` قرار می‌گیرند مگر اینکه `channels.defaults.groupPolicy` صریحاً تنظیم شده باشد. + مرز امنیتی (`2026.2.25+`): احراز هویت فرستندهٔ گروه تأییدهای فروشگاه جفت‌سازی پیام مستقیم را به ارث **نمی‌برد**. + جفت‌سازی فقط برای پیام مستقیم باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر موضوع را تنظیم کنید. + اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به `allowFrom` پیکربندی بازمی‌گردد، نه فروشگاه جفت‌سازی. + الگوی عملی برای ربات‌های تک‌مالک: شناسهٔ کاربر خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده بگذارید و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید. + نکتهٔ زمان اجرا: اگر `channels.telegram` کاملاً وجود نداشته باشد، مقدارهای پیش‌فرض زمان اجرا به `groupPolicy="allowlist"` با حالت بسته در برابر خطا بازمی‌گردند، مگر اینکه `channels.defaults.groupPolicy` صریحاً تنظیم شده باشد. - مثال: اجازه به هر عضو در یک گروه مشخص: + نمونه: مجاز کردن هر عضو در یک گروه مشخص: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - مثال: اجازه فقط به کاربران مشخص درون یک گروه مشخص: + نمونه: مجاز کردن فقط کاربران مشخص داخل یک گروه مشخص: ```json5 { @@ -213,32 +213,32 @@ curl "https://api.telegram.org/bot/getUpdates" اشتباه رایج: `groupAllowFrom` یک allowlist گروه Telegram نیست. - - شناسه‌های منفی گروه یا supergroup در Telegram مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید. - - وقتی می‌خواهید محدود کنید کدام افراد درون یک گروه مجاز می‌توانند ربات را trigger کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید. + - شناسه‌های گفت‌وگوی گروه یا ابرگروه Telegram منفی مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید. + - وقتی می‌خواهید محدود کنید چه افرادی داخل یک گروه مجاز بتوانند ربات را فعال کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید. - فقط وقتی از `groupAllowFrom: ["*"]` استفاده کنید که می‌خواهید هر عضو یک گروه مجاز بتواند با ربات صحبت کند. - - پاسخ‌های گروهی به‌طور پیش‌فرض به mention نیاز دارند. + + پاسخ‌های گروه به‌طور پیش‌فرض به منشن نیاز دارند. - mention می‌تواند از این‌ها بیاید: + منشن می‌تواند از این موارد بیاید: - - mention بومی `@botusername`، یا - - الگوهای mention در: + - منشن بومی `@botusername`، یا + - الگوهای منشن در: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - کلیدهای فرمان در سطح session: + کلیدهای فرمان در سطح نشست: - `/activation always` - `/activation mention` - این‌ها فقط وضعیت session را به‌روزرسانی می‌کنند. برای پایداری از config استفاده کنید. + این‌ها فقط وضعیت نشست را به‌روزرسانی می‌کنند. برای ماندگاری از پیکربندی استفاده کنید. - مثال config پایدار: + نمونهٔ پیکربندی ماندگار: ```json5 { @@ -252,44 +252,44 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - دریافت شناسهٔ گفتگوی گروه: + گرفتن شناسهٔ گفت‌وگوی گروه: - یک پیام گروه را به `@userinfobot` / `@getidsbot` فوروارد کنید - یا `chat.id` را از `openclaw logs --follow` بخوانید - - یا Bot API `getUpdates` را بررسی کنید + - یا `getUpdates` در Bot API را بررسی کنید -## رفتار runtime +## رفتار زمان اجرا -- Telegram تحت مالکیت فرایند gateway است. -- مسیریابی قطعی است: ورودی Telegram به Telegram پاسخ می‌دهد (مدل کانال‌ها را انتخاب نمی‌کند). -- پیام‌های ورودی به envelope مشترک کانال با metadata پاسخ و placeholderهای رسانه نرمال‌سازی می‌شوند. -- sessionهای گروه با شناسهٔ گروه ایزوله می‌شوند. موضوع‌های انجمن `:topic:` را اضافه می‌کنند تا موضوع‌ها ایزوله بمانند. -- پیام‌های DM می‌توانند `message_thread_id` داشته باشند؛ OpenClaw آن‌ها را با کلیدهای session آگاه از thread مسیریابی می‌کند و شناسهٔ thread را برای پاسخ‌ها حفظ می‌کند. -- Long polling از grammY runner با ترتیب‌دهی per-chat/per-thread استفاده می‌کند. هم‌زمانی کلی runner sink از `agents.defaults.maxConcurrent` استفاده می‌کند. -- Long polling درون هر فرایند gateway محافظت می‌شود تا هر بار فقط یک poller فعال بتواند از یک توکن ربات استفاده کند. اگر هنوز conflictهای `getUpdates` 409 می‌بینید، احتمالاً یک OpenClaw gateway، اسکریپت، یا poller خارجی دیگر از همان توکن استفاده می‌کند. -- watchdog مربوط به long-polling به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness کامل‌شدهٔ `getUpdates` restart را trigger می‌کند. فقط اگر deployment شما هنوز هنگام کارهای طولانی false polling-stall restart می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ overrideهای per-account پشتیبانی می‌شوند. -- Telegram Bot API از read-receipt پشتیبانی نمی‌کند (`sendReadReceipts` اعمال نمی‌شود). +- Telegram توسط فرایند gateway مالکیت می‌شود. +- مسیریابی قطعی است: ورودی‌های Telegram به Telegram پاسخ داده می‌شوند (مدل کانال‌ها را انتخاب نمی‌کند). +- پیام‌های ورودی به پوشش کانال مشترک با فرادادهٔ پاسخ و placeholderهای رسانه نرمال‌سازی می‌شوند. +- نشست‌های گروه با شناسهٔ گروه جدا می‌شوند. موضوع‌های انجمن `:topic:` را اضافه می‌کنند تا موضوع‌ها جدا بمانند. +- پیام‌های مستقیم می‌توانند `message_thread_id` داشته باشند؛ OpenClaw آن‌ها را با کلیدهای نشست آگاه از رشته مسیریابی می‌کند و شناسهٔ رشته را برای پاسخ‌ها حفظ می‌کند. +- Long polling از اجراکنندهٔ grammY با توالی‌بندی در سطح هر گفت‌وگو/هر رشته استفاده می‌کند. هم‌روندی کلی sink اجراکننده از `agents.defaults.maxConcurrent` استفاده می‌کند. +- Long polling داخل هر فرایند gateway محافظت می‌شود تا در هر زمان فقط یک poller فعال بتواند از یک توکن ربات استفاده کند. اگر همچنان تعارض‌های `getUpdates` 409 می‌بینید، احتمالاً یک gateway، اسکریپت، یا poller خارجی OpenClaw دیگر از همان توکن استفاده می‌کند. +- راه‌اندازی‌های مجدد watchdog برای long-polling به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness تکمیل‌شدهٔ `getUpdates` فعال می‌شوند. فقط اگر استقرار شما همچنان هنگام کارهای طولانی‌مدت راه‌اندازی مجدد کاذب polling-stall می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ override در سطح هر حساب پشتیبانی می‌شود. +- Telegram Bot API از رسید خواندن پشتیبانی نمی‌کند (`sendReadReceipts` اعمال نمی‌شود). ## مرجع قابلیت‌ها - - OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت real time stream کند: + + OpenClaw می‌تواند پاسخ‌های جزئی را در زمان واقعی stream کند: - - گفتگوهای مستقیم: پیام پیش‌نمایش + `editMessageText` + - گفت‌وگوهای مستقیم: پیام پیش‌نمایش + `editMessageText` - گروه‌ها/موضوع‌ها: پیام پیش‌نمایش + `editMessageText` - الزام: + نیازمندی: - `channels.telegram.streaming` برابر `off | partial | block | progress` است (پیش‌فرض: `partial`) - - `progress` در Telegram به `partial` map می‌شود (سازگاری با نام‌گذاری بین‌کانالی) - - `streaming.preview.toolProgress` کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: وقتی preview streaming فعال است `true`) - - مقادیر legacy `channels.telegram.streamMode` و boolean `streaming` شناسایی می‌شوند؛ `openclaw doctor --fix` را اجرا کنید تا آن‌ها را به `channels.telegram.streaming.mode` migrate کند + - `progress` در Telegram به `partial` نگاشت می‌شود (سازگاری با نام‌گذاری بین‌کانالی) + - `streaming.preview.toolProgress` کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: `true` وقتی streaming پیش‌نمایش فعال است) + - مقدارهای قدیمی `channels.telegram.streamMode` و مقدارهای بولی `streaming` شناسایی می‌شوند؛ `openclaw doctor --fix` را اجرا کنید تا آن‌ها را به `channels.telegram.streaming.mode` مهاجرت دهد - به‌روزرسانی‌های پیش‌نمایش tool-progress همان خط‌های کوتاه «در حال کار...» هستند که هنگام اجرای ابزارها نشان داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشدهٔ OpenClaw از `v2026.4.22` و بعد از آن هماهنگ باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خط‌های tool-progress، تنظیم کنید: + به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار همان خط‌های کوتاه «در حال کار...» هستند که هنگام اجرای ابزارها نمایش داده می‌شوند، برای نمونه اجرای فرمان، خواندن فایل، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشدهٔ OpenClaw از `v2026.4.22` و بعد از آن منطبق باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خط‌های پیشرفت ابزار، تنظیم کنید: ```json { @@ -306,32 +306,30 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - فقط وقتی از `streaming.mode: "off"` استفاده کنید که تحویل فقط نهایی را می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفتگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌عنوان پیام‌های مستقل «در حال کار...» سرکوب می‌شود. اعلان‌های تأیید، payloadهای رسانه، و خطاها همچنان از مسیر تحویل نهایی عادی عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و در عین حال خط‌های وضعیت tool-progress را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید. + فقط زمانی از `streaming.mode: "off"` استفاده کنید که تحویل فقط نهایی می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفت‌وگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌عنوان پیام‌های مستقل «در حال کار...» سرکوب می‌شود. اعلان‌های تأیید، payloadهای رسانه، و خطاها همچنان از مسیر تحویل نهایی معمول عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و هم‌زمان خط‌های وضعیت پیشرفت ابزار را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید. - برای پاسخ‌های فقط‌متنی: + برای پاسخ‌های فقط متنی: - - پیش‌نمایش‌های کوتاه DM/گروه/topic: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و در پایان همان را درجا ویرایش می‌کند - - پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ کامل‌شده را به‌عنوان یک پیام نهایی تازه می‌فرستد و سپس پیش‌نمایش را پاک می‌کند، تا زمان‌نمای قابل‌مشاهده Telegram به‌جای زمان ایجاد پیش‌نمایش، زمان تکمیل را نشان دهد + - پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و در پایان همان‌جا آن را ویرایش می‌کند + - پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ تکمیل‌شده را به‌عنوان یک پیام نهایی تازه ارسال می‌کند و سپس پیش‌نمایش را پاک می‌کند، تا زمان‌نمای قابل مشاهده Telegram زمان تکمیل را به‌جای زمان ایجاد پیش‌نمایش نشان دهد - برای پاسخ‌های پیچیده (برای مثال payloadهای رسانه‌ای)، OpenClaw به تحویل نهایی معمولی برمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند. + برای پاسخ‌های پیچیده (برای مثال بارهای رسانه‌ای)، OpenClaw به تحویل نهایی عادی برمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند. - استریم پیش‌نمایش از استریم بلوک جداست. وقتی استریم بلوک به‌طور صریح برای Telegram فعال شده باشد، OpenClaw برای جلوگیری از دوبار استریم‌کردن، استریم پیش‌نمایش را رد می‌کند. + جریان‌دهی پیش‌نمایش از جریان‌دهی بلوک جدا است. وقتی جریان‌دهی بلوک به‌صراحت برای Telegram فعال شده باشد، OpenClaw جریان پیش‌نمایش را رد می‌کند تا از جریان‌دهی دوباره جلوگیری شود. - اگر انتقال draft بومی در دسترس نباشد/رد شود، OpenClaw به‌طور خودکار به `sendMessage` + `editMessageText` برمی‌گردد. + جریان استدلال ویژه Telegram: - استریم reasoning فقط برای Telegram: - - - `/reasoning stream` هنگام تولید، reasoning را به پیش‌نمایش زنده می‌فرستد - - پاسخ نهایی بدون متن reasoning ارسال می‌شود + - `/reasoning stream` هنگام تولید، استدلال را به پیش‌نمایش زنده می‌فرستد + - پاسخ نهایی بدون متن استدلال ارسال می‌شود - + متن خروجی از Telegram `parse_mode: "HTML"` استفاده می‌کند. - - متن شبیه Markdown به HTML ایمن برای Telegram رندر می‌شود. + - متن شبیه Markdown به HTML امن برای Telegram رندر می‌شود. - HTML خام مدل escape می‌شود تا خطاهای parse در Telegram کاهش یابد. - - اگر Telegram، HTML پردازش‌شده را رد کند، OpenClaw دوباره به‌صورت متن ساده تلاش می‌کند. + - اگر Telegram HTML پردازش‌شده را رد کند، OpenClaw به‌صورت متن ساده دوباره تلاش می‌کند. پیش‌نمایش لینک‌ها به‌صورت پیش‌فرض فعال است و می‌توان آن را با `channels.telegram.linkPreview: false` غیرفعال کرد. @@ -344,7 +342,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `commands.native: "auto"` دستورهای بومی را برای Telegram فعال می‌کند - افزودن ورودی‌های سفارشی به منوی دستور: + ورودی‌های منوی دستور سفارشی را اضافه کنید: ```json5 { @@ -361,47 +359,47 @@ curl "https://api.telegram.org/bot/getUpdates" قواعد: - - نام‌ها نرمال‌سازی می‌شوند (`/` ابتدایی حذف می‌شود، حروف کوچک می‌شوند) + - نام‌ها نرمال می‌شوند (حذف `/` ابتدایی، حروف کوچک) - الگوی معتبر: `a-z`، `0-9`، `_`، طول `1..32` - - دستورهای سفارشی نمی‌توانند دستورهای بومی را override کنند - - تداخل‌ها/تکراری‌ها رد و لاگ می‌شوند + - دستورهای سفارشی نمی‌توانند دستورهای بومی را بازنویسی کنند + - تداخل‌ها/تکراری‌ها رد و ثبت می‌شوند نکته‌ها: - - دستورهای سفارشی فقط ورودی‌های منو هستند؛ رفتار را خودکار پیاده‌سازی نمی‌کنند - - دستورهای plugin/skill حتی اگر در منوی Telegram نشان داده نشوند، همچنان می‌توانند هنگام تایپ‌شدن کار کنند + - دستورهای سفارشی فقط ورودی منو هستند؛ رفتار را به‌صورت خودکار پیاده‌سازی نمی‌کنند + - دستورهای Plugin/skill همچنان می‌توانند هنگام تایپ کار کنند، حتی اگر در منوی Telegram نمایش داده نشوند - اگر دستورهای بومی غیرفعال باشند، موارد داخلی حذف می‌شوند. دستورهای سفارشی/plugin اگر پیکربندی شده باشند همچنان ممکن است ثبت شوند. + اگر دستورهای بومی غیرفعال باشند، موارد داخلی حذف می‌شوند. دستورهای سفارشی/Plugin ممکن است در صورت پیکربندی همچنان ثبت شوند. خطاهای رایج راه‌اندازی: - - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی Telegram حتی پس از کوتاه‌سازی هم سرریز شده است؛ تعداد دستورهای plugin/skill/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید. - - خطای `deleteWebhook`، `deleteMyCommands`، یا `setMyCommands` همراه با `404: Not Found` درحالی‌که دستورهای مستقیم curl برای Bot API کار می‌کنند، می‌تواند یعنی `channels.telegram.apiRoot` روی endpoint کامل `/bot` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد، و `openclaw doctor --fix` یک `/bot` انتهایی تصادفی را حذف می‌کند. - - `getMe returned 401` یعنی Telegram توکن bot پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile`، یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، بنابراین این مورد به‌عنوان خطای پاک‌سازی webhook گزارش نمی‌شود. - - `setMyCommands failed` همراه با خطاهای network/fetch معمولاً یعنی DNS/HTTPS خروجی به `api.telegram.org` مسدود است. + - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی Telegram پس از کوتاه‌سازی همچنان سرریز شده است؛ دستورهای Plugin/skill/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید. + - خطای `deleteWebhook`، `deleteMyCommands`، یا `setMyCommands` همراه با `404: Not Found` در حالی که دستورهای مستقیم Bot API با curl کار می‌کنند، می‌تواند یعنی `channels.telegram.apiRoot` روی endpoint کامل `/bot` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد، و `openclaw doctor --fix` یک `/bot` انتهایی تصادفی را حذف می‌کند. + - `getMe returned 401` یعنی Telegram توکن bot پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile`، یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، پس این مورد به‌عنوان خطای پاک‌سازی Webhook گزارش نمی‌شود. + - `setMyCommands failed` همراه با خطاهای شبکه/fetch معمولاً یعنی DNS/HTTPS خروجی به `api.telegram.org` مسدود است. - ### دستورهای جفت‌سازی دستگاه (plugin `device-pair`) + ### دستورهای جفت‌سازی دستگاه (`device-pair` plugin) - وقتی plugin `device-pair` نصب باشد: + وقتی `device-pair` plugin نصب شده باشد: 1. `/pair` کد راه‌اندازی تولید می‌کند - 2. کد را در اپ iOS جای‌گذاری کنید - 3. `/pair pending` درخواست‌های در انتظار را فهرست می‌کند (از جمله role/scopes) + 2. کد را در برنامه iOS جای‌گذاری کنید + 3. `/pair pending` درخواست‌های در انتظار را فهرست می‌کند (شامل نقش/دامنه‌ها) 4. درخواست را تأیید کنید: - `/pair approve ` برای تأیید صریح - `/pair approve` وقتی فقط یک درخواست در انتظار وجود دارد - `/pair approve latest` برای جدیدترین مورد - کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. handoff داخلی bootstrap، توکن primary node را روی `scopes: []` نگه می‌دارد؛ هر توکن operator واگذارشده محدود به `operator.approvals`، `operator.read`، `operator.talk.secrets`، و `operator.write` می‌ماند. بررسی‌های scope مربوط به bootstrap با پیشوند role انجام می‌شوند، بنابراین allowlist مربوط به operator فقط درخواست‌های operator را برآورده می‌کند؛ roleهای غیر-operator همچنان به scopeهای زیر پیشوند role خودشان نیاز دارند. + کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. تحویل bootstrap داخلی، توکن node اصلی را در `scopes: []` نگه می‌دارد؛ هر توکن operator تحویل‌داده‌شده در محدوده `operator.approvals`، `operator.read`، `operator.talk.secrets`، و `operator.write` باقی می‌ماند. بررسی‌های دامنه bootstrap با پیشوند نقش هستند، بنابراین آن allowlist مربوط به operator فقط درخواست‌های operator را برآورده می‌کند؛ نقش‌های غیر operator همچنان به دامنه‌هایی زیر پیشوند نقش خودشان نیاز دارند. - اگر دستگاهی با جزئیات auth تغییرکرده دوباره تلاش کند (برای مثال role/scopes/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید، دوباره `/pair pending` را اجرا کنید. + اگر دستگاهی با جزئیات احراز هویت تغییرکرده دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید، `/pair pending` را دوباره اجرا کنید. جزئیات بیشتر: [جفت‌سازی](/fa/channels/pairing#pair-via-telegram-recommended-for-ios). - - scope صفحه‌کلید inline را پیکربندی کنید: + + دامنه صفحه‌کلید درون‌خطی را پیکربندی کنید: ```json5 { @@ -415,7 +413,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - override برای هر حساب: + بازنویسی برای هر حساب: ```json5 { @@ -433,7 +431,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Scopeها: + دامنه‌ها: - `off` - `dm` @@ -466,66 +464,66 @@ curl "https://api.telegram.org/bot/getUpdates" - - actionهای tool در Telegram شامل این موارد هستند: + + actionهای ابزار Telegram شامل موارد زیر است: - - `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, اختیاری `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, اختیاری `iconColor`, `iconCustomEmojiId`) actionهای پیام کانال aliasهای خوش‌دست ارائه می‌کنند (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - کنترل‌های gating: + کنترل‌های gate: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (پیش‌فرض: غیرفعال) - نکته: `edit` و `topic-create` در حال حاضر به‌صورت پیش‌فرض فعال هستند و toggleهای جداگانه `channels.telegram.actions.*` ندارند. - ارسال‌های زمان اجرا از snapshot فعال config/secrets (startup/reload) استفاده می‌کنند، بنابراین مسیرهای action برای هر ارسال، باز-حل‌کردن موردی SecretRef انجام نمی‌دهند. + نکته: `edit` و `topic-create` در حال حاضر به‌صورت پیش‌فرض فعال هستند و toggle جداگانه `channels.telegram.actions.*` ندارند. + ارسال‌های runtime از snapshot فعال پیکربندی/secretها (راه‌اندازی/reload) استفاده می‌کنند، بنابراین مسیرهای action برای هر ارسال SecretRef را به‌صورت ad-hoc دوباره resolve نمی‌کنند. - معنای حذف reaction: [/tools/reactions](/fa/tools/reactions) + معناشناسی حذف reaction: [/tools/reactions](/fa/tools/reactions) - - Telegram از تگ‌های threading پاسخ صریح در خروجی تولیدشده پشتیبانی می‌کند: + + Telegram از برچسب‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده پشتیبانی می‌کند: - - `[[reply_to_current]]` به پیام triggerکننده پاسخ می‌دهد - - `[[reply_to:]]` به یک ID پیام مشخص در Telegram پاسخ می‌دهد + - `[[reply_to_current]]` به پیام محرک پاسخ می‌دهد + - `[[reply_to:]]` به یک شناسه پیام مشخص Telegram پاسخ می‌دهد - `channels.telegram.replyToMode` مدیریت را کنترل می‌کند: + `channels.telegram.replyToMode` نحوه رسیدگی را کنترل می‌کند: - `off` (پیش‌فرض) - `first` - `all` - وقتی threading پاسخ فعال باشد و متن یا caption اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک excerpt quote بومی Telegram اضافه می‌کند. Telegram متن quote بومی را به 1024 code unit در UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا quote می‌شوند و اگر Telegram quote را رد کند، به پاسخ ساده برمی‌گردند. + وقتی رشته‌بندی پاسخ فعال باشد و متن یا caption اصلی Telegram در دسترس باشد، OpenClaw به‌صورت خودکار یک excerpt نقل‌قول بومی Telegram را اضافه می‌کند. Telegram متن نقل‌قول بومی را به 1024 واحد کد UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا نقل می‌شوند و اگر Telegram نقل‌قول را رد کند، به یک پاسخ ساده برمی‌گردند. - نکته: `off`، threading پاسخ ضمنی را غیرفعال می‌کند. تگ‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. + نکته: `off` رشته‌بندی پاسخ ضمنی را غیرفعال می‌کند. برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. - + supergroupهای forum: - - کلیدهای session مربوط به topic، `:topic:` را اضافه می‌کنند - - پاسخ‌ها و typing به thread مربوط به topic هدف‌گیری می‌شوند - - مسیر config مربوط به topic: + - کلیدهای session موضوع، `:topic:` را اضافه می‌کنند + - پاسخ‌ها و typing موضوع thread را هدف می‌گیرند + - مسیر پیکربندی موضوع: `channels.telegram.groups..topics.` - حالت خاص topic عمومی (`threadId=1`): + حالت ویژه موضوع عمومی (`threadId=1`): - - ارسال‌های پیام `message_thread_id` را حذف می‌کنند (Telegram، `sendMessage(...thread_id=1)` را رد می‌کند) + - ارسال‌های پیام `message_thread_id` را حذف می‌کنند (Telegram `sendMessage(...thread_id=1)` را رد می‌کند) - actionهای typing همچنان `message_thread_id` را شامل می‌شوند - وراثت topic: ورودی‌های topic تنظیمات گروه را به ارث می‌برند مگر اینکه override شده باشند (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` فقط مخصوص topic است و از پیش‌فرض‌های گروه به ارث نمی‌رسد. + ارث‌بری موضوع: ورودی‌های موضوع تنظیمات گروه را به ارث می‌برند مگر اینکه بازنویسی شوند (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` فقط مربوط به موضوع است و از پیش‌فرض‌های گروه ارث نمی‌برد. - **مسیریابی agent برای هر topic**: هر topic می‌تواند با تنظیم `agentId` در config همان topic به agent متفاوتی route شود. این کار برای هر topic فضای کاری، حافظه، و session ایزوله خودش را فراهم می‌کند. مثال: + **مسیریابی agent برای هر موضوع**: هر موضوع می‌تواند با تنظیم `agentId` در پیکربندی موضوع، به agent متفاوتی route شود. این به هر موضوع workspace، memory، و session ایزوله خودش را می‌دهد. مثال: ```json5 { @@ -545,24 +543,24 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - سپس هر topic کلید session خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3` + سپس هر موضوع کلید session خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3` - **اتصال ماندگار topic در ACP**: topicهای forum می‌توانند sessionهای ACP harness را از طریق bindingهای ACP تایپ‌شده در سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و id واجد topic مانند `-1001234567890:topic:42`). در حال حاضر به topicهای forum در گروه‌ها/supergroupها محدود است. [ACP Agents](/fa/tools/acp-agents) را ببینید. + **binding پایدار موضوع ACP**: موضوع‌های forum می‌توانند sessionهای harness ACP را از طریق bindingهای ACP تایپ‌شده سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و شناسه دارای qualifier موضوع مثل `-1001234567890:topic:42`). در حال حاضر محدود به موضوع‌های forum در گروه‌ها/supergroupها است. [Agentهای ACP](/fa/tools/acp-agents) را ببینید. - **spawn کردن ACP وابسته به thread از chat**: `/acp spawn --thread here|auto`، topic فعلی را به یک session جدید ACP متصل می‌کند؛ follow-upها مستقیماً به همان‌جا route می‌شوند. OpenClaw تأیید spawn را داخل topic pin می‌کند. به `channels.telegram.threadBindings.spawnAcpSessions=true` نیاز دارد. + **spawn کردن ACP وابسته به thread از chat**: `/acp spawn --thread here|auto` موضوع فعلی را به یک session جدید ACP bind می‌کند؛ follow-upها مستقیم به همان‌جا route می‌شوند. OpenClaw تأیید spawn را داخل موضوع pin می‌کند. نیازمند `channels.telegram.threadBindings.spawnAcpSessions=true` است. - context قالب، `MessageThreadId` و `IsForum` را expose می‌کند. chatهای DM با `message_thread_id` مسیریابی DM را نگه می‌دارند اما از کلیدهای session آگاه به thread استفاده می‌کنند. + context قالب `MessageThreadId` و `IsForum` را expose می‌کند. chatهای DM دارای `message_thread_id` مسیریابی DM را نگه می‌دارند اما از کلیدهای session آگاه از thread استفاده می‌کنند. - + ### پیام‌های صوتی - Telegram بین voice note و فایل صوتی تمایز می‌گذارد. + Telegram بین voice noteها و فایل‌های صوتی تمایز می‌گذارد. - پیش‌فرض: رفتار فایل صوتی - - تگ `[[audio_as_voice]]` در پاسخ agent برای اجبار به ارسال به‌صورت voice-note - - transcriptهای voice-note ورودی در context مربوط به agent به‌عنوان متن تولیدشده توسط ماشین و نامطمئن قاب‌بندی می‌شوند؛ تشخیص mention همچنان از transcript خام استفاده می‌کند، بنابراین پیام‌های صوتی mention-gated به کار خود ادامه می‌دهند. + - برچسب `[[audio_as_voice]]` در پاسخ agent برای اجبار به ارسال voice-note + - transcriptهای voice-note ورودی در context agent به‌عنوان متن ماشین‌تولیدشده و غیرقابل اعتماد قاب‌بندی می‌شوند؛ تشخیص mention همچنان از transcript خام استفاده می‌کند تا پیام‌های صوتی mention-gated به کار ادامه دهند. نمونه action پیام: @@ -576,9 +574,9 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - ### پیام‌های ویدیویی + ### پیام‌های ویدئویی - Telegram بین فایل‌های ویدیویی و video noteها تمایز می‌گذارد. + Telegram بین فایل‌های ویدئویی و video noteها تمایز می‌گذارد. نمونه action پیام: @@ -594,15 +592,15 @@ curl "https://api.telegram.org/bot/getUpdates" Video noteها از caption پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود. - ### Stickerها + ### استیکرها - مدیریت sticker ورودی: + رسیدگی به استیکر ورودی: - - WEBP ایستا: دانلود و پردازش می‌شود (placeholder ``) + - WEBP ثابت: دانلود و پردازش می‌شود (placeholder ``) - TGS متحرک: رد می‌شود - - WEBM ویدیویی: رد می‌شود + - WEBM ویدئویی: رد می‌شود - فیلدهای context مربوط به sticker: + فیلدهای context استیکر: - `Sticker.emoji` - `Sticker.setName` @@ -610,13 +608,13 @@ curl "https://api.telegram.org/bot/getUpdates" - `Sticker.fileUniqueId` - `Sticker.cachedDescription` - فایل cache مربوط به sticker: + فایل cache استیکر: - `~/.openclaw/telegram/sticker-cache.json` - Stickerها یک‌بار (در صورت امکان) توصیف و cache می‌شوند تا فراخوانی‌های vision تکراری کاهش یابد. + استیکرها یک‌بار (در صورت امکان) توصیف و cache می‌شوند تا فراخوانی‌های vision تکراری کاهش یابد. - فعال‌سازی actionهای sticker: + actionهای استیکر را فعال کنید: ```json5 { @@ -630,7 +628,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - action ارسال sticker: + action ارسال استیکر: ```json5 { @@ -641,7 +639,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - جست‌وجوی stickerهای cache‌شده: + جست‌وجوی استیکرهای cacheشده: ```json5 { @@ -655,55 +653,55 @@ curl "https://api.telegram.org/bot/getUpdates" - reactionهای Telegram به‌صورت به‌روزرسانی‌های `message_reaction` می‌رسند (جدا از payloadهای پیام). + reactionهای Telegram به‌صورت updateهای `message_reaction` دریافت می‌شوند (جدا از payloadهای پیام). - وقتی فعال باشد، OpenClaw رویدادهای system مانند این‌ها را enqueue می‌کند: + وقتی فعال باشد، OpenClaw رویدادهای سیستمی مانند موارد زیر را enqueue می‌کند: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` - Config: + پیکربندی: - `channels.telegram.reactionNotifications`: `off | own | all` (پیش‌فرض: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (پیش‌فرض: `minimal`) نکته‌ها: - - `own` یعنی فقط واکنش‌های کاربر به پیام‌های ارسال‌شده توسط بات (به‌صورت best-effort از طریق کش پیام‌های ارسال‌شده). - - رویدادهای واکنش همچنان کنترل‌های دسترسی Telegram را رعایت می‌کنند (`dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`)؛ فرستنده‌های غیرمجاز حذف می‌شوند. - - Telegram در به‌روزرسانی‌های واکنش، شناسه thread ارائه نمی‌کند. - - گروه‌های غیر forum به نشست گفت‌وگوی گروه هدایت می‌شوند - - گروه‌های forum به نشست موضوع عمومی گروه (`:topic:1`) هدایت می‌شوند، نه موضوع دقیق مبدأ + - `own` یعنی فقط واکنش‌های کاربر به پیام‌های ارسال‌شده توسط ربات (بهترین تلاش از طریق کش پیام‌های ارسال‌شده). + - رویدادهای واکنش همچنان کنترل‌های دسترسی Telegram را رعایت می‌کنند (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`)؛ فرستنده‌های غیرمجاز حذف می‌شوند. + - Telegram در به‌روزرسانی‌های واکنش، شناسهٔ رشته ارائه نمی‌کند. + - گروه‌های غیرانجمنی به نشست چت گروه هدایت می‌شوند + - گروه‌های انجمنی به نشست موضوع عمومی گروه (`:topic:1`) هدایت می‌شوند، نه موضوع دقیق مبدأ - `allowed_updates` برای polling/webhook به‌صورت خودکار شامل `message_reaction` می‌شود. + `allowed_updates` برای polling/webhook به‌طور خودکار شامل `message_reaction` است. - `ackReaction` هنگامی که OpenClaw در حال پردازش یک پیام ورودی است، یک ایموجی تأیید می‌فرستد. + `ackReaction` هنگام پردازش یک پیام ورودی توسط OpenClaw، یک ایموجی تأیید ارسال می‌کند. - ترتیب تشخیص: + ترتیب حل: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، در غیر این صورت "👀") + - جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، وگرنه "👀") نکته‌ها: - Telegram انتظار ایموجی unicode دارد (برای مثال "👀"). - - برای غیرفعال‌کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید. + - برای غیرفعال کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید. - نوشتن پیکربندی کانال به‌صورت پیش‌فرض فعال است (`configWrites !== false`). + نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (`configWrites !== false`). - نوشتن‌های برانگیخته‌شده توسط Telegram شامل موارد زیر است: + نوشتن‌های فعال‌شده توسط Telegram شامل موارد زیر است: - رویدادهای مهاجرت گروه (`migrate_to_chat_id`) برای به‌روزرسانی `channels.telegram.groups` - - `/config set` و `/config unset` (به فعال‌بودن فرمان نیاز دارد) + - `/config set` و `/config unset` (نیازمند فعال بودن فرمان) - غیرفعال‌سازی: + غیرفعال کردن: ```json5 { @@ -718,37 +716,37 @@ curl "https://api.telegram.org/bot/getUpdates" - پیش‌فرض، long polling است. برای حالت webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath`، `webhookHost`، `webhookPort` اختیاری هستند (پیش‌فرض‌ها `/telegram-webhook`، `127.0.0.1`، `8787`). + پیش‌فرض long polling است. برای حالت webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath`، `webhookHost`، `webhookPort` اختیاری هستند (پیش‌فرض‌ها `/telegram-webhook`، `127.0.0.1`، `8787`). - شنونده محلی به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یا یک reverse proxy جلوی پورت محلی قرار دهید یا آگاهانه `webhookHost: "0.0.0.0"` را تنظیم کنید. + شنوندهٔ محلی به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یا یک reverse proxy جلوی پورت محلی قرار دهید یا آگاهانه `webhookHost: "0.0.0.0"` را تنظیم کنید. - حالت Webhook قبل از برگرداندن `200` به Telegram، محافظ‌های درخواست، توکن محرمانه Telegram و بدنه JSON را اعتبارسنجی می‌کند. - سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از طریق همان مسیرهای باتِ هر گفت‌وگو/هر موضوع که در long polling استفاده می‌شوند پردازش می‌کند، بنابراین نوبت‌های کند عامل، ACK تحویل Telegram را معطل نمی‌کنند. + حالت Webhook پیش از بازگرداندن `200` به Telegram، نگهبان‌های درخواست، توکن محرمانهٔ Telegram و بدنهٔ JSON را اعتبارسنجی می‌کند. + سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از طریق همان مسیرهای ربات برای هر چت/هر موضوع که در long polling استفاده می‌شود پردازش می‌کند، بنابراین نوبت‌های کند عامل، ACK تحویل Telegram را نگه نمی‌دارند. - - پیش‌فرض `channels.telegram.textChunkLimit` برابر 4000 است. - - `channels.telegram.chunkMode="newline"` پیش از تقسیم بر اساس طول، مرزهای پاراگراف (خطوط خالی) را ترجیح می‌دهد. - - `channels.telegram.mediaMaxMb` (پیش‌فرض 100) اندازه رسانه ورودی و خروجی Telegram را محدود می‌کند. - - `channels.telegram.timeoutSeconds` مهلت زمانی کلاینت Telegram API را بازنویسی می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). - - `channels.telegram.pollingStallThresholdMs` به‌صورت پیش‌فرض `120000` است؛ فقط برای راه‌اندازی دوباره‌های کاذب polling-stall آن را بین `30000` و `600000` تنظیم کنید. - - تاریخچه زمینه گروه از `channels.telegram.historyLimit` یا `messages.groupChat.historyLimit` استفاده می‌کند (پیش‌فرض 50)؛ `0` آن را غیرفعال می‌کند. - - زمینه تکمیلی reply/quote/forward در حال حاضر همان‌طور که دریافت می‌شود ارسال می‌شود. - - allowlistهای Telegram عمدتاً تعیین می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل حذف زمینه تکمیلی. - - کنترل‌های تاریخچه DM: + - مقدار پیش‌فرض `channels.telegram.textChunkLimit` برابر 4000 است. + - `channels.telegram.chunkMode="newline"` پیش از تقسیم بر اساس طول، مرزهای پاراگراف (خط‌های خالی) را ترجیح می‌دهد. + - `channels.telegram.mediaMaxMb` (پیش‌فرض 100) اندازهٔ رسانهٔ ورودی و خروجی Telegram را محدود می‌کند. + - `channels.telegram.timeoutSeconds` مهلت زمانی کلاینت API Telegram را بازنویسی می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های ربات long-polling مقدارهای پیکربندی‌شده کمتر از نگهبان درخواست 45 ثانیه‌ای `getUpdates` را محدود می‌کنند تا pollهای بیکار پیش از تکمیل پنجرهٔ poll سی‌ثانیه‌ای لغو نشوند. + - مقدار پیش‌فرض `channels.telegram.pollingStallThresholdMs` برابر `120000` است؛ فقط برای راه‌اندازی‌های دوبارهٔ مثبت کاذب توقف polling، آن را بین `30000` و `600000` تنظیم کنید. + - تاریخچهٔ بافت گروه از `channels.telegram.historyLimit` یا `messages.groupChat.historyLimit` استفاده می‌کند (پیش‌فرض 50)؛ `0` غیرفعال می‌کند. + - بافت تکمیلی پاسخ/نقل‌قول/بازارسال در حال حاضر همان‌طور که دریافت شده منتقل می‌شود. + - allowlistهای Telegram عمدتاً کنترل می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل حذف بافت تکمیلی. + - کنترل‌های تاریخچهٔ DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - پیکربندی `channels.telegram.retry` برای خطاهای قابل‌بازیابی API خروجی، روی کمک‌کننده‌های ارسال Telegram (CLI/tools/actions) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش از اتصال Telegram از یک safe-send retry محدود استفاده می‌کند، اما envelopeهای شبکه مبهم پس از ارسال را که می‌توانند پیام‌های قابل‌مشاهده را تکراری کنند دوباره امتحان نمی‌کند. + - پیکربندی `channels.telegram.retry` برای خطاهای قابل بازیابی API خروجی، روی کمک‌کننده‌های ارسال Telegram (CLI/ابزارها/کنش‌ها) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش‌اتصال Telegram از یک تلاش دوبارهٔ محدود safe-send استفاده می‌کند، اما envelopeهای شبکه‌ای مبهم پس از ارسال را که می‌توانند پیام‌های قابل مشاهده را تکراری کنند دوباره تلاش نمی‌کند. - هدف ارسال CLI می‌تواند شناسه عددی گفت‌وگو یا نام کاربری باشد: + هدف ارسال CLI می‌تواند شناسهٔ عددی چت یا نام کاربری باشد: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - pollهای Telegram از `openclaw message poll` استفاده می‌کنند و از موضوع‌های forum پشتیبانی می‌کنند: + pollهای Telegram از `openclaw message poll` استفاده می‌کنند و از موضوع‌های انجمن پشتیبانی می‌کنند: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -758,41 +756,41 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - پرچم‌های poll مختص Telegram: + پرچم‌های poll فقط مخصوص Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` برای موضوع‌های forum (یا از هدف `:topic:` استفاده کنید) + - `--thread-id` برای موضوع‌های انجمن (یا از یک هدف `:topic:` استفاده کنید) ارسال Telegram همچنین پشتیبانی می‌کند از: - - `--presentation` همراه با بلوک‌های `buttons` برای صفحه‌کلیدهای inline، وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد - - `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل pin‌شده، وقتی بات بتواند در آن گفت‌وگو pin کند - - `--force-document` برای ارسال تصاویر و GIFهای خروجی به‌صورت سند، به‌جای بارگذاری‌های عکس فشرده یا رسانه متحرک + - `--presentation` با بلوک‌های `buttons` برای صفحه‌کلیدهای inline وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد + - `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل سنجاق‌شده وقتی ربات بتواند در آن چت سنجاق کند + - `--force-document` برای ارسال تصویرها و GIFهای خروجی به‌صورت سند به‌جای بارگذاری‌های عکس فشرده یا رسانهٔ متحرک - کنترل action: + محدودسازی کنش: - - `channels.telegram.actions.sendMessage=false` پیام‌های خروجی Telegram، از جمله pollها، را غیرفعال می‌کند - - `channels.telegram.actions.poll=false` ساخت poll در Telegram را غیرفعال می‌کند و ارسال‌های معمول را فعال نگه می‌دارد + - `channels.telegram.actions.sendMessage=false` پیام‌های خروجی Telegram، از جمله pollها را غیرفعال می‌کند + - `channels.telegram.actions.poll=false` ایجاد poll در Telegram را غیرفعال می‌کند، در حالی که ارسال‌های معمولی همچنان فعال می‌مانند - Telegram از تأییدهای exec در DMهای تأییدکننده پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در گفت‌وگو یا موضوع مبدأ منتشر کند. تأییدکنندگان باید شناسه‌های عددی کاربر Telegram باشند. + Telegram از تأییدهای exec در DMهای تأییدکننده پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری اعلان‌ها را در چت یا موضوع مبدأ منتشر کند. تأییدکننده‌ها باید شناسهٔ عددی کاربر Telegram باشند. مسیر پیکربندی: - - `channels.telegram.execApprovals.enabled` (وقتی حداقل یک تأییدکننده قابل تشخیص باشد، خودکار فعال می‌شود) + - `channels.telegram.execApprovals.enabled` (وقتی دست‌کم یک تأییدکننده قابل حل باشد، به‌طور خودکار فعال می‌شود) - `channels.telegram.execApprovals.approvers` (به شناسه‌های عددی مالک از `commands.ownerAllowFrom` برمی‌گردد) - `channels.telegram.execApprovals.target`: `dm` (پیش‌فرض) | `channel` | `both` - - `agentFilter`، `sessionFilter` + - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`، `groupAllowFrom`، و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با بات صحبت کند و بات پاسخ‌های عادی را کجا می‌فرستد. این‌ها کسی را به تأییدکننده exec تبدیل نمی‌کنند. اولین جفت‌سازی DM تأییدشده، وقتی هنوز مالک فرمانی وجود ندارد، `commands.ownerAllowFrom` را راه‌اندازی اولیه می‌کند، بنابراین راه‌اندازی تک‌مالک همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند. + `channels.telegram.allowFrom`، `groupAllowFrom` و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با ربات صحبت کند و ربات پاسخ‌های عادی را کجا بفرستد. آن‌ها کسی را به تأییدکنندهٔ exec تبدیل نمی‌کنند. نخستین جفت‌سازی DM تأییدشده، وقتی هنوز هیچ مالک فرمانی وجود ندارد، `commands.ownerAllowFrom` را bootstrap می‌کند، بنابراین راه‌اندازی تک‌مالک همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند. - تحویل کانال، متن فرمان را در گفت‌وگو نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوع‌های مورد اعتماد فعال کنید. وقتی prompt در یک موضوع forum قرار می‌گیرد، OpenClaw موضوع را برای prompt تأیید و پیگیری حفظ می‌کند. تأییدهای exec به‌صورت پیش‌فرض پس از 30 دقیقه منقضی می‌شوند. + تحویل کانال متن فرمان را در چت نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوع‌های مورد اعتماد فعال کنید. وقتی اعلان در یک موضوع انجمن قرار می‌گیرد، OpenClaw موضوع را برای اعلان تأیید و پیگیری حفظ می‌کند. تأییدهای exec به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند. - دکمه‌های تأیید inline نیز نیاز دارند `channels.telegram.capabilities.inlineButtons` سطح هدف (`dm`، `group`، یا `all`) را مجاز کند. شناسه‌های تأیید با پیشوند `plugin:` از طریق تأییدهای Plugin resolve می‌شوند؛ سایر موارد ابتدا از طریق تأییدهای exec resolve می‌شوند. + دکمه‌های تأیید inline نیز نیاز دارند `channels.telegram.capabilities.inlineButtons` سطح هدف (`dm`، `group` یا `all`) را مجاز کند. شناسه‌های تأیید با پیشوند `plugin:` از طریق تأییدهای plugin حل می‌شوند؛ بقیه ابتدا از طریق تأییدهای exec حل می‌شوند. [تأییدهای exec](/fa/tools/exec-approvals) را ببینید. @@ -801,14 +799,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## کنترل‌های پاسخ خطا -وقتی عامل با خطای تحویل یا provider روبه‌رو می‌شود، Telegram می‌تواند با متن خطا پاسخ دهد یا آن را سرکوب کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند: +وقتی عامل با خطای تحویل یا ارائه‌دهنده روبه‌رو می‌شود، Telegram می‌تواند یا با متن خطا پاسخ دهد یا آن را سرکوب کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند: -| کلید | مقدارها | پیش‌فرض | توضیح | +| کلید | مقدارها | پیش‌فرض | توضیح | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به گفت‌وگو می‌فرستد. `silent` پاسخ‌های خطا را کاملاً سرکوب می‌کند. | -| `channels.telegram.errorCooldownMs` | عدد (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان گفت‌وگو. از هرزپیام خطا هنگام اختلال جلوگیری می‌کند. | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به چت می‌فرستد. `silent` پاسخ‌های خطا را کاملاً سرکوب می‌کند. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان چت. از هرزپراکنی خطا هنگام قطعی‌ها جلوگیری می‌کند. | -بازنویسی‌های هر حساب، هر گروه، و هر موضوع پشتیبانی می‌شوند (همان وراثت کلیدهای دیگر پیکربندی Telegram). +بازنویسی‌های برای هر حساب، هر گروه، و هر موضوع پشتیبانی می‌شوند (همان وراثت کلیدهای پیکربندی دیگر Telegram). ```json5 { @@ -829,54 +827,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## عیب‌یابی - + - - اگر `requireMention=false` باشد، حالت privacy در Telegram باید دید کامل را اجازه دهد. + - اگر `requireMention=false` باشد، حالت حریم خصوصی Telegram باید دید کامل را مجاز کند. - BotFather: `/setprivacy` -> Disable - - سپس بات را از گروه حذف و دوباره اضافه کنید - - وقتی پیکربندی انتظار پیام‌های گروهی بدون mention را دارد، `openclaw channels status` هشدار می‌دهد. - - `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard `"*"` را نمی‌توان از نظر عضویت probe کرد. + - سپس ربات را از گروه حذف و دوباره اضافه کنید + - وقتی پیکربندی انتظار پیام‌های گروهی بدون mention را داشته باشد، `openclaw channels status` هشدار می‌دهد. + - `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ عضویت wildcard `"*"` قابل probe نیست. - آزمون سریع نشست: `/activation always`. - + - وقتی `channels.telegram.groups` وجود دارد، گروه باید فهرست شده باشد (یا شامل `"*"` باشد) - - عضویت بات در گروه را تأیید کنید - - لاگ‌ها را بررسی کنید: `openclaw logs --follow` برای دلیل‌های نادیده‌گرفتن + - عضویت ربات در گروه را بررسی کنید + - لاگ‌ها را بازبینی کنید: `openclaw logs --follow` برای دلیل‌های رد شدن - + - - هویت فرستنده خود را مجاز کنید (جفت‌سازی و/یا `allowFrom` عددی) - - مجوز فرمان حتی وقتی سیاست گروه `open` است نیز اعمال می‌شود - - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی بومی ورودی‌های زیادی دارد؛ فرمان‌های Plugin/skill/custom را کاهش دهید یا منوهای بومی را غیرفعال کنید - - فراخوانی‌های startup مربوط به `deleteMyCommands` / `setMyCommands` محدود هستند و هنگام timeout درخواست، یک‌بار از طریق fallback انتقال Telegram دوباره تلاش می‌شوند. خطاهای پایدار network/fetch معمولاً نشان‌دهنده مشکلات دسترسی DNS/HTTPS به `api.telegram.org` هستند + - هویت فرستندهٔ خود را مجاز کنید (جفت‌سازی و/یا `allowFrom` عددی) + - مجوزدهی فرمان حتی وقتی سیاست گروه `open` باشد همچنان اعمال می‌شود + - `setMyCommands failed` با `BOT_COMMANDS_TOO_MUCH` یعنی منوی بومی ورودی‌های خیلی زیادی دارد؛ فرمان‌های plugin/skill/سفارشی را کاهش دهید یا منوهای بومی را غیرفعال کنید + - فراخوانی‌های راه‌اندازی `deleteMyCommands` / `setMyCommands` محدود هستند و هنگام مهلت زمانی درخواست، یک‌بار از طریق fallback انتقال Telegram دوباره تلاش می‌شوند. خطاهای پایدار شبکه/fetch معمولاً نشان‌دهندهٔ مشکلات دسترسی DNS/HTTPS به `api.telegram.org` هستند - + - - `getMe returned 401` یک شکست احراز هویت Telegram برای توکن بات پیکربندی‌شده است. - - توکن بات را در BotFather دوباره کپی یا بازتولید کنید، سپس `channels.telegram.botToken`، `channels.telegram.tokenFile`، `channels.telegram.accounts..botToken`، یا `TELEGRAM_BOT_TOKEN` را برای حساب پیش‌فرض به‌روزرسانی کنید. - - `deleteWebhook 401 Unauthorized` هنگام startup نیز شکست auth است؛ برخورد با آن به‌عنوان «هیچ webhook وجود ندارد» فقط همان شکست bad-token را به فراخوانی‌های بعدی API موکول می‌کند. - - اگر `deleteWebhook` هنگام startup مربوط به polling با خطای گذرای شبکه شکست بخورد، OpenClaw `getWebhookInfo` را بررسی می‌کند؛ وقتی Telegram یک URL خالی webhook گزارش می‌کند، polling ادامه می‌یابد چون پاک‌سازی از قبل انجام شده است. + - `getMe returned 401` یک شکست احراز هویت Telegram برای توکن پیکربندی‌شدهٔ ربات است. + - توکن ربات را در BotFather دوباره کپی یا بازتولید کنید، سپس برای حساب پیش‌فرض `channels.telegram.botToken`، `channels.telegram.tokenFile`، `channels.telegram.accounts..botToken`، یا `TELEGRAM_BOT_TOKEN` را به‌روزرسانی کنید. + - `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز شکست احراز هویت است؛ برخورد با آن به‌عنوان «هیچ webhookای وجود ندارد» فقط همان شکست توکن بد را به فراخوانی‌های بعدی API موکول می‌کند. + - اگر `deleteWebhook` هنگام راه‌اندازی polling با خطای گذرای شبکه شکست بخورد، OpenClaw `getWebhookInfo` را بررسی می‌کند؛ وقتی Telegram یک URL خالی webhook گزارش کند، polling ادامه می‌یابد چون پاک‌سازی از قبل برآورده شده است. - - Node 22+ + واکشی/پراکسی سفارشی می‌تواند در صورت ناسازگاری نوع‌های AbortSignal باعث رفتار لغو فوری شود. - - بعضی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 resolve می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث خرابی‌های متناوب API Telegram شود. - - اگر لاگ‌ها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این موارد را به‌عنوان خطاهای شبکه قابل‌بازیابی دوباره تلاش می‌کند. - - اگر لاگ‌ها شامل `Polling stall detected` باشند، OpenClaw به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون تکمیل زنده‌بودن long-poll، polling را دوباره راه‌اندازی می‌کند و انتقال Telegram را دوباره می‌سازد. - - `openclaw channels status --probe` و `openclaw doctor` زمانی هشدار می‌دهند که یک حساب polling در حال اجرا پس از مهلت شروع، `getUpdates` را تکمیل نکرده باشد، یک حساب webhook در حال اجرا پس از مهلت شروع، `setWebhook` را تکمیل نکرده باشد، یا آخرین فعالیت موفق انتقال polling کهنه شده باشد. - - فقط زمانی `channels.telegram.pollingStallThresholdMs` را افزایش دهید که فراخوانی‌های طولانی‌مدت `getUpdates` سالم هستند اما میزبان شما همچنان راه‌اندازی‌های دوباره کاذب polling-stall را گزارش می‌کند. stallهای پایدار معمولا به مشکلات پراکسی، DNS، IPv6 یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند. - - Telegram همچنین env پراکسی فرایند را برای انتقال Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌تواند `api.telegram.org` را دور بزند. - - اگر پراکسی مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای یک محیط سرویس پیکربندی شده باشد و هیچ env پراکسی استانداردی وجود نداشته باشد، Telegram برای انتقال Bot API نیز از همان URL استفاده می‌کند. - - روی میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های API Telegram را از طریق `channels.telegram.proxy` مسیریابی کنید: + - Node 22+ و fetch/proxy سفارشی می‌توانند در صورت ناسازگاری نوع‌های AbortSignal، رفتار لغو فوری را فعال کنند. + - برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 resolve می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث خطاهای متناوب Telegram API شود. + - اگر logها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این موارد را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند. + - اگر socketهای Telegram با یک آهنگ ثابت کوتاه بازیافت می‌شوند، مقدار پایین `channels.telegram.timeoutSeconds` را بررسی کنید؛ bot clientهای long-polling مقدارهای پیکربندی‌شده پایین‌تر از guard درخواست `getUpdates` را محدود می‌کنند، اما نسخه‌های قدیمی‌تر وقتی این مقدار پایین‌تر از timeout مربوط به long-poll تنظیم می‌شد، می‌توانستند هر poll را لغو کنند. + - اگر logها شامل `Polling stall detected` باشند، OpenClaw به‌صورت پیش‌فرض پس از ۱۲۰ ثانیه بدون کامل‌شدن liveness مربوط به long-poll، polling را دوباره راه‌اندازی می‌کند و transport تلگرام را دوباره می‌سازد. + - `openclaw channels status --probe` و `openclaw doctor` وقتی یک حساب polling در حال اجرا پس از مهلت startup، `getUpdates` را کامل نکرده باشد، وقتی یک حساب webhook در حال اجرا پس از مهلت startup، `setWebhook` را کامل نکرده باشد، یا وقتی آخرین فعالیت موفق transport مربوط به polling قدیمی شده باشد، هشدار می‌دهند. + - فقط زمانی `channels.telegram.pollingStallThresholdMs` را افزایش دهید که فراخوانی‌های طولانی‌مدت `getUpdates` سالم هستند اما میزبان شما همچنان restartهای کاذب polling-stall گزارش می‌کند. stallهای پایدار معمولا به مشکلات proxy، DNS، IPv6 یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند. + - Telegram همچنین envهای proxy فرایند را برای transport مربوط به Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌توانند `api.telegram.org` را دور بزنند. + - اگر proxy مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای یک محیط service پیکربندی شده باشد و env استاندارد proxy وجود نداشته باشد، Telegram از همان URL برای transport مربوط به Bot API نیز استفاده می‌کند. + - در میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های Telegram API را از طریق `channels.telegram.proxy` مسیریابی کنید: ```yaml channels: @@ -884,8 +883,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ به‌طور پیش‌فرض از `autoSelectFamily=true` (به‌جز WSL2) و `dnsResultOrder=ipv4first` استفاده می‌کند. - - اگر میزبان شما WSL2 است یا صراحتا با رفتار فقط IPv4 بهتر کار می‌کند، انتخاب family را اجباری کنید: + - Node 22+ به‌صورت پیش‌فرض از `autoSelectFamily=true` (به‌جز WSL2) و `dnsResultOrder=ipv4first` استفاده می‌کند. + - اگر میزبان شما WSL2 است یا به‌صراحت با رفتار فقط IPv4 بهتر کار می‌کند، انتخاب family را اجباری کنید: ```yaml channels: @@ -894,11 +893,11 @@ channels: autoSelectFamily: false ``` - - پاسخ‌های محدوده بنچمارک RFC 2544 (`198.18.0.0/15`) از قبل به‌طور پیش‌فرض - برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP مورد اعتماد یا - پراکسی شفاف، `api.telegram.org` را هنگام دانلود رسانه به یک نشانی - خصوصی/داخلی/کاربرد ویژه دیگر بازنویسی می‌کند، می‌توانید برای دور زدن - فقط مخصوص Telegram opt in کنید: + - پاسخ‌های benchmark-range مربوط به RFC 2544 (`198.18.0.0/15`) از قبل به‌صورت پیش‌فرض + برای دانلودهای رسانه‌ای Telegram مجاز هستند. اگر یک fake-IP قابل اعتماد یا + proxy شفاف، `api.telegram.org` را هنگام دانلود رسانه به یک نشانی + private/internal/special-use دیگر بازنویسی می‌کند، می‌توانید bypass فقط مخصوص Telegram را + فعال کنید: ```yaml channels: @@ -907,18 +906,18 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - همین opt-in برای هر حساب نیز در + - همین opt-in به‌ازای هر حساب نیز در `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` در دسترس است. - - اگر پراکسی شما میزبان‌های رسانه Telegram را به `198.18.x.x` resolve می‌کند، ابتدا - پرچم خطرناک را خاموش نگه دارید. رسانه Telegram از قبل به‌طور پیش‌فرض - محدوده بنچمارک RFC 2544 را مجاز می‌کند. + - اگر proxy شما میزبان‌های رسانه‌ای Telegram را به `198.18.x.x` resolve می‌کند، ابتدا + flag خطرناک را خاموش نگه دارید. رسانه Telegram از قبل به‌صورت پیش‌فرض محدوده + benchmark مربوط به RFC 2544 را مجاز می‌داند. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` حفاظت‌های SSRF رسانه - Telegram را ضعیف می‌کند. فقط برای محیط‌های پراکسی مورد اعتماد و تحت کنترل - اپراتور مانند مسیریابی fake-IP در Clash، Mihomo یا Surge از آن استفاده کنید، - زمانی که آن‌ها پاسخ‌های خصوصی یا کاربرد ویژه خارج از محدوده بنچمارک RFC 2544 - می‌سازند. برای دسترسی عادی Telegram از اینترنت عمومی، آن را خاموش نگه دارید. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه + Telegram را ضعیف می‌کند. فقط در محیط‌های proxy قابل اعتماد و تحت کنترل operator + مانند مسیریابی fake-IP در Clash، Mihomo یا Surge، وقتی پاسخ‌های private یا special-use + خارج از محدوده benchmark مربوط به RFC 2544 تولید می‌کنند، از آن استفاده کنید. + برای دسترسی معمول Telegram از اینترنت عمومی، آن را خاموش نگه دارید. - overrideهای محیطی (موقت): @@ -941,48 +940,48 @@ dig +short api.telegram.org AAAA مرجع اصلی: [مرجع پیکربندی - Telegram](/fa/gateway/config-channels#telegram). - + -- راه‌اندازی/احراز هویت: `enabled`، `botToken`، `tokenFile`، `accounts.*` (`tokenFile` باید به یک فایل عادی اشاره کند؛ symlinkها رد می‌شوند) -- کنترل دسترسی: `dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`، `groups`، `groups.*.topics.*`، `bindings[]` سطح بالا (`type: "acp"`) -- تاییدهای exec: `execApprovals`، `accounts.*.execApprovals` -- فرمان/منو: `commands.native`، `commands.nativeSkills`، `customCommands` -- رشته‌بندی/پاسخ‌ها: `replyToMode` -- streaming: `streaming` (پیش‌نمایش)، `streaming.preview.toolProgress`، `blockStreaming` -- قالب‌بندی/تحویل: `textChunkLimit`، `chunkMode`، `linkPreview`، `responsePrefix` -- رسانه/شبکه: `mediaMaxMb`، `timeoutSeconds`، `pollingStallThresholdMs`، `retry`، `network.autoSelectFamily`، `network.dangerouslyAllowPrivateNetwork`، `proxy` -- ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ `/bot` را شامل نکنید) -- webhook: `webhookUrl`، `webhookSecret`، `webhookPath`، `webhookHost` -- کنش‌ها/قابلیت‌ها: `capabilities.inlineButtons`، `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` -- واکنش‌ها: `reactionNotifications`، `reactionLevel` -- خطاها: `errorPolicy`، `errorCooldownMs` -- نوشتن‌ها/تاریخچه: `configWrites`، `historyLimit`، `dmHistoryLimit`، `dms.*.historyLimit` +- راه‌اندازی/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` باید به یک فایل معمولی اشاره کند؛ symlinkها رد می‌شوند) +- کنترل دسترسی: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, top-level `bindings[]` (`type: "acp"`) +- تأییدهای exec: `execApprovals`, `accounts.*.execApprovals` +- فرمان/menu: `commands.native`, `commands.nativeSkills`, `customCommands` +- threadها/replyها: `replyToMode` +- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- قالب‌بندی/تحویل: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- رسانه/network: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` +- ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ `/bot` را وارد نکنید) +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- actionها/capabilityها: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- واکنش‌ها: `reactionNotifications`, `reactionLevel` +- خطاها: `errorPolicy`, `errorCooldownMs` +- نوشتن‌ها/history: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا مسیریابی پیش‌فرض صریح شود. در غیر این صورت OpenClaw به اولین شناسه حساب نرمال‌شده fallback می‌کند و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه. +اولویت چندحسابی: وقتی دو یا چند account ID پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا routing پیش‌فرض صریح شود. در غیر این صورت OpenClaw به اولین account ID نرمال‌شده fallback می‌کند و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه. ## مرتبط - یک کاربر Telegram را به Gateway جفت کنید. + یک کاربر Telegram را با gateway جفت کنید. - رفتار allowlist گروه و موضوع. + رفتار allowlist گروه و topic. - - پیام‌های ورودی را به agentها مسیریابی کنید. + + پیام‌های ورودی را به agentها route کنید. - مدل تهدید و سخت‌سازی. + مدل تهدید و مقاوم‌سازی. - - گروه‌ها و موضوع‌ها را به agentها نگاشت کنید. + + گروه‌ها و topicها را به agentها map کنید. - عیب‌یابی‌های بین‌کانالی. + diagnostics بین‌کانالی. diff --git a/docs/fa/concepts/memory-search.md b/docs/fa/concepts/memory-search.md index ca4f8e5d5..81552923e 100644 --- a/docs/fa/concepts/memory-search.md +++ b/docs/fa/concepts/memory-search.md @@ -1,26 +1,26 @@ --- read_when: - - می‌خواهید بدانید memory_search چگونه کار می‌کند - - می‌خواهید یک ارائه‌دهندهٔ بردارسازی انتخاب کنید + - می‌خواهید بفهمید memory_search چگونه کار می‌کند + - می‌خواهید یک ارائه‌دهندهٔ امبدینگ انتخاب کنید - می‌خواهید کیفیت جست‌وجو را تنظیم کنید -summary: جست‌وجوی حافظه چگونه با استفاده از جاسازی‌ها و بازیابی ترکیبی یادداشت‌های مرتبط را پیدا می‌کند -title: جست‌وجوی حافظه +summary: جست‌وجوی حافظه چگونه یادداشت‌های مرتبط را با استفاده از تعبیه‌سازی‌ها و بازیابی ترکیبی پیدا می‌کند +title: جستجوی حافظه x-i18n: - generated_at: "2026-04-29T22:43:46Z" + generated_at: "2026-04-30T16:27:57Z" model: gpt-5.5 provider: openai - source_hash: 3e6c44d90f49a797bda01b9a575928c128a334f89ae14fc3620e65562a866aa9 + source_hash: 7f40bbe32453a28070ffc67f19a4c06e2fe59a24237a2aef353f4b9b8260bcf2 source_path: concepts/memory-search.md workflow: 16 --- -`memory_search` یادداشت‌های مرتبط را از فایل‌های حافظه شما پیدا می‌کند، حتی وقتی -عبارت‌بندی با متن اصلی متفاوت باشد. این کار با نمایه‌سازی حافظه به قطعه‌های -کوچک و جست‌وجوی آن‌ها با استفاده از تعبیه‌ها، کلیدواژه‌ها، یا هر دو انجام می‌شود. +`memory_search` یادداشت‌های مرتبط را از فایل‌های حافظه‌ی شما پیدا می‌کند، حتی وقتی +عبارت‌بندی با متن اصلی فرق داشته باشد. این کار با نمایه‌سازی حافظه در قطعه‌های +کوچک و جست‌وجوی آن‌ها با استفاده از embeddingها، کلیدواژه‌ها، یا هر دو انجام می‌شود. ## شروع سریع -اگر اشتراک GitHub Copilot یا کلید API پیکربندی‌شده برای OpenAI، Gemini، Voyage یا Mistral +اگر اشتراک GitHub Copilot، یا کلید API پیکربندی‌شده برای OpenAI، Gemini، Voyage، یا Mistral دارید، جست‌وجوی حافظه به‌صورت خودکار کار می‌کند. برای تنظیم صریح یک ارائه‌دهنده: ```json5 @@ -37,30 +37,31 @@ x-i18n: برای راه‌اندازی‌های چندنقطه‌پایانی، `provider` همچنین می‌تواند یک ورودی سفارشی `models.providers.` باشد، مانند `ollama-5080`، وقتی آن ارائه‌دهنده -`api: "ollama"` یا مالک آداپتور تعبیه دیگری را تنظیم می‌کند. +`api: "ollama"` یا مالک آداپتور embedding دیگری را تنظیم می‌کند. -برای تعبیه‌های محلی بدون کلید API، بسته اختیاری زمان اجرای `node-llama-cpp` -را کنار OpenClaw نصب کنید و از `provider: "local"` استفاده کنید. +برای embeddingهای محلی بدون کلید API، `provider: "local"` را تنظیم کنید. نصب‌های بسته‌بندی‌شده +runtime بومی `node-llama-cpp` را در درخت runtime-deps مربوط به Plugin مدیریت‌شده‌ی OpenClaw +نگه می‌دارند؛ اگر آن درخت به ترمیم نیاز دارد، `openclaw doctor --fix` را اجرا کنید. -برخی نقطه‌پایانی‌های تعبیه سازگار با OpenAI به برچسب‌های نامتقارن نیاز دارند، مانند +برخی نقطه‌پایانی‌های embedding سازگار با OpenAI به برچسب‌های نامتقارن مانند `input_type: "query"` برای جست‌وجوها و `input_type: "document"` یا `"passage"` -برای قطعه‌های نمایه‌شده. آن‌ها را با `memorySearch.queryInputType` و +برای قطعه‌های نمایه‌شده نیاز دارند. آن‌ها را با `memorySearch.queryInputType` و `memorySearch.documentInputType` پیکربندی کنید؛ [مرجع پیکربندی حافظه](/fa/reference/memory-config#provider-specific-config) را ببینید. -## ارائه‌دهندگان پشتیبانی‌شده +## ارائه‌دهنده‌های پشتیبانی‌شده | ارائه‌دهنده | شناسه | به کلید API نیاز دارد | یادداشت‌ها | | -------------- | ---------------- | ------------- | ---------------------------------------------------- | -| Bedrock | `bedrock` | خیر | وقتی زنجیره اعتبار AWS resolve شود، به‌صورت خودکار شناسایی می‌شود | -| Gemini | `gemini` | بله | از نمایه‌سازی تصویر/صدا پشتیبانی می‌کند | -| GitHub Copilot | `github-copilot` | خیر | به‌صورت خودکار شناسایی می‌شود، از اشتراک Copilot استفاده می‌کند | -| Local | `local` | خیر | مدل GGUF، دانلود حدود ۰٫۶ گیگابایت | -| Mistral | `mistral` | بله | به‌صورت خودکار شناسایی می‌شود | -| Ollama | `ollama` | خیر | محلی، باید صریح تنظیم شود | -| OpenAI | `openai` | بله | به‌صورت خودکار شناسایی می‌شود، سریع | -| Voyage | `voyage` | بله | به‌صورت خودکار شناسایی می‌شود | +| Bedrock | `bedrock` | خیر | وقتی زنجیره‌ی اعتبارنامه‌ی AWS resolve شود، به‌صورت خودکار شناسایی می‌شود | +| Gemini | `gemini` | بله | از نمایه‌سازی تصویر/صدا پشتیبانی می‌کند | +| GitHub Copilot | `github-copilot` | خیر | به‌صورت خودکار شناسایی می‌شود، از اشتراک Copilot استفاده می‌کند | +| Local | `local` | خیر | مدل GGUF، دانلود حدود ۰٫۶ گیگابایت | +| Mistral | `mistral` | بله | به‌صورت خودکار شناسایی می‌شود | +| Ollama | `ollama` | خیر | محلی، باید صریح تنظیم شود | +| OpenAI | `openai` | بله | به‌صورت خودکار شناسایی می‌شود، سریع | +| Voyage | `voyage` | بله | به‌صورت خودکار شناسایی می‌شود | -## نحوه کار جست‌وجو +## جست‌وجو چگونه کار می‌کند OpenClaw دو مسیر بازیابی را به‌صورت موازی اجرا می‌کند و نتایج را ادغام می‌کند: @@ -75,36 +76,36 @@ flowchart LR M --> R["Top Results"] ``` -- **جست‌وجوی برداری** یادداشت‌هایی با معنای مشابه پیدا می‌کند («میزبان Gateway» با - «ماشینی که OpenClaw را اجرا می‌کند» تطبیق می‌یابد). +- **جست‌وجوی برداری** یادداشت‌هایی با معنای مشابه را پیدا می‌کند ("gateway host" با + "the machine running OpenClaw" تطبیق می‌یابد). - **جست‌وجوی کلیدواژه‌ای BM25** تطبیق‌های دقیق را پیدا می‌کند (شناسه‌ها، رشته‌های خطا، کلیدهای پیکربندی). -اگر فقط یک مسیر در دسترس باشد (بدون تعبیه‌ها یا بدون FTS)، همان مسیر به‌تنهایی اجرا می‌شود. +اگر فقط یک مسیر در دسترس باشد (بدون embedding یا بدون FTS)، همان مسیر به‌تنهایی اجرا می‌شود. -وقتی تعبیه‌ها در دسترس نباشند، OpenClaw همچنان به‌جای بازگشت صرف به ترتیب تطبیق دقیق خام، از رتبه‌بندی واژگانی روی نتایج FTS استفاده می‌کند. این حالت تنزل‌یافته، قطعه‌هایی را که پوشش قوی‌تری برای واژه‌های جست‌وجو و مسیرهای فایل مرتبط دارند تقویت می‌کند، که باعث می‌شود بازیابی حتی بدون `sqlite-vec` یا ارائه‌دهنده تعبیه مفید بماند. +وقتی embeddingها در دسترس نیستند، OpenClaw همچنان به‌جای بازگشت صرف به ترتیب‌دهی خام مبتنی بر تطبیق دقیق، از رتبه‌بندی واژگانی روی نتایج FTS استفاده می‌کند. آن حالت تنزل‌یافته قطعه‌هایی را که پوشش قوی‌تری از عبارت‌های پرس‌وجو و مسیرهای فایل مرتبط دارند تقویت می‌کند، که حتی بدون `sqlite-vec` یا ارائه‌دهنده‌ی embedding نیز یادآوری را مفید نگه می‌دارد. ## بهبود کیفیت جست‌وجو -دو قابلیت اختیاری وقتی تاریخچه یادداشت بزرگی دارید کمک می‌کنند: +دو قابلیت اختیاری زمانی کمک می‌کنند که تاریخچه‌ی یادداشت بزرگی دارید: -### افت زمانی +### کاهش زمانی -یادداشت‌های قدیمی به‌تدریج وزن رتبه‌بندی خود را از دست می‌دهند تا اطلاعات جدیدتر ابتدا نمایش داده شوند. -با نیمه‌عمر پیش‌فرض ۳۰ روز، امتیاز یادداشتی از ماه گذشته ۵۰٪ وزن -اصلی خود خواهد بود. فایل‌های همیشه‌سبز مانند `MEMORY.md` هرگز دچار افت نمی‌شوند. +یادداشت‌های قدیمی به‌تدریج وزن رتبه‌بندی خود را از دست می‌دهند تا اطلاعات جدیدتر اول ظاهر شوند. +با نیمه‌عمر پیش‌فرض ۳۰ روز، یادداشتی از ماه گذشته ۵۰٪ وزن +اصلی خود را می‌گیرد. فایل‌های همیشه‌سبز مانند `MEMORY.md` هرگز کاهش داده نمی‌شوند. -اگر عامل شما ماه‌ها یادداشت روزانه دارد و اطلاعات کهنه همچنان بالاتر از زمینه جدیدتر رتبه می‌گیرند، افت زمانی را فعال کنید. +اگر agent شما ماه‌ها یادداشت روزانه دارد و اطلاعات کهنه همچنان بالاتر از زمینه‌ی جدید رتبه می‌گیرند، کاهش زمانی را فعال کنید. ### MMR (تنوع) -نتایج تکراری را کاهش می‌دهد. اگر پنج یادداشت همگی به همان پیکربندی روتر اشاره کنند، MMR -اطمینان می‌دهد که نتایج برتر به‌جای تکرار، موضوعات متفاوتی را پوشش دهند. +نتایج تکراری را کاهش می‌دهد. اگر پنج یادداشت همگی به یک پیکربندی router اشاره کنند، MMR +تضمین می‌کند نتایج برتر به‌جای تکرار، موضوعات متفاوتی را پوشش دهند. -اگر `memory_search` همچنان قطعه‌های تقریباً تکراری را از یادداشت‌های روزانه متفاوت برمی‌گرداند، MMR را فعال کنید. +اگر `memory_search` مدام قطعه‌های تقریباً تکراری از یادداشت‌های روزانه‌ی متفاوت برمی‌گرداند، MMR را فعال کنید. ### فعال‌سازی هر دو @@ -126,17 +127,17 @@ flowchart LR } ``` -## حافظه چندوجهی +## حافظه‌ی چندوجهی با Gemini Embedding 2، می‌توانید تصویرها و فایل‌های صوتی را در کنار -Markdown نمایه‌سازی کنید. پرس‌وجوهای جست‌وجو متنی باقی می‌مانند، اما با محتوای دیداری و صوتی -تطبیق داده می‌شوند. برای راه‌اندازی، [مرجع پیکربندی حافظه](/fa/reference/memory-config) را ببینید. +Markdown نمایه‌سازی کنید. پرس‌وجوهای جست‌وجو همچنان متنی می‌مانند، اما با محتوای دیداری و صوتی +تطبیق می‌یابند. برای راه‌اندازی، [مرجع پیکربندی حافظه](/fa/reference/memory-config) را ببینید. -## جست‌وجوی حافظه نشست +## جست‌وجوی حافظه‌ی نشست می‌توانید به‌صورت اختیاری رونوشت‌های نشست را نمایه‌سازی کنید تا `memory_search` بتواند -گفت‌وگوهای قبلی را به یاد بیاورد. این از طریق -`memorySearch.experimental.sessionMemory` با انتخاب شما فعال می‌شود. برای جزئیات، +گفت‌وگوهای قبلی را به یاد بیاورد. این قابلیت از طریق +`memorySearch.experimental.sessionMemory` انتخابی است. برای جزئیات، [مرجع پیکربندی](/fa/reference/memory-config) را ببینید. ## عیب‌یابی @@ -144,25 +145,24 @@ Markdown نمایه‌سازی کنید. پرس‌وجوهای جست‌وجو **نتیجه‌ای نیست؟** برای بررسی نمایه، `openclaw memory status` را اجرا کنید. اگر خالی است، `openclaw memory index --force` را اجرا کنید. -**فقط تطبیق‌های کلیدواژه‌ای؟** ممکن است ارائه‌دهنده تعبیه شما پیکربندی نشده باشد. بررسی کنید: +**فقط تطبیق‌های کلیدواژه‌ای؟** ممکن است ارائه‌دهنده‌ی embedding شما پیکربندی نشده باشد. بررسی کنید: `openclaw memory status --deep`. -**تعبیه‌های محلی timeout می‌شوند؟** `ollama`، `lmstudio`، و `local` به‌طور پیش‌فرض از timeout -دسته‌ای درون‌خطی طولانی‌تری استفاده می‌کنند. اگر میزبان صرفاً کند است، مقدار +**embeddingهای محلی timeout می‌شوند؟** `ollama`، `lmstudio`، و `local` به‌طور پیش‌فرض از timeout دسته‌ی inline طولانی‌تری استفاده می‌کنند. اگر میزبان صرفاً کند است، `agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` را تنظیم کنید و دوباره `openclaw memory index --force` را اجرا کنید. -**متن CJK پیدا نمی‌شود؟** نمایه FTS را با -`openclaw memory index --force` بازسازی کنید. +**متن CJK پیدا نمی‌شود؟** نمایه‌ی FTS را با +`openclaw memory index --force` دوباره بسازید. -## مطالعه بیشتر +## مطالعه‌ی بیشتر -- [Active Memory](/fa/concepts/active-memory) -- حافظه زیرعامل برای نشست‌های چت تعاملی -- [حافظه](/fa/concepts/memory) -- چیدمان فایل، پشتوانه‌ها، ابزارها -- [مرجع پیکربندی حافظه](/fa/reference/memory-config) -- همه گزینه‌های پیکربندی +- [Active Memory](/fa/concepts/active-memory) -- حافظه‌ی sub-agent برای نشست‌های گفت‌وگوی تعاملی +- [حافظه](/fa/concepts/memory) -- چیدمان فایل، backendها، ابزارها +- [مرجع پیکربندی حافظه](/fa/reference/memory-config) -- همه‌ی کنترل‌های پیکربندی ## مرتبط - [نمای کلی حافظه](/fa/concepts/memory) - [Active Memory](/fa/concepts/active-memory) -- [موتور حافظه داخلی](/fa/concepts/memory-builtin) +- [موتور حافظه‌ی داخلی](/fa/concepts/memory-builtin) diff --git a/docs/fa/concepts/messages.md b/docs/fa/concepts/messages.md index caf84a6f2..58335c4cf 100644 --- a/docs/fa/concepts/messages.md +++ b/docs/fa/concepts/messages.md @@ -1,20 +1,20 @@ --- read_when: - - توضیح اینکه پیام‌های ورودی چگونه به پاسخ تبدیل می‌شوند - - شفاف‌سازی دربارهٔ نشست‌ها، حالت‌های صف‌بندی یا رفتار پخش جریانی + - توضیح اینکه چگونه پیام‌های ورودی به پاسخ تبدیل می‌شوند + - شفاف‌سازی نشست‌ها، حالت‌های صف‌بندی یا رفتار پخش جریانی - مستندسازی قابلیت مشاهدهٔ استدلال و پیامدهای استفاده -summary: جریان پیام، نشست‌ها، صف‌بندی، و قابلیت مشاهدهٔ استدلال +summary: جریان پیام، نشست‌ها، صف‌بندی و مشاهده‌پذیری استدلال title: پیام‌ها x-i18n: - generated_at: "2026-04-30T09:36:05Z" + generated_at: "2026-04-30T16:27:51Z" model: gpt-5.5 provider: openai - source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e + source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 source_path: concepts/messages.md workflow: 16 --- -OpenClaw پیام‌های ورودی را از طریق خط لوله‌ای شامل تشخیص نشست، صف‌بندی، استریم‌کردن، اجرای ابزار، و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر پیام ورودی تا پاسخ را ترسیم می‌کند. +OpenClaw پیام‌های ورودی را از طریق خط لوله‌ای شامل تشخیص نشست، صف‌بندی، جریان‌سازی، اجرای ابزار و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر از پیام ورودی تا پاسخ را ترسیم می‌کند. ## جریان پیام (سطح بالا) @@ -28,23 +28,19 @@ Inbound message تنظیمات کلیدی در پیکربندی قرار دارند: -- `messages.*` برای پیشوندها، صف‌بندی، و رفتار گروه. -- `agents.defaults.*` برای پیش‌فرض‌های استریم بلوکی و قطعه‌بندی. -- بازنویسی‌های کانال (`channels.whatsapp.*`، `channels.telegram.*`، و غیره) برای سقف‌ها و کلیدهای استریم. +- `messages.*` برای پیشوندها، صف‌بندی و رفتار گروه. +- `agents.defaults.*` برای پیش‌فرض‌های جریان‌سازی بلوکی و تکه‌تکه‌سازی. +- بازنویسی‌های کانال (`channels.whatsapp.*`، `channels.telegram.*` و غیره) برای سقف‌ها و کلیدهای جریان‌سازی. برای طرح‌واره کامل، [پیکربندی](/fa/gateway/configuration) را ببینید. ## حذف تکرار ورودی -کانال‌ها ممکن است پس از اتصال مجدد همان پیام را دوباره تحویل دهند. OpenClaw یک -کش کوتاه‌عمر نگه می‌دارد که با کانال/حساب/همتا/نشست/شناسه پیام کلیدگذاری می‌شود تا تحویل‌های -تکراری اجرای دیگری از عامل را آغاز نکنند. +کانال‌ها می‌توانند پس از اتصال دوباره همان پیام را دوباره تحویل دهند. OpenClaw یک کش کوتاه‌عمر نگه می‌دارد که با شناسه کانال/حساب/همتا/نشست/پیام کلیدگذاری شده است تا تحویل‌های تکراری باعث اجرای دوباره عامل نشوند. -## تجمیع تأخیری ورودی +## ضدپرش ورودی -پیام‌های پیاپی و سریع از **همان فرستنده** می‌توانند از طریق `messages.inbound` در یک نوبت -واحد عامل دسته‌بندی شوند. تجمیع تأخیری به ازای هر کانال + گفتگو محدود می‌شود -و از جدیدترین پیام برای رشته‌بندی/شناسه‌های پاسخ استفاده می‌کند. +پیام‌های پشت‌سرهم سریع از **همان فرستنده** می‌توانند از طریق `messages.inbound` در یک نوبت واحد عامل دسته‌بندی شوند. ضدپرش برای هر کانال + گفتگو محدوده‌بندی می‌شود و از تازه‌ترین پیام برای رشته‌بندی/شناسه‌های پاسخ استفاده می‌کند. پیکربندی (پیش‌فرض سراسری + بازنویسی‌های هر کانال): @@ -65,8 +61,8 @@ Inbound message نکته‌ها: -- تجمیع تأخیری روی پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله ارسال می‌شوند. -- فرمان‌های کنترلی تجمیع تأخیری را دور می‌زنند تا مستقل باقی بمانند — **مگر** زمانی که یک کانال به‌صراحت تجمیع DMهای هم‌فرستنده را فعال کند، مانند [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)، که در آن فرمان‌های DM در پنجره تجمیع تأخیری منتظر می‌مانند تا محتوای ارسال‌شده به‌صورت جداگانه بتواند به همان نوبت عامل بپیوندد. +- ضدپرش فقط روی پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند. +- فرمان‌های کنترلی ضدپرش را دور می‌زنند تا مستقل بمانند — **مگر** وقتی کانالی صراحتا در ادغام DM از همان فرستنده شرکت کند (برای نمونه [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))، که در آن فرمان‌های DM داخل پنجره ضدپرش منتظر می‌مانند تا محتوای ارسالِ تقسیم‌شده بتواند به همان نوبت عامل بپیوندد. ## نشست‌ها و دستگاه‌ها @@ -76,80 +72,58 @@ Inbound message - گروه‌ها/کانال‌ها کلیدهای نشست خودشان را می‌گیرند. - ذخیره‌گاه نشست و رونوشت‌ها روی میزبان Gateway قرار دارند. -چند دستگاه/کانال می‌توانند به یک نشست نگاشت شوند، اما تاریخچه به‌طور کامل -به همه کلاینت‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید -تا از زمینه واگرا جلوگیری شود. Control UI و TUI همیشه رونوشت نشست پشتیبانی‌شده توسط -Gateway را نشان می‌دهند، بنابراین منبع حقیقت هستند. +چند دستگاه/کانال می‌توانند به یک نشست نگاشت شوند، اما تاریخچه به‌طور کامل به همه کلاینت‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید تا از واگرایی زمینه جلوگیری شود. Control UI و TUI همیشه رونوشت نشست پشتیبانی‌شده توسط Gateway را نشان می‌دهند، پس منبع حقیقت هستند. جزئیات: [مدیریت نشست](/fa/concepts/session). ## فراداده نتیجه ابزار -`content` در نتیجه ابزار، نتیجه قابل مشاهده برای مدل است. `details` در نتیجه ابزار -فراداده زمان اجرا برای رندر UI، عیب‌یابی، تحویل رسانه، و Pluginها است. +`content` نتیجه ابزار، نتیجه قابل مشاهده برای مدل است. `details` نتیجه ابزار فراداده زمان اجرا برای رندر UI، عیب‌یابی، تحویل رسانه و Pluginها است. OpenClaw این مرز را صریح نگه می‌دارد: - `toolResult.details` پیش از بازپخش ارائه‌دهنده و ورودی Compaction حذف می‌شود. -- رونوشت‌های نشست ذخیره‌شده فقط `details` محدود را نگه می‌دارند؛ فراداده بیش‌ازحد بزرگ - با خلاصه‌ای فشرده که با `persistedDetailsTruncated: true` نشانه‌گذاری شده جایگزین می‌شود. -- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` قرار دهند، نه فقط - در `details`. +- رونوشت‌های نشست پایدارشده فقط `details` محدود را نگه می‌دارند؛ فراداده بزرگ‌تر با خلاصه‌ای فشرده جایگزین می‌شود که با `persistedDetailsTruncated: true` علامت‌گذاری شده است. +- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` قرار دهند، نه فقط در `details`. ## بدنه‌های ورودی و زمینه تاریخچه OpenClaw **بدنه پرامپت** را از **بدنه فرمان** جدا می‌کند: -- `Body`: متن پرامپت ارسال‌شده به عامل. این ممکن است شامل پوشش‌های کانال و - پوشش‌های اختیاری تاریخچه باشد. -- `CommandBody`: متن خام کاربر برای تجزیه دستور/فرمان. +- `BodyForAgent`: متن اصلی رو به مدل برای پیام فعلی. Pluginهای کانال باید این را روی متن فعلی فرستنده که حامل پرامپت است متمرکز نگه دارند. +- `Body`: جایگزین قدیمی پرامپت. این ممکن است شامل پوشش‌های کانال و پوشش‌های اختیاری تاریخچه باشد، اما کانال‌های فعلی نباید وقتی `BodyForAgent` در دسترس است به‌عنوان ورودی اصلی مدل به آن تکیه کنند. +- `CommandBody`: متن خام کاربر برای تحلیل دستورالعمل/فرمان. - `RawBody`: نام مستعار قدیمی برای `CommandBody` (برای سازگاری نگه داشته شده است). -وقتی یک کانال تاریخچه فراهم می‌کند، از پوشش مشترکی استفاده می‌کند: +وقتی یک کانال تاریخچه ارائه می‌کند، از پوشش مشترک استفاده می‌کند: - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` -برای **گفتگوهای غیرمستقیم** (گروه‌ها/کانال‌ها/اتاق‌ها)، پیشوند **بدنه پیام فعلی** -برچسب فرستنده است (همان سبکی که برای مدخل‌های تاریخچه استفاده می‌شود). این کار پیام‌های -بلادرنگ و صف‌شده/تاریخچه‌ای را در پرامپت عامل سازگار نگه می‌دارد. +برای **گفتگوهای غیرمستقیم** (گروه‌ها/کانال‌ها/اتاق‌ها)، **بدنه پیام فعلی** با برچسب فرستنده پیشوند می‌گیرد (همان سبکی که برای ورودی‌های تاریخچه استفاده می‌شود). این کار پیام‌های بی‌درنگ و صف‌شده/تاریخچه را در پرامپت عامل سازگار نگه می‌دارد. -بافرهای تاریخچه **فقط در انتظار** هستند: آن‌ها شامل پیام‌های گروهی می‌شوند که اجرای عامل را -آغاز _نکرده‌اند_ (برای مثال، پیام‌های مشروط به منشن) و پیام‌هایی را که -از قبل در رونوشت نشست هستند **حذف می‌کنند**. +بافرهای تاریخچه **فقط معلق** هستند: آن‌ها شامل پیام‌های گروهی می‌شوند که اجرا را _فعال نکرده‌اند_ (برای مثال، پیام‌های محدودشده به منشن) و پیام‌هایی را که از قبل در رونوشت نشست هستند **حذف می‌کنند**. -حذف دستور فقط روی بخش **پیام فعلی** اعمال می‌شود تا تاریخچه -دست‌نخورده بماند. کانال‌هایی که تاریخچه را پوشش می‌دهند باید `CommandBody` (یا -`RawBody`) را روی متن اصلی پیام تنظیم کنند و `Body` را به‌عنوان پرامپت ترکیبی نگه دارند. -بافرهای تاریخچه از طریق `messages.groupChat.historyLimit` (پیش‌فرض سراسری) -و بازنویسی‌های هر کانال مانند `channels.slack.historyLimit` یا -`channels.telegram.accounts..historyLimit` قابل پیکربندی هستند (برای غیرفعال‌کردن، `0` تنظیم کنید). +حذف دستورالعمل فقط روی بخش **پیام فعلی** اعمال می‌شود تا تاریخچه دست‌نخورده بماند. کانال‌هایی که تاریخچه را پوشش می‌دهند باید `CommandBody` (یا `RawBody`) را روی متن پیام اصلی تنظیم کنند و `Body` را به‌عنوان پرامپت ترکیبی نگه دارند. تاریخچه ساخت‌یافته، پاسخ، پیام‌های بازفرستاده‌شده و فراداده کانال هنگام مونتاژ پرامپت به‌صورت بلوک‌های زمینه غیرقابل اعتماد با نقش کاربر رندر می‌شوند. +بافرهای تاریخچه از طریق `messages.groupChat.historyLimit` (پیش‌فرض سراسری) و بازنویسی‌های هر کانال مانند `channels.slack.historyLimit` یا `channels.telegram.accounts..historyLimit` قابل پیکربندی هستند (`0` را برای غیرفعال‌سازی تنظیم کنید). ## صف‌بندی و پیگیری‌ها -اگر یک اجرا از قبل فعال باشد، پیام‌های ورودی می‌توانند صف شوند، به اجرای -فعلی هدایت شوند، یا برای نوبت پیگیری جمع‌آوری شوند. +اگر اجرایی از قبل فعال باشد، پیام‌های ورودی می‌توانند صف شوند، به اجرای فعلی هدایت شوند، یا برای یک نوبت پیگیری جمع‌آوری شوند. - از طریق `messages.queue` (و `messages.queue.byChannel`) پیکربندی کنید. -- حالت پیش‌فرض `steer` است، با تجمیع تأخیری ۵۰۰ میلی‌ثانیه‌ای برای پیگیری وقتی هدایت - به تحویل پیگیری صف‌شده بازمی‌گردد. -- حالت‌ها: `steer`، `followup`، `collect`، `steer-backlog`، `interrupt`، و حالت قدیمی - تک‌به‌تک `queue`. +- حالت پیش‌فرض `steer` است، با ضدپرش پیگیری ۵۰۰ میلی‌ثانیه‌ای وقتی هدایت به تحویل پیگیری صف‌شده برمی‌گردد. +- حالت‌ها: `steer`، `followup`، `collect`، `steer-backlog`، `interrupt`، و حالت قدیمی یکی‌درهرزمان `queue`. جزئیات: [صف فرمان](/fa/concepts/queue) و [صف هدایت](/fa/concepts/queue-steering). ## مالکیت اجرای کانال -Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورودی را تجمیع تأخیری کنند، و پیش از ورود پیام -به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید یک -مهلت زمانی جداگانه دور خود نوبت عامل تحمیل کنند. پس از اینکه پیام به یک -نشست مسیریابی شد، کار طولانی‌مدت توسط چرخه عمر نشست، ابزار، و زمان اجرا -کنترل می‌شود تا همه کانال‌ها نوبت‌های کند را به‌طور سازگار گزارش کنند و از آن‌ها بازیابی شوند. +Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورودی را ضدپرش کنند و پیش از ورود پیام به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید زمان‌سنج جداگانه‌ای دور خود نوبت عامل تحمیل کنند. وقتی پیام به یک نشست مسیریابی شد، کارهای طولانی‌مدت توسط چرخه عمر نشست، ابزار و زمان اجرا اداره می‌شوند تا همه کانال‌ها نوبت‌های کند را به‌شکل سازگار گزارش دهند و بازیابی کنند. -## استریم، قطعه‌بندی، و دسته‌بندی +## جریان‌سازی، تکه‌تکه‌سازی و دسته‌بندی -استریم بلوکی، پاسخ‌های جزئی را همان‌طور که مدل بلوک‌های متن را تولید می‌کند ارسال می‌کند. -قطعه‌بندی محدودیت‌های متن کانال را رعایت می‌کند و از شکستن بلوک‌های کد حصاردار جلوگیری می‌کند. +جریان‌سازی بلوکی پاسخ‌های جزئی را هم‌زمان با تولید بلوک‌های متن توسط مدل ارسال می‌کند. تکه‌تکه‌سازی محدودیت‌های متنی کانال را رعایت می‌کند و از تقسیم کردن کد حصارشده پرهیز می‌کند. تنظیمات کلیدی: @@ -157,58 +131,49 @@ Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورو - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) - `agents.defaults.blockStreamingCoalesce` (دسته‌بندی مبتنی بر بیکاری) -- `agents.defaults.humanDelay` (مکث انسان‌مانند بین پاسخ‌های بلوکی) +- `agents.defaults.humanDelay` (مکث شبیه انسان بین پاسخ‌های بلوکی) - بازنویسی‌های کانال: `*.blockStreaming` و `*.blockStreamingCoalesce` (کانال‌های غیر Telegram به `*.blockStreaming: true` صریح نیاز دارند) -جزئیات: [استریم + قطعه‌بندی](/fa/concepts/streaming). +جزئیات: [جریان‌سازی + تکه‌تکه‌سازی](/fa/concepts/streaming). ## نمایش‌پذیری استدلال و توکن‌ها OpenClaw می‌تواند استدلال مدل را آشکار یا پنهان کند: - `/reasoning on|off|stream` نمایش‌پذیری را کنترل می‌کند. -- محتوای استدلال وقتی توسط مدل تولید شود همچنان در مصرف توکن حساب می‌شود. -- Telegram از استریم استدلال به حباب پیش‌نویس پشتیبانی می‌کند. +- محتوای استدلال، وقتی توسط مدل تولید شود، همچنان در مصرف توکن حساب می‌شود. +- Telegram از جریان استدلال به داخل حباب پیش‌نویس پشتیبانی می‌کند. -جزئیات: [دستورهای فکر کردن + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use). +جزئیات: [دستورالعمل‌های فکر کردن + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use). -## پیشوندها، رشته‌بندی، و پاسخ‌ها +## پیشوندها، رشته‌بندی و پاسخ‌ها قالب‌بندی پیام خروجی در `messages` متمرکز شده است: -- `messages.responsePrefix`، `channels..responsePrefix`، و `channels..accounts..responsePrefix` (زنجیره پیشوند خروجی)، به‌علاوه `channels.whatsapp.messagePrefix` (پیشوند ورودی WhatsApp) +- `messages.responsePrefix`، `channels..responsePrefix` و `channels..accounts..responsePrefix` (آبشار پیشوند خروجی)، به‌علاوه `channels.whatsapp.messagePrefix` (پیشوند ورودی WhatsApp) - رشته‌بندی پاسخ از طریق `replyToMode` و پیش‌فرض‌های هر کانال جزئیات: [پیکربندی](/fa/gateway/config-agents#messages) و مستندات کانال. -## پاسخ‌های بی‌صدا +## پاسخ‌های خاموش -توکن دقیق بی‌صدا `NO_REPLY` / `no_reply` یعنی «پاسخ قابل مشاهده برای کاربر تحویل نده». -وقتی یک نوبت رسانه ابزار در انتظار نیز داشته باشد، مانند صوت TTS تولیدشده، OpenClaw -متن بی‌صدا را حذف می‌کند اما همچنان پیوست رسانه را تحویل می‌دهد. -OpenClaw این رفتار را بر اساس نوع گفتگو تعیین می‌کند: +توکن خاموش دقیق `NO_REPLY` / `no_reply` یعنی «پاسخ قابل مشاهده برای کاربر تحویل نده». +وقتی یک نوبت همچنین رسانه ابزار معلق دارد، مانند صوت TTS تولیدشده، OpenClaw متن خاموش را حذف می‌کند اما همچنان پیوست رسانه را تحویل می‌دهد. +OpenClaw این رفتار را بر اساس نوع گفتگو حل می‌کند: -- گفتگوهای مستقیم به‌طور پیش‌فرض سکوت را مجاز نمی‌دانند و یک پاسخ بی‌صدای تنها را - به جایگزینی کوتاه و قابل مشاهده بازنویسی می‌کنند. +- گفتگوهای مستقیم به‌طور پیش‌فرض سکوت را مجاز نمی‌دانند و یک پاسخ خاموش تنها را به جایگزین کوتاه قابل مشاهده بازنویسی می‌کنند. - گروه‌ها/کانال‌ها به‌طور پیش‌فرض سکوت را مجاز می‌دانند. -- هماهنگ‌سازی داخلی به‌طور پیش‌فرض سکوت را مجاز می‌داند. +- ارکستراسیون داخلی به‌طور پیش‌فرض سکوت را مجاز می‌داند. -OpenClaw همچنین برای خرابی‌های داخلی اجراکننده که پیش از هر پاسخ دستیار -در گفتگوهای غیرمستقیم رخ می‌دهند، از پاسخ‌های بی‌صدا استفاده می‌کند تا گروه‌ها/کانال‌ها -متن آماده خطای Gateway را نبینند. گفتگوهای مستقیم به‌طور پیش‌فرض متن فشرده خرابی را نشان می‌دهند؛ -جزئیات خام اجراکننده فقط زمانی نشان داده می‌شوند که `/verbose` روی `on` یا `full` باشد. +OpenClaw همچنین برای خرابی‌های داخلی اجراکننده که پیش از هر پاسخ دستیار در گفتگوهای غیرمستقیم رخ می‌دهند از پاسخ‌های خاموش استفاده می‌کند، تا گروه‌ها/کانال‌ها متن کلیشه‌ای خطای Gateway را نبینند. گفتگوهای مستقیم به‌طور پیش‌فرض متن کوتاه خرابی را نشان می‌دهند؛ جزئیات خام اجراکننده فقط وقتی `/verbose` روی `on` یا `full` باشد نشان داده می‌شود. -پیش‌فرض‌ها زیر `agents.defaults.silentReply` و -`agents.defaults.silentReplyRewrite` قرار دارند؛ `surfaces..silentReply` و -`surfaces..silentReplyRewrite` می‌توانند آن‌ها را به ازای هر سطح بازنویسی کنند. +پیش‌فرض‌ها زیر `agents.defaults.silentReply` و `agents.defaults.silentReplyRewrite` قرار دارند؛ `surfaces..silentReply` و `surfaces..silentReplyRewrite` می‌توانند آن‌ها را برای هر سطح بازنویسی کنند. -وقتی نشست والد یک یا چند اجرای زیعامل ایجادشده در انتظار داشته باشد، پاسخ‌های -بی‌صدای تنها به‌جای بازنویسی، در همه سطح‌ها حذف می‌شوند تا -والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت بماند. +وقتی نشست والد یک یا چند اجرای زیرعامل ایجادشده معلق داشته باشد، پاسخ‌های خاموش تنها به‌جای بازنویسی، روی همه سطح‌ها کنار گذاشته می‌شوند، تا والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت بماند. ## مرتبط -- [استریم](/fa/concepts/streaming) — تحویل پیام بلادرنگ +- [جریان‌سازی](/fa/concepts/streaming) — تحویل بی‌درنگ پیام - [تلاش دوباره](/fa/concepts/retry) — رفتار تلاش دوباره برای تحویل پیام - [صف](/fa/concepts/queue) — صف پردازش پیام - [کانال‌ها](/fa/channels) — یکپارچه‌سازی‌های پلتفرم پیام‌رسانی diff --git a/docs/fa/gateway/config-agents.md b/docs/fa/gateway/config-agents.md index 0edcc1118..d8a4a90bd 100644 --- a/docs/fa/gateway/config-agents.md +++ b/docs/fa/gateway/config-agents.md @@ -1,21 +1,21 @@ --- read_when: - تنظیم پیش‌فرض‌های عامل (مدل‌ها، تفکر، فضای کاری، Heartbeat، رسانه، Skills) - - پیکربندی مسیریابی و پیوندهای چندعاملی - - تنظیم رفتار جلسه، تحویل پیام و حالت گفت‌وگو -summary: پیش‌فرض‌های عامل، مسیریابی چندعاملی، نشست، پیام‌ها و پیکربندی گفت‌وگو + - پیکربندی مسیریابی و اتصال‌های چندعاملی + - تنظیم رفتار نشست، تحویل پیام و حالت گفت‌وگو +summary: پیش‌فرض‌های عامل، مسیریابی چندعاملی، نشست، پیام‌ها، و پیکربندی گفتگو title: پیکربندی — عامل‌ها x-i18n: - generated_at: "2026-04-30T09:37:35Z" + generated_at: "2026-04-30T16:28:03Z" model: gpt-5.5 provider: openai - source_hash: 61f2d33ae1d3f4ce07636ae4584b9e344fd14e8e08a2612bb1f39ed71c99c25a + source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084 source_path: gateway/config-agents.md workflow: 16 --- -کلیدهای پیکربندی در محدودهٔ عامل زیر `agents.*`، `multiAgent.*`، `session.*`، -`messages.*`، و `talk.*`. برای کانال‌ها، ابزارها، زمان اجرای Gateway و دیگر +کلیدهای پیکربندی با دامنه عامل زیر `agents.*`، `multiAgent.*`، `session.*`، +`messages.*` و `talk.*`. برای کانال‌ها، ابزارها، زمان اجرای Gateway و دیگر کلیدهای سطح بالا، [مرجع پیکربندی](/fa/gateway/configuration-reference) را ببینید. ## پیش‌فرض‌های عامل @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -ریشهٔ مخزن اختیاری که در خط Runtime در اعلان سیستم نشان داده می‌شود. اگر تنظیم نشود، OpenClaw با حرکت رو به بالا از workspace آن را به‌صورت خودکار تشخیص می‌دهد. +ریشه مخزن اختیاری که در خط Runtime پرامپت سیستم نمایش داده می‌شود. اگر تنظیم نشده باشد، OpenClaw با پیمایش رو به بالا از فضای کاری آن را خودکار تشخیص می‌دهد. ```json5 { @@ -42,7 +42,7 @@ x-i18n: ### `agents.defaults.skills` -فهرست مجاز پیش‌فرض و اختیاری Skills برای عامل‌هایی که +فهرست مجاز پیش‌فرض اختیاری Skills برای عامل‌هایی که `agents.list[].skills` را تنظیم نمی‌کنند. ```json5 @@ -58,15 +58,15 @@ x-i18n: } ``` -- برای داشتن Skills نامحدود به‌صورت پیش‌فرض، `agents.defaults.skills` را حذف کنید. -- برای ارث‌بری پیش‌فرض‌ها، `agents.list[].skills` را حذف کنید. -- برای نداشتن Skills، مقدار `agents.list[].skills: []` را تنظیم کنید. -- فهرست غیرخالی `agents.list[].skills` مجموعهٔ نهایی برای آن عامل است؛ با پیش‌فرض‌ها - ادغام نمی‌شود. +- برای Skills نامحدود به‌صورت پیش‌فرض، `agents.defaults.skills` را حذف کنید. +- برای به ارث بردن پیش‌فرض‌ها، `agents.list[].skills` را حذف کنید. +- برای نداشتن Skills، `agents.list[].skills: []` را تنظیم کنید. +- یک فهرست غیرخالی `agents.list[].skills` مجموعه نهایی برای آن عامل است؛ با + پیش‌فرض‌ها ادغام نمی‌شود. ### `agents.defaults.skipBootstrap` -ایجاد خودکار فایل‌های راه‌انداز workspace را غیرفعال می‌کند (`AGENTS.md`، `SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، `BOOTSTRAP.md`). +ساخت خودکار فایل‌های بوت‌استرپ فضای کاری (`AGENTS.md`، `SOUL.md`، `TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، `BOOTSTRAP.md`) را غیرفعال می‌کند. ```json5 { @@ -76,10 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -کنترل می‌کند چه زمانی فایل‌های راه‌انداز workspace در اعلان سیستم تزریق شوند. پیش‌فرض: `"always"`. +کنترل می‌کند فایل‌های بوت‌استرپ فضای کاری چه زمانی در پرامپت سیستم تزریق شوند. پیش‌فرض: `"always"`. -- `"continuation-skip"`: نوبت‌های ادامهٔ امن (پس از پاسخ کامل دستیار) تزریق دوبارهٔ راه‌انداز workspace را نادیده می‌گیرند و اندازهٔ اعلان را کاهش می‌دهند. اجرای Heartbeat و تلاش‌های مجدد پس از Compaction همچنان زمینه را بازسازی می‌کنند. -- `"never"`: راه‌انداز workspace و تزریق فایل زمینه را در هر نوبت غیرفعال می‌کند. فقط برای عامل‌هایی از این گزینه استفاده کنید که چرخهٔ عمر اعلان خود را کاملاً مالکیت می‌کنند (موتورهای زمینهٔ سفارشی، زمان‌های اجرای بومی که زمینهٔ خود را می‌سازند، یا گردش‌کارهای تخصصی بدون راه‌انداز). نوبت‌های Heartbeat و بازیابی از Compaction نیز تزریق را نادیده می‌گیرند. +- `"continuation-skip"`: نوبت‌های ادامه امن (پس از پاسخ تکمیل‌شده دستیار) تزریق دوباره بوت‌استرپ فضای کاری را رد می‌کنند و اندازه پرامپت را کاهش می‌دهند. اجراهای Heartbeat و تلاش‌های مجدد پس از Compaction همچنان زمینه را بازسازی می‌کنند. +- `"never"`: بوت‌استرپ فضای کاری و تزریق فایل زمینه را در هر نوبت غیرفعال می‌کند. این را فقط برای عامل‌هایی استفاده کنید که چرخه عمر پرامپت خود را کاملاً مالک هستند (موتورهای زمینه سفارشی، زمان‌های اجرای بومی که زمینه خودشان را می‌سازند، یا گردش‌کارهای تخصصی بدون بوت‌استرپ). نوبت‌های Heartbeat و بازیابی Compaction نیز تزریق را رد می‌کنند. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -حداکثر تعداد نویسه برای هر فایل راه‌انداز workspace پیش از کوتاه‌سازی. پیش‌فرض: `12000`. +حداکثر نویسه برای هر فایل بوت‌استرپ فضای کاری پیش از کوتاه‌سازی. پیش‌فرض: `12000`. ```json5 { @@ -99,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -حداکثر مجموع نویسه‌های تزریق‌شده در همهٔ فایل‌های راه‌انداز workspace. پیش‌فرض: `60000`. +حداکثر مجموع نویسه‌های تزریق‌شده در همه فایل‌های بوت‌استرپ فضای کاری. پیش‌فرض: `60000`. ```json5 { @@ -109,12 +109,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -متن هشدار قابل‌مشاهده برای عامل را هنگام کوتاه‌شدن زمینهٔ راه‌انداز کنترل می‌کند. +متن هشدار قابل مشاهده برای عامل را هنگام کوتاه شدن زمینه بوت‌استرپ کنترل می‌کند. پیش‌فرض: `"once"`. -- `"off"`: هرگز متن هشدار را در اعلان سیستم تزریق نکن. +- `"off"`: هرگز متن هشدار را در پرامپت سیستم تزریق نکن. - `"once"`: برای هر امضای کوتاه‌سازی یکتا، هشدار را یک‌بار تزریق کن (توصیه‌شده). -- `"always"`: وقتی کوتاه‌سازی وجود دارد، در هر اجرا هشدار را تزریق کن. +- `"always"`: هر بار که کوتاه‌سازی وجود دارد، هشدار را در هر اجرا تزریق کن. ```json5 { @@ -122,36 +122,36 @@ x-i18n: } ``` -### نقشهٔ مالکیت بودجهٔ زمینه +### نقشه مالکیت بودجه زمینه -OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و این بودجه‌ها عمداً -بر اساس زیرسامانه جدا شده‌اند، نه اینکه همگی از یک تنظیم عمومی -عبور کنند. +OpenClaw چندین بودجه پرحجم پرامپت/زمینه دارد و آن‌ها به‌عمد بر اساس زیرسامانه +جدا شده‌اند، نه اینکه همگی از یک تنظیم عمومی عبور کنند. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - تزریق عادی راه‌انداز workspace. + تزریق عادی بوت‌استرپ فضای کاری. - `agents.defaults.startupContext.*`: - پیش‌درآمد یک‌بارهٔ اجرای مدل در بازنشانی/راه‌اندازی، شامل فایل‌های اخیر روزانهٔ - `memory/*.md`. فرمان‌های گفت‌وگوی خام `/new` و `/reset` - بدون فراخوانی مدل تأیید می‌شوند. + پیش‌درآمد یک‌باره اجرای مدل هنگام بازنشانی/شروع، شامل فایل‌های روزانه اخیر + `memory/*.md`. فرمان‌های گفت‌وگوی ساده `/new` و `/reset` بدون فراخوانی مدل + تأیید می‌شوند. - `skills.limits.*`: - فهرست فشردهٔ Skills که در اعلان سیستم تزریق می‌شود. + فهرست فشرده Skills که در پرامپت سیستم تزریق می‌شود. - `agents.defaults.contextLimits.*`: - گزیده‌های محدود زمان اجرا و بلوک‌های تزریق‌شدهٔ متعلق به زمان اجرا. + بریده‌های محدود زمان اجرا و بلوک‌های تزریق‌شده تحت مالکیت زمان اجرا. - `memory.qmd.limits.*`: - اندازه‌بندی قطعهٔ جست‌وجوی حافظهٔ نمایه‌شده و تزریق. + قطعه جست‌وجوی حافظه نمایه‌شده و اندازه‌گذاری تزریق. -فقط وقتی یک عامل به بودجه‌ای متفاوت نیاز دارد، از بازنویسی متناظر مخصوص عامل استفاده کنید: +فقط وقتی یک عامل به بودجه متفاوتی نیاز دارد، از بازنویسی متناظر برای هر عامل +استفاده کنید: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -پیش‌درآمد راه‌اندازی نوبت اول را که در اجرای مدل هنگام بازنشانی/راه‌اندازی تزریق می‌شود کنترل می‌کند. -فرمان‌های گفت‌وگوی خام `/new` و `/reset` بازنشانی را بدون فراخوانی -مدل تأیید می‌کنند، بنابراین این پیش‌درآمد را بارگذاری نمی‌کنند. +پیش‌درآمد شروع نوبت اول را که در اجراهای مدل هنگام بازنشانی/شروع تزریق می‌شود کنترل می‌کند. +فرمان‌های گفت‌وگوی ساده `/new` و `/reset` بازنشانی را بدون فراخوانی مدل تأیید +می‌کنند، بنابراین این پیش‌درآمد را بارگذاری نمی‌کنند. ```json5 { @@ -172,7 +172,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و #### `agents.defaults.contextLimits` -پیش‌فرض‌های مشترک برای سطح‌های محدود زمینهٔ زمان اجرا. +پیش‌فرض‌های مشترک برای سطوح محدود زمینه زمان اجرا. ```json5 { @@ -189,19 +189,19 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- `memoryGetMaxChars`: سقف پیش‌فرض گزیدهٔ `memory_get` پیش از افزودن - فرادادهٔ کوتاه‌سازی و اعلان ادامه. -- `memoryGetDefaultLines`: پنجرهٔ خط پیش‌فرض `memory_get` وقتی `lines` - حذف شده باشد. -- `toolResultMaxChars`: سقف نتیجهٔ ابزار زنده که برای نتایج پایدارشده و +- `memoryGetMaxChars`: سقف پیش‌فرض بریده `memory_get` پیش از افزودن + فراداده کوتاه‌سازی و اعلان ادامه. +- `memoryGetDefaultLines`: پنجره خط پیش‌فرض `memory_get` وقتی `lines` حذف + شده باشد. +- `toolResultMaxChars`: سقف نتیجه ابزار زنده که برای نتایج ماندگارشده و بازیابی سرریز استفاده می‌شود. -- `postCompactionMaxChars`: سقف گزیدهٔ AGENTS.md که هنگام تزریق بازآوری +- `postCompactionMaxChars`: سقف بریده AGENTS.md که هنگام تزریق تازه‌سازی پس از Compaction استفاده می‌شود. #### `agents.list[].contextLimits` -بازنویسی مخصوص عامل برای تنظیم‌های مشترک `contextLimits`. فیلدهای حذف‌شده از -`agents.defaults.contextLimits` ارث‌بری می‌کنند. +بازنویسی برای هر عامل برای تنظیم‌های مشترک `contextLimits`. فیلدهای حذف‌شده از +`agents.defaults.contextLimits` به ارث برده می‌شوند. ```json5 { @@ -227,8 +227,8 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و #### `skills.limits.maxSkillsPromptChars` -سقف سراسری برای فهرست فشردهٔ Skills که در اعلان سیستم تزریق می‌شود. این -خواندن فایل‌های `SKILL.md` را در زمان نیاز تحت تأثیر قرار نمی‌دهد. +سقف سراسری برای فهرست فشرده Skills که در پرامپت سیستم تزریق می‌شود. این +روی خواندن فایل‌های `SKILL.md` در صورت نیاز اثری ندارد. ```json5 { @@ -242,7 +242,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و #### `agents.list[].skillsLimits.maxSkillsPromptChars` -بازنویسی مخصوص عامل برای بودجهٔ اعلان Skills. +بازنویسی برای هر عامل برای بودجه پرامپت Skills. ```json5 { @@ -261,10 +261,10 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و ### `agents.defaults.imageMaxDimensionPx` -حداکثر اندازهٔ پیکسلی بلندترین ضلع تصویر در بلوک‌های تصویر transcript/ابزار پیش از فراخوانی‌های ارائه‌دهنده. +حداکثر اندازه پیکسلی برای بلندترین ضلع تصویر در بلوک‌های تصویر رونوشت/ابزار پیش از فراخوانی‌های ارائه‌دهنده. پیش‌فرض: `1200`. -مقادیر کمتر معمولاً مصرف توکن‌های بینایی و اندازهٔ payload درخواست را برای اجراهای دارای screenshot زیاد کاهش می‌دهند. +مقادیر پایین‌تر معمولاً مصرف توکن‌های بینایی و اندازه بار درخواست را برای اجراهای سنگینِ اسکرین‌شات کاهش می‌دهند. مقادیر بالاتر جزئیات بصری بیشتری را حفظ می‌کنند. ```json5 @@ -275,7 +275,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و ### `agents.defaults.userTimezone` -منطقهٔ زمانی برای زمینهٔ اعلان سیستم (نه timestampهای پیام). به منطقهٔ زمانی میزبان برمی‌گردد. +منطقه زمانی برای زمینه پرامپت سیستم (نه مهرزمان‌های پیام). در صورت نبود، به منطقه زمانی میزبان برمی‌گردد. ```json5 { @@ -285,7 +285,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و ### `agents.defaults.timeFormat` -قالب زمان در اعلان سیستم. پیش‌فرض: `auto` (ترجیح سیستم‌عامل). +قالب زمان در پرامپت سیستم. پیش‌فرض: `auto` (ترجیح سیستم‌عامل). ```json5 { @@ -343,59 +343,59 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- `model`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. - - شکل رشته‌ای فقط مدل اصلی را تنظیم می‌کند. - - شکل شیء، مدل اصلی را همراه با مدل‌های failover مرتب‌شده تنظیم می‌کند. -- `imageModel`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. +- `model`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). + - فرم رشته فقط مدل اصلی را تنظیم می‌کند. + - فرم شیء، مدل اصلی به‌علاوه مدل‌های failover مرتب‌شده را تنظیم می‌کند. +- `imageModel`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). - توسط مسیر ابزار `image` به‌عنوان پیکربندی مدل بینایی آن استفاده می‌شود. - همچنین وقتی مدل انتخاب‌شده/پیش‌فرض نمی‌تواند ورودی تصویر را بپذیرد، برای مسیریابی fallback استفاده می‌شود. - - ارجاع‌های صریح `provider/model` را ترجیح دهید. شناسه‌های bare برای سازگاری پذیرفته می‌شوند؛ اگر یک شناسه bare به‌طور یکتا با یک ورودی پیکربندی‌شده دارای قابلیت تصویر در `models.providers.*.models` تطابق داشته باشد، OpenClaw آن را به همان provider نسبت می‌دهد. تطابق‌های پیکربندی‌شده مبهم به پیشوند صریح provider نیاز دارند. -- `imageGenerationModel`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. - - توسط قابلیت مشترک تولید تصویر و هر سطح ابزار/Plugin آینده‌ای که تصویر تولید کند استفاده می‌شود. - - مقادیر معمول: `google/gemini-3.1-flash-image-preview` برای تولید تصویر بومی Gemini، `fal/fal-ai/flux/dev` برای fal، `openai/gpt-image-2` برای OpenAI Images، یا `openai/gpt-image-1.5` برای خروجی PNG/WebP با پس‌زمینه شفاف OpenAI. + - ارجاع‌های صریح `provider/model` را ترجیح دهید. شناسه‌های تنها برای سازگاری پذیرفته می‌شوند؛ اگر یک شناسه تنها به‌طور یکتا با یک ورودی پیکربندی‌شده دارای قابلیت تصویر در `models.providers.*.models` مطابقت داشته باشد، OpenClaw آن را به آن provider منتسب می‌کند. مطابقت‌های پیکربندی‌شده مبهم به پیشوند صریح provider نیاز دارند. +- `imageGenerationModel`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). + - توسط قابلیت مشترک تولید تصویر و هر سطح ابزار/Plugin آینده‌ای که تصویر تولید می‌کند استفاده می‌شود. + - مقادیر معمول: `google/gemini-3.1-flash-image-preview` برای تولید تصویر بومی Gemini، `fal/fal-ai/flux/dev` برای fal، `openai/gpt-image-2` برای OpenAI Images، یا `openai/gpt-image-1.5` برای خروجی OpenAI PNG/WebP با پس‌زمینه شفاف. - اگر مستقیما یک provider/model را انتخاب می‌کنید، احراز هویت provider متناظر را نیز پیکربندی کنید (برای مثال `GEMINI_API_KEY` یا `GOOGLE_API_KEY` برای `google/*`، `OPENAI_API_KEY` یا OpenAI Codex OAuth برای `openai/gpt-image-2` / `openai/gpt-image-1.5`، و `FAL_KEY` برای `fal/*`). - - اگر حذف شود، `image_generate` همچنان می‌تواند یک provider پیش‌فرض دارای پشتوانه احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید تصویر را به ترتیب شناسه provider امتحان می‌کند. -- `musicGenerationModel`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. + - اگر حذف شود، `image_generate` همچنان می‌تواند یک پیش‌فرض provider پشتیبانی‌شده با احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید تصویر را به ترتیب شناسه provider امتحان می‌کند. +- `musicGenerationModel`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). - توسط قابلیت مشترک تولید موسیقی و ابزار داخلی `music_generate` استفاده می‌شود. - مقادیر معمول: `google/lyria-3-clip-preview`، `google/lyria-3-pro-preview`، یا `minimax/music-2.6`. - - اگر حذف شود، `music_generate` همچنان می‌تواند یک provider پیش‌فرض دارای پشتوانه احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید موسیقی را به ترتیب شناسه provider امتحان می‌کند. + - اگر حذف شود، `music_generate` همچنان می‌تواند یک پیش‌فرض provider پشتیبانی‌شده با احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید موسیقی را به ترتیب شناسه provider امتحان می‌کند. - اگر مستقیما یک provider/model را انتخاب می‌کنید، احراز هویت/کلید API provider متناظر را نیز پیکربندی کنید. -- `videoGenerationModel`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. - - توسط قابلیت مشترک تولید ویدیو و ابزار داخلی `video_generate` استفاده می‌شود. +- `videoGenerationModel`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). + - توسط قابلیت مشترک تولید ویدئو و ابزار داخلی `video_generate` استفاده می‌شود. - مقادیر معمول: `qwen/wan2.6-t2v`، `qwen/wan2.6-i2v`، `qwen/wan2.6-r2v`، `qwen/wan2.6-r2v-flash`، یا `qwen/wan2.7-r2v`. - - اگر حذف شود، `video_generate` همچنان می‌تواند یک provider پیش‌فرض دارای پشتوانه احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید ویدیو را به ترتیب شناسه provider امتحان می‌کند. + - اگر حذف شود، `video_generate` همچنان می‌تواند یک پیش‌فرض provider پشتیبانی‌شده با احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده تولید ویدئو را به ترتیب شناسه provider امتحان می‌کند. - اگر مستقیما یک provider/model را انتخاب می‌کنید، احراز هویت/کلید API provider متناظر را نیز پیکربندی کنید. - - provider تولید ویدیوی Qwen همراه، حداکثر ۱ ویدیوی خروجی، ۱ تصویر ورودی، ۴ ویدیوی ورودی، مدت ۱۰ ثانیه، و گزینه‌های سطح provider یعنی `size`، `aspectRatio`، `resolution`، `audio` و `watermark` را پشتیبانی می‌کند. -- `pdfModel`: یا یک رشته (`"provider/model"`) یا یک شیء (`{ primary, fallbacks }`) را می‌پذیرد. + - provider تولید ویدئوی Qwen همراه، تا ۱ ویدئوی خروجی، ۱ تصویر ورودی، ۴ ویدئوی ورودی، مدت ۱۰ ثانیه، و گزینه‌های سطح provider یعنی `size`، `aspectRatio`، `resolution`، `audio` و `watermark` را پشتیبانی می‌کند. +- `pdfModel`: یا یک رشته (`"provider/model"`) را می‌پذیرد یا یک شیء (`{ primary, fallbacks }`). - توسط ابزار `pdf` برای مسیریابی مدل استفاده می‌شود. - - اگر حذف شود، ابزار PDF به `imageModel` و سپس به مدل resolveشده نشست/پیش‌فرض fallback می‌کند. -- `pdfMaxBytesMb`: محدودیت پیش‌فرض اندازه PDF برای ابزار `pdf` وقتی `maxBytesMb` هنگام فراخوانی ارسال نشده باشد. + - اگر حذف شود، ابزار PDF ابتدا به `imageModel` و سپس به مدل حل‌شده نشست/پیش‌فرض fallback می‌کند. +- `pdfMaxBytesMb`: محدودیت اندازه پیش‌فرض PDF برای ابزار `pdf` وقتی `maxBytesMb` در زمان فراخوانی پاس داده نشده باشد. - `pdfMaxPages`: حداکثر صفحات پیش‌فرضی که در حالت fallback استخراج در ابزار `pdf` در نظر گرفته می‌شوند. -- `verboseDefault`: سطح verbose پیش‌فرض برای عامل‌ها. مقادیر: `"off"`، `"on"`، `"full"`. پیش‌فرض: `"off"`. -- `reasoningDefault`: نمایانی reasoning پیش‌فرض برای عامل‌ها. مقادیر: `"off"`، `"on"`، `"stream"`. `agents.list[].reasoningDefault` برای هر عامل این پیش‌فرض را override می‌کند. پیش‌فرض‌های reasoning پیکربندی‌شده فقط برای مالکان، فرستندگان مجاز، یا زمینه‌های Gateway مدیر-اپراتور اعمال می‌شوند، آن هم وقتی هیچ override برای reasoning در سطح پیام یا نشست تنظیم نشده باشد. -- `elevatedDefault`: سطح پیش‌فرض خروجی elevated برای عامل‌ها. مقادیر: `"off"`، `"on"`، `"ask"`، `"full"`. پیش‌فرض: `"on"`. -- `model.primary`: قالب `provider/model` (مثلا `openai/gpt-5.5` برای دسترسی با کلید API یا `openai-codex/gpt-5.5` برای Codex OAuth). اگر provider را حذف کنید، OpenClaw ابتدا یک alias را امتحان می‌کند، سپس یک تطابق provider پیکربندی‌شده یکتا برای همان شناسه مدل دقیق، و فقط بعد از آن به provider پیش‌فرض پیکربندی‌شده fallback می‌کند (رفتار سازگاری منسوخ‌شده، بنابراین `provider/model` صریح را ترجیح دهید). اگر آن provider دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نشان دادن پیش‌فرض stale برای provider حذف‌شده، به نخستین provider/model پیکربندی‌شده fallback می‌کند. -- `models`: کاتالوگ مدل پیکربندی‌شده و allowlist برای `/model`. هر ورودی می‌تواند شامل `alias` (میانبر) و `params` (ویژه provider، برای مثال `temperature`، `maxTokens`، `cacheRetention`، `context1m`، `responsesServerCompaction`، `responsesCompactThreshold`، `chat_template_kwargs`، `extra_body`/`extraBody`) باشد. - - ویرایش‌های امن: برای افزودن ورودی‌ها از `openclaw config set agents.defaults.models '' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌هایی را که باعث حذف ورودی‌های allowlist موجود شوند رد می‌کند، مگر اینکه `--replace` را ارسال کنید. - - جریان‌های پیکربندی/onboarding محدود به provider، مدل‌های provider انتخاب‌شده را در این map ادغام می‌کنند و providerهای نامرتبطی را که از قبل پیکربندی شده‌اند حفظ می‌کنند. - - برای مدل‌های مستقیم OpenAI Responses، Compaction سمت سرور به‌طور خودکار فعال می‌شود. برای توقف تزریق `context_management` از `params.responsesServerCompaction: false` استفاده کنید، یا برای override کردن آستانه از `params.responsesCompactThreshold` استفاده کنید. [Compaction سمت سرور OpenAI](/fa/providers/openai#server-side-compaction-responses-api) را ببینید. -- `params`: پارامترهای پیش‌فرض سراسری provider که روی همه مدل‌ها اعمال می‌شوند. در `agents.defaults.params` تنظیم می‌شود (مثلا `{ cacheRetention: "long" }`). -- تقدم ادغام `params` (پیکربندی): `agents.defaults.params` (پایه سراسری) توسط `agents.defaults.models["provider/model"].params` (برای هر مدل) override می‌شود، سپس `agents.list[].params` (شناسه عامل متناظر) بر اساس کلید override می‌کند. برای جزئیات [Prompt Caching](/fa/reference/prompt-caching) را ببینید. -- `params.extra_body`/`params.extraBody`: JSON پیشرفته pass-through که در بدنه درخواست‌های `api: "openai-completions"` برای پراکسی‌های سازگار با OpenAI ادغام می‌شود. اگر با کلیدهای درخواست تولیدشده تداخل داشته باشد، بدنه اضافی برنده است؛ مسیرهای completions غیر بومی همچنان بعدا `store` مختص OpenAI را حذف می‌کنند. -- `params.chat_template_kwargs`: آرگومان‌های chat-template سازگار با vLLM/OpenAI که در بدنه درخواست‌های سطح بالای `api: "openai-completions"` ادغام می‌شوند. برای `vllm/nemotron-3-*` با thinking خاموش، Plugin همراه vLLM به‌طور خودکار `enable_thinking: false` و `force_nonempty_content: true` را ارسال می‌کند؛ `chat_template_kwargs` صریح، پیش‌فرض‌های تولیدشده را override می‌کند، و `extra_body.chat_template_kwargs` همچنان تقدم نهایی دارد. برای کنترل‌های thinking در vLLM Qwen، در ورودی همان مدل `params.qwenThinkingFormat` را به `"chat-template"` یا `"top-level"` تنظیم کنید. -- `compat.supportedReasoningEfforts`: فهرست effortهای reasoning سازگار با OpenAI برای هر مدل. برای endpointهای سفارشی که واقعا آن را می‌پذیرند، `"xhigh"` را اضافه کنید؛ سپس OpenClaw در منوهای فرمان، ردیف‌های نشست Gateway، اعتبارسنجی patch نشست، اعتبارسنجی CLI عامل، و اعتبارسنجی `llm-task` برای آن provider/model پیکربندی‌شده، `/think xhigh` را ارائه می‌کند. وقتی backend برای یک سطح canonical به مقدار ویژه provider نیاز دارد، از `compat.reasoningEffortMap` استفاده کنید. -- `params.preserveThinking`: opt-in فقط مخصوص Z.AI برای thinking حفظ‌شده. وقتی فعال باشد و thinking روشن باشد، OpenClaw `thinking.clear_thinking: false` را ارسال می‌کند و `reasoning_content` قبلی را بازپخش می‌کند؛ [thinking و thinking حفظ‌شده در Z.AI](/fa/providers/zai#thinking-and-preserved-thinking) را ببینید. -- `agentRuntime`: سیاست پیش‌فرض سطح پایین runtime عامل. شناسه حذف‌شده به‌طور پیش‌فرض OpenClaw Pi است. برای اجبار به harness داخلی PI از `id: "pi"` استفاده کنید، برای اینکه harnessهای Plugin ثبت‌شده مدل‌های پشتیبانی‌شده را claim کنند از `id: "auto"` استفاده کنید، از شناسه harness ثبت‌شده‌ای مانند `id: "codex"` استفاده کنید، یا از یک alias backend CLI پشتیبانی‌شده مانند `id: "claude-cli"` استفاده کنید. برای غیرفعال کردن fallback خودکار PI، `fallback: "none"` را تنظیم کنید. runtimeهای Plugin صریح مانند `codex` به‌طور پیش‌فرض fail closed می‌شوند، مگر اینکه در همان محدوده override، `fallback: "pi"` را تنظیم کنید. ارجاع‌های مدل را به‌صورت canonical یعنی `provider/model` نگه دارید؛ Codex، Claude CLI، Gemini CLI و backendهای اجرایی دیگر را به‌جای پیشوندهای legacy runtime provider از طریق پیکربندی runtime انتخاب کنید. برای اینکه بدانید این با انتخاب provider/model چه تفاوتی دارد، [runtimeهای عامل](/fa/concepts/agent-runtimes) را ببینید. -- نویسنده‌های پیکربندی که این فیلدها را تغییر می‌دهند (برای مثال `/models set`، `/models set-image` و فرمان‌های افزودن/حذف fallback) شکل شیء canonical را ذخیره می‌کنند و در صورت امکان فهرست‌های fallback موجود را حفظ می‌کنند. -- `maxConcurrent`: حداکثر اجرای موازی عامل‌ها در میان نشست‌ها (هر نشست همچنان serialized است). پیش‌فرض: 4. +- `verboseDefault`: سطح verbose پیش‌فرض برای agentها. مقادیر: `"off"`، `"on"`، `"full"`. پیش‌فرض: `"off"`. +- `reasoningDefault`: نمایانی reasoning پیش‌فرض برای agentها. مقادیر: `"off"`، `"on"`، `"stream"`. مقدار `agents.list[].reasoningDefault` مخصوص هر agent این پیش‌فرض را override می‌کند. پیش‌فرض‌های reasoning پیکربندی‌شده فقط برای مالکان، فرستندگان مجاز، یا زمینه‌های Gateway اپراتور-مدیر اعمال می‌شوند، آن هم وقتی override مربوط به reasoning در سطح پیام یا نشست تنظیم نشده باشد. +- `elevatedDefault`: سطح خروجی elevated پیش‌فرض برای agentها. مقادیر: `"off"`، `"on"`، `"ask"`، `"full"`. پیش‌فرض: `"on"`. +- `model.primary`: قالب `provider/model` (برای نمونه `openai/gpt-5.5` برای دسترسی با کلید API یا `openai-codex/gpt-5.5` برای Codex OAuth). اگر provider را حذف کنید، OpenClaw ابتدا یک alias را امتحان می‌کند، سپس یک مطابقت یکتای provider پیکربندی‌شده برای همان شناسه دقیق مدل، و فقط بعد از آن به provider پیش‌فرض پیکربندی‌شده fallback می‌کند (رفتار سازگاری منسوخ، پس `provider/model` صریح را ترجیح دهید). اگر آن provider دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش یک پیش‌فرض قدیمی مربوط به provider حذف‌شده، به نخستین provider/model پیکربندی‌شده fallback می‌کند. +- `models`: کاتالوگ مدل پیکربندی‌شده و allowlist برای `/model`. هر ورودی می‌تواند شامل `alias` (میان‌بر) و `params` (ویژه provider، برای مثال `temperature`، `maxTokens`، `cacheRetention`، `context1m`، `responsesServerCompaction`، `responsesCompactThreshold`، `chat_template_kwargs`، `extra_body`/`extraBody`) باشد. + - ویرایش‌های امن: برای افزودن ورودی‌ها از `openclaw config set agents.defaults.models '' --strict-json --merge` استفاده کنید. `config set` جایگزینی‌هایی را که ورودی‌های allowlist موجود را حذف می‌کنند رد می‌کند، مگر اینکه `--replace` را پاس دهید. + - جریان‌های configure/onboarding با دامنه provider، مدل‌های provider انتخاب‌شده را در این map ادغام می‌کنند و providerهای نامرتبطی را که از قبل پیکربندی شده‌اند حفظ می‌کنند. + - برای مدل‌های مستقیم OpenAI Responses، Compaction سمت سرور به‌طور خودکار فعال می‌شود. از `params.responsesServerCompaction: false` برای توقف تزریق `context_management`، یا از `params.responsesCompactThreshold` برای override آستانه استفاده کنید. [Compaction سمت سرور OpenAI](/fa/providers/openai#server-side-compaction-responses-api) را ببینید. +- `params`: پارامترهای provider پیش‌فرض سراسری که روی همه مدل‌ها اعمال می‌شوند. در `agents.defaults.params` تنظیم می‌شود (برای مثال `{ cacheRetention: "long" }`). +- اولویت ادغام `params` (پیکربندی): `agents.defaults.params` (پایه سراسری) توسط `agents.defaults.models["provider/model"].params` (مخصوص مدل) override می‌شود، سپس `agents.list[].params` (شناسه agent متناظر) بر اساس کلید override می‌کند. برای جزئیات [کش کردن prompt](/fa/reference/prompt-caching) را ببینید. +- `params.extra_body`/`params.extraBody`: JSON pass-through پیشرفته که در بدنه‌های درخواست `api: "openai-completions"` برای proxyهای سازگار با OpenAI ادغام می‌شود. اگر با کلیدهای درخواست تولیدشده برخورد کند، extra body برنده می‌شود؛ مسیرهای completions غیر بومی همچنان بعد از آن `store` مخصوص OpenAI را حذف می‌کنند. +- `params.chat_template_kwargs`: آرگومان‌های chat-template سازگار با vLLM/OpenAI که در بدنه‌های درخواست سطح بالای `api: "openai-completions"` ادغام می‌شوند. برای `vllm/nemotron-3-*` با thinking خاموش، Plugin همراه vLLM به‌طور خودکار `enable_thinking: false` و `force_nonempty_content: true` را ارسال می‌کند؛ `chat_template_kwargs` صریح، پیش‌فرض‌های تولیدشده را override می‌کند، و `extra_body.chat_template_kwargs` همچنان اولویت نهایی را دارد. برای کنترل‌های thinking مربوط به vLLM Qwen، روی آن ورودی مدل `params.qwenThinkingFormat` را به `"chat-template"` یا `"top-level"` تنظیم کنید. +- `compat.supportedReasoningEfforts`: فهرست effortهای reasoning سازگار با OpenAI برای هر مدل. برای endpointهای سفارشی که واقعا آن را می‌پذیرند، `"xhigh"` را اضافه کنید؛ سپس OpenClaw گزینه `/think xhigh` را در منوهای فرمان، ردیف‌های نشست Gateway، اعتبارسنجی patch نشست، اعتبارسنجی CLI agent، و اعتبارسنجی `llm-task` برای آن provider/model پیکربندی‌شده نمایش می‌دهد. وقتی backend برای یک سطح canonical مقدار ویژه provider می‌خواهد، از `compat.reasoningEffortMap` استفاده کنید. +- `params.preserveThinking`: opt-in مخصوص Z.AI برای thinking حفظ‌شده. وقتی فعال باشد و thinking روشن باشد، OpenClaw مقدار `thinking.clear_thinking: false` را ارسال می‌کند و `reasoning_content` قبلی را دوباره پخش می‌کند؛ [thinking و thinking حفظ‌شده در Z.AI](/fa/providers/zai#thinking-and-preserved-thinking) را ببینید. +- `agentRuntime`: سیاست پیش‌فرض runtime سطح پایین agent. شناسه حذف‌شده به‌طور پیش‌فرض OpenClaw Pi است. از `id: "pi"` برای اجبار harness داخلی PI، از `id: "auto"` برای اینکه harnessهای Plugin ثبت‌شده مدل‌های پشتیبانی‌شده را claim کنند، از شناسه harness ثبت‌شده‌ای مثل `id: "codex"`، یا از alias یک backend CLI پشتیبانی‌شده مثل `id: "claude-cli"` استفاده کنید. برای غیرفعال کردن fallback خودکار PI مقدار `fallback: "none"` را تنظیم کنید. runtimeهای Plugin صریح مثل `codex` به‌طور پیش‌فرض fail closed می‌شوند مگر اینکه در همان دامنه override مقدار `fallback: "pi"` را تنظیم کنید. ارجاع‌های مدل را به شکل canonical یعنی `provider/model` نگه دارید؛ Codex، Claude CLI، Gemini CLI و backendهای اجرایی دیگر را از طریق پیکربندی runtime انتخاب کنید، نه از طریق پیشوندهای provider runtime قدیمی. برای اینکه بدانید این موضوع چه تفاوتی با انتخاب provider/model دارد، [runtimeهای agent](/fa/concepts/agent-runtimes) را ببینید. +- نویسنده‌های پیکربندی که این فیلدها را تغییر می‌دهند (برای مثال `/models set`، `/models set-image` و فرمان‌های افزودن/حذف fallback) فرم شیء canonical را ذخیره می‌کنند و در صورت امکان فهرست‌های fallback موجود را حفظ می‌کنند. +- `maxConcurrent`: حداکثر اجرای موازی agent در میان نشست‌ها (هر نشست همچنان سریالی می‌ماند). پیش‌فرض: ۴. ### `agents.defaults.agentRuntime` -`agentRuntime` کنترل می‌کند کدام executor سطح پایین نوبت‌های عامل را اجرا کند. بیشتر -استقرارها باید runtime پیش‌فرض OpenClaw Pi را نگه دارند. وقتی یک Plugin معتمد -یک harness بومی ارائه می‌کند، مانند harness همراه app-server مربوط به Codex، -یا وقتی یک backend CLI پشتیبانی‌شده مانند Claude CLI می‌خواهید، از آن استفاده کنید. برای مدل ذهنی، -[runtimeهای عامل](/fa/concepts/agent-runtimes) را ببینید. +`agentRuntime` کنترل می‌کند کدام executor سطح پایین نوبت‌های agent را اجرا کند. بیشتر +استقرارها باید runtime پیش‌فرض OpenClaw Pi را نگه دارند. وقتی یک Plugin مورد اعتماد +یک harness بومی فراهم می‌کند، مانند harness همراه app-server متعلق به Codex، +یا وقتی یک backend CLI پشتیبانی‌شده مثل Claude CLI می‌خواهید، از آن استفاده کنید. برای مدل ذهنی، +[runtimeهای agent](/fa/concepts/agent-runtimes) را ببینید. ```json5 { @@ -411,18 +411,18 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- `id`: `"auto"`، `"pi"`، شناسه harness یک Plugin ثبت‌شده، یا alias یک backend CLI پشتیبانی‌شده. Plugin همراه Codex، `codex` را ثبت می‌کند؛ Plugin همراه Anthropic، backend CLI با نام `claude-cli` را فراهم می‌کند. -- `fallback`: `"pi"` یا `"none"`. در `id: "auto"`، fallback حذف‌شده به‌طور پیش‌فرض `"pi"` است تا پیکربندی‌های قدیمی وقتی هیچ harness متعلق به Plugin یک اجرا را claim نمی‌کند بتوانند همچنان از PI استفاده کنند. در حالت runtime صریح Plugin، مانند `id: "codex"`، fallback حذف‌شده به‌طور پیش‌فرض `"none"` است تا harness گمشده به‌جای استفاده بی‌صدای PI، شکست بخورد. overrideهای runtime، fallback را از محدوده گسترده‌تر به ارث نمی‌برند؛ وقتی عمدا آن fallback سازگاری را می‌خواهید، `fallback: "pi"` را کنار runtime صریح تنظیم کنید. شکست‌های harness انتخاب‌شده Plugin همیشه مستقیما نمایش داده می‌شوند. -- overrideهای محیطی: `OPENCLAW_AGENT_RUNTIME=` مقدار `id` را override می‌کند؛ `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` مقدار fallback را برای همان فرایند override می‌کند. -- برای استقرارهای فقط Codex، `model: "openai/gpt-5.5"` و `agentRuntime.id: "codex"` را تنظیم کنید. همچنین می‌توانید برای خوانایی، `agentRuntime.fallback: "none"` را صریحا تنظیم کنید؛ این مقدار برای runtimeهای صریح Plugin پیش‌فرض است. -- برای استقرارهای Claude CLI، `model: "anthropic/claude-opus-4-7"` را همراه با `agentRuntime.id: "claude-cli"` ترجیح دهید. ارجاع‌های مدل legacy مانند `claude-cli/claude-opus-4-7` همچنان برای سازگاری کار می‌کنند، اما پیکربندی جدید باید انتخاب provider/model را canonical نگه دارد و backend اجرایی را در `agentRuntime.id` قرار دهد. +- `id`: `"auto"`، `"pi"`، شناسه harness یک Plugin ثبت‌شده، یا alias یک backend CLI پشتیبانی‌شده. Plugin همراه Codex مقدار `codex` را ثبت می‌کند؛ Plugin همراه Anthropic، backend CLI یعنی `claude-cli` را فراهم می‌کند. +- `fallback`: `"pi"` یا `"none"`. در `id: "auto"`، fallback حذف‌شده به‌طور پیش‌فرض `"pi"` است تا پیکربندی‌های قدیمی وقتی هیچ harness مربوط به Plugin یک اجرا را claim نمی‌کند بتوانند همچنان از PI استفاده کنند. در حالت runtime صریح Plugin، مانند `id: "codex"`، fallback حذف‌شده به‌طور پیش‌فرض `"none"` است تا harness گم‌شده به‌جای استفاده بی‌صدای PI شکست بخورد. overrideهای runtime مقدار fallback را از دامنه گسترده‌تر به ارث نمی‌برند؛ وقتی عمدا آن fallback سازگاری را می‌خواهید، همراه runtime صریح `fallback: "pi"` را تنظیم کنید. خرابی‌های harness انتخاب‌شده Plugin همیشه مستقیما نمایش داده می‌شوند. +- overrideهای محیطی: `OPENCLAW_AGENT_RUNTIME=` مقدار `id` را override می‌کند؛ `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` مقدار fallback را برای آن فرایند override می‌کند. +- برای استقرارهای فقط Codex، مقدار `model: "openai/gpt-5.5"` و `agentRuntime.id: "codex"` را تنظیم کنید. همچنین می‌توانید برای خوانایی، `agentRuntime.fallback: "none"` را صریح تنظیم کنید؛ این مقدار پیش‌فرض runtimeهای Plugin صریح است. +- برای استقرارهای Claude CLI، `model: "anthropic/claude-opus-4-7"` به‌علاوه `agentRuntime.id: "claude-cli"` را ترجیح دهید. ارجاع‌های مدل قدیمی `claude-cli/claude-opus-4-7` همچنان برای سازگاری کار می‌کنند، اما پیکربندی جدید باید انتخاب provider/model را canonical نگه دارد و backend اجرایی را در `agentRuntime.id` قرار دهد. - کلیدهای قدیمی‌تر سیاست runtime توسط `openclaw doctor --fix` به `agentRuntime` بازنویسی می‌شوند. -- انتخاب harness پس از نخستین اجرای embedded برای هر شناسه نشست pin می‌شود. تغییرات پیکربندی/محیط روی نشست‌های جدید یا resetشده اثر می‌گذارند، نه روی transcript موجود. نشست‌های legacy که تاریخچه transcript دارند اما pin ثبت‌شده ندارند، به‌عنوان PI-pinned در نظر گرفته می‌شوند. `/status` runtime موثر را گزارش می‌کند، برای مثال `Runtime: OpenClaw Pi Default` یا `Runtime: OpenAI Codex`. -- این فقط اجرای نوبت‌های عامل متنی را کنترل می‌کند. تولید رسانه، بینایی، PDF، موسیقی، ویدیو و TTS همچنان از تنظیمات provider/model خود استفاده می‌کنند. +- انتخاب harness بعد از نخستین اجرای embedded برای هر شناسه نشست pin می‌شود. تغییرات پیکربندی/محیط روی نشست‌های جدید یا reset شده اثر می‌گذارند، نه transcript موجود. نشست‌های قدیمی با سابقه transcript اما بدون pin ثبت‌شده، PI-pinned تلقی می‌شوند. `/status` runtime مؤثر را گزارش می‌کند، برای مثال `Runtime: OpenClaw Pi Default` یا `Runtime: OpenAI Codex`. +- این فقط اجرای نوبت‌های متنی agent را کنترل می‌کند. تولید رسانه، بینایی، PDF، موسیقی، ویدئو و TTS همچنان از تنظیمات provider/model خود استفاده می‌کنند. -**میانبرهای alias داخلی** (فقط وقتی اعمال می‌شوند که مدل در `agents.defaults.models` باشد): +**میان‌برهای alias داخلی** (فقط وقتی اعمال می‌شوند که مدل در `agents.defaults.models` باشد): -| نام مستعار | مدل | +| نام مستعار | مدل | | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -433,15 +433,15 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -نام‌های مستعار پیکربندی‌شدهٔ شما همیشه بر پیش‌فرض‌ها اولویت دارند. +نام‌های مستعار پیکربندی‌شده شما همیشه بر پیش‌فرض‌ها مقدم هستند. مدل‌های Z.AI GLM-4.x به‌طور خودکار حالت تفکر را فعال می‌کنند، مگر اینکه `--thinking off` را تنظیم کنید یا خودتان `agents.defaults.models["zai/"].params.thinking` را تعریف کنید. -مدل‌های Z.AI به‌طور پیش‌فرض برای جریان‌سازی فراخوانی ابزار، `tool_stream` را فعال می‌کنند. برای غیرفعال کردن آن، `agents.defaults.models["zai/"].params.tool_stream` را روی `false` تنظیم کنید. +مدل‌های Z.AI برای جریان‌سازی فراخوانی ابزار، به‌طور پیش‌فرض `tool_stream` را فعال می‌کنند. برای غیرفعال کردن آن، `agents.defaults.models["zai/"].params.tool_stream` را روی `false` تنظیم کنید. مدل‌های Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد، به‌طور پیش‌فرض از تفکر `adaptive` استفاده می‌کنند. ### `agents.defaults.cliBackends` -بک‌اندهای CLI اختیاری برای اجراهای جایگزین فقط متنی (بدون فراخوانی ابزار). زمانی مفید است که ارائه‌دهندگان API شکست بخورند. +پشتانه‌های اختیاری CLI برای اجراهای جایگزین فقط‌متنی (بدون فراخوانی ابزار). زمانی مفید است که ارائه‌دهندگان API شکست بخورند. ```json5 { @@ -470,13 +470,13 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- بک‌اندهای CLI در درجهٔ اول متنی هستند؛ ابزارها همیشه غیرفعال‌اند. +- پشتانه‌های CLI متن‌محور هستند؛ ابزارها همیشه غیرفعال‌اند. - وقتی `sessionArg` تنظیم شده باشد، نشست‌ها پشتیبانی می‌شوند. - وقتی `imageArg` مسیرهای فایل را بپذیرد، عبور مستقیم تصویر پشتیبانی می‌شود. ### `agents.defaults.systemPromptOverride` -کل پرامپت سیستم ساخته‌شده توسط OpenClaw را با یک رشتهٔ ثابت جایگزین کنید. در سطح پیش‌فرض (`agents.defaults.systemPromptOverride`) یا برای هر عامل (`agents.list[].systemPromptOverride`) تنظیم کنید. مقدارهای هر عامل اولویت دارند؛ مقدار خالی یا فقط شامل فاصله نادیده گرفته می‌شود. برای آزمایش‌های کنترل‌شدهٔ پرامپت مفید است. +کل پرامپت سیستمی ساخته‌شده توسط OpenClaw را با یک رشته ثابت جایگزین کنید. در سطح پیش‌فرض (`agents.defaults.systemPromptOverride`) یا برای هر عامل (`agents.list[].systemPromptOverride`) تنظیم کنید. مقادیر مختص عامل اولویت دارند؛ مقدار خالی یا فقط شامل فاصله نادیده گرفته می‌شود. برای آزمایش‌های کنترل‌شده پرامپت مفید است. ```json5 { @@ -490,7 +490,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و ### `agents.defaults.promptOverlays` -روکش‌های پرامپت مستقل از ارائه‌دهنده که بر اساس خانوادهٔ مدل اعمال می‌شوند. شناسه‌های مدل خانوادهٔ GPT-5 قرارداد رفتاری مشترک را در سراسر ارائه‌دهندگان دریافت می‌کنند؛ `personality` فقط لایهٔ سبک تعامل دوستانه را کنترل می‌کند. +پوشش‌های پرامپت مستقل از ارائه‌دهنده که بر اساس خانواده مدل اعمال می‌شوند. شناسه‌های مدل خانواده GPT-5 قرارداد رفتاری مشترک را در همه ارائه‌دهندگان دریافت می‌کنند؛ `personality` فقط لایه سبک تعامل دوستانه را کنترل می‌کند. ```json5 { @@ -506,9 +506,9 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- `"friendly"` (پیش‌فرض) و `"on"` لایهٔ سبک تعامل دوستانه را فعال می‌کنند. -- `"off"` فقط لایهٔ دوستانه را غیرفعال می‌کند؛ قرارداد رفتاری برچسب‌خوردهٔ GPT-5 همچنان فعال می‌ماند. -- مقدار قدیمی `plugins.entries.openai.config.personality` همچنان وقتی این تنظیم مشترک تعیین نشده باشد خوانده می‌شود. +- `"friendly"` (پیش‌فرض) و `"on"` لایه سبک تعامل دوستانه را فعال می‌کنند. +- `"off"` فقط لایه دوستانه را غیرفعال می‌کند؛ قرارداد رفتاری برچسب‌خورده GPT-5 همچنان فعال می‌ماند. +- وقتی این تنظیم مشترک تنظیم نشده باشد، `plugins.entries.openai.config.personality` قدیمی همچنان خوانده می‌شود. ### `agents.defaults.heartbeat` @@ -540,15 +540,15 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- `every`: رشتهٔ مدت‌زمان (ms/s/m/h). پیش‌فرض: `30m` (احراز هویت با کلید API) یا `1h` (احراز هویت OAuth). برای غیرفعال کردن، روی `0m` تنظیم کنید. -- `includeSystemPromptSection`: وقتی false باشد، بخش Heartbeat را از پرامپت سیستم حذف می‌کند و تزریق `HEARTBEAT.md` به بافت راه‌اندازی را رد می‌کند. پیش‌فرض: `true`. -- `suppressToolErrorWarnings`: وقتی true باشد، payloadهای هشدار خطای ابزار را هنگام اجرای Heartbeat سرکوب می‌کند. -- `timeoutSeconds`: بیشینهٔ زمان مجاز به ثانیه برای یک نوبت عامل Heartbeat پیش از لغو شدن. برای استفاده از `agents.defaults.timeoutSeconds` تنظیم‌نشده رهایش کنید. +- `every`: رشته مدت‌زمان (ms/s/m/h). پیش‌فرض: `30m` (احراز هویت با کلید API) یا `1h` (احراز هویت OAuth). برای غیرفعال کردن، روی `0m` تنظیم کنید. +- `includeSystemPromptSection`: وقتی false باشد، بخش Heartbeat را از پرامپت سیستمی حذف می‌کند و تزریق `HEARTBEAT.md` به زمینه آغازین را رد می‌کند. پیش‌فرض: `true`. +- `suppressToolErrorWarnings`: وقتی true باشد، payloadهای هشدار خطای ابزار را در طول اجراهای heartbeat سرکوب می‌کند. +- `timeoutSeconds`: حداکثر زمان مجاز بر حسب ثانیه برای یک نوبت عامل heartbeat پیش از لغو شدن. برای استفاده از `agents.defaults.timeoutSeconds` تنظیم‌نشده بگذارید. - `directPolicy`: سیاست تحویل مستقیم/DM. `allow` (پیش‌فرض) تحویل به مقصد مستقیم را مجاز می‌کند. `block` تحویل به مقصد مستقیم را سرکوب می‌کند و `reason=dm-blocked` منتشر می‌کند. -- `lightContext`: وقتی true باشد، اجراهای Heartbeat از بافت راه‌اندازی سبک استفاده می‌کنند و فقط `HEARTBEAT.md` را از فایل‌های راه‌اندازی فضای کاری نگه می‌دارند. -- `isolatedSession`: وقتی true باشد، هر Heartbeat در یک نشست تازه بدون تاریخچهٔ گفت‌وگوی قبلی اجرا می‌شود. همان الگوی جداسازی مانند Cron با `sessionTarget: "isolated"`. هزینهٔ توکن هر Heartbeat را از حدود 100K به حدود 2 تا 5K توکن کاهش می‌دهد. -- `skipWhenBusy`: وقتی true باشد، اجراهای Heartbeat در مسیرهای مشغول اضافی به تعویق می‌افتند: کار عامل فرعی یا فرمان تودرتو. مسیرهای Cron همیشه Heartbeatها را به تعویق می‌اندازند، حتی بدون این پرچم. -- برای هر عامل: `agents.list[].heartbeat` را تنظیم کنید. وقتی هر عاملی `heartbeat` را تعریف کند، **فقط همان عامل‌ها** Heartbeat اجرا می‌کنند. +- `lightContext`: وقتی true باشد، اجراهای heartbeat از زمینه آغازین سبک استفاده می‌کنند و از میان فایل‌های آغازین فضای کاری فقط `HEARTBEAT.md` را نگه می‌دارند. +- `isolatedSession`: وقتی true باشد، هر heartbeat در یک نشست تازه بدون تاریخچه گفت‌وگوی قبلی اجرا می‌شود. همان الگوی جداسازی cron `sessionTarget: "isolated"`. هزینه توکن هر heartbeat را از حدود 100K به حدود 2-5K توکن کاهش می‌دهد. +- `skipWhenBusy`: وقتی true باشد، اجراهای heartbeat در مسیرهای مشغول اضافی به تعویق می‌افتند: کارهای زیرفعامل یا فرمان‌های تو در تو. مسیرهای Cron همیشه heartbeatها را به تعویق می‌اندازند، حتی بدون این پرچم. +- برای هر عامل: `agents.list[].heartbeat` را تنظیم کنید. وقتی هر عاملی `heartbeat` را تعریف کند، **فقط همان عامل‌ها** heartbeat اجرا می‌کنند. - Heartbeatها نوبت‌های کامل عامل را اجرا می‌کنند — بازه‌های کوتاه‌تر توکن بیشتری مصرف می‌کنند. ### `agents.defaults.compaction` @@ -566,6 +566,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, + midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction @@ -585,21 +586,22 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و ``` - `mode`: `default` یا `safeguard` (خلاصه‌سازی قطعه‌ای برای تاریخچه‌های طولانی). [Compaction](/fa/concepts/compaction) را ببینید. -- `provider`: شناسهٔ یک Plugin ارائه‌دهندهٔ ثبت‌شده برای Compaction. وقتی تنظیم شود، به‌جای خلاصه‌سازی LLM داخلی، `summarize()` ارائه‌دهنده فراخوانی می‌شود. در صورت شکست، به حالت داخلی بازمی‌گردد. تنظیم یک ارائه‌دهنده، `mode: "safeguard"` را اجباری می‌کند. [Compaction](/fa/concepts/compaction) را ببینید. -- `timeoutSeconds`: بیشینهٔ ثانیه‌های مجاز برای یک عملیات Compaction پیش از آنکه OpenClaw آن را لغو کند. پیش‌فرض: `900`. -- `keepRecentTokens`: بودجهٔ نقطهٔ برش Pi برای نگه داشتن دنبالهٔ اخیر transcript به‌صورت کلمه‌به‌کلمه. `/compact` دستی وقتی صریحاً تنظیم شده باشد این را رعایت می‌کند؛ در غیر این صورت، Compaction دستی یک checkpoint سخت است. -- `identifierPolicy`: `strict` (پیش‌فرض)، `off`، یا `custom`. `strict` راهنمای داخلی نگهداشت شناسه‌های opaque را هنگام خلاصه‌سازی Compaction در ابتدا اضافه می‌کند. -- `identifierInstructions`: متن سفارشی اختیاری برای حفظ شناسه، که وقتی `identifierPolicy=custom` باشد استفاده می‌شود. -- `qualityGuard`: بررسی‌های retry-on-malformed-output برای خلاصه‌های safeguard. در حالت safeguard به‌طور پیش‌فرض فعال است؛ برای رد کردن audit، `enabled: false` را تنظیم کنید. -- `postCompactionSections`: نام‌های بخش H2/H3 اختیاری از AGENTS.md برای تزریق دوباره پس از Compaction. پیش‌فرض `["Session Startup", "Red Lines"]` است؛ برای غیرفعال کردن تزریق دوباره، `[]` را تنظیم کنید. وقتی تنظیم نشده باشد یا صریحاً روی همان جفت پیش‌فرض تنظیم شده باشد، عنوان‌های قدیمی‌تر `Every Session`/`Safety` نیز به‌عنوان جایگزین قدیمی پذیرفته می‌شوند. -- `model`: override اختیاری `provider/model-id` فقط برای خلاصه‌سازی Compaction. وقتی نشست اصلی باید یک مدل را نگه دارد اما خلاصه‌های Compaction باید روی مدل دیگری اجرا شوند، از این استفاده کنید؛ وقتی تنظیم نشده باشد، Compaction از مدل اصلی نشست استفاده می‌کند. -- `maxActiveTranscriptBytes`: آستانهٔ بایت اختیاری (`number` یا رشته‌هایی مانند `"20mb"`) که وقتی JSONL فعال از آستانه عبور کند، پیش از اجرا Compaction محلی عادی را فعال می‌کند. به `truncateAfterCompaction` نیاز دارد تا Compaction موفق بتواند به transcript جانشین کوچک‌تری بچرخد. وقتی تنظیم نشده باشد یا `0` باشد، غیرفعال است. -- `notifyUser`: وقتی `true` باشد، هنگام آغاز و پایان Compaction اعلان‌های کوتاهی به کاربر می‌فرستد (برای مثال، "Compacting context..." و "Compaction complete"). برای سکوت Compaction به‌طور پیش‌فرض غیرفعال است. -- `memoryFlush`: نوبت عامل‌محور بی‌صدا پیش از Compaction خودکار برای ذخیرهٔ حافظه‌های پایدار. وقتی این نوبت housekeeping باید روی یک مدل محلی بماند، `model` را روی ارائه‌دهنده/مدل دقیقی مانند `ollama/qwen3:8b` تنظیم کنید؛ این override زنجیرهٔ fallback نشست فعال را به ارث نمی‌برد. وقتی فضای کاری فقط‌خواندنی باشد رد می‌شود. +- `provider`: شناسه یک Plugin ارائه‌دهنده Compaction ثبت‌شده. وقتی تنظیم شود، به‌جای خلاصه‌سازی داخلی LLM، `summarize()` ارائه‌دهنده فراخوانی می‌شود. در صورت شکست، به حالت داخلی بازمی‌گردد. تنظیم ارائه‌دهنده، `mode: "safeguard"` را اجباری می‌کند. [Compaction](/fa/concepts/compaction) را ببینید. +- `timeoutSeconds`: حداکثر ثانیه‌های مجاز برای یک عملیات Compaction پیش از آنکه OpenClaw آن را لغو کند. پیش‌فرض: `900`. +- `keepRecentTokens`: بودجه نقطه برش Pi برای نگه داشتن دنباله اخیر رونوشت به‌صورت عین به عین. `/compact` دستی وقتی صریحا تنظیم شده باشد از این مقدار تبعیت می‌کند؛ در غیر این صورت Compaction دستی یک checkpoint سخت است. +- `identifierPolicy`: `strict` (پیش‌فرض)، `off`، یا `custom`. `strict` راهنمای داخلی نگه‌داری شناسه‌های مبهم را در طول خلاصه‌سازی Compaction به ابتدا اضافه می‌کند. +- `identifierInstructions`: متن سفارشی اختیاری برای حفظ شناسه‌ها که وقتی `identifierPolicy=custom` باشد استفاده می‌شود. +- `qualityGuard`: بررسی‌های تلاش مجدد هنگام خروجی بدشکل برای خلاصه‌های safeguard. به‌طور پیش‌فرض در حالت safeguard فعال است؛ برای رد کردن ممیزی، `enabled: false` را تنظیم کنید. +- `midTurnPrecheck`: بررسی اختیاری فشار چرخه ابزار Pi. وقتی `enabled: true` باشد، OpenClaw پس از افزوده شدن نتایج ابزار و پیش از فراخوانی بعدی مدل، فشار زمینه را بررسی می‌کند. اگر زمینه دیگر جا نشود، تلاش جاری را پیش از ارسال پرامپت لغو می‌کند و از مسیر بازیابی precheck موجود برای کوتاه کردن نتایج ابزار یا compact و تلاش مجدد استفاده می‌کند. با هر دو حالت Compaction یعنی `default` و `safeguard` کار می‌کند. پیش‌فرض: غیرفعال. +- `postCompactionSections`: نام‌های اختیاری بخش‌های H2/H3 در AGENTS.md برای تزریق دوباره پس از Compaction. پیش‌فرض `["Session Startup", "Red Lines"]` است؛ برای غیرفعال کردن تزریق دوباره، `[]` را تنظیم کنید. وقتی تنظیم نشده باشد یا صریحا روی همان جفت پیش‌فرض تنظیم شده باشد، عنوان‌های قدیمی‌تر `Every Session`/`Safety` نیز به‌عنوان جایگزین legacy پذیرفته می‌شوند. +- `model`: بازنویسی اختیاری `provider/model-id` فقط برای خلاصه‌سازی Compaction. زمانی از این استفاده کنید که نشست اصلی باید یک مدل را نگه دارد اما خلاصه‌های Compaction باید روی مدل دیگری اجرا شوند؛ وقتی تنظیم نشده باشد، Compaction از مدل اصلی نشست استفاده می‌کند. +- `maxActiveTranscriptBytes`: آستانه اختیاری بایت (`number` یا رشته‌هایی مانند `"20mb"`) که وقتی JSONL فعال از آستانه عبور کند، پیش از اجرا Compaction محلی عادی را فعال می‌کند. به `truncateAfterCompaction` نیاز دارد تا Compaction موفق بتواند به یک رونوشت جانشین کوچک‌تر بچرخد. وقتی تنظیم نشده باشد یا `0` باشد غیرفعال است. +- `notifyUser`: وقتی `true` باشد، هنگام شروع و تکمیل Compaction اعلان‌های کوتاهی برای کاربر می‌فرستد (برای مثال، "Compacting context..." و "Compaction complete"). به‌طور پیش‌فرض غیرفعال است تا Compaction بی‌صدا بماند. +- `memoryFlush`: نوبت عامل‌محور بی‌صدا پیش از Compaction خودکار برای ذخیره حافظه‌های پایدار. وقتی این نوبت نگه‌داری باید روی یک مدل محلی بماند، `model` را روی ارائه‌دهنده/مدل دقیق مانند `ollama/qwen3:8b` تنظیم کنید؛ این بازنویسی زنجیره جایگزین نشست فعال را به ارث نمی‌برد. وقتی فضای کاری فقط‌خواندنی باشد رد می‌شود. ### `agents.defaults.contextPruning` -**نتایج ابزار قدیمی** را پیش از ارسال به LLM از بافت درون‌حافظه‌ای هرس می‌کند. تاریخچهٔ نشست روی دیسک را **تغییر نمی‌دهد**. +**نتایج قدیمی ابزار** را پیش از ارسال به LLM از زمینه درون‌حافظه‌ای هرس می‌کند. تاریخچه نشست روی دیسک را تغییر **نمی‌دهد**. ```json5 { @@ -624,18 +626,18 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و - `mode: "cache-ttl"` گذرهای هرس را فعال می‌کند. -- `ttl` کنترل می‌کند هرس هر چند وقت یک‌بار می‌تواند دوباره اجرا شود (پس از آخرین لمس cache). -- هرس ابتدا نتایج ابزار بیش‌ازحد بزرگ را نرم‌برش می‌دهد، سپس در صورت نیاز نتایج ابزار قدیمی‌تر را سخت‌پاک می‌کند. +- `ttl` کنترل می‌کند که هرس هر چند وقت یک‌بار دوباره اجرا شود (پس از آخرین لمس cache). +- هرس ابتدا نتایج ابزار بیش‌ازحد بزرگ را به‌صورت نرم کوتاه می‌کند، سپس در صورت نیاز نتایج قدیمی‌تر ابزار را پاک‌سازی سخت می‌کند. -**برش نرم** ابتدا + انتها را نگه می‌دارد و `...` را در میانه درج می‌کند. +**کوتاه‌سازی نرم** ابتدا + انتها را نگه می‌دارد و `...` را در میانه درج می‌کند. -**پاک‌سازی سخت** کل نتیجهٔ ابزار را با placeholder جایگزین می‌کند. +**پاک‌سازی سخت** کل نتیجه ابزار را با placeholder جایگزین می‌کند. -نکته‌ها: +نکات: -- بلوک‌های تصویر هرگز برش/پاک نمی‌شوند. -- نسبت‌ها بر پایهٔ نویسه‌اند (تقریبی)، نه شمارش دقیق توکن. -- اگر کمتر از `keepLastAssistants` پیام دستیار وجود داشته باشد، هرس رد می‌شود. +- بلوک‌های تصویر هرگز کوتاه/پاک‌سازی نمی‌شوند. +- نسبت‌ها مبتنی بر نویسه‌اند (تقریبی)، نه شمارش دقیق توکن. +- اگر تعداد پیام‌های دستیار کمتر از `keepLastAssistants` باشد، هرس رد می‌شود. @@ -657,11 +659,11 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- کانال‌های غیر Telegram برای فعال کردن پاسخ‌های بلوکی به `*.blockStreaming: true` صریح نیاز دارند. -- overrideهای کانال: `channels..blockStreamingCoalesce` (و گونه‌های هر حساب). Signal/Slack/Discord/Google Chat به‌طور پیش‌فرض `minChars: 1500` دارند. -- `humanDelay`: مکث تصادفی بین پاسخ‌های بلوکی. `natural` = 800–2500ms. override هر عامل: `agents.list[].humanDelay`. +- کانال‌های غیر Telegram برای فعال‌کردن پاسخ‌های بلوکی به `*.blockStreaming: true` صریح نیاز دارند. +- بازنویسی‌های کانال: `channels..blockStreamingCoalesce` (و گونه‌های جداگانه برای هر حساب). Signal/Slack/Discord/Google Chat به‌طور پیش‌فرض `minChars: 1500` دارند. +- `humanDelay`: مکث تصادفی بین پاسخ‌های بلوکی. `natural` = ۸۰۰ تا ۲۵۰۰ میلی‌ثانیه. بازنویسی برای هر عامل: `agents.list[].humanDelay`. -برای رفتار و جزئیات تکه‌بندی، [جریان‌سازی](/fa/concepts/streaming) را ببینید. +برای جزئیات رفتار و قطعه‌بندی، [جریان‌سازی](/fa/concepts/streaming) را ببینید. ### نشانگرهای تایپ @@ -676,7 +678,7 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` -- پیش‌فرض‌ها: `instant` برای گفت‌وگوها/اشاره‌های مستقیم، `message` برای گفت‌وگوهای گروهی بدون اشاره. +- پیش‌فرض‌ها: `instant` برای گفت‌وگوهای مستقیم/اشاره‌ها، `message` برای گفت‌وگوهای گروهی بدون اشاره. - بازنویسی‌های هر نشست: `session.typingMode`، `session.typingIntervalSeconds`. [نشانگرهای تایپ](/fa/concepts/typing-indicators) را ببینید. @@ -780,51 +782,51 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و } ``` - + -**Backend:** +**بک‌اند:** -- `docker`: محیط اجرای Docker محلی (پیش‌فرض) -- `ssh`: محیط اجرای راه دور عمومی با پشتوانه SSH -- `openshell`: محیط اجرای OpenShell +- `docker`: زمان‌اجرای Docker محلی (پیش‌فرض) +- `ssh`: زمان‌اجرای راه‌دور عمومی با پشتوانه SSH +- `openshell`: زمان‌اجرای OpenShell -وقتی `backend: "openshell"` انتخاب شود، تنظیمات ویژه محیط اجرا به +وقتی `backend: "openshell"` انتخاب شود، تنظیمات اختصاصی زمان‌اجرا به `plugins.entries.openshell.config` منتقل می‌شوند. -**پیکربندی Backend SSH:** +**پیکربندی بک‌اند SSH:** -- `target`: مقصد SSH در قالب `user@host[:port]` -- `command`: دستور کلاینت SSH (پیش‌فرض: `ssh`) -- `workspaceRoot`: ریشه راه دور مطلق که برای فضاهای کاری هر دامنه استفاده می‌شود +- `target`: هدف SSH در قالب `user@host[:port]` +- `command`: فرمان کلاینت SSH (پیش‌فرض: `ssh`) +- `workspaceRoot`: ریشه مطلق راه‌دور که برای فضاهای کاری هر محدوده استفاده می‌شود - `identityFile` / `certificateFile` / `knownHostsFile`: فایل‌های محلی موجود که به OpenSSH داده می‌شوند -- `identityData` / `certificateData` / `knownHostsData`: محتواهای درون‌خطی یا SecretRefهایی که OpenClaw هنگام اجرا به فایل‌های موقت تبدیل می‌کند -- `strictHostKeyChecking` / `updateHostKeys`: گزینه‌های سیاست کلید میزبان OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: محتوای درون‌خطی یا SecretRefهایی که OpenClaw در زمان اجرا به فایل‌های موقت تبدیل می‌کند +- `strictHostKeyChecking` / `updateHostKeys`: کنترل‌های سیاست کلید میزبان OpenSSH **اولویت احراز هویت SSH:** - `identityData` بر `identityFile` اولویت دارد - `certificateData` بر `certificateFile` اولویت دارد - `knownHostsData` بر `knownHostsFile` اولویت دارد -- مقدارهای `*Data` با پشتوانه SecretRef پیش از شروع نشست سندباکس، از نمایه لحظه‌ای محیط اجرای اسرار فعال resolve می‌شوند +- مقدارهای `*Data` با پشتوانه SecretRef پیش از شروع نشست سندباکس از اسنپ‌شات زمان‌اجرای اسرار فعال حل می‌شوند -**رفتار Backend SSH:** +**رفتار بک‌اند SSH:** -- فضای کاری راه دور را یک بار پس از ایجاد یا ایجاد دوباره seed می‌کند -- سپس فضای کاری SSH راه دور را مرجع نگه می‌دارد +- فضای کاری راه‌دور را پس از ایجاد یا ایجاد دوباره، یک‌بار مقداردهی اولیه می‌کند +- سپس فضای کاری SSH راه‌دور را مرجع اصلی نگه می‌دارد - `exec`، ابزارهای فایل، و مسیرهای رسانه را از طریق SSH مسیریابی می‌کند -- تغییرات راه دور را به‌طور خودکار به میزبان همگام‌سازی نمی‌کند +- تغییرات راه‌دور را به‌طور خودکار به میزبان همگام‌سازی نمی‌کند - از کانتینرهای مرورگر سندباکس پشتیبانی نمی‌کند **دسترسی فضای کاری:** -- `none`: فضای کاری سندباکس هر دامنه زیر `~/.openclaw/sandboxes` -- `ro`: فضای کاری سندباکس در `/workspace`، فضای کاری عامل به‌صورت فقط‌خواندنی در `/agent` mount می‌شود -- `rw`: فضای کاری عامل به‌صورت خواندنی/نوشتنی در `/workspace` mount می‌شود +- `none`: فضای کاری سندباکس برای هر محدوده زیر `~/.openclaw/sandboxes` +- `ro`: فضای کاری سندباکس در `/workspace`، فضای کاری عامل به‌صورت فقط‌خواندنی در `/agent` سوار می‌شود +- `rw`: فضای کاری عامل به‌صورت خواندنی/نوشتنی در `/workspace` سوار می‌شود -**دامنه:** +**محدوده:** -- `session`: کانتینر + فضای کاری برای هر نشست -- `agent`: یک کانتینر + فضای کاری برای هر عامل (پیش‌فرض) +- `session`: کانتینر و فضای کاری برای هر نشست +- `agent`: یک کانتینر و فضای کاری برای هر عامل (پیش‌فرض) - `shared`: کانتینر و فضای کاری مشترک (بدون جداسازی بین نشست‌ها) **پیکربندی Plugin OpenShell:** @@ -855,30 +857,30 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و **حالت OpenShell:** -- `mirror`: پیش از exec راه دور را از محلی seed می‌کند، پس از exec همگام‌سازی معکوس انجام می‌دهد؛ فضای کاری محلی مرجع می‌ماند -- `remote`: هنگام ایجاد سندباکس، راه دور را یک بار seed می‌کند، سپس فضای کاری راه دور را مرجع نگه می‌دارد +- `mirror`: پیش از exec از محلی به راه‌دور مقداردهی اولیه می‌کند، پس از exec به عقب همگام‌سازی می‌کند؛ فضای کاری محلی مرجع اصلی می‌ماند +- `remote`: هنگام ایجاد سندباکس، راه‌دور را یک‌بار مقداردهی اولیه می‌کند، سپس فضای کاری راه‌دور را مرجع اصلی نگه می‌دارد -در حالت `remote`، ویرایش‌های محلی میزبان که خارج از OpenClaw انجام می‌شوند، پس از مرحله seed به‌طور خودکار به سندباکس همگام‌سازی نمی‌شوند. +در حالت `remote`، ویرایش‌های محلی میزبان که خارج از OpenClaw انجام شوند پس از مرحله مقداردهی اولیه به‌طور خودکار داخل سندباکس همگام‌سازی نمی‌شوند. انتقال از طریق SSH به سندباکس OpenShell انجام می‌شود، اما Plugin مالک چرخه عمر سندباکس و همگام‌سازی mirror اختیاری است. -**`setupCommand`** یک بار پس از ایجاد کانتینر اجرا می‌شود (از طریق `sh -lc`). به خروجی شبکه، ریشه قابل نوشتن، و کاربر root نیاز دارد. +**`setupCommand`** یک‌بار پس از ایجاد کانتینر اجرا می‌شود (از طریق `sh -lc`). به خروجی شبکه، ریشه قابل نوشتن، و کاربر ریشه نیاز دارد. **کانتینرها به‌طور پیش‌فرض `network: "none"` دارند** — اگر عامل به دسترسی خروجی نیاز دارد، آن را روی `"bridge"` (یا یک شبکه bridge سفارشی) تنظیم کنید. -`"host"` مسدود است. `"container:"` به‌طور پیش‌فرض مسدود است، مگر اینکه به‌صراحت -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass) را تنظیم کنید. +`"host"` مسدود است. `"container:"` به‌طور پیش‌فرض مسدود است مگر اینکه به‌صراحت +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (حالت اضطراری) را تنظیم کنید. -**پیوست‌های ورودی** در `media/inbound/*` در فضای کاری فعال stage می‌شوند. +**پیوست‌های ورودی** در `media/inbound/*` داخل فضای کاری فعال قرار داده می‌شوند. -**`docker.binds`** دایرکتوری‌های میزبان اضافی را mount می‌کند؛ bindهای سراسری و هر عامل با هم ادغام می‌شوند. +**`docker.binds`** دایرکتوری‌های میزبان اضافی را سوار می‌کند؛ bindهای سراسری و هر عامل با هم ادغام می‌شوند. -**مرورگر سندباکس‌شده** (`sandbox.browser.enabled`): Chromium + CDP در یک کانتینر. URL noVNC به system prompt تزریق می‌شود. به `browser.enabled` در `openclaw.json` نیاز ندارد. -دسترسی ناظر noVNC به‌طور پیش‌فرض از احراز هویت VNC استفاده می‌کند و OpenClaw یک URL توکن کوتاه‌عمر منتشر می‌کند (به‌جای افشای گذرواژه در URL مشترک). +**مرورگر سندباکس‌شده** (`sandbox.browser.enabled`): Chromium + CDP در یک کانتینر. URL مربوط به noVNC داخل پرامپت سیستم تزریق می‌شود. به `browser.enabled` در `openclaw.json` نیاز ندارد. +دسترسی مشاهده‌گر noVNC به‌طور پیش‌فرض از احراز هویت VNC استفاده می‌کند و OpenClaw یک URL توکن کوتاه‌عمر صادر می‌کند (به‌جای افشای گذرواژه در URL مشترک). -- `allowHostControl: false` (پیش‌فرض) نشست‌های سندباکس‌شده را از هدف‌گیری مرورگر میزبان منع می‌کند. +- `allowHostControl: false` (پیش‌فرض) جلوی هدف‌گرفتن مرورگر میزبان توسط نشست‌های سندباکس‌شده را می‌گیرد. - `network` به‌طور پیش‌فرض `openclaw-sandbox-browser` است (شبکه bridge اختصاصی). فقط وقتی به‌صراحت اتصال bridge سراسری می‌خواهید، آن را روی `bridge` تنظیم کنید. -- `cdpSourceRange` به‌صورت اختیاری ورود CDP را در لبه کانتینر به یک بازه CIDR محدود می‌کند (برای مثال `172.21.0.1/32`). -- `sandbox.browser.binds` فقط دایرکتوری‌های میزبان اضافی را در کانتینر مرورگر سندباکس mount می‌کند. وقتی تنظیم شود (از جمله `[]`)، برای کانتینر مرورگر جایگزین `docker.binds` می‌شود. -- پیش‌فرض‌های راه‌اندازی در `scripts/sandbox-browser-entrypoint.sh` تعریف شده‌اند و برای میزبان‌های کانتینر تنظیم شده‌اند: +- `cdpSourceRange` به‌صورت اختیاری ورود CDP را در لبه کانتینر به یک محدوده CIDR محدود می‌کند (برای مثال `172.21.0.1/32`). +- `sandbox.browser.binds` دایرکتوری‌های میزبان اضافی را فقط داخل کانتینر مرورگر سندباکس سوار می‌کند. وقتی تنظیم شود (از جمله `[]`)، جایگزین `docker.binds` برای کانتینر مرورگر می‌شود. +- پیش‌فرض‌های راه‌اندازی در `scripts/sandbox-browser-entrypoint.sh` تعریف شده‌اند و برای میزبان‌های کانتینری تنظیم شده‌اند: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -895,24 +897,24 @@ OpenClaw چندین بودجهٔ پرحجم اعلان/زمینه دارد، و - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (به‌طور پیش‌فرض فعال است) - - `--disable-3d-apis`، `--disable-software-rasterizer`، و `--disable-gpu` - به‌طور پیش‌فرض فعال هستند و اگر استفاده از WebGL/3D به آن نیاز داشته باشد، - می‌توان آن‌ها را با `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` غیرفعال کرد. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` اگر گردش کار شما - به افزونه‌ها وابسته باشد، آن‌ها را دوباره فعال می‌کند. + - `--disable-extensions` (به‌طور پیش‌فرض فعال) + - `--disable-3d-apis`، `--disable-software-rasterizer`، و `--disable-gpu` به‌طور پیش‌فرض + فعال هستند و اگر استفاده از WebGL/3D به آن نیاز داشته باشد، می‌توانند با + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` غیرفعال شوند. + - اگر گردش کار شما به افزونه‌ها وابسته است، `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` + آن‌ها را دوباره فعال می‌کند. - `--renderer-process-limit=2` را می‌توان با - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` تغییر داد؛ برای استفاده از - محدودیت فرایند پیش‌فرض Chromium، `0` تنظیم کنید. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` تغییر داد؛ برای استفاده از سقف + پیش‌فرض فرایند Chromium، `0` تنظیم کنید. - به‌علاوه `--no-sandbox` وقتی `noSandbox` فعال باشد. - - پیش‌فرض‌ها خط مبنای تصویر کانتینر هستند؛ برای تغییر پیش‌فرض‌های کانتینر، از یک تصویر مرورگر سفارشی با + - پیش‌فرض‌ها خط مبنای تصویر کانتینر هستند؛ برای تغییر پیش‌فرض‌های کانتینر از یک تصویر مرورگر سفارشی با entrypoint سفارشی استفاده کنید. سندباکس‌سازی مرورگر و `sandbox.docker.binds` فقط مخصوص Docker هستند. -ساخت تصاویر: +ساخت تصویرها: ```bash scripts/sandbox-setup.sh # main sandbox image @@ -921,10 +923,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `agents.list` (بازنویسی‌های هر عامل) -از `agents.list[].tts` استفاده کنید تا برای یک عامل، ارائه‌دهنده TTS، صدا، مدل، -سبک، یا حالت TTS خودکار اختصاصی تعریف کنید. بلوک عامل روی -`messages.tts` سراسری به‌صورت deep-merge ادغام می‌شود، بنابراین اعتبارنامه‌های مشترک می‌توانند در یک جا بمانند و عامل‌های جداگانه فقط فیلدهای صدا یا ارائه‌دهنده مورد نیازشان را بازنویسی کنند. بازنویسی عامل فعال برای پاسخ‌های گفتاری خودکار، `/tts audio`، `/tts status`، و ابزار عامل `tts` اعمال می‌شود. برای نمونه‌های ارائه‌دهنده و اولویت، [تبدیل متن به گفتار](/fa/tools/tts#per-agent-voice-overrides) -را ببینید. +از `agents.list[].tts` استفاده کنید تا به یک عامل ارائه‌دهنده TTS، صدا، مدل، +سبک، یا حالت TTS خودکار اختصاصی بدهید. بلوک عامل به‌صورت deep-merge روی +`messages.tts` سراسری اعمال می‌شود، بنابراین اعتبارنامه‌های مشترک می‌توانند در یک مکان بمانند درحالی‌که عامل‌های جداگانه +فقط فیلدهای صدا یا ارائه‌دهنده موردنیاز خود را بازنویسی می‌کنند. بازنویسی عامل فعال +برای پاسخ‌های گفتاری خودکار، `/tts audio`، `/tts status`، و +ابزار عامل `tts` اعمال می‌شود. برای نمونه‌های ارائه‌دهنده و اولویت‌بندی، [متن‌به‌گفتار](/fa/tools/tts#per-agent-voice-overrides) را ببینید. ```json5 { @@ -978,22 +982,22 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: شناسه پایدار عامل (الزامی). +- `id`: شناسهٔ پایدار عامل (الزامی). - `default`: وقتی چند مورد تنظیم شده باشد، اولین مورد برنده می‌شود (هشدار ثبت می‌شود). اگر هیچ‌کدام تنظیم نشده باشد، اولین ورودی فهرست پیش‌فرض است. -- `model`: فرم رشته‌ای یک مدل اصلی سخت‌گیرانه برای هر عامل تنظیم می‌کند، بدون fallback مدل؛ فرم شیء `{ primary }` نیز سخت‌گیرانه است مگر اینکه `fallbacks` را اضافه کنید. از `{ primary, fallbacks: [...] }` استفاده کنید تا آن عامل را وارد fallback کنید، یا از `{ primary, fallbacks: [] }` استفاده کنید تا رفتار سخت‌گیرانه را صریح کنید. کارهای Cron که فقط `primary` را override می‌کنند، همچنان fallbackهای پیش‌فرض را به ارث می‌برند مگر اینکه `fallbacks: []` را تنظیم کنید. -- `params`: پارامترهای stream برای هر عامل که روی ورودی مدل انتخاب‌شده در `agents.defaults.models` ادغام می‌شوند. از این برای overrideهای ویژه عامل مانند `cacheRetention`، `temperature` یا `maxTokens` بدون تکرار کل کاتالوگ مدل استفاده کنید. -- `tts`: overrideهای اختیاری تبدیل متن به گفتار برای هر عامل. این بلوک به‌صورت عمیق روی `messages.tts` ادغام می‌شود، بنابراین اعتبارنامه‌های provider مشترک و سیاست fallback را در `messages.tts` نگه دارید و فقط مقدارهای ویژه persona مانند provider، voice، model، style یا auto mode را اینجا تنظیم کنید. -- `skills`: allowlist اختیاری skill برای هر عامل. اگر حذف شود، عامل در صورت تنظیم بودن `agents.defaults.skills` آن را به ارث می‌برد؛ یک فهرست صریح به‌جای ادغام، پیش‌فرض‌ها را جایگزین می‌کند، و `[]` یعنی بدون skills. -- `thinkingDefault`: سطح پیش‌فرض اختیاری thinking برای هر عامل (`off | minimal | low | medium | high | xhigh | adaptive | max`). وقتی override در سطح پیام یا جلسه تنظیم نشده باشد، برای این عامل `agents.defaults.thinkingDefault` را override می‌کند. پروفایل provider/model انتخاب‌شده کنترل می‌کند کدام مقدارها معتبر هستند؛ برای Google Gemini، `adaptive` thinking پویای متعلق به provider را نگه می‌دارد (`thinkingLevel` در Gemini 3/3.1 حذف می‌شود، `thinkingBudget: -1` در Gemini 2.5). -- `reasoningDefault`: نمایانی پیش‌فرض اختیاری reasoning برای هر عامل (`on | off | stream`). وقتی override reasoning در سطح پیام یا جلسه تنظیم نشده باشد، برای این عامل `agents.defaults.reasoningDefault` را override می‌کند. -- `fastModeDefault`: پیش‌فرض اختیاری برای هر عامل در fast mode (`true | false`). وقتی override fast-mode در سطح پیام یا جلسه تنظیم نشده باشد اعمال می‌شود. -- `agentRuntime`: override اختیاری سیاست runtime سطح پایین برای هر عامل. از `{ id: "codex" }` استفاده کنید تا یک عامل فقط Codex باشد، در حالی که عامل‌های دیگر fallback پیش‌فرض Pi را در حالت `auto` نگه می‌دارند. -- `runtime`: توصیف‌گر اختیاری runtime برای هر عامل. وقتی عامل باید به‌طور پیش‌فرض از نشست‌های ACP harness استفاده کند، از `type: "acp"` همراه با پیش‌فرض‌های `runtime.acp` (`agent`، `backend`، `mode`، `cwd`) استفاده کنید. -- `identity.avatar`: مسیر نسبی نسبت به workspace، URL با `http(s)`، یا URI با `data:`. +- `model`: فرم رشته‌ای، یک مدل اصلی سخت‌گیرانهٔ مختص هر عامل را بدون مدل جایگزین تنظیم می‌کند؛ فرم شیء `{ primary }` نیز سخت‌گیرانه است، مگر اینکه `fallbacks` را اضافه کنید. از `{ primary, fallbacks: [...] }` استفاده کنید تا آن عامل را وارد جایگزینی کنید، یا از `{ primary, fallbacks: [] }` استفاده کنید تا رفتار سخت‌گیرانه را صریح کنید. کارهای Cron که فقط `primary` را بازنویسی می‌کنند همچنان جایگزین‌های پیش‌فرض را به ارث می‌برند، مگر اینکه `fallbacks: []` را تنظیم کنید. +- `params`: پارامترهای جریان مختص هر عامل که روی ورودی مدل انتخاب‌شده در `agents.defaults.models` ادغام می‌شوند. از این برای بازنویسی‌های مختص عامل مانند `cacheRetention`، `temperature` یا `maxTokens` بدون تکرار کل کاتالوگ مدل استفاده کنید. +- `tts`: بازنویسی‌های اختیاری تبدیل متن به گفتار مختص هر عامل. این بلوک به‌صورت عمیق روی `messages.tts` ادغام می‌شود، بنابراین اعتبارنامه‌های ارائه‌دهندهٔ مشترک و سیاست جایگزینی را در `messages.tts` نگه دارید و فقط مقدارهای مختص پرسونا مانند ارائه‌دهنده، صدا، مدل، سبک یا حالت خودکار را اینجا تنظیم کنید. +- `skills`: فهرست مجاز اختیاری Skills مختص هر عامل. اگر حذف شود، عامل وقتی `agents.defaults.skills` تنظیم شده باشد آن را به ارث می‌برد؛ یک فهرست صریح، پیش‌فرض‌ها را به‌جای ادغام جایگزین می‌کند، و `[]` یعنی بدون Skills. +- `thinkingDefault`: سطح تفکر پیش‌فرض اختیاری مختص هر عامل (`off | minimal | low | medium | high | xhigh | adaptive | max`). وقتی هیچ بازنویسی مختص پیام یا نشست تنظیم نشده باشد، `agents.defaults.thinkingDefault` را برای این عامل بازنویسی می‌کند. نمایهٔ ارائه‌دهنده/مدل انتخاب‌شده تعیین می‌کند کدام مقدارها معتبر هستند؛ برای Google Gemini، `adaptive` تفکر پویا و متعلق به ارائه‌دهنده را حفظ می‌کند (`thinkingLevel` در Gemini 3/3.1 حذف می‌شود، `thinkingBudget: -1` در Gemini 2.5). +- `reasoningDefault`: نمایانی استدلال پیش‌فرض اختیاری مختص هر عامل (`on | off | stream`). وقتی هیچ بازنویسی استدلال مختص پیام یا نشست تنظیم نشده باشد، `agents.defaults.reasoningDefault` را برای این عامل بازنویسی می‌کند. +- `fastModeDefault`: پیش‌فرض اختیاری مختص هر عامل برای حالت سریع (`true | false`). وقتی هیچ بازنویسی حالت سریع مختص پیام یا نشست تنظیم نشده باشد اعمال می‌شود. +- `agentRuntime`: بازنویسی اختیاری سیاست runtime سطح پایین مختص هر عامل. از `{ id: "codex" }` استفاده کنید تا یک عامل فقط Codex باشد، در حالی که عامل‌های دیگر جایگزینی پیش‌فرض PI را در حالت `auto` نگه می‌دارند. +- `runtime`: توصیفگر runtime اختیاری مختص هر عامل. وقتی عامل باید به‌صورت پیش‌فرض از نشست‌های مهار ACP استفاده کند، از `type: "acp"` همراه با پیش‌فرض‌های `runtime.acp` (`agent`، `backend`، `mode`، `cwd`) استفاده کنید. +- `identity.avatar`: مسیر نسبی نسبت به workspace، نشانی `http(s)`، یا URI از نوع `data:`. - `identity` پیش‌فرض‌ها را مشتق می‌کند: `ackReaction` از `emoji`، و `mentionPatterns` از `name`/`emoji`. -- `subagents.allowAgents`: allowlist شناسه‌های عامل برای هدف‌های صریح `sessions_spawn.agentId` (`["*"]` = هرکدام؛ پیش‌فرض: فقط همان عامل). وقتی فراخوانی‌های `agentId` خود-هدف باید مجاز باشند، شناسه درخواست‌کننده را شامل کنید. -- محافظ ارث‌بری sandbox: اگر نشست درخواست‌کننده sandbox شده باشد، `sessions_spawn` هدف‌هایی را که بدون sandbox اجرا می‌شوند رد می‌کند. -- `subagents.requireAgentId`: وقتی true باشد، فراخوانی‌های `sessions_spawn` را که `agentId` را حذف می‌کنند مسدود می‌کند (انتخاب صریح پروفایل را اجباری می‌کند؛ پیش‌فرض: false). +- `subagents.allowAgents`: فهرست مجاز شناسه‌های عامل برای اهداف صریح `sessions_spawn.agentId` (`["*"]` = هرکدام؛ پیش‌فرض: فقط همان عامل). وقتی فراخوانی‌های خودهدف‌گیر `agentId` باید مجاز باشند، شناسهٔ درخواست‌کننده را وارد کنید. +- محافظ وراثت sandbox: اگر نشست درخواست‌کننده sandbox شده باشد، `sessions_spawn` هدف‌هایی را که بدون sandbox اجرا می‌شوند رد می‌کند. +- `subagents.requireAgentId`: وقتی true باشد، فراخوانی‌های `sessions_spawn` را که `agentId` را حذف کرده‌اند مسدود می‌کند (انتخاب صریح نمایه را اجباری می‌کند؛ پیش‌فرض: false). --- @@ -1016,16 +1020,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### فیلدهای match در binding +### فیلدهای تطبیق binding -- `type` (اختیاری): `route` برای مسیریابی عادی (type حذف‌شده پیش‌فرضش route است)، `acp` برای bindingهای پایدار مکالمه ACP. +- `type` (اختیاری): `route` برای مسیریابی عادی (نوعِ حذف‌شده به‌صورت پیش‌فرض route است)، `acp` برای bindingهای گفت‌وگوی پایدار ACP. - `match.channel` (الزامی) - `match.accountId` (اختیاری؛ `*` = هر حساب؛ حذف‌شده = حساب پیش‌فرض) - `match.peer` (اختیاری؛ `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (اختیاری؛ ویژه کانال) +- `match.guildId` / `match.teamId` (اختیاری؛ مختص کانال) - `acp` (اختیاری؛ فقط برای `type: "acp"`): `{ mode, label, cwd, backend }` -**ترتیب match قطعی:** +**ترتیب تطبیق قطعی:** 1. `match.peer` 2. `match.guildId` @@ -1034,13 +1038,13 @@ scripts/sandbox-browser-setup.sh # optional browser image 5. `match.accountId: "*"` (در سطح کانال) 6. عامل پیش‌فرض -در هر لایه، اولین ورودی مطابق در `bindings` برنده می‌شود. +در هر سطح، اولین ورودی مطابق در `bindings` برنده می‌شود. -برای ورودی‌های `type: "acp"`، OpenClaw بر اساس هویت دقیق مکالمه (`match.channel` + account + `match.peer.id`) resolve می‌کند و از ترتیب لایه‌های route binding بالا استفاده نمی‌کند. +برای ورودی‌های `type: "acp"`، OpenClaw بر پایهٔ هویت دقیق گفت‌وگو (`match.channel` + حساب + `match.peer.id`) resolve می‌کند و از ترتیب سطح‌های route binding در بالا استفاده نمی‌کند. -### پروفایل‌های دسترسی برای هر عامل +### نمایه‌های دسترسی مختص هر عامل - + ```json5 { @@ -1058,7 +1062,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1087,7 +1091,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1133,11 +1137,11 @@ scripts/sandbox-browser-setup.sh # optional browser image -برای جزئیات اولویت، [Sandbox و ابزارهای چندعاملی](/fa/tools/multi-agent-sandbox-tools) را ببینید. +برای جزئیات تقدم، [Sandbox و ابزارهای چندعاملی](/fa/tools/multi-agent-sandbox-tools) را ببینید. --- -## جلسه +## نشست ```json5 { @@ -1183,37 +1187,37 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + -- **`scope`**: راهبرد پایه گروه‌بندی جلسه برای بافت‌های group-chat. - - `per-sender` (پیش‌فرض): هر فرستنده درون یک بافت کانال، جلسه ایزوله خودش را می‌گیرد. - - `global`: همه شرکت‌کنندگان در یک بافت کانال یک جلسه مشترک دارند (فقط وقتی استفاده کنید که بافت مشترک مدنظر باشد). -- **`dmScope`**: روش گروه‌بندی DMها. - - `main`: همه DMها جلسه اصلی را به اشتراک می‌گذارند. - - `per-peer`: بر اساس شناسه فرستنده در سراسر کانال‌ها ایزوله می‌کند. - - `per-channel-peer`: برای هر کانال + فرستنده ایزوله می‌کند (برای inboxهای چندکاربره توصیه می‌شود). - - `per-account-channel-peer`: برای هر حساب + کانال + فرستنده ایزوله می‌کند (برای چندحسابی توصیه می‌شود). -- **`identityLinks`**: نگاشتی از شناسه‌های canonical به peerهای دارای پیشوند provider برای اشتراک‌گذاری جلسه بین کانال‌ها. فرمان‌های Dock مانند `/dock_discord` از همین نگاشت برای تغییر route پاسخ جلسه فعال به peer کانال لینک‌شده دیگر استفاده می‌کنند؛ [Docking کانال](/fa/concepts/channel-docking) را ببینید. -- **`reset`**: سیاست reset اصلی. `daily` در ساعت محلی `atHour` reset می‌کند؛ `idle` پس از `idleMinutes` reset می‌کند. وقتی هر دو پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است. تازگی reset روزانه از `sessionStartedAt` ردیف جلسه استفاده می‌کند؛ تازگی reset بیکار از `lastInteractionAt` استفاده می‌کند. نوشتن‌های پس‌زمینه/رویداد سیستمی مانند heartbeat، بیدارباش‌های cron، اعلان‌های exec، و bookkeeping مربوط به gateway می‌توانند `updatedAt` را به‌روزرسانی کنند، اما جلسه‌های daily/idle را تازه نگه نمی‌دارند. -- **`resetByType`**: overrideهای برای هر type (`direct`، `group`، `thread`). `dm` قدیمی به‌عنوان alias برای `direct` پذیرفته می‌شود. -- **`parentForkMaxTokens`**: حداکثر `totalTokens` مجاز برای parent-session هنگام ساختن یک thread session منشعب (پیش‌فرض `100000`). - - اگر `totalTokens` والد بالاتر از این مقدار باشد، OpenClaw به‌جای به ارث بردن history transcript والد، یک thread session تازه آغاز می‌کند. - - `0` را تنظیم کنید تا این محافظ غیرفعال شود و forking از والد همیشه مجاز باشد. -- **`mainKey`**: فیلد قدیمی. Runtime همیشه برای bucket اصلی direct-chat از `"main"` استفاده می‌کند. -- **`agentToAgent.maxPingPongTurns`**: حداکثر نوبت‌های پاسخ رفت‌وبرگشتی بین عامل‌ها هنگام تبادل‌های agent-to-agent (عدد صحیح، بازه: `0`–`5`). `0` زنجیره‌سازی ping-pong را غیرفعال می‌کند. -- **`sendPolicy`**: تطبیق بر اساس `channel`، `chatType` (`direct|group|channel`، همراه با alias قدیمی `dm`)، `keyPrefix`، یا `rawKeyPrefix`. اولین deny برنده می‌شود. -- **`maintenance`**: کنترل‌های پاک‌سازی + نگهداشت session-store. - - `mode`: `warn` فقط هشدارها را صادر می‌کند؛ `enforce` پاک‌سازی را اعمال می‌کند. - - `pruneAfter`: cutoff سنی برای ورودی‌های stale (پیش‌فرض `30d`). - - `maxEntries`: حداکثر تعداد ورودی‌ها در `sessions.json` (پیش‌فرض `500`). Runtime پاک‌سازی دسته‌ای را با یک high-water buffer کوچک برای سقف‌های در اندازه production می‌نویسد؛ `openclaw sessions cleanup --enforce` سقف را بلافاصله اعمال می‌کند. - - `rotateBytes`: منسوخ و نادیده گرفته می‌شود؛ `openclaw doctor --fix` آن را از configهای قدیمی‌تر حذف می‌کند. - - `resetArchiveRetention`: نگهداشت برای آرشیوهای transcript با `*.reset.`. پیش‌فرضش `pruneAfter` است؛ برای غیرفعال‌سازی `false` را تنظیم کنید. - - `maxDiskBytes`: بودجه اختیاری دیسک برای دایرکتوری sessions. در حالت `warn` هشدارها را log می‌کند؛ در حالت `enforce` ابتدا قدیمی‌ترین artifactها/sessionها را حذف می‌کند. - - `highWaterBytes`: هدف اختیاری پس از پاک‌سازی بودجه. پیش‌فرضش `80%` از `maxDiskBytes` است. -- **`threadBindings`**: پیش‌فرض‌های سراسری برای قابلیت‌های جلسه thread-bound. - - `enabled`: سوییچ پیش‌فرض اصلی (providerها می‌توانند override کنند؛ Discord از `channels.discord.threadBindings.enabled` استفاده می‌کند) - - `idleHours`: auto-unfocus پیش‌فرض بر اثر inactivity به ساعت (`0` غیرفعال می‌کند؛ providerها می‌توانند override کنند) - - `maxAgeHours`: حداکثر سن سخت‌گیرانه پیش‌فرض به ساعت (`0` غیرفعال می‌کند؛ providerها می‌توانند override کنند) +- **`scope`**: راهبرد پایهٔ گروه‌بندی نشست برای زمینه‌های گفت‌وگوی گروهی. + - `per-sender` (پیش‌فرض): هر فرستنده درون زمینهٔ یک کانال، نشست جداگانهٔ خودش را می‌گیرد. + - `global`: همهٔ شرکت‌کنندگان در زمینهٔ یک کانال یک نشست واحد را به اشتراک می‌گذارند (فقط وقتی استفاده کنید که زمینهٔ مشترک مدنظر است). +- **`dmScope`**: شیوهٔ گروه‌بندی پیام‌های مستقیم. + - `main`: همهٔ پیام‌های مستقیم نشست اصلی را به اشتراک می‌گذارند. + - `per-peer`: جداسازی بر اساس شناسهٔ فرستنده در همهٔ کانال‌ها. + - `per-channel-peer`: جداسازی به‌ازای کانال + فرستنده (برای صندوق‌های ورودی چندکاربره توصیه می‌شود). + - `per-account-channel-peer`: جداسازی به‌ازای حساب + کانال + فرستنده (برای چندحسابی توصیه می‌شود). +- **`identityLinks`**: نگاشت شناسه‌های canonical به peerهای دارای پیشوند provider برای اشتراک‌گذاری نشست بین کانال‌ها. دستورهای dock مانند `/dock_discord` از همین نگاشت استفاده می‌کنند تا مسیر پاسخ نشست فعال را به peer کانالِ لینک‌شدهٔ دیگری تغییر دهند؛ [داک کردن کانال](/fa/concepts/channel-docking) را ببینید. +- **`reset`**: سیاست اصلی بازنشانی. `daily` در ساعت محلی `atHour` بازنشانی می‌کند؛ `idle` پس از `idleMinutes` بازنشانی می‌کند. وقتی هر دو پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است. تازگی بازنشانی روزانه از `sessionStartedAt` ردیف نشست استفاده می‌کند؛ تازگی بازنشانی idle از `lastInteractionAt` استفاده می‌کند. نوشتن‌های پس‌زمینه/رویداد سیستمی مانند Heartbeat، بیدارباش‌های Cron، اعلان‌های exec و حسابداری Gateway می‌توانند `updatedAt` را به‌روزرسانی کنند، اما نشست‌های روزانه/idle را تازه نگه نمی‌دارند. +- **`resetByType`**: بازنویسی‌های به‌ازای نوع (`direct`، `group`، `thread`). مقدار قدیمی `dm` به‌عنوان alias برای `direct` پذیرفته می‌شود. +- **`parentForkMaxTokens`**: بیشینهٔ `totalTokens` مجازِ نشست والد هنگام ساخت نشست thread منشعب‌شده (پیش‌فرض `100000`). + - اگر `totalTokens` والد بالاتر از این مقدار باشد، OpenClaw به‌جای به‌ارث‌بردن تاریخچهٔ transcript والد، یک نشست thread تازه شروع می‌کند. + - برای غیرفعال‌کردن این محافظ و همیشه مجاز کردن fork از والد، مقدار را `0` بگذارید. +- **`mainKey`**: فیلد قدیمی. Runtime همیشه برای باکت اصلی گفت‌وگوی مستقیم از `"main"` استفاده می‌کند. +- **`agentToAgent.maxPingPongTurns`**: بیشینهٔ نوبت‌های پاسخ‌برگشتی بین agentها در تبادل‌های agent-to-agent (عدد صحیح، بازه: `0` تا `5`). مقدار `0` زنجیره‌سازی ping-pong را غیرفعال می‌کند. +- **`sendPolicy`**: تطبیق بر اساس `channel`، `chatType` (`direct|group|channel`، همراه با alias قدیمی `dm`)، `keyPrefix`، یا `rawKeyPrefix`. اولین deny برنده است. +- **`maintenance`**: پاک‌سازی session-store + کنترل‌های نگهداشت. + - `mode`: مقدار `warn` فقط هشدارها را منتشر می‌کند؛ `enforce` پاک‌سازی را اعمال می‌کند. + - `pruneAfter`: آستانهٔ سن برای ورودی‌های stale (پیش‌فرض `30d`). + - `maxEntries`: بیشینهٔ تعداد ورودی‌ها در `sessions.json` (پیش‌فرض `500`). Runtime پاک‌سازی batch را با یک بافر high-water کوچک برای سقف‌های در اندازهٔ production می‌نویسد؛ `openclaw sessions cleanup --enforce` سقف را فوری اعمال می‌کند. + - `rotateBytes`: منسوخ شده و نادیده گرفته می‌شود؛ `openclaw doctor --fix` آن را از configهای قدیمی‌تر حذف می‌کند. + - `resetArchiveRetention`: نگهداشت برای آرشیوهای transcript با الگوی `*.reset.`. پیش‌فرض برابر `pruneAfter` است؛ برای غیرفعال‌کردن، `false` بگذارید. + - `maxDiskBytes`: بودجهٔ اختیاری دیسک برای پوشهٔ نشست‌ها. در حالت `warn` هشدارها را log می‌کند؛ در حالت `enforce` ابتدا قدیمی‌ترین artifactها/نشست‌ها را حذف می‌کند. + - `highWaterBytes`: هدف اختیاری پس از پاک‌سازی بودجه. پیش‌فرض `80%` از `maxDiskBytes` است. +- **`threadBindings`**: پیش‌فرض‌های سراسری برای ویژگی‌های نشست‌های وابسته به thread. + - `enabled`: سوییچ پیش‌فرض اصلی (providerها می‌توانند بازنویسی کنند؛ Discord از `channels.discord.threadBindings.enabled` استفاده می‌کند) + - `idleHours`: auto-unfocus پیش‌فرض پس از بی‌فعالیتی، برحسب ساعت (`0` غیرفعال می‌کند؛ providerها می‌توانند بازنویسی کنند) + - `maxAgeHours`: بیشینهٔ عمر سخت پیش‌فرض، برحسب ساعت (`0` غیرفعال می‌کند؛ providerها می‌توانند بازنویسی کنند) @@ -1251,36 +1255,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### پیشوند پاسخ -بازنویسی‌های مخصوص هر کانال/حساب: `channels..responsePrefix`،‏ `channels..accounts..responsePrefix`. +بازنویسی‌های به‌ازای کانال/حساب: `channels..responsePrefix`، `channels..accounts..responsePrefix`. -ترتیب تعیین مقدار (خاص‌ترین مورد برنده است): حساب → کانال → سراسری. `""` غیرفعال می‌کند و زنجیره را متوقف می‌کند. `"auto"` از `[{identity.name}]` ساخته می‌شود. +حل مقدار (خاص‌ترین برنده است): حساب → کانال → سراسری. `""` غیرفعال می‌کند و cascade را متوقف می‌کند. `"auto"` مقدار را از `[{identity.name}]` می‌سازد. **متغیرهای قالب:** -| متغیر | توضیح | مثال | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | نام کوتاه مدل | `claude-opus-4-6` | -| `{modelFull}` | شناسه کامل مدل | `anthropic/claude-opus-4-6` | -| `{provider}` | نام ارائه‌دهنده | `anthropic` | -| `{thinkingLevel}` | سطح تفکر فعلی | `high`, `low`, `off` | -| `{identity.name}` | نام هویت عامل | (همانند `"auto"`) | +| متغیر | توضیح | مثال | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | نام کوتاه مدل | `claude-opus-4-6` | +| `{modelFull}` | شناسهٔ کامل مدل | `anthropic/claude-opus-4-6` | +| `{provider}` | نام provider | `anthropic` | +| `{thinkingLevel}` | سطح thinking فعلی | `high`, `low`, `off` | +| `{identity.name}` | نام هویت agent | (همانند `"auto"`) | -متغیرها به بزرگی و کوچکی حروف حساس نیستند. `{think}` نام مستعار `{thinkingLevel}` است. +متغیرها به بزرگی و کوچکی حروف حساس نیستند. `{think}` یک alias برای `{thinkingLevel}` است. ### واکنش تأیید -- به‌طور پیش‌فرض از `identity.emoji` عامل فعال استفاده می‌کند، و در غیر این صورت `"👀"`. برای غیرفعال‌سازی، `""` تنظیم کنید. -- بازنویسی‌های مخصوص هر کانال: `channels..ackReaction`،‏ `channels..accounts..ackReaction`. -- ترتیب تعیین مقدار: حساب → کانال → `messages.ackReaction` → جایگزین هویت. +- پیش‌فرض برابر `identity.emoji` متعلق به agent فعال است، وگرنه `"👀"`. برای غیرفعال‌کردن، `""` بگذارید. +- بازنویسی‌های به‌ازای کانال: `channels..ackReaction`، `channels..accounts..ackReaction`. +- ترتیب حل مقدار: حساب → کانال → `messages.ackReaction` → fallback هویت. - دامنه: `group-mentions` (پیش‌فرض)، `group-all`، `direct`، `all`. -- `removeAckAfterReply`: پس از پاسخ، تأیید را در کانال‌هایی که از واکنش پشتیبانی می‌کنند، مانند Slack، Discord، Telegram، WhatsApp و BlueBubbles حذف می‌کند. -- `messages.statusReactions.enabled`: واکنش‌های وضعیت چرخه عمر را در Slack، Discord و Telegram فعال می‌کند. - در Slack و Discord، مقدار تنظیم‌نشده وقتی واکنش‌های تأیید فعال باشند، واکنش‌های وضعیت را فعال نگه می‌دارد. - در Telegram، برای فعال کردن واکنش‌های وضعیت چرخه عمر، آن را صراحتاً روی `true` تنظیم کنید. +- `removeAckAfterReply`: پس از پاسخ، ack را در کانال‌هایی که از reaction پشتیبانی می‌کنند، مانند Slack، Discord، Telegram، WhatsApp و BlueBubbles حذف می‌کند. +- `messages.statusReactions.enabled`: واکنش‌های وضعیت چرخهٔ عمر را در Slack، Discord و Telegram فعال می‌کند. + در Slack و Discord، مقدار تنظیم‌نشده وقتی واکنش‌های ack فعال باشند، واکنش‌های وضعیت را فعال نگه می‌دارد. + در Telegram، برای فعال‌کردن واکنش‌های وضعیت چرخهٔ عمر، آن را صراحتاً روی `true` بگذارید. ### debounce ورودی -پیام‌های فقط‌متنِ سریع از یک فرستنده را در یک نوبت عامل واحد دسته‌بندی می‌کند. رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند. فرمان‌های کنترلی debounce را دور می‌زنند. +پیام‌های سریعِ فقط‌متنی از همان فرستنده را در یک نوبت agent واحد دسته‌بندی می‌کند. رسانه/پیوست‌ها فوری flush می‌شوند. دستورهای کنترلی debounce را دور می‌زنند. ### TTS (تبدیل متن به گفتار) @@ -1330,13 +1334,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` حالت پیش‌فرض TTS خودکار را کنترل می‌کند: `off`،‏ `always`،‏ `inbound`، یا `tagged`.‏ `/tts on|off` می‌تواند ترجیحات محلی را بازنویسی کند، و `/tts status` وضعیت مؤثر را نشان می‌دهد. -- `summaryModel` برای خلاصه‌سازی خودکار، `agents.defaults.model.primary` را بازنویسی می‌کند. -- `modelOverrides` به‌طور پیش‌فرض فعال است؛ مقدار پیش‌فرض `modelOverrides.allowProvider` برابر `false` است (نیازمند انتخاب صریح). -- کلیدهای API به `ELEVENLABS_API_KEY`/`XI_API_KEY` و `OPENAI_API_KEY` برمی‌گردند. -- ارائه‌دهندگان گفتار همراه، متعلق به Plugin هستند. اگر `plugins.allow` تنظیم شده باشد، هر Plugin ارائه‌دهنده TTS را که می‌خواهید استفاده کنید اضافه کنید، برای مثال `microsoft` برای Edge TTS. شناسه ارائه‌دهنده قدیمی `edge` به‌عنوان نام مستعار `microsoft` پذیرفته می‌شود. -- `providers.openai.baseUrl` نقطه پایانی TTS مربوط به OpenAI را بازنویسی می‌کند. ترتیب تعیین مقدار ابتدا پیکربندی، سپس `OPENAI_TTS_BASE_URL`، سپس `https://api.openai.com/v1` است. -- وقتی `providers.openai.baseUrl` به یک نقطه پایانی غیر OpenAI اشاره کند، OpenClaw آن را به‌عنوان سرور TTS سازگار با OpenAI در نظر می‌گیرد و اعتبارسنجی مدل/صدا را آسان‌تر می‌کند. +- `auto` حالت پیش‌فرض auto-TTS را کنترل می‌کند: `off`، `always`، `inbound`، یا `tagged`. `/tts on|off` می‌تواند prefs محلی را بازنویسی کند، و `/tts status` وضعیت مؤثر را نشان می‌دهد. +- `summaryModel` مقدار `agents.defaults.model.primary` را برای auto-summary بازنویسی می‌کند. +- `modelOverrides` به‌صورت پیش‌فرض فعال است؛ مقدار پیش‌فرض `modelOverrides.allowProvider` برابر `false` است (opt-in). +- کلیدهای API به `ELEVENLABS_API_KEY`/`XI_API_KEY` و `OPENAI_API_KEY` fallback می‌کنند. +- providerهای speech همراه، متعلق به Plugin هستند. اگر `plugins.allow` تنظیم شده باشد، هر Plugin provider مربوط به TTS را که می‌خواهید استفاده کنید اضافه کنید، برای مثال `microsoft` برای Edge TTS. شناسهٔ provider قدیمی `edge` به‌عنوان alias برای `microsoft` پذیرفته می‌شود. +- `providers.openai.baseUrl` endpoint مربوط به OpenAI TTS را بازنویسی می‌کند. ترتیب حل مقدار config است، سپس `OPENAI_TTS_BASE_URL`، سپس `https://api.openai.com/v1`. +- وقتی `providers.openai.baseUrl` به endpoint غیر OpenAI اشاره کند، OpenClaw آن را یک سرور TTS سازگار با OpenAI در نظر می‌گیرد و اعتبارسنجی model/voice را آسان‌گیرتر می‌کند. --- @@ -1371,21 +1375,21 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- وقتی چند ارائه‌دهنده گفت‌وگو پیکربندی شده‌اند، `talk.provider` باید با یک کلید در `talk.providers` مطابقت داشته باشد. -- کلیدهای تخت قدیمی گفت‌وگو (`talk.voiceId`،‏ `talk.voiceAliases`،‏ `talk.modelId`،‏ `talk.outputFormat`،‏ `talk.apiKey`) فقط برای سازگاری هستند و به‌طور خودکار به `talk.providers.` مهاجرت داده می‌شوند. -- شناسه‌های صدا به `ELEVENLABS_VOICE_ID` یا `SAG_VOICE_ID` برمی‌گردند. -- `providers.*.apiKey` رشته‌های متن ساده یا اشیای SecretRef را می‌پذیرد. -- جایگزین `ELEVENLABS_API_KEY` فقط وقتی اعمال می‌شود که هیچ کلید API گفت‌وگو پیکربندی نشده باشد. -- `providers.*.voiceAliases` به دستورهای گفت‌وگو اجازه می‌دهد از نام‌های دوستانه استفاده کنند. -- `providers.mlx.modelId` مخزن Hugging Face مورد استفاده helper محلی MLX در macOS را انتخاب می‌کند. اگر حذف شود، macOS از `mlx-community/Soprano-80M-bf16` استفاده می‌کند. -- پخش MLX در macOS از طریق helper همراه `openclaw-mlx-tts`، در صورت وجود، یا یک فایل اجرایی در `PATH` اجرا می‌شود؛ `OPENCLAW_MLX_TTS_BIN` مسیر helper را برای توسعه بازنویسی می‌کند. -- `speechLocale` شناسه locale از نوع BCP 47 را تنظیم می‌کند که توسط تشخیص گفتار گفت‌وگو در iOS/macOS استفاده می‌شود. برای استفاده از پیش‌فرض دستگاه، آن را تنظیم‌نشده بگذارید. -- `silenceTimeoutMs` کنترل می‌کند حالت گفت‌وگو پس از سکوت کاربر چه مدت منتظر بماند و سپس رونوشت را ارسال کند. مقدار تنظیم‌نشده پنجره مکث پیش‌فرض پلتفرم را نگه می‌دارد (`700 ms در macOS و Android، 900 ms در iOS`). +- وقتی چند provider گفت‌وگو پیکربندی شده باشد، `talk.provider` باید با یکی از کلیدهای `talk.providers` مطابقت داشته باشد. +- کلیدهای flat قدیمی گفت‌وگو (`talk.voiceId`، `talk.voiceAliases`، `talk.modelId`، `talk.outputFormat`، `talk.apiKey`) فقط برای سازگاری هستند و به‌صورت خودکار به `talk.providers.` مهاجرت داده می‌شوند. +- شناسه‌های صدا به `ELEVENLABS_VOICE_ID` یا `SAG_VOICE_ID` fallback می‌کنند. +- `providers.*.apiKey` رشته‌های plaintext یا اشیای SecretRef را می‌پذیرد. +- fallback مربوط به `ELEVENLABS_API_KEY` فقط وقتی اعمال می‌شود که هیچ کلید API گفت‌وگو پیکربندی نشده باشد. +- `providers.*.voiceAliases` اجازه می‌دهد directiveهای گفت‌وگو از نام‌های دوستانه استفاده کنند. +- `providers.mlx.modelId` repo مربوط به Hugging Face را که helper محلی MLX در macOS استفاده می‌کند انتخاب می‌کند. اگر حذف شود، macOS از `mlx-community/Soprano-80M-bf16` استفاده می‌کند. +- پخش MLX در macOS از طریق helper همراه `openclaw-mlx-tts` هنگام وجود آن اجرا می‌شود، یا از یک فایل اجرایی در `PATH`؛ `OPENCLAW_MLX_TTS_BIN` مسیر helper را برای توسعه بازنویسی می‌کند. +- `speechLocale` شناسهٔ locale از نوع BCP 47 را که تشخیص گفتار گفت‌وگوی iOS/macOS استفاده می‌کند تنظیم می‌کند. برای استفاده از پیش‌فرض دستگاه، آن را تنظیم‌نشده بگذارید. +- `silenceTimeoutMs` کنترل می‌کند حالت گفت‌وگو پس از سکوت کاربر چه مدت منتظر بماند تا transcript را ارسال کند. مقدار تنظیم‌نشده پنجرهٔ مکث پیش‌فرض پلتفرم را نگه می‌دارد (`700 ms در macOS و Android، 900 ms در iOS`). --- ## مرتبط -- [مرجع پیکربندی](/fa/gateway/configuration-reference) — همه کلیدهای پیکربندی دیگر +- [مرجع پیکربندی](/fa/gateway/configuration-reference) — همهٔ کلیدهای config دیگر - [پیکربندی](/fa/gateway/configuration) — کارهای رایج و راه‌اندازی سریع - [نمونه‌های پیکربندی](/fa/gateway/configuration-examples) diff --git a/docs/fa/gateway/config-channels.md b/docs/fa/gateway/config-channels.md index 086d6aa4e..a4a4684d7 100644 --- a/docs/fa/gateway/config-channels.md +++ b/docs/fa/gateway/config-channels.md @@ -1,24 +1,22 @@ --- read_when: - - پیکربندی یک Plugin کانال (احراز هویت، کنترل دسترسی، چندحسابه) - - عیب‌یابی کلیدهای پیکربندی به‌ازای هر کانال - - ممیزی سیاست پیام مستقیم، سیاست گروه، یا کنترل‌گری بر اساس منشن -summary: 'پیکربندی کانال: کنترل دسترسی، جفت‌سازی، کلیدهای مختص هر کانال در Slack، Discord، Telegram، WhatsApp، Matrix، iMessage و موارد دیگر' + - پیکربندی یک Plugin کانال (احراز هویت، کنترل دسترسی، چندحسابی) + - عیب‌یابی کلیدهای پیکربندی هر کانال + - ممیزی سیاست پیام مستقیم، سیاست گروه، یا کنترل دسترسی مبتنی بر منشن +summary: 'پیکربندی کانال: کنترل دسترسی، جفت‌سازی، کلیدهای هر کانال در Slack، Discord، Telegram، WhatsApp، Matrix، iMessage و موارد دیگر' title: پیکربندی — کانال‌ها x-i18n: - generated_at: "2026-04-29T22:49:19Z" + generated_at: "2026-04-30T16:29:10Z" model: gpt-5.5 provider: openai - source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f + source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915 source_path: gateway/config-channels.md workflow: 16 --- -کلیدهای پیکربندی هر کانال زیر `channels.*`. دسترسی DM و گروه، -راه‌اندازی‌های چندحسابی، کنترل با منشن، و کلیدهای هر کانال برای Slack، Discord، -Telegram، WhatsApp، Matrix، iMessage و دیگر Pluginهای کانال همراه را پوشش می‌دهد. +کلیدهای پیکربندی مخصوص هر کانال زیر `channels.*`. دسترسی DM و گروه، راه‌اندازی‌های چندحسابی، کنترل مبتنی بر منشن، و کلیدهای هر کانال برای Slack، Discord، Telegram، WhatsApp، Matrix، iMessage، و سایر Pluginهای کانالِ همراه را پوشش می‌دهد. -برای عامل‌ها، ابزارها، زمان اجرای Gateway و دیگر کلیدهای سطح بالا، ببینید: +برای عامل‌ها، ابزارها، runtime مربوط به Gateway، و سایر کلیدهای سطح بالا، ببینید: [مرجع پیکربندی](/fa/gateway/configuration-reference). ## کانال‌ها @@ -29,28 +27,28 @@ Telegram، WhatsApp، Matrix، iMessage و دیگر Pluginهای کانال هم همه کانال‌ها از سیاست‌های DM و سیاست‌های گروه پشتیبانی می‌کنند: -| سیاست DM | رفتار | -| ------------------- | ---------------------------------------------------------------- | -| `pairing` (پیش‌فرض) | فرستنده‌های ناشناس یک کد جفت‌سازی یک‌بارمصرف می‌گیرند؛ مالک باید تأیید کند | -| `allowlist` | فقط فرستنده‌های داخل `allowFrom` (یا ذخیره مجاز جفت‌شده) | -| `open` | اجازه همه DMهای ورودی (نیازمند `allowFrom: ["*"]`) | -| `disabled` | نادیده گرفتن همه DMهای ورودی | +| سیاست DM | رفتار | +| ------------------- | --------------------------------------------------------------- | +| `pairing` (پیش‌فرض) | فرستنده‌های ناشناس یک کد جفت‌سازی یک‌بارمصرف دریافت می‌کنند؛ مالک باید تأیید کند | +| `allowlist` | فقط فرستنده‌های موجود در `allowFrom` (یا ذخیره‌گاه مجاز جفت‌شده) | +| `open` | همه DMهای ورودی را مجاز می‌کند (به `allowFrom: ["*"]` نیاز دارد) | +| `disabled` | همه DMهای ورودی را نادیده می‌گیرد | -| سیاست گروه | رفتار | -| --------------------- | ------------------------------------------------------- | -| `allowlist` (پیش‌فرض) | فقط گروه‌هایی که با فهرست مجاز پیکربندی‌شده مطابق‌اند | -| `open` | عبور از فهرست‌های مجاز گروه (کنترل با منشن همچنان اعمال می‌شود) | -| `disabled` | مسدود کردن همه پیام‌های گروه/اتاق | +| سیاست گروه | رفتار | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (پیش‌فرض) | فقط گروه‌هایی که با allowlist پیکربندی‌شده مطابقت دارند | +| `open` | allowlistهای گروه را دور می‌زند (کنترل مبتنی بر منشن همچنان اعمال می‌شود) | +| `disabled` | همه پیام‌های گروه/اتاق را مسدود می‌کند | `channels.defaults.groupPolicy` مقدار پیش‌فرض را وقتی `groupPolicy` یک ارائه‌دهنده تنظیم نشده باشد تعیین می‌کند. -کدهای جفت‌سازی پس از ۱ ساعت منقضی می‌شوند. درخواست‌های جفت‌سازی DM در انتظار به **۳ مورد در هر کانال** محدود می‌شوند. -اگر بلوک یک ارائه‌دهنده کاملا وجود نداشته باشد (`channels.` غایب باشد)، سیاست گروه در زمان اجرا با یک هشدار شروع، به `allowlist` (بسته در حالت خطا) برمی‌گردد. +کدهای جفت‌سازی پس از ۱ ساعت منقضی می‌شوند. درخواست‌های در انتظار جفت‌سازی DM حداکثر به **۳ درخواست برای هر کانال** محدود می‌شوند. +اگر یک بلوک ارائه‌دهنده کاملاً وجود نداشته باشد (`channels.` غایب باشد)، سیاست گروه در runtime به `allowlist` (بسته در حالت خطا) با یک هشدار هنگام شروع بازمی‌گردد. -### بازنویسی‌های مدل کانال +### جایگزینی‌های مدل کانال -از `channels.modelByChannel` برای ثابت کردن شناسه‌های کانال مشخص به یک مدل استفاده کنید. مقدارها `provider/model` یا نام‌های مستعار مدل پیکربندی‌شده را می‌پذیرند. نگاشت کانال زمانی اعمال می‌شود که یک نشست از قبل بازنویسی مدل نداشته باشد (برای مثال، تنظیم‌شده با `/model`). +از `channels.modelByChannel` برای ثابت‌کردن شناسه‌های کانال مشخص به یک مدل استفاده کنید. مقادیر `provider/model` یا aliasهای مدل پیکربندی‌شده را می‌پذیرند. نگاشت کانال زمانی اعمال می‌شود که یک session از قبل جایگزینی مدل نداشته باشد (برای مثال، از طریق `/model` تنظیم شده باشد). ```json5 { @@ -91,15 +89,15 @@ Telegram، WhatsApp، Matrix، iMessage و دیگر Pluginهای کانال هم } ``` -- `channels.defaults.groupPolicy`: سیاست گروه پشتیبان وقتی `groupPolicy` در سطح ارائه‌دهنده تنظیم نشده باشد. -- `channels.defaults.contextVisibility`: حالت پیش‌فرض دیدپذیری زمینه تکمیلی برای همه کانال‌ها. مقدارها: `all` (پیش‌فرض، شامل همه زمینه‌های نقل‌قول/رشته/تاریخچه)، `allowlist` (فقط شامل زمینه از فرستنده‌های مجاز)، `allowlist_quote` (همان allowlist، اما زمینه نقل‌قول/پاسخ صریح را نگه می‌دارد). بازنویسی هر کانال: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: سیاست گروه جایگزین وقتی `groupPolicy` در سطح ارائه‌دهنده تنظیم نشده باشد. +- `channels.defaults.contextVisibility`: حالت پیش‌فرض نمایش context تکمیلی برای همه کانال‌ها. مقادیر: `all` (پیش‌فرض، شامل همه contextهای نقل‌قول/thread/history)، `allowlist` (فقط شامل context از فرستنده‌های موجود در allowlist)، `allowlist_quote` (همانند allowlist اما context صریح quote/reply را نگه می‌دارد). جایگزینی برای هر کانال: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: وضعیت‌های سالم کانال را در خروجی Heartbeat وارد می‌کند. -- `channels.defaults.heartbeat.showAlerts`: وضعیت‌های تنزل‌یافته/خطا را در خروجی Heartbeat وارد می‌کند. -- `channels.defaults.heartbeat.useIndicator`: خروجی Heartbeat فشرده به سبک نشانگر را نمایش می‌دهد. +- `channels.defaults.heartbeat.showAlerts`: وضعیت‌های degraded/error را در خروجی Heartbeat وارد می‌کند. +- `channels.defaults.heartbeat.useIndicator`: خروجی Heartbeat فشرده به سبک indicator را رندر می‌کند. ### WhatsApp -WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌شود. وقتی یک نشست پیوندشده وجود داشته باشد، به‌صورت خودکار شروع می‌شود. +WhatsApp از طریق کانال وب Gateway اجرا می‌شود (Baileys Web). وقتی یک session پیوندشده وجود داشته باشد، به‌صورت خودکار شروع می‌شود. ```json5 { @@ -157,10 +155,10 @@ WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌ش } ``` -- دستورهای خروجی در صورت وجود، به‌طور پیش‌فرض از حساب `default` استفاده می‌کنند؛ در غیر این صورت از نخستین شناسه حساب پیکربندی‌شده (مرتب‌شده). -- گزینه اختیاری `channels.whatsapp.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض پشتیبان را بازنویسی می‌کند. -- مسیر احراز هویت Baileys قدیمی تک‌حسابی توسط `openclaw doctor` به `whatsapp/default` منتقل می‌شود. -- بازنویسی‌های هر حساب: `channels.whatsapp.accounts..sendReadReceipts`، `channels.whatsapp.accounts..dmPolicy`، `channels.whatsapp.accounts..allowFrom`. +- دستورهای خروجی به‌طور پیش‌فرض از حساب `default` استفاده می‌کنند اگر وجود داشته باشد؛ در غیر این صورت، نخستین شناسه حساب پیکربندی‌شده (مرتب‌شده) استفاده می‌شود. +- گزینه اختیاری `channels.whatsapp.defaultAccount` انتخاب حساب پیش‌فرض جایگزین را وقتی با یک شناسه حساب پیکربندی‌شده مطابقت داشته باشد override می‌کند. +- مسیر auth قدیمی Baileys برای تک‌حساب توسط `openclaw doctor` به `whatsapp/default` مهاجرت داده می‌شود. +- overrideهای هر حساب: `channels.whatsapp.accounts..sendReadReceipts`، `channels.whatsapp.accounts..dmPolicy`، `channels.whatsapp.accounts..allowFrom`. @@ -219,14 +217,14 @@ WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌ش } ``` -- توکن ربات: `channels.telegram.botToken` یا `channels.telegram.tokenFile` (فقط فایل عادی؛ پیوندهای نمادین رد می‌شوند)، با `TELEGRAM_BOT_TOKEN` به‌عنوان پشتیبان برای حساب پیش‌فرض. -- `apiRoot` فقط ریشه Telegram Bot API است. از `https://api.telegram.org` یا ریشه خودمیزبان/پراکسی خود استفاده کنید، نه `https://api.telegram.org/bot`؛ `openclaw doctor --fix` پسوند تصادفی انتهایی `/bot` را حذف می‌کند. -- گزینه اختیاری `channels.telegram.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- در راه‌اندازی‌های چندحسابی (۲ یا چند شناسه حساب)، برای جلوگیری از مسیریابی پشتیبان، یک پیش‌فرض صریح تنظیم کنید (`channels.telegram.defaultAccount` یا `channels.telegram.accounts.default`)؛ `openclaw doctor` وقتی این مورد وجود نداشته باشد یا نامعتبر باشد هشدار می‌دهد. -- `configWrites: false` نوشتن‌های پیکربندی آغازشده از Telegram را مسدود می‌کند (مهاجرت‌های شناسه سوپرگروه، `/config set|unset`). -- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` اتصال‌های پایدار ACP را برای موضوع‌های انجمن پیکربندی می‌کنند (از `chatId:topic:topicId` استاندارد در `match.peer.id` استفاده کنید). معنای فیلدها در [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings) مشترک است. -- پیش‌نمایش‌های جریان Telegram از `sendMessage` + `editMessageText` استفاده می‌کنند (در چت‌های مستقیم و گروهی کار می‌کند). -- سیاست تلاش مجدد: ببینید [سیاست تلاش مجدد](/fa/concepts/retry). +- توکن ربات: `channels.telegram.botToken` یا `channels.telegram.tokenFile` (فقط فایل معمولی؛ symlinkها رد می‌شوند)، با `TELEGRAM_BOT_TOKEN` به‌عنوان fallback برای حساب پیش‌فرض. +- `apiRoot` فقط ریشه Telegram Bot API است. از `https://api.telegram.org` یا ریشه self-hosted/proxy خود استفاده کنید، نه `https://api.telegram.org/bot`؛ `openclaw doctor --fix` پسوند تصادفی انتهایی `/bot` را حذف می‌کند. +- گزینه اختیاری `channels.telegram.defaultAccount` انتخاب حساب پیش‌فرض را وقتی با یک شناسه حساب پیکربندی‌شده مطابقت داشته باشد override می‌کند. +- در راه‌اندازی‌های چندحسابی (۲ شناسه حساب یا بیشتر)، یک پیش‌فرض صریح تنظیم کنید (`channels.telegram.defaultAccount` یا `channels.telegram.accounts.default`) تا از مسیریابی fallback جلوگیری شود؛ `openclaw doctor` وقتی این مقدار وجود نداشته یا نامعتبر باشد هشدار می‌دهد. +- `configWrites: false` نوشتن پیکربندی آغازشده از Telegram را مسدود می‌کند (مهاجرت‌های شناسه supergroup، `/config set|unset`). +- ورودی‌های سطح بالای `bindings[]` با `type: "acp"`، اتصال‌های ماندگار ACP را برای موضوع‌های forum پیکربندی می‌کنند (از `chatId:topic:topicId` استاندارد در `match.peer.id` استفاده کنید). معنای فیلدها در [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings) مشترک است. +- پیش‌نمایش‌های stream در Telegram از `sendMessage` + `editMessageText` استفاده می‌کنند (در چت‌های مستقیم و گروهی کار می‌کند). +- سیاست retry: ببینید [سیاست retry](/fa/concepts/retry). ### Discord @@ -329,36 +327,36 @@ WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌ش ``` - Token: `channels.discord.token`، با `DISCORD_BOT_TOKEN` به‌عنوان جایگزین برای حساب پیش‌فرض. -- فراخوانی‌های خروجی مستقیم که یک Discord `token` صریح ارائه می‌کنند، از همان توکن برای فراخوانی استفاده می‌کنند؛ تنظیمات تلاش مجدد/سیاست حساب همچنان از حساب انتخاب‌شده در تصویر لحظه‌ای runtime فعال می‌آید. -- `channels.discord.defaultAccount` اختیاری، وقتی با شناسهٔ یک حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- برای اهداف تحویل از `user:` (DM) یا `channel:` (کانال guild) استفاده کنید؛ شناسه‌های عددی بدون پیشوند رد می‌شوند. -- اسلاگ‌های guild با حروف کوچک هستند و فاصله‌ها با `-` جایگزین می‌شوند؛ کلیدهای کانال از نام اسلاگ‌شده استفاده می‌کنند (بدون `#`). شناسه‌های guild را ترجیح دهید. -- پیام‌های نوشته‌شده توسط بات به‌صورت پیش‌فرض نادیده گرفته می‌شوند. `allowBots: true` آن‌ها را فعال می‌کند؛ از `allowBots: "mentions"` استفاده کنید تا فقط پیام‌های باتی پذیرفته شوند که بات را mention کرده‌اند (پیام‌های خود بات همچنان فیلتر می‌شوند). -- `channels.discord.guilds..ignoreOtherMentions` (و بازنویسی‌های کانال) پیام‌هایی را حذف می‌کند که کاربر یا نقش دیگری را mention می‌کنند اما بات را نه (به‌جز @everyone/@here). -- `maxLinesPerMessage` (پیش‌فرض 17) پیام‌های بلند را حتی وقتی کمتر از 2000 نویسه باشند تقسیم می‌کند. +- تماس‌های خروجی مستقیم که یک Discord `token` صریح ارائه می‌کنند از همان توکن برای تماس استفاده می‌کنند؛ تنظیمات تلاش مجدد/سیاست حساب همچنان از حساب انتخاب‌شده در اسنپ‌شات runtime فعال می‌آیند. +- مقدار اختیاری `channels.discord.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- برای مقصدهای تحویل از `user:` (DM) یا `channel:` (کانال guild) استفاده کنید؛ شناسه‌های عددی بدون پیشوند رد می‌شوند. +- اسلاگ‌های Guild با حروف کوچک هستند و فاصله‌ها با `-` جایگزین می‌شوند؛ کلیدهای کانال از نام اسلاگ‌شده استفاده می‌کنند (بدون `#`). شناسه‌های guild را ترجیح دهید. +- پیام‌های نوشته‌شده توسط bot به‌صورت پیش‌فرض نادیده گرفته می‌شوند. `allowBots: true` آن‌ها را فعال می‌کند؛ از `allowBots: "mentions"` استفاده کنید تا فقط پیام‌های bot پذیرفته شوند که bot را mention می‌کنند (پیام‌های خود همچنان فیلتر می‌شوند). +- `channels.discord.guilds..ignoreOtherMentions` (و بازنویسی‌های کانال) پیام‌هایی را حذف می‌کند که کاربر یا نقش دیگری را mention می‌کنند اما bot را نه (به‌جز @everyone/@here). +- `maxLinesPerMessage` (پیش‌فرض 17) پیام‌های بلند را حتی وقتی زیر 2000 کاراکتر باشند تقسیم می‌کند. - `channels.discord.threadBindings` مسیریابی وابسته به thread در Discord را کنترل می‌کند: - `enabled`: بازنویسی Discord برای ویژگی‌های نشست وابسته به thread (`/focus`، `/unfocus`، `/agents`، `/session idle`، `/session max-age`، و تحویل/مسیریابی وابسته) - - `idleHours`: بازنویسی Discord برای auto-unfocus هنگام بی‌فعالیتی، بر حسب ساعت (`0` غیرفعال می‌کند) + - `idleHours`: بازنویسی Discord برای auto-unfocus در اثر عدم فعالیت، بر حسب ساعت (`0` غیرفعال می‌کند) - `maxAgeHours`: بازنویسی Discord برای حداکثر عمر سخت، بر حسب ساعت (`0` غیرفعال می‌کند) - - `spawnSubagentSessions`: سوییچ opt-in برای ایجاد/اتصال خودکار thread در `sessions_spawn({ thread: true })` -- ورودی‌های سطح‌بالای `bindings[]` با `type: "acp"` اتصال‌های پایدار ACP را برای کانال‌ها و threadها پیکربندی می‌کنند (از شناسهٔ کانال/thread در `match.peer.id` استفاده کنید). معناشناسی فیلدها در [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings) مشترک است. -- `channels.discord.ui.components.accentColor` رنگ تأکیدی را برای کانتینرهای Discord components v2 تنظیم می‌کند. + - `spawnSubagentSessions`: سوییچ opt-in برای ساخت/اتصال خودکار thread در `sessions_spawn({ thread: true })` +- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` اتصال‌های پایدار ACP را برای کانال‌ها و threadها پیکربندی می‌کنند (از شناسه کانال/thread در `match.peer.id` استفاده کنید). معناشناسی فیلدها در [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings) مشترک است. +- `channels.discord.ui.components.accentColor` رنگ تأکیدی را برای کانتینرهای مؤلفه‌های Discord v2 تنظیم می‌کند. - `channels.discord.voice` گفت‌وگوهای کانال صوتی Discord و بازنویسی‌های اختیاری auto-join + LLM + TTS را فعال می‌کند. - `channels.discord.voice.model` به‌صورت اختیاری مدل LLM استفاده‌شده برای پاسخ‌های کانال صوتی Discord را بازنویسی می‌کند. -- `channels.discord.voice.daveEncryption` و `channels.discord.voice.decryptionFailureTolerance` به گزینه‌های DAVE در `@discordjs/voice` پاس داده می‌شوند (به‌ترتیب `true` و `24` به‌صورت پیش‌فرض). -- OpenClaw افزون بر این، پس از خطاهای رمزگشایی تکرارشونده، با ترک/پیوستن دوباره به یک نشست صوتی برای بازیابی دریافت صوت تلاش می‌کند. -- `channels.discord.streaming` کلید canonical حالت stream است. مقادیر legacy `streamMode` و boolean `streaming` به‌صورت خودکار migrate می‌شوند. -- `channels.discord.autoPresence` دسترس‌پذیری runtime را به presence بات نگاشت می‌کند (healthy => online، degraded => idle، exhausted => dnd) و بازنویسی‌های اختیاری متن وضعیت را مجاز می‌کند. -- `channels.discord.dangerouslyAllowNameMatching` تطبیق تغییرپذیر نام/برچسب را دوباره فعال می‌کند (حالت سازگاری break-glass). +- `channels.discord.voice.daveEncryption` و `channels.discord.voice.decryptionFailureTolerance` به گزینه‌های DAVE در `@discordjs/voice` پاس داده می‌شوند (`true` و `24` به‌صورت پیش‌فرض). +- OpenClaw علاوه بر این، پس از شکست‌های تکراری رمزگشایی، با ترک/پیوستن دوباره به یک نشست صوتی تلاش می‌کند دریافت صوتی را بازیابی کند. +- `channels.discord.streaming` کلید متعارف حالت stream است. مقادیر قدیمی `streamMode` و `streaming` بولی به‌صورت خودکار مهاجرت داده می‌شوند. +- `channels.discord.autoPresence` در دسترس بودن runtime را به حضور bot نگاشت می‌کند (healthy => online، degraded => idle، exhausted => dnd) و بازنویسی اختیاری متن وضعیت را مجاز می‌کند. +- `channels.discord.dangerouslyAllowNameMatching` تطبیق نام/tag قابل‌تغییر را دوباره فعال می‌کند (حالت سازگاری break-glass). - `channels.discord.execApprovals`: تحویل تأیید exec بومی Discord و مجوزدهی تأییدکننده. - - `enabled`: `true`، `false`، یا `"auto"` (پیش‌فرض). در حالت خودکار، تأییدهای exec وقتی فعال می‌شوند که تأییدکننده‌ها از `approvers` یا `commands.ownerAllowFrom` قابل resolve باشند. - - `approvers`: شناسه‌های کاربر Discord که مجازند درخواست‌های exec را تأیید کنند. اگر حذف شود به `commands.ownerAllowFrom` برمی‌گردد. - - `agentFilter`: allowlist اختیاری شناسهٔ عامل. برای ارسال تأییدها برای همهٔ عامل‌ها حذف کنید. + - `enabled`: `true`، `false`، یا `"auto"` (پیش‌فرض). در حالت auto، تأییدهای exec وقتی فعال می‌شوند که تأییدکنندگان از `approvers` یا `commands.ownerAllowFrom` قابل resolve باشند. + - `approvers`: شناسه‌های کاربر Discord مجاز به تأیید درخواست‌های exec. در صورت حذف، به `commands.ownerAllowFrom` fallback می‌کند. + - `agentFilter`: allowlist اختیاری شناسه agent. برای ارسال تأییدها برای همه agentها حذف کنید. - `sessionFilter`: الگوهای اختیاری کلید نشست (زیررشته یا regex). - - `target`: محل ارسال promptهای تأیید. `"dm"` (پیش‌فرض) به DMهای تأییدکننده می‌فرستد، `"channel"` به کانال مبدأ می‌فرستد، `"both"` به هر دو می‌فرستد. وقتی target شامل `"channel"` باشد، دکمه‌ها فقط توسط تأییدکننده‌های resolve‌شده قابل استفاده‌اند. + - `target`: محل ارسال promptهای تأیید. `"dm"` (پیش‌فرض) به DMهای تأییدکننده می‌فرستد، `"channel"` به کانال مبدأ می‌فرستد، `"both"` به هر دو می‌فرستد. وقتی target شامل `"channel"` باشد، دکمه‌ها فقط توسط تأییدکنندگان resolve‌شده قابل استفاده هستند. - `cleanupAfterResolve`: وقتی `true` باشد، DMهای تأیید را پس از تأیید، رد، یا timeout حذف می‌کند. -**حالت‌های اعلان واکنش:** `off` (هیچ‌کدام)، `own` (پیام‌های بات، پیش‌فرض)، `all` (همهٔ پیام‌ها)، `allowlist` (از `guilds..users` روی همهٔ پیام‌ها). +**حالت‌های اعلان واکنش:** `off` (هیچ‌کدام)، `own` (پیام‌های bot، پیش‌فرض)، `all` (همه پیام‌ها)، `allowlist` (از `guilds..users` روی همه پیام‌ها). ### Google Chat @@ -392,8 +390,8 @@ WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌ش - JSON حساب سرویس: درون‌خطی (`serviceAccount`) یا مبتنی بر فایل (`serviceAccountFile`). - SecretRef حساب سرویس نیز پشتیبانی می‌شود (`serviceAccountRef`). - جایگزین‌های env: `GOOGLE_CHAT_SERVICE_ACCOUNT` یا `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- برای اهداف تحویل از `spaces/` یا `users/` استفاده کنید. -- `channels.googlechat.dangerouslyAllowNameMatching` تطبیق تغییرپذیر principal ایمیل را دوباره فعال می‌کند (حالت سازگاری break-glass). +- برای مقصدهای تحویل از `spaces/` یا `users/` استفاده کنید. +- `channels.googlechat.dangerouslyAllowNameMatching` تطبیق principal ایمیل قابل‌تغییر را دوباره فعال می‌کند (حالت سازگاری break-glass). ### Slack @@ -465,43 +463,43 @@ WhatsApp از طریق کانال وب Gateway (Baileys Web) اجرا می‌ش } ``` -- **حالت Socket** هم به `botToken` و هم به `appToken` نیاز دارد (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` برای جایگزین env حساب پیش‌فرض). -- **حالت HTTP** به `botToken` به‌علاوهٔ `signingSecret` نیاز دارد (در ریشه یا برای هر حساب). -- `socketMode` تنظیمات انتقال Socket Mode در Slack SDK را به API گیرندهٔ عمومی Bolt پاس می‌دهد. فقط هنگام بررسی timeoutهای ping/pong یا رفتار websocket کهنه از آن استفاده کنید. +- **حالت Socket** هم `botToken` و هم `appToken` را نیاز دارد (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` برای env fallback حساب پیش‌فرض). +- **حالت HTTP** به `botToken` به‌همراه `signingSecret` نیاز دارد (در root یا به‌ازای هر حساب). +- `socketMode` تنظیمات انتقال Slack SDK Socket Mode را به API عمومی گیرنده Bolt پاس می‌دهد. فقط هنگام بررسی timeout پینگ/پونگ یا رفتار websocket قدیمی از آن استفاده کنید. - `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های plaintext - یا اشیای SecretRef را می‌پذیرند. -- تصویرهای لحظه‌ای حساب Slack فیلدهای source/status مخصوص هر credential را آشکار می‌کنند، مانند - `botTokenSource`، `botTokenStatus`، `appTokenStatus`، و، در حالت HTTP، - `signingSecretStatus`. `configured_unavailable` یعنی حساب از طریق SecretRef - پیکربندی شده است اما مسیر فرمان/runtime فعلی نتوانسته مقدار secret را - resolve کند. -- `configWrites: false` نوشتن پیکربندی آغازشده از Slack را مسدود می‌کند. -- `channels.slack.defaultAccount` اختیاری، وقتی با شناسهٔ یک حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- `channels.slack.streaming.mode` کلید canonical حالت stream در Slack است. `channels.slack.streaming.nativeTransport` انتقال streaming بومی Slack را کنترل می‌کند. مقادیر legacy `streamMode`، boolean `streaming`، و `nativeStreaming` به‌صورت خودکار migrate می‌شوند. -- برای اهداف تحویل از `user:` (DM) یا `channel:` استفاده کنید. + یا آبجکت‌های SecretRef را می‌پذیرند. +- اسنپ‌شات‌های حساب Slack فیلدهای source/status به‌ازای هر credential را آشکار می‌کنند، مانند + `botTokenSource`، `botTokenStatus`، `appTokenStatus` و، در حالت HTTP، + `signingSecretStatus`. `configured_unavailable` یعنی حساب از طریق + SecretRef پیکربندی شده اما مسیر فرمان/runtime فعلی نتوانسته + مقدار secret را resolve کند. +- `configWrites: false` نوشتن پیکربندی آغازشده توسط Slack را مسدود می‌کند. +- مقدار اختیاری `channels.slack.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- `channels.slack.streaming.mode` کلید متعارف حالت stream در Slack است. `channels.slack.streaming.nativeTransport` انتقال streaming بومی Slack را کنترل می‌کند. مقادیر قدیمی `streamMode`، `streaming` بولی، و `nativeStreaming` به‌صورت خودکار مهاجرت داده می‌شوند. +- برای مقصدهای تحویل از `user:` (DM) یا `channel:` استفاده کنید. **حالت‌های اعلان واکنش:** `off`، `own` (پیش‌فرض)، `all`، `allowlist` (از `reactionAllowlist`). -**ایزوله‌سازی نشست thread:** `thread.historyScope` برای هر thread جداگانه است (پیش‌فرض) یا در سراسر کانال مشترک است. `thread.inheritParent` رونوشت کانال والد را به threadهای جدید کپی می‌کند. +**ایزولاسیون نشست thread:** `thread.historyScope` به‌ازای هر thread (پیش‌فرض) است یا در سراسر کانال مشترک می‌شود. `thread.inheritParent` رونوشت کانال والد را به threadهای جدید کپی می‌کند. -- streaming بومی Slack به‌همراه وضعیت thread به سبک دستیار Slack، یعنی "is typing..."، به یک هدف thread پاسخ نیاز دارد. DMهای سطح‌بالا به‌صورت پیش‌فرض خارج از thread می‌مانند، بنابراین به‌جای پیش‌نمایش سبک thread از `typingReaction` یا تحویل عادی استفاده می‌کنند. -- `typingReaction` هنگام اجرای پاسخ، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس در پایان آن را حذف می‌کند. از shortcode ایموجی Slack مانند `"hourglass_flowing_sand"` استفاده کنید. -- `channels.slack.execApprovals`: تحویل تأیید exec بومی Slack و مجوزدهی تأییدکننده. همان schema Discord: `enabled` (`true`/`false`/`"auto"`)، `approvers` (شناسه‌های کاربر Slack)، `agentFilter`، `sessionFilter`، و `target` (`"dm"`، `"channel"`، یا `"both"`). +- streaming بومی Slack به‌همراه وضعیت thread به سبک دستیار Slack با متن "is typing..." به یک مقصد thread پاسخ نیاز دارد. DMهای سطح بالا به‌صورت پیش‌فرض خارج از thread می‌مانند، بنابراین به‌جای پیش‌نمایش سبک thread از `typingReaction` یا تحویل عادی استفاده می‌کنند. +- `typingReaction` هنگام اجرای پاسخ، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس پس از تکمیل آن را حذف می‌کند. از shortcode ایموجی Slack مانند `"hourglass_flowing_sand"` استفاده کنید. +- `channels.slack.execApprovals`: تحویل تأیید exec بومی Slack و مجوزدهی تأییدکننده. همان schema مثل Discord: `enabled` (`true`/`false`/`"auto"`)، `approvers` (شناسه‌های کاربر Slack)، `agentFilter`، `sessionFilter`، و `target` (`"dm"`، `"channel"`، یا `"both"`). | گروه اقدام | پیش‌فرض | یادداشت‌ها | | ------------ | ------- | ---------------------- | | reactions | فعال | واکنش + فهرست واکنش‌ها | | messages | فعال | خواندن/ارسال/ویرایش/حذف | -| pins | فعال | سنجاق/برداشتن سنجاق/فهرست | +| pins | فعال | سنجاق کردن/برداشتن سنجاق/فهرست | | memberInfo | فعال | اطلاعات عضو | | emojiList | فعال | فهرست ایموجی سفارشی | ### Mattermost -Mattermost در نسخه‌های فعلی OpenClaw به‌صورت Plugin همراه عرضه می‌شود. buildهای قدیمی‌تر یا -سفارشی می‌توانند یک بستهٔ npm فعلی را با -`openclaw plugins install @openclaw/mattermost` نصب کنند؛ اگر npm بستهٔ متعلق به -OpenClaw را deprecated گزارش کند، تا زمانی که بستهٔ npm جدیدتری منتشر شود از Plugin همراه یا یک checkout محلی +Mattermost در نسخه‌های فعلی OpenClaw به‌عنوان یک Plugin همراه عرضه می‌شود. buildهای قدیمی‌تر یا +سفارشی می‌توانند یک بسته npm فعلی را با +`openclaw plugins install @openclaw/mattermost` نصب کنند؛ اگر npm گزارش دهد که +بسته متعلق به OpenClaw منسوخ شده است، تا زمان انتشار بسته npm جدیدتر، از Plugin همراه یا checkout محلی استفاده کنید. ```json5 @@ -532,23 +530,24 @@ OpenClaw را deprecated گزارش کند، تا زمانی که بستهٔ npm } ``` -حالت‌های چت: `oncall` (پاسخ هنگام @-mention، پیش‌فرض)، `onmessage` (هر پیام)، `onchar` (پیام‌هایی که با پیشوند trigger شروع می‌شوند). +حالت‌های چت: `oncall` (پاسخ به @-mention، پیش‌فرض)، `onmessage` (هر پیام)، `onchar` (پیام‌هایی که با پیشوند trigger شروع می‌شوند). وقتی فرمان‌های بومی Mattermost فعال باشند: - `commands.callbackPath` باید یک مسیر باشد (برای مثال `/api/channels/mattermost/command`)، نه یک URL کامل. -- `commands.callbackUrl` باید به endpoint Gateway در OpenClaw resolve شود و از سرور Mattermost قابل دسترسی باشد. -- callbackهای slash بومی با توکن‌های مخصوص هر فرمان که Mattermost هنگام ثبت slash command برمی‌گرداند احراز هویت می‌شوند. اگر ثبت ناموفق باشد یا هیچ +- `commands.callbackUrl` باید به endpoint مربوط به OpenClaw gateway resolve شود و از سرور Mattermost قابل دسترسی باشد. +- callbackهای slash بومی با توکن‌های به‌ازای هر فرمان که + Mattermost هنگام ثبت slash command برمی‌گرداند احراز هویت می‌شوند. اگر ثبت شکست بخورد یا هیچ فرمانی فعال نشود، OpenClaw callbackها را با `Unauthorized: invalid command token.` رد می‌کند. -- برای میزبان‌های callback خصوصی/tailnet/داخلی، Mattermost ممکن است نیاز داشته باشد - `ServiceSettings.AllowedUntrustedInternalConnections` شامل میزبان/دامنهٔ callback باشد. - از مقدارهای میزبان/دامنه استفاده کنید، نه URLهای کامل. -- `channels.mattermost.configWrites`: نوشتن پیکربندی آغازشده از Mattermost را مجاز یا رد کنید. -- `channels.mattermost.requireMention`: پیش از پاسخ در کانال‌ها `@mention` را الزامی کنید. -- `channels.mattermost.groups..requireMention`: بازنویسی دروازه‌گذاری mention مخصوص هر کانال (`"*"` برای پیش‌فرض). -- `channels.mattermost.defaultAccount` اختیاری، وقتی با شناسهٔ یک حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- برای میزبان‌های callback خصوصی/tailnet/داخلی، Mattermost ممکن است نیاز داشته باشد که + `ServiceSettings.AllowedUntrustedInternalConnections` شامل میزبان/دامنه callback باشد. + از مقادیر میزبان/دامنه استفاده کنید، نه URLهای کامل. +- `channels.mattermost.configWrites`: نوشتن پیکربندی آغازشده توسط Mattermost را مجاز یا رد می‌کند. +- `channels.mattermost.requireMention`: پیش از پاسخ دادن در کانال‌ها، `@mention` را الزامی می‌کند. +- `channels.mattermost.groups..requireMention`: بازنویسی mention-gating به‌ازای هر کانال (`"*"` برای پیش‌فرض). +- مقدار اختیاری `channels.mattermost.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. ### Signal @@ -572,12 +571,12 @@ OpenClaw را deprecated گزارش کند، تا زمانی که بستهٔ npm **حالت‌های اعلان واکنش:** `off`، `own` (پیش‌فرض)، `all`، `allowlist` (از `reactionAllowlist`). - `channels.signal.account`: راه‌اندازی کانال را به یک هویت حساب Signal مشخص پین می‌کند. -- `channels.signal.configWrites`: نوشتن پیکربندی آغازشده از Signal را مجاز یا رد می‌کند. -- گزینه اختیاری `channels.signal.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- `channels.signal.configWrites`: نوشتن‌های پیکربندی آغازشده از Signal را مجاز یا رد می‌کند. +- گزینهٔ اختیاری `channels.signal.defaultAccount` وقتی با یک شناسهٔ حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. ### BlueBubbles -BlueBubbles مسیر پیشنهادی iMessage است (با پشتوانه Plugin، پیکربندی‌شده زیر `channels.bluebubbles`). +BlueBubbles مسیر توصیه‌شده برای iMessage است (با پشتوانهٔ Plugin، پیکربندی‌شده زیر `channels.bluebubbles`). ```json5 { @@ -592,14 +591,14 @@ BlueBubbles مسیر پیشنهادی iMessage است (با پشتوانه Plugi } ``` -- مسیرهای کلیدی اصلی که اینجا پوشش داده شده‌اند: `channels.bluebubbles`، `channels.bluebubbles.dmPolicy`. -- گزینه اختیاری `channels.bluebubbles.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` می‌توانند مکالمه‌های BlueBubbles را به نشست‌های پایدار ACP متصل کنند. در `match.peer.id` از یک handle یا رشته هدف BlueBubbles (`chat_id:*`، `chat_guid:*`، `chat_identifier:*`) استفاده کنید. معناشناسی فیلدهای مشترک: [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings). +- مسیرهای کلیدی هسته که اینجا پوشش داده شده‌اند: `channels.bluebubbles`، `channels.bluebubbles.dmPolicy`. +- گزینهٔ اختیاری `channels.bluebubbles.defaultAccount` وقتی با یک شناسهٔ حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` می‌توانند گفت‌وگوهای BlueBubbles را به نشست‌های پایدار ACP متصل کنند. در `match.peer.id` از یک هندل BlueBubbles یا رشتهٔ هدف (`chat_id:*`، `chat_guid:*`، `chat_identifier:*`) استفاده کنید. معناشناسی فیلدهای مشترک: [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings). - پیکربندی کامل کانال BlueBubbles در [BlueBubbles](/fa/channels/bluebubbles) مستند شده است. ### iMessage -OpenClaw فرایند `imsg rpc` را اجرا می‌کند (JSON-RPC روی stdio). به daemon یا پورت نیاز نیست. +OpenClaw دستور `imsg rpc` را اجرا می‌کند (JSON-RPC روی stdio). به daemon یا پورت نیاز نیست. ```json5 { @@ -623,17 +622,17 @@ OpenClaw فرایند `imsg rpc` را اجرا می‌کند (JSON-RPC روی st } ``` -- گزینه اختیاری `channels.imessage.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- گزینهٔ اختیاری `channels.imessage.defaultAccount` وقتی با یک شناسهٔ حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- به Full Disk Access برای پایگاه داده Messages نیاز دارد. -- هدف‌های `chat_id:` را ترجیح دهید. برای فهرست کردن چت‌ها از `imsg chats --limit 20` استفاده کنید. -- `cliPath` می‌تواند به یک wrapper برای SSH اشاره کند؛ برای دریافت پیوست‌ها با SCP، `remoteHost` (`host` یا `user@host`) را تنظیم کنید. +- به Full Disk Access برای پایگاه‌دادهٔ Messages نیاز دارد. +- اهداف `chat_id:` را ترجیح دهید. برای فهرست کردن چت‌ها از `imsg chats --limit 20` استفاده کنید. +- `cliPath` می‌تواند به یک پوشش‌دهندهٔ SSH اشاره کند؛ برای دریافت پیوست‌ها با SCP، `remoteHost` (`host` یا `user@host`) را تنظیم کنید. - `attachmentRoots` و `remoteAttachmentRoots` مسیرهای پیوست ورودی را محدود می‌کنند (پیش‌فرض: `/Users/*/Library/Messages/Attachments`). -- SCP از بررسی سخت‌گیرانه کلید میزبان استفاده می‌کند، بنابراین مطمئن شوید کلید میزبان relay از قبل در `~/.ssh/known_hosts` وجود دارد. -- `channels.imessage.configWrites`: نوشتن پیکربندی آغازشده از iMessage را مجاز یا رد می‌کند. -- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` می‌توانند مکالمه‌های iMessage را به نشست‌های پایدار ACP متصل کنند. در `match.peer.id` از یک handle نرمال‌سازی‌شده یا هدف چت صریح (`chat_id:*`، `chat_guid:*`، `chat_identifier:*`) استفاده کنید. معناشناسی فیلدهای مشترک: [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings). +- SCP از بررسی سخت‌گیرانهٔ کلید میزبان استفاده می‌کند، پس مطمئن شوید کلید میزبان relay از قبل در `~/.ssh/known_hosts` وجود دارد. +- `channels.imessage.configWrites`: نوشتن‌های پیکربندی آغازشده از iMessage را مجاز یا رد می‌کند. +- ورودی‌های سطح بالای `bindings[]` با `type: "acp"` می‌توانند گفت‌وگوهای iMessage را به نشست‌های پایدار ACP متصل کنند. در `match.peer.id` از یک هندل نرمال‌سازی‌شده یا هدف چت صریح (`chat_id:*`، `chat_guid:*`، `chat_identifier:*`) استفاده کنید. معناشناسی فیلدهای مشترک: [عامل‌های ACP](/fa/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -644,7 +643,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix با پشتوانه Plugin است و زیر `channels.matrix` پیکربندی می‌شود. +Matrix با پشتوانهٔ Plugin است و زیر `channels.matrix` پیکربندی می‌شود. ```json5 { @@ -674,25 +673,25 @@ Matrix با پشتوانه Plugin است و زیر `channels.matrix` پیکرب } ``` -- احراز هویت با token از `accessToken` استفاده می‌کند؛ احراز هویت با گذرواژه از `userId` + `password` استفاده می‌کند. -- `channels.matrix.proxy` ترافیک HTTP مربوط به Matrix را از طریق یک proxy صریح HTTP(S) هدایت می‌کند. حساب‌های نام‌گذاری‌شده می‌توانند آن را با `channels.matrix.accounts..proxy` بازنویسی کنند. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` homeserverهای خصوصی/داخلی را مجاز می‌کند. `proxy` و این opt-in شبکه کنترل‌های مستقلی هستند. -- `channels.matrix.defaultAccount` حساب ترجیحی را در تنظیمات چندحسابی انتخاب می‌کند. -- مقدار پیش‌فرض `channels.matrix.autoJoin` برابر `off` است، بنابراین اتاق‌های دعوت‌شده و دعوت‌های تازه به سبک DM تا وقتی `autoJoin: "allowlist"` را همراه با `autoJoinAllowlist` یا `autoJoin: "always"` تنظیم نکنید نادیده گرفته می‌شوند. +- احراز هویت با توکن از `accessToken` استفاده می‌کند؛ احراز هویت با گذرواژه از `userId` + `password` استفاده می‌کند. +- `channels.matrix.proxy` ترافیک HTTP مربوط به Matrix را از طریق یک پراکسی HTTP(S) صریح عبور می‌دهد. حساب‌های نام‌گذاری‌شده می‌توانند آن را با `channels.matrix.accounts..proxy` بازنویسی کنند. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` homeserverهای خصوصی/داخلی را مجاز می‌کند. `proxy` و این انتخاب صریح شبکه کنترل‌های مستقلی هستند. +- `channels.matrix.defaultAccount` حساب ترجیحی را در راه‌اندازی‌های چندحسابی انتخاب می‌کند. +- مقدار پیش‌فرض `channels.matrix.autoJoin` برابر `off` است، بنابراین اتاق‌های دعوت‌شده و دعوت‌های تازهٔ شبیه DM نادیده گرفته می‌شوند تا زمانی که `autoJoin: "allowlist"` را همراه با `autoJoinAllowlist` یا `autoJoin: "always"` تنظیم کنید. - `channels.matrix.execApprovals`: تحویل تأیید اجرای بومی Matrix و مجوزدهی تأییدکننده. - - `enabled`: `true`، `false`، یا `"auto"` (پیش‌فرض). در حالت خودکار، وقتی تأییدکننده‌ها از `approvers` یا `commands.ownerAllowFrom` قابل resolve باشند، تأییدهای اجرا فعال می‌شوند. - - `approvers`: شناسه‌های کاربر Matrix (مثلاً `@owner:example.org`) که اجازه تأیید درخواست‌های اجرا را دارند. - - `agentFilter`: allowlist اختیاری شناسه عامل. برای ارسال تأییدها برای همه عامل‌ها حذفش کنید. + - `enabled`: `true`، `false`، یا `"auto"` (پیش‌فرض). در حالت خودکار، تأییدهای اجرا وقتی فعال می‌شوند که تأییدکنندگان از `approvers` یا `commands.ownerAllowFrom` قابل resolve باشند. + - `approvers`: شناسه‌های کاربر Matrix (مثلاً `@owner:example.org`) که مجاز به تأیید درخواست‌های اجرا هستند. + - `agentFilter`: allowlist اختیاری شناسهٔ عامل. برای ارسال تأییدها برای همهٔ عامل‌ها آن را حذف کنید. - `sessionFilter`: الگوهای اختیاری کلید نشست (زیررشته یا regex). - - `target`: محل ارسال promptهای تأیید. `"dm"` (پیش‌فرض)، `"channel"` (اتاق مبدأ)، یا `"both"`. - - بازنویسی‌های به‌ازای حساب: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` کنترل می‌کند DMهای Matrix چگونه در نشست‌ها گروه‌بندی شوند: `per-user` (پیش‌فرض) بر اساس peer مسیریابی‌شده مشترک است، در حالی که `per-room` هر اتاق DM را جدا می‌کند. -- probeهای وضعیت Matrix و lookupهای زنده directory از همان سیاست proxy ترافیک زمان اجرا استفاده می‌کنند. + - `target`: محل ارسال درخواست‌های تأیید. `"dm"` (پیش‌فرض)، `"channel"` (اتاق مبدأ)، یا `"both"`. + - بازنویسی‌های هر حساب: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` کنترل می‌کند DMهای Matrix چگونه در نشست‌ها گروه‌بندی شوند: `per-user` (پیش‌فرض) بر اساس همتای مسیریابی‌شده مشترک می‌شود، در حالی که `per-room` هر اتاق DM را جدا می‌کند. +- probeهای وضعیت Matrix و جست‌وجوهای زندهٔ directory از همان سیاست پراکسی ترافیک runtime استفاده می‌کنند. - پیکربندی کامل Matrix، قواعد هدف‌گیری، و نمونه‌های راه‌اندازی در [Matrix](/fa/channels/matrix) مستند شده‌اند. ### Microsoft Teams -Microsoft Teams با پشتوانه Plugin است و زیر `channels.msteams` پیکربندی می‌شود. +Microsoft Teams با پشتوانهٔ Plugin است و زیر `channels.msteams` پیکربندی می‌شود. ```json5 { @@ -707,12 +706,12 @@ Microsoft Teams با پشتوانه Plugin است و زیر `channels.msteams` } ``` -- مسیرهای کلیدی اصلی که اینجا پوشش داده شده‌اند: `channels.msteams`، `channels.msteams.configWrites`. -- پیکربندی کامل Teams (اعتبارنامه‌ها، Webhook، سیاست DM/گروه، بازنویسی‌های به‌ازای تیم/کانال) در [Microsoft Teams](/fa/channels/msteams) مستند شده است. +- مسیرهای کلیدی هسته که اینجا پوشش داده شده‌اند: `channels.msteams`، `channels.msteams.configWrites`. +- پیکربندی کامل Teams (اعتبارنامه‌ها، Webhook، سیاست DM/گروه، بازنویسی‌های هر تیم/هر کانال) در [Microsoft Teams](/fa/channels/msteams) مستند شده است. ### IRC -IRC با پشتوانه Plugin است و زیر `channels.irc` پیکربندی می‌شود. +IRC با پشتوانهٔ Plugin است و زیر `channels.irc` پیکربندی می‌شود. ```json5 { @@ -733,13 +732,13 @@ IRC با پشتوانه Plugin است و زیر `channels.irc` پیکربندی } ``` -- مسیرهای کلیدی اصلی که اینجا پوشش داده شده‌اند: `channels.irc`، `channels.irc.dmPolicy`، `channels.irc.configWrites`، `channels.irc.nickserv.*`. -- گزینه اختیاری `channels.irc.defaultAccount` وقتی با یک شناسه حساب پیکربندی‌شده مطابق باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. -- پیکربندی کامل کانال IRC (میزبان/پورت/TLS/کانال‌ها/allowlistها/دروازه‌گذاری mention) در [IRC](/fa/channels/irc) مستند شده است. +- مسیرهای کلیدی هسته که اینجا پوشش داده شده‌اند: `channels.irc`، `channels.irc.dmPolicy`، `channels.irc.configWrites`، `channels.irc.nickserv.*`. +- گزینهٔ اختیاری `channels.irc.defaultAccount` وقتی با یک شناسهٔ حساب پیکربندی‌شده مطابقت داشته باشد، انتخاب حساب پیش‌فرض را بازنویسی می‌کند. +- پیکربندی کامل کانال IRC (host/port/TLS/channels/allowlists/mention gating) در [IRC](/fa/channels/irc) مستند شده است. -### چندحسابی (همه کانال‌ها) +### چندحسابی (همهٔ کانال‌ها) -چند حساب را در هر کانال اجرا کنید (هرکدام با `accountId` خودش): +اجرای چند حساب برای هر کانال (هر کدام با `accountId` خودش): ```json5 { @@ -761,29 +760,31 @@ IRC با پشتوانه Plugin است و زیر `channels.irc` پیکربندی ``` - وقتی `accountId` حذف شود، از `default` استفاده می‌شود (CLI + مسیریابی). -- tokenهای env فقط روی حساب **پیش‌فرض** اعمال می‌شوند. -- تنظیمات پایه کانال روی همه حساب‌ها اعمال می‌شوند مگر اینکه به‌ازای حساب بازنویسی شده باشند. -- برای مسیریابی هر حساب به یک عامل متفاوت از `bindings[].match.accountId` استفاده کنید. -- اگر در حالی که هنوز روی پیکربندی کانال سطح بالای تک‌حسابی هستید، یک حساب غیرپیش‌فرض را از طریق `openclaw channels add` (یا onboarding کانال) اضافه کنید، OpenClaw ابتدا مقدارهای تک‌حسابی سطح بالای دارای محدوده حساب را به map حساب کانال منتقل می‌کند تا حساب اصلی همچنان کار کند. بیشتر کانال‌ها آن‌ها را به `channels..accounts.default` منتقل می‌کنند؛ Matrix می‌تواند به‌جای آن یک هدف نام‌گذاری‌شده/پیش‌فرض مطابق موجود را حفظ کند. -- bindingهای موجود فقط-کانال (بدون `accountId`) همچنان با حساب پیش‌فرض مطابق می‌شوند؛ bindingهای دارای محدوده حساب اختیاری می‌مانند. -- `openclaw doctor --fix` نیز شکل‌های ترکیبی را با انتقال مقدارهای تک‌حسابی سطح بالای دارای محدوده حساب به حساب ارتقایافته انتخاب‌شده برای آن کانال تعمیر می‌کند. بیشتر کانال‌ها از `accounts.default` استفاده می‌کنند؛ Matrix می‌تواند به‌جای آن یک هدف نام‌گذاری‌شده/پیش‌فرض مطابق موجود را حفظ کند. +- توکن‌های env فقط روی حساب **پیش‌فرض** اعمال می‌شوند. +- تنظیمات پایهٔ کانال روی همهٔ حساب‌ها اعمال می‌شوند، مگر اینکه برای هر حساب بازنویسی شوند. +- برای مسیریابی هر حساب به یک عامل متفاوت، از `bindings[].match.accountId` استفاده کنید. +- اگر از طریق `openclaw channels add` (یا onboarding کانال) یک حساب غیرپیش‌فرض اضافه کنید، در حالی که هنوز روی پیکربندی کانال سطح بالای تک‌حسابی هستید، OpenClaw ابتدا مقدارهای سطح بالای تک‌حسابی در محدودهٔ حساب را به map حساب کانال ارتقا می‌دهد تا حساب اصلی همچنان کار کند. بیشتر کانال‌ها آن‌ها را به `channels..accounts.default` منتقل می‌کنند؛ Matrix می‌تواند در عوض یک هدف نام‌گذاری‌شده/پیش‌فرض موجود و منطبق را حفظ کند. +- اتصال‌های موجود فقط-کانال (بدون `accountId`) همچنان با حساب پیش‌فرض مطابقت دارند؛ اتصال‌های در محدودهٔ حساب اختیاری می‌مانند. +- `openclaw doctor --fix` نیز شکل‌های ترکیبی را با انتقال مقدارهای سطح بالای تک‌حسابی در محدودهٔ حساب به حساب ارتقاداده‌شدهٔ انتخاب‌شده برای آن کانال تعمیر می‌کند. بیشتر کانال‌ها از `accounts.default` استفاده می‌کنند؛ Matrix می‌تواند در عوض یک هدف نام‌گذاری‌شده/پیش‌فرض موجود و منطبق را حفظ کند. -### کانال‌های Plugin دیگر +### دیگر کانال‌های Plugin بسیاری از کانال‌های Plugin به‌صورت `channels.` پیکربندی می‌شوند و در صفحه‌های اختصاصی کانال خود مستند شده‌اند (برای مثال Feishu، Matrix، LINE، Nostr، Zalo، Nextcloud Talk، Synology Chat، و Twitch). -نمایه کامل کانال‌ها را ببینید: [کانال‌ها](/fa/channels). +نمایهٔ کامل کانال‌ها را ببینید: [کانال‌ها](/fa/channels). -### دروازه‌گذاری mention در گفت‌وگوی گروهی +### mention gating در چت گروهی -پیام‌های گروهی به‌صورت پیش‌فرض **نیازمند mention** هستند (mention فراداده‌ای یا الگوهای regex امن). روی گفت‌وگوهای گروهی WhatsApp، Telegram، Discord، Google Chat، و iMessage اعمال می‌شود. +پیام‌های گروهی به‌طور پیش‌فرض **نیازمند mention** هستند (mention فراداده یا الگوهای regex ایمن). این مورد روی چت‌های گروهی WhatsApp، Telegram، Discord، Google Chat، و iMessage اعمال می‌شود. -پاسخ‌های قابل مشاهده جداگانه کنترل می‌شوند. مقدار پیش‌فرض اتاق‌های گروهی/کانالی `messages.groupChat.visibleReplies: "message_tool"` است: OpenClaw همچنان turn را پردازش می‌کند، اما پاسخ‌های نهایی عادی خصوصی می‌مانند و خروجی قابل مشاهده اتاق به `message(action=send)` نیاز دارد. `"automatic"` را فقط وقتی تنظیم کنید که رفتار legacy را می‌خواهید که در آن پاسخ‌های عادی به اتاق ارسال می‌شوند. برای اعمال همان رفتار پاسخ قابل مشاهده فقط-ابزار به چت‌های مستقیم نیز، `messages.visibleReplies: "message_tool"` را تنظیم کنید. +پاسخ‌های قابل مشاهده جداگانه کنترل می‌شوند. مقدار پیش‌فرض اتاق‌های گروه/کانال `messages.groupChat.visibleReplies: "message_tool"` است: OpenClaw همچنان نوبت را پردازش می‌کند، اما پاسخ‌های نهایی معمولی خصوصی می‌مانند و خروجی قابل مشاهده در اتاق به `message(action=send)` نیاز دارد. `"automatic"` را فقط وقتی تنظیم کنید که رفتار قدیمی را می‌خواهید که در آن پاسخ‌های معمولی به اتاق ارسال می‌شوند. برای اعمال همان رفتار پاسخ قابل مشاهدهٔ فقط-ابزار روی چت‌های مستقیم نیز، `messages.visibleReplies: "message_tool"` را تنظیم کنید. -**انواع mention:** +Gateway پس از ذخیره شدن فایل، پیکربندی `messages` را hot-reload می‌کند. فقط وقتی file watching یا reload پیکربندی در استقرار غیرفعال است، restart کنید. -- **mentionهای فراداده‌ای**: @-mentionهای بومی پلتفرم. در حالت خودچت WhatsApp نادیده گرفته می‌شوند. -- **الگوهای متنی**: الگوهای regex امن در `agents.list[].groupChat.mentionPatterns`. الگوهای نامعتبر و تکرار تودرتوی ناامن نادیده گرفته می‌شوند. -- دروازه‌گذاری mention فقط زمانی اعمال می‌شود که تشخیص ممکن باشد (mentionهای بومی یا دست‌کم یک الگو). +**نوع‌های mention:** + +- **mentionهای فراداده**: @-mentionهای بومی پلتفرم. در حالت self-chat WhatsApp نادیده گرفته می‌شوند. +- **الگوهای متن**: الگوهای regex ایمن در `agents.list[].groupChat.mentionPatterns`. الگوهای نامعتبر و تکرار تودرتوی ناامن نادیده گرفته می‌شوند. +- mention gating فقط وقتی اعمال می‌شود که تشخیص ممکن باشد (mentionهای بومی یا دست‌کم یک الگو). ```json5 { @@ -800,11 +801,11 @@ IRC با پشتوانه Plugin است و زیر `channels.irc` پیکربندی } ``` -`messages.groupChat.historyLimit` پیش‌فرض سراسری را تنظیم می‌کند. کانال‌ها می‌توانند با `channels..historyLimit` (یا به‌ازای حساب) آن را بازنویسی کنند. برای غیرفعال کردن، `0` را تنظیم کنید. +`messages.groupChat.historyLimit` پیش‌فرض سراسری را تنظیم می‌کند. کانال‌ها می‌توانند با `channels..historyLimit` (یا برای هر حساب) آن را بازنویسی کنند. برای غیرفعال کردن، `0` را تنظیم کنید. -`messages.visibleReplies` پیش‌فرض سراسری turnهای منبع است؛ `messages.groupChat.visibleReplies` آن را برای turnهای منبع گروهی/کانالی بازنویسی می‌کند. allowlistهای کانال و دروازه‌گذاری mention همچنان تعیین می‌کنند که آیا یک turn پردازش شود یا نه. +`messages.visibleReplies` پیش‌فرض سراسری نوبت منبع است؛ `messages.groupChat.visibleReplies` آن را برای نوبت‌های منبع گروه/کانال بازنویسی می‌کند. allowlistهای کانال و mention gating همچنان تعیین می‌کنند که آیا یک نوبت پردازش شود یا نه. -#### محدودیت‌های تاریخچه DM +#### محدودیت‌های تاریخچهٔ DM ```json5 { @@ -819,13 +820,13 @@ IRC با پشتوانه Plugin است و زیر `channels.irc` پیکربندی } ``` -Resolution: بازنویسی به‌ازای DM → پیش‌فرض ارائه‌دهنده → بدون محدودیت (همه نگه داشته می‌شوند). +resolve: بازنویسی برای هر DM → پیش‌فرض ارائه‌دهنده → بدون محدودیت (همه نگه داشته می‌شوند). پشتیبانی‌شده: `telegram`، `whatsapp`، `discord`، `slack`، `signal`، `imessage`، `msteams`. -#### حالت خودچت +#### حالت self-chat -برای فعال کردن حالت خودچت، شماره خودتان را در `allowFrom` قرار دهید (mentionهای بومی را نادیده می‌گیرد و فقط به الگوهای متنی پاسخ می‌دهد): +شمارهٔ خودتان را در `allowFrom` قرار دهید تا حالت self-chat فعال شود (mentionهای @ بومی را نادیده می‌گیرد، فقط به الگوهای متن پاسخ می‌دهد): ```json5 { @@ -846,7 +847,7 @@ Resolution: بازنویسی به‌ازای DM → پیش‌فرض ارائه } ``` -### فرمان‌ها (مدیریت فرمان چت) +### Commands (رسیدگی به دستور چت) ```json5 { @@ -873,33 +874,33 @@ Resolution: بازنویسی به‌ازای DM → پیش‌فرض ارائه } ``` - + -- این بلوک سطح‌های فرمان را پیکربندی می‌کند. برای کاتالوگ فعلی فرمان‌های داخلی و همراه، [فرمان‌های Slash](/fa/tools/slash-commands) را ببینید. -- این صفحه یک **مرجع کلیدهای پیکربندی** است، نه کاتالوگ کامل فرمان‌ها. فرمان‌های متعلق به کانال/Plugin مانند QQ Bot `/bot-ping` `/bot-help` `/bot-logs`، LINE `/card`، جفت‌سازی دستگاه `/pair`، حافظه `/dreaming`، کنترل تلفن `/phone`، و Talk `/voice` در صفحه‌های کانال/Plugin خود به‌همراه [فرمان‌های Slash](/fa/tools/slash-commands) مستند شده‌اند. -- فرمان‌های متنی باید پیام‌های **مستقل** با `/` ابتدایی باشند. -- `native: "auto"` فرمان‌های بومی را برای Discord/Telegram روشن می‌کند و Slack را خاموش نگه می‌دارد. -- `nativeSkills: "auto"` فرمان‌های Skills بومی را برای Discord/Telegram روشن می‌کند و Slack را خاموش نگه می‌دارد. -- بازنویسی برای هر کانال: `channels.discord.commands.native` (بولی یا `"auto"`). `false` فرمان‌های ثبت‌شده قبلی را پاک می‌کند. +- این بلوک سطح‌های دستور را پیکربندی می‌کند. برای کاتالوگ فعلی دستورهای داخلی + همراه، [دستورهای Slash](/fa/tools/slash-commands) را ببینید. +- این صفحه یک **مرجع کلیدهای پیکربندی** است، نه کاتالوگ کامل دستورها. دستورهای متعلق به کانال/Plugin مانند QQ Bot `/bot-ping` `/bot-help` `/bot-logs`، LINE `/card`، device-pair `/pair`، حافظه `/dreaming`، کنترل تلفن `/phone`، و Talk `/voice` در صفحه‌های کانال/Plugin خودشان به‌علاوه [دستورهای Slash](/fa/tools/slash-commands) مستند شده‌اند. +- دستورهای متنی باید پیام‌های **مستقل** با `/` در ابتدا باشند. +- `native: "auto"` دستورهای بومی را برای Discord/Telegram روشن می‌کند و Slack را خاموش نگه می‌دارد. +- `nativeSkills: "auto"` دستورهای بومی Skills را برای Discord/Telegram روشن می‌کند و Slack را خاموش نگه می‌دارد. +- بازنویسی برای هر کانال: `channels.discord.commands.native` (بولی یا `"auto"`). مقدار `false` دستورهای ثبت‌شده قبلی را پاک می‌کند. - ثبت Skills بومی را برای هر کانال با `channels..commands.nativeSkills` بازنویسی کنید. -- `channels.telegram.customCommands` ورودی‌های اضافی به منوی ربات Telegram اضافه می‌کند. -- `bash: true`، `! ` را برای پوسته میزبان فعال می‌کند. به `tools.elevated.enabled` و فرستنده در `tools.elevated.allowFrom.` نیاز دارد. -- `config: true`، `/config` را فعال می‌کند (`openclaw.json` را می‌خواند/می‌نویسد). برای کلاینت‌های Gateway `chat.send`، نوشتن‌های پایدار `/config set|unset` همچنین به `operator.admin` نیاز دارند؛ `/config show` فقط‌خواندنی همچنان برای کلاینت‌های عملگر معمولی با دامنه نوشتن در دسترس می‌ماند. -- `mcp: true`، `/mcp` را برای پیکربندی سرور MCP مدیریت‌شده توسط OpenClaw زیر `mcp.servers` فعال می‌کند. -- `plugins: true`، `/plugins` را برای کشف، نصب، و کنترل‌های فعال/غیرفعال‌سازی Plugin فعال می‌کند. +- `channels.telegram.customCommands` ورودی‌های اضافی منوی ربات Telegram را اضافه می‌کند. +- `bash: true` مقدار `! ` را برای پوسته میزبان فعال می‌کند. به `tools.elevated.enabled` و فرستنده در `tools.elevated.allowFrom.` نیاز دارد. +- `config: true` مقدار `/config` را فعال می‌کند (`openclaw.json` را می‌خواند/می‌نویسد). برای کلاینت‌های Gateway `chat.send`، نوشتن‌های پایدار `/config set|unset` همچنین به `operator.admin` نیاز دارند؛ `/config show` فقط‌خواندنی برای کلاینت‌های عملگر معمولی با محدوده نوشتن همچنان در دسترس می‌ماند. +- `mcp: true` مقدار `/mcp` را برای پیکربندی سرور MCP مدیریت‌شده توسط OpenClaw زیر `mcp.servers` فعال می‌کند. +- `plugins: true` مقدار `/plugins` را برای کشف، نصب، و کنترل‌های فعال/غیرفعال کردن Plugin فعال می‌کند. - `channels..configWrites` جهش‌های پیکربندی را برای هر کانال کنترل می‌کند (پیش‌فرض: true). - برای کانال‌های چندحسابی، `channels..accounts..configWrites` همچنین نوشتن‌هایی را کنترل می‌کند که آن حساب را هدف می‌گیرند (برای مثال `/allowlist --config --account ` یا `/config set channels..accounts....`). -- `restart: false`، `/restart` و کنش‌های ابزار راه‌اندازی دوباره Gateway را غیرفعال می‌کند. پیش‌فرض: `true`. -- `ownerAllowFrom` allowlist صریح مالک برای فرمان‌ها/ابزارهای فقط‌مالک است. این مورد از `allowFrom` جداست. -- `ownerDisplay: "hash"` شناسه‌های مالک را در پرامپت سیستم هش می‌کند. برای کنترل هش‌کردن، `ownerDisplaySecret` را تنظیم کنید. -- `allowFrom` برای هر ارائه‌دهنده است. وقتی تنظیم شود، **تنها** منبع مجوزدهی است (allowlistهای کانال/جفت‌سازی و `useAccessGroups` نادیده گرفته می‌شوند). -- `useAccessGroups: false` به فرمان‌ها اجازه می‌دهد وقتی `allowFrom` تنظیم نشده است، سیاست‌های گروه دسترسی را دور بزنند. -- نقشه مستندات فرمان: - - کاتالوگ داخلی و همراه: [فرمان‌های Slash](/fa/tools/slash-commands) - - سطح‌های فرمان ویژه کانال: [کانال‌ها](/fa/channels) - - فرمان‌های QQ Bot: [QQ Bot](/fa/channels/qqbot) - - فرمان‌های جفت‌سازی: [جفت‌سازی](/fa/channels/pairing) - - فرمان کارت LINE: [LINE](/fa/channels/line) +- `restart: false` مقدار `/restart` و کنش‌های ابزار راه‌اندازی مجدد Gateway را غیرفعال می‌کند. پیش‌فرض: `true`. +- `ownerAllowFrom` فهرست مجاز صریح مالک برای دستورها/ابزارهای فقط‌مالک است. این از `allowFrom` جداست. +- `ownerDisplay: "hash"` شناسه‌های مالک را در اعلان سیستم هش می‌کند. برای کنترل هش‌کردن، `ownerDisplaySecret` را تنظیم کنید. +- `allowFrom` برای هر ارائه‌دهنده است. وقتی تنظیم شود، **تنها** منبع مجوزدهی است (فهرست‌های مجاز کانال/جفت‌سازی و `useAccessGroups` نادیده گرفته می‌شوند). +- `useAccessGroups: false` اجازه می‌دهد وقتی `allowFrom` تنظیم نشده است، دستورها سیاست‌های گروه دسترسی را دور بزنند. +- نقشه مستندات دستور: + - کاتالوگ داخلی + همراه: [دستورهای Slash](/fa/tools/slash-commands) + - سطح‌های دستور ویژه کانال: [کانال‌ها](/fa/channels) + - دستورهای QQ Bot: [QQ Bot](/fa/channels/qqbot) + - دستورهای جفت‌سازی: [جفت‌سازی](/fa/channels/pairing) + - دستور کارت LINE: [LINE](/fa/channels/line) - Dreaming حافظه: [Dreaming](/fa/concepts/dreaming) diff --git a/docs/fa/gateway/doctor.md b/docs/fa/gateway/doctor.md index 3d7d43510..f1480f443 100644 --- a/docs/fa/gateway/doctor.md +++ b/docs/fa/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - افزودن یا تغییر مهاجرت‌های doctor + - افزودن یا اصلاح مهاجرت‌های doctor - معرفی تغییرات ناسازگار در پیکربندی sidebarTitle: Doctor -summary: 'فرمان Doctor: بررسی‌های سلامت، مهاجرت‌های پیکربندی، و مراحل ترمیم' +summary: 'دستور Doctor: بررسی‌های سلامت، مهاجرت‌های پیکربندی، و مراحل تعمیر' title: عیب‌یاب x-i18n: - generated_at: "2026-04-30T09:37:35Z" + generated_at: "2026-04-30T16:29:18Z" model: gpt-5.5 provider: openai - source_hash: c27b8e85eb0a577e676f0e6e205262775ff37303453e64fc1bc2adaf8b51147c + source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` ابزار تعمیر + مهاجرت برای OpenClaw است. پیکربندی/وضعیت قدیمی را اصلاح می‌کند، سلامت را بررسی می‌کند، و مراحل تعمیر قابل اجرا ارائه می‌دهد. +`openclaw doctor` ابزار تعمیر + مهاجرت برای OpenClaw است. این ابزار پیکربندی/وضعیت کهنه را اصلاح می‌کند، سلامت را بررسی می‌کند، و گام‌های تعمیر قابل اقدام ارائه می‌دهد. ## شروع سریع @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### حالت‌های بی‌نیاز از رابط تعاملی و خودکارسازی +### حالت‌های بدون سر و خودکارسازی @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - پیش‌فرض‌ها را بدون پرسش بپذیرید (از جمله مراحل تعمیر راه‌اندازی مجدد/سرویس/sandbox در صورت کاربرد). + پذیرش پیش‌فرض‌ها بدون پرسش (از جمله گام‌های تعمیر راه‌اندازی مجدد/سرویس/سندباکس در صورت کاربرد). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - تعمیرهای پیشنهادی را بدون پرسش اعمال کنید (تعمیرها + راه‌اندازی‌های مجدد در موارد امن). + اعمال تعمیرهای توصیه‌شده بدون پرسش (تعمیرها + راه‌اندازی‌های مجدد در موارد امن). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - تعمیرهای تهاجمی را نیز اعمال کنید (پیکربندی‌های سفارشی supervisor را بازنویسی می‌کند). + تعمیرهای تهاجمی را هم اعمال می‌کند (پیکربندی‌های سفارشی سرپرست را بازنویسی می‌کند). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - بدون پرسش اجرا کنید و فقط مهاجرت‌های امن را اعمال کنید (عادی‌سازی پیکربندی + جابه‌جایی‌های وضعیت روی دیسک). اقدام‌های راه‌اندازی مجدد/سرویس/sandbox را که به تأیید انسانی نیاز دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند. + بدون اعلان اجرا می‌شود و فقط مهاجرت‌های امن را اعمال می‌کند (نرمال‌سازی پیکربندی + جابه‌جایی وضعیت روی دیسک). اقدام‌های راه‌اندازی مجدد/سرویس/سندباکس را که نیاز به تأیید انسانی دارند رد می‌کند. مهاجرت‌های وضعیت قدیمی هنگام شناسایی به‌طور خودکار اجرا می‌شوند. @@ -62,113 +62,114 @@ openclaw doctor openclaw doctor --deep ``` - سرویس‌های سیستم را برای نصب‌های اضافی gateway اسکن کنید (launchd/systemd/schtasks). + سرویس‌های سیستم را برای نصب‌های Gateway اضافی اسکن می‌کند (launchd/systemd/schtasks). -اگر می‌خواهید پیش از نوشتن، تغییرات را بازبینی کنید، ابتدا فایل پیکربندی را باز کنید: +اگر می‌خواهید تغییرات را پیش از نوشتن بازبینی کنید، ابتدا فایل پیکربندی را باز کنید: ```bash cat ~/.openclaw/openclaw.json ``` -## کاری که انجام می‌دهد (خلاصه) +## چه کار می‌کند (خلاصه) - به‌روزرسانی اختیاری پیش از اجرا برای نصب‌های git (فقط تعاملی). - - بررسی تازگی پروتکل UI (وقتی شِمای پروتکل جدیدتر است Control UI را دوباره می‌سازد). - - بررسی سلامت + درخواست راه‌اندازی مجدد. - - خلاصه وضعیت Skills (واجد شرایط/گمشده/مسدود) و وضعیت Plugin. + - بررسی تازگی پروتکل UI (وقتی شِمای پروتکل جدیدتر باشد، Control UI را دوباره می‌سازد). + - بررسی سلامت + اعلان راه‌اندازی مجدد. + - خلاصه وضعیت Skills (واجد شرایط/موجود نیست/مسدود) و وضعیت plugin. - - عادی‌سازی پیکربندی برای مقادیر قدیمی. + - نرمال‌سازی پیکربندی برای مقدارهای قدیمی. - مهاجرت پیکربندی Talk از فیلدهای تخت قدیمی `talk.*` به `talk.provider` + `talk.providers.`. - - بررسی‌های مهاجرت مرورگر برای پیکربندی‌های قدیمی Chrome extension و آمادگی Chrome MCP. - - هشدارهای بازنویسی provider در OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). + - بررسی‌های مهاجرت مرورگر برای پیکربندی‌های قدیمی افزونه Chrome و آمادگی Chrome MCP. + - هشدارهای بازنویسی ارائه‌دهنده OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - هشدارهای سایه‌انداختن OAuth در Codex (`models.providers.openai-codex`). - بررسی پیش‌نیازهای OAuth TLS برای پروفایل‌های OpenAI Codex OAuth. - مهاجرت وضعیت قدیمی روی دیسک (sessions/agent dir/WhatsApp auth). - - مهاجرت کلید قدیمی قرارداد manifest برای Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - مهاجرت store قدیمی Cron (`jobId`, `schedule.cron`, فیلدهای سطح‌بالای delivery/payload، payload `provider`، jobهای fallback ساده webhook با `notify: true`). - - مهاجرت runtime-policy قدیمی agent به `agents.defaults.agentRuntime` و `agents.list[].agentRuntime`. - - پاک‌سازی پیکربندی قدیمی Plugin وقتی Pluginها فعال هستند؛ وقتی `plugins.enabled=false` باشد، ارجاع‌های قدیمی Plugin به‌عنوان پیکربندی containment بی‌اثر در نظر گرفته می‌شوند و حفظ می‌شوند. + - مهاجرت کلید قرارداد manifest قدیمی plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - مهاجرت فروشگاه cron قدیمی (`jobId`, `schedule.cron`, فیلدهای سطح بالای delivery/payload، payload `provider`، کارهای fallback ساده `notify: true` webhook). + - مهاجرت سیاست runtime عامل قدیمی به `agents.defaults.agentRuntime` و `agents.list[].agentRuntime`. + - پاک‌سازی پیکربندی کهنه plugin وقتی pluginها فعال هستند؛ وقتی `plugins.enabled=false` باشد، ارجاع‌های کهنه plugin به‌عنوان پیکربندی containment بی‌اثر تلقی می‌شوند و حفظ می‌شوند. - - بررسی فایل قفل session و پاک‌سازی قفل قدیمی. - - تعمیر رونوشت session برای شاخه‌های تکراری بازنویسی prompt که توسط buildهای تحت‌تأثیر 2026.4.24 ایجاد شده‌اند. + - بازرسی فایل قفل نشست و پاک‌سازی قفل‌های کهنه. + - تعمیر رونوشت نشست برای شاخه‌های تکراری بازنویسی اعلان که توسط buildهای آسیب‌دیده 2026.4.24 ایجاد شده‌اند. + - شناسایی tombstone بازیابی-راه‌اندازی مجدد subagent گیرکرده، با پشتیبانی `--fix` برای پاک‌سازی پرچم‌های کهنه بازیابی لغوشده تا startup همچنان فرزند را restart-aborted تلقی نکند. - بررسی‌های یکپارچگی وضعیت و مجوزها (sessions، transcripts، state dir). - - بررسی‌های مجوز فایل پیکربندی (chmod 600) هنگام اجرای محلی. - - سلامت auth مدل: انقضای OAuth را بررسی می‌کند، می‌تواند tokenهای نزدیک به انقضا را تازه‌سازی کند، و وضعیت‌های cooldown/disabled برای auth-profile را گزارش می‌دهد. - - شناسایی پوشه workspace اضافی (`~/openclaw`). + - بررسی مجوزهای فایل پیکربندی (chmod 600) هنگام اجرای محلی. + - سلامت احراز هویت مدل: انقضای OAuth را بررسی می‌کند، می‌تواند tokenهای در آستانه انقضا را تازه‌سازی کند، و وضعیت‌های cooldown/disabled در auth-profile را گزارش می‌دهد. + - شناسایی دایرکتوری workspace اضافی (`~/openclaw`). - - - تعمیر image مربوط به sandbox وقتی sandboxing فعال است. - - مهاجرت سرویس قدیمی و شناسایی gateway اضافی. + + - تعمیر تصویر سندباکس وقتی سندباکس فعال است. + - مهاجرت سرویس قدیمی و شناسایی Gateway اضافی. - مهاجرت وضعیت قدیمی کانال Matrix (در حالت `--fix` / `--repair`). - - بررسی‌های runtime برای Gateway (سرویس نصب شده اما در حال اجرا نیست؛ برچسب launchd cache شده). - - هشدارهای وضعیت کانال (از gateway در حال اجرا بررسی می‌شوند). - - ممیزی پیکربندی supervisor (launchd/systemd/schtasks) همراه با تعمیر اختیاری. - - پاک‌سازی محیط proxy جاسازی‌شده برای سرویس‌های gateway که مقادیر shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` را هنگام نصب یا به‌روزرسانی گرفته‌اند. - - بررسی‌های بهترین‌روش runtime برای Gateway (Node در برابر Bun، مسیرهای version-manager). - - عیب‌یابی تداخل port در Gateway (پیش‌فرض `18789`). + - بررسی‌های runtime مربوط به Gateway (سرویس نصب شده اما اجرا نمی‌شود؛ برچسب launchd کش‌شده). + - هشدارهای وضعیت کانال (از Gateway در حال اجرا probe شده). + - ممیزی پیکربندی سرپرست (launchd/systemd/schtasks) با تعمیر اختیاری. + - پاک‌سازی محیط proxy تعبیه‌شده برای سرویس‌های Gateway که هنگام نصب یا به‌روزرسانی مقدارهای shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` را گرفته‌اند. + - بررسی بهترین‌رویه‌های runtime مربوط به Gateway (Node در برابر Bun، مسیرهای version-manager). + - عیب‌یابی برخورد پورت Gateway (پیش‌فرض `18789`). - + - هشدارهای امنیتی برای سیاست‌های DM باز. - - بررسی‌های auth در Gateway برای حالت token محلی (وقتی هیچ منبع token وجود ندارد تولید token را پیشنهاد می‌کند؛ پیکربندی‌های token SecretRef را بازنویسی نمی‌کند). - - شناسایی مشکل pairing دستگاه (درخواست‌های جفت‌سازی نخستین بار در انتظار، ارتقاهای role/scope در انتظار، drift کش قدیمی token دستگاه محلی، و drift در auth رکورد جفت‌شده). + - بررسی‌های احراز هویت Gateway برای حالت token محلی (وقتی منبع token وجود ندارد، تولید token را پیشنهاد می‌دهد؛ پیکربندی‌های token SecretRef را بازنویسی نمی‌کند). + - شناسایی مشکلات جفت‌سازی دستگاه (درخواست‌های جفت‌سازی نخستین‌بار معلق، ارتقاهای role/scope معلق، drift کش token دستگاه محلی کهنه، و drift احراز هویت رکورد جفت‌شده). - بررسی systemd linger در Linux. - - بررسی اندازه فایل bootstrap در workspace (هشدارهای truncation/نزدیک به حد برای فایل‌های context). + - بررسی اندازه فایل bootstrap در workspace (هشدارهای کوتاه‌شدن/نزدیک‌بودن به حد برای فایل‌های context). - بررسی وضعیت تکمیل shell و نصب/ارتقای خودکار. - - بررسی آمادگی provider برای embedding در جست‌وجوی memory (مدل محلی، کلید API راه‌دور، یا binary مربوط به QMD). - - بررسی‌های نصب از source (ناهماهنگی pnpm workspace، دارایی‌های UI گمشده، binary گمشده tsx). - - پیکربندی به‌روزشده + metadata ویزارد را می‌نویسد. + - بررسی آمادگی ارائه‌دهنده embedding جست‌وجوی حافظه (مدل محلی، کلید API راه‌دور، یا باینری QMD). + - بررسی‌های نصب از source (ناهماهنگی pnpm workspace، دارایی‌های UI موجود نیست، باینری tsx موجود نیست). + - پیکربندی به‌روزشده + فراداده wizard را می‌نویسد. -## backfill و reset در UI مربوط به Dreams +## پس‌پر کردن و بازنشانی UI رویاها -صحنه Dreams در Control UI شامل اقدام‌های **Backfill**، **Reset**، و **Clear Grounded** برای گردش‌کار grounded dreaming است. این اقدام‌ها از روش‌های RPC سبک gateway doctor استفاده می‌کنند، اما بخشی از تعمیر/مهاجرت CLI مربوط به `openclaw doctor` نیستند. +صحنه Dreams در Control UI شامل اقدام‌های **پس‌پر کردن**، **بازنشانی**، و **پاک‌سازی Grounded** برای گردش‌کار dreaming grounded است. این اقدام‌ها از روش‌های RPC به سبک doctor در Gateway استفاده می‌کنند، اما بخشی از تعمیر/مهاجرت CLI مربوط به `openclaw doctor` نیستند. کاری که انجام می‌دهند: -- **Backfill** فایل‌های تاریخی `memory/YYYY-MM-DD.md` را در workspace فعال اسکن می‌کند، گذر grounded REM diary را اجرا می‌کند، و ورودی‌های backfill برگشت‌پذیر را در `DREAMS.md` می‌نویسد. -- **Reset** فقط همان ورودی‌های علامت‌گذاری‌شده backfill diary را از `DREAMS.md` حذف می‌کند. -- **Clear Grounded** فقط ورودی‌های کوتاه‌مدت staged و فقط-grounded را حذف می‌کند که از بازپخش تاریخی آمده‌اند و هنوز recall زنده یا پشتیبانی روزانه جمع نکرده‌اند. +- **پس‌پر کردن** فایل‌های تاریخی `memory/YYYY-MM-DD.md` را در workspace فعال اسکن می‌کند، گذر دفترچه REM grounded را اجرا می‌کند، و ورودی‌های پس‌پر کردن برگشت‌پذیر را در `DREAMS.md` می‌نویسد. +- **بازنشانی** فقط همان ورودی‌های دفترچه پس‌پر کردن علامت‌گذاری‌شده را از `DREAMS.md` حذف می‌کند. +- **پاک‌سازی Grounded** فقط ورودی‌های کوتاه‌مدت staged و فقط grounded را که از بازپخش تاریخی آمده‌اند و هنوز recall زنده یا پشتیبانی روزانه جمع نکرده‌اند حذف می‌کند. -کاری که به‌تنهایی انجام **نمی‌دهند**: +کاری که خودشان انجام **نمی‌دهند**: -- `MEMORY.md` را ویرایش نمی‌کنند -- مهاجرت‌های کامل doctor را اجرا نمی‌کنند -- candidateهای grounded را به‌طور خودکار وارد store زنده promotion کوتاه‌مدت نمی‌کنند، مگر اینکه ابتدا مسیر CLI مربوط به staged را صراحتاً اجرا کنید +- آن‌ها `MEMORY.md` را ویرایش نمی‌کنند +- آن‌ها مهاجرت‌های کامل doctor را اجرا نمی‌کنند +- آن‌ها نامزدهای grounded را به‌طور خودکار در فروشگاه promotion کوتاه‌مدت زنده stage نمی‌کنند، مگر اینکه ابتدا مسیر CLI مربوط به staged را صراحتاً اجرا کنید -اگر می‌خواهید بازپخش تاریخی grounded روی lane عادی deep promotion اثر بگذارد، به‌جای آن از جریان CLI استفاده کنید: +اگر می‌خواهید بازپخش تاریخی grounded روی lane معمول deep promotion اثر بگذارد، به‌جای آن از جریان CLI استفاده کنید: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -این کار candidateهای durable و grounded را در store مربوط به short-term dreaming قرار می‌دهد و در عین حال `DREAMS.md` را به‌عنوان سطح بازبینی نگه می‌دارد. +این کار نامزدهای پایدار grounded را در فروشگاه dreaming کوتاه‌مدت stage می‌کند، در حالی که `DREAMS.md` را به‌عنوان سطح بازبینی نگه می‌دارد. -## رفتار دقیق و منطق +## رفتار تفصیلی و دلیل طراحی - اگر این یک git checkout باشد و doctor به‌صورت تعاملی اجرا شود، پیش از اجرای doctor پیشنهاد به‌روزرسانی (fetch/rebase/build) می‌دهد. + اگر این یک checkout از git باشد و doctor به‌صورت تعاملی اجرا شود، پیش از اجرای doctor پیشنهاد به‌روزرسانی (fetch/rebase/build) می‌دهد. - - اگر پیکربندی شامل شکل‌های قدیمی مقدار باشد (برای مثال `messages.ackReaction` بدون بازنویسی مخصوص کانال)، doctor آن‌ها را به شِمای فعلی عادی‌سازی می‌کند. + + اگر پیکربندی شامل شکل‌های مقدار قدیمی باشد (برای مثال `messages.ackReaction` بدون بازنویسی مخصوص کانال)، doctor آن‌ها را به شِمای فعلی نرمال‌سازی می‌کند. - این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.`. Doctor شکل‌های قدیمی `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` را در map مربوط به provider بازنویسی می‌کند. + این شامل فیلدهای تخت قدیمی Talk هم می‌شود. پیکربندی عمومی فعلی Talk برابر است با `talk.provider` + `talk.providers.`. Doctor شکل‌های قدیمی `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` را به نقشه ارائه‌دهنده بازنویسی می‌کند. @@ -180,7 +181,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - مهاجرتی را که اعمال کرده نشان می‌دهد. - `~/.openclaw/openclaw.json` را با شِمای به‌روزشده بازنویسی می‌کند. - Gateway همچنین هنگام startup، اگر قالب پیکربندی قدیمی را شناسایی کند، مهاجرت‌های doctor را به‌طور خودکار اجرا می‌کند، بنابراین پیکربندی‌های قدیمی بدون مداخله دستی تعمیر می‌شوند. مهاجرت‌های store مربوط به jobهای Cron توسط `openclaw doctor --fix` انجام می‌شوند. + Gateway نیز هنگام startup، وقتی قالب پیکربندی قدیمی را شناسایی کند، مهاجرت‌های doctor را خودکار اجرا می‌کند تا پیکربندی‌های کهنه بدون مداخله دستی تعمیر شوند. مهاجرت‌های فروشگاه کار Cron توسط `openclaw doctor --fix` انجام می‌شوند. مهاجرت‌های فعلی: @@ -189,7 +190,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` - - `routing.bindings` → `bindings` سطح‌بالا + - `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.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -205,280 +206,280 @@ 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` نام‌دار دارند اما مقادیر سطح‌بالای کانالِ تک‌حسابی هنوز باقی مانده است، آن مقادیر scoped به account را به account ارتقایافته‌ای منتقل کنید که برای آن کانال انتخاب شده است (`accounts.default` برای بیشتر کانال‌ها؛ Matrix می‌تواند یک target نام‌دار/default موجود و مطابق را حفظ کند) + - برای کانال‌هایی که `accounts` نام‌دار دارند اما مقدارهای سطح بالای کانالِ تک‌حسابی همچنان باقی مانده‌اند، آن مقدارهای account-scoped را به حساب promote‌شده‌ای منتقل می‌کند که برای آن کانال انتخاب شده است (`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`؛ برای timeoutهای provider/model کند از `models.providers..timeoutSeconds` استفاده کنید + - حذف `agents.defaults.llm`؛ برای timeoutهای کند ارائه‌دهنده/مدل از `models.providers..timeoutSeconds` استفاده کنید - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - حذف `browser.relayBindHost` (تنظیم قدیمی extension relay) - - `models.providers.*.api: "openai"` قدیمی → `"openai-completions"` (startup مربوط به gateway همچنین providerهایی را که `api` آن‌ها روی مقدار enum آینده یا ناشناخته تنظیم شده باشد رد می‌کند، به‌جای اینکه با حالت fail-closed متوقف شود) + - حذف `browser.relayBindHost` (تنظیم قدیمی relay افزونه) + - `models.providers.*.api: "openai"` قدیمی → `"openai-completions"` (startup مربوط به Gateway همچنین ارائه‌دهندگانی را که `api` آن‌ها روی مقدار enum آینده یا ناشناخته تنظیم شده باشد به‌جای fail closed رد می‌کند) - هشدارهای Doctor همچنین شامل راهنمایی account-default برای کانال‌های چندحسابی می‌شوند: + هشدارهای Doctor همچنین شامل راهنمایی account-default برای کانال‌های چندحسابی است: - - اگر دو یا چند ورودی `channels..accounts` بدون `channels..defaultAccount` یا `accounts.default` پیکربندی شده باشند، doctor هشدار می‌دهد که fallback routing می‌تواند یک account غیرمنتظره را انتخاب کند. - - اگر `channels..defaultAccount` روی یک account ID ناشناخته تنظیم شده باشد، doctor هشدار می‌دهد و account IDهای پیکربندی‌شده را فهرست می‌کند. + - اگر دو یا چند ورودی `channels..accounts` بدون `channels..defaultAccount` یا `accounts.default` پیکربندی شده باشند، دکتر هشدار می‌دهد که مسیریابی جایگزین ممکن است یک حساب غیرمنتظره را انتخاب کند. + - اگر `channels..defaultAccount` روی یک شناسه حساب ناشناخته تنظیم شده باشد، دکتر هشدار می‌دهد و شناسه‌های حساب پیکربندی‌شده را فهرست می‌کند. - - اگر `models.providers.opencode`، `opencode-zen`، یا `opencode-go` را به‌صورت دستی اضافه کرده باشید، کاتالوگ داخلی OpenCode از `@mariozechner/pi-ai` را نادیده می‌گیرد. این می‌تواند مدل‌ها را مجبور کند از API نادرست استفاده کنند یا هزینه‌ها را صفر کند. doctor هشدار می‌دهد تا بتوانید نادیده‌گیری را حذف کنید و مسیریابی API و هزینه‌های هر مدل را بازیابی کنید. + + اگر `models.providers.opencode`، `opencode-zen`، یا `opencode-go` را به‌صورت دستی اضافه کرده باشید، کاتالوگ داخلی OpenCode از `@mariozechner/pi-ai` را بازنویسی می‌کند. این می‌تواند مدل‌ها را مجبور کند از API اشتباه استفاده کنند یا هزینه‌ها را صفر کند. دکتر هشدار می‌دهد تا بتوانید این بازنویسی را حذف کنید و مسیریابی API و هزینه‌های مخصوص هر مدل را بازیابی کنید. - اگر پیکربندی مرورگر شما هنوز به مسیر افزونه Chrome حذف‌شده اشاره کند، doctor آن را به مدل اتصال Chrome MCP میزبان-محلی فعلی نرمال‌سازی می‌کند: + اگر پیکربندی مرورگر شما هنوز به مسیر افزونه حذف‌شده Chrome اشاره کند، دکتر آن را به مدل اتصال Chrome MCP میزبان-محلی فعلی عادی‌سازی می‌کند: - `browser.profiles.*.driver: "extension"` به `"existing-session"` تبدیل می‌شود - `browser.relayBindHost` حذف می‌شود - doctor همچنین وقتی از `defaultProfile: "user"` یا یک پروفایل `existing-session` پیکربندی‌شده استفاده می‌کنید، مسیر Chrome MCP میزبان-محلی را بررسی می‌کند: + دکتر همچنین زمانی که از `defaultProfile: "user"` یا یک پروفایل پیکربندی‌شده `existing-session` استفاده می‌کنید، مسیر Chrome MCP میزبان-محلی را بررسی می‌کند: - - بررسی می‌کند آیا Google Chrome روی همان میزبان برای پروفایل‌های اتصال خودکار پیش‌فرض نصب شده است یا نه + - بررسی می‌کند که آیا Google Chrome روی همان میزبان برای پروفایل‌های اتصال خودکار پیش‌فرض نصب شده است - نسخه Chrome شناسایی‌شده را بررسی می‌کند و وقتی پایین‌تر از Chrome 144 باشد هشدار می‌دهد - - یادآوری می‌کند اشکال‌زدایی از راه دور را در صفحه inspect مرورگر فعال کنید (برای مثال `chrome://inspect/#remote-debugging`، `brave://inspect/#remote-debugging`، یا `edge://inspect/#remote-debugging`) + - یادآوری می‌کند که اشکال‌زدایی راه‌دور را در صفحه بازرسی مرورگر فعال کنید (برای مثال `chrome://inspect/#remote-debugging`، `brave://inspect/#remote-debugging`، یا `edge://inspect/#remote-debugging`) - doctor نمی‌تواند تنظیم سمت Chrome را برای شما فعال کند. Chrome MCP میزبان-محلی همچنان به این موارد نیاز دارد: + دکتر نمی‌تواند تنظیم سمت Chrome را برای شما فعال کند. Chrome MCP میزبان-محلی همچنان نیاز دارد به: - یک مرورگر مبتنی بر Chromium نسخه 144+ روی میزبان Gateway/Node - - اجرای محلی مرورگر - - فعال بودن اشکال‌زدایی از راه دور در آن مرورگر + - مرورگری که به‌صورت محلی در حال اجرا باشد + - اشکال‌زدایی راه‌دور که در آن مرورگر فعال شده باشد - تایید نخستین درخواست رضایت اتصال در مرورگر - آمادگی در اینجا فقط درباره پیش‌نیازهای اتصال محلی است. Existing-session محدودیت‌های مسیر Chrome MCP فعلی را حفظ می‌کند؛ مسیرهای پیشرفته مانند `responsebody`، خروجی PDF، رهگیری دانلود، و عملیات دسته‌ای همچنان به یک مرورگر مدیریت‌شده یا پروفایل CDP خام نیاز دارند. + آمادگی در اینجا فقط درباره پیش‌نیازهای اتصال محلی است. Existing-session محدودیت‌های مسیر فعلی Chrome MCP را حفظ می‌کند؛ مسیرهای پیشرفته مانند `responsebody`، خروجی PDF، رهگیری دانلود، و کنش‌های دسته‌ای همچنان به یک مرورگر مدیریت‌شده یا پروفایل CDP خام نیاز دارند. - این بررسی برای Docker، sandbox، remote-browser، یا سایر جریان‌های headless اعمال **نمی‌شود**. آن‌ها همچنان از CDP خام استفاده می‌کنند. + این بررسی برای Docker، sandbox، remote-browser، یا جریان‌های headless دیگر اعمال **نمی‌شود**. آن‌ها همچنان از CDP خام استفاده می‌کنند. - وقتی یک پروفایل OpenAI Codex OAuth پیکربندی شده باشد، doctor نقطه پایانی مجوزدهی OpenAI را بررسی می‌کند تا تایید کند پشته TLS محلی Node/OpenSSL می‌تواند زنجیره گواهی را اعتبارسنجی کند. اگر بررسی با خطای گواهی شکست بخورد (برای مثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`، گواهی منقضی‌شده، یا گواهی خودامضاشده)، doctor راهنمای رفع مشکل مخصوص پلتفرم را چاپ می‌کند. در macOS با Node نصب‌شده از Homebrew، راه‌حل معمولا `brew postinstall ca-certificates` است. با `--deep`، این بررسی حتی اگر Gateway سالم باشد هم اجرا می‌شود. + وقتی یک پروفایل OpenAI Codex OAuth پیکربندی شده باشد، دکتر نقطه پایانی مجوزدهی OpenAI را بررسی می‌کند تا تایید کند پشته TLS محلی Node/OpenSSL می‌تواند زنجیره گواهی را اعتبارسنجی کند. اگر بررسی با خطای گواهی شکست بخورد (برای مثال `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`، گواهی منقضی‌شده، یا گواهی خودامضاشده)، دکتر راهنمای رفع مشکل مخصوص پلتفرم را چاپ می‌کند. در macOS با Node نصب‌شده از Homebrew، راه‌حل معمولا `brew postinstall ca-certificates` است. با `--deep`، بررسی حتی اگر gateway سالم باشد نیز اجرا می‌شود. - - اگر قبلا تنظیمات انتقال قدیمی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر ارائه‌دهنده داخلی Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند، تحت‌الشعاع قرار دهند. doctor وقتی آن تنظیمات انتقال قدیمی را کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید نادیده‌گیری انتقال منسوخ را حذف یا بازنویسی کنید و رفتار مسیریابی/بازگشت داخلی را دوباره به دست آورید. پروکسی‌های سفارشی و نادیده‌گیری‌های فقط-هدر همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند. + + اگر قبلا تنظیمات انتقال قدیمی OpenAI را زیر `models.providers.openai-codex` اضافه کرده باشید، می‌توانند مسیر ارائه‌دهنده داخلی Codex OAuth را که نسخه‌های جدیدتر به‌صورت خودکار استفاده می‌کنند تحت‌الشعاع قرار دهند. دکتر وقتی این تنظیمات انتقال قدیمی را کنار Codex OAuth ببیند هشدار می‌دهد تا بتوانید بازنویسی انتقال کهنه را حذف یا بازنویسی کنید و رفتار مسیریابی/جایگزینی داخلی را برگردانید. پراکسی‌های سفارشی و بازنویسی‌های فقط-هدر همچنان پشتیبانی می‌شوند و این هشدار را فعال نمی‌کنند. - - وقتی Plugin بسته‌بندی‌شده Codex فعال باشد، doctor همچنین بررسی می‌کند که آیا ارجاع‌های مدل اصلی `openai-codex/*` هنوز از طریق اجراکننده پیش‌فرض PI حل می‌شوند یا نه. این ترکیب وقتی می‌خواهید احراز هویت OAuth/اشتراک Codex از طریق PI انجام شود معتبر است، اما به‌راحتی با هارنس app-server بومی Codex اشتباه گرفته می‌شود. doctor هشدار می‌دهد و به شکل app-server صریح اشاره می‌کند: `openai/*` به‌علاوه `agentRuntime.id: "codex"` یا `OPENCLAW_AGENT_RUNTIME=codex`. + + وقتی Plugin بسته‌بندی‌شده Codex فعال باشد، دکتر همچنین بررسی می‌کند که آیا ارجاع‌های مدل اصلی `openai-codex/*` همچنان از طریق اجراکننده پیش‌فرض PI resolve می‌شوند یا نه. این ترکیب زمانی معتبر است که احراز هویت Codex OAuth/اشتراک را از طریق PI بخواهید، اما به‌راحتی ممکن است با هارنس بومی app-server مربوط به Codex اشتباه گرفته شود. دکتر هشدار می‌دهد و به شکل صریح app-server اشاره می‌کند: `openai/*` به‌همراه `agentRuntime.id: "codex"` یا `OPENCLAW_AGENT_RUNTIME=codex`. - doctor این را خودکار تعمیر نمی‌کند چون هر دو مسیر معتبرند: + دکتر این را به‌صورت خودکار تعمیر نمی‌کند، چون هر دو مسیر معتبر هستند: - - `openai-codex/*` + PI یعنی «از احراز هویت OAuth/اشتراک Codex از طریق اجراکننده عادی OpenClaw استفاده کن.» + - `openai-codex/*` + PI یعنی «از احراز هویت Codex OAuth/اشتراک از طریق اجراکننده عادی OpenClaw استفاده کن.» - `openai/*` + `runtime: "codex"` یعنی «نوبت تعبیه‌شده را از طریق app-server بومی Codex اجرا کن.» - - `/codex ...` یعنی «یک گفت‌وگوی بومی Codex را از چت کنترل یا متصل کن.» + - `/codex ...` یعنی «یک گفت‌وگوی بومی Codex را از چت کنترل یا bind کن.» - `/acp ...` یا `runtime: "acp"` یعنی «از آداپتور خارجی ACP/acpx استفاده کن.» - اگر هشدار ظاهر شد، مسیری را که مد نظرتان بوده انتخاب کنید و پیکربندی را دستی ویرایش کنید. وقتی PI Codex OAuth عمدی است، هشدار را همان‌طور نگه دارید. + اگر هشدار ظاهر شد، مسیری را که قصد داشتید انتخاب کنید و پیکربندی را دستی ویرایش کنید. وقتی PI Codex OAuth عمدی است، هشدار را همان‌طور نگه دارید. - doctor می‌تواند چیدمان‌های قدیمی روی دیسک را به ساختار فعلی مهاجرت دهد: + دکتر می‌تواند چیدمان‌های قدیمی روی دیسک را به ساختار فعلی مهاجرت دهد: - - ذخیره‌گاه نشست‌ها + رونوشت‌ها: + - ذخیره‌ساز نشست‌ها + رونوشت‌ها: - از `~/.openclaw/sessions/` به `~/.openclaw/agents//sessions/` - دایرکتوری عامل: - از `~/.openclaw/agent/` به `~/.openclaw/agents//agent/` - وضعیت احراز هویت WhatsApp (Baileys): - - از `~/.openclaw/credentials/*.json` قدیمی (به‌جز `oauth.json`) + - از مسیر قدیمی `~/.openclaw/credentials/*.json` (به‌جز `oauth.json`) - به `~/.openclaw/credentials/whatsapp//...` (شناسه حساب پیش‌فرض: `default`) - این مهاجرت‌ها با بهترین تلاش و idempotent هستند؛ doctor وقتی هر پوشه قدیمی را به‌عنوان پشتیبان باقی بگذارد هشدار منتشر می‌کند. Gateway/CLI همچنین هنگام شروع، نشست‌های قدیمی + دایرکتوری عامل را خودکار مهاجرت می‌دهد تا تاریخچه/احراز هویت/مدل‌ها بدون اجرای دستی doctor در مسیر هر عامل قرار بگیرند. احراز هویت WhatsApp عمدا فقط از طریق `openclaw doctor` مهاجرت داده می‌شود. نرمال‌سازی ارائه‌دهنده گفت‌وگو/نگاشت ارائه‌دهنده اکنون با برابری ساختاری مقایسه می‌کند، بنابراین تفاوت‌هایی که فقط مربوط به ترتیب کلیدها هستند دیگر تغییرات تکراری بی‌اثر `doctor --fix` را فعال نمی‌کنند. + این مهاجرت‌ها به‌صورت best-effort و idempotent هستند؛ دکتر وقتی هر پوشه قدیمی را به‌عنوان پشتیبان باقی بگذارد هشدار منتشر می‌کند. Gateway/CLI همچنین نشست‌های قدیمی + دایرکتوری عامل را هنگام راه‌اندازی به‌صورت خودکار مهاجرت می‌دهد تا تاریخچه/احراز هویت/مدل‌ها بدون اجرای دستی دکتر در مسیر مخصوص هر عامل قرار بگیرند. احراز هویت WhatsApp عمدا فقط از طریق `openclaw doctor` مهاجرت داده می‌شود. عادی‌سازی ارائه‌دهنده Talk/نگاشت ارائه‌دهنده اکنون بر اساس برابری ساختاری مقایسه می‌کند، بنابراین تفاوت‌هایی که فقط مربوط به ترتیب کلیدها هستند دیگر باعث تغییرات تکراری بی‌اثر `doctor --fix` نمی‌شوند. - - doctor همه مانیفست‌های Plugin نصب‌شده را برای کلیدهای قابلیت سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل مانیفست را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقادیر را داشته باشد، کلید قدیمی بدون تکرار داده حذف می‌شود. + + دکتر همه manifestهای Plugin نصب‌شده را برای کلیدهای قابلیت سطح بالای منسوخ (`speechProviders`، `realtimeTranscriptionProviders`، `realtimeVoiceProviders`، `mediaUnderstandingProviders`، `imageGenerationProviders`، `videoGenerationProviders`، `webFetchProviders`، `webSearchProviders`) اسکن می‌کند. وقتی پیدا شوند، پیشنهاد می‌دهد آن‌ها را به شیء `contracts` منتقل کند و فایل manifest را درجا بازنویسی کند. این مهاجرت idempotent است؛ اگر کلید `contracts` از قبل همان مقادیر را داشته باشد، کلید قدیمی بدون تکرار داده حذف می‌شود. - - doctor همچنین ذخیره‌گاه کار Cron (`~/.openclaw/cron/jobs.json` به‌صورت پیش‌فرض، یا `cron.store` وقتی بازنویسی شده باشد) را برای شکل‌های قدیمی کار که زمان‌بند هنوز برای سازگاری می‌پذیرد بررسی می‌کند. + + دکتر همچنین ذخیره‌ساز کارهای cron را (`~/.openclaw/cron/jobs.json` به‌صورت پیش‌فرض، یا `cron.store` وقتی بازنویسی شده باشد) برای شکل‌های قدیمی کار که زمان‌بند هنوز برای سازگاری می‌پذیرد بررسی می‌کند. - پاک‌سازی‌های فعلی Cron شامل این موارد است: + پاک‌سازی‌های فعلی cron شامل موارد زیر است: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - فیلدهای payload سطح بالا (`message`، `model`، `thinking`، ...) → `payload` - فیلدهای delivery سطح بالا (`deliver`، `channel`، `to`، `provider`، ...) → `delivery` - - نام‌های مستعار delivery مربوط به `provider` در payload → `delivery.channel` صریح - - کارهای fallback وبهوک ساده قدیمی `notify: true` → `delivery.mode="webhook"` صریح همراه با `delivery.to=cron.webhook` + - نام‌های مستعار delivery مربوط به payload `provider` → `delivery.channel` صریح + - کارهای fallback ساده قدیمی webhook با `notify: true` → `delivery.mode="webhook"` صریح با `delivery.to=cron.webhook` - doctor فقط وقتی کارهای `notify: true` را خودکار مهاجرت می‌دهد که بتواند این کار را بدون تغییر رفتار انجام دهد. اگر کاری fallback اطلاع‌رسانی قدیمی را با یک حالت delivery غیر وبهوک موجود ترکیب کند، doctor هشدار می‌دهد و آن کار را برای بازبینی دستی باقی می‌گذارد. + دکتر فقط زمانی کارهای `notify: true` را به‌صورت خودکار مهاجرت می‌دهد که بتواند این کار را بدون تغییر رفتار انجام دهد. اگر یک کار fallback قدیمی notify را با یک حالت delivery غیر-webhook موجود ترکیب کند، دکتر هشدار می‌دهد و آن کار را برای بازبینی دستی باقی می‌گذارد. - doctor همه دایرکتوری‌های نشست عامل را برای فایل‌های قفل نوشتن مانده اسکن می‌کند؛ فایل‌هایی که وقتی یک نشست به‌صورت غیرعادی خارج شده باقی مانده‌اند. برای هر فایل قفل پیدا شده این موارد را گزارش می‌کند: مسیر، PID، اینکه PID هنوز زنده است یا نه، سن قفل، و اینکه stale محسوب می‌شود یا نه (PID مرده یا قدیمی‌تر از 30 دقیقه). در حالت `--fix` / `--repair` فایل‌های قفل stale را خودکار حذف می‌کند؛ در غیر این صورت یادداشتی چاپ می‌کند و به شما می‌گوید با `--fix` دوباره اجرا کنید. + دکتر هر دایرکتوری نشست عامل را برای فایل‌های write-lock مانده اسکن می‌کند — فایل‌هایی که وقتی یک نشست به‌صورت غیرعادی خارج شده باقی مانده‌اند. برای هر فایل قفل پیدا‌شده گزارش می‌دهد: مسیر، PID، اینکه PID هنوز زنده است یا نه، سن قفل، و اینکه stale در نظر گرفته می‌شود یا نه (PID مرده یا قدیمی‌تر از 30 دقیقه). در حالت `--fix` / `--repair` فایل‌های قفل stale را به‌صورت خودکار حذف می‌کند؛ در غیر این صورت یک یادداشت چاپ می‌کند و به شما دستور می‌دهد با `--fix` دوباره اجرا کنید. - doctor فایل‌های JSONL نشست عامل را برای شکل شاخه تکراری ایجادشده توسط باگ بازنویسی رونوشت prompt در 2026.4.24 اسکن می‌کند: یک نوبت کاربر رهاشده با زمینه runtime داخلی OpenClaw به‌علاوه یک خواهر/برادر فعال که همان prompt قابل مشاهده کاربر را دارد. در حالت `--fix` / `--repair`، doctor از هر فایل تحت تاثیر کنار فایل اصلی پشتیبان می‌گیرد و رونوشت را به شاخه فعال بازنویسی می‌کند تا تاریخچه Gateway و خواننده‌های حافظه دیگر نوبت‌های تکراری نبینند. + دکتر فایل‌های JSONL نشست عامل را برای شکل شاخه تکراری ایجادشده توسط باگ بازنویسی رونوشت prompt در 2026.4.24 اسکن می‌کند: یک نوبت کاربر رهاشده با زمینه اجرای داخلی OpenClaw به‌همراه یک sibling فعال که همان prompt قابل‌مشاهده کاربر را دارد. در حالت `--fix` / `--repair`، دکتر از هر فایل متاثر کنار نسخه اصلی پشتیبان می‌گیرد و رونوشت را به شاخه فعال بازنویسی می‌کند تا خواننده‌های تاریخچه و حافظه gateway دیگر نوبت‌های تکراری نبینند. - - دایرکتوری وضعیت ساقه مغز عملیاتی است. اگر ناپدید شود، نشست‌ها، اعتبارنامه‌ها، لاگ‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه جای دیگری پشتیبان داشته باشید). + + دایرکتوری وضعیت brainstem عملیاتی است. اگر ناپدید شود، نشست‌ها، اطلاعات ورود، گزارش‌ها، و پیکربندی را از دست می‌دهید (مگر اینکه در جای دیگری پشتیبان داشته باشید). - 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` باشد، doctor یادآوری می‌کند آن را روی میزبان راه دور اجرا کنید (وضعیت آنجا زندگی می‌کند). - - **مجوزهای فایل پیکربندی**: اگر `~/.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` باشد، دکتر یادآوری می‌کند آن را روی میزبان راه‌دور اجرا کنید (وضعیت آنجا قرار دارد). + - **مجوزهای فایل پیکربندی**: اگر `~/.openclaw/openclaw.json` برای گروه/جهان قابل خواندن باشد هشدار می‌دهد و پیشنهاد می‌دهد آن را به `600` محدود کند. - doctor پروفایل‌های OAuth را در ذخیره‌گاه احراز هویت بررسی می‌کند، وقتی توکن‌ها در حال انقضا/منقضی‌شده باشند هشدار می‌دهد، و وقتی ایمن باشد می‌تواند آن‌ها را تازه‌سازی کند. اگر پروفایل OAuth/توکن Anthropic stale باشد، یک کلید API Anthropic یا مسیر setup-token Anthropic را پیشنهاد می‌دهد. درخواست‌های تازه‌سازی فقط هنگام اجرای تعاملی (TTY) ظاهر می‌شوند؛ `--non-interactive` تلاش‌های تازه‌سازی را رد می‌کند. + دکتر پروفایل‌های OAuth را در ذخیره‌ساز احراز هویت بررسی می‌کند، وقتی توکن‌ها در حال انقضا/منقضی‌شده باشند هشدار می‌دهد، و وقتی ایمن باشد می‌تواند آن‌ها را refresh کند. اگر پروفایل OAuth/token مربوط به Anthropic کهنه باشد، یک کلید API Anthropic یا مسیر setup-token مربوط به Anthropic را پیشنهاد می‌دهد. درخواست‌های refresh فقط وقتی به‌صورت تعاملی (TTY) اجرا شود ظاهر می‌شوند؛ `--non-interactive` تلاش‌های refresh را رد می‌کند. - وقتی تازه‌سازی OAuth به‌صورت دائمی شکست بخورد (برای مثال `refresh_token_reused`، `invalid_grant`، یا ارائه‌دهنده‌ای که می‌گوید باید دوباره وارد شوید)، doctor گزارش می‌دهد که احراز هویت دوباره لازم است و دستور دقیق `openclaw models auth login --provider ...` را برای اجرا چاپ می‌کند. + وقتی refresh مربوط به OAuth به‌صورت دائمی شکست بخورد (برای مثال `refresh_token_reused`، `invalid_grant`، یا ارائه‌دهنده‌ای که به شما می‌گوید دوباره وارد شوید)، دکتر گزارش می‌دهد که احراز هویت دوباره لازم است و فرمان دقیق `openclaw models auth login --provider ...` را برای اجرا چاپ می‌کند. - doctor همچنین پروفایل‌های احراز هویتی را گزارش می‌کند که به این دلایل موقتا غیرقابل استفاده هستند: + دکتر همچنین پروفایل‌های احراز هویتی را گزارش می‌دهد که به‌طور موقت به دلایل زیر غیرقابل استفاده هستند: - - cooldownهای کوتاه (محدودیت نرخ/timeout/شکست‌های احراز هویت) - - غیرفعال‌سازی‌های طولانی‌تر (شکست‌های صورت‌حساب/اعتبار) + - cooldownهای کوتاه (محدودیت نرخ/timeoutها/شکست‌های احراز هویت) + - غیرفعال‌سازی‌های طولانی‌تر (شکست‌های صورتحساب/اعتبار) - - اگر `hooks.gmail.model` تنظیم شده باشد، doctor ارجاع مدل را در برابر کاتالوگ و allowlist اعتبارسنجی می‌کند و وقتی حل نشود یا مجاز نباشد هشدار می‌دهد. + + اگر `hooks.gmail.model` تنظیم شده باشد، doctor ارجاع مدل را در برابر کاتالوگ و allowlist اعتبارسنجی می‌کند و وقتی قابل resolve نباشد یا مجاز نباشد هشدار می‌دهد. - - وقتی sandboxing فعال باشد، doctor تصاویر Docker را بررسی می‌کند و اگر تصویر فعلی موجود نباشد پیشنهاد می‌دهد بسازد یا به نام‌های قدیمی تغییر دهد. + + وقتی sandboxing فعال باشد، doctor تصاویر Docker را بررسی می‌کند و اگر تصویر فعلی وجود نداشته باشد، پیشنهاد ساختن آن یا تغییر به نام‌های legacy را می‌دهد. - - doctor وابستگی‌های runtime را فقط برای Pluginهای بسته‌بندی‌شده‌ای که در پیکربندی فعلی فعال‌اند یا به‌صورت پیش‌فرض توسط مانیفست بسته‌بندی‌شده‌شان فعال شده‌اند اعتبارسنجی می‌کند، برای مثال `plugins.entries.discord.enabled: true`، `channels.discord.enabled: true` قدیمی، `models.providers.*` / ارجاع‌های مدل عامل پیکربندی‌شده، یا یک Plugin بسته‌بندی‌شده با فعال‌سازی پیش‌فرض بدون مالکیت ارائه‌دهنده. اگر موردی گم شده باشد، doctor بسته‌ها را گزارش می‌کند و آن‌ها را در حالت `openclaw doctor --fix` / `openclaw doctor --repair` نصب می‌کند. Pluginهای خارجی همچنان از `openclaw plugins install` / `openclaw plugins update` استفاده می‌کنند؛ doctor وابستگی‌ها را برای مسیرهای دلخواه Plugin نصب نمی‌کند. + + Doctor وابستگی‌های runtime را فقط برای Pluginهای همراهی تأیید می‌کند که در پیکربندی فعلی فعال هستند یا با پیش‌فرض manifest همراهشان فعال شده‌اند، برای مثال `plugins.entries.discord.enabled: true`، مقدار legacy یعنی `channels.discord.enabled: true`، ارجاع‌های پیکربندی‌شده‌ی `models.providers.*` / مدل agent، یا یک Plugin همراهِ فعال به‌صورت پیش‌فرض بدون مالکیت provider. اگر موردی وجود نداشته باشد، doctor بسته‌ها را گزارش می‌کند و آن‌ها را در حالت `openclaw doctor --fix` / `openclaw doctor --repair` نصب می‌کند. Pluginهای خارجی همچنان از `openclaw plugins install` / `openclaw plugins update` استفاده می‌کنند؛ doctor وابستگی‌ها را برای مسیرهای دلخواه Plugin نصب نمی‌کند. - هنگام ترمیم doctor، نصب‌های npm وابستگی‌های زمان اجرای bundled در نشست‌های TTY پیشرفت را با spinner گزارش می‌کنند و در خروجی piped/headless به‌صورت دوره‌ای پیشرفت خطی نشان می‌دهند. Gateway و CLI محلی نیز می‌توانند وابستگی‌های زمان اجرای Plugin های bundled فعال را پیش از import کردن یک Plugin bundled، بنا به درخواست ترمیم کنند. این نصب‌ها به ریشه نصب زمان اجرای Plugin محدود هستند، با scripts غیرفعال اجرا می‌شوند، package lock نمی‌نویسند، و با قفل ریشه نصب محافظت می‌شوند تا شروع‌های هم‌زمان CLI یا Gateway در یک زمان همان درخت `node_modules` را تغییر ندهند. + در طول ترمیم doctor، نصب‌های npm مربوط به وابستگی‌های runtime همراه، در نشست‌های TTY پیشرفت spinner و در خروجی piped/headless پیشرفت خطی دوره‌ای را گزارش می‌کنند. Gateway و CLI محلی نیز می‌توانند وابستگی‌های runtime مربوط به Pluginهای همراهِ فعال را پیش از import کردن یک Plugin همراه، در صورت نیاز ترمیم کنند. این نصب‌ها به ریشه‌ی نصب runtime Plugin محدود هستند، با scriptهای غیرفعال اجرا می‌شوند، package lock نمی‌نویسند، و با یک lock مربوط به install-root محافظت می‌شوند تا شروع‌های هم‌زمان CLI یا Gateway درخت یکسان `node_modules` را هم‌زمان تغییر ندهند. - - Doctor سرویس‌های Gateway قدیمی (launchd/systemd/schtasks) را تشخیص می‌دهد و پیشنهاد می‌کند آن‌ها را حذف کند و سرویس OpenClaw را با پورت Gateway فعلی نصب کند. همچنین می‌تواند سرویس‌های اضافی شبیه Gateway را اسکن کند و راهنمای پاک‌سازی چاپ کند. سرویس‌های Gateway OpenClaw که با نام پروفایل مشخص شده‌اند، درجه‌اول محسوب می‌شوند و به‌عنوان «اضافی» علامت‌گذاری نمی‌شوند. + + Doctor سرویس‌های legacy gateway را تشخیص می‌دهد (launchd/systemd/schtasks) و پیشنهاد می‌دهد آن‌ها را حذف کند و سرویس OpenClaw را با پورت Gateway فعلی نصب کند. همچنین می‌تواند سرویس‌های اضافی شبیه gateway را اسکن کند و نکته‌های پاک‌سازی چاپ کند. سرویس‌های OpenClaw gateway با نام profile، first-class در نظر گرفته می‌شوند و به‌عنوان «اضافی» علامت‌گذاری نمی‌شوند. - در Linux، اگر سرویس Gateway سطح کاربر وجود نداشته باشد اما یک سرویس Gateway سطح سیستم OpenClaw وجود داشته باشد، Doctor به‌طور خودکار یک سرویس سطح کاربر دوم نصب نمی‌کند. با `openclaw gateway status --deep` یا `openclaw doctor --deep` بررسی کنید، سپس نمونه تکراری را حذف کنید یا وقتی یک supervisor سیستمی چرخه‌عمر Gateway را مالک است، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. + در Linux، اگر سرویس Gateway سطح کاربر وجود نداشته باشد اما یک سرویس OpenClaw Gateway سطح سیستم وجود داشته باشد، doctor به‌صورت خودکار سرویس سطح کاربر دومی نصب نمی‌کند. با `openclaw gateway status --deep` یا `openclaw doctor --deep` بررسی کنید، سپس duplicate را حذف کنید یا وقتی یک supervisor سیستمی مالک چرخه‌ی عمر Gateway است، `OPENCLAW_SERVICE_REPAIR_POLICY=external` را تنظیم کنید. - وقتی یک حساب کانال Matrix مهاجرت وضعیت قدیمیِ در انتظار یا قابل اقدام داشته باشد، Doctor (در حالت `--fix` / `--repair`) یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس مراحل مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت قدیمی Matrix و آماده‌سازی وضعیت رمزنگاری‌شده قدیمی. هر دو مرحله غیرکشنده هستند؛ خطاها ثبت می‌شوند و startup ادامه می‌یابد. در حالت فقط‌خواندنی (`openclaw doctor` بدون `--fix`) این بررسی کاملا نادیده گرفته می‌شود. + وقتی یک حساب کانال Matrix یک مهاجرت وضعیت legacy در حالت pending یا actionable داشته باشد، doctor در حالت `--fix` / `--repair` یک snapshot پیش از مهاجرت ایجاد می‌کند و سپس مراحل مهاجرت best-effort را اجرا می‌کند: مهاجرت وضعیت legacy Matrix و آماده‌سازی وضعیت رمزگذاری‌شده‌ی legacy. هر دو مرحله non-fatal هستند؛ خطاها ثبت می‌شوند و startup ادامه پیدا می‌کند. در حالت read-only (`openclaw doctor` بدون `--fix`) این بررسی به‌طور کامل نادیده گرفته می‌شود. - - Doctor اکنون وضعیت جفت‌سازی دستگاه را به‌عنوان بخشی از گذر سلامت عادی بررسی می‌کند. + + Doctor اکنون وضعیت pairing دستگاه را به‌عنوان بخشی از گذر سلامت عادی بررسی می‌کند. - مواردی که گزارش می‌کند: + آنچه گزارش می‌کند: - - درخواست‌های جفت‌سازی اولیه در انتظار - - ارتقاهای نقش در انتظار برای دستگاه‌هایی که قبلا جفت شده‌اند - - ارتقاهای scope در انتظار برای دستگاه‌هایی که قبلا جفت شده‌اند - - ترمیم‌های عدم تطابق public-key که در آن‌ها device id هنوز مطابقت دارد اما هویت دستگاه دیگر با رکورد تاییدشده مطابقت ندارد - - رکوردهای جفت‌شده‌ای که برای یک نقش تاییدشده token فعال ندارند - - token های جفت‌شده‌ای که scope هایشان از baseline جفت‌سازی تاییدشده منحرف شده است - - ورودی‌های cache محلی device-token برای دستگاه فعلی که قدیمی‌تر از یک چرخش token در سمت Gateway هستند یا metadata scope کهنه دارند + - درخواست‌های pending برای pairing اولین‌بار + - ارتقاهای role در حالت pending برای دستگاه‌هایی که از قبل paired شده‌اند + - ارتقاهای scope در حالت pending برای دستگاه‌هایی که از قبل paired شده‌اند + - ترمیم‌های عدم تطابق public-key که در آن id دستگاه همچنان مطابق است اما identity دستگاه دیگر با رکورد تأییدشده مطابق نیست + - رکوردهای paired که برای یک role تأییدشده token فعال ندارند + - tokenهای paired که scopeهایشان از baseline تأییدشده‌ی pairing خارج شده است + - ورودی‌های token دستگاه cacheشده‌ی محلی برای ماشین فعلی که پیش از چرخش token در سمت Gateway هستند یا metadata مربوط به scope منسوخ دارند - Doctor درخواست‌های جفت‌سازی را به‌طور خودکار تایید نمی‌کند و token های دستگاه را به‌طور خودکار نمی‌چرخاند. در عوض مراحل بعدی دقیق را چاپ می‌کند: + Doctor درخواست‌های pair را خودکار تأیید نمی‌کند و tokenهای دستگاه را خودکار rotate نمی‌کند. در عوض مراحل دقیق بعدی را چاپ می‌کند: - - درخواست‌های در انتظار را با `openclaw devices list` بررسی کنید - - درخواست دقیق را با `openclaw devices approve ` تایید کنید - - یک token تازه را با `openclaw devices rotate --device --role ` بچرخانید - - یک رکورد کهنه را با `openclaw devices remove ` حذف و دوباره تایید کنید + - درخواست‌های pending را با `openclaw devices list` بررسی کنید + - درخواست دقیق را با `openclaw devices approve ` تأیید کنید + - یک token تازه را با `openclaw devices rotate --device --role ` rotate کنید + - یک رکورد منسوخ را با `openclaw devices remove ` حذف و دوباره تأیید کنید - این رخنه رایج «قبلا جفت شده اما هنوز پیام نیاز به جفت‌سازی می‌گیرد» را می‌بندد: Doctor اکنون جفت‌سازی اولیه را از ارتقاهای نقش/scope در انتظار و از انحراف token/هویت دستگاه کهنه تفکیک می‌کند. + این کار حفره‌ی رایج «از قبل paired شده اما هنوز pairing required دریافت می‌کند» را می‌بندد: doctor اکنون pairing اولین‌بار را از ارتقاهای pending مربوط به role/scope و از drift منسوخ token/identity دستگاه تفکیک می‌کند. - Doctor زمانی هشدار صادر می‌کند که یک provider بدون allowlist برای DM ها باز باشد، یا وقتی یک policy به‌شکل خطرناک پیکربندی شده باشد. + Doctor وقتی یک provider بدون allowlist برای DMها باز باشد، یا وقتی یک policy به‌شکل خطرناک پیکربندی شده باشد، هشدار صادر می‌کند. - اگر به‌عنوان سرویس کاربر systemd اجرا شود، Doctor مطمئن می‌شود lingering فعال است تا Gateway پس از logout زنده بماند. + اگر به‌عنوان یک سرویس کاربر systemd اجرا شود، doctor مطمئن می‌شود lingering فعال است تا Gateway پس از logout زنده بماند. - - Doctor خلاصه‌ای از وضعیت workspace را برای agent پیش‌فرض چاپ می‌کند: + + Doctor خلاصه‌ای از وضعیت workspace برای agent پیش‌فرض چاپ می‌کند: - - **وضعیت Skills**: تعداد skills واجد شرایط، دارای requirements ناقص، و مسدودشده توسط allowlist را می‌شمارد. - - **دایرکتوری‌های workspace قدیمی**: وقتی `~/openclaw` یا سایر دایرکتوری‌های workspace قدیمی کنار workspace فعلی وجود داشته باشند، هشدار می‌دهد. - - **وضعیت Plugin**: Plugin های فعال/غیرفعال/خطادار را می‌شمارد؛ برای هر خطا، شناسه‌های Plugin را فهرست می‌کند؛ capability های bundle plugin را گزارش می‌کند. - - **هشدارهای سازگاری Plugin**: Plugin هایی را که با runtime فعلی مشکل سازگاری دارند علامت‌گذاری می‌کند. - - **عیب‌یابی Plugin**: هر هشدار یا خطای زمان load که توسط registry Plugin صادر شده باشد را نمایش می‌دهد. + - **وضعیت Skills**: تعداد Skills واجد شرایط، دارای نیازمندی‌های گم‌شده، و مسدودشده توسط allowlist. + - **دایرکتوری‌های workspace legacy**: وقتی `~/openclaw` یا دایرکتوری‌های workspace legacy دیگر در کنار workspace فعلی وجود داشته باشند، هشدار می‌دهد. + - **وضعیت Plugin**: تعداد Pluginهای فعال/غیرفعال/دارای خطا را می‌شمارد؛ IDهای Plugin را برای هر خطا فهرست می‌کند؛ قابلیت‌های Pluginهای bundle را گزارش می‌کند. + - **هشدارهای سازگاری Plugin**: Pluginهایی را که با runtime فعلی مشکل سازگاری دارند علامت‌گذاری می‌کند. + - **عیب‌یابی Plugin**: هرگونه هشدار یا خطای زمان load صادرشده توسط registry Plugin را نمایش می‌دهد. - - Doctor بررسی می‌کند آیا فایل‌های bootstrap workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا سایر فایل‌های context تزریق‌شده) نزدیک یا فراتر از بودجه کاراکتر پیکربندی‌شده هستند یا نه. تعداد کاراکتر خام در برابر تزریق‌شده برای هر فایل، درصد truncation، علت truncation (`max/file` یا `max/total`)، و کل کاراکترهای تزریق‌شده به‌عنوان کسری از کل بودجه را گزارش می‌کند. وقتی فایل‌ها truncate شده‌اند یا نزدیک حد هستند، Doctor نکاتی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند. + + Doctor بررسی می‌کند که آیا فایل‌های bootstrap مربوط به workspace (برای مثال `AGENTS.md`، `CLAUDE.md`، یا فایل‌های context تزریق‌شده‌ی دیگر) نزدیک به بودجه‌ی کاراکتر پیکربندی‌شده هستند یا از آن عبور کرده‌اند. برای هر فایل، تعداد کاراکترهای raw در برابر injected، درصد truncation، علت truncation (`max/file` یا `max/total`)، و مجموع کاراکترهای injected را به‌عنوان کسری از بودجه‌ی کل گزارش می‌کند. وقتی فایل‌ها trunc شده‌اند یا نزدیک به limit هستند، doctor نکته‌هایی برای تنظیم `agents.defaults.bootstrapMaxChars` و `agents.defaults.bootstrapTotalMaxChars` چاپ می‌کند. - - وقتی `openclaw doctor --fix` یک Plugin کانال گمشده را حذف می‌کند، config آویزانِ scoped به کانال را که به آن Plugin ارجاع داده بود نیز حذف می‌کند: ورودی‌های `channels.`، target های Heartbeat که نام کانال را آورده بودند، و override های `agents.*.models["/*"]`. این از loop های بوت Gateway جلوگیری می‌کند که در آن runtime کانال حذف شده اما config هنوز از Gateway می‌خواهد به آن bind شود. + + وقتی `openclaw doctor --fix` یک Plugin کانال گم‌شده را حذف می‌کند، پیکربندی آویزانِ scoped به کانال را نیز که به آن Plugin ارجاع داده بود حذف می‌کند: ورودی‌های `channels.`، هدف‌های Heartbeat که نام کانال را آورده بودند، و overrideهای `agents.*.models["/*"]`. این از boot loopهای Gateway جلوگیری می‌کند که در آن runtime کانال از بین رفته اما پیکربندی هنوز از gateway می‌خواهد به آن bind شود. - - Doctor بررسی می‌کند آیا تکمیل tab برای shell فعلی (zsh، bash، fish، یا PowerShell) نصب شده است یا نه: + + Doctor بررسی می‌کند که آیا تکمیل tab برای shell فعلی نصب شده است یا نه (zsh، bash، fish، یا PowerShell): - - اگر پروفایل shell از الگوی تکمیل dynamic کند (`source <(openclaw completion ...)`) استفاده کند، Doctor آن را به نوع سریع‌تر فایل cache شده ارتقا می‌دهد. - - اگر تکمیل در پروفایل پیکربندی شده باشد اما فایل cache وجود نداشته باشد، Doctor به‌طور خودکار cache را دوباره تولید می‌کند. - - اگر هیچ تکمیلی اصلا پیکربندی نشده باشد، Doctor برای نصب آن درخواست تایید می‌کند (فقط حالت تعاملی؛ با `--non-interactive` نادیده گرفته می‌شود). + - اگر profile shell از الگوی تکمیل dynamic کند (`source <(openclaw completion ...)`) استفاده کند، doctor آن را به variant سریع‌ترِ فایل cacheشده ارتقا می‌دهد. + - اگر تکمیل در profile پیکربندی شده باشد اما فایل cache وجود نداشته باشد، doctor به‌صورت خودکار cache را دوباره تولید می‌کند. + - اگر هیچ تکمیلی اصلاً پیکربندی نشده باشد، doctor برای نصب آن prompt می‌دهد (فقط حالت interactive؛ با `--non-interactive` نادیده گرفته می‌شود). - برای تولید دوباره cache به‌صورت دستی، `openclaw completion --write-state` را اجرا کنید. + برای تولید دوباره‌ی cache به‌صورت دستی، `openclaw completion --write-state` را اجرا کنید. Doctor آمادگی احراز هویت token محلی Gateway را بررسی می‌کند. - - اگر حالت token به token نیاز داشته باشد و هیچ منبع token وجود نداشته باشد، Doctor پیشنهاد تولید یکی را می‌دهد. - - اگر `gateway.auth.token` توسط SecretRef مدیریت شود اما در دسترس نباشد، Doctor هشدار می‌دهد و آن را با plaintext بازنویسی نمی‌کند. - - `openclaw doctor --generate-gateway-token` فقط وقتی تولید را اجباری می‌کند که هیچ token SecretRef پیکربندی نشده باشد. + - اگر حالت token به token نیاز داشته باشد و هیچ منبع token وجود نداشته باشد، doctor پیشنهاد می‌دهد یکی تولید کند. + - اگر `gateway.auth.token` با SecretRef مدیریت شود اما در دسترس نباشد، doctor هشدار می‌دهد و آن را با plaintext بازنویسی نمی‌کند. + - `openclaw doctor --generate-gateway-token` فقط وقتی هیچ SecretRef مربوط به token پیکربندی نشده باشد، تولید را اجبار می‌کند. - - برخی جریان‌های ترمیم باید credentials پیکربندی‌شده را بدون تضعیف رفتار runtime fail-fast بررسی کنند. + + برخی جریان‌های ترمیم باید credentials پیکربندی‌شده را بدون تضعیف رفتار fail-fast در runtime بررسی کنند. - - `openclaw doctor --fix` اکنون برای ترمیم‌های هدفمند config از همان مدل خلاصه SecretRef فقط‌خواندنی استفاده می‌کند که command های خانواده status استفاده می‌کنند. - - مثال: ترمیم `allowFrom` / `groupAllowFrom` `@username` در Telegram تلاش می‌کند وقتی credentials بات پیکربندی‌شده در دسترس هستند، از آن‌ها استفاده کند. - - اگر token بات Telegram از طریق SecretRef پیکربندی شده اما در مسیر command فعلی در دسترس نباشد، Doctor گزارش می‌کند که credential پیکربندی‌شده-اما-ناموجود است و به‌جای crash کردن یا گزارش نادرستِ گمشده بودن token، auto-resolution را نادیده می‌گیرد. + - `openclaw doctor --fix` اکنون برای ترمیم‌های هدفمند پیکربندی، از همان مدل خلاصه‌ی read-only SecretRef مانند فرمان‌های خانواده‌ی status استفاده می‌کند. + - مثال: ترمیم `allowFrom` / `groupAllowFrom` مربوط به Telegram `@username` تلاش می‌کند در صورت دسترس بودن، از credentials پیکربندی‌شده‌ی bot استفاده کند. + - اگر token bot در Telegram از طریق SecretRef پیکربندی شده باشد اما در مسیر فرمان فعلی در دسترس نباشد، doctor گزارش می‌کند که credential پیکربندی‌شده اما در دسترس نیست و به‌جای crash کردن یا گزارش نادرست token به‌عنوان missing، auto-resolution را رد می‌کند. - Doctor بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد restart کردن آن را می‌دهد. + Doctor یک بررسی سلامت اجرا می‌کند و وقتی Gateway ناسالم به نظر برسد، پیشنهاد راه‌اندازی مجدد آن را می‌دهد. - - Doctor بررسی می‌کند آیا provider embedding جست‌وجوی حافظه پیکربندی‌شده برای agent پیش‌فرض آماده است یا نه. رفتار به backend و provider پیکربندی‌شده بستگی دارد: + + Doctor بررسی می‌کند که آیا provider مربوط به embedding جست‌وجوی memory پیکربندی‌شده برای agent پیش‌فرض آماده است یا نه. رفتار به backend و provider پیکربندی‌شده بستگی دارد: - - **backend QMD**: بررسی می‌کند آیا binary `qmd` در دسترس و قابل start است یا نه. اگر نباشد، راهنمای رفع شامل package npm و گزینه مسیر binary دستی را چاپ می‌کند. - - **provider محلی صریح**: وجود فایل مدل محلی یا URL مدل remote/downloadable شناخته‌شده را بررسی می‌کند. اگر وجود نداشته باشد، پیشنهاد می‌کند به provider remote تغییر دهید. - - **provider remote صریح** (`openai`، `voyage`، و غیره): بررسی می‌کند API key در environment یا auth store وجود دارد. اگر وجود نداشته باشد، راهنمای رفع قابل اقدام چاپ می‌کند. + - **QMD backend**: بررسی می‌کند که آیا binary مربوط به `qmd` در دسترس و قابل شروع است یا نه. اگر نباشد، راهنمایی رفع شامل بسته‌ی npm و گزینه‌ی مسیر binary دستی را چاپ می‌کند. + - **provider محلی صریح**: وجود یک فایل مدل محلی یا URL مدل remote/downloadable شناخته‌شده را بررسی می‌کند. اگر وجود نداشته باشد، پیشنهاد تغییر به یک provider remote را می‌دهد. + - **provider remote صریح** (`openai`، `voyage`، و غیره): تأیید می‌کند که یک API key در محیط یا auth store وجود دارد. اگر گم شده باشد، hintهای رفع قابل اقدام چاپ می‌کند. - **provider خودکار**: ابتدا دسترس‌پذیری مدل محلی را بررسی می‌کند، سپس هر provider remote را به‌ترتیب auto-selection امتحان می‌کند. - وقتی نتیجه probe cache شده Gateway در دسترس باشد (Gateway هنگام بررسی سالم بوده است)، Doctor نتیجه آن را با config قابل مشاهده از CLI تطبیق می‌دهد و هر اختلافی را ذکر می‌کند. Doctor در مسیر پیش‌فرض ping تازه embedding را start نمی‌کند؛ وقتی بررسی زنده provider می‌خواهید، از command وضعیت حافظه deep استفاده کنید. + وقتی نتیجه‌ی cached مربوط به probe در Gateway در دسترس باشد (Gateway در زمان بررسی سالم بوده است)، doctor نتیجه‌ی آن را با پیکربندی قابل مشاهده برای CLI تطبیق می‌دهد و هر discrepancy را یادداشت می‌کند. Doctor در مسیر پیش‌فرض یک embedding ping تازه شروع نمی‌کند؛ وقتی بررسی زنده‌ی provider می‌خواهید، از فرمان deep memory status استفاده کنید. - برای تایید آمادگی embedding در runtime، `openclaw memory status --deep` را استفاده کنید. + برای تأیید آمادگی embedding در runtime، `openclaw memory status --deep` را استفاده کنید. - اگر Gateway سالم باشد، Doctor یک probe وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌دهد. + اگر Gateway سالم باشد، doctor یک probe وضعیت کانال اجرا می‌کند و هشدارها را همراه با رفع‌های پیشنهادی گزارش می‌کند. - - Doctor config نصب‌شده supervisor (launchd/systemd/schtasks) را برای defaults گمشده یا قدیمی (مثلا وابستگی‌های systemd network-online و تاخیر restart) بررسی می‌کند. وقتی عدم تطابق پیدا کند، به‌روزرسانی را توصیه می‌کند و می‌تواند فایل سرویس/task را به defaults فعلی بازنویسی کند. + + Doctor پیکربندی supervisor نصب‌شده (launchd/systemd/schtasks) را برای پیش‌فرض‌های گم‌شده یا قدیمی بررسی می‌کند (مثلاً وابستگی‌های systemd network-online و تأخیر restart). وقتی mismatch پیدا کند، یک update را توصیه می‌کند و می‌تواند فایل service/task را با پیش‌فرض‌های فعلی دوباره بنویسد. - نکات: + نکته‌ها: - - `openclaw doctor` پیش از بازنویسی config supervisor درخواست تایید می‌کند. - - `openclaw doctor --yes` prompt های ترمیم پیش‌فرض را می‌پذیرد. - - `openclaw doctor --repair` رفع‌های توصیه‌شده را بدون prompt اعمال می‌کند. - - `openclaw doctor --repair --force` config های سفارشی supervisor را بازنویسی می‌کند. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` برای چرخه‌عمر سرویس Gateway، Doctor را فقط‌خواندنی نگه می‌دارد. همچنان سلامت سرویس را گزارش می‌کند و ترمیم‌های غیرسرویسی را اجرا می‌کند، اما نصب/start/restart/bootstrap سرویس، بازنویسی‌های config supervisor، و پاک‌سازی سرویس قدیمی را نادیده می‌گیرد چون یک supervisor خارجی مالک آن چرخه‌عمر است. - - در Linux، Doctor metadata مربوط به command/entrypoint را زمانی که unit مطابق Gateway در systemd فعال است بازنویسی نمی‌کند. همچنین هنگام اسکن duplicate-service، unit های غیرفعال غیرقدیمی اضافیِ شبیه Gateway را نادیده می‌گیرد تا فایل‌های سرویس همراه نویز پاک‌سازی ایجاد نکنند. - - اگر احراز هویت token به token نیاز داشته باشد و `gateway.auth.token` توسط SecretRef مدیریت شود، نصب/ترمیم سرویس Doctor، SecretRef را validate می‌کند اما مقدارهای token plaintext حل‌شده را در metadata محیط سرویس supervisor ماندگار نمی‌کند. - - Doctor مقدارهای محیط سرویس مبتنی بر `.env`/SecretRef مدیریت‌شده را که نصب‌های قدیمی‌تر LaunchAgent، systemd، یا Windows Scheduled Task به‌صورت inline تعبیه کرده‌اند تشخیص می‌دهد و metadata سرویس را بازنویسی می‌کند تا آن مقدارها به‌جای definition supervisor از منبع runtime load شوند. - - Doctor تشخیص می‌دهد چه زمانی command سرویس پس از تغییر `gateway.port` هنوز یک `--port` قدیمی را pin کرده است و metadata سرویس را به پورت فعلی بازنویسی می‌کند. - - اگر احراز هویت token به token نیاز داشته باشد و token SecretRef پیکربندی‌شده حل‌نشده باشد، Doctor مسیر نصب/ترمیم را با راهنمای قابل اقدام مسدود می‌کند. - - اگر هم `gateway.auth.token` و هم `gateway.auth.password` پیکربندی شده باشند و `gateway.auth.mode` تنظیم نشده باشد، Doctor نصب/ترمیم را تا زمانی که mode صریحا تنظیم شود مسدود می‌کند. - - برای unit های user-systemd در Linux، بررسی‌های انحراف token در Doctor اکنون هنگام مقایسه metadata احراز هویت سرویس، هر دو منبع `Environment=` و `EnvironmentFile=` را شامل می‌شود. - - ترمیم‌های سرویس Doctor از بازنویسی، stop کردن، یا restart کردن یک سرویس Gateway از binary قدیمی‌تر OpenClaw خودداری می‌کنند وقتی config آخرین بار توسط نسخه جدیدتری نوشته شده باشد. به [عیب‌یابی Gateway](/fa/gateway/troubleshooting#split-brain-installs-and-newer-config-guard) مراجعه کنید. - - همیشه می‌توانید با `openclaw gateway install --force` یک بازنویسی کامل را اجبار کنید. + - `openclaw doctor` پیش از بازنویسی پیکربندی سرپرست درخواست تأیید می‌کند. + - `openclaw doctor --yes` درخواست‌های تعمیر پیش‌فرض را می‌پذیرد. + - `openclaw doctor --repair` اصلاحات پیشنهادی را بدون درخواست تأیید اعمال می‌کند. + - `openclaw doctor --repair --force` پیکربندی‌های سفارشی سرپرست را بازنویسی می‌کند. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` دستور doctor را برای چرخهٔ عمر سرویس Gateway فقط-خواندنی نگه می‌دارد. همچنان سلامت سرویس را گزارش می‌کند و تعمیرهای غیرسرویسی را اجرا می‌کند، اما نصب/شروع/راه‌اندازی مجدد/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 نصب/تعمیر را تا زمانی که حالت به‌صورت صریح تنظیم شود مسدود می‌کند. + - برای واحدهای user-systemd در Linux، بررسی‌های drift توکن در doctor اکنون هنگام مقایسهٔ فرادادهٔ احراز هویت سرویس، هم منابع `Environment=` و هم `EnvironmentFile=` را شامل می‌شود. + - تعمیرهای سرویس doctor از بازنویسی، توقف، یا راه‌اندازی مجدد یک سرویس Gateway از یک باینری قدیمی‌تر OpenClaw خودداری می‌کنند، وقتی پیکربندی آخرین بار توسط نسخه‌ای جدیدتر نوشته شده باشد. [عیب‌یابی Gateway](/fa/gateway/troubleshooting#split-brain-installs-and-newer-config-guard) را ببینید. + - همیشه می‌توانید از طریق `openclaw gateway install --force` یک بازنویسی کامل را اجبار کنید. - Doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و زمانی هشدار می‌دهد که سرویس نصب شده اما واقعاً در حال اجرا نیست. همچنین تداخل‌های پورت روی پورت Gateway (پیش‌فرض `18789`) را بررسی می‌کند و علت‌های محتمل (Gateway از قبل در حال اجرا است، تونل SSH) را گزارش می‌دهد. + دستور doctor زمان اجرای سرویس (PID، آخرین وضعیت خروج) را بررسی می‌کند و وقتی سرویس نصب شده اما واقعاً در حال اجرا نیست هشدار می‌دهد. همچنین تداخل‌های پورت را روی پورت Gateway (پیش‌فرض `18789`) بررسی می‌کند و علت‌های محتمل را گزارش می‌دهد (Gateway از قبل در حال اجرا است، تونل SSH). - - Doctor زمانی هشدار می‌دهد که سرویس Gateway روی Bun یا مسیر Node مدیریت‌شده با نسخه (`nvm`، `fnm`، `volta`، `asdf` و غیره) اجرا شود. کانال‌های WhatsApp + Telegram به Node نیاز دارند، و مسیرهای مدیر نسخه می‌توانند پس از ارتقاها خراب شوند چون سرویس مقداردهی اولیه شل شما را بارگذاری نمی‌کند. Doctor پیشنهاد می‌دهد در صورت وجود نصب سیستمی Node (Homebrew/apt/choco)، به آن مهاجرت کنید. + + دستور doctor وقتی سرویس Gateway روی Bun یا یک مسیر Node مدیریت‌شده با نسخه‌مدیر (`nvm`، `fnm`، `volta`، `asdf` و غیره) اجرا می‌شود هشدار می‌دهد. کانال‌های WhatsApp + Telegram به Node نیاز دارند، و مسیرهای نسخه‌مدیر می‌توانند پس از ارتقا خراب شوند، چون سرویس init شل شما را بارگذاری نمی‌کند. دستور doctor پیشنهاد می‌دهد در صورت موجود بودن، به نصب سیستمی Node مهاجرت کنید (Homebrew/apt/choco). - سرویس‌هایی که تازه نصب یا تعمیر شده‌اند ریشه‌های محیطی صریح (`NVM_DIR`، `FNM_DIR`، `VOLTA_HOME`، `ASDF_DATA_DIR`، `BUN_INSTALL`، `PNPM_HOME`) و دایرکتوری‌های پایدار user-bin را نگه می‌دارند، اما دایرکتوری‌های جایگزین حدسی مدیر نسخه فقط زمانی در PATH سرویس نوشته می‌شوند که آن دایرکتوری‌ها روی دیسک وجود داشته باشند. این کار PATH ناظر تولیدشده را با همان ممیزی حداقلی PATH که Doctor بعداً اجرا می‌کند هم‌راستا نگه می‌دارد. + سرویس‌های تازه نصب‌شده یا تعمیرشده ریشه‌های محیطی صریح (`NVM_DIR`، `FNM_DIR`، `VOLTA_HOME`، `ASDF_DATA_DIR`، `BUN_INSTALL`، `PNPM_HOME`) و دایرکتوری‌های پایدار user-bin را نگه می‌دارند، اما دایرکتوری‌های fallback حدسیِ نسخه‌مدیر فقط وقتی در PATH سرویس نوشته می‌شوند که آن دایرکتوری‌ها روی دیسک وجود داشته باشند. این کار PATH سرپرست تولیدشده را با همان ممیزی حداقلی PATH که doctor بعداً اجرا می‌کند هم‌راستا نگه می‌دارد. - - Doctor هرگونه تغییر پیکربندی را پایدار می‌کند و فراداده ویزارد را برای ثبت اجرای Doctor مهر می‌زند. + + دستور doctor هرگونه تغییر پیکربندی را ذخیره می‌کند و برای ثبت اجرای doctor، فرادادهٔ ویزارد را مهر می‌کند. - - Doctor هنگام نبود سامانه حافظه فضای کاری، آن را پیشنهاد می‌دهد و اگر فضای کاری از قبل زیر git نباشد، یک نکته پشتیبان‌گیری چاپ می‌کند. + + دستور doctor وقتی سامانهٔ حافظهٔ فضای کاری وجود ندارد آن را پیشنهاد می‌دهد و اگر فضای کاری از قبل زیر git نباشد، یک نکتهٔ پشتیبان‌گیری چاپ می‌کند. برای راهنمای کامل ساختار فضای کاری و پشتیبان‌گیری با git (GitHub یا GitLab خصوصی توصیه می‌شود)، [/concepts/agent-workspace](/fa/concepts/agent-workspace) را ببینید. diff --git a/docs/fa/gateway/gateway-lock.md b/docs/fa/gateway/gateway-lock.md index 9101309c3..930930ad5 100644 --- a/docs/fa/gateway/gateway-lock.md +++ b/docs/fa/gateway/gateway-lock.md @@ -1,42 +1,42 @@ --- read_when: - اجرای فرایند Gateway یا اشکال‌زدایی آن - - بررسی الزام تک‌نمونه‌ای بودن -summary: محافظ تک‌نمونه Gateway با استفاده از اتصال شنونده WebSocket + - بررسی اعمال تک‌نمونه‌ای +summary: محافظ تک‌نمونهٔ Gateway با استفاده از اتصال شنوندهٔ WebSocket title: قفل Gateway x-i18n: - generated_at: "2026-04-29T22:51:36Z" + generated_at: "2026-04-30T16:29:35Z" model: gpt-5.5 provider: openai - source_hash: fe61ff81106554e98de1ca04c213b76d230265cdf3e81b70897d2de00f6a0179 + source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13 source_path: gateway/gateway-lock.md workflow: 16 --- ## چرا -- اطمینان از اینکه فقط یک نمونه Gateway برای هر پورت پایه روی همان میزبان اجرا می‌شود؛ Gatewayهای اضافی باید از پروفایل‌های ایزوله و پورت‌های یکتا استفاده کنند. -- تحمل خرابی‌ها/`SIGKILL` بدون باقی گذاشتن فایل‌های قفل کهنه. -- وقتی پورت کنترل از قبل اشغال است، سریع و با خطایی روشن شکست بخورد. +- اطمینان حاصل کنید که روی همان میزبان، برای هر پورت پایه فقط یک نمونه Gateway اجرا می‌شود؛ Gatewayهای اضافی باید از پروفایل‌های ایزوله و پورت‌های یکتا استفاده کنند. +- پس از کرش/SIGKILL بدون باقی گذاشتن فایل‌های قفل کهنه، دوام بیاورد. +- وقتی پورت کنترل از قبل اشغال شده است، با خطایی روشن سریع شکست بخورد. ## سازوکار -- Gateway ابتدا یک فایل قفل مخصوص هر پیکربندی را زیر دایرکتوری قفل وضعیت می‌گیرد و پورت پیکربندی‌شده را برای وجود یک شنونده بررسی می‌کند. -- اگر مالک ثبت‌شده‌ی قفل دیگر وجود نداشته باشد، پورت آزاد باشد، یا قفل کهنه باشد، راه‌اندازی قفل را بازپس می‌گیرد و ادامه می‌دهد. -- سپس Gateway شنونده HTTP/WebSocket را (به‌طور پیش‌فرض `ws://127.0.0.1:18789`) با استفاده از یک شنونده TCP انحصاری bind می‌کند. -- اگر bind با `EADDRINUSE` شکست بخورد، راه‌اندازی `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:")` را پرتاب می‌کند. -- هنگام خاموش‌سازی، Gateway سرور HTTP/WebSocket را می‌بندد و فایل قفل را حذف می‌کند. +- Gateway ابتدا یک فایل قفل برای هر پیکربندی را زیر دایرکتوری قفل وضعیت می‌گیرد و پورت پیکربندی‌شده را برای وجود یک شنونده فعلی بررسی می‌کند. +- اگر مالک قفل ثبت‌شده دیگر وجود نداشته باشد، پورت آزاد باشد، یا قفل کهنه باشد، راه‌اندازی قفل را بازپس می‌گیرد و ادامه می‌دهد. +- سپس Gateway شنونده HTTP/WebSocket را (پیش‌فرض `ws://127.0.0.1:18789`) با استفاده از یک شنونده TCP انحصاری متصل می‌کند. +- اگر اتصال با `EADDRINUSE` شکست بخورد، راه‌اندازی `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:")` را پرتاب می‌کند. +- هنگام خاموشی، Gateway سرور HTTP/WebSocket را می‌بندد و فایل قفل را حذف می‌کند. ## سطح خطا - اگر فرایند دیگری پورت را در اختیار داشته باشد، راه‌اندازی `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:")` را پرتاب می‌کند. -- سایر شکست‌های bind به‌صورت `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:: …")` بروز می‌کنند. +- سایر شکست‌های اتصال به صورت `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:: …")` نمایان می‌شوند. ## نکات عملیاتی -- اگر پورت توسط فرایند _دیگری_ اشغال شده باشد، خطا همان است؛ پورت را آزاد کنید یا با `openclaw gateway --port ` پورت دیگری انتخاب کنید. -- زیر نظر یک ناظر سرویس، فرایند Gateway جدیدی که یک پاسخ‌دهنده سالم موجود برای `/healthz` ببیند، با موفقیت خارج می‌شود و کنترل را به همان فرایند واگذار می‌کند. اگر فرایند موجود هرگز سالم نشود، تلاش‌های مجدد محدود هستند و راه‌اندازی به‌جای حلقه زدن برای همیشه، با یک خطای قفل روشن شکست می‌خورد. -- برنامه macOS همچنان پیش از ایجاد Gateway محافظ سبک PID خودش را نگه می‌دارد؛ قفل زمان اجرا با فایل قفل به‌همراه bind مربوط به HTTP/WebSocket اعمال می‌شود. +- اگر پورت توسط فرایند _دیگری_ اشغال شده باشد، خطا یکسان است؛ پورت را آزاد کنید یا با `openclaw gateway --port ` پورت دیگری انتخاب کنید. +- زیر یک ناظر سرویس، فرایند Gateway جدیدی که یک پاسخ‌دهنده سالم فعلی `/healthz` را می‌بیند، کنترل را در اختیار همان فرایند می‌گذارد. در systemd، راه‌انداز تکراری با کد 78 خارج می‌شود تا مقدار پیش‌فرض `RestartPreventExitStatus=78` مانع شود `Restart=always` در برخورد با قفل یا تداخل `EADDRINUSE` وارد حلقه شود. اگر فرایند موجود هرگز سالم نشود، تلاش‌های دوباره محدود می‌شوند و راه‌اندازی به‌جای حلقه بی‌پایان، با خطای قفل روشن شکست می‌خورد. +- برنامه macOS همچنان پیش از ایجاد Gateway محافظ PID سبک خودش را نگه می‌دارد؛ قفل زمان اجرا با فایل قفل به‌علاوه اتصال HTTP/WebSocket اعمال می‌شود. ## مرتبط diff --git a/docs/fa/providers/deepseek.md b/docs/fa/providers/deepseek.md index 7b109a36e..5caabb2a5 100644 --- a/docs/fa/providers/deepseek.md +++ b/docs/fa/providers/deepseek.md @@ -1,21 +1,21 @@ --- read_when: - می‌خواهید از DeepSeek با OpenClaw استفاده کنید - - به متغیر محیطی کلید API یا گزینه احراز هویت CLI نیاز دارید + - به متغیر محیطی کلید API یا انتخاب احراز هویت CLI نیاز دارید summary: راه‌اندازی DeepSeek (احراز هویت + انتخاب مدل) title: DeepSeek x-i18n: - generated_at: "2026-04-29T23:24:27Z" + generated_at: "2026-04-30T16:29:54Z" model: gpt-5.5 provider: openai - source_hash: e84d989a7cba8d259779ac02293718050ce51efe6ce2bdbfacb9e22bbfd294ef + source_hash: 6fbc7bd4de14000eaa5c42b17eb8c9312321ed02ac1667e60774ead3f1749eb4 source_path: providers/deepseek.md workflow: 16 --- -[DeepSeek](https://www.deepseek.com) مدل‌های قدرتمند هوش مصنوعی را با API سازگار با OpenAI ارائه می‌کند. +[DeepSeek](https://www.deepseek.com) مدل‌های هوش مصنوعی قدرتمندی را با API سازگار با OpenAI ارائه می‌دهد. -| ویژگی | مقدار | +| ویژگی | مقدار | | -------- | -------------------------- | | ارائه‌دهنده | `deepseek` | | احراز هویت | `DEEPSEEK_API_KEY` | @@ -36,12 +36,12 @@ x-i18n: این دستور کلید API شما را درخواست می‌کند و `deepseek/deepseek-v4-flash` را به‌عنوان مدل پیش‌فرض تنظیم می‌کند. - + ```bash openclaw models list --provider deepseek ``` - برای بررسی کاتالوگ ایستای همراه بدون نیاز به Gateway در حال اجرا، + برای بررسی کاتالوگ ایستای همراه، بدون نیاز به Gateway در حال اجرا، از این استفاده کنید: ```bash @@ -53,7 +53,7 @@ x-i18n: - برای نصب‌های اسکریپت‌شده یا بدون رابط کاربری، همه فلگ‌ها را مستقیم وارد کنید: + برای نصب‌های اسکریپتی یا بدون رابط، همه پرچم‌ها را مستقیم ارسال کنید: ```bash openclaw onboard --non-interactive \ @@ -75,41 +75,43 @@ x-i18n: ## کاتالوگ داخلی -| ارجاع مدل | نام | ورودی | زمینه | حداکثر خروجی | یادداشت‌ها | +| ارجاع مدل | نام | ورودی | زمینه | بیشینه خروجی | یادداشت‌ها | | ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ | -| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | مدل پیش‌فرض؛ سطح V4 با قابلیت فکر کردن | -| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | سطح V4 با قابلیت فکر کردن | -| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | سطح DeepSeek V3.2 بدون فکر کردن | +| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | مدل پیش‌فرض؛ سطح V4 با قابلیت تفکر | +| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | سطح V4 با قابلیت تفکر | +| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | سطح بدون تفکر DeepSeek V3.2 | | `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | سطح V3.2 با قابلیت استدلال | مدل‌های V4 از کنترل `thinking` در DeepSeek پشتیبانی می‌کنند. OpenClaw همچنین -`reasoning_content` در DeepSeek را در نوبت‌های بعدی بازپخش می‌کند تا نشست‌های فکر کردن با فراخوانی ابزارها -بتوانند ادامه پیدا کنند. +`reasoning_content` مربوط به DeepSeek را در نوبت‌های بعدی بازپخش می‌کند تا نشست‌های تفکر همراه با +فراخوانی ابزارها بتوانند ادامه پیدا کنند. +برای درخواست بیشینه `reasoning_effort` در DeepSeek، +از `/think xhigh` یا `/think max` با مدل‌های DeepSeek V4 استفاده کنید. -## فکر کردن و ابزارها +## تفکر و ابزارها -نشست‌های فکر کردن DeepSeek V4 نسبت به بیشتر ارائه‌دهنده‌های سازگار با OpenAI -قرارداد بازپخش سخت‌گیرانه‌تری دارند: پس از آن‌که یک نوبت با فکر کردن فعال از ابزارها استفاده کند، DeepSeek -انتظار دارد پیام‌های assistant بازپخش‌شده از آن نوبت در درخواست‌های بعدی شامل -`reasoning_content` باشند. OpenClaw این موضوع را در Plugin -DeepSeek مدیریت می‌کند، بنابراین استفاده عادی چندنوبتی از ابزارها با +نشست‌های تفکر DeepSeek V4 نسبت به بیشتر ارائه‌دهندگان سازگار با OpenAI +قرارداد بازپخش سخت‌گیرانه‌تری دارند: پس از اینکه یک نوبت با تفکر فعال از ابزارها استفاده کند، DeepSeek +انتظار دارد پیام‌های assistant بازپخش‌شده از آن نوبت، در درخواست‌های بعدی شامل +`reasoning_content` باشند. OpenClaw این مورد را داخل +Plugin مربوط به DeepSeek مدیریت می‌کند، بنابراین استفاده عادی چندنوبتی از ابزارها با `deepseek/deepseek-v4-flash` و `deepseek/deepseek-v4-pro` کار می‌کند. اگر یک نشست موجود را از ارائه‌دهنده سازگار با OpenAI دیگری به یک -مدل DeepSeek V4 تغییر دهید، نوبت‌های قدیمی‌تر فراخوانی ابزار assistant ممکن است -`reasoning_content` بومی DeepSeek نداشته باشند. OpenClaw این فیلد گمشده را هنگام بازپخش -پیام‌های assistant برای درخواست‌های فکر کردن DeepSeek V4 پر می‌کند تا ارائه‌دهنده بتواند +مدل DeepSeek V4 تغییر دهید، نوبت‌های قدیمی‌تر فراخوانی ابزار توسط assistant ممکن است +`reasoning_content` بومی DeepSeek را نداشته باشند. OpenClaw هنگام بازپخش +پیام‌های assistant برای درخواست‌های تفکر DeepSeek V4، آن فیلد ازدست‌رفته را پر می‌کند تا ارائه‌دهنده بتواند تاریخچه را بدون نیاز به `/new` بپذیرد. -وقتی فکر کردن در OpenClaw غیرفعال است (از جمله انتخاب **None** در UI)، -OpenClaw مقدار `thinking: { type: "disabled" }` را برای DeepSeek ارسال می‌کند و -`reasoning_content` بازپخش‌شده را از تاریخچه خروجی حذف می‌کند. این کار نشست‌های با فکر کردن غیرفعال را -در مسیر بدون فکر کردن DeepSeek نگه می‌دارد. +وقتی تفکر در OpenClaw غیرفعال باشد (از جمله انتخاب **None** در UI)، +OpenClaw مقدار `thinking: { type: "disabled" }` را به DeepSeek می‌فرستد و +`reasoning_content` بازپخش‌شده را از تاریخچه خروجی حذف می‌کند. این کار نشست‌های +با تفکر غیرفعال را در مسیر بدون تفکر DeepSeek نگه می‌دارد. -برای مسیر سریع پیش‌فرض از `deepseek/deepseek-v4-flash` استفاده کنید. وقتی مدل V4 -قوی‌تر را می‌خواهید و می‌توانید هزینه یا تأخیر بالاتر را بپذیرید، از +برای مسیر سریع پیش‌فرض از `deepseek/deepseek-v4-flash` استفاده کنید. وقتی +مدل V4 قوی‌تر را می‌خواهید و می‌توانید هزینه یا تأخیر بیشتر را بپذیرید، از `deepseek/deepseek-v4-pro` استفاده کنید. ## آزمون زنده @@ -123,8 +125,8 @@ OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \ pnpm test:live src/agents/models.profiles.live.test.ts ``` -این بررسی زنده تأیید می‌کند که هر دو مدل V4 می‌توانند کامل شوند و نوبت‌های بعدی فکر کردن/ابزار -payload بازپخشی را که DeepSeek نیاز دارد حفظ می‌کنند. +این بررسی زنده تأیید می‌کند که هر دو مدل V4 می‌توانند تکمیل شوند و نوبت‌های بعدی تفکر/ابزار +محموله بازپخشی را که DeepSeek نیاز دارد حفظ می‌کنند. ## نمونه پیکربندی @@ -143,9 +145,9 @@ payload بازپخشی را که DeepSeek نیاز دارد حفظ می‌کنن - انتخاب ارائه‌دهنده‌ها، ارجاع‌های مدل، و رفتار failover. + انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover. - مرجع کامل پیکربندی برای عامل‌ها، مدل‌ها، و ارائه‌دهنده‌ها. + مرجع کامل پیکربندی برای agents، مدل‌ها، و ارائه‌دهندگان. diff --git a/docs/fa/providers/openai.md b/docs/fa/providers/openai.md index f0d09b739..010b5aab1 100644 --- a/docs/fa/providers/openai.md +++ b/docs/fa/providers/openai.md @@ -2,83 +2,99 @@ read_when: - می‌خواهید از مدل‌های OpenAI در OpenClaw استفاده کنید - می‌خواهید به‌جای کلیدهای API از احراز هویت اشتراک Codex استفاده کنید - - به رفتار اجرای سخت‌گیرانه‌تری برای عامل GPT-5 نیاز دارید -summary: از OpenAI از طریق کلیدهای API یا اشتراک Codex در OpenClaw استفاده کنید + - به رفتار اجرایی سخت‌گیرانه‌تری برای عامل GPT-5 نیاز دارید +summary: استفاده از OpenAI از طریق کلیدهای API یا اشتراک Codex در OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-29T23:27:20Z" + generated_at: "2026-04-30T16:30:36Z" model: gpt-5.5 provider: openai - source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8 + source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad source_path: providers/openai.md workflow: 16 --- -OpenAI APIهای توسعه‌دهنده را برای مدل‌های GPT فراهم می‌کند، و Codex نیز به‌عنوان یک عامل کدنویسی مبتنی بر طرح ChatGPT از طریق کلاینت‌های Codex متعلق به OpenAI در دسترس است. OpenClaw این سطوح را جدا نگه می‌دارد تا پیکربندی قابل پیش‌بینی بماند. +OpenAI APIهای توسعه‌دهنده را برای مدل‌های GPT ارائه می‌کند، و Codex نیز به‌عنوان یک عامل کدنویسیِ طرح ChatGPT از طریق کلاینت‌های Codex متعلق به OpenAI در دسترس است. OpenClaw این +سطح‌ها را جدا نگه می‌دارد تا پیکربندی قابل پیش‌بینی بماند. -OpenClaw از سه مسیر خانواده OpenAI پشتیبانی می‌کند. پیشوند مدل مسیر ارائه‌دهنده/احراز هویت را انتخاب می‌کند؛ یک تنظیم جداگانه زمان اجرا انتخاب می‌کند چه کسی حلقه عامل تعبیه‌شده را اجرا کند: +OpenClaw از سه مسیر خانواده OpenAI پشتیبانی می‌کند. پیشوند مدل، مسیر +ارائه‌دهنده/احراز هویت را انتخاب می‌کند؛ یک تنظیم زمان اجرای جداگانه انتخاب می‌کند چه کسی حلقه +عامل تعبیه‌شده را اجرا کند: - **کلید API** — دسترسی مستقیم به OpenAI Platform با صورت‌حساب مبتنی بر مصرف (مدل‌های `openai/*`) - **اشتراک Codex از طریق PI** — ورود ChatGPT/Codex با دسترسی اشتراکی (مدل‌های `openai-codex/*`) -- **سازوکار app-server در Codex** — اجرای بومی app-server در Codex (مدل‌های `openai/*` به‌همراه `agents.defaults.agentRuntime.id: "codex"`) +- **مهار app-server متعلق به Codex** — اجرای بومی app-server متعلق به Codex (مدل‌های `openai/*` به‌همراه `agents.defaults.agentRuntime.id: "codex"`) -OpenAI به‌صراحت از استفاده OAuth اشتراکی در ابزارها و گردش‌کارهای خارجی مانند OpenClaw پشتیبانی می‌کند. +OpenAI صراحتا استفاده از OAuth اشتراکی را در ابزارها و گردش‌کارهای خارجی مانند OpenClaw پشتیبانی می‌کند. -ارائه‌دهنده، مدل، زمان اجرا، و کانال لایه‌های جداگانه‌ای هستند. اگر این برچسب‌ها با هم مخلوط می‌شوند، پیش از تغییر پیکربندی [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) را بخوانید. +ارائه‌دهنده، مدل، زمان اجرا، و کانال لایه‌های جداگانه‌اند. اگر این برچسب‌ها با هم +قاطی می‌شوند، پیش از تغییر پیکربندی [زمان‌های اجرای عامل](/fa/concepts/agent-runtimes) را بخوانید. ## انتخاب سریع -| هدف | استفاده کنید | نکات | +| هدف | استفاده کنید از | یادداشت‌ها | | --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | -| صورت‌حساب مستقیم با کلید API | `openai/gpt-5.5` | `OPENAI_API_KEY` را تنظیم کنید یا راه‌اندازی کلید API برای OpenAI را اجرا کنید. | -| GPT-5.5 با احراز هویت اشتراک ChatGPT/Codex | `openai-codex/gpt-5.5` | مسیر پیش‌فرض PI برای OAuth در Codex. بهترین انتخاب اولیه برای راه‌اندازی‌های اشتراکی. | -| GPT-5.5 با رفتار بومی app-server در Codex | `openai/gpt-5.5` به‌همراه `agentRuntime.id: "codex"` | سازوکار app-server در Codex را برای آن ارجاع مدل اجباری می‌کند. | -| تولید یا ویرایش تصویر | `openai/gpt-image-2` | با `OPENAI_API_KEY` یا OAuth مربوط به OpenAI Codex کار می‌کند. | -| تصاویر با پس‌زمینه شفاف | `openai/gpt-image-1.5` | از `outputFormat=png` یا `webp` و `openai.background=transparent` استفاده کنید. | +| صورت‌حساب مستقیم با کلید API | `openai/gpt-5.5` | `OPENAI_API_KEY` را تنظیم کنید یا راه‌اندازی کلید API متعلق به OpenAI را اجرا کنید. | +| GPT-5.5 با احراز هویت اشتراک ChatGPT/Codex | `openai-codex/gpt-5.5` | مسیر پیش‌فرض PI برای OAuth متعلق به Codex. بهترین انتخاب اولیه برای راه‌اندازی‌های اشتراکی. | +| GPT-5.5 با رفتار بومی app-server متعلق به Codex | `openai/gpt-5.5` به‌همراه `agentRuntime.id: "codex"` | مهار app-server متعلق به Codex را برای آن ارجاع مدل اجبار می‌کند. | +| تولید یا ویرایش تصویر | `openai/gpt-image-2` | با `OPENAI_API_KEY` یا OpenAI Codex OAuth کار می‌کند. | +| تصاویر با پس‌زمینه شفاف | `openai/gpt-image-1.5` | از `outputFormat=png` یا `webp` و `openai.background=transparent` استفاده کنید. | ## نقشه نام‌گذاری -نام‌ها مشابه‌اند اما قابل جایگزینی با یکدیگر نیستند: +نام‌ها شبیه‌اند اما قابل جایگزینی نیستند: -| نامی که می‌بینید | لایه | معنا | +| نامی که می‌بینید | لایه | معنی | | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | -| `openai` | پیشوند ارائه‌دهنده | مسیر مستقیم API در OpenAI Platform. | -| `openai-codex` | پیشوند ارائه‌دهنده | مسیر OAuth/اشتراک OpenAI Codex از طریق اجراکننده عادی PI در OpenClaw. | -| Plugin مربوط به `codex` | Plugin | Plugin همراه OpenClaw که زمان اجرای بومی app-server در Codex و کنترل‌های گفت‌وگوی `/codex` را فراهم می‌کند. | -| `agentRuntime.id: codex` | زمان اجرای عامل | سازوکار بومی app-server در Codex را برای نوبت‌های تعبیه‌شده اجباری می‌کند. | -| `/codex ...` | مجموعه فرمان‌های گفت‌وگو | رشته‌های app-server در Codex را از داخل یک مکالمه متصل/کنترل می‌کند. | -| `runtime: "acp", agentId: "codex"` | مسیر نشست ACP | مسیر پشتیبان صریحی که Codex را از طریق ACP/acpx اجرا می‌کند. | +| `openai` | پیشوند ارائه‌دهنده | مسیر مستقیم API متعلق به OpenAI Platform. | +| `openai-codex` | پیشوند ارائه‌دهنده | مسیر OpenAI Codex OAuth/اشتراک از طریق اجراکننده معمول PI در OpenClaw. | +| Plugin متعلق به `codex` | Plugin | Plugin بسته‌شده OpenClaw که زمان اجرای بومی app-server متعلق به Codex و کنترل‌های گفت‌وگوی `/codex` را فراهم می‌کند. | +| `agentRuntime.id: codex` | زمان اجرای عامل | مهار بومی app-server متعلق به Codex را برای نوبت‌های تعبیه‌شده اجبار می‌کند. | +| `/codex ...` | مجموعه فرمان گفت‌وگو | رشته‌های app-server متعلق به Codex را از یک مکالمه متصل/کنترل می‌کند. | +| `runtime: "acp", agentId: "codex"` | مسیر نشست ACP | مسیر جایگزین صریحی که Codex را از طریق ACP/acpx اجرا می‌کند. | -این یعنی یک پیکربندی می‌تواند عمدا هم `openai-codex/*` و هم Plugin مربوط به `codex` را داشته باشد. وقتی هم OAuth مربوط به Codex را از طریق PI می‌خواهید و هم می‌خواهید کنترل‌های گفت‌وگوی بومی `/codex` در دسترس باشند، این معتبر است. `openclaw doctor` درباره آن ترکیب هشدار می‌دهد تا تأیید کنید عمدی است؛ آن را بازنویسی نمی‌کند. +این یعنی یک پیکربندی می‌تواند عمدا هم `openai-codex/*` و هم Plugin +`codex` را داشته باشد. وقتی OAuth متعلق به Codex را از طریق PI می‌خواهید و همچنین می‌خواهید +کنترل‌های گفت‌وگوی بومی `/codex` در دسترس باشند، این معتبر است. `openclaw doctor` درباره آن +ترکیب هشدار می‌دهد تا بتوانید تایید کنید که عمدی است؛ آن را بازنویسی نمی‌کند. -GPT-5.5 هم از طریق دسترسی مستقیم با کلید API به OpenAI Platform و هم از طریق مسیرهای اشتراک/OAuth در دسترس است. برای ترافیک مستقیم `OPENAI_API_KEY` از `openai/gpt-5.5`، برای OAuth مربوط به Codex از طریق PI از `openai-codex/gpt-5.5`، یا برای سازوکار بومی app-server در Codex از `openai/gpt-5.5` با `agentRuntime.id: "codex"` استفاده کنید. +GPT-5.5 هم از طریق دسترسی مستقیم با کلید API متعلق به OpenAI Platform و هم +مسیرهای اشتراک/OAuth در دسترس است. از `openai/gpt-5.5` برای ترافیک مستقیم +`OPENAI_API_KEY`، از `openai-codex/gpt-5.5` برای OAuth متعلق به Codex از طریق PI، یا +از `openai/gpt-5.5` همراه با `agentRuntime.id: "codex"` برای مهار بومی app-server +متعلق به Codex استفاده کنید. -فعال کردن Plugin مربوط به OpenAI، یا انتخاب یک مدل `openai-codex/*`، Plugin همراه app-server در Codex را فعال نمی‌کند. OpenClaw آن Plugin را فقط زمانی فعال می‌کند که سازوکار بومی Codex را با `agentRuntime.id: "codex"` صریحا انتخاب کنید یا از یک ارجاع مدل قدیمی `codex/*` استفاده کنید. -اگر Plugin همراه `codex` فعال باشد اما `openai-codex/*` همچنان از طریق PI resolve شود، `openclaw doctor` هشدار می‌دهد و مسیر را بدون تغییر باقی می‌گذارد. +فعال کردن Plugin متعلق به OpenAI، یا انتخاب یک مدل `openai-codex/*`، Plugin بسته‌شده +app-server متعلق به Codex را فعال نمی‌کند. OpenClaw آن Plugin را فقط زمانی فعال می‌کند +که مهار بومی Codex را با +`agentRuntime.id: "codex"` صراحتا انتخاب کنید یا از یک ارجاع مدل قدیمی `codex/*` استفاده کنید. +اگر Plugin بسته‌شده `codex` فعال باشد اما `openai-codex/*` همچنان از طریق PI حل شود، +`openclaw doctor` هشدار می‌دهد و مسیر را بدون تغییر می‌گذارد. ## پوشش قابلیت‌های OpenClaw -| قابلیت OpenAI | سطح OpenClaw | وضعیت | +| قابلیت OpenAI | سطح OpenClaw | وضعیت | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -| گفت‌وگو / Responses | ارائه‌دهنده مدل `openai/` | بله | -| مدل‌های اشتراک Codex | `openai-codex/` با OAuth مربوط به `openai-codex` | بله | -| سازوکار app-server در Codex | `openai/` با `agentRuntime.id: codex` | بله | -| جست‌وجوی وب سمت سرور | ابزار بومی OpenAI Responses | بله، وقتی جست‌وجوی وب فعال باشد و هیچ ارائه‌دهنده‌ای pin نشده باشد | +| گفت‌وگو / Responses | ارائه‌دهنده مدل `openai/` | بله | +| مدل‌های اشتراک Codex | `openai-codex/` با OAuth متعلق به `openai-codex` | بله | +| مهار app-server متعلق به Codex | `openai/` با `agentRuntime.id: codex` | بله | +| جست‌وجوی وب سمت سرور | ابزار بومی OpenAI Responses | بله، وقتی جست‌وجوی وب فعال باشد و هیچ ارائه‌دهنده‌ای سنجاق نشده باشد | | تصاویر | `image_generate` | بله | -| ویدئوها | `video_generate` | بله | -| متن به گفتار | `messages.tts.provider: "openai"` / `tts` | بله | -| گفتار به متن دسته‌ای | `tools.media.audio` / درک رسانه | بله | -| گفتار به متن جریانی | Voice Call `streaming.provider: "openai"` | بله | -| صدای بلادرنگ | Voice Call `realtime.provider: "openai"` / گفت‌وگوی Control UI | بله | -| Embeddings | ارائه‌دهنده embedding حافظه | بله | +| ویدئوها | `video_generate` | بله | +| متن به گفتار | `messages.tts.provider: "openai"` / `tts` | بله | +| گفتار به متن دسته‌ای | `tools.media.audio` / درک رسانه | بله | +| گفتار به متن جریانی | Voice Call `streaming.provider: "openai"` | بله | +| صدای بلادرنگ | Voice Call `realtime.provider: "openai"` / گفت‌وگوی Control UI | بله | +| تعبیه‌ها | ارائه‌دهنده تعبیه حافظه | بله | -## Embeddingهای حافظه +## تعبیه‌های حافظه -OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با OpenAI برای embedding، جهت indexing و embeddingهای پرس‌وجوی `memory_search` استفاده کند: +OpenClaw می‌تواند از OpenAI، یا یک نقطه پایانی تعبیه سازگار با OpenAI، برای +نمایه‌سازی `memory_search` و تعبیه‌های پرس‌وجو استفاده کند: ```json5 { @@ -93,11 +109,15 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op } ``` -برای endpointهای سازگار با OpenAI که به برچسب‌های embedding نامتقارن نیاز دارند، `queryInputType` و `documentInputType` را زیر `memorySearch` تنظیم کنید. OpenClaw آن‌ها را به‌عنوان فیلدهای درخواست `input_type` مخصوص ارائه‌دهنده ارسال می‌کند: embeddingهای پرس‌وجو از `queryInputType` استفاده می‌کنند؛ قطعه‌های حافظه indexشده و indexing دسته‌ای از `documentInputType` استفاده می‌کنند. برای نمونه کامل، [مرجع پیکربندی حافظه](/fa/reference/memory-config#provider-specific-config) را ببینید. +برای نقطه‌های پایانی سازگار با OpenAI که به برچسب‌های تعبیه نامتقارن نیاز دارند، +`queryInputType` و `documentInputType` را زیر `memorySearch` تنظیم کنید. OpenClaw +آن‌ها را به‌عنوان فیلدهای درخواست `input_type` ویژه ارائه‌دهنده ارسال می‌کند: تعبیه‌های پرس‌وجو از +`queryInputType` استفاده می‌کنند؛ قطعه‌های حافظه نمایه‌شده و نمایه‌سازی دسته‌ای از +`documentInputType` استفاده می‌کنند. برای نمونه کامل، [مرجع پیکربندی حافظه](/fa/reference/memory-config#provider-specific-config) را ببینید. ## شروع به کار -روش احراز هویت دلخواهتان را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید. +روش احراز هویت ترجیحی خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید. @@ -105,20 +125,20 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op - یک کلید API را از [داشبورد OpenAI Platform](https://platform.openai.com/api-keys) بسازید یا کپی کنید. + یک کلید API از [داشبورد OpenAI Platform](https://platform.openai.com/api-keys) بسازید یا کپی کنید. ```bash openclaw onboard --auth-choice openai-api-key ``` - یا کلید را مستقیما ارسال کنید: + یا کلید را مستقیما پاس بدهید: ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -127,14 +147,17 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op ### خلاصه مسیر - | ارجاع مدل | پیکربندی زمان اجرا | مسیر | احراز هویت | - | ---------------------- | -------------------------- | --------------------------- | ---------------- | + | ارجاع مدل | پیکربندی زمان اجرا | مسیر | احراز هویت | + | ---------------------- | ------------------------------------- | --------------------------- | ---------------- | | `openai/gpt-5.5` | حذف‌شده / `agentRuntime.id: "pi"` | API مستقیم OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | حذف‌شده / `agentRuntime.id: "pi"` | API مستقیم OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | سازوکار app-server در Codex | app-server در Codex | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | مهار app-server متعلق به Codex | app-server متعلق به Codex | - `openai/*` مسیر مستقیم کلید API برای OpenAI است مگر اینکه سازوکار app-server در Codex را صریحا اجباری کنید. برای OAuth مربوط به Codex از طریق اجراکننده پیش‌فرض PI از `openai-codex/*` استفاده کنید، یا برای اجرای بومی app-server در Codex از `openai/gpt-5.5` با `agentRuntime.id: "codex"` استفاده کنید. + `openai/*` مسیر مستقیم کلید API متعلق به OpenAI است، مگر اینکه مهار + app-server متعلق به Codex را صراحتا اجبار کنید. از `openai-codex/*` برای OAuth متعلق به Codex از طریق + اجراکننده پیش‌فرض PI استفاده کنید، یا از `openai/gpt-5.5` همراه با + `agentRuntime.id: "codex"` برای اجرای بومی app-server متعلق به Codex استفاده کنید. ### نمونه پیکربندی @@ -147,16 +170,16 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op ``` - OpenClaw مدل `openai/gpt-5.3-codex-spark` را در معرض استفاده قرار نمی‌دهد. درخواست‌های زنده OpenAI API آن مدل را رد می‌کنند، و کاتالوگ فعلی Codex نیز آن را در معرض استفاده قرار نمی‌دهد. + OpenClaw مدل `openai/gpt-5.3-codex-spark` را در معرض استفاده قرار نمی‌دهد. درخواست‌های زنده OpenAI API آن مدل را رد می‌کنند، و کاتالوگ فعلی Codex نیز آن را ارائه نمی‌کند. - **بهترین برای:** استفاده از اشتراک ChatGPT/Codex شما به‌جای یک کلید API جداگانه. ابر Codex به ورود ChatGPT نیاز دارد. + **بهترین برای:** استفاده از اشتراک ChatGPT/Codex خود به‌جای یک کلید API جداگانه. Codex cloud به ورود ChatGPT نیاز دارد. - + ```bash openclaw onboard --auth-choice openai-codex ``` @@ -167,7 +190,7 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op openclaw models auth login --provider openai-codex ``` - برای راه‌اندازی‌های headless یا ناسازگار با callback، `--device-code` را اضافه کنید تا به‌جای callback مرورگر localhost، با جریان کد دستگاه ChatGPT وارد شوید: + برای راه‌اندازی‌های بدون رابط یا ناسازگار با callback، `--device-code` را اضافه کنید تا به‌جای callback مرورگر localhost با جریان device-code متعلق به ChatGPT وارد شوید: ```bash openclaw models auth login --provider openai-codex --device-code @@ -178,7 +201,7 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -189,18 +212,17 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op | ارجاع مدل | پیکربندی زمان اجرا | مسیر | احراز هویت | |-----------|----------------|-------|------| - | `openai-codex/gpt-5.5` | حذف‌شده / `runtime: "pi"` | OAuth مربوط به ChatGPT/Codex از طریق PI | ورود Codex | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | همچنان PI، مگر اینکه یک Plugin صریحا مالک `openai-codex` شود | ورود Codex | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | سازوکار app-server در Codex | احراز هویت app-server در Codex | + | `openai-codex/gpt-5.5` | حذف‌شده / `runtime: "pi"` | ChatGPT/Codex OAuth از طریق PI | ورود Codex | + | `openai-codex/gpt-5.4-mini` | حذف‌شده / `runtime: "pi"` | ChatGPT/Codex OAuth از طریق PI | ورود Codex | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | همچنان PI، مگر اینکه یک Plugin صراحتا مالکیت `openai-codex` را ادعا کند | ورود Codex | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | مهار app-server متعلق به Codex | احراز هویت app-server متعلق به Codex | - برای فرمان‌های احراز هویت/پروفایل، به استفاده از شناسه ارائه‌دهنده `openai-codex` ادامه دهید. پیشوند مدل `openai-codex/*` نیز مسیر صریح PI برای OAuth مربوط به Codex است. این پیشوند سازوکار همراه app-server در Codex را انتخاب یا خودکار فعال نمی‌کند. + برای فرمان‌های احراز هویت/پروفایل، همچنان از شناسه ارائه‌دهنده `openai-codex` استفاده کنید. پیشوند مدل + `openai-codex/*` نیز مسیر صریح PI برای OAuth متعلق به Codex است. + این پیشوند مهار بسته‌شده app-server متعلق به Codex را انتخاب یا خودکار فعال نمی‌کند. - - `openai-codex/gpt-5.4-mini` یک مسیر پشتیبانی‌شده OAuth برای Codex نیست. از `openai/gpt-5.4-mini` با یک کلید API مربوط به OpenAI استفاده کنید، یا از `openai-codex/gpt-5.5` با OAuth مربوط به Codex استفاده کنید. - - ### نمونه پیکربندی ```json5 @@ -210,31 +232,32 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op ``` - راه‌اندازی دیگر مواد OAuth را از `~/.codex` وارد نمی‌کند. با OAuth مرورگر (پیش‌فرض) یا جریان کد دستگاه بالا وارد شوید — OpenClaw اعتبارنامه‌های حاصل را در مخزن احراز هویت عامل خودش مدیریت می‌کند. + راه‌اندازی دیگر مواد OAuth را از `~/.codex` وارد نمی‌کند. با OAuth مرورگر (پیش‌فرض) یا جریان device-code بالا وارد شوید — OpenClaw اعتبارنامه‌های حاصل را در فروشگاه احراز هویت عامل خودش مدیریت می‌کند. ### نشانگر وضعیت - چت `/status` نشان می‌دهد کدام زمان‌اجرای مدل برای نشست فعلی فعال است. - هارنس پیش‌فرض Pi به صورت `Runtime: OpenClaw Pi Default` ظاهر می‌شود. وقتی هارنس app-server همراهِ Codex انتخاب شده باشد، `/status` این را نشان می‌دهد: - `Runtime: OpenAI Codex`. نشست‌های موجود شناسه هارنس ثبت‌شده خود را نگه می‌دارند، بنابراین اگر می‌خواهید پس از تغییر `agentRuntime`، خروجی `/status` انتخاب جدید Pi/Codex را بازتاب دهد، از - `/new` یا `/reset` استفاده کنید. + گفت‌وگوی `/status` نشان می‌دهد کدام زمان اجرای مدل برای نشست فعلی فعال است. + چارچوب اجرایی پیش‌فرض PI به‌صورت `Runtime: OpenClaw Pi Default` نمایش داده می‌شود. وقتی + چارچوب اجرایی app-server بسته‌شده Codex انتخاب شده باشد، `/status` مقدار + `Runtime: OpenAI Codex` را نشان می‌دهد. نشست‌های موجود شناسه چارچوب اجرایی ثبت‌شده خود را نگه می‌دارند، بنابراین اگر می‌خواهید پس از تغییر `agentRuntime`، `/status` + انتخاب جدید PI/Codex را نشان دهد، از `/new` یا `/reset` استفاده کنید. ### هشدار Doctor - اگر Plugin همراهِ `codex` در حالی فعال باشد که مسیر + اگر Plugin بسته‌شده `codex` در حالی فعال باشد که مسیر `openai-codex/*` این زبانه انتخاب شده است، `openclaw doctor` هشدار می‌دهد که مدل - همچنان از طریق Pi حل می‌شود. وقتی این مسیر احراز هویت اشتراکی همان چیزی است که قصد دارید، پیکربندی را بدون تغییر نگه دارید. فقط وقتی به اجرای بومی app-server در Codex نیاز دارید، به `openai/` به‌همراه - `agentRuntime.id: "codex"` تغییر دهید. + همچنان از طریق PI resolve می‌شود. وقتی این همان مسیر احراز هویت اشتراکی مورد نظر است، پیکربندی را بدون تغییر نگه دارید. فقط زمانی به `openai/` به‌همراه + `agentRuntime.id: "codex"` جابه‌جا شوید که اجرای app-server بومی Codex را می‌خواهید. ### سقف پنجره زمینه - OpenClaw فراداده مدل و سقف زمینه زمان‌اجرا را به‌عنوان مقادیر جداگانه در نظر می‌گیرد. + OpenClaw فراداده مدل و سقف زمینه زمان اجرا را به‌عنوان مقدارهای جداگانه در نظر می‌گیرد. - برای `openai-codex/gpt-5.5` از طریق OAuth در Codex: + برای `openai-codex/gpt-5.5` از طریق Codex OAuth: - `contextWindow` بومی: `1000000` - - سقف پیش‌فرض `contextTokens` زمان‌اجرا: `272000` + - سقف پیش‌فرض `contextTokens` زمان اجرا: `272000` سقف پیش‌فرض کوچک‌تر در عمل ویژگی‌های بهتری از نظر تأخیر و کیفیت دارد. آن را با `contextTokens` بازنویسی کنید: @@ -251,44 +274,53 @@ OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با Op ``` - از `contextWindow` برای اعلان فراداده بومی مدل استفاده کنید. از `contextTokens` برای محدود کردن بودجه زمینه زمان‌اجرا استفاده کنید. + برای اعلام فراداده بومی مدل از `contextWindow` استفاده کنید. برای محدود کردن بودجه زمینه زمان اجرا از `contextTokens` استفاده کنید. ### بازیابی کاتالوگ - OpenClaw وقتی فراداده کاتالوگ بالادستی Codex برای `gpt-5.5` موجود باشد، از آن استفاده می‌کند. اگر کشف زنده Codex در حالی که حساب احراز هویت شده است، ردیف `openai-codex/gpt-5.5` را حذف کند، OpenClaw آن ردیف مدل OAuth را می‌سازد تا اجرای cron، عامل فرعی، و مدل پیش‌فرض پیکربندی‌شده با خطای - `Unknown model` شکست نخورد. + OpenClaw وقتی فراداده کاتالوگ upstream Codex برای `gpt-5.5` وجود داشته باشد، از آن استفاده می‌کند. اگر کشف زنده Codex ردیف `openai-codex/gpt-5.5` را در حالی حذف کند که + حساب احراز هویت شده است، OpenClaw آن ردیف مدل OAuth را می‌سازد تا اجراهای + cron، زیرعامل و مدل پیش‌فرض پیکربندی‌شده با خطای + `Unknown model` شکست نخورند. ## احراز هویت app-server بومی Codex -هارنس app-server بومی Codex از ارجاع‌های مدل `openai/*` به‌همراه -`agentRuntime.id: "codex"` استفاده می‌کند، اما احراز هویت آن همچنان مبتنی بر حساب است. OpenClaw احراز هویت را به این ترتیب انتخاب می‌کند: +چارچوب اجرایی app-server بومی Codex از ارجاع‌های مدل `openai/*` به‌همراه +`agentRuntime.id: "codex"` استفاده می‌کند، اما احراز هویت آن همچنان مبتنی بر حساب است. OpenClaw +احراز هویت را با این ترتیب انتخاب می‌کند: -1. یک پروفایل احراز هویت صریح OpenClaw برای `openai-codex` که به عامل متصل است. -2. حساب موجود app-server، مانند ورود محلی Codex CLI با ChatGPT. -3. فقط برای راه‌اندازی‌های app-server محلی از نوع stdio، ابتدا `CODEX_API_KEY` و سپس - `OPENAI_API_KEY`، وقتی app-server هیچ حسابی گزارش نمی‌کند و هنوز به احراز هویت - OpenAI نیاز دارد. +1. یک پروفایل احراز هویت صریح `openai-codex` در OpenClaw که به عامل متصل شده باشد. +2. حساب موجود app-server، مانند ورود محلی Codex CLI ChatGPT. +3. فقط برای راه‌اندازی‌های app-server محلی stdio، ابتدا `CODEX_API_KEY` و سپس + `OPENAI_API_KEY`، وقتی app-server هیچ حسابی گزارش نمی‌کند و همچنان به + احراز هویت OpenAI نیاز دارد. -این یعنی ورود اشتراکی محلی ChatGPT/Codex فقط به این دلیل جایگزین نمی‌شود که فرایند Gateway برای مدل‌های مستقیم OpenAI یا جاسازی‌ها نیز `OPENAI_API_KEY` دارد. جایگزین کلید API از محیط فقط مسیر محلی stdio بدون حساب است؛ به اتصال‌های app-server مبتنی بر WebSocket ارسال نمی‌شود. وقتی یک پروفایل Codex از نوع اشتراکی انتخاب شده باشد، OpenClaw همچنین `CODEX_API_KEY` و `OPENAI_API_KEY` را از فرزند app-server نوع stdio که ایجاد می‌شود بیرون نگه می‌دارد و اعتبارنامه‌های انتخاب‌شده را از طریق RPC ورود app-server ارسال می‌کند. +این یعنی ورود اشتراکی محلی ChatGPT/Codex فقط به این دلیل جایگزین نمی‌شود که فرایند Gateway برای مدل‌های مستقیم OpenAI +یا embeddings نیز `OPENAI_API_KEY` دارد. بازگشت به کلید API از env فقط مسیر محلی stdio بدون حساب است؛ +به اتصال‌های app-server از نوع WebSocket ارسال نمی‌شود. وقتی یک پروفایل Codex +به سبک اشتراکی انتخاب شده باشد، OpenClaw همچنین `CODEX_API_KEY` و `OPENAI_API_KEY` +را از فرزند app-server stdio ایجادشده بیرون نگه می‌دارد و اعتبارنامه‌های انتخاب‌شده را +از طریق RPC ورود app-server ارسال می‌کند. ## تولید تصویر -Plugin همراهِ `openai` تولید تصویر را از طریق ابزار `image_generate` ثبت می‌کند. -این Plugin هم از تولید تصویر با کلید API در OpenAI و هم از تولید تصویر با OAuth در Codex از طریق همان ارجاع مدل `openai/gpt-image-2` پشتیبانی می‌کند. +Plugin بسته‌شده `openai` تولید تصویر را از طریق ابزار `image_generate` ثبت می‌کند. +این Plugin هم تولید تصویر با کلید API OpenAI و هم تولید تصویر با Codex OAuth را +از طریق همان ارجاع مدل `openai/gpt-image-2` پشتیبانی می‌کند. -| قابلیت | کلید API در OpenAI | OAuth در Codex | +| قابلیت | کلید API OpenAI | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | -| ارجاع مدل | `openai/gpt-image-2` | `openai/gpt-image-2` | -| احراز هویت | `OPENAI_API_KEY` | ورود OAuth برای OpenAI Codex | -| انتقال | API تصاویر OpenAI | پشتانه Responses در Codex | -| بیشینه تصاویر در هر درخواست | 4 | 4 | -| حالت ویرایش | فعال (تا 5 تصویر مرجع) | فعال (تا 5 تصویر مرجع) | -| بازنویسی‌های اندازه | پشتیبانی می‌شود، شامل اندازه‌های 2K/4K | پشتیبانی می‌شود، شامل اندازه‌های 2K/4K | -| نسبت تصویر / وضوح | به API تصاویر OpenAI ارسال نمی‌شود | وقتی ایمن باشد به یک اندازه پشتیبانی‌شده نگاشت می‌شود | +| ارجاع مدل | `openai/gpt-image-2` | `openai/gpt-image-2` | +| احراز هویت | `OPENAI_API_KEY` | ورود OpenAI Codex OAuth | +| انتقال | OpenAI Images API | backend پاسخ‌های Codex | +| بیشینه تصاویر در هر درخواست | 4 | 4 | +| حالت ویرایش | فعال (تا 5 تصویر مرجع) | فعال (تا 5 تصویر مرجع) | +| بازنویسی‌های اندازه | پشتیبانی می‌شود، از جمله اندازه‌های 2K/4K | پشتیبانی می‌شود، از جمله اندازه‌های 2K/4K | +| نسبت تصویر / وضوح | به OpenAI Images API ارسال نمی‌شود | در صورت امن بودن به یک اندازه پشتیبانی‌شده نگاشت می‌شود | ```json5 { @@ -301,18 +333,23 @@ Plugin همراهِ `openai` تولید تصویر را از طریق ابزار ``` -برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار جایگزینی در زمان خطا، [تولید تصویر](/fa/tools/image-generation) را ببینید. +برای پارامترهای مشترک ابزار، انتخاب provider و رفتار failover، [تولید تصویر](/fa/tools/image-generation) را ببینید. -`gpt-image-2` پیش‌فرض برای تولید متن‌به‌تصویر OpenAI و ویرایش تصویر است. `gpt-image-1.5`، `gpt-image-1`، و `gpt-image-1-mini` همچنان به‌عنوان بازنویسی‌های صریح مدل قابل استفاده هستند. برای خروجی PNG/WebP با پس‌زمینه شفاف از `openai/gpt-image-1.5` استفاده کنید؛ API فعلی `gpt-image-2` مقدار -`background: "transparent"` را رد می‌کند. +`gpt-image-2` پیش‌فرض هم برای تولید متن‌به‌تصویر OpenAI و هم برای +ویرایش تصویر است. `gpt-image-1.5`، `gpt-image-1` و `gpt-image-1-mini` همچنان به‌عنوان +بازنویسی‌های صریح مدل قابل استفاده‌اند. برای خروجی PNG/WebP با پس‌زمینه شفاف از `openai/gpt-image-1.5` استفاده کنید؛ API فعلی `gpt-image-2` +گزینه `background: "transparent"` را رد می‌کند. -برای درخواست پس‌زمینه شفاف، عامل‌ها باید `image_generate` را با -`model: "openai/gpt-image-1.5"`، `outputFormat: "png"` یا `"webp"`، و -`background: "transparent"` فراخوانی کنند؛ گزینه قدیمی ارائه‌دهنده `openai.background` همچنان پذیرفته می‌شود. OpenClaw همچنین با بازنویسی درخواست‌های شفاف پیش‌فرض `openai/gpt-image-2` به `gpt-image-1.5` از مسیرهای عمومی OpenAI و -OAuth در OpenAI Codex محافظت می‌کند؛ نقطه‌پایان‌های Azure و سازگار با OpenAI سفارشی، نام‌های deployment/model پیکربندی‌شده خود را نگه می‌دارند. +برای یک درخواست با پس‌زمینه شفاف، عامل‌ها باید `image_generate` را با +`model: "openai/gpt-image-1.5"`، `outputFormat: "png"` یا `"webp"` و +`background: "transparent"` فراخوانی کنند؛ گزینه قدیمی provider یعنی `openai.background` +همچنان پذیرفته می‌شود. OpenClaw همچنین مسیرهای عمومی OpenAI و +OpenAI Codex OAuth را با بازنویسی درخواست‌های شفاف پیش‌فرض `openai/gpt-image-2` +به `gpt-image-1.5` محافظت می‌کند؛ endpointهای Azure و سفارشی سازگار با OpenAI +نام‌های deployment/مدل پیکربندی‌شده خود را نگه می‌دارند. -همین تنظیم برای اجرای‌های CLI بدون رابط نیز در دسترس است: +همین تنظیم برای اجراهای CLI بدون رابط نیز در دسترس است: ```bash openclaw infer image generate \ @@ -323,13 +360,19 @@ openclaw infer image generate \ --json ``` -هنگام شروع از یک فایل ورودی، همین پرچم‌های `--output-format` و `--background` را با +وقتی از یک فایل ورودی شروع می‌کنید، همین پرچم‌های `--output-format` و `--background` را با `openclaw infer image edit` استفاده کنید. -`--openai-background` همچنان به‌عنوان نام مستعار ویژه OpenAI در دسترس است. +`--openai-background` همچنان به‌عنوان یک alias مخصوص OpenAI در دسترس است. -برای نصب‌های OAuth در Codex، همان ارجاع `openai/gpt-image-2` را نگه دارید. وقتی یک پروفایل OAuth برای `openai-codex` پیکربندی شده باشد، OpenClaw آن توکن دسترسی OAuth ذخیره‌شده را حل می‌کند و درخواست‌های تصویر را از طریق پشتانه Responses در Codex ارسال می‌کند. برای آن درخواست، ابتدا `OPENAI_API_KEY` را امتحان نمی‌کند و بی‌صدا به یک کلید API برنمی‌گردد. وقتی مسیر مستقیم API تصاویر OpenAI را می‌خواهید، `models.providers.openai` را به‌طور صریح با یک کلید API، نشانی پایه سفارشی، یا نقطه‌پایان Azure پیکربندی کنید. -اگر آن نقطه‌پایان تصویر سفارشی روی یک نشانی LAN/خصوصی مورد اعتماد است، همچنین -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` را تنظیم کنید؛ OpenClaw نقطه‌پایان‌های تصویر خصوصی/داخلی سازگار با OpenAI را مسدود نگه می‌دارد مگر اینکه این انتخاب صریح وجود داشته باشد. +برای نصب‌های Codex OAuth، همان ارجاع `openai/gpt-image-2` را نگه دارید. وقتی یک +پروفایل OAuth از نوع `openai-codex` پیکربندی شده باشد، OpenClaw آن access token ذخیره‌شده OAuth را resolve می‌کند و درخواست‌های تصویر را از طریق backend پاسخ‌های Codex ارسال می‌کند. برای آن +درخواست ابتدا `OPENAI_API_KEY` را امتحان نمی‌کند یا بی‌صدا به یک کلید API برنمی‌گردد. وقتی مسیر مستقیم OpenAI Images API +را می‌خواهید، `models.providers.openai` را صریحا با یک کلید API، +URL پایه سفارشی یا endpoint Azure پیکربندی کنید. +اگر آن endpoint تصویر سفارشی روی یک نشانی LAN/خصوصی مورد اعتماد است، همچنین +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` را تنظیم کنید؛ OpenClaw +endpointهای تصویر خصوصی/داخلی سازگار با OpenAI را مسدود نگه می‌دارد مگر اینکه این opt-in +وجود داشته باشد. تولید: @@ -337,7 +380,7 @@ openclaw infer image generate \ /tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` -تولید PNG شفاف: +تولید یک PNG شفاف: ``` /tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent @@ -349,17 +392,17 @@ openclaw infer image generate \ /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` -## تولید ویدئو +## تولید ویدیو -Plugin همراهِ `openai` تولید ویدئو را از طریق ابزار `video_generate` ثبت می‌کند. +Plugin بسته‌شده `openai` تولید ویدیو را از طریق ابزار `video_generate` ثبت می‌کند. -| قابلیت | مقدار | +| قابلیت | مقدار | | ---------------- | --------------------------------------------------------------------------------- | -| مدل پیش‌فرض | `openai/sora-2` | -| حالت‌ها | متن‌به‌ویدئو، تصویر‌به‌ویدئو، ویرایش تک‌ویدئو | -| ورودی‌های مرجع | 1 تصویر یا 1 ویدئو | -| بازنویسی‌های اندازه | پشتیبانی می‌شود | -| بازنویسی‌های دیگر | `aspectRatio`، `resolution`، `audio`، `watermark` با هشدار ابزار نادیده گرفته می‌شوند | +| مدل پیش‌فرض | `openai/sora-2` | +| حالت‌ها | متن‌به‌ویدیو، تصویر‌به‌ویدیو، ویرایش تک‌ویدیو | +| ورودی‌های مرجع | 1 تصویر یا 1 ویدیو | +| بازنویسی‌های اندازه | پشتیبانی می‌شود | +| بازنویسی‌های دیگر | `aspectRatio`، `resolution`، `audio`، `watermark` با یک هشدار ابزار نادیده گرفته می‌شوند | ```json5 { @@ -372,22 +415,22 @@ Plugin همراهِ `openai` تولید ویدئو را از طریق ابزار ``` -برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار جایگزینی در زمان خطا، [تولید ویدئو](/fa/tools/video-generation) را ببینید. +برای پارامترهای مشترک ابزار، انتخاب provider و رفتار failover، [تولید ویدیو](/fa/tools/video-generation) را ببینید. -## مشارکت prompt در GPT-5 +## مشارکت پرامپت GPT-5 -OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه‌دهنده‌ها یک مشارکت prompt مشترک GPT-5 اضافه می‌کند. این مشارکت بر اساس شناسه مدل اعمال می‌شود، بنابراین `openai-codex/gpt-5.5`، `openai/gpt-5.5`، `openrouter/openai/gpt-5.5`، `opencode/gpt-5.5`، و دیگر ارجاع‌های سازگار GPT-5 همان پوشش را دریافت می‌کنند. مدل‌های قدیمی‌تر GPT-4.x آن را دریافت نمی‌کنند. +OpenClaw یک مشارکت پرامپت مشترک GPT-5 برای اجراهای خانواده GPT-5 در providerهای مختلف اضافه می‌کند. این بر اساس شناسه مدل اعمال می‌شود، بنابراین `openai-codex/gpt-5.5`، `openai/gpt-5.5`، `openrouter/openai/gpt-5.5`، `opencode/gpt-5.5` و سایر ارجاع‌های سازگار GPT-5 همان overlay را دریافت می‌کنند. مدل‌های قدیمی‌تر GPT-4.x این را دریافت نمی‌کنند. -هارنس بومی Codex همراه، همان رفتار GPT-5 و پوشش Heartbeat را از طریق دستورالعمل‌های توسعه‌دهنده app-server در Codex به‌کار می‌گیرد، بنابراین نشست‌های `openai/gpt-5.x` که از طریق `agentRuntime.id: "codex"` اجبار شده‌اند، همان راهنمایی پیگیری و Heartbeat پیش‌دستانه را نگه می‌دارند، حتی با اینکه بقیه prompt هارنس در مالکیت Codex است. +چارچوب اجرایی بومی Codex بسته‌شده از همان رفتار GPT-5 و overlay مربوط به Heartbeat از طریق دستورالعمل‌های توسعه‌دهنده app-server در Codex استفاده می‌کند، بنابراین نشست‌های `openai/gpt-5.x` که با `agentRuntime.id: "codex"` از مسیر Codex عبور داده شده‌اند، همان راهنمایی پیگیری و Heartbeat پیش‌دستانه را نگه می‌دارند، هرچند Codex مالک بقیه پرامپت چارچوب اجرایی است. -مشارکت GPT-5 یک قرارداد رفتاری برچسب‌دار برای پایداری پرسونا، ایمنی اجرا، انضباط ابزار، شکل خروجی، بررسی‌های تکمیل، و راستی‌آزمایی اضافه می‌کند. رفتار پاسخ مخصوص کانال و پیام بی‌صدا در prompt سیستمی مشترک OpenClaw و سیاست تحویل خروجی باقی می‌ماند. راهنمایی GPT-5 برای مدل‌های منطبق همیشه فعال است. لایه سبک تعامل دوستانه جدا و قابل پیکربندی است. +مشارکت GPT-5 یک قرارداد رفتاری برچسب‌دار برای تداوم پرسونا، ایمنی اجرا، انضباط ابزار، شکل خروجی، بررسی‌های تکمیل و راستی‌آزمایی اضافه می‌کند. رفتار پاسخ‌گویی مخصوص کانال و پیام‌های خاموش در پرامپت سیستمی مشترک OpenClaw و سیاست تحویل خروجی باقی می‌ماند. راهنمای GPT-5 همیشه برای مدل‌های منطبق فعال است. لایه سبک تعامل دوستانه جداگانه و قابل پیکربندی است. -| مقدار | اثر | +| مقدار | اثر | | ---------------------- | ------------------------------------------- | -| `"friendly"` (پیش‌فرض) | فعال کردن لایه سبک تعامل دوستانه | -| `"on"` | نام مستعار برای `"friendly"` | -| `"off"` | فقط لایه سبک دوستانه را غیرفعال می‌کند | +| `"friendly"` (پیش‌فرض) | لایه سبک تعامل دوستانه را فعال می‌کند | +| `"on"` | Alias برای `"friendly"` | +| `"off"` | فقط لایه سبک دوستانه را غیرفعال می‌کند | @@ -411,18 +454,18 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه -مقادیر در زمان اجرا به بزرگی و کوچکی حروف حساس نیستند، بنابراین `"Off"` و `"off"` هر دو لایه سبک دوستانه را غیرفعال می‌کنند. +مقدارها در زمان اجرا به بزرگی و کوچکی حروف حساس نیستند، بنابراین `"Off"` و `"off"` هر دو لایه سبک دوستانه را غیرفعال می‌کنند. -وقتی تنظیم مشترک `agents.defaults.promptOverlays.gpt5.personality` تنظیم نشده باشد، مقدار قدیمی `plugins.entries.openai.config.personality` همچنان به‌عنوان جایگزین سازگاری خوانده می‌شود. +گزینه قدیمی `plugins.entries.openai.config.personality` همچنان به‌عنوان fallback سازگاری خوانده می‌شود، وقتی تنظیم مشترک `agents.defaults.promptOverlays.gpt5.personality` تنظیم نشده باشد. ## صدا و گفتار - - Plugin همراهِ `openai` سنتز گفتار را برای سطح `messages.tts` ثبت می‌کند. + + Plugin بسته‌شده `openai` ترکیب گفتار را برای سطح `messages.tts` ثبت می‌کند. | تنظیم | مسیر پیکربندی | پیش‌فرض | |---------|------------|---------| @@ -430,9 +473,9 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه | صدا | `messages.tts.providers.openai.voice` | `coral` | | سرعت | `messages.tts.providers.openai.speed` | (تنظیم‌نشده) | | دستورالعمل‌ها | `messages.tts.providers.openai.instructions` | (تنظیم‌نشده، فقط `gpt-4o-mini-tts`) | - | قالب | `messages.tts.providers.openai.responseFormat` | `opus` برای پیام‌های صوتی، `mp3` برای فایل‌ها | - | کلید API | `messages.tts.providers.openai.apiKey` | به `OPENAI_API_KEY` برمی‌گردد | - | نشانی پایه | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | قالب | `messages.tts.providers.openai.responseFormat` | `opus` برای یادداشت‌های صوتی، `mp3` برای فایل‌ها | + | کلید API | `messages.tts.providers.openai.apiKey` | به `OPENAI_API_KEY` fallback می‌کند | + | URL پایه | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | مدل‌های در دسترس: `gpt-4o-mini-tts`، `tts-1`، `tts-1-hd`. صداهای در دسترس: `alloy`، `ash`، `ballad`، `cedar`، `coral`، `echo`، `fable`، `juniper`، `marin`، `onyx`، `nova`، `sage`، `shimmer`، `verse`. @@ -449,21 +492,21 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه ``` - برای بازنویسی نشانی پایه TTS بدون اثر گذاشتن بر نقطه‌پایان API چت، `OPENAI_TTS_BASE_URL` را تنظیم کنید. + برای بازنویسی URL پایه TTS بدون تأثیر بر endpoint چت API، `OPENAI_TTS_BASE_URL` را تنظیم کنید. - Plugin همراهِ `openai` گفتار‌به‌متن دسته‌ای را از طریق سطح رونویسی درک رسانه‌ای OpenClaw ثبت می‌کند. + Plugin بسته‌شده `openai` گفتار به متن دسته‌ای را از طریق + سطح رونویسی درک رسانه OpenClaw ثبت می‌کند. - مدل پیش‌فرض: `gpt-4o-transcribe` - - نقطه‌پایان: REST در OpenAI با `/v1/audio/transcriptions` - - مسیر ورودی: بارگذاری فایل صوتی چندبخشی - - در OpenClaw هر جا رونویسی صوت ورودی از - `tools.media.audio` استفاده کند پشتیبانی می‌شود، از جمله بخش‌های کانال صوتی Discord و پیوست‌های صوتی کانال + - endpoint: OpenAI REST `/v1/audio/transcriptions` + - مسیر ورودی: بارگذاری فایل صوتی multipart + - هرجا که رونویسی صوتی ورودی از `tools.media.audio` استفاده می‌کند، توسط OpenClaw پشتیبانی می‌شود، از جمله بخش‌های کانال صوتی Discord و پیوست‌های صوتی کانال - برای اجبار استفاده از OpenAI برای رونویسی صوتی ورودی: + برای اجبار OpenAI برای رونویسی صدای ورودی: ```json5 { @@ -483,13 +526,13 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه } ``` - راهنمایی‌های زبان و پرامپت، وقتی توسط پیکربندی مشترک رسانه صوتی - یا درخواست رونویسی جداگانه در هر فراخوانی ارائه شوند، به OpenAI ارسال می‌شوند. + وقتی راهنماهای زبان و پرامپت از سوی پیکربندی رسانه‌ی صوتی مشترک یا درخواست + رونویسی هر فراخوانی ارائه شوند، به OpenAI ارسال می‌شوند. - Plugin همراه `openai`، رونویسی بلادرنگ را برای Plugin Voice Call ثبت می‌کند. + Plugin بسته‌بندی‌شده‌ی `openai` رونویسی بلادرنگ را برای Plugin تماس صوتی ثبت می‌کند. | تنظیم | مسیر پیکربندی | پیش‌فرض | |---------|------------|---------| @@ -497,68 +540,68 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه | زبان | `...openai.language` | (تنظیم‌نشده) | | پرامپت | `...openai.prompt` | (تنظیم‌نشده) | | مدت سکوت | `...openai.silenceDurationMs` | `800` | - | آستانه VAD | `...openai.vadThreshold` | `0.5` | - | کلید API | `...openai.apiKey` | به `OPENAI_API_KEY` بازمی‌گردد | + | آستانه‌ی VAD | `...openai.vadThreshold` | `0.5` | + | کلید API | `...openai.apiKey` | به `OPENAI_API_KEY` برمی‌گردد | - از اتصال WebSocket به `wss://api.openai.com/v1/realtime` با صوت G.711 u-law (`g711_ulaw` / `audio/pcmu`) استفاده می‌کند. این ارائه‌دهنده استریم برای مسیر رونویسی بلادرنگ Voice Call است؛ صدای Discord در حال حاضر بخش‌های کوتاه را ضبط می‌کند و به‌جای آن از مسیر رونویسی دسته‌ای `tools.media.audio` استفاده می‌کند. + از یک اتصال WebSocket به `wss://api.openai.com/v1/realtime` با صدای G.711 u-law (`g711_ulaw` / `audio/pcmu`) استفاده می‌کند. این ارائه‌دهنده‌ی جریانی برای مسیر رونویسی بلادرنگ تماس صوتی است؛ صدای Discord در حال حاضر بخش‌های کوتاه را ضبط می‌کند و به‌جای آن از مسیر رونویسی دسته‌ای `tools.media.audio` استفاده می‌کند. - Plugin همراه `openai`، صدای بلادرنگ را برای Plugin Voice Call ثبت می‌کند. + Plugin بسته‌بندی‌شده‌ی `openai` صدای بلادرنگ را برای Plugin تماس صوتی ثبت می‌کند. | تنظیم | مسیر پیکربندی | پیش‌فرض | |---------|------------|---------| | مدل | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | صدا | `...openai.voice` | `alloy` | | دما | `...openai.temperature` | `0.8` | - | آستانه VAD | `...openai.vadThreshold` | `0.5` | + | آستانه‌ی VAD | `...openai.vadThreshold` | `0.5` | | مدت سکوت | `...openai.silenceDurationMs` | `500` | - | کلید API | `...openai.apiKey` | به `OPENAI_API_KEY` بازمی‌گردد | + | کلید API | `...openai.apiKey` | به `OPENAI_API_KEY` برمی‌گردد | - از Azure OpenAI از طریق کلیدهای پیکربندی `azureEndpoint` و `azureDeployment` برای پل‌های بلادرنگ backend پشتیبانی می‌کند. از فراخوانی دوطرفه ابزار پشتیبانی می‌کند. از قالب صوتی G.711 u-law استفاده می‌کند. + از Azure OpenAI از طریق کلیدهای پیکربندی `azureEndpoint` و `azureDeployment` برای پل‌های بلادرنگ سمت بک‌اند پشتیبانی می‌کند. از فراخوانی ابزار دوسویه پشتیبانی می‌کند. از قالب صوتی G.711 u-law استفاده می‌کند. - Talk در Control UI از نشست‌های بلادرنگ مرورگر OpenAI با یک secret موقت سمت کلاینت که توسط Gateway صادر شده - و تبادل مستقیم WebRTC SDP مرورگر در برابر - OpenAI Realtime API استفاده می‌کند. راستی‌آزمایی زنده نگه‌دارنده با + گفت‌وگوی UI کنترل از نشست‌های بلادرنگ مرورگر OpenAI با راز موقت کلاینت + صادرشده توسط Gateway و تبادل مستقیم WebRTC SDP مرورگر با OpenAI Realtime API + استفاده می‌کند. راستی‌آزمایی زنده‌ی نگه‌دارنده با `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` - در دسترس است؛ مسیر OpenAI در Node یک client secret صادر می‌کند، یک پیشنهاد SDP مرورگر - با رسانه میکروفون جعلی تولید می‌کند، آن را به OpenAI ارسال می‌کند، و پاسخ SDP را - بدون ثبت secretها اعمال می‌کند. + در دسترس است؛ بخش OpenAI یک راز کلاینت را در Node صادر می‌کند، یک پیشنهاد SDP مرورگر + با رسانه‌ی میکروفون ساختگی تولید می‌کند، آن را به OpenAI ارسال می‌کند و پاسخ SDP را + بدون ثبت اسرار اعمال می‌کند. -## نقاط پایانی Azure OpenAI +## نقطه‌های پایانی Azure OpenAI -ارائه‌دهنده همراه `openai` می‌تواند با بازنویسی URL پایه، یک منبع Azure OpenAI را برای تولید تصویر -هدف بگیرد. در مسیر تولید تصویر، OpenClaw -نام میزبان‌های Azure را روی `models.providers.openai.baseUrl` تشخیص می‌دهد و به‌طور خودکار به -شکل درخواست Azure تغییر می‌کند. +ارائه‌دهنده‌ی بسته‌بندی‌شده‌ی `openai` می‌تواند با بازنویسی URL پایه، یک منبع Azure OpenAI را برای +تولید تصویر هدف بگیرد. در مسیر تولید تصویر، OpenClaw نام‌های میزبان Azure را در +`models.providers.openai.baseUrl` تشخیص می‌دهد و به‌طور خودکار به شکل درخواست +Azure تغییر می‌کند. صدای بلادرنگ از مسیر پیکربندی جداگانه‌ای استفاده می‌کند (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) و تحت تأثیر `models.providers.openai.baseUrl` نیست. برای تنظیمات Azure آن، آکاردئون **صدای بلادرنگ** -زیر [صدا و گفتار](#voice-and-speech) را ببینید. +را زیر [صدا و گفتار](#voice-and-speech) ببینید. از Azure OpenAI زمانی استفاده کنید که: - از قبل اشتراک، سهمیه، یا قرارداد سازمانی Azure OpenAI دارید -- به اقامت داده منطقه‌ای یا کنترل‌های انطباقی که Azure فراهم می‌کند نیاز دارید +- به اقامت داده‌ی منطقه‌ای یا کنترل‌های انطباقی که Azure فراهم می‌کند نیاز دارید - می‌خواهید ترافیک را داخل یک tenancy موجود Azure نگه دارید ### پیکربندی -برای تولید تصویر Azure از طریق ارائه‌دهنده همراه `openai`، -`models.providers.openai.baseUrl` را به منبع Azure خود اشاره دهید و `apiKey` را روی +برای تولید تصویر Azure از طریق ارائه‌دهنده‌ی بسته‌بندی‌شده‌ی `openai`، +`models.providers.openai.baseUrl` را به منبع Azure خود اشاره دهید و `apiKey` را به کلید Azure OpenAI تنظیم کنید (نه کلید OpenAI Platform): ```json5 @@ -574,7 +617,7 @@ OpenClaw برای اجراهای خانواده GPT-5 در میان ارائه } ``` -OpenClaw این پسوندهای میزبان Azure را برای مسیر تولید تصویر Azure می‌شناسد: +OpenClaw این پسوندهای میزبان Azure را برای مسیر تولید تصویر Azure تشخیص می‌دهد: - `*.openai.azure.com` - `*.services.ai.azure.com` @@ -582,25 +625,25 @@ OpenClaw این پسوندهای میزبان Azure را برای مسیر تو برای درخواست‌های تولید تصویر روی میزبان Azure شناخته‌شده، OpenClaw: -- سرآیند `api-key` را به‌جای `Authorization: Bearer` می‌فرستد -- از مسیرهای scoped به deployment استفاده می‌کند (`/openai/deployments/{deployment}/...`) +- سرآیند `api-key` را به‌جای `Authorization: Bearer` ارسال می‌کند +- از مسیرهای محدود به deployment استفاده می‌کند (`/openai/deployments/{deployment}/...`) - به هر درخواست `?api-version=...` اضافه می‌کند -- از timeout پیش‌فرض ۶۰۰ ثانیه‌ای برای فراخوانی‌های تولید تصویر Azure استفاده می‌کند. - مقدارهای `timeoutMs` در هر فراخوانی همچنان این پیش‌فرض را بازنویسی می‌کنند. +- برای فراخوانی‌های تولید تصویر Azure از مهلت زمانی پیش‌فرض درخواست ۶۰۰ ثانیه استفاده می‌کند. + مقدارهای `timeoutMs` هر فراخوانی همچنان این پیش‌فرض را بازنویسی می‌کنند. -URLهای پایه دیگر (OpenAI عمومی، پراکسی‌های سازگار با OpenAI) شکل استاندارد -درخواست تصویر OpenAI را حفظ می‌کنند. +URLهای پایه‌ی دیگر (OpenAI عمومی، پراکسی‌های سازگار با OpenAI) شکل استاندارد +درخواست تصویر OpenAI را نگه می‌دارند. -مسیردهی Azure برای مسیر تولید تصویر ارائه‌دهنده `openai` به +مسیریابی Azure برای مسیر تولید تصویر ارائه‌دهنده‌ی `openai` به OpenClaw 2026.4.22 یا جدیدتر نیاز دارد. نسخه‌های قدیمی‌تر هر -`openai.baseUrl` سفارشی را مثل نقطه پایانی عمومی OpenAI در نظر می‌گیرند و در برابر deploymentهای تصویر Azure -ناموفق می‌شوند. +`openai.baseUrl` سفارشی را مانند نقطه‌ی پایانی عمومی OpenAI در نظر می‌گیرند و در برابر deploymentهای +تصویر Azure شکست می‌خورند. -### نسخه API +### نسخه‌ی API -برای ثابت کردن یک نسخه پیش‌نمایش یا GA مشخص Azure برای مسیر تولید تصویر Azure، +برای ثابت‌کردن یک نسخه‌ی preview یا GA مشخص Azure برای مسیر تولید تصویر Azure، `AZURE_OPENAI_API_VERSION` را تنظیم کنید: ```bash @@ -612,64 +655,64 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ### نام مدل‌ها همان نام deploymentها هستند Azure OpenAI مدل‌ها را به deploymentها متصل می‌کند. برای درخواست‌های تولید تصویر Azure -که از طریق ارائه‌دهنده همراه `openai` مسیردهی می‌شوند، فیلد `model` در OpenClaw +که از طریق ارائه‌دهنده‌ی بسته‌بندی‌شده‌ی `openai` مسیریابی می‌شوند، فیلد `model` در OpenClaw باید **نام deployment در Azure** باشد که در پورتال Azure پیکربندی کرده‌اید، نه -شناسه مدل عمومی OpenAI. +شناسه‌ی مدل عمومی OpenAI. -اگر deploymentی به نام `gpt-image-2-prod` بسازید که `gpt-image-2` را ارائه می‌دهد: +اگر deploymentای به نام `gpt-image-2-prod` بسازید که `gpt-image-2` را ارائه می‌کند: ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -همین قاعده نام deployment برای فراخوانی‌های تولید تصویر که از طریق -ارائه‌دهنده همراه `openai` مسیردهی می‌شوند نیز اعمال می‌شود. +همین قاعده‌ی نام deployment برای فراخوانی‌های تولید تصویر که از طریق +ارائه‌دهنده‌ی بسته‌بندی‌شده‌ی `openai` مسیریابی می‌شوند نیز اعمال می‌شود. ### دسترس‌پذیری منطقه‌ای -تولید تصویر Azure در حال حاضر فقط در زیرمجموعه‌ای از منطقه‌ها در دسترس است +تولید تصویر Azure در حال حاضر فقط در زیرمجموعه‌ای از مناطق در دسترس است (برای مثال `eastus2`، `swedencentral`، `polandcentral`، `westus3`، -`uaenorth`). پیش از ایجاد deployment، فهرست منطقه‌های فعلی Microsoft را بررسی کنید -و تأیید کنید که مدل مشخص در منطقه شما ارائه می‌شود. +`uaenorth`). پیش از ایجاد deployment، فهرست فعلی مناطق Microsoft را بررسی کنید +و تأیید کنید که مدل مشخص در منطقه‌ی شما ارائه می‌شود. -### تفاوت‌های پارامتر +### تفاوت‌های پارامترها Azure OpenAI و OpenAI عمومی همیشه پارامترهای تصویر یکسانی را نمی‌پذیرند. -Azure ممکن است گزینه‌هایی را که OpenAI عمومی مجاز می‌داند رد کند (برای مثال بعضی -مقدارهای `background` روی `gpt-image-2`) یا آن‌ها را فقط در نسخه‌های مشخص مدل -ارائه دهد. این تفاوت‌ها از Azure و مدل زیربنایی می‌آیند، نه -OpenClaw. اگر یک درخواست Azure با خطای اعتبارسنجی ناموفق شد، مجموعه -پارامترهای پشتیبانی‌شده توسط deployment و نسخه API مشخص خود را در -پورتال Azure بررسی کنید. +Azure ممکن است گزینه‌هایی را که OpenAI عمومی اجازه می‌دهد رد کند (برای مثال برخی +مقدارهای `background` روی `gpt-image-2`) یا آن‌ها را فقط روی نسخه‌های مشخص مدل +ارائه کند. این تفاوت‌ها از Azure و مدل زیربنایی می‌آیند، نه +OpenClaw. اگر یک درخواست Azure با خطای اعتبارسنجی شکست خورد، مجموعه‌ی پارامترهای +پشتیبانی‌شده توسط deployment و نسخه‌ی API مشخص خود را در پورتال +Azure بررسی کنید. -Azure OpenAI از transport بومی و رفتار سازگار استفاده می‌کند اما سرآیندهای انتساب پنهان -OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای بومی در برابر مسیرهای سازگار با OpenAI** -زیر [پیکربندی پیشرفته](#advanced-configuration) را ببینید. +Azure OpenAI از انتقال بومی و رفتار سازگاری استفاده می‌کند، اما +سرآیندهای انتساب پنهان OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای بومی در برابر مسیرهای سازگار با OpenAI** +را زیر [پیکربندی پیشرفته](#advanced-configuration) ببینید. برای ترافیک chat یا Responses روی Azure (فراتر از تولید تصویر)، از -جریان onboarding یا یک پیکربندی اختصاصی ارائه‌دهنده Azure استفاده کنید — `openai.baseUrl` به‌تنهایی -شکل API/auth Azure را انتخاب نمی‌کند. یک ارائه‌دهنده جداگانه -`azure-openai-responses/*` وجود دارد؛ آکاردئون Compaction سمت سرور را در پایین ببینید. +جریان onboarding یا پیکربندی ارائه‌دهنده‌ی اختصاصی Azure استفاده کنید — `openai.baseUrl` به‌تنهایی +شکل API/auth Azure را انتخاب نمی‌کند. یک ارائه‌دهنده‌ی جداگانه‌ی +`azure-openai-responses/*` وجود دارد؛ آکاردئون compaction سمت سرور را در پایین ببینید. ## پیکربندی پیشرفته - + OpenClaw برای هر دو `openai/*` و `openai-codex/*` از WebSocket-first با fallback به SSE (`"auto"`) استفاده می‌کند. در حالت `"auto"`، OpenClaw: - - یک شکست اولیه WebSocket را پیش از fallback به SSE یک بار دوباره تلاش می‌کند - - پس از شکست، WebSocket را حدود ۶۰ ثانیه degraded علامت‌گذاری می‌کند و در دوره cool-down از SSE استفاده می‌کند - - سرآیندهای پایدار هویت نشست و turn را برای تلاش‌های دوباره و اتصال‌های مجدد ضمیمه می‌کند - - شمارنده‌های مصرف (`input_tokens` / `prompt_tokens`) را در گونه‌های transport نرمال‌سازی می‌کند + - یک شکست زودهنگام WebSocket را پیش از fallback به SSE دوباره تلاش می‌کند + - پس از شکست، WebSocket را برای حدود ۶۰ ثانیه degraded علامت‌گذاری می‌کند و طی زمان cool-down از SSE استفاده می‌کند + - برای تلاش‌های دوباره و اتصال‌های مجدد، سرآیندهای پایدار هویت نشست و نوبت را پیوست می‌کند + - شمارنده‌های مصرف (`input_tokens` / `prompt_tokens`) را میان گونه‌های انتقال نرمال‌سازی می‌کند | مقدار | رفتار | |-------|----------| | `"auto"` (پیش‌فرض) | ابتدا WebSocket، fallback به SSE | - | `"sse"` | اجبار به فقط SSE | - | `"websocket"` | اجبار به فقط WebSocket | + | `"sse"` | فقط SSE را اجباری می‌کند | + | `"websocket"` | فقط WebSocket را اجباری می‌کند | ```json5 { @@ -695,7 +738,7 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای - OpenClaw برای کاهش تأخیر turn نخست، گرم‌سازی WebSocket را به‌طور پیش‌فرض برای `openai/*` و `openai-codex/*` فعال می‌کند. + OpenClaw گرم‌سازی WebSocket را به‌طور پیش‌فرض برای `openai/*` و `openai-codex/*` فعال می‌کند تا تأخیر نوبت اول را کاهش دهد. ```json5 // Disable warm-up @@ -715,12 +758,12 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای - OpenClaw یک کلید مشترک حالت سریع را برای `openai/*` و `openai-codex/*` ارائه می‌کند: + OpenClaw یک سوییچ مشترک حالت سریع برای `openai/*` و `openai-codex/*` ارائه می‌کند: - **Chat/UI:** `/fast status|on|off` - **پیکربندی:** `agents.defaults.models["/"].params.fastMode` - وقتی فعال باشد، OpenClaw حالت سریع را به پردازش اولویت‌دار OpenAI نگاشت می‌کند (`service_tier = "priority"`). مقدارهای موجود `service_tier` حفظ می‌شوند، و حالت سریع `reasoning` یا `text.verbosity` را بازنویسی نمی‌کند. + وقتی فعال باشد، OpenClaw حالت سریع را به پردازش اولویت‌دار OpenAI نگاشت می‌کند (`service_tier = "priority"`). مقدارهای موجود `service_tier` حفظ می‌شوند و حالت سریع `reasoning` یا `text.verbosity` را بازنویسی نمی‌کند. ```json5 { @@ -735,13 +778,13 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای ``` - بازنویسی‌های نشست بر پیکربندی مقدم‌اند. پاک کردن بازنویسی نشست در UI نشست‌ها، نشست را به پیش‌فرض پیکربندی‌شده برمی‌گرداند. + بازنویسی‌های نشست بر پیکربندی مقدم‌اند. پاک‌کردن بازنویسی نشست در UI نشست‌ها، نشست را به پیش‌فرض پیکربندی‌شده برمی‌گرداند. - API متعلق به OpenAI پردازش اولویت‌دار را از طریق `service_tier` ارائه می‌کند. آن را در OpenClaw برای هر مدل تنظیم کنید: + API OpenAI پردازش اولویت‌دار را از طریق `service_tier` ارائه می‌کند. آن را برای هر مدل در OpenClaw تنظیم کنید: ```json5 { @@ -758,23 +801,23 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای مقدارهای پشتیبانی‌شده: `auto`، `default`، `flex`، `priority`. - `serviceTier` فقط به نقاط پایانی بومی OpenAI (`api.openai.com`) و نقاط پایانی بومی Codex (`chatgpt.com/backend-api`) ارسال می‌شود. اگر هر یک از ارائه‌دهنده‌ها را از طریق پراکسی مسیردهی کنید، OpenClaw مقدار `service_tier` را دست‌نخورده می‌گذارد. + `serviceTier` فقط به نقطه‌های پایانی بومی OpenAI (`api.openai.com`) و نقطه‌های پایانی بومی Codex (`chatgpt.com/backend-api`) ارسال می‌شود. اگر هرکدام از ارائه‌دهنده‌ها را از طریق پراکسی مسیریابی کنید، OpenClaw `service_tier` را دست‌نخورده می‌گذارد. - - برای مدل‌های مستقیم OpenAI Responses (`openai/*` روی `api.openai.com`)، wrapper استریم Pi-harness متعلق به Plugin OpenAI به‌طور خودکار Compaction سمت سرور را فعال می‌کند: + + برای مدل‌های مستقیم OpenAI Responses (`openai/*` روی `api.openai.com`)، پوشش‌دهنده‌ی جریان Pi-harness مربوط به Plugin OpenAI به‌طور خودکار compaction سمت سرور را فعال می‌کند: - `store: true` را اجباری می‌کند (مگر اینکه سازگاری مدل `supportsStore: false` را تنظیم کند) - `context_management: [{ type: "compaction", compact_threshold: ... }]` را تزریق می‌کند - `compact_threshold` پیش‌فرض: ۷۰٪ از `contextWindow` (یا `80000` وقتی در دسترس نباشد) - این برای مسیر Pi harness داخلی و برای hookهای ارائه‌دهنده OpenAI که توسط اجراهای embedded استفاده می‌شوند اعمال می‌شود. harness بومی app-server متعلق به Codex، context خودش را از طریق Codex مدیریت می‌کند و جداگانه با `agents.defaults.agentRuntime.id` پیکربندی می‌شود. + این برای مسیر Pi harness داخلی و برای hookهای ارائه‌دهنده‌ی OpenAI که توسط اجراهای embedded استفاده می‌شوند اعمال می‌شود. harness بومی سرور اپ Codex زمینه‌ی خودش را از طریق Codex مدیریت می‌کند و جداگانه با `agents.defaults.agentRuntime.id` پیکربندی می‌شود. - برای نقاط پایانی سازگار مانند Azure OpenAI Responses مفید است: + برای نقطه‌های پایانی سازگار مانند Azure OpenAI Responses مفید است: ```json5 { @@ -790,7 +833,7 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای } ``` - + ```json5 { agents: { @@ -826,13 +869,13 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای - `responsesServerCompaction` فقط تزریق `context_management` را کنترل می‌کند. مدل‌های مستقیم OpenAI Responses همچنان `store: true` را اجباری می‌کنند، مگر اینکه سازگاری `supportsStore: false` را تنظیم کند. + `responsesServerCompaction` فقط تزریق `context_management` را کنترل می‌کند. مدل‌های مستقیم OpenAI Responses همچنان `store: true` را اجبار می‌کنند، مگر اینکه سازگاری `supportsStore: false` را تنظیم کند. - - برای اجراهای خانواده GPT-5 روی `openai/*`، OpenClaw می‌تواند از یک قرارداد اجرای تعبیه‌شده سخت‌گیرانه‌تر استفاده کند: + + برای اجراهای خانوادهٔ GPT-5 روی `openai/*`، OpenClaw می‌تواند از یک قرارداد اجرای تعبیه‌شدهٔ سخت‌گیرانه‌تر استفاده کند: ```json5 { @@ -845,33 +888,33 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای ``` با `strict-agentic`، OpenClaw: - - دیگر وقتی یک اقدام ابزار در دسترس است، نوبت فقط-برنامه را پیشرفت موفق محسوب نمی‌کند - - نوبت را با هدایت برای اقدام فوری دوباره امتحان می‌کند - - برای کارهای قابل توجه، `update_plan` را به‌صورت خودکار فعال می‌کند - - اگر مدل همچنان بدون اقدام برنامه‌ریزی کند، وضعیت مسدودشده صریحی را نشان می‌دهد + - وقتی یک اقدام ابزاری در دسترس است، دیگر یک نوبت فقط شامل طرح را پیشرفت موفق تلقی نمی‌کند + - نوبت را با یک هدایت برای اقدام فوری دوباره تلاش می‌کند + - برای کارهای قابل‌توجه `update_plan` را به‌طور خودکار فعال می‌کند + - اگر مدل همچنان بدون اقدام فقط برنامه‌ریزی کند، یک وضعیت مسدودشدهٔ صریح را نمایش می‌دهد - فقط به اجراهای OpenAI و Codex از خانواده GPT-5 محدود است. ارائه‌دهندگان دیگر و خانواده‌های مدل قدیمی‌تر رفتار پیش‌فرض را نگه می‌دارند. + فقط به اجراهای OpenAI و Codex از خانوادهٔ GPT-5 محدود است. ارائه‌دهندگان دیگر و خانواده‌های مدل قدیمی‌تر رفتار پیش‌فرض را حفظ می‌کنند. - OpenClaw نقاط پایانی مستقیم OpenAI، Codex و Azure OpenAI را متفاوت از پراکسی‌های عمومی سازگار با OpenAI در `/v1` در نظر می‌گیرد: + OpenClaw نقاط پایانی مستقیم OpenAI، Codex، و Azure OpenAI را متفاوت از پراکسی‌های عمومی سازگار با OpenAI در `/v1` در نظر می‌گیرد: **مسیرهای بومی** (`openai/*`، Azure OpenAI): - `reasoning: { effort: "none" }` را فقط برای مدل‌هایی نگه می‌دارد که از تلاش `none` در OpenAI پشتیبانی می‌کنند - - reasoning غیرفعال را برای مدل‌ها یا پراکسی‌هایی که `reasoning.effort: "none"` را رد می‌کنند حذف می‌کند + - استدلال غیرفعال را برای مدل‌ها یا پراکسی‌هایی که `reasoning.effort: "none"` را رد می‌کنند حذف می‌کند - طرح‌واره‌های ابزار را به‌طور پیش‌فرض روی حالت سخت‌گیرانه می‌گذارد - - سرآیندهای انتساب پنهان را فقط روی میزبان‌های بومی تأییدشده اضافه می‌کند - - شکل‌دهی درخواست مخصوص OpenAI را نگه می‌دارد (`service_tier`، `store`، سازگاری reasoning، راهنمایی‌های prompt-cache) + - سرآیندهای انتساب پنهان را فقط روی میزبان‌های بومی تأییدشده پیوست می‌کند + - شکل‌دهی درخواست مختص OpenAI را نگه می‌دارد (`service_tier`، `store`، سازگاری استدلال، راهنمایی‌های کش اعلان) **مسیرهای پراکسی/سازگار:** - - از رفتار سازگاری آزادتر استفاده می‌کند - - `store` مربوط به Completions را از payloadهای غیر بومی `openai-completions` حذف می‌کند - - عبور JSON پیشرفته `params.extra_body`/`params.extraBody` را برای پراکسی‌های Completions سازگار با OpenAI می‌پذیرد - - `params.chat_template_kwargs` را برای پراکسی‌های Completions سازگار با OpenAI مانند vLLM می‌پذیرد - - طرح‌واره‌های سخت‌گیرانه ابزار یا سرآیندهای فقط-بومی را اجباری نمی‌کند + - از رفتار سازگاری آزادتر استفاده می‌کنند + - `store` در Completions را از payloadهای غیربومی `openai-completions` حذف می‌کنند + - عبور JSON پیشرفتهٔ `params.extra_body`/`params.extraBody` را برای پراکسی‌های Completions سازگار با OpenAI می‌پذیرند + - `params.chat_template_kwargs` را برای پراکسی‌های Completions سازگار با OpenAI مانند vLLM می‌پذیرند + - طرح‌واره‌های ابزار سخت‌گیرانه یا سرآیندهای فقط بومی را اجبار نمی‌کنند Azure OpenAI از انتقال بومی و رفتار سازگاری استفاده می‌کند، اما سرآیندهای انتساب پنهان را دریافت نمی‌کند. @@ -882,7 +925,7 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای - انتخاب ارائه‌دهندگان، ارجاع‌های مدل و رفتار failover. + انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover. پارامترهای ابزار تصویر مشترک و انتخاب ارائه‌دهنده. @@ -891,6 +934,6 @@ OpenClaw را دریافت نمی‌کند — آکاردئون **مسیرهای پارامترهای ابزار ویدئوی مشترک و انتخاب ارائه‌دهنده. - جزئیات احراز هویت و قواعد استفاده دوباره از اعتبارنامه‌ها. + جزئیات احراز هویت و قواعد استفادهٔ دوباره از اعتبارنامه. diff --git a/docs/fa/reference/memory-config.md b/docs/fa/reference/memory-config.md index caa67f04b..47220d659 100644 --- a/docs/fa/reference/memory-config.md +++ b/docs/fa/reference/memory-config.md @@ -2,63 +2,63 @@ read_when: - می‌خواهید ارائه‌دهندگان جست‌وجوی حافظه یا مدل‌های تعبیه‌سازی را پیکربندی کنید - می‌خواهید بک‌اند QMD را راه‌اندازی کنید - - می‌خواهید جست‌وجوی ترکیبی، MMR یا افت زمانی را تنظیم کنید + - می‌خواهید جست‌وجوی ترکیبی، MMR یا زوال زمانی را تنظیم کنید - می‌خواهید نمایه‌سازی حافظهٔ چندوجهی را فعال کنید sidebarTitle: Memory config summary: همهٔ گزینه‌های پیکربندی برای جست‌وجوی حافظه، ارائه‌دهندگان تعبیه، QMD، جست‌وجوی ترکیبی و نمایه‌سازی چندوجهی title: مرجع پیکربندی حافظه x-i18n: - generated_at: "2026-04-29T23:32:01Z" + generated_at: "2026-04-30T16:30:44Z" model: gpt-5.5 provider: openai - source_hash: fbb21d407f7ec9ef76e68c268138892b12568137735b723579703e535d34b195 + source_hash: 58b75751a19afb883fd7646cf5f71859f95bac468b2bfd8cc79db12ae892f70f source_path: reference/memory-config.md workflow: 16 --- -این صفحه همهٔ گزینه‌های پیکربندی جست‌وجوی حافظه برای OpenClaw را فهرست می‌کند. برای مرورهای مفهومی، ببینید: +این صفحه همه‌ی تنظیمات پیکربندی برای جست‌وجوی حافظه‌ی OpenClaw را فهرست می‌کند. برای مرورهای مفهومی، ببینید: - + حافظه چگونه کار می‌کند. - + بک‌اند پیش‌فرض SQLite. - - سایدکار با اولویت محلی. + + سایدکار local-first. - - خط لولهٔ جست‌وجو و تنظیم آن. + + پایپ‌لاین جست‌وجو و تنظیم آن. - + زیرعامل حافظه برای نشست‌های تعاملی. -همهٔ تنظیمات جست‌وجوی حافظه زیر `agents.defaults.memorySearch` در `openclaw.json` قرار دارند، مگر اینکه خلاف آن ذکر شده باشد. +همه‌ی تنظیمات جست‌وجوی حافظه، مگر اینکه خلاف آن ذکر شده باشد، زیر `agents.defaults.memorySearch` در `openclaw.json` قرار دارند. اگر به دنبال کلید فعال‌سازی قابلیت **active memory** و پیکربندی زیرعامل هستید، این مورد به‌جای `memorySearch` زیر `plugins.entries.active-memory` قرار دارد. Active memory از یک مدل دو دروازه‌ای استفاده می‌کند: -1. Plugin باید فعال باشد و شناسهٔ عامل فعلی را هدف بگیرد -2. درخواست باید یک نشست گفت‌وگوی پایدار تعاملی واجد شرایط باشد +1. Plugin باید فعال باشد و شناسه‌ی عامل فعلی را هدف بگیرد +2. درخواست باید یک نشست چت پایدار تعاملی واجد شرایط باشد -برای مدل فعال‌سازی، پیکربندی متعلق به Plugin، پایداری رونوشت، و الگوی عرضهٔ ایمن، [Active Memory](/fa/concepts/active-memory) را ببینید. +برای مدل فعال‌سازی، پیکربندی تحت مالکیت Plugin، پایداری رونوشت، و الگوی rollout ایمن، [Active Memory](/fa/concepts/active-memory) را ببینید. --- ## انتخاب ارائه‌دهنده -| کلید | نوع | پیش‌فرض | توضیح | -| ---------- | --------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | تشخیص خودکار | شناسهٔ آداپتور embedding مانند `bedrock`، `deepinfra`، `gemini`، `github-copilot`، `local`، `mistral`، `ollama`، `openai`، یا `voyage`؛ همچنین می‌تواند یک `models.providers.` پیکربندی‌شده باشد که `api` آن به یکی از این آداپتورها اشاره می‌کند | -| `model` | `string` | پیش‌فرض ارائه‌دهنده | نام مدل embedding | -| `fallback` | `string` | `"none"` | شناسهٔ آداپتور جایگزین وقتی گزینهٔ اصلی شکست می‌خورد | -| `enabled` | `boolean` | `true` | فعال یا غیرفعال کردن جست‌وجوی حافظه | +| کلید | نوع | پیش‌فرض | توضیح | +| ---------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | تشخیص خودکار | شناسه‌ی آداپتر embedding مانند `bedrock`، `deepinfra`، `gemini`، `github-copilot`، `local`، `mistral`، `ollama`، `openai`، یا `voyage`؛ همچنین می‌تواند یک `models.providers.` پیکربندی‌شده باشد که `api` آن به یکی از این آداپترها اشاره می‌کند | +| `model` | `string` | پیش‌فرض ارائه‌دهنده | نام مدل embedding | +| `fallback` | `string` | `"none"` | شناسه‌ی آداپتر جایگزین وقتی مورد اصلی شکست می‌خورد | +| `enabled` | `boolean` | `true` | فعال یا غیرفعال کردن جست‌وجوی حافظه | ### ترتیب تشخیص خودکار @@ -69,33 +69,33 @@ Active memory از یک مدل دو دروازه‌ای استفاده می‌ک اگر `memorySearch.local.modelPath` پیکربندی شده باشد و فایل وجود داشته باشد، انتخاب می‌شود. - اگر توکن GitHub Copilot قابل حل باشد (متغیر محیطی یا پروفایل احراز هویت)، انتخاب می‌شود. + اگر یک توکن GitHub Copilot قابل resolve باشد (متغیر محیطی یا پروفایل auth)، انتخاب می‌شود. - اگر کلید OpenAI قابل حل باشد، انتخاب می‌شود. + اگر یک کلید OpenAI قابل resolve باشد، انتخاب می‌شود. - اگر کلید Gemini قابل حل باشد، انتخاب می‌شود. + اگر یک کلید Gemini قابل resolve باشد، انتخاب می‌شود. - اگر کلید Voyage قابل حل باشد، انتخاب می‌شود. + اگر یک کلید Voyage قابل resolve باشد، انتخاب می‌شود. - اگر کلید Mistral قابل حل باشد، انتخاب می‌شود. + اگر یک کلید Mistral قابل resolve باشد، انتخاب می‌شود. - اگر کلید DeepInfra قابل حل باشد، انتخاب می‌شود. + اگر یک کلید DeepInfra قابل resolve باشد، انتخاب می‌شود. - اگر زنجیرهٔ اعتبارنامهٔ AWS SDK قابل حل باشد (نقش نمونه، کلیدهای دسترسی، پروفایل، SSO، هویت وب، یا پیکربندی مشترک)، انتخاب می‌شود. + اگر زنجیره‌ی اعتبارنامه‌ی AWS SDK resolve شود (نقش instance، کلیدهای دسترسی، پروفایل، SSO، هویت وب، یا پیکربندی اشتراکی)، انتخاب می‌شود. `ollama` پشتیبانی می‌شود اما به‌صورت خودکار تشخیص داده نمی‌شود (آن را صریح تنظیم کنید). -### شناسه‌های سفارشی ارائه‌دهنده +### شناسه‌های ارائه‌دهنده‌ی سفارشی -`memorySearch.provider` می‌تواند به یک ورودی سفارشی `models.providers.` اشاره کند. OpenClaw مالک `api` آن ارائه‌دهنده را برای آداپتور embedding حل می‌کند، در حالی که شناسهٔ سفارشی ارائه‌دهنده را برای endpoint، احراز هویت، و مدیریت پیشوند مدل حفظ می‌کند. این کار به چیدمان‌های چند GPU یا چند میزبان اجازه می‌دهد embeddingهای حافظه را به یک endpoint محلی مشخص اختصاص دهند: +`memorySearch.provider` می‌تواند به یک ورودی سفارشی `models.providers.` اشاره کند. OpenClaw مالک `api` آن ارائه‌دهنده را برای آداپتر embedding resolve می‌کند، در حالی که شناسه‌ی ارائه‌دهنده‌ی سفارشی را برای مدیریت endpoint، auth و پیشوند مدل حفظ می‌کند. این کار به راه‌اندازی‌های چند GPU یا چند میزبان اجازه می‌دهد embeddingهای حافظه را به یک endpoint محلی مشخص اختصاص دهند: ```json5 { @@ -120,18 +120,18 @@ Active memory از یک مدل دو دروازه‌ای استفاده می‌ک } ``` -### حل API key +### resolve کردن کلید API -embeddingهای راه‌دور به API key نیاز دارند. Bedrock به‌جای آن از زنجیرهٔ اعتبارنامهٔ پیش‌فرض AWS SDK استفاده می‌کند (نقش‌های نمونه، SSO، کلیدهای دسترسی). +Embeddingهای remote به یک کلید API نیاز دارند. Bedrock به‌جای آن از زنجیره‌ی اعتبارنامه‌ی پیش‌فرض AWS SDK استفاده می‌کند (نقش‌های instance، SSO، کلیدهای دسترسی). -| ارائه‌دهنده | متغیر محیطی | کلید پیکربندی | +| ارائه‌دهنده | متغیر محیطی | کلید پیکربندی | | -------------- | -------------------------------------------------- | ----------------------------------- | -| Bedrock | زنجیرهٔ اعتبارنامهٔ AWS | به API key نیاز نیست | +| Bedrock | زنجیره‌ی اعتبارنامه‌ی AWS | به کلید API نیاز نیست | | DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` | | Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | پروفایل احراز هویت از طریق ورود دستگاه | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | پروفایل auth از طریق ورود دستگاه | | Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY` (placeholder) | -- | +| Ollama | `OLLAMA_API_KEY` (جای‌نگهدار) | -- | | OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | | Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | @@ -141,18 +141,18 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ --- -## پیکربندی endpoint راه‌دور +## پیکربندی endpoint remote -برای endpointهای سفارشی سازگار با OpenAI یا بازنویسی پیش‌فرض‌های ارائه‌دهنده: +برای endpointهای سفارشی سازگار با OpenAI یا override کردن پیش‌فرض‌های ارائه‌دهنده: - URL پایهٔ API سفارشی. + URL پایه‌ی API سفارشی. - بازنویسی API key. + override کردن کلید API. - سرآیندهای HTTP اضافی (با پیش‌فرض‌های ارائه‌دهنده ادغام می‌شوند). + هدرهای HTTP اضافی (با پیش‌فرض‌های ارائه‌دهنده ادغام می‌شوند). ```json5 @@ -174,28 +174,28 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ --- -## پیکربندی ویژهٔ ارائه‌دهنده +## پیکربندی ویژه‌ی ارائه‌دهنده - | کلید | نوع | پیش‌فرض | توضیح | + | کلید | نوع | پیش‌فرض | توضیح | | ---------------------- | -------- | ---------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | از `gemini-embedding-2-preview` نیز پشتیبانی می‌کند | - | `outputDimensionality` | `number` | `3072` | برای Embedding 2: 768، 1536، یا 3072 | + | `outputDimensionality` | `number` | `3072` | برای Embedding 2: 768، 1536، یا 3072 | - تغییر مدل یا `outputDimensionality` باعث اجرای خودکار بازنمایه‌سازی کامل می‌شود. + تغییر مدل یا `outputDimensionality` باعث reindex کامل خودکار می‌شود. - - endpointهای embedding سازگار با OpenAI می‌توانند از فیلدهای درخواست `input_type` ویژهٔ ارائه‌دهنده استفاده کنند. این برای مدل‌های embedding نامتقارن که برای embeddingهای پرس‌وجو و سند به برچسب‌های متفاوت نیاز دارند، مفید است. + + Endpointهای embedding سازگار با OpenAI می‌توانند فیلدهای درخواست `input_type` ویژه‌ی ارائه‌دهنده را فعال کنند. این برای مدل‌های embedding نامتقارن که برای embeddingهای پرس‌وجو و سند به برچسب‌های متفاوت نیاز دارند مفید است. - | کلید | نوع | پیش‌فرض | توضیح | - | ------------------- | -------- | ------------ | ---------------------------------------------------- | - | `inputType` | `string` | تنظیم‌نشده | `input_type` مشترک برای embeddingهای پرس‌وجو و سند | - | `queryInputType` | `string` | تنظیم‌نشده | `input_type` هنگام پرس‌وجو؛ `inputType` را بازنویسی می‌کند | - | `documentInputType` | `string` | تنظیم‌نشده | `input_type` نمایه/سند؛ `inputType` را بازنویسی می‌کند | + | کلید | نوع | پیش‌فرض | توضیح | + | ------------------- | -------- | ------- | ------------------------------------------------------- | + | `inputType` | `string` | تنظیم‌نشده | `input_type` مشترک برای embeddingهای پرس‌وجو و سند | + | `queryInputType` | `string` | تنظیم‌نشده | `input_type` هنگام پرس‌وجو؛ `inputType` را override می‌کند | + | `documentInputType` | `string` | تنظیم‌نشده | `input_type` شاخص/سند؛ `inputType` را override می‌کند | ```json5 { @@ -216,11 +216,11 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ } ``` - تغییر این مقادیر بر هویت کش embedding برای نمایه‌سازی دسته‌ای ارائه‌دهنده اثر می‌گذارد و وقتی مدل بالادستی با برچسب‌ها رفتار متفاوتی دارد، باید پس از آن بازنمایه‌سازی حافظه انجام شود. + تغییر این مقادیر بر هویت کش embedding برای index کردن دسته‌ای ارائه‌دهنده اثر می‌گذارد و وقتی مدل بالادستی با برچسب‌ها رفتار متفاوتی دارد، باید پس از آن حافظه reindex شود. - Bedrock از زنجیرهٔ اعتبارنامهٔ پیش‌فرض AWS SDK استفاده می‌کند؛ نیازی به API key نیست. اگر OpenClaw روی EC2 با نقش نمونهٔ دارای Bedrock اجرا می‌شود، فقط ارائه‌دهنده و مدل را تنظیم کنید: + Bedrock از زنجیره‌ی اعتبارنامه‌ی پیش‌فرض AWS SDK استفاده می‌کند — به کلیدهای API نیاز نیست. اگر OpenClaw روی EC2 با یک نقش instance فعال برای Bedrock اجرا می‌شود، فقط ارائه‌دهنده و مدل را تنظیم کنید: ```json5 { @@ -235,37 +235,37 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ } ``` - | کلید | نوع | پیش‌فرض | توضیح | - | ---------------------- | -------- | ----------------------------- | ----------------------------- | - | `model` | `string` | `amazon.titan-embed-text-v2:0` | هر شناسهٔ مدل embedding در Bedrock | - | `outputDimensionality` | `number` | پیش‌فرض مدل | برای Titan V2: 256، 512، یا 1024 | + | کلید | نوع | پیش‌فرض | توضیح | + | ---------------------- | -------- | ------------------------------ | ------------------------------- | + | `model` | `string` | `amazon.titan-embed-text-v2:0` | هر شناسه‌ی مدل embedding در Bedrock | + | `outputDimensionality` | `number` | پیش‌فرض مدل | برای Titan V2: 256، 512، یا 1024 | **مدل‌های پشتیبانی‌شده** (با تشخیص خانواده و پیش‌فرض‌های بُعد): - | شناسهٔ مدل | ارائه‌دهنده | ابعاد پیش‌فرض | ابعاد قابل پیکربندی | - | ------------------------------------------- | ------------ | ------------- | ------------------- | - | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256، 512، 1024 | - | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | - | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | - | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | - | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256، 384، 1024، 3072 | - | `cohere.embed-english-v3` | Cohere | 1024 | -- | - | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | - | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | - | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | - | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | + | شناسه‌ی مدل | ارائه‌دهنده | ابعاد پیش‌فرض | ابعاد قابل پیکربندی | + | ------------------------------------------ | ---------- | ------------ | -------------------- | + | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256، 512، 1024 | + | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | + | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | + | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | + | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256، 384، 1024، 3072 | + | `cohere.embed-english-v3` | Cohere | 1024 | -- | + | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | + | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | + | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | + | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | - گونه‌های دارای پسوند توان عملیاتی (برای مثال، `amazon.titan-embed-text-v1:2:8k`) پیکربندی مدل پایه را به ارث می‌برند. + گونه‌های دارای پسوند throughput (برای مثال، `amazon.titan-embed-text-v1:2:8k`) پیکربندی مدل پایه را به ارث می‌برند. - **احراز هویت:** احراز هویت Bedrock از ترتیب استاندارد حل اعتبارنامهٔ AWS SDK استفاده می‌کند: + **احراز هویت:** احراز هویت Bedrock از ترتیب استاندارد resolve کردن اعتبارنامه در AWS SDK استفاده می‌کند: 1. متغیرهای محیطی (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. کش توکن SSO 3. اعتبارنامه‌های توکن هویت وب - 4. فایل‌های اعتبارنامه و پیکربندی مشترک - 5. اعتبارنامه‌های فرادادهٔ ECS یا EC2 + 4. فایل‌های اعتبارنامه و پیکربندی اشتراکی + 5. اعتبارنامه‌های metadata مربوط به ECS یا EC2 - Region از `AWS_REGION`، `AWS_DEFAULT_REGION`، `baseUrl` ارائه‌دهندهٔ `amazon-bedrock` حل می‌شود، یا به‌صورت پیش‌فرض `us-east-1` است. + Region از `AWS_REGION`، `AWS_DEFAULT_REGION`، `baseUrl` ارائه‌دهنده‌ی `amazon-bedrock` resolve می‌شود، یا به‌صورت پیش‌فرض `us-east-1` است. **مجوزهای IAM:** نقش یا کاربر IAM به این موارد نیاز دارد: @@ -277,30 +277,30 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ } ``` - برای اصل حداقل امتیاز، دامنهٔ `InvokeModel` را به مدل مشخص محدود کنید: + برای کمترین سطح دسترسی، دامنه‌ی `InvokeModel` را به مدل مشخص محدود کنید: ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ``` - - | کلید | نوع | پیش‌فرض | توضیح | - | --------------------- | ------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `local.modelPath` | `string` | دانلود خودکار | مسیر فایل مدل GGUF | - | `local.modelCacheDir` | `string` | پیش‌فرض node-llama-cpp | دایرکتوری کش برای مدل‌های دانلودشده | - | `local.contextSize` | `number \| "auto"` | `4096` | اندازه پنجره زمینه برای زمینه embedding. مقدار 4096 قطعه‌های معمولی (128 تا 512 توکن) را پوشش می‌دهد و هم‌زمان VRAM غیرمرتبط با وزن‌ها را محدود نگه می‌دارد. روی میزبان‌های محدود، آن را به 1024 تا 2048 کاهش دهید. `"auto"` از حداکثر آموزش‌دیده مدل استفاده می‌کند - برای مدل‌های 8B+ توصیه نمی‌شود (Qwen3-Embedding-8B: 40 960 توکن → حدود 32 گیگابایت VRAM در برابر حدود 8.8 گیگابایت در 4096). | + + | کلید | نوع | پیش‌فرض | توضیح | + | --------------------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `local.modelPath` | `string` | بارگیری خودکار | مسیر فایل مدل GGUF | + | `local.modelCacheDir` | `string` | پیش‌فرض node-llama-cpp | دایرکتوری کش برای مدل‌های بارگیری‌شده | + | `local.contextSize` | `number \| "auto"` | `4096` | اندازه پنجره زمینه برای زمینه embedding. مقدار 4096 قطعه‌های معمولی (128 تا 512 توکن) را پوشش می‌دهد و در عین حال VRAM غیرمرتبط با وزن‌ها را محدود می‌کند. در میزبان‌های محدود، آن را به 1024 تا 2048 کاهش دهید. `"auto"` از بیشینه آموزش‌دیده مدل استفاده می‌کند؛ برای مدل‌های 8B+ توصیه نمی‌شود (Qwen3-Embedding-8B: 40 960 توکن → حدود 32 گیگابایت VRAM در برابر حدود 8.8 گیگابایت در 4096). | - مدل پیش‌فرض: `embeddinggemma-300m-qat-Q8_0.gguf` (حدود 0.6 گیگابایت، دانلود خودکار). به بیلد بومی نیاز دارد: ابتدا `pnpm approve-builds` و سپس `pnpm rebuild node-llama-cpp`. + مدل پیش‌فرض: `embeddinggemma-300m-qat-Q8_0.gguf` (حدود 0.6 گیگابایت، با بارگیری خودکار). نصب‌های بسته‌بندی‌شده، هنگام پیکربندی `provider: "local"`، runtime بومی `node-llama-cpp` را از طریق وابستگی‌های runtime مدیریت‌شده Plugin ترمیم می‌کنند. checkoutهای سورس همچنان به تأیید ساخت بومی نیاز دارند: ابتدا `pnpm approve-builds` و سپس `pnpm rebuild node-llama-cpp`. - از CLI مستقل استفاده کنید تا همان مسیر provider را که Gateway استفاده می‌کند بررسی کنید: + از CLI مستقل استفاده کنید تا همان مسیر provider را که Gateway استفاده می‌کند تأیید کنید: ```bash openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` - اگر `provider` برابر `auto` باشد، `local` فقط زمانی انتخاب می‌شود که `local.modelPath` به یک فایل محلی موجود اشاره کند. ارجاع‌های مدل `hf:` و HTTP(S) همچنان می‌توانند به‌طور صریح با `provider: "local"` استفاده شوند، اما باعث نمی‌شوند `auto` پیش از در دسترس بودن مدل روی دیسک، local را انتخاب کند. + اگر `provider` برابر `auto` باشد، `local` فقط زمانی انتخاب می‌شود که `local.modelPath` به یک فایل محلی موجود اشاره کند. ارجاع‌های مدل `hf:` و HTTP(S) همچنان می‌توانند به‌صراحت با `provider: "local"` استفاده شوند، اما پیش از آنکه مدل روی دیسک در دسترس باشد باعث نمی‌شوند `auto` گزینه local را انتخاب کند. @@ -308,43 +308,43 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ ### مهلت زمانی embedding درون‌خطی - مهلت زمانی دسته‌های embedding درون‌خطی هنگام نمایه‌سازی حافظه را بازنویسی کنید. + مهلت زمانی batchهای embedding درون‌خطی را هنگام ایندکس‌سازی حافظه بازنویسی کنید. -در صورت تنظیم نشدن، از پیش‌فرض provider استفاده می‌شود: 600 ثانیه برای providerهای محلی/خودمیزبان مانند `local`، `ollama` و `lmstudio`، و 120 ثانیه برای providerهای میزبانی‌شده. وقتی دسته‌های embedding محلی وابسته به CPU سالم اما کند هستند، این مقدار را افزایش دهید. +در حالت تنظیم‌نشده از پیش‌فرض provider استفاده می‌شود: 600 ثانیه برای providerهای local/self-hosted مانند `local`، `ollama` و `lmstudio`، و 120 ثانیه برای providerهای میزبانی‌شده. وقتی batchهای embedding محلیِ وابسته به CPU سالم اما کند هستند، این مقدار را افزایش دهید. --- ## پیکربندی جست‌وجوی ترکیبی -همه موارد زیر `memorySearch.query.hybrid` قرار دارند: +همه زیر `memorySearch.query.hybrid` قرار دارند: -| کلید | نوع | پیش‌فرض | توضیح | -| --------------------- | --------- | ------- | ------------------------------------- | -| `enabled` | `boolean` | `true` | فعال‌سازی جست‌وجوی ترکیبی BM25 + برداری | -| `vectorWeight` | `number` | `0.7` | وزن امتیازهای برداری (0-1) | -| `textWeight` | `number` | `0.3` | وزن امتیازهای BM25 (0-1) | -| `candidateMultiplier` | `number` | `4` | ضریب اندازه مجموعه نامزدها | +| کلید | نوع | پیش‌فرض | توضیح | +| --------------------- | --------- | ------- | ---------------------------------- | +| `enabled` | `boolean` | `true` | جست‌وجوی ترکیبی BM25 + برداری را فعال می‌کند | +| `vectorWeight` | `number` | `0.7` | وزن امتیازهای برداری (0-1) | +| `textWeight` | `number` | `0.3` | وزن امتیازهای BM25 (0-1) | +| `candidateMultiplier` | `number` | `4` | ضریب اندازه مجموعه نامزدها | - - | کلید | نوع | پیش‌فرض | توضیح | - | ------------- | --------- | ------- | -------------------------------------- | - | `mmr.enabled` | `boolean` | `false` | فعال‌سازی رتبه‌بندی دوباره MMR | - | `mmr.lambda` | `number` | `0.7` | 0 = بیشترین تنوع، 1 = بیشترین ارتباط | + + | کلید | نوع | پیش‌فرض | توضیح | + | ------------- | --------- | ------- | --------------------------------------- | + | `mmr.enabled` | `boolean` | `false` | بازرتبه‌بندی MMR را فعال می‌کند | + | `mmr.lambda` | `number` | `0.7` | 0 = بیشینه تنوع، 1 = بیشینه ارتباط | - - | کلید | نوع | پیش‌فرض | توضیح | - | ---------------------------- | --------- | ------- | ----------------------------- | - | `temporalDecay.enabled` | `boolean` | `false` | فعال‌سازی تقویت تازگی | - | `temporalDecay.halfLifeDays` | `number` | `30` | امتیاز هر N روز نصف می‌شود | + + | کلید | نوع | پیش‌فرض | توضیح | + | ---------------------------- | --------- | ------- | -------------------------------- | + | `temporalDecay.enabled` | `boolean` | `false` | تقویت تازگی را فعال می‌کند | + | `temporalDecay.halfLifeDays` | `number` | `30` | امتیاز هر N روز نصف می‌شود | - فایل‌های همیشه‌سبز (`MEMORY.md`، فایل‌های بدون تاریخ در `memory/`) هرگز دچار کاهش نمی‌شوند. + فایل‌های همیشه‌سبز (`MEMORY.md`، فایل‌های بدون تاریخ در `memory/`) هرگز دچار افت زمانی نمی‌شوند. -### نمونه کامل +### مثال کامل ```json5 { @@ -369,9 +369,9 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ ## مسیرهای حافظه اضافی -| کلید | نوع | توضیح | -| ------------ | ---------- | ------------------------------------------ | -| `extraPaths` | `string[]` | دایرکتوری‌ها یا فایل‌های اضافی برای نمایه‌سازی | +| کلید | نوع | توضیح | +| ------------ | ---------- | -------------------------------------- | +| `extraPaths` | `string[]` | دایرکتوری‌ها یا فایل‌های اضافی برای ایندکس‌سازی | ```json5 { @@ -385,144 +385,144 @@ OAuth مربوط به Codex فقط چت/تکمیل‌ها را پوشش می‌ } ``` -مسیرها می‌توانند مطلق یا نسبی به workspace باشند. دایرکتوری‌ها به‌صورت بازگشتی برای فایل‌های `.md` پویش می‌شوند. نحوه مدیریت symlink به backend فعال بستگی دارد: موتور داخلی symlinkها را نادیده می‌گیرد، در حالی که QMD از رفتار اسکنر QMD زیربنایی پیروی می‌کند. +مسیرها می‌توانند مطلق یا نسبی نسبت به workspace باشند. دایرکتوری‌ها به‌صورت بازگشتی برای فایل‌های `.md` اسکن می‌شوند. نحوه رسیدگی به symlink به backend فعال بستگی دارد: موتور داخلی symlinkها را نادیده می‌گیرد، در حالی که QMD از رفتار scanner زیربنایی QMD پیروی می‌کند. -برای جست‌وجوی transcript میان‌عامل با دامنه عامل، به‌جای `memory.qmd.paths` از `agents.list[].memorySearch.qmd.extraCollections` استفاده کنید. آن مجموعه‌های اضافی همان شکل `{ path, name, pattern? }` را دنبال می‌کنند، اما برای هر عامل ادغام می‌شوند و وقتی مسیر به بیرون از workspace فعلی اشاره کند، می‌توانند نام‌های مشترک صریح را حفظ کنند. اگر همان مسیر resolve‌شده هم در `memory.qmd.paths` و هم در `memorySearch.qmd.extraCollections` ظاهر شود، QMD اولین ورودی را نگه می‌دارد و مورد تکراری را رد می‌کند. +برای جست‌وجوی transcript بین agentها در محدوده agent، به‌جای `memory.qmd.paths` از `agents.list[].memorySearch.qmd.extraCollections` استفاده کنید. آن collectionهای اضافی از همان شکل `{ path, name, pattern? }` پیروی می‌کنند، اما به ازای هر agent ادغام می‌شوند و وقتی مسیر به بیرون از workspace فعلی اشاره می‌کند می‌توانند نام‌های مشترک صریح را حفظ کنند. اگر همان مسیر resolve‌شده هم در `memory.qmd.paths` و هم در `memorySearch.qmd.extraCollections` ظاهر شود، QMD نخستین ورودی را نگه می‌دارد و مورد تکراری را رد می‌کند. --- -## حافظه چندوجهی (Gemini) +## حافظه چندرسانه‌ای (Gemini) -تصویرها و صدا را همراه با Markdown با استفاده از Gemini Embedding 2 نمایه‌سازی کنید: +تصاویر و صدا را در کنار Markdown با استفاده از Gemini Embedding 2 ایندکس کنید: -| کلید | نوع | پیش‌فرض | توضیح | -| ------------------------- | ---------- | ---------- | -------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | فعال‌سازی نمایه‌سازی چندوجهی | +| کلید | نوع | پیش‌فرض | توضیح | +| ------------------------- | ---------- | ---------- | ------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | ایندکس‌سازی چندرسانه‌ای را فعال می‌کند | | `multimodal.modalities` | `string[]` | -- | `["image"]`، `["audio"]`، یا `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | حداکثر اندازه فایل برای نمایه‌سازی | +| `multimodal.maxFileBytes` | `number` | `10000000` | بیشینه اندازه فایل برای ایندکس‌سازی | -فقط برای فایل‌های موجود در `extraPaths` اعمال می‌شود. ریشه‌های حافظهٔ پیش‌فرض فقط Markdown باقی می‌مانند. به `gemini-embedding-2-preview` نیاز دارد. `fallback` باید `"none"` باشد. +فقط روی فایل‌های موجود در `extraPaths` اعمال می‌شود. ریشه‌های حافظه پیش‌فرض فقط Markdown باقی می‌مانند. به `gemini-embedding-2-preview` نیاز دارد. `fallback` باید `"none"` باشد. -قالب‌های پشتیبانی‌شده: `.jpg`، `.jpeg`، `.png`، `.webp`، `.gif`، `.heic`، `.heif` (تصاویر)؛ `.mp3`، `.wav`، `.ogg`، `.opus`، `.m4a`، `.aac`، `.flac` (صوت). +فرمت‌های پشتیبانی‌شده: `.jpg`، `.jpeg`، `.png`، `.webp`، `.gif`، `.heic`، `.heif` (تصاویر)؛ `.mp3`، `.wav`، `.ogg`، `.opus`، `.m4a`، `.aac`، `.flac` (صدا). --- ## کش embedding -| کلید | نوع | پیش‌فرض | توضیح | -| ------------------ | --------- | ------- | ---------------------------------------- | -| `cache.enabled` | `boolean` | `false` | کش کردن embeddingهای قطعه‌ها در SQLite | -| `cache.maxEntries` | `number` | `50000` | بیشینهٔ embeddingهای کش‌شده | +| کلید | نوع | پیش‌فرض | توضیح | +| ------------------ | --------- | ------- | ---------------------------------- | +| `cache.enabled` | `boolean` | `false` | embeddingهای قطعه‌ها را در SQLite کش می‌کند | +| `cache.maxEntries` | `number` | `50000` | بیشینه embeddingهای کش‌شده | -از embedding دوبارهٔ متن تغییرنکرده هنگام reindex یا به‌روزرسانی‌های transcript جلوگیری می‌کند. +از embedding مجدد متن بدون تغییر هنگام reindex یا به‌روزرسانی transcript جلوگیری می‌کند. --- -## نمایه‌سازی دسته‌ای +## ایندکس‌سازی batch -| کلید | نوع | پیش‌فرض | توضیح | -| ----------------------------- | --------- | ------- | ------------------------ | -| `remote.nonBatchConcurrency` | `number` | `4` | embeddingهای درون‌خطی موازی | -| `remote.batch.enabled` | `boolean` | `false` | فعال‌سازی API embedding دسته‌ای | -| `remote.batch.concurrency` | `number` | `2` | کارهای دسته‌ای موازی | -| `remote.batch.wait` | `boolean` | `true` | انتظار برای تکمیل دسته | -| `remote.batch.pollIntervalMs` | `number` | -- | بازهٔ polling | -| `remote.batch.timeoutMinutes` | `number` | -- | مهلت زمانی دسته | +| کلید | نوع | پیش‌فرض | توضیح | +| ----------------------------- | --------- | ------- | -------------------------------- | +| `remote.nonBatchConcurrency` | `number` | `4` | embeddingهای درون‌خطی موازی | +| `remote.batch.enabled` | `boolean` | `false` | API embedding batch را فعال می‌کند | +| `remote.batch.concurrency` | `number` | `2` | کارهای batch موازی | +| `remote.batch.wait` | `boolean` | `true` | منتظر تکمیل batch می‌ماند | +| `remote.batch.pollIntervalMs` | `number` | -- | بازه نظرسنجی | +| `remote.batch.timeoutMinutes` | `number` | -- | مهلت زمانی batch | -برای `openai`، `gemini` و `voyage` در دسترس است. دسته‌ای OpenAI معمولاً برای backfillهای بزرگ سریع‌ترین و ارزان‌ترین گزینه است. +برای `openai`، `gemini` و `voyage` در دسترس است. batch در OpenAI معمولا برای backfillهای بزرگ سریع‌ترین و کم‌هزینه‌ترین گزینه است. -`remote.nonBatchConcurrency` فراخوانی‌های embedding درون‌خطی را کنترل می‌کند که ارائه‌دهندگان محلی/خودمیزبان و ارائه‌دهندگان میزبانی‌شده وقتی APIهای دسته‌ای ارائه‌دهنده فعال نیستند از آن‌ها استفاده می‌کنند. مقدار پیش‌فرض Ollama برای نمایه‌سازی غیردسته‌ای `1` است تا از فشار بیش از حد به میزبان‌های محلی کوچک‌تر جلوگیری شود؛ روی ماشین‌های بزرگ‌تر مقدار بالاتری تنظیم کنید. +`remote.nonBatchConcurrency` فراخوانی‌های embedding درون‌خطی را کنترل می‌کند که providerهای local/self-hosted و providerهای میزبانی‌شده هنگامی که APIهای batch مربوط به provider فعال نیستند از آن استفاده می‌کنند. مقدار پیش‌فرض Ollama برای ایندکس‌سازی غیر batch برابر `1` است تا میزبان‌های محلی کوچک‌تر بیش از حد تحت فشار قرار نگیرند؛ روی ماشین‌های بزرگ‌تر مقدار بالاتری تنظیم کنید. -این جدا از `sync.embeddingBatchTimeoutSeconds` است که مهلت زمانی فراخوانی‌های embedding درون‌خطی را کنترل می‌کند. +این مورد جدا از `sync.embeddingBatchTimeoutSeconds` است که مهلت زمانی فراخوانی‌های embedding درون‌خطی را کنترل می‌کند. --- -## جست‌وجوی حافظهٔ نشست (آزمایشی) +## جست‌وجوی حافظه جلسه (آزمایشی) -transcriptهای نشست را نمایه‌سازی کنید و از طریق `memory_search` نمایش دهید: +transcriptهای جلسه را ایندکس کنید و آن‌ها را از طریق `memory_search` ارائه دهید: -| کلید | نوع | پیش‌فرض | توضیح | -| ----------------------------- | ---------- | ------------ | -------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | فعال‌سازی نمایه‌سازی نشست | +| کلید | نوع | پیش‌فرض | توضیح | +| ----------------------------- | ---------- | ------------ | ------------------------------------------ | +| `experimental.sessionMemory` | `boolean` | `false` | ایندکس‌سازی جلسه را فعال می‌کند | | `sources` | `string[]` | `["memory"]` | برای شامل کردن transcriptها، `"sessions"` را اضافه کنید | -| `sync.sessions.deltaBytes` | `number` | `100000` | آستانهٔ بایت برای reindex | -| `sync.sessions.deltaMessages` | `number` | `50` | آستانهٔ پیام برای reindex | +| `sync.sessions.deltaBytes` | `number` | `100000` | آستانه بایت برای reindex | +| `sync.sessions.deltaMessages` | `number` | `50` | آستانه پیام برای reindex | -نمایه‌سازی نشست اختیاری است و به‌صورت ناهمگام اجرا می‌شود. نتایج ممکن است کمی قدیمی باشند. گزارش‌های نشست روی دیسک قرار دارند، بنابراین دسترسی به فایل‌سیستم را مرز اعتماد در نظر بگیرید. +ایندکس‌سازی جلسه opt-in است و به‌صورت ناهمگام اجرا می‌شود. نتایج ممکن است کمی stale باشند. لاگ‌های جلسه روی دیسک قرار دارند، بنابراین دسترسی به filesystem را مرز اعتماد در نظر بگیرید. --- ## شتاب‌دهی برداری SQLite (sqlite-vec) -| کلید | نوع | پیش‌فرض | توضیح | -| ---------------------------- | --------- | ------- | ------------------------------------ | -| `store.vector.enabled` | `boolean` | `true` | استفاده از sqlite-vec برای پرس‌وجوهای برداری | -| `store.vector.extensionPath` | `string` | همراه بسته | بازنویسی مسیر sqlite-vec | +| کلید | نوع | پیش‌فرض | توضیح | +| ---------------------------- | --------- | ------------ | ---------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | از sqlite-vec برای queryهای برداری استفاده می‌کند | +| `store.vector.extensionPath` | `string` | همراه بسته | مسیر sqlite-vec را بازنویسی می‌کند | -وقتی sqlite-vec در دسترس نباشد، OpenClaw به‌طور خودکار به شباهت کسینوسی درون‌پردازشی fallback می‌کند. +وقتی sqlite-vec در دسترس نباشد، OpenClaw به‌صورت خودکار به شباهت کسینوسی درون‌پردازشی برمی‌گردد. --- -## ذخیره‌سازی نمایه +## ذخیره‌سازی ایندکس | کلید | نوع | پیش‌فرض | توضیح | | --------------------- | -------- | ------------------------------------- | ------------------------------------------ | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | مکان نمایه (از توکن `{agentId}` پشتیبانی می‌کند) | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | مکان ایندکس (از توکن `{agentId}` پشتیبانی می‌کند) | | `store.fts.tokenizer` | `string` | `unicode61` | tokenizer مربوط به FTS5 (`unicode61` یا `trigram`) | --- -## پیکربندی backend مربوط به QMD +## پیکربندی backend QMD -برای فعال‌سازی، `memory.backend = "qmd"` را تنظیم کنید. همهٔ تنظیمات QMD زیر `memory.qmd` قرار دارند: +برای فعال‌سازی، `memory.backend = "qmd"` را تنظیم کنید. همه تنظیمات QMD زیر `memory.qmd` قرار دارند: -| کلید | نوع | پیش‌فرض | توضیح | -| ------------------------ | --------- | ------- | -------------------------------------------------------------------------------------- | -| `command` | `string` | `qmd` | مسیر فایل اجرایی QMD؛ وقتی `PATH` سرویس با shell شما متفاوت است، یک مسیر مطلق تنظیم کنید | -| `searchMode` | `string` | `search` | فرمان جست‌وجو: `search`، `vsearch`، `query` | -| `includeDefaultMemory` | `boolean` | `true` | نمایه‌سازی خودکار `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | مسیرهای اضافه: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | نمایه‌سازی transcriptهای نشست | -| `sessions.retentionDays` | `number` | -- | نگه‌داری transcript | -| `sessions.exportDir` | `string` | -- | دایرکتوری export | +| کلید | نوع | پیش‌فرض | توضیح | +| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- | +| `command` | `string` | `qmd` | مسیر اجرایی QMD؛ وقتی `PATH` سرویس با پوسته شما متفاوت است، یک مسیر مطلق تنظیم کنید | +| `searchMode` | `string` | `search` | فرمان جستجو: `search`، `vsearch`، `query` | +| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` را به‌صورت خودکار نمایه‌سازی کن | +| `paths[]` | `array` | -- | مسیرهای اضافی: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | رونوشت‌های نشست را نمایه‌سازی کن | +| `sessions.retentionDays` | `number` | -- | نگهداری رونوشت | +| `sessions.exportDir` | `string` | -- | دایرکتوری خروجی | -`searchMode: "search"` فقط واژگانی/BM25 است. OpenClaw برای این حالت، از جمله هنگام `memory status --deep`، کاوشگرهای آمادگی بردار معنایی یا نگهداری embedding در QMD را اجرا نمی‌کند؛ `vsearch` و `query` همچنان به آمادگی بردار QMD و embeddingها نیاز دارند. +`searchMode: "search"` فقط واژگانی/BM25 است. OpenClaw برای این حالت، از جمله هنگام `memory status --deep`، کاوشگرهای آمادگی بردار معنایی یا نگهداری تعبیه‌های QMD را اجرا نمی‌کند؛ `vsearch` و `query` همچنان به آمادگی برداری QMD و تعبیه‌ها نیاز دارند. -OpenClaw شکل‌های فعلی مجموعه QMD و پرس‌وجوی MCP را ترجیح می‌دهد، اما با تلاش برای پرچم‌های الگوی مجموعه سازگار و نام‌های قدیمی‌تر ابزار MCP در صورت نیاز، نسخه‌های قدیمی‌تر QMD را همچنان قابل استفاده نگه می‌دارد. وقتی QMD پشتیبانی از چند فیلتر مجموعه را اعلام می‌کند، مجموعه‌های هم‌منبع با یک فرایند QMD جست‌وجو می‌شوند؛ ساخت‌های قدیمی‌تر QMD مسیر سازگاری برای هر مجموعه را حفظ می‌کنند. هم‌منبع یعنی مجموعه‌های حافظه پایدار با هم گروه‌بندی می‌شوند، در حالی که مجموعه‌های رونوشت نشست در گروهی جدا می‌مانند تا تنوع منبع همچنان هر دو ورودی را داشته باشد. +OpenClaw شکل‌های فعلی مجموعه QMD و پرس‌وجوی MCP را ترجیح می‌دهد، اما با امتحان کردن پرچم‌های سازگار الگوی مجموعه و نام‌های قدیمی‌تر ابزار MCP در صورت نیاز، نسخه‌های قدیمی‌تر QMD را نیز فعال نگه می‌دارد. وقتی QMD پشتیبانی از چند فیلتر مجموعه را اعلام می‌کند، مجموعه‌های هم‌منبع با یک فرایند QMD جستجو می‌شوند؛ ساخت‌های قدیمی‌تر QMD مسیر سازگاری به‌ازای هر مجموعه را حفظ می‌کنند. هم‌منبع یعنی مجموعه‌های حافظه پایدار با هم گروه‌بندی می‌شوند، در حالی که مجموعه‌های رونوشت نشست به‌صورت یک گروه جدا باقی می‌مانند تا تنوع منبع همچنان هر دو ورودی را داشته باشد. -بازنویسی‌های مدل QMD در سمت QMD می‌مانند، نه در پیکربندی OpenClaw. اگر لازم است مدل‌های QMD را به‌صورت سراسری بازنویسی کنید، متغیرهای محیطی مانند `QMD_EMBED_MODEL`، `QMD_RERANK_MODEL` و `QMD_GENERATE_MODEL` را در محیط زمان اجرای Gateway تنظیم کنید. +بازنویسی‌های مدل QMD در سمت QMD می‌مانند، نه در پیکربندی OpenClaw. اگر لازم است مدل‌های QMD را به‌صورت سراسری بازنویسی کنید، متغیرهای محیطی مانند `QMD_EMBED_MODEL`، `QMD_RERANK_MODEL` و `QMD_GENERATE_MODEL` را در محیط اجرای gateway تنظیم کنید. - | کلید | نوع | پیش‌فرض | توضیح | + | کلید | نوع | پیش‌فرض | توضیح | | ------------------------- | --------- | ------- | ------------------------------------- | - | `update.interval` | `string` | `5m` | بازه تازه‌سازی | - | `update.debounceMs` | `number` | `15000` | Debounce برای تغییرات فایل | - | `update.onBoot` | `boolean` | `true` | هنگام باز شدن مدیر بلندمدت QMD تازه‌سازی می‌کند؛ همچنین تازه‌سازی اختیاری هنگام راه‌اندازی را کنترل می‌کند | - | `update.startup` | `string` | `off` | تازه‌سازی اختیاری هنگام شروع Gateway: `off`، `idle` یا `immediate` | - | `update.startupDelayMs` | `number` | `120000` | تاخیر پیش از اجرای تازه‌سازی `startup: "idle"` | - | `update.waitForBootSync` | `boolean` | `false` | باز شدن مدیر را تا تکمیل تازه‌سازی اولیه آن مسدود می‌کند | - | `update.embedInterval` | `string` | -- | آهنگ جداگانه embed | + | `update.interval` | `string` | `5m` | فاصله نوسازی | + | `update.debounceMs` | `number` | `15000` | تغییرات فایل را debounce کن | + | `update.onBoot` | `boolean` | `true` | هنگام باز شدن مدیر QMD بلندعمر نوسازی کن؛ نوسازی راه‌اندازی اختیاری را نیز کنترل می‌کند | + | `update.startup` | `string` | `off` | نوسازی اختیاری هنگام شروع gateway: `off`، `idle`، یا `immediate` | + | `update.startupDelayMs` | `number` | `120000` | تاخیر پیش از اجرای نوسازی `startup: "idle"` | + | `update.waitForBootSync` | `boolean` | `false` | باز شدن مدیر را تا کامل شدن نوسازی اولیه آن مسدود کن | + | `update.embedInterval` | `string` | -- | آهنگ جداگانه تعبیه | | `update.commandTimeoutMs` | `number` | -- | مهلت زمانی برای فرمان‌های QMD | | `update.updateTimeoutMs` | `number` | -- | مهلت زمانی برای عملیات به‌روزرسانی QMD | - | `update.embedTimeoutMs` | `number` | -- | مهلت زمانی برای عملیات embed در QMD | + | `update.embedTimeoutMs` | `number` | -- | مهلت زمانی برای عملیات تعبیه QMD | - | کلید | نوع | پیش‌فرض | توضیح | + | کلید | نوع | پیش‌فرض | توضیح | | ------------------------- | -------- | ------- | -------------------------- | - | `limits.maxResults` | `number` | `6` | بیشینه نتایج جست‌وجو | - | `limits.maxSnippetChars` | `number` | -- | محدود کردن طول قطعه متن | - | `limits.maxInjectedChars` | `number` | -- | محدود کردن مجموع نویسه‌های تزریق‌شده | - | `limits.timeoutMs` | `number` | `4000` | مهلت زمانی جست‌وجو | + | `limits.maxResults` | `number` | `6` | بیشینه نتایج جستجو | + | `limits.maxSnippetChars` | `number` | -- | طول قطعه را محدود کن | + | `limits.maxInjectedChars` | `number` | -- | مجموع نویسه‌های تزریق‌شده را محدود کن | + | `limits.timeoutMs` | `number` | `4000` | مهلت زمانی جستجو | - کنترل می‌کند کدام نشست‌ها می‌توانند نتایج جست‌وجوی QMD را دریافت کنند. همان schema مربوط به [`session.sendPolicy`](/fa/gateway/config-agents#session): + کنترل می‌کند کدام نشست‌ها می‌توانند نتایج جستجوی QMD را دریافت کنند. همان طرح‌واره [`session.sendPolicy`](/fa/gateway/config-agents#session): ```json5 { @@ -537,26 +537,26 @@ OpenClaw شکل‌های فعلی مجموعه QMD و پرس‌وجوی MCP را } ``` - پیش‌فرض ارسال‌شده نشست‌های مستقیم و کانالی را مجاز می‌کند، در حالی که گروه‌ها را همچنان رد می‌کند. + پیش‌فرض ارائه‌شده، نشست‌های مستقیم و کانالی را مجاز می‌کند، در حالی که همچنان گروه‌ها را رد می‌کند. پیش‌فرض فقط DM است. `match.keyPrefix` با کلید نشست نرمال‌سازی‌شده مطابقت می‌دهد؛ `match.rawKeyPrefix` با کلید خام شامل `agent::` مطابقت می‌دهد. - `memory.citations` برای همه backendها اعمال می‌شود: + `memory.citations` برای همه پشتانه‌ها اعمال می‌شود: - | مقدار | رفتار | + | مقدار | رفتار | | ---------------- | --------------------------------------------------- | - | `auto` (پیش‌فرض) | فوتر `Source: ` را در قطعه‌های متن وارد می‌کند | - | `on` | همیشه فوتر را وارد می‌کند | - | `off` | فوتر را حذف می‌کند (مسیر همچنان به‌صورت داخلی به عامل داده می‌شود) | + | `auto` (پیش‌فرض) | پابرگ `Source: ` را در قطعه‌ها درج کن | + | `on` | همیشه پابرگ را درج کن | + | `off` | پابرگ را حذف کن (مسیر همچنان در داخل به عامل داده می‌شود) | -تازه‌سازی‌های بوت QMD هنگام راه‌اندازی Gateway از مسیر زیرفرایند یک‌باره استفاده می‌کنند. مدیر بلندمدت QMD همچنان وقتی جست‌وجوی حافظه برای استفاده تعاملی باز می‌شود، مالک ناظر معمول فایل و تایمرهای بازه‌ای است. +نوسازی‌های راه‌اندازی QMD هنگام شروع gateway از یک مسیر زیرفرایند تک‌مرحله‌ای استفاده می‌کنند. مدیر QMD بلندعمر همچنان وقتی جستجوی حافظه برای استفاده تعاملی باز می‌شود، مالک ناظر معمول فایل و تایمرهای بازه‌ای است. -### مثال کامل QMD +### نمونه کامل QMD ```json5 { @@ -589,13 +589,13 @@ Dreaming به‌صورت یک پیمایش زمان‌بندی‌شده اجرا ### تنظیمات کاربر -| کلید | نوع | پیش‌فرض | توضیح | +| کلید | نوع | پیش‌فرض | توضیح | | ----------- | --------- | ------------- | ------------------------------------------------- | -| `enabled` | `boolean` | `false` | فعال یا غیرفعال کردن کامل dreaming | -| `frequency` | `string` | `0 3 * * *` | آهنگ Cron اختیاری برای پیمایش کامل dreaming | +| `enabled` | `boolean` | `false` | Dreaming را کاملا فعال یا غیرفعال کن | +| `frequency` | `string` | `0 3 * * *` | آهنگ Cron اختیاری برای پیمایش کامل Dreaming | | `model` | `string` | مدل پیش‌فرض | بازنویسی اختیاری مدل زیرعامل Dream Diary | -### مثال +### نمونه ```json5 { @@ -620,11 +620,11 @@ Dreaming به‌صورت یک پیمایش زمان‌بندی‌شده اجرا ``` -- Dreaming وضعیت ماشینی را در `memory/.dreams/` می‌نویسد. +- Dreaming وضعیت ماشین را در `memory/.dreams/` می‌نویسد. - Dreaming خروجی روایی خوانا برای انسان را در `DREAMS.md` (یا `dreams.md` موجود) می‌نویسد. -- `dreaming.model` از دروازه اعتماد موجود برای زیرعامل Plugin استفاده می‌کند؛ پیش از فعال کردن آن، `plugins.entries.memory-core.subagent.allowModelOverride: true` را تنظیم کنید. -- Dream Diary وقتی مدل پیکربندی‌شده در دسترس نباشد، یک بار با مدل پیش‌فرض نشست دوباره تلاش می‌کند. شکست‌های اعتماد یا allowlist ثبت می‌شوند و بی‌صدا دوباره تلاش نمی‌شوند. -- سیاست فاز سبک/عمیق/REM و آستانه‌ها رفتار داخلی هستند، نه پیکربندی کاربرمحور. +- `dreaming.model` از دروازه اعتماد زیرعامل Plugin موجود استفاده می‌کند؛ پیش از فعال کردن آن، `plugins.entries.memory-core.subagent.allowModelOverride: true` را تنظیم کنید. +- وقتی مدل پیکربندی‌شده در دسترس نباشد، Dream Diary یک‌بار با مدل پیش‌فرض نشست دوباره تلاش می‌کند. شکست‌های اعتماد یا allowlist ثبت می‌شوند و بی‌صدا دوباره تلاش نمی‌شوند. +- سیاست فاز سبک/عمیق/REM و آستانه‌ها رفتار داخلی هستند، نه پیکربندی روبه‌کاربر. @@ -632,4 +632,4 @@ Dreaming به‌صورت یک پیمایش زمان‌بندی‌شده اجرا - [مرجع پیکربندی](/fa/gateway/configuration-reference) - [نمای کلی حافظه](/fa/concepts/memory) -- [جست‌وجوی حافظه](/fa/concepts/memory-search) +- [جستجوی حافظه](/fa/concepts/memory-search) diff --git a/docs/fa/reference/session-management-compaction.md b/docs/fa/reference/session-management-compaction.md index efe373be4..8ecb08d1e 100644 --- a/docs/fa/reference/session-management-compaction.md +++ b/docs/fa/reference/session-management-compaction.md @@ -1,100 +1,100 @@ --- read_when: - - باید شناسه‌های نشست، JSONL رونوشت، یا فیلدهای sessions.json را اشکال‌زدایی کنید - - در حال تغییر رفتار Compaction خودکار یا افزودن خانه‌داری «پیش از Compaction» هستید + - لازم است شناسه‌های نشست، رونوشت JSONL، یا فیلدهای sessions.json را اشکال‌زدایی کنید + - شما در حال تغییر رفتار Compaction خودکار یا افزودن امور نگه‌داری “پیش از Compaction” هستید - می‌خواهید پاک‌سازی‌های حافظه یا نوبت‌های سیستمی بی‌صدا را پیاده‌سازی کنید -summary: 'بررسی عمیق: ذخیره‌ساز نشست + رونوشت‌ها، چرخهٔ حیات، و جزئیات داخلی Compaction خودکار' +summary: 'بررسی عمیق: ذخیره‌گاه نشست + رونوشت‌ها، چرخه حیات، و جزئیات داخلی Compaction خودکار' title: بررسی عمیق مدیریت نشست x-i18n: - generated_at: "2026-04-29T23:33:19Z" + generated_at: "2026-04-30T16:31:05Z" model: gpt-5.5 provider: openai - source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700 + source_hash: 5a6a7031cebd90d27784a32a0d0378ea9959249389d209f0745395f90b8a0df9 source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw نشست‌ها را از ابتدا تا انتها در این حوزه‌ها مدیریت می‌کند: +OpenClaw جلسه‌ها را از ابتدا تا انتها در این حوزه‌ها مدیریت می‌کند: -- **مسیریابی نشست** (اینکه پیام‌های ورودی چگونه به یک `sessionKey` نگاشت می‌شوند) -- **ذخیره‌گاه نشست** (`sessions.json`) و چیزهایی که ردیابی می‌کند -- **ماندگارسازی رونوشت** (`*.jsonl`) و ساختار آن -- **بهداشت رونوشت** (اصلاحات ویژه‌ی ارائه‌دهنده پیش از اجراها) -- **محدودیت‌های زمینه** (پنجره‌ی زمینه در برابر توکن‌های ردیابی‌شده) +- **مسیریابی جلسه** (اینکه پیام‌های ورودی چگونه به یک `sessionKey` نگاشت می‌شوند) +- **ذخیره‌ساز جلسه** (`sessions.json`) و آنچه ردیابی می‌کند +- **پایداری رونوشت** (`*.jsonl`) و ساختار آن +- **بهداشت رونوشت** (اصلاحات ویژه ارائه‌دهنده پیش از اجراها) +- **محدودیت‌های زمینه** (پنجره زمینه در برابر توکن‌های ردیابی‌شده) - **Compaction** (Compaction دستی و خودکار) و محل اتصال کارهای پیش از Compaction -- **خانه‌داری خاموش** (نوشتن‌های حافظه که نباید خروجی قابل مشاهده برای کاربر تولید کنند) +- **خانه‌داری بی‌صدا** (نوشتن‌های حافظه که نباید خروجی قابل مشاهده برای کاربر تولید کنند) اگر ابتدا نمایی کلی‌تر می‌خواهید، از اینجا شروع کنید: -- [مدیریت نشست](/fa/concepts/session) +- [مدیریت جلسه](/fa/concepts/session) - [Compaction](/fa/concepts/compaction) - [نمای کلی حافظه](/fa/concepts/memory) - [جست‌وجوی حافظه](/fa/concepts/memory-search) -- [هرس نشست](/fa/concepts/session-pruning) +- [هرس جلسه](/fa/concepts/session-pruning) - [بهداشت رونوشت](/fa/reference/transcript-hygiene) --- ## منبع حقیقت: Gateway -OpenClaw حول یک **فرایند Gateway** واحد طراحی شده است که مالک وضعیت نشست است. +OpenClaw بر پایه یک **فرایند Gateway** واحد طراحی شده است که مالک وضعیت جلسه است. -- رابط‌های کاربری (برنامه‌ی macOS، رابط کاربری Control وب، TUI) باید فهرست نشست‌ها و شمارش توکن‌ها را از Gateway پرس‌وجو کنند. -- در حالت راه‌دور، فایل‌های نشست روی میزبان راه‌دور هستند؛ «بررسی فایل‌های Mac محلی شما» آنچه Gateway استفاده می‌کند را بازتاب نمی‌دهد. +- رابط‌های کاربری (برنامه macOS، رابط کنترل وب، TUI) باید فهرست جلسه‌ها و شمارش توکن‌ها را از Gateway پرس‌وجو کنند. +- در حالت ریموت، فایل‌های جلسه روی میزبان ریموت هستند؛ «بررسی فایل‌های محلی Mac خودتان» آنچه Gateway استفاده می‌کند را نشان نمی‌دهد. --- -## دو لایه‌ی ماندگاری +## دو لایه پایداری -OpenClaw نشست‌ها را در دو لایه ماندگار می‌کند: +OpenClaw جلسه‌ها را در دو لایه پایدار می‌کند: -1. **ذخیره‌گاه نشست (`sessions.json`)** +1. **ذخیره‌ساز جلسه (`sessions.json`)** - نگاشت کلید/مقدار: `sessionKey -> SessionEntry` - - کوچک، تغییرپذیر، و امن برای ویرایش (یا حذف ورودی‌ها) - - فراداده‌ی نشست را ردیابی می‌کند (شناسه‌ی نشست فعلی، آخرین فعالیت، تغییر‌دهنده‌ها، شمارنده‌های توکن و غیره) + - کوچک، قابل تغییر، و برای ویرایش (یا حذف ورودی‌ها) امن + - فراداده جلسه را ردیابی می‌کند (شناسه جلسه فعلی، آخرین فعالیت، سوییچ‌ها، شمارنده‌های توکن، و غیره) 2. **رونوشت (`.jsonl`)** - - رونوشت فقط-افزودنی با ساختار درختی (ورودی‌ها `id` + `parentId` دارند) + - رونوشت فقط-الحاقی با ساختار درختی (ورودی‌ها `id` + `parentId` دارند) - گفت‌وگوی واقعی + فراخوانی‌های ابزار + خلاصه‌های Compaction را ذخیره می‌کند - - برای بازسازی زمینه‌ی مدل در نوبت‌های آینده استفاده می‌شود - - وقتی رونوشت فعال از سقف اندازه‌ی checkpoint بیشتر شود، checkpointهای اشکال‌زدایی بزرگ پیش از Compaction نادیده گرفته می‌شوند تا یک نسخه‌ی عظیم دوم از نوع `.checkpoint.*.jsonl` ایجاد نشود. + - برای بازسازی زمینه مدل در نوبت‌های آینده استفاده می‌شود + - نقاط وارسی بزرگ عیب‌یابی پیش از Compaction، پس از اینکه رونوشت فعال از سقف اندازه نقطه وارسی بیشتر شود، نادیده گرفته می‌شوند و از ایجاد یک کپی غول‌آسای دوم با نام `.checkpoint.*.jsonl` جلوگیری می‌کنند. --- -## مکان‌ها روی دیسک +## مکان‌های روی دیسک -برای هر agent، روی میزبان Gateway: +برای هر عامل، روی میزبان Gateway: -- ذخیره‌گاه: `~/.openclaw/agents//sessions/sessions.json` +- ذخیره‌ساز: `~/.openclaw/agents//sessions/sessions.json` - رونوشت‌ها: `~/.openclaw/agents//sessions/.jsonl` - - نشست‌های موضوع Telegram: `.../-topic-.jsonl` + - جلسه‌های موضوعی Telegram: `.../-topic-.jsonl` OpenClaw این‌ها را از طریق `src/config/sessions.ts` حل می‌کند. --- -## نگهداری ذخیره‌گاه و کنترل‌های دیسک +## نگهداری ذخیره‌ساز و کنترل‌های دیسک -ماندگاری نشست برای `sessions.json`، artifactهای رونوشت، و sidecarهای مسیر، کنترل‌های نگهداری خودکار (`session.maintenance`) دارد: +پایداری جلسه کنترل‌های نگهداری خودکار (`session.maintenance`) برای `sessions.json`، آثار رونوشت، و فایل‌های جانبی مسیر اجرا دارد: - `mode`: `warn` (پیش‌فرض) یا `enforce` -- `pruneAfter`: آستانه‌ی سن ورودی‌های کهنه (پیش‌فرض `30d`) +- `pruneAfter`: حد سن ورودی‌های کهنه (پیش‌فرض `30d`) - `maxEntries`: سقف ورودی‌ها در `sessions.json` (پیش‌فرض `500`) -- `resetArchiveRetention`: نگهداشت archiveهای رونوشت `*.reset.` (پیش‌فرض: همان `pruneAfter`؛ مقدار `false` پاک‌سازی را غیرفعال می‌کند) -- `maxDiskBytes`: بودجه‌ی اختیاری برای پوشه‌ی نشست‌ها -- `highWaterBytes`: هدف اختیاری پس از پاک‌سازی (پیش‌فرض `80%` از `maxDiskBytes`) +- `resetArchiveRetention`: نگهداری برای آرشیوهای رونوشت `*.reset.` (پیش‌فرض: همان `pruneAfter`؛ `false` پاکسازی را غیرفعال می‌کند) +- `maxDiskBytes`: بودجه اختیاری دایرکتوری جلسه‌ها +- `highWaterBytes`: هدف اختیاری پس از پاکسازی (پیش‌فرض `80%` از `maxDiskBytes`) -نوشتن‌های عادی Gateway پاک‌سازی `maxEntries` را برای سقف‌های هم‌اندازه‌ی production به‌صورت دسته‌ای انجام می‌دهند، بنابراین ممکن است یک ذخیره‌گاه برای مدت کوتاهی از سقف پیکربندی‌شده فراتر برود تا پاک‌سازی high-water بعدی آن را دوباره به زیر سقف بازنویسی کند. `openclaw sessions cleanup --enforce` همچنان سقف پیکربندی‌شده را بی‌درنگ اعمال می‌کند. +نوشتن‌های عادی Gateway پاکسازی `maxEntries` را برای سقف‌های در اندازه تولید به‌صورت دسته‌ای انجام می‌دهند، بنابراین یک ذخیره‌ساز ممکن است برای مدت کوتاهی از سقف پیکربندی‌شده بیشتر شود تا پاکسازی بعدی در سطح آب بالا آن را دوباره کاهش دهد. `openclaw sessions cleanup --enforce` همچنان سقف پیکربندی‌شده را فوراً اعمال می‌کند. -OpenClaw دیگر هنگام نوشتن‌های Gateway پشتیبان‌های چرخشی خودکار `sessions.json.bak.*` ایجاد نمی‌کند. کلید قدیمی `session.maintenance.rotateBytes` نادیده گرفته می‌شود و `openclaw doctor --fix` آن را از پیکربندی‌های قدیمی‌تر حذف می‌کند. +OpenClaw دیگر هنگام نوشتن‌های Gateway پشتیبان‌های چرخشی خودکار `sessions.json.bak.*` ایجاد نمی‌کند. کلید قدیمی `session.maintenance.rotateBytes` نادیده گرفته می‌شود و `openclaw doctor --fix` آن را از پیکربندی‌های قدیمی حذف می‌کند. -ترتیب اعمال پاک‌سازی بودجه‌ی دیسک (`mode: "enforce"`): +ترتیب اعمال برای پاکسازی بودجه دیسک (`mode: "enforce"`): -1. ابتدا قدیمی‌ترین artifactهای archiveشده، رونوشت یتیم، یا مسیر یتیم را حذف کنید. -2. اگر هنوز بالاتر از هدف است، قدیمی‌ترین ورودی‌های نشست و فایل‌های رونوشت/مسیر آن‌ها را بیرون بیندازید. +1. ابتدا قدیمی‌ترین آثار آرشیوشده، رونوشت‌های یتیم، یا آثار مسیر اجرای یتیم را حذف کنید. +2. اگر همچنان بالاتر از هدف بود، قدیمی‌ترین ورودی‌های جلسه و فایل‌های رونوشت/مسیر اجرای آن‌ها را بیرون بیندازید. 3. ادامه دهید تا مصرف برابر یا کمتر از `highWaterBytes` شود. -در `mode: "warn"`، OpenClaw بیرون‌اندازی‌های احتمالی را گزارش می‌کند اما ذخیره‌گاه/فایل‌ها را تغییر نمی‌دهد. +در `mode: "warn"`، OpenClaw حذف‌های احتمالی را گزارش می‌کند اما ذخیره‌ساز/فایل‌ها را تغییر نمی‌دهد. نگهداری را در صورت نیاز اجرا کنید: @@ -105,109 +105,109 @@ openclaw sessions cleanup --enforce --- -## نشست‌های Cron و گزارش‌های اجرا +## جلسه‌های Cron و گزارش‌های اجرا -اجراهای جداافتاده‌ی Cron نیز ورودی‌های نشست/رونوشت ایجاد می‌کنند و کنترل‌های نگهداشت اختصاصی دارند: +اجراهای جداافتاده Cron نیز ورودی‌ها/رونوشت‌های جلسه ایجاد می‌کنند و کنترل‌های نگهداری اختصاصی دارند: -- `cron.sessionRetention` (پیش‌فرض `24h`) نشست‌های قدیمی اجرای جداافتاده‌ی Cron را از ذخیره‌گاه نشست هرس می‌کند (`false` غیرفعال می‌کند). +- `cron.sessionRetention` (پیش‌فرض `24h`) جلسه‌های قدیمی اجرای جداافتاده Cron را از ذخیره‌ساز جلسه هرس می‌کند (`false` غیرفعال می‌کند). - `cron.runLog.maxBytes` + `cron.runLog.keepLines` فایل‌های `~/.openclaw/cron/runs/.jsonl` را هرس می‌کنند (پیش‌فرض‌ها: `2_000_000` بایت و `2000` خط). -وقتی Cron با اجبار یک نشست اجرای جداافتاده‌ی جدید ایجاد می‌کند، پیش از نوشتن ردیف جدید، ورودی نشست قبلی `cron:` را پاک‌سازی می‌کند. ترجیح‌های امنی مثل تنظیمات thinking/fast/verbose، برچسب‌ها، و بازنویسی‌های صریح مدل/احراز هویت انتخاب‌شده توسط کاربر را حمل می‌کند. زمینه‌ی گفت‌وگوی محیطی مانند مسیریابی کانال/گروه، سیاست ارسال یا صف، ارتقا، مبدأ، و اتصال زمان اجرای ACP را حذف می‌کند تا یک اجرای جداافتاده‌ی تازه نتواند تحویل کهنه یا اختیار زمان اجرا را از اجرای قدیمی‌تر به ارث ببرد. +وقتی Cron یک جلسه اجرای جداافتاده جدید را به‌اجبار ایجاد می‌کند، پیش از نوشتن ردیف جدید، ورودی جلسه قبلی `cron:` را پاکسازی می‌کند. این کار ترجیح‌های امنی مانند تنظیمات فکرکردن/سریع/پرگویی، برچسب‌ها، و بازنویسی‌های صریح مدل/احراز هویت انتخاب‌شده توسط کاربر را منتقل می‌کند. زمینه گفت‌وگوی محیطی مانند مسیریابی کانال/گروه، سیاست ارسال یا صف، ارتقا، مبدأ، و اتصال زمان اجرای ACP را حذف می‌کند تا یک اجرای جداافتاده تازه نتواند تحویل کهنه یا اختیار زمان اجرا را از اجرای قدیمی‌تر به ارث ببرد. --- -## کلیدهای نشست (`sessionKey`) +## کلیدهای جلسه (`sessionKey`) یک `sessionKey` مشخص می‌کند در _کدام سطل گفت‌وگو_ هستید (مسیریابی + جداسازی). الگوهای رایج: -- گفت‌وگوی اصلی/مستقیم (برای هر agent): `agent::` (پیش‌فرض `main`) +- گفت‌وگوی اصلی/مستقیم (برای هر عامل): `agent::` (پیش‌فرض `main`) - گروه: `agent:::group:` - اتاق/کانال (Discord/Slack): `agent:::channel:` یا `...:room:` - Cron: `cron:` - Webhook: `hook:` (مگر اینکه بازنویسی شده باشد) -قواعد canonical در [/concepts/session](/fa/concepts/session) مستند شده‌اند. +قواعد رسمی در [/concepts/session](/fa/concepts/session) مستند شده‌اند. --- -## شناسه‌های نشست (`sessionId`) +## شناسه‌های جلسه (`sessionId`) هر `sessionKey` به یک `sessionId` فعلی اشاره می‌کند (فایل رونوشت که گفت‌وگو را ادامه می‌دهد). -قواعد کلی: +قواعد سرانگشتی: -- **Reset** (`/new`، `/reset`) برای آن `sessionKey` یک `sessionId` جدید ایجاد می‌کند. -- **بازنشانی روزانه** (پیش‌فرض 4:00 صبح به‌وقت محلی روی میزبان Gateway) در پیام بعدی پس از مرز بازنشانی یک `sessionId` جدید ایجاد می‌کند. -- **انقضای بیکاری** (`session.reset.idleMinutes` یا `session.idleMinutes` قدیمی) وقتی پیامی پس از پنجره‌ی بیکاری برسد، یک `sessionId` جدید ایجاد می‌کند. وقتی روزانه + بیکاری هر دو پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است. -- **رویدادهای سیستمی** (Heartbeat، بیدارباش‌های Cron، اعلان‌های exec، bookkeeping Gateway) ممکن است ردیف نشست را تغییر دهند اما تازگی بازنشانی روزانه/بیکاری را تمدید نمی‌کنند. rollover بازنشانی، اعلان‌های صف‌شده‌ی رویداد سیستمی برای نشست قبلی را پیش از ساخته‌شدن prompt تازه دور می‌اندازد. -- **محافظ fork والد thread** (`session.parentForkMaxTokens`، پیش‌فرض `100000`) وقتی نشست والد از قبل بیش از حد بزرگ باشد، fork کردن رونوشت والد را نادیده می‌گیرد؛ thread جدید تازه شروع می‌شود. برای غیرفعال‌کردن، `0` تنظیم کنید. +- **بازنشانی** (`/new`، `/reset`) برای آن `sessionKey` یک `sessionId` جدید ایجاد می‌کند. +- **بازنشانی روزانه** (پیش‌فرض ساعت 4:00 صبح به وقت محلی روی میزبان Gateway) در پیام بعدی پس از مرز بازنشانی، یک `sessionId` جدید ایجاد می‌کند. +- **انقضای بیکاری** (`session.reset.idleMinutes` یا `session.idleMinutes` قدیمی) وقتی پیامی پس از پنجره بیکاری برسد، یک `sessionId` جدید ایجاد می‌کند. وقتی روزانه + بیکاری هر دو پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است. +- **رویدادهای سیستمی** (Heartbeat، بیدارباش‌های Cron، اعلان‌های exec، حسابداری Gateway) ممکن است ردیف جلسه را تغییر دهند اما تازگی بازنشانی روزانه/بیکاری را تمدید نمی‌کنند. چرخش بازنشانی پیش از ساخته شدن درخواست تازه، اعلان‌های رویداد سیستمی صف‌شده برای جلسه قبلی را دور می‌اندازد. +- **نگهبان انشعاب والد نخ** (`session.parentForkMaxTokens`، پیش‌فرض `100000`) وقتی جلسه والد از قبل بیش از حد بزرگ باشد، انشعاب رونوشت والد را رد می‌کند؛ نخ جدید تازه شروع می‌شود. برای غیرفعال کردن، `0` تنظیم کنید. جزئیات پیاده‌سازی: تصمیم در `initSessionState()` در `src/auto-reply/reply/session.ts` رخ می‌دهد. --- -## schema ذخیره‌گاه نشست (`sessions.json`) +## طرح‌واره ذخیره‌ساز جلسه (`sessions.json`) -نوع مقدار ذخیره‌گاه `SessionEntry` در `src/config/sessions.ts` است. +نوع مقدار ذخیره‌ساز `SessionEntry` در `src/config/sessions.ts` است. فیلدهای کلیدی (غیرجامع): -- `sessionId`: شناسه‌ی رونوشت فعلی (نام فایل از این مشتق می‌شود مگر اینکه `sessionFile` تنظیم شده باشد) -- `sessionStartedAt`: timestamp شروع برای `sessionId` فعلی؛ تازگی بازنشانی روزانه از این استفاده می‌کند. ردیف‌های قدیمی ممکن است آن را از header نشست JSONL مشتق کنند. -- `lastInteractionAt`: timestamp آخرین تعامل واقعی کاربر/کانال؛ تازگی بازنشانی بیکاری از این استفاده می‌کند تا Heartbeat، Cron، و رویدادهای exec نشست‌ها را زنده نگه ندارند. ردیف‌های قدیمی بدون این فیلد برای تازگی بیکاری به زمان شروع نشست بازیابی‌شده fallback می‌کنند. -- `updatedAt`: timestamp آخرین تغییر ردیف ذخیره‌گاه، که برای فهرست‌سازی، هرس، و bookkeeping استفاده می‌شود. این مرجع معتبر برای تازگی بازنشانی روزانه/بیکاری نیست. -- `sessionFile`: بازنویسی اختیاری مسیر رونوشت به‌صورت صریح +- `sessionId`: شناسه رونوشت فعلی (نام فایل از این مشتق می‌شود مگر اینکه `sessionFile` تنظیم شده باشد) +- `sessionStartedAt`: مُهر زمانی شروع برای `sessionId` فعلی؛ تازگی بازنشانی روزانه از این استفاده می‌کند. ردیف‌های قدیمی ممکن است آن را از سرآیند جلسه JSONL مشتق کنند. +- `lastInteractionAt`: مُهر زمانی آخرین تعامل واقعی کاربر/کانال؛ تازگی بازنشانی بیکاری از این استفاده می‌کند تا Heartbeat، Cron، و رویدادهای exec جلسه‌ها را زنده نگه ندارند. ردیف‌های قدیمی بدون این فیلد برای تازگی بیکاری به زمان شروع جلسه بازیابی‌شده برمی‌گردند. +- `updatedAt`: مُهر زمانی آخرین تغییر ردیف ذخیره‌ساز، که برای فهرست‌کردن، هرس، و حسابداری استفاده می‌شود. این مرجع تازگی بازنشانی روزانه/بیکاری نیست. +- `sessionFile`: بازنویسی اختیاری مسیر صریح رونوشت - `chatType`: `direct | group | room` (به رابط‌های کاربری و سیاست ارسال کمک می‌کند) - `provider`، `subject`، `room`، `space`، `displayName`: فراداده برای برچسب‌گذاری گروه/کانال -- تغییر‌دهنده‌ها: +- سوییچ‌ها: - `thinkingLevel`، `verboseLevel`، `reasoningLevel`، `elevatedLevel` - - `sendPolicy` (بازنویسی برای هر نشست) + - `sendPolicy` (بازنویسی برای هر جلسه) - انتخاب مدل: - `providerOverride`، `modelOverride`، `authProfileOverride` -- شمارنده‌های توکن (best-effort / وابسته به ارائه‌دهنده): +- شمارنده‌های توکن (بهترین تلاش / وابسته به ارائه‌دهنده): - `inputTokens`، `outputTokens`، `totalTokens`، `contextTokens` -- `compactionCount`: اینکه auto-compaction چند بار برای این کلید نشست کامل شده است -- `memoryFlushAt`: timestamp آخرین تخلیه‌ی حافظه پیش از Compaction -- `memoryFlushCompactionCount`: شمارش Compaction هنگام اجرای آخرین تخلیه +- `compactionCount`: تعداد دفعاتی که Compaction خودکار برای این کلید جلسه کامل شده است +- `memoryFlushAt`: مُهر زمانی آخرین تخلیه حافظه پیش از Compaction +- `memoryFlushCompactionCount`: شمار Compaction هنگام اجرای آخرین تخلیه -ویرایش ذخیره‌گاه امن است، اما Gateway مرجع معتبر است: ممکن است هنگام اجرای نشست‌ها ورودی‌ها را بازنویسی یا دوباره hydrate کند. +ویرایش ذخیره‌ساز امن است، اما Gateway مرجع است: ممکن است هنگام اجرای جلسه‌ها ورودی‌ها را بازنویسی یا دوباره آب‌دهی کند. --- ## ساختار رونوشت (`*.jsonl`) -رونوشت‌ها توسط `SessionManager` مربوط به `@mariozechner/pi-coding-agent` مدیریت می‌شوند. +رونوشت‌ها توسط `SessionManager` متعلق به `@mariozechner/pi-coding-agent` مدیریت می‌شوند. فایل JSONL است: -- خط اول: header نشست (`type: "session"`، شامل `id`، `cwd`، `timestamp`، `parentSession` اختیاری) -- سپس: ورودی‌های نشست با `id` + `parentId` (درخت) +- خط نخست: سرآیند جلسه (`type: "session"`، شامل `id`، `cwd`، `timestamp`، `parentSession` اختیاری) +- سپس: ورودی‌های جلسه با `id` + `parentId` (درخت) انواع ورودی قابل توجه: -- `message`: پیام‌های کاربر/دستیار/toolResult -- `custom_message`: پیام‌های تزریق‌شده توسط extension که _وارد_ زمینه‌ی مدل می‌شوند (می‌توانند از رابط کاربری پنهان باشند) -- `custom`: وضعیت extension که وارد زمینه‌ی مدل _نمی‌شود_ -- `compaction`: خلاصه‌ی Compaction ماندگارشده با `firstKeptEntryId` و `tokensBefore` -- `branch_summary`: خلاصه‌ی ماندگارشده هنگام پیمایش یک شاخه‌ی درخت +- `message`: پیام‌های کاربر/دستیار/نتیجه ابزار +- `custom_message`: پیام‌های تزریق‌شده توسط افزونه که _وارد_ زمینه مدل می‌شوند (می‌توانند از رابط کاربری پنهان باشند) +- `custom`: وضعیت افزونه که وارد زمینه مدل _نمی‌شود_ +- `compaction`: خلاصه Compaction پایدارشده با `firstKeptEntryId` و `tokensBefore` +- `branch_summary`: خلاصه پایدارشده هنگام پیمایش یک شاخه درخت -OpenClaw عمدا رونوشت‌ها را «اصلاح» نمی‌کند؛ Gateway برای خواندن/نوشتن آن‌ها از `SessionManager` استفاده می‌کند. +OpenClaw عمداً رونوشت‌ها را «اصلاح» نمی‌کند؛ Gateway برای خواندن/نوشتن آن‌ها از `SessionManager` استفاده می‌کند. --- ## پنجره‌های زمینه در برابر توکن‌های ردیابی‌شده -دو مفهوم متفاوت مهم‌اند: +دو مفهوم متفاوت اهمیت دارند: -1. **پنجره‌ی زمینه‌ی مدل**: سقف سخت برای هر مدل (توکن‌هایی که برای مدل قابل مشاهده‌اند) -2. **شمارنده‌های ذخیره‌گاه نشست**: آمارهای چرخشی نوشته‌شده در `sessions.json` (برای /status و داشبوردها استفاده می‌شوند) +1. **پنجره زمینه مدل**: سقف سخت برای هر مدل (توکن‌های قابل مشاهده برای مدل) +2. **شمارنده‌های ذخیره‌ساز جلسه**: آمارهای چرخشی نوشته‌شده در `sessions.json` (برای /status و داشبوردها استفاده می‌شوند) اگر محدودیت‌ها را تنظیم می‌کنید: -- پنجره‌ی زمینه از catalog مدل می‌آید (و می‌تواند از طریق config بازنویسی شود). -- `contextTokens` در ذخیره‌گاه یک مقدار برآورد/گزارشی زمان اجرا است؛ آن را تضمین سخت‌گیرانه تلقی نکنید. +- پنجره زمینه از فهرست مدل می‌آید (و می‌تواند از طریق پیکربندی بازنویسی شود). +- `contextTokens` در ذخیره‌ساز یک مقدار تخمینی/گزارشی زمان اجرا است؛ با آن مثل تضمین سخت‌گیرانه رفتار نکنید. برای اطلاعات بیشتر، [/token-use](/fa/reference/token-use) را ببینید. @@ -215,52 +215,66 @@ OpenClaw عمدا رونوشت‌ها را «اصلاح» نمی‌کند؛ Gate ## Compaction: چیست -Compaction گفت‌وگوی قدیمی‌تر را در یک ورودی `compaction` ماندگارشده در رونوشت خلاصه می‌کند و پیام‌های اخیر را دست‌نخورده نگه می‌دارد. +Compaction گفت‌وگوی قدیمی‌تر را در یک ورودی `compaction` پایدارشده در رونوشت خلاصه می‌کند و پیام‌های اخیر را دست‌نخورده نگه می‌دارد. پس از Compaction، نوبت‌های آینده این‌ها را می‌بینند: -- خلاصه‌ی Compaction +- خلاصه Compaction - پیام‌های پس از `firstKeptEntryId` -Compaction **ماندگار** است (برخلاف هرس نشست). [/concepts/session-pruning](/fa/concepts/session-pruning) را ببینید. +Compaction **پایدار** است (برخلاف هرس جلسه). [/concepts/session-pruning](/fa/concepts/session-pruning) را ببینید. -## مرزهای chunk در Compaction و جفت‌سازی ابزار +## مرزهای قطعه Compaction و جفت‌سازی ابزار -وقتی OpenClaw یک رونوشت طولانی را به chunkهای Compaction تقسیم می‌کند، فراخوانی‌های ابزار دستیار را با ورودی‌های `toolResult` متناظرشان جفت نگه می‌دارد. +وقتی OpenClaw یک رونوشت بلند را به قطعه‌های Compaction تقسیم می‌کند، فراخوانی‌های ابزار دستیار را با ورودی‌های `toolResult` متناظرشان جفت نگه می‌دارد. -- اگر تقسیم بر اساس سهم توکن بین فراخوانی ابزار و نتیجه‌ی آن بیفتد، OpenClaw به‌جای جداکردن این جفت، مرز را به پیام فراخوانی ابزار دستیار منتقل می‌کند. -- اگر یک بلوک پایانی نتیجه‌ی ابزار در غیر این صورت chunk را از هدف فراتر ببرد، OpenClaw آن بلوک ابزار معلق را حفظ می‌کند و دنباله‌ی خلاصه‌نشده را دست‌نخورده نگه می‌دارد. -- بلوک‌های فراخوانی ابزار لغوشده/خطادار split معلق را باز نگه نمی‌دارند. +- اگر تقسیم بر پایه سهم توکن بین یک فراخوانی ابزار و نتیجه آن بیفتد، OpenClaw مرز را به پیام فراخوانی ابزار دستیار منتقل می‌کند به‌جای اینکه جفت را جدا کند. +- اگر یک بلوک انتهایی نتیجه ابزار در غیر این صورت قطعه را از هدف بزرگ‌تر کند، OpenClaw آن بلوک ابزار در انتظار را حفظ می‌کند و دنباله خلاصه‌نشده را دست‌نخورده نگه می‌دارد. +- بلوک‌های فراخوانی ابزار لغوشده/خطادار یک تقسیم در انتظار را باز نگه نمی‌دارند. --- -## زمان رخ‌دادن auto-compaction (زمان اجرای Pi) +## زمان رخ‌دادن Compaction خودکار (زمان اجرای Pi) -در agent تعبیه‌شده‌ی Pi، auto-compaction در دو حالت فعال می‌شود: +در عامل Pi تعبیه‌شده، Compaction خودکار در دو حالت فعال می‌شود: -1. **بازیابی از سرریز**: مدل یک خطای سرریز زمینه برمی‌گرداند +1. **بازیابی سرریز**: مدل یک خطای سرریز زمینه برمی‌گرداند (`request_too_large`، `context length exceeded`، `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`، و گونه‌های مشابه با شکل ارائه‌دهنده) → compact → تلاش دوباره. -2. **نگهداری آستانه‌ای**: پس از یک نوبت موفق، وقتی: +exceeded`، و گونه‌های مشابه با شکل ارائه‌دهنده) → فشرده‌سازی → تلاش دوباره. +2. **نگهداری آستانه**: پس از یک نوبت موفق، وقتی: `contextTokens > contextWindow - reserveTokens` که در آن: -- `contextWindow` پنجره‌ی زمینه‌ی مدل است -- `reserveTokens` فضای اضافه‌ای است که برای promptها + خروجی بعدی مدل رزرو می‌شود +- `contextWindow` پنجره زمینه مدل است +- `reserveTokens` فضای اضافه رزروشده برای درخواست‌ها + خروجی بعدی مدل است -این‌ها معناشناسی زمان اجرای Pi هستند (OpenClaw رویدادها را مصرف می‌کند، اما Pi تصمیم می‌گیرد چه زمانی compact کند). +این‌ها معناشناسی زمان اجرای Pi هستند (OpenClaw رویدادها را مصرف می‌کند، اما Pi تصمیم می‌گیرد چه زمانی Compaction کند). -OpenClaw همچنین می‌تواند پیش از بازکردن اجرای بعدی، وقتی `agents.defaults.compaction.maxActiveTranscriptBytes` تنظیم شده باشد و فایل رونوشت فعال به آن اندازه برسد، یک Compaction محلی preflight را فعال کند. این یک محافظ اندازه‌ی فایل برای هزینه‌ی reopen محلی است، نه archive خام: OpenClaw همچنان Compaction معنایی عادی را اجرا می‌کند، و به `truncateAfterCompaction` نیاز دارد تا خلاصه‌ی compactشده بتواند به یک رونوشت successor جدید تبدیل شود. +OpenClaw همچنین می‌تواند پیش از باز کردن اجرای بعدی، وقتی `agents.defaults.compaction.maxActiveTranscriptBytes` تنظیم شده باشد و فایل رونوشت فعال به آن اندازه برسد، یک Compaction محلی پیش‌پرواز را فعال کند. این یک نگهبان اندازه فایل برای هزینه بازگشایی محلی است، نه آرشیوسازی خام: OpenClaw همچنان Compaction معنایی عادی را اجرا می‌کند، و به `truncateAfterCompaction` نیاز دارد تا خلاصه فشرده‌شده بتواند به یک رونوشت جانشین جدید تبدیل شود. + +برای اجرای تعبیه‌شده‌ی Pi، گزینه‌ی `agents.defaults.compaction.midTurnPrecheck.enabled: true` +یک نگهبان اختیاری برای حلقه‌ی ابزار اضافه می‌کند. پس از اینکه نتیجه‌ی ابزار افزوده شد و پیش از +فراخوانی مدل بعدی، OpenClaw فشار پرامپت را با همان منطق بودجه‌ی preflight +که در شروع turn استفاده می‌شود تخمین می‌زند. اگر context دیگر جا نشود، این نگهبان +داخل hook‏ `transformContext` مربوط به Pi فشرده‌سازی انجام نمی‌دهد. در عوض یک سیگنال ساختاریافته‌ی +precheck میان-turn ایجاد می‌کند، ارسال پرامپت فعلی را متوقف می‌کند و اجازه می‌دهد +حلقه‌ی اجرای بیرونی از مسیر بازیابی موجود استفاده کند: وقتی کافی باشد نتایج بیش‌ازحد بزرگ ابزار را کوتاه کند، +یا حالت پیکربندی‌شده‌ی Compaction را اجرا کرده و دوباره تلاش کند. این گزینه به‌صورت پیش‌فرض غیرفعال است +و با هر دو حالت Compaction یعنی `default` و `safeguard` کار می‌کند، از جمله +Compaction حفاظتیِ متکی به provider. +این مستقل از `maxActiveTranscriptBytes` است: نگهبان اندازه‌ی بایتی +پیش از باز شدن یک turn اجرا می‌شود، در حالی که precheck میان-turn بعدتر در حلقه‌ی ابزار +تعبیه‌شده‌ی Pi و پس از افزوده شدن نتایج ابزار جدید اجرا می‌شود. --- -## تنظیمات Compaction (`reserveTokens`، `keepRecentTokens`) +## تنظیمات Compaction (`reserveTokens`, `keepRecentTokens`) -تنظیمات Compaction در Pi در تنظیمات Pi قرار دارند: +تنظیمات Compaction مربوط به Pi در تنظیمات Pi قرار دارند: ```json5 { @@ -272,133 +286,137 @@ OpenClaw همچنین می‌تواند پیش از بازکردن اجرای ب } ``` -OpenClaw همچنین یک کف ایمنی برای اجراهای جاسازی‌شده اعمال می‌کند: +OpenClaw همچنین برای اجراهای تعبیه‌شده یک کف ایمنی اعمال می‌کند: - اگر `compaction.reserveTokens < reserveTokensFloor` باشد، OpenClaw آن را افزایش می‌دهد. -- کف پیش‌فرض `20000` توکن است. +- کف پیش‌فرض `20000` token است. - برای غیرفعال کردن کف، `agents.defaults.compaction.reserveTokensFloor: 0` را تنظیم کنید. - اگر از قبل بالاتر باشد، OpenClaw آن را دست‌نخورده می‌گذارد. - دستور دستی `/compact` مقدار صریح `agents.defaults.compaction.keepRecentTokens` - را رعایت می‌کند و نقطه برش دنباله اخیر Pi را نگه می‌دارد. بدون بودجه نگهداری صریح، - Compaction دستی همچنان یک نقطه وارسی سخت می‌ماند و زمینه بازسازی‌شده از - خلاصه جدید شروع می‌شود. -- `agents.defaults.compaction.maxActiveTranscriptBytes` را روی یک مقدار بایتی یا - رشته‌ای مانند `"20mb"` تنظیم کنید تا وقتی رونوشت فعال بزرگ می‌شود، پیش از یک نوبت - Compaction محلی اجرا شود. این محافظ فقط زمانی فعال است که - `truncateAfterCompaction` نیز فعال باشد. برای غیرفعال کردن، آن را تنظیم‌نشده بگذارید یا روی `0` تنظیم کنید. + را رعایت می‌کند و نقطه‌ی برش دنباله‌ی اخیر Pi را نگه می‌دارد. بدون بودجه‌ی صریح برای نگه‌داری، + Compaction دستی همچنان یک checkpoint سخت باقی می‌ماند و context بازسازی‌شده از + summary جدید شروع می‌شود. +- برای اجرای precheck اختیاری حلقه‌ی ابزار پس از نتایج ابزار جدید و پیش از فراخوانی مدل بعدی، + `agents.defaults.compaction.midTurnPrecheck.enabled: true` را تنظیم کنید. این فقط یک trigger است؛ + تولید summary همچنان از مسیر پیکربندی‌شده‌ی Compaction استفاده می‌کند. این مستقل از + `maxActiveTranscriptBytes` است، که یک نگهبان اندازه‌ی بایتی برای active-transcript در شروع turn است. +- برای اجرای Compaction محلی پیش از یک turn، هنگامی که active transcript بزرگ می‌شود، + `agents.defaults.compaction.maxActiveTranscriptBytes` را به یک مقدار بایتی یا + رشته‌ای مانند `"20mb"` تنظیم کنید. این نگهبان فقط وقتی فعال است که + `truncateAfterCompaction` نیز فعال باشد. برای غیرفعال کردن، آن را تنظیم‌نشده بگذارید یا `0` قرار دهید. - وقتی `agents.defaults.compaction.truncateAfterCompaction` فعال باشد، - OpenClaw پس از Compaction رونوشت فعال را به یک JSONL جانشین فشرده‌شده می‌چرخاند. - رونوشت کامل قدیمی بایگانی می‌ماند و به‌جای بازنویسی درجا، از نقطه وارسی - Compaction لینک می‌شود. + OpenClaw پس از Compaction، active transcript را به یک JSONL جانشینِ فشرده‌شده می‌چرخاند. + transcript کامل قدیمی بایگانی می‌ماند و از checkpoint مربوط به + Compaction به آن لینک می‌شود، نه اینکه درجا بازنویسی شود. -چرا: فضای کافی برای «کارهای نگهداشتی» چندنوبتی، مانند نوشتن حافظه، باقی بماند پیش از آنکه Compaction اجتناب‌ناپذیر شود. +چرایی: فضای کافی برای «خانه‌تکانی» چند-turnی (مانند نوشتن در memory) باقی بماند، پیش از آنکه Compaction اجتناب‌ناپذیر شود. پیاده‌سازی: `ensurePiCompactionReserveTokens()` در `src/agents/pi-settings.ts` -(از `src/agents/pi-embedded-runner.ts` فراخوانی می‌شود). +(که از `src/agents/pi-embedded-runner.ts` فراخوانی می‌شود). --- -## ارائه‌دهندگان Compaction قابل‌اتصال +## providerهای قابل‌اتصال برای Compaction -Pluginها می‌توانند از طریق `registerCompactionProvider()` در API مربوط به Plugin یک ارائه‌دهنده Compaction ثبت کنند. وقتی `agents.defaults.compaction.provider` روی شناسه یک ارائه‌دهنده ثبت‌شده تنظیم شود، افزونه محافظ به‌جای خط لوله داخلی `summarizeInStages`، خلاصه‌سازی را به آن ارائه‌دهنده واگذار می‌کند. +Plugins می‌توانند از طریق `registerCompactionProvider()` روی API مربوط به plugin، یک provider برای Compaction ثبت کنند. وقتی `agents.defaults.compaction.provider` روی id یک provider ثبت‌شده تنظیم شود، افزونه‌ی safeguard به‌جای pipeline داخلی `summarizeInStages`، خلاصه‌سازی را به آن provider واگذار می‌کند. -- `provider`: شناسه یک Plugin ارائه‌دهنده Compaction ثبت‌شده. برای خلاصه‌سازی پیش‌فرض با LLM تنظیم‌نشده بگذارید. -- تنظیم یک `provider` باعث اجبار `mode: "safeguard"` می‌شود. -- ارائه‌دهندگان همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را که مسیر داخلی استفاده می‌کند دریافت می‌کنند. -- محافظ همچنان پس از خروجی ارائه‌دهنده، زمینه پسوند نوبت اخیر و نوبت جداشده را حفظ می‌کند. -- خلاصه‌سازی داخلی محافظ، خلاصه‌های قبلی را همراه با پیام‌های جدید دوباره تقطیر می‌کند - به‌جای اینکه خلاصه کامل قبلی را عینا حفظ کند. -- حالت محافظ به‌طور پیش‌فرض ممیزی‌های کیفیت خلاصه را فعال می‌کند؛ برای نادیده گرفتن - رفتار تلاش دوباره هنگام خروجی بدشکل، `qualityGuard.enabled: false` را تنظیم کنید. -- اگر ارائه‌دهنده شکست بخورد یا نتیجه‌ای خالی برگرداند، OpenClaw به‌طور خودکار به خلاصه‌سازی داخلی با LLM بازمی‌گردد. -- سیگنال‌های لغو/مهلت زمانی دوباره پرتاب می‌شوند (بلعیده نمی‌شوند) تا لغو فراخواننده رعایت شود. +- `provider`: id یک plugin ثبت‌شده به‌عنوان provider Compaction. برای خلاصه‌سازی LLM پیش‌فرض، آن را تنظیم‌نشده بگذارید. +- تنظیم یک `provider` باعث می‌شود `mode: "safeguard"` اجباری شود. +- providerها همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را مانند مسیر داخلی دریافت می‌کنند. +- safeguard همچنان context مربوط به turnهای اخیر و suffix مربوط به split-turn را پس از خروجی provider حفظ می‌کند. +- خلاصه‌سازی safeguard داخلی، summaryهای قبلی را با پیام‌های جدید دوباره تقطیر می‌کند + به‌جای اینکه summary کامل قبلی را عیناً حفظ کند. +- حالت safeguard به‌صورت پیش‌فرض ممیزی کیفیت summary را فعال می‌کند؛ برای رد کردن رفتار retry-on-malformed-output، + `qualityGuard.enabled: false` را تنظیم کنید. +- اگر provider شکست بخورد یا نتیجه‌ی خالی برگرداند، OpenClaw به‌صورت خودکار به خلاصه‌سازی داخلی LLM برمی‌گردد. +- سیگنال‌های abort/timeout دوباره پرتاب می‌شوند (بلعیده نمی‌شوند) تا cancellation فراخواننده رعایت شود. -منبع: `src/plugins/compaction-provider.ts`، `src/agents/pi-hooks/compaction-safeguard.ts`. +منبع: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. --- -## سطح‌های قابل مشاهده برای کاربر +## سطوح قابل‌مشاهده برای کاربر -می‌توانید Compaction و وضعیت نشست را از طریق موارد زیر مشاهده کنید: +می‌توانید وضعیت Compaction و session را از این مسیرها مشاهده کنید: -- `/status` (در هر نشست گفتگو) +- `/status` (در هر session گفت‌وگو) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- حالت پرجزئیات: `🧹 Auto-compaction complete` + تعداد Compaction +- حالت verbose: `🧹 Auto-compaction complete` + تعداد Compaction --- -## نگهداشت بی‌صدا (`NO_REPLY`) +## خانه‌تکانی بی‌صدا (`NO_REPLY`) -OpenClaw از نوبت‌های «بی‌صدا» برای کارهای پس‌زمینه پشتیبانی می‌کند؛ جایی که کاربر نباید خروجی میانی ببیند. +OpenClaw از turnهای «بی‌صدا» برای کارهای پس‌زمینه پشتیبانی می‌کند؛ جایی که کاربر نباید خروجی میانی ببیند. قرارداد: -- دستیار خروجی خود را با توکن بی‌صدای دقیق `NO_REPLY` / - `no_reply` شروع می‌کند تا نشان دهد «پاسخی به کاربر تحویل داده نشود». -- OpenClaw این مورد را در لایه تحویل حذف/سرکوب می‌کند. -- سرکوب توکن بی‌صدای دقیق به حروف بزرگ و کوچک حساس نیست، بنابراین وقتی کل payload فقط همان توکن بی‌صدا باشد، هر دو - `NO_REPLY` و `no_reply` حساب می‌شوند. -- این فقط برای نوبت‌های واقعا پس‌زمینه/بدون تحویل است؛ میان‌بری برای - درخواست‌های عادی و قابل اقدام کاربر نیست. +- assistant خروجی خود را با token بی‌صدای دقیق `NO_REPLY` / + `no_reply` شروع می‌کند تا نشان دهد «پاسخی به کاربر تحویل نده». +- OpenClaw این مورد را در لایه‌ی تحویل حذف/سرکوب می‌کند. +- سرکوب token بی‌صدای دقیق به حروف بزرگ و کوچک حساس نیست، بنابراین `NO_REPLY` و + `no_reply` هر دو وقتی کل payload فقط همان token بی‌صدا باشد معتبرند. +- این فقط برای turnهای واقعاً پس‌زمینه/بدون تحویل است؛ میان‌بری برای + درخواست‌های معمول و اقدام‌پذیر کاربر نیست. -از `2026.1.10`، OpenClaw همچنین وقتی یک -بخش جزئی با `NO_REPLY` شروع شود، **استریم پیش‌نویس/درحال تایپ** را سرکوب می‌کند، بنابراین عملیات بی‌صدا خروجی جزئی را -در میانه نوبت افشا نمی‌کنند. +از نسخه‌ی `2026.1.10`، OpenClaw همچنین وقتی یک +chunk جزئی با `NO_REPLY` شروع شود، **draft/typing streaming** را سرکوب می‌کند؛ بنابراین عملیات بی‌صدا خروجی جزئی +را وسط turn افشا نمی‌کنند. --- -## «تخلیه حافظه» پیش از Compaction (پیاده‌سازی شده) +## «flush کردن memory» پیش از Compaction (پیاده‌سازی‌شده) -هدف: پیش از وقوع Compaction خودکار، یک نوبت عاملی بی‌صدا اجرا شود که وضعیت بادوام را -روی دیسک بنویسد، مثلا `memory/YYYY-MM-DD.md` در فضای کاری عامل، تا Compaction نتواند -زمینه حیاتی را پاک کند. +هدف: پیش از وقوع auto-compaction، یک turn agentic بی‌صدا اجرا شود که state پایدار را +روی دیسک بنویسد (مثلاً `memory/YYYY-MM-DD.md` در workspace عامل)، تا Compaction نتواند +context حیاتی را پاک کند. -OpenClaw از رویکرد **تخلیه پیش از آستانه** استفاده می‌کند: +OpenClaw از رویکرد **pre-threshold flush** استفاده می‌کند: -1. مصرف زمینه نشست را پایش کنید. -2. وقتی از یک «آستانه نرم» عبور کرد (پایین‌تر از آستانه Compaction در Pi)، یک دستور بی‌صدا - با مضمون «اکنون حافظه را بنویس» برای عامل اجرا کنید. -3. از توکن بی‌صدای دقیق `NO_REPLY` / `no_reply` استفاده کنید تا کاربر +1. مصرف context در session را پایش کنید. +2. وقتی از یک «soft threshold» عبور کرد (پایین‌تر از آستانه‌ی Compaction در Pi)، یک دستور بی‌صدا + برای «اکنون memory را بنویس» به عامل اجرا کنید. +3. از token بی‌صدای دقیق `NO_REPLY` / `no_reply` استفاده کنید تا کاربر چیزی نبیند. -پیکربندی (`agents.defaults.compaction.memoryFlush`): +Config (`agents.defaults.compaction.memoryFlush`): - `enabled` (پیش‌فرض: `true`) -- `model` (بازنویسی اختیاری و دقیق ارائه‌دهنده/مدل برای نوبت تخلیه، برای مثال `ollama/qwen3:8b`) +- `model` (override اختیاری و دقیق provider/model برای turn مربوط به flush، برای مثال `ollama/qwen3:8b`) - `softThresholdTokens` (پیش‌فرض: `4000`) -- `prompt` (پیام کاربر برای نوبت تخلیه) -- `systemPrompt` (پرامپت سیستمی اضافه که برای نوبت تخلیه پیوست می‌شود) +- `prompt` (پیام کاربر برای turn مربوط به flush) +- `systemPrompt` (system prompt اضافی که برای turn مربوط به flush افزوده می‌شود) -نکات: +نکته‌ها: -- پرامپت/پرامپت سیستمی پیش‌فرض شامل یک راهنمای `NO_REPLY` برای سرکوب - تحویل است. -- وقتی `model` تنظیم شده باشد، نوبت تخلیه از همان مدل استفاده می‌کند بدون اینکه زنجیره fallback نشست فعال را - به ارث ببرد، بنابراین نگهداشت صرفا محلی بی‌صدا به یک مدل گفتگوی پولی - fallback نمی‌کند. -- تخلیه در هر چرخه Compaction یک‌بار اجرا می‌شود (در `sessions.json` ردیابی می‌شود). -- تخلیه فقط برای نشست‌های جاسازی‌شده Pi اجرا می‌شود (backendهای CLI از آن عبور می‌کنند). -- وقتی فضای کاری نشست فقط‌خواندنی باشد (`workspaceAccess: "ro"` یا `"none"`)، تخلیه رد می‌شود. -- برای طرح فایل فضای کاری و الگوهای نوشتن، [حافظه](/fa/concepts/memory) را ببینید. +- prompt/system prompt پیش‌فرض شامل یک hint با `NO_REPLY` هستند تا تحویل + سرکوب شود. +- وقتی `model` تنظیم شود، turn مربوط به flush از همان مدل استفاده می‌کند بدون اینکه + زنجیره‌ی fallback مربوط به session فعال را به ارث ببرد؛ بنابراین خانه‌تکانی فقط-محلی به‌صورت بی‌صدا + به یک مدل گفت‌وگوی پولی fallback نمی‌کند. +- flush در هر چرخه‌ی Compaction یک‌بار اجرا می‌شود (در `sessions.json` ردیابی می‌شود). +- flush فقط برای sessionهای تعبیه‌شده‌ی Pi اجرا می‌شود (backendهای CLI آن را رد می‌کنند). +- وقتی workspace مربوط به session فقط‌خواندنی باشد (`workspaceAccess: "ro"` یا `"none"`)، flush رد می‌شود. +- برای چیدمان فایل‌های workspace و الگوهای نوشتن، [Memory](/fa/concepts/memory) را ببینید. -Pi همچنین یک hook با نام `session_before_compact` در API افزونه ارائه می‌دهد، اما منطق -تخلیه OpenClaw امروز در سمت Gateway زندگی می‌کند. +Pi همچنین یک hook با نام `session_before_compact` در API افزونه ارائه می‌کند، اما منطق +flush در OpenClaw امروز در سمت Gateway قرار دارد. --- -## فهرست عیب‌یابی +## چک‌لیست عیب‌یابی -- کلید نشست اشتباه است؟ از [/concepts/session](/fa/concepts/session) شروع کنید و `sessionKey` را در `/status` تایید کنید. -- ناهماهنگی بین ذخیره‌گاه و رونوشت؟ میزبان Gateway و مسیر ذخیره‌گاه را از `openclaw status` تایید کنید. -- اسپم Compaction؟ بررسی کنید: - - پنجره زمینه مدل (بیش از حد کوچک) - - تنظیمات Compaction (`reserveTokens` بیش از حد بالا برای پنجره مدل می‌تواند باعث Compaction زودتر شود) - - تورم نتیجه ابزار: هرس نشست را فعال/تنظیم کنید -- نوبت‌های بی‌صدا نشت می‌کنند؟ تایید کنید پاسخ با `NO_REPLY` شروع می‌شود (توکن دقیق و غیرحساس به بزرگی/کوچکی حروف) و روی بیلدی هستید که شامل اصلاح سرکوب استریم است. +- کلید session اشتباه است؟ از [/concepts/session](/fa/concepts/session) شروع کنید و `sessionKey` را در `/status` تأیید کنید. +- ناهماهنگی بین store و transcript؟ میزبان Gateway و مسیر store را از `openclaw status` تأیید کنید. +- spam شدن Compaction؟ بررسی کنید: + - پنجره‌ی context مدل (بیش از حد کوچک) + - تنظیمات Compaction (`reserveTokens` اگر برای پنجره‌ی مدل بیش از حد بالا باشد، می‌تواند باعث Compaction زودتر شود) + - بادکردن نتیجه‌ی ابزار: session pruning را فعال/تنظیم کنید +- نشت turnهای بی‌صدا؟ تأیید کنید پاسخ با `NO_REPLY` شروع می‌شود (token دقیق و غیرحساس به حروف بزرگ/کوچک) و روی buildی هستید که اصلاح سرکوب streaming را شامل می‌شود. ## مرتبط -- [مدیریت نشست](/fa/concepts/session) -- [هرس نشست](/fa/concepts/session-pruning) -- [موتور زمینه](/fa/concepts/context-engine) +- [مدیریت session](/fa/concepts/session) +- [session pruning](/fa/concepts/session-pruning) +- [موتور context](/fa/concepts/context-engine) diff --git a/docs/fa/tools/index.md b/docs/fa/tools/index.md index a589ca501..18aa25471 100644 --- a/docs/fa/tools/index.md +++ b/docs/fa/tools/index.md @@ -1,129 +1,129 @@ --- read_when: - می‌خواهید بدانید OpenClaw چه ابزارهایی ارائه می‌دهد - - باید ابزارها را پیکربندی کنید، به آن‌ها اجازه دهید یا آن‌ها را رد کنید - - در حال تصمیم‌گیری بین ابزارهای توکار، Skills و Pluginها هستید -summary: 'مرور کلی ابزارها و Pluginهای OpenClaw: عامل چه کارهایی می‌تواند انجام دهد و چگونه آن را گسترش دهید' -title: ابزارها و Pluginها + - باید ابزارها را پیکربندی، مجاز یا رد کنید + - شما در حال تصمیم‌گیری بین ابزارهای داخلی، Skills و Pluginها هستید +summary: 'نمای کلی ابزارها و Pluginهای OpenClaw: عامل چه کارهایی می‌تواند انجام دهد و چگونه آن را گسترش دهید' +title: ابزارها و Plugin‌ها x-i18n: - generated_at: "2026-04-29T23:43:43Z" + generated_at: "2026-04-30T16:31:32Z" model: gpt-5.5 provider: openai - source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0 + source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb source_path: tools/index.md workflow: 16 --- -هر کاری که عامل فراتر از تولید متن انجام می‌دهد، از طریق **ابزارها** رخ می‌دهد. -ابزارها راهی هستند که عامل با آن فایل‌ها را می‌خواند، فرمان‌ها را اجرا می‌کند، وب را مرور می‌کند، پیام +هر کاری که عامل فراتر از تولید متن انجام می‌دهد از طریق **ابزارها** انجام می‌شود. +ابزارها روشی هستند که عامل با آن‌ها فایل‌ها را می‌خواند، فرمان‌ها را اجرا می‌کند، وب را مرور می‌کند، پیام می‌فرستد و با دستگاه‌ها تعامل می‌کند. -## ابزارها، Skills، و Pluginها +## ابزارها، Skills، و plugins OpenClaw سه لایه دارد که با هم کار می‌کنند: - ابزار یک تابع دارای نوع است که عامل می‌تواند آن را فراخوانی کند (مثلاً `exec`، `browser`، - `web_search`، `message`). OpenClaw مجموعه‌ای از **ابزارهای داخلی** ارائه می‌کند و - Pluginها می‌توانند موارد بیشتری ثبت کنند. + ابزار یک تابع دارای نوع است که عامل می‌تواند آن را فراخوانی کند (برای نمونه `exec`، `browser`، + `web_search`، `message`). OpenClaw مجموعه‌ای از **ابزارهای داخلی** را ارائه می‌کند و + plugins می‌توانند موارد بیشتری را ثبت کنند. عامل ابزارها را به‌صورت تعریف‌های تابع ساختاریافته‌ای می‌بیند که به API مدل فرستاده می‌شوند. - یک skill فایل markdown (`SKILL.md`) است که در system prompt تزریق می‌شود. - Skills به عامل زمینه، محدودیت‌ها و راهنمایی گام‌به‌گام می‌دهند تا از - ابزارها به‌طور مؤثر استفاده کند. Skills در workspace شما، در پوشه‌های مشترک، - یا داخل Pluginها ارائه می‌شوند. + یک Skill یک فایل markdown (`SKILL.md`) است که در system prompt تزریق می‌شود. + Skills به عامل زمینه، محدودیت‌ها، و راهنمایی گام‌به‌گام برای + استفاده مؤثر از ابزارها می‌دهند. Skills در فضای کاری شما، در پوشه‌های مشترک، + یا داخل plugins عرضه می‌شوند. [مرجع Skills](/fa/tools/skills) | [ایجاد Skills](/fa/tools/creating-skills) - - Plugin بسته‌ای است که می‌تواند هر ترکیبی از قابلیت‌ها را ثبت کند: - کانال‌ها، ارائه‌دهندگان مدل، ابزارها، Skills، گفتار، رونویسی هم‌زمان، - صدای هم‌زمان، درک رسانه، تولید تصویر، تولید ویدئو، - دریافت وب، جست‌وجوی وب، و موارد بیشتر. برخی Pluginها **core** هستند (همراه - OpenClaw ارائه می‌شوند)، برخی دیگر **external** هستند (توسط جامعه روی npm منتشر می‌شوند). + + یک plugin بسته‌ای است که می‌تواند هر ترکیبی از قابلیت‌ها را ثبت کند: + کانال‌ها، ارائه‌دهندگان مدل، ابزارها، Skills، گفتار، رونویسی بی‌درنگ، + صدای بی‌درنگ، درک رسانه، تولید تصویر، تولید ویدئو، + دریافت وب، جستجوی وب، و موارد بیشتر. برخی plugins **هسته‌ای** هستند (همراه با + OpenClaw عرضه می‌شوند)، و برخی دیگر **خارجی** هستند (توسط جامعه در npm منتشر می‌شوند). - [نصب و پیکربندی Pluginها](/fa/tools/plugin) | [خودتان بسازید](/fa/plugins/building-plugins) + [نصب و پیکربندی plugins](/fa/tools/plugin) | [ساخت مورد اختصاصی خودتان](/fa/plugins/building-plugins) ## ابزارهای داخلی -این ابزارها همراه OpenClaw ارائه می‌شوند و بدون نصب هیچ Pluginی در دسترس هستند: +این ابزارها همراه با OpenClaw عرضه می‌شوند و بدون نصب هیچ plugin در دسترس هستند: -| ابزار | کاری که انجام می‌دهد | صفحه | +| ابزار | کاری که انجام می‌دهد | صفحه | | ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ | -| `exec` / `process` | اجرای فرمان‌های shell، مدیریت فرایندهای پس‌زمینه | [Exec](/fa/tools/exec), [تأییدهای Exec](/fa/tools/exec-approvals) | -| `code_execution` | اجرای تحلیل Python از راه دور در sandbox | [اجرای کد](/fa/tools/code-execution) | -| `browser` | کنترل مرورگر Chromium (ناوبری، کلیک، screenshot) | [مرورگر](/fa/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | جست‌وجوی وب، جست‌وجوی پست‌های X، دریافت محتوای صفحه | [وب](/fa/tools/web), [دریافت وب](/fa/tools/web-fetch) | -| `read` / `write` / `edit` | ورودی/خروجی فایل در workspace | | -| `apply_patch` | patchهای فایل چندبخشی | [اعمال Patch](/fa/tools/apply-patch) | -| `message` | ارسال پیام در همه کانال‌ها | [ارسال عامل](/fa/tools/agent-send) | -| `canvas` | راهبری node Canvas (ارائه، eval، snapshot) | | -| `nodes` | کشف و هدف‌گیری دستگاه‌های جفت‌شده | | -| `cron` / `gateway` | مدیریت کارهای زمان‌بندی‌شده؛ بازرسی، patch، راه‌اندازی مجدد، یا به‌روزرسانی gateway | | -| `image` / `image_generate` | تحلیل یا تولید تصویر | [تولید تصویر](/fa/tools/image-generation) | -| `music_generate` | تولید قطعه‌های موسیقی | [تولید موسیقی](/fa/tools/music-generation) | -| `video_generate` | تولید ویدئوها | [تولید ویدئو](/fa/tools/video-generation) | -| `tts` | تبدیل یک‌باره متن به گفتار | [TTS](/fa/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | مدیریت نشست، وضعیت، و هماهنگ‌سازی زیرعامل‌ها | [زیرعامل‌ها](/fa/tools/subagents) | -| `session_status` | بازخوانی سبک به سبک `/status` و override مدل نشست | [ابزارهای نشست](/fa/concepts/session-tool) | +| `exec` / `process` | اجرای فرمان‌های shell، مدیریت فرایندهای پس‌زمینه | [Exec](/fa/tools/exec), [تأییدیه‌های Exec](/fa/tools/exec-approvals) | +| `code_execution` | اجرای تحلیل Python راه‌دور در sandbox | [اجرای کد](/fa/tools/code-execution) | +| `browser` | کنترل مرورگر Chromium (پیمایش، کلیک، screenshot) | [مرورگر](/fa/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | جستجوی وب، جستجوی پست‌های X، دریافت محتوای صفحه | [وب](/fa/tools/web), [دریافت وب](/fa/tools/web-fetch) | +| `read` / `write` / `edit` | ورودی/خروجی فایل در فضای کاری | | +| `apply_patch` | patchهای چندبخشی فایل | [اعمال Patch](/fa/tools/apply-patch) | +| `message` | ارسال پیام در همه کانال‌ها | [ارسال عامل](/fa/tools/agent-send) | +| `canvas` | هدایت Canvas مربوط به Node (ارائه، eval، snapshot) | | +| `nodes` | کشف و هدف‌گیری دستگاه‌های جفت‌شده | | +| `cron` / `gateway` | مدیریت کارهای زمان‌بندی‌شده؛ بررسی، patch، راه‌اندازی مجدد، یا به‌روزرسانی gateway | | +| `image` / `image_generate` | تحلیل یا تولید تصویر | [تولید تصویر](/fa/tools/image-generation) | +| `music_generate` | تولید قطعه‌های موسیقی | [تولید موسیقی](/fa/tools/music-generation) | +| `video_generate` | تولید ویدئو | [تولید ویدئو](/fa/tools/video-generation) | +| `tts` | تبدیل یک‌باره متن به گفتار | [TTS](/fa/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | مدیریت نشست، وضعیت، و هماهنگ‌سازی زیرعامل‌ها | [زیرعامل‌ها](/fa/tools/subagents) | +| `session_status` | بازخوانی سبک‌وزن به سبک `/status` و override مدل نشست | [ابزارهای نشست](/fa/concepts/session-tool) | -برای کار با تصویر، از `image` برای تحلیل و از `image_generate` برای تولید یا ویرایش استفاده کنید. اگر `openai/*`، `google/*`، `fal/*`، یا ارائه‌دهنده تصویر غیردیفالتی دیگری را هدف می‌گیرید، ابتدا auth/API key آن ارائه‌دهنده را پیکربندی کنید. +برای کار با تصویر، از `image` برای تحلیل و از `image_generate` برای تولید یا ویرایش استفاده کنید. اگر `openai/*`، `google/*`، `fal/*`، یا ارائه‌دهنده تصویر غیرفضلی دیگری را هدف می‌گیرید، ابتدا احراز هویت/API key آن ارائه‌دهنده را پیکربندی کنید. -برای کار با موسیقی، از `music_generate` استفاده کنید. اگر `google/*`، `minimax/*`، یا ارائه‌دهنده موسیقی غیردیفالتی دیگری را هدف می‌گیرید، ابتدا auth/API key آن ارائه‌دهنده را پیکربندی کنید. +برای کار با موسیقی، از `music_generate` استفاده کنید. اگر `google/*`، `minimax/*`، یا ارائه‌دهنده موسیقی غیرفضلی دیگری را هدف می‌گیرید، ابتدا احراز هویت/API key آن ارائه‌دهنده را پیکربندی کنید. -برای کار با ویدئو، از `video_generate` استفاده کنید. اگر `qwen/*` یا ارائه‌دهنده ویدئوی غیردیفالتی دیگری را هدف می‌گیرید، ابتدا auth/API key آن ارائه‌دهنده را پیکربندی کنید. +برای کار با ویدئو، از `video_generate` استفاده کنید. اگر `qwen/*` یا ارائه‌دهنده ویدئوی غیرفضلی دیگری را هدف می‌گیرید، ابتدا احراز هویت/API key آن ارائه‌دهنده را پیکربندی کنید. -برای تولید صدای مبتنی بر workflow، وقتی Pluginای مانند -ComfyUI آن را ثبت می‌کند، از `music_generate` استفاده کنید. این جدا از `tts` است که متن را به گفتار تبدیل می‌کند. +برای تولید صوت مبتنی بر workflow، وقتی pluginای مانند +ComfyUI آن را ثبت می‌کند، از `music_generate` استفاده کنید. این از `tts` که تبدیل متن به گفتار است جداست. -`session_status` ابزار سبک وضعیت/بازخوانی در گروه نشست‌ها است. -به پرسش‌های به سبک `/status` درباره نشست فعلی پاسخ می‌دهد و می‌تواند +`session_status` ابزار سبک‌وزن وضعیت/بازخوانی در گروه نشست‌ها است. +این ابزار به پرسش‌هایی به سبک `/status` درباره نشست فعلی پاسخ می‌دهد و می‌تواند به‌صورت اختیاری یک override مدل برای هر نشست تنظیم کند؛ `model=default` آن -override را پاک می‌کند. مانند `/status`، می‌تواند شمارنده‌های پراکنده token/cache و -برچسب مدل runtime فعال را از آخرین ورودی استفاده transcript تکمیل کند. +override را پاک می‌کند. مانند `/status`، می‌تواند شمارنده‌های پراکنده token/cache و برچسب +مدل runtime فعال را از آخرین ورودی کاربرد transcript تکمیل کند. -`gateway` ابزار runtime فقط برای مالک در عملیات gateway است: +`gateway` ابزار runtime فقط مخصوص مالک برای عملیات gateway است: -- `config.schema.lookup` برای یک زیردرخت پیکربندی محدود به مسیر پیش از ویرایش‌ها +- `config.schema.lookup` برای یک زیرشاخه پیکربندی محدود به مسیر پیش از ویرایش‌ها - `config.get` برای snapshot + hash پیکربندی فعلی - `config.patch` برای به‌روزرسانی‌های جزئی پیکربندی همراه با راه‌اندازی مجدد - `config.apply` فقط برای جایگزینی کامل پیکربندی - `update.run` برای خودبه‌روزرسانی صریح + راه‌اندازی مجدد -برای تغییرات جزئی، ابتدا `config.schema.lookup` و سپس `config.patch` را ترجیح دهید. فقط وقتی از +برای تغییرات جزئی، ابتدا `config.schema.lookup` و سپس `config.patch` را ترجیح دهید. فقط زمانی از `config.apply` استفاده کنید که عمداً کل پیکربندی را جایگزین می‌کنید. برای مستندات گسترده‌تر پیکربندی، [پیکربندی](/fa/gateway/configuration) و [مرجع پیکربندی](/fa/gateway/configuration-reference) را بخوانید. این ابزار همچنین از تغییر `tools.exec.ask` یا `tools.exec.security` خودداری می‌کند؛ -aliasهای قدیمی `tools.bash.*` به همان مسیرهای محافظت‌شده exec نرمال‌سازی می‌شوند. +نام‌های مستعار قدیمی `tools.bash.*` به همان مسیرهای exec محافظت‌شده عادی‌سازی می‌شوند. ### ابزارهای ارائه‌شده توسط Plugin -Pluginها می‌توانند ابزارهای بیشتری ثبت کنند. چند نمونه: +Plugins می‌توانند ابزارهای بیشتری ثبت کنند. چند نمونه: -- [Diffها](/fa/tools/diffs) — نمایشگر و renderer diff +- [Diffها](/fa/tools/diffs) — نمایشگر و رندرکننده diff - [وظیفه LLM](/fa/tools/llm-task) — گام LLM فقط JSON برای خروجی ساختاریافته -- [Lobster](/fa/tools/lobster) — runtime workflow دارای نوع با تأییدهای قابل‌ازسرگیری -- [تولید موسیقی](/fa/tools/music-generation) — ابزار مشترک `music_generate` با ارائه‌دهندگان پشتیبانی‌شده با workflow -- [OpenProse](/fa/prose) — هماهنگ‌سازی workflow با اولویت markdown +- [Lobster](/fa/tools/lobster) — runtime workflow دارای نوع با تأییدیه‌های قابل ازسرگیری +- [تولید موسیقی](/fa/tools/music-generation) — ابزار مشترک `music_generate` با ارائه‌دهندگان مبتنی بر workflow +- [OpenProse](/fa/prose) — هماهنگ‌سازی workflow با رویکرد markdown-first - [Tokenjuice](/fa/tools/tokenjuice) — فشرده‌سازی نتایج پرنویز ابزارهای `exec` و `bash` ## پیکربندی ابزار ### فهرست‌های مجاز و ممنوع -کنترل کنید عامل کدام ابزارها را می‌تواند از طریق `tools.allow` / `tools.deny` در -پیکربندی فراخوانی کند. deny همیشه بر allow غلبه می‌کند. +اینکه عامل چه ابزارهایی را می‌تواند فراخوانی کند، از طریق `tools.allow` / `tools.deny` در +پیکربندی کنترل کنید. ممنوع همیشه بر مجاز اولویت دارد. ```json5 { @@ -134,42 +134,45 @@ Pluginها می‌توانند ابزارهای بیشتری ثبت کنند. چ } ``` -OpenClaw وقتی یک allowlist صریح به هیچ ابزار قابل‌فراخوانی‌ای resolve نشود، بسته و متوقف می‌شود. -برای مثال، `tools.allow: ["query_db"]` فقط وقتی کار می‌کند که یک Plugin بارگذاری‌شده واقعاً -`query_db` را ثبت کند. اگر هیچ ابزار داخلی، Plugin، یا ابزار MCP بسته‌بندی‌شده‌ای با -allowlist تطبیق نداشته باشد، اجرا پیش از فراخوانی مدل متوقف می‌شود، به‌جای اینکه به‌صورت -اجرای فقط متنی ادامه دهد که ممکن است نتایج ابزار را hallucinate کند. +OpenClaw وقتی یک allowlist صریح به هیچ ابزار قابل فراخوانی‌ای resolve نشود، به‌صورت بسته شکست می‌خورد. +برای مثال، `tools.allow: ["query_db"]` فقط زمانی کار می‌کند که یک plugin بارگذاری‌شده واقعاً +`query_db` را ثبت کند. اگر هیچ ابزار داخلی، plugin، یا ابزار MCP بسته‌بندی‌شده‌ای با +allowlist مطابقت نداشته باشد، اجرا پیش از فراخوانی مدل متوقف می‌شود، به‌جای اینکه به‌صورت +اجرای فقط‌متن ادامه دهد که ممکن است نتایج ابزار را توهم کند. ### پروفایل‌های ابزار `tools.profile` پیش از اعمال `allow`/`deny` یک allowlist پایه تنظیم می‌کند. override برای هر عامل: `agents.list[].tools.profile`. -| پروفایل | شامل چه چیزهایی است | +| پروفایل | شامل چه چیزهایی است | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | baseline نامحدود برای دسترسی گسترده‌تر command/control؛ همانند تنظیم‌نکردن `tools.profile` | +| `full` | پایه نامحدود برای دسترسی گسترده‌تر فرمان/کنترل؛ همانند تنظیم‌نکردن `tools.profile` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `minimal` | فقط `session_status` | `tools.profile: "messaging"` عمداً برای عامل‌های متمرکز بر کانال محدود است. -ابزارهای گسترده‌تر command/control مانند filesystem، runtime، +این پروفایل ابزارهای گسترده‌تر فرمان/کنترل مانند filesystem، runtime، browser، canvas، nodes، cron، و کنترل gateway را کنار می‌گذارد. از `tools.profile: "full"` -به‌عنوان baseline نامحدود برای دسترسی گسترده‌تر command/control استفاده کنید، سپس در صورت نیاز +به‌عنوان پایه نامحدود برای دسترسی گسترده‌تر فرمان/کنترل استفاده کنید، سپس در صورت نیاز دسترسی را با `tools.allow` / `tools.deny` محدود کنید. -`coding` ابزارهای سبک وب (`web_search`، `web_fetch`، `x_search`) را شامل می‌شود -اما ابزار کامل کنترل مرورگر را نه. خودکارسازی مرورگر می‌تواند نشست‌های واقعی -و پروفایل‌های واردشده را راهبری کند، بنابراین آن را صریحاً با +`coding` ابزارهای سبک‌وزن وب (`web_search`، `web_fetch`، `x_search`) را شامل می‌شود +اما ابزار کامل کنترل مرورگر را نه. خودکارسازی مرورگر می‌تواند نشست‌های واقعی و +پروفایل‌های واردشده را هدایت کند، بنابراین آن را به‌صراحت با `tools.alsoAllow: ["browser"]` یا `agents.list[].tools.alsoAllow: ["browser"]` برای هر عامل اضافه کنید. + +پیکربندی `tools.exec` یا `tools.fs` زیر یک پروفایل محدود (`messaging`، `minimal`) به‌صورت ضمنی allowlist پروفایل را گسترده‌تر نمی‌کند. وقتی می‌خواهید یک پروفایل محدود از آن بخش‌های پیکربندی‌شده استفاده کند، ورودی‌های صریح `tools.alsoAllow` اضافه کنید (برای نمونه `["exec", "process"]` برای exec، یا `["read", "write", "edit"]` برای fs). OpenClaw وقتی یک بخش پیکربندی بدون grant متناظر `alsoAllow` حاضر باشد، هنگام startup هشدار ثبت می‌کند. + + پروفایل‌های `coding` و `messaging` همچنین ابزارهای MCP بسته‌بندی‌شده پیکربندی‌شده را -زیر کلید Plugin با نام `bundle-mcp` مجاز می‌کنند. وقتی می‌خواهید -یک پروفایل built-inهای عادی خود را نگه دارد اما همه ابزارهای MCP پیکربندی‌شده را پنهان کند، -`tools.deny: ["bundle-mcp"]` را اضافه کنید. +زیر کلید plugin با نام `bundle-mcp` مجاز می‌کنند. وقتی می‌خواهید +یک پروفایل built-inهای عادی خود را نگه دارد اما همه ابزارهای MCP پیکربندی‌شده را پنهان کند، `tools.deny: ["bundle-mcp"]` را اضافه کنید. پروفایل `minimal` ابزارهای MCP بسته‌بندی‌شده را شامل نمی‌شود. مثال (گسترده‌ترین سطح ابزار به‌صورت پیش‌فرض): @@ -184,36 +187,35 @@ browser، canvas، nodes، cron، و کنترل gateway را کنار می‌گ ### گروه‌های ابزار -در فهرست‌های allow/deny از میان‌برهای `group:*` استفاده کنید: +از میان‌برهای `group:*` در فهرست‌های allow/deny استفاده کنید: | گروه | ابزارها | | ------------------ | --------------------------------------------------------------------------------------------------------- | -| `group:runtime` | exec، process، code_execution (`bash` به‌عنوان نام مستعار برای `exec` پذیرفته می‌شود) | -| `group:fs` | read، write، edit، apply_patch | -| `group:sessions` | sessions_list، sessions_history، sessions_send، sessions_spawn، sessions_yield، subagents، session_status | -| `group:memory` | memory_search، memory_get | -| `group:web` | web_search، x_search، web_fetch | -| `group:ui` | browser، canvas | -| `group:automation` | cron، gateway | +| `group:runtime` | exec, process, code_execution (`bash` به‌عنوان نام مستعار برای `exec` پذیرفته می‌شود) | +| `group:fs` | read, write, edit, apply_patch | +| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | +| `group:memory` | memory_search, memory_get | +| `group:web` | web_search, x_search, web_fetch | +| `group:ui` | browser, canvas | +| `group:automation` | cron, gateway | | `group:messaging` | message | | `group:nodes` | nodes | | `group:agents` | agents_list | -| `group:media` | image، image_generate، music_generate، video_generate، tts | -| `group:openclaw` | همه ابزارهای داخلی OpenClaw (ابزارهای Plugin را شامل نمی‌شود) | +| `group:media` | image, image_generate, music_generate, video_generate, tts | +| `group:openclaw` | همهٔ ابزارهای داخلی OpenClaw (به‌جز ابزارهای Plugin) | -`sessions_history` نمای یادآوری محدود و فیلترشده از نظر ایمنی را برمی‌گرداند. این نما -برچسب‌های تفکر، ساختار کمکی ``، بارهای XML فراخوانی ابزار به‌صورت متن ساده +`sessions_history` یک نمای یادآوری محدود و فیلترشده از نظر ایمنی برمی‌گرداند. این نما +برچسب‌های thinking، اسکفلدینگ ``، payloadهای XML فراخوانی ابزار به‌صورت متن ساده (از جمله `...`، `...`، `...`، -`...` و بلوک‌های کوتاه‌شده فراخوانی ابزار)، -ساختار کمکی تنزل‌یافته فراخوانی ابزار، توکن‌های کنترلی مدل ASCII/تمام‌عرضِ نشت‌کرده، -و XML ناقص فراخوانی ابزار MiniMax را از متن دستیار حذف می‌کند، سپس -پوشاندن/کوتاه‌سازی و جای‌نگهدارهای احتمالی برای ردیف‌های بیش‌ازحد بزرگ را اعمال می‌کند، به‌جای آنکه -مثل تخلیه خام رونوشت عمل کند. +`...`، و بلوک‌های کوتاه‌شدهٔ فراخوانی ابزار)، +اسکفلدینگ تنزل‌یافتهٔ فراخوانی ابزار، توکن‌های کنترل مدل ASCII/تمام‌عرض افشاشده، +و XML نادرست فراخوانی ابزار MiniMax را از متن دستیار حذف می‌کند، سپس +به‌جای اینکه مانند یک دامپ خام رونوشت عمل کند، ویرایش محرمانه/کوتاه‌سازی و جایگزین‌های احتمالی برای ردیف‌های بیش‌ازحد بزرگ را اعمال می‌کند. -### محدودیت‌های ویژه ارائه‌دهنده +### محدودیت‌های ویژهٔ ارائه‌دهنده -از `tools.byProvider` برای محدود کردن ابزارها برای ارائه‌دهندگان مشخص استفاده کنید، بدون اینکه +از `tools.byProvider` برای محدود کردن ابزارها برای ارائه‌دهنده‌های مشخص استفاده کنید، بدون اینکه پیش‌فرض‌های سراسری را تغییر دهید: ```json5 diff --git a/docs/fa/tools/subagents.md b/docs/fa/tools/subagents.md index 008268b14..f7700337d 100644 --- a/docs/fa/tools/subagents.md +++ b/docs/fa/tools/subagents.md @@ -1,44 +1,46 @@ --- read_when: - - می‌خواهید کار در پس‌زمینه یا به‌صورت موازی از طریق عامل انجام شود - - شما در حال تغییر سیاست ابزار `sessions_spawn` یا ابزار عامل فرعی هستید - - شما در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیرعامل وابسته به رشته هستید + - می‌خواهید کار پس‌زمینه یا موازی را از طریق عامل انجام دهید + - شما در حال تغییر سیاست ابزار sessions_spawn یا زیرعامل هستید + - شما در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیرعاملِ وابسته به رشته هستید sidebarTitle: Sub-agents -summary: اجراهای ایزولهٔ عامل در پس‌زمینه را ایجاد کنید که نتایج را به گفت‌وگوی درخواست‌دهنده اعلام می‌کنند. -title: زیرعامل‌ها +summary: اجراهای جداافتادهٔ عامل را در پس‌زمینه راه‌اندازی کنید که نتایج را به گفت‌وگوی درخواست‌دهنده اعلام می‌کنند +title: عامل‌های فرعی x-i18n: - generated_at: "2026-04-29T23:46:31Z" + generated_at: "2026-04-30T16:32:06Z" model: gpt-5.5 provider: openai - source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e + source_hash: c7c46d2c6d9ddac23653dcbfaf20df0ff5be9619035a1b115a3b49fd48fd8280 source_path: tools/subagents.md workflow: 16 --- -Sub-agentها اجرای agent پس‌زمینه هستند که از یک اجرای agent موجود ایجاد می‌شوند. -آن‌ها در جلسهٔ خودشان (`agent::subagent:`) اجرا می‌شوند و، -پس از پایان، نتیجهٔ خود را به کانال گفت‌وگوی درخواست‌کننده **اعلام** می‌کنند. -هر اجرای sub-agent به‌عنوان یک [وظیفهٔ پس‌زمینه](/fa/automation/tasks) ردیابی می‌شود. +عامل‌های فرعی اجراهای پس‌زمینهٔ عامل هستند که از یک اجرای عامل موجود ایجاد می‌شوند. +آن‌ها در نشست خودشان (`agent::subagent:`) اجرا می‌شوند و، +پس از پایان، نتیجهٔ خود را به کانال گفت‌وگوی درخواست‌دهنده **اعلام** می‌کنند. +هر اجرای عامل فرعی به‌عنوان یک +[وظیفهٔ پس‌زمینه](/fa/automation/tasks) ردیابی می‌شود. اهداف اصلی: - موازی‌سازی کارهای «پژوهش / وظیفهٔ طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی. -- جدا نگه داشتن sub-agentها به‌صورت پیش‌فرض (جداسازی جلسه + sandboxing اختیاری). -- سخت کردن سوءاستفاده از سطح ابزار: sub-agentها به‌صورت پیش‌فرض ابزارهای جلسه را دریافت نمی‌کنند. -- پشتیبانی از عمق تو‌در‌توی قابل پیکربندی برای الگوهای هماهنگ‌کننده. +- ایزوله نگه داشتن عامل‌های فرعی به‌صورت پیش‌فرض (جداسازی نشست + سندباکس اختیاری). +- سخت کردن سوءاستفاده از سطح ابزار: عامل‌های فرعی به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند. +- پشتیبانی از عمق تودرتوی قابل پیکربندی برای الگوهای هماهنگ‌کننده. -**یادداشت هزینه:** هر sub-agent به‌صورت پیش‌فرض context و مصرف توکن خودش را دارد. -برای وظایف سنگین یا تکراری، مدل ارزان‌تری برای sub-agentها تنظیم کنید -و agent اصلی خود را روی مدل باکیفیت‌تری نگه دارید. از طریق -`agents.defaults.subagents.model` یا بازنویسی‌های مخصوص هر agent پیکربندی کنید. -وقتی یک فرزند واقعاً به transcript فعلی درخواست‌کننده نیاز دارد، agent می‌تواند -برای همان spawn درخواست `context: "fork"` کند. +**نکتهٔ هزینه:** هر عامل فرعی به‌صورت پیش‌فرض زمینه و مصرف توکن +خودش را دارد. برای وظایف سنگین یا تکراری، یک مدل ارزان‌تر برای عامل‌های فرعی +تنظیم کنید و عامل اصلی خود را روی مدلی با کیفیت بالاتر نگه دارید. از طریق +`agents.defaults.subagents.model` یا بازنویسی‌های هر عامل پیکربندی کنید. وقتی یک فرزند +واقعاً به رونوشت فعلی درخواست‌دهنده نیاز دارد، عامل می‌تواند در همان ایجاد +`context: "fork"` را درخواست کند. ## دستور اسلش -از `/subagents` برای بررسی یا کنترل اجراهای sub-agent برای **جلسهٔ فعلی** استفاده کنید: +از `/subagents` برای بازرسی یا کنترل اجراهای عامل فرعی برای **نشست فعلی** +استفاده کنید: ```text /subagents list @@ -50,15 +52,15 @@ Sub-agentها اجرای agent پس‌زمینه هستند که از یک اج /subagents spawn [--model ] [--thinking ] ``` -`/subagents info` فرادادهٔ اجرا را نشان می‌دهد (وضعیت، زمان‌مهرها، شناسهٔ جلسه، -مسیر transcript، پاک‌سازی). از `sessions_history` برای نمای یادآوری محدود و -فیلترشده از نظر ایمنی استفاده کنید؛ وقتی به transcript خام و کامل نیاز دارید، -مسیر transcript را روی دیسک بررسی کنید. +`/subagents info` فرادادهٔ اجرا را نشان می‌دهد (وضعیت، زمان‌ها، شناسهٔ نشست، +مسیر رونوشت، پاک‌سازی). برای نمای یادآوری محدود و فیلترشده از نظر ایمنی، +از `sessions_history` استفاده کنید؛ وقتی به رونوشت کامل خام نیاز دارید، +مسیر رونوشت روی دیسک را بررسی کنید. -### کنترل‌های اتصال thread +### کنترل‌های اتصال رشته -این دستورها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند. -پایین‌تر [کانال‌های پشتیبان thread](#thread-supporting-channels) را ببینید. +این دستورها روی کانال‌هایی کار می‌کنند که از اتصال‌های پایدار رشته پشتیبانی می‌کنند. +در پایین، [کانال‌های پشتیبان رشته](#thread-supporting-channels) را ببینید. ```text /focus @@ -68,144 +70,145 @@ Sub-agentها اجرای agent پس‌زمینه هستند که از یک اج /session max-age ``` -### رفتار spawn +### رفتار ایجاد -`/subagents spawn` یک sub-agent پس‌زمینه را به‌عنوان دستور کاربر شروع می‌کند (نه یک -relay داخلی) و هنگام پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به گفت‌وگوی -درخواست‌کننده می‌فرستد. +`/subagents spawn` یک عامل فرعی پس‌زمینه را به‌عنوان دستور کاربر (نه یک +رلهٔ داخلی) شروع می‌کند و وقتی اجرا پایان می‌یابد، یک به‌روزرسانی نهایی +تکمیل را به گفت‌وگوی درخواست‌دهنده می‌فرستد. - - - دستور spawn غیرمسدودکننده است؛ بلافاصله یک شناسهٔ اجرا برمی‌گرداند. - - هنگام تکمیل، sub-agent یک پیام خلاصه/نتیجه را به کانال گفت‌وگوی درخواست‌کننده اعلام می‌کند. - - تکمیل مبتنی بر push است. پس از spawn شدن، فقط برای انتظار پایان آن، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه poll نکنید؛ وضعیت را فقط هنگام نیاز برای اشکال‌زدایی یا مداخله بررسی کنید. - - هنگام تکمیل، OpenClaw با بهترین تلاش tabها/فرایندهای مرورگرِ بازشده توسط آن جلسهٔ sub-agent را پیش از ادامهٔ جریان پاک‌سازی اعلام می‌بندد. + + - دستور ایجاد غیرمسدودکننده است؛ بلافاصله یک شناسهٔ اجرا برمی‌گرداند. + - پس از تکمیل، عامل فرعی پیام خلاصه/نتیجه را به کانال گفت‌وگوی درخواست‌دهنده اعلام می‌کند. + - تکمیل مبتنی بر ارسال است. پس از ایجاد، فقط برای انتظار پایان آن، `/subagents list`، `sessions_list` یا `sessions_history` را در حلقه polling نکنید؛ وضعیت را فقط در صورت نیاز برای اشکال‌زدایی یا مداخله بررسی کنید. + - پس از تکمیل، OpenClaw به‌صورت بهترین تلاش، تب‌ها/فرآیندهای مرورگر ردیابی‌شده‌ای را که آن نشست عامل فرعی باز کرده است، پیش از ادامهٔ جریان پاک‌سازی اعلام می‌بندد. - - - OpenClaw ابتدا تحویل مستقیم `agent` را با یک کلید idempotency پایدار امتحان می‌کند. - - اگر تحویل مستقیم شکست بخورد، به مسیریابی صف fallback می‌کند. - - اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با backoff نمایی کوتاه دوباره تلاش می‌شود و سپس در نهایت رها می‌شود. - - تحویل تکمیل، مسیر حل‌شدهٔ درخواست‌کننده را نگه می‌دارد: مسیرهای تکمیل متصل به thread یا متصل به conversation وقتی در دسترس باشند برنده می‌شوند؛ اگر منشأ تکمیل فقط یک کانال ارائه کند، OpenClaw هدف/account جاافتاده را از مسیر حل‌شدهٔ جلسهٔ درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند. + + - OpenClaw ابتدا تحویل مستقیم `agent` را با یک کلید پایداری عملیات پایدار امتحان می‌کند. + - اگر تحویل مستقیم شکست بخورد، به مسیریابی صف بازمی‌گردد. + - اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با یک backoff نمایی کوتاه پیش از انصراف نهایی دوباره تلاش می‌شود. + - تحویل تکمیل مسیر حل‌شدهٔ درخواست‌دهنده را حفظ می‌کند: مسیرهای تکمیل متصل به رشته یا متصل به مکالمه، وقتی در دسترس باشند، اولویت دارند؛ اگر مبدأ تکمیل فقط یک کانال ارائه کند، OpenClaw مقصد/حساب مفقود را از مسیر حل‌شدهٔ نشست درخواست‌دهنده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند. - - handoff تکمیل به جلسهٔ درخواست‌کننده context داخلی تولیدشده در زمان اجرا است - (نه متن نوشته‌شده توسط کاربر) و شامل این موارد می‌شود: + + واگذاری تکمیل به نشست درخواست‌دهنده، زمینهٔ داخلی تولیدشده در زمان اجرا + است (نه متن نوشته‌شده توسط کاربر) و شامل این موارد است: - - `Result` — تازه‌ترین متن پاسخ قابل مشاهدهٔ `assistant`، وگرنه تازه‌ترین متن پاک‌سازی‌شدهٔ tool/toolResult. اجراهای نهاییِ ناموفق از متن پاسخ ضبط‌شده دوباره استفاده نمی‌کنند. + - `Result` — تازه‌ترین متن پاسخ قابل مشاهدهٔ `assistant`، وگرنه تازه‌ترین متن پاک‌سازی‌شدهٔ ابزار/toolResult. اجراهای شکست‌خوردهٔ پایانی از متن پاسخ ثبت‌شده دوباره استفاده نمی‌کنند. - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`. - - آمار فشردهٔ runtime/token. - - یک دستور تحویل که به agent درخواست‌کننده می‌گوید آن را با صدای عادی assistant بازنویسی کند (نه اینکه فرادادهٔ داخلی خام را forward کند). + - آمار فشردهٔ زمان اجرا/توکن. + - یک دستور تحویل که به عامل درخواست‌دهنده می‌گوید با صدای معمول دستیار بازنویسی کند (نه اینکه فرادادهٔ داخلی خام را فوروارد کند). - + - `--model` و `--thinking` پیش‌فرض‌ها را برای همان اجرای مشخص بازنویسی می‌کنند. - - از `info`/`log` برای بررسی جزئیات و خروجی پس از تکمیل استفاده کنید. - - `/subagents spawn` حالت یک‌باره است (`mode: "run"`). برای جلسه‌های پایدار متصل به thread، از `sessions_spawn` با `thread: true` و `mode: "session"` استفاده کنید. - - برای جلسه‌های harness مربوط به ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن runtime را advertised می‌کند از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های agent-to-agent، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی plugin `codex` فعال است، کنترل chat/thread در Codex باید `/codex ...` را به ACP ترجیح دهد مگر اینکه کاربر صریحاً ACP/acpx بخواهد. - - OpenClaw تا زمانی که ACP فعال نشده باشد، درخواست‌کننده sandboxed نباشد، و یک plugin backend مانند `acpx` بارگذاری نشده باشد، `runtime: "acp"` را پنهان می‌کند. `runtime: "acp"` انتظار یک شناسهٔ harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای agentهای معمول پیکربندی OpenClaw از `agents_list`، از runtime پیش‌فرض sub-agent استفاده کنید. + - برای بررسی جزئیات و خروجی پس از تکمیل، از `info`/`log` استفاده کنید. + - `/subagents spawn` حالت یک‌باره است (`mode: "run"`). برای نشست‌های پایدار متصل به رشته، از `sessions_spawn` با `thread: true` و `mode: "session"` استفاده کنید. + - برای نشست‌های harness مربوط به ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن زمان اجرا را اعلام می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل‌به‌عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل گفت‌وگو/رشتهٔ Codex باید `/codex ...` را بر ACP ترجیح دهد، مگر اینکه کاربر صریحاً ACP/acpx را درخواست کند. + - OpenClaw تا وقتی ACP فعال نشده، درخواست‌دهنده سندباکس نشده، و یک Plugin بک‌اند مانند `acpx` بارگذاری نشده باشد، `runtime: "acp"` را پنهان می‌کند. `runtime: "acp"` انتظار یک شناسهٔ خارجی harness مربوط به ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای عامل‌های پیکربندی عادی OpenClaw از `agents_list`، از زمان اجرای پیش‌فرض عامل فرعی استفاده کنید. -## حالت‌های context +## حالت‌های زمینه -Sub-agentهای native جدا شروع می‌شوند مگر اینکه فراخواننده صریحاً درخواست fork کردن -transcript فعلی را بدهد. +عامل‌های فرعی بومی ایزوله شروع می‌شوند، مگر اینکه فراخوان صریحاً درخواست کند +رونوشت فعلی fork شود. -| حالت | چه زمانی از آن استفاده شود | رفتار | +| حالت | چه زمانی از آن استفاده کنید | رفتار | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان آن را در متن وظیفه brief کرد | یک transcript فرزند تمیز ایجاد می‌کند. این حالت پیش‌فرض است و مصرف توکن را پایین‌تر نگه می‌دارد. | -| `fork` | کاری که به گفت‌وگوی فعلی، نتایج ابزار قبلی، یا دستورهای ظریف موجود در transcript درخواست‌کننده وابسته است | transcript درخواست‌کننده را پیش از شروع فرزند به جلسهٔ فرزند branch می‌کند. | +| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان آن را در متن وظیفه خلاصه کرد | یک رونوشت فرزند پاک ایجاد می‌کند. این حالت پیش‌فرض است و مصرف توکن را پایین‌تر نگه می‌دارد. | +| `fork` | کاری که به مکالمهٔ فعلی، نتایج ابزار قبلی، یا دستورهای ظریفِ موجود در رونوشت درخواست‌دهنده وابسته است | رونوشت درخواست‌دهنده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. | -از `fork` کم‌استفاده کنید. این حالت برای delegation حساس به context است، نه -جایگزینی برای نوشتن prompt وظیفهٔ شفاف. +از `fork` با احتیاط استفاده کنید. این حالت برای واگذاری حساس به زمینه است، نه +جایگزینی برای نوشتن یک اعلان وظیفهٔ شفاف. ## ابزار: `sessions_spawn` -یک اجرای sub-agent را با `deliver: false` روی lane سراسری `subagent` شروع می‌کند، -سپس یک گام اعلام اجرا می‌کند و پاسخ اعلام را به کانال گفت‌وگوی درخواست‌کننده -post می‌کند. +یک اجرای عامل فرعی را با `deliver: false` روی مسیر سراسری `subagent` شروع می‌کند، +سپس یک مرحلهٔ اعلام را اجرا می‌کند و پاسخ اعلام را در کانال گفت‌وگوی درخواست‌دهنده +ارسال می‌کند. -دسترسی به سیاست ابزار مؤثر فراخواننده بستگی دارد. پروفایل‌های `coding` و -`full` به‌صورت پیش‌فرض `sessions_spawn` را expose می‌کنند. پروفایل `messaging` -این کار را نمی‌کند؛ برای agentهایی که باید کار را delegate کنند +در دسترس بودن به سیاست ابزار مؤثر فراخوان بستگی دارد. پروفایل‌های `coding` و +`full` به‌صورت پیش‌فرض `sessions_spawn` را در معرض دسترس قرار می‌دهند. پروفایل `messaging` +این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند، `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` را اضافه کنید یا از `tools.profile: "coding"` استفاده کنید. -سیاست‌های allow/deny مربوط به channel/group، provider، sandbox و هر agent -همچنان می‌توانند پس از مرحلهٔ profile ابزار را حذف کنند. برای تأیید فهرست -ابزار مؤثر، از همان جلسه از `/tools` استفاده کنید. +سیاست‌های اجازه/رد در سطح کانال/گروه، provider، سندباکس، و هر عامل همچنان می‌توانند +ابزار را پس از مرحلهٔ پروفایل حذف کنند. از همان نشست، برای تأیید فهرست ابزار مؤثر +از `/tools` استفاده کنید. **پیش‌فرض‌ها:** -- **مدل:** از فراخواننده ارث می‌برد مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` مخصوص هر agent) را تنظیم کنید؛ `sessions_spawn.model` صریح همچنان برنده است. -- **Thinking:** از فراخواننده ارث می‌برد مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` مخصوص هر agent) را تنظیم کنید؛ `sessions_spawn.thinking` صریح همچنان برنده است. -- **Timeout اجرا:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw وقتی تنظیم شده باشد از `agents.defaults.subagents.runTimeoutSeconds` استفاده می‌کند؛ وگرنه به `0` (بدون timeout) fallback می‌کند. +- **مدل:** از فراخوان ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.model` همچنان اولویت دارد. +- **تفکر:** از فراخوان ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.thinking` همچنان اولویت دارد. +- **مهلت اجرای کار:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw وقتی `agents.defaults.subagents.runTimeoutSeconds` تنظیم شده باشد از آن استفاده می‌کند؛ در غیر این صورت به `0` (بدون مهلت) بازمی‌گردد. ### پارامترهای ابزار - توضیح وظیفه برای sub-agent. + توضیح وظیفه برای عامل فرعی. - برچسب خوانای اختیاری برای انسان. + برچسب اختیاری قابل خواندن برای انسان. - وقتی `subagents.allowAgents` اجازه دهد، زیر یک شناسهٔ agent دیگر spawn کنید. + وقتی `subagents.allowAgents` اجازه دهد، زیر شناسهٔ عامل دیگری ایجاد کنید. `acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صریحاً درخواست شده) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است. - فقط ACP. وقتی `runtime: "acp"` باشد، یک جلسهٔ harness موجود ACP را resume می‌کند؛ برای spawnهای native sub-agent نادیده گرفته می‌شود. + فقط ACP. وقتی `runtime: "acp"` باشد، یک نشست harness موجود ACP را از سر می‌گیرد؛ برای ایجاد عامل فرعی بومی نادیده گرفته می‌شود. - فقط ACP. وقتی `runtime: "acp"` باشد، خروجی اجرای ACP را به جلسهٔ والد stream می‌کند؛ برای spawnهای native sub-agent حذف کنید. + فقط ACP. وقتی `runtime: "acp"` باشد، خروجی اجرای ACP را به نشست والد استریم می‌کند؛ برای ایجاد عامل فرعی بومی حذف کنید. - مدل sub-agent را بازنویسی کنید. مقادیر نامعتبر رد می‌شوند و sub-agent با مدل پیش‌فرض اجرا می‌شود، همراه با هشداری در نتیجهٔ ابزار. + مدل عامل فرعی را بازنویسی کنید. مقادیر نامعتبر رد می‌شوند و عامل فرعی با مدل پیش‌فرض اجرا می‌شود و در نتیجهٔ ابزار هشدار داده می‌شود. - سطح thinking را برای اجرای sub-agent بازنویسی کنید. + سطح تفکر را برای اجرای عامل فرعی بازنویسی کنید. - وقتی تنظیم شده باشد، پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای sub-agent پس از N ثانیه abort می‌شود. + وقتی تنظیم شده باشد، پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای عامل فرعی پس از N ثانیه لغو می‌شود. - وقتی `true` باشد، اتصال thread کانال را برای این جلسهٔ sub-agent درخواست می‌کند. + وقتی `true` باشد، اتصال رشتهٔ کانال را برای این نشست عامل فرعی درخواست می‌کند. اگر `thread: true` باشد و `mode` حذف شده باشد، پیش‌فرض به `session` تبدیل می‌شود. `mode: "session"` به `thread: true` نیاز دارد. - `"delete"` بلافاصله پس از اعلام archive می‌کند (همچنان transcript را از طریق rename نگه می‌دارد). + `"delete"` بلافاصله پس از اعلام آرشیو می‌کند (همچنان رونوشت را از طریق تغییر نام نگه می‌دارد). - `require` spawn را رد می‌کند مگر اینکه runtime فرزند هدف sandboxed باشد. + `require` ایجاد را رد می‌کند، مگر اینکه زمان اجرای فرزند هدف سندباکس شده باشد. - `fork` transcript فعلی درخواست‌کننده را به جلسهٔ فرزند branch می‌کند. فقط sub-agentهای native. فقط وقتی از `fork` استفاده کنید که فرزند به transcript فعلی نیاز دارد. + `fork` رونوشت فعلی درخواست‌دهنده را به نشست فرزند منشعب می‌کند. فقط عامل‌های فرعی بومی. فقط وقتی از `fork` استفاده کنید که فرزند به رونوشت فعلی نیاز دارد. `sessions_spawn` پارامترهای تحویل کانال (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`) را نمی‌پذیرد. برای تحویل، از -`message`/`sessions_send` از اجرای spawnشده استفاده کنید. +`message`/`sessions_send` از اجرای ایجادشده استفاده کنید. -## جلسه‌های متصل به thread +## نشست‌های متصل به رشته -وقتی اتصال‌های thread برای یک کانال فعال باشند، یک sub-agent می‌تواند به یک thread -متصل بماند تا پیام‌های follow-up کاربر در همان thread همچنان به همان جلسهٔ -sub-agent route شوند. +وقتی اتصال‌های رشته برای یک کانال فعال باشند، یک عامل فرعی می‌تواند به یک رشته +متصل بماند تا پیام‌های بعدی کاربر در آن رشته همچنان به همان نشست عامل فرعی +مسیریابی شوند. -### کانال‌های پشتیبان thread +### کانال‌های پشتیبان رشته -**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. از جلسه‌های subagent -پایدار متصل به thread (`sessions_spawn` با `thread: true`)، کنترل‌های دستی thread -(`/focus`، `/unfocus`، `/agents`، `/session idle`، `/session max-age`) و کلیدهای -adapter یعنی `channels.discord.threadBindings.enabled`, +**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از +نشست‌های عامل فرعی پایدار متصل به رشته (`sessions_spawn` با +`thread: true`)، کنترل‌های دستی رشته (`/focus`، `/unfocus`، `/agents`, +`/session idle`، `/session max-age`) و کلیدهای adapter +`channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` و `channels.discord.threadBindings.spawnSubagentSessions` پشتیبانی می‌کند. @@ -213,21 +216,21 @@ adapter یعنی `channels.discord.threadBindings.enabled`, ### جریان سریع - - `sessions_spawn` با `thread: true` (و به‌صورت اختیاری `mode: "session"`). + + `sessions_spawn` با `thread: true` (و در صورت نیاز `mode: "session"`). - - OpenClaw یک thread را به آن هدف جلسه در کانال فعال ایجاد یا bind می‌کند. + + OpenClaw یک رشته را به هدف آن نشست در کانال فعال ایجاد یا متصل می‌کند. - - پاسخ‌ها و پیام‌های follow-up در آن thread به جلسهٔ متصل‌شده route می‌شوند. + + پاسخ‌ها و پیام‌های پیگیری در آن رشته به نشست متصل مسیریابی می‌شوند. - - از `/session idle` برای بررسی/به‌روزرسانی auto-unfocus در اثر inactivity و + + از `/session idle` برای بررسی/به‌روزرسانی unfocus خودکار در اثر عدم فعالیت و از `/session max-age` برای کنترل سقف سخت استفاده کنید. - - از `/unfocus` برای detach دستی استفاده کنید. + + از `/unfocus` برای جداسازی دستی استفاده کنید. @@ -235,57 +238,56 @@ adapter یعنی `channels.discord.threadBindings.enabled`, | فرمان | اثر | | ------------------ | --------------------------------------------------------------------- | -| `/focus ` | رشتهٔ فعلی را (یا یک رشته ایجاد می‌کند و آن را) به هدف یک زیرعامل/نشست متصل می‌کند | -| `/unfocus` | اتصال رشتهٔ متصل فعلی را حذف می‌کند | -| `/agents` | اجراهای فعال و وضعیت اتصال را فهرست می‌کند (`thread:` یا `unbound`) | -| `/session idle` | عدم‌تمرکز خودکار در حالت بی‌کاری را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ متمرکز) | -| `/session max-age` | سقف سخت را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ متمرکز) | +| `/focus ` | رشتهٔ فعلی را (یا یک رشتهٔ جدید بساز) به هدف یک زیرعامل/نشست متصل کن | +| `/unfocus` | اتصال رشتهٔ متصل فعلی را حذف کن | +| `/agents` | اجراهای فعال و وضعیت اتصال را فهرست کن (`thread:` یا `unbound`) | +| `/session idle` | بی‌تمرکزسازی خودکار در حالت بی‌کاری را بررسی/به‌روزرسانی کن (فقط رشته‌های متصلِ در تمرکز) | +| `/session max-age` | سقف سخت را بررسی/به‌روزرسانی کن (فقط رشته‌های متصلِ در تمرکز) | -### کلیدهای پیکربندی +### سوییچ‌های پیکربندی - **پیش‌فرض سراسری:** `session.threadBindings.enabled`، `session.threadBindings.idleHours`، `session.threadBindings.maxAgeHours`. - **بازنویسی کانال و کلیدهای اتصال خودکار هنگام ایجاد** مختص آداپتور هستند. بخش [کانال‌های پشتیبان رشته](#thread-supporting-channels) را در بالا ببینید. برای جزئیات فعلی آداپتور، [مرجع پیکربندی](/fa/gateway/configuration-reference) و -[دستورهای اسلش](/fa/tools/slash-commands) را ببینید. +[فرمان‌های اسلش](/fa/tools/slash-commands) را ببینید. ### فهرست مجاز - فهرستی از شناسه‌های عامل که می‌توان از طریق `agentId` صریح هدف گرفت (`["*"]` هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌کننده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌کننده بتواند خودش را با `agentId` ایجاد کند، شناسهٔ درخواست‌کننده را در فهرست بیاورید. + فهرست شناسه‌های عامل که می‌توانند از طریق `agentId` صریح هدف قرار بگیرند (`["*"]` هرکدام را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌کننده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌کننده خودش را با `agentId` ایجاد کند، شناسهٔ درخواست‌کننده را در فهرست قرار دهید. فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌کننده `subagents.allowAgents` خودش را تنظیم نکرده باشد استفاده می‌شود. - فراخوانی‌های `sessions_spawn` را که `agentId` را حذف کرده‌اند مسدود می‌کند (انتخاب صریح نمایه را اجباری می‌کند). بازنویسی برای هر عامل: `agents.list[].subagents.requireAgentId`. + فراخوانی‌های `sessions_spawn` را که `agentId` را حذف می‌کنند مسدود کن (انتخاب صریح پروفایل را اجباری می‌کند). بازنویسی برای هر عامل: `agents.list[].subagents.requireAgentId`. -اگر نشست درخواست‌کننده در sandbox باشد، `sessions_spawn` هدف‌هایی را که -بدون sandbox اجرا می‌شوند رد می‌کند. +اگر نشست درخواست‌کننده سندباکس شده باشد، `sessions_spawn` هدف‌هایی را +که بدون سندباکس اجرا می‌شوند رد می‌کند. ### کشف -از `agents_list` استفاده کنید تا ببینید کدام شناسه‌های عامل در حال حاضر برای -`sessions_spawn` مجاز هستند. پاسخ شامل مدل مؤثر هر عامل فهرست‌شده و فرادادهٔ -زمان اجرای جاسازی‌شده است تا فراخوان‌ها بتوانند PI، سرور برنامهٔ Codex -و دیگر زمان‌های اجرای بومی پیکربندی‌شده را از هم تشخیص دهند. +برای دیدن اینکه کدام شناسه‌های عامل در حال حاضر برای `sessions_spawn` +مجاز هستند، از `agents_list` استفاده کنید. پاسخ شامل مدل مؤثر هر عامل +فهرست‌شده و فرادادهٔ زمان‌اجرای تعبیه‌شده است تا فراخواننده‌ها بتوانند Pi، +سرور برنامهٔ Codex، و زمان‌اجراهای بومی پیکربندی‌شدهٔ دیگر را از هم تشخیص دهند. -### آرشیو خودکار +### بایگانی خودکار -- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` (پیش‌فرض `60`) به‌طور خودکار آرشیو می‌شوند. -- آرشیو از `sessions.delete` استفاده می‌کند و transcript را به `*.deleted.` تغییر نام می‌دهد (در همان پوشه). -- `cleanup: "delete"` بلافاصله پس از اعلام، آرشیو می‌کند (همچنان transcript را از طریق تغییر نام نگه می‌دارد). -- آرشیو خودکار به‌صورت بهترین تلاش انجام می‌شود؛ اگر Gateway بازراه‌اندازی شود، تایمرهای معلق از دست می‌روند. -- `runTimeoutSeconds` آرشیو خودکار انجام نمی‌دهد؛ فقط اجرا را متوقف می‌کند. نشست تا زمان آرشیو خودکار باقی می‌ماند. -- آرشیو خودکار به‌طور یکسان روی نشست‌های عمق ۱ و عمق ۲ اعمال می‌شود. -- پاک‌سازی مرورگر از پاک‌سازی آرشیو جداست: تب‌ها/فرآیندهای مرورگرِ ردیابی‌شده، وقتی اجرا تمام می‌شود، به‌صورت بهترین تلاش بسته می‌شوند، حتی اگر رکورد transcript/نشست نگه داشته شود. +- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌صورت خودکار بایگانی می‌شوند (پیش‌فرض `60`). +- بایگانی از `sessions.delete` استفاده می‌کند و رونویس را به `*.deleted.` تغییر نام می‌دهد (همان پوشه). +- `cleanup: "delete"` بلافاصله پس از اعلام بایگانی می‌کند (رونویس را همچنان با تغییر نام نگه می‌دارد). +- بایگانی خودکار بر اساس بهترین تلاش است؛ اگر Gateway دوباره راه‌اندازی شود، تایمرهای معلق از دست می‌روند. +- `runTimeoutSeconds` بایگانی خودکار انجام نمی‌دهد؛ فقط اجرا را متوقف می‌کند. نشست تا بایگانی خودکار باقی می‌ماند. +- بایگانی خودکار به‌طور یکسان برای نشست‌های عمق ۱ و عمق ۲ اعمال می‌شود. +- پاک‌سازی مرورگر از پاک‌سازی بایگانی جداست: زبانه‌ها/فرایندهای مرورگرِ ردیابی‌شده پس از پایان اجرا بر اساس بهترین تلاش بسته می‌شوند، حتی اگر رکورد رونویس/نشست نگه داشته شود. -## زیرعامل‌های تو در تو +## زیرعامل‌های تودرتو -به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند -(`maxSpawnDepth: 1`). برای فعال کردن یک سطح از تودرتویی، `maxSpawnDepth: 2` -را تنظیم کنید — **الگوی هماهنگ‌کننده**: عامل اصلی → زیرعامل هماهنگ‌کننده → +به‌صورت پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند +(`maxSpawnDepth: 1`). برای فعال کردن یک سطح تودرتویی، `maxSpawnDepth: 2` را تنظیم کنید — **الگوی هماهنگ‌کننده**: اصلی → زیرعامل هماهنگ‌کننده → زیر-زیرعامل‌های کارگر. ```json5 @@ -313,58 +315,58 @@ adapter یعنی `channels.discord.threadBindings.enabled`, ### زنجیرهٔ اعلام -نتیجه‌ها در زنجیره به بالا جریان پیدا می‌کنند: +نتایج در زنجیره به بالا بازمی‌گردند: 1. کارگر عمق ۲ تمام می‌شود → به والدش اعلام می‌کند (هماهنگ‌کنندهٔ عمق ۱). -2. هماهنگ‌کنندهٔ عمق ۱ اعلام را دریافت می‌کند، نتیجه‌ها را ترکیب می‌کند، تمام می‌شود → به عامل اصلی اعلام می‌کند. +2. هماهنگ‌کنندهٔ عمق ۱ اعلام را دریافت می‌کند، نتایج را ترکیب می‌کند، تمام می‌شود → به اصلی اعلام می‌کند. 3. عامل اصلی اعلام را دریافت می‌کند و به کاربر تحویل می‌دهد. هر سطح فقط اعلام‌های فرزندان مستقیم خودش را می‌بیند. -**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی -دور `sessions_list`، `sessions_history`، `/subagents list` یا دستورهای -خواب `exec`، منتظر رویدادهای تکمیل بمانید. -`sessions_list` و `/subagents list` رابطه‌های نشست فرزند را -متمرکز بر کار زنده نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته -برای یک بازهٔ کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزند کهنه و فقط موجود در ذخیره‌گاه -پس از پنجرهٔ تازگی‌شان نادیده گرفته می‌شوند. این کار جلوی این را می‌گیرد که فرادادهٔ قدیمی -`spawnedBy` / `parentSessionKey` پس از بازراه‌اندازی، فرزندان شبحی را دوباره زنده کند. -اگر رویداد تکمیل فرزند پس از این برسد که پاسخ نهایی را فرستاده‌اید، پیگیری درست همان توکن -بی‌صدای دقیق `NO_REPLY` / `no_reply` است. +**راهنمای عملیاتی:** کار فرزند را یک بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی پیرامون `sessions_list`، +`sessions_history`، `/subagents list`، یا فرمان‌های خواب `exec`، منتظر رویدادهای تکمیل بمانید. +`sessions_list` و `/subagents list` روابط نشست فرزند را +روی کار زنده متمرکز نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته +برای یک بازهٔ کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزندِ فقط-ذخیرهٔ کهنه +پس از پنجرهٔ تازگی‌شان نادیده گرفته می‌شوند. این کار مانع می‌شود فرادادهٔ قدیمی `spawnedBy` / +`parentSessionKey` پس از راه‌اندازی دوباره، فرزندان شبح‌گونه را زنده کند. +اگر رویداد تکمیل فرزند پس از اینکه پاسخ نهایی را فرستادید برسد، پیگیری درست همان توکن خاموش دقیق +`NO_REPLY` / `no_reply` است. -### سیاست ابزار بر اساس عمق +### خط‌مشی ابزار بر اساس عمق - نقش و دامنهٔ کنترل هنگام ایجاد در فرادادهٔ نشست نوشته می‌شوند. این باعث می‌شود کلیدهای نشست تخت یا بازیابی‌شده به‌طور تصادفی دوباره امتیازهای هماهنگ‌کننده را به دست نیاورند. -- **عمق ۱ (هماهنگ‌کننده، وقتی `maxSpawnDepth >= 2`):** ابزارهای `sessions_spawn`، `subagents`، `sessions_list`، `sessions_history` را دریافت می‌کند تا بتواند فرزندانش را مدیریت کند. دیگر ابزارهای نشست/سیستم همچنان رد می‌شوند. -- **عمق ۱ (برگ، وقتی `maxSpawnDepth == 1`):** هیچ ابزار نشستی ندارد (رفتار پیش‌فرض فعلی). -- **عمق ۲ (کارگر برگ):** هیچ ابزار نشستی ندارد — `sessions_spawn` همیشه در عمق ۲ رد می‌شود. نمی‌تواند فرزندان بیشتری ایجاد کند. +- **عمق ۱ (هماهنگ‌کننده، وقتی `maxSpawnDepth >= 2`):** `sessions_spawn`، `subagents`، `sessions_list`، `sessions_history` را دریافت می‌کند تا بتواند فرزندانش را مدیریت کند. ابزارهای دیگر نشست/سیستم همچنان رد می‌شوند. +- **عمق ۱ (برگ، وقتی `maxSpawnDepth == 1`):** بدون ابزار نشست (رفتار پیش‌فرض فعلی). +- **عمق ۲ (کارگر برگ):** بدون ابزار نشست — `sessions_spawn` همیشه در عمق ۲ رد می‌شود. نمی‌تواند فرزند بیشتری ایجاد کند. ### محدودیت ایجاد برای هر عامل هر نشست عامل (در هر عمقی) می‌تواند هم‌زمان حداکثر `maxChildrenPerAgent` -(پیش‌فرض `5`) فرزند فعال داشته باشد. این کار از گسترش مهارنشده از یک هماهنگ‌کنندهٔ واحد جلوگیری می‌کند. +(پیش‌فرض `5`) فرزند فعال داشته باشد. این از گسترش بی‌مهار +از یک هماهنگ‌کنندهٔ واحد جلوگیری می‌کند. ### توقف آبشاری -متوقف کردن یک هماهنگ‌کنندهٔ عمق ۱ به‌طور خودکار همهٔ فرزندان عمق ۲ آن را +توقف یک هماهنگ‌کنندهٔ عمق ۱ به‌طور خودکار همهٔ فرزندان عمق ۲ آن را متوقف می‌کند: -- `/stop` در گفتگوی اصلی همهٔ عامل‌های عمق ۱ را متوقف می‌کند و این توقف را به فرزندان عمق ۲ آن‌ها آبشاری می‌کند. -- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و این توقف را به فرزندانش آبشاری می‌کند. -- `/subagents kill all` همهٔ زیرعامل‌های درخواست‌کننده را متوقف می‌کند و توقف را آبشاری می‌کند. +- `/stop` در گفت‌وگوی اصلی همهٔ عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها سرایت می‌کند. +- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و به فرزندانش سرایت می‌کند. +- `/subagents kill all` همهٔ زیرعامل‌های درخواست‌کننده را متوقف می‌کند و سرایت می‌کند. ## احراز هویت -احراز هویت زیرعامل بر اساس **شناسهٔ عامل** تعیین می‌شود، نه بر اساس نوع نشست: +احراز هویت زیرعامل بر اساس **شناسهٔ عامل** حل می‌شود، نه نوع نشست: - کلید نشست زیرعامل `agent::subagent:` است. -- ذخیره‌گاه احراز هویت از `agentDir` آن عامل بارگذاری می‌شود. -- نمایه‌های احراز هویت عامل اصلی به‌عنوان **fallback** ادغام می‌شوند؛ در تعارض‌ها، نمایه‌های عامل بر نمایه‌های اصلی مقدم‌اند. +- ذخیره‌گاه احراز هویت از `agentDir` همان عامل بارگذاری می‌شود. +- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **پشتیبان** ادغام می‌شوند؛ پروفایل‌های عامل در تعارض‌ها پروفایل‌های اصلی را بازنویسی می‌کنند. -این ادغام افزایشی است، بنابراین نمایه‌های اصلی همیشه به‌عنوان -fallback در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود. +ادغام افزایشی است، بنابراین پروفایل‌های اصلی همیشه به‌عنوان +پشتیبان در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود. ## اعلام @@ -372,24 +374,24 @@ fallback در دسترس هستند. احراز هویت کاملاً ایزول - گام اعلام داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌کننده). - اگر زیرعامل دقیقاً `ANNOUNCE_SKIP` پاسخ دهد، چیزی ارسال نمی‌شود. -- اگر آخرین متن دستیار توکن بی‌صدای دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلام سرکوب می‌شود حتی اگر پیش‌تر پیشرفت قابل مشاهده‌ای وجود داشته باشد. +- اگر آخرین متن دستیار همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلام حتی اگر پیشرفت قابل مشاهدهٔ قبلی وجود داشته باشد سرکوب می‌شود. تحویل به عمق درخواست‌کننده بستگی دارد: - نشست‌های درخواست‌کنندهٔ سطح بالا از یک فراخوانی پیگیری `agent` با تحویل خارجی (`deliver=true`) استفاده می‌کنند. -- نشست‌های زیرعاملِ درخواست‌کنندهٔ تو در تو یک تزریق پیگیری داخلی (`deliver=false`) دریافت می‌کنند تا هماهنگ‌کننده بتواند نتیجه‌های فرزند را درون نشست ترکیب کند. -- اگر نشست زیرعاملِ درخواست‌کنندهٔ تو در تو از بین رفته باشد، OpenClaw در صورت موجود بودن به درخواست‌کنندهٔ آن نشست fallback می‌کند. +- نشست‌های زیرعاملِ درخواست‌کنندهٔ تودرتو تزریق پیگیری داخلی دریافت می‌کنند (`deliver=false`) تا هماهنگ‌کننده بتواند نتایج فرزند را درون نشست ترکیب کند. +- اگر نشست زیرعاملِ درخواست‌کنندهٔ تودرتو از بین رفته باشد، OpenClaw در صورت وجود به درخواست‌کنندهٔ آن نشست بازمی‌گردد. -برای نشست‌های درخواست‌کنندهٔ سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا -هر مسیر گفتگوی/رشتهٔ متصل و بازنویسی hook را resolve می‌کند، سپس -فیلدهای هدف کانالِ گمشده را از مسیر ذخیره‌شدهٔ نشست درخواست‌کننده پر می‌کند. -این کار تکمیل‌ها را در گفتگوی/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل -فقط کانال را مشخص می‌کند. +برای نشست‌های درخواست‌کنندهٔ سطح بالا، تحویل مستقیمِ حالت تکمیل ابتدا +هر مسیر گفت‌وگو/رشتهٔ متصل و بازنویسی hook را حل می‌کند، سپس +فیلدهای هدف کانالِ جاافتاده را از مسیر ذخیره‌شدهٔ نشست درخواست‌کننده پر می‌کند. +این کار تکمیل‌ها را روی گفت‌وگو/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل +فقط کانال را شناسایی می‌کند. -تجمیع تکمیل فرزند هنگام ساخت یافته‌های تکمیل تو در تو، به اجرای فعلی درخواست‌کننده -محدود می‌شود و مانع نشت خروجی‌های فرزند از اجراهای قبلی و کهنه -به اعلام فعلی می‌شود. پاسخ‌های اعلام، در صورت موجود بودن روی آداپتورهای کانال، -مسیر‌یابی رشته/موضوع را حفظ می‌کنند. +تجمیع تکمیل فرزند هنگام ساخت یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌کننده محدود می‌شود +و از نشت خروجی‌های فرزندِ اجرای قبلیِ کهنه +به اعلام فعلی جلوگیری می‌کند. پاسخ‌های اعلام، وقتی در آداپتورهای کانال در دسترس باشند، +مسیر رشته/موضوع را حفظ می‌کنند. ### زمینهٔ اعلام @@ -400,40 +402,42 @@ fallback در دسترس هستند. احراز هویت کاملاً ایزول | منبع | `subagent` یا `cron` | | شناسه‌های نشست | کلید/شناسهٔ نشست فرزند | | نوع | نوع اعلام + برچسب کار | -| وضعیت | برگرفته از نتیجهٔ زمان اجرا (`success`، `error`، `timeout`، یا `unknown`) — **نه** استنباط‌شده از متن مدل | -| محتوای نتیجه | آخرین متن قابل مشاهدهٔ دستیار، و در غیر این صورت آخرین متن ابزار/toolResult پاک‌سازی‌شده | -| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ داده شود و چه زمانی سکوت شود | +| وضعیت | مشتق‌شده از نتیجهٔ زمان‌اجرا (`success`، `error`، `timeout`، یا `unknown`) — **نه** استنباط‌شده از متن مدل | +| محتوای نتیجه | آخرین متن قابل مشاهدهٔ دستیار، در غیر این صورت آخرین متن پاک‌سازی‌شدهٔ ابزار/toolResult | +| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ داده شود و چه زمانی خاموش بماند | -اجراهای ناموفق پایانی، وضعیت شکست را بدون بازپخش متن پاسخ -گرفته‌شده گزارش می‌کنند. هنگام timeout، اگر فرزند فقط تا فراخوانی‌های ابزار پیش رفته باشد، اعلام -می‌تواند آن تاریخچه را به یک خلاصهٔ کوتاه از پیشرفت جزئی فروبکاهد، به‌جای آن‌که خروجی خام ابزار را بازپخش کند. +اجراهای شکست‌خوردهٔ پایانی، وضعیت شکست را بدون بازپخش متن پاسخ +ضبط‌شده گزارش می‌کنند. در زمان پایان مهلت، اگر فرزند فقط تا فراخوانی‌های ابزار پیش رفته باشد، اعلام +می‌تواند آن تاریخچه را به‌جای بازپخش خروجی خام ابزار، +در یک خلاصهٔ کوتاه از پیشرفت جزئی فشرده کند. ### خط آمار -payloadهای اعلام در پایان شامل یک خط آمار هستند (حتی وقتی پیچیده شده باشند): +بارهای اعلام در پایان شامل یک خط آمار هستند (حتی وقتی پیچیده شده باشند): -- زمان اجرا (مثلاً `runtime 5m12s`). +- زمان‌اجرا (مثلاً `runtime 5m12s`). - مصرف توکن (ورودی/خروجی/کل). - هزینهٔ تخمینی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`). -- `sessionKey`، `sessionId` و مسیر transcript تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` واکشی کند یا فایل را روی دیسک بررسی کند. +- `sessionKey`، `sessionId`، و مسیر رونویس تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` واکشی کند یا فایل روی دیسک را بررسی کند. -فرادادهٔ داخلی فقط برای هماهنگ‌سازی در نظر گرفته شده است؛ پاسخ‌های رو به کاربر +فرادادهٔ داخلی فقط برای هماهنگ‌سازی است؛ پاسخ‌های روبه‌کاربر باید با صدای معمول دستیار بازنویسی شوند. -### چرا `sessions_history` ترجیح داده می‌شود +### چرا `sessions_history` را ترجیح دهیم `sessions_history` مسیر هماهنگ‌سازی امن‌تری است: -- یادآوری دستیار ابتدا نرمال‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ داربست `` / `` حذف می‌شود؛ بلوک‌های payload XML فراخوانی ابزارِ متن ساده (``، ``، ``، ``) حذف می‌شوند، شامل payloadهای کوتاه‌شده‌ای که هرگز تمیز بسته نمی‌شوند؛ داربست تنزل‌یافتهٔ فراخوانی/نتیجهٔ ابزار و نشانگرهای زمینهٔ تاریخی حذف می‌شوند؛ توکن‌های کنترل مدلِ نشت‌کرده (`<|assistant|>`، دیگر ASCII `<|...|>`، تمام‌عرض `<｜...｜>`) حذف می‌شوند؛ XML بدشکل فراخوانی ابزار MiniMax حذف می‌شود. -- متن شبیه اعتبارنامه/توکن redacted می‌شود. -- بلوک‌های طولانی می‌توانند کوتاه شوند. +- یادآوری دستیار ابتدا نرمال‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ داربست `` / `` حذف می‌شود؛ بلوک‌های payload XML فراخوانی ابزارِ متن ساده (``، ``، ``، ``) حذف می‌شوند، از جمله payloadهای ناقص که هرگز تمیز بسته نمی‌شوند؛ داربست تنزل‌یافتهٔ فراخوانی ابزار/نتیجه و نشانگرهای زمینهٔ تاریخی حذف می‌شوند؛ توکن‌های کنترلی مدلِ نشت‌کرده (`<|assistant|>`، سایر `<|...|>`های ASCII، `<｜...｜>` تمام‌عرض) حذف می‌شوند؛ XML فراخوانی ابزار MiniMax نادرست حذف می‌شود. +- متن شبیه اعتبارنامه/توکن پوشانده می‌شود. +- بلوک‌های بلند می‌توانند کوتاه شوند. - تاریخچه‌های بسیار بزرگ می‌توانند ردیف‌های قدیمی‌تر را حذف کنند یا یک ردیف بیش‌ازحد بزرگ را با `[sessions_history omitted: message too large]` جایگزین کنند. -- بررسی transcript خام روی دیسک fallback است وقتی به transcript کاملِ بایت‌به‌بایت نیاز دارید. +- بررسی رونویس خام روی دیسک گزینهٔ پشتیبان است وقتی به رونویس کاملِ بایت‌به‌بایت نیاز دارید. -## سیاست ابزار +## خط‌مشی ابزار -زیرعامل‌ها ابتدا از همان نمایه و pipeline سیاست ابزارِ والد یا -عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت زیرعامل را اعمال می‌کند. +زیرعامل‌ها ابتدا از همان پروفایل و خط‌لولهٔ خط‌مشی ابزارِ والد یا +عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت +زیرعامل را اعمال می‌کند. بدون `tools.profile` محدودکننده، زیرعامل‌ها **همهٔ ابزارها به‌جز ابزارهای نشست** و ابزارهای سیستم را دریافت می‌کنند: @@ -444,9 +448,9 @@ payloadهای اعلام در پایان شامل یک خط آمار هستند - `sessions_spawn` `sessions_history` اینجا هم یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند — -dump خام transcript نیست. +نه یک dump خام رونویس. -وقتی `maxSpawnDepth >= 2` باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر این +وقتی `maxSpawnDepth >= 2` باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر آن `sessions_spawn`، `subagents`، `sessions_list`، و `sessions_history` را دریافت می‌کنند تا بتوانند فرزندانشان را مدیریت کنند. @@ -474,12 +478,7 @@ dump خام transcript نیست. } ``` -`tools.subagents.tools.allow` یک فیلتر نهایی فقط-مجاز است. می‌تواند -مجموعه ابزارهای از پیش حل‌شده را محدودتر کند، اما نمی‌تواند ابزاری را که -با `tools.profile` حذف شده است **دوباره اضافه کند**. برای مثال، `tools.profile: "coding"` -شامل `web_search`/`web_fetch` است اما ابزار `browser` را شامل نمی‌شود. برای اینکه -زیرعامل‌های دارای پروفایل کدنویسی بتوانند از اتوماسیون مرورگر استفاده کنند، browser را در -مرحلهٔ پروفایل اضافه کنید: +`tools.subagents.tools.allow` یک فیلتر نهایی فقط-مجاز است. می‌تواند مجموعه ابزار ازپیش‌حل‌شده را محدودتر کند، اما نمی‌تواند ابزاری را که توسط `tools.profile` حذف شده است **دوباره اضافه کند**. برای مثال، `tools.profile: "coding"` شامل `web_search`/`web_fetch` است اما ابزار `browser` را شامل نمی‌شود. برای اینکه زیرعامل‌های پروفایل کدنویسی بتوانند از خودکارسازی مرورگر استفاده کنند، browser را در مرحله پروفایل اضافه کنید: ```json5 { @@ -490,7 +489,7 @@ dump خام transcript نیست. } ``` -وقتی فقط یک عامل باید اتوماسیون مرورگر را دریافت کند، از `agents.list[].tools.alsoAllow: ["browser"]` برای هر عامل استفاده کنید. +وقتی فقط یک عامل باید خودکارسازی مرورگر را دریافت کند، از `agents.list[].tools.alsoAllow: ["browser"]` برای هر عامل استفاده کنید. ## هم‌زمانی @@ -501,40 +500,30 @@ dump خام transcript نیست. ## زنده‌بودن و بازیابی -OpenClaw نبود `endedAt` را به‌عنوان اثبات دائمی زنده‌بودن یک -زیرعامل در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجرهٔ اجرای کهنه قدیمی‌تر هستند، -دیگر در `/subagents list`، خلاصه‌های وضعیت، -دروازه‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر نشست به‌عنوان فعال/در انتظار شمرده نمی‌شوند. +OpenClaw نبود `endedAt` را به‌عنوان اثبات دائمی زنده بودن یک زیرعامل در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجره اجرای کهنه قدیمی‌تر هستند، دیگر در `/subagents list`، خلاصه‌های وضعیت، دروازه‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر نشست، فعال/در انتظار شمرده نمی‌شوند. -پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شدهٔ پایان‌نیافتهٔ کهنه حذف می‌شوند مگر اینکه -نشست فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. این -نشست‌های فرزندِ لغوشده در اثر راه‌اندازی مجدد، از طریق جریان بازیابی یتیم زیرعامل -همچنان قابل بازیابی می‌مانند؛ این جریان پیش از پاک‌کردن نشانگر لغوشده، -یک پیام ازسرگیری مصنوعی ارسال می‌کند. +پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شده پایان‌نیافته که کهنه هستند حذف می‌شوند، مگر اینکه نشست فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. آن نشست‌های فرزند که با راه‌اندازی مجدد لغو شده‌اند، از طریق جریان بازیابی یتیم زیرعامل قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر لغوشده، یک پیام ازسرگیری ساختگی می‌فرستد. + +بازیابی خودکار پس از راه‌اندازی مجدد برای هر نشست فرزند محدود شده است. اگر همان فرزند زیرعامل در بازه اتصال مجدد سریع، چندین‌بار برای بازیابی یتیم پذیرفته شود، OpenClaw یک سنگ‌قبر بازیابی روی آن نشست ذخیره می‌کند و در راه‌اندازی‌های مجدد بعدی ازسرگیری خودکار آن را متوقف می‌کند. برای هم‌ساز کردن رکورد وظیفه، `openclaw tasks maintenance --apply` را اجرا کنید، یا برای پاک کردن پرچم‌های بازیابی لغوشده کهنه روی نشست‌های سنگ‌قبرشده، `openclaw doctor --fix` را اجرا کنید. -اگر ایجاد زیرعامل با خطای Gateway `PAIRING_REQUIRED` / -`scope-upgrade` شکست خورد، پیش از ویرایش وضعیت جفت‌سازی، فراخوان RPC را بررسی کنید. -هماهنگی داخلی `sessions_spawn` باید با -`client.id: "gateway-client"` و `client.mode: "backend"` از طریق احراز هویت مستقیم -loopback با توکن/گذرواژهٔ مشترک متصل شود؛ این مسیر به خط مبنای دامنهٔ دستگاه جفت‌شدهٔ CLI وابسته نیست. فراخوان‌های راه‌دور، `deviceIdentity` صریح، -مسیرهای صریح توکن دستگاه، و کلاینت‌های مرورگر/Node -هنوز برای ارتقاهای دامنه به تأیید معمول دستگاه نیاز دارند. +اگر ایجاد زیرعامل با Gateway `PAIRING_REQUIRED` / +`scope-upgrade` شکست خورد، پیش از ویرایش وضعیت جفت‌سازی، فراخوان RPC را بررسی کنید. هماهنگی داخلی `sessions_spawn` باید به‌صورت `client.id: "gateway-client"` با `client.mode: "backend"` از طریق احراز هویت مستقیم loopback با توکن/رمز عبور مشترک وصل شود؛ آن مسیر به خط مبنای دامنه دستگاه جفت‌شده CLI وابسته نیست. فراخوان‌های راه دور، `deviceIdentity` صریح، مسیرهای صریح توکن دستگاه، و کلاینت‌های مرورگر/node همچنان برای ارتقای دامنه به تأیید عادی دستگاه نیاز دارند. -## توقف +## متوقف کردن -- ارسال `/stop` در گفت‌وگوی درخواست‌کننده، نشست درخواست‌کننده را لغو می‌کند و هر اجرای زیرعامل فعالی را که از آن ایجاد شده باشد، با سرایت به فرزندان تودرتو متوقف می‌کند. -- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و به فرزندان آن نیز سرایت می‌کند. +- ارسال `/stop` در گفت‌وگوی درخواست‌کننده، نشست درخواست‌کننده را لغو می‌کند و هر اجرای فعال زیرعامل را که از آن ایجاد شده باشد متوقف می‌کند و این توقف به فرزندان تو در تو نیز سرایت می‌کند. +- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و این توقف به فرزندان آن نیز سرایت می‌کند. ## محدودیت‌ها -- اعلام زیرعامل **بهترین‌تلاش** است. اگر Gateway دوباره راه‌اندازی شود، کارهای در انتظار «اعلام بازگشتی» از دست می‌روند. -- زیرعامل‌ها همچنان منابع همان فرایند Gateway را به اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک شیر اطمینان در نظر بگیرید. +- اعلام زیرعامل **تلاشی در حد امکان** است. اگر Gateway راه‌اندازی مجدد شود، کارهای در انتظار «اعلام بازگشت» از دست می‌روند. +- زیرعامل‌ها همچنان منابع همان فرایند Gateway را به اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک سوپاپ ایمنی در نظر بگیرید. - `sessions_spawn` همیشه غیرمسدودکننده است: بلافاصله `{ status: "accepted", runId, childSessionKey }` را برمی‌گرداند. -- زمینهٔ زیرعامل فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`). -- بیشینهٔ عمق تودرتویی ۵ است (بازهٔ `maxSpawnDepth`: ۱ تا ۵). عمق ۲ برای بیشتر موارد استفاده توصیه می‌شود. -- `maxChildrenPerAgent` تعداد فرزندان فعال برای هر نشست را محدود می‌کند (پیش‌فرض `5`، بازهٔ `1–20`). +- بافت زیرعامل فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`). +- بیشینه عمق تودرتویی 5 است (بازه `maxSpawnDepth`: 1–5). عمق 2 برای بیشتر موارد استفاده توصیه می‌شود. +- `maxChildrenPerAgent` تعداد فرزندان فعال به‌ازای هر نشست را محدود می‌کند (پیش‌فرض `5`، بازه `1–20`). ## مرتبط diff --git a/docs/fa/tools/thinking.md b/docs/fa/tools/thinking.md index f5ebe9d4d..0f7dd3072 100644 --- a/docs/fa/tools/thinking.md +++ b/docs/fa/tools/thinking.md @@ -1,139 +1,140 @@ --- read_when: - - تنظیم تجزیه یا پیش‌فرض‌های دستورالعمل‌های thinking، fast-mode یا verbose -summary: نحو دستورالعمل‌ها برای /think، /fast، /verbose، /trace و قابلیت مشاهدهٔ استدلال + - تنظیم تجزیه یا پیش‌فرض‌های تفکر، حالت سریع، یا دستورالعمل پرجزئیات +summary: نحو دستورها برای /think، /fast، /verbose، /trace و قابلیت مشاهدهٔ استدلال title: سطوح تفکر x-i18n: - generated_at: "2026-04-29T23:46:26Z" + generated_at: "2026-04-30T16:32:32Z" model: gpt-5.5 provider: openai - source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705 + source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7 source_path: tools/thinking.md workflow: 16 --- ## چه کاری انجام می‌دهد -- دستور درون‌خطی در هر بدنه ورودی: `/t `، `/think:`، یا `/thinking `. +- دستور درون‌خطی در هر بدنهٔ ورودی: `/t `، `/think:`، یا `/thinking `. - سطح‌ها (نام‌های مستعار): `off | minimal | low | medium | high | xhigh | adaptive | max` - - 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` خود نگاشت می‌کند) + - minimal → “think” + - low → “think hard” + - medium → “think harder” + - high → “ultrathink” (بیشینهٔ بودجه) + - xhigh → “ultrathink+” (مدل‌های GPT-5.2+ و Codex، به‌علاوه effort مربوط به 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 این را به بالاترین effort بومی `think` خود نگاشت می‌کند) - `x-high`، `x_high`، `extra-high`، `extra high`، و `extra_high` به `xhigh` نگاشت می‌شوند. - `highest` به `high` نگاشت می‌شود. -- نکات ارائه‌دهنده: - - منوها و انتخاب‌گرهای تفکر توسط نمایه ارائه‌دهنده هدایت می‌شوند. Pluginهای ارائه‌دهنده مجموعه دقیق سطح‌ها را برای مدل انتخاب‌شده اعلام می‌کنند، از جمله برچسب‌هایی مانند `on` دودویی. +- نکته‌های ارائه‌دهنده: + - منوها و انتخابگرهای تفکر بر اساس نمایهٔ ارائه‌دهنده هدایت می‌شوند. 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` را ارائه می‌کند؛ این دستور به همان مسیر حداکثر تلاشِ در مالکیت ارائه‌دهنده نگاشت می‌شود. - - مدل‌های دارای قابلیت تفکر 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..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 جلوگیری می‌کند. + - سطح‌های ذخیره‌شدهٔ پشتیبانی‌نشدهٔ موجود بر اساس رتبهٔ نمایهٔ ارائه‌دهنده بازنگاشت می‌شوند. `adaptive` در مدل‌های غیرتطبیقی به `medium` برمی‌گردد، در حالی که `xhigh` و `max` به بزرگ‌ترین سطح غیر `off` پشتیبانی‌شده برای مدل انتخاب‌شده برمی‌گردند. + - مدل‌های Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد، به‌طور پیش‌فرض از `adaptive` استفاده می‌کنند. + - Anthropic Claude Opus 4.7 به‌طور پیش‌فرض از تفکر تطبیقی استفاده نمی‌کند. پیش‌فرض effort در API آن همچنان در مالکیت ارائه‌دهنده می‌ماند، مگر اینکه صراحتا یک سطح تفکر تنظیم کنید. + - Anthropic Claude Opus 4.7 دستور `/think xhigh` را به تفکر تطبیقی به‌همراه `output_config.effort: "xhigh"` نگاشت می‌کند، چون `/think` یک دستور تفکر است و `xhigh` تنظیم effort در Opus 4.7 است. + - Anthropic Claude Opus 4.7 همچنین `/think max` را در دسترس می‌گذارد؛ این دستور به همان مسیر بیشینهٔ effort در مالکیت ارائه‌دهنده نگاشت می‌شود. + - مدل‌های DeepSeek V4 دستورهای `/think xhigh|max` را در دسترس می‌گذارند؛ هر دو به `reasoning_effort: "max"` در DeepSeek نگاشت می‌شوند، در حالی که سطح‌های پایین‌تر غیر `off` به `high` نگاشت می‌شوند. + - مدل‌های Ollama با قابلیت تفکر دستور `/think low|medium|high|max` را در دسترس می‌گذارند؛ `max` به `think: "high"` بومی نگاشت می‌شود، چون API بومی Ollama رشته‌های effort با مقدارهای `low`، `medium`، و `high` را می‌پذیرد. + - مدل‌های OpenAI GPT دستور `/think` را از مسیر پشتیبانی effort ویژهٔ هر مدل در Responses API نگاشت می‌کنند. `/think off` فقط وقتی مدل هدف از آن پشتیبانی کند `reasoning.effort: "none"` را ارسال می‌کند؛ در غیر این صورت OpenClaw به‌جای ارسال مقدار پشتیبانی‌نشده، payload غیرفعال‌سازی استدلال را حذف می‌کند. + - مدخل‌های کاتالوگ سفارشی سازگار با OpenAI می‌توانند با تنظیم `models.providers..models[].compat.supportedReasoningEfforts` برای شامل کردن `"xhigh"`، پشتیبانی از `/think xhigh` را فعال کنند. این کار از همان فرادادهٔ سازگاری استفاده می‌کند که payloadهای effort استدلال خروجی OpenAI را نگاشت می‌کند؛ بنابراین منوها، اعتبارسنجی نشست، CLI عامل، و `llm-task` با رفتار انتقال هم‌نظر می‌مانند. + - ارجاع‌های قدیمی پیکربندی‌شده به OpenRouter Hunter Alpha تزریق استدلال proxy را رد می‌کنند، چون آن مسیر بازنشسته می‌توانست متن پاسخ نهایی را از طریق فیلدهای استدلال برگرداند. + - 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. بازنویسی نشست (با فرستادن پیام فقط-دستور تنظیم می‌شود). +1. دستور درون‌خطی روی پیام (فقط برای همان پیام اعمال می‌شود). +2. بازنویسی نشست (با ارسال پیام فقط شامل دستور تنظیم می‌شود). 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:medium` یا `/t high`. +- این تنظیم برای نشست فعلی باقی می‌ماند (به‌طور پیش‌فرض برای هر فرستنده جداگانه)؛ با `/think:off` یا بازنشانی نشست پس از بیکاری پاک می‌شود. +- پاسخ تأیید ارسال می‌شود (`Thinking level set to high.` / `Thinking disabled.`). اگر سطح نامعتبر باشد (مثلا `/thinking big`)، فرمان با یک راهنما رد می‌شود و وضعیت نشست بدون تغییر می‌ماند. - برای دیدن سطح تفکر فعلی، `/think` (یا `/think:`) را بدون آرگومان بفرستید. -## اعمال بر اساس عامل +## اعمال توسط عامل -- **Pi تعبیه‌شده**: سطح حل‌وفصل‌شده به زمان اجرای عامل Pi درون‌فرایندی پاس داده می‌شود. +- **Pi توکار**: سطح حل‌شده به runtime عامل Pi درون‌فرآیندی پاس داده می‌شود. ## حالت سریع (/fast) - سطح‌ها: `on|off`. -- پیام فقط-دستور، بازنویسی حالت سریع نشست را تغییر می‌دهد و با `Fast mode enabled.` / `Fast mode disabled.` پاسخ می‌دهد. -- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون حالت بفرستید. +- پیام فقط شامل دستور، بازنویسی حالت سریع نشست را تغییر می‌دهد و با `Fast mode enabled.` / `Fast mode disabled.` پاسخ می‌دهد. +- برای دیدن وضعیت مؤثر فعلی حالت سریع، `/fast` (یا `/fast status`) را بدون mode بفرستید. - OpenClaw حالت سریع را با این ترتیب حل‌وفصل می‌کند: - 1. درون‌خطی/فقط-دستور `/fast on|off` + 1. `/fast on|off` درون‌خطی/فقط شامل دستور 2. بازنویسی نشست 3. پیش‌فرض هر عامل (`agents.list[].fastModeDefault`) 4. پیکربندی هر مدل: `agents.defaults.models["/"].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` را تنظیم می‌کند. -- برای `minimax/*` در مسیر سازگار با Anthropic، `/fast on` (یا `params.fastMode: true`) مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی می‌کند. -- پارامترهای مدل Anthropic صریح `serviceTier` / `service_tier` وقتی هر دو تنظیم شده باشند، پیش‌فرض حالت سریع را بازنویسی می‌کنند. OpenClaw همچنان تزریق سطح سرویس Anthropic را برای URLهای پایه پروکسی غیر Anthropic رد می‌کند. -- `/status` فقط وقتی حالت سریع فعال باشد `Fast` را نشان می‌دهد. + 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` را تنظیم می‌کند. +- برای `minimax/*` روی مسیر سازگار با Anthropic، `/fast on` (یا `params.fastMode: true`) مقدار `MiniMax-M2.7` را به `MiniMax-M2.7-highspeed` بازنویسی می‌کند. +- پارامترهای مدل Anthropic با مقدار صریح `serviceTier` / `service_tier` وقتی هر دو تنظیم شده باشند، پیش‌فرض حالت سریع را بازنویسی می‌کنند. OpenClaw همچنان تزریق سطح سرویس Anthropic را برای URLهای پایهٔ proxy غیر Anthropic رد می‌کند. +- `/status` فقط وقتی حالت سریع فعال باشد، `Fast` را نشان می‌دهد. -## دستورهای پرجزئیات (/verbose یا /v) +## دستورهای verbose (/verbose یا /v) - سطح‌ها: `on` (حداقلی) | `full` | `off` (پیش‌فرض). -- پیام فقط-دستور، پرجزئیات بودن نشست را تغییر می‌دهد و با `Verbose logging enabled.` / `Verbose logging disabled.` پاسخ می‌دهد؛ سطح‌های نامعتبر بدون تغییر وضعیت، یک راهنما برمی‌گردانند. -- `/verbose off` یک بازنویسی صریح نشست ذخیره می‌کند؛ آن را از طریق رابط کاربری Sessions با انتخاب `inherit` پاک کنید. -- دستور درون‌خطی فقط روی همان پیام اثر می‌گذارد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند. -- برای دیدن سطح پرجزئیات فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان بفرستید. -- وقتی پرجزئیات روشن باشد، عامل‌هایی که نتایج ابزار ساختاریافته منتشر می‌کنند (Pi، عامل‌های JSON دیگر) هر فراخوانی ابزار را به‌صورت پیام جداگانه فقط-فراداده برمی‌گردانند، در صورت وجود (مسیر/فرمان) با پیشوند ` : `. این خلاصه‌های ابزار به‌محض شروع هر ابزار فرستاده می‌شوند (حباب‌های جداگانه)، نه به‌صورت دلتاهای استریم. -- خلاصه‌های شکست ابزار در حالت عادی قابل مشاهده می‌مانند، اما پسوندهای جزئیات خطای خام پنهان هستند مگر اینکه پرجزئیات `on` یا `full` باشد. -- وقتی پرجزئیات `full` باشد، خروجی‌های ابزار نیز پس از تکمیل ارسال می‌شوند (حباب جداگانه، کوتاه‌شده تا طول امن). اگر هنگام اجرای در جریان، `/verbose on|full|off` را تغییر دهید، حباب‌های ابزار بعدی تنظیم جدید را رعایت می‌کنند. +- پیام فقط شامل دستور، verbose نشست را تغییر می‌دهد و با `Verbose logging enabled.` / `Verbose logging disabled.` پاسخ می‌دهد؛ سطح‌های نامعتبر بدون تغییر وضعیت، یک راهنما برمی‌گردانند. +- `/verbose off` یک بازنویسی صریح نشست ذخیره می‌کند؛ آن را از طریق UI نشست‌ها با انتخاب `inherit` پاک کنید. +- دستور درون‌خطی فقط همان پیام را تحت تأثیر قرار می‌دهد؛ در غیر این صورت پیش‌فرض‌های نشست/سراسری اعمال می‌شوند. +- برای دیدن سطح verbose فعلی، `/verbose` (یا `/verbose:`) را بدون آرگومان بفرستید. +- وقتی verbose روشن است، عامل‌هایی که نتایج ساخت‌یافتهٔ ابزار منتشر می‌کنند (Pi، عامل‌های JSON دیگر) هر فراخوانی ابزار را به‌صورت پیام جداگانهٔ فقط-فراداده برمی‌گردانند، و وقتی موجود باشد با ` : ` پیشوند می‌زنند (مسیر/فرمان). این خلاصه‌های ابزار به‌محض شروع هر ابزار ارسال می‌شوند (حباب‌های جداگانه)، نه به‌شکل دلتاهای جریان‌سازی. +- خلاصه‌های شکست ابزار در حالت عادی قابل مشاهده می‌مانند، اما پسوندهای جزئیات خطای خام پنهان هستند، مگر اینکه verbose برابر `on` یا `full` باشد. +- وقتی verbose برابر `full` است، خروجی‌های ابزار نیز پس از تکمیل فوروارد می‌شوند (حباب جداگانه، کوتاه‌شده تا طول امن). اگر هنگام در حال اجرا بودن یک اجرا، `/verbose on|full|off` را تغییر دهید، حباب‌های بعدی ابزار تنظیم جدید را رعایت می‌کنند. -## دستورهای ردیابی 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:`) را بدون آرگومان بفرستید. +- `/trace` محدودتر از `/verbose` است: فقط خطوط trace/debug در مالکیت Plugin را، مانند خلاصه‌های debug مربوط به Active Memory، آشکار می‌کند. +- خطوط trace می‌توانند در `/status` و به‌عنوان پیام تشخیصی پیگیری پس از پاسخ عادی دستیار ظاهر شوند. -## قابلیت مشاهده استدلال (/reasoning) +## مشاهده‌پذیری استدلال (/reasoning) - سطح‌ها: `on|off|stream`. -- پیام فقط-دستور، نمایش یا عدم نمایش بلوک‌های تفکر در پاسخ‌ها را تغییر می‌دهد. -- وقتی فعال باشد، استدلال به‌صورت **پیام جداگانه** با پیشوند `Reasoning:` فرستاده می‌شود. -- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را در حباب پیش‌نویس Telegram استریم می‌کند، سپس پاسخ نهایی را بدون استدلال می‌فرستد. +- پیام فقط شامل دستور، نمایش یا عدم نمایش بلوک‌های تفکر در پاسخ‌ها را تغییر می‌دهد. +- وقتی فعال باشد، استدلال به‌صورت **پیام جداگانه** با پیشوند `Reasoning:` ارسال می‌شود. +- `stream` (فقط Telegram): هنگام تولید پاسخ، استدلال را در حباب پیش‌نویس Telegram جریان‌سازی می‌کند، سپس پاسخ نهایی را بدون استدلال ارسال می‌کند. - نام مستعار: `/reason`. - برای دیدن سطح استدلال فعلی، `/reasoning` (یا `/reasoning:`) را بدون آرگومان بفرستید. -- ترتیب حل‌وفصل: دستور درون‌خطی، سپس بازنویسی نشست، سپس پیش‌فرض هر عامل (`agents.list[].reasoningDefault`)، سپس بازگشت (`off`). +- ترتیب حل‌وفصل: دستور درون‌خطی، سپس بازنویسی نشست، سپس پیش‌فرض هر عامل (`agents.list[].reasoningDefault`)، سپس جایگزین (`off`). -برچسب‌های استدلال بدشکل مدل محلی با احتیاط مدیریت می‌شوند. بلوک‌های بسته‌شده `...` در پاسخ‌های عادی پنهان می‌مانند، و استدلال بسته‌نشده پس از متن از پیش قابل مشاهده نیز پنهان می‌شود. اگر پاسخی کاملا در یک برچسب بازکننده بسته‌نشده منفرد پیچیده شده باشد و در غیر این صورت به‌عنوان متن خالی تحویل داده شود، OpenClaw برچسب بازکننده بدشکل را حذف می‌کند و متن باقی‌مانده را تحویل می‌دهد. +برچسب‌های استدلال مدل محلی که بدشکل باشند محافظه‌کارانه مدیریت می‌شوند. بلوک‌های بسته‌شدهٔ `...` در پاسخ‌های عادی پنهان می‌مانند، و استدلال بسته‌نشده پس از متنی که از قبل قابل مشاهده است نیز پنهان می‌شود. اگر یک پاسخ به‌طور کامل در یک برچسب بازکنندهٔ بسته‌نشده پیچیده شده باشد و در غیر این صورت به‌صورت متن خالی تحویل داده شود، 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 به‌طور پیش‌فرض فقط شامل payload نهایی است. برای اینکه پیام جداگانهٔ `Reasoning:` نیز ارسال شود (وقتی موجود باشد)، `agents.defaults.heartbeat.includeReasoning: true` یا برای هر عامل `agents.list[].heartbeat.includeReasoning: true` را تنظیم کنید. -## رابط کاربری گفت‌وگوی وب +## UI گفت‌وگوی وب -- انتخاب‌گر تفکر گفت‌وگوی وب هنگام بارگذاری صفحه، سطح ذخیره‌شده نشست را از ذخیره‌ساز/پیکربندی نشست ورودی بازتاب می‌دهد. -- انتخاب سطح دیگر، بازنویسی نشست را بلافاصله از طریق `sessions.patch` می‌نویسد؛ منتظر ارسال بعدی نمی‌ماند و یک بازنویسی یک‌باره `thinkingOnce` نیست. -- گزینه نخست همیشه `Default ()` است، که در آن پیش‌فرض حل‌وفصل‌شده از نمایه تفکر ارائه‌دهنده مدل نشست فعال به‌علاوه همان منطق بازگشتی می‌آید که `/status` و `session_status` استفاده می‌کنند. -- انتخاب‌گر از `thinkingLevels` برگشتی توسط ردیف/پیش‌فرض‌های نشست Gateway استفاده می‌کند، و `thinkingOptions` به‌عنوان فهرست برچسب قدیمی نگه داشته می‌شود. رابط کاربری مرورگر فهرست regex ارائه‌دهنده اختصاصی خود را نگه نمی‌دارد؛ Pluginها مالک مجموعه سطح‌های ویژه مدل هستند. -- `/think:` همچنان کار می‌کند و همان سطح نشست ذخیره‌شده را به‌روزرسانی می‌کند، بنابراین دستورهای گفت‌وگو و انتخاب‌گر همگام می‌مانند. +- انتخابگر تفکر گفت‌وگوی وب، سطح ذخیره‌شدهٔ نشست را از store/پیکربندی نشست ورودی هنگام بارگذاری صفحه بازتاب می‌دهد. +- انتخاب سطح دیگر، بازنویسی نشست را فورا از طریق `sessions.patch` می‌نویسد؛ منتظر ارسال بعدی نمی‌ماند و یک بازنویسی یک‌بارهٔ `thinkingOnce` نیست. +- گزینهٔ اول همیشه `Default ()` است، که در آن پیش‌فرض حل‌شده از نمایهٔ تفکر ارائه‌دهندهٔ مدل نشست فعال به‌همراه همان منطق جایگزینی می‌آید که `/status` و `session_status` استفاده می‌کنند. +- انتخابگر از `thinkingLevels` برگردانده‌شده توسط ردیف/پیش‌فرض‌های نشست gateway استفاده می‌کند، و `thinkingOptions` به‌عنوان فهرست برچسب قدیمی نگه داشته می‌شود. UI مرورگر فهرست regex ارائه‌دهندهٔ خودش را نگه نمی‌دارد؛ Pluginها مالک مجموعه‌های سطح ویژهٔ مدل هستند. +- `/think:` همچنان کار می‌کند و همان سطح ذخیره‌شدهٔ نشست را به‌روزرسانی می‌کند، بنابراین دستورهای گفت‌وگو و انتخابگر همگام می‌مانند. ## نمایه‌های ارائه‌دهنده -- 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/chat همان شناسه‌ها و برچسب‌های پروفایلی را رندر کنند که اعتبارسنجی زمان اجرا از آن‌ها استفاده می‌کند.