diff --git a/docs/fa/channels/discord.md b/docs/fa/channels/discord.md index 83fb28883..7c8b28a45 100644 --- a/docs/fa/channels/discord.md +++ b/docs/fa/channels/discord.md @@ -1,72 +1,72 @@ --- read_when: - کار روی قابلیت‌های کانال Discord -summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی بات Discord +summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Discord title: Discord x-i18n: - generated_at: "2026-05-04T02:21:19Z" + generated_at: "2026-05-04T07:02:39Z" model: gpt-5.5 provider: openai - source_hash: df4e045e39f8977f779fe409abf41dad0d950c92f1230c51ff356343513df812 + source_hash: 1e00f9d9b134296ac1ca52bb4058fc62ea7a95c4d46d9478648b2ecdd448652a source_path: channels/discord.md workflow: 16 --- -آماده برای پیام‌های مستقیم و کانال‌های سرور از طریق Gateway رسمی Discord. +آماده برای پیام‌های خصوصی و کانال‌های سرور از طریق Gateway رسمی Discord. - پیام‌های مستقیم Discord به‌طور پیش‌فرض در حالت جفت‌سازی هستند. + پیام‌های خصوصی Discord به‌طور پیش‌فرض در حالت جفت‌سازی هستند. - رفتار دستور بومی و کاتالوگ دستورها. + رفتار دستورهای بومی و کاتالوگ دستورها. - عیب‌یابی بین‌کانالی و جریان تعمیر. + عیب‌یابی میان‌کانالی و جریان تعمیر. ## راه‌اندازی سریع -باید یک برنامه جدید همراه با یک ربات بسازید، ربات را به سرور خود اضافه کنید و آن را با OpenClaw جفت کنید. توصیه می‌کنیم رباتتان را به سرور خصوصی خودتان اضافه کنید. اگر هنوز یکی ندارید، [ابتدا یکی بسازید](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (گزینه **Create My Own > For me and my friends** را انتخاب کنید). +باید یک برنامه جدید همراه با bot بسازید، bot را به سرور خود اضافه کنید، و آن را با OpenClaw جفت کنید. پیشنهاد می‌کنیم bot خود را به سرور خصوصی خودتان اضافه کنید. اگر هنوز سروری ندارید، [ابتدا یکی بسازید](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (گزینه **Create My Own > For me and my friends** را انتخاب کنید). - + به [Discord Developer Portal](https://discord.com/developers/applications) بروید و روی **New Application** کلیک کنید. نامی مثل «OpenClaw» برای آن بگذارید. - در نوار کناری روی **Bot** کلیک کنید. **Username** را روی هر نامی که برای عامل OpenClaw خود استفاده می‌کنید تنظیم کنید. + در نوار کناری روی **Bot** کلیک کنید. مقدار **Username** را به هر نامی که برای عامل OpenClaw خود استفاده می‌کنید تنظیم کنید. - + همچنان در صفحه **Bot**، به پایین تا **Privileged Gateway Intents** بروید و این موارد را فعال کنید: - - **Message Content Intent** (لازم) - - **Server Members Intent** (توصیه‌شده؛ برای فهرست‌های مجاز نقش و تطبیق نام با شناسه لازم است) - - **Presence Intent** (اختیاری؛ فقط برای به‌روزرسانی‌های حضور لازم است) + - **Message Content Intent** (الزامی) + - **Server Members Intent** (توصیه‌شده؛ برای فهرست‌های مجاز نقش و تطبیق نام با شناسه الزامی است) + - **Presence Intent** (اختیاری؛ فقط برای به‌روزرسانی‌های وضعیت حضور لازم است) - + در صفحه **Bot** دوباره به بالا بروید و روی **Reset Token** کلیک کنید. - با وجود این نام، این کار نخستین توکن شما را تولید می‌کند — چیزی «بازنشانی» نمی‌شود. + برخلاف نامش، این کار اولین توکن شما را تولید می‌کند — چیزی «بازنشانی» نمی‌شود. - توکن را کپی کنید و جایی ذخیره کنید. این **Bot Token** شماست و به‌زودی به آن نیاز خواهید داشت. + توکن را کپی کنید و جایی ذخیره کنید. این **Bot Token** شماست و کمی بعد به آن نیاز دارید. - - در نوار کناری روی **OAuth2** کلیک کنید. یک URL دعوت با مجوزهای درست برای افزودن ربات به سرورتان تولید خواهید کرد. + + در نوار کناری روی **OAuth2** کلیک کنید. یک URL دعوت با مجوزهای درست برای افزودن bot به سرورتان تولید می‌کنید. به پایین تا **OAuth2 URL Generator** بروید و این موارد را فعال کنید: - `bot` - `applications.commands` - بخشی با عنوان **Bot Permissions** در پایین ظاهر می‌شود. حداقل این موارد را فعال کنید: + بخشی با عنوان **Bot Permissions** در پایین ظاهر می‌شود. دست‌کم این موارد را فعال کنید: **مجوزهای عمومی** - مشاهده کانال‌ها @@ -74,34 +74,34 @@ x-i18n: - ارسال پیام‌ها - خواندن تاریخچه پیام‌ها - جاسازی پیوندها - - پیوست کردن فایل‌ها + - پیوست‌کردن فایل‌ها - افزودن واکنش‌ها (اختیاری) - این مجموعه پایه برای کانال‌های متنی عادی است. اگر قصد دارید در رشته‌های Discord پست بگذارید، از جمله جریان‌های کاری کانال انجمن یا رسانه که یک رشته ایجاد می‌کنند یا ادامه می‌دهند، **Send Messages in Threads** را نیز فعال کنید. - URL تولیدشده در پایین را کپی کنید، در مرورگر خود جای‌گذاری کنید، سرورتان را انتخاب کنید و برای اتصال روی **Continue** کلیک کنید. اکنون باید ربات خود را در سرور Discord ببینید. + این مجموعه پایه برای کانال‌های متنی معمولی است. اگر قصد دارید در threadهای Discord پست بگذارید، از جمله گردش‌کارهای کانال forum یا media که یک thread ایجاد یا ادامه می‌دهند، **Send Messages in Threads** را هم فعال کنید. + URL تولیدشده در پایین را کپی کنید، آن را در مرورگر خود جای‌گذاری کنید، سرور خود را انتخاب کنید، و برای اتصال روی **Continue** کلیک کنید. اکنون باید bot خود را در سرور Discord ببینید. - + در برنامه Discord، باید Developer Mode را فعال کنید تا بتوانید شناسه‌های داخلی را کپی کنید. - 1. روی **User Settings** (نماد چرخ‌دنده کنار آواتار خود) کلیک کنید → **Advanced** → **Developer Mode** را روشن کنید - 2. در نوار کناری روی **server icon** خود راست‌کلیک کنید → **Copy Server ID** - 3. روی **own avatar** خود راست‌کلیک کنید → **Copy User ID** + 1. روی **User Settings** (آیکون چرخ‌دنده کنار آواتارتان) کلیک کنید → **Advanced** → **Developer Mode** را روشن کنید + 2. در نوار کناری روی **آیکون سرور** خود راست‌کلیک کنید → **Copy Server ID** + 3. روی **آواتار خودتان** راست‌کلیک کنید → **Copy User ID** - **Server ID** و **User ID** خود را در کنار Bot Token ذخیره کنید — در مرحله بعد هر سه را به OpenClaw می‌فرستید. + **Server ID** و **User ID** خود را کنار Bot Token ذخیره کنید — در گام بعدی هر سه را به OpenClaw می‌فرستید. - - برای کار کردن جفت‌سازی، Discord باید به ربات شما اجازه دهد به شما پیام مستقیم بدهد. روی **server icon** خود راست‌کلیک کنید → **Privacy Settings** → **Direct Messages** را روشن کنید. + + برای اینکه جفت‌سازی کار کند، Discord باید اجازه دهد bot به شما پیام خصوصی بفرستد. روی **آیکون سرور** خود راست‌کلیک کنید → **Privacy Settings** → **Direct Messages** را روشن کنید. - این کار به اعضای سرور (از جمله ربات‌ها) اجازه می‌دهد به شما پیام مستقیم بدهند. اگر می‌خواهید از پیام‌های مستقیم Discord با OpenClaw استفاده کنید، این گزینه را فعال نگه دارید. اگر فقط قصد دارید از کانال‌های سرور استفاده کنید، می‌توانید پس از جفت‌سازی پیام‌های مستقیم را غیرفعال کنید. + این کار اجازه می‌دهد اعضای سرور (از جمله botها) برای شما پیام خصوصی بفرستند. اگر می‌خواهید از پیام‌های خصوصی Discord با OpenClaw استفاده کنید، این گزینه را روشن نگه دارید. اگر فقط قصد استفاده از کانال‌های سرور را دارید، می‌توانید پس از جفت‌سازی پیام‌های خصوصی را غیرفعال کنید. - - توکن ربات Discord شما یک راز است (مانند گذرواژه). پیش از پیام دادن به عامل خود، آن را روی دستگاهی که OpenClaw را اجرا می‌کند تنظیم کنید. + + توکن bot در Discord یک راز است (مثل گذرواژه). پیش از پیام‌دادن به عامل خود، آن را روی ماشینی که OpenClaw را اجرا می‌کند تنظیم کنید. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -120,9 +120,9 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - اگر OpenClaw از قبل به‌عنوان سرویس پس‌زمینه در حال اجراست، آن را از طریق برنامه Mac مربوط به OpenClaw یا با توقف و راه‌اندازی دوباره فرایند `openclaw gateway run` بازراه‌اندازی کنید. - برای نصب‌های سرویس مدیریت‌شده، `openclaw gateway install` را از پوسته‌ای اجرا کنید که `DISCORD_BOT_TOKEN` در آن وجود دارد، یا متغیر را در `~/.openclaw/.env` ذخیره کنید تا سرویس پس از بازراه‌اندازی بتواند env SecretRef را resolve کند. - اگر میزبان شما توسط جست‌وجوی برنامه هنگام راه‌اندازی Discord مسدود یا rate-limit شده است، شناسه برنامه/کلاینت Discord را از Developer Portal تنظیم کنید تا راه‌اندازی بتواند آن فراخوانی REST را رد کند. برای حساب پیش‌فرض از `channels.discord.applicationId` استفاده کنید، یا وقتی چند ربات Discord اجرا می‌کنید از `channels.discord.accounts..applicationId` استفاده کنید. + اگر OpenClaw از قبل به‌عنوان سرویس پس‌زمینه در حال اجراست، آن را از طریق برنامه Mac مربوط به OpenClaw یا با متوقف‌کردن و راه‌اندازی دوباره فرایند `openclaw gateway run` راه‌اندازی مجدد کنید. + برای نصب‌های سرویس مدیریت‌شده، `openclaw gateway install` را از شلی اجرا کنید که `DISCORD_BOT_TOKEN` در آن موجود است، یا متغیر را در `~/.openclaw/.env` ذخیره کنید تا سرویس بتواند پس از راه‌اندازی مجدد env SecretRef را resolve کند. + اگر میزبان شما توسط lookup برنامه در زمان راه‌اندازی Discord مسدود یا rate-limit شده است، شناسه برنامه/کلاینت Discord را از Developer Portal تنظیم کنید تا راه‌اندازی بتواند آن فراخوانی REST را رد کند. برای حساب پیش‌فرض از `channels.discord.applicationId` استفاده کنید، یا وقتی چند bot در Discord اجرا می‌کنید از `channels.discord.accounts..applicationId` استفاده کنید. @@ -130,12 +130,12 @@ openclaw gateway - در هر کانال موجود (مثلاً Telegram) با عامل OpenClaw خود چت کنید و به آن بگویید. اگر Discord نخستین کانال شماست، به‌جای آن از زبانه CLI / پیکربندی استفاده کنید. + با عامل OpenClaw خود در هر کانال موجود (مثلاً Telegram) چت کنید و به آن بگویید. اگر Discord اولین کانال شماست، به‌جای آن از زبانه CLI / پیکربندی استفاده کنید. - > «توکن ربات Discord خود را از قبل در پیکربندی تنظیم کرده‌ام. لطفاً راه‌اندازی Discord را با User ID `` و Server ID `` تکمیل کن.» + > «من قبلاً توکن bot در Discord را در پیکربندی تنظیم کرده‌ام. لطفاً راه‌اندازی Discord را با User ID `` و Server ID `` تمام کن.» - اگر پیکربندی مبتنی بر فایل را ترجیح می‌دهید، تنظیم کنید: + اگر پیکربندی مبتنی بر فایل را ترجیح می‌دهید، این را تنظیم کنید: ```json5 { @@ -152,15 +152,15 @@ openclaw gateway } ``` - fallback محیطی برای حساب پیش‌فرض: + fallback env برای حساب پیش‌فرض: ```bash DISCORD_BOT_TOKEN=... ``` - برای راه‌اندازی اسکریپتی یا راه‌دور، همان بلوک JSON5 را با `openclaw config patch --file ./discord.patch.json5 --dry-run` بنویسید و سپس بدون `--dry-run` دوباره اجرا کنید. مقادیر متنی ساده `token` پشتیبانی می‌شوند. مقادیر SecretRef نیز برای `channels.discord.token` در providerهای env/file/exec پشتیبانی می‌شوند. [مدیریت رازها](/fa/gateway/secrets) را ببینید. + برای راه‌اندازی اسکریپتی یا راه‌دور، همان بلوک JSON5 را با `openclaw config patch --file ./discord.patch.json5 --dry-run` بنویسید و سپس دوباره بدون `--dry-run` اجرا کنید. مقدارهای plaintext برای `token` پشتیبانی می‌شوند. مقدارهای SecretRef نیز برای `channels.discord.token` در providerهای env/file/exec پشتیبانی می‌شوند. [مدیریت رازها](/fa/gateway/secrets) را ببینید. - برای چند ربات Discord، هر توکن ربات و شناسه برنامه را زیر حساب خودش نگه دارید. `channels.discord.applicationId` سطح بالا توسط حساب‌ها به ارث برده می‌شود، بنابراین فقط زمانی آن را آنجا تنظیم کنید که همه حساب‌ها باید از همان شناسه برنامه استفاده کنند. + برای چند bot در Discord، هر توکن bot و شناسه برنامه را زیر حساب خودش نگه دارید. مقدار سطح‌بالای `channels.discord.applicationId` توسط حساب‌ها به ارث برده می‌شود، بنابراین فقط زمانی آن را در آنجا تنظیم کنید که همه حساب‌ها باید از همان شناسه برنامه استفاده کنند. ```json5 { @@ -187,12 +187,12 @@ DISCORD_BOT_TOKEN=... - - صبر کنید تا Gateway در حال اجرا باشد، سپس در Discord به ربات خود پیام مستقیم بدهید. ربات با یک کد جفت‌سازی پاسخ می‌دهد. + + صبر کنید تا Gateway در حال اجرا باشد، سپس در Discord به bot خود پیام خصوصی بدهید. با یک کد جفت‌سازی پاسخ می‌دهد. - کد جفت‌سازی را در کانال موجود خود به عاملتان بفرستید: + کد جفت‌سازی را در کانال موجود خود برای عاملتان بفرستید: > «این کد جفت‌سازی Discord را تأیید کن: ``» @@ -206,26 +206,26 @@ openclaw pairing approve discord - کدهای جفت‌سازی پس از 1 ساعت منقضی می‌شوند. + کدهای جفت‌سازی پس از ۱ ساعت منقضی می‌شوند. - اکنون باید بتوانید در Discord از طریق پیام مستقیم با عامل خود چت کنید. + اکنون باید بتوانید در Discord از طریق پیام خصوصی با عامل خود چت کنید. -حل توکن نسبت به حساب آگاه است. مقادیر توکن پیکربندی بر fallback محیطی اولویت دارند. `DISCORD_BOT_TOKEN` فقط برای حساب پیش‌فرض استفاده می‌شود. -اگر دو حساب فعال Discord به یک توکن ربات یکسان resolve شوند، OpenClaw فقط یک پایشگر Gateway برای آن توکن راه‌اندازی می‌کند. توکنی که از پیکربندی آمده باشد بر fallback محیطی پیش‌فرض اولویت دارد؛ در غیر این صورت نخستین حساب فعال برنده می‌شود و حساب تکراری به‌عنوان غیرفعال گزارش می‌شود. -برای فراخوانی‌های خروجی پیشرفته (ابزار پیام/اقدام‌های کانال)، یک `token` صریح برای هر فراخوانی برای همان فراخوانی استفاده می‌شود. این برای اقدام‌های ارسال و خواندن/پروب‌مانند اعمال می‌شود (برای مثال read/search/fetch/thread/pins/permissions). تنظیمات سیاست حساب/تلاش مجدد همچنان از حساب انتخاب‌شده در snapshot زمان اجرای فعال می‌آیند. +resolve شدن توکن نسبت به حساب آگاه است. مقدارهای توکن در پیکربندی بر fallback env اولویت دارند. `DISCORD_BOT_TOKEN` فقط برای حساب پیش‌فرض استفاده می‌شود. +اگر دو حساب فعال Discord به یک توکن bot یکسان resolve شوند، OpenClaw فقط یک مانیتور Gateway برای آن توکن شروع می‌کند. توکنِ دارای منبع پیکربندی بر fallback env پیش‌فرض اولویت دارد؛ در غیر این صورت اولین حساب فعال برنده می‌شود و حساب تکراری به‌عنوان غیرفعال گزارش می‌شود. +برای فراخوانی‌های خروجی پیشرفته (ابزار message/اقدام‌های کانال)، یک `token` صریح برای همان فراخوانی استفاده می‌شود. این برای اقدام‌های send و read/probe-style اعمال می‌شود (برای مثال read/search/fetch/thread/pins/permissions). تنظیمات سیاست حساب/تلاش دوباره همچنان از حساب انتخاب‌شده در snapshot زمان اجرای فعال می‌آید. -## توصیه‌شده: راه‌اندازی یک فضای کاری سرور +## توصیه‌شده: راه‌اندازی فضای کاری سرور -پس از کار کردن پیام‌های مستقیم، می‌توانید سرور Discord خود را به‌عنوان یک فضای کاری کامل راه‌اندازی کنید که در آن هر کانال نشست عامل جداگانه خودش را با زمینه خودش دریافت می‌کند. این برای سرورهای خصوصی که فقط شما و رباتتان در آن هستید توصیه می‌شود. +پس از اینکه پیام‌های خصوصی کار کردند، می‌توانید سرور Discord خود را به‌عنوان یک فضای کاری کامل راه‌اندازی کنید که در آن هر کانال جلسه عامل خودش را با context خودش دریافت می‌کند. این برای سرورهای خصوصی که فقط شما و bot شما در آن هستید توصیه می‌شود. - - این کار به عامل شما امکان می‌دهد در هر کانالی در سرورتان پاسخ دهد، نه فقط در پیام‌های مستقیم. + + این کار به عامل شما امکان می‌دهد در هر کانالی روی سرورتان پاسخ دهد، نه فقط پیام‌های خصوصی. @@ -254,16 +254,16 @@ openclaw pairing approve discord - - به‌طور پیش‌فرض، عامل شما در کانال‌های سرور فقط وقتی @mention شود پاسخ می‌دهد. برای یک سرور خصوصی، احتمالاً می‌خواهید به هر پیام پاسخ دهد. + + به‌طور پیش‌فرض، عامل شما فقط وقتی در کانال‌های سرور پاسخ می‌دهد که @mention شود. برای یک سرور خصوصی، احتمالاً می‌خواهید به هر پیام پاسخ دهد. - در کانال‌های سرور، پاسخ‌های نهایی معمول دستیار به‌طور پیش‌فرض خصوصی می‌مانند. خروجی قابل مشاهده Discord باید به‌صراحت با ابزار `message` ارسال شود، بنابراین عامل می‌تواند به‌طور پیش‌فرض در سکوت بماند و فقط وقتی تصمیم می‌گیرد پاسخ کانال مفید است پست کند. + در کانال‌های سرور، پاسخ‌های نهایی معمول assistant به‌طور پیش‌فرض خصوصی می‌مانند. خروجی قابل‌مشاهده Discord باید به‌صراحت با ابزار `message` ارسال شود، تا عامل بتواند به‌طور پیش‌فرض در سکوت مشاهده کند و فقط وقتی تصمیم می‌گیرد پاسخ کانال مفید است پست بگذارد. - این یعنی مدل انتخاب‌شده باید با اطمینان ابزارها را فراخوانی کند. اگر Discord در حال تایپ نشان می‌دهد و گزارش‌ها مصرف توکن را نشان می‌دهند اما پیامی پست نشده است، گزارش نشست را برای متن دستیار با `didSendViaMessagingTool: false` بررسی کنید. این یعنی مدل به‌جای فراخوانی `message(action=send)` یک پاسخ نهایی خصوصی تولید کرده است. به یک مدل قوی‌تر در فراخوانی ابزارها تغییر دهید، یا از پیکربندی زیر برای بازگرداندن پاسخ‌های نهایی خودکار قدیمی استفاده کنید. + این یعنی مدل انتخاب‌شده باید ابزارها را با اطمینان فراخوانی کند. اگر Discord وضعیت تایپ‌کردن نشان می‌دهد و لاگ‌ها مصرف توکن را نشان می‌دهند اما پیامی پست نشده است، لاگ جلسه را برای متن assistant با `didSendViaMessagingTool: false` بررسی کنید. این یعنی مدل به‌جای فراخوانی `message(action=send)` یک پاسخ نهایی خصوصی تولید کرده است. به یک مدل قوی‌تر در فراخوانی ابزار تغییر دهید، یا از پیکربندی زیر برای بازگرداندن پاسخ‌های نهایی خودکار قدیمی استفاده کنید. - > «به عامل من اجازه بده در این سرور بدون اینکه لازم باشد @mention شود پاسخ دهد» + > «به عامل من اجازه بده بدون اینکه لازم باشد @mention شود، روی این سرور پاسخ دهد» در پیکربندی سرور خود `requireMention: false` را تنظیم کنید: @@ -290,85 +290,90 @@ openclaw pairing approve discord - به‌طور پیش‌فرض، حافظه بلندمدت (MEMORY.md) فقط در نشست‌های پیام مستقیم بارگذاری می‌شود. کانال‌های سرور MEMORY.md را به‌صورت خودکار بارگذاری نمی‌کنند. + به‌طور پیش‌فرض، حافظه بلندمدت (MEMORY.md) فقط در جلسه‌های پیام خصوصی بارگذاری می‌شود. کانال‌های سرور MEMORY.md را به‌طور خودکار بارگذاری نمی‌کنند. - > «وقتی در کانال‌های Discord سؤال می‌پرسم، اگر برای زمینه بلندمدت از MEMORY.md نیاز داری، از memory_search یا memory_get استفاده کن.» + > «وقتی در کانال‌های Discord سؤال می‌پرسم، اگر برای context بلندمدت از MEMORY.md نیاز داشتی، از memory_search یا memory_get استفاده کن.» - اگر در هر کانال به زمینه مشترک نیاز دارید، دستورالعمل‌های پایدار را در `AGENTS.md` یا `USER.md` بگذارید (برای هر نشست تزریق می‌شوند). یادداشت‌های بلندمدت را در `MEMORY.md` نگه دارید و در صورت نیاز با ابزارهای حافظه به آن‌ها دسترسی پیدا کنید. + اگر در هر کانال به context مشترک نیاز دارید، دستورالعمل‌های پایدار را در `AGENTS.md` یا `USER.md` بگذارید (آن‌ها برای هر جلسه تزریق می‌شوند). یادداشت‌های بلندمدت را در `MEMORY.md` نگه دارید و هنگام نیاز با ابزارهای حافظه به آن‌ها دسترسی پیدا کنید. -اکنون چند کانال در سرور Discord خود بسازید و شروع به چت کنید. عامل شما می‌تواند نام کانال را ببیند، و هر کانال نشست جداگانه ایزوله خودش را دریافت می‌کند — بنابراین می‌توانید `#coding`، `#home`، `#research` یا هر چیزی را که با جریان کاری شما سازگار است راه‌اندازی کنید. +اکنون چند کانال در سرور Discord خود بسازید و چت را شروع کنید. عامل شما می‌تواند نام کانال را ببیند، و هر کانال جلسه جداافتاده خودش را دریافت می‌کند — بنابراین می‌توانید `#coding`، `#home`، `#research` یا هر چیزی را که با گردش‌کار شما سازگار است راه‌اندازی کنید. ## مدل زمان اجرا - Gateway مالک اتصال Discord است. -- مسیریابی پاسخ قطعی است: پاسخ‌های ورودی Discord دوباره به Discord برمی‌گردند. -- فراداده سرور/کانال Discord به‌عنوان زمینه غیرقابل‌اعتماد به اعلان مدل اضافه می‌شود، نه به‌عنوان پیشوند پاسخ قابل‌مشاهده برای کاربر. اگر مدلی آن پوشش را دوباره کپی کند، OpenClaw فراداده کپی‌شده را از پاسخ‌های خروجی و از زمینه بازپخش آینده حذف می‌کند. -- به‌صورت پیش‌فرض (`session.dmScope=main`)، گفت‌وگوهای مستقیم نشست اصلی عامل را به اشتراک می‌گذارند (`agent:main:main`). -- کانال‌های سرور از کلیدهای نشست ایزوله استفاده می‌کنند (`agent::discord:channel:`). -- پیام‌های مستقیم گروهی به‌صورت پیش‌فرض نادیده گرفته می‌شوند (`channels.discord.dm.groupEnabled=false`). -- فرمان‌های اسلش بومی در نشست‌های فرمان ایزوله اجرا می‌شوند (`agent::discord:slash:`)، در حالی که همچنان `CommandTargetSessionKey` را به نشست گفت‌وگوی مسیریابی‌شده حمل می‌کنند. -- تحویل اعلان cron/heartbeat فقط‌متنی به Discord یک‌بار از پاسخ نهایی قابل‌مشاهده برای دستیار استفاده می‌کند. payloadهای رسانه‌ای و مؤلفه‌های ساختاریافته وقتی عامل چند payload قابل‌تحویل تولید می‌کند، همچنان چندپیامی باقی می‌مانند. +- مسیریابی پاسخ قطعی است: پاسخ‌های ورودی Discord به Discord برمی‌گردند. +- فرادادهٔ guild/channel مربوط به Discord به‌عنوان زمینهٔ نامطمئن به پرامپت مدل اضافه می‌شود، + نه به‌عنوان پیشوند پاسخ قابل مشاهده برای کاربر. اگر مدلی آن پوشش را + بازنویسی کند، OpenClaw فرادادهٔ کپی‌شده را از پاسخ‌های خروجی و از + زمینهٔ بازپخش آینده حذف می‌کند. +- به‌صورت پیش‌فرض (`session.dmScope=main`)، چت‌های مستقیم نشست اصلی عامل را به اشتراک می‌گذارند (`agent:main:main`). +- کانال‌های Guild کلیدهای نشست جداگانه دارند (`agent::discord:channel:`). +- DMهای گروهی به‌صورت پیش‌فرض نادیده گرفته می‌شوند (`channels.discord.dm.groupEnabled=false`). +- فرمان‌های slash بومی در نشست‌های فرمان جداگانه اجرا می‌شوند (`agent::discord:slash:`)، در حالی که همچنان `CommandTargetSessionKey` را به نشست گفت‌وگوی مسیریابی‌شده حمل می‌کنند. +- تحویل اعلان‌های متنی cron/heartbeat به Discord از پاسخ نهایی + قابل مشاهده برای دستیار، یک بار استفاده می‌کند. محموله‌های رسانه‌ای و مؤلفه‌های ساخت‌یافته + وقتی عامل چند محمولهٔ قابل تحویل منتشر می‌کند، همچنان چندپیامی می‌مانند. ## کانال‌های انجمن -کانال‌های انجمن و رسانه Discord فقط پست‌های thread را می‌پذیرند. OpenClaw از دو روش برای ایجاد آن‌ها پشتیبانی می‌کند: +کانال‌های انجمن و رسانهٔ Discord فقط پست‌های رشته‌ای را می‌پذیرند. OpenClaw از دو روش برای ساخت آن‌ها پشتیبانی می‌کند: -- پیامی به والد انجمن (`channel:`) بفرستید تا یک thread به‌صورت خودکار ایجاد شود. عنوان thread از اولین خط غیرخالی پیام شما استفاده می‌کند. -- از `openclaw message thread create` برای ایجاد مستقیم thread استفاده کنید. برای کانال‌های انجمن، `--message-id` را ارسال نکنید. +- پیامی به والد انجمن (`channel:`) بفرستید تا یک رشته به‌صورت خودکار ساخته شود. عنوان رشته از نخستین خط غیرخالی پیام شما استفاده می‌کند. +- از `openclaw message thread create` برای ساخت مستقیم یک رشته استفاده کنید. برای کانال‌های انجمن `--message-id` را ارسال نکنید. -نمونه: ارسال به والد انجمن برای ایجاد thread +مثال: ارسال به والد انجمن برای ساخت یک رشته ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -نمونه: ایجاد صریح یک thread انجمن +مثال: ساخت صریح یک رشتهٔ انجمن ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -والدهای انجمن مؤلفه‌های Discord را نمی‌پذیرند. اگر به مؤلفه‌ها نیاز دارید، به خود thread ارسال کنید (`channel:`). +والدهای انجمن مؤلفه‌های Discord را نمی‌پذیرند. اگر به مؤلفه‌ها نیاز دارید، به خود رشته (`channel:`) ارسال کنید. ## مؤلفه‌های تعاملی -OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پیام‌های عامل پشتیبانی می‌کند. از ابزار پیام با payload به‌نام `components` استفاده کنید. نتایج تعامل به‌عنوان پیام‌های ورودی عادی دوباره به عامل مسیریابی می‌شوند و از تنظیمات موجود `replyToMode` در Discord پیروی می‌کنند. +OpenClaw از کانتینرهای مؤلفهٔ v2 در Discord برای پیام‌های عامل پشتیبانی می‌کند. از ابزار پیام با محمولهٔ `components` استفاده کنید. نتایج تعامل به‌صورت پیام‌های ورودی عادی به عامل مسیریابی می‌شوند و تنظیمات موجود Discord برای `replyToMode` را دنبال می‌کنند. بلوک‌های پشتیبانی‌شده: - `text`, `section`, `separator`, `actions`, `media-gallery`, `file` -- ردیف‌های کنش تا ۵ دکمه یا یک منوی انتخاب واحد را مجاز می‌کنند +- ردیف‌های اقدام تا ۵ دکمه یا یک منوی انتخاب واحد را مجاز می‌کنند - نوع‌های انتخاب: `string`, `user`, `role`, `mentionable`, `channel` -به‌صورت پیش‌فرض، مؤلفه‌ها یک‌بارمصرف هستند. برای اجازه دادن به استفاده چندباره از دکمه‌ها، انتخاب‌ها و فرم‌ها تا زمان انقضای آن‌ها، `components.reusable=true` را تنظیم کنید. +به‌صورت پیش‌فرض، مؤلفه‌ها یک‌بارمصرف هستند. برای اینکه دکمه‌ها، انتخاب‌گرها و فرم‌ها تا زمان انقضا چند بار قابل استفاده باشند، `components.reusable=true` را تنظیم کنید. -برای محدود کردن کسانی که می‌توانند روی یک دکمه کلیک کنند، `allowedUsers` را روی آن دکمه تنظیم کنید (شناسه‌های کاربری Discord، برچسب‌ها، یا `*`). وقتی پیکربندی شده باشد، کاربران نامطابق یک رد موقت دریافت می‌کنند. +برای محدود کردن افرادی که می‌توانند روی دکمه کلیک کنند، `allowedUsers` را روی آن دکمه تنظیم کنید (شناسه‌های کاربر Discord، برچسب‌ها، یا `*`). وقتی پیکربندی شده باشد، کاربران نامنطبق یک رد موقت دریافت می‌کنند. -فرمان‌های اسلش `/model` و `/models` یک انتخابگر تعاملی مدل را با فهرست‌های کشویی ارائه‌دهنده، مدل و runtime سازگار، به‌همراه مرحله Submit باز می‌کنند. `/models add` منسوخ شده است و اکنون به‌جای ثبت مدل‌ها از چت، پیام منسوخ‌شدن برمی‌گرداند. پاسخ انتخابگر موقت است و فقط کاربر فراخواننده می‌تواند از آن استفاده کند. +فرمان‌های slash با نام‌های `/model` و `/models` یک انتخاب‌گر تعاملی مدل را با منوهای کشویی provider، مدل، و runtime سازگار به‌همراه مرحلهٔ Submit باز می‌کنند. `/models add` منسوخ شده و اکنون به‌جای ثبت مدل‌ها از چت، پیام منسوخ‌شدن برمی‌گرداند. پاسخ انتخاب‌گر موقت است و فقط کاربر فراخواننده می‌تواند از آن استفاده کند. پیوست‌های فایل: -- بلوک‌های `file` باید به یک مرجع پیوست اشاره کنند (`attachment://`) -- پیوست را از طریق `media`/`path`/`filePath` ارائه کنید (فایل واحد)؛ برای چند فایل از `media-gallery` استفاده کنید -- وقتی نام بارگذاری باید با مرجع پیوست مطابقت داشته باشد، از `filename` برای بازنویسی نام استفاده کنید +- بلوک‌های `file` باید به یک ارجاع پیوست اشاره کنند (`attachment://`) +- پیوست را از طریق `media`/`path`/`filePath` ارائه کنید (یک فایل)؛ برای چند فایل از `media-gallery` استفاده کنید +- وقتی نام بارگذاری باید با ارجاع پیوست مطابقت داشته باشد، از `filename` برای بازنویسی نام استفاده کنید -فرم‌های مودال: +فرم‌های Modal: - `components.modal` را با حداکثر ۵ فیلد اضافه کنید - نوع‌های فیلد: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- OpenClaw به‌صورت خودکار یک دکمه محرک اضافه می‌کند +- OpenClaw به‌صورت خودکار یک دکمهٔ راه‌انداز اضافه می‌کند -نمونه: +مثال: ```json5 { @@ -426,37 +431,37 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - `channels.discord.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.discord.allowFrom` allowlist رسمی DM است. + `channels.discord.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.discord.allowFrom` فهرست مجاز canonical برای DM است. - `pairing` (پیش‌فرض) - `allowlist` - - `open` (نیازمند این است که `channels.discord.allowFrom` شامل `"*"` باشد) + - `open` (نیاز دارد `channels.discord.allowFrom` شامل `"*"` باشد) - `disabled` - اگر سیاست DM باز نباشد، کاربران ناشناخته مسدود می‌شوند (یا در حالت `pairing` برای جفت‌سازی راهنمایی می‌شوند). + اگر سیاست DM باز نباشد، کاربران ناشناس مسدود می‌شوند (یا در حالت `pairing` برای جفت‌سازی راهنمایی می‌شوند). - تقدم چندحسابی: + اولویت در چندحسابی: - - `channels.discord.accounts.default.allowFrom` فقط روی حساب `default` اعمال می‌شود. - - برای یک حساب، `allowFrom` بر `dm.allowFrom` قدیمی تقدم دارد. + - `channels.discord.accounts.default.allowFrom` فقط برای حساب `default` اعمال می‌شود. + - برای یک حساب، `allowFrom` بر `dm.allowFrom` قدیمی اولویت دارد. - حساب‌های نام‌دار وقتی `allowFrom` خودشان و `dm.allowFrom` قدیمی تنظیم نشده باشند، `channels.discord.allowFrom` را به ارث می‌برند. - حساب‌های نام‌دار `channels.discord.accounts.default.allowFrom` را به ارث نمی‌برند. `channels.discord.dm.policy` و `channels.discord.dm.allowFrom` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` مهاجرت می‌دهد. - قالب مقصد DM برای تحویل: + قالب هدف DM برای تحویل: - `user:` - - اشاره `<@id>` + - اشارهٔ `<@id>` - شناسه‌های عددی خام معمولاً وقتی پیش‌فرض کانال فعال است به‌عنوان شناسه‌های کانال resolve می‌شوند، اما شناسه‌هایی که در `allowFrom` مؤثر DM حساب فهرست شده‌اند، برای سازگاری به‌عنوان مقصدهای DM کاربر در نظر گرفته می‌شوند. + شناسه‌های عددی بدون پیشوند، وقتی پیش‌فرض کانال فعال باشد، معمولاً به‌عنوان شناسهٔ کانال resolve می‌شوند، اما شناسه‌های فهرست‌شده در `allowFrom` مؤثر DM حساب، برای سازگاری به‌عنوان هدف‌های DM کاربر در نظر گرفته می‌شوند. - DMهای Discord می‌توانند از مدخل‌های پویا `accessGroup:` در `channels.discord.allowFrom` استفاده کنند. + DMهای Discord می‌توانند از ورودی‌های پویای `accessGroup:` در `channels.discord.allowFrom` استفاده کنند. - نام‌های گروه دسترسی بین کانال‌های پیام مشترک هستند. برای یک گروه ایستا که اعضایش با نحو عادی `allowFrom` هر کانال بیان می‌شوند، از `type: "message.senders"` استفاده کنید، یا وقتی مخاطبان فعلی `ViewChannel` یک کانال Discord باید عضویت را به‌صورت پویا تعریف کنند، از `type: "discord.channelAudience"` استفاده کنید. رفتار مشترک گروه دسترسی اینجا مستند شده است: [گروه‌های دسترسی](/fa/channels/access-groups). + نام‌های گروه دسترسی بین کانال‌های پیام مشترک‌اند. برای یک گروه ایستا که اعضایش در نحو عادی `allowFrom` هر کانال بیان می‌شوند، از `type: "message.senders"` استفاده کنید، یا وقتی مخاطبان فعلی `ViewChannel` یک کانال Discord باید عضویت را به‌صورت پویا تعریف کنند، از `type: "discord.channelAudience"` استفاده کنید. رفتار مشترک access-group اینجا مستند شده است: [گروه‌های دسترسی](/fa/channels/access-groups). ```json5 { @@ -479,9 +484,9 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - یک کانال متنی Discord فهرست اعضای جداگانه‌ای ندارد. `type: "discord.channelAudience"` عضویت را این‌گونه مدل می‌کند: فرستنده DM عضو سرور پیکربندی‌شده است و پس از اعمال بازنویسی‌های نقش و کانال، در حال حاضر مجوز مؤثر `ViewChannel` روی کانال پیکربندی‌شده دارد. + یک کانال متنی Discord فهرست اعضای جداگانه ندارد. `type: "discord.channelAudience"` عضویت را این‌گونه مدل می‌کند: فرستندهٔ DM عضو guild پیکربندی‌شده است و در حال حاضر پس از اعمال بازنویسی‌های نقش و کانال، مجوز مؤثر `ViewChannel` را روی کانال پیکربندی‌شده دارد. - نمونه: اجازه دهید هر کسی که می‌تواند `#maintainers` را ببیند به bot پیام مستقیم بدهد، در حالی که DMها برای بقیه بسته می‌مانند. + مثال: به هر کسی که می‌تواند `#maintainers` را ببیند اجازه دهید به ربات DM بدهد، در حالی که DMها برای همهٔ افراد دیگر بسته می‌مانند. ```json5 { @@ -502,7 +507,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - می‌توانید مدخل‌های پویا و ایستا را ترکیب کنید: + می‌توانید ورودی‌های پویا و ایستا را ترکیب کنید: ```json5 { @@ -522,31 +527,31 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - جست‌وجوها در صورت شکست بسته می‌مانند. اگر Discord مقدار `Missing Access` را برگرداند، جست‌وجوی عضو شکست بخورد، یا کانال به سرور دیگری تعلق داشته باشد، فرستنده DM غیرمجاز در نظر گرفته می‌شود. + جست‌وجوها در حالت خطا بسته می‌شوند. اگر Discord مقدار `Missing Access` برگرداند، جست‌وجوی عضو شکست بخورد، یا کانال به guild دیگری تعلق داشته باشد، فرستندهٔ DM غیرمجاز در نظر گرفته می‌شود. - هنگام استفاده از گروه‌های دسترسی مبتنی بر مخاطبان کانال، **Server Members Intent** را در Discord Developer Portal برای bot فعال کنید. DMها وضعیت عضو سرور را شامل نمی‌شوند، بنابراین OpenClaw در زمان مجوزدهی عضو را از طریق REST مربوط به Discord resolve می‌کند. + هنگام استفاده از گروه‌های دسترسی channel-audience، **Server Members Intent** را برای ربات در Discord Developer Portal فعال کنید. DMها وضعیت عضو guild را شامل نمی‌شوند، بنابراین OpenClaw در زمان مجوزدهی عضو را از طریق Discord REST resolve می‌کند. - - مدیریت سرور با `channels.discord.groupPolicy` کنترل می‌شود: + + مدیریت Guild توسط `channels.discord.groupPolicy` کنترل می‌شود: - `open` - `allowlist` - `disabled` - خط مبنای امن وقتی `channels.discord` وجود دارد، `allowlist` است. + خط پایهٔ امن وقتی `channels.discord` وجود دارد، `allowlist` است. رفتار `allowlist`: - - سرور باید با `channels.discord.guilds` مطابقت داشته باشد (`id` ترجیح داده می‌شود، slug پذیرفته می‌شود) - - allowlistهای اختیاری فرستنده: `users` (شناسه‌های پایدار توصیه می‌شوند) و `roles` (فقط شناسه‌های نقش)؛ اگر هرکدام پیکربندی شده باشد، فرستنده‌ها وقتی با `users` یا `roles` مطابقت داشته باشند مجاز می‌شوند + - guild باید با `channels.discord.guilds` مطابقت داشته باشد (`id` ترجیح داده می‌شود، slug پذیرفته می‌شود) + - فهرست‌های مجاز اختیاری فرستنده: `users` (شناسه‌های پایدار توصیه می‌شوند) و `roles` (فقط شناسه‌های نقش)؛ اگر هرکدام پیکربندی شده باشد، فرستندگان وقتی با `users` یا `roles` مطابقت داشته باشند مجازند - تطبیق مستقیم نام/برچسب به‌صورت پیش‌فرض غیرفعال است؛ `channels.discord.dangerouslyAllowNameMatching: true` را فقط به‌عنوان حالت سازگاری اضطراری فعال کنید - - نام‌ها/برچسب‌ها برای `users` پشتیبانی می‌شوند، اما شناسه‌ها امن‌ترند؛ وقتی مدخل‌های نام/برچسب استفاده شوند، `openclaw security audit` هشدار می‌دهد - - اگر یک سرور `channels` پیکربندی‌شده داشته باشد، کانال‌های فهرست‌نشده رد می‌شوند - - اگر یک سرور بلوک `channels` نداشته باشد، همه کانال‌ها در آن سرور allowlistشده مجاز هستند + - نام‌ها/برچسب‌ها برای `users` پشتیبانی می‌شوند، اما شناسه‌ها امن‌ترند؛ `openclaw security audit` هنگام استفاده از ورودی‌های نام/برچسب هشدار می‌دهد + - اگر یک guild دارای `channels` پیکربندی‌شده باشد، کانال‌های فهرست‌نشده رد می‌شوند + - اگر یک guild بلوک `channels` نداشته باشد، همهٔ کانال‌های آن guild مجازشمرده‌شده اجازه دارند - نمونه: + مثال: ```json5 { @@ -570,35 +575,35 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - اگر فقط `DISCORD_BOT_TOKEN` را تنظیم کنید و بلوک `channels.discord` نسازید، fallback زمان اجرا `groupPolicy="allowlist"` خواهد بود (با یک هشدار در لاگ‌ها)، حتی اگر `channels.defaults.groupPolicy` برابر `open` باشد. + اگر فقط `DISCORD_BOT_TOKEN` را تنظیم کنید و بلوک `channels.discord` نسازید، fallback زمان اجرا `groupPolicy="allowlist"` است (با هشدار در لاگ‌ها)، حتی اگر `channels.defaults.groupPolicy` برابر `open` باشد. - پیام‌های سرور به‌صورت پیش‌فرض با اشاره gate می‌شوند. + پیام‌های Guild به‌صورت پیش‌فرض پشت دروازهٔ اشاره قرار دارند. - تشخیص اشاره شامل این موارد است: + تشخیص اشاره شامل موارد زیر است: - - اشاره صریح به bot - - الگوهای اشاره پیکربندی‌شده (`agents.list[].groupChat.mentionPatterns`، fallback با `messages.groupChat.mentionPatterns`) - - رفتار ضمنی پاسخ‌به-bot در موارد پشتیبانی‌شده + - اشارهٔ صریح به ربات + - الگوهای اشارهٔ پیکربندی‌شده (`agents.list[].groupChat.mentionPatterns`، fallback با `messages.groupChat.mentionPatterns`) + - رفتار ضمنی پاسخ به ربات در موارد پشتیبانی‌شده - هنگام نوشتن پیام‌های خروجی Discord، از نحو اشاره رسمی استفاده کنید: `<@USER_ID>` برای کاربران، `<#CHANNEL_ID>` برای کانال‌ها، و `<@&ROLE_ID>` برای نقش‌ها. از فرم اشاره نام مستعار قدیمی `<@!USER_ID>` استفاده نکنید. + هنگام نوشتن پیام‌های خروجی Discord، از نحو canonical اشاره استفاده کنید: `<@USER_ID>` برای کاربران، `<#CHANNEL_ID>` برای کانال‌ها، و `<@&ROLE_ID>` برای نقش‌ها. از فرم اشارهٔ قدیمی nickname یعنی `<@!USER_ID>` استفاده نکنید. - `requireMention` برای هر سرور/کانال پیکربندی می‌شود (`channels.discord.guilds...`). - `ignoreOtherMentions` به‌صورت اختیاری پیام‌هایی را که به کاربر/نقش دیگری اشاره می‌کنند اما به bot اشاره نمی‌کنند حذف می‌کند (به‌جز @everyone/@here). + `requireMention` برای هر guild/channel پیکربندی می‌شود (`channels.discord.guilds...`). + `ignoreOtherMentions` به‌صورت اختیاری پیام‌هایی را که به کاربر/نقش دیگری اشاره می‌کنند اما به ربات اشاره ندارند حذف می‌کند (به‌جز @everyone/@here). DMهای گروهی: - پیش‌فرض: نادیده گرفته می‌شوند (`dm.groupEnabled=false`) - - allowlist اختیاری از طریق `dm.groupChannels` (شناسه‌ها یا slugهای کانال) + - فهرست مجاز اختیاری از طریق `dm.groupChannels` (شناسه‌های کانال یا slugها) -### مسیریابی عامل بر پایه نقش +### مسیریابی عامل بر پایهٔ نقش -از `bindings[].match.roles` برای مسیریابی اعضای سرور Discord به عامل‌های مختلف بر اساس شناسه نقش استفاده کنید. bindingهای مبتنی بر نقش فقط شناسه‌های نقش را می‌پذیرند و پس از bindingهای peer یا parent-peer و پیش از bindingهای فقط-سرور ارزیابی می‌شوند. اگر یک binding فیلدهای تطبیق دیگری هم تنظیم کند (برای مثال `peer` + `guildId` + `roles`)، همه فیلدهای پیکربندی‌شده باید مطابقت داشته باشند. +از `bindings[].match.roles` برای مسیریابی اعضای guild در Discord به عامل‌های مختلف بر اساس شناسهٔ نقش استفاده کنید. bindingهای مبتنی بر نقش فقط شناسه‌های نقش را می‌پذیرند و پس از bindingهای peer یا parent-peer و پیش از bindingهای فقط-guild ارزیابی می‌شوند. اگر یک binding فیلدهای match دیگری هم تنظیم کند (برای مثال `peer` + `guildId` + `roles`)، همهٔ فیلدهای پیکربندی‌شده باید مطابقت داشته باشند. ```json5 { @@ -624,11 +629,11 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی ## فرمان‌های بومی و احراز هویت فرمان -- `commands.native` به‌طور پیش‌فرض روی `"auto"` است و برای Discord فعال می‌شود. -- بازنویسی مخصوص هر کانال: `channels.discord.commands.native`. -- `commands.native=false` ثبت و پاک‌سازی دستورهای اسلش Discord را هنگام راه‌اندازی رد می‌کند. دستورهایی که قبلاً ثبت شده‌اند ممکن است تا زمانی که آن‌ها را از برنامه Discord حذف نکنید، همچنان در Discord قابل مشاهده بمانند. +- `commands.native` به‌طور پیش‌فرض `"auto"` است و برای Discord فعال است. +- بازنویسی برای هر کانال: `channels.discord.commands.native`. +- `commands.native=false` ثبت و پاک‌سازی دستورهای اسلش Discord را هنگام راه‌اندازی رد می‌کند. دستورهایی که قبلاً ثبت شده‌اند ممکن است تا زمانی که آن‌ها را از برنامه Discord حذف کنید، همچنان در Discord قابل مشاهده بمانند. - احراز هویت دستور بومی از همان فهرست‌های مجاز/سیاست‌های Discord استفاده می‌کند که پردازش عادی پیام استفاده می‌کند. -- دستورها ممکن است همچنان در UI Discord برای کاربرانی که مجاز نیستند قابل مشاهده باشند؛ اجرا همچنان احراز هویت OpenClaw را اعمال می‌کند و "not authorized" برمی‌گرداند. +- دستورها ممکن است همچنان در رابط کاربری Discord برای کاربرانی که مجاز نیستند دیده شوند؛ اجرا همچنان احراز هویت OpenClaw را اعمال می‌کند و "not authorized" برمی‌گرداند. برای فهرست دستورها و رفتار، [دستورهای اسلش](/fa/tools/slash-commands) را ببینید. @@ -636,7 +641,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - `ephemeral: true` -## جزئیات ویژگی +## جزئیات قابلیت @@ -652,21 +657,21 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - `all` - `batched` - نکته: `off` رشته‌سازی پاسخ ضمنی را غیرفعال می‌کند. برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. - `first` همیشه ارجاع پاسخ بومی ضمنی را به نخستین پیام خروجی Discord برای آن نوبت متصل می‌کند. - `batched` فقط زمانی ارجاع پاسخ بومی ضمنی Discord را متصل می‌کند که - نوبت ورودی یک دسته debounce‌شده از چند پیام بوده باشد. این زمانی مفید است - که پاسخ‌های بومی را عمدتاً برای گفتگوهای جهشی و مبهم می‌خواهید، نه هر + نکته: `off` رشته‌سازی ضمنی پاسخ را غیرفعال می‌کند. برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. + `first` همیشه ارجاع پاسخ بومی ضمنی را به اولین پیام خروجی Discord برای نوبت وصل می‌کند. + `batched` فقط وقتی ارجاع پاسخ بومی ضمنی Discord را وصل می‌کند که + نوبت ورودی یک دسته debounce‌شده از چند پیام باشد. این زمانی مفید است + که پاسخ‌های بومی را عمدتاً برای گفت‌وگوهای انفجاری و مبهم می‌خواهید، نه برای هر نوبت تک‌پیامی. - شناسه‌های پیام در بافت/تاریخچه نمایان می‌شوند تا عامل‌ها بتوانند پیام‌های مشخصی را هدف بگیرند. + شناسه‌های پیام در زمینه/تاریخچه آشکار می‌شوند تا عامل‌ها بتوانند پیام‌های مشخصی را هدف بگیرند. - - OpenClaw می‌تواند با ارسال یک پیام موقت و ویرایش آن هنگام رسیدن متن، پاسخ‌های پیش‌نویس را پخش کند. `channels.discord.streaming` مقادیر `off` (پیش‌فرض) | `partial` | `block` | `progress` را می‌پذیرد. `progress` یک پیش‌نویس وضعیت قابل ویرایش را نگه می‌دارد و آن را تا تحویل نهایی با پیشرفت ابزار به‌روزرسانی می‌کند؛ `streamMode` یک نام مستعار قدیمی است و به‌صورت خودکار مهاجرت داده می‌شود. + + OpenClaw می‌تواند پاسخ‌های پیش‌نویس را با ارسال یک پیام موقت و ویرایش آن هنگام رسیدن متن، به‌صورت جریانی ارسال کند. `channels.discord.streaming` مقدارهای `off` (پیش‌فرض) | `partial` | `block` | `progress` را می‌پذیرد. `progress` یک پیش‌نویس وضعیت قابل ویرایش را نگه می‌دارد و آن را تا تحویل نهایی با پیشرفت ابزار به‌روزرسانی می‌کند؛ `streamMode` یک نام مستعار قدیمی است و به‌طور خودکار مهاجرت داده می‌شود. - مقدار پیش‌فرض `off` می‌ماند چون ویرایش‌های پیش‌نمایش Discord وقتی چند بات یا Gateway یک حساب را به اشتراک می‌گذارند، سریعاً به محدودیت نرخ می‌خورند. + مقدار پیش‌فرض `off` باقی می‌ماند، چون ویرایش‌های پیش‌نمایش Discord وقتی چند ربات یا Gateway یک حساب را به اشتراک می‌گذارند به‌سرعت با محدودیت نرخ برخورد می‌کند. ```json5 { @@ -684,22 +689,41 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی ``` - `partial` هنگام رسیدن توکن‌ها یک پیام پیش‌نمایش واحد را ویرایش می‌کند. - - `block` قطعه‌هایی به اندازه پیش‌نویس منتشر می‌کند (برای تنظیم اندازه و نقاط شکست از `draftChunk` استفاده کنید، با محدود شدن به `textChunkLimit`). - - رسانه، خطا، و نهایی‌های پاسخ صریح، ویرایش‌های پیش‌نمایش در انتظار را لغو می‌کنند. + - `block` تکه‌هایی به اندازه پیش‌نویس منتشر می‌کند (برای تنظیم اندازه و نقاط شکست از `draftChunk` استفاده کنید، که به `textChunkLimit` محدود می‌شود). + - رسانه، خطا، و نهایی‌های پاسخ صریح ویرایش‌های پیش‌نمایش در انتظار را لغو می‌کنند. - `streaming.preview.toolProgress` (پیش‌فرض `true`) کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از پیام پیش‌نمایش دوباره استفاده کنند یا نه. + - `streaming.preview.commandText` / `streaming.progress.commandText` جزئیات دستور/اجرا را در خطوط پیشرفت فشرده کنترل می‌کند: `raw` (پیش‌فرض) یا `status` (فقط برچسب ابزار). - پخش پیش‌نمایش فقط متنی است؛ پاسخ‌های رسانه‌ای به تحویل عادی برمی‌گردند. وقتی پخش `block` صریحاً فعال باشد، OpenClaw برای جلوگیری از پخش دوباره، جریان پیش‌نمایش را رد می‌کند. + متن خام دستور/اجرا را پنهان کنید، درحالی‌که خطوط پیشرفت فشرده حفظ می‌شوند: + + ```json + { + "channels": { + "discord": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + جریان پیش‌نمایش فقط متنی است؛ پاسخ‌های رسانه‌ای به تحویل عادی برمی‌گردند. وقتی جریان `block` صراحتاً فعال باشد، OpenClaw برای جلوگیری از جریان‌دهی دوباره، جریان پیش‌نمایش را رد می‌کند. - - بافت تاریخچه انجمن: + + زمینه تاریخچه انجمن: - - مقدار پیش‌فرض `channels.discord.historyLimit` برابر `20` + - پیش‌فرض `channels.discord.historyLimit` برابر `20` - جایگزین: `messages.groupChat.historyLimit` - `0` غیرفعال می‌کند - کنترل‌های تاریخچه DM: + کنترل‌های تاریخچه پیام مستقیم: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` @@ -707,25 +731,25 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی رفتار رشته: - رشته‌های Discord به‌عنوان نشست‌های کانال مسیریابی می‌شوند و پیکربندی کانال والد را به ارث می‌برند مگر اینکه بازنویسی شده باشد. - - نشست‌های رشته انتخاب `/model` سطح نشست کانال والد را فقط به‌عنوان جایگزین مدل به ارث می‌برند؛ انتخاب‌های `/model` محلی رشته همچنان اولویت دارند و تاریخچه رونوشت والد کپی نمی‌شود مگر اینکه ارث‌بری رونوشت فعال باشد. - - `channels.discord.thread.inheritParent` (پیش‌فرض `false`) رشته‌های خودکار جدید را برای seed شدن از رونوشت والد فعال می‌کند. بازنویسی‌های هر حساب زیر `channels.discord.accounts..thread.inheritParent` قرار دارند. - - واکنش‌های ابزار پیام می‌توانند هدف‌های DM به شکل `user:` را حل کنند. + - نشست‌های رشته انتخاب `/model` در سطح نشست کانال والد را فقط به‌عنوان جایگزین مدل به ارث می‌برند؛ انتخاب‌های `/model` محلی رشته همچنان اولویت دارند و تاریخچه رونوشت والد کپی نمی‌شود مگر اینکه ارث‌بری رونوشت فعال باشد. + - `channels.discord.thread.inheritParent` (پیش‌فرض `false`) رشته‌های خودکار جدید را وارد کاشتن از رونوشت والد می‌کند. بازنویسی‌های هر حساب زیر `channels.discord.accounts..thread.inheritParent` قرار دارند. + - واکنش‌های ابزار پیام می‌توانند مقصدهای پیام مستقیم `user:` را حل کنند. - `guilds..channels..requireMention: false` هنگام جایگزین فعال‌سازی مرحله پاسخ حفظ می‌شود. - موضوع‌های کانال به‌عنوان بافت **غیرقابل اعتماد** تزریق می‌شوند. فهرست‌های مجاز تعیین می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل پاک‌سازی بافت تکمیلی. + موضوع‌های کانال به‌عنوان زمینه **نامطمئن** تزریق می‌شوند. فهرست‌های مجاز کنترل می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل حذف زمینه تکمیلی. - - Discord می‌تواند یک رشته را به هدف نشست متصل کند تا پیام‌های بعدی در آن رشته همچنان به همان نشست مسیریابی شوند (از جمله نشست‌های زیربرنامه). + + Discord می‌تواند یک رشته را به یک هدف نشست متصل کند تا پیام‌های بعدی در آن رشته همچنان به همان نشست مسیریابی شوند (از جمله نشست‌های زیرعامل). دستورها: - - `/focus ` رشته فعلی/جدید را به هدف زیربرنامه/نشست متصل می‌کند - - `/unfocus` اتصال رشته فعلی را حذف می‌کند - - `/agents` اجراهای فعال و وضعیت اتصال را نشان می‌دهد - - `/session idle ` auto-unfocus ناشی از عدم فعالیت را برای اتصال‌های متمرکز بررسی/به‌روزرسانی می‌کند - - `/session max-age ` حداکثر عمر سخت را برای اتصال‌های متمرکز بررسی/به‌روزرسانی می‌کند + - `/focus ` اتصال رشته فعلی/جدید به یک هدف زیرعامل/نشست + - `/unfocus` حذف اتصال رشته فعلی + - `/agents` نمایش اجراهای فعال و وضعیت اتصال + - `/session idle ` بررسی/به‌روزرسانی عدم فعالیت auto-unfocus برای اتصال‌های متمرکز + - `/session max-age ` بررسی/به‌روزرسانی حداکثر عمر سخت برای اتصال‌های متمرکز پیکربندی: @@ -756,23 +780,23 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - `session.threadBindings.*` پیش‌فرض‌های سراسری را تنظیم می‌کند. - `channels.discord.threadBindings.*` رفتار Discord را بازنویسی می‌کند. - - `spawnSessions` ایجاد/اتصال خودکار رشته‌ها را برای `sessions_spawn({ thread: true })` و ایجاد رشته‌های ACP کنترل می‌کند. پیش‌فرض: `true`. - - `defaultSpawnContext` بافت بومی زیربرنامه را برای ایجادهای مقید به رشته کنترل می‌کند. پیش‌فرض: `"fork"`. + - `spawnSessions` ایجاد/اتصال خودکار رشته‌ها را برای `sessions_spawn({ thread: true })` و ایجاد رشته ACP کنترل می‌کند. پیش‌فرض: `true`. + - `defaultSpawnContext` زمینه زیرعامل بومی را برای ایجادهای مقید به رشته کنترل می‌کند. پیش‌فرض: `"fork"`. - کلیدهای منسوخ `spawnSubagentSessions`/`spawnAcpSessions` با `openclaw doctor --fix` مهاجرت داده می‌شوند. - - اگر اتصال‌های رشته برای یک حساب غیرفعال باشند، `/focus` و عملیات مرتبط با اتصال رشته در دسترس نیستند. + - اگر اتصال‌های رشته برای یک حساب غیرفعال باشند، `/focus` و عملیات مرتبط اتصال رشته در دسترس نیستند. - [زیربرنامه‌ها](/fa/tools/subagents)، [عامل‌های ACP](/fa/tools/acp-agents)، و [مرجع پیکربندی](/fa/gateway/configuration-reference) را ببینید. + [زیرعامل‌ها](/fa/tools/subagents)، [عامل‌های ACP](/fa/tools/acp-agents)، و [مرجع پیکربندی](/fa/gateway/configuration-reference) را ببینید. - برای فضاهای کاری ACP پایدار و «همیشه روشن»، اتصال‌های ACP نوع‌دار سطح بالا را که گفتگوهای Discord را هدف می‌گیرند پیکربندی کنید. + برای فضاهای کاری ACP پایدار و «همیشه روشن»، اتصال‌های ACP تایپ‌شده سطح بالا را پیکربندی کنید که گفت‌وگوهای Discord را هدف می‌گیرند. مسیر پیکربندی: - `bindings[]` با `type: "acp"` و `match.channel: "discord"` - مثال: + نمونه: ```json5 { @@ -823,7 +847,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی نکته‌ها: - `/acp spawn codex --bind here` کانال یا رشته فعلی را درجا متصل می‌کند و پیام‌های آینده را روی همان نشست ACP نگه می‌دارد. پیام‌های رشته اتصال کانال والد را به ارث می‌برند. - - در یک کانال یا رشته متصل، `/new` و `/reset` همان نشست ACP را درجا بازنشانی می‌کنند. اتصال‌های موقت رشته می‌توانند در زمان فعال بودن، حل هدف را بازنویسی کنند. + - در یک کانال یا رشته متصل، `/new` و `/reset` همان نشست ACP را درجا بازنشانی می‌کنند. اتصال‌های موقت رشته می‌توانند هنگام فعال بودن حل هدف را بازنویسی کنند. - `spawnSessions` ایجاد/اتصال رشته فرزند را از طریق `--thread auto|here` کنترل می‌کند. برای جزئیات رفتار اتصال، [عامل‌های ACP](/fa/tools/acp-agents) را ببینید. @@ -838,12 +862,12 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - `all` - `allowlist` (از `guilds..users` استفاده می‌کند) - رویدادهای واکنش به رویدادهای سیستمی تبدیل می‌شوند و به نشست Discord مسیریابی‌شده متصل می‌شوند. + رویدادهای واکنش به رویدادهای سیستمی تبدیل می‌شوند و به نشست Discord مسیریابی‌شده پیوست می‌شوند. - `ackReaction` هنگام پردازش یک پیام ورودی توسط OpenClaw یک ایموجی تأیید دریافت ارسال می‌کند. + `ackReaction` هنگامی که OpenClaw در حال پردازش یک پیام ورودی است، یک ایموجی تأیید ارسال می‌کند. ترتیب حل: @@ -854,7 +878,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی نکته‌ها: - - Discord ایموجی یونیکد یا نام‌های ایموجی سفارشی را می‌پذیرد. + - Discord ایموجی unicode یا نام‌های ایموجی سفارشی را می‌پذیرد. - برای غیرفعال کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید. @@ -862,7 +886,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی نوشتن پیکربندی آغازشده از کانال به‌طور پیش‌فرض فعال است. - این روی جریان‌های `/config set|unset` اثر می‌گذارد (وقتی ویژگی‌های دستور فعال باشند). + این بر جریان‌های `/config set|unset` اثر می‌گذارد (وقتی قابلیت‌های دستور فعال باشند). غیرفعال‌سازی: @@ -878,8 +902,8 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - - ترافیک WebSocket مربوط به Gateway در Discord و جستجوهای REST هنگام راه‌اندازی (شناسه برنامه + حل فهرست مجاز) را با `channels.discord.proxy` از طریق یک پراکسی HTTP(S) مسیریابی کنید. + + ترافیک WebSocket Gateway متعلق به Discord و جست‌وجوهای REST هنگام راه‌اندازی (شناسه برنامه + حل فهرست مجاز) را با `channels.discord.proxy` از طریق یک پروکسی HTTP(S) مسیریابی کنید. ```json5 { @@ -928,14 +952,14 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی نکته‌ها: - فهرست‌های مجاز می‌توانند از `pk:` استفاده کنند - - نام‌های نمایشی عضو فقط وقتی با نام/slug تطبیق داده می‌شوند که `channels.discord.dangerouslyAllowNameMatching: true` - - جستجوها از شناسه پیام اصلی استفاده می‌کنند و محدود به بازه زمانی هستند - - اگر جستجو ناموفق باشد، پیام‌های پروکسی‌شده به‌عنوان پیام بات در نظر گرفته می‌شوند و حذف می‌شوند مگر اینکه `allowBots=true` باشد + - نام‌های نمایشی عضو فقط وقتی `channels.discord.dangerouslyAllowNameMatching: true` باشد با نام/slug تطبیق داده می‌شوند + - جست‌وجوها از شناسه پیام اصلی استفاده می‌کنند و به پنجره زمانی محدود هستند + - اگر جست‌وجو شکست بخورد، پیام‌های پروکسی‌شده به‌عنوان پیام ربات تلقی می‌شوند و حذف می‌شوند مگر اینکه `allowBots=true` باشد - وقتی عامل‌ها برای کاربران شناخته‌شده Discord به منشن‌های خروجی قطعی نیاز دارند، از `mentionAliases` استفاده کنید. کلیدها handle بدون `@` ابتدایی هستند؛ مقدارها شناسه‌های کاربری Discord هستند. handleهای ناشناخته، `@everyone`، `@here`، و منشن‌های داخل code spanهای Markdown بدون تغییر می‌مانند. + وقتی عامل‌ها به منشن‌های خروجی قطعی برای کاربران شناخته‌شده Discord نیاز دارند، از `mentionAliases` استفاده کنید. کلیدها handleها بدون `@` ابتدایی هستند؛ مقدارها شناسه‌های کاربر Discord هستند. handleهای ناشناخته، `@everyone`، `@here`، و منشن‌های داخل code spanهای Markdown بدون تغییر باقی می‌مانند. ```json5 { @@ -959,9 +983,9 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - به‌روزرسانی‌های حضور وقتی اعمال می‌شوند که یک فیلد وضعیت یا فعالیت تنظیم کنید، یا حضور خودکار را فعال کنید. + به‌روزرسانی‌های حضور وقتی اعمال می‌شوند که یک فیلد وضعیت یا فعالیت تنظیم کنید، یا وقتی حضور خودکار را فعال کنید. - مثال فقط وضعیت: + نمونه فقط وضعیت: ```json5 { @@ -973,7 +997,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - مثال فعالیت (وضعیت سفارشی نوع فعالیت پیش‌فرض است): + نمونه فعالیت (وضعیت سفارشی نوع فعالیت پیش‌فرض است): ```json5 { @@ -986,7 +1010,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - مثال پخش: + نمونه جریان: ```json5 { @@ -1000,16 +1024,16 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - نگاشت نوع فعالیت: + نقشه نوع فعالیت: - 0: در حال بازی - - 1: در حال پخش (به `activityUrl` نیاز دارد) + - 1: در حال پخش جریانی (به `activityUrl` نیاز دارد) - 2: در حال گوش دادن - 3: در حال تماشا - 4: سفارشی (از متن فعالیت به‌عنوان حالت وضعیت استفاده می‌کند؛ ایموجی اختیاری است) - 5: در حال رقابت - مثال حضور خودکار (سیگنال سلامت زمان اجرا): + نمونه حضور خودکار (سیگنال سلامت زمان اجرا): ```json5 { @@ -1026,7 +1050,7 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی } ``` - حضور خودکار دسترس‌پذیری زمان اجرا را به وضعیت Discord نگاشت می‌کند: سالم => آنلاین، تنزل‌یافته یا ناشناخته => بیکار، تمام‌شده یا در دسترس نبودن => dnd. بازنویسی‌های متنی اختیاری: + حضور خودکار، در دسترس بودن زمان اجرا را به وضعیت Discord نگاشت می‌کند: healthy => online، degraded یا unknown => idle، exhausted یا unavailable => dnd. بازنویسی‌های متنی اختیاری: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -1035,71 +1059,71 @@ OpenClaw از کانتینرهای مؤلفه‌های v2 Discord برای پی - Discord از پردازش تأیید مبتنی بر دکمه در DMها پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری اعلان‌های تأیید را در کانال مبدأ ارسال کند. + Discord از مدیریت تأیید مبتنی بر دکمه در پیام‌های مستقیم پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری اعلان‌های تأیید را در کانال مبدأ ارسال کند. مسیر پیکربندی: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (اختیاری؛ در صورت امکان به `commands.ownerAllowFrom` بازمی‌گردد) + - `channels.discord.execApprovals.approvers` (اختیاری؛ در صورت امکان به `commands.ownerAllowFrom` برمی‌گردد) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`، پیش‌فرض: `dm`) - `agentFilter`، `sessionFilter`، `cleanupAfterResolve` - Discord وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک تأییدکننده، چه از `execApprovals.approvers` و چه از `commands.ownerAllowFrom`، قابل تشخیص باشد، تأییدهای اجرای بومی را به‌صورت خودکار فعال می‌کند. Discord تأییدکنندگان اجرا را از `allowFrom` کانال، `dm.allowFrom` قدیمی، یا `defaultTo` پیام مستقیم استنتاج نمی‌کند. برای غیرفعال کردن صریح Discord به‌عنوان کلاینت تأیید بومی، `enabled: false` را تنظیم کنید. + وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک تأییدکننده، چه از `execApprovals.approvers` و چه از `commands.ownerAllowFrom`، قابل حل باشد، Discord تأییدهای اجرای بومی را به‌صورت خودکار فعال می‌کند. Discord تأییدکنندگان اجرا را از `allowFrom` کانال، `dm.allowFrom` قدیمی، یا `defaultTo` پیام مستقیم استنباط نمی‌کند. برای غیرفعال کردن صریح Discord به‌عنوان کلاینت تأیید بومی، `enabled: false` را تنظیم کنید. - برای فرمان‌های گروهی حساس و فقط مخصوص مالک مانند `/diagnostics` و `/export-trajectory`، OpenClaw درخواست‌های تأیید و نتایج نهایی را به‌صورت خصوصی ارسال می‌کند. وقتی مالک فراخواننده مسیر مالک Discord داشته باشد، ابتدا Discord DM را امتحان می‌کند؛ اگر در دسترس نباشد، به نخستین مسیر مالک موجود از `commands.ownerAllowFrom`، مانند Telegram، بازمی‌گردد. + برای فرمان‌های گروهی حساس و فقط مالک مانند `/diagnostics` و `/export-trajectory`، OpenClaw اعلان‌های تأیید و نتایج نهایی را به‌صورت خصوصی ارسال می‌کند. اگر مالک فراخواننده مسیر مالک Discord داشته باشد، ابتدا پیام مستقیم Discord را امتحان می‌کند؛ اگر در دسترس نباشد، به نخستین مسیر مالک موجود از `commands.ownerAllowFrom`، مانند Telegram، برمی‌گردد. - وقتی `target` برابر `channel` یا `both` باشد، درخواست تأیید در کانال قابل مشاهده است. فقط تأییدکنندگان تشخیص‌داده‌شده می‌توانند از دکمه‌ها استفاده کنند؛ کاربران دیگر یک رد موقت دریافت می‌کنند. درخواست‌های تأیید شامل متن فرمان هستند، بنابراین تحویل در کانال را فقط در کانال‌های مورد اعتماد فعال کنید. اگر شناسه کانال را نتوان از کلید نشست استخراج کرد، OpenClaw به تحویل از طریق DM بازمی‌گردد. + وقتی `target` برابر `channel` یا `both` باشد، اعلان تأیید در کانال قابل مشاهده است. فقط تأییدکنندگان حل‌شده می‌توانند از دکمه‌ها استفاده کنند؛ کاربران دیگر یک رد موقت دریافت می‌کنند. اعلان‌های تأیید شامل متن فرمان هستند، بنابراین تحویل در کانال را فقط در کانال‌های مورد اعتماد فعال کنید. اگر شناسه کانال از کلید نشست قابل استخراج نباشد، OpenClaw به تحویل از طریق پیام مستقیم برمی‌گردد. - Discord دکمه‌های تأیید مشترکی را هم که کانال‌های گفت‌وگوی دیگر استفاده می‌کنند رندر می‌کند. آداپتر بومی Discord عمدتاً مسیریابی DM تأییدکننده و انتشار به کانال را اضافه می‌کند. - وقتی این دکمه‌ها وجود داشته باشند، تجربه کاربری اصلی تأیید هستند؛ OpenClaw + Discord همچنین دکمه‌های تأیید مشترکی را که سایر کانال‌های چت استفاده می‌کنند رندر می‌کند. آداپتور بومی Discord عمدتاً مسیریابی پیام مستقیم تأییدکننده و پخش به کانال را اضافه می‌کند. + وقتی آن دکمه‌ها وجود داشته باشند، تجربه کاربری اصلی تأیید همان‌ها هستند؛ OpenClaw فقط زمانی باید فرمان دستی `/approve` را اضافه کند که نتیجه ابزار بگوید - تأییدهای گفت‌وگو در دسترس نیستند یا تأیید دستی تنها مسیر است. - اگر زمان‌اجرای تأیید بومی Discord فعال نباشد، OpenClaw درخواست - محلی و قطعی `/approve ` را قابل مشاهده نگه می‌دارد. اگر - زمان‌اجرا فعال باشد اما کارت بومی به هیچ مقصدی قابل تحویل نباشد، - OpenClaw یک اعلان جایگزین در همان گفت‌وگو با فرمان دقیق `/approve` - از تأیید در انتظار ارسال می‌کند. + تأییدهای چت در دسترس نیستند یا تأیید دستی تنها مسیر است. + اگر زمان اجرای تأیید بومی Discord فعال نباشد، OpenClaw اعلان + قطعی محلی `/approve ` را قابل مشاهده نگه می‌دارد. اگر + زمان اجرا فعال باشد اما کارت بومی به هیچ هدفی قابل تحویل نباشد، + OpenClaw یک اعلان جایگزین در همان چت همراه با فرمان دقیق `/approve` + از تأیید معلق ارسال می‌کند. - احراز هویت Gateway و حل تأیید از قرارداد مشترک کلاینت Gateway پیروی می‌کنند (شناسه‌های `plugin:` از طریق `plugin.approval.resolve` حل می‌شوند؛ شناسه‌های دیگر از طریق `exec.approval.resolve`). تأییدها به‌صورت پیش‌فرض پس از ۳۰ دقیقه منقضی می‌شوند. + احراز هویت Gateway و حل تأیید از قرارداد مشترک کلاینت Gateway پیروی می‌کنند (شناسه‌های `plugin:` از طریق `plugin.approval.resolve` حل می‌شوند؛ شناسه‌های دیگر از طریق `exec.approval.resolve`). تأییدها به‌طور پیش‌فرض پس از ۳۰ دقیقه منقضی می‌شوند. [تأییدهای اجرا](/fa/tools/exec-approvals) را ببینید. -## ابزارها و دروازه‌های کنش +## ابزارها و دروازه‌های اقدام -کنش‌های پیام Discord شامل کنش‌های پیام‌رسانی، مدیریت کانال، نظارت، حضور و فراداده هستند. +اقدام‌های پیام Discord شامل پیام‌رسانی، مدیریت کانال، تعدیل، حضور، و اقدام‌های فراداده هستند. نمونه‌های اصلی: - پیام‌رسانی: `sendMessage`، `readMessages`، `editMessage`، `deleteMessage`، `threadReply` - واکنش‌ها: `react`، `reactions`، `emojiList` -- نظارت: `timeout`، `kick`، `ban` +- تعدیل: `timeout`، `kick`، `ban` - حضور: `setPresence` -کنش `event-create` یک پارامتر اختیاری `image` می‌پذیرد (URL یا مسیر فایل محلی) تا تصویر کاور رویداد زمان‌بندی‌شده را تنظیم کند. +اقدام `event-create` یک پارامتر اختیاری `image` (URL یا مسیر فایل محلی) می‌پذیرد تا تصویر جلد رویداد زمان‌بندی‌شده را تنظیم کند. -دروازه‌های کنش زیر `channels.discord.actions.*` قرار دارند. +دروازه‌های اقدام زیر `channels.discord.actions.*` قرار دارند. رفتار پیش‌فرض دروازه: -| گروه کنش | پیش‌فرض | +| گروه اقدام | پیش‌فرض | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | فعال | -| roles | غیرفعال | -| moderation | غیرفعال | -| presence | غیرفعال | +| roles | غیرفعال | +| moderation | غیرفعال | +| presence | غیرفعال | ## رابط کاربری Components v2 -OpenClaw برای تأییدهای اجرا و نشانگرهای میان‌بافتی از components v2 در Discord استفاده می‌کند. کنش‌های پیام Discord همچنین می‌توانند برای رابط کاربری سفارشی `components` را بپذیرند (پیشرفته؛ نیازمند ساخت payload کامپوننت از طریق ابزار discord)، در حالی که `embeds` قدیمی همچنان در دسترس هستند اما توصیه نمی‌شوند. +OpenClaw از components v2 در Discord برای تأییدهای اجرا و نشانگرهای میان‌بافتی استفاده می‌کند. اقدام‌های پیام Discord همچنین می‌توانند برای رابط کاربری سفارشی `components` بپذیرند (پیشرفته؛ نیازمند ساخت payload کامپوننت از طریق ابزار discord)، در حالی که `embeds` قدیمی همچنان در دسترس هستند اما توصیه نمی‌شوند. - `channels.discord.ui.components.accentColor` رنگ تأکیدی استفاده‌شده توسط کانتینرهای کامپوننت Discord را تنظیم می‌کند (hex). - برای هر حساب با `channels.discord.accounts..ui.components.accentColor` تنظیم کنید. -- وقتی components v2 وجود داشته باشند، `embeds` نادیده گرفته می‌شوند. +- وقتی components v2 وجود داشته باشد، `embeds` نادیده گرفته می‌شود. -نمونه: +مثال: ```json5 { @@ -1115,22 +1139,22 @@ OpenClaw برای تأییدهای اجرا و نشانگرهای میان‌ب } ``` -## صوت +## صدا -Discord دو سطح صوتی متمایز دارد: **کانال‌های صوتی** بلادرنگ (گفت‌وگوهای پیوسته) و **پیوست‌های پیام صوتی** (قالب پیش‌نمایش موجی). Gateway از هر دو پشتیبانی می‌کند. +Discord دو سطح صوتی متمایز دارد: **کانال‌های صوتی** بی‌درنگ (گفت‌وگوهای پیوسته) و **پیوست‌های پیام صوتی** (قالب پیش‌نمایش موج صدا). Gateway از هر دو پشتیبانی می‌کند. ### کانال‌های صوتی فهرست راه‌اندازی: 1. Message Content Intent را در Discord Developer Portal فعال کنید. -2. وقتی allowlistهای نقش/کاربر استفاده می‌شوند، Server Members Intent را فعال کنید. -3. بات را با scopeهای `bot` و `applications.commands` دعوت کنید. -4. در کانال صوتی هدف مجوزهای Connect، Speak، Send Messages و Read Message History را اعطا کنید. +2. وقتی فهرست‌های مجاز نقش/کاربر استفاده می‌شوند، Server Members Intent را فعال کنید. +3. بات را با دامنه‌های `bot` و `applications.commands` دعوت کنید. +4. در کانال صوتی هدف، مجوزهای Connect، Speak، Send Messages، و Read Message History را بدهید. 5. فرمان‌های بومی (`commands.native` یا `channels.discord.commands.native`) را فعال کنید. 6. `channels.discord.voice` را پیکربندی کنید. -برای کنترل نشست‌ها از `/vc join|leave|status` استفاده کنید. این فرمان از عامل پیش‌فرض حساب استفاده می‌کند و همان قوانین allowlist و سیاست گروهی سایر فرمان‌های Discord را دنبال می‌کند. +برای کنترل نشست‌ها از `/vc join|leave|status` استفاده کنید. این فرمان از عامل پیش‌فرض حساب استفاده می‌کند و همان قوانین فهرست مجاز و خط‌مشی گروهیِ سایر فرمان‌های Discord را دنبال می‌کند. ```bash /vc join channel: @@ -1138,7 +1162,7 @@ Discord دو سطح صوتی متمایز دارد: **کانال‌های صوت /vc leave ``` -نمونه اتصال خودکار: +نمونه پیوستن خودکار: ```json5 { @@ -1167,35 +1191,35 @@ Discord دو سطح صوتی متمایز دارد: **کانال‌های صوت } ``` -نکته‌ها: +نکات: -- `voice.tts` فقط برای پخش صوتی، `messages.tts` را override می‌کند. -- `voice.model` فقط LLM استفاده‌شده برای پاسخ‌های کانال صوتی Discord را override می‌کند. برای ارث‌بری مدل عامل مسیریابی‌شده، آن را تنظیم‌نشده بگذارید. +- `voice.tts` فقط برای پخش صوتی، `messages.tts` را بازنویسی می‌کند. +- `voice.model` فقط LLM استفاده‌شده برای پاسخ‌های کانال صوتی Discord را بازنویسی می‌کند. برای به‌ارث‌بردن مدل عامل مسیریابی‌شده، آن را تنظیم‌نشده بگذارید. - STT از `tools.media.audio` استفاده می‌کند؛ `voice.model` بر رونویسی اثر نمی‌گذارد. -- overrideهای `systemPrompt` هر کانال Discord بر نوبت‌های رونوشت صوتی برای همان کانال صوتی اعمال می‌شوند. -- نوبت‌های رونوشت صوتی وضعیت مالک را از `allowFrom` مربوط به Discord (یا `dm.allowFrom`) استخراج می‌کنند؛ گویندگان غیرمالک نمی‌توانند به ابزارهای فقط مخصوص مالک دسترسی داشته باشند (برای مثال `gateway` و `cron`). -- صوت Discord برای پیکربندی‌های فقط متنی اختیاری است؛ برای فعال کردن فرمان‌های `/vc`، زمان‌اجرای صوت، و intent مربوط به gateway با نام `GuildVoiceStates`، `channels.discord.voice.enabled=true` را تنظیم کنید (یا یک بلوک موجود `channels.discord.voice` را نگه دارید). -- `channels.discord.intents.voiceStates` می‌تواند اشتراک intent وضعیت صوتی را صریحاً override کند. برای اینکه intent از فعال‌سازی مؤثر صوت پیروی کند، آن را تنظیم‌نشده بگذارید. -- `voice.daveEncryption` و `voice.decryptionFailureTolerance` به گزینه‌های join در `@discordjs/voice` منتقل می‌شوند. +- بازنویسی‌های `systemPrompt` مختص هر کانال Discord برای نوبت‌های رونویسی صوتی همان کانال صوتی اعمال می‌شوند. +- نوبت‌های رونویسی صوتی، وضعیت مالک را از `allowFrom` در Discord (یا `dm.allowFrom`) استخراج می‌کنند؛ گویندگان غیرمالک نمی‌توانند به ابزارهای فقط مالک (برای مثال `gateway` و `cron`) دسترسی داشته باشند. +- صدای Discord برای پیکربندی‌های فقط متنی اختیاری است؛ برای فعال کردن فرمان‌های `/vc`، زمان اجرای صوتی، و intent مربوط به Gateway یعنی `GuildVoiceStates`، `channels.discord.voice.enabled=true` را تنظیم کنید (یا یک بلوک موجود `channels.discord.voice` را نگه دارید). +- `channels.discord.intents.voiceStates` می‌تواند اشتراک intent وضعیت صوتی را صریحاً بازنویسی کند. برای اینکه intent از فعال‌سازی مؤثر صدا پیروی کند، آن را تنظیم‌نشده بگذارید. +- `voice.daveEncryption` و `voice.decryptionFailureTolerance` به گزینه‌های پیوستن `@discordjs/voice` پاس داده می‌شوند. - اگر تنظیم نشده باشند، پیش‌فرض‌های `@discordjs/voice` برابر `daveEncryption=true` و `decryptionFailureTolerance=24` هستند. -- `voice.connectTimeoutMs` انتظار اولیه Ready در `@discordjs/voice` را برای `/vc join` و تلاش‌های اتصال خودکار کنترل می‌کند. پیش‌فرض: `30000`. -- `voice.reconnectGraceMs` کنترل می‌کند OpenClaw پس از قطع یک نشست صوتی، پیش از نابود کردن آن، چه مدت برای شروع اتصال مجدد صبر کند. پیش‌فرض: `15000`. -- OpenClaw همچنین خطاهای رمزگشایی دریافت را پایش می‌کند و پس از تکرار خطاها در یک بازه کوتاه، با ترک و ورود دوباره به کانال صوتی به‌صورت خودکار بازیابی می‌کند. -- اگر پس از به‌روزرسانی، لاگ‌های دریافت به‌طور مکرر `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` را نشان می‌دهند، یک گزارش وابستگی و لاگ‌ها را جمع‌آوری کنید. خط همراه `@discordjs/voice` شامل اصلاح padding بالادستی از PR #11449 در discord.js است که issue #11419 در discord.js را بست. +- `voice.connectTimeoutMs` انتظار اولیه Ready در `@discordjs/voice` را برای `/vc join` و تلاش‌های پیوستن خودکار کنترل می‌کند. پیش‌فرض: `30000`. +- `voice.reconnectGraceMs` کنترل می‌کند OpenClaw چه مدت منتظر می‌ماند تا یک نشست صوتی قطع‌شده پیش از نابود شدن، شروع به اتصال مجدد کند. پیش‌فرض: `15000`. +- OpenClaw همچنین خطاهای رمزگشایی دریافت را پایش می‌کند و پس از خطاهای تکراری در یک بازه کوتاه، با ترک/پیوستن دوباره به کانال صوتی، به‌صورت خودکار بازیابی می‌شود. +- اگر پس از به‌روزرسانی، لاگ‌های دریافت به‌طور مکرر `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` را نشان می‌دهند، یک گزارش وابستگی و لاگ‌ها را جمع‌آوری کنید. خط همراه `@discordjs/voice` شامل اصلاح padding بالادستی از PR شماره #11449 در discord.js است که issue شماره #11419 در discord.js را بست. خط لوله کانال صوتی: -- ضبط PCM در Discord به یک فایل موقت WAV تبدیل می‌شود. +- ضبط PCM از Discord به یک فایل موقت WAV تبدیل می‌شود. - `tools.media.audio` STT را مدیریت می‌کند، برای مثال `openai/gpt-4o-mini-transcribe`. -- رونوشت از طریق ingress و مسیریابی Discord ارسال می‌شود، در حالی که LLM پاسخ با سیاست خروجی صوتی اجرا می‌شود که ابزار `tts` عامل را پنهان می‌کند و متن برگشتی می‌خواهد، چون صوت Discord مالک پخش TTS نهایی است. -- وقتی `voice.model` تنظیم شده باشد، فقط LLM پاسخ را برای این نوبت کانال صوتی override می‌کند. -- `voice.tts` روی `messages.tts` ادغام می‌شود؛ صوت حاصل در کانال متصل‌شده پخش می‌شود. +- رونویسی از طریق ورودی و مسیریابی Discord ارسال می‌شود، در حالی که LLM پاسخ با خط‌مشی خروجی صوتی اجرا می‌شود که ابزار `tts` عامل را پنهان می‌کند و متن بازگشتی را درخواست می‌کند، زیرا صدای Discord مالک پخش نهایی TTS است. +- وقتی `voice.model` تنظیم شده باشد، فقط LLM پاسخ را برای این نوبت کانال صوتی بازنویسی می‌کند. +- `voice.tts` روی `messages.tts` ادغام می‌شود؛ صدای حاصل در کانال پیوسته‌شده پخش می‌شود. اعتبارنامه‌ها برای هر مؤلفه جداگانه حل می‌شوند: احراز هویت مسیر LLM برای `voice.model`، احراز هویت STT برای `tools.media.audio`، و احراز هویت TTS برای `messages.tts`/`voice.tts`. ### پیام‌های صوتی -پیام‌های صوتی Discord یک پیش‌نمایش موجی نشان می‌دهند و به صوت OGG/Opus نیاز دارند. OpenClaw شکل موج را به‌صورت خودکار تولید می‌کند، اما برای بازرسی و تبدیل روی میزبان gateway به `ffmpeg` و `ffprobe` نیاز دارد. +پیام‌های صوتی Discord یک پیش‌نمایش موج صدا نشان می‌دهند و به صدای OGG/Opus نیاز دارند. OpenClaw موج صدا را به‌صورت خودکار تولید می‌کند، اما برای بررسی و تبدیل، به `ffmpeg` و `ffprobe` روی میزبان Gateway نیاز دارد. - یک **مسیر فایل محلی** ارائه کنید (URLها رد می‌شوند). - محتوای متنی را حذف کنید (Discord متن + پیام صوتی را در همان payload رد می‌کند). @@ -1208,7 +1232,7 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## عیب‌یابی - + - Message Content Intent را فعال کنید - وقتی به حل کاربر/عضو وابسته هستید، Server Members Intent را فعال کنید @@ -1219,9 +1243,9 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - `groupPolicy` را بررسی کنید - - allowlist مربوط به guild را زیر `channels.discord.guilds` بررسی کنید - - اگر نگاشت `channels` مربوط به guild وجود دارد، فقط کانال‌های فهرست‌شده مجاز هستند - - رفتار `requireMention` و الگوهای اشاره را بررسی کنید + - فهرست مجاز guild را زیر `channels.discord.guilds` بررسی کنید + - اگر نگاشت `channels` در guild وجود دارد، فقط کانال‌های فهرست‌شده مجاز هستند + - رفتار `requireMention` و الگوهای mention را بررسی کنید بررسی‌های مفید: @@ -1236,9 +1260,9 @@ openclaw logs --follow علت‌های رایج: - - `groupPolicy="allowlist"` بدون allowlist منطبق برای guild/کانال - - `requireMention` در جای اشتباه پیکربندی شده است (باید زیر `channels.discord.guilds` یا ورودی کانال باشد) - - فرستنده توسط allowlist مربوط به `users` در guild/کانال مسدود شده است + - `groupPolicy="allowlist"` بدون فهرست مجاز guild/channel منطبق + - `requireMention` در جای نادرست پیکربندی شده است (باید زیر `channels.discord.guilds` یا ورودی channel باشد) + - فرستنده توسط فهرست مجاز `users` در guild/channel مسدود شده است @@ -1249,13 +1273,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - تنظیمات صف gateway مربوط به Discord: + تنظیم‌های صف Gateway در Discord: - تک‌حساب: `channels.discord.eventQueue.listenerTimeout` - چندحساب: `channels.discord.accounts..eventQueue.listenerTimeout` - - این فقط کار listener مربوط به gateway در Discord را کنترل می‌کند، نه طول عمر نوبت عامل + - این فقط کار listener در Gateway مربوط به Discord را کنترل می‌کند، نه طول عمر نوبت عامل - Discord timeout مالک کانال را روی نوبت‌های عامل در صف اعمال نمی‌کند. listenerهای پیام فوراً واگذار می‌کنند، و اجراهای Discord در صف، ترتیب هر نشست را تا زمانی که چرخه‌عمر نشست/ابزار/زمان‌اجرا کامل شود یا کار را abort کند، حفظ می‌کنند. + Discord timeout متعلق به کانال را روی نوبت‌های عاملِ در صف اعمال نمی‌کند. listenerهای پیام فوراً واگذار می‌کنند، و اجراهای Discord در صف، ترتیب هر نشست را حفظ می‌کنند تا چرخه عمر نشست/ابزار/زمان اجرا کامل شود یا کار را لغو کند. ```json5 { @@ -1275,10 +1299,10 @@ openclaw logs --follow - - OpenClaw پیش از اتصال، فراداده `/gateway/bot` در Discord را واکشی می‌کند. خرابی‌های گذرا به URL پیش‌فرض Gateway در Discord بازمی‌گردند و در لاگ‌ها rate-limit می‌شوند. + + OpenClaw پیش از اتصال، فراداده Discord `/gateway/bot` را دریافت می‌کند. خرابی‌های گذرا به URL پیش‌فرض Gateway در Discord بازمی‌گردند و در گزارش‌ها محدودسازی نرخ دارند. - تنظیمات timeout فراداده: + تنظیمات پایان مهلت فراداده: - تک‌حساب: `channels.discord.gatewayInfoTimeoutMs` - چندحساب: `channels.discord.accounts..gatewayInfoTimeoutMs` @@ -1287,33 +1311,33 @@ openclaw logs --follow - - OpenClaw هنگام راه‌اندازی و پس از اتصال‌های مجدد در زمان اجرا، منتظر رویداد `READY` در Gateway مربوط به Discord می‌ماند. پیکربندی‌های چندحسابی با راه‌اندازی مرحله‌ای ممکن است به بازه READY طولانی‌تری نسبت به مقدار پیش‌فرض نیاز داشته باشند. + + OpenClaw هنگام راه‌اندازی و پس از اتصال‌های مجدد زمان اجرا، منتظر رویداد `READY` در Gateway مربوط به Discord می‌ماند. پیکربندی‌های چندحساب با فاصله‌گذاری در راه‌اندازی ممکن است به بازه READY طولانی‌تری در راه‌اندازی نسبت به مقدار پیش‌فرض نیاز داشته باشند. تنظیمات پایان مهلت READY: - - تک‌حسابی هنگام راه‌اندازی: `channels.discord.gatewayReadyTimeoutMs` - - چندحسابی هنگام راه‌اندازی: `channels.discord.accounts..gatewayReadyTimeoutMs` - - جایگزین محیطی هنگام راه‌اندازی وقتی پیکربندی تنظیم نشده است: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - - مقدار پیش‌فرض هنگام راه‌اندازی: `15000` (۱۵ ثانیه)، حداکثر: `120000` - - تک‌حسابی در زمان اجرا: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - چندحسابی در زمان اجرا: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - جایگزین محیطی در زمان اجرا وقتی پیکربندی تنظیم نشده است: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - - مقدار پیش‌فرض در زمان اجرا: `30000` (۳۰ ثانیه)، حداکثر: `120000` + - راه‌اندازی تک‌حساب: `channels.discord.gatewayReadyTimeoutMs` + - راه‌اندازی چندحساب: `channels.discord.accounts..gatewayReadyTimeoutMs` + - جایگزین env راه‌اندازی وقتی config تنظیم نشده باشد: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - پیش‌فرض راه‌اندازی: `15000` (۱۵ ثانیه)، حداکثر: `120000` + - زمان اجرا تک‌حساب: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - زمان اجرا چندحساب: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - جایگزین env زمان اجرا وقتی config تنظیم نشده باشد: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - پیش‌فرض زمان اجرا: `30000` (۳۰ ثانیه)، حداکثر: `120000` - + بررسی‌های مجوز `channels status --probe` فقط برای شناسه‌های عددی کانال کار می‌کنند. - اگر از کلیدهای slug استفاده می‌کنید، تطبیق در زمان اجرا همچنان می‌تواند کار کند، اما probe نمی‌تواند مجوزها را به‌طور کامل تأیید کند. + اگر از کلیدهای slug استفاده می‌کنید، تطبیق در زمان اجرا همچنان می‌تواند کار کند، اما probe نمی‌تواند مجوزها را کامل تأیید کند. - - DM غیرفعال است: `channels.discord.dm.enabled=false` - - خط‌مشی DM غیرفعال است: `channels.discord.dmPolicy="disabled"` (قدیمی: `channels.discord.dm.policy`) + - DM غیرفعال: `channels.discord.dm.enabled=false` + - سیاست DM غیرفعال: `channels.discord.dmPolicy="disabled"` (قدیمی: `channels.discord.dm.policy`) - در انتظار تأیید جفت‌سازی در حالت `pairing` @@ -1322,7 +1346,7 @@ openclaw logs --follow به‌طور پیش‌فرض پیام‌های نوشته‌شده توسط بات نادیده گرفته می‌شوند. اگر `channels.discord.allowBots=true` را تنظیم می‌کنید، برای جلوگیری از رفتار حلقه‌ای از قوانین سخت‌گیرانه mention و allowlist استفاده کنید. - بهتر است از `channels.discord.allowBots="mentions"` استفاده کنید تا فقط پیام‌های بات‌هایی پذیرفته شوند که بات را mention می‌کنند. + بهتر است از `channels.discord.allowBots="mentions"` استفاده کنید تا فقط پیام‌های باتی پذیرفته شوند که بات را mention می‌کنند. ```json5 { @@ -1330,7 +1354,7 @@ openclaw logs --follow discord: { accounts: { mantis: { - // Mantis only when they mention her. + // Mantis listens to other bots only when they mention her. allowBots: "mentions", }, molty: { @@ -1349,15 +1373,15 @@ openclaw logs --follow - + - - OpenClaw را به‌روز نگه دارید (`openclaw update`) تا منطق بازیابی دریافت صدای Discord موجود باشد + - OpenClaw را به‌روز نگه دارید (`openclaw update`) تا منطق بازیابی دریافت صوتی Discord حاضر باشد - تأیید کنید `channels.discord.voice.daveEncryption=true` (پیش‌فرض) - - از `channels.discord.voice.decryptionFailureTolerance=24` (پیش‌فرض upstream) شروع کنید و فقط در صورت نیاز تنظیمش کنید - - لاگ‌ها را برای موارد زیر بررسی کنید: + - از `channels.discord.voice.decryptionFailureTolerance=24` (پیش‌فرض بالادستی) شروع کنید و فقط در صورت نیاز تنظیم کنید + - گزارش‌ها را برای این موارد پایش کنید: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - اگر خطاها پس از پیوستن مجدد خودکار ادامه داشتند، لاگ‌ها را جمع‌آوری کنید و با سابقه دریافت upstream DAVE در [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) و [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) مقایسه کنید + - اگر خرابی‌ها پس از پیوستن مجدد خودکار ادامه یافتند، گزارش‌ها را گردآوری کنید و با تاریخچه دریافت DAVE بالادستی در [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) و [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) مقایسه کنید @@ -1369,7 +1393,7 @@ openclaw logs --follow - راه‌اندازی/احراز هویت: `enabled`, `token`, `accounts.*`, `allowBots` -- خط‌مشی: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` +- سیاست: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - فرمان: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - صف رویداد: `eventQueue.listenerTimeout` (بودجه listener)، `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` - Gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` @@ -1386,9 +1410,9 @@ openclaw logs --follow ## ایمنی و عملیات -- توکن‌های بات را به‌عنوان راز در نظر بگیرید (`DISCORD_BOT_TOKEN` در محیط‌های نظارت‌شده ترجیح داده می‌شود). -- حداقل مجوزهای لازم Discord را اعطا کنید. -- اگر deploy/state فرمان قدیمی است، Gateway را دوباره راه‌اندازی کنید و با `openclaw channels status --probe` دوباره بررسی کنید. +- توکن‌های بات را به‌عنوان راز در نظر بگیرید (`DISCORD_BOT_TOKEN` در محیط‌های تحت نظارت ترجیح داده می‌شود). +- کمترین مجوزهای لازم Discord را اعطا کنید. +- اگر deploy/state فرمان قدیمی است، Gateway را راه‌اندازی مجدد کنید و دوباره با `openclaw channels status --probe` بررسی کنید. ## مرتبط @@ -1408,7 +1432,7 @@ openclaw logs --follow guildها و کانال‌ها را به عامل‌ها نگاشت کنید. - + رفتار فرمان بومی. diff --git a/docs/fa/channels/slack.md b/docs/fa/channels/slack.md index e1b96cd0c..c9d10e77a 100644 --- a/docs/fa/channels/slack.md +++ b/docs/fa/channels/slack.md @@ -1,47 +1,47 @@ --- read_when: - راه‌اندازی Slack یا اشکال‌زدایی حالت سوکت/HTTP در Slack -summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت Socket + نشانی‌های URL درخواست HTTP) +summary: راه‌اندازی Slack و رفتار زمان اجرا (حالت سوکت + URLهای درخواست HTTP) title: Slack x-i18n: - generated_at: "2026-05-04T02:22:25Z" + generated_at: "2026-05-04T07:02:46Z" model: gpt-5.5 provider: openai - source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b + source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228 source_path: channels/slack.md workflow: 16 --- -آماده برای تولید در DMها و کانال‌ها از طریق یکپارچه‌سازی‌های برنامه Slack. حالت پیش‌فرض Socket Mode است؛ HTTP Request URLs نیز پشتیبانی می‌شوند. +آمادهٔ تولید برای پیام‌های مستقیم و کانال‌ها از طریق یکپارچه‌سازی‌های اپلیکیشن Slack. حالت پیش‌فرض، حالت Socket است؛ URLهای درخواست HTTP نیز پشتیبانی می‌شوند. - - DMهای Slack به‌طور پیش‌فرض در حالت همگام‌سازی هستند. + + پیام‌های مستقیم 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](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید - - یک **App-Level Token** (`xapp-...`) با `connections:write` ایجاد کنید - - برنامه را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید + - گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید + - [نمونهٔ manifest](#manifest-and-scope-checklist) زیر را جای‌گذاری کنید و برای ایجاد ادامه دهید + - یک **توکن سطح اپلیکیشن** (`xapp-...`) با `connections:write` ایجاد کنید + - اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید - + راه‌اندازی پیشنهادی SecretRef: @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -84,19 +84,19 @@ 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](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید - - **Signing Secret** را برای راستی‌آزمایی درخواست ذخیره کنید - - برنامه را نصب کنید و **Bot Token** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید + - گزینهٔ **from a manifest** را انتخاب کنید و یک فضای کاری برای اپلیکیشن خود برگزینید + - [نمونهٔ manifest](#manifest-and-scope-checklist) را جای‌گذاری کنید و پیش از ایجاد، URLها را به‌روزرسانی کنید + - **راز امضا** را برای راستی‌آزمایی درخواست ذخیره کنید + - اپلیکیشن را نصب کنید و **توکن Bot** (`xoxb-...`) نمایش‌داده‌شده را کپی کنید - + راه‌اندازی پیشنهادی SecretRef: @@ -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 +## تنظیم دقیق انتقال در حالت Socket -OpenClaw به‌طور پیش‌فرض برای Socket Mode، زمان‌انتظار pong کلاینت SDK مربوط به Slack را روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط وقتی بازنویسی کنید که به تنظیمات اختصاصی workspace یا میزبان نیاز دارید: +OpenClaw به‌طور پیش‌فرض زمان پایان انتظار pong کلاینت SDK Slack را برای حالت Socket روی ۱۵ ثانیه تنظیم می‌کند. تنظیمات انتقال را فقط زمانی بازنویسی کنید که به تنظیم دقیق مخصوص فضای کاری یا میزبان نیاز دارید: ```json5 { @@ -159,13 +159,13 @@ OpenClaw به‌طور پیش‌فرض برای Socket Mode، زمان‌انت } ``` -این را فقط برای workspaceهای Socket Mode استفاده کنید که زمان‌انتظار‌های Slack websocket pong/server-ping را ثبت می‌کنند یا روی میزبان‌هایی با کمبود شناخته‌شده چرخه رویداد اجرا می‌شوند. `clientPingTimeout` مدت انتظار برای pong پس از ارسال client ping توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای برنامه، وضعیت برنامه باقی می‌مانند، نه سیگنال‌های زنده‌بودن انتقال. +این را فقط برای فضاهای کاری حالت Socket استفاده کنید که پایان زمان انتظار pong وب‌سوکت Slack یا server-ping را ثبت می‌کنند، یا روی میزبان‌هایی اجرا می‌شوند که گرسنگی حلقهٔ رویداد شناخته‌شده دارند. `clientPingTimeout` مدت انتظار برای pong پس از ارسال ping کلاینت توسط SDK است؛ `serverPingTimeout` مدت انتظار برای pingهای سرور Slack است. پیام‌ها و رویدادهای اپلیکیشن همچنان وضعیت اپلیکیشن هستند، نه سیگنال‌های زنده‌بودن انتقال. -## فهرست کنترل manifest و scope +## فهرست بررسی manifest و scope -manifest پایه برنامه Slack برای Socket Mode و HTTP Request URLs یکسان است. فقط بلوک `settings` (و `url` فرمان slash) تفاوت دارد. +manifest پایهٔ اپلیکیشن Slack برای حالت Socket و URLهای درخواست HTTP یکسان است. فقط بلوک `settings` (و `url` دستور اسلش) متفاوت است. -manifest پایه (پیش‌فرض Socket Mode): +manifest پایه (پیش‌فرض حالت Socket): ```json { @@ -240,7 +240,7 @@ manifest پایه (پیش‌فرض Socket Mode): } ``` -برای حالت **HTTP Request URLs**، `settings` را با گونه HTTP جایگزین کنید و به هر فرمان slash مقدار `url` اضافه کنید. URL عمومی لازم است: +برای **حالت URLهای درخواست HTTP**، `settings` را با گونهٔ HTTP جایگزین کنید و به هر دستور اسلش `url` اضافه کنید. URL عمومی لازم است: ```json { @@ -282,24 +282,24 @@ manifest پایه (پیش‌فرض Socket Mode): } ``` -### تنظیمات اضافی manifest +### تنظیمات تکمیلی manifest -قابلیت‌های متفاوتی را آشکار کنید که پیش‌فرض‌های بالا را گسترش می‌دهند. +ویژگی‌های متفاوتی را که پیش‌فرض‌های بالا را گسترش می‌دهند، ارائه کنید. -manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی عضوی از workspace زبانه Home را باز می‌کند، OpenClaw با `views.publish` یک نمای Home پیش‌فرض امن منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی گنجانده نمی‌شود. زبانه **Messages** برای DMهای Slack فعال می‌ماند. +manifest پیش‌فرض، زبانهٔ **Home** در Slack App Home را فعال می‌کند و در `app_home_opened` مشترک می‌شود. وقتی یکی از اعضای فضای کاری زبانهٔ Home را باز می‌کند، OpenClaw با `views.publish` یک نمای Home پیش‌فرض امن منتشر می‌کند؛ هیچ payload مکالمه یا پیکربندی خصوصی در آن گنجانده نمی‌شود. زبانهٔ **Messages** برای پیام‌های مستقیم Slack همچنان فعال می‌ماند. - + - می‌توان به‌جای یک فرمان پیکربندی‌شده واحد، با ظرافت از چند [فرمان slash بومی](#commands-and-slash-behavior) استفاده کرد: + می‌توان به‌جای یک دستور پیکربندی‌شدهٔ واحد، از چندین [دستور اسلش بومی](#commands-and-slash-behavior) با جزئیات استفاده کرد: - - از `/agentstatus` به‌جای `/status` استفاده کنید، چون فرمان `/status` رزرو شده است. - - هم‌زمان بیش از ۲۵ فرمان slash را نمی‌توان در دسترس قرار داد. + - از `/agentstatus` به‌جای `/status` استفاده کنید، چون دستور `/status` رزرو شده است. + - نمی‌توان بیش از ۲۵ دستور اسلش را هم‌زمان در دسترس قرار داد. - بخش موجود `features.slash_commands` خود را با زیرمجموعه‌ای از [فرمان‌های موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: + بخش `features.slash_commands` موجود خود را با زیرمجموعه‌ای از [دستورهای موجود](/fa/tools/slash-commands#command-list) جایگزین کنید: - + ```json { @@ -422,8 +422,8 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال ``` - - از همان فهرست `slash_commands` بالا برای Socket Mode استفاده کنید، و به هر مدخل `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: + + از همان فهرست `slash_commands` حالت Socket در بالا استفاده کنید و به هر ورودی `"url": "https://gateway-host.example.com/slack/events"` اضافه کنید. نمونه: ```json { @@ -443,20 +443,20 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال } ``` - آن مقدار `url` را روی هر فرمان در فهرست تکرار کنید. + آن مقدار `url` را برای هر دستور در فهرست تکرار کنید. - - اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت agent فعال (نام کاربری و آیکون سفارشی) استفاده کنند، scope ربات `chat:write.customize` را اضافه کنید. + + اگر می‌خواهید پیام‌های خروجی به‌جای هویت پیش‌فرض برنامه Slack از هویت عامل فعال (نام کاربری و نماد سفارشی) استفاده کنند، دامنه ربات `chat:write.customize` را اضافه کنید. - اگر از آیکون ایموجی استفاده می‌کنید، Slack انتظار دستور زبان `:emoji_name:` را دارد. + اگر از نماد ایموجی استفاده می‌کنید، Slack انتظار نحو `:emoji_name:` را دارد. - - اگر `channels.slack.userToken` را پیکربندی می‌کنید، scopeهای خواندن معمول عبارت‌اند از: + + اگر `channels.slack.userToken` را پیکربندی کنید، دامنه‌های خواندن معمول عبارت‌اند از: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -473,34 +473,34 @@ manifest پیش‌فرض، زبانه **Home** در Slack App Home را فعال - `botToken` + `appToken` برای Socket Mode الزامی هستند. - حالت HTTP به `botToken` + `signingSecret` نیاز دارد. -- `botToken`، `appToken`، `signingSecret`، و `userToken` رشته‌های متن ساده - یا شیءهای SecretRef را می‌پذیرند. -- توکن‌های پیکربندی fallback متغیرهای محیطی را override می‌کنند. -- fallback متغیرهای محیطی `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. -- `userToken` (`xoxp-...`) فقط از پیکربندی می‌آید (بدون fallback متغیر محیطی) و رفتار پیش‌فرض آن فقط‌خواندنی است (`userTokenReadOnly: true`). +- `botToken`، `appToken`، `signingSecret` و `userToken` رشته‌های متن ساده + یا اشیای SecretRef را می‌پذیرند. +- توکن‌های پیکربندی، جایگزین بازگشت env می‌شوند. +- بازگشت env برای `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. +- `userToken` (`xoxp-...`) فقط از طریق پیکربندی است (بدون بازگشت env) و به‌طور پیش‌فرض رفتار فقط‌خواندنی دارد (`userTokenReadOnly: true`). -رفتار snapshot وضعیت: +رفتار نمایه وضعیت: - بازرسی حساب Slack فیلدهای `*Source` و `*Status` - را برای هر credential پیگیری می‌کند (`botToken`، `appToken`، `signingSecret`، `userToken`). -- وضعیت `available`، `configured_unavailable`، یا `missing` است. + را برای هر اعتبارنامه (`botToken`، `appToken`، `signingSecret`، `userToken`) رهگیری می‌کند. +- وضعیت `available`، `configured_unavailable` یا `missing` است. - `configured_unavailable` یعنی حساب از طریق SecretRef - یا منبع secret غیر inline دیگری پیکربندی شده است، اما مسیر فرمان/runtime فعلی + یا منبع راز غیرخطی دیگری پیکربندی شده است، اما مسیر فرمان/زمان اجرای فعلی نتوانسته مقدار واقعی را resolve کند. -- در حالت HTTP، `signingSecretStatus` درج می‌شود؛ در Socket Mode، +- در حالت HTTP، `signingSecretStatus` گنجانده می‌شود؛ در Socket Mode، جفت الزامی `botTokenStatus` + `appTokenStatus` است. -برای actionها/خواندن‌های directory، وقتی user token پیکربندی شده باشد، می‌تواند ترجیح داده شود. برای نوشتن‌ها، bot token همچنان ترجیح داده می‌شود؛ نوشتن با user-token فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و bot token در دسترس نباشد. +برای خواندن‌های اقدامات/فهرست، وقتی توکن کاربر پیکربندی شده باشد می‌توان آن را ترجیح داد. برای نوشتن‌ها، توکن ربات همچنان ترجیح داده می‌شود؛ نوشتن با توکن کاربر فقط وقتی مجاز است که `userTokenReadOnly: false` باشد و توکن ربات در دسترس نباشد. -## actionها و gateها +## اقدامات و گیت‌ها -actionهای Slack با `channels.slack.actions.*` کنترل می‌شوند. +اقدامات Slack با `channels.slack.actions.*` کنترل می‌شوند. -گروه‌های action موجود در ابزارهای فعلی Slack: +گروه‌های اقدام موجود در ابزار فعلی Slack: -| گروه | پیش‌فرض | +| گروه | پیش‌فرض | | ---------- | ------- | | messages | فعال | | reactions | فعال | @@ -508,60 +508,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 را که در جای‌نگهدارهای فایل ورودی نشان داده می‌شوند می‌پذیرد و برای تصاویر پیش‌نمایش تصویر یا برای انواع دیگر فایل، فراداده فایل محلی را برمی‌گرداند. ## کنترل دسترسی و مسیریابی - - `channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` allowlist رسمی DM است. + + `channels.slack.dmPolicy` دسترسی DM را کنترل می‌کند. `channels.slack.allowFrom` فهرست مجاز canonical برای DM است. - `pairing` (پیش‌فرض) - `allowlist` - `open` (نیاز دارد `channels.slack.allowFrom` شامل `"*"` باشد) - `disabled` - flagهای DM: + پرچم‌های DM: - `dm.enabled` (پیش‌فرض true) - `channels.slack.allowFrom` - `dm.allowFrom` (قدیمی) - - `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false) - - `dm.groupChannels` (allowlist اختیاری MPIM) + - `dm.groupEnabled` (DMهای گروهی به‌طور پیش‌فرض false هستند) + - `dm.groupChannels` (فهرست مجاز MPIM اختیاری) - اولویت چندحسابی: + تقدم چندحسابی: - `channels.slack.accounts.default.allowFrom` فقط برای حساب `default` اعمال می‌شود. - - حساب‌های نام‌دار وقتی `allowFrom` خودشان unset باشد، `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` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` migrate می‌کند. + `channels.slack.dm.policy` و `channels.slack.dm.allowFrom` قدیمی همچنان برای سازگاری خوانده می‌شوند. `openclaw doctor --fix` وقتی بتواند بدون تغییر دسترسی این کار را انجام دهد، آن‌ها را به `dmPolicy` و `allowFrom` مهاجرت می‌دهد. - Pairing در DMها از `openclaw pairing approve slack ` استفاده می‌کند. + جفت‌سازی در DMها از `openclaw pairing approve slack ` استفاده می‌کند. - - `channels.slack.groupPolicy` نحوه رسیدگی به کانال را کنترل می‌کند: + + `channels.slack.groupPolicy` مدیریت کانال را کنترل می‌کند: - `open` - `allowlist` - `disabled` - allowlist کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای نمونه `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند. + فهرست مجاز کانال زیر `channels.slack.channels` قرار دارد و **باید از شناسه‌های پایدار کانال Slack** (برای مثال `C12345678`) به‌عنوان کلیدهای پیکربندی استفاده کند. - نکته runtime: اگر `channels.slack` کاملاً وجود نداشته باشد (راه‌اندازی فقط با env)، runtime به `groupPolicy="allowlist"` fallback می‌کند و warning ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). + نکته زمان اجرا: اگر `channels.slack` کاملا وجود نداشته باشد (راه‌اندازی فقط با env)، زمان اجرا به `groupPolicy="allowlist"` برمی‌گردد و یک هشدار ثبت می‌کند (حتی اگر `channels.defaults.groupPolicy` تنظیم شده باشد). resolve نام/شناسه: - - entryهای allowlist کانال و entryهای allowlist مربوط به DM هنگام startup و وقتی دسترسی token اجازه دهد resolve می‌شوند - - entryهای resolveنشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند - - authorization ورودی و مسیریابی کانال به‌طور پیش‌فرض ID-first هستند؛ تطبیق مستقیم username/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد + - ورودی‌های فهرست مجاز کانال و ورودی‌های فهرست مجاز DM هنگام راه‌اندازی، وقتی دسترسی توکن اجازه دهد، resolve می‌شوند + - ورودی‌های resolveنشده نام کانال همان‌طور که پیکربندی شده‌اند نگه داشته می‌شوند، اما به‌طور پیش‌فرض برای مسیریابی نادیده گرفته می‌شوند + - مجوزدهی ورودی و مسیریابی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است؛ تطبیق مستقیم نام کاربری/slug به `channels.slack.dangerouslyAllowNameMatching: true` نیاز دارد - کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) زیر `groupPolicy: "allowlist"` مطابقت **نمی‌کنند**. lookup کانال به‌طور پیش‌فرض ID-first است، بنابراین کلید مبتنی بر نام هرگز با موفقیت route نمی‌شود و همه پیام‌های آن کانال بی‌صدا block می‌شوند. این با `groupPolicy: "open"` فرق دارد؛ در آن حالت کلید کانال برای مسیریابی لازم نیست و کلید مبتنی بر نام ظاهراً کار می‌کند. + کلیدهای مبتنی بر نام (`#channel-name` یا `channel-name`) تحت `groupPolicy: "allowlist"` تطبیق **نمی‌شوند**. جست‌وجوی کانال به‌طور پیش‌فرض ابتدا بر پایه شناسه است، بنابراین یک کلید مبتنی بر نام هرگز با موفقیت مسیریابی نمی‌شود و همه پیام‌های آن کانال بی‌صدا مسدود خواهند شد. این با `groupPolicy: "open"` فرق دارد؛ در آنجا کلید کانال برای مسیریابی لازم نیست و به نظر می‌رسد یک کلید مبتنی بر نام کار می‌کند. - همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای پیدا کردن آن: در Slack روی کانال راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. + همیشه از شناسه کانال Slack به‌عنوان کلید استفاده کنید. برای یافتن آن: روی کانال در Slack راست‌کلیک کنید → **Copy link** — شناسه (`C...`) در انتهای URL ظاهر می‌شود. درست: @@ -578,7 +578,7 @@ actionهای پیام فعلی Slack شامل `send`، `upload-file`، `download } ``` - نادرست (زیر `groupPolicy: "allowlist"` بی‌صدا block می‌شود): + نادرست (به‌صورت بی‌صدا تحت `groupPolicy: "allowlist"` مسدود می‌شود): ```json5 { @@ -597,93 +597,112 @@ actionهای پیام فعلی Slack شامل `send`، `upload-file`، `download - پیام‌های کانال به‌طور پیش‌فرض با mention gated می‌شوند. + پیام‌های کانال به‌صورت پیش‌فرض با اشاره کنترل می‌شوند. - منابع mention: + منابع اشاره: - - mention صریح app (`<@botId>`) - - mention گروه کاربری Slack (``) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد - - الگوهای regex برای mention (`agents.list[].groupChat.mentionPatterns`، fallback با `messages.groupChat.mentionPatterns`) - - رفتار thread ضمنی reply-to-bot (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود) + - اشاره صریح به اپ (`<@botId>`) + - اشاره به گروه کاربری Slack (``) وقتی کاربر ربات عضو آن گروه کاربری باشد؛ به `usergroups:read` نیاز دارد + - الگوهای regex اشاره (`agents.list[].groupChat.mentionPatterns`، جایگزین `messages.groupChat.mentionPatterns`) + - رفتار ضمنی پاسخ به رشته ربات (وقتی `thread.requireExplicitMention` برابر `true` باشد غیرفعال می‌شود) - کنترل‌های هر کانال (`channels.slack.channels.`؛ نام‌ها فقط از طریق resolve در startup یا `dangerouslyAllowNameMatching`): + کنترل‌های هر کانال (`channels.slack.channels.`؛ نام‌ها فقط از طریق حل‌وفصل هنگام راه‌اندازی یا `dangerouslyAllowNameMatching`): - `requireMention` - `users` (allowlist) - `allowBots` - `skills` - `systemPrompt` - - `tools`, `toolsBySender` + - `tools`، `toolsBySender` - قالب کلید `toolsBySender`: `id:`، `e164:`، `username:`، `name:`، یا wildcard `"*"` - (کلیدهای قدیمی بدون prefix همچنان فقط به `id:` map می‌شوند) + (کلیدهای قدیمی بدون پیشوند همچنان فقط به `id:` نگاشت می‌شوند) - `allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های room که توسط bot نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که bot فرستنده صراحتاً در allowlist `users` همان room فهرست شده باشد، یا وقتی دست‌کم یک شناسه صریح مالک Slack از `channels.slack.allowFrom` در حال حاضر عضو room باشد. wildcardها و entryهای مالک با display-name حضور مالک را برآورده نمی‌کنند. حضور مالک از `conversations.members` Slack استفاده می‌کند؛ مطمئن شوید app scope خواندن مطابق با نوع room را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر member lookup شکست بخورد، OpenClaw پیام room نوشته‌شده توسط bot را drop می‌کند. + `allowBots` برای کانال‌ها و کانال‌های خصوصی محافظه‌کارانه است: پیام‌های اتاق که توسط ربات نوشته شده‌اند فقط وقتی پذیرفته می‌شوند که ربات فرستنده به‌صراحت در allowlist `users` همان اتاق فهرست شده باشد، یا وقتی دست‌کم یک شناسه مالک صریح Slack از `channels.slack.allowFrom` در حال حاضر عضو اتاق باشد. wildcardها و ورودی‌های مالک با نام نمایشی، حضور مالک را برآورده نمی‌کنند. حضور مالک از `conversations.members` در Slack استفاده می‌کند؛ مطمئن شوید اپ scope خواندن متناظر با نوع اتاق را دارد (`channels:read` برای کانال‌های عمومی، `groups:read` برای کانال‌های خصوصی). اگر جست‌وجوی عضو شکست بخورد، OpenClaw پیام اتاق نوشته‌شده توسط ربات را حذف می‌کند. -## threadها، sessionها، و tagهای پاسخ +## رشته‌ها، نشست‌ها، و برچسب‌های پاسخ -- DMها به‌صورت `direct` route می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`. -- bindingهای route در Slack شناسه‌های خام peer به‌علاوه شکل‌های هدف Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` را می‌پذیرند. -- با `session.dmScope=main` پیش‌فرض، DMهای Slack به session اصلی agent collapse می‌شوند. -- sessionهای کانال: `agent::slack:channel:`. -- پاسخ‌های thread می‌توانند در صورت کاربرد، suffixهای session thread بسازند (`:thread:`). +- DMها به‌صورت `direct` مسیر‌دهی می‌شوند؛ کانال‌ها به‌صورت `channel`؛ MPIMها به‌صورت `group`. +- اتصال‌های مسیر Slack شناسه‌های خام طرف مقابل به‌علاوه فرم‌های مقصد Slack مانند `channel:C12345678`، `user:U12345678`، و `<@U12345678>` را می‌پذیرند. +- با مقدار پیش‌فرض `session.dmScope=main`، DMهای Slack در نشست اصلی عامل ادغام می‌شوند. +- نشست‌های کانال: `agent::slack:channel:`. +- پاسخ‌های رشته می‌توانند در صورت کاربرد پسوندهای نشست رشته (`: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 مشارکت کرده باشد. بدون این، پاسخ‌ها در threadی که bot در آن مشارکت کرده است gate مربوط به `requireMention` را bypass می‌کنند. +- `channels.slack.thread.initialHistoryLimit` کنترل می‌کند هنگام شروع یک نشست رشته جدید چند پیام موجود رشته دریافت شود (پیش‌فرض `20`؛ برای غیرفعال‌سازی روی `0` تنظیم کنید). +- `channels.slack.thread.requireExplicitMention` (پیش‌فرض `false`): وقتی `true` باشد، اشاره‌های ضمنی رشته را سرکوب می‌کند تا ربات فقط به اشاره‌های صریح `@bot` داخل رشته‌ها پاسخ دهد، حتی وقتی ربات قبلا در رشته مشارکت کرده باشد. بدون این، پاسخ‌ها در رشته‌ای که ربات در آن مشارکت داشته از کنترل `requireMention` عبور می‌کنند. -کنترل‌های thread پاسخ: +کنترل‌های رشته پاسخ: - `channels.slack.replyToMode`: `off|first|all|batched` (پیش‌فرض `off`) -- `channels.slack.replyToModeByChatType`: برای هر `direct|group|channel` -- fallback قدیمی برای چت‌های مستقیم: `channels.slack.dm.replyToMode` +- `channels.slack.replyToModeByChatType`: به‌ازای هر `direct|group|channel` +- جایگزین قدیمی برای چت‌های مستقیم: `channels.slack.dm.replyToMode` -tagهای پاسخ دستی پشتیبانی می‌شوند: +برچسب‌های پاسخ دستی پشتیبانی می‌شوند: - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"` **همه** thread کردن پاسخ در Slack را غیرفعال می‌کند، از جمله tagهای صریح `[[reply_to_*]]`. این با Telegram متفاوت است؛ در آنجا tagهای صریح همچنان در حالت `"off"` رعایت می‌شوند. threadهای Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت inline قابل مشاهده می‌مانند. +`replyToMode="off"` **تمام** رشته‌سازی پاسخ در Slack را غیرفعال می‌کند، از جمله برچسب‌های صریح `[[reply_to_*]]`. این با Telegram متفاوت است، جایی که برچسب‌های صریح همچنان در حالت `"off"` رعایت می‌شوند. رشته‌های Slack پیام‌ها را از کانال پنهان می‌کنند، در حالی که پاسخ‌های Telegram به‌صورت درون‌خطی قابل مشاهده می‌مانند. -## واکنش‌های Ack +## واکنش‌های تایید -`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw، یک ایموجی acknowledgement می‌فرستد. +`ackReaction` هنگام پردازش پیام ورودی توسط OpenClaw یک ایموجی تایید ارسال می‌کند. -ترتیب resolve: +ترتیب حل‌وفصل: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback ایموجی هویت agent (`agents.list[].identity.emoji`، وگرنه "👀") +- جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، وگرنه "👀") نکته‌ها: -- Slack انتظار shortcode دارد (برای نمونه `"eyes"`). -- برای غیرفعال‌سازی واکنش برای حساب Slack یا به‌صورت global از `""` استفاده کنید. +- Slack انتظار shortcode دارد (برای مثال `"eyes"`). +- برای غیرفعال کردن واکنش برای حساب Slack یا به‌صورت سراسری از `""` استفاده کنید. -## streaming متن +## پخش جریانی متن -`channels.slack.streaming` رفتار preview زنده را کنترل می‌کند: +`channels.slack.streaming` رفتار پیش‌نمایش زنده را کنترل می‌کند: -- `off`: streaming preview زنده را غیرفعال می‌کند. -- `partial` (پیش‌فرض): متن preview را با آخرین خروجی partial جایگزین می‌کند. -- `block`: به‌روزرسانی‌های preview تکه‌تکه‌شده را append می‌کند. -- `progress`: هنگام تولید، متن وضعیت progress را نشان می‌دهد، سپس متن نهایی را می‌فرستد. -- `streaming.preview.toolProgress`: وقتی draft preview فعال است، به‌روزرسانی‌های tool/progress را به همان پیام preview ویرایش‌شده route می‌کند (پیش‌فرض: `true`). برای نگه‌داشتن پیام‌های tool/progress جداگانه، `false` تنظیم کنید. +- `off`: پخش جریانی پیش‌نمایش زنده را غیرفعال می‌کند. +- `partial` (پیش‌فرض): متن پیش‌نمایش را با آخرین خروجی جزئی جایگزین می‌کند. +- `block`: به‌روزرسانی‌های پیش‌نمایش بخش‌بندی‌شده را اضافه می‌کند. +- `progress`: هنگام تولید، متن وضعیت پیشرفت را نشان می‌دهد، سپس متن نهایی را ارسال می‌کند. +- `streaming.preview.toolProgress`: وقتی پیش‌نمایش پیش‌نویس فعال است، به‌روزرسانی‌های ابزار/پیشرفت را به همان پیام پیش‌نمایش ویرایش‌شده مسیر‌دهی می‌کند (پیش‌فرض: `true`). برای نگه داشتن پیام‌های جداگانه ابزار/پیشرفت، روی `false` تنظیم کنید. +- `streaming.preview.commandText` / `streaming.progress.commandText`: برای حفظ خطوط فشرده پیشرفت ابزار هنگام پنهان کردن متن خام command/exec، روی `status` تنظیم کنید (پیش‌فرض: `raw`). -`channels.slack.streaming.nativeTransport` وقتی `channels.slack.streaming.mode` برابر `partial` باشد، streaming متن native در Slack را کنترل می‌کند (پیش‌فرض: `true`). +پنهان کردن متن خام command/exec در عین حفظ خطوط فشرده پیشرفت: -- برای نمایش streaming متن native و وضعیت thread دستیار Slack، یک thread پاسخ باید در دسترس باشد. انتخاب thread همچنان از `replyToMode` پیروی می‌کند. -- کانال، group-chat، و ریشه‌های DM سطح بالا همچنان می‌توانند وقتی native streaming در دسترس نیست یا thread پاسخی وجود ندارد از draft preview عادی استفاده کنند. -- DMهای سطح بالای Slack به‌طور پیش‌فرض خارج از thread می‌مانند، بنابراین preview native stream/status به سبک thread Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک draft preview در DM post و edit می‌کند. -- payloadهای رسانه‌ای و غیرمتنی به delivery عادی fallback می‌کنند. -- finalهای رسانه/خطا ویرایش‌های pending preview را cancel می‌کنند؛ finalهای واجد شرایط متن/block فقط وقتی flush می‌شوند که بتوانند preview را درجا edit کنند. -- اگر streaming در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به delivery عادی fallback می‌کند. +```json +{ + "channels": { + "slack": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` -استفاده از draft preview به‌جای streaming متن native در Slack: +`channels.slack.streaming.nativeTransport` پخش جریانی متن بومی Slack را وقتی `channels.slack.streaming.mode` برابر `partial` است کنترل می‌کند (پیش‌فرض: `true`). + +- برای ظاهر شدن پخش جریانی متن بومی و وضعیت رشته دستیار Slack، باید یک رشته پاسخ در دسترس باشد. انتخاب رشته همچنان از `replyToMode` پیروی می‌کند. +- ریشه‌های کانال، چت گروهی، و DM سطح بالا همچنان می‌توانند وقتی پخش جریانی بومی در دسترس نیست یا رشته پاسخی وجود ندارد، از پیش‌نمایش پیش‌نویس معمول استفاده کنند. +- DMهای سطح بالای Slack به‌صورت پیش‌فرض خارج از رشته می‌مانند، بنابراین پیش‌نمایش جریان/وضعیت بومی به سبک رشته Slack را نشان نمی‌دهند؛ OpenClaw به‌جای آن یک پیش‌نمایش پیش‌نویس را در DM ارسال و ویرایش می‌کند. +- رسانه و payloadهای غیرمتنی به تحویل معمول بازمی‌گردند. +- نتیجه‌های نهایی رسانه/خطا ویرایش‌های پیش‌نمایش معلق را لغو می‌کنند؛ نتیجه‌های نهایی متن/block واجد شرایط فقط وقتی flush می‌شوند که بتوانند پیش‌نمایش را درجا ویرایش کنند. +- اگر پخش جریانی در میانه پاسخ شکست بخورد، OpenClaw برای payloadهای باقی‌مانده به تحویل معمول بازمی‌گردد. + +استفاده از پیش‌نمایش پیش‌نویس به‌جای پخش جریانی متن بومی Slack: ```json5 { @@ -700,41 +719,41 @@ tagهای پاسخ دستی پشتیبانی می‌شوند: کلیدهای قدیمی: -- `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 می‌شود. +- `channels.slack.streamMode` (`replace | status_final | append`) به‌صورت خودکار به `channels.slack.streaming.mode` مهاجرت داده می‌شود. +- مقدار boolean `channels.slack.streaming` به‌صورت خودکار به `channels.slack.streaming.mode` و `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. +- `channels.slack.nativeStreaming` قدیمی به‌صورت خودکار به `channels.slack.streaming.nativeTransport` مهاجرت داده می‌شود. -## fallback واکنش typing +## جایگزین واکنش تایپ کردن -`typingReaction` هنگام پردازش پاسخ توسط OpenClaw، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و وقتی run پایان می‌یابد آن را حذف می‌کند. این بیرون از پاسخ‌های thread بیشترین کاربرد را دارد؛ پاسخ‌های thread از نشانگر وضعیت پیش‌فرض "is typing..." استفاده می‌کنند. +`typingReaction` هنگامی که OpenClaw در حال پردازش یک پاسخ است، یک واکنش موقت به پیام ورودی Slack اضافه می‌کند و سپس هنگام پایان اجرای کار آن را حذف می‌کند. این قابلیت بیشتر خارج از پاسخ‌های رشته‌ای مفید است؛ پاسخ‌های رشته‌ای از نشانگر وضعیت پیش‌فرض «در حال تایپ است...» استفاده می‌کنند. -ترتیب resolve: +ترتیب حل: - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` نکته‌ها: -- Slack انتظار shortcodeها را دارد (برای مثال `"hourglass_flowing_sand"`). -- واکنش به‌صورت best-effort انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود. +- Slack انتظار کدهای کوتاه دارد (برای مثال `"hourglass_flowing_sand"`). +- واکنش به‌صورت بهترین تلاش انجام می‌شود و پس از تکمیل مسیر پاسخ یا شکست، پاک‌سازی به‌طور خودکار تلاش می‌شود. -## رسانه، بخش‌بندی و تحویل +## رسانه، بخش‌بندی، و تحویل - پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احراز هویت‌شده با توکن) و وقتی واکشی موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جای‌نگهدارهای فایل شامل `fileId` مربوط به Slack هستند تا عامل‌ها بتوانند فایل اصلی را با `download-file` واکشی کنند. + پیوست‌های فایل Slack از URLهای خصوصی میزبانی‌شده توسط Slack دانلود می‌شوند (جریان درخواست احراز هویت‌شده با توکن) و وقتی واکشی موفق باشد و محدودیت‌های اندازه اجازه دهند، در مخزن رسانه نوشته می‌شوند. جای‌نگهدارهای فایل شامل `fileId` مربوط به Slack هستند تا agentها بتوانند فایل اصلی را با `download-file` واکشی کنند. - دانلودها از timeoutهای idle و کل محدودشده استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جای‌نگهدار فایل fallback می‌کند. + دانلودها از timeoutهای محدود برای بیکاری و کل زمان استفاده می‌کنند. اگر بازیابی فایل Slack متوقف شود یا شکست بخورد، OpenClaw پردازش پیام را ادامه می‌دهد و به جای‌نگهدار فایل برمی‌گردد. - سقف اندازه ورودی runtime به‌طور پیش‌فرض `20MB` است، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود. + سقف اندازه ورودی در زمان اجرا به‌طور پیش‌فرض `20MB` است، مگر اینکه با `channels.slack.mediaMaxMb` بازنویسی شود. - بخش‌های متن از `channels.slack.textChunkLimit` استفاده می‌کنند (پیش‌فرض 4000) - `channels.slack.chunkMode="newline"` تقسیم‌بندی با اولویت پاراگراف را فعال می‌کند - - ارسال فایل از APIهای آپلود Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های thread (`thread_ts`) باشد - - سقف رسانه خروجی، وقتی پیکربندی شده باشد، از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در pipeline رسانه استفاده می‌کنند + - ارسال فایل‌ها از APIهای بارگذاری Slack استفاده می‌کند و می‌تواند شامل پاسخ‌های رشته‌ای (`thread_ts`) باشد + - سقف رسانه خروجی هنگام پیکربندی از `channels.slack.mediaMaxMb` پیروی می‌کند؛ در غیر این صورت ارسال‌های کانال از پیش‌فرض‌های نوع MIME در pipeline رسانه استفاده می‌کنند @@ -744,14 +763,14 @@ tagهای پاسخ دستی پشتیبانی می‌شوند: - `user:` برای DMها - `channel:` برای کانال‌ها - DMهای Slack که فقط متن/بلاک دارند می‌توانند مستقیماً به شناسه‌های کاربر post شوند؛ آپلود فایل و ارسال‌های thread ابتدا DM را از طریق APIهای مکالمه Slack باز می‌کنند، زیرا این مسیرها به یک شناسه مکالمه مشخص نیاز دارند. + DMهای Slack فقط متنی/بلوکی می‌توانند مستقیماً به شناسه‌های کاربر ارسال شوند؛ بارگذاری فایل و ارسال‌های رشته‌ای ابتدا DM را از طریق APIهای گفت‌وگوی Slack باز می‌کنند، چون آن مسیرها به یک شناسه گفت‌وگوی مشخص نیاز دارند. ## دستورها و رفتار slash -دستورهای slash در Slack یا به‌صورت یک دستور پیکربندی‌شده واحد ظاهر می‌شوند یا چند دستور native. برای تغییر پیش‌فرض‌های دستور، `channels.slack.slashCommand` را پیکربندی کنید: +دستورهای slash در Slack یا به‌صورت یک دستور پیکربندی‌شده واحد ظاهر می‌شوند یا به‌صورت چند دستور native. برای تغییر پیش‌فرض‌های دستور، `channels.slack.slashCommand` را پیکربندی کنید: - `enabled: false` - `name: "openclaw"` @@ -762,7 +781,7 @@ tagهای پاسخ دستی پشتیبانی می‌شوند: /openclaw /help ``` -دستورهای native به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و در عوض با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. +دستورهای native به [تنظیمات manifest اضافی](#additional-manifest-settings) در برنامه Slack شما نیاز دارند و به‌جای آن با `channels.slack.commands.native: true` یا `commands.native: true` در پیکربندی‌های سراسری فعال می‌شوند. - حالت خودکار دستور native برای Slack **خاموش** است، بنابراین `commands.native: "auto"` دستورهای native Slack را فعال نمی‌کند. @@ -770,24 +789,24 @@ tagهای پاسخ دستی پشتیبانی می‌شوند: /help ``` -منوهای آرگومان native از راهبرد رندر تطبیقی استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد: +منوهای آرگومان native از یک راهبرد رندر تطبیقی استفاده می‌کنند که پیش از dispatch کردن مقدار گزینه انتخاب‌شده، یک modal تأیید نشان می‌دهد: -- تا 5 گزینه: بلاک‌های دکمه -- 6 تا 100 گزینه: منوی انتخاب static -- بیش از 100 گزینه: انتخاب external با فیلترسازی گزینه async وقتی handlerهای گزینه‌های interactivity در دسترس باشند -- عبور از محدودیت‌های Slack: مقادیر گزینه encoded به دکمه‌ها fallback می‌کنند +- تا 5 گزینه: بلوک‌های دکمه +- 6 تا 100 گزینه: منوی انتخاب ایستا +- بیش از 100 گزینه: انتخاب خارجی با فیلتر ناهمگام گزینه‌ها وقتی handlerهای گزینه‌های interactivity در دسترس باشند +- عبور از محدودیت‌های Slack: مقدارهای کدگذاری‌شده گزینه به دکمه‌ها برمی‌گردند ```txt /think ``` -نشست‌های slash از کلیدهای ایزوله مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست مکالمه هدف route می‌کنند. +نشست‌های slash از کلیدهای جداشده‌ای مانند `agent::slack:slash:` استفاده می‌کنند و همچنان اجرای دستورها را با استفاده از `CommandTargetSessionKey` به نشست گفت‌وگوی مقصد route می‌کنند. ## پاسخ‌های تعاملی -Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط عامل را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است. +Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌شده توسط agent را رندر کند، اما این قابلیت به‌طور پیش‌فرض غیرفعال است. -آن را به‌صورت سراسری فعال کنید: +فعال‌سازی سراسری: ```json5 { @@ -801,7 +820,7 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌ } ``` -یا آن را فقط برای یک حساب Slack فعال کنید: +یا فقط برای یک حساب Slack فعال کنید: ```json5 { @@ -819,44 +838,44 @@ Slack می‌تواند کنترل‌های پاسخ تعاملی نوشته‌ } ``` -وقتی فعال باشد، عامل‌ها می‌توانند directiveهای پاسخ فقط مخصوص Slack تولید کنند: +پس از فعال‌سازی، agentها می‌توانند دستورهای پاسخ فقط مخصوص Slack منتشر کنند: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -این directiveها به Slack Block Kit کامپایل می‌شوند و clickها یا انتخاب‌ها را از مسیر event تعامل Slack موجود دوباره route می‌کنند. +این دستورها به Slack Block Kit کامپایل می‌شوند و کلیک‌ها یا انتخاب‌ها را از مسیر موجود رویداد تعامل Slack برمی‌گردانند. -یادداشت‌ها: +نکته‌ها: -- این UI مخصوص Slack است. کانال‌های دیگر directiveهای Slack Block Kit را به سامانه‌های دکمه خودشان ترجمه نمی‌کنند. -- مقادیر callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقادیر خام نوشته‌شده توسط عامل. -- اگر بلاک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit عبور کنند، OpenClaw به‌جای ارسال payload بلاک‌های نامعتبر، به پاسخ متنی اصلی fallback می‌کند. +- این UI مخصوص Slack است. کانال‌های دیگر دستورهای Slack Block Kit را به سیستم‌های دکمه خودشان ترجمه نمی‌کنند. +- مقدارهای callback تعاملی، توکن‌های opaque تولیدشده توسط OpenClaw هستند، نه مقدارهای خام نوشته‌شده توسط agent. +- اگر بلوک‌های تعاملی تولیدشده از محدودیت‌های Slack Block Kit فراتر بروند، OpenClaw به‌جای ارسال payload بلوک‌های نامعتبر، به پاسخ متنی اصلی برمی‌گردد. ## تأییدهای exec در Slack -Slack می‌تواند به‌جای fallback کردن به Web UI یا ترمینال، به‌عنوان یک client تأیید native با دکمه‌ها و تعامل‌های تعاملی عمل کند. +Slack می‌تواند به‌جای برگشت به Web UI یا ترمینال، با دکمه‌ها و تعامل‌های تعاملی به‌عنوان یک client تأیید native عمل کند. -- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن native در DM/کانال استفاده می‌کنند. -- تأییدهای Plugin همچنان می‌توانند از طریق همان سطح دکمه native Slack resolve شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد. -- مجوزدهی تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند از طریق Slack درخواست‌ها را تأیید یا رد کنند. +- تأییدهای exec از `channels.slack.execApprovals.*` برای route کردن native به DM/کانال استفاده می‌کنند. +- تأییدهای Plugin همچنان می‌توانند از همان سطح دکمه native در Slack حل شوند، وقتی درخواست از قبل در Slack فرود آمده باشد و نوع شناسه تأیید `plugin:` باشد. +- مجوز تأییدکننده همچنان اعمال می‌شود: فقط کاربرانی که به‌عنوان تأییدکننده شناسایی شده‌اند می‌توانند درخواست‌ها را از طریق Slack تأیید یا رد کنند. -این از همان سطح دکمه تأیید مشترک مانند کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در مکالمه به‌صورت دکمه‌های Block Kit رندر می‌شوند. -وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید هستند؛ OpenClaw -فقط باید زمانی یک دستور دستی `/approve` اضافه کند که نتیجه ابزار بگوید تأییدهای chat +این از همان سطح مشترک دکمه تأیید مثل کانال‌های دیگر استفاده می‌کند. وقتی `interactivity` در تنظیمات برنامه Slack شما فعال باشد، promptهای تأیید مستقیماً در گفت‌وگو به‌صورت دکمه‌های Block Kit رندر می‌شوند. +وقتی آن دکمه‌ها وجود دارند، UX اصلی تأیید همان‌ها هستند؛ OpenClaw +فقط وقتی باید دستور دستی `/approve` را اضافه کند که نتیجه ابزار بگوید تأییدهای chat در دسترس نیستند یا تأیید دستی تنها مسیر است. مسیر پیکربندی: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (اختیاری؛ وقتی ممکن باشد به `commands.ownerAllowFrom` fallback می‌کند) +- `channels.slack.execApprovals.approvers` (اختیاری؛ در صورت امکان به `commands.ownerAllowFrom` برمی‌گردد) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`، پیش‌فرض: `dm`) - `agentFilter`, `sessionFilter` -وقتی `enabled` تنظیم نشده یا `"auto"` باشد و دست‌کم یک -تأییدکننده resolve شود، Slack تأییدهای exec native را به‌طور خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان client تأیید native، `enabled: false` را تنظیم کنید. -برای اجبار به روشن بودن تأییدهای native وقتی تأییدکننده‌ها resolve می‌شوند، `enabled: true` را تنظیم کنید. +Slack وقتی `enabled` تنظیم نشده باشد یا `"auto"` باشد و دست‌کم یک +تأییدکننده حل شود، تأییدهای exec native را به‌طور خودکار فعال می‌کند. برای غیرفعال کردن صریح Slack به‌عنوان client تأیید native، `enabled: false` را تنظیم کنید. +برای اجبار به فعال‌سازی تأییدهای native وقتی تأییدکننده‌ها حل می‌شوند، `enabled: true` را تنظیم کنید. -رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec Slack: +رفتار پیش‌فرض بدون پیکربندی صریح تأیید exec در Slack: ```json5 { @@ -866,8 +885,8 @@ Slack می‌تواند به‌جای fallback کردن به Web UI یا ترم } ``` -پیکربندی صریح native برای Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، فیلتر اضافه کنید، یا -به تحویل در chat مبدأ opt in کنید: +پیکربندی صریح native مربوط به Slack فقط زمانی لازم است که بخواهید تأییدکننده‌ها را بازنویسی کنید، filter اضافه کنید، یا +تحویل به chat مبدأ را فعال کنید: ```json5 { @@ -883,37 +902,37 @@ Slack می‌تواند به‌جای fallback کردن به Web UI یا ترم } ``` -forward کردن مشترک `approvals.exec` جداست. فقط زمانی از آن استفاده کنید که promptهای تأیید exec باید همچنین -به chatهای دیگر یا مقصدهای out-of-band صریح route شوند. forward کردن مشترک `approvals.plugin` نیز -جداست؛ دکمه‌های native Slack همچنان می‌توانند تأییدهای Plugin را resolve کنند، وقتی آن درخواست‌ها از قبل +forwarding مشترک `approvals.exec` جدا است. فقط وقتی از آن استفاده کنید که promptهای تأیید exec باید همچنین +به chatهای دیگر یا مقصدهای out-of-band صریح route شوند. forwarding مشترک `approvals.plugin` نیز +جدا است؛ دکمه‌های native Slack همچنان می‌توانند تأییدهای Plugin را حل کنند، وقتی آن درخواست‌ها از قبل در Slack فرود آمده باشند. -`/approve` در همان chat نیز در کانال‌ها و DMهای Slack که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forward کردن تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید. +`/approve` در همان chat نیز در کانال‌ها و DMهای Slack که از قبل از دستورها پشتیبانی می‌کنند کار می‌کند. برای مدل کامل forwarding تأیید، [تأییدهای exec](/fa/tools/exec-approvals) را ببینید. -## eventها و رفتار عملیاتی +## رویدادها و رفتار عملیاتی -- ویرایش/حذف پیام‌ها به eventهای سامانه map می‌شوند. -- broadcastهای thread (پاسخ‌های thread با گزینه «همچنین به کانال ارسال شود») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند. -- eventهای افزودن/حذف واکنش به eventهای سامانه map می‌شوند. -- eventهای پیوستن/خروج عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به eventهای سامانه map می‌شوند. -- `channel_id_changed` می‌تواند وقتی `configWrites` فعال باشد، کلیدهای پیکربندی کانال را migrate کند. -- فراداده topic/purpose کانال به‌عنوان context غیرقابل اعتماد تلقی می‌شود و می‌تواند به context routing تزریق شود. -- آغازگر thread و seeding context تاریخچه اولیه thread، در صورت کاربرد، با allowlistهای فرستنده پیکربندی‌شده فیلتر می‌شوند. -- کنش‌های بلاک و تعامل‌های modal، eventهای ساختاریافته سامانه با قالب `Slack interaction: ...` و fieldهای payload غنی تولید می‌کنند: - - کنش‌های بلاک: مقادیر انتخاب‌شده، برچسب‌ها، مقادیر picker و فراداده `workflow_*` - - eventهای modal `view_submission` و `view_closed` با فراداده کانال routeشده و ورودی‌های فرم +- ویرایش/حذف پیام‌ها به رویدادهای سیستم نگاشت می‌شوند. +- پخش‌های رشته‌ای (پاسخ‌های رشته‌ای «Also send to channel») به‌عنوان پیام‌های عادی کاربر پردازش می‌شوند. +- رویدادهای افزودن/حذف واکنش به رویدادهای سیستم نگاشت می‌شوند. +- رویدادهای پیوستن/ترک عضو، ایجاد/تغییرنام کانال، و افزودن/حذف pin به رویدادهای سیستم نگاشت می‌شوند. +- وقتی `configWrites` فعال باشد، `channel_id_changed` می‌تواند کلیدهای پیکربندی کانال را migrate کند. +- metadata موضوع/هدف کانال به‌عنوان context غیرقابل اعتماد در نظر گرفته می‌شود و می‌تواند به context route کردن inject شود. +- آغازکننده رشته و seed کردن context اولیه تاریخچه رشته، در صورت کاربرد، بر اساس allowlistهای فرستنده پیکربندی‌شده filter می‌شوند. +- کنش‌های بلوک و تعامل‌های modal رویدادهای ساخت‌یافته سیستم `Slack interaction: ...` را با فیلدهای payload غنی منتشر می‌کنند: + - کنش‌های بلوک: مقدارهای انتخاب‌شده، labelها، مقدارهای picker، و metadata مربوط به `workflow_*` + - رویدادهای modal `view_submission` و `view_closed` با metadata کانال route‌شده و ورودی‌های فرم ## مرجع پیکربندی مرجع اصلی: [مرجع پیکربندی - Slack](/fa/gateway/config-channels#slack). - + - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` -- دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` +- دسترسی DM: `dm.enabled`, `dmPolicy`, `allowFrom` (قدیمی: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - toggle سازگاری: `dangerouslyAllowNameMatching` (break-glass؛ مگر در صورت نیاز خاموش نگه دارید) - دسترسی کانال: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- thread/history: `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` @@ -922,13 +941,13 @@ forward کردن مشترک `approvals.exec` جداست. فقط زمانی از ## عیب‌یابی - + به‌ترتیب بررسی کنید: - `groupPolicy` - - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام تحت `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، زیرا routing کانال به‌طور پیش‌فرض ابتدا بر اساس شناسه است. برای یافتن شناسه: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است. + - allowlist کانال (`channels.slack.channels`) — **کلیدها باید شناسه کانال باشند** (`C12345678`)، نه نام‌ها (`#channel-name`). کلیدهای مبتنی بر نام زیر `groupPolicy: "allowlist"` بی‌صدا شکست می‌خورند، چون route کردن کانال به‌طور پیش‌فرض ID-first است. برای پیدا کردن یک ID: روی کانال در Slack راست‌کلیک کنید → **Copy link** — مقدار `C...` در انتهای URL شناسه کانال است. - `requireMention` - - allowlist کاربران برای هر کانال + - allowlist کاربران در سطح هر کانال دستورهای مفید: @@ -944,11 +963,11 @@ openclaw doctor بررسی کنید: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (یا legacy `channels.slack.dm.policy`) + - `channels.slack.dmPolicy` (یا گزینه قدیمی `channels.slack.dm.policy`) - تأییدهای pairing / ورودی‌های allowlist - - eventهای DM دستیار Slack: لاگ‌های verbose که به `drop message_changed` اشاره می‌کنند - معمولاً یعنی Slack یک event ویرایش‌شده thread دستیار را بدون - فرستنده انسانی قابل بازیابی در فراداده پیام ارسال کرده است + - رویدادهای DM مربوط به Slack Assistant: logهای verbose که `drop message_changed` را ذکر می‌کنند + معمولاً یعنی Slack یک رویداد ویرایش‌شده Assistant-thread بدون + فرستنده انسانی قابل بازیابی در metadata پیام فرستاده است ```bash openclaw pairing list slack @@ -957,16 +976,16 @@ 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 را + پیکربندی شده است اما runtime فعلی نتوانسته مقدار پشتیبانی‌شده با SecretRef را resolve کند. - + اعتبارسنجی کنید: - signing secret @@ -975,106 +994,106 @@ openclaw pairing list slack - `webhookPath` یکتا برای هر حساب HTTP اگر `signingSecretStatus: "configured_unavailable"` در snapshotهای حساب - ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته signing secret پشتوانه‌شده با SecretRef را - resolve کند. + ظاهر شود، حساب HTTP پیکربندی شده است اما runtime فعلی نتوانسته + signing secret پشتیبانی‌شده با SecretRef را resolve کند. - بررسی کنید که کدام را مدنظر داشتید: + بررسی کنید که منظورتان کدام بوده است: - حالت دستور native (`channels.slack.commands.native: true`) با دستورهای slash متناظر ثبت‌شده در Slack - - یا حالت تک دستور slash (`channels.slack.slashCommand.enabled: true`) + - یا حالت دستور slash واحد (`channels.slack.slashCommand.enabled: true`) همچنین `commands.useAccessGroups` و allowlistهای کانال/کاربر را بررسی کنید. -## مرجع vision پیوست‌ها +## مرجع vision پیوست -Slack می‌تواند وقتی دانلود فایل‌های Slack موفق باشد و محدودیت‌های اندازه اجازه دهند، رسانه دانلودشده را به turn عامل پیوست کند. فایل‌های تصویری می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به یک مدل پاسخ vision-capable داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر تلقی شوند، به‌صورت context فایل قابل دانلود نگه داشته می‌شوند. +Slack وقتی دانلود فایل‌های Slack موفق باشند و محدودیت‌های اندازه اجازه دهند، می‌تواند رسانه دانلودشده را به turn مربوط به agent پیوست کند. فایل‌های تصویر می‌توانند از مسیر درک رسانه عبور داده شوند یا مستقیماً به مدل پاسخ دارای قابلیت vision داده شوند؛ فایل‌های دیگر به‌جای اینکه به‌عنوان ورودی تصویر در نظر گرفته شوند، به‌عنوان context فایل قابل دانلود نگه داشته می‌شوند. ### انواع رسانه پشتیبانی‌شده | نوع رسانه | منبع | رفتار فعلی | یادداشت‌ها | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود و برای پردازش با قابلیت بینایی به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض ۲۰ MB) | -| فایل‌های PDF | URL فایل Slack | دانلود و به‌عنوان زمینهٔ فایل برای ابزارهایی مانند `download-file` یا `pdf` ارائه می‌شود | ورودی Slack به‌طور خودکار PDFها را به ورودی بینایی تصویری تبدیل نمی‌کند | -| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود و به‌عنوان زمینهٔ فایل ارائه می‌شود | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | -| پاسخ‌های رشته | فایل‌های شروع‌کنندهٔ رشته | وقتی پاسخ رسانهٔ مستقیم ندارد، فایل‌های پیام ریشه می‌توانند به‌عنوان زمینه آماده‌سازی شوند | شروع‌کننده‌های فقط‌فایل از جای‌نگهدار پیوست استفاده می‌کنند | -| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌طور مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است | +| تصاویر JPEG / PNG / GIF / WebP | URL فایل Slack | دانلود می‌شود و برای پردازش دارای قابلیت بینایی به نوبت پیوست می‌شود | سقف هر فایل: `channels.slack.mediaMaxMb` (پیش‌فرض 20 MB) | +| فایل‌های PDF | URL فایل Slack | دانلود می‌شود و به‌عنوان زمینهٔ فایل برای ابزارهایی مانند `download-file` یا `pdf` در دسترس قرار می‌گیرد | ورودی Slack به‌طور خودکار PDFها را به ورودی بینایی تصویر تبدیل نمی‌کند | +| فایل‌های دیگر | URL فایل Slack | در صورت امکان دانلود می‌شود و به‌عنوان زمینهٔ فایل در دسترس قرار می‌گیرد | فایل‌های باینری به‌عنوان ورودی تصویر در نظر گرفته نمی‌شوند | +| پاسخ‌های رشته | فایل‌های آغازگر رشته | فایل‌های پیام ریشه وقتی پاسخ رسانهٔ مستقیم ندارد می‌توانند به‌عنوان زمینه بارگذاری شوند | آغازگرهای فقط‌فایل از یک جای‌نگهدار پیوست استفاده می‌کنند | +| پیام‌های چندتصویری | چند فایل Slack | هر فایل به‌صورت مستقل ارزیابی می‌شود | پردازش Slack به هشت فایل برای هر پیام محدود است | ### خط لولهٔ ورودی -وقتی یک پیام Slack همراه با پیوست‌های فایل می‌رسد: +وقتی یک پیام Slack با پیوست‌های فایل می‌رسد: 1. OpenClaw فایل را از URL خصوصی Slack با استفاده از توکن ربات (`xoxb-...`) دانلود می‌کند. -2. در صورت موفقیت، فایل در ذخیره‌گاه رسانه نوشته می‌شود. +2. فایل در صورت موفقیت در انبار رسانه نوشته می‌شود. 3. مسیرهای رسانهٔ دانلودشده و نوع‌های محتوا به زمینهٔ ورودی افزوده می‌شوند. -4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویری آن زمینه استفاده کنند. +4. مسیرهای مدل/ابزار دارای قابلیت تصویر می‌توانند از پیوست‌های تصویر موجود در آن زمینه استفاده کنند. 5. فایل‌های غیرتصویری همچنان به‌صورت فرادادهٔ فایل یا ارجاع‌های رسانه برای ابزارهایی که می‌توانند آن‌ها را پردازش کنند در دسترس می‌مانند. -### ارث‌بری پیوست از ریشهٔ رشته +### وراثت پیوست ریشهٔ رشته -وقتی پیامی در یک رشته می‌رسد (دارای والد `thread_ts` است): +وقتی پیامی در یک رشته می‌رسد (یک والد `thread_ts` دارد): -- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ شامل‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ شروع‌کنندهٔ رشته آماده‌سازی کند. +- اگر خود پاسخ رسانهٔ مستقیم نداشته باشد و پیام ریشهٔ گنجانده‌شده فایل داشته باشد، Slack می‌تواند فایل‌های ریشه را به‌عنوان زمینهٔ آغازگر رشته بارگذاری کند. - پیوست‌های مستقیم پاسخ بر پیوست‌های پیام ریشه اولویت دارند. -- پیام ریشه‌ای که فقط فایل دارد و متن ندارد، با یک جای‌نگهدار پیوست نمایش داده می‌شود تا مسیر جایگزین همچنان بتواند فایل‌های آن را شامل کند. +- پیام ریشه‌ای که فقط فایل دارد و متن ندارد با یک جای‌نگهدار پیوست نمایش داده می‌شود تا مسیر پشتیبان همچنان بتواند فایل‌های آن را شامل شود. -### پردازش چندپیوستی +### مدیریت چند پیوست وقتی یک پیام Slack شامل چند پیوست فایل باشد: -- هر پیوست به‌طور مستقل از خط لولهٔ رسانه پردازش می‌شود. +- هر پیوست به‌صورت مستقل از طریق خط لولهٔ رسانه پردازش می‌شود. - ارجاع‌های رسانهٔ دانلودشده در زمینهٔ پیام تجمیع می‌شوند. -- ترتیب پردازش از ترتیب فایل‌های Slack در payload رویداد پیروی می‌کند. -- شکست در دانلود یک پیوست، پیوست‌های دیگر را مسدود نمی‌کند. +- ترتیب پردازش از ترتیب فایل‌های Slack در بار رویداد پیروی می‌کند. +- شکست در دانلود یک پیوست، سایر پیوست‌ها را مسدود نمی‌کند. ### محدودیت‌های اندازه، دانلود و مدل -- **سقف اندازه**: پیش‌فرض ۲۰ 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` را پیکربندی کنید یا از مدل پاسخ دارای قابلیت بینایی استفاده کنید | -| تصاویر بسیار بزرگ (بیش از ۲۰ 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) - [ابزار PDF](/fa/tools/pdf) -- اپیک: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی برای پیوست‌های Slack +- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — فعال‌سازی بینایی پیوست‌های Slack - آزمون‌های رگرسیون: [#51353](https://github.com/openclaw/openclaw/issues/51353) - راستی‌آزمایی زنده: [#51354](https://github.com/openclaw/openclaw/issues/51354) ## مرتبط - - یک کاربر Slack را با Gateway جفت کنید. + + یک کاربر Slack را به Gateway جفت کنید. - - رفتار کانال و پیام مستقیم گروهی. + + رفتار کانال و DM گروهی. - + پیام‌های ورودی را به عامل‌ها مسیریابی کنید. - + مدل تهدید و سخت‌سازی. - - چیدمان پیکربندی و تقدم. + + چیدمان پیکربندی و اولویت‌بندی. - + فهرست فرمان‌ها و رفتار. diff --git a/docs/fa/channels/telegram.md b/docs/fa/channels/telegram.md index 6c30a64de..faede34d1 100644 --- a/docs/fa/channels/telegram.md +++ b/docs/fa/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - - کار روی قابلیت‌های Telegram یا Webhookها -summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Telegram + - کار روی قابلیت‌های Telegram یا Webhook‌ها +summary: وضعیت پشتیبانی ربات Telegram، قابلیت‌ها و پیکربندی title: Telegram x-i18n: - generated_at: "2026-05-03T21:27:10Z" + generated_at: "2026-05-04T07:02:42Z" model: gpt-5.5 provider: openai - source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0 + source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6 source_path: channels/telegram.md workflow: 16 --- -آماده برای تولید برای DMهای ربات و گروه‌ها از طریق grammY. حالت پیش‌فرض، long polling است؛ حالت Webhook اختیاری است. +آمادهٔ تولید برای DMهای ربات و گروه‌ها از طریق grammY. حالت پیش‌فرض long polling است؛ حالت Webhook اختیاری است. - سیاست پیش‌فرض DM برای Telegram جفت‌سازی است. + سیاست DM پیش‌فرض برای Telegram جفت‌سازی است. - عیب‌یابی‌های میان‌کانالی و راهنماهای تعمیر. + عیب‌یابی‌های میان‌کانالی و راهنماهای رفع مشکل. الگوها و مثال‌های کامل پیکربندی کانال. @@ -30,7 +30,7 @@ x-i18n: - Telegram را باز کنید و با **@BotFather** گفت‌وگو کنید (مطمئن شوید handle دقیقاً `@BotFather` است). + Telegram را باز کنید و با **@BotFather** گفتگو کنید (تأیید کنید که شناسه دقیقاً `@BotFather` است). دستور `/newbot` را اجرا کنید، اعلان‌ها را دنبال کنید، و توکن را ذخیره کنید. @@ -51,7 +51,7 @@ x-i18n: } ``` - fallback محیطی: `TELEGRAM_BOT_TOKEN=...` (فقط حساب پیش‌فرض). + جایگزین env: `TELEGRAM_BOT_TOKEN=...` (فقط حساب پیش‌فرض). Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در config/env پیکربندی کنید، سپس gateway را شروع کنید. @@ -74,35 +74,35 @@ openclaw pairing approve telegram -ترتیب resolve شدن توکن، وابسته به حساب است. در عمل، مقادیر config بر fallback محیطی اولویت دارند، و `TELEGRAM_BOT_TOKEN` فقط روی حساب پیش‌فرض اعمال می‌شود. +ترتیب حل توکن از حساب آگاه است. در عمل، مقدارهای config بر جایگزین env اولویت دارند، و `TELEGRAM_BOT_TOKEN` فقط برای حساب پیش‌فرض اعمال می‌شود. ## تنظیمات سمت Telegram - - ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند، که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند. + + ربات‌های Telegram به‌صورت پیش‌فرض در **Privacy Mode** هستند، که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند. اگر ربات باید همه پیام‌های گروه را ببیند، یکی از این کارها را انجام دهید: - - privacy mode را از طریق `/setprivacy` غیرفعال کنید، یا - - ربات را admin گروه کنید. + - حالت حریم خصوصی را از طریق `/setprivacy` غیرفعال کنید، یا + - ربات را مدیر گروه کنید. - هنگام تغییر privacy mode، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند. + هنگام تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند. - وضعیت admin در تنظیمات گروه Telegram کنترل می‌شود. + وضعیت مدیر بودن در تنظیمات گروه Telegram کنترل می‌شود. - ربات‌های admin همه پیام‌های گروه را دریافت می‌کنند، که برای رفتار گروهی همیشه‌فعال مفید است. + ربات‌های مدیر همه پیام‌های گروه را دریافت می‌کنند، که برای رفتار همیشه‌فعال در گروه مفید است. - + - - `/setjoingroups` برای اجازه دادن یا ندادن به افزودن به گروه - - `/setprivacy` برای رفتار دیده‌شدن در گروه + - `/setjoingroups` برای مجاز/غیرمجاز کردن افزودن به گروه‌ها + - `/setprivacy` برای رفتار مشاهده‌پذیری گروه @@ -114,25 +114,25 @@ openclaw pairing approve telegram `channels.telegram.dmPolicy` دسترسی پیام مستقیم را کنترل می‌کند: - `pairing` (پیش‌فرض) - - `allowlist` (حداقل به یک شناسه فرستنده در `allowFrom` نیاز دارد) - - `open` (نیاز دارد `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 صریح باشد. + در configهای چندحسابی، یک `channels.telegram.allowFrom` محدودکننده در سطح بالا به‌عنوان مرز ایمنی در نظر گرفته می‌شود: ورودی‌های سطح حساب `allowFrom: ["*"]` آن حساب را عمومی نمی‌کنند مگر اینکه allowlist مؤثر حساب پس از ادغام همچنان یک wildcard صریح داشته باشد. `dmPolicy: "allowlist"` با `allowFrom` خالی همه DMها را مسدود می‌کند و توسط اعتبارسنجی config رد می‌شود. راه‌اندازی فقط شناسه‌های عددی کاربر را درخواست می‌کند. - اگر ارتقا داده‌اید و config شما شامل ورودی‌های allowlist به شکل `@username` است، برای resolve کردن آن‌ها `openclaw doctor --fix` را اجرا کنید (تا حد امکان؛ به توکن ربات Telegram نیاز دارد). - اگر پیش‌تر به فایل‌های allowlist در pairing-store متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را در جریان‌های allowlist به `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد). + اگر ارتقا داده‌اید و config شما شامل ورودی‌های allowlist از نوع `@username` است، برای حل آن‌ها `openclaw doctor --fix` را اجرا کنید (بهترین تلاش؛ نیازمند توکن ربات Telegram). + اگر قبلاً به فایل‌های allowlist ذخیره جفت‌سازی متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را در جریان‌های allowlist به `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد). - برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` با شناسه‌های عددی صریح `allowFrom` را ترجیح دهید تا سیاست دسترسی در config پایدار بماند (به‌جای وابستگی به تأییدهای جفت‌سازی قبلی). + برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` را با شناسه‌های عددی صریح `allowFrom` ترجیح دهید تا سیاست دسترسی در config پایدار بماند (به‌جای وابستگی به تأییدهای قبلی جفت‌سازی). - سردرگمی رایج: تأیید جفت‌سازی DM به معنی «این فرستنده همه‌جا مجاز است» نیست. - جفت‌سازی دسترسی DM می‌دهد. اگر هنوز مالک فرمانی وجود نداشته باشد، اولین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند. - مجوز فرستنده گروه همچنان از allowlistهای صریح config می‌آید. - اگر می‌خواهید «من یک‌بار مجاز شوم و هم DMها و هم فرمان‌های گروهی کار کنند»، شناسه عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:` است. + ابهام رایج: تأیید جفت‌سازی DM به معنی «این فرستنده در همه‌جا مجاز است» نیست. + جفت‌سازی دسترسی DM را اعطا می‌کند. اگر هنوز مالک فرمانی وجود نداشته باشد، اولین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند تا فرمان‌های فقط‌مالک و تأییدهای exec یک حساب اپراتور صریح داشته باشند. + مجوز فرستنده در گروه همچنان از allowlistهای صریح config می‌آید. + اگر می‌خواهید «یک‌بار مجاز شوم و هم DMها و هم فرمان‌های گروه کار کنند»، شناسه عددی کاربر Telegram خود را در `channels.telegram.allowFrom` قرار دهید؛ برای فرمان‌های فقط‌مالک، مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:` است. ### یافتن شناسه کاربر Telegram شما @@ -148,7 +148,7 @@ openclaw pairing approve telegram curl "https://api.telegram.org/bot/getUpdates" ``` - روش شخص ثالث (با حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`. + روش شخص ثالث (کمتر خصوصی): `@userinfobot` یا `@getidsbot`. @@ -156,10 +156,10 @@ curl "https://api.telegram.org/bot/getUpdates" دو کنترل با هم اعمال می‌شوند: 1. **کدام گروه‌ها مجاز هستند** (`channels.telegram.groups`) - - بدون config برای `groups`: - - با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسه گروه را پاس کند - - با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه نکنید مسدود می‌شوند - - `groups` پیکربندی‌شده: به‌عنوان allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`) + - بدون config مربوط به `groups`: + - با `groupPolicy: "open"`: هر گروهی می‌تواند بررسی‌های شناسه گروه را بگذراند + - با `groupPolicy: "allowlist"` (پیش‌فرض): گروه‌ها مسدود می‌شوند تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه کنید + - وقتی `groups` پیکربندی شده باشد: مانند allowlist عمل می‌کند (شناسه‌های صریح یا `"*"`) 2. **کدام فرستنده‌ها در گروه‌ها مجاز هستند** (`channels.telegram.groupPolicy`) - `open` @@ -168,15 +168,15 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` برای فیلتر کردن فرستنده گروه استفاده می‌شود. اگر تنظیم نشده باشد، Telegram به `allowFrom` برمی‌گردد. ورودی‌های `groupAllowFrom` باید شناسه‌های عددی کاربر Telegram باشند (پیشوندهای `telegram:` / `tg:` نرمال‌سازی می‌شوند). - شناسه‌های chat گروه یا supergroup در Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های chat منفی باید زیر `channels.telegram.groups` قرار بگیرند. + شناسه‌های گفتگوی گروه یا ابرگروه Telegram را در `groupAllowFrom` قرار ندهید. شناسه‌های منفی گفتگو زیر `channels.telegram.groups` قرار می‌گیرند. ورودی‌های غیرعددی برای مجوز فرستنده نادیده گرفته می‌شوند. - مرز امنیتی (`2026.2.25+`): احراز مجوز فرستنده گروه، تأییدهای pairing-store مربوط به DM را به ارث **نمی‌برد**. - جفت‌سازی فقط برای DM باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر topic را تنظیم کنید. - اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به `allowFrom` در config برمی‌گردد، نه pairing store. + مرز امنیتی (`2026.2.25+`): احراز هویت فرستنده گروه، تأییدهای ذخیره جفت‌سازی DM را به ارث **نمی‌برد**. + جفت‌سازی فقط برای DM باقی می‌ماند. برای گروه‌ها، `groupAllowFrom` یا `allowFrom` در سطح هر گروه/هر موضوع را تنظیم کنید. + اگر `groupAllowFrom` تنظیم نشده باشد، Telegram به config `allowFrom` برمی‌گردد، نه ذخیره جفت‌سازی. الگوی عملی برای ربات‌های تک‌مالک: شناسه کاربر خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده بگذارید، و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید. - نکته runtime: اگر `channels.telegram` کاملاً وجود نداشته باشد، runtime به‌صورت پیش‌فرض fail-closed با `groupPolicy="allowlist"` کار می‌کند، مگر اینکه `channels.defaults.groupPolicy` صریحاً تنظیم شده باشد. + نکته زمان اجرا: اگر `channels.telegram` کاملاً وجود نداشته باشد، پیش‌فرض زمان اجرا fail-closed با `groupPolicy="allowlist"` است مگر اینکه `channels.defaults.groupPolicy` صراحتاً تنظیم شده باشد. - مثال: اجازه دادن به هر عضو در یک گروه مشخص: + مثال: مجاز کردن هر عضو در یک گروه مشخص: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - مثال: اجازه دادن فقط به کاربران مشخص داخل یک گروه مشخص: + مثال: مجاز کردن فقط کاربران مشخص در یک گروه مشخص: ```json5 { @@ -211,32 +211,32 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - اشتباه رایج: `groupAllowFrom` یک allowlist گروه Telegram نیست. + اشتباه رایج: `groupAllowFrom`، allowlist گروه Telegram نیست. - - شناسه‌های منفی chat گروه یا supergroup در Telegram مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید. - - وقتی می‌خواهید محدود کنید کدام افراد داخل یک گروه مجاز بتوانند ربات را فعال کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید. - - فقط وقتی از `groupAllowFrom: ["*"]` استفاده کنید که می‌خواهید هر عضو یک گروه مجاز بتواند با ربات صحبت کند. + - شناسه‌های منفی گفتگوی گروه یا ابرگروه Telegram مانند `-1001234567890` را زیر `channels.telegram.groups` قرار دهید. + - وقتی می‌خواهید محدود کنید چه کسانی داخل یک گروه مجاز بتوانند ربات را فعال کنند، شناسه‌های کاربر Telegram مانند `8734062810` را زیر `groupAllowFrom` قرار دهید. + - فقط زمانی از `groupAllowFrom: ["*"]` استفاده کنید که می‌خواهید هر عضو یک گروه مجاز بتواند با ربات صحبت کند. - - پاسخ‌های گروه به‌طور پیش‌فرض به mention نیاز دارند. + + پاسخ‌های گروهی به‌صورت پیش‌فرض به منشن نیاز دارند. - mention می‌تواند از این‌ها بیاید: + منشن می‌تواند از این موارد بیاید: - - mention بومی `@botusername`، یا - - الگوهای mention در: + - منشن بومی `@botusername`، یا + - الگوهای منشن در: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - toggleهای فرمان در سطح session: + کلیدهای فرمان در سطح نشست: - `/activation always` - `/activation mention` - این‌ها فقط وضعیت session را به‌روزرسانی می‌کنند. برای پایداری از config استفاده کنید. + این‌ها فقط وضعیت نشست را به‌روزرسانی می‌کنند. برای پایداری از config استفاده کنید. مثال config پایدار: @@ -252,44 +252,45 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - گرفتن شناسه chat گروه: + دریافت شناسه گفتگوی گروه: - - یک پیام گروه را به `@userinfobot` / `@getidsbot` forward کنید + - یک پیام گروهی را به `@userinfobot` / `@getidsbot` فوروارد کنید - یا `chat.id` را از `openclaw logs --follow` بخوانید - یا Bot API `getUpdates` را بررسی کنید -## رفتار runtime +## رفتار زمان اجرا -- Telegram تحت مالکیت فرایند gateway است. +- Telegram در مالکیت فرایند gateway است. - مسیریابی قطعی است: ورودی Telegram به Telegram پاسخ داده می‌شود (مدل کانال‌ها را انتخاب نمی‌کند). -- پیام‌های ورودی به envelope کانال مشترک با metadata پاسخ و placeholderهای رسانه نرمال‌سازی می‌شوند. -- sessionهای گروه بر اساس شناسه گروه ایزوله می‌شوند. topicهای forum، `:topic:` را اضافه می‌کنند تا topicها ایزوله بمانند. -- پیام‌های DM می‌توانند `message_thread_id` داشته باشند؛ OpenClaw شناسه thread را برای پاسخ‌ها حفظ می‌کند اما به‌طور پیش‌فرض DMها را روی session تخت نگه می‌دارد. وقتی عمداً ایزوله‌سازی session topic در DM را می‌خواهید، `channels.telegram.dm.threadReplies: "inbound"`، `channels.telegram.direct..threadReplies: "inbound"`، `requireTopic: true`، یا یک config topic منطبق را پیکربندی کنید. -- Long polling از runner در grammY با توالی‌دهی per-chat/per-thread استفاده می‌کند. هم‌روندی کلی runner sink از `agents.defaults.maxConcurrent` استفاده می‌کند. -- Long polling داخل هر فرایند gateway محافظت می‌شود تا در هر زمان فقط یک poller فعال بتواند از یک توکن ربات استفاده کند. اگر همچنان conflictهای `getUpdates` 409 می‌بینید، احتمالاً یک gateway دیگر OpenClaw، یک script، یا یک poller خارجی از همان توکن استفاده می‌کند. -- راه‌اندازی‌های مجدد watchdog برای long-polling به‌طور پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness کامل‌شده `getUpdates` فعال می‌شوند. فقط اگر deployment شما همچنان هنگام کارهای طولانی‌مدت راه‌اندازی مجدد کاذب polling-stall می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ overrideهای per-account پشتیبانی می‌شوند. +- پیام‌های ورودی به پوشش مشترک کانال با فراداده پاسخ و جای‌نگهدارهای رسانه نرمال‌سازی می‌شوند. +- نشست‌های گروهی بر اساس شناسه گروه ایزوله می‌شوند. موضوع‌های فروم `:topic:` را اضافه می‌کنند تا موضوع‌ها ایزوله بمانند. +- پیام‌های DM می‌توانند `message_thread_id` داشته باشند؛ OpenClaw شناسه رشته را برای پاسخ‌ها حفظ می‌کند اما به‌صورت پیش‌فرض DMها را روی نشست تخت نگه می‌دارد. وقتی عمداً ایزوله‌سازی نشست موضوع DM را می‌خواهید، `channels.telegram.dm.threadReplies: "inbound"`، `channels.telegram.direct..threadReplies: "inbound"`، `requireTopic: true`، یا یک config موضوع مطابق را پیکربندی کنید. +- long polling از grammY runner با ترتیب‌دهی به‌ازای هر گفتگو/هر رشته استفاده می‌کند. همزمانی کلی runner sink از `agents.defaults.maxConcurrent` استفاده می‌کند. +- long polling داخل هر فرایند gateway محافظت می‌شود تا در هر زمان فقط یک poller فعال بتواند از توکن ربات استفاده کند. اگر همچنان تداخل‌های `getUpdates` 409 می‌بینید، احتمالاً یک gateway دیگر OpenClaw، اسکریپت، یا poller خارجی از همان توکن استفاده می‌کند. +- شروع‌های مجدد نگهبان long-polling به‌صورت پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness تکمیل‌شده `getUpdates` فعال می‌شوند. فقط اگر استقرار شما همچنان هنگام کارهای طولانی‌مدت شروع مجددهای کاذب polling-stall می‌بیند، `channels.telegram.pollingStallThresholdMs` را افزایش دهید. مقدار بر حسب میلی‌ثانیه است و از `30000` تا `600000` مجاز است؛ overrideهای به‌ازای حساب پشتیبانی می‌شوند. - Telegram Bot API از رسید خواندن پشتیبانی نمی‌کند (`sendReadReceipts` اعمال نمی‌شود). ## مرجع قابلیت‌ها - - OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت real time stream کند: + + OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت بلادرنگ stream کند: - - chatهای مستقیم: پیام پیش‌نمایش + `editMessageText` - - گروه‌ها/topicها: پیام پیش‌نمایش + `editMessageText` + - گفتگوهای مستقیم: پیام پیش‌نمایش + `editMessageText` + - گروه‌ها/موضوع‌ها: پیام پیش‌نمایش + `editMessageText` نیازمندی: - `channels.telegram.streaming` برابر `off | partial | block | progress` است (پیش‌فرض: `partial`) - - `progress` یک پیش‌نویس وضعیت قابل‌ویرایش نگه می‌دارد و تا تحویل نهایی، آن را با پیشرفت ابزار به‌روزرسانی می‌کند - - `streaming.preview.toolProgress` کنترل می‌کند آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: `true` وقتی preview streaming فعال است) - - مقادیر legacy `channels.telegram.streamMode` و boolean `streaming` شناسایی می‌شوند؛ برای مهاجرت آن‌ها به `channels.telegram.streaming.mode` دستور `openclaw doctor --fix` را اجرا کنید + - `progress` یک پیش‌نویس وضعیت قابل‌ویرایش را نگه می‌دارد و تا تحویل نهایی آن را با پیشرفت ابزار به‌روزرسانی می‌کند + - `streaming.preview.toolProgress` کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام پیش‌نمایش ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: وقتی stream کردن پیش‌نمایش فعال است `true`) + - `streaming.preview.commandText` جزئیات command/exec داخل آن خطوط tool-progress را کنترل می‌کند: `raw` (پیش‌فرض، رفتار منتشرشده را حفظ می‌کند) یا `status` (فقط برچسب ابزار) + - مقدارهای قدیمی `channels.telegram.streamMode` و بولی `streaming` شناسایی می‌شوند؛ برای مهاجرت آن‌ها به `channels.telegram.streaming.mode`، `openclaw doctor --fix` را اجرا کنید - به‌روزرسانی‌های پیش‌نمایش tool-progress همان خطوط کوتاه وضعیت هستند که هنگام اجرای ابزارها نشان داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشده OpenClaw از `v2026.4.22` و نسخه‌های بعدی منطبق باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خطوط tool-progress، تنظیم کنید: + به‌روزرسانی‌های پیش‌نمایش tool-progress خطوط کوتاه وضعیتی هستند که هنگام اجرای ابزارها نشان داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل‌ها، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌صورت پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشده OpenClaw از `v2026.4.22` و بعد از آن هم‌خوان باشد. برای نگه داشتن پیش‌نمایش ویرایش‌شده برای متن پاسخ اما پنهان کردن خطوط tool-progress، تنظیم کنید: ```json { @@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - از `streaming.mode: "off"` فقط زمانی استفاده کنید که تحویل فقط-نهایی می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفت‌وگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌عنوان پیام‌های وضعیت مستقل، سرکوب می‌شود. اعلان‌های تأیید، محموله‌های رسانه‌ای و خطاها همچنان از مسیر تحویل نهایی عادی عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و خطوط وضعیت پیشرفت ابزار را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید. + برای اینکه tool-progress قابل مشاهده بماند اما متن command/exec پنهان شود، تنظیم کنید: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "partial", + "preview": { + "commandText": "status" + } + } + } + } + } + ``` + + برای حالت پیش‌نویس پیشرفت، همان سیاست متن فرمان را زیر `streaming.progress` قرار دهید: + + ```json + { + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" + } + } + } + } + } + ``` + + از `streaming.mode: "off"` فقط زمانی استفاده کنید که تحویل فقط نهایی می‌خواهید: ویرایش‌های پیش‌نمایش Telegram غیرفعال می‌شوند و گفت‌وگوی عمومی ابزار/پیشرفت به‌جای ارسال به‌صورت پیام‌های وضعیت مستقل، سرکوب می‌شود. اعلان‌های تأیید، بارهای رسانه‌ای، و خطاها همچنان از مسیر تحویل نهایی معمول عبور می‌کنند. وقتی فقط می‌خواهید ویرایش‌های پیش‌نمایش پاسخ را نگه دارید و خط‌های وضعیت پیشرفت ابزار را پنهان کنید، از `streaming.preview.toolProgress: false` استفاده کنید. - پاسخ‌های نقل‌قول انتخاب‌شده Telegram استثنا هستند. وقتی `replyToMode` برابر `"first"`، `"all"` یا `"batched"` باشد و پیام ورودی شامل متن نقل‌قول انتخاب‌شده باشد، OpenClaw پاسخ نهایی را به‌جای ویرایش پیش‌نمایش پاسخ، از مسیر بومی پاسخِ نقل‌قولی Telegram ارسال می‌کند؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند خطوط کوتاه وضعیت را برای آن نوبت نشان دهد. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان جریان پیش‌نمایش را نگه می‌دارند. وقتی نمایش پیشرفت ابزار از پاسخ‌های نقل‌قولی بومی مهم‌تر است، `replyToMode: "off"` را تنظیم کنید، یا برای پذیرفتن این بده‌بستان `streaming.preview.toolProgress: false` را تنظیم کنید. + پاسخ‌های نقل‌قولی انتخاب‌شده در Telegram استثنا هستند. وقتی `replyToMode` برابر `"first"`، `"all"`، یا `"batched"` باشد و پیام ورودی شامل متن نقل‌قول انتخاب‌شده باشد، OpenClaw پاسخ نهایی را به‌جای ویرایش پیش‌نمایش پاسخ، از مسیر بومی پاسخ نقل‌قولی Telegram ارسال می‌کند؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند خط‌های کوتاه وضعیت را برای آن نوبت نشان دهد. پاسخ‌ها به پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان پخش پیش‌نمایش را نگه می‌دارند. وقتی دیده‌شدن پیشرفت ابزار از پاسخ‌های نقل‌قولی بومی مهم‌تر است، `replyToMode: "off"` را تنظیم کنید، یا برای پذیرش این بده‌بستان `streaming.preview.toolProgress: false` را تنظیم کنید. برای پاسخ‌های فقط متنی: - - پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و یک ویرایش نهایی را در همان‌جا انجام می‌دهد، مگر اینکه پس از ظاهر شدن پیش‌نمایش، یک پیام غیرپیش‌نمایش قابل‌مشاهده ارسال شده باشد - - پیش‌نمایش‌هایی که خروجی غیرپیش‌نمایش قابل‌مشاهده پس از آن‌ها می‌آید: OpenClaw پاسخ کامل‌شده را به‌عنوان یک پیام نهایی تازه ارسال می‌کند و پیش‌نمایش قدیمی‌تر را پاک می‌کند، بنابراین پاسخ نهایی پس از خروجی میانی ظاهر می‌شود - - پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ کامل‌شده را به‌عنوان یک پیام نهایی تازه ارسال می‌کند و سپس پیش‌نمایش را پاک می‌کند، بنابراین زمان‌نمای قابل‌مشاهده Telegram زمان تکمیل را به‌جای زمان ایجاد پیش‌نمایش نشان می‌دهد + - پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و یک ویرایش نهایی را درجا انجام می‌دهد، مگر اینکه پس از ظاهر شدن پیش‌نمایش یک پیام غیرپیش‌نمایش قابل مشاهده ارسال شده باشد + - پیش‌نمایش‌هایی که خروجی غیرپیش‌نمایش قابل مشاهده پس از آنها می‌آید: OpenClaw پاسخ کامل‌شده را به‌صورت یک پیام نهایی تازه ارسال می‌کند و پیش‌نمایش قدیمی‌تر را پاک می‌کند، بنابراین پاسخ نهایی پس از خروجی میانی ظاهر می‌شود + - پیش‌نمایش‌های قدیمی‌تر از حدود یک دقیقه: OpenClaw پاسخ کامل‌شده را به‌صورت یک پیام نهایی تازه ارسال می‌کند و سپس پیش‌نمایش را پاک می‌کند، بنابراین مهر زمانی قابل مشاهده Telegram به‌جای زمان ایجاد پیش‌نمایش، زمان تکمیل را نشان می‌دهد - برای پاسخ‌های پیچیده (برای مثال محموله‌های رسانه‌ای)، OpenClaw به تحویل نهایی عادی بازمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند. + برای پاسخ‌های پیچیده (برای مثال بارهای رسانه‌ای)، OpenClaw به تحویل نهایی معمول برمی‌گردد و سپس پیام پیش‌نمایش را پاک می‌کند. - جریان پیش‌نمایش از جریان بلوکی جدا است. وقتی جریان بلوکی به‌طور صریح برای Telegram فعال شده باشد، OpenClaw برای جلوگیری از جریان‌دهی دوگانه، جریان پیش‌نمایش را رد می‌کند. + پخش پیش‌نمایش از پخش بلوک جداست. وقتی پخش بلوک به‌صراحت برای Telegram فعال باشد، OpenClaw برای جلوگیری از پخش دوگانه، پخش پیش‌نمایش را نادیده می‌گیرد. - جریان استدلال فقط برای Telegram: + جریان استدلال فقط مخصوص Telegram: - - `/reasoning stream` هنگام تولید، استدلال را به پیش‌نمایش زنده ارسال می‌کند + - `/reasoning stream` هنگام تولید، استدلال را به پیش‌نمایش زنده می‌فرستد + - پیش‌نمایش استدلال پس از تحویل نهایی حذف می‌شود؛ وقتی استدلال باید قابل مشاهده باقی بماند از `/reasoning on` استفاده کنید - پاسخ نهایی بدون متن استدلال ارسال می‌شود @@ -332,11 +369,11 @@ curl "https://api.telegram.org/bot/getUpdates" متن خروجی از Telegram `parse_mode: "HTML"` استفاده می‌کند. - - متن شبیه Markdown به HTML امن برای Telegram رندر می‌شود. - - HTML خام مدل escape می‌شود تا شکست‌های parse در Telegram کاهش یابد. - - اگر Telegram HTML تجزیه‌شده را رد کند، OpenClaw دوباره به‌صورت متن ساده تلاش می‌کند. + - متن شبیه Markdown به HTML ایمن برای Telegram رندر می‌شود. + - HTML خام مدل برای کاهش شکست‌های پردازش Telegram escape می‌شود. + - اگر Telegram HTML پردازش‌شده را رد کند، OpenClaw به‌صورت متن ساده دوباره تلاش می‌کند. - پیش‌نمایش‌های لینک به‌طور پیش‌فرض فعال هستند و می‌توان آن‌ها را با `channels.telegram.linkPreview: false` غیرفعال کرد. + پیش‌نمایش‌های لینک به‌طور پیش‌فرض فعال هستند و می‌توان آنها را با `channels.telegram.linkPreview: false` غیرفعال کرد. @@ -367,25 +404,25 @@ curl "https://api.telegram.org/bot/getUpdates" - نام‌ها نرمال‌سازی می‌شوند (`/` ابتدایی حذف می‌شود، حروف کوچک می‌شوند) - الگوی معتبر: `a-z`، `0-9`، `_`، طول `1..32` - فرمان‌های سفارشی نمی‌توانند فرمان‌های بومی را بازنویسی کنند - - تداخل‌ها/تکراری‌ها رد می‌شوند و لاگ می‌شوند + - تعارض‌ها/تکراری‌ها نادیده گرفته و ثبت می‌شوند - نکته‌ها: + نکات: - - فرمان‌های سفارشی فقط ورودی‌های منو هستند؛ آن‌ها رفتار را به‌صورت خودکار پیاده‌سازی نمی‌کنند - - فرمان‌های 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 توکن بات پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile` یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، بنابراین این مورد به‌عنوان شکست پاک‌سازی Webhook گزارش نمی‌شود. + - `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 توکن بات پیکربندی‌شده را رد کرده است. `botToken`، `tokenFile`، یا `TELEGRAM_BOT_TOKEN` را با توکن فعلی BotFather به‌روزرسانی کنید؛ OpenClaw پیش از polling متوقف می‌شود، بنابراین این مورد به‌عنوان شکست پاک‌سازی webhook گزارش نمی‌شود. - `setMyCommands failed` همراه با خطاهای network/fetch معمولاً یعنی DNS/HTTPS خروجی به `api.telegram.org` مسدود شده است. - ### فرمان‌های جفت‌سازی دستگاه (Plugin `device-pair`) + ### فرمان‌های جفت‌سازی دستگاه (plugin `device-pair`) - وقتی Plugin `device-pair` نصب شده باشد: + وقتی plugin `device-pair` نصب شده باشد: 1. `/pair` کد راه‌اندازی تولید می‌کند 2. کد را در برنامه iOS جای‌گذاری کنید @@ -393,11 +430,11 @@ curl "https://api.telegram.org/bot/getUpdates" 4. درخواست را تأیید کنید: - `/pair approve ` برای تأیید صریح - `/pair approve` وقتی فقط یک درخواست در انتظار وجود دارد - - `/pair approve latest` برای تازه‌ترین مورد + - `/pair approve latest` برای جدیدترین مورد - کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. handoff داخلی bootstrap توکن node اصلی را در `scopes: []` نگه می‌دارد؛ هر توکن operator واگذار‌شده به `operator.approvals`، `operator.read`، `operator.talk.secrets` و `operator.write` محدود می‌ماند. بررسی‌های دامنه bootstrap با پیشوند نقش هستند، بنابراین آن allowlist مربوط به operator فقط درخواست‌های operator را برآورده می‌کند؛ نقش‌های غیر-operator همچنان به دامنه‌هایی زیر پیشوند نقش خودشان نیاز دارند. + کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر را حمل می‌کند. واگذاری bootstrap داخلی توکن نود اصلی را در `scopes: []` نگه می‌دارد؛ هر توکن عملگر واگذارشده در محدوده‌های `operator.approvals`، `operator.read`، `operator.talk.secrets`، و `operator.write` محدود می‌ماند. بررسی‌های دامنه bootstrap با پیشوند نقش انجام می‌شوند، بنابراین آن allowlist عملگر فقط درخواست‌های عملگر را برآورده می‌کند؛ نقش‌های غیرعملگر همچنان به دامنه‌هایی زیر پیشوند نقش خودشان نیاز دارند. - اگر دستگاهی با جزئیات احراز هویت تغییر‌یافته دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید، `/pair pending` را دوباره اجرا کنید. + اگر دستگاهی با جزئیات احراز هویت تغییرکرده دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و درخواست جدید از `requestId` متفاوتی استفاده می‌کند. پیش از تأیید دوباره `/pair pending` را اجرا کنید. جزئیات بیشتر: [جفت‌سازی](/fa/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -446,7 +483,7 @@ curl "https://api.telegram.org/bot/getUpdates" `capabilities: ["inlineButtons"]` قدیمی به `inlineButtons: "all"` نگاشت می‌شود. - نمونه اقدام پیام: + نمونه کنش پیام: ```json5 { @@ -464,23 +501,23 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - کلیک‌های callback به‌صورت متن به agent پاس داده می‌شوند: + کلیک‌های callback به‌صورت متن به عامل منتقل می‌شوند: `callback_data: ` - - اقدام‌های ابزار Telegram شامل این موارد است: + + کنش‌های ابزار Telegram شامل این موارد هستند: - - `sendMessage` (`to`, `content`, اختیاری `mediaUrl`, `replyToMessageId`, `messageThreadId`) - - `react` (`chatId`, `messageId`, `emoji`) - - `deleteMessage` (`chatId`, `messageId`) - - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, اختیاری `iconColor`, `iconCustomEmojiId`) + - `sendMessage` (`to`، `content`، اختیاری `mediaUrl`، `replyToMessageId`، `messageThreadId`) + - `react` (`chatId`، `messageId`، `emoji`) + - `deleteMessage` (`chatId`، `messageId`) + - `editMessage` (`chatId`، `messageId`، `content`) + - `createForumTopic` (`chatId`، `name`، اختیاری `iconColor`، `iconCustomEmojiId`) - اقدام‌های پیام channel نام‌های مستعار خوش‌دست را ارائه می‌کنند (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + کنش‌های پیام کانال aliasهای ارگونومیک را ارائه می‌کنند (`send`، `react`، `delete`، `edit`، `sticker`، `sticker-search`، `topic-create`). - کنترل‌های gating: + کنترل‌های محدودسازی: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -488,16 +525,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (پیش‌فرض: غیرفعال) نکته: `edit` و `topic-create` در حال حاضر به‌طور پیش‌فرض فعال هستند و toggleهای جداگانه `channels.telegram.actions.*` ندارند. - ارسال‌های runtime از snapshot فعال پیکربندی/secretها (راه‌اندازی/بارگذاری مجدد) استفاده می‌کنند، بنابراین مسیرهای اقدام برای هر ارسال، SecretRef را به‌صورت ad-hoc دوباره resolve نمی‌کنند. + ارسال‌های زمان اجرا از snapshot پیکربندی/رازهای فعال (راه‌اندازی/بارگذاری مجدد) استفاده می‌کنند، بنابراین مسیرهای کنش برای هر ارسال بازحل ad-hoc مربوط به SecretRef انجام نمی‌دهند. - معنای حذف واکنش: [/tools/reactions](/fa/tools/reactions) + معناشناسی حذف واکنش: [/tools/reactions](/fa/tools/reactions) - - Telegram از تگ‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده پشتیبانی می‌کند: + + Telegram از برچسب‌های رشته‌بندی پاسخ صریح در خروجی تولیدشده پشتیبانی می‌کند: - - `[[reply_to_current]]` به پیام تحریک‌کننده پاسخ می‌دهد + - `[[reply_to_current]]` به پیام محرک پاسخ می‌دهد - `[[reply_to:]]` به یک شناسه پیام مشخص Telegram پاسخ می‌دهد `channels.telegram.replyToMode` مدیریت را کنترل می‌کند: @@ -506,29 +543,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - وقتی رشته‌بندی پاسخ فعال باشد و متن یا caption اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی Telegram را شامل می‌کند. Telegram متن نقل‌قول بومی را به 1024 واحد کد UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا نقل می‌شوند و اگر Telegram نقل‌قول را رد کند، به پاسخ ساده fallback می‌کنند. + وقتی رشته‌بندی پاسخ فعال باشد و متن یا کپشن اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی Telegram را شامل می‌کند. Telegram متن نقل‌قول بومی را به ۱۰۲۴ واحد کد UTF-16 محدود می‌کند، بنابراین پیام‌های طولانی‌تر از ابتدا نقل‌قول می‌شوند و اگر Telegram نقل‌قول را رد کند به یک پاسخ ساده برمی‌گردند. - نکته: `off` رشته‌بندی ضمنی پاسخ را غیرفعال می‌کند. تگ‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. + نکته: `off` رشته‌بندی پاسخ ضمنی را غیرفعال می‌کند. برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. - - ابرگروه‌های Forum: + + ابرگروه‌های انجمن: - - کلیدهای session موضوع `:topic:` را اضافه می‌کنند - - پاسخ‌ها و typing موضوع thread را هدف می‌گیرند + - کلیدهای جلسه موضوع `:topic:` را اضافه می‌کنند + - پاسخ‌ها و typing موضوع رشته را هدف می‌گیرند - مسیر پیکربندی موضوع: `channels.telegram.groups..topics.` حالت ویژه موضوع عمومی (`threadId=1`): - - ارسال پیام‌ها `message_thread_id` را حذف می‌کند (Telegram `sendMessage(...thread_id=1)` را رد می‌کند) - - اقدام‌های typing همچنان `message_thread_id` را شامل می‌شوند + - ارسال‌های پیام `message_thread_id` را حذف می‌کنند (Telegram، `sendMessage(...thread_id=1)` را رد می‌کند) + - کنش‌های typing همچنان `message_thread_id` را شامل می‌شوند - ارث‌بری موضوع: ورودی‌های موضوع تنظیمات گروه را ارث می‌برند مگر اینکه بازنویسی شده باشند (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + وراثت موضوع: ورودی‌های موضوع تنظیمات گروه را به ارث می‌برند مگر اینکه بازنویسی شوند (`requireMention`، `allowFrom`، `skills`، `systemPrompt`، `enabled`، `groupPolicy`). `agentId` فقط مخصوص موضوع است و از پیش‌فرض‌های گروه ارث نمی‌برد. - **مسیریابی agent برای هر موضوع**: هر موضوع می‌تواند با تنظیم `agentId` در پیکربندی موضوع، به agent متفاوتی مسیر داده شود. این کار به هر موضوع workspace، memory و session ایزوله خودش را می‌دهد. مثال: + **مسیریابی عامل برای هر موضوع**: هر موضوع می‌تواند با تنظیم `agentId` در پیکربندی موضوع، به عامل متفاوتی مسیریابی شود. این به هر موضوع workspace، حافظه، و جلسه جداگانه خودش را می‌دهد. مثال: ```json5 { @@ -548,26 +585,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - سپس هر موضوع کلید session خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3` + سپس هر موضوع کلید جلسه خودش را دارد: `agent:zu:telegram:group:-1001234567890:topic:3` - **اتصال پایدار موضوع ACP**: موضوعات Forum می‌توانند sessionهای harness مربوط به ACP را از طریق bindingهای تایپ‌شده ACP در سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و یک شناسه واجد موضوع مثل `-1001234567890:topic:42`). در حال حاضر به موضوعات Forum در گروه‌ها/ابرگروه‌ها محدود است. [Agentهای ACP](/fa/tools/acp-agents) را ببینید. + **اتصال پایدار موضوع ACP**: موضوعات انجمن می‌توانند جلسه‌های harness مربوط به ACP را از طریق اتصال‌های ACP تایپ‌شده سطح بالا pin کنند (`bindings[]` با `type: "acp"` و `match.channel: "telegram"`، `peer.kind: "group"`، و یک شناسه دارای topic qualifier مانند `-1001234567890:topic:42`). در حال حاضر به موضوعات انجمن در گروه‌ها/ابرگروه‌ها محدود است. [عامل‌های ACP](/fa/tools/acp-agents) را ببینید. - **spawn وابسته به thread برای ACP از chat**: `/acp spawn --thread here|auto` موضوع فعلی را به یک session جدید ACP متصل می‌کند؛ پیگیری‌ها مستقیماً به همان‌جا مسیر داده می‌شوند. OpenClaw تأیید spawn را درون موضوع pin می‌کند. نیاز دارد `channels.telegram.threadBindings.spawnSessions` فعال بماند (پیش‌فرض: `true`). + **spawn کردن ACP وابسته به رشته از chat**: `/acp spawn --thread here|auto` موضوع فعلی را به یک جلسه ACP جدید متصل می‌کند؛ پیگیری‌ها مستقیم به آنجا مسیریابی می‌شوند. OpenClaw تأیید spawn را داخل موضوع pin می‌کند. نیاز دارد `channels.telegram.threadBindings.spawnSessions` فعال بماند (پیش‌فرض: `true`). - زمینه template، `MessageThreadId` و `IsForum` را ارائه می‌کند. chatهای DM با `message_thread_id` به‌طور پیش‌فرض مسیریابی DM و metadata پاسخ را روی sessionهای تخت نگه می‌دارند؛ آن‌ها فقط زمانی از کلیدهای session آگاه از thread استفاده می‌کنند که با `threadReplies: "inbound"`، `threadReplies: "always"`، `requireTopic: true` یا یک پیکربندی موضوع مطابق پیکربندی شده باشند. برای پیش‌فرض حساب از `channels.telegram.dm.threadReplies` در سطح بالا، یا برای یک DM از `direct..threadReplies` استفاده کنید. + زمینهٔ الگو `MessageThreadId` و `IsForum` را در دسترس می‌گذارد. چت‌های DM با `message_thread_id` به‌طور پیش‌فرض مسیریابی DM و فرادادهٔ پاسخ را در نشست‌های تخت نگه می‌دارند؛ آن‌ها فقط وقتی از کلیدهای نشست آگاه از رشته استفاده می‌کنند که با `threadReplies: "inbound"`، `threadReplies: "always"`، `requireTopic: true`، یا یک پیکربندی موضوع منطبق تنظیم شده باشند. برای پیش‌فرض حساب از `channels.telegram.dm.threadReplies` در سطح بالا استفاده کنید، یا برای یک DM از `direct..threadReplies`. - + ### پیام‌های صوتی - Telegram یادداشت‌های صوتی را از فایل‌های صوتی متمایز می‌کند. + Telegram میان یادداشت‌های صوتی و فایل‌های صوتی تمایز می‌گذارد. - پیش‌فرض: رفتار فایل صوتی - - تگ `[[audio_as_voice]]` در پاسخ agent برای اجبار ارسال به‌صورت یادداشت صوتی - - رونوشت‌های یادداشت صوتی ورودی در زمینه agent به‌عنوان متن تولیدشده توسط ماشین و نامطمئن frame می‌شوند؛ تشخیص mention همچنان از رونوشت خام استفاده می‌کند، بنابراین پیام‌های صوتی وابسته به mention همچنان کار می‌کنند. + - برچسب `[[audio_as_voice]]` در پاسخ عامل برای اجبار ارسال یادداشت صوتی + - رونویسی‌های یادداشت صوتی ورودی در زمینهٔ عامل به‌عنوان متن تولیدشده توسط ماشین و نامطمئن قاب‌بندی می‌شوند؛ تشخیص اشاره همچنان از رونویسی خام استفاده می‌کند تا پیام‌های صوتی وابسته به اشاره همچنان کار کنند. - نمونه اقدام پیام: + نمونهٔ کنش پیام: ```json5 { @@ -581,7 +618,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### پیام‌های ویدیویی - Telegram فایل‌های ویدیویی را از پیام‌های ویدیویی متمایز می‌کند. + Telegram میان فایل‌های ویدیویی و یادداشت‌های ویدیویی تمایز می‌گذارد. نمونهٔ کنش پیام: @@ -595,13 +632,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - پیام‌های ویدیویی از کپشن پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود. + یادداشت‌های ویدیویی از کپشن پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود. ### استیکرها - مدیریت استیکرهای ورودی: + مدیریت استیکر ورودی: - - WEBP ایستا: دانلود و پردازش می‌شود (placeholder ``) + - WEBP ایستا: دانلود و پردازش می‌شود (جای‌نگهدار ``) - TGS متحرک: نادیده گرفته می‌شود - WEBM ویدیویی: نادیده گرفته می‌شود @@ -633,7 +670,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - کنش ارسال استیکر: + ارسال کنش استیکر: ```json5 { @@ -644,7 +681,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - جستجوی استیکرهای کش‌شده: + جست‌وجوی استیکرهای کش‌شده: ```json5 { @@ -657,10 +694,10 @@ curl "https://api.telegram.org/bot/getUpdates" - - واکنش‌های Telegram به‌صورت به‌روزرسانی‌های `message_reaction` دریافت می‌شوند (جدا از payloadهای پیام). + + واکنش‌های Telegram به‌صورت به‌روزرسانی‌های `message_reaction` می‌رسند (جدا از بارهای پیام). - وقتی فعال باشد، OpenClaw رویدادهای سیستمی مانند این را در صف قرار می‌دهد: + هنگام فعال بودن، OpenClaw رویدادهای سیستمی مانند این را در صف قرار می‌دهد: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -671,40 +708,40 @@ curl "https://api.telegram.org/bot/getUpdates" نکته‌ها: - - `own` یعنی فقط واکنش‌های کاربر به پیام‌های ارسال‌شده توسط bot (بهترین تلاش از طریق کش پیام‌های ارسال‌شده). - - رویدادهای واکنش همچنان کنترل‌های دسترسی 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 یک emoji تأیید ارسال می‌کند. + + `ackReaction` در حالی که OpenClaw در حال پردازش یک پیام ورودی است، یک ایموجی تأیید می‌فرستد. ترتیب حل: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - fallback emoji هویت agent (`agents.list[].identity.emoji`، وگرنه "👀") + - جایگزین ایموجی هویت عامل (`agents.list[].identity.emoji`، در غیر این صورت "👀") نکته‌ها: - - Telegram انتظار emoji یونیکد دارد (برای مثال "👀"). - - از `""` برای غیرفعال‌کردن واکنش برای یک channel یا account استفاده کنید. + - Telegram انتظار ایموجی یونیکد دارد (برای مثال "👀"). + - برای غیرفعال کردن واکنش برای یک کانال یا حساب، از `""` استفاده کنید. - - نوشتن پیکربندی channel به‌طور پیش‌فرض فعال است (`configWrites !== false`). + + نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (`configWrites !== false`). - نوشتن‌های فعال‌شده توسط Telegram شامل موارد زیر است: + نوشتن‌های برانگیخته از Telegram شامل این موارد است: - رویدادهای مهاجرت گروه (`migrate_to_chat_id`) برای به‌روزرسانی `channels.telegram.groups` - - `/config set` و `/config unset` (نیازمند فعال‌سازی فرمان) + - `/config set` و `/config unset` (به فعال‌سازی فرمان نیاز دارد) غیرفعال‌سازی: @@ -720,30 +757,30 @@ 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، guardهای درخواست، توکن محرمانهٔ Telegram و بدنهٔ JSON را اعتبارسنجی می‌کند. - سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از طریق همان مسیرهای bot برای هر چت/هر موضوع که long polling استفاده می‌کند پردازش می‌کند، بنابراین نوبت‌های کند agent باعث نگه‌داشتن 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.mediaGroupFlushMs` (پیش‌فرض 500) کنترل می‌کند که آلبوم‌ها/گروه‌های رسانه‌ای Telegram چه مدت buffer شوند پیش از آنکه OpenClaw آن‌ها را به‌عنوان یک پیام ورودی dispatch کند. اگر بخش‌های آلبوم دیر می‌رسند، آن را افزایش دهید؛ برای کاهش تأخیر پاسخ آلبوم آن را کاهش دهید. - - `channels.telegram.timeoutSeconds` timeout کلاینت API Telegram را override می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های bot مقدارهای پیکربندی‌شدهٔ کمتر از guard درخواست 60 ثانیه‌ای متن/typing خروجی را clamp می‌کنند تا grammY پیش از اجرای transport guard و fallback OpenClaw، تحویل پاسخ قابل مشاهده را abort نکند. long polling همچنان از guard درخواست 45 ثانیه‌ای `getUpdates` استفاده می‌کند تا pollهای idle برای همیشه رها نشوند. - - `channels.telegram.pollingStallThresholdMs` به‌طور پیش‌فرض `120000` است؛ فقط برای restartهای false-positive polling-stall، آن را بین `30000` و `600000` تنظیم کنید. + - `channels.telegram.mediaGroupFlushMs` (پیش‌فرض 500) کنترل می‌کند آلبوم‌ها/گروه‌های رسانه‌ای Telegram چه مدت پیش از اینکه OpenClaw آن‌ها را به‌عنوان یک پیام ورودی dispatch کند، buffer شوند. اگر بخش‌های آلبوم دیر می‌رسند، آن را افزایش دهید؛ برای کاهش تأخیر پاسخ آلبوم، آن را کاهش دهید. + - `channels.telegram.timeoutSeconds` timeout کلاینت Telegram API را بازنویسی می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های ربات مقادیر پیکربندی‌شدهٔ کمتر از نگهبان 60 ثانیه‌ای درخواست متن/تایپ خروجی را clamp می‌کنند تا grammY تحویل پاسخ قابل مشاهده را پیش از اجرای نگهبان transport و fallback در OpenClaw لغو نکند. Long polling همچنان از نگهبان درخواست 45 ثانیه‌ای `getUpdates` استفاده می‌کند تا pollهای بیکار به‌طور نامحدود رها نشوند. + - `channels.telegram.pollingStallThresholdMs` به‌طور پیش‌فرض `120000` است؛ فقط برای راه‌اندازی‌های مجدد polling-stall مثبت کاذب، آن را بین `30000` و `600000` تنظیم کنید. - تاریخچهٔ زمینهٔ گروه از `channels.telegram.historyLimit` یا `messages.groupChat.historyLimit` استفاده می‌کند (پیش‌فرض 50)؛ `0` غیرفعال می‌کند. - - زمینهٔ تکمیلی reply/quote/forward در حال حاضر همان‌طور که دریافت شده منتقل می‌شود. - - allowlistهای Telegram عمدتاً تعیین می‌کنند چه کسی می‌تواند agent را فعال کند، نه اینکه یک مرز کامل حذف زمینهٔ تکمیلی باشند. + - زمینهٔ تکمیلی پاسخ/نقل‌قول/forward در حال حاضر همان‌طور که دریافت شده منتقل می‌شود. + - allowlistهای Telegram عمدتاً کنترل می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل ویرایش زمینهٔ تکمیلی. - کنترل‌های تاریخچهٔ DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - پیکربندی `channels.telegram.retry` برای خطاهای قابل بازیابی API خروجی، روی helperهای ارسال Telegram (CLI/tools/actions) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش‌اتصال Telegram از تلاش مجدد safe-send محدود استفاده می‌کند، اما envelopeهای شبکهٔ مبهم پس از ارسال را که می‌توانند پیام‌های قابل مشاهده را تکراری کنند، دوباره امتحان نمی‌کند. + - پیکربندی `channels.telegram.retry` برای خطاهای API خروجی قابل بازیابی، روی کمک‌تابع‌های ارسال Telegram (CLI/ابزارها/کنش‌ها) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای خرابی‌های پیش‌اتصال Telegram از یک retry محدود safe-send استفاده می‌کند، اما envelopeهای شبکه‌ای مبهم پس از ارسال را که ممکن است پیام‌های قابل مشاهده را تکراری کنند، retry نمی‌کند. هدف ارسال CLI می‌تواند شناسهٔ عددی چت یا نام کاربری باشد: @@ -752,7 +789,7 @@ 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 \ @@ -762,41 +799,41 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - flagهای poll مخصوص Telegram: + پرچم‌های poll فقط مخصوص Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` برای موضوع‌های forum (یا از هدف `:topic:` استفاده کنید) + - `--thread-id` برای موضوعات انجمن (یا از یک هدف `:topic:` استفاده کنید) - ارسال Telegram همچنین پشتیبانی می‌کند از: + ارسال Telegram همچنین از این موارد پشتیبانی می‌کند: - - `--presentation` همراه با blockهای `buttons` برای inline keyboardها وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد - - `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل pinned وقتی bot بتواند در آن چت pin کند - - `--force-document` برای ارسال تصویرها و GIFهای خروجی به‌صورت document به‌جای آپلودهای photo فشرده یا animated-media + - `--presentation` با بلوک‌های `buttons` برای صفحه‌کلیدهای inline وقتی `channels.telegram.capabilities.inlineButtons` اجازه دهد + - `--pin` یا `--delivery '{"pin":true}'` برای درخواست تحویل pin‌شده وقتی ربات بتواند در آن چت pin کند + - `--force-document` برای ارسال تصاویر خروجی و GIFها به‌صورت سند به‌جای آپلود عکس فشرده یا رسانهٔ متحرک - gating کنش: + کنترل کنش: - `channels.telegram.actions.sendMessage=false` پیام‌های خروجی Telegram، از جمله pollها را غیرفعال می‌کند - - `channels.telegram.actions.poll=false` ایجاد poll در Telegram را غیرفعال می‌کند و ارسال‌های عادی را فعال نگه می‌دارد + - `channels.telegram.actions.poll=false` ساخت poll در Telegram را غیرفعال می‌کند و ارسال‌های عادی را فعال نگه می‌دارد - - Telegram از تأییدهای exec در DMهای approver پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در چت یا موضوع مبدأ ارسال کند. Approverها باید شناسه‌های عددی کاربر Telegram باشند. + + Telegram از تأییدهای exec در DMهای تأییدکننده پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در چت یا موضوع مبدأ ارسال کند. تأییدکنندگان باید شناسه‌های عددی کاربر Telegram باشند. مسیر پیکربندی: - - `channels.telegram.execApprovals.enabled` (وقتی دست‌کم یک approver قابل resolve باشد، خودکار فعال می‌شود) + - `channels.telegram.execApprovals.enabled` (وقتی حداقل یک تأییدکننده قابل حل باشد، خودکار فعال می‌شود) - `channels.telegram.execApprovals.approvers` (به شناسه‌های عددی owner از `commands.ownerAllowFrom` fallback می‌کند) - `channels.telegram.execApprovals.target`: `dm` (پیش‌فرض) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`، `groupAllowFrom` و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با bot صحبت کند و bot پاسخ‌های عادی را کجا ارسال کند. این‌ها کسی را به approver exec تبدیل نمی‌کنند. نخستین جفت‌سازی DM تأییدشده، وقتی هنوز owner فرمانی وجود ندارد، `commands.ownerAllowFrom` را bootstrap می‌کند، بنابراین راه‌اندازی تک-owner همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند. + `channels.telegram.allowFrom`، `groupAllowFrom`، و `defaultTo` کنترل می‌کنند چه کسی می‌تواند با ربات صحبت کند و ربات پاسخ‌های عادی را کجا ارسال می‌کند. آن‌ها کسی را به تأییدکنندهٔ exec تبدیل نمی‌کنند. نخستین pair کردن DM تأییدشده، وقتی هنوز owner فرمانی وجود ندارد، `commands.ownerAllowFrom` را bootstrap می‌کند، بنابراین راه‌اندازی تک‌مالک همچنان بدون تکرار شناسه‌ها زیر `execApprovals.approvers` کار می‌کند. - تحویل channel متن فرمان را در چت نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوع‌های مورد اعتماد فعال کنید. وقتی prompt در یک موضوع forum قرار می‌گیرد، OpenClaw موضوع را برای prompt تأیید و پیام follow-up حفظ می‌کند. تأییدهای exec به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند. + تحویل کانال متن فرمان را در چت نشان می‌دهد؛ `channel` یا `both` را فقط در گروه‌ها/موضوعات مورد اعتماد فعال کنید. وقتی prompt در یک موضوع انجمن قرار می‌گیرد، OpenClaw موضوع را برای prompt تأیید و پیگیری حفظ می‌کند. تأییدهای 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) را ببینید. @@ -805,14 +842,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## کنترل‌های پاسخ خطا -وقتی agent با خطای تحویل یا provider مواجه می‌شود، Telegram می‌تواند یا با متن خطا پاسخ دهد یا آن را suppress کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند: +وقتی عامل با خطای تحویل یا provider روبه‌رو می‌شود، Telegram می‌تواند یا با متن خطا پاسخ دهد یا آن را سرکوب کند. دو کلید پیکربندی این رفتار را کنترل می‌کنند: -| کلید | مقدارها | پیش‌فرض | توضیح | -| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به چت ارسال می‌کند. `silent` پاسخ‌های خطا را کاملاً suppress می‌کند. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان چت. از spam خطا هنگام قطعی جلوگیری می‌کند. | +| کلید | مقادیر | پیش‌فرض | توضیح | +| ----------------------------------- | ---------------- | ------- | --------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` یک پیام خطای دوستانه به چت می‌فرستد. `silent` پاسخ‌های خطا را کاملاً سرکوب می‌کند. | +| `channels.telegram.errorCooldownMs` | عدد (ms) | `60000` | حداقل زمان بین پاسخ‌های خطا به همان چت. از هرزپیام خطا هنگام قطعی‌ها جلوگیری می‌کند. | -Overrideهای per-account، per-group و per-topic پشتیبانی می‌شوند (همان inheritance کلیدهای دیگر پیکربندی Telegram). +بازنویسی‌های به‌ازای هر حساب، هر گروه، و هر موضوع پشتیبانی می‌شوند (همان وراثت سایر کلیدهای پیکربندی Telegram). ```json5 { @@ -833,56 +870,56 @@ Overrideهای per-account، per-group و per-topic پشتیبانی می‌شو ## عیب‌یابی - + - - اگر `requireMention=false`، حالت privacy در Telegram باید visibility کامل را مجاز کند. + - اگر `requireMention=false`، حالت حریم خصوصی Telegram باید دید کامل را مجاز کند. - BotFather: `/setprivacy` -> Disable - - سپس bot را از گروه حذف و دوباره اضافه کنید - - وقتی پیکربندی انتظار پیام‌های گروهی بدون mention دارد، `openclaw channels status` هشدار می‌دهد. - - `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard `"*"` را نمی‌توان membership-probe کرد. - - تست سریع نشست: `/activation always`. + - سپس ربات را از گروه حذف کنید و دوباره اضافه کنید + - وقتی پیکربندی انتظار پیام‌های گروهی بدون اشاره را داشته باشد، `openclaw channels status` هشدار می‌دهد. + - `openclaw channels status --probe` می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard `"*"` را نمی‌توان از نظر عضویت probe کرد. + - آزمون سریع نشست: `/activation always`. - + - - وقتی `channels.telegram.groups` وجود دارد، گروه باید فهرست شده باشد (یا شامل `"*"`) - - عضویت bot در گروه را بررسی کنید - - لاگ‌ها را مرور کنید: `openclaw logs --follow` برای دلایل skip + - وقتی `channels.telegram.groups` وجود دارد، گروه باید فهرست شده باشد (یا شامل `"*"` باشد) + - عضویت bot در گروه را تأیید کنید + - گزارش‌ها را بررسی کنید: `openclaw logs --follow` برای دلایل رد شدن - + - - هویت فرستندهٔ خود را مجاز کنید (pairing و/یا `allowFrom` عددی) - - مجوز فرمان حتی وقتی policy گروه `open` باشد همچنان اعمال می‌شود - - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` یعنی منوی native ورودی‌های زیادی دارد؛ فرمان‌های Plugin/skill/custom را کاهش دهید یا منوهای native را غیرفعال کنید - - فراخوانی‌های startup مربوط به `deleteMyCommands` / `setMyCommands` و فراخوانی‌های typing مربوط به `sendChatAction` محدود هستند و در timeout درخواست، یک‌بار از طریق fallback transport Telegram دوباره امتحان می‌شوند. خطاهای پایدار network/fetch معمولاً نشان‌دهندهٔ مشکلات دسترسی DNS/HTTPS به `api.telegram.org` هستند + - هویت فرستنده خود را مجاز کنید (pairing و/یا `allowFrom` عددی) + - مجوزدهی دستورها حتی وقتی سیاست گروه `open` است همچنان اعمال می‌شود + - `setMyCommands failed` با `BOT_COMMANDS_TOO_MUCH` یعنی منوی بومی ورودی‌های بیش‌ازحد زیادی دارد؛ تعداد دستورهای Plugin/Skills/سفارشی را کاهش دهید یا منوهای بومی را غیرفعال کنید + - فراخوانی‌های راه‌اندازی `deleteMyCommands` / `setMyCommands` و فراخوانی‌های تایپ `sendChatAction` محدود هستند و هنگام timeout درخواست، یک‌بار از طریق 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` هنگام راه‌اندازی نیز شکست احراز هویت است؛ در نظر گرفتن آن به‌عنوان «هیچ webhookای وجود ندارد» فقط همان شکست ناشی از توکن نامعتبر را به فراخوانی‌های بعدی API موکول می‌کند. + - `getMe returned 401` یک شکست احراز هویت Telegram برای token پیکربندی‌شده bot است. + - token مربوط به bot را در BotFather دوباره کپی یا بازتولید کنید، سپس `channels.telegram.botToken`، `channels.telegram.tokenFile`، `channels.telegram.accounts..botToken` یا `TELEGRAM_BOT_TOKEN` را برای حساب پیش‌فرض به‌روزرسانی کنید. + - `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز شکست احراز هویت است؛ تلقی کردن آن به‌عنوان «هیچ webhookی وجود ندارد» فقط همان شکست token نامعتبر را به فراخوانی‌های بعدی API موکول می‌کند. - + - - Node 22+ به‌همراه fetch/proxy سفارشی می‌تواند در صورت ناسازگاری نوع‌های AbortSignal، رفتار لغو فوری را فعال کند. - - برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 حل می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث شکست‌های متناوب API Telegram شود. - - اگر لاگ‌ها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این موارد را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند. - - هنگام راه‌اندازی polling، OpenClaw همان بررسی موفق `getMe` زمان راه‌اندازی را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از نخستین `getUpdates` به `getMe` دوم نیاز نداشته باشد. - - اگر `deleteWebhook` هنگام راه‌اندازی polling با خطای شبکه گذرا شکست بخورد، OpenClaw به‌جای انجام یک فراخوانی control-plane دیگر پیش از poll، وارد long polling می‌شود. webhook همچنان فعال به‌صورت تعارض `getUpdates` ظاهر می‌شود؛ سپس OpenClaw انتقال Telegram را بازسازی می‌کند و پاک‌سازی webhook را دوباره تلاش می‌کند. - - اگر سوکت‌های Telegram در یک تناوب کوتاه و ثابت بازیافت می‌شوند، مقدار پایین `channels.telegram.timeoutSeconds` را بررسی کنید؛ کلاینت‌های بات مقدارهای پیکربندی‌شده کمتر از محافظ‌های درخواست خروجی و `getUpdates` را محدود می‌کنند، اما نسخه‌های قدیمی‌تر ممکن بود وقتی این مقدار کمتر از آن محافظ‌ها تنظیم می‌شد، هر poll یا پاسخ را لغو کنند. - - اگر لاگ‌ها شامل `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 کاذب گزارش می‌کند. توقف‌های پایدار معمولاً به مشکلات proxy، DNS، IPv6، یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند. - - Telegram همچنین envهای proxy فرایند را برای انتقال Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌تواند `api.telegram.org` را دور بزند. - - اگر proxy مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای محیط سرویس پیکربندی شده باشد و هیچ env استاندارد proxy وجود نداشته باشد، Telegram نیز از همان URL برای انتقال Bot API استفاده می‌کند. - - روی میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های API Telegram را از طریق `channels.telegram.proxy` مسیریابی کنید: + - Node 22+ همراه با fetch/proxy سفارشی می‌تواند در صورت ناسازگاری نوع‌های AbortSignal باعث رفتار abort فوری شود. + - برخی میزبان‌ها ابتدا `api.telegram.org` را به IPv6 resolve می‌کنند؛ خروجی IPv6 خراب می‌تواند باعث شکست‌های متناوب API Telegram شود. + - اگر گزارش‌ها شامل `TypeError: fetch failed` یا `Network request for 'getUpdates' failed!` باشند، OpenClaw اکنون این‌ها را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند. + - هنگام راه‌اندازی polling، OpenClaw probe موفق `getMe` راه‌اندازی را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از اولین `getUpdates` به `getMe` دوم نیاز نداشته باشد. + - اگر `deleteWebhook` هنگام راه‌اندازی polling با خطای شبکه گذرا شکست بخورد، OpenClaw به‌جای انجام یک فراخوانی control-plane دیگر پیش از poll، وارد long polling می‌شود. Webhook همچنان فعال به‌صورت تعارض `getUpdates` نمایان می‌شود؛ سپس OpenClaw انتقال Telegram را دوباره می‌سازد و cleanup webhook را دوباره تلاش می‌کند. + - اگر socketهای Telegram با یک آهنگ ثابت کوتاه بازیافت می‌شوند، مقدار پایین `channels.telegram.timeoutSeconds` را بررسی کنید؛ clientهای bot مقادیر پیکربندی‌شده زیر guardهای درخواست خروجی و `getUpdates` را clamp می‌کنند، اما نسخه‌های قدیمی‌تر وقتی این مقدار زیر آن guardها تنظیم می‌شد می‌توانستند هر poll یا پاسخ را abort کنند. + - اگر گزارش‌ها شامل `Polling stall detected` باشند، OpenClaw به‌صورت پیش‌فرض پس از ۱۲۰ ثانیه بدون liveness تکمیل‌شده long-poll، polling را restart می‌کند و انتقال Telegram را دوباره می‌سازد. + - `openclaw channels status --probe` و `openclaw doctor` وقتی یک حساب polling در حال اجرا پس از مهلت شروع، `getUpdates` را کامل نکرده باشد، وقتی یک حساب webhook در حال اجرا پس از مهلت شروع، `setWebhook` را کامل نکرده باشد، یا وقتی آخرین فعالیت موفق انتقال polling کهنه باشد، هشدار می‌دهند. + - `channels.telegram.pollingStallThresholdMs` را فقط زمانی افزایش دهید که فراخوانی‌های بلندمدت `getUpdates` سالم هستند اما میزبان شما همچنان restartهای polling-stall مثبت کاذب گزارش می‌کند. stallهای پایدار معمولاً به مشکلات proxy، DNS، IPv6 یا خروجی TLS بین میزبان و `api.telegram.org` اشاره دارند. + - Telegram همچنین envهای proxy فرایند را برای انتقال Bot API رعایت می‌کند، از جمله `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و گونه‌های حروف کوچک آن‌ها. `NO_PROXY` / `no_proxy` همچنان می‌تواند `api.telegram.org` را bypass کند. + - اگر proxy مدیریت‌شده OpenClaw از طریق `OPENCLAW_PROXY_URL` برای یک محیط سرویس پیکربندی شده باشد و env استاندارد proxy وجود نداشته باشد، Telegram نیز از همان URL برای انتقال Bot API استفاده می‌کند. + - روی میزبان‌های VPS با خروجی/TLS مستقیم ناپایدار، فراخوانی‌های API Telegram را از طریق `channels.telegram.proxy` مسیریابی کنید: ```yaml channels: @@ -890,7 +927,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ به‌طور پیش‌فرض `autoSelectFamily=true` است (به‌جز WSL2). ترتیب نتیجه DNS برای Telegram ابتدا `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`، سپس `channels.telegram.network.dnsResultOrder`، سپس پیش‌فرض فرایند مانند `NODE_OPTIONS=--dns-result-order=ipv4first` را رعایت می‌کند؛ اگر هیچ‌کدام اعمال نشود، Node 22+ به `ipv4first` بازمی‌گردد. + - Node 22+ به‌صورت پیش‌فرض `autoSelectFamily=true` دارد (به‌جز WSL2). ترتیب نتیجه DNS برای Telegram ابتدا `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`، سپس `channels.telegram.network.dnsResultOrder`، سپس پیش‌فرض فرایند مانند `NODE_OPTIONS=--dns-result-order=ipv4first` را رعایت می‌کند؛ اگر هیچ‌کدام اعمال نشود، Node 22+ به `ipv4first` fallback می‌کند. - اگر میزبان شما WSL2 است یا صراحتاً با رفتار فقط IPv4 بهتر کار می‌کند، انتخاب خانواده را اجباری کنید: ```yaml @@ -900,11 +937,10 @@ channels: autoSelectFamily: false ``` - - پاسخ‌های محدوده benchmark در RFC 2544 (`198.18.0.0/15`) از قبل به‌طور پیش‌فرض - برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP یا - proxy شفاف مورد اعتماد، `api.telegram.org` را هنگام دانلود رسانه به نشانی - خصوصی/داخلی/با کاربرد ویژه دیگری بازنویسی می‌کند، می‌توانید برای دورزدن فقط مخصوص Telegram - opt-in کنید: + - پاسخ‌های بازه benchmark RFC 2544 (`198.18.0.0/15`) از قبل به‌صورت پیش‌فرض + برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP قابل‌اعتماد یا + proxy شفاف، هنگام دانلود رسانه، `api.telegram.org` را به نشانی خصوصی/داخلی/کاربرد ویژه دیگری بازنویسی کند، می‌توانید + در bypass مخصوص Telegram opt in کنید: ```yaml channels: @@ -913,17 +949,17 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - همین opt-in برای هر حساب نیز در - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` در دسترس است. - - اگر proxy شما میزبان‌های رسانه Telegram را به `198.18.x.x` حل می‌کند، ابتدا - پرچم خطرناک را خاموش نگه دارید. رسانه Telegram از قبل به‌طور پیش‌فرض محدوده - benchmark در RFC 2544 را مجاز می‌داند. + - همین opt-in برای هر حساب در + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` نیز در دسترس است. + - اگر proxy شما میزبان‌های رسانه Telegram را به `198.18.x.x` resolve می‌کند، ابتدا + flag خطرناک را خاموش نگه دارید. رسانه Telegram از قبل بازه benchmark + RFC 2544 را به‌صورت پیش‌فرض مجاز می‌داند. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. از آن فقط برای محیط‌های proxy مورد اعتماد و تحت کنترل اپراتور مانند Clash، Mihomo، یا مسیریابی fake-IP در Surge استفاده کنید، آن هم زمانی که پاسخ‌های خصوصی یا با کاربرد ویژه خارج از محدوده benchmark در RFC 2544 تولید می‌کنند. برای دسترسی عادی Telegram روی اینترنت عمومی آن را خاموش نگه دارید. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. فقط در محیط‌های proxy قابل‌اعتماد و تحت کنترل operator مانند مسیریابی fake-IP در Clash، Mihomo یا Surge از آن استفاده کنید، آن هم زمانی که پاسخ‌های خصوصی یا کاربرد ویژه خارج از بازه benchmark RFC 2544 تولید می‌کنند. برای دسترسی عادی عمومی اینترنت به Telegram، آن را خاموش نگه دارید. - - بازنویسی‌های محیطی (موقت): + - overrideهای محیطی (موقت): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -943,48 +979,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"`) -- تأییدهای اجرا: `execApprovals`، `accounts.*.execApprovals` -- فرمان/منو: `commands.native`، `commands.nativeSkills`، `customCommands` -- threadها/پاسخ‌ها: `replyToMode`، `dm.threadReplies`، `direct.*.threadReplies` -- streaming: `streaming` (پیش‌نمایش)، `streaming.preview.toolProgress`، `blockStreaming` -- قالب‌بندی/تحویل: `textChunkLimit`، `chunkMode`، `linkPreview`، `responsePrefix` -- رسانه/شبکه: `mediaMaxMb`، `mediaGroupFlushMs`، `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.*`, `bindings[]` سطح بالا (`type: "acp"`) +- تأییدهای exec: `execApprovals`, `accounts.*.execApprovals` +- دستور/menu: `commands.native`, `commands.nativeSkills`, `customCommands` +- thread/reply: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` +- streaming: `streaming` (پیش‌نمایش), `streaming.preview.toolProgress`, `blockStreaming` +- قالب‌بندی/تحویل: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- رسانه/شبکه: `mediaMaxMb`, `mediaGroupFlushMs`, `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` +- reactionها: `reactionNotifications`, `reactionLevel` +- خطاها: `errorPolicy`, `errorCooldownMs` +- نوشتن/history: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا مسیریابی پیش‌فرض صریح شود. در غیر این صورت OpenClaw به نخستین شناسه حساب نرمال‌سازی‌شده بازمی‌گردد و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه. +اولویت چندحسابی: وقتی دو یا چند شناسه حساب پیکربندی شده‌اند، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را شامل کنید) تا مسیریابی پیش‌فرض صریح شود. در غیر این صورت OpenClaw به اولین شناسه حساب نرمال‌شده fallback می‌کند و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقدارهای `accounts.default.*` را نه. ## مرتبط - یک کاربر Telegram را با Gateway جفت کنید. + یک کاربر Telegram را به Gateway pair کنید. - - رفتار allowlist برای گروه و موضوع. + + رفتار allowlist گروه و موضوع. - + پیام‌های ورودی را به agentها مسیریابی کنید. - + مدل تهدید و سخت‌سازی. - + گروه‌ها و موضوع‌ها را به agentها نگاشت کنید. - - عیب‌یابی میان‌کانالی. + + عیب‌یابی‌های میان‌کانالی. diff --git a/docs/fa/ci.md b/docs/fa/ci.md index a09108e1d..de17aee18 100644 --- a/docs/fa/ci.md +++ b/docs/fa/ci.md @@ -1,94 +1,94 @@ --- read_when: - - لازم است بدانید چرا یک وظیفهٔ CI اجرا شده یا نشده است - - شما در حال اشکال‌زدایی یک بررسی ناموفق GitHub Actions هستید - - شما اجرای اعتبارسنجی انتشار یا اجرای مجدد آن را هماهنگ می‌کنید - - شما در حال تغییر فراخوانی ClawSweeper یا بازارسال فعالیت‌های GitHub هستید -summary: گراف کارهای CI، گیت‌های محدوده، چترهای انتشار، و معادل‌های دستورهای محلی -title: خط لوله CI + - باید بفهمید چرا یک وظیفهٔ CI اجرا شد یا نشد + - شما در حال عیب‌یابی یک بررسی ناموفق GitHub Actions هستید + - شما در حال هماهنگی یک اجرای اعتبارسنجی انتشار یا اجرای مجدد آن هستید + - شما در حال تغییر ارسال ClawSweeper یا بازارسال فعالیت GitHub هستید +summary: گراف کارهای CI، گیت‌های دامنه، چترهای انتشار و معادل‌های فرمان‌های محلی +title: خط لولهٔ CI x-i18n: - generated_at: "2026-05-03T21:27:40Z" + generated_at: "2026-05-04T07:03:13Z" model: gpt-5.5 provider: openai - source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678 + source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d source_path: ci.md workflow: 16 --- -OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job `preflight`، diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجرای دستی `workflow_dispatch` عمدا scoped هوشمند را دور می‌زند و کل graph را برای release candidateها و اعتبارسنجی گسترده پخش می‌کند. laneهای Android از طریق `include_android` همچنان opt-in می‌مانند. پوشش Plugin مخصوص release در workflow جداگانه [`پیش‌انتشار Plugin`](#plugin-prerelease) قرار دارد و فقط از [`اعتبارسنجی کامل release`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود. +OpenClaw CI روی هر push به `main` و هر pull request اجرا می‌شود. job `preflight`، diff را طبقه‌بندی می‌کند و وقتی فقط بخش‌های نامرتبط تغییر کرده باشند، laneهای پرهزینه را خاموش می‌کند. اجراهای دستی `workflow_dispatch` عمداً از محدوده‌بندی هوشمند عبور می‌کنند و برای release candidateها و اعتبارسنجی گسترده، کل گراف را منشعب می‌کنند. laneهای Android از طریق `include_android` همچنان اختیاری می‌مانند. پوشش Plugin مخصوص انتشار در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا می‌شود. ## نمای کلی pipeline | Job | هدف | زمان اجرا | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | تشخیص تغییرات فقط-docs، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای non-draft | -| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای non-draft | -| `security-dependency-audit` | audit lockfile production بدون dependency در برابر advisoryهای npm | همیشه روی pushها و PRهای non-draft | -| `security-fast` | aggregate لازم برای jobهای امنیتی سریع | همیشه روی pushها و PRهای non-draft | -| `check-dependencies` | pass فقط-dependency مربوط به Knip در production به‌همراه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node | -| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های built-artifact، و artifactهای قابل‌استفاده مجدد برای downstream | تغییرات مرتبط با Node | +| `preflight` | تشخیص تغییرات فقط مستندات، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای غیر draft | +| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای غیر draft | +| `security-dependency-audit` | audit بدون وابستگی lockfile تولید در برابر advisoryهای npm | همیشه روی pushها و PRهای غیر draft | +| `security-fast` | aggregate الزامی برای jobهای امنیتی سریع | همیشه روی pushها و PRهای غیر draft | +| `check-dependencies` | گذر فقط وابستگی Knip تولید به‌علاوه guard مربوط به allowlist فایل‌های استفاده‌نشده | تغییرات مرتبط با Node | +| `build-artifacts` | ساخت `dist/`، Control UI، بررسی‌های artifact ساخته‌شده، و artifactهای پایین‌دستی قابل استفاده مجدد | تغییرات مرتبط با Node | | `checks-fast-core` | laneهای صحت‌سنجی سریع Linux مانند بررسی‌های bundled/plugin-contract/protocol | تغییرات مرتبط با Node | -| `checks-fast-contracts-channels` | بررسی‌های sharded مربوط به contractهای channel با یک نتیجه aggregate پایدار | تغییرات مرتبط با Node | -| `checks-node-core-test` | shardهای آزمون Core Node، به‌جز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node | -| `check` | معادل gate محلی اصلی به‌صورت sharded: typeهای prod، lint، guardها، typeهای test، و smoke سخت‌گیرانه | تغییرات مرتبط با Node | -| `check-additional` | architecture، boundary/prompt drift به‌صورت sharded، guardهای extension، package boundary، و gateway watch | تغییرات مرتبط با Node | -| `build-smoke` | آزمون‌های smoke برای CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node | -| `checks` | verifier برای آزمون‌های channel مربوط به built-artifact | تغییرات مرتبط با Node | -| `checks-node-compat-node22` | lane ساخت و smoke برای سازگاری Node 22 | dispatch دستی CI برای releaseها | -| `check-docs` | قالب‌بندی docs، lint، و بررسی لینک‌های خراب | docs تغییر کرده باشد | -| `skills-python` | Ruff + pytest برای Skills مبتنی بر Python | تغییرات مرتبط با Python-skill | -| `checks-windows` | آزمون‌های process/path مخصوص Windows به‌همراه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows | -| `macos-node` | lane آزمون TypeScript روی macOS با استفاده از artifactهای ساخته‌شده مشترک | تغییرات مرتبط با macOS | -| `macos-swift` | lint، build، و آزمون‌های Swift برای app macOS | تغییرات مرتبط با macOS | -| `android` | آزمون‌های واحد Android برای هر دو flavor به‌همراه یک build از debug APK | تغییرات مرتبط با Android | -| `test-performance-agent` | بهینه‌سازی روزانه آزمون‌های کند Codex پس از فعالیت trusted | موفقیت CI اصلی یا dispatch دستی | -| `openclaw-performance` | گزارش‌های عملکرد runtime روزانه/درخواستی Kova با laneهای mock-provider، deep-profile، و GPT 5.4 live | dispatch زمان‌بندی‌شده و دستی | +| `checks-fast-contracts-channels` | بررسی‌های sharded قرارداد channel با نتیجه بررسی aggregate پایدار | تغییرات مرتبط با Node | +| `checks-node-core-test` | shardهای تست Core Node، به‌جز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node | +| `check` | معادل gate محلی اصلی sharded: typeهای تولید، lint، guardها، typeهای تست، و smoke سختگیرانه | تغییرات مرتبط با Node | +| `check-additional` | معماری، drift مرزی/prompt به‌صورت sharded، guardهای extension، مرز package، و gateway watch | تغییرات مرتبط با Node | +| `build-smoke` | تست‌های smoke مربوط به CLI ساخته‌شده و smoke حافظه startup | تغییرات مرتبط با Node | +| `checks` | verifier برای تست‌های channel مربوط به artifact ساخته‌شده | تغییرات مرتبط با Node | +| `checks-node-compat-node22` | lane ساخت و smoke سازگاری Node 22 | dispatch دستی CI برای انتشارها | +| `check-docs` | قالب‌بندی مستندات، lint، و بررسی لینک‌های خراب | مستندات تغییر کرده باشند | +| `skills-python` | Ruff + pytest برای skills مبتنی بر Python | تغییرات مرتبط با Python-skill | +| `checks-windows` | تست‌های process/path مخصوص Windows به‌علاوه regressionهای مشترک runtime import specifier | تغییرات مرتبط با Windows | +| `macos-node` | lane تست TypeScript در macOS با استفاده از artifactهای ساخته‌شده مشترک | تغییرات مرتبط با macOS | +| `macos-swift` | lint، build، و تست‌های Swift برای app macOS | تغییرات مرتبط با macOS | +| `android` | تست‌های unit Android برای هر دو flavor به‌علاوه یک build APK debug | تغییرات مرتبط با Android | +| `test-performance-agent` | بهینه‌سازی روزانه تست‌های کند Codex پس از فعالیت مورد اعتماد | موفقیت Main CI یا dispatch دستی | +| `openclaw-performance` | گزارش‌های عملکرد runtime روزانه/درخواستی Kova با laneهای mock-provider، deep-profile، و live GPT 5.4 | dispatch زمان‌بندی‌شده و دستی | ## ترتیب fail-fast -1. `preflight` تصمیم می‌گیرد اصلا کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` stepهایی داخل همین job هستند، نه jobهای مستقل. -2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگین‌تر artifact و platform matrix سریع fail می‌شوند. -3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان downstream به‌محض آماده‌شدن build مشترک بتوانند شروع کنند. -4. پس از آن، laneهای سنگین‌تر platform و runtime پخش می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`. +1. `preflight` تصمیم می‌گیرد اصلاً کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` مرحله‌هایی داخل این job هستند، نه jobهای مستقل. +2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگین‌تر artifact و matrix پلتفرم، سریع fail می‌شوند. +3. `build-artifacts` با laneهای سریع Linux هم‌پوشانی دارد تا مصرف‌کنندگان پایین‌دستی به‌محض آماده شدن build مشترک شروع شوند. +4. پس از آن، laneهای سنگین‌تر پلتفرم و runtime منشعب می‌شوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`. -GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref مربوط به `main` می‌نشیند، jobهای superseded را با وضعیت `cancelled` علامت‌گذاری کند. این را noise مربوط به CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref نیز در حال fail شدن باشد. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند، بنابراین همچنان failureهای عادی shard را گزارش می‌دهند اما پس از اینکه کل workflow از قبل superseded شده باشد در صف قرار نمی‌گیرند. concurrency key خودکار CI نسخه‌دار است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند اجرای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و اجراهای درحال‌انجام را cancel نمی‌کنند. +GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref مربوط به `main` قرار می‌گیرد، jobهای جایگزین‌شده را به‌صورت `cancelled` علامت‌گذاری کند. این را noise مربوط به CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref نیز fail شده باشد. بررسی‌های aggregate shard از `!cancelled() && always()` استفاده می‌کنند، بنابراین همچنان failureهای عادی shard را گزارش می‌کنند اما پس از اینکه کل workflow از قبل جایگزین شده باشد، در queue قرار نمی‌گیرند. کلید concurrency خودکار CI نسخه‌گذاری شده است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند اجراهای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده می‌کنند و اجراهای در حال انجام را cancel نمی‌کنند. ## Scope و routing -منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با آزمون‌های واحد در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی از تشخیص changed-scope عبور می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه بخش‌های scoped تغییر کرده‌اند. +منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تست‌های unit در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی، تشخیص changed-scope را رد می‌کند و باعث می‌شود manifest مربوط به preflight طوری عمل کند که انگار همه بخش‌های scoped تغییر کرده‌اند. -- **ویرایش‌های workflow مربوط به CI** graph مربوط به Node CI و workflow linting را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native مربوط به Windows، Android، یا macOS را force نمی‌کنند؛ آن laneهای platform همچنان به تغییرات source مربوط به platform محدود می‌مانند. -- **ویرایش‌های فقط-routing مربوط به CI، ویرایش‌های منتخب و ارزان fixture آزمون core، و ویرایش‌های محدود helper/test-routing مربوط به plugin contract** از مسیر manifest سریع و فقط-Node استفاده می‌کنند: `preflight`، امنیت، و یک task واحد `checks-fast-core`. وقتی تغییر فقط به surfaceهای routing یا helper محدود باشد که task سریع مستقیما exercise می‌کند، آن مسیر از build artifactها، سازگاری Node 22، channel contractها، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی عبور می‌کند. -- **بررسی‌های Windows Node** به wrapperهای process/path مخصوص Windows، helperهای runner مربوط به npm/pnpm/UI، config مدیر package، و surfaceهای workflow مربوط به CI که آن lane را اجرا می‌کنند محدود است؛ تغییرات نامرتبط در source، plugin، install-smoke، و فقط-test روی laneهای Linux Node می‌مانند. +- **ویرایش‌های workflow مربوط به CI** گراف Node CI به‌علاوه linting workflow را اعتبارسنجی می‌کنند، اما به‌تنهایی buildهای native Windows، Android، یا macOS را اجبار نمی‌کنند؛ آن laneهای پلتفرم همچنان به تغییرات source پلتفرم scoped می‌مانند. +- **ویرایش‌های فقط routing مربوط به CI، ویرایش‌های منتخب و کم‌هزینه fixture تست core، و ویرایش‌های محدود helper/test-routing قرارداد Plugin** از مسیر سریع manifest فقط Node استفاده می‌کنند: `preflight`، امنیت، و یک task واحد `checks-fast-core`. وقتی تغییر به سطح‌های routing یا helper محدود باشد که task سریع مستقیماً آن‌ها را اجرا می‌کند، آن مسیر artifactهای build، سازگاری Node 22، قراردادهای channel، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی را رد می‌کند. +- **بررسی‌های Windows Node** به wrapperهای process/path مخصوص Windows، helperهای runner مربوط به npm/pnpm/UI، config مدیر package، و سطح‌های workflow مربوط به CI که آن lane را اجرا می‌کنند scoped هستند؛ تغییرات نامرتبط source، Plugin، install-smoke، و فقط تست روی laneهای Linux Node باقی می‌مانند. -کندترین خانواده‌های آزمون Node split یا balanced شده‌اند تا هر job بدون رزرو بیش‌ازحد runner کوچک بماند: channel contractها به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای core unit fast/support جداگانه اجرا می‌شوند، core runtime infra بین shardهای state و process/config تقسیم شده است، auto-reply به‌صورت workerهای balanced اجرا می‌شود (با subtree مربوط به reply که به shardهای agent-runner، dispatch، و commands/state-routing تقسیم شده است)، و configهای agentic gateway/server به‌جای انتظار برای built artifactها بین laneهای chat/auth/model/http-plugin/runtime/startup تقسیم شده‌اند. آزمون‌های گسترده browser، QA، media، و pluginهای متفرقه به‌جای catch-all مشترک plugin از configهای اختصاصی Vitest خودشان استفاده می‌کنند. shardهای include-pattern، entryهای timing را با نام shard مربوط به CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کار compile/canary مربوط به package-boundary را کنار هم نگه می‌دارد و architecture مربوط به runtime topology را از پوشش gateway watch جدا می‌کند؛ فهرست guardهای boundary بین چهار shard matrix نواری تقسیم شده است، که هرکدام guardهای مستقل منتخب را همزمان اجرا می‌کنند و timing هر check را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift مربوط به prompt مسیر موفق runtime در Codex به همان PR که باعث آن شده pin شود. Gateway watch، آزمون‌های channel، و shard مربوط به core support-boundary داخل `build-artifacts` پس از اینکه `dist/` و `dist-runtime/` از قبل ساخته شدند، همزمان اجرا می‌شوند. +کندترین خانواده‌های تست Node تقسیم یا متعادل شده‌اند تا هر job بدون رزرو بیش‌ازحد runnerها کوچک بماند: قراردادهای channel به‌صورت سه shard وزن‌دار اجرا می‌شوند، laneهای core unit fast/support جداگانه اجرا می‌شوند، زیرساخت runtime core بین shardهای state و process/config تقسیم شده است، auto-reply به‌صورت workerهای متعادل اجرا می‌شود (با تقسیم subtree مربوط به reply به shardهای agent-runner، dispatch، و commands/state-routing)، و configهای agentic gateway/server به‌جای انتظار برای artifactهای ساخته‌شده، میان laneهای chat/auth/model/http-plugin/runtime/startup تقسیم شده‌اند. تست‌های گسترده browser، QA، media، و Pluginهای متفرقه به‌جای catch-all مشترک Plugin، از configهای اختصاصی Vitest خود استفاده می‌کنند. shardهای include-pattern، entryهای timing را با نام shard مربوط به CI ثبت می‌کنند، بنابراین `.artifacts/vitest-shard-timings.json` می‌تواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کارهای compile/canary مرز package را کنار هم نگه می‌دارد و معماری توپولوژی runtime را از پوشش gateway watch جدا می‌کند؛ فهرست guard مرزی روی چهار shard matrix stripe شده است، که هرکدام guardهای مستقل منتخب را هم‌زمان اجرا می‌کنند و timing هر بررسی را چاپ می‌کنند، از جمله `pnpm prompt:snapshots:check` تا drift prompt مسیر موفق runtime مربوط به Codex به PRی که باعث آن شده pin شود. Gateway watch، تست‌های channel، و shard مرز support مربوط به core پس از اینکه `dist/` و `dist-runtime/` ساخته شدند، هم‌زمان داخل `build-artifacts` اجرا می‌شوند. -Android CI هر دو `testPlayDebugUnitTest` و `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس Play debug APK را می‌سازد. flavor شخص ثالث source set یا manifest جداگانه‌ای ندارد؛ lane آزمون واحد آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log compile می‌کند، درحالی‌که از job تکراری package کردن debug APK روی هر push مرتبط با Android جلوگیری می‌کند. +Android CI هم `testPlayDebugUnitTest` و هم `testThirdPartyDebugUnitTest` را اجرا می‌کند و سپس APK debug مربوط به Play را می‌سازد. flavor شخص ثالث هیچ source set یا manifest جداگانه‌ای ندارد؛ lane تست unit آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log کامپایل می‌کند، در حالی که از یک job تکراری package کردن APK debug در هر push مرتبط با Android جلوگیری می‌کند. -shard `check-dependencies` دستور `pnpm deadcode:dependencies` (یک pass فقط-dependency مربوط به Knip در production که به آخرین نسخه Knip pin شده، با minimum release age مربوط به pnpm که برای نصب `dlx` غیرفعال شده است) و `pnpm deadcode:unused-files` را اجرا می‌کند؛ دومی findingهای production unused-file در Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. وقتی یک PR فایل استفاده‌نشده جدید و بررسی‌نشده‌ای اضافه کند یا entry کهنه‌ای در allowlist باقی بگذارد، guard مربوط به unused-file fail می‌شود، درحالی‌که surfaceهای عمدی dynamic plugin، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت statically resolve کند حفظ می‌کند. +shard مربوط به `check-dependencies`، `pnpm deadcode:dependencies` (یک گذر فقط وابستگی Knip تولید که به آخرین نسخه Knip pin شده و minimum release age مربوط به pnpm برای نصب `dlx` غیرفعال است) و `pnpm deadcode:unused-files` را اجرا می‌کند، که یافته‌های فایل استفاده‌نشده تولیدی Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه می‌کند. guard فایل استفاده‌نشده زمانی fail می‌شود که یک PR فایل استفاده‌نشده جدید و بازبینی‌نشده‌ای اضافه کند یا یک entry قدیمی در allowlist باقی بگذارد، در حالی که سطح‌های intentional dynamic plugin، generated، build، live-test، و package bridge را که Knip نمی‌تواند به‌صورت static resolve کند حفظ می‌کند. ## forwarding فعالیت ClawSweeper -`.github/workflows/clawsweeper-dispatch.yml` bridge سمت هدف از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیرtrusted را checkout یا اجرا نمی‌کند. workflow یک token برای GitHub App از `CLAWSWEEPER_APP_PRIVATE_KEY` می‌سازد، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند. +`.github/workflows/clawsweeper-dispatch.yml` پل سمت هدف از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیرقابل اعتماد را checkout یا اجرا نمی‌کند. workflow یک token مربوط به GitHub App از `CLAWSWEEPER_APP_PRIVATE_KEY` ایجاد می‌کند، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch می‌کند. این workflow چهار lane دارد: - `clawsweeper_item` برای درخواست‌های دقیق review مربوط به issue و pull request؛ - `clawsweeper_comment` برای commandهای صریح ClawSweeper در commentهای issue؛ - `clawsweeper_commit_review` برای درخواست‌های review در سطح commit روی pushهای `main`؛ -- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است inspect کند. +- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است بررسی کند. -lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها در صورت وجود. این کار عمدا از forward کردن body کامل webhook پرهیز می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper` فایل `.github/workflows/github-activity.yml` است، که event نرمال‌شده را برای agent مربوط به ClawSweeper به OpenClaw Gateway hook ارسال می‌کند. +lane مربوط به `github_activity` فقط metadata نرمال‌شده را forward می‌کند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها وقتی وجود داشته باشند. این lane عمداً از forward کردن کل body مربوط به webhook اجتناب می‌کند. workflow دریافت‌کننده در `openclaw/clawsweeper`، `.github/workflows/github-activity.yml` است، که event نرمال‌شده را برای agent مربوط به ClawSweeper به hook مربوط به OpenClaw Gateway ارسال می‌کند. -فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper هدف Discord را در prompt خود دریافت می‌کند و باید فقط وقتی event غافلگیرکننده، actionable، پرریسک، یا از نظر عملیاتی مفید است در `#clawsweeper` پست کند. بازکردن‌ها، ویرایش‌ها، churn ربات‌ها، noise تکراری webhook، و traffic عادی review باید به `NO_REPLY` منجر شوند. +فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper مقصد Discord را در prompt خود دریافت می‌کند و فقط وقتی event غافلگیرکننده، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید باشد باید در `#clawsweeper` پست کند. openهای routine، editها، bot churn، noise تکراری Webhook، و ترافیک عادی review باید به `NO_REPLY` منجر شوند. -در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و پیام‌های commit در GitHub را داده غیرtrusted بدانید. آن‌ها ورودی summarization و triage هستند، نه دستورهایی برای workflow یا runtime مربوط به agent. +در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و messageهای commit مربوط به GitHub را داده غیرقابل اعتماد در نظر بگیرید. آن‌ها input برای summarization و triage هستند، نه دستورالعمل برای workflow یا runtime agent. ## dispatchهای دستی -اجرای دستی CI همان گراف کار معمول CI را اجرا می‌کند، اما هر مسیر محدوده‌دار غیر Android را اجباری فعال می‌کند: شاردهای Linux Node، شاردهای Pluginهای بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسی‌های مستندات، Skills پایتون، Windows، macOS و i18n مربوط به Control UI. اجرای مستقل دستی CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، شارد فقط-انتشار `agentic-plugins`، پیمایش دسته‌ای کامل extension، و مسیرهای Docker پیش‌انتشار Plugin از CI کنار گذاشته شده‌اند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation`، workflow جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند. +اجرای دستی CI همان گراف کارهای CI عادی را اجرا می‌کند، اما همه مسیرهای scoped غیر Android را اجباری فعال می‌کند: shardهای Linux Node، shardهای Plugin بسته‌بندی‌شده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های مستندات، Python skills، Windows، macOS و Control UI i18n. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا می‌کند؛ چتر کامل انتشار، Android را با ارسال `include_android=true` فعال می‌کند. بررسی‌های ایستای پیش‌انتشار Plugin، shard فقط مخصوص انتشار `agentic-plugins`، sweep کامل دسته extension و مسیرهای Docker پیش‌انتشار Plugin از CI مستثنا هستند. مجموعه پیش‌انتشار Docker فقط زمانی اجرا می‌شود که `Full Release Validation` workflow جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند. -اجرای دستی از یک گروه concurrency یکتا استفاده می‌کند تا مجموعه کامل release-candidate توسط اجرای push یا PR دیگری روی همان ref لغو نشود. ورودی اختیاری `target_ref` به یک فراخوان trusted اجازه می‌دهد آن گراف را در برابر یک branch، tag، یا SHA کامل commit اجرا کند، در حالی که از فایل workflow مربوط به dispatch ref انتخاب‌شده استفاده می‌شود. +اجراهای دستی از یک گروه concurrency یکتا استفاده می‌کنند تا مجموعه کامل release-candidate با یک اجرای push یا PR دیگر روی همان ref لغو نشود. ورودی اختیاری `target_ref` به فراخوان مورد اعتماد اجازه می‌دهد آن گراف را روی یک branch، tag یا commit SHA کامل اجرا کند، در حالی که از فایل workflow متعلق به dispatch ref انتخاب‌شده استفاده می‌شود. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -96,14 +96,14 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Runnerها +## اجراکننده‌ها -| Runner | کارها | +| اجراکننده | کارها | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع protocol/contract/bundled، بررسی‌های شاردشده قرارداد کانال، شاردهای `check` به‌جز lint، شاردها و aggregateهای `check-additional`، verifierهای aggregate تست Node، بررسی‌های مستندات، Skills پایتون، workflow-sanity، labeler، auto-response؛ preflight مربوط به install-smoke نیز از Ubuntu میزبانی‌شده در GitHub استفاده می‌کند تا matrix مربوط به Blacksmith زودتر بتواند queue شود | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، شاردهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types` و `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، شاردهای تست Linux Node، شاردهای تست Plugin بسته‌بندی‌شده، `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به‌اندازه‌ای به CPU حساس است که 8 vCPU بیش از صرفه‌جویی‌اش هزینه داشت)؛ ساخت‌های Docker مربوط به install-smoke (هزینه زمان queue برای 32-vCPU بیش از صرفه‌جویی‌اش بود) | +| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسی‌های سریع protocol/contract/bundled، بررسی‌های sharded قرارداد کانال، shardهای `check` به‌جز lint، shardها و aggregateهای `check-additional`، verifierهای aggregate آزمون Node، بررسی‌های مستندات، Python skills، workflow-sanity، labeler، auto-response؛ install-smoke preflight نیز از Ubuntu میزبانی‌شده در GitHub استفاده می‌کند تا matrix Blacksmith زودتر بتواند queue شود | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، shardهای extension سبک‌تر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types` و `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، shardهای آزمون Linux Node، shardهای آزمون Plugin بسته‌بندی‌شده، `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (به اندازه‌ای حساس به CPU که 8 vCPU بیش از آنکه صرفه‌جویی کند هزینه داشت)؛ buildهای Docker برای install-smoke (هزینه زمان queue برای 32-vCPU بیش از صرفه‌جویی آن بود) | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `macos-node` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند | | `blacksmith-12vcpu-macos-latest` | `macos-swift` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback می‌کنند | @@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso ## عملکرد OpenClaw -`OpenClaw Performance` workflow عملکرد product/runtime است. این workflow روزانه روی `main` اجرا می‌شود و می‌توان آن را دستی هم dispatch کرد: +`OpenClaw Performance` workflow عملکرد محصول/runtime است. این workflow هر روز روی `main` اجرا می‌شود و می‌توان آن را به‌صورت دستی dispatch کرد: ```bash gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 @@ -145,25 +145,25 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -Dispatch دستی معمولا benchmark را روی workflow ref انجام می‌دهد. برای benchmark کردن یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و pointerهای latest بر اساس ref تست‌شده کلیدگذاری می‌شوند، و هر `index.md` ref/SHA تست‌شده، workflow ref/SHA، Kova ref، profile، حالت auth مسیر، مدل، تعداد تکرار، و فیلترهای سناریو را ثبت می‌کند. +dispatch دستی معمولاً benchmark را روی workflow ref اجرا می‌کند. برای benchmark گرفتن از یک tag انتشار یا branch دیگر با پیاده‌سازی فعلی workflow، `target_ref` را تنظیم کنید. مسیرهای گزارش منتشرشده و pointerهای latest بر اساس ref آزموده‌شده کلیدگذاری می‌شوند و هر `index.md`، ref/SHA آزموده‌شده، workflow ref/SHA، Kova ref، profile، حالت احراز هویت lane، model، تعداد تکرار و فیلترهای سناریو را ثبت می‌کند. -این workflow، OCM را از یک انتشار pin‌شده و Kova را از `openclaw/Kova` در ورودی pin‌شده `kova_ref` نصب می‌کند، سپس سه مسیر را اجرا می‌کند: +این workflow، OCM را از یک انتشار pinشده و Kova را از `openclaw/Kova` در ورودی pinشده `kova_ref` نصب می‌کند، سپس سه lane را اجرا می‌کند: -- `mock-provider`: سناریوهای diagnostic مربوط به Kova در برابر runtime ساخت محلی با auth جعلی deterministic سازگار با OpenAI. -- `mock-deep-profile`: profiling مربوط به CPU/heap/trace برای نقاط داغ startup، Gateway، و agent-turn. -- `live-gpt54`: یک نوبت agent واقعی OpenAI `openai/gpt-5.4` که وقتی `OPENAI_API_KEY` در دسترس نباشد skip می‌شود. +- `mock-provider`: سناریوهای diagnostic Kova در برابر runtime با local-build و احراز هویت fake سازگار با OpenAI به‌صورت deterministic. +- `mock-deep-profile`: profiling CPU/heap/trace برای hotspotهای startup، Gateway و agent-turn. +- `live-gpt54`: یک agent turn واقعی OpenAI `openai/gpt-5.4`، که وقتی `OPENAI_API_KEY` در دسترس نباشد skip می‌شود. -مسیر mock-provider پس از عبور Kova، probeهای source بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی boot و حافظه Gateway در حالت‌های startup پیش‌فرض، hook، و 50-Plugin؛ loopهای hello تکراری `channel-chat-baseline` با mock-OpenAI؛ و فرمان‌های startup مربوط به CLI در برابر Gateway بوت‌شده. خلاصه Markdown مربوط به source probe در بسته گزارش، در `source/index.md` قرار دارد و JSON خام کنار آن است. +lane مربوط به mock-provider پس از عبور Kova، probeهای source بومی OpenClaw را نیز اجرا می‌کند: زمان‌بندی boot و حافظه Gateway در حالت‌های startup پیش‌فرض، hook و 50-Plugin؛ loopهای تکراری hello برای mock-OpenAI `channel-chat-baseline`؛ و فرمان‌های startup CLI در برابر Gateway بوت‌شده. خلاصه Markdown مربوط به source probe در bundle گزارش در `source/index.md` قرار دارد و JSON خام کنار آن است. -هر مسیر artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance//-//` commit می‌کند. pointer فعلی tested-ref به‌شکل `openclaw-performance//latest-.json` نوشته می‌شود. +هر lane artifactهای GitHub را upload می‌کند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md` و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance//-//` commit می‌کند. pointer فعلی ref آزموده‌شده به‌صورت `openclaw-performance//latest-.json` نوشته می‌شود. ## اعتبارسنجی کامل انتشار -`Full Release Validation` workflow چتر دستی برای «اجرای همه‌چیز پیش از انتشار» است. این workflow یک branch، tag، یا SHA کامل commit می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای proof فقط-انتشار مربوط به Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های Docker release-path، live/E2E، OpenWebUI، parity مربوط به QA Lab، Matrix، و مسیرهای Telegram dispatch می‌کند. با `rerun_group=all` و `release_profile=full`، این workflow همچنین `NPM Telegram Beta E2E` را در برابر artifact مربوط به `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان مسیر package مربوط به Telegram در برابر package منتشرشده npm دوباره اجرا شود. +`Full Release Validation` workflow دستی چتری برای «اجرای همه چیز پیش از انتشار» است. این workflow یک branch، tag یا commit SHA کامل را می‌پذیرد، workflow دستی `CI` را با آن target dispatch می‌کند، `Plugin Prerelease` را برای اثبات فقط مخصوص انتشار در حوزه Plugin/package/static/Docker dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های Docker release-path، live/E2E، OpenWebUI، QA Lab parity، Matrix و laneهای Telegram dispatch می‌کند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان lane package مربوط به Telegram در برابر package منتشرشده npm دوباره اجرا شود. -برای matrix مرحله، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. +برای matrix مرحله، نام دقیق jobهای workflow، تفاوت‌های profile، artifactها و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. -`OpenClaw Release Publish` workflow دستی mutating انتشار است. پس از وجود داشتن tag انتشار و پس از موفقیت preflight مربوط به npm در OpenClaw، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای قابل انتشار Plugin dispatch می‌کند، `Plugin ClawHub Release` را برای همان SHA انتشار dispatch می‌کند، و فقط سپس `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند. +`OpenClaw Release Publish` workflow دستی mutating انتشار است. پس از اینکه tag انتشار وجود داشت و preflight مربوط به npm برای OpenClaw موفق شد، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify می‌کند، `Plugin NPM Release` را برای همه packageهای Plugin قابل انتشار dispatch می‌کند، `Plugin ClawHub Release` را برای همان release SHA dispatch می‌کند، و فقط بعد از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیره‌شده dispatch می‌کند. ```bash gh workflow run openclaw-release-publish.yml \ @@ -173,40 +173,35 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -برای proof مربوط به commit pin‌شده روی یک branch با حرکت سریع، به‌جای `gh workflow run ... --ref main -f ref=` از helper استفاده کنید: +برای اثبات commit pinشده روی یک branch که سریع حرکت می‌کند، به‌جای `gh workflow run ... --ref main -f ref=` از helper استفاده کنید: ```bash pnpm ci:full-release --sha ``` -Dispatch refهای workflow در GitHub باید branch یا tag باشند، نه SHA خام commit. helper یک branch موقت `release-ci/-...` را در SHA هدف push می‌کند، `Full Release Validation` را از آن ref pin‌شده dispatch می‌کند، verify می‌کند که `headSha` هر workflow فرزند با target مطابقت دارد، و پس از تکمیل run، branch موقت را حذف می‌کند. verifier چتر همچنین اگر هر workflow فرزند روی SHA متفاوتی اجرا شده باشد، fail می‌شود. +dispatch refهای GitHub workflow باید branch یا tag باشند، نه commit SHA خام. helper یک branch موقت `release-ci/-...` را در target SHA push می‌کند، `Full Release Validation` را از همان ref pinشده dispatch می‌کند، verify می‌کند که `headSha` هر child workflow با target مطابقت داشته باشد، و پس از کامل شدن run، branch موقت را حذف می‌کند. verifier چتری همچنین اگر هر child workflow در SHA متفاوتی اجرا شده باشد fail می‌شود. -`release_profile` گستره‌ی live/provider را که به بررسی‌های انتشار داده می‌شود کنترل می‌کند. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط زمانی از `full` استفاده کنید که عمدا ماتریس گسترده‌ی مشورتی provider/media را می‌خواهید. +`release_profile` گستره live/ارائه‌دهنده‌ای را کنترل می‌کند که به بررسی‌های انتشار پاس داده می‌شود. گردش‌کارهای انتشار دستی به‌طور پیش‌فرض از `stable` استفاده می‌کنند؛ فقط زمانی از `full` استفاده کنید که عمداً ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را می‌خواهید. -- `minimum` سریع‌ترین مسیرهای حیاتی انتشار OpenAI/core را نگه می‌دارد. -- `stable` مجموعه‌ی پایدار provider/backend را اضافه می‌کند. -- `full` ماتریس گسترده‌ی مشورتی provider/media را اجرا می‌کند. +- `minimum` سریع‌ترین مسیرهای OpenAI/هسته‌ای حیاتی برای انتشار را نگه می‌دارد. +- `stable` مجموعه پایدار ارائه‌دهنده/پس‌زمینه را اضافه می‌کند. +- `full` ماتریس گسترده مشورتی ارائه‌دهنده/رسانه را اجرا می‌کند. -چتر، شناسه‌های اجرای فرزندِ dispatchشده را ثبت می‌کند و کار نهایی `Verify full validation` دوباره نتیجه‌گیری‌های فعلی اجرای فرزند را بررسی می‌کند و جدول‌های کندترین کارها را برای هر اجرای فرزند اضافه می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شد و سبز شد، فقط کار تأییدکننده‌ی والد را دوباره اجرا کنید تا نتیجه‌ی چتر و خلاصه‌ی زمان‌بندی تازه‌سازی شود. +چتر، شناسه‌های اجرای فرزند ارسال‌شده را ثبت می‌کند، و کار نهایی `Verify full validation` نتیجه‌های فعلی اجرای فرزند را دوباره بررسی می‌کند و جدول‌های کندترین کار را برای هر اجرای فرزند پیوست می‌کند. اگر یک گردش‌کار فرزند دوباره اجرا شود و سبز شود، فقط کار راستی‌آزمای والد را دوباره اجرا کنید تا نتیجه چتر و خلاصه زمان‌بندی تازه شود. -برای بازیابی، هم `Full Release Validation` و هم `OpenClaw Release Checks` مقدار `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all` استفاده کنید، برای فقط فرزند CI کامل عادی از `ci`، برای فقط فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر روی چتر: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram`. این کار اجرای دوباره‌ی یک جعبه‌ی انتشار ناموفق را پس از یک رفع متمرکز محدود نگه می‌دارد. +برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` ورودی `rerun_group` را می‌پذیرند. برای یک نامزد انتشار از `all`، فقط برای فرزند CI کامل عادی از `ci`، فقط برای فرزند پیش‌انتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر استفاده کنید: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی چتر. این کار اجرای دوباره یک جعبه انتشار ناموفق را پس از یک اصلاح متمرکز، محدود نگه می‌دارد. -`OpenClaw Release Checks` از ref گردش‌کار معتمد استفاده می‌کند تا ref انتخاب‌شده را یک بار به tarball با نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردش‌کار Docker مسیر انتشار live/E2E و هم به shard پذیرش بسته می‌دهد. این کار بایت‌های بسته را در جعبه‌های انتشار یکسان نگه می‌دارد و از بسته‌بندی دوباره‌ی همان نامزد در چند کار فرزند جلوگیری می‌کند. +`OpenClaw Release Checks` از ref گردش‌کار مورداعتماد استفاده می‌کند تا ref انتخاب‌شده را یک‌بار به یک tarball به نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردش‌کار Docker مسیر انتشار live/E2E و هم به shard پذیرش بسته پاس می‌دهد. این کار بایت‌های بسته را در سراسر جعبه‌های انتشار ثابت نگه می‌دارد و از بسته‌بندی دوباره همان نامزد در چندین کار فرزند جلوگیری می‌کند. -اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all` -چتر قدیمی‌تر را جایگزین می‌کنند. ناظر والد هر گردش‌کار فرزندی را که -قبلا dispatch کرده است، هنگام لغو شدن والد لغو می‌کند، بنابراین اعتبارسنجی -جدیدتر main پشت یک اجرای قدیمی دو ساعته‌ی بررسی انتشار منتظر نمی‌ماند. -اعتبارسنجی شاخه/برچسب انتشار و گروه‌های اجرای دوباره‌ی متمرکز -`cancel-in-progress: false` را نگه می‌دارند. +اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all` چتر قدیمی‌تر را منسوخ می‌کنند. پایشگر والد هر گردش‌کار فرزندی را که قبلاً ارسال کرده باشد هنگام لغو والد لغو می‌کند، بنابراین اعتبارسنجی جدیدتر main پشت یک اجرای قدیمی دوساعته بررسی انتشار منتظر نمی‌ماند. اعتبارسنجی شاخه/برچسب انتشار و گروه‌های اجرای دوباره متمرکز، `cancel-in-progress: false` را حفظ می‌کنند. -## Shardهای live و E2E +## shardهای live و E2E -فرزند live/E2E انتشار، پوشش گسترده‌ی native `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک کار ترتیبی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند: +فرزند live/E2E انتشار پوشش گسترده بومی `pnpm test:live` را نگه می‌دارد، اما آن را به‌جای یک کار سریالی، به‌صورت shardهای نام‌گذاری‌شده از طریق `scripts/test-live-shard.mjs` اجرا می‌کند: - `native-live-src-agents` - `native-live-src-gateway-core` -- کارهای provider-filtered با نام `native-live-src-gateway-profiles` +- کارهای `native-live-src-gateway-profiles` فیلترشده بر اساس ارائه‌دهنده - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -214,63 +209,61 @@ Dispatch refهای workflow در GitHub باید branch یا tag باشند، ن - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- shardهای جداشده‌ی صدای/ویدئوی media و shardهای موسیقی provider-filtered +- shardهای جداشده صوت/ویدئوی رسانه و shardهای موسیقی فیلترشده بر اساس ارائه‌دهنده -این کار همان پوشش فایل را حفظ می‌کند، درحالی‌که اجرای دوباره و عیب‌یابی خرابی‌های کند provider در live را آسان‌تر می‌کند. نام shardهای تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media`، و `native-live-extensions-media-music` همچنان برای اجرای دوباره‌ی دستی یک‌باره معتبر می‌مانند. +این کار همان پوشش فایل را حفظ می‌کند، در حالی که اجرای دوباره و تشخیص خرابی‌های کند ارائه‌دهنده live را آسان‌تر می‌کند. نام‌های shard تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media` و `native-live-extensions-media-music` همچنان برای اجرای دوباره دستی یک‌مرحله‌ای معتبر می‌مانند. -Shardهای media native live در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن تصویر `ffmpeg` و `ffprobe` را از پیش نصب می‌کند؛ کارهای media فقط پیش از آماده‌سازی، باینری‌ها را بررسی می‌کنند. مجموعه‌های live متکی بر Docker را روی runnerهای عادی Blacksmith نگه دارید — کارهای container جای مناسبی برای اجرای تست‌های Docker تودرتو نیستند. +shardهای رسانه live بومی در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا می‌شوند که توسط گردش‌کار `Live Media Runner Image` ساخته می‌شود. آن image، `ffmpeg` و `ffprobe` را از پیش نصب می‌کند؛ کارهای رسانه فقط پیش از راه‌اندازی دودویی‌ها را راستی‌آزمایی می‌کنند. مجموعه‌های live متکی بر Docker را روی runnerهای معمول Blacksmith نگه دارید — کارهای کانتینری جای درستی برای راه‌اندازی آزمون‌های Docker تو‌در‌تو نیستند. -Shardهای live model/backend متکی بر Docker از یک تصویر مشترک جداگانه‌ی `ghcr.io/openclaw/openclaw-live-test:` برای هر commit انتخاب‌شده استفاده می‌کنند. گردش‌کار live انتشار آن تصویر را یک بار می‌سازد و push می‌کند، سپس shardهای Docker live model، Gateway با shardبندی provider، CLI backend، اتصال ACP، و harness مربوط به Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. Shardهای Gateway Docker سقف‌های explicit در سطح script با `timeout` دارند که پایین‌تر از timeout کار گردش‌کار است، تا یک container گیرکرده یا مسیر پاک‌سازی به‌جای مصرف کل بودجه‌ی بررسی انتشار سریع شکست بخورد. اگر آن shardها هدف Docker کامل source را مستقل بازسازی کنند، اجرای انتشار پیکربندی نادرستی دارد و زمان دیواری را برای ساخت‌های تکراری تصویر هدر خواهد داد. +shardهای live مدل/پس‌زمینه متکی بر Docker برای هر commit انتخاب‌شده از یک image مشترک جداگانه `ghcr.io/openclaw/openclaw-live-test:` استفاده می‌کنند. گردش‌کار انتشار live آن image را یک‌بار می‌سازد و push می‌کند، سپس shardهای مدل live Docker، Gateway شاردشده بر اساس ارائه‌دهنده، پس‌زمینه CLI، اتصال ACP و harness Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌شوند. shardهای Docker مربوط به Gateway سقف‌های `timeout` صریح در سطح اسکریپت دارند که پایین‌تر از timeout کار گردش‌کار است، تا یک کانتینر گیرکرده یا مسیر پاک‌سازی، به‌جای مصرف کل بودجه بررسی انتشار، سریع شکست بخورد. اگر آن shardها target کامل Docker منبع را مستقل دوباره بسازند، اجرای انتشار بد پیکربندی شده است و زمان دیواری را روی ساخت‌های تکراری image هدر خواهد داد. ## پذیرش بسته -وقتی پرسش این است که «آیا این بسته‌ی قابل نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» از `Package Acceptance` استفاده کنید. این با CI عادی فرق دارد: CI عادی درخت source را اعتبارسنجی می‌کند، درحالی‌که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E که کاربران پس از نصب یا به‌روزرسانی به کار می‌گیرند اعتبارسنجی می‌کند. +از `Package Acceptance` وقتی استفاده کنید که پرسش این است: «آیا این بسته قابل نصب OpenClaw به‌عنوان یک محصول کار می‌کند؟» این با CI عادی متفاوت است: CI عادی درخت منبع را اعتبارسنجی می‌کند، در حالی که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E اعتبارسنجی می‌کند که کاربران پس از نصب یا به‌روزرسانی تجربه می‌کنند. ### کارها -1. `resolve_package` مقدار `workflow_ref` را checkout می‌کند، یک نامزد بسته را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact با نام `package-under-test` آپلود می‌کند، و source، ref گردش‌کار، ref بسته، نسخه، SHA-256، و profile را در خلاصه‌ی مرحله‌ی GitHub چاپ می‌کند. -2. `docker_acceptance` فایل `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار قابل استفاده‌ی مجدد آن artifact را دانلود می‌کند، inventory مربوط به tarball را اعتبارسنجی می‌کند، هنگام نیاز تصویرهای Docker با digest بسته را آماده می‌کند، و مسیرهای Docker انتخاب‌شده را به‌جای بسته‌بندی checkout گردش‌کار، در برابر آن بسته اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب می‌کند، گردش‌کار قابل استفاده‌ی مجدد بسته و تصویرهای مشترک را یک بار آماده می‌کند، سپس آن مسیرها را به‌عنوان کارهای Docker هدفمند موازی با artifactهای یکتا پخش می‌کند. -3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. وقتی `telegram_mode` برابر `none` نیست اجرا می‌شود و زمانی که پذیرش بسته یک مورد را resolve کرده باشد همان artifact با نام `package-under-test` را نصب می‌کند؛ dispatch مستقل Telegram همچنان می‌تواند یک spec منتشرشده‌ی npm را نصب کند. -4. `summary` اگر resolve بسته، پذیرش Docker، یا مسیر اختیاری Telegram شکست خورده باشد گردش‌کار را ناموفق می‌کند. +1. `resolve_package`، `workflow_ref` را checkout می‌کند، یک نامزد بسته را resolve می‌کند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را می‌نویسد، `.artifacts/docker-e2e-package/package-candidate.json` را می‌نویسد، هر دو را به‌عنوان artifact به نام `package-under-test` بارگذاری می‌کند، و منبع، ref گردش‌کار، ref بسته، نسخه، SHA-256 و profile را در خلاصه گام GitHub چاپ می‌کند. +2. `docker_acceptance`، `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی می‌کند. گردش‌کار قابل استفاده مجدد آن artifact را دانلود می‌کند، موجودی tarball را اعتبارسنجی می‌کند، در صورت نیاز imageهای Docker با digest بسته را آماده می‌کند، و مسیرهای انتخاب‌شده Docker را به‌جای بسته‌بندی checkout گردش‌کار، علیه همان بسته اجرا می‌کند. وقتی یک profile چند `docker_lanes` هدفمند را انتخاب می‌کند، گردش‌کار قابل استفاده مجدد بسته و imageهای مشترک را یک‌بار آماده می‌کند، سپس آن مسیرها را به‌صورت کارهای Docker هدفمند موازی با artifactهای یکتا پخش می‌کند. +3. `package_telegram` به‌صورت اختیاری `NPM Telegram Beta E2E` را فراخوانی می‌کند. این کار وقتی اجرا می‌شود که `telegram_mode` برابر `none` نباشد و همان artifact به نام `package-under-test` را زمانی نصب می‌کند که پذیرش بسته یکی را resolve کرده باشد؛ ارسال مستقل Telegram همچنان می‌تواند یک مشخصه منتشرشده npm را نصب کند. +4. `summary` اگر resolve بسته، پذیرش Docker، یا مسیر اختیاری Telegram شکست خورده باشد، گردش‌کار را ناموفق می‌کند. ### منابع نامزد -- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه‌ی دقیق انتشار OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این برای پذیرش پیش‌انتشار/پایدار منتشرشده استفاده کنید. -- `source=ref` یک شاخه، برچسب، یا SHA کامل commit از `package_ref` معتمد را بسته‌بندی می‌کند. Resolver شاخه‌ها/برچسب‌های OpenClaw را fetch می‌کند، بررسی می‌کند که commit انتخاب‌شده از تاریخچه‌ی شاخه‌ی repository یا یک برچسب انتشار قابل دسترسی باشد، deps را در یک worktree جداشده نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند. -- `source=url` یک `.tgz` مبتنی بر HTTPS را دانلود می‌کند؛ `package_sha256` الزامی است. -- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود می‌کند؛ `package_sha256` اختیاری است اما برای artifactهای به‌اشتراک‌گذاشته‌شده‌ی بیرونی باید ارائه شود. +- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق OpenClaw مانند `openclaw@2026.4.27-beta.2` را می‌پذیرد. از این برای پذیرش پیش‌انتشار/پایدار منتشرشده استفاده کنید. +- `source=ref` یک شاخه، برچسب، یا SHA کامل commit مورداعتماد `package_ref` را بسته‌بندی می‌کند. resolver شاخه‌ها/برچسب‌های OpenClaw را fetch می‌کند، راستی‌آزمایی می‌کند که commit انتخاب‌شده از تاریخچه شاخه مخزن یا یک برچسب انتشار قابل دسترسی باشد، وابستگی‌ها را در یک worktree جداشده نصب می‌کند، و آن را با `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند. +- `source=url` یک `.tgz` از HTTPS دانلود می‌کند؛ `package_sha256` الزامی است. +- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود می‌کند؛ `package_sha256` اختیاری است، اما برای artifactهای اشتراک‌گذاری‌شده خارجی باید ارائه شود. -`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد معتمد گردش‌کار/harness است که تست را اجرا می‌کند. `package_ref` همان commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این اجازه می‌دهد harness تست فعلی commitهای منبع معتمد قدیمی‌تر را بدون اجرای منطق قدیمی گردش‌کار اعتبارسنجی کند. +`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد مورداعتماد گردش‌کار/harness است که آزمون را اجرا می‌کند. `package_ref` commit منبعی است که وقتی `source=ref` باشد بسته‌بندی می‌شود. این اجازه می‌دهد harness آزمون فعلی، commitهای منبع مورداعتماد قدیمی‌تر را بدون اجرای منطق گردش‌کار قدیمی اعتبارسنجی کند. -### Profileهای مجموعه +### profileهای مجموعه - `smoke` — `npm-onboard-channel-agent`، `gateway-network`، `config-reload` - `package` — `npm-onboard-channel-agent`، `doctor-switch`، `update-channel-switch`، `upgrade-survivor`، `published-upgrade-survivor`، `plugins-offline`، `plugin-update` -- `product` — `package` به‌علاوه‌ی `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui` -- `full` — chunkهای کامل مسیر انتشار Docker با OpenWebUI -- `custom` — مقدار دقیق `docker_lanes`؛ وقتی `suite_profile=custom` باشد الزامی است +- `product` — `package` به‌علاوه `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui` +- `full` — chunkهای کامل Docker مسیر انتشار همراه با OpenWebUI +- `custom` — `docker_lanes` دقیق؛ وقتی `suite_profile=custom` باشد الزامی است -Profile مربوط به `package` از پوشش آفلاین Plugin استفاده می‌کند تا اعتبارسنجی بسته‌ی منتشرشده به دسترس‌بودن live ClawHub وابسته نباشد. مسیر اختیاری Telegram از artifact با نام `package-under-test` در `NPM Telegram Beta E2E` دوباره استفاده می‌کند، و مسیر spec منتشرشده‌ی npm برای dispatchهای مستقل نگه داشته می‌شود. +profile به نام `package` از پوشش آفلاین Plugin استفاده می‌کند تا اعتبارسنجی بسته منتشرشده وابسته به دسترس‌پذیری live ClawHub نباشد. مسیر اختیاری Telegram در `NPM Telegram Beta E2E` از artifact به نام `package-under-test` دوباره استفاده می‌کند، در حالی که مسیر مشخصه npm منتشرشده برای ارسال‌های مستقل نگه داشته می‌شود. -برای سیاست اختصاصی تست به‌روزرسانی و Plugin، شامل فرمان‌های محلی، -مسیرهای Docker، ورودی‌های پذیرش بسته، پیش‌فرض‌های انتشار، و triage شکست، -[تست به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) را ببینید. +برای سیاست اختصاصی آزمون به‌روزرسانی و Plugin، شامل فرمان‌های محلی، مسیرهای Docker، ورودی‌های پذیرش بسته، پیش‌فرض‌های انتشار، و تریاژ خرابی، [Testing updates and plugins](/fa/help/testing-updates-plugins) را ببینید. -بررسی‌های انتشار، پذیرش بسته را با `source=artifact`، artifact بسته‌ی انتشار آماده‌شده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues`، و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار اثبات مهاجرت بسته، به‌روزرسانی، پاک‌سازی وابستگی Plugin کهنه، ترمیم نصب Plugin پیکربندی‌شده، Plugin آفلاین، به‌روزرسانی Plugin، و Telegram را روی همان tarball بسته‌ی resolveشده نگه می‌دارد. برای اجرای همان ماتریس در برابر یک بسته‌ی npm ارسال‌شده به‌جای artifact ساخته‌شده از SHA، مقدار `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسی‌های انتشار cross-OS همچنان onboarding، installer، و رفتار platform وابسته به سیستم‌عامل را پوشش می‌دهند؛ اعتبارسنجی محصول بسته/به‌روزرسانی باید با پذیرش بسته شروع شود. مسیر Docker با نام `published-upgrade-survivor` در هر اجرا یک baseline بسته‌ی منتشرشده را اعتبارسنجی می‌کند. در پذیرش بسته، tarball resolveشده‌ی `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده‌ی fallback را انتخاب می‌کند، که پیش‌فرض آن `openclaw@latest` است؛ فرمان‌های اجرای دوباره‌ی مسیر ناموفق آن baseline را حفظ می‌کنند. برای گسترش Full Release CI در همه‌ی انتشارهای پایدار npm از `2026.4.23` تا `latest`، مقدار `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` همچنان برای نمونه‌گیری دستی گسترده‌تر با anchor قدیمی‌تر پیش از تاریخ در دسترس است. برای گسترش همان baselineها در fixtureهای شبیه issue برای پیکربندی Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های OpenClaw Plugin پیکربندی‌شده، مسیرهای log با tilde، و rootهای وابستگی legacy Plugin کهنه، مقدار `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردش‌کار جداگانه‌ی `Update Migration` زمانی از مسیر Docker با نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده می‌کند که پرسش درباره‌ی پاک‌سازی کامل به‌روزرسانی منتشرشده باشد، نه گستره‌ی عادی Full Release CI. اجراهای تجمیعی محلی می‌توانند specهای دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` بدهند، یک مسیر واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس scenario تنظیم کنند. مسیر منتشرشده baseline را با یک دستورالعمل آماده‌ی فرمان `openclaw config set` پیکربندی می‌کند، گام‌های دستورالعمل را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz`، به‌علاوه‌ی وضعیت RPC را probe می‌کند. مسیرهای تازه‌ی بسته‌بندی‌شده و installer در Windows همچنین بررسی می‌کنند که یک بسته‌ی نصب‌شده بتواند override مربوط به browser-control را از یک مسیر مطلق خام Windows import کند. Smoke مربوط به agent-turn cross-OS با OpenAI در صورت تنظیم‌شدن `OPENCLAW_CROSS_OS_OPENAI_MODEL` به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی مدل تست GPT-5 بماند و از پیش‌فرض‌های GPT-4.x دوری شود. +بررسی‌های انتشار، پذیرش بسته را با `source=artifact`، artifact بسته انتشار آماده‌شده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues` و `telegram_mode=mock-openai` فراخوانی می‌کنند. این کار اثبات مهاجرت بسته، به‌روزرسانی، پاک‌سازی وابستگی Plugin کهنه، تعمیر نصب Plugin پیکربندی‌شده، Plugin آفلاین، به‌روزرسانی Plugin و Telegram را روی همان tarball بسته resolveشده نگه می‌دارد. برای اجرای همان ماتریس علیه یک بسته npm ارسال‌شده به‌جای artifact ساخته‌شده از SHA، `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسی‌های انتشار چندسیستمی همچنان onboarding، نصب‌کننده، و رفتار پلتفرمی خاص OS را پوشش می‌دهند؛ اعتبارسنجی محصول بسته/به‌روزرسانی باید از پذیرش بسته شروع شود. مسیر Docker به نام `published-upgrade-survivor` در هر اجرا یک baseline بسته منتشرشده را اعتبارسنجی می‌کند. در پذیرش بسته، tarball resolveشده `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline`، baseline منتشرشده fallback را انتخاب می‌کند که پیش‌فرض آن `openclaw@latest` است؛ فرمان‌های اجرای دوباره مسیر ناموفق آن baseline را حفظ می‌کنند. برای گسترش CI انتشار کامل روی هر انتشار پایدار npm از `2026.4.23` تا `latest`، `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` برای نمونه‌برداری دستی گسترده‌تر با لنگر پیشاتاریخ قدیمی‌تر همچنان در دسترس است. برای گسترش همان baselineها در fixtureهای مشابه issue برای پیکربندی Feishu، فایل‌های bootstrap/persona حفظ‌شده، نصب‌های Plugin پیکربندی‌شده OpenClaw، مسیرهای log با tilde، و ریشه‌های وابستگی Plugin قدیمی و کهنه، `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردش‌کار جداگانه `Update Migration` وقتی پرسش، پاک‌سازی جامع به‌روزرسانی منتشرشده است و نه گستره عادی CI انتشار کامل، از مسیر Docker به نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده می‌کند. اجراهای تجمیعی محلی می‌توانند مشخصه‌های دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` پاس دهند، یک مسیر واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس سناریو تنظیم کنند. مسیر منتشرشده baseline را با یک دستور پخته‌شده `openclaw config set` پیکربندی می‌کند، گام‌های دستور را در `summary.json` ثبت می‌کند، و پس از شروع Gateway، `/healthz`، `/readyz` و وضعیت RPC را probe می‌کند. مسیرهای تازه بسته‌بندی‌شده و نصب‌کننده Windows همچنین راستی‌آزمایی می‌کنند که یک بسته نصب‌شده بتواند override کنترل مرورگر را از یک مسیر مطلق خام Windows import کند. smoke چرخش agent چندسیستمی OpenAI وقتی `OPENCLAW_CROSS_OS_OPENAI_MODEL` تنظیم شده باشد به‌طور پیش‌فرض از آن استفاده می‌کند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی یک مدل آزمون GPT-5 بماند و از پیش‌فرض‌های GPT-4.x پرهیز شود. ### پنجره‌های سازگاری legacy -پذیرش بسته برای بسته‌های از قبل منتشرشده پنجره‌های سازگاری legacy محدود دارد. بسته‌ها تا `2026.4.25`، شامل `2026.4.25-beta.*`، می‌توانند از مسیر سازگاری استفاده کنند: +پذیرش بسته پنجره‌های سازگاری legacy محدود برای بسته‌هایی دارد که از قبل منتشر شده‌اند. بسته‌ها تا `2026.4.25`، شامل `2026.4.25-beta.*`، ممکن است از مسیر سازگاری استفاده کنند: -- ورودی‌های QA خصوصی شناخته‌شده در `dist/postinstall-inventory.json` ممکن است به فایل‌هایی اشاره کنند که از tarball حذف شده‌اند؛ -- وقتی بسته آن flag را expose نمی‌کند، `doctor-switch` ممکن است زیرمورد persistence مربوط به `gateway install --wrapper` را رد کند؛ -- `update-channel-switch` ممکن است `pnpm.patchedDependencies` مفقود را از fixture ساختگی git مشتق‌شده از tarball حذف کند و ممکن است مقدار persisted مفقود `update.channel` را log کند؛ -- smokeهای Plugin ممکن است محل‌های legacy رکورد نصب را بخوانند یا persistence مفقود رکورد نصب marketplace را بپذیرند؛ -- `plugin-update` ممکن است مهاجرت metadata پیکربندی را مجاز بداند، درحالی‌که همچنان لازم می‌داند رکورد نصب و رفتار بدون نصب دوباره بدون تغییر بمانند. +- ورودی‌های خصوصی شناخته‌شده QA در `dist/postinstall-inventory.json` ممکن است به فایل‌های حذف‌شده از tarball اشاره کنند؛ +- `doctor-switch` ممکن است زیرمورد ماندگاری `gateway install --wrapper` را وقتی بسته آن flag را expose نمی‌کند رد کند؛ +- `update-channel-switch` ممکن است `pnpm.patchedDependencies` گمشده را از fixture جعلی git مشتق‌شده از tarball هرس کند و ممکن است `update.channel` ماندگار گمشده را log کند؛ +- smokeهای Plugin ممکن است مکان‌های legacy رکورد نصب را بخوانند یا نبود ماندگاری رکورد نصب marketplace را بپذیرند؛ +- `plugin-update` ممکن است مهاجرت metadata پیکربندی را مجاز بداند، در حالی که همچنان الزام می‌کند رکورد نصب و رفتار عدم نصب مجدد بدون تغییر بمانند. -بسته‌ی منتشرشده‌ی `2026.4.26` همچنین ممکن است برای فایل‌های stamp مربوط به metadata ساخت محلی که از قبل ارسال شده بودند هشدار بدهد. بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا رد شدن، شکست می‌خورند. +بسته منتشرشده `2026.4.26` نیز ممکن است برای فایل‌های stamp metadata ساخت محلی که از قبل ارسال شده بودند هشدار دهد. بسته‌های بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به‌جای هشدار یا رد شدن، شکست می‌خورند. -### مثال‌ها +### نمونه‌ها ```bash # Validate the current beta package with product-level coverage. @@ -311,110 +304,110 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -هنگام اشکال‌زدایی یک اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه، و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و مصنوعات Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، گزارش‌های lane، زمان‌بندی فازها، و فرمان‌های اجرای دوباره. به‌جای اجرای دوباره‌ی اعتبارسنجی کامل انتشار، اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا laneهای دقیق Docker را ترجیح دهید. +هنگام اشکال‌زدایی اجرای ناموفق پذیرش بسته، از خلاصه‌ی `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکت‌های Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، لاگ‌های lane، زمان‌بندی فازها و فرمان‌های اجرای دوباره. اجرای دوباره‌ی پروفایل بسته‌ی ناموفق یا laneهای دقیق Docker را به اجرای دوباره‌ی اعتبارسنجی کامل انتشار ترجیح دهید. -## آزمون smoke نصب +## دودآزمایی نصب -گردش‌کار جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق کار `preflight` خودش دوباره استفاده می‌کند. این پوشش smoke را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند. +Workflow جداگانه‌ی `Install Smoke` همان اسکریپت دامنه را از طریق job مخصوص خود به نام `preflight` دوباره استفاده می‌کند. این workflow پوشش دودآزمایی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم می‌کند. -- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/manifest مربوط به Pluginهای همراه، یا سطح‌های اصلی Plugin/channel/Gateway/Plugin SDK را لمس می‌کنند که کارهای smoke Docker آن‌ها را اجرا می‌کنند. تغییرات فقط-منبع در Pluginهای همراه، ویرایش‌های فقط-تست، و ویرایش‌های فقط-مستندات، workerهای Docker را رزرو نمی‌کنند. مسیر سریع، تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، smoke حذف agents از فضای کاری مشترک در CLI را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک آرگومان ساخت extension همراه را تأیید می‌کند، و پروفایل Docker محدود Plugin همراه را زیر مهلت زمانی تجمیعی ۲۴۰ ثانیه‌ای برای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود). -- **مسیر کامل** نصب بسته QR و پوشش Docker/به‌روزرسانی نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر smoke هدف-SHA از Dockerfile ریشه در GHCR را آماده یا دوباره استفاده می‌کند، سپس نصب بسته QR، smokeهای Dockerfile/Gateway ریشه، smokeهای نصب‌کننده/به‌روزرسانی، و E2E سریع Docker مربوط به Plugin همراه را به‌عنوان کارهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت smokeهای تصویر ریشه منتظر نماند. +- **مسیر سریع** برای pull requestهایی اجرا می‌شود که سطح‌های Docker/بسته، تغییرات بسته/manifest مربوط به Pluginهای همراه، یا سطح‌های Plugin/کانال/Gateway/Plugin SDK هسته را که jobهای دودآزمایی Docker اجرا می‌کنند، لمس کرده باشند. تغییرات فقط‌منبع در Pluginهای همراه، ویرایش‌های فقط‌تست، و ویرایش‌های فقط‌مستندات workerهای Docker را رزرو نمی‌کنند. مسیر سریع تصویر Dockerfile ریشه را یک‌بار می‌سازد، CLI را بررسی می‌کند، دودآزمایی CLI حذف agentهای workspace مشترک را اجرا می‌کند، e2e مربوط به gateway-network کانتینر را اجرا می‌کند، یک build arg برای extension همراه را تأیید می‌کند، و پروفایل Docker محدودِ Plugin همراه را با timeout تجمعی ۲۴۰ ثانیه‌ای برای فرمان اجرا می‌کند (اجرای Docker هر سناریو جداگانه محدود می‌شود). +- **مسیر کامل** پوشش نصب بسته‌ی QR و Docker/update مربوط به نصب‌کننده را برای اجراهای زمان‌بندی‌شده‌ی شبانه، dispatchهای دستی، بررسی‌های انتشار با workflow-call، و pull requestهایی نگه می‌دارد که واقعاً سطح‌های نصب‌کننده/بسته/Docker را لمس می‌کنند. در حالت کامل، install-smoke یک تصویر دودآزمایی GHCR از Dockerfile ریشه برای target-SHA آماده می‌کند یا دوباره استفاده می‌کند، سپس نصب بسته‌ی QR، دودآزمایی‌های Dockerfile/Gateway ریشه، دودآزمایی‌های نصب‌کننده/update، و Docker E2E سریعِ Plugin همراه را به‌عنوان jobهای جداگانه اجرا می‌کند تا کار نصب‌کننده پشت دودآزمایی‌های تصویر ریشه منتظر نماند. -pushهای `main` (از جمله commitهای merge) مسیر کامل را اجبار نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push پوشش کامل را درخواست کند، گردش‌کار smoke سریع Docker را نگه می‌دارد و smoke کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند. +pushهای `main` (از جمله merge commitها) مسیر کامل را اجباری نمی‌کنند؛ وقتی منطق دامنه‌ی تغییرات روی یک push پوشش کامل را درخواست کند، workflow دودآزمایی سریع Docker را نگه می‌دارد و دودآزمایی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار می‌کند. -smoke کند provider تصویر در نصب سراسری Bun به‌طور جداگانه با `run_bun_global_install_smoke` دروازه‌بانی می‌شود. این smoke روی زمان‌بندی شبانه و از گردش‌کار بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` آن را اجرا نمی‌کنند. تست‌های QR و Docker نصب‌کننده، Dockerfileهای متمرکز بر نصب خودشان را نگه می‌دارند. +دودآزمایی کندِ ارائه‌دهنده‌ی تصویر با نصب global در Bun به‌طور جداگانه با `run_bun_global_install_smoke` کنترل می‌شود. این دودآزمایی در زمان‌بندی شبانه و از workflow بررسی‌های انتشار اجرا می‌شود، و dispatchهای دستی `Install Smoke` می‌توانند آن را فعال کنند، اما pull requestها و pushهای `main` این کار را نمی‌کنند. تست‌های Docker مربوط به QR و نصب‌کننده Dockerfileهای نصب‌محور خودشان را نگه می‌دارند. -## E2E محلی Docker +## Docker E2E محلی -`pnpm test:docker:all` یک تصویر مشترک live-test را از پیش می‌سازد، OpenClaw را یک‌بار به‌صورت tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` می‌سازد: +`pnpm test:docker:all` یک تصویر live-test مشترک را از قبل می‌سازد، OpenClaw را یک‌بار به‌صورت tarball npm بسته‌بندی می‌کند، و دو تصویر مشترک `scripts/e2e/Dockerfile` را می‌سازد: -- یک اجراکننده‌ی خام Node/Git برای laneهای نصب‌کننده/به‌روزرسانی/وابستگی-Plugin؛ +- یک runner خام Node/Git برای laneهای نصب‌کننده/update/وابستگی Plugin؛ - یک تصویر کاربردی که همان tarball را برای laneهای عملکرد عادی در `/app` نصب می‌کند. -تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و اجراکننده فقط طرح انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر را برای هر lane با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند. +تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامه‌ریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و runner فقط طرح انتخاب‌شده را اجرا می‌کند. زمان‌بند تصویر هر lane را با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب می‌کند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند. -### قابل تنظیم‌ها +### تنظیم‌پذیرها | متغیر | پیش‌فرض | هدف | | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای استخر اصلی برای laneهای عادی. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای استخر انتهایی حساس به provider. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live هم‌زمان تا providerها throttle نکنند. | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای pool اصلی برای laneهای عادی. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای pool انتهایی حساس به provider. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live هم‌زمان تا providerها throttle نکنند. | | `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | سقف laneهای نصب npm هم‌زمان. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی هم‌زمان. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌گذاری بین شروع laneها برای جلوگیری از هجوم ایجاد در daemon Docker؛ برای بدون فاصله‌گذاری `0` تنظیم کنید. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | مهلت زمانی پشتیبان برای هر lane (۱۲۰ دقیقه)؛ laneهای live/tail انتخاب‌شده سقف‌های فشرده‌تری دارند. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` طرح زمان‌بند را بدون اجرای laneها چاپ می‌کند. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکننده‌ی ویرگول؛ smoke پاک‌سازی را رد می‌کند تا agents بتوانند یک lane ناموفق را بازتولید کنند. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی هم‌زمان. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصله‌ی زمانی بین شروع laneها برای جلوگیری از هجوم create در daemon Docker؛ برای نبود فاصله `0` بگذارید. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | timeout پشتیبان برای هر lane (۱۲۰ دقیقه)؛ laneهای live/tail انتخاب‌شده سقف‌های سخت‌گیرانه‌تری دارند. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` طرح زمان‌بند را بدون اجرای laneها چاپ می‌کند. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکننده‌ی کاما؛ دودآزمایی پاک‌سازی را رد می‌کند تا agentها بتوانند یک lane ناموفق را بازتولید کنند. | -laneای که از سقف مؤثرش سنگین‌تر باشد همچنان می‌تواند از یک استخر خالی شروع شود، سپس تا زمانی که ظرفیت را آزاد کند به‌تنهایی اجرا می‌شود. preflightهای تجمیعی محلی Docker را بررسی می‌کنند، کانتینرهای کهنه‌ی E2E مربوط به OpenClaw را حذف می‌کنند، وضعیت lane فعال را منتشر می‌کنند، زمان‌بندی laneها را برای ترتیب‌دهی longest-first ماندگار می‌کنند، و به‌طور پیش‌فرض پس از نخستین شکست، زمان‌بندی laneهای pooled جدید را متوقف می‌کنند. +laneای که از سقف مؤثر خود سنگین‌تر است همچنان می‌تواند از یک pool خالی شروع شود، سپس تا زمانی که ظرفیت را آزاد کند به‌تنهایی اجرا می‌شود. preflight تجمعی محلی Docker را بررسی می‌کند، کانتینرهای کهنه‌ی OpenClaw E2E را حذف می‌کند، وضعیت laneهای فعال را منتشر می‌کند، زمان‌بندی laneها را برای مرتب‌سازی طولانی‌ترین‌ها در ابتدا نگه می‌دارد، و به‌طور پیش‌فرض پس از نخستین شکست، زمان‌بندی laneهای pooled جدید را متوقف می‌کند. -### گردش‌کار live/E2E قابل استفاده‌ی دوباره +### Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E -گردش‌کار live/E2E قابل استفاده‌ی دوباره از `scripts/test-docker-all.mjs --plan-json` می‌پرسد که کدام بسته، نوع تصویر، تصویر live، lane، و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن طرح را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این گردش‌کار یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا مصنوع بسته‌ی اجرای جاری را دانلود می‌کند، یا یک مصنوع بسته را از `package_artifact_run_id` دانلود می‌کند؛ موجودی tarball را اعتبارسنجی می‌کند؛ وقتی طرح به laneهای با بسته نصب‌شده نیاز دارد، تصویرهای E2E خام/کاربردی Docker در GHCR با tag مبتنی بر digest بسته را از طریق کش لایه‌ی Docker در Blacksmith می‌سازد و push می‌کند؛ و به‌جای ساخت دوباره، ورودی‌های `docker_e2e_bare_image`/`docker_e2e_functional_image` ارائه‌شده یا تصویرهای موجود مبتنی بر digest بسته را دوباره استفاده می‌کند. pullهای تصویر Docker با یک مهلت زمانی محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا جریان گیرکرده‌ی registry/cache به‌جای مصرف بیشتر مسیر بحرانی CI، سریع دوباره تلاش شود. +Workflow قابل‌استفاده‌ی دوباره‌ی live/E2E از `scripts/test-docker-all.mjs --plan-json` می‌پرسد کدام بسته، نوع تصویر، تصویر live، lane و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن طرح را به خروجی‌ها و خلاصه‌های GitHub تبدیل می‌کند. این workflow یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بسته‌بندی می‌کند، یا آرتیفکت بسته‌ی اجرای فعلی را دانلود می‌کند، یا یک آرتیفکت بسته را از `package_artifact_run_id` دانلود می‌کند؛ inventory tarball را اعتبارسنجی می‌کند؛ وقتی طرح به laneهای package-installed نیاز داشته باشد، تصاویر Docker E2E خام/کاربردی GHCR با tag مبتنی بر digest بسته را از طریق cache لایه‌ی Docker در Blacksmith می‌سازد و push می‌کند؛ و به‌جای ساخت دوباره، از ورودی‌های ارائه‌شده‌ی `docker_e2e_bare_image`/`docker_e2e_functional_image` یا تصاویر موجود مبتنی بر digest بسته دوباره استفاده می‌کند. pullهای تصویر Docker با timeout محدود ۱۸۰ ثانیه‌ای برای هر تلاش دوباره امتحان می‌شوند تا جریان گیرکرده‌ی registry/cache به‌جای مصرف بخش بزرگی از مسیر بحرانی CI، سریع دوباره امتحان شود. ### تکه‌های مسیر انتشار -پوشش Docker انتشار، کارهای کوچک‌تر و تکه‌شده را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویری را که نیاز دارد pull کند و چندین lane را از طریق همان زمان‌بند وزن‌دار اجرا کند: +پوشش Docker انتشار jobهای تکه‌تکه‌ی کوچک‌تری را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا می‌کند تا هر تکه فقط نوع تصویر موردنیاز خود را pull کند و چندین lane را از طریق همان زمان‌بند وزن‌دار اجرا کند: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime`، و `plugins-integrations` همچنان aliasهای تجمیعی Plugin/runtime باقی می‌مانند. alias مربوط به lane `install-e2e` همچنان alias تجمیعی اجرای دوباره‌ی دستی برای هر دو lane نصب‌کننده‌ی provider باقی می‌ماند. +تکه‌های فعلی Docker انتشار عبارت‌اند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime` و `plugins-integrations` همچنان aliasهای تجمعی Plugin/runtime هستند. alias مربوط به lane به نام `install-e2e` همچنان alias تجمعی اجرای دوباره‌ی دستی برای هر دو lane نصب‌کننده‌ی provider است. -OpenWebUI وقتی پوشش کامل release-path آن را درخواست کند در `plugins-runtime-services` ادغام می‌شود، و تکه‌ی مستقل `openwebui` را فقط برای dispatchهای فقط-OpenWebUI نگه می‌دارد. laneهای به‌روزرسانی کانال همراه، برای شکست‌های گذرای شبکه npm یک‌بار دوباره تلاش می‌کنند. +وقتی پوشش کامل release-path آن را درخواست کند، OpenWebUI در `plugins-runtime-services` ادغام می‌شود، و فقط برای dispatchهای مختص OpenWebUI، یک تکه‌ی مستقل `openwebui` را نگه می‌دارد. laneهای update کانال‌های همراه برای شکست‌های گذرای شبکه‌ی npm یک‌بار دوباره تلاش می‌کنند. -هر تکه `.artifacts/docker-tests/` را همراه با گزارش‌های lane، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON طرح زمان‌بند، جدول‌های laneهای کند، و فرمان‌های اجرای دوباره برای هر lane بارگذاری می‌کند. ورودی `docker_lanes` گردش‌کار، laneهای انتخاب‌شده را به‌جای کارهای تکه‌ای علیه تصویرهای آماده اجرا می‌کند؛ این کار اشکال‌زدایی lane ناموفق را به یک کار Docker هدفمند محدود می‌کند و مصنوع بسته را برای همان اجرا آماده، دانلود، یا دوباره استفاده می‌کند؛ اگر یک lane انتخاب‌شده lane زنده‌ی Docker باشد، کار هدفمند تصویر live-test را برای همان اجرای دوباره به‌صورت محلی می‌سازد. فرمان‌های اجرای دوباره‌ی GitHub تولیدشده برای هر lane، وقتی آن مقدارها وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name`، و ورودی‌های تصویر آماده هستند، تا یک lane ناموفق بتواند همان بسته و تصویرهای دقیق اجرای ناموفق را دوباره استفاده کند. +هر تکه `.artifacts/docker-tests/` را همراه با لاگ‌های lane، زمان‌بندی‌ها، `summary.json`، `failures.json`، زمان‌بندی فازها، JSON طرح زمان‌بند، جدول‌های laneهای کند، و فرمان‌های اجرای دوباره برای هر lane آپلود می‌کند. ورودی `docker_lanes` در workflow به‌جای jobهای تکه‌ای، laneهای انتخاب‌شده را روی تصاویر آماده‌شده اجرا می‌کند؛ این کار اشکال‌زدایی lane ناموفق را به یک job هدفمند Docker محدود نگه می‌دارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود یا دوباره استفاده می‌کند؛ اگر lane انتخاب‌شده یک lane زنده‌ی Docker باشد، job هدفمند تصویر live-test را برای آن اجرای دوباره به‌صورت محلی می‌سازد. فرمان‌های اجرای دوباره‌ی GitHub تولیدشده برای هر lane، وقتی آن مقادیر وجود داشته باشند، شامل `package_artifact_run_id`، `package_artifact_name` و ورودی‌های تصویر آماده هستند، تا یک lane ناموفق بتواند از همان بسته و تصاویر دقیق اجرای ناموفق دوباره استفاده کند. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -گردش‌کار زمان‌بندی‌شده‌ی live/E2E هر روز مجموعه‌ی کامل Docker مربوط به release-path را اجرا می‌کند. +Workflow زمان‌بندی‌شده‌ی live/E2E مجموعه‌ی کامل Docker مربوط به release-path را روزانه اجرا می‌کند. ## پیش‌انتشار Plugin -`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین گردش‌کاری جداگانه است که توسط `Full Release Validation` یا توسط یک اپراتور صریح dispatch می‌شود. pull requestهای عادی، pushهای `main`، و dispatchهای دستی مستقل CI این مجموعه را خاموش نگه می‌دارند. این گردش‌کار تست‌های Plugin همراه را میان هشت worker extension متوازن می‌کند؛ آن کارهای shard مربوط به extension هم‌زمان تا دو گروه پیکربندی Plugin را با یک worker Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا دسته‌های Plugin با import سنگین، کارهای CI اضافی ایجاد نکنند. مسیر پیش‌انتشار Docker فقط-انتشار، laneهای هدفمند Docker را در گروه‌های کوچک دسته‌بندی می‌کند تا از رزرو ده‌ها runner برای کارهای یک تا سه دقیقه‌ای جلوگیری شود. +`Plugin Prerelease` پوشش محصول/بسته‌ی پرهزینه‌تری است، بنابراین workflow جداگانه‌ای است که توسط `Full Release Validation` یا یک operator صریح dispatch می‌شود. pull requestهای عادی، pushهای `main` و dispatchهای دستی مستقل CI این مجموعه را خاموش نگه می‌دارند. این workflow تست‌های Plugin همراه را میان هشت worker مربوط به extension متعادل می‌کند؛ آن jobهای shard مربوط به extension تا دو گروه config Plugin را هم‌زمان با یک worker از Vitest برای هر گروه و heap بزرگ‌تر Node اجرا می‌کنند تا batchهای Plugin با import سنگین jobهای CI اضافی ایجاد نکنند. مسیر prerelease مخصوص انتشار در Docker، laneهای هدفمند Docker را در گروه‌های کوچک batch می‌کند تا برای jobهای یک تا سه دقیقه‌ای ده‌ها runner رزرو نشود. ## آزمایشگاه QA -آزمایشگاه QA laneهای اختصاصی CI خارج از گردش‌کار اصلی smart-scoped دارد. همسانی agentic زیر harnessهای گسترده‌ی QA و انتشار تو در تو قرار دارد، نه یک گردش‌کار مستقل PR. وقتی همسانی باید همراه یک اجرای اعتبارسنجی گسترده اجرا شود، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید. +آزمایشگاه QA laneهای CI اختصاصی بیرون از workflow اصلی با دامنه‌ی هوشمند دارد. برابری agentic زیر harnessهای گسترده‌ی QA و انتشار قرار دارد، نه یک workflow مستقل PR. وقتی برابری باید همراه یک اجرای اعتبارسنجی گسترده باشد، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید. -- گردش‌کار `QA-Lab - All Lanes` هر شب روی `main` و در dispatch دستی اجرا می‌شود؛ این گردش‌کار lane همسانی mock، lane زنده‌ی Matrix، و laneهای زنده‌ی Telegram و Discord را به‌عنوان کارهای موازی منشعب می‌کند. کارهای زنده از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند. +- Workflow `QA-Lab - All Lanes` هر شب روی `main` و هنگام dispatch دستی اجرا می‌شود؛ این workflow lane برابری mock، lane زنده‌ی Matrix، و laneهای زنده‌ی Telegram و Discord را به‌صورت jobهای موازی fan out می‌کند. jobهای live از محیط `qa-live-shared` استفاده می‌کنند، و Telegram/Discord از leaseهای Convex استفاده می‌کنند. -بررسی‌های انتشار، laneهای transport زنده‌ی Matrix و Telegram را با provider mock قطعی و مدل‌های mock-qualified (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد channel از تأخیر مدل زنده و راه‌اندازی عادی provider-plugin جدا شود. Gateway مربوط به transport زنده، جست‌وجوی حافظه را غیرفعال می‌کند زیرا همسانی QA رفتار حافظه را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل زنده، provider بومی، و provider در Docker پوشش داده می‌شود. +بررسی‌های انتشار، laneهای transport زنده‌ی Matrix و Telegram را با provider mock قطعی و مدل‌های دارای صلاحیت mock (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا می‌کنند تا قرارداد کانال از latency مدل live و راه‌اندازی عادی provider-plugin جدا شود. Gateway مربوط به transport زنده، جست‌وجوی memory را غیرفعال می‌کند، زیرا برابری QA رفتار memory را جداگانه پوشش می‌دهد؛ اتصال provider توسط مجموعه‌های جداگانه‌ی مدل live، provider بومی، و provider Docker پوشش داده می‌شود. -Matrix از `--profile fast` برای gateهای زمان‌بندی‌شده و انتشار استفاده می‌کند و فقط وقتی CLI checkout‌شده از آن پشتیبانی کند `--fail-fast` را اضافه می‌کند. پیش‌فرض CLI و ورودی گردش‌کار دستی همچنان `all` می‌مانند؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به کارهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep`، و `e2ee-cli` shard می‌کند. +Matrix برای gateهای زمان‌بندی‌شده و انتشار از `--profile fast` استفاده می‌کند و فقط وقتی CLI checkoutشده از آن پشتیبانی کند، `--fail-fast` را اضافه می‌کند. پیش‌فرض CLI و ورودی workflow دستی همچنان `all` است؛ dispatch دستی با `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep` و `e2ee-cli` shard می‌کند. -`OpenClaw Release Checks` همچنین laneهای حیاتی انتشار آزمایشگاه QA را پیش از تأیید انتشار اجرا می‌کند؛ gate همسانی QA آن بسته‌های نامزد و baseline را به‌عنوان کارهای lane موازی اجرا می‌کند، سپس هر دو مصنوع را در یک کار گزارش کوچک برای مقایسه‌ی نهایی همسانی دانلود می‌کند. +`OpenClaw Release Checks` همچنین laneهای حیاتی انتشارِ آزمایشگاه QA را پیش از تأیید انتشار اجرا می‌کند؛ gate برابری QA آن، بسته‌های candidate و baseline را به‌صورت jobهای lane موازی اجرا می‌کند، سپس هر دو آرتیفکت را در یک job گزارش کوچک برای مقایسه‌ی نهایی برابری دانلود می‌کند. -برای PRهای عادی، به‌جای تلقی همسانی به‌عنوان یک وضعیت الزامی، از شواهد CI/check دامنه‌مند پیروی کنید. +برای PRهای عادی، به‌جای اینکه برابری را یک status الزامی بدانید، از شواهد CI/check دامنه‌دار پیروی کنید. ## CodeQL -گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی مرحلهٔ اول و محدود است، نه پیمایش کامل مخزن. اجراهای محافظ روزانه، دستی و pull requestهای غیرپیش‌نویس، کد گردش‌کارهای Actions به‌همراه پرریسک‌ترین سطوح JavaScript/TypeScript را با پرس‌وجوهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی محدود شده‌اند اسکن می‌کنند. +گردش‌کار `CodeQL` عمداً یک اسکنر امنیتی باریک برای گذر اول است، نه پایش کامل مخزن. اجراهای روزانه، دستی، و محافظ pull requestهای غیرپیش‌نویس، کد گردش‌کار Actions به‌علاوه پرریسک‌ترین سطوح JavaScript/TypeScript را با queryهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی فیلتر شده‌اند اسکن می‌کنند. -محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود و همان ماتریس امنیتی با اطمینان بالا را مثل گردش‌کار زمان‌بندی‌شده اجرا می‌کند. CodeQL مربوط به Android و macOS خارج از پیش‌فرض‌های PR می‌مانند. +محافظ pull request سبک می‌ماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع می‌شود، و همان ماتریس امنیتی با اطمینان بالا را مثل گردش‌کار زمان‌بندی‌شده اجرا می‌کند. Android و macOS CodeQL خارج از پیش‌فرض‌های PR می‌مانند. ### دسته‌های امنیتی -| دسته | سطح | +| دسته | سطح | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، cron، و خط مبنای gateway | -| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال core به‌علاوه runtime مربوط به Plugin کانال، Gateway، Plugin SDK، secrets، نقاط تماس audit | -| `/codeql-security-high/network-ssrf-boundary` | سطوح سیاست SSRF در core، تحلیل IP، محافظ شبکه، web-fetch، و Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، کمک‌کننده‌های اجرای فرایند، تحویل خروجی، و دروازه‌های اجرای ابزار agent | -| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، بارگذاری منبع، و قرارداد بستهٔ Plugin SDK | +| `/codeql-security-high/core-auth-secrets` | Auth، secrets، sandbox، Cron، و خط مبنای Gateway | +| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته به‌همراه runtime مربوط به channel plugin، Gateway، Plugin SDK، secrets، و نقاط تماس audit | +| `/codeql-security-high/network-ssrf-boundary` | سطوح SSRF هسته، تجزیه IP، نگهبان شبکه، web-fetch، و سیاست SSRF در Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، helperهای اجرای فرایند، تحویل خروجی، و gateهای اجرای ابزار agent | +| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، بارگذاری منبع، و قرارداد package در Plugin SDK | -### شاردهای امنیتی ویژهٔ پلتفرم +### shardهای امنیتی مختص پلتفرم -- `CodeQL Android Critical Security` — شارد امنیتی زمان‌بندی‌شدهٔ Android. برنامهٔ Android را برای CodeQL به‌صورت دستی روی کوچک‌ترین رانر Blacksmith Linux پذیرفته‌شده توسط workflow sanity می‌سازد. زیر `/codeql-critical-security/android` بارگذاری می‌کند. -- `CodeQL macOS Critical Security` — شارد امنیتی هفتگی/دستی macOS. برنامهٔ macOS را برای CodeQL به‌صورت دستی روی Blacksmith macOS می‌سازد، نتایج ساخت وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده چون ساخت macOS حتی وقتی پاک است، runtime را غالب می‌کند. +- `CodeQL Android Critical Security` — shard امنیتی زمان‌بندی‌شده Android. برنامه Android را برای CodeQL روی کوچک‌ترین runner لینوکسی Blacksmith که sanity گردش‌کار می‌پذیرد به‌صورت دستی build می‌کند. خروجی را زیر `/codeql-critical-security/android` بارگذاری می‌کند. +- `CodeQL macOS Critical Security` — shard امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL روی Blacksmith macOS به‌صورت دستی build می‌کند، نتایج build وابستگی‌ها را از SARIF بارگذاری‌شده فیلتر می‌کند، و خروجی را زیر `/codeql-critical-security/macos` بارگذاری می‌کند. خارج از پیش‌فرض‌های روزانه نگه داشته شده، چون build macOS حتی در حالت تمیز هم بر زمان اجرا غالب است. ### دسته‌های کیفیت بحرانی -`CodeQL Critical Quality` شارد غیرامنیتی متناظر است. فقط پرس‌وجوهای کیفیت JavaScript/TypeScript با شدت خطا و غیرامنیتی را روی سطوح محدود و باارزش بالا روی رانر کوچک‌تر Blacksmith Linux اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از پروفایل زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط شاردهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای تغییرات کد اجرای command/model/tool و dispatch پاسخ agent، کد schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، runtime کانال core و Plugin کانال بسته‌بندی‌شده، protocol/server-method مربوط به Gateway، runtime/SDK glue مربوط به memory، MCP/process/outbound delivery، runtime/catalog مدل provider، session diagnostics/delivery queues، loader مربوط به Plugin، قرارداد Plugin SDK/package، یا runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات پیکربندی CodeQL و گردش‌کار کیفیت، هر دوازده شارد کیفیت PR را اجرا می‌کنند. +`CodeQL Critical Quality` shard غیرامنیتی متناظر است. فقط queryهای کیفیت JavaScript/TypeScript غیرامنیتی با شدت خطا را روی سطوح باریک و باارزش بالا، روی runner لینوکسی کوچک‌تر Blacksmith اجرا می‌کند. محافظ pull request آن عمداً کوچک‌تر از پروفایل زمان‌بندی‌شده است: PRهای غیرپیش‌نویس فقط shardهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای کد اجرای فرمان/مدل/ابزار agent و dispatch پاسخ، schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، هسته کانال و runtime مربوط به channel plugin بسته‌بندی‌شده، پروتکل Gateway/server-method، چسب runtime/SDK حافظه، MCP/process/تحویل خروجی، runtime/provider catalog مدل، diagnostics جلسه/صف‌های تحویل، loader Plugin، قرارداد Plugin SDK/package، یا تغییرات runtime پاسخ Plugin SDK اجرا می‌کنند. تغییرات CodeQL config و گردش‌کار کیفیت هر دوازده shard کیفیت PR را اجرا می‌کنند. dispatch دستی می‌پذیرد: @@ -422,40 +415,40 @@ dispatch دستی می‌پذیرد: profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -پروفایل‌های محدود، قلاب‌های آموزش/تکرار برای اجرای یک شارد کیفیت به‌صورت جداگانه هستند. +پروفایل‌های باریک hookهای آموزش/تکرار برای اجرای یک shard کیفیت به‌صورت جداگانه هستند. | دسته | سطح | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، cron، و gateway | -| `/codeql-critical-quality/config-boundary` | قراردادهای schema، migration، normalization، و IO پیکربندی | -| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای protocol مربوط به Gateway و قراردادهای server method | -| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال core و Plugin کانال بسته‌بندی‌شده | -| `/codeql-critical-quality/agent-runtime-boundary` | اجرای command، dispatch مربوط به model/provider، dispatch و queueهای auto-reply، و قراردادهای runtime صفحهٔ کنترل ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، کمک‌کننده‌های نظارت بر فرایند، و قراردادهای تحویل خروجی | -| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK، facadeهای runtime حافظه، aliasهای Plugin SDK حافظه، glue فعال‌سازی runtime حافظه، و commandهای doctor حافظه | -| `/codeql-critical-quality/session-diagnostics-boundary` | اجزای داخلی reply queue، queueهای تحویل session، کمک‌کننده‌های binding/delivery نشست خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، کمک‌کننده‌های reply payload/chunking/runtime، گزینه‌های پاسخ کانال، queueهای تحویل، و کمک‌کننده‌های binding نشست/thread | -| `/codeql-critical-quality/provider-runtime-boundary` | normalization کاتالوگ مدل، auth و discovery مربوط به provider، ثبت runtime مربوط به provider، defaults/catalogs مربوط به provider، و registryهای web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | راه‌اندازی Control UI، persistence محلی، جریان‌های کنترل Gateway، و قراردادهای runtime صفحهٔ کنترل task | -| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب core، IO رسانه، فهم رسانه، تولید تصویر، و تولید رسانه | -| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع منتشرشدهٔ Plugin SDK در سمت بسته و کمک‌کننده‌های قرارداد بستهٔ Plugin | +| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی Auth، secrets، sandbox، Cron، و Gateway | +| `/codeql-critical-quality/config-boundary` | قراردادهای schema پیکربندی، migration، نرمال‌سازی، و IO | +| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای پروتکل Gateway و قراردادهای server method | +| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیاده‌سازی کانال هسته و channel pluginهای بسته‌بندی‌شده | +| `/codeql-critical-quality/agent-runtime-boundary` | اجرای فرمان، dispatch مدل/provider، dispatch و صف‌های auto-reply، و قراردادهای runtime صفحه کنترل ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پل‌های ابزار، helperهای نظارت بر فرایند، و قراردادهای تحویل خروجی | +| `/codeql-critical-quality/memory-runtime-boundary` | SDK میزبان حافظه، facadeهای runtime حافظه، aliasهای Plugin SDK حافظه، چسب فعال‌سازی runtime حافظه، و فرمان‌های doctor حافظه | +| `/codeql-critical-quality/session-diagnostics-boundary` | بخش‌های داخلی صف پاسخ، صف‌های تحویل جلسه، helperهای اتصال/تحویل جلسه خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، helperهای payload/chunking/runtime پاسخ، گزینه‌های پاسخ کانال، صف‌های تحویل، و helperهای اتصال session/thread | +| `/codeql-critical-quality/provider-runtime-boundary` | نرمال‌سازی catalog مدل، auth و discovery provider، ثبت runtime provider، پیش‌فرض‌ها/catalogهای provider، و registryهای web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | راه‌اندازی Control UI، persistence محلی، جریان‌های کنترل Gateway، و قراردادهای runtime صفحه کنترل task | +| `/codeql-critical-quality/web-media-runtime-boundary` | قراردادهای runtime مربوط به fetch/search وب هسته، media IO، درک رسانه، تولید تصویر، و تولید رسانه | +| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع Plugin SDK سمت package منتشرشده و helperهای قرارداد package مربوط به plugin | -کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون مبهم‌کردن سیگنال امنیتی زمان‌بندی، اندازه‌گیری، غیرفعال یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و Pluginهای بسته‌بندی‌شده فقط پس از پایدار شدن runtime و سیگنال پروفایل‌های محدود باید دوباره به‌عنوان کار پیگیری scoped یا sharded اضافه شود. +کیفیت از امنیت جدا می‌ماند تا یافته‌های کیفیت بتوانند بدون پنهان‌کردن سیگنال امنیتی زمان‌بندی، اندازه‌گیری، غیرفعال، یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و pluginهای بسته‌بندی‌شده باید فقط پس از پایدار شدن runtime و سیگنال پروفایل‌های باریک، به‌صورت کار پیگیری scopeشده یا shardشده دوباره اضافه شود. -## گردش‌کارهای نگهداشت +## گردش‌کارهای نگهداری -### Docs Agent +### عامل مستندات -گردش‌کار `Docs Agent` یک مسیر نگهداشت Codex رویدادمحور برای همسو نگه‌داشتن اسناد موجود با تغییرات اخیراً land شده است. زمان‌بندی خالص ندارد: یک اجرای CI موفق از push غیرربات روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. فراخوانی‌های workflow-run وقتی `main` جلو رفته باشد یا وقتی اجرای Docs Agent غیر skip شدهٔ دیگری در یک ساعت گذشته ساخته شده باشد، skip می‌شوند. وقتی اجرا می‌شود، بازهٔ commit را از SHA منبع قبلیِ Docs Agent غیر skip شده تا `main` فعلی بررسی می‌کند، بنابراین یک اجرای ساعتی می‌تواند همهٔ تغییرات main انباشته‌شده از آخرین گذر اسناد را پوشش دهد. +گردش‌کار `Docs Agent` یک مسیر نگهداری event-driven با Codex برای هم‌راستا نگه‌داشتن مستندات موجود با تغییراتی است که اخیراً landing شده‌اند. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، و dispatch دستی می‌تواند مستقیماً آن را اجرا کند. invocationهای workflow-run وقتی `main` جلو رفته باشد یا وقتی اجرای غیر skipشده دیگری از Docs Agent در ساعت گذشته ایجاد شده باشد skip می‌شوند. وقتی اجرا می‌شود، بازه commit از source SHA مربوط به Docs Agent غیر skipشده قبلی تا `main` فعلی را review می‌کند، بنابراین یک اجرای ساعتی می‌تواند همه تغییرات main انباشته‌شده از آخرین گذر مستندات را پوشش دهد. -### Test Performance Agent +### عامل عملکرد تست -گردش‌کار `Test Performance Agent` یک مسیر نگهداشت Codex رویدادمحور برای تست‌های کند است. زمان‌بندی خالص ندارد: یک اجرای CI موفق از push غیرربات روی `main` می‌تواند آن را trigger کند، اما اگر فراخوانی workflow-run دیگری در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی این دروازهٔ فعالیت روزانه را دور می‌زند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شدهٔ مجموعهٔ کامل می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست که coverage را حفظ می‌کنند انجام دهد، نه refactorهای گسترده، سپس گزارش مجموعهٔ کامل را دوباره اجرا می‌کند و تغییراتی را که تعداد تست‌های پاس‌شدهٔ baseline را کاهش دهند رد می‌کند. اگر baseline تست‌های شکست‌خورده داشته باشد، Codex فقط می‌تواند شکست‌های آشکار را اصلاح کند و گزارش مجموعهٔ کامل پس از agent باید قبل از commit شدن هر چیزی پاس شود. وقتی `main` پیش از land شدن bot push جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای کهنهٔ دارای conflict skip می‌شوند. از Ubuntu میزبانی‌شده توسط GitHub استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل docs agent حفظ کند. +گردش‌کار `Test Performance Agent` یک مسیر نگهداری event-driven با Codex برای تست‌های کند است. برنامه زمان‌بندی خالص ندارد: یک اجرای موفق CI مربوط به push غیررباتی روی `main` می‌تواند آن را trigger کند، اما اگر invocation دیگری از workflow-run در همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد، skip می‌شود. dispatch دستی آن gate فعالیت روزانه را دور می‌زند. این مسیر یک گزارش عملکرد Vitest گروه‌بندی‌شده برای کل suite می‌سازد، به Codex اجازه می‌دهد فقط اصلاحات کوچک عملکرد تست با حفظ پوشش انجام دهد نه refactorهای گسترده، سپس گزارش کل suite را دوباره اجرا می‌کند و تغییراتی را که تعداد baseline تست‌های موفق را کاهش دهند رد می‌کند. اگر baseline تست‌های ناموفق داشته باشد، Codex فقط می‌تواند failureهای بدیهی را اصلاح کند و گزارش کل suite پس از agent باید پیش از هر commit موفق شود. وقتی `main` پیش از landing شدن push ربات جلو می‌رود، این مسیر patch اعتبارسنجی‌شده را rebase می‌کند، `pnpm check:changed` را دوباره اجرا می‌کند، و push را retry می‌کند؛ patchهای stale دارای conflict skip می‌شوند. از GitHub-hosted Ubuntu استفاده می‌کند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مثل عامل مستندات حفظ کند. -### PRهای تکراری پس از Merge +### PRهای تکراری پس از ادغام -گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی تکراری‌ها پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر GitHub، بررسی می‌کند که PR land شده merge شده باشد و هر تکراری یا issue ارجاع‌شدهٔ مشترک داشته باشد یا hunkهای تغییر یافتهٔ همپوشان. +گردش‌کار `Duplicate PRs After Merge` یک گردش‌کار دستی maintainer برای پاک‌سازی duplicate پس از land است. پیش‌فرض آن dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرست‌شده را می‌بندد. پیش از تغییر دادن GitHub، تأیید می‌کند که PR landشده merge شده و هر duplicate یا issue ارجاع‌شده مشترک دارد یا hunkهای تغییر یافته هم‌پوشان دارد. ```bash gh workflow run duplicate-after-merge.yml \ @@ -464,38 +457,115 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## دروازه‌های بررسی محلی و مسیریابی تغییرات +## gateهای check محلی و مسیریابی تغییرات -منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن دروازهٔ بررسی محلی نسبت به دامنهٔ پلتفرم CI گسترده، دربارهٔ مرزهای معماری سخت‌گیرتر است: +منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا می‌شود. آن gate check محلی نسبت به scope گسترده پلتفرم CI درباره مرزهای معماری سخت‌گیرتر است: -- تغییرات production مربوط به core، typecheck تولید core و تست core به‌علاوه lint/guardهای core را اجرا می‌کنند؛ -- تغییرات فقط تست مربوط به core، فقط typecheck تست core به‌علاوه lint core را اجرا می‌کنند؛ -- تغییرات production مربوط به extension، typecheck تولید extension و تست extension به‌علاوه lint extension را اجرا می‌کنند؛ -- تغییرات فقط تست مربوط به extension، typecheck تست extension به‌علاوه lint extension را اجرا می‌کنند؛ -- تغییرات public Plugin SDK یا plugin-contract به typecheck مربوط به extension گسترش می‌یابند چون extensionها به آن قراردادهای core وابسته‌اند (پیمایش‌های extension با Vitest کار تست صریح می‌مانند)؛ -- افزایش نسخه‌های فقط metadata انتشار، بررسی‌های هدفمند version/config/root-dependency را اجرا می‌کنند؛ -- تغییرات ناشناختهٔ root/config برای fail-safe به همهٔ مسیرهای بررسی می‌روند. +- تغییرات production هسته، typecheck مربوط به core prod و core test به‌علاوه lint/guardهای هسته را اجرا می‌کنند؛ +- تغییرات فقط-test هسته، فقط typecheck مربوط به core test به‌علاوه lint هسته را اجرا می‌کنند؛ +- تغییرات production extension، typecheck مربوط به extension prod و extension test به‌علاوه lint extension را اجرا می‌کنند؛ +- تغییرات فقط-test extension، typecheck مربوط به extension test به‌علاوه lint extension را اجرا می‌کنند؛ +- تغییرات Plugin SDK عمومی یا قرارداد plugin به typecheck extension گسترش می‌یابند، چون extensionها به آن قراردادهای هسته وابسته‌اند (پایش‌های Vitest extension همچنان کار تست صریح می‌مانند)؛ +- افزایش نسخه‌های فقط metadata انتشار، checkهای هدفمند version/config/root-dependency را اجرا می‌کنند؛ +- تغییرات ناشناخته root/config برای fail-safe به همه check laneها می‌روند. -مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش‌های مستقیم تست خودشان را اجرا می‌کنند، ویرایش‌های منبع ابتدا mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و وابستگان import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی پاسخ قابل‌مشاهدهٔ گروه، حالت تحویل پاسخ منبع، یا مسیر message-tool system prompt از تست‌های پاسخ core به‌علاوه regressionهای تحویل Discord و Slack عبور می‌کنند تا تغییر پیش‌فرض مشترک پیش از اولین push مربوط به PR شکست بخورد. فقط وقتی تغییر آن‌قدر harness-wide است که مجموعهٔ mapped ارزان proxy قابل‌اعتمادی نیست، از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. +مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً ارزان‌تر از `check:changed` است: ویرایش مستقیم تست‌ها خودشان را اجرا می‌کنند، ویرایش‌های source ابتدا mappingهای صریح را ترجیح می‌دهند، سپس تست‌های sibling و وابستگان import-graph را. پیکربندی تحویل shared group-room یکی از mappingهای صریح است: تغییرات در پیکربندی visible-reply گروه، حالت تحویل پاسخ source، یا system prompt ابزار پیام، از طریق تست‌های پاسخ هسته به‌علاوه regressionهای تحویل Discord و Slack مسیر داده می‌شوند تا تغییر پیش‌فرض مشترک پیش از اولین push PR شکست بخورد. فقط وقتی از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید که تغییر آن‌قدر harness-wide باشد که مجموعه mapped ارزان نماینده قابل اعتمادی نباشد. ## اعتبارسنجی Testbox -Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات گسترده، یک باکس تازه و از پیش گرم‌شده را ترجیح دهید. پیش از صرف کردن یک گیت کند روی باکسی که دوباره استفاده شده، منقضی شده، یا همین حالا همگام‌سازی غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل باکس اجرا کنید. +Testbox را از ریشهٔ مخزن اجرا کنید و برای اثبات‌های گسترده، یک جعبهٔ تازه گرم‌شده را ترجیح دهید. پیش از صرف‌کردن یک گیت کند روی جعبه‌ای که دوباره استفاده شده، منقضی شده، یا همین حالا همگام‌سازیِ غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل جعبه اجرا کنید. -بررسی سلامت وقتی فایل‌های ریشهٔ لازم مانند `pnpm-lock.yaml` ناپدید شده باشند، یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ رهگیری‌شده را نشان دهد، سریع شکست می‌خورد. این معمولا یعنی وضعیت همگام‌سازی ریموت یک کپی قابل اعتماد از PR نیست؛ آن باکس را متوقف کنید و به‌جای اشکال‌زدایی شکست تست محصول، یک باکس تازه را گرم کنید. برای PRهایی که حذف‌های بزرگ عمدی دارند، برای آن اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید. +بررسی سلامت وقتی فایل‌های ضروری ریشه مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دست‌کم ۲۰۰ حذفِ ردیابی‌شده نشان دهد، سریع شکست می‌خورد. این معمولاً یعنی وضعیت همگام‌سازی راه‌دور، کپی قابل اعتمادی از PR نیست؛ به‌جای اشکال‌زدایی شکست آزمون محصول، آن جعبه را متوقف کنید و یک جعبهٔ تازه گرم کنید. برای PRهای بزرگ‌حذفِ عمدی، برای همان اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید. -`pnpm testbox:run` همچنین یک فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در مرحلهٔ همگام‌سازی بماند، پایان می‌دهد. برای غیرفعال کردن این محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمول بزرگ از یک مقدار بزرگ‌تر بر حسب میلی‌ثانیه استفاده کنید. +`pnpm testbox:run` همچنین فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگام‌سازی در مرحلهٔ همگام‌سازی می‌ماند، پایان می‌دهد. برای غیرفعال‌کردن آن محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای diffهای محلی غیرمعمولاً بزرگ، مقدار میلی‌ثانیه‌ای بزرگ‌تری به کار ببرید. -Crabbox مسیر دومِ باکس ریموتِ متعلق به مخزن برای اثبات Linux است، وقتی Blacksmith در دسترس نیست یا وقتی ظرفیت ابریِ تحت مالکیت ترجیح داده می‌شود. یک باکس را گرم کنید، آن را از طریق گردش‌کار پروژه آماده کنید، سپس دستورها را از طریق Crabbox CLI اجرا کنید: +Crabbox پوشش جعبهٔ راه‌دورِ متعلق به مخزن برای اثبات لینوکس نگه‌دارندگان است. وقتی یک بررسی برای حلقهٔ ویرایش محلی بیش از حد گسترده است، وقتی هم‌ارزی CI مهم است، یا وقتی اثبات به secrets، Docker، مسیرهای بسته، جعبه‌های قابل استفادهٔ مجدد، یا گزارش‌های راه‌دور نیاز دارد، از آن استفاده کنید. backend عادی OpenClaw برابر `blacksmith-testbox` است؛ ظرفیت AWS/Hetzner تحت مالکیت، پشتیبانِ قطعی‌های Blacksmith، مشکلات سهمیه، یا آزمون صریح ظرفیت تحت مالکیت است. + +پیش از نخستین اجرا، پوشش را از ریشهٔ مخزن بررسی کنید: ```bash -pnpm crabbox:warmup -- --idle-timeout 90m -pnpm crabbox:hydrate -- --id -pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed" -pnpm crabbox:stop -- +pnpm crabbox:run -- --help | sed -n '1,120p' ``` -`.crabbox.yaml` مالک پیش‌فرض‌های ارائه‌دهنده، همگام‌سازی، و آماده‌سازی GitHub Actions است. این فایل `.git` محلی را مستثنا می‌کند تا checkout آماده‌شدهٔ Actions به‌جای همگام‌سازی ریموت‌ها و انبارهای آبجکت محلیِ نگه‌دارنده، فرادادهٔ Git ریموت خودش را حفظ کند، و آرتیفکت‌های محلی runtime/build را که هرگز نباید منتقل شوند مستثنا می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانه‌ای است که دستورهای بعدی `crabbox run --id ` از آن source می‌کنند. +پوشش مخزن، دودویی Crabbox کهنه‌ای را که `blacksmith-testbox` را اعلام نمی‌کند رد می‌کند. با اینکه `.crabbox.yaml` پیش‌فرض‌های ابرِ تحت مالکیت دارد، ارائه‌دهنده را صریحاً پاس دهید. + +گیت تغییرات: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +``` + +اجرای دوبارهٔ آزمون متمرکز: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test " +``` + +مجموعهٔ کامل: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox \ + --blacksmith-org openclaw \ + --blacksmith-workflow .github/workflows/ci-check-testbox.yml \ + --blacksmith-job check \ + --blacksmith-ref main \ + --idle-timeout 90m \ + --ttl 240m \ + --timing-json \ + --shell -- \ + "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" +``` + +خلاصهٔ نهایی JSON را بخوانید. فیلدهای مفید `provider`، `leaseId`، `syncDelegated`، `exitCode`، `commandMs` و `totalMs` هستند. اجراهای یک‌بارهٔ Crabbox با پشتوانهٔ Blacksmith باید Testbox را به‌طور خودکار متوقف کنند؛ اگر اجرا قطع شد یا پاک‌سازی نامشخص بود، جعبه‌های زنده را بررسی کنید و فقط جعبه‌هایی را که خودتان ساخته‌اید متوقف کنید: + +```bash +blacksmith testbox list +blacksmith testbox stop --id +``` + +فقط وقتی استفادهٔ مجدد را به کار ببرید که عمداً به چند فرمان روی همان جعبهٔ آماده‌شده نیاز دارید: + +```bash +pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " +pnpm crabbox:stop -- +``` + +اگر لایهٔ خراب Crabbox است اما خود Blacksmith کار می‌کند، از Blacksmith مستقیم به‌عنوان پشتیبان محدود استفاده کنید: + +```bash +blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 +blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +blacksmith testbox stop --id +``` + +فقط وقتی به ظرفیت Crabbox تحت مالکیت ارتقا دهید که Blacksmith از کار افتاده، با محدودیت سهمیه روبه‌رو است، محیط لازم را ندارد، یا ظرفیت تحت مالکیت صراحتاً هدف است: + +```bash +pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m +pnpm crabbox:hydrate -- --id +pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" +pnpm crabbox:stop -- +``` + +`.crabbox.yaml` مالک پیش‌فرض‌های ارائه‌دهنده، همگام‌سازی، و آماده‌سازی GitHub Actions برای مسیرهای ابرِ تحت مالکیت است. این فایل `.git` محلی را مستثنی می‌کند تا checkout آماده‌شدهٔ Actions فرادادهٔ Git راه‌دور خودش را نگه دارد، نه اینکه remoteهای محلی نگه‌دارنده و انباره‌های object را همگام کند؛ همچنین artifactهای runtime/build محلی را که هرگز نباید منتقل شوند مستثنی می‌کند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راه‌اندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانه برای فرمان‌های ابرِ تحت مالکیت `crabbox run --id ` است. ## مرتبط diff --git a/docs/fa/cli/plugins.md b/docs/fa/cli/plugins.md index 9397501f0..cf222452a 100644 --- a/docs/fa/cli/plugins.md +++ b/docs/fa/cli/plugins.md @@ -1,20 +1,20 @@ --- read_when: - - می‌خواهید Pluginهای Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید + - می‌خواهید Plugin‌های Gateway یا بسته‌های سازگار را نصب یا مدیریت کنید - می‌خواهید خطاهای بارگذاری Plugin را اشکال‌زدایی کنید sidebarTitle: Plugins summary: مرجع CLI برای `openclaw plugins` (list، install، marketplace، uninstall، enable/disable، doctor) -title: Plugin‌ها +title: Pluginها x-i18n: - generated_at: "2026-05-03T21:28:58Z" + generated_at: "2026-05-04T07:03:00Z" model: gpt-5.5 provider: openai - source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c + source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776 source_path: cli/plugins.md workflow: 16 --- -مدیریت Pluginهای Gateway، بسته‌های hook و باندل‌های سازگار. +Pluginهای Gateway، بسته‌های hook و bundleهای سازگار را مدیریت کنید. @@ -23,14 +23,14 @@ x-i18n: نمونه‌های سریع برای نصب، فهرست‌کردن، به‌روزرسانی، حذف نصب و انتشار. - - مدل سازگاری باندل. + + مدل سازگاری bundle. فیلدهای مانیفست و شِمای پیکربندی. - سخت‌سازی امنیتی برای نصب Pluginها. + مقاوم‌سازی امنیتی برای نصب Pluginها. @@ -62,14 +62,14 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -برای بررسی نصب، inspect، حذف نصب یا تازه‌سازی رجیستری که کند است، فرمان را با `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل تجزیه نگه می‌دارد. [عیب‌یابی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید. +برای بررسی نصب، inspect، حذف نصب یا تازه‌سازی registry که کند است، فرمان را با `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` اجرا کنید. trace زمان‌بندی فازها را در stderr می‌نویسد و خروجی JSON را قابل parse نگه می‌دارد. [اشکال‌زدایی](/fa/help/debugging#plugin-lifecycle-trace) را ببینید. -Pluginهای همراه با OpenClaw همراه محصول ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال هستند (برای مثال ارائه‌دهندگان مدل همراه، ارائه‌دهندگان گفتار همراه، و Plugin مرورگر همراه)؛ بقیه به `plugins enable` نیاز دارند. +Pluginهای bundled همراه OpenClaw ارائه می‌شوند. برخی به‌صورت پیش‌فرض فعال هستند (برای مثال providerهای مدل bundled، providerهای گفتار bundled و Plugin مرورگر bundled)؛ بقیه به `plugins enable` نیاز دارند. -Pluginهای بومی OpenClaw باید `openclaw.plugin.json` را همراه یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. باندل‌های سازگار به‌جای آن از مانیفست‌های باندل خودشان استفاده می‌کنند. +Pluginهای native OpenClaw باید `openclaw.plugin.json` را با یک JSON Schema درون‌خطی (`configSchema`، حتی اگر خالی باشد) ارائه کنند. bundleهای سازگار به‌جای آن از مانیفست‌های bundle خودشان استفاده می‌کنند. -`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی مفصل list/info همچنین زیرنوع باندل (`codex`، `claude` یا `cursor`) به‌علاوه قابلیت‌های شناسایی‌شده باندل را نشان می‌دهد. +`plugins list` مقدار `Format: openclaw` یا `Format: bundle` را نشان می‌دهد. خروجی verbose فهرست/اطلاعات همچنین زیرگونه bundle (`codex`، `claude` یا `cursor`) به‌همراه قابلیت‌های bundle شناسایی‌شده را نشان می‌دهد. ### نصب @@ -91,100 +91,100 @@ openclaw plugins install --marketplace https://github.com// -در دوره گذار راه‌اندازی، نام‌های ساده بسته به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:` استفاده کنید. نصب Plugin را مانند اجرای کد در نظر بگیرید. نسخه‌های پین‌شده را ترجیح دهید. +نام‌های ساده package در دوره جابه‌جایی launch به‌صورت پیش‌فرض از npm نصب می‌شوند. برای ClawHub از `clawhub:` استفاده کنید. نصب Plugin را مثل اجرای کد در نظر بگیرید. نسخه‌های pinned را ترجیح دهید. -`plugins search` برای بسته‌های Plugin قابل نصب، ClawHub را جست‌وجو می‌کند و نام بسته‌های آماده نصب را چاپ می‌کند. این فرمان بسته‌های code-plugin و bundle-plugin را جست‌وجو می‌کند، نه Skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید. +`plugins search` برای packageهای Plugin قابل نصب از ClawHub پرس‌وجو می‌کند و نام‌های package آماده نصب را چاپ می‌کند. این فرمان packageهای code-plugin و bundle-plugin را جست‌وجو می‌کند، نه skills را. برای Skills در ClawHub از `openclaw skills search` استفاده کنید. -ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. Npm همچنان یک مسیر fallback پشتیبانی‌شده و مسیر نصب مستقیم است. بسته‌های Plugin متعلق به OpenClaw با الگوی `@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا [فهرست موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. نصب‌ها و به‌روزرسانی‌های کانال beta، وقتی npm dist-tag با نام `beta` در دسترس باشد آن را ترجیح می‌دهند و سپس به `latest` برمی‌گردند. +ClawHub سطح اصلی توزیع و کشف برای بیشتر Pluginها است. npm همچنان یک fallback پشتیبانی‌شده و مسیر نصب مستقیم باقی می‌ماند. packageهای Plugin متعلق به OpenClaw با الگوی `@openclaw/*` دوباره روی npm منتشر می‌شوند؛ فهرست فعلی را در [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) یا [موجودی Plugin](/fa/plugins/plugin-inventory) ببینید. نصب‌های پایدار از `latest` استفاده می‌کنند. نصب‌ها و به‌روزرسانی‌های کانال beta وقتی tag در دسترس باشد، dist-tag مربوط به `beta` در npm را ترجیح می‌دهند و سپس به `latest` fallback می‌کنند. - - اگر بخش `plugins` شما با یک `$include` تک‌فایلی پشتیبانی می‌شود، `plugins install/update/enable/disable/uninstall` تغییرات را در همان فایل includeشده می‌نویسد و `openclaw.json` را دست‌نخورده می‌گذارد. includeهای ریشه، آرایه‌های include و includeهایی با overrideهای هم‌سطح، به‌جای تخت‌سازی با حالت fail closed متوقف می‌شوند. برای شکل‌های پشتیبانی‌شده [includeهای پیکربندی](/fa/gateway/configuration) را ببینید. + + اگر بخش `plugins` شما با یک `$include` تک‌فایلی پشتیبانی می‌شود، `plugins install/update/enable/disable/uninstall` در همان فایل includeشده می‌نویسد و `openclaw.json` را دست‌نخورده باقی می‌گذارد. includeهای ریشه، آرایه‌های include و includeهایی با overrideهای هم‌سطح به‌جای flatten شدن، fail closed می‌شوند. برای شکل‌های پشتیبانی‌شده، [Config includes](/fa/gateway/configuration) را ببینید. - اگر پیکربندی هنگام نصب نامعتبر باشد، `plugins install` معمولاً با حالت fail closed متوقف می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و بارگذاری مجدد داغ، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگری با حالت fail closed متوقف می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستند در زمان نصب، مسیر بازیابی محدودی برای Pluginهای همراه است که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را فعال کرده‌اند. + اگر پیکربندی هنگام نصب نامعتبر باشد، `plugins install` معمولاً fail closed می‌شود و به شما می‌گوید ابتدا `openclaw doctor --fix` را اجرا کنید. هنگام راه‌اندازی Gateway و hot reload، پیکربندی نامعتبر Plugin مانند هر پیکربندی نامعتبر دیگر fail closed می‌شود؛ `openclaw doctor --fix` می‌تواند ورودی نامعتبر Plugin را قرنطینه کند. تنها استثنای مستندشده در زمان نصب، یک مسیر بازیابی محدود برای Pluginهای bundled است که صراحتاً `openclaw.install.allowInvalidConfigRecovery` را opt in می‌کنند. - `--force` هدف نصب موجود را دوباره استفاده می‌کند و Plugin یا بسته hook نصب‌شده قبلی را در همان‌جا بازنویسی می‌کند. وقتی عمداً همان شناسه را از یک مسیر محلی جدید، آرشیو، بسته ClawHub یا artifact مربوط به npm دوباره نصب می‌کنید، از آن استفاده کنید. برای ارتقاهای معمول یک Plugin مربوط به npm که از قبل ردیابی شده است، `openclaw plugins update ` را ترجیح دهید. + `--force` از مقصد نصب موجود دوباره استفاده می‌کند و یک Plugin یا hook pack ازپیش‌نصب‌شده را درجا بازنویسی می‌کند. وقتی عمداً همان id را از یک مسیر محلی جدید، archive، package از ClawHub یا artifact از npm دوباره نصب می‌کنید از آن استفاده کنید. برای ارتقاهای معمول یک Plugin از npm که از قبل دنبال می‌شود، `openclaw plugins update ` را ترجیح دهید. - اگر `plugins install` را برای شناسه Pluginای اجرا کنید که از قبل نصب شده است، OpenClaw متوقف می‌شود و برای ارتقای عادی شما را به `plugins update `، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید به `plugins install --force` ارجاع می‌دهد. + اگر `plugins install` را برای id یک Plugin که از قبل نصب شده اجرا کنید، OpenClaw متوقف می‌شود و برای ارتقای معمول شما را به `plugins update ` ارجاع می‌دهد، یا وقتی واقعاً می‌خواهید نصب فعلی را از منبعی متفاوت بازنویسی کنید، به `plugins install --force` ارجاع می‌دهد. - `--pin` فقط برای نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع پین‌شده می‌خواهید، از یک git ref صریح مانند `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای npm spec فراداده منبع marketplace را نگه می‌دارند. + `--pin` فقط برای نصب‌های npm اعمال می‌شود. با نصب‌های `git:` پشتیبانی نمی‌شود؛ وقتی منبع pinned می‌خواهید، از یک git ref صریح مثل `git:github.com/acme/plugin@v1.2.3` استفاده کنید. با `--marketplace` پشتیبانی نمی‌شود، چون نصب‌های marketplace به‌جای spec از npm، metadata منبع marketplace را پایدار می‌کنند. - `--dangerously-force-unsafe-install` گزینه‌ای اضطراری برای مثبت‌های کاذب در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه یابد، اما مسدودسازی‌های سیاست hook مربوط به `before_install` در Plugin را دور نمی‌زند و شکست‌های اسکن را نیز دور نمی‌زند. + `--dangerously-force-unsafe-install` یک گزینه break-glass برای مثبت‌های کاذب در اسکنر داخلی کد خطرناک است. این گزینه اجازه می‌دهد نصب حتی وقتی اسکنر داخلی یافته‌های `critical` گزارش می‌کند ادامه پیدا کند، اما blockهای policy مربوط به hook `before_install` در Plugin را دور نمی‌زند و خطاهای scan را هم دور نمی‌زند. - این پرچم CLI برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skill مبتنی بر Gateway از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کنند، در حالی که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skill از ClawHub است. + این پرچم CLI برای جریان‌های نصب/به‌روزرسانی Plugin اعمال می‌شود. نصب‌های وابستگی Skills که از Gateway پشتیبانی می‌شوند از override درخواست متناظر `dangerouslyForceUnsafeInstall` استفاده می‌کنند، در حالی که `openclaw skills install` همچنان یک جریان جداگانه دانلود/نصب Skills از ClawHub باقی می‌ماند. - اگر Pluginای که در ClawHub منتشر کرده‌اید توسط اسکن رجیستری مسدود شده است، از مراحل ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید. + اگر Pluginی که روی ClawHub منتشر کرده‌اید با scan registry مسدود شده است، از گام‌های ناشر در [ClawHub](/fa/tools/clawhub) استفاده کنید. - - `plugins install` همچنین سطح نصب برای بسته‌های hook است که `openclaw.hooks` را در `package.json` ارائه می‌کنند. برای دیدپذیری فیلترشده hook و فعال‌سازی تک‌به‌تک hookها از `openclaw hooks` استفاده کنید، نه برای نصب بسته. + + `plugins install` همچنین سطح نصب برای hook packهایی است که `openclaw.hooks` را در `package.json` عرضه می‌کنند. برای دید محدودشده hook و فعال‌سازی هر hook از `openclaw hooks` استفاده کنید، نه برای نصب package. - specهای npm **فقط رجیستری** هستند (نام بسته + **نسخه دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و بازه‌های semver رد می‌شوند. نصب‌های وابستگی برای ایمنی، حتی وقتی shell شما تنظیمات نصب سراسری npm دارد، به‌صورت project-local با `--ignore-scripts` اجرا می‌شوند. + specهای npm **فقط registry** هستند (نام package + **نسخه دقیق** اختیاری یا **dist-tag** اختیاری). specهای Git/URL/file و rangeهای semver رد می‌شوند. نصب‌های dependency برای ایمنی، حتی وقتی shell شما تنظیمات global نصب npm دارد، به‌صورت project-local با `--ignore-scripts` اجرا می‌شوند. - وقتی می‌خواهید حل‌وفصل npm را صریح کنید، از `npm:` استفاده کنید. در دوره گذار راه‌اندازی، specهای ساده بسته نیز مستقیماً از npm نصب می‌شوند. + وقتی می‌خواهید resolution مربوط به npm را صریح کنید، از `npm:` استفاده کنید. specهای ساده package نیز در دوره جابه‌جایی launch مستقیماً از npm نصب می‌شوند. - specهای ساده و `@latest` روی مسیر پایدار می‌مانند. اگر npm هرکدام از آن‌ها را به یک prerelease حل کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک برچسب prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صریحاً opt in کنید. + specهای ساده و `@latest` روی track پایدار باقی می‌مانند. نسخه‌های اصلاحی date-stamped مربوط به OpenClaw مانند `2026.5.3-1` برای این check، releaseهای پایدار هستند. اگر npm هرکدام از این‌ها را به prerelease resolve کند، OpenClaw متوقف می‌شود و از شما می‌خواهد با یک tag prerelease مانند `@beta`/`@rc` یا یک نسخه دقیق prerelease مانند `@1.2.3-beta.4` صریحاً opt in کنید. - اگر یک spec نصب ساده با شناسه رسمی Plugin منطبق باشد (برای مثال `diffs`)، OpenClaw مستقیماً ورودی کاتالوگ را نصب می‌کند. برای نصب بسته npm با همان نام، از یک spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`). + اگر یک spec نصب ساده با id رسمی Plugin مطابقت داشته باشد (برای مثال `diffs`)، OpenClaw ورودی catalog را مستقیماً نصب می‌کند. برای نصب یک package از npm با همان نام، از یک spec scoped صریح استفاده کنید (برای مثال `@scope/diffs`). - - برای نصب مستقیم از یک مخزن git از `git:` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با قالب‌های `git:github.com/owner/repo`، `git:owner/repo`، `https://` کامل، `ssh://`، `git://`، `file://` و `git@host:owner/repo.git` هستند. برای checkout کردن یک شاخه، tag یا commit پیش از نصب، `@` یا `#` را اضافه کنید. + + برای نصب مستقیم از یک مخزن git از `git:` استفاده کنید. شکل‌های پشتیبانی‌شده شامل URLهای clone با الگوهای `git:github.com/owner/repo`، `git:owner/repo`، `https://` کامل، `ssh://`، `git://`، `file://` و `git@host:owner/repo.git` هستند. برای checkout کردن یک branch، tag یا commit پیش از نصب، `@` یا `#` اضافه کنید. - نصب‌های Git در یک پوشه موقت clone می‌شوند، در صورت وجود ref درخواستی آن را checkout می‌کنند، و سپس از نصب‌کننده عادی پوشه Plugin استفاده می‌کنند. یعنی اعتبارسنجی مانیفست، اسکن کد خطرناک، کار نصب package-manager و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit حل‌شده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند. + نصب‌های Git در یک دایرکتوری موقت clone می‌شوند، اگر ref درخواست‌شده وجود داشته باشد آن را checkout می‌کنند و سپس از نصب‌کننده عادی دایرکتوری Plugin استفاده می‌کنند. یعنی اعتبارسنجی manifest، اسکن کد خطرناک، کار نصب package-manager و رکوردهای نصب مانند نصب‌های npm رفتار می‌کنند. نصب‌های git ثبت‌شده شامل URL/ref منبع به‌همراه commit resolveشده هستند تا `openclaw plugins update` بتواند بعداً منبع را دوباره resolve کند. - پس از نصب از git، برای تأیید ثبت‌های runtime مانند متدهای gateway و فرمان‌های CLI از `openclaw plugins inspect --runtime --json` استفاده کنید. اگر Plugin با `api.registerCli` یک ریشه CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`. + پس از نصب از git، از `openclaw plugins inspect --runtime --json` برای تأیید registrationهای runtime مانند methodهای gateway و فرمان‌های CLI استفاده کنید. اگر Plugin با `api.registerCli` یک root مربوط به CLI ثبت کرده باشد، آن فرمان را مستقیماً از طریق CLI ریشه OpenClaw اجرا کنید، برای مثال `openclaw demo-plugin ping`. - - آرشیوهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. آرشیوهای Plugin بومی OpenClaw باید در ریشه Plugin استخراج‌شده یک `openclaw.plugin.json` معتبر داشته باشند؛ آرشیوهایی که فقط `package.json` دارند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند. + + Archiveهای پشتیبانی‌شده: `.zip`، `.tgz`، `.tar.gz`، `.tar`. Archiveهای Plugin native OpenClaw باید در ریشه Plugin استخراج‌شده یک `openclaw.plugin.json` معتبر داشته باشند؛ archiveهایی که فقط شامل `package.json` هستند پیش از اینکه OpenClaw رکوردهای نصب را بنویسد رد می‌شوند. نصب‌های marketplace مربوط به Claude نیز پشتیبانی می‌شوند. -نصب‌های ClawHub از locator صریح `clawhub:` استفاده می‌کنند: +نصب‌های ClawHub از یک locator صریح `clawhub:` استفاده می‌کنند: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -در دوره گذار راه‌اندازی، specهای Plugin ساده و امن برای npm به‌صورت پیش‌فرض از npm نصب می‌شوند: +specهای ساده Plugin که برای npm امن هستند، در دوره جابه‌جایی launch به‌صورت پیش‌فرض از npm نصب می‌شوند: ```bash openclaw plugins install openclaw-codex-app-server ``` -برای صریح‌کردن حل‌وفصل فقط npm از `npm:` استفاده کنید: +برای صریح‌کردن resolution فقط از npm، از `npm:` استفاده کنید: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw پیش از نصب، API اعلام‌شده Plugin / حداقل سازگاری Gateway را بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact از نوع ClawPack منتشر کند، OpenClaw فایل `.tgz` نسخه‌دار npm-pack را دانلود می‌کند، header digest مربوط به ClawHub و artifact digest را تأیید می‌کند، سپس آن را از مسیر عادی آرشیو نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون فراداده ClawPack همچنان از مسیر قدیمی تأیید آرشیو بسته نصب می‌شوند. نصب‌های ثبت‌شده فراداده منبع ClawHub، نوع artifact، integrity مربوط به npm، shasum مربوط به npm، نام tarball و واقعیت‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند. -نصب‌های بدون نسخه ClawHub یک spec ثبت‌شده بدون نسخه نگه می‌دارند تا `openclaw plugins update` بتواند نسخه‌های جدیدتر ClawHub را دنبال کند؛ انتخابگرهای نسخه یا tag صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` به همان انتخابگر پین‌شده باقی می‌مانند. +OpenClaw سازگاری API تبلیغ‌شده Plugin / حداقل Gateway را پیش از نصب بررسی می‌کند. وقتی نسخه انتخاب‌شده ClawHub یک artifact از ClawPack منتشر می‌کند، OpenClaw فایل `.tgz` مربوط به npm-pack نسخه‌گذاری‌شده را دانلود می‌کند، header digest مربوط به ClawHub و digest artifact را تأیید می‌کند، سپس آن را از مسیر عادی archive نصب می‌کند. نسخه‌های قدیمی‌تر ClawHub بدون metadata مربوط به ClawPack همچنان از مسیر قدیمی اعتبارسنجی archive مربوط به package نصب می‌شوند. نصب‌های ثبت‌شده metadata منبع ClawHub، نوع artifact، integrity مربوط به npm، shasum مربوط به npm، نام tarball و واقعیت‌های digest مربوط به ClawPack را برای به‌روزرسانی‌های بعدی نگه می‌دارند. +نصب‌های ClawHub بدون نسخه، spec ثبت‌شده بدون نسخه را نگه می‌دارند تا `openclaw plugins update` بتواند releaseهای جدیدتر ClawHub را دنبال کند؛ selectorهای نسخه یا tag صریح مانند `clawhub:pkg@1.2.3` و `clawhub:pkg@beta` به همان selector pinned باقی می‌مانند. #### کوتاه‌نویسی Marketplace -وقتی نام marketplace در cache رجیستری محلی Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از کوتاه‌نویسی `plugin@marketplace` استفاده کنید: +وقتی نام marketplace در cache محلی registry مربوط به Claude در `~/.claude/plugins/known_marketplaces.json` وجود دارد، از کوتاه‌نویسی `plugin@marketplace` استفاده کنید: ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -وقتی می‌خواهید منبع marketplace را صریحاً پاس دهید، از `--marketplace` استفاده کنید: +وقتی می‌خواهید منبع marketplace را صریحاً پاس بدهید، از `--marketplace` استفاده کنید: ```bash openclaw plugins install --marketplace @@ -194,28 +194,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - نام marketplace شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json` - - ریشه marketplace محلی یا مسیر `marketplace.json` - - کوتاه‌نویسی مخزن GitHub مانند `owner/repo` - - URL مخزن GitHub مانند `https://github.com/owner/repo` + + - یک نام بازار شناخته‌شده Claude از `~/.claude/plugins/known_marketplaces.json` + - یک ریشه بازار محلی یا مسیر `marketplace.json` + - یک کوتاه‌نویسی مخزن GitHub مانند `owner/repo` + - یک URL مخزن GitHub مانند `https://github.com/owner/repo` - یک URL git - - برای marketplaceهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن marketplace کلون‌شده باقی بمانند. OpenClaw منابع مسیر نسبی را از آن مخزن می‌پذیرد و منابع HTTP(S)، مسیر مطلق، git، GitHub و دیگر منابع غیرمسیری Plugin را از manifestهای راه‌دور رد می‌کند. + + برای بازارهای راه‌دوری که از GitHub یا git بارگذاری می‌شوند، ورودی‌های Plugin باید داخل مخزن بازار کلون‌شده بمانند. OpenClaw منابع مسیر نسبی را از همان مخزن می‌پذیرد و منابع HTTP(S)، مسیر مطلق، git، GitHub، و دیگر منابع غیرمسیر Plugin را از manifestهای راه‌دور رد می‌کند. -برای مسیرها و آرشیوهای محلی، OpenClaw به‌صورت خودکار تشخیص می‌دهد: +برای مسیرها و آرشیوهای محلی، OpenClaw به‌طور خودکار تشخیص می‌دهد: - Pluginهای بومی OpenClaw (`openclaw.plugin.json`) - بسته‌های سازگار با Codex (`.codex-plugin/plugin.json`) -- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه Claude) +- بسته‌های سازگار با Claude (`.claude-plugin/plugin.json` یا چیدمان پیش‌فرض مؤلفه‌های Claude) - بسته‌های سازگار با Cursor (`.cursor-plugin/plugin.json`) -بسته‌های سازگار در ریشه معمول Plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. امروز، Skills بسته، command-skillsهای Claude، پیش‌فرض‌های Claude `settings.json`، پیش‌فرض‌های Claude `.lsp.json` / `lspServers` اعلام‌شده در manifest، command-skillsهای Cursor، و دایرکتوری‌های hook سازگار Codex پشتیبانی می‌شوند؛ قابلیت‌های دیگر بسته که شناسایی شوند در diagnostics/info نمایش داده می‌شوند اما هنوز به اجرای زمان اجرا متصل نشده‌اند. +بسته‌های سازگار در ریشه معمول Plugin نصب می‌شوند و در همان جریان فهرست/اطلاعات/فعال‌سازی/غیرفعال‌سازی شرکت می‌کنند. امروز، Skills بسته، command-skills مربوط به Claude، پیش‌فرض‌های `settings.json` مربوط به Claude، پیش‌فرض‌های `.lsp.json` مربوط به Claude / `lspServers` اعلام‌شده در manifest، command-skills مربوط به Cursor، و دایرکتوری‌های hook سازگار Codex پشتیبانی می‌شوند؛ قابلیت‌های بسته دیگری که تشخیص داده شوند در diagnostics/info نمایش داده می‌شوند، اما هنوز به اجرای زمان اجرا متصل نشده‌اند. ### فهرست @@ -231,49 +231,48 @@ openclaw plugins search --json ``` - فقط Pluginهای فعال‌شده را نشان بده. + فقط Pluginهای فعال را نشان بده. - از نمای جدول به خط‌های جزئیات برای هر Plugin با metadata منبع/خاستگاه/نسخه/فعال‌سازی تغییر بده. + از نمای جدول به خط‌های جزئیات برای هر Plugin با فراداده منبع/مبدأ/نسخه/فعال‌سازی تغییر بده. - موجودی قابل‌خواندن برای ماشین همراه با diagnostics رجیستری و وضعیت نصب وابستگی بسته. + فهرست موجودی قابل خواندن برای ماشین، به‌همراه diagnostics رجیستری و وضعیت نصب وابستگی‌های بسته. -`plugins list` ابتدا رجیستری محلی پایدارشده Plugin را می‌خواند، و اگر رجیستری وجود نداشته باشد یا نامعتبر باشد از یک fallback مشتق‌شده فقط از manifest استفاده می‌کند. این فرمان برای بررسی اینکه آیا یک Plugin نصب، فعال و برای برنامه‌ریزی شروع سرد قابل مشاهده است مفید است، اما probe زنده زمان اجرا برای یک فرایند Gateway ازپیش‌درحال‌اجرا نیست. پس از تغییر کد Plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار اجرای کد `register(api)` یا hookهای جدید، Gatewayای را که به کانال سرویس می‌دهد راه‌اندازی مجدد کنید. برای استقرارهای راه‌دور/کانتینری، بررسی کنید که فرزند واقعی `openclaw gateway run` را راه‌اندازی مجدد می‌کنید، نه فقط یک فرایند wrapper. +`plugins list` ابتدا رجیستری محلی ماندگارشده Plugin را می‌خواند، و وقتی رجیستری وجود نداشته باشد یا نامعتبر باشد از جایگزین مشتق‌شده فقط از manifest استفاده می‌کند. این دستور برای بررسی اینکه آیا یک Plugin نصب شده، فعال است، و برای برنامه‌ریزی راه‌اندازی سرد قابل مشاهده است مفید است، اما یک کاوش زنده زمان اجرا از فرایند Gateway در حال اجرا نیست. پس از تغییر کد Plugin، فعال‌سازی، سیاست hook، یا `plugins.load.paths`، پیش از انتظار برای اجرای کد `register(api)` یا hookهای جدید، Gatewayای را که به کانال سرویس می‌دهد راه‌اندازی مجدد کنید. برای استقرارهای راه‌دور/کانتینری، مطمئن شوید فرزند واقعی `openclaw gateway run` را راه‌اندازی مجدد می‌کنید، نه فقط یک فرایند wrapper. -`plugins list --json` شامل `dependencyStatus` هر Plugin از `package.json` -`dependencies` و `optionalDependencies` است. OpenClaw بررسی می‌کند که آیا نام‌های آن بسته‌ها در مسیر lookup معمول Node `node_modules` برای Plugin وجود دارند یا نه؛ کد زمان اجرای Plugin را import نمی‌کند، package manager اجرا نمی‌کند، و وابستگی‌های گمشده را repair نمی‌کند. +`plugins list --json` شامل `dependencyStatus` هر Plugin از `dependencies` و `optionalDependencies` در `package.json` است. OpenClaw بررسی می‌کند که آیا نام‌های آن بسته‌ها در مسیر معمول جست‌وجوی Node `node_modules` مربوط به Plugin وجود دارند؛ کد زمان اجرای Plugin را import نمی‌کند، package manager اجرا نمی‌کند، و وابستگی‌های گم‌شده را تعمیر نمی‌کند. -`plugins search` یک lookup کاتالوگ راه‌دور ClawHub است. این فرمان وضعیت محلی را بازرسی نمی‌کند، config را تغییر نمی‌دهد، بسته‌ها را نصب نمی‌کند، یا کد زمان اجرای Plugin را بارگذاری نمی‌کند. نتایج جستجو شامل نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:` هستند. +`plugins search` یک جست‌وجوی کاتالوگ راه‌دور ClawHub است. این دستور وضعیت محلی را بازرسی نمی‌کند، config را تغییر نمی‌دهد، بسته‌ها را نصب نمی‌کند، و کد زمان اجرای Plugin را بارگذاری نمی‌کند. نتایج جست‌وجو شامل نام بسته ClawHub، خانواده، کانال، نسخه، خلاصه، و یک راهنمای نصب مانند `openclaw plugins install clawhub:` هستند. -برای کار روی Pluginهای بسته‌بندی‌شده داخل یک تصویر Docker بسته‌بندی‌شده، دایرکتوری منبع Plugin را روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mount‌شده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع صرفا کپی‌شده بی‌اثر می‌ماند تا نصب‌های بسته‌بندی‌شده معمول همچنان از dist کامپایل‌شده استفاده کنند. +برای کار روی Pluginهای بسته‌بندی‌شده داخل یک تصویر Docker بسته‌بندی‌شده، دایرکتوری منبع Plugin را روی مسیر منبع بسته‌بندی‌شده متناظر bind-mount کنید، مانند `/app/extensions/synology-chat`. OpenClaw آن overlay منبع mount‌شده را پیش از `/app/dist/extensions/synology-chat` کشف می‌کند؛ یک دایرکتوری منبع که صرفاً کپی شده باشد بی‌اثر می‌ماند تا نصب‌های بسته‌بندی‌شده معمول همچنان از dist کامپایل‌شده استفاده کنند. -برای عیب‌یابی hook زمان اجرا: +برای اشکال‌زدایی hookهای زمان اجرا: -- `openclaw plugins inspect --runtime --json` hookهای ثبت‌شده و diagnostics را از یک pass بازرسی با module-loaded نشان می‌دهد. بازرسی زمان اجرا هرگز وابستگی‌ها را نصب نمی‌کند؛ برای پاک‌سازی وضعیت وابستگی legacy یا نصب Pluginهای قابل‌دانلود پیکربندی‌شده گمشده از `openclaw doctor --fix` استفاده کنید. -- `openclaw gateway status --deep --require-rpc` Gateway قابل دسترس، راهنمایی‌های سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند. -- hookهای گفت‌وگوی غیر bundled (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) به `plugins.entries..hooks.allowConversationAccess=true` نیاز دارند. +- `openclaw plugins inspect --runtime --json` hookهای ثبت‌شده و diagnostics را از یک گذر بازرسی با ماژول بارگذاری‌شده نشان می‌دهد. بازرسی زمان اجرا هرگز وابستگی‌ها را نصب نمی‌کند؛ برای پاک‌سازی وضعیت وابستگی قدیمی یا نصب Pluginهای قابل دانلودِ پیکربندی‌شده و گم‌شده از `openclaw doctor --fix` استفاده کنید. +- `openclaw gateway status --deep --require-rpc` Gateway قابل دسترسی، اشاره‌های سرویس/فرایند، مسیر config، و سلامت RPC را تأیید می‌کند. +- hookهای گفت‌وگوی غیرهمراه (`llm_input`، `llm_output`، `before_agent_finalize`، `agent_end`) به `plugins.entries..hooks.allowConversationAccess=true` نیاز دارند. -برای جلوگیری از کپی‌کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند): +برای جلوگیری از کپی کردن یک دایرکتوری محلی از `--link` استفاده کنید (به `plugins.load.paths` اضافه می‌کند): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` همراه با `--link` پشتیبانی نمی‌شود، زیرا نصب‌های linked به‌جای کپی‌کردن روی یک هدف نصب مدیریت‌شده، از مسیر منبع دوباره استفاده می‌کنند. +`--force` همراه با `--link` پشتیبانی نمی‌شود، چون نصب‌های linked به‌جای کپی کردن روی هدف نصب مدیریت‌شده، مسیر منبع را دوباره استفاده می‌کنند. -در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در اندیس Plugin مدیریت‌شده ذخیره شود و در عین حال رفتار پیش‌فرض unpinned باقی بماند. +در نصب‌های npm از `--pin` استفاده کنید تا spec دقیق resolve‌شده (`name@version`) در نمایه Plugin مدیریت‌شده ذخیره شود، در حالی که رفتار پیش‌فرض بدون pin باقی بماند. -### اندیس Plugin +### نمایه Plugin -metadata نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. map سطح بالای `installRecords` منبع پایدار metadata نصب است، شامل رکوردهای manifestهای Plugin خراب یا گمشده. آرایه `plugins` کش رجیستری سرد مشتق‌شده از manifest است. این فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، حذف نصب، diagnostics، و رجیستری سرد Plugin استفاده می‌شود. +فراداده نصب Plugin وضعیت مدیریت‌شده توسط ماشین است، نه config کاربر. نصب‌ها و به‌روزرسانی‌ها آن را در `plugins/installs.json` زیر دایرکتوری وضعیت فعال OpenClaw می‌نویسند. نگاشت سطح‌بالای `installRecords` منبع ماندگار فراداده نصب است، از جمله recordهای مربوط به manifestهای خراب یا گم‌شده Plugin. آرایه `plugins` کش رجیستری سرد مشتق‌شده از manifest است. فایل شامل هشدار ویرایش‌نکنید است و توسط `openclaw plugins update`، uninstall، diagnostics، و رجیستری سرد Plugin استفاده می‌شود. -وقتی OpenClaw رکوردهای legacy ارسال‌شده `plugins.installs` را در config ببیند، آن‌ها را به اندیس Plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از writeها شکست بخورد، رکوردهای config نگه داشته می‌شوند تا metadata نصب از دست نرود. +وقتی OpenClaw recordهای قدیمی ارسال‌شده `plugins.installs` را در config ببیند، آن‌ها را به نمایه Plugin منتقل می‌کند و کلید config را حذف می‌کند؛ اگر هرکدام از نوشتن‌ها شکست بخورد، recordهای config حفظ می‌شوند تا فراداده نصب از دست نرود. ### حذف نصب @@ -283,10 +282,10 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` رکوردهای Plugin را از `plugins.entries`، اندیس پایدارشده Plugin، ورودی‌های فهرست allow/deny برای Plugin، و ورودی‌های linked `plugins.load.paths` در صورت کاربرد حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، حذف نصب همچنین دایرکتوری نصب مدیریت‌شده track‌شده را وقتی داخل ریشه extensions Pluginهای OpenClaw باشد حذف می‌کند. برای Pluginهای active memory، slot حافظه به `memory-core` بازنشانی می‌شود. +`uninstall` recordهای Plugin را از `plugins.entries`، نمایه ماندگار Plugin، ورودی‌های فهرست allow/deny مربوط به Plugin، و در صورت کاربرد ورودی‌های linked `plugins.load.paths` حذف می‌کند. مگر اینکه `--keep-files` تنظیم شده باشد، uninstall همچنین دایرکتوری نصب مدیریت‌شده ردیابی‌شده را وقتی داخل ریشه افزونه‌های Plugin OpenClaw باشد حذف می‌کند. برای Pluginهای حافظه فعال، slot حافظه به `memory-core` بازنشانی می‌شود. -`--keep-config` به‌عنوان alias منسوخ برای `--keep-files` پشتیبانی می‌شود. +`--keep-config` به‌عنوان نام مستعار منسوخ‌شده برای `--keep-files` پشتیبانی می‌شود. ### به‌روزرسانی @@ -299,29 +298,29 @@ openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -به‌روزرسانی‌ها روی نصب‌های Plugin track‌شده در اندیس Plugin مدیریت‌شده و نصب‌های hook-pack track‌شده در `hooks.internal.installs` اعمال می‌شوند. +به‌روزرسانی‌ها روی نصب‌های Plugin ردیابی‌شده در نمایه Plugin مدیریت‌شده و نصب‌های hook-pack ردیابی‌شده در `hooks.internal.installs` اعمال می‌شوند. - - وقتی یک شناسه Plugin پاس می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای ذخیره‌شده قبلی مانند `@beta` و نسخه‌های دقیق pinned همچنان در اجراهای بعدی `update ` استفاده می‌شوند. + + وقتی یک id مربوط به Plugin را می‌دهید، OpenClaw از spec نصب ثبت‌شده برای آن Plugin دوباره استفاده می‌کند. یعنی dist-tagهای ذخیره‌شده قبلی مانند `@beta` و نسخه‌های دقیق pinشده در اجرای بعدی `update ` همچنان استفاده می‌شوند. - برای نصب‌های npm، همچنین می‌توانید یک spec صریح بسته npm با dist-tag یا نسخه دقیق پاس دهید. OpenClaw آن نام بسته را به رکورد Plugin track‌شده برمی‌گرداند، آن Plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های مبتنی بر شناسه در آینده ثبت می‌کند. + برای نصب‌های npm، می‌توانید یک spec صریح بسته npm با dist-tag یا نسخه دقیق هم بدهید. OpenClaw آن نام بسته را به record ردیابی‌شده Plugin برمی‌گرداند، آن Plugin نصب‌شده را به‌روزرسانی می‌کند، و spec جدید npm را برای به‌روزرسانی‌های آینده مبتنی بر id ثبت می‌کند. - پاس‌دادن نام بسته npm بدون نسخه یا tag نیز به رکورد Plugin track‌شده برمی‌گردد. وقتی یک Plugin به یک نسخه دقیق pinned شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید. + دادن نام بسته npm بدون نسخه یا tag نیز به record ردیابی‌شده Plugin برمی‌گردد. وقتی Plugin به یک نسخه دقیق pin شده و می‌خواهید آن را به خط انتشار پیش‌فرض رجیستری برگردانید، از این استفاده کنید. - - `openclaw plugins update` از spec Plugin track‌شده دوباره استفاده می‌کند مگر اینکه spec جدیدی پاس دهید. `openclaw update` علاوه بر این کانال فعال به‌روزرسانی OpenClaw را می‌شناسد: در کانال beta، رکوردهای Plugin خط پیش‌فرض npm و ClawHub ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار beta برای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده fallback می‌کنند. نسخه‌های دقیق و tagهای صریح روی همان selector pinned می‌مانند. + + `openclaw plugins update` از spec ردیابی‌شده Plugin دوباره استفاده می‌کند، مگر اینکه spec جدیدی بدهید. `openclaw update` علاوه بر این کانال به‌روزرسانی فعال OpenClaw را می‌شناسد: در کانال بتا، recordهای Plugin مربوط به npm و ClawHub در خط پیش‌فرض ابتدا `@beta` را امتحان می‌کنند، سپس اگر انتشار بتای Plugin وجود نداشته باشد به spec پیش‌فرض/latest ثبت‌شده برمی‌گردند. نسخه‌های دقیق و tagهای صریح روی همان selector pin می‌مانند. - پیش از به‌روزرسانی زنده npm، OpenClaw نسخه بسته نصب‌شده را با metadata رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolve‌شده تطبیق داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود. + پیش از یک به‌روزرسانی زنده npm، OpenClaw نسخه بسته نصب‌شده را در برابر فراداده رجیستری npm بررسی می‌کند. اگر نسخه نصب‌شده و هویت artifact ثبت‌شده از قبل با هدف resolve‌شده مطابقت داشته باشند، به‌روزرسانی بدون دانلود، نصب مجدد، یا بازنویسی `openclaw.json` رد می‌شود. - وقتی یک hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw آن را drift artifact npm تلقی می‌کند. فرمان تعاملی `openclaw plugins update` hashهای مورد انتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی به‌صورت fail closed عمل می‌کنند مگر اینکه caller یک سیاست ادامه صریح ارائه کند. + وقتی یک hash یکپارچگی ذخیره‌شده وجود داشته باشد و hash artifact دریافت‌شده تغییر کند، OpenClaw آن را drift در artifact npm تلقی می‌کند. دستور تعاملی `openclaw plugins update` hashهای مورد انتظار و واقعی را چاپ می‌کند و پیش از ادامه تأیید می‌خواهد. helperهای به‌روزرسانی غیرتعاملی fail closed می‌شوند، مگر اینکه فراخوان یک سیاست ادامه صریح ارائه کند. - `--dangerously-force-unsafe-install` همچنین در `plugins update` به‌عنوان override اضطراری برای مثبت‌های کاذب اسکن dangerous-code داخلی هنگام به‌روزرسانی Pluginها در دسترس است. این گزینه همچنان blockهای سیاست `before_install` Plugin یا blocking ناشی از شکست اسکن را دور نمی‌زند، و فقط روی به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack. + `--dangerously-force-unsafe-install` روی `plugins update` نیز به‌عنوان override اضطراری برای false positiveهای اسکن داخلی کد خطرناک هنگام به‌روزرسانی Plugin در دسترس است. این گزینه همچنان blockهای سیاست `before_install` مربوط به Plugin یا مسدودسازی ناشی از شکست اسکن را دور نمی‌زند، و فقط برای به‌روزرسانی‌های Plugin اعمال می‌شود، نه به‌روزرسانی‌های hook-pack. @@ -333,21 +332,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect هویت، وضعیت بارگذاری، منبع، قابلیت‌های manifest، flagهای سیاست، diagnostics، metadata نصب، قابلیت‌های بسته، و هر پشتیبانی شناسایی‌شده MCP یا سرور LSP را بدون import کردن پیش‌فرض زمان اجرای Plugin نشان می‌دهد. برای بارگذاری ماژول Plugin و شامل‌کردن hookها، tools، commands، services، متدهای gateway، و routeهای HTTP ثبت‌شده، `--runtime` را اضافه کنید. بازرسی زمان اجرا وابستگی‌های گمشده Plugin را مستقیما گزارش می‌کند؛ نصب‌ها و repairها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند. +Inspect هویت، وضعیت بارگذاری، منبع، قابلیت‌های manifest، پرچم‌های سیاست، diagnostics، فراداده نصب، قابلیت‌های بسته، و هر پشتیبانی تشخیص‌داده‌شده از سرور MCP یا LSP را بدون import کردن زمان اجرای Plugin به‌صورت پیش‌فرض نشان می‌دهد. برای بارگذاری ماژول Plugin و شامل‌کردن hookها، tools، commands، services، methodهای gateway، و routeهای HTTP ثبت‌شده، `--runtime` را اضافه کنید. بازرسی زمان اجرا وابستگی‌های گم‌شده Plugin را مستقیماً گزارش می‌کند؛ نصب‌ها و تعمیرها در `openclaw plugins install`، `openclaw plugins update`، و `openclaw doctor --fix` باقی می‌مانند. -فرمان‌های CLI متعلق به Plugin به‌عنوان گروه‌های فرمان ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک فرمان را زیر `cliCommands` نشان داد، آن را به‌شکل `openclaw ...` اجرا کنید؛ برای مثال Pluginای که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود. +دستورهای CLI متعلق به Plugin به‌عنوان گروه‌های دستور ریشه `openclaw` نصب می‌شوند. پس از اینکه `inspect --runtime` یک دستور را زیر `cliCommands` نشان داد، آن را به‌صورت `openclaw ...` اجرا کنید؛ برای نمونه، Pluginای که `demo-git` را ثبت می‌کند می‌تواند با `openclaw demo-git ping` تأیید شود. -هر Plugin بر اساس چیزی که واقعا در زمان اجرا ثبت می‌کند طبقه‌بندی می‌شود: +هر Plugin بر اساس آنچه واقعاً در زمان اجرا ثبت می‌کند طبقه‌بندی می‌شود: -- **plain-capability** — یک نوع قابلیت (برای مثال یک Plugin فقط provider) -- **hybrid-capability** — چند نوع قابلیت (برای مثال متن + گفتار + تصویر) +- **plain-capability** — یک نوع قابلیت (مثلاً یک Plugin فقط provider) +- **hybrid-capability** — چند نوع قابلیت (مثلاً متن + گفتار + تصاویر) - **hook-only** — فقط hookها، بدون قابلیت یا surface - **non-capability** — tools/commands/services اما بدون قابلیت برای اطلاعات بیشتر درباره مدل قابلیت، [شکل‌های Plugin](/fa/plugins/architecture#plugin-shapes) را ببینید. -flag `--json` گزارشی قابل‌خواندن برای ماشین تولید می‌کند که برای اسکریپت‌نویسی و auditing مناسب است. `inspect --all` یک جدول سراسری با ستون‌های shape، نوع‌های قابلیت، اعلان‌های سازگاری، قابلیت‌های بسته، و خلاصه hook رندر می‌کند. `info` نام مستعار `inspect` است. +پرچم `--json` گزارشی قابل خواندن برای ماشین تولید می‌کند که برای اسکریپت‌نویسی و حسابرسی مناسب است. `inspect --all` یک جدول در سطح کل مجموعه با ستون‌های شکل، گونه‌های قابلیت، اعلان‌های سازگاری، قابلیت‌های بسته، و خلاصه hook نمایش می‌دهد. `info` نام مستعار `inspect` است. ### Doctor @@ -358,9 +357,9 @@ openclaw plugins doctor `doctor` خطاهای بارگذاری Plugin، diagnostics مربوط به manifest/discovery، و اعلان‌های سازگاری را گزارش می‌کند. وقتی همه چیز پاک باشد، `No plugin issues detected.` را چاپ می‌کند. -اگر یک Plugin پیکربندی‌شده روی دیسک حاضر باشد اما توسط بررسی‌های path-safety لودر blocked شده باشد، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف config مربوط به `plugins.entries.` یا `plugins.allow`، diagnostic قبلی Plugin blocked را رفع کنید، مانند مالکیت مسیر یا مجوزهای world-writable. +اگر یک Plugin پیکربندی‌شده روی دیسک وجود داشته باشد اما توسط بررسی‌های path-safety loader مسدود شود، اعتبارسنجی config ورودی Plugin را نگه می‌دارد و آن را به‌صورت `present but blocked` گزارش می‌کند. به‌جای حذف config مربوط به `plugins.entries.` یا `plugins.allow`، diagnostic قبلی Plugin مسدودشده، مانند مالکیت مسیر یا مجوزهای world-writable را اصلاح کنید. -برای شکست‌های شکل ماژول مانند exportهای گمشده `register`/`activate`، با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` دوباره اجرا کنید تا خلاصه فشرده‌ای از export-shape در خروجی diagnostic گنجانده شود. +برای شکست‌های شکل ماژول مانند exportهای گم‌شده `register`/`activate`، با `OPENCLAW_PLUGIN_LOAD_DEBUG=1` دوباره اجرا کنید تا یک خلاصه فشرده از شکل exportها در خروجی diagnostic گنجانده شود. ### رجیستری @@ -370,12 +369,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -رجیستری محلی Plugin مدل خواندن سرد پایدارشده OpenClaw برای هویت Plugin نصب‌شده، فعال‌سازی، metadata منبع، و مالکیت contribution است. شروع معمول، lookup مالک provider، طبقه‌بندی راه‌اندازی کانال، و موجودی Plugin می‌توانند بدون import کردن ماژول‌های زمان اجرای Plugin آن را بخوانند. +رجیستری محلی Plugin مدل خواندن سرد ماندگار OpenClaw برای هویت Plugin نصب‌شده، فعال‌سازی، فراداده منبع، و مالکیت مشارکت است. راه‌اندازی معمول، جست‌وجوی مالک provider، طبقه‌بندی راه‌اندازی کانال، و موجودی Plugin می‌توانند بدون import کردن ماژول‌های زمان اجرای Plugin آن را بخوانند. -از `plugins registry` برای بررسی اینکه رجیستری پایدارشده موجود، به‌روز یا قدیمی است استفاده کنید. از `--refresh` برای بازسازی آن از نمایهٔ Plugin پایدارشده، سیاست پیکربندی، و فرادادهٔ manifest/package استفاده کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی در زمان اجرا. +از `plugins registry` استفاده کنید تا بررسی کنید آیا رجیستری پایدارشده وجود دارد، به‌روز است، یا کهنه شده است. از `--refresh` استفاده کنید تا آن را از شاخص Plugin پایدارشده، سیاست پیکربندی، و فراداده‌های manifest/package بازسازی کنید. این یک مسیر تعمیر است، نه مسیر فعال‌سازی در زمان اجرا. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک سوییچ سازگاری منسوخ‌شدهٔ اضطراری برای خطاهای خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ fallback محیطی فقط برای بازیابی اضطراری راه‌اندازی هنگام عرضهٔ مهاجرت است. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` یک کلید سازگاری اضطراری منسوخ برای خرابی‌های خواندن رجیستری است. `plugins registry --refresh` یا `openclaw doctor --fix` را ترجیح دهید؛ جایگزین env فقط برای بازیابی اضطراری شروع به کار در زمانی است که مهاجرت در حال انتشار است. ### بازارچه @@ -385,7 +384,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -فهرست بازارچه یک مسیر بازارچهٔ محلی، یک مسیر `marketplace.json`، یک اختصار GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL گیت را می‌پذیرد. `--json` برچسب منبع حل‌شده را به‌همراه manifest بازارچهٔ تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند. +فهرست بازارچه یک مسیر بازارچه محلی، یک مسیر `marketplace.json`، یک خلاصه‌نویسی GitHub مانند `owner/repo`، یک URL مخزن GitHub، یا یک URL git را می‌پذیرد. `--json` برچسب منبع حل‌شده را همراه با manifest بازارچه تجزیه‌شده و ورودی‌های Plugin چاپ می‌کند. ## مرتبط diff --git a/docs/fa/cli/proxy.md b/docs/fa/cli/proxy.md index ac36073ab..cf1866c7d 100644 --- a/docs/fa/cli/proxy.md +++ b/docs/fa/cli/proxy.md @@ -1,24 +1,29 @@ --- read_when: - - باید مسیریابی پروکسیِ مدیریت‌شده توسط اپراتور را پیش از استقرار اعتبارسنجی کنید - - باید ترافیک انتقال OpenClaw را به‌صورت محلی برای اشکال‌زدایی ضبط کنید - - می‌خواهید نشست‌های پراکسی اشکال‌زدایی، blobها یا پیش‌تنظیم‌های داخلی پرس‌وجو را بررسی کنید + - باید مسیریابی پروکسیِ مدیریت‌شده توسط اپراتور را پیش از استقرار اعتبارسنجی کنید. + - برای اشکال‌زدایی باید ترافیک انتقال OpenClaw را به‌صورت محلی ضبط کنید + - می‌خواهید نشست‌های پراکسی اشکال‌زدایی، اشیای باینری بزرگ، یا پیش‌تنظیم‌های پرس‌وجوی داخلی را بررسی کنید summary: مرجع CLI برای `openclaw proxy`، شامل اعتبارسنجی پروکسی مدیریت‌شده توسط اپراتور و بازرس ضبط پروکسی اشکال‌زدایی محلی title: پروکسی x-i18n: - generated_at: "2026-05-01T11:44:59Z" + generated_at: "2026-05-04T07:03:02Z" model: gpt-5.5 provider: openai - source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9 + source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb source_path: cli/proxy.md workflow: 16 --- # `openclaw proxy` -مسیریابی پراکسی تحت مدیریت اپراتور را اعتبارسنجی کنید، یا پراکسی اشکال‌زدایی صریح محلی را اجرا کنید و ترافیک ضبط‌شده را بررسی کنید. +مسیریابی پراکسیِ مدیریت‌شده توسط راهبر را اعتبارسنجی کنید، یا پراکسی اشکال‌زدایی صریح محلی را اجرا کنید +و ترافیک ثبت‌شده را بررسی کنید. -از `validate` برای پیش‌بررسی یک پراکسی پیش‌برنده تحت مدیریت اپراتور پیش از فعال‌سازی مسیریابی پراکسی OpenClaw استفاده کنید. فرمان‌های دیگر ابزارهای اشکال‌زدایی برای بررسی در سطح انتقال هستند: آن‌ها می‌توانند یک پراکسی محلی را شروع کنند، یک فرمان فرزند را با ضبط فعال اجرا کنند، نشست‌های ضبط را فهرست کنند، الگوهای رایج ترافیک را پرس‌وجو کنند، blobهای ضبط‌شده را بخوانند، و داده‌های ضبط محلی را پاک کنند. +از `validate` برای پیش‌بررسی یک پراکسی روبه‌جلوی مدیریت‌شده توسط راهبر، پیش از فعال‌سازی +مسیریابی پراکسی OpenClaw استفاده کنید. فرمان‌های دیگر ابزارهای اشکال‌زدایی برای +بررسی در سطح انتقال هستند: آن‌ها می‌توانند یک پراکسی محلی را شروع کنند، یک فرمان فرزند را +با ثبت فعال اجرا کنند، نشست‌های ثبت را فهرست کنند، الگوهای رایج ترافیک را پرس‌وجو کنند، blobهای +ثبت‌شده را بخوانند، و داده‌های ثبت محلی را پاک‌سازی کنند. ## فرمان‌ها @@ -35,17 +40,23 @@ openclaw proxy purge ## اعتبارسنجی -`openclaw proxy validate` نشانی مؤثر پراکسی تحت مدیریت اپراتور را از `--proxy-url`، پیکربندی، یا `OPENCLAW_PROXY_URL` بررسی می‌کند. وقتی هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، یک مشکل پیکربندی گزارش می‌کند؛ برای یک پیش‌بررسی موردی پیش از تغییر پیکربندی، از `--proxy-url` استفاده کنید. به‌طور پیش‌فرض بررسی می‌کند که یک مقصد عمومی از طریق پراکسی موفق شود و پراکسی نتواند به یک قناری موقت loopback دسترسی پیدا کند. مقصدهای ردشده سفارشی fail-closed هستند: پاسخ‌های HTTP و خطاهای مبهم انتقال هر دو ناموفق محسوب می‌شوند، مگر اینکه بتوانید یک سیگنال رد دسترسی ویژه استقرار را جداگانه تأیید کنید. +`openclaw proxy validate` نشانی URL مؤثر پراکسیِ مدیریت‌شده توسط راهبر را از +`--proxy-url`، پیکربندی، یا `OPENCLAW_PROXY_URL` بررسی می‌کند. وقتی +هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، یک مشکل پیکربندی گزارش می‌دهد؛ برای یک پیش‌بررسی موردی +پیش از تغییر پیکربندی، از `--proxy-url` استفاده کنید. به‌طور پیش‌فرض، بررسی می‌کند که یک مقصد عمومی +از طریق پراکسی موفق شود و پراکسی نتواند به یک کاناری موقت بازگشت محلی دسترسی پیدا کند. +مقصدهای ردشده سفارشی fail-closed هستند: پاسخ‌های HTTP و خطاهای مبهم انتقال +هر دو شکست محسوب می‌شوند، مگر اینکه بتوانید یک سیگنال ردشدن مخصوص استقرار را جداگانه تأیید کنید. گزینه‌ها: -- `--json`: JSON قابل خواندن توسط ماشین را چاپ می‌کند. -- `--proxy-url `: این نشانی پراکسی را به‌جای پیکربندی یا env اعتبارسنجی می‌کند. -- `--allowed-url `: مقصدی را اضافه می‌کند که انتظار می‌رود از طریق پراکسی موفق شود. برای بررسی چند مقصد، تکرار کنید. -- `--denied-url `: مقصدی را اضافه می‌کند که انتظار می‌رود توسط پراکسی مسدود شود. برای بررسی چند مقصد، تکرار کنید. +- `--json`: JSON قابل‌خواندن توسط ماشین چاپ می‌کند. +- `--proxy-url `: این URL پراکسی را به‌جای پیکربندی یا env اعتبارسنجی می‌کند. +- `--allowed-url `: مقصدی را اضافه می‌کند که انتظار می‌رود از طریق پراکسی موفق شود. برای بررسی چند مقصد تکرار کنید. +- `--denied-url `: مقصدی را اضافه می‌کند که انتظار می‌رود توسط پراکسی مسدود شود. برای بررسی چند مقصد تکرار کنید. - `--timeout-ms `: مهلت زمانی هر درخواست بر حسب میلی‌ثانیه. -برای راهنمایی استقرار و معناشناسی رد دسترسی، [پراکسی شبکه](/fa/security/network-proxy) را ببینید. +برای راهنمای استقرار و معناشناسی ردشدن، [پراکسی شبکه](/fa/security/network-proxy) را ببینید. ## پیش‌تنظیم‌های پرس‌وجو @@ -58,15 +69,16 @@ openclaw proxy purge - `missing-ack` - `error-bursts` -## نکات +## یادداشت‌ها - `start` به‌طور پیش‌فرض از `127.0.0.1` استفاده می‌کند، مگر اینکه `--host` تنظیم شده باشد. -- `run` یک پراکسی اشکال‌زدایی محلی را شروع می‌کند و سپس فرمان پس از `--` را اجرا می‌کند. -- `validate` وقتی پیکربندی پراکسی یا بررسی‌های مقصد ناموفق شوند، با کد 1 خارج می‌شود. -- ضبط‌ها داده‌های اشکال‌زدایی محلی هستند؛ پس از اتمام کار از `openclaw proxy purge` استفاده کنید. +- `run` یک پراکسی اشکال‌زدایی محلی را شروع می‌کند و سپس فرمان بعد از `--` را اجرا می‌کند. +- ارسال مستقیم به upstream در پراکسی اشکال‌زدایی، سوکت‌های upstream را برای عیب‌یابی باز می‌کند. وقتی حالت پراکسی مدیریت‌شده OpenClaw فعال باشد، ارسال مستقیم برای درخواست‌های پراکسی و تونل‌های CONNECT به‌طور پیش‌فرض غیرفعال است؛ `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` را فقط برای عیب‌یابی محلی تأییدشده تنظیم کنید. +- `validate` وقتی پیکربندی پراکسی یا بررسی‌های مقصد شکست بخورند، با کد 1 خارج می‌شود. +- ثبت‌ها داده‌های اشکال‌زدایی محلی هستند؛ پس از پایان کار از `openclaw proxy purge` استفاده کنید. ## مرتبط - [مرجع CLI](/fa/cli) - [پراکسی شبکه](/fa/security/network-proxy) -- [احراز هویت پراکسی معتمد](/fa/gateway/trusted-proxy-auth) +- [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) diff --git a/docs/fa/cli/sessions.md b/docs/fa/cli/sessions.md index 0281cb2d8..fe1c39f4d 100644 --- a/docs/fa/cli/sessions.md +++ b/docs/fa/cli/sessions.md @@ -1,28 +1,34 @@ --- read_when: - - می‌خواهید جلسات ذخیره‌شده را فهرست کنید و فعالیت اخیر را ببینید -summary: مرجع CLI برای `openclaw sessions` (فهرست کردن نشست‌های ذخیره‌شده + نحوه استفاده) + - می‌خواهید نشست‌های ذخیره‌شده را فهرست کنید و فعالیت‌های اخیر را ببینید +summary: مرجع CLI برای `openclaw sessions` (فهرست‌کردن نشست‌های ذخیره‌شده + نحوه استفاده) title: نشست‌ها x-i18n: - generated_at: "2026-05-02T20:42:20Z" + generated_at: "2026-05-04T07:02:44Z" model: gpt-5.5 provider: openai - source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f + source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e source_path: cli/sessions.md workflow: 16 --- # `openclaw sessions` -نشست‌های مکالمه ذخیره‌شده را فهرست کنید. +نشست‌های گفت‌وگوی ذخیره‌شده را فهرست کنید. -فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های -مکالمه پایدارشده را از ذخیره‌گاه‌های نشست نشان می‌دهند. یک کانال ساکت Discord، -Slack، Telegram یا کانالی دیگر می‌تواند بدون ایجاد ردیف نشست جدید، تا زمانی که -پیامی پردازش شود، با موفقیت دوباره وصل شود. وقتی به اتصال زنده کانال نیاز دارید، -از `openclaw channels status --probe`،‏ `openclaw status --deep` یا +فهرست‌های نشست، بررسی زنده‌بودن کانال/ارائه‌دهنده نیستند. آن‌ها ردیف‌های گفت‌وگوی +ماندگارشده از مخزن‌های نشست را نشان می‌دهند. یک Discord، Slack، Telegram یا +کانال دیگرِ ساکت می‌تواند بدون ایجاد ردیف نشست جدید با موفقیت دوباره وصل شود +تا زمانی که پیامی پردازش شود. وقتی به اتصال زندهٔ کانال نیاز دارید از +`openclaw channels status --probe`، `openclaw status --deep` یا `openclaw health --verbose` استفاده کنید. +پاسخ‌های Gateway `sessions.list` به‌طور پیش‌فرض محدود هستند تا مخزن‌های بزرگ و +دیرپا نتوانند حلقهٔ رویداد Gateway را در انحصار بگیرند. وقتی بازهٔ نتیجهٔ +متفاوتی لازم است، از کلاینت‌های RPC یک `limit` مثبت و صریح ارسال کنید؛ پاسخ‌ها +وقتی فراخوان‌ها نیاز داشته باشند نشان دهند ردیف‌های بیشتری وجود دارد، شامل +`totalCount`، `limitApplied` و `hasMore` هستند. + ```bash openclaw sessions openclaw sessions --agent work @@ -34,29 +40,28 @@ openclaw sessions --json انتخاب دامنه: -- پیش‌فرض: ذخیره‌گاه عامل پیش‌فرض پیکربندی‌شده -- `--verbose`: ثبت گزارش تفصیلی -- `--agent `: یک ذخیره‌گاه عامل پیکربندی‌شده -- `--all-agents`: تجمیع همه ذخیره‌گاه‌های عامل پیکربندی‌شده -- `--store `: مسیر صریح ذخیره‌گاه (نمی‌تواند با `--agent` یا `--all-agents` ترکیب شود) +- پیش‌فرض: مخزن عامل پیش‌فرض پیکربندی‌شده +- `--verbose`: گزارش‌گیری پرجزئیات +- `--agent `: یک مخزن عامل پیکربندی‌شده +- `--all-agents`: تجمیع همهٔ مخزن‌های عامل پیکربندی‌شده +- `--store `: مسیر صریح مخزن (نمی‌توان آن را با `--agent` یا `--all-agents` ترکیب کرد) -یک بسته مسیر اجرا برای یک نشست ذخیره‌شده صادر کنید: +یک بستهٔ مسیر اجرا را برای یک نشست ذخیره‌شده صادر کنید: ```bash openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json ``` -این همان مسیر دستوری است که پس از تایید درخواست اجرا توسط مالک، توسط دستور اسلش -`/export-trajectory` استفاده می‌شود. دایرکتوری خروجی همیشه داخل -`.openclaw/trajectory-exports/` زیر فضای کاری انتخاب‌شده resolve می‌شود. +این همان مسیر فرمانی است که فرمان اسلش `/export-trajectory` پس از تأیید درخواست +اجرایی توسط مالک استفاده می‌کند. پوشهٔ خروجی همیشه داخل +`.openclaw/trajectory-exports/` در فضای کاری انتخاب‌شده resolve می‌شود. -`openclaw sessions --all-agents` ذخیره‌گاه‌های عامل پیکربندی‌شده را می‌خواند. -کشف نشست Gateway و ACP گسترده‌تر است: آن‌ها ذخیره‌گاه‌های فقط-دیسک را هم که زیر -ریشه پیش‌فرض `agents/` یا ریشه قالب‌دار `session.store` پیدا می‌شوند شامل -می‌کنند. این ذخیره‌گاه‌های کشف‌شده باید به فایل‌های معمولی `sessions.json` داخل -ریشه عامل resolve شوند؛ پیوندهای نمادین و مسیرهای خارج از ریشه نادیده گرفته -می‌شوند. +`openclaw sessions --all-agents` مخزن‌های عامل پیکربندی‌شده را می‌خواند. کشف +نشست در Gateway و ACP گسترده‌تر است: آن‌ها مخزن‌های فقط-دیسکی پیدا‌شده زیر ریشهٔ +پیش‌فرض `agents/` یا یک ریشهٔ قالب‌بندی‌شدهٔ `session.store` را هم شامل می‌شوند. +آن مخزن‌های کشف‌شده باید به فایل‌های عادی `sessions.json` داخل ریشهٔ عامل resolve +شوند؛ symlinkها و مسیرهای بیرون از ریشه نادیده گرفته می‌شوند. نمونه‌های JSON: @@ -79,9 +84,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 } ``` -## نگه‌داری پاک‌سازی +## نگهداری پاک‌سازی -نگه‌داری را اکنون اجرا کنید (به‌جای انتظار برای چرخه نوشتن بعدی): +همین حالا نگهداری را اجرا کنید (به‌جای انتظار برای چرخهٔ نوشتن بعدی): ```bash openclaw sessions cleanup --dry-run @@ -94,22 +99,22 @@ openclaw sessions cleanup --json `openclaw sessions cleanup` از تنظیمات `session.maintenance` در پیکربندی استفاده می‌کند: -- نکته دامنه: `openclaw sessions cleanup` ذخیره‌گاه‌های نشست، transcriptها و فایل‌های جانبی مسیر اجرا را نگه‌داری می‌کند. این دستور گزارش‌های اجرای cron (`cron/runs/.jsonl`) را هرس نمی‌کند؛ آن‌ها توسط `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگه‌داری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند. +- نکتهٔ دامنه: `openclaw sessions cleanup` مخزن‌های نشست، رونوشت‌ها و sidecarهای مسیر اجرا را نگهداری می‌کند. این فرمان گزارش‌های اجرای cron را (`cron/runs/.jsonl`) هرس نمی‌کند؛ این گزارش‌ها با `cron.runLog.maxBytes` و `cron.runLog.keepLines` در [پیکربندی Cron](/fa/automation/cron-jobs#configuration) مدیریت می‌شوند و در [نگهداری Cron](/fa/automation/cron-jobs#maintenance) توضیح داده شده‌اند. - `--dry-run`: پیش‌نمایش تعداد ورودی‌هایی که بدون نوشتن هرس/محدود می‌شوند. - در حالت متنی، dry-run یک جدول اقدام برای هر نشست چاپ می‌کند (`Action`، `Key`، `Age`، `Model`، `Flags`) تا بتوانید ببینید چه چیزی نگه داشته می‌شود و چه چیزی حذف می‌شود. -- `--enforce`: نگه‌داری را حتی وقتی `session.maintenance.mode` برابر `warn` است اعمال می‌کند. -- `--fix-missing`: ورودی‌هایی را که فایل‌های transcript آن‌ها گم شده‌اند حذف می‌کند، حتی اگر به طور عادی هنوز از نظر سن/تعداد مشمول حذف نمی‌شدند. -- `--active-key `: از یک کلید فعال مشخص در برابر تخلیه ناشی از بودجه دیسک محافظت می‌کند. اشاره‌گرهای بادوام مکالمه خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگه‌داری سن/تعداد/بودجه دیسک نگه داشته می‌شوند. -- `--agent `: پاک‌سازی را برای یک ذخیره‌گاه عامل پیکربندی‌شده اجرا می‌کند. -- `--all-agents`: پاک‌سازی را برای همه ذخیره‌گاه‌های عامل پیکربندی‌شده اجرا می‌کند. -- `--store `: روی یک فایل `sessions.json` مشخص اجرا می‌کند. -- `--json`: خلاصه JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر ذخیره‌گاه است. +- `--enforce`: نگهداری را حتی وقتی `session.maintenance.mode` برابر `warn` است اعمال می‌کند. +- `--fix-missing`: ورودی‌هایی را که فایل‌های رونوشتشان وجود ندارد حذف می‌کند، حتی اگر معمولاً هنوز به دلیل سن/تعداد حذف نمی‌شدند. +- `--active-key `: از یک کلید فعال مشخص در برابر تخلیهٔ بودجهٔ دیسک محافظت می‌کند. اشاره‌گرهای بادوام گفت‌وگوی خارجی، مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به thread، نیز توسط نگهداری سن/تعداد/بودجهٔ دیسک نگه داشته می‌شوند. +- `--agent `: پاک‌سازی را برای یک مخزن عامل پیکربندی‌شده اجرا می‌کند. +- `--all-agents`: پاک‌سازی را برای همهٔ مخزن‌های عامل پیکربندی‌شده اجرا می‌کند. +- `--store `: روی یک فایل مشخص `sessions.json` اجرا می‌شود. +- `--json`: خلاصهٔ JSON چاپ می‌کند. با `--all-agents`، خروجی شامل یک خلاصه برای هر مخزن است. -وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای ذخیره‌گاه‌های عامل -پیکربندی‌شده از طریق Gateway فرستاده می‌شود تا همان نویسنده ذخیره‌گاه نشست -را که ترافیک زمان اجرا استفاده می‌کند به اشتراک بگذارد. برای تعمیر آفلاین صریح -یک فایل ذخیره‌گاه، از `--store ` استفاده کنید. +وقتی یک Gateway در دسترس باشد، پاک‌سازی غیر dry-run برای مخزن‌های عامل +پیکربندی‌شده از طریق Gateway ارسال می‌شود تا از همان نویسندهٔ مخزن نشستِ ترافیک +زمان اجرا استفاده کند. برای تعمیر آفلاین صریحِ یک فایل مخزن از `--store ` +استفاده کنید. `openclaw sessions cleanup --all-agents --dry-run --json`: diff --git a/docs/fa/concepts/mantis.md b/docs/fa/concepts/mantis.md index cc1fa1103..8afbcff5a 100644 --- a/docs/fa/concepts/mantis.md +++ b/docs/fa/concepts/mantis.md @@ -1,58 +1,58 @@ --- read_when: - - ساخت یا اجرای کنترل کیفیت بصری زنده برای باگ‌های OpenClaw + - ساخت یا اجرای تضمین کیفیت بصری زنده برای باگ‌های OpenClaw - افزودن راستی‌آزمایی قبل و بعد برای یک درخواست کشش - - افزودن Discord، Slack، WhatsApp یا سناریوهای انتقال زندهٔ دیگر - - اشکال‌زدایی اجراهای تضمین کیفیت که به نماگرفت‌ها، خودکارسازی مرورگر یا دسترسی VNC نیاز دارند -summary: Mantis سامانهٔ تأیید بصری سرتاسری برای بازتولید باگ‌های OpenClaw روی انتقال‌دهنده‌های زنده، ثبت شواهد قبل و بعد، و پیوست کردن مصنوعات به درخواست‌های کشش است. + - افزودن Discord، Slack، WhatsApp یا سناریوهای ترابری زندهٔ دیگر + - اشکال‌زدایی اجراهای QA که به اسکرین‌شات، خودکارسازی مرورگر یا دسترسی VNC نیاز دارند +summary: Mantis سامانهٔ راستی‌آزمایی بصری سرتاسری برای بازتولید باگ‌های OpenClaw روی بسترهای انتقال زنده، ثبت شواهد قبل و بعد، و پیوست کردن آرتیفکت‌ها به PRها است. title: آخوندک x-i18n: - generated_at: "2026-05-04T02:23:59Z" + generated_at: "2026-05-04T07:03:13Z" model: gpt-5.5 provider: openai - source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d + source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164 source_path: concepts/mantis.md workflow: 16 --- -Mantis سامانهٔ راستی‌آزمایی سرتاسری OpenClaw برای باگ‌هایی است که به runtime واقعی، transport واقعی و اثبات دیداری نیاز دارند. این سامانه یک سناریو را روی یک ref خرابِ شناخته‌شده اجرا می‌کند، شواهد را ثبت می‌کند، همان سناریو را روی یک ref نامزد اجرا می‌کند، و مقایسه را به‌صورت artifactهایی منتشر می‌کند که یک نگه‌دارنده می‌تواند از یک PR یا از یک فرمان محلی بررسی کند. +Mantis سامانه راستی‌آزمایی سرتاسری OpenClaw برای باگ‌هایی است که به runtime واقعی، transport واقعی و شواهد قابل مشاهده نیاز دارند. این سامانه یک سناریو را روی ref شناخته‌شده معیوب اجرا می‌کند، شواهد را ثبت می‌کند، همان سناریو را روی ref نامزد اجرا می‌کند و مقایسه را به‌صورت artifacts منتشر می‌کند تا نگه‌دارنده بتواند آن را از یک PR یا از یک فرمان محلی بررسی کند. -Mantis با Discord شروع می‌شود، چون Discord یک مسیر اولیهٔ بسیار ارزشمند در اختیار ما می‌گذارد: احراز هویت واقعی bot، کانال‌های واقعی guild، واکنش‌ها، threadها، فرمان‌های بومی، و یک رابط کاربری مرورگر که انسان‌ها می‌توانند در آن به‌صورت دیداری تأیید کنند transport چه چیزی را نشان داده است. +Mantis با Discord شروع می‌شود چون Discord یک مسیر نخست با ارزش بالا در اختیار ما می‌گذارد: احراز هویت واقعی بات، کانال‌های واقعی guild، reactionها، threadها، فرمان‌های بومی و یک رابط کاربری مرورگر که انسان‌ها می‌توانند در آن به‌صورت بصری تأیید کنند transport چه چیزی نشان داده است. ## اهداف - بازتولید یک باگ از یک issue یا PR در GitHub با همان شکل transport که کاربران می‌بینند. - ثبت یک artifact **قبل** روی ref مبنا پیش از اعمال اصلاح. - ثبت یک artifact **بعد** روی ref نامزد پس از اعمال اصلاح. -- استفاده از oracle قطعی هر زمان ممکن باشد، مانند خواندن واکنش با Discord REST یا بررسی رونوشت کانال. +- استفاده از oracle قطعی هر زمان ممکن باشد، مانند خواندن reaction با Discord REST یا بررسی transcript کانال. - ثبت screenshotها وقتی باگ سطح رابط کاربری قابل مشاهده دارد. -- اجرای محلی از یک CLI کنترل‌شده توسط agent و اجرای راه‌دور از GitHub. -- حفظ وضعیت کافی از ماشین برای نجات با VNC وقتی ورود، خودکارسازی مرورگر، یا احراز هویت provider گیر می‌کند. -- ارسال وضعیت کوتاه به یک کانال Discord عملیاتی وقتی اجرا مسدود شده، به کمک دستی VNC نیاز دارد، یا تمام می‌شود. +- اجرای محلی از یک CLI تحت کنترل agent و اجرای راه دور از GitHub. +- حفظ وضعیت کافی ماشین برای نجات با VNC وقتی ورود، خودکارسازی مرورگر یا احراز هویت provider گیر می‌کند. +- ارسال وضعیت مختصر به یک کانال Discord اپراتور وقتی اجرا مسدود شده، به کمک دستی VNC نیاز دارد یا تمام می‌شود. ## غیرهدف‌ها -- Mantis جایگزین تست‌های واحد نیست. اجرای Mantis معمولاً باید پس از فهمیدن اصلاح، به یک تست regression کوچک‌تر تبدیل شود. -- Mantis دروازهٔ CI سریع معمول نیست. کندتر است، از credentialهای زنده استفاده می‌کند، و برای باگ‌هایی نگه داشته می‌شود که محیط زنده در آن‌ها مهم است. -- Mantis نباید برای عملیات عادی به انسان نیاز داشته باشد. VNC دستی مسیر نجات است، نه مسیر مطلوب. -- Mantis secretهای خام را در artifactها، logها، screenshotها، گزارش‌های Markdown، یا دیدگاه‌های PR ذخیره نمی‌کند. +- Mantis جایگزین unit testها نیست. اجرای Mantis معمولاً پس از فهمیدن اصلاح باید به یک regression test کوچک‌تر تبدیل شود. +- Mantis gate سریع و معمول CI نیست. کندتر است، از اعتبارنامه‌های زنده استفاده می‌کند و برای باگ‌هایی نگه داشته می‌شود که محیط زنده در آن‌ها مهم است. +- Mantis نباید برای عملکرد عادی به انسان نیاز داشته باشد. VNC دستی مسیر نجات است، نه مسیر مطلوب. +- Mantis secretهای خام را در artifacts، logها، screenshotها، گزارش‌های Markdown یا دیدگاه‌های PR ذخیره نمی‌کند. ## مالکیت -Mantis در پشتهٔ QA OpenClaw قرار دارد. +Mantis در پشته QA OpenClaw قرار دارد. -- OpenClaw مالک runtime سناریو، adapterهای transport، schema شواهد، و CLI محلی زیر `pnpm openclaw qa mantis` است. -- QA Lab مالک قطعه‌های harness مربوط به transport زنده، helperهای ثبت مرورگر، و writerهای artifact است. -- Crabbox مالک ماشین‌های Linux گرم‌شده وقتی به VM راه‌دور نیاز باشد است. -- GitHub Actions مالک نقطهٔ ورود workflow راه‌دور و نگه‌داری artifact است. -- ClawSweeper مالک مسیریابی دیدگاه‌های GitHub است: parse کردن فرمان‌های نگه‌دارنده، dispatch کردن workflow، و ارسال دیدگاه نهایی PR. -- agentهای OpenClaw وقتی یک سناریو به راه‌اندازی agentic، اشکال‌زدایی، یا گزارش وضعیت گیرکرده نیاز دارد، Mantis را از طریق Codex هدایت می‌کنند. +- OpenClaw مالک runtime سناریو، adapterهای transport، schema شواهد و CLI محلی زیر `pnpm openclaw qa mantis` است. +- QA Lab مالک قطعات harness مربوط به transport زنده، helperهای ثبت مرورگر و نویسنده‌های artifact است. +- Crabbox مالک ماشین‌های Linux گرم‌شده است وقتی به VM راه دور نیاز باشد. +- GitHub Actions مالک نقطه ورود workflow راه دور و نگه‌داری artifact است. +- ClawSweeper مالک مسیریابی دیدگاه‌های GitHub است: parse کردن فرمان‌های نگه‌دارنده، dispatch کردن workflow و ارسال دیدگاه نهایی PR. +- agentهای OpenClaw وقتی یک سناریو به راه‌اندازی agentic، debugging یا گزارش وضعیت گیرکرده نیاز دارد، Mantis را از طریق Codex هدایت می‌کنند. -این مرز دانش transport را در OpenClaw، زمان‌بندی ماشین را در Crabbox، و چسب workflow نگه‌دارنده را در ClawSweeper نگه می‌دارد. +این مرز، دانش transport را در OpenClaw، زمان‌بندی ماشین را در Crabbox و چسب workflow نگه‌دارنده را در ClawSweeper نگه می‌دارد. ## شکل فرمان -نخستین فرمان محلی، bot در Discord، guild، کانال، ارسال پیام، ارسال واکنش، و مسیر artifact را راستی‌آزمایی می‌کند: +نخستین فرمان محلی، بات Discord، guild، کانال، ارسال پیام، ارسال reaction و مسیر artifact را راستی‌آزمایی می‌کند: ```bash pnpm openclaw qa mantis discord-smoke \ @@ -70,7 +70,7 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -runner زیر دایرکتوری خروجی، worktreeهای جداشدهٔ baseline و candidate می‌سازد، وابستگی‌ها را نصب می‌کند، هر ref را build می‌کند، سناریو را با `--allow-failures` اجرا می‌کند، سپس `baseline/`، `candidate/`، `comparison.json`، و `mantis-report.md` را می‌نویسد. برای نخستین سناریوی Discord، راستی‌آزمایی موفق یعنی وضعیت baseline برابر `fail` و وضعیت candidate برابر `pass` است. +runner، worktreeهای detached مبنا و نامزد را زیر دایرکتوری خروجی می‌سازد، dependencyها را نصب می‌کند، هر ref را build می‌کند، سناریو را با `--allow-failures` اجرا می‌کند، سپس `baseline/`، `candidate/`، `comparison.json` و `mantis-report.md` را می‌نویسد. برای نخستین سناریوی Discord، راستی‌آزمایی موفق یعنی وضعیت مبنا `fail` و وضعیت نامزد `pass` است. نخستین primitive مربوط به VM/مرورگر، smoke دسکتاپ است: @@ -79,22 +79,55 @@ pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -این فرمان یک ماشین دسکتاپ Crabbox را اجاره می‌کند یا دوباره به‌کار می‌گیرد، یک مرورگر قابل مشاهده را داخل نشست VNC شروع می‌کند، دسکتاپ را ثبت می‌کند، artifactها را به دایرکتوری خروجی محلی برمی‌گرداند، و فرمان reconnect را داخل گزارش می‌نویسد. فرمان به‌صورت پیش‌فرض از provider Hetzner استفاده می‌کند، چون نخستین provider با پوشش کارآمد دسکتاپ/VNC در مسیر Mantis است. هنگام اجرا روی fleet دیگری از Crabbox، آن را با `--provider`، `--crabbox-bin`، یا `OPENCLAW_MANTIS_CRABBOX_PROVIDER` override کنید. +این فرمان یک ماشین دسکتاپ Crabbox را lease یا بازاستفاده می‌کند، مرورگری قابل مشاهده را داخل نشست VNC شروع می‌کند، دسکتاپ را ثبت می‌کند، artifacts را به دایرکتوری خروجی محلی برمی‌گرداند و فرمان reconnect را در گزارش می‌نویسد. فرمان به‌صورت پیش‌فرض از provider Hetzner استفاده می‌کند چون نخستین provider با پوشش دسکتاپ/VNC فعال در مسیر Mantis است. هنگام اجرا روی fleet دیگری از Crabbox، آن را با `--provider`، `--crabbox-bin` یا `OPENCLAW_MANTIS_CRABBOX_PROVIDER` override کنید. flagهای مفید smoke دسکتاپ: -- `--lease-id ` یا `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` یک دسکتاپ گرم‌شده را دوباره به‌کار می‌گیرد. +- `--lease-id ` یا `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` یک دسکتاپ گرم‌شده را بازاستفاده می‌کند. - `--browser-url ` صفحه‌ای را که در مرورگر قابل مشاهده باز می‌شود تغییر می‌دهد. -- `--html-file ` یک artifact HTML محلی repo را در مرورگر قابل مشاهده render می‌کند. Mantis از این برای ثبت timeline تولیدشدهٔ واکنش‌های وضعیت Discord از طریق یک دسکتاپ واقعی Crabbox استفاده می‌کند. -- `--keep-lease` یا `OPENCLAW_MANTIS_KEEP_VM=1` یک lease تازه‌ساخته و موفق را برای بررسی VNC باز نگه می‌دارد. اجراهای ناموفق وقتی lease ساخته شده باشد به‌صورت پیش‌فرض آن را نگه می‌دارند تا یک operator بتواند دوباره وصل شود. -- `--class`، `--idle-timeout`، و `--ttl` اندازهٔ ماشین و طول عمر lease را تنظیم می‌کنند. +- `--html-file ` یک artifact HTML محلی repo را در مرورگر قابل مشاهده render می‌کند. Mantis از این برای ثبت timeline تولیدشده reactionهای وضعیت Discord از طریق یک دسکتاپ واقعی Crabbox استفاده می‌کند. +- `--keep-lease` یا `OPENCLAW_MANTIS_KEEP_VM=1` یک lease تازه‌ساخته و موفق را برای بررسی VNC باز نگه می‌دارد. اجراهای ناموفق به‌صورت پیش‌فرض وقتی lease ساخته شده باشد آن را نگه می‌دارند تا اپراتور بتواند دوباره وصل شود. +- `--class`، `--idle-timeout` و `--ttl` اندازه ماشین و عمر lease را تنظیم می‌کنند. -workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow قبل و بعد GitHub برای نخستین سناریوی واقعی برابر `Mantis Discord Status Reactions` است. این workflow موارد زیر را می‌پذیرد: +نخستین primitive کامل transport دسکتاپ، smoke دسکتاپ Slack است: -- `baseline_ref`: همان ref که انتظار می‌رود رفتار فقط queued را بازتولید کند. -- `candidate_ref`: همان ref که انتظار می‌رود `queued -> thinking -> done` را نشان دهد. +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --output-dir .artifacts/qa-e2e/mantis/slack-desktop \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` -این workflow، ref مربوط به harness workflow را checkout می‌کند، worktreeهای جداگانهٔ baseline و candidate را build می‌کند، `discord-status-reactions-tool-only` را روی هر worktree اجرا می‌کند، و `baseline/`، `candidate/`، `comparison.json`، و `mantis-report.md` را به‌عنوان artifactهای Actions upload می‌کند. همچنین HTML timeline هر مسیر را در مرورگر دسکتاپ Crabbox render می‌کند و آن screenshotهای VNC را کنار PNGهای قطعی timeline در دیدگاه PR منتشر می‌کند. workflow، CLI مربوط به Crabbox را از main در `openclaw/crabbox` build می‌کند تا بتواند از flagهای فعلی lease دسکتاپ/مرورگر پیش از انتشار binary بعدی Crabbox استفاده کند. +این فرمان یک ماشین دسکتاپ Crabbox را lease یا بازاستفاده می‌کند، checkout فعلی را داخل VM همگام می‌کند، `pnpm openclaw qa slack` را داخل آن VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، دسکتاپ قابل مشاهده را ثبت می‌کند و هم artifacts مربوط به Slack QA و هم screenshot مربوط به VNC را به دایرکتوری خروجی محلی کپی می‌کند. این نخستین شکل Mantis است که در آن Gateway متعلق به SUT OpenClaw و مرورگر هر دو داخل همان VM دسکتاپ Linux زندگی می‌کنند. + +با `--gateway-setup`، فرمان یک خانه OpenClaw یک‌بارمصرف و پایدار در `$HOME/.openclaw-mantis/slack-openclaw` آماده می‌کند، پیکربندی Slack Socket Mode را برای کانال انتخاب‌شده patch می‌کند، `openclaw gateway run` را روی port `38973` شروع می‌کند و Chrome را در نشست VNC در حال اجرا نگه می‌دارد. این حالت «برایم یک دسکتاپ Linux با Slack و یک claw در حال اجرا بگذار» است؛ مسیر Slack QA بات‌به‌بات وقتی `--gateway-setup` حذف شود همچنان پیش‌فرض است. + +ورودی‌های لازم برای `--credential-source env`: + +- `OPENCLAW_QA_SLACK_CHANNEL_ID` +- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` +- `OPENCLAW_LIVE_OPENAI_KEY` برای مسیر مدل راه دور. اگر فقط + `OPENAI_API_KEY` به‌صورت محلی تنظیم شده باشد، Mantis پیش از فراخوانی Crabbox آن را به `OPENCLAW_LIVE_OPENAI_KEY` map می‌کند تا forwarding envهای `OPENCLAW_*` در Crabbox بتواند آن را به VM منتقل کند. + +flagهای مفید دسکتاپ Slack: + +- `--lease-id ` اجرا را روی ماشینی تکرار می‌کند که اپراتور قبلاً از طریق VNC وارد Slack Web شده است. +- `--gateway-setup` به‌جای فقط اجرای مسیر QA بات‌به‌بات، یک Gateway پایدار OpenClaw Slack را در VM شروع می‌کند. +- `--slack-url ` یک URL مشخص Slack Web را باز می‌کند. بدون آن، Mantis وقتی token بات SUT موجود باشد، `https://app.slack.com/client//` را از Slack `auth.test` استخراج می‌کند. +- `--slack-channel-id ` allowlist کانال Slack را که setup مربوط به gateway استفاده می‌کند کنترل می‌کند. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` پروفایل پایدار Chrome داخل VM را کنترل می‌کند. پیش‌فرض `$HOME/.config/openclaw-mantis/slack-chrome-profile` است، پس ورود دستی Slack Web روی همان lease در اجراهای دوباره باقی می‌ماند. +- `--credential-source convex --credential-role ci` به‌جای tokenهای مستقیم env مربوط به Slack، از pool اعتبارنامه مشترک استفاده می‌کند. +- `--provider-mode`، `--model`، `--alt-model` و `--fast` به مسیر زنده Slack pass-through می‌شوند. + +workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow قبل و بعد در GitHub برای نخستین سناریوی واقعی برابر `Mantis Discord Status Reactions` است. این ورودی‌ها را می‌پذیرد: + +- `baseline_ref`: refای که انتظار می‌رود رفتار فقط queued را بازتولید کند. +- `candidate_ref`: refای که انتظار می‌رود `queued -> thinking -> done` را نشان دهد. + +این workflow، ref مربوط به harness workflow را checkout می‌کند، worktreeهای جداگانه مبنا و نامزد را build می‌کند، `discord-status-reactions-tool-only` را روی هر worktree اجرا می‌کند و `baseline/`، `candidate/`، `comparison.json` و `mantis-report.md` را به‌عنوان artifacts در Actions upload می‌کند. همچنین HTML مربوط به timeline هر مسیر را در یک مرورگر دسکتاپ Crabbox render می‌کند و آن screenshotهای VNC را کنار PNGهای deterministic timeline در دیدگاه PR منتشر می‌کند. workflow، CLI مربوط به Crabbox را از main در `openclaw/crabbox` build می‌کند تا بتواند پیش از انتشار binary بعدی Crabbox از flagهای فعلی lease دسکتاپ/مرورگر استفاده کند. همچنین می‌توانید اجرای status-reactions را مستقیماً از یک دیدگاه PR trigger کنید: @@ -102,7 +135,7 @@ workflow smoke در GitHub برابر `Mantis Discord Smoke` است. workflow ق @Mantis discord status reactions ``` -trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌های pull request از کاربرانی با دسترسی write، maintain، یا admin اجرا می‌شود، و فقط درخواست‌های مربوط به واکنش وضعیت Discord را تشخیص می‌دهد. به‌صورت پیش‌فرض، از ref مبنای خرابِ شناخته‌شده و SHA مربوط به head فعلی PR به‌عنوان candidate استفاده می‌کند. نگه‌دارنده‌ها می‌توانند هر دو ref را override کنند: +trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌های pull request از کاربرانی با دسترسی write، maintain یا admin اجرا می‌شود و فقط درخواست‌های status-reaction مربوط به Discord را تشخیص می‌دهد. به‌صورت پیش‌فرض از ref مبنای شناخته‌شده معیوب و SHA فعلی head در PR به‌عنوان نامزد استفاده می‌کند. نگه‌دارنده‌ها می‌توانند هر کدام از refها را override کنند: ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -115,43 +148,43 @@ trigger دیدگاه عمداً محدود است. فقط روی دیدگاه‌ @clawsweeper verify e2e discord ``` -فرمان اول صریح و متمرکز بر سناریو است. فرمان دوم می‌تواند بعداً یک PR یا issue را از روی labelها، فایل‌های تغییرکرده، و یافته‌های review در ClawSweeper به سناریوهای پیشنهادی Mantis نگاشت کند. +فرمان اول explicit و متمرکز بر سناریو است. فرمان دوم می‌تواند بعداً یک PR یا issue را از روی labelها، فایل‌های تغییریافته و یافته‌های review در ClawSweeper به سناریوهای پیشنهادی Mantis map کند. -## چرخهٔ اجرای +## چرخه عمر اجرا -1. دریافت credentialها. -2. تخصیص یا استفادهٔ دوباره از یک VM. -3. آماده‌سازی profile دسکتاپ/مرورگر وقتی سناریو به شواهد رابط کاربری نیاز دارد. +1. گرفتن اعتبارنامه‌ها. +2. تخصیص یا بازاستفاده از یک VM. +3. آماده‌سازی پروفایل دسکتاپ/مرورگر وقتی سناریو به شواهد UI نیاز دارد. 4. آماده‌سازی یک checkout تمیز برای ref مبنا. -5. نصب وابستگی‌ها و build فقط آنچه سناریو نیاز دارد. -6. شروع یک OpenClaw Gateway فرزند با دایرکتوری وضعیت ایزوله. -7. پیکربندی transport زنده، provider، model، و profile مرورگر. -8. اجرای سناریو و ثبت شواهد baseline. +5. نصب dependencyها و build کردن فقط آنچه سناریو نیاز دارد. +6. شروع یک Gateway فرزند OpenClaw با دایرکتوری وضعیت ایزوله. +7. پیکربندی transport زنده، provider، مدل و پروفایل مرورگر. +8. اجرای سناریو و ثبت شواهد مبنا. 9. توقف gateway و حفظ logها. 10. آماده‌سازی ref نامزد در همان VM. -11. اجرای همان سناریو و ثبت شواهد candidate. -12. مقایسهٔ نتایج oracle و شواهد دیداری. -13. نوشتن Markdown، JSON، logها، screenshotها، و artifactهای trace اختیاری. -14. upload کردن artifactهای GitHub Actions. -15. ارسال یک پیام وضعیت کوتاه در PR یا Discord. +11. اجرای همان سناریو و ثبت شواهد نامزد. +12. مقایسه نتایج oracle و شواهد بصری. +13. نوشتن Markdown، JSON، logها، screenshotها و artifacts اختیاری trace. +14. upload کردن artifacts در GitHub Actions. +15. ارسال یک پیام وضعیت مختصر در PR یا Discord. -سناریو باید بتواند به دو شکل متفاوت شکست بخورد: +سناریو باید بتواند به دو روش متفاوت fail شود: -- **بازتولید باگ**: baseline به شکل مورد انتظار شکست خورده است. -- **شکست harness**: راه‌اندازی محیط، credentialها، Discord API، مرورگر، یا provider پیش از معنادار شدن oracle باگ شکست خورده است. +- **باگ بازتولید شد**: مبنا به روش مورد انتظار fail شد. +- **شکست harness**: راه‌اندازی محیط، اعتبارنامه‌ها، Discord API، مرورگر یا provider پیش از معنادار شدن oracle باگ fail شد. گزارش نهایی باید این موارد را جدا کند تا نگه‌دارنده‌ها محیط ناپایدار را با رفتار محصول اشتباه نگیرند. -## MVP در Discord +## Discord MVP -نخستین سناریو باید واکنش‌های وضعیت Discord را در کانال‌های guild هدف بگیرد، جایی که حالت تحویل پاسخ منبع `message_tool_only` است. +نخستین سناریو باید reactionهای وضعیت Discord را در کانال‌های guild هدف بگیرد، جایی که حالت تحویل پاسخ منبع `message_tool_only` است. -چرا seed خوبی برای Mantis است: +چرا بذر خوبی برای Mantis است: -- در Discord به‌صورت واکنش روی پیام triggerکننده قابل مشاهده است. -- از طریق وضعیت واکنش پیام Discord یک oracle قوی REST دارد. -- یک OpenClaw Gateway واقعی، احراز هویت bot در Discord، dispatch پیام، حالت تحویل پاسخ منبع، وضعیت واکنش وضعیت، و چرخهٔ عمر turn در model را تمرین می‌دهد. -- به‌اندازهٔ کافی محدود است تا نخستین پیاده‌سازی دقیق بماند. +- در Discord به‌صورت reaction روی پیام triggerکننده قابل مشاهده است. +- از طریق وضعیت reaction پیام در Discord یک oracle قوی REST دارد. +- یک Gateway واقعی OpenClaw، احراز هویت بات Discord، dispatch پیام، حالت تحویل پاسخ منبع، وضعیت reaction وضعیت و چرخه عمر turn مدل را تمرین می‌دهد. +- به‌اندازه کافی محدود است تا نخستین پیاده‌سازی را درست و صادق نگه دارد. شکل مورد انتظار سناریو: @@ -184,9 +217,9 @@ evidence: screenshotMessageRow: true ``` -شواهد baseline باید واکنش acknowledgement مربوط به queued را نشان دهد اما در حالت tool-only هیچ transition چرخهٔ عمر نداشته باشد. شواهد candidate باید نشان دهد واکنش‌های وضعیت چرخهٔ عمر وقتی `messages.statusReactions.enabled` به‌صورت صریح true است اجرا می‌شوند. +شواهد مبنا باید reaction تأیید queued را نشان دهد اما در حالت فقط tool هیچ lifecycle transition نشان ندهد. شواهد نامزد باید نشان دهد که status reactionهای چرخه عمر وقتی `messages.statusReactions.enabled` صریحاً true است اجرا می‌شوند. -نخستین بخش اجرایی، سناریوی QA زندهٔ Discord به‌صورت opt-in است: +نخستین برش قابل اجرا، سناریوی opt-in زنده QA در Discord است: ```bash pnpm openclaw qa discord \ @@ -198,24 +231,32 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -این SUT را با رسیدگی همیشه‌روشن به guild، `visibleReplies: -"message_tool"`، `ackReaction: "👀"`، و واکنش‌های وضعیت صریح پیکربندی می‌کند. oracle پیام triggerکنندهٔ واقعی Discord را poll می‌کند و sequence مشاهده‌شدهٔ `👀 -> 🤔 -> 👍` را انتظار دارد. artifactها شامل `discord-qa-reaction-timelines.json`، `discord-status-reactions-tool-only-timeline.html`، و `discord-status-reactions-tool-only-timeline.png` هستند. +این کار SUT را با رسیدگی همیشه‌فعال به guild، `visibleReplies: +"message_tool"`، `ackReaction: "👀"` و واکنش‌های وضعیت صریح پیکربندی می‌کند. اوراکل +پیام محرک واقعی Discord را نظرسنجی می‌کند و انتظار دارد توالی مشاهده‌شده +`👀 -> 🤔 -> 👍` باشد. مصنوعات شامل `discord-qa-reaction-timelines.json`، +`discord-status-reactions-tool-only-timeline.html` و +`discord-status-reactions-tool-only-timeline.png` هستند. -## قطعه‌های موجود QA +## اجزای QA موجود -Mantis باید به‌جای شروع از صفر، روی پشتهٔ خصوصی QA موجود ساخته شود: +Mantis باید به‌جای شروع از صفر، بر پشته QA خصوصی موجود بنا شود: -- `pnpm openclaw qa discord` از قبل یک مسیر زندهٔ Discord را با botهای driver و SUT اجرا می‌کند. -- runner مربوط به transport زنده از قبل گزارش‌ها و artifactهای observed-message را زیر `.artifacts/qa-e2e/` می‌نویسد. -- leaseهای credential در Convex از قبل دسترسی انحصاری به credentialهای transport زندهٔ مشترک را فراهم می‌کنند. -- سرویس کنترل مرورگر از قبل از screenshotها، snapshotها، profileهای مدیریت‌شدهٔ headless، و profileهای CDP راه‌دور پشتیبانی می‌کند. -- QA Lab از قبل یک رابط کاربری debugger و bus برای تست‌هایی با شکل transport دارد. +- `pnpm openclaw qa discord` از قبل یک مسیر زنده Discord را با ربات‌های محرک و + SUT اجرا می‌کند. +- اجراکننده انتقال زنده از قبل گزارش‌ها و مصنوعات پیام مشاهده‌شده را زیر + `.artifacts/qa-e2e/` می‌نویسد. +- اجاره‌های اعتبارنامه Convex از قبل دسترسی انحصاری به اعتبارنامه‌های انتقال زنده مشترک را فراهم می‌کنند. +- سرویس کنترل مرورگر از قبل از نماگرفت‌ها، snapshotها، + پروفایل‌های مدیریت‌شده headless و پروفایل‌های CDP راه‌دور پشتیبانی می‌کند. +- QA Lab از قبل یک رابط کاربری اشکال‌زدا و گذرگاه برای آزمون‌هایی با شکل انتقال دارد. -نخستین پیاده‌سازی Mantis می‌تواند یک runner نازک قبل/بعد روی این قطعه‌ها، به‌علاوهٔ یک لایهٔ شواهد دیداری باشد. +پیاده‌سازی اول Mantis می‌تواند یک اجراکننده نازک قبل/بعد روی همین اجزا، +به‌علاوه یک لایه شواهد بصری باشد. ## مدل شواهد -هر اجرا یک دایرکتوری artifact پایدار می‌نویسد: +هر اجرا یک پوشه مصنوع پایدار می‌نویسد: ```text .artifacts/qa-e2e/mantis// @@ -235,63 +276,77 @@ Mantis باید به‌جای شروع از صفر، روی پشتهٔ خصوص run.log ``` -`mantis-summary.json` باید منبع حقیقت machine-readable باشد. گزارش Markdown برای دیدگاه‌های PR و review انسانی است. +`mantis-summary.json` باید منبع حقیقت قابل‌خواندن برای ماشین باشد. گزارش +Markdown برای نظرهای PR و بازبینی انسانی است. -summary باید شامل این موارد باشد: +خلاصه باید شامل موارد زیر باشد: -- refها و SHAهای تست‌شده -- transport و شناسهٔ سناریو -- provider ماشین و شناسهٔ ماشین یا شناسهٔ lease -- منبع credential بدون مقادیر secret -- نتیجهٔ baseline -- نتیجهٔ candidate +- refها و SHAهای آزموده‌شده +- انتقال و شناسه سناریو +- ارائه‌دهنده ماشین و شناسه ماشین یا شناسه اجاره +- منبع اعتبارنامه بدون مقادیر محرمانه +- نتیجه baseline +- نتیجه candidate - اینکه آیا باگ روی baseline بازتولید شد یا نه -- اینکه آیا candidate آن را اصلاح کرد یا نه -- مسیرهای artifact -- مشکلات setup یا cleanup پاک‌سازی‌شده +- اینکه آیا candidate آن را رفع کرد یا نه +- مسیرهای مصنوع +- مشکلات راه‌اندازی یا پاک‌سازی پالایش‌شده -screenshotها شواهد هستند، نه secret. بااین‌حال همچنان به انضباط redaction نیاز دارند: نام کانال‌های خصوصی، نام کاربران، یا محتوای پیام ممکن است ظاهر شود. برای PRهای عمومی، تا زمانی که داستان redaction قوی‌تر شود، linkهای artifact در GitHub Actions را به imageهای inline ترجیح دهید. +نماگرفت‌ها شواهد هستند، نه راز. بااین‌حال همچنان به انضباط ویرایش محرمانگی نیاز دارند: +نام کانال‌های خصوصی، نام کاربران یا محتوای پیام ممکن است ظاهر شود. برای PRهای عمومی، +تا زمانی که داستان ویرایش محرمانگی قوی‌تر نشده است، پیوندهای مصنوع GitHub Actions را +به تصویرهای درون‌خطی ترجیح دهید. ## مرورگر و VNC مسیر مرورگر دو حالت دارد: -- **خودکارسازی headless**: پیش‌فرض برای CI. Chrome با CDP فعال اجرا می‌شود، و Playwright یا کنترل مرورگر OpenClaw screenshotها را ثبت می‌کند. -- **نجات با VNC**: روی همان VM فعال می‌شود وقتی ورود، MFA، ضدخودکارسازی Discord، یا اشکال‌زدایی دیداری به انسان نیاز دارد. +- **خودکارسازی headless**: پیش‌فرض برای CI. Chrome با CDP فعال اجرا می‌شود، و + Playwright یا کنترل مرورگر OpenClaw نماگرفت‌ها را ثبت می‌کند. +- **نجات VNC**: روی همان VM فعال می‌شود وقتی ورود، MFA، ضدخودکارسازی Discord، + یا اشکال‌زدایی بصری به انسان نیاز دارد. -پروفایل مرورگر ناظر Discord باید آن‌قدر پایدار باشد که برای هر اجرا نیاز به ورود دوباره نباشد، اما از وضعیت مرورگر شخصی جدا باشد. یک پروفایل به استخر ماشین Mantis تعلق دارد، نه به لپ‌تاپ یک توسعه‌دهنده. +پروفایل مرورگر ناظر Discord باید به‌اندازه‌ای پایدار باشد که برای هر اجرا نیاز به +ورود دوباره نباشد، اما از وضعیت مرورگر شخصی جدا باشد. یک پروفایل متعلق به مخزن ماشین +Mantis است، نه لپ‌تاپ توسعه‌دهنده. -وقتی Mantis گیر می‌کند، یک پیام وضعیت Discord ارسال می‌کند که شامل این موارد است: +وقتی Mantis گیر می‌کند، یک پیام وضعیت Discord با این موارد ارسال می‌کند: - شناسه اجرا - شناسه سناریو - ارائه‌دهنده ماشین -- دایرکتوری آرتیفکت +- پوشه مصنوع - دستورالعمل‌های اتصال VNC یا noVNC در صورت وجود -- متن کوتاه مانع +- متن کوتاه مسدودکننده -اولین استقرار خصوصی می‌تواند این پیام‌ها را در کانال فعلی اپراتورها ارسال کند و بعدا به یک کانال اختصاصی Mantis منتقل شود. +استقرار خصوصی اول می‌تواند این پیام‌ها را در کانال عملیاتی موجود ارسال کند و بعدا +به یک کانال اختصاصی Mantis منتقل شود. ## ماشین‌ها -Mantis باید برای اولین پیاده‌سازی راه‌دور، AWS از طریق Crabbox را ترجیح دهد. Crabbox ماشین‌های آماده، رهگیری اجاره، آماده‌سازی، لاگ‌ها، نتایج و پاک‌سازی را در اختیار ما می‌گذارد. اگر ظرفیت AWS بیش از حد کند یا ناموجود بود، یک ارائه‌دهنده Hetzner پشت همان رابط ماشین اضافه کنید. +Mantis باید برای اولین پیاده‌سازی راه‌دور، AWS از طریق Crabbox را ترجیح دهد. +Crabbox ماشین‌های آماده، رهگیری اجاره، آب‌رسانی، لاگ‌ها، نتایج و پاک‌سازی را در اختیارمان می‌گذارد. +اگر ظرفیت AWS بیش‌ازحد کند یا در دسترس نبود، یک ارائه‌دهنده Hetzner پشت همان +رابط ماشین اضافه کنید. -حداقل نیازمندی‌های VM: +حداقل الزامات VM: -- Linux با نصب Chrome یا Chromium که قابلیت دسکتاپ داشته باشد +- Linux با نصب Chrome یا Chromium مناسب دسکتاپ - دسترسی CDP برای خودکارسازی مرورگر -- VNC یا noVNC برای بازیابی +- VNC یا noVNC برای نجات - Node 22 و pnpm -- checkout از OpenClaw و کش وابستگی‌ها -- کش مرورگر Playwright Chromium وقتی از Playwright استفاده می‌شود +- checkout مربوط به OpenClaw و cache وابستگی‌ها +- cache مرورگر Playwright Chromium وقتی از Playwright استفاده می‌شود - CPU و حافظه کافی برای یک OpenClaw Gateway، یک مرورگر، و یک اجرای مدل - دسترسی خروجی به Discord، GitHub، ارائه‌دهندگان مدل، و کارگزار اعتبارنامه -VM نباید رازهای خام بلندمدت را بیرون از مخزن‌های مورد انتظار اعتبارنامه یا پروفایل مرورگر نگه دارد. +VM نباید رازهای خام بلندمدت را بیرون از مخزن‌های مورد انتظار اعتبارنامه یا +پروفایل مرورگر نگه دارد. ## رازها -رازها برای اجراهای راه‌دور در رازهای سازمان یا مخزن GitHub، و برای اجراهای محلی در یک فایل راز محلی تحت کنترل اپراتور نگهداری می‌شوند. +رازها برای اجراهای راه‌دور در رازهای سازمان یا مخزن GitHub، و برای اجراهای محلی در +یک فایل راز تحت کنترل اپراتور محلی قرار می‌گیرند. نام‌های پیشنهادی رازها: @@ -301,34 +356,51 @@ VM نباید رازهای خام بلندمدت را بیرون از مخزن - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` برای بارگذاری آرتیفکت‌های عمومی GitHub +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` برای بارگذاری مصنوعات عمومی GitHub - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -در بلندمدت، استخر اعتبارنامه Convex باید منبع عادی برای اعتبارنامه‌های انتقال زنده باقی بماند. رازهای GitHub کارگزار و مسیرهای fallback را راه‌اندازی اولیه می‌کنند. گردش‌کار واکنش‌های وضعیت Discord رازهای Mantis Crabbox را دوباره به متغیرهای محیطی `CRABBOX_COORDINATOR` و `CRABBOX_COORDINATOR_TOKEN` که CLI مربوط به Crabbox انتظار دارد نگاشت می‌کند. نام‌های ساده راز GitHub با الگوی `CRABBOX_*` همچنان به‌عنوان fallback سازگاری پذیرفته می‌شوند. +در بلندمدت، مخزن اعتبارنامه Convex باید منبع عادی اعتبارنامه‌های انتقال زنده باقی بماند. +رازهای GitHub کارگزار و مسیرهای fallback را راه‌اندازی اولیه می‌کنند. +گردش‌کار واکنش‌های وضعیت Discord رازهای Mantis Crabbox را دوباره به متغیرهای محیطی +`CRABBOX_COORDINATOR` و `CRABBOX_COORDINATOR_TOKEN` نگاشت می‌کند که CLI مربوط به Crabbox انتظار دارد. +نام‌های ساده راز GitHub با الگوی `CRABBOX_*` همچنان به‌عنوان fallback سازگاری پذیرفته می‌شوند. -اجراکننده Mantis هرگز نباید این موارد را چاپ کند: +اجراکننده Mantis هرگز نباید موارد زیر را چاپ کند: - توکن‌های ربات Discord - کلیدهای API ارائه‌دهنده -- کوکی‌های مرورگر +- cookieهای مرورگر - محتوای پروفایل احراز هویت - گذرواژه‌های VNC - payloadهای خام اعتبارنامه -بارگذاری آرتیفکت‌های عمومی باید فراداده هدف Discord مانند شناسه‌های ربات، guild، کانال و پیام را نیز حذف کند. گردش‌کار smoke در GitHub به همین دلیل `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` را فعال می‌کند. +بارگذاری‌های مصنوع عمومی همچنین باید فراداده هدف Discord مانند شناسه‌های ربات، +guild، کانال و پیام را ویرایش محرمانه کنند. گردش‌کار smoke GitHub به همین دلیل +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` را فعال می‌کند. -اگر یک توکن تصادفا در issue، PR، چت یا لاگ چسبانده شد، پس از ذخیره شدن راز جدید، آن را چرخش دهید. +اگر توکنی به‌طور تصادفی در یک issue، PR، chat یا log جای‌گذاری شد، پس از ذخیره شدن +راز جدید آن را بچرخانید. -## آرتیفکت‌های GitHub و دیدگاه‌های PR +## مصنوعات GitHub و نظرهای PR -گردش‌کارهای Mantis باید بسته کامل شواهد را به‌عنوان یک آرتیفکت کوتاه‌مدت Actions بارگذاری کنند. وقتی گردش‌کار برای یک گزارش باگ یا PR اصلاح اجرا می‌شود، باید اسکرین‌شات‌های PNG حذف‌اطلاعات‌شده را نیز در شاخه `qa-artifacts` منتشر کند و روی همان باگ یا PR اصلاح، یک دیدگاه با اسکرین‌شات‌های درون‌خطی قبل/بعد درج یا به‌روزرسانی کند. اثبات اصلی را فقط روی یک PR عمومی خودکارسازی QA منتشر نکنید. لاگ‌های خام، پیام‌های مشاهده‌شده و شواهد حجیم دیگر در آرتیفکت Actions باقی می‌مانند. +گردش‌کارهای Mantis باید بسته کامل شواهد را به‌عنوان یک مصنوع کوتاه‌عمر Actions +بارگذاری کنند. وقتی گردش‌کار برای گزارش باگ یا PR رفع اجرا می‌شود، باید +نماگرفت‌های PNG ویرایش محرمانه‌شده را نیز در شاخه `qa-artifacts` منتشر کند و +روی آن باگ یا PR رفع، نظری با نماگرفت‌های قبل/بعد درون‌خطی upsert کند. اثبات اصلی را +فقط روی یک PR عمومی خودکارسازی QA منتشر نکنید. لاگ‌های خام، پیام‌های مشاهده‌شده، +و شواهد حجیم دیگر در مصنوع Actions باقی می‌مانند. -گردش‌کارهای تولیدی باید این دیدگاه‌ها را با Mantis GitHub App ارسال کنند، نه با `github-actions[bot]`. شناسه app و کلید خصوصی را به‌عنوان رازهای GitHub Actions با نام‌های `MANTIS_GITHUB_APP_ID` و `MANTIS_GITHUB_APP_PRIVATE_KEY` ذخیره کنید. گردش‌کار از یک marker پنهان به‌عنوان کلید upsert استفاده می‌کند، وقتی توکن بتواند آن را ویرایش کند همان دیدگاه را به‌روزرسانی می‌کند، و وقتی marker قدیمی متعلق به ربات قابل ویرایش نیست یک دیدگاه جدید متعلق به Mantis می‌سازد. +گردش‌کارهای production باید آن نظرها را با Mantis GitHub App منتشر کنند، نه با +`github-actions[bot]`. شناسه app و کلید خصوصی را به‌عنوان رازهای GitHub Actions +با نام‌های `MANTIS_GITHUB_APP_ID` و `MANTIS_GITHUB_APP_PRIVATE_KEY` ذخیره کنید. +گردش‌کار از یک نشانگر پنهان به‌عنوان کلید upsert استفاده می‌کند، وقتی توکن بتواند آن را +ویرایش کند همان نظر را به‌روزرسانی می‌کند، و وقتی نشانگر قدیمی متعلق به ربات قابل‌ویرایش +نباشد یک نظر جدید متعلق به Mantis ایجاد می‌کند. -دیدگاه PR باید کوتاه و تصویری باشد: +نظر PR باید کوتاه و بصری باشد: ```md Mantis Discord Status Reactions QA @@ -348,60 +420,69 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -وقتی اجرا به‌دلیل شکست harness ناموفق می‌شود، دیدگاه باید همین را بگوید و القا نکند که candidate شکست خورده است. +وقتی اجرا به دلیل شکست harness ناموفق می‌شود، نظر باید همین را بگوید، نه اینکه القا کند +candidate شکست خورده است. ## یادداشت‌های استقرار خصوصی -یک استقرار خصوصی ممکن است از قبل یک برنامه Discord برای Mantis داشته باشد. وقتی آن برنامه مجوزهای درست ربات را دارد و می‌توان آن را با ایمنی چرخش داد، به‌جای ساختن یک app دیگر، همان برنامه را دوباره استفاده کنید. +یک استقرار خصوصی ممکن است از قبل یک برنامه Discord مربوط به Mantis داشته باشد. وقتی آن برنامه +مجوزهای ربات درست را دارد و می‌توان آن را با اطمینان چرخاند، به‌جای ساختن app دیگر از همان استفاده کنید. -کانال اولیه اعلان اپراتور را از طریق رازها یا پیکربندی استقرار تنظیم کنید. این کانال ابتدا می‌تواند به یک کانال فعلی نگه‌دارندگان یا عملیات اشاره کند، سپس پس از ایجاد کانال اختصاصی Mantis به آن منتقل شود. +کانال اعلان اپراتور اولیه را از طریق رازها یا پیکربندی استقرار تنظیم کنید. +این کانال ابتدا می‌تواند به یک کانال نگه‌دارنده یا عملیات موجود اشاره کند، سپس پس از ایجاد +کانال اختصاصی Mantis به آن منتقل شود. -شناسه‌های guild، شناسه‌های کانال، توکن‌های ربات، کوکی‌های مرورگر یا گذرواژه‌های VNC را در این سند قرار ندهید. آن‌ها را در رازهای GitHub، کارگزار اعتبارنامه، یا مخزن راز محلی اپراتور ذخیره کنید. +شناسه‌های guild، شناسه‌های کانال، توکن‌های ربات، cookieهای مرورگر یا گذرواژه‌های VNC را +در این سند قرار ندهید. آن‌ها را در رازهای GitHub، کارگزار اعتبارنامه، یا مخزن راز محلی +اپراتور ذخیره کنید. ## افزودن یک سناریو -یک سناریوی Mantis باید این موارد را اعلان کند: +یک سناریوی Mantis باید موارد زیر را اعلام کند: - شناسه و عنوان - انتقال -- اعتبارنامه‌های موردنیاز -- سیاست ref خط مبنا -- سیاست ref candidate -- patch پیکربندی OpenClaw -- مراحل راه‌اندازی +- اعتبارنامه‌های لازم +- خط‌مشی ref مربوط به baseline +- خط‌مشی ref مربوط به candidate +- وصله پیکربندی OpenClaw +- گام‌های راه‌اندازی - محرک -- oracle مورد انتظار خط مبنا -- oracle مورد انتظار candidate +- اوراکل baseline مورد انتظار +- اوراکل candidate مورد انتظار - هدف‌های ثبت بصری - بودجه timeout -- مراحل پاک‌سازی +- گام‌های پاک‌سازی -سناریوها باید oracleهای کوچک و typed را ترجیح دهند: +سناریوها باید اوراکل‌های کوچک و typed را ترجیح دهند: - وضعیت واکنش Discord برای باگ‌های واکنش -- ارجاع‌های پیام Discord برای باگ‌های threading +- ارجاع‌های پیام Discord برای باگ‌های thread - thread ts و وضعیت API واکنش Slack برای باگ‌های Slack -- شناسه‌ها و headerهای پیام ایمیل برای باگ‌های ایمیل -- اسکرین‌شات‌های مرورگر وقتی UI تنها مشاهده‌پذیر قابل‌اعتماد است +- شناسه‌ها و headerهای پیام email برای باگ‌های email +- نماگرفت‌های مرورگر وقتی UI تنها مشاهده‌پذیر قابل‌اعتماد است -بررسی‌های بینایی باید افزایشی باشند. اگر یک API پلتفرم می‌تواند باگ را اثبات کند، از API به‌عنوان oracle قبولی/شکست استفاده کنید و اسکرین‌شات‌ها را برای اطمینان انسانی نگه دارید. +بررسی‌های بینایی باید افزایشی باشند. اگر یک API پلتفرم می‌تواند باگ را اثبات کند، +از API به‌عنوان اوراکل قبولی/ردی استفاده کنید و نماگرفت‌ها را برای اطمینان انسانی نگه دارید. ## گسترش ارائه‌دهنده -پس از Discord، همان اجراکننده می‌تواند این موارد را اضافه کند: +پس از Discord، همان اجراکننده می‌تواند موارد زیر را اضافه کند: -- Slack: واکنش‌ها، threadها، اشاره به app، modalها، بارگذاری فایل. -- ایمیل: احراز هویت Gmail و threading پیام با استفاده از `gog` در جاهایی که connectorها کافی نیستند. +- Slack: واکنش‌ها، threadها، mentionهای app، modalها، بارگذاری فایل. +- Email: احراز هویت Gmail و thread کردن پیام با استفاده از `gog` در جاهایی که connectorها کافی نیستند. - WhatsApp: ورود QR، شناسایی دوباره، تحویل پیام، رسانه، واکنش‌ها. -- Telegram: دروازه‌بانی mention گروه، commandها، واکنش‌ها در صورت وجود. -- Matrix: roomهای رمزنگاری‌شده، رابطه‌های thread یا reply، ازسرگیری پس از restart. +- Telegram: gating مربوط به mention گروه، فرمان‌ها، واکنش‌ها در صورت پشتیبانی. +- Matrix: اتاق‌های رمزگذاری‌شده، روابط thread یا reply، ازسرگیری پس از راه‌اندازی دوباره. -هر انتقال باید یک سناریوی smoke ارزان و یک یا چند سناریوی کلاس باگ داشته باشد. سناریوهای بصری پرهزینه باید opt-in باقی بمانند. +هر انتقال باید یک سناریوی smoke ارزان و یک یا چند سناریوی رده باگ داشته باشد. +سناریوهای بصری پرهزینه باید opt-in باقی بمانند. ## پرسش‌های باز -- وقتی ربات فعلی Mantis دوباره استفاده می‌شود، کدام ربات Discord باید driver باشد و کدام باید SUT باشد؟ -- ورود مرورگر ناظر در فاز اول باید از حساب انسانی Discord، حساب آزمایشی، یا فقط شواهد REST قابل‌خواندن توسط ربات استفاده کند؟ -- GitHub چه مدت باید آرتیفکت‌های Mantis را برای PRها نگه دارد؟ -- چه زمانی ClawSweeper باید به‌جای انتظار برای command نگه‌دارنده، Mantis را به‌صورت خودکار پیشنهاد کند؟ -- آیا اسکرین‌شات‌ها باید پیش از بارگذاری برای PRهای عمومی حذف‌اطلاعات یا برش داده شوند؟ +- وقتی ربات موجود Mantis دوباره استفاده می‌شود، کدام ربات Discord باید driver باشد و کدام باید SUT باشد؟ +- ورود مرورگر ناظر باید در فاز اول از حساب انسانی Discord، حساب test، + یا فقط شواهد REST قابل‌خواندن برای ربات استفاده کند؟ +- GitHub باید مصنوعات Mantis برای PRها را چه مدت نگه دارد؟ +- چه زمانی ClawSweeper باید به‌جای انتظار برای فرمان نگه‌دارنده، به‌طور خودکار Mantis را پیشنهاد کند؟ +- آیا نماگرفت‌ها باید پیش از بارگذاری برای PRهای عمومی ویرایش محرمانه یا برش داده شوند؟ diff --git a/docs/fa/concepts/messages.md b/docs/fa/concepts/messages.md index 58335c4cf..201cc504e 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-30T16:27:51Z" + generated_at: "2026-05-04T07:03:52Z" model: gpt-5.5 provider: openai - source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 + source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f source_path: concepts/messages.md workflow: 16 --- -OpenClaw پیام‌های ورودی را از طریق خط لوله‌ای شامل تشخیص نشست، صف‌بندی، جریان‌سازی، اجرای ابزار و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر از پیام ورودی تا پاسخ را ترسیم می‌کند. +OpenClaw پیام‌های ورودی را از طریق یک خط لوله شامل تشخیص نشست، صف‌گذاری، جریان‌دهی، اجرای ابزار، و نمایش‌پذیری استدلال پردازش می‌کند. این صفحه مسیر از پیام ورودی تا پاسخ را ترسیم می‌کند. ## جریان پیام (سطح بالا) @@ -28,19 +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` در یک نوبت عامل واحد تجمیع شوند. ادغام تأخیری برای هر کانال + گفتگو جداگانه اعمال می‌شود و برای رشته‌بندی/شناسه‌های پاسخ از جدیدترین پیام استفاده می‌کند. پیکربندی (پیش‌فرض سراسری + بازنویسی‌های هر کانال): @@ -61,69 +61,69 @@ Inbound message نکته‌ها: -- ضدپرش فقط روی پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند. -- فرمان‌های کنترلی ضدپرش را دور می‌زنند تا مستقل بمانند — **مگر** وقتی کانالی صراحتا در ادغام DM از همان فرستنده شرکت کند (برای نمونه [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))، که در آن فرمان‌های DM داخل پنجره ضدپرش منتظر می‌مانند تا محتوای ارسالِ تقسیم‌شده بتواند به همان نوبت عامل بپیوندد. +- ادغام تأخیری برای پیام‌های **فقط متنی** اعمال می‌شود؛ رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند. +- فرمان‌های کنترلی از ادغام تأخیری عبور می‌کنند تا مستقل باقی بمانند — **به‌جز** زمانی که یک کانال صریحاً ادغام پیام‌های مستقیم از همان فرستنده را فعال کند (برای مثال [BlueBubbles `coalesceSameSenderDms`](/fa/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))، که در آن فرمان‌های پیام مستقیم داخل پنجره ادغام تأخیری منتظر می‌مانند تا یک محموله ارسال‌شده به‌صورت جداشده بتواند به همان نوبت عامل بپیوندد. ## نشست‌ها و دستگاه‌ها -نشست‌ها متعلق به Gateway هستند، نه کلاینت‌ها. +نشست‌ها متعلق به Gateway هستند، نه مشتری‌ها. -- گفتگوهای مستقیم در کلید نشست اصلی عامل ادغام می‌شوند. -- گروه‌ها/کانال‌ها کلیدهای نشست خودشان را می‌گیرند. -- ذخیره‌گاه نشست و رونوشت‌ها روی میزبان Gateway قرار دارند. +- چت‌های مستقیم در کلید نشست اصلی عامل ادغام می‌شوند. +- گروه‌ها/کانال‌ها کلیدهای نشست خودشان را دریافت می‌کنند. +- ذخیره‌ساز نشست و رونوشت‌ها روی میزبان Gateway قرار دارند. -چند دستگاه/کانال می‌توانند به یک نشست نگاشت شوند، اما تاریخچه به‌طور کامل به همه کلاینت‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید تا از واگرایی زمینه جلوگیری شود. Control UI و TUI همیشه رونوشت نشست پشتیبانی‌شده توسط Gateway را نشان می‌دهند، پس منبع حقیقت هستند. +چند دستگاه/کانال می‌توانند به یک نشست یکسان نگاشت شوند، اما تاریخچه به‌طور کامل به همه مشتری‌ها همگام‌سازی نمی‌شود. توصیه: برای گفتگوهای طولانی از یک دستگاه اصلی استفاده کنید تا از واگرایی زمینه جلوگیری شود. رابط کاربری کنترل و TUI همیشه رونوشت نشست متکی بر Gateway را نشان می‌دهند، بنابراین منبع حقیقت هستند. جزئیات: [مدیریت نشست](/fa/concepts/session). ## فراداده نتیجه ابزار -`content` نتیجه ابزار، نتیجه قابل مشاهده برای مدل است. `details` نتیجه ابزار فراداده زمان اجرا برای رندر UI، عیب‌یابی، تحویل رسانه و Pluginها است. +`content` نتیجه ابزار همان نتیجه قابل مشاهده برای مدل است. `details` نتیجه ابزار فراداده زمان اجرا برای رندر رابط کاربری، عیب‌یابی، تحویل رسانه، و Pluginها است. OpenClaw این مرز را صریح نگه می‌دارد: - `toolResult.details` پیش از بازپخش ارائه‌دهنده و ورودی Compaction حذف می‌شود. -- رونوشت‌های نشست پایدارشده فقط `details` محدود را نگه می‌دارند؛ فراداده بزرگ‌تر با خلاصه‌ای فشرده جایگزین می‌شود که با `persistedDetailsTruncated: true` علامت‌گذاری شده است. -- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` قرار دهند، نه فقط در `details`. +- رونوشت‌های نشست ماندگارشده فقط `details` محدودشده را نگه می‌دارند؛ فراداده بزرگ‌تر از حد با خلاصه‌ای فشرده جایگزین می‌شود که با `persistedDetailsTruncated: true` علامت‌گذاری شده است. +- Pluginها و ابزارها باید متنی را که مدل باید بخواند در `content` بگذارند، نه فقط در `details`. ## بدنه‌های ورودی و زمینه تاریخچه OpenClaw **بدنه پرامپت** را از **بدنه فرمان** جدا می‌کند: -- `BodyForAgent`: متن اصلی رو به مدل برای پیام فعلی. Pluginهای کانال باید این را روی متن فعلی فرستنده که حامل پرامپت است متمرکز نگه دارند. -- `Body`: جایگزین قدیمی پرامپت. این ممکن است شامل پوشش‌های کانال و پوشش‌های اختیاری تاریخچه باشد، اما کانال‌های فعلی نباید وقتی `BodyForAgent` در دسترس است به‌عنوان ورودی اصلی مدل به آن تکیه کنند. -- `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` است، با ادغام تأخیری پیگیری 500 میلی‌ثانیه‌ای وقتی هدایت به تحویل پیگیری صف‌شده بازمی‌گردد. +- حالت‌ها: `steer`، `followup`، `collect`، `steer-backlog`، `interrupt`، و حالت قدیمی تک‌به‌تک `queue`. جزئیات: [صف فرمان](/fa/concepts/queue) و [صف هدایت](/fa/concepts/queue-steering). ## مالکیت اجرای کانال -Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورودی را ضدپرش کنند و پیش از ورود پیام به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید زمان‌سنج جداگانه‌ای دور خود نوبت عامل تحمیل کنند. وقتی پیام به یک نشست مسیریابی شد، کارهای طولانی‌مدت توسط چرخه عمر نشست، ابزار و زمان اجرا اداره می‌شوند تا همه کانال‌ها نوبت‌های کند را به‌شکل سازگار گزارش دهند و بازیابی کنند. +Pluginهای کانال می‌توانند ترتیب را حفظ کنند، ورودی را با تأخیر ادغام کنند، و پیش از ورود پیام به صف نشست، پس‌فشار انتقال را اعمال کنند. آن‌ها نباید پیرامون خود نوبت عامل زمان‌سنج جداگانه‌ای تحمیل کنند. پس از مسیریابی یک پیام به نشست، کارهای طولانی‌مدت توسط چرخه عمر نشست، ابزار، و زمان اجرا اداره می‌شوند تا همه کانال‌ها نوبت‌های کند را به‌صورت سازگار گزارش دهند و از آن‌ها بازیابی کنند. -## جریان‌سازی، تکه‌تکه‌سازی و دسته‌بندی +## جریان‌دهی، قطعه‌بندی، و دسته‌بندی -جریان‌سازی بلوکی پاسخ‌های جزئی را هم‌زمان با تولید بلوک‌های متن توسط مدل ارسال می‌کند. تکه‌تکه‌سازی محدودیت‌های متنی کانال را رعایت می‌کند و از تقسیم کردن کد حصارشده پرهیز می‌کند. +جریان‌دهی بلوکی پاسخ‌های جزئی را هم‌زمان با تولید بلوک‌های متن توسط مدل ارسال می‌کند. قطعه‌بندی محدودیت‌های متنی کانال را رعایت می‌کند و از شکستن کدهای محصور جلوگیری می‌کند. تنظیمات کلیدی: @@ -134,46 +134,46 @@ Pluginهای کانال ممکن است ترتیب را حفظ کنند، ورو - `agents.defaults.humanDelay` (مکث شبیه انسان بین پاسخ‌های بلوکی) - بازنویسی‌های کانال: `*.blockStreaming` و `*.blockStreamingCoalesce` (کانال‌های غیر Telegram به `*.blockStreaming: true` صریح نیاز دارند) -جزئیات: [جریان‌سازی + تکه‌تکه‌سازی](/fa/concepts/streaming). +جزئیات: [جریان‌دهی + قطعه‌بندی](/fa/concepts/streaming). ## نمایش‌پذیری استدلال و توکن‌ها -OpenClaw می‌تواند استدلال مدل را آشکار یا پنهان کند: +OpenClaw می‌تواند استدلال مدل را نمایش دهد یا پنهان کند: - `/reasoning on|off|stream` نمایش‌پذیری را کنترل می‌کند. -- محتوای استدلال، وقتی توسط مدل تولید شود، همچنان در مصرف توکن حساب می‌شود. -- Telegram از جریان استدلال به داخل حباب پیش‌نویس پشتیبانی می‌کند. +- محتوای استدلال، وقتی توسط مدل تولید شود، همچنان در مصرف توکن محاسبه می‌شود. +- Telegram از جریان استدلال به یک حباب پیش‌نویس گذرا پشتیبانی می‌کند که پس از تحویل نهایی حذف می‌شود؛ برای خروجی استدلال ماندگار از `/reasoning on` استفاده کنید. -جزئیات: [دستورالعمل‌های فکر کردن + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use). +جزئیات: [دستورهای تفکر + استدلال](/fa/tools/thinking) و [مصرف توکن](/fa/reference/token-use). -## پیشوندها، رشته‌بندی و پاسخ‌ها +## پیشوندها، رشته‌بندی، و پاسخ‌ها -قالب‌بندی پیام خروجی در `messages` متمرکز شده است: +قالب‌بندی پیام خروجی در `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 متن خاموش را حذف می‌کند اما همچنان پیوست رسانه را تحویل می‌دهد. +توکن دقیق بی‌صدا `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` می‌توانند آن‌ها را برای هر سطح بازنویسی کنند. -وقتی نشست والد یک یا چند اجرای زیرعامل ایجادشده معلق داشته باشد، پاسخ‌های خاموش تنها به‌جای بازنویسی، روی همه سطح‌ها کنار گذاشته می‌شوند، تا والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت بماند. +وقتی نشست والد یک یا چند اجرای زیرعامل ایجادشده در انتظار داشته باشد، پاسخ‌های صرفاً بی‌صدا در همه سطح‌ها به‌جای بازنویسی کنار گذاشته می‌شوند، بنابراین والد تا زمانی که رویداد تکمیل فرزند پاسخ واقعی را تحویل دهد ساکت می‌ماند. ## مرتبط -- [جریان‌سازی](/fa/concepts/streaming) — تحویل بی‌درنگ پیام +- [جریان‌دهی](/fa/concepts/streaming) — تحویل پیام بلادرنگ - [تلاش دوباره](/fa/concepts/retry) — رفتار تلاش دوباره برای تحویل پیام - [صف](/fa/concepts/queue) — صف پردازش پیام - [کانال‌ها](/fa/channels) — یکپارچه‌سازی‌های پلتفرم پیام‌رسانی diff --git a/docs/fa/concepts/progress-drafts.md b/docs/fa/concepts/progress-drafts.md index fe0167932..bc8aad19b 100644 --- a/docs/fa/concepts/progress-drafts.md +++ b/docs/fa/concepts/progress-drafts.md @@ -1,26 +1,26 @@ --- read_when: - - پیکربندی به‌روزرسانی‌های پیشرفت قابل مشاهده برای نوبت‌های گفت‌وگوی طولانی‌مدت - - انتخاب میان حالت‌های جریان‌دهی جزئی، بلوکی و پیشرفت - - توضیح اینکه OpenClaw چگونه در حالی که کار در حال انجام است، یک پیام کانال را به‌روزرسانی می‌کند + - پیکربندی به‌روزرسانی‌های قابل مشاهدهٔ پیشرفت برای نوبت‌های طولانی‌مدت گفت‌وگو + - انتخاب بین حالت‌های استریم جزئی، بلوکی و پیشرفت + - توضیح اینکه OpenClaw چگونه هنگام در جریان بودن کار، یک پیام کانال را به‌روزرسانی می‌کند - عیب‌یابی پیش‌نویس‌های پیشرفت، پیام‌های مستقل پیشرفت، یا مسیر جایگزین نهایی‌سازی summary: 'پیش‌نویس‌های پیشرفت: یک پیام قابل مشاهدهٔ کار در حال انجام که هنگام اجرای یک عامل به‌روزرسانی می‌شود' -title: پیش‌نویس‌های پیشرفت +title: پیش‌بردن پیش‌نویس‌ها x-i18n: - generated_at: "2026-05-04T02:24:03Z" + generated_at: "2026-05-04T07:04:10Z" model: gpt-5.5 provider: openai - source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe + source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788 source_path: concepts/progress-drafts.md workflow: 16 --- پیش‌نویس‌های پیشرفت باعث می‌شوند نوبت‌های طولانی‌مدت عامل در چت زنده به نظر برسند، بدون اینکه -گفت‌وگو به پشته‌ای از پاسخ‌های وضعیت موقت تبدیل شود. +گفت‌وگو به انباشته‌ای از پاسخ‌های وضعیت موقت تبدیل شود. -وقتی پیش‌نویس‌های پیشرفت فعال باشند، OpenClaw فقط پس از اینکه نوبت ثابت کرد در حال انجام کار واقعی است -یک پیام کاریِ قابل مشاهده ایجاد می‌کند، هنگام خواندن، برنامه‌ریزی، فراخوانی ابزارها یا انتظار برای تأیید توسط -عامل آن را به‌روزرسانی می‌کند، و سپس وقتی کانال بتواند این کار را با ایمنی انجام دهد، آن پیش‌نویس را +وقتی پیش‌نویس‌های پیشرفت فعال باشند، OpenClaw فقط بعد از اینکه نوبت نشان داد کار واقعی انجام می‌دهد +یک پیام visible work-in-progress ایجاد می‌کند، آن را هنگامی که +عامل می‌خواند، برنامه‌ریزی می‌کند، ابزارها را فراخوانی می‌کند یا منتظر تأیید می‌ماند به‌روزرسانی می‌کند، و سپس وقتی کانال بتواند این کار را با ایمنی انجام دهد، آن پیش‌نویس را به پاسخ نهایی تبدیل می‌کند. ```text @@ -30,8 +30,8 @@ Shelling... 🛠️ Exec: run tests ``` -وقتی در کارهای سنگین از نظر ابزار، یک پیام وضعیت مرتب می‌خواهید -و پاسخ نهایی را پس از پایان نوبت می‌خواهید، از پیش‌نویس‌های پیشرفت استفاده کنید. +وقتی در کارهای پرابزار یک پیام وضعیت مرتب می‌خواهید +و پس از پایان نوبت پاسخ نهایی را، از پیش‌نویس‌های پیشرفت استفاده کنید. ## شروع سریع @@ -49,9 +49,9 @@ Shelling... } ``` -این معمولاً کافی است. OpenClaw یک برچسب تک‌کلمه‌ای خودکار انتخاب می‌کند، صبر می‌کند -تا کار دست‌کم پنج ثانیه طول بکشد یا رویداد کاری دومی منتشر شود، در زمان انجام کار مفید -خطوط پیشرفت فشرده اضافه می‌کند، و گفت‌وگوی پیشرفت مستقلِ تکراری را برای آن نوبت سرکوب می‌کند. +این معمولاً کافی است. OpenClaw یک برچسب خودکار یک‌کلمه‌ای انتخاب می‌کند، صبر می‌کند +تا کار دست‌کم پنج ثانیه طول بکشد یا یک رویداد کاری دوم منتشر کند، هنگام انجام کار مفید +خطوط پیشرفت فشرده اضافه می‌کند، و گفت‌وگوی پیشرفت مستقل و تکراری را برای آن نوبت سرکوب می‌کند. ## کاربران چه می‌بینند @@ -60,45 +60,45 @@ Shelling... | بخش | هدف | | -------------- | --------------------------------------------------------------------------- | | برچسب | عنوانی کوتاه مانند `Thinking...` یا `Shelling...`. | -| خطوط پیشرفت | به‌روزرسانی‌های اجرای فشرده با همان برچسب‌ها و آیکون‌های ابزار مانند خروجی پرجزئیات. | +| خطوط پیشرفت | به‌روزرسانی‌های اجرای فشرده با همان برچسب‌ها و آیکون‌های ابزار که در خروجی پرجزئیات استفاده می‌شوند. | برچسب پس از شروع کار معنادار توسط عامل ظاهر می‌شود و یا تا پنج ثانیه مشغول می‌ماند -یا رویداد کاری دومی منتشر می‌کند. پاسخ‌های صرفاً متنی ساده -پیش‌نویس پیشرفت نشان نمی‌دهند. خطوط پیشرفت فقط وقتی اضافه می‌شوند که عامل -به‌روزرسانی‌های کاری مفید منتشر کند، برای مثال `🛠️ Exec`، `🔎 Web Search` یا `✍️ Write: to /tmp/file`. -به‌طور پیش‌فرض از همان حالت توضیح فشرده مانند `/verbose` استفاده می‌کنند؛ وقتی در حال اشکال‌زدایی هستید -و می‌خواهید فرمان‌ها/جزئیات خام نیز افزوده شوند، `agents.defaults.toolProgressDetail: "raw"` را تنظیم کنید. -در صورت امکان پاسخ نهایی جایگزین پیش‌نویس می‌شود؛ در غیر این صورت -OpenClaw پاسخ نهایی را به‌صورت معمول می‌فرستد و پیش‌نویس را طبق انتقال کانال -پاک می‌کند یا به‌روزرسانی آن را متوقف می‌کند. +یا یک رویداد کاری دوم منتشر می‌کند. پاسخ‌های صرفاً متنی، پیش‌نویس پیشرفت نشان نمی‌دهند. +خطوط پیشرفت فقط وقتی اضافه می‌شوند که عامل به‌روزرسانی‌های کاری مفید منتشر کند، +برای مثال `🛠️ Exec`، `🔎 Web Search`، یا `✍️ Write: to /tmp/file`. +به‌صورت پیش‌فرض از همان حالت توضیح فشرده مثل `/verbose` استفاده می‌کنند؛ وقتی در حال اشکال‌زدایی هستید و جزئیات/دستورات خام افزوده‌شده را هم می‌خواهید، +`agents.defaults.toolProgressDetail: "raw"` را تنظیم کنید. +پاسخ نهایی در صورت امکان جایگزین پیش‌نویس می‌شود؛ در غیر این صورت +OpenClaw پاسخ نهایی را به‌صورت عادی می‌فرستد و بسته به انتقال کانال، +پیش‌نویس را پاک‌سازی می‌کند یا به‌روزرسانی آن را متوقف می‌کند. -## انتخاب حالت +## انتخاب یک حالت -`channels..streaming.mode` رفتار قابل مشاهده هنگام در جریان بودن کار را کنترل می‌کند: +`channels..streaming.mode` رفتار visible in-progress را کنترل می‌کند: | حالت | مناسب برای | آنچه در چت ظاهر می‌شود | | ---------- | -------------------------------- | ------------------------------------------------- | -| `off` | کانال‌های ساکت | فقط پاسخ نهایی. | +| `off` | کانال‌های کم‌صدا | فقط پاسخ نهایی. | | `partial` | دیدن ظاهر شدن متن پاسخ | یک پیش‌نویس که با آخرین متن پاسخ ویرایش می‌شود. | -| `block` | قطعه‌های بزرگ‌تر پیش‌نمایش پاسخ | یک پیش‌نمایش که در قطعه‌های بزرگ‌تر به‌روزرسانی یا افزوده می‌شود. | -| `progress` | نوبت‌های سنگین از نظر ابزار یا طولانی‌مدت | یک پیش‌نویس وضعیت، سپس پاسخ نهایی. | +| `block` | تکه‌های بزرگ‌تر پیش‌نمایش پاسخ | یک پیش‌نمایش که در تکه‌های بزرگ‌تر به‌روزرسانی یا افزوده می‌شود. | +| `progress` | نوبت‌های پرابزار یا طولانی‌مدت | یک پیش‌نویس وضعیت، سپس پاسخ نهایی. | -وقتی کاربران بیشتر از تماشای جریان متن پاسخ، توکن به توکن، -به «چه اتفاقی دارد می‌افتد» اهمیت می‌دهند، `progress` را انتخاب کنید. +وقتی کاربران بیشتر به «چه اتفاقی در حال رخ دادن است» اهمیت می‌دهند تا دیدن +جریان متن پاسخ به‌صورت توکن‌به‌توکن، `progress` را انتخاب کنید. -وقتی خود پاسخ، سیگنال پیشرفت است، `partial` را انتخاب کنید. +وقتی خود پاسخ سیگنال پیشرفت است، `partial` را انتخاب کنید. -وقتی می‌خواهید به‌روزرسانی‌های پیش‌نمایش پیش‌نویس در قطعه‌های متنی بزرگ‌تر باشد، `block` را انتخاب کنید. در -Discord و Telegram، `streaming.mode: "block"` همچنان جریان‌دهی پیش‌نمایش است، نه -تحویل بلوکی معمولی. وقتی پاسخ‌های بلوکی معمولی می‌خواهید، از `streaming.block.enabled` یا +وقتی به‌روزرسانی‌های پیش‌نمایش پیش‌نویس را در تکه‌های متنی بزرگ‌تر می‌خواهید، `block` را انتخاب کنید. در +Discord و Telegram، `streaming.mode: "block"` همچنان جریان پیش‌نمایش است، نه +تحویل عادی بلوکی. وقتی پاسخ‌های بلوکی عادی می‌خواهید از `streaming.block.enabled` یا `blockStreaming` قدیمی استفاده کنید. ## پیکربندی برچسب‌ها برچسب‌های پیشرفت زیر `channels..streaming.progress` قرار دارند. -برچسب پیش‌فرض `auto` است که از مجموعه برچسب تک‌کلمه‌ای همراه با سه‌نقطه داخلی OpenClaw -انتخاب می‌کند: +برچسب پیش‌فرض `auto` است، که از مجموعه برچسب داخلی +تک‌کلمه‌ای-با-سه‌نقطه OpenClaw انتخاب می‌کند: ```text Thinking... @@ -177,11 +177,11 @@ Surfacing... ## کنترل خطوط پیشرفت -خطوط پیشرفت به‌طور پیش‌فرض در حالت پیشرفت فعال هستند. آن‌ها از رویدادهای اجرای واقعی می‌آیند: -شروع ابزارها، به‌روزرسانی آیتم‌ها، برنامه‌های وظیفه، تأییدها، خروجی فرمان، خلاصه‌های وصله، +خطوط پیشرفت در حالت پیشرفت به‌صورت پیش‌فرض فعال هستند. آن‌ها از رویدادهای اجرای واقعی می‌آیند: +شروع ابزارها، به‌روزرسانی آیتم‌ها، برنامه‌های کار، تأییدها، خروجی فرمان، خلاصه‌های patch و فعالیت‌های مشابه عامل. -OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پیشرفت و `/verbose` استفاده می‌کند: +OpenClaw برای پیش‌نویس‌های پیشرفت و `/verbose` از یک formatter یکسان استفاده می‌کند: ```json5 { @@ -193,19 +193,18 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ } ``` -`"explain"` پیش‌فرض است و پیش‌نویس‌ها را با برچسب‌های موجز مانند -`🛠️ Exec: check JS syntax for /tmp/app.js` پایدار نگه می‌دارد. `"raw"` وقتی در دسترس باشد -فرمان/جزئیات زیربنایی را اضافه می‌کند، که هنگام اشکال‌زدایی مفید است اما در -چت پرسر و صداتر است. +`"explain"` پیش‌فرض است و پیش‌نویس‌ها را با برچسب‌های کوتاهی مثل +`🛠️ Exec: check JS syntax for /tmp/app.js` پایدار نگه می‌دارد. `"raw"` در صورت وجود، فرمان/جزئیات زیربنایی را اضافه می‌کند، که هنگام اشکال‌زدایی مفید است اما در +چت پرنویزتر است. -برای مثال، یک فرمان یکسان بسته به حالت جزئیات متفاوت ظاهر می‌شود: +برای مثال، همان فرمان بسته به حالت جزئیات متفاوت ظاهر می‌شود: | حالت | خط پیشرفت | | --------- | -------------------------------------------------------------------- | | `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` | | `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` | -تعداد خطوطی را که قابل مشاهده می‌مانند محدود کنید: +تعداد خطوطی را که visible می‌مانند محدود کنید: ```json5 { @@ -222,7 +221,34 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ } ``` -پیش‌نویس پیشرفت تکی را نگه دارید، اما خطوط ابزار و وظیفه را پنهان کنید: +خطوط پیشرفت به‌صورت خودکار فشرده می‌شوند تا هنگام ویرایش پیش‌نویس، بازچینی حباب چت کاهش یابد. + +OpenClaw به‌صورت پیش‌فرض خطوط پیشرفت طولانی را کوتاه می‌کند تا ویرایش‌های تکراری پیش‌نویس +در هر به‌روزرسانی به شکل متفاوتی wrap نشوند. پیشوند خوانا می‌ماند، و جزئیات طولانی +مانند مسیرها یا فرمان‌های خام با سه‌نقطه کوتاه می‌شوند. + +Slack می‌تواند خطوط پیشرفت را به‌جای یک بدنه متنی واحد، به‌صورت فیلدهای ساختاریافته Block Kit +render کند: + +```json5 +{ + channels: { + slack: { + streaming: { + mode: "progress", + progress: { + render: "rich", + }, + }, + }, + }, +} +``` + +render کردن rich همان fallback متن ساده را نگه می‌دارد تا کانال‌ها و کلاینت‌هایی که +از شکل غنی‌تر پشتیبانی نمی‌کنند همچنان بتوانند متن فشرده پیشرفت را نشان دهند. + +پیش‌نویس پیشرفت واحد را نگه دارید اما خطوط ابزار و کار را پنهان کنید: ```json5 { @@ -240,8 +266,8 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ ``` با `toolProgress: false`، OpenClaw همچنان پیام‌های قدیمی‌تر مستقل -پیشرفت ابزار را برای آن نوبت سرکوب می‌کند. کانال تا پاسخ نهایی، به‌جز برچسب در صورت پیکربندی، -از نظر بصری ساکت می‌ماند. +پیشرفت ابزار را برای آن نوبت سرکوب می‌کند. کانال تا پاسخ نهایی از نظر بصری آرام می‌ماند، +به‌جز برچسب اگر یکی پیکربندی شده باشد. ## رفتار کانال @@ -249,68 +275,68 @@ OpenClaw از همان قالب‌ساز برای پیش‌نویس‌های پ | کانال | انتقال پیشرفت | یادداشت‌ها | | --------------- | -------------------------------------- | --------------------------------------------------------------------- | -| Discord | یک پیام بفرست، سپس آن را ویرایش کن. | وقتی متن نهایی در یک پیام پیش‌نمایش ایمن جا شود، درجا ویرایش می‌شود. | -| Matrix | یک رویداد بفرست، سپس آن را ویرایش کن. | پیکربندی جریان‌دهی در سطح حساب، پیش‌نویس‌های سطح حساب را کنترل می‌کند. | +| Discord | یک پیام بفرست، سپس آن را ویرایش کن. | متن نهایی وقتی در یک پیام پیش‌نمایش ایمن جا شود، درجا ویرایش می‌شود. | +| Matrix | یک رویداد بفرست، سپس آن را ویرایش کن. | پیکربندی جریان در سطح حساب، پیش‌نویس‌های سطح حساب را کنترل می‌کند. | | Microsoft Teams | جریان بومی Teams در چت‌های شخصی. | `streaming.mode: "block"` به تحویل بلوکی Teams نگاشت می‌شود. | -| Slack | جریان بومی یا پست پیش‌نویس قابل ویرایش. | دسترس‌پذیری رشته تعیین می‌کند آیا می‌توان از جریان‌دهی بومی استفاده کرد. | -| Telegram | یک پیام بفرست، سپس آن را ویرایش کن. | پیش‌نویس‌های قابل مشاهده قدیمی‌تر ممکن است جایگزین شوند تا زمان‌مهرهای نهایی مفید بمانند. | -| Mattermost | پست پیش‌نویس قابل ویرایش. | فعالیت ابزار در همان پست سبک پیش‌نویس ادغام می‌شود. | +| Slack | جریان بومی یا پست پیش‌نویس قابل ویرایش. | دسترس‌پذیری thread روی اینکه آیا جریان بومی قابل استفاده است اثر می‌گذارد. | +| Telegram | یک پیام بفرست، سپس آن را ویرایش کن. | پیش‌نویس‌های visible قدیمی‌تر ممکن است جایگزین شوند تا timestampهای نهایی مفید بمانند. | +| Mattermost | پست پیش‌نویس قابل ویرایش. | فعالیت ابزار در همان پست به سبک پیش‌نویس ادغام می‌شود. | -کانال‌هایی که پشتیبانی ایمن از ویرایش ندارند معمولاً به نشانگرهای تایپ یا -تحویل فقط نهایی بازمی‌گردند. +کانال‌هایی که از ویرایش ایمن پشتیبانی نمی‌کنند معمولاً به نشانگرهای درحال‌تایپ یا +تحویل فقط نهایی fallback می‌کنند. ## نهایی‌سازی وقتی پاسخ نهایی آماده است، OpenClaw تلاش می‌کند چت را تمیز نگه دارد: - اگر پیش‌نویس بتواند با ایمنی به پاسخ نهایی تبدیل شود، OpenClaw آن را درجا ویرایش می‌کند. -- اگر کانال از جریان‌دهی پیشرفت بومی استفاده کند، OpenClaw وقتی انتقال بومی متن نهایی را می‌پذیرد - آن جریان را نهایی می‌کند. +- اگر کانال از جریان پیشرفت بومی استفاده کند، OpenClaw آن جریان را + وقتی انتقال بومی متن نهایی را بپذیرد نهایی می‌کند. - اگر پاسخ نهایی رسانه، درخواست تأیید، هدف پاسخ صریح، - قطعه‌های بیش از حد، یا ویرایش/ارسال ناموفق داشته باشد، OpenClaw پاسخ نهایی را از مسیر + تکه‌های بیش از حد، یا ویرایش/ارسال ناموفق داشته باشد، OpenClaw پاسخ نهایی را از مسیر تحویل عادی کانال می‌فرستد. -مسیر جایگزین عمدی است. بهتر است یک پاسخ نهایی تازه ارسال شود تا اینکه -متن از دست برود، پاسخ در رشته اشتباه قرار گیرد، یا پیش‌نویس با محتوایی بازنویسی شود که کانال -نتواند آن را با ایمنی نمایش دهد. +مسیر fallback عمدی است. بهتر است یک پاسخ نهایی تازه ارسال شود تا اینکه +متن از دست برود، یک پاسخ در thread اشتباه قرار گیرد، یا پیش‌نویسی با payloadی بازنویسی شود که کانال +نمی‌تواند آن را با ایمنی نمایش دهد. ## عیب‌یابی **فقط پاسخ نهایی را می‌بینم.** -بررسی کنید `channels..streaming.mode` برای حساب یا کانالی که پیام را پردازش کرده -روی `progress` تنظیم شده باشد. برخی مسیرهای گروهی یا پاسخ همراه با نقل‌قول ممکن است -پیش‌نمایش‌های پیش‌نویس را برای یک نوبت غیرفعال کنند، وقتی کانال نتواند پیام درست را با ایمنی -ویرایش کند. +بررسی کنید که `channels..streaming.mode` برای حساب یا کانالی که پیام را پردازش کرده +روی `progress` تنظیم شده باشد. برخی مسیرهای گروهی یا quote-reply ممکن است +پیش‌نمایش‌های پیش‌نویس را برای یک نوبت غیرفعال کنند وقتی کانال نتواند پیام درست را +با ایمنی ویرایش کند. -**برچسب را می‌بینم اما خطوط ابزار را نه.** +**برچسب را می‌بینم اما خطوط ابزار را نمی‌بینم.** `streaming.progress.toolProgress` را بررسی کنید. اگر `false` باشد، OpenClaw رفتار -پیش‌نویس تکی را نگه می‌دارد اما خطوط پیشرفت ابزار و وظیفه را پنهان می‌کند. +پیش‌نویس واحد را نگه می‌دارد اما خطوط پیشرفت ابزار و کار را پنهان می‌کند. -**به‌جای پیش‌نویس ویرایش‌شده، یک پیام نهایی تازه می‌بینم.** +**به‌جای پیش‌نویس ویرایش‌شده یک پیام نهایی تازه می‌بینم.** -این یک مسیر جایگزین ایمنی است. ممکن است برای پاسخ‌های رسانه‌ای، پاسخ‌های طولانی، -هدف‌های پاسخ صریح، پیش‌نویس‌های قدیمی Telegram، هدف‌های رشته گم‌شده Slack، +این یک fallback ایمنی است. این می‌تواند برای پاسخ‌های رسانه‌ای، پاسخ‌های طولانی، +هدف‌های پاسخ صریح، پیش‌نویس‌های قدیمی Telegram، هدف‌های thread گم‌شده Slack، پیام‌های پیش‌نمایش حذف‌شده، یا نهایی‌سازی ناموفق جریان بومی رخ دهد. -**هنوز پیام‌های پیشرفت مستقل را می‌بینم.** +**هنوز پیام‌های پیشرفت مستقل می‌بینم.** -حالت پیشرفت وقتی یک پیش‌نویس فعال باشد پیام‌های پیش‌فرض مستقل پیشرفت ابزار را سرکوب می‌کند. -اگر پیام‌های مستقل هنوز ظاهر می‌شوند، بررسی کنید که نوبت واقعاً از حالت پیشرفت استفاده می‌کند -و نه `streaming.mode: "off"` یا مسیر کانالی که -نمی‌تواند برای آن پیام پیش‌نویس ایجاد کند. +حالت پیشرفت وقتی یک پیش‌نویس فعال باشد، پیام‌های پیش‌فرض مستقل پیشرفت ابزار را سرکوب می‌کند. +اگر پیام‌های مستقل همچنان ظاهر می‌شوند، تأیید کنید که نوبت واقعاً +از حالت پیشرفت استفاده می‌کند و نه `streaming.mode: "off"` یا یک مسیر کانالی که +نمی‌تواند برای آن پیام پیش‌نویس بسازد. **Teams متفاوت از Discord یا Telegram رفتار می‌کند.** -Microsoft Teams در چت‌های شخصی به‌جای انتقال پیش‌نمایش عمومیِ ارسال و ویرایش، +Microsoft Teams در چت‌های شخصی به‌جای انتقال عمومی پیش‌نمایش send-and-edit، از جریان بومی استفاده می‌کند. Teams همچنین `streaming.mode: "block"` را به‌عنوان -تحویل بلوکی Teams در نظر می‌گیرد، چون همان حالت بلوکیِ پیش‌نمایش پیش‌نویس را که +تحویل بلوکی Teams در نظر می‌گیرد، زیرا همان حالت بلوکی پیش‌نمایش پیش‌نویس را که Discord و Telegram استفاده می‌کنند ندارد. ## مرتبط -- [جریان‌دهی و قطعه‌بندی](/fa/concepts/streaming) +- [جریان و قطعه‌بندی](/fa/concepts/streaming) - [پیام‌ها](/fa/concepts/messages) - [پیکربندی کانال](/fa/gateway/config-channels) - [Discord](/fa/channels/discord) diff --git a/docs/fa/concepts/qa-e2e-automation.md b/docs/fa/concepts/qa-e2e-automation.md index 8e1a556ab..5b7369783 100644 --- a/docs/fa/concepts/qa-e2e-automation.md +++ b/docs/fa/concepts/qa-e2e-automation.md @@ -1,82 +1,82 @@ --- read_when: - - درک اینکه پشتهٔ QA چگونه کنار هم قرار می‌گیرد - - گسترش qa-lab، qa-channel یا یک آداپتور ترابری + - درک نحوهٔ قرارگیری اجزای پشتهٔ QA در کنار هم + - گسترش qa-lab، qa-channel یا یک آداپتور انتقال - افزودن سناریوهای تضمین کیفیت مبتنی بر مخزن - - ساخت خودکارسازی تضمین کیفیت واقع‌گرایانه‌تر برای داشبورد Gateway -summary: 'نمای کلی پشته QA: qa-lab، qa-channel، سناریوهای متکی به مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال و گزارش‌دهی.' -title: نمای کلی QA + - ساخت اتوماسیون تضمین کیفیت واقع‌گرایانه‌تر برای داشبورد Gateway +summary: 'نمای کلی پشتهٔ تضمین کیفیت: qa-lab، qa-channel، سناریوهای مبتنی بر مخزن، مسیرهای انتقال زنده، آداپتورهای انتقال، و گزارش‌دهی.' +title: نمای کلی تضمین کیفیت x-i18n: - generated_at: "2026-05-04T02:24:18Z" + generated_at: "2026-05-04T07:05:38Z" model: gpt-5.5 provider: openai - source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba + source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -پشته QA خصوصی قرار است OpenClaw را به شکلی واقعی‌تر و -کانال‌محورتر از چیزی که یک آزمون واحد می‌تواند پوشش دهد، تمرین دهد. +استک خصوصی QA برای آن است که OpenClaw را به شکلی واقعی‌تر و +کانال‌محورتر از آنچه یک آزمون واحد می‌تواند انجام دهد، تمرین دهد. اجزای فعلی: - `extensions/qa-channel`: کانال پیام مصنوعی با سطوح DM، کانال، رشته، واکنش، ویرایش، و حذف. -- `extensions/qa-lab`: رابط اشکال‌زدایی و گذرگاه QA برای مشاهده رونوشت، +- `extensions/qa-lab`: رابط کاربری اشکال‌زدا و گذرگاه QA برای مشاهده رونوشت، تزریق پیام‌های ورودی، و صادر کردن گزارش Markdown. -- `extensions/qa-matrix`، Pluginهای اجراکننده آینده: آداپترهای انتقال زنده که +- `extensions/qa-matrix`، Pluginهای اجراکننده آینده: آداپتورهای انتقال زنده که یک کانال واقعی را داخل یک Gateway فرزند QA هدایت می‌کنند. -- `qa/`: دارایی‌های اولیه متکی به مخزن برای وظیفه آغازین و سناریوهای پایه - QA. +- `qa/`: دارایی‌های seed پشتیبانی‌شده با مخزن برای وظیفه آغازین و سناریوهای + پایه QA. - [Mantis](/fa/concepts/mantis): راستی‌آزمایی زنده قبل و بعد برای باگ‌هایی که به انتقال‌های واقعی، اسکرین‌شات‌های مرورگر، وضعیت VM، و شواهد PR نیاز دارند. ## سطح فرمان -هر جریان QA زیر `pnpm openclaw qa ` اجرا می‌شود. بسیاری از آن‌ها نام مستعار اسکریپت `pnpm qa:*` +هر جریان QA زیر `pnpm openclaw qa ` اجرا می‌شود. بسیاری از آن‌ها نام‌های مستعار اسکریپتی `pnpm qa:*` دارند؛ هر دو شکل پشتیبانی می‌شوند. -| فرمان | هدف | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | خودآزمایی QA بسته‌بندی‌شده؛ یک گزارش Markdown می‌نویسد. | -| `qa suite` | سناریوهای متکی به مخزن را در برابر خط Gateway QA اجرا می‌کند. نام‌های مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM لینوکسی یک‌بارمصرف. | -| `qa coverage` | فهرست پوشش سناریوی markdown را چاپ می‌کند (`--json` برای خروجی ماشینی). | -| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عاملی را می‌نویسد. | -| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با یک گزارش داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. | -| `qa manual` | یک درخواست یک‌باره را در برابر خط provider/model انتخاب‌شده اجرا می‌کند. | -| `qa ui` | رابط اشکال‌زدایی QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | تصویر Docker از پیش پخته‌شده QA را می‌سازد. | -| `qa docker-scaffold` | یک داربست docker-compose برای داشبورد QA + خط Gateway می‌نویسد. | -| `qa up` | سایت QA را می‌سازد، پشته متکی به Docker را شروع می‌کند، و URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونه `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). | -| `qa aimock` | فقط سرور provider AIMock را شروع می‌کند. | -| `qa mock-openai` | فقط سرور provider آگاه از سناریوی `mock-openai` را شروع می‌کند. | -| `qa credentials doctor` / `add` / `list` / `remove` | مخزن مشترک اعتبارنامه Convex را مدیریت می‌کند. | -| `qa matrix` | خط انتقال زنده در برابر یک homeserver یک‌بارمصرف Tuwunel. [Matrix QA](/fa/concepts/qa-matrix) را ببینید. | -| `qa telegram` | خط انتقال زنده در برابر یک گروه خصوصی واقعی Telegram. | -| `qa discord` | خط انتقال زنده در برابر یک کانال guild خصوصی واقعی Discord. | -| `qa slack` | خط انتقال زنده در برابر یک کانال خصوصی واقعی Slack. | -| `qa mantis` | اجراکننده راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord و یک smoke دسکتاپ/مرورگر Crabbox. [Mantis](/fa/concepts/mantis) را ببینید. | +| فرمان | هدف | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | خودآزمایی QA همراه بسته؛ یک گزارش Markdown می‌نویسد. | +| `qa suite` | سناریوهای پشتیبانی‌شده با مخزن را در برابر مسیر Gateway QA اجرا می‌کند. نام مستعار: `pnpm openclaw qa suite --runner multipass` برای یک VM یک‌بارمصرف Linux. | +| `qa coverage` | موجودی پوشش سناریو به صورت markdown را چاپ می‌کند (`--json` برای خروجی ماشینی). | +| `qa parity-report` | دو فایل `qa-suite-summary.json` را مقایسه می‌کند و گزارش برابری عامل‌محور را می‌نویسد. | +| `qa character-eval` | سناریوی QA شخصیت را روی چند مدل زنده با گزارشی داوری‌شده اجرا می‌کند. [گزارش‌دهی](#reporting) را ببینید. | +| `qa manual` | یک اعلان یک‌باره را در برابر مسیر provider/model انتخاب‌شده اجرا می‌کند. | +| `qa ui` | رابط کاربری اشکال‌زدای QA و گذرگاه محلی QA را شروع می‌کند (نام مستعار: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | تصویر ازپیش‌آماده Docker QA را می‌سازد. | +| `qa docker-scaffold` | یک اسکفولد docker-compose برای داشبورد QA + مسیر Gateway می‌نویسد. | +| `qa up` | سایت QA را می‌سازد، استک پشتیبانی‌شده با Docker را شروع می‌کند، URL را چاپ می‌کند (نام مستعار: `pnpm qa:lab:up`؛ گونه `:fast` گزینه‌های `--use-prebuilt-image --bind-ui-dist --skip-ui-build` را اضافه می‌کند). | +| `qa aimock` | فقط سرور provider مربوط به AIMock را شروع می‌کند. | +| `qa mock-openai` | فقط سرور provider سناریوآگاه `mock-openai` را شروع می‌کند. | +| `qa credentials doctor` / `add` / `list` / `remove` | مخزن اعتبارنامه مشترک Convex را مدیریت می‌کند. | +| `qa matrix` | مسیر انتقال زنده در برابر یک homeserver یک‌بارمصرف Tuwunel. [Matrix QA](/fa/concepts/qa-matrix) را ببینید. | +| `qa telegram` | مسیر انتقال زنده در برابر یک گروه خصوصی واقعی Telegram. | +| `qa discord` | مسیر انتقال زنده در برابر یک کانال guild خصوصی واقعی Discord. | +| `qa slack` | مسیر انتقال زنده در برابر یک کانال خصوصی واقعی Slack. | +| `qa mantis` | اجراکننده راستی‌آزمایی قبل و بعد برای باگ‌های انتقال زنده، همراه با شواهد واکنش‌های وضعیت Discord، smoke دسکتاپ/مرورگر Crabbox، و smoke مربوط به Slack در VNC. [Mantis](/fa/concepts/mantis) را ببینید. | ## جریان اپراتور -جریان فعلی اپراتور QA یک سایت QA دو صفحه‌ای است: +جریان فعلی اپراتور QA یک سایت QA دوپنجره‌ای است: -- چپ: داشبورد Gateway (Control UI) همراه با عامل. +- چپ: داشبورد Gateway (Control UI) همراه عامل. - راست: QA Lab، که رونوشت شبیه Slack و برنامه سناریو را نشان می‌دهد. -آن را با این فرمان اجرا کنید: +آن را با این اجرا کنید: ```bash pnpm qa:lab:up ``` -این کار سایت QA را می‌سازد، خط Gateway متکی به Docker را شروع می‌کند، و صفحه -QA Lab را در دسترس قرار می‌دهد؛ جایی که یک اپراتور یا حلقه خودکارسازی می‌تواند به عامل یک مأموریت QA -بدهد، رفتار کانال واقعی را مشاهده کند، و ثبت کند چه چیزی کار کرد، شکست خورد، یا +این فرمان سایت QA را می‌سازد، مسیر Gateway پشتیبانی‌شده با Docker را شروع می‌کند، و صفحه +QA Lab را در دسترس قرار می‌دهد؛ جایی که یک اپراتور یا حلقه خودکار می‌تواند به عامل یک مأموریت QA +بدهد، رفتار واقعی کانال را مشاهده کند، و ثبت کند چه چیزی کار کرد، شکست خورد، یا مسدود ماند. -برای تکرار سریع‌تر روی رابط QA Lab بدون بازسازی تصویر Docker در هر بار، -پشته را با یک بسته QA Lab متصل‌شده از طریق bind mount شروع کنید: +برای تکرار سریع‌تر روی رابط کاربری QA Lab بدون ساخت دوباره تصویر Docker در هر بار، +استک را با یک بسته QA Lab متصل‌شده با bind mount شروع کنید: ```bash pnpm openclaw qa docker-build-image @@ -85,39 +85,39 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` سرویس‌های Docker را روی یک تصویر از پیش ساخته‌شده نگه می‌دارد و -`extensions/qa-lab/web/dist` را در کانتینر `qa-lab` به‌صورت bind-mount متصل می‌کند. `qa:lab:watch` -آن بسته را هنگام تغییر بازسازی می‌کند، و مرورگر وقتی هش دارایی QA Lab +`qa:lab:up:fast` سرویس‌های Docker را روی یک تصویر ازپیش‌ساخته نگه می‌دارد و +`extensions/qa-lab/web/dist` را داخل کانتینر `qa-lab` با bind mount متصل می‌کند. `qa:lab:watch` +آن بسته را هنگام تغییر دوباره می‌سازد، و مرورگر وقتی hash دارایی QA Lab تغییر کند به‌صورت خودکار بارگذاری مجدد می‌شود. -برای یک smoke محلی ردیابی OpenTelemetry، اجرا کنید: +برای یک smoke محلی OpenTelemetry trace، اجرا کنید: ```bash pnpm qa:otel:smoke ``` -آن اسکریپت یک گیرنده محلی ردیابی OTLP/HTTP را شروع می‌کند، سناریوی QA -`otel-trace-smoke` را با Plugin `diagnostics-otel` فعال اجرا می‌کند، سپس -spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را بررسی می‌کند: +این اسکریپت یک گیرنده trace محلی OTLP/HTTP را شروع می‌کند، سناریوی QA +`otel-trace-smoke` را با Plugin فعال `diagnostics-otel` اجرا می‌کند، سپس +spanهای protobuf صادرشده را رمزگشایی می‌کند و شکل حیاتی برای انتشار را assert می‌کند: `openclaw.run`، `openclaw.harness.run`، `openclaw.model.call`، -`openclaw.context.assembled`، و `openclaw.message.delivery` باید وجود داشته باشند؛ -فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام تشخیصی و -ویژگی‌های `openclaw.content.*` باید خارج از ردیابی بمانند. این اسکریپت -`otel-smoke-summary.json` را کنار مصنوعات مجموعه QA می‌نویسد. +`openclaw.context.assembled`، و `openclaw.message.delivery` باید حاضر باشند؛ +فراخوانی‌های مدل نباید در نوبت‌های موفق `StreamAbandoned` صادر کنند؛ شناسه‌های خام diagnostic و +attributeهای `openclaw.content.*` باید بیرون از trace بمانند. این اسکریپت +`otel-smoke-summary.json` را کنار artifactهای مجموعه QA می‌نویسد. -QA مشاهده‌پذیری فقط مخصوص checkout منبع می‌ماند. tarball npm عمداً -QA Lab را حذف می‌کند، بنابراین خط‌های انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر ابزارگذاری تشخیصی، -از `pnpm qa:otel:smoke` در یک checkout ساخته‌شده از منبع استفاده کنید. +QA مشاهده‌پذیری فقط مخصوص checkout منبع باقی می‌ماند. tarball مربوط به npm عمداً +QA Lab را حذف می‌کند، بنابراین مسیرهای انتشار Docker بسته فرمان‌های `qa` را اجرا نمی‌کنند. هنگام تغییر instrumentation تشخیصی، +از `pnpm qa:otel:smoke` در یک checkout منبع ساخته‌شده استفاده کنید. -برای یک خط smoke واقعی از نظر انتقال برای Matrix، اجرا کنید: +برای یک مسیر smoke مربوط به Matrix با انتقال واقعی، اجرا کنید: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -مرجع کامل CLI، کاتالوگ پروفایل/سناریو، متغیرهای env، و چیدمان مصنوعات برای این خط در [Matrix QA](/fa/concepts/qa-matrix) قرار دارد. در یک نگاه: این فرمان یک homeserver یک‌بارمصرف Tuwunel را در Docker فراهم می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA محدود به همان انتقال اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصه JSON، مصنوع observed-events، و لاگ خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-/` می‌نویسد. +مرجع کامل CLI، کاتالوگ profile/scenario، env varها، و چیدمان artifact برای این مسیر در [Matrix QA](/fa/concepts/qa-matrix) قرار دارد. در یک نگاه: این مسیر یک homeserver یک‌بارمصرف Tuwunel را در Docker فراهم می‌کند، کاربران موقت driver/SUT/observer را ثبت می‌کند، Plugin واقعی Matrix را داخل یک Gateway فرزند QA محدود به همان انتقال اجرا می‌کند (بدون `qa-channel`)، سپس یک گزارش Markdown، خلاصه JSON، artifact رویدادهای مشاهده‌شده، و log خروجی ترکیبی را زیر `.artifacts/qa-e2e/matrix-/` می‌نویسد. -برای خط‌های smoke واقعی از نظر انتقال برای Telegram، Discord، و Slack: +برای مسیرهای smoke با انتقال واقعی Telegram، Discord، و Slack: ```bash pnpm openclaw qa telegram @@ -125,92 +125,107 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -آن‌ها یک کانال واقعی از پیش موجود با دو ربات (driver + SUT) را هدف می‌گیرند. متغیرهای env لازم، فهرست سناریوها، مصنوعات خروجی، و مخزن اعتبارنامه Convex در [مرجع QA برای Telegram، Discord، و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند. +این مسیرها یک کانال واقعی ازپیش‌موجود با دو bot (driver + SUT) را هدف می‌گیرند. env varهای لازم، فهرست‌های سناریو، artifactهای خروجی، و مخزن اعتبارنامه Convex در [مرجع QA مربوط به Telegram، Discord، و Slack](#telegram-discord-and-slack-qa-reference) در ادامه مستند شده‌اند. -قبل از استفاده از اعتبارنامه‌های زنده تجمیع‌شده، اجرا کنید: +برای یک اجرای کامل Slack desktop VM همراه نجات VNC، اجرا کنید: + +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` + +این فرمان یک ماشین دسکتاپ/مرورگر Crabbox را lease می‌کند، مسیر زنده Slack را +داخل VM اجرا می‌کند، Slack Web را در مرورگر VNC باز می‌کند، از دسکتاپ تصویر می‌گیرد، و +`slack-qa/` به‌همراه `slack-desktop-smoke.png` را به دایرکتوری artifact +Mantis برمی‌گرداند. پس از ورود دستی به Slack Web از طریق VNC، +`--lease-id ` را دوباره استفاده کنید. با `--gateway-setup`، Mantis یک Gateway پایدار OpenClaw Slack را +داخل VM روی پورت `38973` در حال اجرا باقی می‌گذارد؛ بدون آن، فرمان مسیر QA معمولی +bot-to-bot مربوط به Slack را اجرا می‌کند و پس از ضبط artifact خارج می‌شود. + +پیش از استفاده از اعتبارنامه‌های زنده pooled، اجرا کنید: ```bash pnpm openclaw qa credentials doctor ``` -doctor متغیرهای env کارگزار Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند، و وقتی secret نگهدارنده حاضر باشد دسترسی‌پذیری admin/list را راستی‌آزمایی می‌کند. برای secretها فقط وضعیت تنظیم‌شده/مفقود را گزارش می‌دهد. +doctor محیط broker مربوط به Convex را بررسی می‌کند، تنظیمات endpoint را اعتبارسنجی می‌کند، و وقتی secret نگه‌دارنده حاضر باشد دسترسی admin/list را تأیید می‌کند. برای secretها فقط وضعیت set/missing را گزارش می‌دهد. ## پوشش انتقال زنده -خط‌های انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خودشان را اختراع کنند، یک قرارداد مشترک دارند. `qa-channel` مجموعه مصنوعی گسترده رفتار محصول است و بخشی از ماتریس پوشش انتقال زنده نیست. +مسیرهای انتقال زنده به‌جای اینکه هرکدام شکل فهرست سناریوی خودشان را بسازند، یک قرارداد مشترک دارند. `qa-channel` مجموعه گسترده رفتار محصول به‌صورت مصنوعی است و بخشی از ماتریس پوشش انتقال زنده نیست. -| خط | Canary | دروازه‌بانی mention | ربات-به-ربات | مسدودسازی allowlist | پاسخ سطح بالا | ازسرگیری پس از restart | پیگیری رشته | جداسازی رشته | مشاهده واکنش | فرمان help | ثبت فرمان بومی | +| مسیر | Canary | دروازه‌گذاری mention | Bot-to-bot | مسدودسازی allowlist | پاسخ سطح بالا | ازسرگیری پس از restart | پیگیری رشته | جداسازی رشته | مشاهده واکنش | فرمان help | ثبت فرمان بومی | | -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | | Matrix | x | x | x | x | x | x | x | x | x | | | | Telegram | x | x | x | | | | | | | x | | | Discord | x | x | x | | | | | | | | x | | Slack | x | x | x | | | | | | | | | -این کار `qa-channel` را به‌عنوان مجموعه گسترده رفتار محصول نگه می‌دارد، در حالی که Matrix، -Telegram، و انتقال‌های زنده آینده یک چک‌لیست صریح قرارداد انتقال را -به اشتراک می‌گذارند. +این کار `qa-channel` را به‌عنوان مجموعه گسترده رفتار محصول نگه می‌دارد، درحالی‌که Matrix، +Telegram، و انتقال‌های زنده آینده یک چک‌لیست صریح قرارداد انتقال مشترک دارند. -برای یک خط VM لینوکسی یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید: +برای یک مسیر Linux VM یک‌بارمصرف بدون وارد کردن Docker به مسیر QA، اجرا کنید: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -این فرمان یک مهمان تازه Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را -داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش QA معمول و +این کار یک مهمان تازه Multipass را بوت می‌کند، وابستگی‌ها را نصب می‌کند، OpenClaw را +داخل مهمان می‌سازد، `qa suite` را اجرا می‌کند، سپس گزارش عادی QA و خلاصه را به `.artifacts/qa-e2e/...` روی میزبان کپی می‌کند. -این همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد دوباره استفاده می‌کند. -اجراهای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی -با workerهای Gateway ایزوله اجرا می‌کنند. مقدار پیش‌فرض هم‌روندی `qa-channel` -4 است و به تعداد سناریوهای انتخاب‌شده محدود می‌شود. برای تنظیم -تعداد workerها از `--concurrency ` استفاده کنید، یا برای اجرای سریالی -`--concurrency 1` را به کار ببرید. -وقتی هر سناریویی شکست بخورد، فرمان با مقدار غیرصفر خارج می‌شود. وقتی -مصنوعات را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. -اجراهای زنده ورودی‌های پشتیبانی‌شده احراز هویت QA را که برای -مهمان عملی هستند ارسال می‌کنند: کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و -`CODEX_HOME` وقتی حاضر باشد. `--output-dir` را زیر ریشه مخزن نگه دارید تا مهمان -بتواند از طریق workspace متصل‌شده دوباره بنویسد. +این همان رفتار انتخاب سناریو را که `qa suite` روی میزبان دارد، دوباره استفاده می‌کند. +اجرای مجموعه روی میزبان و Multipass به‌صورت پیش‌فرض چند سناریوی انتخاب‌شده را به‌طور موازی +با workerهای Gateway ایزوله اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض هم‌روندی +4 دارد که به تعداد سناریوهای انتخاب‌شده محدود می‌شود. از `--concurrency ` برای تنظیم +تعداد workerها، یا از `--concurrency 1` برای اجرای سریالی استفاده کنید. +وقتی هر سناریویی شکست بخورد، فرمان با کد غیرصفر خارج می‌شود. وقتی +artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. +اجرای زنده ورودی‌های پشتیبانی‌شده احراز هویت QA را که برای مهمان عملی هستند +forward می‌کند: کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و +`CODEX_HOME` در صورت وجود. `--output-dir` را زیر ریشه repo نگه دارید تا مهمان +بتواند از طریق workspace mountشده بنویسد. ## مرجع QA برای Telegram، Discord، و Slack -Matrix به‌دلیل تعداد سناریوها و فراهم‌سازی homeserver متکی به Docker، یک [صفحه اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord، و Slack کوچک‌تر هستند - هرکدام چند سناریو، بدون سیستم پروفایل، در برابر کانال‌های واقعی از پیش موجود - بنابراین مرجع آن‌ها اینجا قرار دارد. +Matrix به‌دلیل تعداد سناریوها و آماده‌سازی homeserver مبتنی بر Docker یک [صفحه اختصاصی](/fa/concepts/qa-matrix) دارد. Telegram، Discord، و Slack کوچک‌تر هستند — هرکدام چند سناریو، بدون سیستم profile، در برابر کانال‌های واقعی از پیش موجود — بنابراین مرجع آن‌ها اینجا قرار دارد. ### پرچم‌های مشترک CLI -این خط‌ها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند: +این laneها از طریق `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` ثبت می‌شوند و همان پرچم‌ها را می‌پذیرند: | پرچم | پیش‌فرض | توضیح | | ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `--scenario ` | — | فقط این سناریو را اجرا می‌کند. قابل تکرار است. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | محل نوشته شدن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` تفسیر می‌شوند. | -| `--repo-root ` | `process.cwd()` | ریشه مخزن هنگام فراخوانی از یک cwd خنثی. | -| `--sut-account ` | `sut` | شناسه حساب موقت داخل پیکربندی QA Gateway. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | محل نوشتن گزارش‌ها/خلاصه/پیام‌های مشاهده‌شده و لاگ خروجی. مسیرهای نسبی نسبت به `--repo-root` resolve می‌شوند. | +| `--repo-root ` | `process.cwd()` | ریشه repository هنگام فراخوانی از یک cwd خنثی. | +| `--sut-account ` | `sut` | id حساب موقت داخل پیکربندی Gateway QA. | | `--provider-mode ` | `live-frontier` | `mock-openai` یا `live-frontier`؛ مقدار قدیمی `live-openai` همچنان کار می‌کند. | -| `--model ` / `--alt-model ` | پیش‌فرض ارائه‌دهنده | ارجاع‌های مدل اصلی/جایگزین. | -| `--fast` | خاموش | حالت سریع ارائه‌دهنده در جاهایی که پشتیبانی شود. | +| `--model ` / `--alt-model ` | پیش‌فرض provider | refهای model اصلی/جایگزین. | +| `--fast` | خاموش | حالت سریع provider در جاهایی که پشتیبانی می‌شود. | | `--credential-source ` | `env` | [استخر اعتبارنامه Convex](#convex-credential-pool) را ببینید. | | `--credential-role ` | `ci` در CI، در غیر این صورت `maintainer` | نقشی که هنگام `--credential-source convex` استفاده می‌شود. | -هر lane در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` آرتیفکت‌ها را بدون تنظیم کد خروجی شکست‌خورده می‌نویسد. +هر lane در صورت شکست هر سناریو با کد غیرصفر خارج می‌شود. `--allow-failures` artifactها را بدون تنظیم کد خروج شکست‌خورده می‌نویسد. -### QA در Telegram +### QA برای Telegram ```bash pnpm openclaw qa telegram ``` -یک گروه خصوصی واقعی Telegram را با دو ربات متمایز هدف می‌گیرد (driver + SUT). ربات SUT باید نام کاربری Telegram داشته باشد؛ مشاهده ربات‌به‌ربات زمانی بهتر کار می‌کند که هر دو ربات **حالت ارتباط ربات‌به‌ربات** را در `@BotFather` فعال کرده باشند. +یک گروه خصوصی واقعی Telegram را با دو bot متمایز (driver + SUT) هدف می‌گیرد. bot مربوط به SUT باید username در Telegram داشته باشد؛ مشاهده bot-to-bot وقتی بهتر کار می‌کند که هر دو bot **Bot-to-Bot Communication Mode** را در `@BotFather` فعال کرده باشند. -env لازم هنگام `--credential-source env`: +envهای لازم هنگام `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — شناسه عددی چت (رشته). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — chat id عددی (string). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` اختیاری: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد (پیش‌فرض آن‌ها را ویرایش می‌کند). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد (پیش‌فرض redact می‌کند). سناریوها (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -223,38 +238,38 @@ env لازم هنگام `--credential-source env`: - `telegram-whoami-command` - `telegram-context-command` -آرتیفکت‌های خروجی: +artifactهای خروجی: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — شامل RTT هر پاسخ (ارسال driver → پاسخ مشاهده‌شده SUT) که از canary شروع می‌شود. -- `telegram-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` باشد. +- `telegram-qa-summary.json` — شامل RTT برای هر reply (ارسال driver → reply مشاهده‌شده SUT) از canary به بعد. +- `telegram-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` باشد. -### QA در Discord +### QA برای Discord ```bash pnpm openclaw qa discord ``` -یک کانال guild خصوصی واقعی Discord را با دو ربات هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط OpenClaw Gateway فرزند از طریق Plugin داخلی Discord شروع می‌شود. مدیریت mention کانال، اینکه ربات SUT دستور بومی `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد opt-in مربوط به Mantis را بررسی می‌کند. +یک کانال guild خصوصی واقعی Discord را با دو bot هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Discord راه‌اندازی می‌شود. مدیریت mention کانال، اینکه bot مربوط به SUT فرمان native `/help` را در Discord ثبت کرده باشد، و سناریوهای شواهد Mantis به‌صورت opt-in را بررسی می‌کند. -env لازم هنگام `--credential-source env`: +envهای لازم هنگام `--credential-source env`: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با شناسه کاربر ربات SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت lane سریع شکست می‌خورد). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — باید با id کاربر bot مربوط به SUT که Discord برمی‌گرداند مطابقت داشته باشد (در غیر این صورت lane زود شکست می‌خورد). اختیاری: -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد. +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد. سناریوها (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`): - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — سناریوی opt-in مربوط به Mantis. به‌تنهایی اجرا می‌شود، چون SUT را به پاسخ‌های guild همیشه‌فعال و فقط‌ابزاری با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک خط زمانی واکنش REST به‌همراه یک آرتیفکت بصری HTML/PNG ثبت می‌کند. +- `discord-status-reactions-tool-only` — سناریوی opt-in Mantis. به‌تنهایی اجرا می‌شود چون SUT را به replyهای guild همیشه‌فعال و فقط ابزاری با `messages.statusReactions.enabled=true` تغییر می‌دهد، سپس یک timeline واکنش REST به‌همراه یک artifact بصری HTML/PNG ثبت می‌کند. سناریوی واکنش وضعیت Mantis را صراحتا اجرا کنید: @@ -267,22 +282,22 @@ pnpm openclaw qa discord \ --fast ``` -آرتیفکت‌های خروجی: +artifactهای خروجی: - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` باشد. -- `discord-qa-reaction-timelines.json` و `discord-status-reactions-tool-only-timeline.png` هنگام اجرای سناریوی واکنش وضعیت. +- `discord-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` باشد. +- `discord-qa-reaction-timelines.json` و `discord-status-reactions-tool-only-timeline.png` وقتی سناریوی واکنش وضعیت اجرا شود. -### QA در Slack +### QA برای Slack ```bash pnpm openclaw qa slack ``` -یک کانال خصوصی واقعی Slack را با دو ربات متمایز هدف می‌گیرد: یک ربات driver که توسط harness کنترل می‌شود و یک ربات SUT که توسط OpenClaw Gateway فرزند از طریق Plugin داخلی Slack شروع می‌شود. +یک کانال خصوصی واقعی Slack را با دو bot متمایز هدف می‌گیرد: یک bot driver که توسط harness کنترل می‌شود و یک bot SUT که توسط Gateway فرزند OpenClaw از طریق Plugin بسته‌بندی‌شده Slack راه‌اندازی می‌شود. -env لازم هنگام `--credential-source env`: +envهای لازم هنگام `--credential-source env`: - `OPENCLAW_QA_SLACK_CHANNEL_ID` - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` @@ -291,143 +306,146 @@ env لازم هنگام `--credential-source env`: اختیاری: -- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه پیام‌ها را در آرتیفکت‌های پیام مشاهده‌شده نگه می‌دارد. +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` بدنه پیام‌ها را در artifactهای پیام مشاهده‌شده نگه می‌دارد. سناریوها (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`): - `slack-canary` - `slack-mention-gating` -آرتیفکت‌های خروجی: +artifactهای خروجی: - `slack-qa-report.md` - `slack-qa-summary.json` -- `slack-qa-observed-messages.json` — بدنه‌ها ویرایش می‌شوند مگر اینکه `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` باشد. +- `slack-qa-observed-messages.json` — بدنه‌ها redact می‌شوند مگر اینکه `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` باشد. ### استخر اعتبارنامه Convex -laneهای Telegram، Discord و Slack می‌توانند به‌جای خواندن env vars بالا، اعتبارنامه‌ها را از یک استخر مشترک Convex اجاره کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک اجاره انحصاری می‌گیرد، در طول اجرا برای آن Heartbeat می‌فرستد، و هنگام خاموش شدن آن را آزاد می‌کند. انواع استخر `"telegram"`، `"discord"` و `"slack"` هستند. +laneهای Telegram، Discord، و Slack می‌توانند به‌جای خواندن env varهای بالا، اعتبارنامه‌ها را از یک استخر مشترک Convex اجاره کنند. `--credential-source convex` را پاس دهید (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید)؛ QA Lab یک lease انحصاری دریافت می‌کند، در طول اجرا برای آن heartbeat می‌فرستد، و هنگام shutdown آن را آزاد می‌کند. انواع استخر `"telegram"`، `"discord"`، و `"slack"` هستند. -شکل payloadهایی که broker در `admin/add` اعتبارسنجی می‌کند: +شکل payloadهایی که broker روی `admin/add` اعتبارسنجی می‌کند: -- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک رشته chat-id عددی باشد. +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` باید یک string عددی chat-id باشد. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -env vars عملیاتی و قرارداد endpoint مربوط به broker در [آزمایش → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش به پیش از پشتیبانی Discord برمی‌گردد؛ معناشناسی broker برای هر دو نوع یکسان است). +env varهای عملیاتی و قرارداد endpoint مربوط به broker در Convex در [Testing → اعتبارنامه‌های مشترک Telegram از طریق Convex](/fa/help/testing#shared-telegram-credentials-via-convex-v1) قرار دارند (نام بخش پیش از پشتیبانی Discord انتخاب شده است؛ معناشناسی broker برای هر دو نوع یکسان است). -## seedهای پشتیبانی‌شده توسط مخزن +## seedهای مبتنی بر repo -دارایی‌های seed در `qa/` قرار دارند: +assetهای seed در `qa/` قرار دارند: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -این‌ها عمدا در git هستند تا طرح QA هم برای انسان‌ها و هم برای +این‌ها عمدا در git هستند تا برنامه QA هم برای انسان‌ها و هم برای agent قابل مشاهده باشد. -`qa-lab` باید یک اجراکننده markdown عمومی باقی بماند. هر فایل markdown سناریو -منبع حقیقت برای یک اجرای آزمایش است و باید موارد زیر را تعریف کند: +`qa-lab` باید یک runner عمومی markdown باقی بماند. هر فایل markdown سناریو +source of truth برای یک اجرای test است و باید موارد زیر را تعریف کند: -- فراداده سناریو -- فراداده اختیاری category، capability، lane و risk -- ارجاع‌های مستندات و کد -- الزامات اختیاری Plugin +- metadata سناریو +- metadata اختیاری category، capability، lane، و risk +- refهای docs و code +- نیازمندی‌های اختیاری Plugin - patch اختیاری پیکربندی Gateway -- `qa-flow` اجرایی +- `qa-flow` قابل اجرا -سطح runtime قابل استفاده مجددی که پشتوانه `qa-flow` است مجاز است عمومی -و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport -را با helperهای سمت مرورگر ترکیب کنند که Control UI توکار را از طریق seam -`browser.request` مربوط به Gateway هدایت می‌کنند، بدون اینکه runner مورد خاص اضافه شود. +سطح runtime قابل استفاده مجدد که پشتوانه `qa-flow` است اجازه دارد عمومی +و cross-cutting باقی بماند. برای مثال، سناریوهای markdown می‌توانند helperهای سمت transport را +با helperهای سمت browser ترکیب کنند که Control UI جاسازی‌شده را از طریق +درز `browser.request` در Gateway پیش می‌برند، بدون اینکه runner ویژه اضافه شود. -فایل‌های سناریو باید بر اساس قابلیت محصول گروه‌بندی شوند، نه پوشه -درخت منبع. هنگام جابه‌جایی فایل‌ها، شناسه‌های سناریو را پایدار نگه دارید؛ برای traceability پیاده‌سازی از `docsRefs` و `codeRefs` -استفاده کنید. +فایل‌های سناریو باید بر اساس قابلیت محصول گروه‌بندی شوند، نه بر اساس پوشه +source tree. وقتی فایل‌ها جابه‌جا می‌شوند، IDهای سناریو را پایدار نگه دارید؛ از `docsRefs` و `codeRefs` +برای traceability پیاده‌سازی استفاده کنید. -فهرست baseline باید به‌اندازه‌ای گسترده بماند که موارد زیر را پوشش دهد: +فهرست baseline باید به‌اندازه کافی گسترده بماند تا موارد زیر را پوشش دهد: -- چت DM و کانال +- chat در DM و کانال - رفتار thread - چرخه عمر action پیام - callbackهای cron - recall حافظه -- تغییر مدل -- handoff زیرagent -- خواندن مخزن و خواندن مستندات -- یک وظیفه کوچک build مانند Lobster Invaders +- تغییر model +- تحویل به subagent +- خواندن repo و خواندن docs +- یک task کوچک build مانند Lobster Invaders -## laneهای mock ارائه‌دهنده +## laneهای mock provider -`qa suite` دو lane mock ارائه‌دهنده محلی دارد: +`qa suite` دو lane محلی mock provider دارد: -- `mock-openai` همان mock سناریوآگاه OpenClaw است. این lane به‌عنوان lane mock قطعی پیش‌فرض برای QA پشتیبانی‌شده توسط مخزن و parity gateها باقی می‌ماند. -- `aimock` یک سرور ارائه‌دهنده پشتیبانی‌شده با AIMock را برای پوشش آزمایشی protocol، fixture، record/replay و chaos شروع می‌کند. این مورد افزایشی است و جایگزین dispatcher سناریوی `mock-openai` نمی‌شود. +- `mock-openai` mock سناریوآگاه OpenClaw است. این lane همچنان lane پیش‌فرض + mock قطعی برای QA مبتنی بر repo و parity gateها باقی می‌ماند. +- `aimock` یک server provider مبتنی بر AIMock را برای پوشش آزمایشی protocol، + fixture، record/replay، و chaos شروع می‌کند. این مورد افزایشی است و + dispatcher سناریوی `mock-openai` را جایگزین نمی‌کند. -پیاده‌سازی lane ارائه‌دهنده زیر `extensions/qa-lab/src/providers/` قرار دارد. -هر ارائه‌دهنده مالک پیش‌فرض‌های خود، راه‌اندازی سرور محلی، پیکربندی مدل Gateway، -نیازهای staging مربوط به auth-profile، و پرچم‌های قابلیت live/mock است. کد suite و -Gateway مشترک باید به‌جای branch زدن بر اساس نام‌های ارائه‌دهنده، از طریق registry ارائه‌دهنده route شود. +پیاده‌سازی provider-lane زیر `extensions/qa-lab/src/providers/` قرار دارد. +هر provider مالک پیش‌فرض‌ها، startup server محلی، پیکربندی model در Gateway، +نیازهای staging مربوط به auth-profile، و پرچم‌های capability زنده/mock خودش است. کد suite و +Gateway مشترک باید به‌جای branching بر اساس نام providerها، از registry provider عبور کند. ## adapterهای transport -`qa-lab` مالک یک seam عمومی transport برای سناریوهای QA در markdown است. `qa-channel` نخستین adapter روی این seam است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا مصنوعی آینده باید به‌جای افزودن یک QA runner مخصوص transport، به همان suite runner متصل شوند. +`qa-lab` مالک یک درز عمومی transport برای سناریوهای markdown QA است. `qa-channel` اولین adapter روی آن درز است، اما هدف طراحی گسترده‌تر است: کانال‌های واقعی یا synthetic آینده باید به‌جای افزودن runner مخصوص transport برای QA، به همان runner مجموعه وصل شوند. -در سطح معماری، این تقسیم چنین است: +در سطح معماری، تقسیم به این صورت است: -- `qa-lab` مالک اجرای عمومی سناریو، هم‌زمانی worker، نوشتن آرتیفکت، و گزارش‌دهی است. -- adapter transport مالک پیکربندی Gateway، آمادگی، مشاهده ورودی و خروجی، actionهای transport، و وضعیت normalized transport است. -- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای آزمایش را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفاده مجددی را فراهم می‌کند که آن‌ها را اجرا می‌کند. +- `qa-lab` مالک اجرای عمومی سناریو، هم‌روندی worker، نوشتن artifact، و reporting است. +- adapter transport مالک پیکربندی Gateway، readiness، مشاهده inbound و outbound، actionهای transport، و وضعیت normalized transport است. +- فایل‌های سناریوی markdown زیر `qa/scenarios/` اجرای test را تعریف می‌کنند؛ `qa-lab` سطح runtime قابل استفاده مجدد را فراهم می‌کند که آن‌ها را اجرا می‌کند. -### افزودن یک کانال +### افزودن کانال -افزودن یک کانال به سامانه QA در markdown دقیقا به دو چیز نیاز دارد: +افزودن یک کانال به سیستم QA مبتنی بر markdown دقیقا به دو چیز نیاز دارد: 1. یک adapter transport برای کانال. -2. یک بسته سناریو که قرارداد کانال را تمرین کند. +2. یک بسته سناریو که قرارداد کانال را تمرین دهد. -وقتی میزبان مشترک `qa-lab` می‌تواند مالک flow باشد، root جدیدی برای فرمان QA در سطح بالا اضافه نکنید. +وقتی host مشترک `qa-lab` می‌تواند مالک flow باشد، ریشه فرمان QA سطح‌بالای جدید اضافه نکنید. -`qa-lab` مالک سازوکارهای میزبان مشترک است: +`qa-lab` مکانیک‌های میزبان مشترک را در اختیار دارد: -- root فرمان `openclaw qa` -- راه‌اندازی و teardown مربوط به suite -- هم‌زمانی worker -- نوشتن آرتیفکت +- ریشه فرمان `openclaw qa` +- راه‌اندازی و پاک‌سازی مجموعه +- هم‌روندی worker +- نوشتن artifact - تولید گزارش - اجرای سناریو - aliasهای سازگاری برای سناریوهای قدیمی‌تر `qa-channel` -Pluginهای runner مالک قرارداد transport هستند: +Pluginهای اجراکننده قرارداد انتقال را در اختیار دارند: -- اینکه `openclaw qa ` چگونه زیر root مشترک `qa` mount می‌شود -- اینکه Gateway چگونه برای آن transport پیکربندی می‌شود +- اینکه `openclaw qa ` چگونه زیر ریشه مشترک `qa` mount می‌شود +- اینکه Gateway برای آن انتقال چگونه پیکربندی می‌شود - اینکه آمادگی چگونه بررسی می‌شود -- اینکه eventهای ورودی چگونه تزریق می‌شوند +- اینکه رویدادهای ورودی چگونه تزریق می‌شوند - اینکه پیام‌های خروجی چگونه مشاهده می‌شوند -- اینکه transcriptها و وضعیت normalized transport چگونه در دسترس قرار می‌گیرند -- اینکه actionهای پشتیبانی‌شده با transport چگونه اجرا می‌شوند -- اینکه reset یا cleanup مخصوص transport چگونه مدیریت می‌شود +- اینکه transcriptها و وضعیت نرمال‌سازی‌شده انتقال چگونه عرضه می‌شوند +- اینکه اقدام‌های پشتوانه‌دار با انتقال چگونه اجرا می‌شوند +- اینکه بازنشانی یا پاک‌سازی ویژه انتقال چگونه انجام می‌شود حداقل سطح پذیرش برای یک کانال جدید: -1. `qa-lab` را مالک ریشهٔ مشترک `qa` نگه دارید. -2. اجراکنندهٔ انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید. -3. سازوکارهای ویژهٔ انتقال را داخل Plugin اجراکننده یا harness کانال نگه دارید. -4. اجراکننده را به‌صورت `openclaw qa ` mount کنید، نه با ثبت یک فرمان ریشهٔ رقیب. Pluginهای اجراکننده باید `qaRunners` را در `openclaw.plugin.json` اعلام کنند و آرایهٔ متناظر `qaRunnerCliRegistrations` را از `runtime-api.ts` export کنند. `runtime-api.ts` را سبک نگه دارید؛ CLI تنبل و اجرای runner باید پشت entrypointهای جداگانه بمانند. -5. سناریوهای markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا تطبیق دهید. -6. برای سناریوهای جدید از helperهای عمومی سناریو استفاده کنید. +1. `qa-lab` را مالک ریشه مشترک `qa` نگه دارید. +2. اجراکننده انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید. +3. مکانیک‌های ویژه انتقال را داخل Plugin اجراکننده یا harness کانال نگه دارید. +4. اجراکننده را به‌صورت `openclaw qa ` mount کنید، نه با ثبت یک فرمان ریشه رقیب. Pluginهای اجراکننده باید `qaRunners` را در `openclaw.plugin.json` اعلام کنند و آرایه مطابق `qaRunnerCliRegistrations` را از `runtime-api.ts` صادر کنند. `runtime-api.ts` را سبک نگه دارید؛ CLI تنبل و اجرای runner باید پشت entrypointهای جداگانه بمانند. +5. سناریوهای Markdown را زیر دایرکتوری‌های موضوعی `qa/scenarios/` بنویسید یا سازگار کنید. +6. برای سناریوهای جدید از helperهای سناریوی عمومی استفاده کنید. 7. aliasهای سازگاری موجود را فعال نگه دارید، مگر اینکه repo در حال انجام یک مهاجرت عمدی باشد. -قاعدهٔ تصمیم‌گیری سخت‌گیرانه است: +قاعده تصمیم‌گیری سخت‌گیرانه است: -- اگر رفتار را می‌توان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید. -- اگر رفتار به انتقال یک کانال وابسته است، آن را در همان Plugin اجراکننده یا harness Plugin نگه دارید. -- اگر یک سناریو به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای شاخهٔ ویژهٔ کانال در `suite.ts` یک helper عمومی اضافه کنید. -- اگر یک رفتار فقط برای یک انتقال معنادار است، سناریو را ویژهٔ همان انتقال نگه دارید و این را در قرارداد سناریو صریح کنید. +- اگر رفتاری را می‌توان یک‌بار در `qa-lab` بیان کرد، آن را در `qa-lab` قرار دهید. +- اگر رفتاری به انتقال یک کانال وابسته است، آن را در همان Plugin اجراکننده یا harness Plugin نگه دارید. +- اگر سناریویی به قابلیت جدیدی نیاز دارد که بیش از یک کانال می‌تواند از آن استفاده کند، به‌جای شاخه ویژه کانال در `suite.ts` یک helper عمومی اضافه کنید. +- اگر رفتاری فقط برای یک انتقال معنی‌دار است، سناریو را ویژه همان انتقال نگه دارید و این را در قرارداد سناریو صریح کنید. ### نام‌های helper سناریو -helperهای عمومی ترجیحی برای سناریوهای جدید: +helperهای عمومی پیشنهادی برای سناریوهای جدید: - `waitForTransportReady` - `waitForChannelReady` @@ -442,21 +460,21 @@ helperهای عمومی ترجیحی برای سناریوهای جدید: - `formatTransportTranscript` - `resetTransport` -aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس هستند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نوشتن سناریوهای جدید باید از نام‌های عمومی استفاده کند. این aliasها برای جلوگیری از یک مهاجرت flag-day وجود دارند، نه به‌عنوان مدل آینده. +aliasهای سازگاری برای سناریوهای موجود همچنان در دسترس‌اند — `waitForQaChannelReady`، `waitForOutboundMessage`، `waitForNoOutbound`، `formatConversationTranscript`، `resetBus` — اما نگارش سناریوهای جدید باید از نام‌های عمومی استفاده کند. این aliasها برای جلوگیری از یک مهاجرت یک‌باره وجود دارند، نه به‌عنوان الگوی آینده. ## گزارش‌دهی -`qa-lab` یک گزارش پروتکل Markdown را از timeline مشاهده‌شدهٔ bus export می‌کند. -گزارش باید به این موارد پاسخ دهد: +`qa-lab` یک گزارش پروتکل Markdown را از timeline مشاهده‌شده bus صادر می‌کند. +گزارش باید پاسخ دهد: -- چه چیزهایی کار کرد -- چه چیزهایی شکست خورد -- چه چیزهایی همچنان مسدود ماند -- چه سناریوهای پیگیری‌ای ارزش اضافه شدن دارند +- چه چیزی کار کرد +- چه چیزی شکست خورد +- چه چیزی مسدود ماند +- چه سناریوهای پیگیری ارزش اضافه‌شدن دارند -برای فهرست سناریوهای موجود — که هنگام برآورد کارهای پیگیری یا سیم‌کشی یک انتقال جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (برای خروجی قابل‌خواندن توسط ماشین، `--json` را اضافه کنید). +برای inventory سناریوهای موجود — که هنگام اندازه‌گیری کار پیگیری یا وصل‌کردن یک انتقال جدید مفید است — `pnpm openclaw qa coverage` را اجرا کنید (`--json` را برای خروجی قابل‌خواندن برای ماشین اضافه کنید). -برای بررسی‌های شخصیت و سبک، همان سناریو را روی چندین ref مدل زنده اجرا کنید +برای بررسی‌های کاراکتر و سبک، همان سناریو را روی چندین ref مدل زنده اجرا کنید و یک گزارش Markdown داوری‌شده بنویسید: ```bash @@ -476,41 +494,42 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -این فرمان processهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی شخصیت -باید persona را از طریق `SOUL.md` تنظیم کنند، سپس turnهای معمول کاربر -مانند chat، کمک workspace، و taskهای کوچک فایل را اجرا کنند. به مدل کاندیدا نباید -گفته شود که در حال ارزیابی شدن است. این فرمان هر transcript کامل را حفظ می‌کند، -آمار پایهٔ اجرا را ثبت می‌کند، سپس از مدل‌های داور در حالت fast با reasoning -`xhigh` در جاهایی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی بودن، vibe، و طنز رتبه‌بندی کنند. -هنگام مقایسهٔ providerها از `--blind-judge-models` استفاده کنید: prompt داور همچنان -هر transcript و وضعیت اجرا را دریافت می‌کند، اما refهای کاندیدا با labelهای خنثی -مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از parsing رتبه‌بندی‌ها را دوباره به refهای واقعی map می‌کند. -اجراهای کاندیدا به‌طور پیش‌فرض از thinking سطح `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh` -برای refهای قدیمی‌تر ارزیابی OpenAI که از آن پشتیبانی می‌کنند. یک کاندیدای مشخص را به‌صورت inline با +این فرمان فرایندهای فرزند Gateway محلی QA را اجرا می‌کند، نه Docker. سناریوهای ارزیابی کاراکتر +باید persona را از طریق `SOUL.md` تنظیم کنند، سپس نوبت‌های عادی کاربر +مانند chat، کمک workspace و کارهای کوچک فایل را اجرا کنند. به مدل candidate نباید +گفته شود که در حال ارزیابی است. این فرمان هر transcript کامل را حفظ می‌کند، +آمار پایه اجرا را ثبت می‌کند، سپس از مدل‌های judge در حالت سریع با +استدلال `xhigh` در جاهایی که پشتیبانی می‌شود می‌خواهد اجراها را بر اساس طبیعی‌بودن، حس‌وحال و شوخ‌طبعی رتبه‌بندی کنند. +هنگام مقایسه providerها از `--blind-judge-models` استفاده کنید: prompt داور همچنان +هر transcript و وضعیت اجرا را دریافت می‌کند، اما refهای candidate با +برچسب‌های خنثی مانند `candidate-01` جایگزین می‌شوند؛ گزارش پس از +parsing رتبه‌بندی‌ها را دوباره به refهای واقعی نگاشت می‌کند. +اجراهای candidate به‌صورت پیش‌فرض از thinking برابر `high` استفاده می‌کنند، با `medium` برای GPT-5.5 و `xhigh` +برای refهای ارزیابی قدیمی‌تر OpenAI که از آن پشتیبانی می‌کنند. یک candidate مشخص را به‌صورت inline با `--model provider/model,thinking=` override کنید. `--thinking ` همچنان یک fallback سراسری تنظیم می‌کند، و فرم قدیمی‌تر `--model-thinking ` برای -سازگاری حفظ شده است. -refهای کاندیدای OpenAI به‌طور پیش‌فرض در حالت fast هستند تا در جاهایی که -provider پشتیبانی می‌کند از پردازش اولویت‌دار استفاده شود. وقتی یک -کاندیدا یا داور منفرد به override نیاز دارد، `,fast`، `,no-fast`، یا `,fast=false` را inline اضافه کنید. فقط زمانی `--fast` را pass کنید که می‌خواهید -حالت fast را برای همهٔ مدل‌های کاندیدا force کنید. مدت‌زمان کاندیدا و داور -برای تحلیل benchmark در گزارش ثبت می‌شود، اما promptهای داور صراحتا می‌گویند -که بر اساس سرعت رتبه‌بندی نکنند. -اجراهای مدل کاندیدا و داور هر دو به‌طور پیش‌فرض concurrency 16 دارند. وقتی محدودیت‌های -provider یا فشار Gateway محلی یک اجرا را بیش از حد noisy می‌کند، `--concurrency` -یا `--judge-concurrency` را کاهش دهید. -وقتی هیچ `--model` کاندیدایی pass نشود، character eval به‌طور پیش‌فرض از +سازگاری نگه داشته شده است. +refهای candidate مربوط به OpenAI به‌صورت پیش‌فرض در حالت fast هستند تا در جاهایی که +provider پشتیبانی می‌کند از پردازش priority استفاده شود. وقتی یک +candidate یا judge تکی به override نیاز دارد، `,fast`، `,no-fast` یا `,fast=false` را inline اضافه کنید. فقط وقتی `--fast` را پاس بدهید که می‌خواهید +حالت fast را برای همه مدل‌های candidate اجباری کنید. مدت‌زمان‌های candidate و judge +برای تحلیل benchmark در گزارش ثبت می‌شوند، اما promptهای judge صراحتا می‌گویند +بر اساس سرعت رتبه‌بندی نکنند. +اجرای مدل‌های candidate و judge هر دو به‌صورت پیش‌فرض هم‌روندی 16 دارند. وقتی +محدودیت‌های provider یا فشار Gateway محلی باعث می‌شود یک اجرا بیش از حد noisy شود، +`--concurrency` یا `--judge-concurrency` را کاهش دهید. +وقتی هیچ candidateای با `--model` پاس داده نشود، character eval به‌صورت پیش‌فرض از `openai/gpt-5.5`، `openai/gpt-5.2`، `openai/gpt-5`، `anthropic/claude-opus-4-6`، `anthropic/claude-sonnet-4-6`، `zai/glm-5.1`، `moonshot/kimi-k2.5`، و `google/gemini-3.1-pro-preview` استفاده می‌کند. -وقتی هیچ `--judge-model`ی pass نشود، داورها به‌طور پیش‌فرض +وقتی هیچ `--judge-model` پاس داده نشود، داورها به‌صورت پیش‌فرض `openai/gpt-5.5,thinking=xhigh,fast` و `anthropic/claude-opus-4-6,thinking=high` هستند. ## مستندات مرتبط -- [Matrix QA](/fa/concepts/qa-matrix) +- [QA ماتریسی](/fa/concepts/qa-matrix) - [کانال QA](/fa/channels/qa-channel) - [آزمایش](/fa/help/testing) - [داشبورد](/fa/web/dashboard) diff --git a/docs/fa/concepts/streaming.md b/docs/fa/concepts/streaming.md index cd67147b9..aeacb4667 100644 --- a/docs/fa/concepts/streaming.md +++ b/docs/fa/concepts/streaming.md @@ -1,29 +1,29 @@ --- read_when: - - توضیح نحوهٔ کار جریان‌سازی یا قطعه‌بندی در کانال‌ها - - تغییر رفتار جریان‌دهی بلوک یا تکه‌بندی کانال + - توضیح نحوهٔ کار پخش جریانی یا قطعه‌بندی در کانال‌ها + - تغییر رفتار پخش جریانی بلوک یا قطعه‌بندی کانال - اشکال‌زدایی پاسخ‌های بلوکی تکراری/زودهنگام یا پخش جریانی پیش‌نمایش کانال summary: رفتار پخش جریانی + قطعه‌بندی (پاسخ‌های بلوکی، پخش جریانی پیش‌نمایش کانال، نگاشت حالت) -title: جریان‌سازی و قطعه‌بندی +title: جریان‌دهی و قطعه‌بندی x-i18n: - generated_at: "2026-05-03T21:32:06Z" + generated_at: "2026-05-04T07:05:50Z" model: gpt-5.5 provider: openai - source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50 + source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1 source_path: concepts/streaming.md workflow: 16 --- -OpenClaw دو لایهٔ streaming جداگانه دارد: +OpenClaw دو لایه جریان‌دهی جداگانه دارد: -- **streaming بلوکی (کانال‌ها):** هنگام نوشتن دستیار، **بلوک‌های** کامل‌شده را منتشر می‌کند. این‌ها پیام‌های معمولی کانال هستند (نه token delta). -- **streaming پیش‌نمایش (Telegram/Discord/Slack):** هنگام تولید، یک **پیام پیش‌نمایش** موقت را به‌روزرسانی می‌کند. +- **جریان‌دهی بلوکی (کانال‌ها):** هنگام نوشتن دستیار، **بلوک‌های** کامل‌شده را منتشر می‌کند. این‌ها پیام‌های عادی کانال هستند (نه دلتاهای توکن). +- **جریان‌دهی پیش‌نمایش (Telegram/Discord/Slack):** هنگام تولید، یک **پیام پیش‌نمایش** موقت را به‌روزرسانی می‌کند. -امروز **streaming واقعی از نوع token-delta** برای پیام‌های کانال وجود ندارد. streaming پیش‌نمایش مبتنی بر پیام است (ارسال + ویرایش‌ها/افزودن‌ها). +امروز **جریان‌دهی واقعی دلتا-توکن** به پیام‌های کانال وجود ندارد. جریان‌دهی پیش‌نمایش مبتنی بر پیام است (ارسال + ویرایش/افزودن). -## streaming بلوکی (پیام‌های کانال) +## جریان‌دهی بلوکی (پیام‌های کانال) -streaming بلوکی خروجی دستیار را وقتی در دسترس می‌شود، در قطعه‌های درشت ارسال می‌کند. +جریان‌دهی بلوکی خروجی دستیار را به‌صورت قطعه‌های درشت، هم‌زمان با آماده‌شدن، ارسال می‌کند. ``` Model output @@ -37,180 +37,180 @@ Model output راهنما: -- `text_delta/events`: رویدادهای جریان مدل (ممکن است برای مدل‌های غیرstreaming پراکنده باشند). +- `text_delta/events`: رویدادهای جریان مدل (ممکن است برای مدل‌های غیرجریانی پراکنده باشد). - `chunker`: `EmbeddedBlockChunker` که کران‌های کمینه/بیشینه + ترجیح شکست را اعمال می‌کند. - `channel send`: پیام‌های خروجی واقعی (پاسخ‌های بلوکی). **کنترل‌ها:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (پیش‌فرض خاموش). -- بازنویسی‌های کانال: `*.blockStreaming` (و گونه‌های هر حساب) برای اجبار `"on"`/`"off"` برای هر کانال. +- بازنویسی‌های کانال: `*.blockStreaming` (و گونه‌های هر حساب) برای اجبار `"on"`/`"off"` در هر کانال. - `agents.defaults.blockStreamingBreak`: `"text_end"` یا `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (ادغام بلوک‌های streaming پیش از ارسال). -- سقف سخت کانال: `*.textChunkLimit` (برای نمونه، `channels.whatsapp.textChunkLimit`). -- حالت قطعه‌بندی کانال: `*.chunkMode` (`length` پیش‌فرض است، `newline` پیش از قطعه‌بندی بر اساس طول، روی خط‌های خالی (مرزهای پاراگراف) تقسیم می‌کند). -- سقف نرم Discord: `channels.discord.maxLinesPerMessage` (پیش‌فرض 17) پاسخ‌های بلند را تقسیم می‌کند تا از بریده‌شدن رابط کاربری جلوگیری شود. +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (ادغام بلوک‌های جریانی پیش از ارسال). +- سقف سخت کانال: `*.textChunkLimit` (مثلاً `channels.whatsapp.textChunkLimit`). +- حالت قطعه‌بندی کانال: `*.chunkMode` (`length` پیش‌فرض است، `newline` پیش از قطعه‌بندی بر اساس طول، روی خطوط خالی (مرزهای پاراگراف) تقسیم می‌کند). +- سقف نرم Discord: `channels.discord.maxLinesPerMessage` (پیش‌فرض 17) پاسخ‌های بلند را تقسیم می‌کند تا از بریده‌شدن UI جلوگیری شود. **معنای مرزها:** -- `text_end`: به محض اینکه قطعه‌ساز بلوک منتشر کند، بلوک‌ها را streaming کن؛ در هر `text_end` تخلیه کن. -- `message_end`: تا پایان پیام دستیار صبر کن، سپس خروجی بافرشده را تخلیه کن. +- `text_end`: به‌محض انتشار از سوی chunker، بلوک‌ها را جریان می‌دهد؛ در هر `text_end` تخلیه می‌کند. +- `message_end`: تا پایان پیام دستیار صبر می‌کند، سپس خروجی بافرشده را تخلیه می‌کند. -اگر متن بافرشده از `maxChars` بیشتر شود، `message_end` همچنان از قطعه‌ساز استفاده می‌کند، بنابراین می‌تواند در پایان چند قطعه منتشر کند. +`message_end` همچنان اگر متن بافرشده از `maxChars` فراتر برود از chunker استفاده می‌کند، بنابراین می‌تواند در پایان چند قطعه منتشر کند. -### تحویل رسانه با streaming بلوکی +### تحویل رسانه با جریان‌دهی بلوکی -دستورهای `MEDIA:` فرادادهٔ معمول تحویل هستند. وقتی streaming بلوکی یک -بلوک رسانه را زود ارسال کند، OpenClaw آن تحویل را برای آن نوبت به خاطر می‌سپارد. اگر payload نهایی -دستیار همان URL رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوبارهٔ پیوست، -رسانهٔ تکراری را حذف می‌کند. +دستورهای `MEDIA:` فراداده تحویل عادی هستند. وقتی جریان‌دهی بلوکی یک +بلوک رسانه را زود ارسال می‌کند، OpenClaw آن تحویل را برای آن نوبت به خاطر می‌سپارد. اگر محتوای نهایی +دستیار همان URL رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوباره پیوست، +رسانه تکراری را حذف می‌کند. -payloadهای نهایی کاملاً تکراری سرکوب می‌شوند. اگر payload نهایی -متن متمایزی پیرامون رسانه‌ای اضافه کند که قبلاً streaming شده است، OpenClaw همچنان -متن جدید را می‌فرستد و رسانه را تک‌تحویلی نگه می‌دارد. این کار از یادداشت‌های صوتی -یا فایل‌های تکراری در کانال‌هایی مثل Telegram جلوگیری می‌کند، وقتی یک عامل هنگام -streaming مقدار `MEDIA:` منتشر می‌کند و provider نیز آن را در پاسخ کامل‌شده وارد می‌کند. +محتواهای نهایی کاملاً تکراری سرکوب می‌شوند. اگر محتوای نهایی متن +متمایزی پیرامون رسانه‌ای که قبلاً جریان داده شده اضافه کند، OpenClaw همچنان +متن جدید را می‌فرستد و رسانه را تک‌تحویلی نگه می‌دارد. این کار از تکرار یادداشت‌های صوتی +یا فایل‌ها در کانال‌هایی مثل Telegram جلوگیری می‌کند، زمانی که یک عامل هنگام +جریان‌دهی `MEDIA:` منتشر می‌کند و ارائه‌دهنده نیز آن را در پاسخ کامل‌شده می‌آورد. -## الگوریتم قطعه‌بندی (کران‌های کم/زیاد) +## الگوریتم قطعه‌بندی (کران‌های پایین/بالا) -قطعه‌بندی بلوک توسط `EmbeddedBlockChunker` پیاده‌سازی شده است: +قطعه‌بندی بلوکی توسط `EmbeddedBlockChunker` پیاده‌سازی شده است: -- **کران کم:** تا زمانی که بافر >= `minChars` نشده است منتشر نکن (مگر اینکه اجباری باشد). -- **کران زیاد:** تقسیم‌ها را پیش از `maxChars` ترجیح بده؛ اگر اجباری شد، در `maxChars` تقسیم کن. +- **کران پایین:** تا زمانی که بافر >= `minChars` نباشد منتشر نکن (مگر با اجبار). +- **کران بالا:** تقسیم پیش از `maxChars` ترجیح داده می‌شود؛ اگر اجباری باشد، در `maxChars` تقسیم کن. - **ترجیح شکست:** `paragraph` → `newline` → `sentence` → `whitespace` → شکست سخت. -- **حصارهای کد:** هرگز داخل حصارها تقسیم نکن؛ وقتی در `maxChars` اجباراً تقسیم می‌شود، حصار را ببند + دوباره باز کن تا Markdown معتبر بماند. +- **حصارهای کد:** هرگز داخل حصارها تقسیم نکن؛ هنگام اجبار در `maxChars`، حصار را ببند + دوباره باز کن تا Markdown معتبر بماند. `maxChars` به `textChunkLimit` کانال محدود می‌شود، بنابراین نمی‌توانید از سقف‌های هر کانال فراتر بروید. -## هم‌جوشی (ادغام بلوک‌های streaming) +## هم‌جوشی (ادغام بلوک‌های جریانی) -وقتی streaming بلوکی فعال باشد، OpenClaw می‌تواند **قطعه‌های بلوکی متوالی را** -پیش از ارسال ادغام کند. این کار «هرزپیام تک‌خطی» را کم می‌کند و همچنان -خروجی تدریجی ارائه می‌دهد. +وقتی جریان‌دهی بلوکی فعال است، OpenClaw می‌تواند **قطعه‌های بلوکی پیاپی را** +پیش از ارسال به بیرون **ادغام کند**. این کار «هرزپیام تک‌خطی» را کاهش می‌دهد و همچنان +خروجی تدریجی ارائه می‌کند. -- هم‌جوشی پیش از تخلیه منتظر **فاصله‌های بیکاری** (`idleMs`) می‌ماند. +- هم‌جوشی پیش از تخلیه، منتظر **وقفه‌های بی‌کار** (`idleMs`) می‌ماند. - بافرها با `maxChars` محدود می‌شوند و اگر از آن فراتر بروند تخلیه خواهند شد. -- `minChars` جلوی ارسال پاره‌های خیلی کوچک را می‌گیرد تا متن کافی جمع شود - (تخلیهٔ نهایی همیشه متن باقی‌مانده را می‌فرستد). -- چسباننده از `blockStreamingChunk.breakPreference` مشتق می‌شود +- `minChars` از ارسال قطعه‌های بسیار کوچک جلوگیری می‌کند تا متن کافی جمع شود + (تخلیه نهایی همیشه متن باقی‌مانده را می‌فرستد). +- اتصال‌دهنده از `blockStreamingChunk.breakPreference` مشتق می‌شود (`paragraph` → `\n\n`، `newline` → `\n`، `sentence` → فاصله). - بازنویسی‌های کانال از طریق `*.blockStreamingCoalesce` در دسترس هستند (شامل پیکربندی‌های هر حساب). -- مقدار پیش‌فرض `minChars` برای هم‌جوشی، مگر اینکه بازنویسی شود، برای Signal/Slack/Discord به 1500 افزایش داده می‌شود. +- مقدار پیش‌فرض هم‌جوشی `minChars` برای Signal/Slack/Discord به 1500 افزایش داده می‌شود، مگر اینکه بازنویسی شده باشد. -## آهنگ انسانی بین بلوک‌ها +## مکث انسانی‌مانند بین بلوک‌ها -وقتی streaming بلوکی فعال باشد، می‌توانید بین +وقتی جریان‌دهی بلوکی فعال است، می‌توانید بین پاسخ‌های بلوکی (پس از بلوک اول) یک **مکث تصادفی‌شده** اضافه کنید. این باعث می‌شود پاسخ‌های چندحبابی طبیعی‌تر به نظر برسند. -- پیکربندی: `agents.defaults.humanDelay` (برای هر عامل از طریق `agents.list[].humanDelay` بازنویسی کنید). +- پیکربندی: `agents.defaults.humanDelay` (بازنویسی برای هر عامل از طریق `agents.list[].humanDelay`). - حالت‌ها: `off` (پیش‌فرض)، `natural` (800–2500ms)، `custom` (`minMs`/`maxMs`). - فقط روی **پاسخ‌های بلوکی** اعمال می‌شود، نه پاسخ‌های نهایی یا خلاصه‌های ابزار. -## «قطعه‌ها را streaming کن یا همه‌چیز را» +## «جریان‌دهی قطعه‌ها یا همه‌چیز» این به موارد زیر نگاشت می‌شود: -- **قطعه‌ها را streaming کن:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (هم‌زمان با تولید منتشر کن). کانال‌های غیرTelegram همچنین به `*.blockStreaming: true` نیاز دارند. -- **همه‌چیز را در پایان streaming کن:** `blockStreamingBreak: "message_end"` (یک‌بار تخلیه کن، اگر خیلی طولانی باشد احتمالاً چند قطعه). -- **بدون streaming بلوکی:** `blockStreamingDefault: "off"` (فقط پاسخ نهایی). +- **جریان‌دهی قطعه‌ها:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (هم‌زمان با پیشرفت منتشر کن). کانال‌های غیر Telegram همچنین به `*.blockStreaming: true` نیاز دارند. +- **جریان‌دهی همه‌چیز در پایان:** `blockStreamingBreak: "message_end"` (یک‌بار تخلیه، در صورت بسیار طولانی بودن شاید چند قطعه). +- **بدون جریان‌دهی بلوکی:** `blockStreamingDefault: "off"` (فقط پاسخ نهایی). -**نکتهٔ کانال:** streaming بلوکی **خاموش است مگر اینکه** -`*.blockStreaming` صراحتاً روی `true` تنظیم شده باشد. کانال‌ها می‌توانند بدون پاسخ‌های بلوکی، -یک پیش‌نمایش زنده را streaming کنند (`channels..streaming`). +**نکته کانال:** جریان‌دهی بلوکی **خاموش است مگر اینکه** +`*.blockStreaming` صریحاً روی `true` تنظیم شود. کانال‌ها می‌توانند بدون پاسخ‌های بلوکی، +یک پیش‌نمایش زنده (`channels..streaming`) را جریان دهند. یادآوری محل پیکربندی: پیش‌فرض‌های `blockStreaming*` زیر `agents.defaults` قرار دارند، نه پیکربندی ریشه. -## حالت‌های streaming پیش‌نمایش +## حالت‌های جریان‌دهی پیش‌نمایش -کلید معیار: `channels..streaming` +کلید canonical: `channels..streaming` حالت‌ها: -- `off`: streaming پیش‌نمایش را غیرفعال می‌کند. -- `partial`: یک پیش‌نمایش واحد که با تازه‌ترین متن جایگزین می‌شود. +- `off`: جریان‌دهی پیش‌نمایش را غیرفعال می‌کند. +- `partial`: یک پیش‌نمایش که با آخرین متن جایگزین می‌شود. - `block`: پیش‌نمایش در گام‌های قطعه‌بندی‌شده/افزوده‌شده به‌روزرسانی می‌شود. - `progress`: پیش‌نمایش پیشرفت/وضعیت هنگام تولید، پاسخ نهایی در پایان. -`streaming.mode: "block"` یک حالت streaming پیش‌نمایش برای کانال‌های قابل‌ویرایش -مانند Discord و Telegram است. این حالت تحویل بلوکی کانال را در آنجا فعال نمی‌کند. -وقتی پاسخ‌های بلوکی معمولی می‌خواهید، از `streaming.block.enabled` یا کلید قدیمی کانال `blockStreaming` استفاده کنید. Microsoft Teams استثناست: این کانال -انتقال بلوکی پیش‌نویس-پیش‌نمایش ندارد، بنابراین `streaming.mode: "block"` به‌جای -streaming جزئی/پیشرفت بومی، به تحویل بلوکی Teams نگاشت می‌شود. +`streaming.mode: "block"` یک حالت جریان‌دهی پیش‌نمایش برای کانال‌های قابل ویرایش +مانند Discord و Telegram است. این کار تحویل بلوکی کانال را در آنجا فعال نمی‌کند. +وقتی پاسخ‌های بلوکی عادی می‌خواهید، از `streaming.block.enabled` یا کلید قدیمی کانال `blockStreaming` استفاده کنید. +Microsoft Teams استثناست: انتقال بلوکی پیش‌نمایش پیش‌نویس ندارد، بنابراین `streaming.mode: "block"` به‌جای +جریان‌دهی جزئی/پیشرفت بومی، به تحویل بلوکی Teams نگاشت می‌شود. ### نگاشت کانال -| کانال | `off` | `partial` | `block` | `progress` | +| کانال | `off` | `partial` | `block` | `progress` | | ---------- | ----- | --------- | ------- | ----------------------- | -| Telegram | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل‌ویرایش | -| Discord | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل‌ویرایش | +| Telegram | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل ویرایش | +| Discord | ✅ | ✅ | ✅ | پیش‌نویس پیشرفت قابل ویرایش | | Slack | ✅ | ✅ | ✅ | ✅ | | Mattermost | ✅ | ✅ | ✅ | ✅ | -| MS Teams | ✅ | ✅ | ✅ | جریان پیشرفت بومی | +| MS Teams | ✅ | ✅ | ✅ | جریان پیشرفت بومی | فقط Slack: -- `channels.slack.streaming.nativeTransport` فراخوانی‌های API streaming بومی Slack را وقتی `channels.slack.streaming.mode="partial"` باشد روشن/خاموش می‌کند (پیش‌فرض: `true`). -- streaming بومی Slack و وضعیت رشتهٔ دستیار Slack به یک هدف رشتهٔ پاسخ نیاز دارند. پیام‌های مستقیم سطح‌بالا آن پیش‌نمایش به سبک رشته را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌های پیش‌نمایش پیش‌نویس Slack و ویرایش‌ها استفاده کنند. +- `channels.slack.streaming.nativeTransport` فراخوانی‌های API جریان‌دهی بومی Slack را زمانی که `channels.slack.streaming.mode="partial"` باشد تغییر وضعیت می‌دهد (پیش‌فرض: `true`). +- جریان‌دهی بومی Slack و وضعیت رشته دستیار Slack به یک هدف رشته پاسخ نیاز دارند. پیام‌های مستقیم سطح بالا آن پیش‌نمایش سبک‌رشته‌ای را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌ها و ویرایش‌های پیش‌نمایش پیش‌نویس Slack استفاده کنند. مهاجرت کلید قدیمی: -- Telegram: مقدارهای قدیمی `streamMode` و مقدارهای اسکالر/بولی `streaming` توسط مسیرهای سازگاری doctor/config شناسایی و به `streaming.mode` مهاجرت داده می‌شوند. -- Discord: `streamMode` + مقدار بولی `streaming` به‌صورت خودکار به enum ‏`streaming` مهاجرت می‌کنند. +- Telegram: مقادیر قدیمی `streamMode` و مقادیر عددی/بولی `streaming` توسط مسیرهای سازگاری doctor/config به `streaming.mode` شناسایی و مهاجرت می‌شوند. +- Discord: `streamMode` + مقدار بولی `streaming` به‌صورت خودکار به enum `streaming` مهاجرت می‌کنند. - Slack: `streamMode` به‌صورت خودکار به `streaming.mode` مهاجرت می‌کند؛ مقدار بولی `streaming` به‌صورت خودکار به `streaming.mode` به‌همراه `streaming.nativeTransport` مهاجرت می‌کند؛ `nativeStreaming` قدیمی به‌صورت خودکار به `streaming.nativeTransport` مهاجرت می‌کند. ### رفتار زمان اجرا Telegram: -- از `sendMessage` + به‌روزرسانی‌های پیش‌نمایش `editMessageText` در پیام‌های مستقیم و گروه‌ها/موضوع‌ها استفاده می‌کند. -- وقتی یک پیش‌نمایش حدود یک دقیقه قابل‌مشاهده بوده است، به‌جای ویرایش درجا یک پیام نهایی تازه می‌فرستد، سپس پیش‌نمایش را پاک می‌کند تا timestamp در Telegram پایان پاسخ را بازتاب دهد. -- وقتی streaming بلوکی Telegram صراحتاً فعال باشد، streaming پیش‌نمایش رد می‌شود (برای جلوگیری از streaming دوگانه). -- `/reasoning stream` می‌تواند reasoning را در پیش‌نمایش بنویسد. +- از به‌روزرسانی‌های پیش‌نمایش `sendMessage` + `editMessageText` در پیام‌های مستقیم و گروه‌ها/موضوعات استفاده می‌کند. +- وقتی یک پیش‌نمایش حدود یک دقیقه قابل مشاهده بوده باشد، به‌جای ویرایش درجا یک پیام نهایی تازه می‌فرستد، سپس پیش‌نمایش را پاک می‌کند تا مُهر زمانی Telegram تکمیل پاسخ را بازتاب دهد. +- وقتی جریان‌دهی بلوکی Telegram صریحاً فعال باشد، جریان‌دهی پیش‌نمایش نادیده گرفته می‌شود (برای جلوگیری از جریان‌دهی دوگانه). +- `/reasoning stream` می‌تواند استدلال را در یک پیش‌نمایش گذرا بنویسد که پس از تحویل نهایی حذف می‌شود. Discord: -- از پیام‌های پیش‌نمایش ارسال + ویرایش استفاده می‌کند. +- از ارسال + ویرایش پیام‌های پیش‌نمایش استفاده می‌کند. - حالت `block` از قطعه‌بندی پیش‌نویس (`draftChunk`) استفاده می‌کند. -- وقتی streaming بلوکی Discord صراحتاً فعال باشد، streaming پیش‌نمایش رد می‌شود. -- payloadهای رسانهٔ نهایی، خطا و پاسخ صریح، پیش‌نمایش‌های معلق را بدون تخلیهٔ پیش‌نویس تازه لغو می‌کنند، سپس از تحویل معمول استفاده می‌کنند. +- وقتی جریان‌دهی بلوکی Discord صریحاً فعال باشد، جریان‌دهی پیش‌نمایش نادیده گرفته می‌شود. +- رسانه نهایی، خطا، و محتواهای پاسخ صریح، پیش‌نمایش‌های معلق را بدون تخلیه پیش‌نویس جدید لغو می‌کنند، سپس از تحویل عادی استفاده می‌کنند. Slack: -- `partial` در صورت در دسترس بودن می‌تواند از streaming بومی Slack (`chat.startStream`/`append`/`stop`) استفاده کند. +- `partial` در صورت در دسترس بودن می‌تواند از جریان‌دهی بومی Slack (`chat.startStream`/`append`/`stop`) استفاده کند. - `block` از پیش‌نمایش‌های پیش‌نویس به سبک افزودن استفاده می‌کند. - `progress` از متن پیش‌نمایش وضعیت و سپس پاسخ نهایی استفاده می‌کند. -- پیام‌های مستقیم سطح‌بالا بدون رشتهٔ پاسخ، به‌جای streaming بومی Slack از پست‌های پیش‌نمایش پیش‌نویس و ویرایش‌ها استفاده می‌کنند. -- streaming پیش‌نمایش بومی و پیش‌نویس، پاسخ‌های بلوکی را برای آن نوبت سرکوب می‌کنند، بنابراین یک پاسخ Slack فقط از یک مسیر تحویل streaming می‌شود. -- payloadهای رسانه/خطای نهایی و نهایی‌های پیشرفت، پیام‌های پیش‌نویس دورریختنی ایجاد نمی‌کنند؛ فقط نهایی‌های متنی/بلوکی که می‌توانند پیش‌نمایش را ویرایش کنند، متن پیش‌نویس معلق را تخلیه می‌کنند. +- پیام‌های مستقیم سطح بالا بدون رشته پاسخ، به‌جای جریان‌دهی بومی Slack، از پست‌ها و ویرایش‌های پیش‌نمایش پیش‌نویس استفاده می‌کنند. +- جریان‌دهی بومی و پیش‌نمایش پیش‌نویس، پاسخ‌های بلوکی را برای آن نوبت سرکوب می‌کنند، بنابراین یک پاسخ Slack فقط از یک مسیر تحویل جریان داده می‌شود. +- محتواهای رسانه/خطای نهایی و نهایی‌های پیشرفت، پیام‌های پیش‌نویس دورریختنی ایجاد نمی‌کنند؛ فقط نهایی‌های متنی/بلوکی که می‌توانند پیش‌نمایش را ویرایش کنند، متن پیش‌نویس معلق را تخلیه می‌کنند. Mattermost: -- فکر کردن، فعالیت ابزار و متن جزئی پاسخ را در یک پست پیش‌نمایش پیش‌نویس واحد streaming می‌کند که وقتی پاسخ نهایی برای ارسال امن باشد، درجا نهایی می‌شود. -- اگر پست پیش‌نمایش حذف شده باشد یا هنگام نهایی‌سازی به هر دلیل در دسترس نباشد، به ارسال یک پست نهایی تازه برمی‌گردد. -- payloadهای رسانه/خطای نهایی پیش از تحویل معمول، به‌جای تخلیهٔ یک پست پیش‌نمایش موقت، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند. +- فکرکردن، فعالیت ابزار، و متن پاسخ جزئی را در یک پست پیش‌نمایش پیش‌نویس واحد جریان می‌دهد که وقتی پاسخ نهایی برای ارسال امن باشد، درجا نهایی می‌شود. +- اگر پست پیش‌نمایش حذف شده باشد یا در زمان نهایی‌سازی در دسترس نباشد، به ارسال یک پست نهایی تازه برمی‌گردد. +- محتواهای رسانه/خطای نهایی، پیش از تحویل عادی، به‌جای تخلیه یک پست پیش‌نمایش موقت، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند. Matrix: -- پیش‌نمایش‌های پیش‌نویس وقتی متن نهایی بتواند رویداد پیش‌نمایش را دوباره استفاده کند، درجا نهایی می‌شوند. -- نهایی‌های فقط‌رسانه، خطا و ناهماهنگی هدف پاسخ، پیش از تحویل معمول، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند؛ یک پیش‌نمایش کهنه‌ای که از قبل قابل‌مشاهده است حذف می‌شود. +- پیش‌نمایش‌های پیش‌نویس وقتی متن نهایی بتواند از رویداد پیش‌نمایش دوباره استفاده کند، درجا نهایی می‌شوند. +- نهایی‌های فقط رسانه، خطا، و ناسازگاری هدف پاسخ، پیش از تحویل عادی، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند؛ یک پیش‌نمایش کهنه که از قبل قابل مشاهده است حذف‌انتشاری می‌شود. ### به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار -streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی‌های **پیشرفت ابزار** نیز باشد — خط‌های کوتاه وضعیت مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل» یا «در حال فراخوانی ابزار» — که هنگام اجرای ابزارها و پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. این کار نوبت‌های چندمرحله‌ای ابزار را به‌جای سکوت بین نخستین پیش‌نمایش فکر کردن و پاسخ نهایی، از نظر بصری زنده نگه می‌دارد. +جریان‌دهی پیش‌نمایش همچنین می‌تواند شامل به‌روزرسانی‌های **پیشرفت ابزار** باشد - خط‌های وضعیت کوتاه مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل»، یا «در حال فراخوانی ابزار» - که هنگام اجرای ابزارها، پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. این کار نوبت‌های چندمرحله‌ای ابزار را به‌جای سکوت بین اولین پیش‌نمایش تفکر و پاسخ نهایی، از نظر بصری زنده نگه می‌دارد. -سطح‌های پشتیبانی‌شده: +سطوح پشتیبانی‌شده: -- **Discord**، **Slack**، **Telegram** و **Matrix** وقتی streaming پیش‌نمایش فعال باشد، به‌طور پیش‌فرض پیشرفت ابزار را در ویرایش پیش‌نمایش زنده streaming می‌کنند. Microsoft Teams در گفت‌وگوهای شخصی از جریان پیشرفت بومی خود استفاده می‌کند. -- Telegram از `v2026.4.22` با به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار فعال منتشر شده است؛ فعال نگه داشتن آن‌ها همان رفتار منتشرشده را حفظ می‌کند. +- **Discord**، **Slack**، **Telegram**، و **Matrix** به‌طور پیش‌فرض وقتی جریان‌دهی پیش‌نمایش فعال باشد، پیشرفت ابزار را در ویرایش پیش‌نمایش زنده جریان می‌دهند. Microsoft Teams در گفت‌وگوهای شخصی از جریان پیشرفت بومی خود استفاده می‌کند. +- Telegram از `v2026.4.22` با به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار فعال منتشر شده است؛ فعال نگه‌داشتن آن‌ها رفتار منتشرشده را حفظ می‌کند. - **Mattermost** از قبل فعالیت ابزار را در پست پیش‌نمایش پیش‌نویس واحد خود ادغام می‌کند (بالا را ببینید). -- ویرایش‌های پیشرفت ابزار از حالت فعال streaming پیش‌نمایش پیروی می‌کنند؛ وقتی streaming پیش‌نمایش `off` باشد یا وقتی streaming بلوکی پیام را بر عهده گرفته باشد، رد می‌شوند. در Telegram، `streaming.mode: "off"` فقط نهایی است: گفت‌وگوی عمومی پیشرفت نیز به‌جای تحویل به‌صورت پیام‌های وضعیت مستقل سرکوب می‌شود، درحالی‌که درخواست‌های تأیید، payloadهای رسانه و خطاها همچنان به‌طور معمول مسیریابی می‌شوند. -- برای نگه داشتن streaming پیش‌نمایش اما پنهان کردن خط‌های پیشرفت ابزار، `streaming.preview.toolProgress` را برای آن کانال روی `false` تنظیم کنید. برای غیرفعال کردن کامل ویرایش‌های پیش‌نمایش، `streaming.mode` را روی `off` تنظیم کنید. -- پاسخ‌های نقل‌قول انتخاب‌شدهٔ Telegram یک استثنا هستند: وقتی `replyToMode` مقدار `"off"` نباشد و متن نقل‌قول انتخاب‌شده وجود داشته باشد، OpenClaw جریان پیش‌نمایش پاسخ را برای آن نوبت رد می‌کند، بنابراین خط‌های پیش‌نمایش پیشرفت ابزار نمی‌توانند رندر شوند. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان streaming پیش‌نمایش را نگه می‌دارند. برای جزئیات، [مستندات کانال Telegram](/fa/channels/telegram) را ببینید. +- ویرایش‌های پیشرفت ابزار از حالت جریان‌دهی پیش‌نمایش فعال پیروی می‌کنند؛ وقتی جریان‌دهی پیش‌نمایش `off` باشد یا جریان‌دهی بلوکی کنترل پیام را به دست گرفته باشد، نادیده گرفته می‌شوند. در Telegram، `streaming.mode: "off"` فقط-نهایی است: گفت‌وگوی پیشرفت عمومی نیز به‌جای تحویل به‌عنوان پیام‌های وضعیت مستقل، سرکوب می‌شود، در حالی که درخواست‌های تأیید، محتواهای رسانه، و خطاها همچنان به‌طور عادی مسیریابی می‌شوند. +- برای نگه‌داشتن جریان‌دهی پیش‌نمایش اما پنهان‌کردن خط‌های پیشرفت ابزار، `streaming.preview.toolProgress` را برای آن کانال روی `false` تنظیم کنید. برای قابل مشاهده نگه‌داشتن خط‌های پیشرفت ابزار و در عین حال پنهان‌کردن متن command/exec، `streaming.preview.commandText` را روی `"status"` یا `streaming.progress.commandText` را روی `"status"` تنظیم کنید؛ مقدار پیش‌فرض `"raw"` است تا رفتار منتشرشده حفظ شود. این سیاست میان کانال‌های پیش‌نویس/پیشرفت که از رندرکننده پیشرفت فشرده OpenClaw استفاده می‌کنند مشترک است، از جمله Discord، Matrix، Microsoft Teams، Mattermost، پیش‌نمایش‌های پیش‌نویس Slack، و Telegram. برای غیرفعال‌کردن کامل ویرایش‌های پیش‌نمایش، `streaming.mode` را روی `off` تنظیم کنید. +- پاسخ‌های نقل‌قول انتخاب‌شده Telegram یک استثنا هستند: وقتی `replyToMode` برابر `"off"` نیست و متن نقل‌قول انتخاب‌شده وجود دارد، OpenClaw جریان پیش‌نمایش پاسخ را برای آن نوبت نادیده می‌گیرد، بنابراین خط‌های پیش‌نمایش پیشرفت ابزار نمی‌توانند رندر شوند. پاسخ‌های پیام فعلی بدون متن نقل‌قول انتخاب‌شده همچنان جریان‌دهی پیش‌نمایش را نگه می‌دارند. برای جزئیات، [مستندات کانال Telegram](/fa/channels/telegram) را ببینید. -نمونه: +خطوط پیشرفت را قابل مشاهده نگه دارید، اما متن خام فرمان/اجرا را پنهان کنید: ```json { @@ -219,7 +219,26 @@ streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی "streaming": { "mode": "partial", "preview": { - "toolProgress": false + "toolProgress": true, + "commandText": "status" + } + } + } + } +} +``` + +همین ساختار را زیر یک کلید فشردهٔ دیگر برای کانال پیشرفت استفاده کنید، برای مثال `channels.discord`، `channels.matrix`، `channels.msteams`، `channels.mattermost`، یا پیش‌نمایش‌های پیش‌نویس Slack. برای حالت پیش‌نویس پیشرفت، همین سیاست را زیر `streaming.progress` قرار دهید: + +```json +{ + "channels": { + "telegram": { + "streaming": { + "mode": "progress", + "progress": { + "toolProgress": true, + "commandText": "status" } } } @@ -229,7 +248,7 @@ streaming پیش‌نمایش می‌تواند شامل به‌روزرسانی ## مرتبط -- [پیش‌نویس‌های پیشرفت](/fa/concepts/progress-drafts) — پیام‌های قابل‌مشاهدهٔ کار در جریان که هنگام نوبت‌های طولانی به‌روزرسانی می‌شوند -- [پیام‌ها](/fa/concepts/messages) — چرخهٔ عمر و تحویل پیام -- [تلاش دوباره](/fa/concepts/retry) — رفتار تلاش دوباره هنگام شکست تحویل -- [کانال‌ها](/fa/channels) — پشتیبانی streaming برای هر کانال +- [پیش‌نویس‌های پیشرفت](/fa/concepts/progress-drafts) — پیام‌های قابل مشاهدهٔ کار در جریان که در طول نوبت‌های طولانی به‌روزرسانی می‌شوند +- [پیام‌ها](/fa/concepts/messages) — چرخهٔ عمر پیام و تحویل +- [تلاش مجدد](/fa/concepts/retry) — رفتار تلاش مجدد هنگام شکست تحویل +- [کانال‌ها](/fa/channels) — پشتیبانی پخش جریانی به‌ازای هر کانال diff --git a/docs/fa/help/testing.md b/docs/fa/help/testing.md index 0a53d3726..5049c16b9 100644 --- a/docs/fa/help/testing.md +++ b/docs/fa/help/testing.md @@ -1,174 +1,220 @@ --- read_when: - - اجرای تست‌ها به‌صورت محلی یا در CI + - اجرای آزمون‌ها به‌صورت محلی یا در CI - افزودن آزمون‌های رگرسیون برای باگ‌های مدل/ارائه‌دهنده - اشکال‌زدایی رفتار Gateway + عامل -summary: 'کیت آزمون: مجموعه‌های unit/e2e/live، اجراکننده‌های Docker، و آنچه هر آزمون پوشش می‌دهد' +summary: 'کیت تست: مجموعه‌های unit/e2e/live، اجراکننده‌های Docker، و اینکه هر تست چه مواردی را پوشش می‌دهد' title: آزمایش x-i18n: - generated_at: "2026-05-03T11:38:26Z" + generated_at: "2026-05-04T07:05:47Z" model: gpt-5.5 provider: openai - source_hash: e7fb57bee958c4e6243f02193a657d7b19ca633c7a27f70eac6b590931390671 + source_hash: ad724e3879d1d4dec21c4ea97e2fd5724c47269c1084c558a09f51bd72afc6a4 source_path: help/testing.md workflow: 16 --- -OpenClaw سه مجموعه Vitest دارد (واحد/یکپارچه‌سازی، سرتاسری، زنده) و یک مجموعه کوچک -از اجراکننده‌های Docker. این سند راهنمای «چگونه آزمون می‌کنیم» است: +OpenClaw سه مجموعه Vitest دارد (واحد/یکپارچه‌سازی، e2e، زنده) و مجموعه کوچکی +از اجراکننده‌های Docker. این سند راهنمای «ما چگونه آزمون می‌کنیم» است: -- هر مجموعه چه چیزهایی را پوشش می‌دهد (و عمدا چه چیزهایی را پوشش _نمی‌دهد_). -- برای گردش‌کارهای رایج (محلی، پیش از push، اشکال‌زدایی) کدام فرمان‌ها را اجرا کنید. -- آزمون‌های زنده چگونه اعتبارنامه‌ها را کشف می‌کنند و مدل‌ها/ارائه‌دهنده‌ها را انتخاب می‌کنند. +- هر مجموعه چه چیزهایی را پوشش می‌دهد (و عمداً چه چیزهایی را پوشش _نمی‌دهد_). +- برای جریان‌های کاری رایج (محلی، پیش از push، اشکال‌زدایی) کدام فرمان‌ها را اجرا کنید. +- آزمون‌های زنده چگونه اعتبارنامه‌ها را کشف می‌کنند و مدل‌ها/ارائه‌دهندگان را انتخاب می‌کنند. - چگونه برای مشکلات واقعی مدل/ارائه‌دهنده، رگرسیون اضافه کنید. -**پشته QA (qa-lab، qa-channel، مسیرهای انتقال زنده)** جداگانه مستند شده است: +**پشته QA (qa-lab، qa-channel، مسیرهای انتقال زنده)** به‌صورت جداگانه مستند شده است: -- [نمای کلی QA](/fa/concepts/qa-e2e-automation) — معماری، سطح فرمان، نگارش سناریو. -- [QA ماتریسی](/fa/concepts/qa-matrix) — مرجع برای `pnpm openclaw qa matrix`. -- [کانال QA](/fa/channels/qa-channel) — Plugin انتقال مصنوعی که سناریوهای پشتیبانی‌شده با repo از آن استفاده می‌کنند. +- [نمای کلی QA](/fa/concepts/qa-e2e-automation) — معماری، سطح فرمان، نوشتن سناریو. +- [Matrix QA](/fa/concepts/qa-matrix) — مرجع `pnpm openclaw qa matrix`. +- [کانال QA](/fa/channels/qa-channel) — Plugin انتقال مصنوعی که سناریوهای پشتیبانی‌شده با مخزن از آن استفاده می‌کنند. -این صفحه اجرای مجموعه‌های آزمون معمولی و اجراکننده‌های Docker/Parallels را پوشش می‌دهد. بخش اجراکننده‌های مخصوص QA در پایین ([اجراکننده‌های مخصوص QA](#qa-specific-runners)) فراخوانی‌های مشخص `qa` را فهرست می‌کند و دوباره به مراجع بالا اشاره می‌کند. +این صفحه اجرای مجموعه‌های آزمون عادی و اجراکننده‌های Docker/Parallels را پوشش می‌دهد. بخش اجراکننده‌های ویژه QA در ادامه ([اجراکننده‌های ویژه QA](#qa-specific-runners)) فراخوانی‌های مشخص `qa` را فهرست می‌کند و دوباره به مراجع بالا ارجاع می‌دهد. ## شروع سریع در بیشتر روزها: -- گیت کامل (انتظار می‌رود پیش از push اجرا شود): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- اجرای سریع‌تر کل مجموعه آزمون محلی روی دستگاهی با منابع کافی: `pnpm test:max` +- دروازه کامل (پیش از push انتظار می‌رود): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- اجرای سریع‌تر مجموعه کامل محلی روی دستگاهی با منابع کافی: `pnpm test:max` - حلقه watch مستقیم Vitest: `pnpm test:watch` -- هدف‌گیری مستقیم فایل اکنون مسیرهای extension/channel را هم مسیریابی می‌کند: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- وقتی روی یک شکست واحد در حال تکرار هستید، ابتدا اجراهای هدفمند را ترجیح دهید. +- هدف‌گیری مستقیم فایل اکنون مسیرهای افزونه/کانال را هم مسیریابی می‌کند: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- وقتی روی یک شکست واحد تکرار می‌کنید، ابتدا اجراهای هدفمند را ترجیح دهید. - سایت QA پشتیبانی‌شده با Docker: `pnpm qa:lab:up` - مسیر QA پشتیبانی‌شده با ماشین مجازی Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -وقتی آزمون‌ها را لمس می‌کنید یا اطمینان بیشتری می‌خواهید: +وقتی آزمون‌ها را تغییر می‌دهید یا اطمینان بیشتری می‌خواهید: -- گیت پوشش: `pnpm test:coverage` -- مجموعه سرتاسری: `pnpm test:e2e` +- دروازه پوشش: `pnpm test:coverage` +- مجموعه E2E: `pnpm test:e2e` -هنگام اشکال‌زدایی ارائه‌دهنده‌ها/مدل‌های واقعی (به اعتبارنامه‌های واقعی نیاز دارد): +هنگام اشکال‌زدایی ارائه‌دهندگان/مدل‌های واقعی (به اعتبارنامه واقعی نیاز دارد): -- مجموعه زنده (مدل‌ها + کاوش‌های ابزار/تصویر Gateway): `pnpm test:live` -- هدف‌گیری بی‌سروصدای یک فایل زنده: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- گزارش‌های کارایی زمان اجرا: `OpenClaw Performance` را با +- مجموعه زنده (مدل‌ها + بررسی‌های ابزار/تصویر Gateway): `pnpm test:live` +- هدف‌گیری بی‌صدای یک فایل زنده: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- گزارش‌های عملکرد زمان اجرا: `OpenClaw Performance` را با `live_gpt54=true` برای یک نوبت عامل واقعی `openai/gpt-5.4` یا - `deep_profile=true` برای آرتیفکت‌های CPU/heap/trace مربوط به Kova ارسال کنید. اجراهای زمان‌بندی‌شده روزانه - وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، آرتیفکت‌های مسیر mock-provider، deep-profile، و GPT 5.4 را در - `openclaw/clawgrit-reports` منتشر می‌کنند. - گزارش mock-provider همچنین شامل اعداد بوت Gateway در سطح منبع، حافظه، - فشار Plugin، حلقه تکراری hello برای fake-model، و شروع CLI است. -- جاروب مدل زنده با Docker: `pnpm test:docker:live-models` - - هر مدل انتخاب‌شده اکنون یک نوبت متنی به‌علاوه یک کاوش کوچک به سبک خواندن فایل اجرا می‌کند. - مدل‌هایی که فراداده‌شان ورودی `image` را اعلام می‌کند، یک نوبت تصویر کوچک هم اجرا می‌کنند. - هنگام جداسازی شکست‌های ارائه‌دهنده، کاوش‌های اضافی را با `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` یا + `deep_profile=true` برای مصنوعات CPU/heap/trace مربوط به Kova dispatch کنید. اجراهای زمان‌بندی‌شده روزانه + وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، مصنوعات مسیر mock-provider، deep-profile، و GPT 5.4 را در + `openclaw/clawgrit-reports` منتشر می‌کنند. گزارش + mock-provider همچنین شامل اعداد بوت Gateway در سطح منبع، حافظه، + فشار Plugin، حلقه تکراری hello-loop مدل ساختگی، و راه‌اندازی CLI است. +- پیمایش مدل زنده Docker: `pnpm test:docker:live-models` + - هر مدل انتخاب‌شده اکنون یک نوبت متنی به‌علاوه یک بررسی کوچک به سبک خواندن فایل را اجرا می‌کند. + مدل‌هایی که فراداده آن‌ها ورودی `image` را اعلام می‌کند، یک نوبت تصویر کوچک هم اجرا می‌کنند. + هنگام جداسازی شکست‌های ارائه‌دهنده، بررسی‌های اضافی را با `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` یا `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` غیرفعال کنید. - - پوشش CI: اجرای روزانه `OpenClaw Scheduled Live And E2E Checks` و اجرای دستی - `OpenClaw Release Checks` هر دو گردش‌کار قابل استفاده مجدد live/E2E را با - `include_live_suites: true` فراخوانی می‌کنند، که شامل jobهای ماتریسی جداگانه مدل زنده Docker است - که بر اساس ارائه‌دهنده shard شده‌اند. + - پوشش CI: `OpenClaw Scheduled Live And E2E Checks` روزانه و + `OpenClaw Release Checks` دستی هر دو گردش کار قابل استفاده مجدد live/E2E را با + `include_live_suites: true` فراخوانی می‌کنند، که شامل کارهای ماتریسی جداگانه مدل زنده Docker + است که بر اساس ارائه‌دهنده shard شده‌اند. - برای اجرای دوباره متمرکز در CI، `OpenClaw Live And E2E Checks (Reusable)` را - با `include_live_suites: true` و `live_models_only: true` ارسال کنید. - - secretهای جدید و پربازده ارائه‌دهنده را به `scripts/ci-hydrate-live-auth.sh` + با `include_live_suites: true` و `live_models_only: true` dispatch کنید. + - رازهای ارائه‌دهنده جدید و با سیگنال بالا را به `scripts/ci-hydrate-live-auth.sh` به‌علاوه `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` و فراخوان‌های زمان‌بندی‌شده/انتشار آن اضافه کنید. -- اسموک گفت‌وگوی متصل Native Codex: `pnpm test:docker:live-codex-bind` - - یک مسیر زنده Docker را در برابر مسیر app-server مربوط به Codex اجرا می‌کند، یک DM مصنوعی +- smoke گفت‌وگوی متصل بومی Codex: `pnpm test:docker:live-codex-bind` + - یک مسیر زنده Docker را در برابر مسیر app-server مربوط به Codex اجرا می‌کند، یک پیام مستقیم مصنوعی Slack را با `/codex bind` متصل می‌کند، `/codex fast` و - `/codex permissions` را تمرین می‌دهد، سپس بررسی می‌کند که یک پاسخ ساده و یک پیوست تصویر - از طریق اتصال native Plugin به‌جای ACP مسیریابی شوند. -- اسموک harness مربوط به app-server در Codex: `pnpm test:docker:live-codex-harness` - - نوبت‌های عامل Gateway را از طریق harness مربوط به app-server در Codex که مالکیتش با Plugin است اجرا می‌کند، - `/codex status` و `/codex models` را بررسی می‌کند، و به‌صورت پیش‌فرض کاوش‌های تصویر، - cron MCP، زیرعامل، و Guardian را تمرین می‌دهد. هنگام جداسازی دیگر شکست‌های app-server در Codex، - کاوش زیرعامل را با `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` غیرفعال کنید. - برای یک بررسی متمرکز زیرعامل، کاوش‌های دیگر را غیرفعال کنید: + `/codex permissions` را تمرین می‌کند، سپس تأیید می‌کند که یک پاسخ ساده و یک پیوست تصویر + به‌جای ACP از طریق اتصال بومی Plugin عبور می‌کنند. +- smoke ابزار app-server مربوط به Codex: `pnpm test:docker:live-codex-harness` + - نوبت‌های عامل Gateway را از طریق ابزار app-server مالکیت‌شده توسط Plugin مربوط به Codex اجرا می‌کند، + `/codex status` و `/codex models` را تأیید می‌کند، و به‌طور پیش‌فرض بررسی‌های تصویر، + MCP متعلق به cron، زیرعامل، و Guardian را تمرین می‌کند. هنگام جداسازی شکست‌های دیگر + app-server مربوط به Codex، بررسی زیرعامل را با + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` غیرفعال کنید. برای بررسی متمرکز زیرعامل، بررسی‌های دیگر را غیرفعال کنید: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - این اجرا پس از کاوش زیرعامل خارج می‌شود مگر اینکه + این پس از بررسی زیرعامل خارج می‌شود مگر اینکه `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` تنظیم شده باشد. -- اسموک فرمان نجات Crestodian: `pnpm test:live:crestodian-rescue-channel` - - بررسی اختیاری و کمربند-و-بند شلواری برای سطح فرمان نجات کانال پیام. - `/crestodian status` را تمرین می‌دهد، یک تغییر پایدار مدل را در صف می‌گذارد، - به `/crestodian yes` پاسخ می‌دهد، و مسیر نوشتن audit/config را بررسی می‌کند. -- اسموک Docker برنامه‌ریز Crestodian: `pnpm test:docker:crestodian-planner` - - Crestodian را در یک کانتینر بدون پیکربندی با یک Claude CLI جعلی روی `PATH` اجرا می‌کند - و بررسی می‌کند fallback برنامه‌ریز fuzzy به یک نوشتن پیکربندی تایپ‌شده و audit‌شده ترجمه شود. -- اسموک Docker اجرای نخست Crestodian: `pnpm test:docker:crestodian-first-run` - - از یک دایرکتوری state خالی OpenClaw شروع می‌کند، `openclaw` خام را به - Crestodian مسیریابی می‌کند، نوشتن‌های setup/model/agent/Discord plugin + SecretRef را اعمال می‌کند، - پیکربندی را اعتبارسنجی می‌کند، و ورودی‌های audit را بررسی می‌کند. همان مسیر راه‌اندازی Ring 0 +- smoke فرمان نجات Crestodian: `pnpm test:live:crestodian-rescue-channel` + - بررسی اختیاری و دو‌لایه برای سطح فرمان نجات کانال پیام. + `/crestodian status` را تمرین می‌کند، یک تغییر مدل پایدار را صف می‌کند، + به `/crestodian yes` پاسخ می‌دهد، و مسیر نوشتن audit/config را تأیید می‌کند. +- smoke برنامه‌ریز Crestodian در Docker: `pnpm test:docker:crestodian-planner` + - Crestodian را در یک کانتینر بدون پیکربندی با یک Claude CLI ساختگی روی `PATH` + اجرا می‌کند و تأیید می‌کند که fallback برنامه‌ریز fuzzy به یک نوشتن پیکربندی typed و auditشده + ترجمه می‌شود. +- smoke اجرای نخست Crestodian در Docker: `pnpm test:docker:crestodian-first-run` + - از یک پوشه وضعیت خالی OpenClaw شروع می‌کند، `openclaw` خام را به + Crestodian مسیریابی می‌کند، نوشتن‌های setup/model/agent/Plugin متعلق به Discord + SecretRef را اعمال می‌کند، + پیکربندی را اعتبارسنجی می‌کند، و ورودی‌های audit را تأیید می‌کند. همان مسیر راه‌اندازی Ring 0 در QA Lab نیز با - `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` پوشش داده شده است. -- اسموک هزینه Moonshot/Kimi: با تنظیم بودن `MOONSHOT_API_KEY`، - `openclaw models list --provider moonshot --json` را اجرا کنید، سپس یک اجرای ایزوله + `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup` پوشش داده می‌شود. +- smoke هزینه Moonshot/Kimi: با تنظیم `MOONSHOT_API_KEY`، فرمان + `openclaw models list --provider moonshot --json` را اجرا کنید، سپس یک `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - را در برابر `moonshot/kimi-k2.6` اجرا کنید. بررسی کنید که JSON، Moonshot/K2.6 را گزارش کند و - transcript دستیار، `usage.cost` نرمال‌شده را ذخیره کند. + ایزوله را در برابر `moonshot/kimi-k2.6` اجرا کنید. تأیید کنید که JSON، Moonshot/K2.6 را گزارش می‌کند و + رونوشت assistant مقدار نرمال‌شده `usage.cost` را ذخیره می‌کند. -وقتی فقط به یک مورد شکست‌خورده نیاز دارید، محدود کردن آزمون‌های زنده از طریق env varهای allowlist که در پایین توضیح داده شده‌اند را ترجیح دهید. +وقتی فقط به یک مورد شکست‌خورده نیاز دارید، محدود کردن آزمون‌های زنده از طریق متغیرهای محیطی allowlist که در ادامه توصیف شده‌اند را ترجیح دهید. -## اجراکننده‌های مخصوص QA +## اجراکننده‌های ویژه QA -این فرمان‌ها وقتی به واقع‌گرایی QA-lab نیاز دارید، کنار مجموعه‌های آزمون اصلی قرار می‌گیرند: +وقتی به واقع‌گرایی QA-lab نیاز دارید، این فرمان‌ها کنار مجموعه‌های آزمون اصلی قرار می‌گیرند: -CI، QA Lab را در گردش‌کارهای اختصاصی اجرا می‌کند. برابری agentic زیر -`QA-Lab - All Lanes` و اعتبارسنجی انتشار تو در تو است، نه یک گردش‌کار مستقل PR. +CI، QA Lab را در گردش‌کارهای اختصاصی اجرا می‌کند. برابری عاملی زیر +`QA-Lab - All Lanes` و اعتبارسنجی انتشار قرار دارد، نه یک گردش‌کار مستقل PR. اعتبارسنجی گسترده باید از `Full Release Validation` با `rerun_group=qa-parity` یا گروه QA مربوط به release-checks استفاده کند. `QA-Lab - All Lanes` -هر شب روی `main` و از طریق ارسال دستی، با مسیر برابری mock، مسیر زنده +هر شب روی `main` و از dispatch دستی با مسیر mock parity، مسیر زنده Matrix، مسیر زنده Telegram مدیریت‌شده با Convex، و مسیر زنده Discord -مدیریت‌شده با Convex به‌عنوان jobهای موازی اجرا می‌شود. QA زمان‌بندی‌شده و بررسی‌های انتشار، -Matrix را صراحتا با `--profile fast` ارسال می‌کنند، در حالی که مقدار پیش‌فرض CLI مربوط به Matrix و ورودی گردش‌کار دستی -همچنان `all` است؛ ارسال دستی می‌تواند `all` را به jobهای `transport`، -`media`، `e2ee-smoke`، `e2ee-deep`، و `e2ee-cli` shard کند. `OpenClaw Release -Checks` پیش از تایید انتشار، برابری به‌علاوه مسیرهای سریع Matrix و Telegram را اجرا می‌کند +مدیریت‌شده با Convex به‌عنوان کارهای موازی اجرا می‌شود. QA زمان‌بندی‌شده و بررسی‌های انتشار، Matrix +`--profile fast` را صراحتاً پاس می‌دهند، در حالی که مقدار پیش‌فرض Matrix CLI و ورودی گردش‌کار دستی +همچنان `all` می‌ماند؛ dispatch دستی می‌تواند `all` را به کارهای `transport`, +`media`, `e2ee-smoke`, `e2ee-deep`, و `e2ee-cli` shard کند. `OpenClaw Release +Checks` پیش از تأیید انتشار، parity به‌علاوه مسیرهای سریع Matrix و Telegram را اجرا می‌کند و برای بررسی‌های انتقال انتشار از `mock-openai/gpt-5.5` استفاده می‌کند تا قطعی بمانند -و از شروع عادی Plugin ارائه‌دهنده پرهیز کنند. این Gatewayهای انتقال زنده -جست‌وجوی حافظه را غیرفعال می‌کنند؛ رفتار حافظه همچنان توسط مجموعه‌های برابری QA +و از راه‌اندازی عادی Plugin ارائه‌دهنده پرهیز کنند. این Gatewayهای انتقال زنده +جست‌وجوی حافظه را غیرفعال می‌کنند؛ رفتار حافظه همچنان توسط مجموعه‌های QA parity پوشش داده می‌شود. shardهای رسانه زنده انتشار کامل از `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` استفاده می‌کنند، که از قبل `ffmpeg` و `ffprobe` را دارد. shardهای مدل/بک‌اند زنده Docker از تصویر مشترک `ghcr.io/openclaw/openclaw-live-test:` استفاده می‌کنند که یک‌بار برای commit انتخاب‌شده ساخته می‌شود، -سپس آن را با `OPENCLAW_SKIP_DOCKER_BUILD=1` pull می‌کنند، به‌جای اینکه داخل هر shard -دوباره build کنند. +سپس آن را با `OPENCLAW_SKIP_DOCKER_BUILD=1` pull می‌کنند، به‌جای اینکه داخل هر shard دوباره build شود. - `pnpm openclaw qa suite` - - سناریوهای QA مبتنی بر مخزن را مستقیماً روی میزبان اجرا می‌کند. - - چندین سناریوی انتخاب‌شده را به‌صورت پیش‌فرض با workerهای Gateway ایزوله به‌صورت موازی اجرا می‌کند. `qa-channel` به‌صورت پیش‌فرض از همزمانی 4 استفاده می‌کند (محدود به تعداد سناریوهای انتخاب‌شده). برای تنظیم تعداد workerها از `--concurrency ` استفاده کنید، یا برای مسیر سریال قدیمی‌تر از `--concurrency 1`. - - وقتی هر سناریویی شکست بخورد، با کد غیرصفر خارج می‌شود. وقتی artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. - - از حالت‌های provider با نام‌های `live-frontier`، `mock-openai` و `aimock` پشتیبانی می‌کند. `aimock` یک سرور provider محلی مبتنی بر AIMock را برای پوشش آزمایشی fixture و mock پروتکل راه‌اندازی می‌کند، بدون اینکه مسیر آگاه از سناریوی `mock-openai` را جایگزین کند. + - سناریوهای QA پشتوانه‌دار با مخزن را مستقیماً روی میزبان اجرا می‌کند. + - به‌طور پیش‌فرض چند سناریوی انتخاب‌شده را به‌صورت موازی با workerهای + Gateway ایزوله اجرا می‌کند. `qa-channel` به‌طور پیش‌فرض هم‌زمانی ۴ دارد (محدود به + تعداد سناریوهای انتخاب‌شده). برای تنظیم تعداد workerها از `--concurrency ` استفاده کنید، + یا برای مسیر سریال قدیمی‌تر از `--concurrency 1` استفاده کنید. + - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی + artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. + - از حالت‌های provider به نام‌های `live-frontier`، `mock-openai` و `aimock` پشتیبانی می‌کند. + `aimock` یک سرور provider محلی با پشتوانه AIMock برای پوشش آزمایشی + fixture و protocol-mock راه‌اندازی می‌کند، بدون اینکه مسیر آگاه از سناریوی + `mock-openai` را جایگزین کند. - `pnpm test:gateway:cpu-scenarios` - - bench راه‌اندازی Gateway را به‌همراه یک بسته کوچک سناریوی mock QA Lab (`channel-chat-baseline`، `memory-failure-fallback`، `gateway-restart-inflight-run`) اجرا می‌کند و یک خلاصه ترکیبی مشاهده CPU را زیر `.artifacts/gateway-cpu-scenarios/` می‌نویسد. - - به‌صورت پیش‌فرض فقط مشاهده‌های CPU داغ و پایدار را علامت‌گذاری می‌کند (`--cpu-core-warn` به‌علاوه `--hot-wall-warn-ms`)، بنابراین جهش‌های کوتاه راه‌اندازی به‌عنوان metric ثبت می‌شوند، بدون اینکه شبیه رگرسیون چنددقیقه‌ای درگیری Gateway به نظر برسند. - - از artifactهای ساخته‌شده `dist` استفاده می‌کند؛ وقتی checkout هنوز خروجی runtime تازه ندارد، ابتدا build را اجرا کنید. + - بنچ راه‌اندازی Gateway را همراه با یک بسته کوچک سناریوی mock QA Lab + (`channel-chat-baseline`، `memory-failure-fallback`، + `gateway-restart-inflight-run`) اجرا می‌کند و یک خلاصه ترکیبی از مشاهده CPU + زیر `.artifacts/gateway-cpu-scenarios/` می‌نویسد. + - به‌طور پیش‌فرض فقط مشاهده‌های پایدار CPU داغ را علامت‌گذاری می‌کند (`--cpu-core-warn` + به‌همراه `--hot-wall-warn-ms`)، بنابراین جهش‌های کوتاه زمان راه‌اندازی به‌عنوان metrics + ثبت می‌شوند بدون اینکه شبیه رگرسیون چنددقیقه‌ای قفل‌شدن Gateway به نظر برسند. + - از artifactهای ساخته‌شده `dist` استفاده می‌کند؛ وقتی checkout از قبل خروجی runtime تازه ندارد، + ابتدا یک build اجرا کنید. - `pnpm openclaw qa suite --runner multipass` - - همان مجموعه QA را داخل یک VM یک‌بارمصرف Linux با Multipass اجرا می‌کند. - - همان رفتار انتخاب سناریو را مانند `qa suite` روی میزبان حفظ می‌کند. - - از همان flagهای انتخاب provider/model مانند `qa suite` دوباره استفاده می‌کند. - - اجراهای live ورودی‌های احراز هویت QA پشتیبانی‌شده‌ای را که برای guest عملی هستند forward می‌کنند: کلیدهای provider مبتنی بر env، مسیر config مربوط به provider زنده QA، و `CODEX_HOME` در صورت وجود. - - دایرکتوری‌های خروجی باید زیر ریشه مخزن بمانند تا guest بتواند از طریق workspace mount‌شده دوباره بنویسد. - - گزارش و خلاصه معمول QA به‌علاوه logهای Multipass را زیر `.artifacts/qa-e2e/...` می‌نویسد. + - همان مجموعه QA را داخل یک VM لینوکسی disposable در Multipass اجرا می‌کند. + - همان رفتار انتخاب سناریو مثل `qa suite` روی میزبان را نگه می‌دارد. + - همان flagهای انتخاب provider/model مثل `qa suite` را دوباره استفاده می‌کند. + - اجراهای live ورودی‌های پشتیبانی‌شده auth برای QA را که برای guest عملی هستند forward می‌کنند: + کلیدهای provider مبتنی بر env، مسیر پیکربندی provider زنده QA، و `CODEX_HOME` + وقتی حاضر باشد. + - مسیرهای خروجی باید زیر ریشه مخزن بمانند تا guest بتواند از طریق + workspace mount‌شده دوباره بنویسد. + - گزارش و خلاصه معمول QA به‌علاوه logهای Multipass را زیر + `.artifacts/qa-e2e/...` می‌نویسد. - `pnpm qa:lab:up` - - سایت QA مبتنی بر Docker را برای کار QA به سبک operator راه‌اندازی می‌کند. + - سایت QA با پشتوانه Docker را برای کار QA به سبک operator راه‌اندازی می‌کند. - `pnpm test:docker:npm-onboard-channel-agent` - - از checkout فعلی یک tarball مربوط به npm می‌سازد، آن را به‌صورت global در Docker نصب می‌کند، onboarding غیرتعاملی با کلید API مربوط به OpenAI را اجرا می‌کند، به‌صورت پیش‌فرض Telegram را config می‌کند، تأیید می‌کند runtime مربوط به Plugin بسته‌بندی‌شده بدون تعمیر dependency هنگام راه‌اندازی load می‌شود، doctor را اجرا می‌کند، و یک نوبت agent محلی را در برابر یک endpoint شبیه‌سازی‌شده OpenAI اجرا می‌کند. - - برای اجرای همان مسیر نصب بسته‌بندی‌شده با Discord، از `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` استفاده کنید. + - از checkout فعلی یک tarball مربوط به npm می‌سازد، آن را به‌صورت global در + Docker نصب می‌کند، onboarding غیرتعاملی کلید OpenAI API را اجرا می‌کند، به‌طور پیش‌فرض Telegram + را پیکربندی می‌کند، تأیید می‌کند runtime مربوط به Plugin بسته‌بندی‌شده بدون تعمیر وابستگی + در زمان راه‌اندازی load می‌شود، doctor را اجرا می‌کند، و یک نوبت agent محلی را در برابر یک + endpoint mock‌شده OpenAI اجرا می‌کند. + - برای اجرای همان مسیر نصب بسته‌بندی‌شده با Discord از `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` استفاده کنید. - `pnpm test:docker:session-runtime-context` - - یک smoke قطعی Docker برای app ساخته‌شده، جهت transcriptهای context مربوط به runtime تعبیه‌شده اجرا می‌کند. تأیید می‌کند context مخفی runtime مربوط به OpenClaw به‌عنوان یک پیام سفارشی غیرنمایشی persist می‌شود و به نوبت کاربر قابل‌مشاهده leak نمی‌کند، سپس یک session JSONL خرابِ affected را seed می‌کند و تأیید می‌کند `openclaw doctor --fix` آن را با backup به branch فعال بازنویسی می‌کند. + - یک smoke قطعی Docker از برنامه ساخته‌شده برای transcriptهای context runtime توکار + اجرا می‌کند. تأیید می‌کند context runtime پنهان OpenClaw به‌عنوان یک پیام سفارشی + غیرنمایشی persisted می‌شود، به‌جای اینکه به نوبت قابل‌مشاهده کاربر نشت کند، + سپس یک session JSONL خراب تحت‌تأثیر را seed می‌کند و تأیید می‌کند + `openclaw doctor --fix` آن را با یک backup به branch فعال بازنویسی می‌کند. - `pnpm test:docker:npm-telegram-live` - - یک candidate مربوط به package OpenClaw را در Docker نصب می‌کند، onboarding مربوط به package نصب‌شده را اجرا می‌کند، Telegram را از طریق CLI نصب‌شده config می‌کند، سپس مسیر live Telegram QA را با همان package نصب‌شده به‌عنوان SUT Gateway دوباره استفاده می‌کند. - - مقدار پیش‌فرض `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` است؛ برای test کردن یک tarball محلی resolve‌شده به‌جای نصب از registry، `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` یا `OPENCLAW_CURRENT_PACKAGE_TGZ` را تنظیم کنید. - - از همان credentials مربوط به env در Telegram یا منبع credential مربوط به Convex مانند `pnpm openclaw qa telegram` استفاده می‌کند. برای automation در CI/release، `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` را به‌همراه `OPENCLAW_QA_CONVEX_SITE_URL` و secret نقش تنظیم کنید. اگر `OPENCLAW_QA_CONVEX_SITE_URL` و یک secret نقش Convex در CI حاضر باشند، wrapper مربوط به Docker به‌صورت خودکار Convex را انتخاب می‌کند. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` فقط برای این مسیر، `OPENCLAW_QA_CREDENTIAL_ROLE` مشترک را override می‌کند. - - GitHub Actions این مسیر را به‌عنوان workflow دستی maintainer با نام `NPM Telegram Beta E2E` ارائه می‌کند. هنگام merge اجرا نمی‌شود. این workflow از environment با نام `qa-live-shared` و leaseهای credential مربوط به Convex CI استفاده می‌کند. -- GitHub Actions همچنین `Package Acceptance` را برای اثبات محصول در اجرای جانبی در برابر یک package candidate ارائه می‌کند. این workflow یک ref مورداعتماد، spec منتشرشده npm، URL مربوط به tarball با HTTPS به‌همراه SHA-256، یا artifact مربوط به tarball از اجرای دیگری را می‌پذیرد، `openclaw-current.tgz` نرمال‌شده را به‌عنوان `package-under-test` upload می‌کند، سپس scheduler موجود Docker E2E را با profileهای مسیر smoke، package، product، full یا custom اجرا می‌کند. برای اجرای workflow مربوط به Telegram QA در برابر همان artifact با نام `package-under-test`، `telegram_mode=mock-openai` یا `live-frontier` را تنظیم کنید. - - تازه‌ترین اثبات محصول beta: + - یک کاندید package از OpenClaw را در Docker نصب می‌کند، onboarding package نصب‌شده را + اجرا می‌کند، Telegram را از طریق CLI نصب‌شده پیکربندی می‌کند، سپس مسیر QA زنده Telegram + را با همان package نصب‌شده به‌عنوان Gateway تحت آزمون دوباره استفاده می‌کند. + - مقدار پیش‌فرض `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` است؛ برای آزمون یک tarball + محلی resolve‌شده به‌جای نصب از registry، `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` + یا `OPENCLAW_CURRENT_PACKAGE_TGZ` را تنظیم کنید. + - از همان credentials محیطی Telegram یا منبع credential Convex مثل + `pnpm openclaw qa telegram` استفاده می‌کند. برای automation در CI/release، + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` را به‌همراه + `OPENCLAW_QA_CONVEX_SITE_URL` و secret نقش تنظیم کنید. اگر + `OPENCLAW_QA_CONVEX_SITE_URL` و یک secret نقش Convex در CI حاضر باشند، + wrapper Docker به‌طور خودکار Convex را انتخاب می‌کند. + - wrapper پیش از کار build/install در Docker، env مربوط به credentialهای Telegram یا Convex + را روی میزبان validate می‌کند. فقط وقتی عمداً در حال debug تنظیمات پیش از credential هستید، + `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` را تنظیم کنید. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` فقط برای این مسیر، مقدار مشترک + `OPENCLAW_QA_CREDENTIAL_ROLE` را override می‌کند. + - GitHub Actions این مسیر را به‌عنوان workflow دستی maintainer با نام + `NPM Telegram Beta E2E` ارائه می‌کند. روی merge اجرا نمی‌شود. این workflow از + محیط `qa-live-shared` و leaseهای credential مربوط به Convex CI استفاده می‌کند. +- GitHub Actions همچنین `Package Acceptance` را برای اثبات محصول side-run + در برابر یک package کاندید ارائه می‌کند. یک ref قابل‌اعتماد، spec منتشرشده npm، + URL tarball از نوع HTTPS به‌همراه SHA-256، یا artifact tarball از اجرای دیگری را می‌پذیرد، + `openclaw-current.tgz` نرمال‌شده را به‌عنوان `package-under-test` upload می‌کند، سپس + scheduler موجود Docker E2E را با profileهای مسیر smoke، package، product، full، یا custom + اجرا می‌کند. برای اجرای workflow QA مربوط به Telegram در برابر همان artifact + `package-under-test`، `telegram_mode=mock-openai` یا `live-frontier` را تنظیم کنید. + - اثبات محصول آخرین beta: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -188,7 +234,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- اثبات artifact یک artifact مربوط به tarball را از اجرای دیگری در Actions دانلود می‌کند: +- اثبات artifact یک artifact مربوط به tarball را از اجرای Actions دیگری download می‌کند: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -199,50 +245,75 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - build فعلی OpenClaw را در Docker pack و install می‌کند، Gateway را با OpenAI config‌شده راه‌اندازی می‌کند، سپس channel/plugins بسته‌بندی‌شده را از طریق ویرایش config فعال می‌کند. - - تأیید می‌کند discovery راه‌اندازی، plugins قابل‌دانلودِ configنشده را غایب نگه می‌دارد، اولین تعمیر doctor پیکربندی‌شده هر Plugin قابل‌دانلودِ گمشده را صراحتاً نصب می‌کند، و restart دوم تعمیر dependency پنهان اجرا نمی‌کند. - - همچنین یک baseline قدیمی‌تر و شناخته‌شده از npm را نصب می‌کند، Telegram را قبل از اجرای `openclaw update --tag ` فعال می‌کند، و تأیید می‌کند doctor پس از update مربوط به candidate، بقایای legacy dependency مربوط به Plugin را بدون تعمیر postinstall در سمت harness پاک‌سازی می‌کند. + - build فعلی OpenClaw را در Docker pack و install می‌کند، Gateway را + با OpenAI پیکربندی‌شده راه‌اندازی می‌کند، سپس channel/pluginsهای bundled را از طریق ویرایش‌های config + فعال می‌کند. + - تأیید می‌کند discovery مربوط به setup، Pluginهای downloadable پیکربندی‌نشده را absent می‌گذارد، + نخستین repair پیکربندی‌شده doctor هر Plugin دانلودشدنی missing را صریحاً install می‌کند، + و restart دوم repair پنهان وابستگی را اجرا نمی‌کند. + - همچنین یک baseline قدیمی‌تر شناخته‌شده npm را install می‌کند، پیش از اجرای + `openclaw update --tag `، Telegram را فعال می‌کند، و تأیید می‌کند doctor پس از update + کاندید، بقایای legacy وابستگی Plugin را بدون repair مربوط به postinstall در سمت harness پاک می‌کند. - `pnpm test:parallels:npm-update` - - smoke مربوط به update نصب بسته‌بندی‌شده native را در سراسر guestهای Parallels اجرا می‌کند. هر platform انتخاب‌شده ابتدا package baseline درخواست‌شده را نصب می‌کند، سپس command نصب‌شده `openclaw update` را در همان guest اجرا می‌کند و نسخه نصب‌شده، وضعیت update، آمادگی Gateway و یک نوبت agent محلی را تأیید می‌کند. - - هنگام تکرار روی یک guest، از `--platform macos`، `--platform windows` یا `--platform linux` استفاده کنید. برای مسیر artifact خلاصه و وضعیت هر مسیر از `--json` استفاده کنید. - - مسیر OpenAI به‌صورت پیش‌فرض از `openai/gpt-5.5` برای اثبات live نوبت agent استفاده می‌کند. وقتی عمداً model دیگری از OpenAI را validate می‌کنید، `--model ` را pass کنید یا `OPENCLAW_PARALLELS_OPENAI_MODEL` را تنظیم کنید. - - اجراهای محلی طولانی را در یک timeout میزبان wrap کنید تا stallهای transport مربوط به Parallels نتوانند باقی پنجره test را مصرف کنند: + - smoke بومی update برای نصب package‌شده را روی guestهای Parallels اجرا می‌کند. هر + platform انتخاب‌شده ابتدا package baseline درخواست‌شده را install می‌کند، سپس + دستور نصب‌شده `openclaw update` را در همان guest اجرا می‌کند و version نصب‌شده، + status update، آمادگی Gateway، و یک نوبت agent محلی را verify می‌کند. + - هنگام iteration روی یک guest، از `--platform macos`، `--platform windows`، یا `--platform linux` استفاده کنید. + برای مسیر artifact خلاصه و وضعیت هر مسیر، از `--json` استفاده کنید. + - مسیر OpenAI به‌طور پیش‌فرض از `openai/gpt-5.5` برای اثبات نوبت agent live استفاده می‌کند. + وقتی عمداً یک model دیگر OpenAI را validate می‌کنید، `--model ` را pass کنید + یا `OPENCLAW_PARALLELS_OPENAI_MODEL` را تنظیم کنید. + - اجراهای محلی طولانی را در یک timeout میزبان wrap کنید تا stallهای transport در Parallels نتوانند + باقی پنجره testing را مصرف کنند: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - script، logهای nested lane را زیر `/tmp/openclaw-parallels-npm-update.*` می‌نویسد. پیش از اینکه فرض کنید wrapper بیرونی hang کرده است، `windows-update.log`، `macos-update.log` یا `linux-update.log` را بررسی کنید. - - update در Windows روی guest سرد می‌تواند 10 تا 15 دقیقه را در کارهای doctor پس از update و update package صرف کند؛ تا وقتی log debug داخلی npm در حال پیشرفت است، این هنوز سالم است. - - این wrapper تجمیعی را هم‌زمان با مسیرهای smoke جداگانه macOS، Windows یا Linux در Parallels اجرا نکنید. آن‌ها وضعیت VM مشترک دارند و ممکن است در restore snapshot، سرو package یا وضعیت Gateway در guest با هم collide کنند. - - اثبات پس از update سطح معمول Pluginهای bundled را اجرا می‌کند، چون facadeهای capability مانند speech، image generation و media understanding از طریق APIهای runtime مربوط به bundled load می‌شوند، حتی وقتی خود نوبت agent فقط یک پاسخ متنی ساده را بررسی می‌کند. + - این script logهای تو در توی هر مسیر را زیر `/tmp/openclaw-parallels-npm-update.*` می‌نویسد. + پیش از اینکه فرض کنید wrapper بیرونی hang شده، `windows-update.log`، `macos-update.log`، یا `linux-update.log` + را inspect کنید. + - update ویندوز می‌تواند در guest سرد ۱۰ تا ۱۵ دقیقه در کار doctor پس از update و package + update زمان بگذارد؛ تا وقتی log debug تو در توی npm در حال پیشروی است، این وضعیت هنوز سالم است. + - این wrapper aggregate را به‌صورت موازی با مسیرهای smoke تکی Parallels + macOS، Windows، یا Linux اجرا نکنید. آن‌ها state مربوط به VM را share می‌کنند و می‌توانند در + restore snapshot، serving package، یا state مربوط به Gateway در guest تداخل کنند. + - اثبات پس از update سطح معمول Plugin bundled را اجرا می‌کند، زیرا + facadeهای capability مانند گفتار، تولید تصویر، و فهم رسانه + از طریق APIهای runtime bundled load می‌شوند، حتی وقتی خود نوبت agent + فقط یک پاسخ متنی ساده را بررسی می‌کند. - `pnpm openclaw qa aimock` - - فقط سرور provider محلی AIMock را برای smoke testing مستقیم protocol راه‌اندازی می‌کند. + - فقط سرور provider محلی AIMock را برای smoke testing مستقیم protocol + راه‌اندازی می‌کند. - `pnpm openclaw qa matrix` - - مسیر live QA مربوط به Matrix را در برابر یک homeserver یک‌بارمصرف Tuwunel مبتنی بر Docker اجرا می‌کند. فقط source-checkout — نصب‌های بسته‌بندی‌شده `qa-lab` را ship نمی‌کنند. - - CLI کامل، catalog مربوط به profile/scenario، env vars و layout مربوط به artifact: [Matrix QA](/fa/concepts/qa-matrix). + - مسیر QA زنده Matrix را در برابر یک homeserver یک‌بارمصرف Tuwunel با پشتوانه Docker اجرا می‌کند. فقط source-checkout — نصب‌های package‌شده `qa-lab` را ship نمی‌کنند. + - CLI کامل، catalog مربوط به profile/scenario، env varها، و layout مربوط به artifact: [Matrix QA](/fa/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - مسیر live QA مربوط به Telegram را در برابر یک گروه خصوصی واقعی با استفاده از tokenهای driver و SUT bot از env اجرا می‌کند. - - به `OPENCLAW_QA_TELEGRAM_GROUP_ID`، `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` و `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` نیاز دارد. group id باید chat id عددی Telegram باشد. - - از `--credential-source convex` برای credentials pooled مشترک پشتیبانی می‌کند. به‌صورت پیش‌فرض از حالت env استفاده کنید، یا برای opt in به leaseهای pooled، `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید. - - وقتی هر سناریویی شکست بخورد، با کد غیرصفر خارج می‌شود. وقتی artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. - - به دو bot متمایز در همان گروه خصوصی نیاز دارد، به‌طوری‌که SUT bot یک username در Telegram ارائه کند. - - برای مشاهده پایدار bot-to-bot، Bot-to-Bot Communication Mode را در `@BotFather` برای هر دو bot فعال کنید و مطمئن شوید driver bot می‌تواند ترافیک botهای گروه را مشاهده کند. - - یک گزارش Telegram QA، خلاصه، و artifact مربوط به پیام‌های مشاهده‌شده را زیر `.artifacts/qa-e2e/...` می‌نویسد. سناریوهای پاسخ‌دهنده شامل RTT از درخواست ارسال driver تا پاسخ مشاهده‌شده SUT هستند. + - مسیر QA زنده Telegram را در برابر یک گروه private واقعی با استفاده از tokenهای driver و SUT bot از env اجرا می‌کند. + - به `OPENCLAW_QA_TELEGRAM_GROUP_ID`، `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`، و `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` نیاز دارد. group id باید chat id عددی Telegram باشد. + - از `--credential-source convex` برای credentialهای pooled مشترک پشتیبانی می‌کند. به‌طور پیش‌فرض از حالت env استفاده کنید، یا برای opt in به leaseهای pooled، `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` را تنظیم کنید. + - وقتی هر سناریویی شکست بخورد با کد غیرصفر خارج می‌شود. وقتی + artifactها را بدون کد خروج شکست‌خورده می‌خواهید، از `--allow-failures` استفاده کنید. + - به دو bot متمایز در همان گروه private نیاز دارد، در حالی که bot مربوط به SUT یک username مربوط به Telegram را expose می‌کند. + - برای مشاهده پایدار bot-to-bot، Bot-to-Bot Communication Mode را در `@BotFather` برای هر دو bot فعال کنید و مطمئن شوید driver bot می‌تواند traffic botهای گروه را observe کند. + - یک گزارش QA مربوط به Telegram، خلاصه، و artifact پیام‌های مشاهده‌شده را زیر `.artifacts/qa-e2e/...` می‌نویسد. سناریوهای reply شامل RTT از درخواست ارسال driver تا reply مشاهده‌شده SUT هستند. -مسیرهای live transport یک قرارداد استاندارد مشترک دارند تا transportهای جدید دچار drift نشوند؛ ماتریس پوشش هر مسیر در [مرور کلی QA → پوشش live transport](/fa/concepts/qa-e2e-automation#live-transport-coverage) قرار دارد. `qa-channel` مجموعه synthetic گسترده است و بخشی از آن matrix نیست. +مسیرهای transport زنده یک قرارداد استاندارد مشترک دارند تا transportهای جدید drift نکنند؛ matrix پوشش هر مسیر در [نمای کلی QA → پوشش transport زنده](/fa/concepts/qa-e2e-automation#live-transport-coverage) قرار دارد. `qa-channel` مجموعه synthetic گسترده است و بخشی از آن matrix نیست. -### credentials مشترک Telegram از طریق Convex (v1) +### credentialهای مشترک Telegram از طریق Convex (v1) -وقتی `--credential-source convex` (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) برای `openclaw qa telegram` فعال باشد، QA lab یک lease انحصاری از pool مبتنی بر Convex دریافت می‌کند، هنگام اجرای مسیر برای آن lease Heartbeat می‌فرستد، و هنگام shutdown lease را آزاد می‌کند. +وقتی `--credential-source convex` (یا `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) برای +`openclaw qa telegram` فعال باشد، QA lab یک lease انحصاری از pool با پشتوانه Convex می‌گیرد، هنگام اجرای مسیر +برای آن lease Heartbeat می‌فرستد، و هنگام shutdown آن lease را release می‌کند. scaffold مرجع پروژه Convex: - `qa/convex-credential-broker/` -env vars لازم: +env varهای لازم: - `OPENCLAW_QA_CONVEX_SITE_URL` (برای مثال `https://your-deployment.convex.site`) - یک secret برای نقش انتخاب‌شده: @@ -250,9 +321,9 @@ env vars لازم: - `OPENCLAW_QA_CONVEX_SECRET_CI` برای `ci` - انتخاب نقش credential: - CLI: `--credential-role maintainer|ci` - - پیش‌فرض Env: `OPENCLAW_QA_CREDENTIAL_ROLE` (در CI به‌صورت پیش‌فرض `ci`، در غیر این صورت `maintainer`) + - پیش‌فرض env: `OPENCLAW_QA_CREDENTIAL_ROLE` (در CI به‌طور پیش‌فرض `ci`، در غیر این صورت `maintainer`) -env vars اختیاری: +env varهای اختیاری: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (پیش‌فرض `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (پیش‌فرض `30000`) @@ -260,11 +331,12 @@ env vars اختیاری: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (پیش‌فرض `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (پیش‌فرض `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (trace id اختیاری) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` اجازه URLهای Convex با `http://` روی local loopback را برای توسعه فقط محلی می‌دهد. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` اجازه URLهای Convex از نوع loopback `http://` را فقط برای توسعه محلی می‌دهد. -`OPENCLAW_QA_CONVEX_SITE_URL` باید در operation عادی از `https://` استفاده کند. +`OPENCLAW_QA_CONVEX_SITE_URL` باید در عملیات عادی از `https://` استفاده کند. -commandهای admin مربوط به maintainer (pool add/remove/list) مشخصاً به `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` نیاز دارند. +دستورهای admin مربوط به maintainer (pool add/remove/list) مشخصاً به +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` نیاز دارند. helperهای CLI برای maintainerها: @@ -275,14 +347,17 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -پیش از اجراهای live از `doctor` استفاده کنید تا URL سایت Convex، broker secrets، endpoint prefix، HTTP timeout و دسترسی‌پذیری admin/list را بدون چاپ مقدارهای secret بررسی کنید. برای خروجی machine-readable در scriptها و ابزارهای CI از `--json` استفاده کنید. +از `doctor` پیش از اجراهای زنده استفاده کنید تا URL سایت Convex، اسرار broker، +پیشوند endpoint، مهلت زمانی HTTP، و دسترسی‌پذیری admin/list را بدون چاپ +مقادیر محرمانه بررسی کنید. برای خروجی قابل خواندن توسط ماشین در اسکریپت‌ها و ابزارهای CI +از `--json` استفاده کنید. -قرارداد نقطه پایانی پیش‌فرض (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +قرارداد endpoint پیش‌فرض (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - درخواست: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - موفقیت: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - تمام‌شده/قابل‌تلاش مجدد: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - تمام‌شده/قابل تلاش دوباره: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - درخواست: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - موفقیت: `{ status: "ok" }` (یا `2xx` خالی) @@ -295,135 +370,135 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (فقط راز نگه‌دارنده) - درخواست: `{ credentialId, actorId }` - موفقیت: `{ status: "ok", changed, credential }` - - محافظ اجاره فعال: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - محافظ lease فعال: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (فقط راز نگه‌دارنده) - درخواست: `{ kind?, status?, includePayload?, limit? }` - موفقیت: `{ status: "ok", credentials, count }` -شکل payload برای kind مربوط به Telegram: +شکل payload برای نوع Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` باید یک رشته عددی شناسه گفت‌وگوی Telegram باشد. +- `groupId` باید یک رشته عددی شناسه چت Telegram باشد. - `admin/add` این شکل را برای `kind: "telegram"` اعتبارسنجی می‌کند و payloadهای بدشکل را رد می‌کند. ### افزودن یک کانال به QA -معماری و نام‌های کمک‌کننده سناریو برای آداپتورهای کانال جدید در [نمای کلی QA ← افزودن یک کانال](/fa/concepts/qa-e2e-automation#adding-a-channel) قرار دارند. حداقل معیار: پیاده‌سازی runner حمل‌ونقل روی درز میزبان مشترک `qa-lab`، اعلام `qaRunners` در manifest مربوط به Plugin، نصب به‌صورت `openclaw qa `، و نوشتن سناریوها زیر `qa/scenarios/`. +معماری و نام‌های helper سناریو برای adapterهای کانال جدید در [نمای کلی QA → افزودن یک کانال](/fa/concepts/qa-e2e-automation#adding-a-channel) قرار دارند. حداقل معیار: runner انتقال را روی seam میزبان مشترک `qa-lab` پیاده‌سازی کنید، `qaRunners` را در manifest Plugin اعلام کنید، آن را به‌صورت `openclaw qa ` mount کنید، و سناریوها را زیر `qa/scenarios/` بنویسید. ## مجموعه‌های آزمون (چه چیزی کجا اجرا می‌شود) -مجموعه‌ها را به‌صورت «واقع‌گرایی افزایشی» در نظر بگیرید (و همراه با افزایش ناپایداری/هزینه): +این مجموعه‌ها را به‌عنوان «افزایش واقع‌گرایی» (و افزایش ناپایداری/هزینه) در نظر بگیرید: ### واحد / یکپارچه‌سازی (پیش‌فرض) - فرمان: `pnpm test` -- پیکربندی: اجراهای بدون هدف از مجموعه shardهای `vitest.full-*.config.ts` استفاده می‌کنند و ممکن است shardهای چندپروژه‌ای را برای زمان‌بندی موازی به پیکربندی‌های جداگانه هر پروژه گسترش دهند -- فایل‌ها: فهرست‌های core/unit زیر `src/**/*.test.ts`، `packages/**/*.test.ts`، و `test/**/*.test.ts`؛ آزمون‌های واحد UI در shard اختصاصی `unit-ui` اجرا می‌شوند +- پیکربندی: اجراهای بدون هدف از مجموعه shardهای `vitest.full-*.config.ts` استفاده می‌کنند و ممکن است shardهای چندپروژه‌ای را برای زمان‌بندی موازی به پیکربندی‌های per-project گسترش دهند +- فایل‌ها: inventoryهای core/unit زیر `src/**/*.test.ts`، `packages/**/*.test.ts`، و `test/**/*.test.ts`؛ آزمون‌های واحد UI در shard اختصاصی `unit-ui` اجرا می‌شوند - دامنه: - آزمون‌های واحد خالص - - آزمون‌های یکپارچه‌سازی درون‌فرآیندی (احراز هویت Gateway، مسیریابی، ابزارها، تجزیه، پیکربندی) - - رگرسیون‌های قطعی برای خطاهای شناخته‌شده + - آزمون‌های یکپارچه‌سازی درون‌فرایندی (احراز هویت Gateway، مسیریابی، tooling، parsing، config) + - رگرسیون‌های قطعی برای باگ‌های شناخته‌شده - انتظارات: - در CI اجرا می‌شود - - به کلید واقعی نیاز ندارد + - به کلیدهای واقعی نیاز ندارد - باید سریع و پایدار باشد - آزمون‌های resolver و loader سطح عمومی باید رفتار fallback گسترده `api.js` و - `runtime-api.js` را با fixtureهای کوچک تولیدشده Plugin اثبات کنند، نه - APIهای سورس Pluginهای bundled واقعی. بارگذاری‌های API واقعی Plugin به - مجموعه‌های قرارداد/یکپارچه‌سازی متعلق به Plugin تعلق دارند. + `runtime-api.js` را با fixtureهای Plugin کوچک تولیدشده اثبات کنند، نه + APIهای منبع Plugin بسته‌بندی‌شده واقعی. بارگذاری API واقعی Plugin به + مجموعه‌های contract/integration متعلق به Plugin مربوط است. - + - - اجرای بدون هدف `pnpm test` به‌جای یک فرآیند عظیم پروژه ریشه native، دوازده پیکربندی shard کوچک‌تر (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) را اجرا می‌کند. این کار اوج RSS را روی ماشین‌های پربار کاهش می‌دهد و مانع می‌شود کار auto-reply/extension مجموعه‌های نامرتبط را محروم کند. - - `pnpm test --watch` همچنان از گراف پروژه native ریشه `vitest.config.ts` استفاده می‌کند، چون یک حلقه watch چند-shard عملی نیست. - - `pnpm test`، `pnpm test:watch`، و `pnpm test:perf:imports` هدف‌های صریح فایل/دایرکتوری را ابتدا از laneهای دامنه‌دار عبور می‌دهند، بنابراین `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` هزینه راه‌اندازی کامل پروژه ریشه را پرداخت نمی‌کند. - - `pnpm test:changed` مسیرهای git تغییریافته را به‌طور پیش‌فرض به laneهای ارزان دامنه‌دار گسترش می‌دهد: ویرایش مستقیم آزمون‌ها، فایل‌های خواهر `*.test.ts`، نگاشت‌های صریح سورس، و وابستگان گراف import محلی. ویرایش‌های config/setup/package آزمون‌ها را به‌صورت گسترده اجرا نمی‌کنند مگر اینکه صراحتا از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. - - `pnpm check:changed` گیت بررسی هوشمند محلی معمول برای کارهای محدود است. diff را به core، آزمون‌های core، extensions، آزمون‌های extension، apps، docs، فراداده release، ابزارهای Docker زنده، و tooling طبقه‌بندی می‌کند، سپس فرمان‌های typecheck، lint، و guard متناظر را اجرا می‌کند. آزمون‌های Vitest را اجرا نمی‌کند؛ برای اثبات آزمون، `pnpm test:changed` یا `pnpm test ` صریح را فراخوانی کنید. افزایش نسخه فقط با فراداده release بررسی‌های هدفمند version/config/root-dependency را اجرا می‌کند، با محافظی که تغییرات package بیرون از فیلد نسخه سطح بالا را رد می‌کند. - - ویرایش‌های harness زنده Docker ACP بررسی‌های متمرکز اجرا می‌کنند: نحو shell برای اسکریپت‌های احراز هویت زنده Docker و dry-run زمان‌بند زنده Docker. تغییرات `package.json` فقط زمانی شامل می‌شوند که diff محدود به `scripts["test:docker:live-*"]` باشد؛ ویرایش‌های dependency، export، version، و سایر سطوح package همچنان از guardهای گسترده‌تر استفاده می‌کنند. - - آزمون‌های واحد سبک از نظر import از agents، commands، plugins، کمک‌کننده‌های auto-reply، `plugin-sdk`، و نواحی ابزار خالص مشابه از lane `unit-fast` عبور می‌کنند، که `test/setup-openclaw-runtime.ts` را رد می‌کند؛ فایل‌های stateful/runtime-heavy روی laneهای موجود می‌مانند. - - فایل‌های سورس کمک‌کننده منتخب `plugin-sdk` و `commands` نیز اجراهای changed-mode را به آزمون‌های خواهر صریح در همان laneهای سبک نگاشت می‌کنند، بنابراین ویرایش‌های کمک‌کننده از اجرای دوباره مجموعه کامل سنگین برای آن دایرکتوری پرهیز می‌کنند. - - `auto-reply` bucketهای اختصاصی برای کمک‌کننده‌های core سطح بالا، آزمون‌های یکپارچه‌سازی سطح بالای `reply.*`، و زیردرخت `src/auto-reply/reply/**` دارد. CI زیردرخت reply را بیشتر به shardهای agent-runner، dispatch، و commands/state-routing تقسیم می‌کند تا یک bucket سنگین از نظر import کل دنباله Node را در اختیار نگیرد. - - CI عادی PR/main عمدا sweep دسته‌ای extension و shard فقط مخصوص release به نام `agentic-plugins` را رد می‌کند. Full Release Validation گردش‌کار فرزند جداگانه `Plugin Prerelease` را برای آن مجموعه‌های سنگین از نظر Plugin/extension روی نامزدهای release dispatch می‌کند. + - `pnpm test` بدون هدف، به‌جای یک فرایند عظیم native root-project، دوازده پیکربندی shard کوچک‌تر (`core-unit-fast`، `core-unit-src`، `core-unit-security`، `core-unit-ui`، `core-unit-support`، `core-support-boundary`، `core-contracts`، `core-bundled`، `core-runtime`، `agentic`، `auto-reply`، `extensions`) را اجرا می‌کند. این کار peak RSS را روی ماشین‌های پربار کاهش می‌دهد و از گرسنه ماندن مجموعه‌های نامرتبط توسط کار auto-reply/extension جلوگیری می‌کند. + - `pnpm test --watch` همچنان از گراف پروژه native root در `vitest.config.ts` استفاده می‌کند، چون loop watch چند-shard عملی نیست. + - `pnpm test`، `pnpm test:watch`، و `pnpm test:perf:imports` هدف‌های صریح فایل/دایرکتوری را ابتدا از مسیر scoped laneها عبور می‌دهند، بنابراین `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` هزینه راه‌اندازی کامل root project را نمی‌پردازد. + - `pnpm test:changed` مسیرهای تغییرکرده git را به‌طور پیش‌فرض به laneهای scoped ارزان گسترش می‌دهد: ویرایش‌های مستقیم آزمون، فایل‌های هم‌جوار `*.test.ts`، نگاشت‌های صریح source، و وابسته‌های محلی import-graph. ویرایش‌های config/setup/package آزمون‌ها را به‌صورت گسترده اجرا نمی‌کنند مگر اینکه صریحاً از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. + - `pnpm check:changed` دروازه عادی بررسی هوشمند محلی برای کارهای محدود است. این دستور diff را به core، آزمون‌های core، extensions، آزمون‌های extension، apps، docs، metadata انتشار، ابزارهای live Docker، و tooling طبقه‌بندی می‌کند، سپس فرمان‌های typecheck، lint، و guard متناظر را اجرا می‌کند. آزمون‌های Vitest را اجرا نمی‌کند؛ برای اثبات آزمون، `pnpm test:changed` یا `pnpm test ` صریح را فراخوانی کنید. bumpهای نسخه فقط metadata انتشار، بررسی‌های هدفمند version/config/root-dependency را با guardی اجرا می‌کنند که تغییرات package خارج از فیلد نسخه سطح بالا را رد می‌کند. + - ویرایش‌های harness زنده Docker ACP بررسی‌های متمرکز اجرا می‌کنند: syntax shell برای اسکریپت‌های احراز هویت live Docker و dry-run scheduler زنده Docker. تغییرات `package.json` فقط وقتی شامل می‌شوند که diff به `scripts["test:docker:live-*"]` محدود باشد؛ ویرایش‌های dependency، export، version، و سایر package-surface همچنان از guardهای گسترده‌تر استفاده می‌کنند. + - آزمون‌های واحد import-light از agents، commands، plugins، helperهای auto-reply، `plugin-sdk`، و نواحی utility خالص مشابه از مسیر lane `unit-fast` عبور می‌کنند، که `test/setup-openclaw-runtime.ts` را رد می‌کند؛ فایل‌های stateful/runtime-heavy روی laneهای موجود باقی می‌مانند. + - برخی فایل‌های source helper در `plugin-sdk` و `commands` نیز اجراهای changed-mode را به آزمون‌های هم‌جوار صریح در همان laneهای سبک نگاشت می‌کنند، تا ویرایش‌های helper از اجرای دوباره کل مجموعه سنگین برای آن دایرکتوری پرهیز کنند. + - `auto-reply` bucketهای اختصاصی برای helperهای core سطح بالا، آزمون‌های یکپارچه‌سازی سطح بالای `reply.*`، و زیردرخت `src/auto-reply/reply/**` دارد. CI زیردرخت reply را بیشتر به shardهای agent-runner، dispatch، و commands/state-routing تقسیم می‌کند تا یک bucket با import سنگین مالک کل tail مربوط به Node نشود. + - CI عادی PR/main عمداً sweep دسته‌ای extension و shard فقط‌انتشار `agentic-plugins` را رد می‌کند. Full Release Validation workflow فرزند جداگانه `Plugin Prerelease` را برای آن مجموعه‌های سنگین plugin/extension روی release candidateها dispatch می‌کند. - + - - وقتی ورودی‌های کشف message-tool یا زمینه runtime مربوط به compaction را تغییر می‌دهید، + - وقتی ورودی‌های کشف message-tool یا context runtime مربوط به Compaction را تغییر می‌دهید، هر دو سطح پوشش را نگه دارید. - - رگرسیون‌های کمک‌کننده متمرکز برای مرزهای مسیریابی و نرمال‌سازی خالص اضافه کنید. - - مجموعه‌های یکپارچه‌سازی runner تعبیه‌شده را سالم نگه دارید: - `src/agents/pi-embedded-runner/compact.hooks.test.ts`, + - برای مرزهای routing و normalization خالص، رگرسیون‌های helper متمرکز اضافه کنید. + - مجموعه‌های یکپارچه‌سازی embedded runner را سالم نگه دارید: + `src/agents/pi-embedded-runner/compact.hooks.test.ts`، `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`، و `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - این مجموعه‌ها تأیید می‌کنند که شناسه‌های دامنه‌دار و رفتار compaction همچنان - از مسیرهای واقعی `run.ts` / `compact.ts` عبور می‌کنند؛ آزمون‌های فقط کمک‌کننده - جایگزین کافی برای آن مسیرهای یکپارچه‌سازی نیستند. + - این مجموعه‌ها بررسی می‌کنند که شناسه‌های scoped و رفتار Compaction همچنان + از مسیرهای واقعی `run.ts` / `compact.ts` عبور می‌کنند؛ آزمون‌های + فقط-helper جایگزین کافی برای آن مسیرهای یکپارچه‌سازی نیستند. - + - پیکربندی پایه Vitest به‌طور پیش‌فرض `threads` است. - پیکربندی مشترک Vitest مقدار `isolate: false` را ثابت می‌کند و از runner - غیرایزوله در پروژه‌های ریشه، e2e، و پیکربندی‌های live استفاده می‌کند. - - lane ریشه UI راه‌اندازی و optimizer مربوط به `jsdom` خود را نگه می‌دارد، اما آن هم روی + غیرایزوله در پروژه‌های root، e2e، و configهای live استفاده می‌کند. + - lane ریشه UI setup و optimizer مربوط به `jsdom` خود را نگه می‌دارد، اما آن هم روی runner مشترک غیرایزوله اجرا می‌شود. - هر shard مربوط به `pnpm test` همان پیش‌فرض‌های `threads` + `isolate: false` را از پیکربندی مشترک Vitest به ارث می‌برد. - - `scripts/run-vitest.mjs` به‌طور پیش‌فرض `--no-maglev` را برای فرآیندهای فرزند Node - در Vitest اضافه می‌کند تا churn کامپایل V8 در اجراهای بزرگ محلی کاهش یابد. - برای مقایسه با رفتار استاندارد V8، `OPENCLAW_VITEST_ENABLE_MAGLEV=1` را تنظیم کنید. + - `scripts/run-vitest.mjs` به‌طور پیش‌فرض برای فرایندهای فرزند Node مربوط به Vitest + مقدار `--no-maglev` را اضافه می‌کند تا churn کامپایل V8 در اجراهای محلی بزرگ کاهش یابد. + برای مقایسه با رفتار stock V8 مقدار `OPENCLAW_VITEST_ENABLE_MAGLEV=1` را تنظیم کنید. - + - `pnpm changed:lanes` نشان می‌دهد یک diff کدام laneهای معماری را فعال می‌کند. - - hook پیش از commit فقط قالب‌بندی انجام می‌دهد. فایل‌های قالب‌بندی‌شده را دوباره stage می‌کند و + - hook پیش از commit فقط formatting انجام می‌دهد. فایل‌های formatشده را دوباره stage می‌کند و lint، typecheck، یا آزمون‌ها را اجرا نمی‌کند. - - وقتی به گیت بررسی هوشمند محلی نیاز دارید، پیش از handoff یا push، `pnpm check:changed` - را صراحتا اجرا کنید. - - `pnpm test:changed` به‌طور پیش‌فرض از laneهای ارزان دامنه‌دار عبور می‌کند. فقط وقتی agent - تصمیم می‌گیرد یک ویرایش harness، config، package، یا contract واقعا به پوشش گسترده‌تر - Vitest نیاز دارد، از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید. - - `pnpm test:max` و `pnpm test:changed:max` همان رفتار مسیریابی را نگه می‌دارند، + - وقتی به دروازه بررسی هوشمند محلی نیاز دارید، پیش از handoff یا push، + `pnpm check:changed` را صریحاً اجرا کنید. + - `pnpm test:changed` به‌طور پیش‌فرض از مسیر laneهای scoped ارزان عبور می‌کند. فقط وقتی از + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید که agent + تصمیم بگیرد ویرایش harness، config، package، یا contract واقعاً به پوشش گسترده‌تر + Vitest نیاز دارد. + - `pnpm test:max` و `pnpm test:changed:max` همان رفتار routing را نگه می‌دارند، فقط با سقف worker بالاتر. - - مقیاس‌گذاری خودکار worker محلی عمدا محافظه‌کارانه است و وقتی میانگین بار میزبان - از قبل بالا باشد عقب‌نشینی می‌کند، بنابراین چند اجرای همزمان Vitest به‌طور پیش‌فرض - آسیب کمتری می‌زنند. + - auto-scaling محلی worker عمداً محافظه‌کار است و وقتی میانگین load میزبان از قبل بالا باشد + عقب‌نشینی می‌کند، بنابراین چند اجرای هم‌زمان Vitest به‌طور پیش‌فرض آسیب کمتری می‌زنند. - پیکربندی پایه Vitest پروژه‌ها/فایل‌های config را به‌عنوان `forceRerunTriggers` علامت‌گذاری می‌کند تا rerunهای changed-mode وقتی wiring آزمون - تغییر می‌کند درست بمانند. - - پیکربندی، `OPENCLAW_VITEST_FS_MODULE_CACHE` را روی میزبان‌های پشتیبانی‌شده فعال نگه می‌دارد؛ - اگر برای profiling مستقیم یک مکان cache صریح می‌خواهید، `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` را تنظیم کنید. + تغییر می‌کند صحیح بمانند. + - config مقدار `OPENCLAW_VITEST_FS_MODULE_CACHE` را روی میزبان‌های پشتیبانی‌شده فعال نگه می‌دارد؛ + اگر یک محل cache صریح برای profiling مستقیم می‌خواهید، `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` را تنظیم کنید. - + - - `pnpm test:perf:imports` گزارش مدت‌زمان import در Vitest به‌همراه - خروجی breakdown مربوط به import را فعال می‌کند. - - `pnpm test:perf:imports:changed` همان نمای profiling را به فایل‌های تغییریافته از - `origin/main` محدود می‌کند. - - داده‌های زمان‌بندی shard در `.artifacts/vitest-shard-timings.json` نوشته می‌شوند. - اجراهای کل config از مسیر config به‌عنوان کلید استفاده می‌کنند؛ shardهای CI با include-pattern - نام shard را اضافه می‌کنند تا shardهای فیلترشده جداگانه قابل رهگیری باشند. - - وقتی یک آزمون داغ همچنان بیشتر زمان خود را در importهای راه‌اندازی صرف می‌کند، - وابستگی‌های سنگین را پشت یک درز محلی محدود `*.runtime.ts` نگه دارید و - آن درز را مستقیما mock کنید، به‌جای اینکه کمک‌کننده‌های runtime را فقط برای - عبور دادن از `vi.mock(...)` به‌صورت deep-import وارد کنید. - - `pnpm test:perf:changed:bench -- --ref ` مسیر‌دهی‌شده - `test:changed` را با مسیر native پروژه ریشه برای آن diff commitشده مقایسه می‌کند - و زمان wall به‌همراه حداکثر RSS در macOS را چاپ می‌کند. - - `pnpm test:perf:changed:bench -- --worktree` درخت dirty فعلی را با مسیریابی - فهرست فایل‌های تغییریافته از طریق `scripts/test-projects.mjs` و پیکربندی ریشه Vitest + - `pnpm test:perf:imports` گزارش duration مربوط به import در Vitest به‌همراه + خروجی import-breakdown را فعال می‌کند. + - `pnpm test:perf:imports:changed` همان نمای profiling را به فایل‌های تغییرکرده + از زمان `origin/main` محدود می‌کند. + - داده‌های زمان‌بندی shard در `.artifacts/vitest-shard-timings.json` نوشته می‌شود. + اجراهای whole-config از مسیر config به‌عنوان key استفاده می‌کنند؛ shardهای CI مبتنی بر include-pattern + نام shard را اضافه می‌کنند تا shardهای فیلترشده جداگانه قابل ردیابی باشند. + - وقتی یک آزمون داغ همچنان بیشتر زمان خود را در importهای startup می‌گذراند، + dependencyهای سنگین را پشت یک seam محلی محدود `*.runtime.ts` نگه دارید و + همان seam را مستقیماً mock کنید، به‌جای اینکه runtime helperها را فقط برای عبور دادن به + `vi.mock(...)` به‌صورت deep import وارد کنید. + - `pnpm test:perf:changed:bench -- --ref ` مسیر routed + `test:changed` را با مسیر native root-project برای آن diff commitشده مقایسه می‌کند + و wall time به‌همراه max RSS در macOS را چاپ می‌کند. + - `pnpm test:perf:changed:bench -- --worktree` درخت dirty فعلی را با عبور دادن + فهرست فایل‌های تغییرکرده از مسیر `scripts/test-projects.mjs` و پیکربندی ریشه Vitest benchmark می‌کند. - - `pnpm test:perf:profile:main` یک پروفایل CPU برای thread اصلی جهت - سربار راه‌اندازی و transform در Vitest/Vite می‌نویسد. - - `pnpm test:perf:profile:runner` پروفایل‌های CPU+heap مربوط به runner را برای - مجموعه واحد با موازی‌سازی فایل غیرفعال می‌نویسد. + - `pnpm test:perf:profile:main` یک profile CPU مربوط به main-thread برای + سربار startup و transform در Vitest/Vite می‌نویسد. + - `pnpm test:perf:profile:runner` profileهای CPU+heap مربوط به runner را برای + مجموعه واحد با file parallelism غیرفعال می‌نویسد. @@ -433,317 +508,318 @@ pnpm openclaw qa credentials remove --credential-id - فرمان: `pnpm test:stability:gateway` - پیکربندی: `vitest.gateway.config.ts`، اجبار به یک worker - دامنه: - - یک Gateway واقعی loopback را با diagnostics فعال به‌صورت پیش‌فرض راه‌اندازی می‌کند - - churn پیام gateway مصنوعی، memory، و payload بزرگ را از مسیر رویداد diagnostic عبور می‌دهد - - `diagnostics.stability` را از طریق Gateway WS RPC پرس‌وجو می‌کند - - کمک‌کننده‌های persistence بسته پایداری diagnostic را پوشش می‌دهد - - assert می‌کند recorder محدود می‌ماند، نمونه‌های RSS مصنوعی زیر بودجه فشار می‌مانند، و عمق صف‌های هر نشست دوباره به صفر تخلیه می‌شود + - یک Gateway واقعی روی local loopback را با diagnostics فعال به‌طور پیش‌فرض شروع می‌کند + - churn مصنوعی پیام، حافظه، و payload بزرگ Gateway را از مسیر رویداد diagnostic عبور می‌دهد + - `diagnostics.stability` را از طریق Gateway WS RPC query می‌کند + - helperهای persistence مربوط به bundle پایداری diagnostic را پوشش می‌دهد + - assert می‌کند که recorder محدود می‌ماند، نمونه‌های مصنوعی RSS زیر بودجه فشار باقی می‌مانند، و عمق صف‌های per-session دوباره به صفر تخلیه می‌شود - انتظارات: - - برای CI امن و بدون نیاز به کلید + - برای CI امن و بدون نیاز به کلید است - lane محدود برای پیگیری رگرسیون پایداری، نه جایگزینی برای مجموعه کامل Gateway -### E2E (smoke Gateway) +### E2E (gateway smoke) -- فرمان: `pnpm test:e2e` +- دستور: `pnpm test:e2e` - پیکربندی: `vitest.e2e.config.ts` -- فایل‌ها: `src/**/*.e2e.test.ts`، `test/**/*.e2e.test.ts`، و آزمون‌های E2E مربوط به Pluginهای bundled زیر `extensions/` -- پیش‌فرض‌های runtime: - - از `threads` در Vitest با `isolate: false` استفاده می‌کند، مطابق با بقیه repo. - - از workerهای adaptive استفاده می‌کند (CI: تا 2، محلی: به‌طور پیش‌فرض 1). - - به‌طور پیش‌فرض در حالت silent اجرا می‌شود تا سربار I/O کنسول کاهش یابد. -- overrideهای مفید: - - `OPENCLAW_E2E_WORKERS=` برای اجبار تعداد workerها (با سقف 16). - - `OPENCLAW_E2E_VERBOSE=1` برای فعال‌سازی دوباره خروجی verbose کنسول. +- فایل‌ها: `src/**/*.e2e.test.ts`، `test/**/*.e2e.test.ts`، و آزمون‌های E2E مربوط به Pluginهای همراه در `extensions/` +- پیش‌فرض‌های زمان اجرا: + - از `threads` در Vitest با `isolate: false` استفاده می‌کند، مطابق با بقیه مخزن. + - از کارگرهای تطبیقی استفاده می‌کند (CI: حداکثر ۲، محلی: به‌طور پیش‌فرض ۱). + - به‌طور پیش‌فرض در حالت بی‌صدا اجرا می‌شود تا سربار I/O کنسول کاهش یابد. +- بازنویسی‌های مفید: + - `OPENCLAW_E2E_WORKERS=` برای اجبار تعداد کارگرها (با سقف ۱۶). + - `OPENCLAW_E2E_VERBOSE=1` برای فعال‌سازی دوباره خروجی مفصل کنسول. - دامنه: - - رفتار end-to-end چندنمونه‌ای gateway - - سطوح WebSocket/HTTP، pairing نود، و networking سنگین‌تر + - رفتار سرتاسری Gateway چندنمونه‌ای + - سطوح WebSocket/HTTP، جفت‌سازی Node، و شبکه‌سازی سنگین‌تر - انتظارات: - - در CI اجرا می‌شود (وقتی در pipeline فعال باشد) - - به کلید واقعی نیاز ندارد + - در CI اجرا می‌شود (وقتی در خط لوله فعال باشد) + - به کلیدهای واقعی نیاز ندارد - قطعات متحرک بیشتری نسبت به آزمون‌های واحد دارد (می‌تواند کندتر باشد) -### E2E: smoke بک‌اند OpenShell +### E2E: اسموک بک‌اند OpenShell -- فرمان: `pnpm test:e2e:openshell` +- دستور: `pnpm test:e2e:openshell` - فایل: `extensions/openshell/src/backend.e2e.test.ts` - دامنه: - - یک Gateway ایزوله‌شده OpenShell را از طریق Docker روی میزبان راه‌اندازی می‌کند - - یک sandbox از یک Dockerfile محلی موقت ایجاد می‌کند - - backend مربوط به OpenShell در OpenClaw را از مسیر واقعی `sandbox ssh-config` + اجرای SSH آزمایش می‌کند - - رفتار فایل‌سیستم remote-canonical را از طریق پل fs در sandbox تأیید می‌کند + - یک Gateway ایزوله OpenShell را از طریق Docker روی میزبان راه‌اندازی می‌کند + - از یک Dockerfile محلی موقت یک sandbox می‌سازد + - بک‌اند OpenShell در OpenClaw را از طریق `sandbox ssh-config` واقعی + اجرای SSH تمرین می‌دهد + - رفتار سیستم فایلِ canonical راه‌دور را از طریق پل sandbox fs بررسی می‌کند - انتظارات: - - فقط با انتخاب صریح فعال می‌شود؛ بخشی از اجرای پیش‌فرض `pnpm test:e2e` نیست - - به یک CLI محلی `openshell` به‌همراه daemon فعال Docker نیاز دارد - - از `HOME` / `XDG_CONFIG_HOME` ایزوله استفاده می‌کند، سپس Gateway آزمایشی و sandbox را حذف می‌کند + - فقط با انتخاب صریح؛ بخشی از اجرای پیش‌فرض `pnpm test:e2e` نیست + - به CLI محلی `openshell` به‌همراه یک Docker daemon فعال نیاز دارد + - از `HOME` / `XDG_CONFIG_HOME` ایزوله استفاده می‌کند، سپس Gateway و sandbox آزمون را نابود می‌کند - بازنویسی‌های مفید: - `OPENCLAW_E2E_OPENSHELL=1` برای فعال‌کردن آزمون هنگام اجرای دستی مجموعه e2e گسترده‌تر - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` برای اشاره به binary یا wrapper script غیرپیش‌فرض CLI + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` برای اشاره به باینری CLI یا اسکریپت wrapper غیرپیش‌فرض ### زنده (ارائه‌دهندگان واقعی + مدل‌های واقعی) -- فرمان: `pnpm test:live` +- دستور: `pnpm test:live` - پیکربندی: `vitest.live.config.ts` -- فایل‌ها: `src/**/*.live.test.ts`، `test/**/*.live.test.ts`، و آزمون‌های زنده Plugin‌های بسته‌بندی‌شده زیر `extensions/` +- فایل‌ها: `src/**/*.live.test.ts`، `test/**/*.live.test.ts`، و آزمون‌های زنده Pluginهای همراه در `extensions/` - پیش‌فرض: با `pnpm test:live` **فعال** است (`OPENCLAW_LIVE_TEST=1` را تنظیم می‌کند) - دامنه: - «آیا این ارائه‌دهنده/مدل واقعاً _امروز_ با اعتبارنامه‌های واقعی کار می‌کند؟» - - تغییرات قالب ارائه‌دهنده، ویژگی‌های خاص فراخوانی ابزار، مشکلات احراز هویت، و رفتار محدودیت نرخ را پیدا می‌کند + - تغییرات قالب ارائه‌دهنده، ویژگی‌های خاص فراخوانی ابزار، مشکلات احراز هویت، و رفتار محدودیت نرخ را می‌گیرد - انتظارات: - بنا به طراحی برای CI پایدار نیست (شبکه‌های واقعی، سیاست‌های واقعی ارائه‌دهنده، سهمیه‌ها، قطعی‌ها) - هزینه دارد / از محدودیت‌های نرخ استفاده می‌کند - اجرای زیرمجموعه‌های محدودشده را به‌جای «همه‌چیز» ترجیح دهید - اجراهای زنده `~/.profile` را source می‌کنند تا کلیدهای API جاافتاده را بردارند. -- به‌طور پیش‌فرض، اجراهای زنده همچنان `HOME` را ایزوله می‌کنند و مواد config/auth را در یک خانه آزمایشی موقت کپی می‌کنند تا fixtureهای واحد نتوانند `~/.openclaw` واقعی شما را تغییر دهند. -- `OPENCLAW_LIVE_USE_REAL_HOME=1` را فقط زمانی تنظیم کنید که عمداً نیاز دارید آزمون‌های زنده از دایرکتوری خانه واقعی شما استفاده کنند. -- `pnpm test:live` اکنون به‌طور پیش‌فرض روی حالت کم‌صداتری قرار دارد: خروجی پیشرفت `[live] ...` را نگه می‌دارد، اما اعلان اضافی `~/.profile` را سرکوب می‌کند و logهای راه‌اندازی Gateway/گفت‌وگوی Bonjour را بی‌صدا می‌کند. اگر می‌خواهید logهای کامل راه‌اندازی برگردند، `OPENCLAW_LIVE_TEST_QUIET=0` را تنظیم کنید. -- چرخش کلید API (مختص ارائه‌دهنده): `*_API_KEYS` را با قالب کاما/نقطه‌ویرگول یا `*_API_KEY_1`، `*_API_KEY_2` تنظیم کنید (برای مثال `OPENAI_API_KEYS`، `ANTHROPIC_API_KEYS`، `GEMINI_API_KEYS`) یا بازنویسی مخصوص live را از طریق `OPENCLAW_LIVE_*_KEY` انجام دهید؛ آزمون‌ها در پاسخ‌های محدودیت نرخ دوباره تلاش می‌کنند. +- به‌طور پیش‌فرض، اجراهای زنده همچنان `HOME` را ایزوله می‌کنند و مواد پیکربندی/احراز هویت را در یک خانه آزمون موقت کپی می‌کنند تا fixtureهای واحد نتوانند `~/.openclaw` واقعی شما را تغییر دهند. +- فقط وقتی `OPENCLAW_LIVE_USE_REAL_HOME=1` را تنظیم کنید که عمداً نیاز دارید آزمون‌های زنده از دایرکتوری home واقعی شما استفاده کنند. +- `pnpm test:live` اکنون به‌طور پیش‌فرض از حالت کم‌سروصداتر استفاده می‌کند: خروجی پیشرفت `[live] ...` را نگه می‌دارد، اما اعلان اضافی `~/.profile` را سرکوب می‌کند و لاگ‌های bootstrap مربوط به Gateway/گفت‌وگوی Bonjour را بی‌صدا می‌کند. اگر می‌خواهید لاگ‌های کامل راه‌اندازی برگردند، `OPENCLAW_LIVE_TEST_QUIET=0` را تنظیم کنید. +- چرخش کلید API (ویژه هر ارائه‌دهنده): `*_API_KEYS` را با قالب کاما/نقطه‌ویرگول یا `*_API_KEY_1`، `*_API_KEY_2` تنظیم کنید (برای مثال `OPENAI_API_KEYS`، `ANTHROPIC_API_KEYS`، `GEMINI_API_KEYS`) یا بازنویسی مختص زنده را از طریق `OPENCLAW_LIVE_*_KEY` تنظیم کنید؛ آزمون‌ها هنگام پاسخ‌های محدودیت نرخ دوباره تلاش می‌کنند. - خروجی پیشرفت/Heartbeat: - - مجموعه‌های زنده اکنون خط‌های پیشرفت را به stderr می‌فرستند تا فراخوانی‌های طولانی ارائه‌دهنده حتی وقتی گرفتن خروجی کنسول Vitest کم‌صداست، به‌صورت قابل مشاهده فعال باشند. - - `vitest.live.config.ts` رهگیری کنسول Vitest را غیرفعال می‌کند تا خط‌های پیشرفت ارائه‌دهنده/Gateway فوراً هنگام اجراهای زنده stream شوند. + - مجموعه‌های زنده اکنون خطوط پیشرفت را به stderr منتشر می‌کنند تا فراخوانی‌های طولانی ارائه‌دهنده حتی وقتی capture کنسول Vitest کم‌صداست، به‌صورت قابل مشاهده فعال باشند. + - `vitest.live.config.ts` رهگیری کنسول Vitest را غیرفعال می‌کند تا خطوط پیشرفت ارائه‌دهنده/Gateway بلافاصله در طول اجراهای زنده stream شوند. - Heartbeatهای مدل مستقیم را با `OPENCLAW_LIVE_HEARTBEAT_MS` تنظیم کنید. - Heartbeatهای Gateway/probe را با `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` تنظیم کنید. -## کدام مجموعه را باید اجرا کنم؟ +## کدام مجموعه را اجرا کنم؟ از این جدول تصمیم استفاده کنید: -- ویرایش منطق/آزمون‌ها: `pnpm test` را اجرا کنید (و اگر تغییر زیادی داده‌اید `pnpm test:coverage` را هم اجرا کنید) -- دست‌زدن به شبکه‌سازی Gateway / پروتکل WS / pairing: `pnpm test:e2e` را اضافه کنید -- اشکال‌زدایی «bot من از کار افتاده» / خطاهای مختص ارائه‌دهنده / فراخوانی ابزار: یک `pnpm test:live` محدودشده اجرا کنید +- ویرایش منطق/آزمون‌ها: `pnpm test` را اجرا کنید (و اگر چیزهای زیادی تغییر داده‌اید، `pnpm test:coverage`) +- لمس شبکه‌سازی Gateway / پروتکل WS / جفت‌سازی: `pnpm test:e2e` را اضافه کنید +- اشکال‌زدایی «بات من از کار افتاده است» / خرابی‌های ویژه ارائه‌دهنده / فراخوانی ابزار: یک `pnpm test:live` محدودشده را اجرا کنید -## آزمون‌های زنده (تماس‌گیرنده با شبکه) +## آزمون‌های زنده (دارای تماس شبکه) -برای ماتریس مدل زنده، smokeهای backend در CLI، smokeهای ACP، harness مربوط به app-server در Codex، و همه آزمون‌های زنده ارائه‌دهنده رسانه (Deepgram، BytePlus، ComfyUI، تصویر، -موسیقی، ویدئو، media harness) — به‌همراه مدیریت اعتبارنامه برای اجراهای زنده — به -[آزمودن مجموعه‌های زنده](/fa/help/testing-live) مراجعه کنید. برای checklist اختصاصی به‌روزرسانی و اعتبارسنجی -Plugin، به -[آزمودن به‌روزرسانی‌ها و Plugin‌ها](/fa/help/testing-updates-plugins) مراجعه کنید. +برای ماتریس مدل زنده، اسموک‌های بک‌اند CLI، اسموک‌های ACP، harness سرور برنامه Codex، +و همه آزمون‌های زنده ارائه‌دهنده رسانه (Deepgram، BytePlus، ComfyUI، تصویر، +موسیقی، ویدئو، harness رسانه) — به‌علاوه مدیریت اعتبارنامه برای اجراهای زنده — ببینید +[آزمون مجموعه‌های زنده](/fa/help/testing-live). برای چک‌لیست اختصاصی به‌روزرسانی و +اعتبارسنجی Plugin، ببینید +[آزمون به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins). ## اجراکننده‌های Docker (بررسی‌های اختیاری «در Linux کار می‌کند») این اجراکننده‌های Docker به دو دسته تقسیم می‌شوند: -- اجراکننده‌های مدل زنده: `test:docker:live-models` و `test:docker:live-gateway` فقط فایل زنده profile-key متناظر خود را داخل تصویر Docker ریپو اجرا می‌کنند (`src/agents/models.profiles.live.test.ts` و `src/gateway/gateway-models.profiles.live.test.ts`) و دایرکتوری config محلی و workspace شما را mount می‌کنند (و اگر mount شده باشد `~/.profile` را source می‌کنند). entrypointهای محلی متناظر `test:live:models-profiles` و `test:live:gateway-profiles` هستند. -- اجراکننده‌های زنده Docker به‌طور پیش‌فرض یک سقف smoke کوچک‌تر دارند تا sweep کامل Docker عملی بماند: +- اجراکننده‌های مدل زنده: `test:docker:live-models` و `test:docker:live-gateway` فقط فایل زنده منطبق با کلید پروفایل خود را داخل image Docker مخزن اجرا می‌کنند (`src/agents/models.profiles.live.test.ts` و `src/gateway/gateway-models.profiles.live.test.ts`) و دایرکتوری پیکربندی محلی و workspace شما را mount می‌کنند (و اگر `~/.profile` mount شده باشد، آن را source می‌کنند). نقطه‌های ورود محلی منطبق `test:live:models-profiles` و `test:live:gateway-profiles` هستند. +- اجراکننده‌های زنده Docker به‌طور پیش‌فرض از سقف اسموک کوچک‌تری استفاده می‌کنند تا یک sweep کامل Docker عملی بماند: `test:docker:live-models` به‌طور پیش‌فرض `OPENCLAW_LIVE_MAX_MODELS=12` است، و `test:docker:live-gateway` به‌طور پیش‌فرض `OPENCLAW_LIVE_GATEWAY_SMOKE=1`، `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`، `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`، و - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` است. وقتی صراحتاً scan بزرگ‌تر و کامل‌تر می‌خواهید، آن env varها را بازنویسی کنید. -- `test:docker:all` تصویر Docker زنده را یک‌بار از طریق `test:docker:live-build` می‌سازد، OpenClaw را یک‌بار از طریق `scripts/package-openclaw-for-docker.mjs` به‌عنوان tarball مربوط به npm بسته‌بندی می‌کند، سپس دو تصویر `scripts/e2e/Dockerfile` را می‌سازد/دوباره استفاده می‌کند. تصویر bare فقط اجراکننده Node/Git برای laneهای نصب/به‌روزرسانی/وابستگی-Plugin است؛ آن laneها tarball ازپیش‌ساخته را mount می‌کنند. تصویر functional همان tarball را برای laneهای قابلیت built-app در `/app` نصب می‌کند. تعریف‌های laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند؛ منطق planner در `scripts/lib/docker-e2e-plan.mjs` قرار دارد؛ `scripts/test-docker-all.mjs` plan انتخاب‌شده را اجرا می‌کند. aggregate از یک زمان‌بند محلی وزن‌دار استفاده می‌کند: `OPENCLAW_DOCKER_ALL_PARALLELISM` slotهای process را کنترل می‌کند، درحالی‌که سقف‌های resource مانع می‌شوند laneهای سنگین زنده، npm-install، و چندسرویسی همگی با هم شروع شوند. اگر یک lane منفرد از سقف‌های فعال سنگین‌تر باشد، زمان‌بند همچنان می‌تواند وقتی pool خالی است آن را شروع کند و سپس تا وقتی ظرفیت دوباره در دسترس شود آن را تنها در حال اجرا نگه می‌دارد. پیش‌فرض‌ها 10 slot، `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`، `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`، و `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` هستند؛ `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` یا `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` را فقط وقتی تنظیم کنید که میزبان Docker ظرفیت بیشتری دارد. اجراکننده به‌طور پیش‌فرض یک preflight مربوط به Docker انجام می‌دهد، containerهای قدیمی OpenClaw E2E را حذف می‌کند، هر 30 ثانیه status چاپ می‌کند، زمان‌بندی‌های lane موفق را در `.artifacts/docker-tests/lane-timings.json` ذخیره می‌کند، و از آن زمان‌بندی‌ها استفاده می‌کند تا در اجراهای بعدی laneهای طولانی‌تر را زودتر شروع کند. از `OPENCLAW_DOCKER_ALL_DRY_RUN=1` برای چاپ manifest وزن‌دار lane بدون ساختن یا اجرای Docker استفاده کنید، یا از `node scripts/test-docker-all.mjs --plan-json` برای چاپ plan مربوط به CI برای laneهای انتخاب‌شده، نیازهای package/image، و اعتبارنامه‌ها استفاده کنید. -- `Package Acceptance` gate بومی GitHub برای package است که می‌پرسد «آیا این tarball قابل نصب به‌عنوان یک محصول کار می‌کند؟» یک package نامزد را از `source=npm`، `source=ref`، `source=url`، یا `source=artifact` resolve می‌کند، آن را با نام `package-under-test` آپلود می‌کند، سپس laneهای Docker E2E قابل استفاده مجدد را در برابر همان tarball دقیق اجرا می‌کند، نه اینکه ref انتخاب‌شده را دوباره بسته‌بندی کند. Profileها بر اساس گستره مرتب شده‌اند: `smoke`، `package`، `product`، و `full`. برای قرارداد package/update/Plugin، ماتریس survivor مربوط به published-upgrade، پیش‌فرض‌های release، و triage خطا به [آزمودن به‌روزرسانی‌ها و Plugin‌ها](/fa/help/testing-updates-plugins) مراجعه کنید. -- بررسی‌های build و release پس از tsdown، `scripts/check-cli-bootstrap-imports.mjs` را اجرا می‌کنند. guard گراف ساخته‌شده static را از `dist/entry.js` و `dist/cli/run-main.js` پیمایش می‌کند و اگر startup پیش از dispatch وابستگی‌های package مانند Commander، prompt UI، undici، یا logging را پیش از command dispatch import کند، fail می‌شود؛ همچنین chunk اجرای Gateway بسته‌بندی‌شده را زیر بودجه نگه می‌دارد و importهای static مسیرهای cold شناخته‌شده Gateway را رد می‌کند. smoke مربوط به CLI بسته‌بندی‌شده همچنین root help، onboard help، doctor help، status، config schema، و یک فرمان model-list را پوشش می‌دهد. -- سازگاری legacy در Package Acceptance تا `2026.4.25` سقف دارد (`2026.4.25-beta.*` هم شامل می‌شود). تا آن cutoff، harness فقط شکاف‌های metadata مربوط به packageهای منتشرشده را تحمل می‌کند: entryهای خصوصی QA inventory حذف‌شده، `gateway install --wrapper` جاافتاده، فایل‌های patch جاافتاده در git fixture مشتق‌شده از tarball، `update.channel` پایدارسازی‌نشده، مکان‌های legacy رکورد نصب Plugin، پایدارسازی جاافتاده رکورد نصب marketplace، و مهاجرت metadata پیکربندی هنگام `plugins update`. برای packageهای بعد از `2026.4.25`، آن مسیرها خطاهای strict هستند. -- اجراکننده‌های smoke در container: `test:docker:openwebui`، `test:docker:onboard`، `test:docker:npm-onboard-channel-agent`، `test:docker:update-channel-switch`، `test:docker:upgrade-survivor`، `test:docker:published-upgrade-survivor`، `test:docker:session-runtime-context`، `test:docker:agents-delete-shared-workspace`، `test:docker:gateway-network`، `test:docker:browser-cdp-snapshot`، `test:docker:mcp-channels`، `test:docker:pi-bundle-mcp-tools`، `test:docker:cron-mcp-cleanup`، `test:docker:plugins`، `test:docker:plugin-update`، `test:docker:plugin-lifecycle-matrix`، و `test:docker:config-reload` یک یا چند container واقعی را boot می‌کنند و مسیرهای integration سطح‌بالاتر را تأیید می‌کنند. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` است. وقتی صراحتاً اسکن جامع بزرگ‌تر را می‌خواهید، آن متغیرهای env را بازنویسی کنید. +- `test:docker:all` تصویر Docker زنده را یک‌بار از طریق `test:docker:live-build` می‌سازد، OpenClaw را یک‌بار از طریق `scripts/package-openclaw-for-docker.mjs` به‌صورت npm tarball بسته‌بندی می‌کند، سپس دو image مبتنی بر `scripts/e2e/Dockerfile` را می‌سازد/دوباره استفاده می‌کند. image ساده فقط اجراکننده Node/Git برای مسیرهای install/update/plugin-dependency است؛ آن مسیرها tarball از پیش ساخته‌شده را mount می‌کنند. image عملکردی همان tarball را برای مسیرهای عملکرد برنامه ساخته‌شده در `/app` نصب می‌کند. تعریف مسیرهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارد؛ منطق planner در `scripts/lib/docker-e2e-plan.mjs` قرار دارد؛ `scripts/test-docker-all.mjs` طرح انتخاب‌شده را اجرا می‌کند. تجمیع‌کننده از یک زمان‌بند محلی وزن‌دار استفاده می‌کند: `OPENCLAW_DOCKER_ALL_PARALLELISM` جایگاه‌های پردازه را کنترل می‌کند، در حالی که سقف‌های منبع مانع می‌شوند مسیرهای سنگین زنده، نصب npm، و چندسرویسی همگی هم‌زمان شروع شوند. اگر یک مسیر واحد از سقف‌های فعال سنگین‌تر باشد، زمان‌بند همچنان می‌تواند وقتی pool خالی است آن را شروع کند و سپس آن را تنها در حال اجرا نگه می‌دارد تا ظرفیت دوباره در دسترس شود. پیش‌فرض‌ها ۱۰ جایگاه، `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`، `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`، و `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` هستند؛ فقط وقتی میزبان Docker فضای بیشتری دارد، `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` یا `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` را تنظیم کنید. اجراکننده به‌طور پیش‌فرض preflight Docker را انجام می‌دهد، کانتینرهای E2E کهنه OpenClaw را حذف می‌کند، هر ۳۰ ثانیه وضعیت را چاپ می‌کند، زمان‌بندی‌های مسیر موفق را در `.artifacts/docker-tests/lane-timings.json` ذخیره می‌کند، و از آن زمان‌بندی‌ها برای شروع مسیرهای طولانی‌تر در اجراهای بعدی استفاده می‌کند. از `OPENCLAW_DOCKER_ALL_DRY_RUN=1` برای چاپ manifest مسیر وزن‌دار بدون ساخت یا اجرای Docker استفاده کنید، یا از `node scripts/test-docker-all.mjs --plan-json` برای چاپ طرح CI برای مسیرهای انتخاب‌شده، نیازهای package/image، و اعتبارنامه‌ها استفاده کنید. +- `Package Acceptance` دروازه بومی GitHub برای package است: «آیا این tarball قابل نصب به‌عنوان یک محصول کار می‌کند؟» یک package نامزد را از `source=npm`، `source=ref`، `source=url`، یا `source=artifact` resolve می‌کند، آن را به‌عنوان `package-under-test` بارگذاری می‌کند، سپس مسیرهای Docker E2E قابل استفاده مجدد را در برابر همان tarball دقیق اجرا می‌کند، به‌جای اینکه ref انتخاب‌شده را دوباره بسته‌بندی کند. پروفایل‌ها بر اساس گستردگی مرتب شده‌اند: `smoke`، `package`، `product`، و `full`. برای قرارداد package/update/plugin، ماتریس بازمانده ارتقای منتشرشده، پیش‌فرض‌های انتشار، و triage خرابی، ببینید [آزمون به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins). +- بررسی‌های build و انتشار بعد از tsdown، `scripts/check-cli-bootstrap-imports.mjs` را اجرا می‌کنند. این guard گراف ساخته‌شده ایستا را از `dist/entry.js` و `dist/cli/run-main.js` پیمایش می‌کند و اگر importهای راه‌اندازی پیش از dispatch وابستگی‌های package مانند Commander، UI پرامپت، undici، یا logging را قبل از dispatch فرمان وارد کنند، شکست می‌خورد؛ همچنین chunk اجرای Gateway همراه را زیر بودجه نگه می‌دارد و importهای ایستای مسیرهای سرد شناخته‌شده Gateway را رد می‌کند. اسموک CLI بسته‌بندی‌شده همچنین help ریشه، help onboarding، help doctor، status، schema پیکربندی، و یک فرمان فهرست مدل را پوشش می‌دهد. +- سازگاری legacy در Package Acceptance در `2026.4.25` سقف دارد (`2026.4.25-beta.*` هم شامل می‌شود). تا آن cutoff، harness فقط شکاف‌های metadata مربوط به packageهای shipped را تحمل می‌کند: ورودی‌های private QA inventory حذف‌شده، نبود `gateway install --wrapper`، نبود فایل‌های patch در fixture گیت مشتق‌شده از tarball، نبود `update.channel` پایدارشده، مکان‌های legacy رکورد نصب Plugin، نبود پایداری رکورد نصب marketplace، و مهاجرت metadata پیکربندی هنگام `plugins update`. برای packageهای بعد از `2026.4.25`، آن مسیرها خرابی سخت‌گیرانه هستند. +- اجراکننده‌های اسموک کانتینر: `test:docker:openwebui`، `test:docker:onboard`، `test:docker:npm-onboard-channel-agent`، `test:docker:update-channel-switch`، `test:docker:upgrade-survivor`، `test:docker:published-upgrade-survivor`، `test:docker:session-runtime-context`، `test:docker:agents-delete-shared-workspace`، `test:docker:gateway-network`، `test:docker:browser-cdp-snapshot`، `test:docker:mcp-channels`، `test:docker:pi-bundle-mcp-tools`، `test:docker:cron-mcp-cleanup`، `test:docker:plugins`، `test:docker:plugin-update`، `test:docker:plugin-lifecycle-matrix`، و `test:docker:config-reload` یک یا چند کانتینر واقعی را بوت می‌کنند و مسیرهای یکپارچه‌سازی سطح بالاتر را بررسی می‌کنند. -اجراکننده‌های Docker مدل زنده همچنین فقط خانه‌های auth مورد نیاز CLI را bind-mount می‌کنند (یا وقتی اجرا محدود نشده باشد، همه موارد پشتیبانی‌شده را)، سپس پیش از اجرا آن‌ها را در خانه container کپی می‌کنند تا OAuth مربوط به CLI خارجی بتواند tokenها را بدون تغییر دادن auth store میزبان refresh کند: +اجراکننده‌های Docker مدل زنده همچنین فقط خانه‌های احراز هویت CLI موردنیاز را bind-mount می‌کنند (یا وقتی اجرا محدود نشده باشد، همه خانه‌های پشتیبانی‌شده را)، سپس پیش از اجرا آن‌ها را در home کانتینر کپی می‌کنند تا OAuth مربوط به CLI خارجی بتواند tokenها را بدون تغییر دادن مخزن احراز هویت میزبان refresh کند: - مدل‌های مستقیم: `pnpm test:docker:live-models` (اسکریپت: `scripts/test-live-models-docker.sh`) -- دودآزمون اتصال ACP: `pnpm test:docker:live-acp-bind` (اسکریپت: `scripts/test-live-acp-bind-docker.sh`؛ به‌صورت پیش‌فرض Claude، Codex، و Gemini را پوشش می‌دهد، با پوشش سخت‌گیرانه Droid/OpenCode از طریق `pnpm test:docker:live-acp-bind:droid` و `pnpm test:docker:live-acp-bind:opencode`) -- دودآزمون backend CLI: `pnpm test:docker:live-cli-backend` (اسکریپت: `scripts/test-live-cli-backend-docker.sh`) -- دودآزمون harness سرور برنامه Codex: `pnpm test:docker:live-codex-harness` (اسکریپت: `scripts/test-live-codex-harness-docker.sh`) +- دودآزمون اتصال ACP: `pnpm test:docker:live-acp-bind` (اسکریپت: `scripts/test-live-acp-bind-docker.sh`؛ به‌طور پیش‌فرض Claude، Codex و Gemini را پوشش می‌دهد، با پوشش سخت‌گیرانه Droid/OpenCode از طریق `pnpm test:docker:live-acp-bind:droid` و `pnpm test:docker:live-acp-bind:opencode`) +- دودآزمون بک‌اند CLI: `pnpm test:docker:live-cli-backend` (اسکریپت: `scripts/test-live-cli-backend-docker.sh`) +- دودآزمون هارنس کارساز برنامه Codex: `pnpm test:docker:live-codex-harness` (اسکریپت: `scripts/test-live-codex-harness-docker.sh`) - Gateway + عامل توسعه: `pnpm test:docker:live-gateway` (اسکریپت: `scripts/test-live-gateway-models-docker.sh`) -- دودآزمون مشاهده‌پذیری: `pnpm qa:otel:smoke` یک مسیر خصوصی بررسی سورس در QA است. عمداً بخشی از مسیرهای انتشار Docker بسته نیست، چون tarball مربوط به npm، QA Lab را حذف می‌کند. +- دودآزمون مشاهده‌پذیری: `pnpm qa:otel:smoke` یک مسیر خصوصی QA برای checkout منبع است. این مورد عمداً بخشی از مسیرهای انتشار Docker بسته نیست، چون tarball مربوط به npm، QA Lab را حذف می‌کند. - دودآزمون زنده Open WebUI: `pnpm test:docker:openwebui` (اسکریپت: `scripts/e2e/openwebui-docker.sh`) -- ویزارد راه‌اندازی اولیه (TTY، قالب‌بندی کامل): `pnpm test:docker:onboard` (اسکریپت: `scripts/e2e/onboard-docker.sh`) -- دودآزمون راه‌اندازی اولیه/کانال/عامل tarball مربوط به Npm: `pnpm test:docker:npm-onboard-channel-agent` tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، OpenAI را از طریق راه‌اندازی اولیه env-ref به‌همراه Telegram به‌صورت پیش‌فرض پیکربندی می‌کند، doctor را اجرا می‌کند، و یک نوبت عامل OpenAI شبیه‌سازی‌شده را اجرا می‌کند. یک tarball از پیش ساخته‌شده را با `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` دوباره استفاده کنید، بازسازی میزبان را با `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` رد کنید، یا کانال را با `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` تغییر دهید. -- دودآزمون تغییر کانال به‌روزرسانی: `pnpm test:docker:update-channel-switch` tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، از بسته `stable` به git `dev` تغییر می‌دهد، کارکرد کانال ماندگارشده و Plugin پس از به‌روزرسانی را تأیید می‌کند، سپس دوباره به بسته `stable` برمی‌گردد و وضعیت به‌روزرسانی را بررسی می‌کند. -- دودآزمون بقا پس از ارتقا: `pnpm test:docker:upgrade-survivor` tarball بسته‌بندی‌شده OpenClaw را روی یک fixture کاربر قدیمی و کثیف با عامل‌ها، پیکربندی کانال، فهرست‌های مجاز Plugin، وضعیت کهنه وابستگی Plugin، و فایل‌های workspace/session موجود نصب می‌کند. به‌روزرسانی بسته به‌علاوه doctor غیرتعاملی را بدون کلیدهای ارائه‌دهنده زنده یا کانال اجرا می‌کند، سپس یک Gateway از نوع loopback را شروع می‌کند و حفظ config/state به‌علاوه بودجه‌های راه‌اندازی/وضعیت را بررسی می‌کند. -- دودآزمون منتشرشده بقا پس از ارتقا: `pnpm test:docker:published-upgrade-survivor` به‌صورت پیش‌فرض `openclaw@latest` را نصب می‌کند، فایل‌های واقع‌گرایانه کاربر موجود را seed می‌کند، آن baseline را با یک دستورالعمل پخته‌شده پیکربندی می‌کند، پیکربندی حاصل را اعتبارسنجی می‌کند، آن نصب منتشرشده را به tarball نامزد به‌روزرسانی می‌کند، doctor غیرتعاملی را اجرا می‌کند، `.artifacts/upgrade-survivor/summary.json` را می‌نویسد، سپس یک Gateway از نوع loopback را شروع می‌کند و intentهای پیکربندی‌شده، حفظ state، راه‌اندازی، `/healthz`، `/readyz`، و بودجه‌های وضعیت RPC را بررسی می‌کند. یک baseline را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` override کنید، از زمان‌بند تجمیعی بخواهید baselineهای دقیق را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` مانند `all-since-2026.4.23` گسترش دهد، و fixtureهای شبیه issue را با `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` مانند `reported-issues` گسترش دهید؛ مجموعه reported-issues شامل `configured-plugin-installs` برای تعمیر خودکار نصب Plugin خارجی OpenClaw است. Package Acceptance این موارد را با نام‌های `published_upgrade_survivor_baseline`، `published_upgrade_survivor_baselines`، و `published_upgrade_survivor_scenarios` ارائه می‌کند. -- دودآزمون زمینه runtime نشست: `pnpm test:docker:session-runtime-context` ماندگاری transcript زمینه runtime پنهان به‌علاوه تعمیر doctor برای شاخه‌های تکراری prompt-rewrite آسیب‌دیده را تأیید می‌کند. -- دودآزمون نصب سراسری Bun: `bash scripts/e2e/bun-global-install-smoke.sh` درخت فعلی را بسته‌بندی می‌کند، آن را با `bun install -g` در یک home ایزوله نصب می‌کند، و تأیید می‌کند که `openclaw infer image providers --json` به‌جای گیر کردن، ارائه‌دهندگان تصویر همراه بسته را برمی‌گرداند. یک tarball از پیش ساخته‌شده را با `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` دوباره استفاده کنید، ساخت میزبان را با `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` رد کنید، یا `dist/` را از یک تصویر Docker ساخته‌شده با `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` کپی کنید. -- دودآزمون Docker نصب‌کننده: `bash scripts/test-install-sh-docker.sh` یک cache مشترک npm را میان containerهای root، update، و direct-npm خود به‌اشتراک می‌گذارد. دودآزمون به‌روزرسانی به‌صورت پیش‌فرض پیش از ارتقا به tarball نامزد، از npm `latest` به‌عنوان baseline پایدار استفاده می‌کند. به‌صورت محلی با `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` یا در GitHub با ورودی `update_baseline_version` مربوط به workflow Install Smoke، آن را override کنید. بررسی‌های نصب‌کننده non-root یک cache ایزوله npm نگه می‌دارند تا ورودی‌های cache متعلق به root رفتار نصب user-local را پنهان نکنند. برای استفاده دوباره از cache root/update/direct-npm در اجرای مجدد محلی، `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` را تنظیم کنید. -- CI مربوط به Install Smoke به‌روزرسانی سراسری تکراری direct-npm را با `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` رد می‌کند؛ وقتی پوشش مستقیم `npm install -g` لازم است، اسکریپت را به‌صورت محلی بدون آن env اجرا کنید. -- دودآزمون CLI حذف workspace مشترک عامل‌ها: `pnpm test:docker:agents-delete-shared-workspace` (اسکریپت: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) به‌صورت پیش‌فرض تصویر Dockerfile ریشه را می‌سازد، دو عامل را با یک workspace در یک home ایزوله container seed می‌کند، `agents delete --json` را اجرا می‌کند، و JSON معتبر به‌علاوه رفتار workspace حفظ‌شده را تأیید می‌کند. تصویر install-smoke را با `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` دوباره استفاده کنید. -- شبکه‌سازی Gateway (دو container، احراز هویت WS + سلامت): `pnpm test:docker:gateway-network` (اسکریپت: `scripts/e2e/gateway-network-docker.sh`) -- دودآزمون snapshot مرورگر CDP: `pnpm test:docker:browser-cdp-snapshot` (اسکریپت: `scripts/e2e/browser-cdp-snapshot-docker.sh`) تصویر E2E سورس به‌علاوه یک لایه Chromium را می‌سازد، Chromium را با CDP خام شروع می‌کند، `browser doctor --deep` را اجرا می‌کند، و تأیید می‌کند snapshotهای نقش CDP شامل URLهای لینک، موارد قابل کلیک ارتقایافته با cursor، refs مربوط به iframe، و metadata فریم هستند. -- رگرسیون reasoning حداقلی OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (اسکریپت: `scripts/e2e/openai-web-search-minimal-docker.sh`) یک سرور OpenAI شبیه‌سازی‌شده را از طریق Gateway اجرا می‌کند، تأیید می‌کند `web_search` مقدار `reasoning.effort` را از `minimal` به `low` بالا می‌برد، سپس رد schema ارائه‌دهنده را اجبار می‌کند و بررسی می‌کند جزئیات خام در لاگ‌های Gateway ظاهر شود. -- پل کانال MCP (Gateway seed‌شده + پل stdio + دودآزمون notification-frame خام Claude): `pnpm test:docker:mcp-channels` (اسکریپت: `scripts/e2e/mcp-channels-docker.sh`) -- ابزارهای MCP بسته Pi (سرور MCP واقعی stdio + دودآزمون allow/deny پروفایل Pi تعبیه‌شده): `pnpm test:docker:pi-bundle-mcp-tools` (اسکریپت: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- پاک‌سازی MCP مربوط به Cron/subagent (Gateway واقعی + teardown فرزند MCP stdio پس از اجرای cron ایزوله و subagent یک‌باره): `pnpm test:docker:cron-mcp-cleanup` (اسکریپت: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (دودآزمون نصب/به‌روزرسانی برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، kitchen-sink مربوط به ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/بازرسی بسته Claude): `pnpm test:docker:plugins` (اسکریپت: `scripts/e2e/plugins-docker.sh`) - برای رد کردن بلوک ClawHub مقدار `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید، یا جفت package/runtime پیش‌فرض kitchen-sink را با `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` و `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` override کنید. بدون `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`، تست از یک سرور fixture محلی hermetic برای ClawHub استفاده می‌کند. -- دودآزمون به‌روزرسانی بدون تغییر Plugin: `pnpm test:docker:plugin-update` (اسکریپت: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- دودآزمون ماتریس lifecycle مربوط به Plugin: `pnpm test:docker:plugin-lifecycle-matrix` tarball بسته‌بندی‌شده OpenClaw را در یک container خالی نصب می‌کند، یک Plugin از npm نصب می‌کند، enable/disable را تغییر می‌دهد، آن را از طریق یک registry محلی npm ارتقا و تنزل می‌دهد، کد نصب‌شده را حذف می‌کند، سپس تأیید می‌کند uninstall همچنان state کهنه را حذف می‌کند، در حالی که برای هر فاز lifecycle متریک‌های RSS/CPU را لاگ می‌کند. -- دودآزمون metadata بازبارگذاری config: `pnpm test:docker:config-reload` (اسکریپت: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` دودآزمون نصب/به‌روزرسانی برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، fixtureهای ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/بازرسی بسته Claude را پوشش می‌دهد. `pnpm test:docker:plugin-update` رفتار به‌روزرسانی بدون تغییر برای plugins نصب‌شده را پوشش می‌دهد. `pnpm test:docker:plugin-lifecycle-matrix` نصب Plugin از npm با ردیابی منابع، enable، disable، upgrade، downgrade، و uninstall در نبود کد را پوشش می‌دهد. +- جادوگر آغازبه‌کار (TTY، داربست‌سازی کامل): `pnpm test:docker:onboard` (اسکریپت: `scripts/e2e/onboard-docker.sh`) +- دودآزمون آغازبه‌کار/کانال/عامل tarball مربوط به Npm: `pnpm test:docker:npm-onboard-channel-agent`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، OpenAI را از طریق آغازبه‌کار env-ref به‌همراه Telegram به‌طور پیش‌فرض پیکربندی می‌کند، doctor را اجرا می‌کند، و یک نوبت عامل OpenAI شبیه‌سازی‌شده را اجرا می‌کند. با `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz` از tarball ازپیش‌ساخته استفاده کنید، با `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` بازسازی میزبان را رد کنید، یا با `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` کانال را تغییر دهید. +- دودآزمون تغییر کانال به‌روزرسانی: `pnpm test:docker:update-channel-switch`، tarball بسته‌بندی‌شده OpenClaw را به‌صورت سراسری در Docker نصب می‌کند، از بسته `stable` به git `dev` تغییر می‌دهد، کانال پایدارشده و عملکرد Plugin پس از به‌روزرسانی را راستی‌آزمایی می‌کند، سپس دوباره به بسته `stable` برمی‌گردد و وضعیت به‌روزرسانی را بررسی می‌کند. +- دودآزمون بازمانده ارتقا: `pnpm test:docker:upgrade-survivor`، tarball بسته‌بندی‌شده OpenClaw را روی یک fixture کثیف کاربر قدیمی با عامل‌ها، پیکربندی کانال، فهرست‌های مجاز Plugin، وضعیت کهنه وابستگی Plugin، و فایل‌های موجود workspace/session نصب می‌کند. به‌روزرسانی بسته به‌همراه doctor غیرتعاملی را بدون کلیدهای provider یا کانال زنده اجرا می‌کند، سپس یک Gateway حلقه‌بازگشتی را شروع می‌کند و حفظ پیکربندی/وضعیت به‌همراه بودجه‌های startup/status را بررسی می‌کند. +- دودآزمون بازمانده ارتقای منتشرشده: `pnpm test:docker:published-upgrade-survivor` به‌طور پیش‌فرض `openclaw@latest` را نصب می‌کند، فایل‌های واقع‌گرایانه کاربر موجود را seed می‌کند، آن مبنا را با یک recipe فرمان baked پیکربندی می‌کند، پیکربندی حاصل را اعتبارسنجی می‌کند، آن نصب منتشرشده را به tarball نامزد به‌روزرسانی می‌کند، doctor غیرتعاملی را اجرا می‌کند، `.artifacts/upgrade-survivor/summary.json` را می‌نویسد، سپس یک Gateway حلقه‌بازگشتی را شروع می‌کند و intentهای پیکربندی‌شده، حفظ وضعیت، startup، `/healthz`، `/readyz`، و بودجه‌های وضعیت RPC را بررسی می‌کند. یک مبنا را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` بازنویسی کنید، از زمان‌بند تجمیعی بخواهید مبناهای دقیق را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` مانند `all-since-2026.4.23` گسترش دهد، و fixtureهای مسئله‌محور را با `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` مانند `reported-issues` گسترش دهید؛ مجموعه reported-issues شامل `configured-plugin-installs` برای ترمیم خودکار نصب Plugin خارجی OpenClaw است. Package Acceptance این موارد را با نام‌های `published_upgrade_survivor_baseline`، `published_upgrade_survivor_baselines`، و `published_upgrade_survivor_scenarios` ارائه می‌کند. +- دودآزمون زمینه runtime نشست: `pnpm test:docker:session-runtime-context`، پایداری transcript زمینه runtime پنهان به‌همراه ترمیم doctor برای شاخه‌های تکراری متاثر prompt-rewrite را راستی‌آزمایی می‌کند. +- دودآزمون نصب سراسری Bun: `bash scripts/e2e/bun-global-install-smoke.sh` درخت فعلی را بسته‌بندی می‌کند، آن را با `bun install -g` در یک home ایزوله نصب می‌کند، و راستی‌آزمایی می‌کند که `openclaw infer image providers --json` به‌جای hang شدن، providerهای تصویر bundled را برمی‌گرداند. با `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` از tarball ازپیش‌ساخته استفاده کنید، با `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` build میزبان را رد کنید، یا با `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`، `dist/` را از یک تصویر Docker ساخته‌شده کپی کنید. +- دودآزمون Docker نصب‌کننده: `bash scripts/test-install-sh-docker.sh` یک cache مشترک npm را میان containerهای root، update، و direct-npm خود به‌اشتراک می‌گذارد. دودآزمون update پیش از ارتقا به tarball نامزد، به‌طور پیش‌فرض npm `latest` را به‌عنوان مبنای stable استفاده می‌کند. به‌صورت محلی با `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`، یا در GitHub با ورودی `update_baseline_version` گردش‌کار Install Smoke بازنویسی کنید. بررسی‌های نصب‌کننده غیر root، یک cache ایزوله npm نگه می‌دارند تا entryهای cache متعلق به root، رفتار نصب کاربر-محلی را پنهان نکنند. برای استفاده دوباره از cache مربوط به root/update/direct-npm در اجرای مجدد محلی، `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` را تنظیم کنید. +- CI مربوط به Install Smoke با `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` به‌روزرسانی تکراری direct-npm سراسری را رد می‌کند؛ وقتی پوشش مستقیم `npm install -g` لازم است، اسکریپت را به‌صورت محلی بدون آن env اجرا کنید. +- دودآزمون CLI حذف workspace مشترک عامل‌ها: `pnpm test:docker:agents-delete-shared-workspace` (اسکریپت: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) به‌طور پیش‌فرض تصویر Dockerfile ریشه را می‌سازد، دو عامل را با یک workspace در home ایزوله container seed می‌کند، `agents delete --json` را اجرا می‌کند، و JSON معتبر به‌همراه رفتار حفظ workspace را راستی‌آزمایی می‌کند. با `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1` از تصویر install-smoke استفاده کنید. +- شبکه‌سازی Gateway (دو container، احراز هویت WS + health): `pnpm test:docker:gateway-network` (اسکریپت: `scripts/e2e/gateway-network-docker.sh`) +- دودآزمون snapshot مرورگر CDP: `pnpm test:docker:browser-cdp-snapshot` (اسکریپت: `scripts/e2e/browser-cdp-snapshot-docker.sh`) تصویر E2E منبع به‌همراه یک لایه Chromium را می‌سازد، Chromium را با CDP خام شروع می‌کند، `browser doctor --deep` را اجرا می‌کند، و راستی‌آزمایی می‌کند که snapshotهای نقش CDP شامل URLهای لینک، clickableهای ارتقایافته با cursor، ارجاع‌های iframe، و metadata فریم هستند. +- رگرسیون استدلال حداقلی OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (اسکریپت: `scripts/e2e/openai-web-search-minimal-docker.sh`) یک کارساز OpenAI شبیه‌سازی‌شده را از طریق Gateway اجرا می‌کند، راستی‌آزمایی می‌کند که `web_search` مقدار `reasoning.effort` را از `minimal` به `low` افزایش می‌دهد، سپس رد schema توسط provider را اجباری می‌کند و بررسی می‌کند که جزئیات خام در لاگ‌های Gateway ظاهر شده باشد. +- پل کانال MCP (Gateway seedشده + پل stdio + دودآزمون خام notification-frame مربوط به Claude): `pnpm test:docker:mcp-channels` (اسکریپت: `scripts/e2e/mcp-channels-docker.sh`) +- ابزارهای MCP بسته Pi (کارساز واقعی stdio MCP + دودآزمون allow/deny پروفایل Pi embedded): `pnpm test:docker:pi-bundle-mcp-tools` (اسکریپت: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- پاک‌سازی MCP مربوط به Cron/subagent (Gateway واقعی + teardown فرزند stdio MCP پس از اجرای cron ایزوله و subagent یک‌باره): `pnpm test:docker:cron-mcp-cleanup` (اسکریپت: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Pluginها (دودآزمون install/update برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، kitchen-sink مربوط به ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/inspect بسته Claude): `pnpm test:docker:plugins` (اسکریپت: `scripts/e2e/plugins-docker.sh`) + برای رد کردن بلوک ClawHub، `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` را تنظیم کنید، یا جفت package/runtime پیش‌فرض kitchen-sink را با `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` و `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID` بازنویسی کنید. بدون `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`، آزمون از یک کارساز fixture محلی hermetic مربوط به ClawHub استفاده می‌کند. +- دودآزمون بدون تغییر به‌روزرسانی Plugin: `pnpm test:docker:plugin-update` (اسکریپت: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- دودآزمون ماتریس چرخه عمر Plugin: `pnpm test:docker:plugin-lifecycle-matrix`، tarball بسته‌بندی‌شده OpenClaw را در یک container bare نصب می‌کند، یک Plugin مربوط به npm را نصب می‌کند، enable/disable را تغییر می‌دهد، آن را از طریق یک registry محلی npm ارتقا و تنزل می‌دهد، کد نصب‌شده را حذف می‌کند، سپس راستی‌آزمایی می‌کند که uninstall همچنان وضعیت کهنه را حذف می‌کند و هم‌زمان معیارهای RSS/CPU را برای هر فاز چرخه عمر ثبت می‌کند. +- دودآزمون metadata بارگذاری مجدد پیکربندی: `pnpm test:docker:config-reload` (اسکریپت: `scripts/e2e/config-reload-source-docker.sh`) +- Pluginها: `pnpm test:docker:plugins` دودآزمون install/update را برای مسیر محلی، `file:`، registry مربوط به npm با وابستگی‌های hoist‌شده، refs متحرک git، fixtureهای ClawHub، به‌روزرسانی‌های marketplace، و فعال‌سازی/inspect بسته Claude پوشش می‌دهد. `pnpm test:docker:plugin-update` رفتار update بدون تغییر برای Pluginهای نصب‌شده را پوشش می‌دهد. `pnpm test:docker:plugin-lifecycle-matrix` نصب، enable، disable، upgrade، downgrade، و uninstall در حالت نبود کد برای Plugin مربوط به npm با ردیابی منابع را پوشش می‌دهد. -برای پیش‌ساخت و استفاده دوباره دستی از تصویر عملکردی مشترک: +برای پیش‌ساخت و استفاده دوباره دستی از تصویر کارکردی مشترک: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -overrideهای مخصوص suite برای تصویر، مانند `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`، در صورت تنظیم همچنان اولویت دارند. وقتی `OPENCLAW_SKIP_DOCKER_BUILD=1` به یک تصویر مشترک remote اشاره می‌کند، اگر تصویر از قبل local نباشد، اسکریپت‌ها آن را pull می‌کنند. تست‌های QR و Docker نصب‌کننده Dockerfileهای خودشان را نگه می‌دارند، چون به‌جای runtime برنامه ساخته‌شده مشترک، رفتار بسته/نصب را اعتبارسنجی می‌کنند. +بازنویسی‌های تصویر ویژه suite مانند `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` همچنان در صورت تنظیم، اولویت دارند. وقتی `OPENCLAW_SKIP_DOCKER_BUILD=1` به یک تصویر مشترک remote اشاره می‌کند، اگر از قبل local نباشد، اسکریپت‌ها آن را pull می‌کنند. آزمون‌های Docker مربوط به QR و نصب‌کننده، Dockerfileهای خودشان را نگه می‌دارند، چون رفتار package/install را اعتبارسنجی می‌کنند نه runtime برنامه ساخته‌شده مشترک. -اجراکننده‌های Docker مدل زنده همچنین checkout فعلی را به‌صورت فقط‌خواندنی bind-mount می‌کنند و -آن را در یک پوشهٔ کاری موقت داخل کانتینر آماده‌سازی می‌کنند. این کار باعث می‌شود ایمیج زمان اجرا -کم‌حجم بماند، در حالی که Vitest همچنان روی همان منبع/پیکربندی محلی دقیق شما اجرا می‌شود. -گام آماده‌سازی، cacheهای بزرگ فقط‌محلی و خروجی‌های ساخت برنامه مانند -`.pnpm-store`، `.worktrees`، `__openclaw_vitest__`، و پوشه‌های خروجی `.build` محلی برنامه یا -Gradle را رد می‌کند تا اجراهای زندهٔ Docker چند دقیقه صرف کپی کردن -آرتیفکت‌های وابسته به ماشین نکنند. -آن‌ها همچنین `OPENCLAW_SKIP_CHANNELS=1` را تنظیم می‌کنند تا کاوشگرهای زندهٔ Gateway، -پردازش‌گرهای کانال واقعی Telegram/Discord و غیره را داخل کانتینر شروع نکنند. -`test:docker:live-models` همچنان `pnpm test:live` را اجرا می‌کند، بنابراین وقتی لازم است پوشش -زندهٔ Gateway را از آن مسیر Docker محدود یا مستثنی کنید، `OPENCLAW_LIVE_GATEWAY_*` را نیز -منتقل کنید. -`test:docker:openwebui` یک تست دود سازگاری سطح بالاتر است: یک کانتینر Gateway متعلق به -OpenClaw را با endpointهای HTTP سازگار با OpenAI فعال می‌کند، یک کانتینر Open WebUI -پین‌شده را در برابر آن Gateway شروع می‌کند، از طریق Open WebUI وارد می‌شود، -بررسی می‌کند `/api/models` مدل `openclaw/default` را در معرض می‌گذارد، سپس یک درخواست -گفت‌وگوی واقعی را از طریق پروکسی `/api/chat/completions` در Open WebUI می‌فرستد. -اجرای اول می‌تواند به‌طور محسوسی کندتر باشد، چون Docker ممکن است لازم باشد ایمیج -Open WebUI را دریافت کند و Open WebUI ممکن است لازم باشد راه‌اندازی شروع سرد خودش را کامل کند. -این مسیر انتظار یک کلید مدل زندهٔ قابل استفاده را دارد، و `OPENCLAW_PROFILE_FILE` -(`~/.profile` به‌صورت پیش‌فرض) راه اصلی برای فراهم کردن آن در اجراهای Docker شده است. +اجراکننده‌های Docker مدل زنده همچنین checkout فعلی را به‌صورت read-only bind-mount می‌کنند و +آن را در یک workdir موقت داخل container stage می‌کنند. این کار runtime +image را سبک نگه می‌دارد، درحالی‌که همچنان Vitest را روی دقیقاً همان منبع/پیکربندی محلی شما اجرا می‌کند. +مرحله staging cacheهای بزرگ و فقط‌محلی و خروجی‌های build اپ مانند +`.pnpm-store`، `.worktrees`، `__openclaw_vitest__`، و دایرکتوری‌های خروجی `.build` محلی اپ یا +Gradle را رد می‌کند تا اجراهای زنده Docker چند دقیقه را صرف کپی کردن +artifactهای مخصوص ماشین نکنند. +آن‌ها همچنین `OPENCLAW_SKIP_CHANNELS=1` را تنظیم می‌کنند تا probeهای زنده gateway +workerهای کانال واقعی Telegram/Discord/و غیره را داخل container شروع نکنند. +`test:docker:live-models` همچنان `pnpm test:live` را اجرا می‌کند، پس وقتی لازم است coverage زنده +gateway را از آن lane Docker محدود یا مستثنا کنید، `OPENCLAW_LIVE_GATEWAY_*` را نیز +pass through کنید. +`test:docker:openwebui` یک smoke سازگاری سطح‌بالاتر است: یک container +gateway OpenClaw را با endpointهای HTTP سازگار با OpenAI فعال‌شده شروع می‌کند، +یک container پین‌شده Open WebUI را در برابر آن gateway شروع می‌کند، از طریق +Open WebUI وارد می‌شود، بررسی می‌کند `/api/models` مدل `openclaw/default` را expose می‌کند، سپس یک +درخواست chat واقعی را از طریق proxy `/api/chat/completions` متعلق به Open WebUI ارسال می‌کند. +اجرای اول می‌تواند به‌طور محسوسی کندتر باشد، چون Docker ممکن است لازم باشد image +Open WebUI را pull کند و Open WebUI ممکن است لازم باشد setup شروع سرد خودش را تمام کند. +این lane انتظار یک key مدل زنده قابل‌استفاده دارد، و `OPENCLAW_PROFILE_FILE` +(به‌صورت پیش‌فرض `~/.profile`) روش اصلی برای فراهم کردن آن در اجراهای Dockerized است. اجراهای موفق یک payload کوچک JSON مانند `{ "ok": true, "model": "openclaw/default", ... }` چاپ می‌کنند. -`test:docker:mcp-channels` عمداً قطعی است و به حساب واقعی Telegram، Discord یا iMessage نیاز ندارد. -این مسیر یک کانتینر Gateway seeded را بوت می‌کند، کانتینر دومی را شروع می‌کند که -`openclaw mcp serve` را راه‌اندازی می‌کند، سپس کشف گفت‌وگوی مسیریابی‌شده، خواندن رونوشت‌ها، -فرادادهٔ پیوست، رفتار صف رویداد زنده، مسیریابی ارسال خروجی، و اعلان‌های کانال + مجوز -به سبک Claude را روی پل واقعی stdio MCP بررسی می‌کند. بررسی اعلان، فریم‌های خام stdio MCP -را مستقیماً بررسی می‌کند تا تست دود همان چیزی را اعتبارسنجی کند که پل واقعاً منتشر می‌کند، -نه فقط آنچه یک SDK کلاینت مشخص ممکن است نمایش دهد. -`test:docker:pi-bundle-mcp-tools` قطعی است و به کلید مدل زنده نیاز ندارد. این مسیر ایمیج -Docker مخزن را می‌سازد، یک سرور کاوش واقعی stdio MCP را داخل کانتینر شروع می‌کند، آن سرور -را از طریق زمان اجرای MCP باندل‌شدهٔ Pi در دسترس قرار می‌دهد، ابزار را اجرا می‌کند، سپس بررسی -می‌کند `coding` و `messaging` ابزارهای `bundle-mcp` را نگه می‌دارند، در حالی که `minimal` و -`tools.deny: ["bundle-mcp"]` آن‌ها را فیلتر می‌کنند. -`test:docker:cron-mcp-cleanup` قطعی است و به کلید مدل زنده نیاز ندارد. این مسیر یک Gateway -seeded را با یک سرور کاوش واقعی stdio MCP شروع می‌کند، یک نوبت Cron ایزوله و یک نوبت فرزند -یک‌بارهٔ `/subagents spawn` را اجرا می‌کند، سپس بررسی می‌کند فرایند فرزند MCP پس از هر اجرا -خارج می‌شود. +`test:docker:mcp-channels` عمداً deterministic است و به حساب واقعی +Telegram، Discord، یا iMessage نیاز ندارد. این lane یک container Gateway seed‌شده را boot می‌کند، +یک container دوم را شروع می‌کند که `openclaw mcp serve` را spawn می‌کند، سپس +کشف مکالمه routed، خواندن transcript، metadata پیوست، +رفتار live event queue، routing ارسال outbound، و اعلان‌های کانال + permission به سبک Claude را از طریق پل MCP واقعی stdio +بررسی می‌کند. بررسی اعلان، frameهای خام stdio MCP را مستقیماً inspect می‌کند تا smoke اعتبارسنجی کند که +bridge واقعاً چه چیزی emit می‌کند، نه فقط چیزی که یک SDK client خاص اتفاقاً surface می‌کند. +`test:docker:pi-bundle-mcp-tools` deterministic است و به key مدل زنده نیاز ندارد. +این lane image Docker repo را build می‌کند، یک probe server واقعی stdio MCP را +داخل container شروع می‌کند، آن server را از طریق runtime MCP bundle تعبیه‌شده Pi +materialize می‌کند، tool را اجرا می‌کند، سپس بررسی می‌کند `coding` و `messaging` +toolهای `bundle-mcp` را نگه می‌دارند درحالی‌که `minimal` و `tools.deny: ["bundle-mcp"]` آن‌ها را filter می‌کنند. +`test:docker:cron-mcp-cleanup` deterministic است و به key مدل زنده نیاز ندارد. +این lane یک Gateway seed‌شده را با یک probe server واقعی stdio MCP شروع می‌کند، یک +turn ایزوله cron و یک turn فرزند one-shot `/subagents spawn` را اجرا می‌کند، سپس بررسی می‌کند +process فرزند MCP پس از هر اجرا exit می‌کند. -تست دود دستی رشتهٔ گفت‌وگوی زبان طبیعی ACP (غیر CI): +smoke دستی thread زبان ساده ACP (نه CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- این اسکریپت را برای گردش‌کارهای رگرسیون/اشکال‌زدایی نگه دارید. ممکن است دوباره برای اعتبارسنجی مسیریابی رشتهٔ گفت‌وگوی ACP لازم شود، پس آن را حذف نکنید. +- این script را برای workflowهای regression/debug نگه دارید. ممکن است دوباره برای اعتبارسنجی routing thread ACP لازم شود، پس آن را حذف نکنید. -متغیرهای محیطی مفید: +env varهای مفید: -- `OPENCLAW_CONFIG_DIR=...` (پیش‌فرض: `~/.openclaw`) روی `/home/node/.openclaw` متصل می‌شود -- `OPENCLAW_WORKSPACE_DIR=...` (پیش‌فرض: `~/.openclaw/workspace`) روی `/home/node/.openclaw/workspace` متصل می‌شود -- `OPENCLAW_PROFILE_FILE=...` (پیش‌فرض: `~/.profile`) روی `/home/node/.profile` متصل می‌شود و پیش از اجرای تست‌ها بارگذاری می‌شود -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` برای اعتبارسنجی فقط متغیرهای محیطی بارگذاری‌شده از `OPENCLAW_PROFILE_FILE`، با استفاده از پوشه‌های موقت پیکربندی/فضای کاری و بدون اتصال‌های احراز هویت CLI خارجی -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (پیش‌فرض: `~/.cache/openclaw/docker-cli-tools`) روی `/home/node/.npm-global` برای نصب‌های cache‌شدهٔ CLI داخل Docker متصل می‌شود -- پوشه‌ها/فایل‌های احراز هویت CLI خارجی زیر `$HOME` به‌صورت فقط‌خواندنی زیر `/host-auth...` متصل می‌شوند، سپس پیش از شروع تست‌ها در `/home/node/...` کپی می‌شوند - - پوشه‌های پیش‌فرض: `.minimax` +- `OPENCLAW_CONFIG_DIR=...` (پیش‌فرض: `~/.openclaw`) که روی `/home/node/.openclaw` mount می‌شود +- `OPENCLAW_WORKSPACE_DIR=...` (پیش‌فرض: `~/.openclaw/workspace`) که روی `/home/node/.openclaw/workspace` mount می‌شود +- `OPENCLAW_PROFILE_FILE=...` (پیش‌فرض: `~/.profile`) که روی `/home/node/.profile` mount می‌شود و پیش از اجرای testها source می‌شود +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` برای بررسی فقط env varهایی که از `OPENCLAW_PROFILE_FILE` source شده‌اند، با استفاده از دایرکتوری‌های موقت config/workspace و بدون mountهای auth خارجی CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (پیش‌فرض: `~/.cache/openclaw/docker-cli-tools`) که برای نصب‌های CLI cache‌شده داخل Docker روی `/home/node/.npm-global` mount می‌شود +- دایرکتوری‌ها/فایل‌های auth خارجی CLI زیر `$HOME` به‌صورت read-only زیر `/host-auth...` mount می‌شوند، سپس پیش از شروع testها در `/home/node/...` کپی می‌شوند + - دایرکتوری‌های پیش‌فرض: `.minimax` - فایل‌های پیش‌فرض: `~/.codex/auth.json`، `~/.codex/config.toml`، `.claude.json`، `~/.claude/.credentials.json`، `~/.claude/settings.json`، `~/.claude/settings.local.json` - - اجراهای محدودشدهٔ ارائه‌دهنده فقط پوشه‌ها/فایل‌های لازم را که از `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` استنتاج شده‌اند متصل می‌کنند - - به‌صورت دستی با `OPENCLAW_DOCKER_AUTH_DIRS=all`، `OPENCLAW_DOCKER_AUTH_DIRS=none`، یا یک فهرست جداشده با ویرگول مانند `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` بازنویسی کنید + - اجراهای provider محدودشده فقط دایرکتوری‌ها/فایل‌های لازم استنباط‌شده از `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` را mount می‌کنند + - override دستی با `OPENCLAW_DOCKER_AUTH_DIRS=all`، `OPENCLAW_DOCKER_AUTH_DIRS=none`، یا یک comma list مانند `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` برای محدود کردن اجرا -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` برای فیلتر کردن ارائه‌دهندگان داخل کانتینر -- `OPENCLAW_SKIP_DOCKER_BUILD=1` برای استفادهٔ دوباره از ایمیج موجود `openclaw:local-live` در اجرای مجددهایی که به ساخت دوباره نیاز ندارند -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` برای اطمینان از اینکه اعتبارنامه‌ها از مخزن پروفایل می‌آیند (نه از محیط) -- `OPENCLAW_OPENWEBUI_MODEL=...` برای انتخاب مدلی که Gateway برای تست دود Open WebUI در معرض می‌گذارد -- `OPENCLAW_OPENWEBUI_PROMPT=...` برای بازنویسی پرامپت بررسی nonce که تست دود Open WebUI استفاده می‌کند -- `OPENWEBUI_IMAGE=...` برای بازنویسی تگ ایمیج پین‌شدهٔ Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` برای filter کردن providerها داخل container +- `OPENCLAW_SKIP_DOCKER_BUILD=1` برای reuse کردن image موجود `openclaw:local-live` برای rerunهایی که به rebuild نیاز ندارند +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` برای اطمینان از اینکه creds از profile store می‌آیند (نه env) +- `OPENCLAW_OPENWEBUI_MODEL=...` برای انتخاب مدلی که gateway برای smoke Open WebUI expose می‌کند +- `OPENCLAW_OPENWEBUI_PROMPT=...` برای override کردن prompt nonce-check استفاده‌شده توسط smoke Open WebUI +- `OPENWEBUI_IMAGE=...` برای override کردن tag image پین‌شده Open WebUI -## سلامت‌سنجی مستندات +## sanity اسناد -پس از ویرایش مستندات، بررسی‌های مستندات را اجرا کنید: `pnpm check:docs`. -وقتی به بررسی headingهای داخل صفحه هم نیاز دارید، اعتبارسنجی کامل anchorهای Mintlify را اجرا کنید: `pnpm docs:check-links:anchors`. +پس از ویرایش اسناد، checkهای اسناد را اجرا کنید: `pnpm check:docs`. +وقتی به checkهای heading درون صفحه هم نیاز دارید، اعتبارسنجی کامل anchor در Mintlify را اجرا کنید: `pnpm docs:check-links:anchors`. -## رگرسیون آفلاین (ایمن برای CI) +## regression آفلاین (CI-safe) -این‌ها رگرسیون‌های «خط لولهٔ واقعی» بدون ارائه‌دهندگان واقعی هستند: +این‌ها regressionهای «pipeline واقعی» بدون providerهای واقعی هستند: -- فراخوانی ابزار Gateway (OpenAI شبیه‌سازی‌شده، Gateway واقعی + حلقهٔ عامل): `src/gateway/gateway.test.ts` (مورد: "یک فراخوانی ابزار OpenAI شبیه‌سازی‌شده را به‌صورت سرتاسری از طریق حلقهٔ عامل Gateway اجرا می‌کند") -- راهنمای Gateway (WS `wizard.start`/`wizard.next`، پیکربندی را می‌نویسد + احراز هویت اعمال می‌شود): `src/gateway/gateway.test.ts` (مورد: "راهنما را روی ws اجرا می‌کند و پیکربندی توکن احراز هویت را می‌نویسد") +- فراخوانی tool در Gateway (mock OpenAI، gateway واقعی + agent loop): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- wizard Gateway (WS `wizard.start`/`wizard.next`، نوشتن config + auth enforced): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") -## ارزیابی‌های قابلیت اتکای عامل (Skills) +## evalهای قابلیت‌اعتماد agent (skills) -ما از قبل چند تست ایمن برای CI داریم که مانند «ارزیابی‌های قابلیت اتکای عامل» رفتار می‌کنند: +ما از قبل چند test CI-safe داریم که مانند «evalهای قابلیت‌اعتماد agent» رفتار می‌کنند: -- فراخوانی ابزار شبیه‌سازی‌شده از طریق Gateway واقعی + حلقهٔ عامل (`src/gateway/gateway.test.ts`). -- جریان‌های سرتاسری راهنما که اتصال نشست و اثرات پیکربندی را اعتبارسنجی می‌کنند (`src/gateway/gateway.test.ts`). +- فراخوانی mock tool از طریق gateway واقعی + agent loop (`src/gateway/gateway.test.ts`). +- جریان‌های wizard end-to-end که wiring session و اثرات config را اعتبارسنجی می‌کنند (`src/gateway/gateway.test.ts`). -مواردی که هنوز برای Skills کم است (ببینید [Skills](/fa/tools/skills)): +چیزی که هنوز برای skills کم است (ببینید [Skills](/fa/tools/skills)): -- **تصمیم‌گیری:** وقتی Skills در پرامپت فهرست شده‌اند، آیا عامل مورد درست را انتخاب می‌کند (یا از موارد نامرتبط دوری می‌کند)؟ -- **انطباق:** آیا عامل پیش از استفاده `SKILL.md` را می‌خواند و گام‌ها/آرگومان‌های لازم را دنبال می‌کند؟ -- **قراردادهای گردش‌کار:** سناریوهای چندنوبتی که ترتیب ابزارها، انتقال تاریخچهٔ نشست، و مرزهای محیط محصور را راستی‌آزمایی می‌کنند. +- **تصمیم‌گیری:** وقتی skillها در prompt فهرست شده‌اند، آیا agent skill درست را انتخاب می‌کند (یا از موارد نامرتبط اجتناب می‌کند)؟ +- **انطباق:** آیا agent پیش از استفاده `SKILL.md` را می‌خواند و stepها/argهای الزامی را دنبال می‌کند؟ +- **قراردادهای workflow:** سناریوهای multi-turn که ترتیب tool، carryover تاریخچه session، و boundaryهای sandbox را assert می‌کنند. -ارزیابی‌های آینده باید ابتدا قطعی بمانند: +evalهای آینده باید ابتدا deterministic بمانند: -- یک اجراکنندهٔ سناریو با ارائه‌دهندگان شبیه‌سازی‌شده برای راستی‌آزمایی فراخوانی‌های ابزار + ترتیب، خواندن فایل‌های Skills، و اتصال نشست. -- یک مجموعهٔ کوچک از سناریوهای متمرکز بر Skills (استفاده در برابر پرهیز، دروازه‌گذاری، تزریق پرامپت). -- ارزیابی‌های زندهٔ اختیاری (با فعال‌سازی صریح و محدودشده با متغیرهای محیطی) فقط پس از آماده شدن مجموعهٔ ایمن برای CI. +- یک scenario runner با استفاده از providerهای mock برای assert کردن tool callها + ترتیب، خواندن فایل skill، و wiring session. +- یک suite کوچک از سناریوهای متمرکز بر skill (استفاده در برابر اجتناب، gating، prompt injection). +- evalهای زنده اختیاری (opt-in، env-gated) فقط پس از آماده شدن suite CI-safe. -## تست‌های قرارداد (شکل Plugin و کانال) +## testهای قرارداد (شکل plugin و channel) -تست‌های قرارداد بررسی می‌کنند که هر Plugin و کانال ثبت‌شده با قرارداد -رابط خودش سازگار باشد. آن‌ها روی همهٔ Pluginهای کشف‌شده پیمایش می‌کنند و مجموعه‌ای از -راستی‌آزمایی‌های شکل و رفتار را اجرا می‌کنند. مسیر واحد پیش‌فرض `pnpm test` عمداً -این فایل‌های نقاط اتصال مشترک و تست دود را رد می‌کند؛ وقتی سطوح مشترک کانال یا ارائه‌دهنده -را لمس می‌کنید، دستورهای قرارداد را صریح اجرا کنید. +testهای قرارداد بررسی می‌کنند که هر plugin و channel ثبت‌شده با +قرارداد interface خودش مطابقت دارد. آن‌ها روی همه pluginهای کشف‌شده iterate می‌کنند و یک suite از +assertionهای شکل و رفتار را اجرا می‌کنند. lane واحد پیش‌فرض `pnpm test` عمداً +این فایل‌های seam و smoke مشترک را skip می‌کند؛ وقتی سطح‌های channel یا provider مشترک را touch می‌کنید، +commandهای قرارداد را صراحتاً اجرا کنید. -### دستورها +### Commandها -- همهٔ قراردادها: `pnpm test:contracts` -- فقط قراردادهای کانال: `pnpm test:contracts:channels` -- فقط قراردادهای ارائه‌دهنده: `pnpm test:contracts:plugins` +- همه قراردادها: `pnpm test:contracts` +- فقط قراردادهای channel: `pnpm test:contracts:channels` +- فقط قراردادهای provider: `pnpm test:contracts:plugins` -### قراردادهای کانال +### قراردادهای channel در `src/channels/plugins/contracts/*.contract.test.ts` قرار دارند: -- **Plugin** - شکل پایهٔ Plugin (id، name، capabilities) -- **راه‌اندازی** - قرارداد راهنمای راه‌اندازی -- **اتصال نشست** - رفتار اتصال نشست -- **باردادهٔ خروجی** - ساختار باردادهٔ پیام -- **ورودی** - مدیریت پیام ورودی -- **اقدام‌ها** - رسیدگی‌کننده‌های اقدام کانال -- **مدیریت رشتهٔ گفت‌وگو** - مدیریت شناسهٔ رشتهٔ گفت‌وگو -- **دایرکتوری** - API دایرکتوری/فهرست اعضا -- **سیاست گروه** - اعمال سیاست گروه +- **plugin** - شکل پایه plugin (id، name، capabilities) +- **setup** - قرارداد setup wizard +- **session-binding** - رفتار session binding +- **outbound-payload** - ساختار payload پیام +- **inbound** - handling پیام inbound +- **actions** - handlerهای action کانال +- **threading** - handling Thread ID +- **directory** - API directory/roster +- **group-policy** - enforcement سیاست group -### قراردادهای وضعیت ارائه‌دهنده +### قراردادهای status provider در `src/plugins/contracts/*.contract.test.ts` قرار دارند. -- **وضعیت** - کاوشگرهای وضعیت کانال -- **رجیستری** - شکل رجیستری Plugin +- **status** - probeهای status channel +- **registry** - شکل registry plugin -### قراردادهای ارائه‌دهنده +### قراردادهای provider در `src/plugins/contracts/*.contract.test.ts` قرار دارند: -- **احراز هویت** - قرارداد جریان احراز هویت -- **انتخاب احراز هویت** - انتخاب/گزینش احراز هویت -- **کاتالوگ** - API کاتالوگ مدل -- **کشف** - کشف Plugin -- **بارگذار** - بارگذاری Plugin -- **زمان اجرا** - زمان اجرای ارائه‌دهنده -- **شکل** - شکل/رابط Plugin -- **راهنما** - راهنمای راه‌اندازی +- **auth** - قرارداد جریان auth +- **auth-choice** - انتخاب/گزینش auth +- **catalog** - API catalog مدل +- **discovery** - کشف Plugin +- **loader** - loading Plugin +- **runtime** - runtime provider +- **shape** - شکل/interface Plugin +- **wizard** - Setup wizard -### چه زمانی اجرا شود +### زمان اجرا -- پس از تغییر خروجی‌های plugin-sdk یا زیرمسیرهای آن -- پس از افزودن یا تغییر یک کانال یا Plugin ارائه‌دهنده -- پس از بازآرایی ثبت یا کشف Plugin +- پس از تغییر exportها یا subpathهای plugin-sdk +- پس از افزودن یا تغییر یک channel یا provider plugin +- پس از refactor کردن registration یا discovery plugin -تست‌های قرارداد در CI اجرا می‌شوند و به کلیدهای واقعی API نیاز ندارند. +testهای قرارداد در CI اجرا می‌شوند و به keyهای واقعی API نیاز ندارند. -## افزودن رگرسیون‌ها (راهنما) +## افزودن regressionها (راهنما) -وقتی یک مشکل ارائه‌دهنده/مدل کشف‌شده در اجرای زنده را رفع می‌کنید: +وقتی issue مربوط به provider/model را که در live کشف شده fix می‌کنید: -- در صورت امکان یک رگرسیون ایمن برای CI اضافه کنید (ارائه‌دهندهٔ شبیه‌سازی‌شده/جایگزین ساده، یا ثبت تبدیل دقیق شکل درخواست) -- اگر ذاتاً فقط زنده است (محدودیت‌های نرخ، سیاست‌های احراز هویت)، تست زنده را محدود و با فعال‌سازی صریح از طریق متغیرهای محیطی نگه دارید -- ترجیح دهید کوچک‌ترین لایه‌ای را هدف بگیرید که خطا را می‌گیرد: - - خطای تبدیل/بازپخش درخواست ارائه‌دهنده → تست مستقیم مدل‌ها - - خطای خط لولهٔ نشست/تاریخچه/ابزار Gateway → تست دود زندهٔ Gateway یا تست شبیه‌سازی‌شدهٔ Gateway ایمن برای CI -- محافظ پیمایش SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` از فرادادهٔ رجیستری (`listSecretTargetRegistryEntries()`) برای هر کلاس SecretRef یک هدف نمونه استخراج می‌کند، سپس راستی‌آزمایی می‌کند که شناسه‌های اجرای دارای بخش پیمایش رد می‌شوند. - - اگر یک خانوادهٔ هدف SecretRef جدید با `includeInPlan` در `src/secrets/target-registry-data.ts` اضافه می‌کنید، `classifyTargetClass` را در آن تست به‌روزرسانی کنید. تست عمداً روی شناسه‌های هدف طبقه‌بندی‌نشده شکست می‌خورد تا کلاس‌های جدید نتوانند بی‌صدا نادیده گرفته شوند. +- در صورت امکان یک regression CI-safe اضافه کنید (provider mock/stub، یا capture کردن transformation دقیق request-shape) +- اگر ذاتاً فقط live است (rate limitها، policyهای auth)، test زنده را محدود و opt-in از طریق env varها نگه دارید +- ترجیح دهید کوچک‌ترین layer را هدف بگیرید که bug را catch می‌کند: + - bug تبدیل/replay درخواست provider → test مستقیم models + - bug pipeline session/history/tool gateway → smoke زنده gateway یا test mock gateway CI-safe +- guardrail پیمایش SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` یک target نمونه برای هر class از SecretRef را از metadata registry (`listSecretTargetRegistryEntries()`) derive می‌کند، سپس assert می‌کند exec idهای traversal-segment رد می‌شوند. + - اگر یک target family جدید SecretRef با `includeInPlan` در `src/secrets/target-registry-data.ts` اضافه می‌کنید، `classifyTargetClass` را در آن test update کنید. این test عمداً روی target idهای unclassified fail می‌شود تا classهای جدید نتوانند بی‌صدا skip شوند. ## مرتبط -- [تست زنده](/fa/help/testing-live) -- [تست به‌روزرسانی‌ها و Pluginها](/fa/help/testing-updates-plugins) +- [Testing live](/fa/help/testing-live) +- [Testing updates and plugins](/fa/help/testing-updates-plugins) - [CI](/fa/ci) diff --git a/docs/fa/install/updating.md b/docs/fa/install/updating.md index a500a37b9..07b701cfb 100644 --- a/docs/fa/install/updating.md +++ b/docs/fa/install/updating.md @@ -1,14 +1,14 @@ --- read_when: - به‌روزرسانی OpenClaw - - بعد از یک به‌روزرسانی مشکلی پیش می‌آید -summary: به‌روزرسانی ایمن OpenClaw (نصب سراسری یا از سورس)، به‌همراه راهبرد بازگشت + - پس از به‌روزرسانی چیزی خراب می‌شود +summary: به‌روزرسانی ایمن OpenClaw (نصب سراسری یا از منبع)، به‌همراه راهبرد بازگشت به نسخهٔ قبلی title: به‌روزرسانی x-i18n: - generated_at: "2026-05-03T21:36:30Z" + generated_at: "2026-05-04T07:05:33Z" model: gpt-5.5 provider: openai - source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1 + source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714 source_path: install/updating.md workflow: 16 --- @@ -17,13 +17,13 @@ OpenClaw را به‌روز نگه دارید. ## توصیه‌شده: `openclaw update` -سریع‌ترین روش برای به‌روزرسانی. نوع نصب شما را تشخیص می‌دهد (npm یا git)، آخرین نسخه را دریافت می‌کند، `openclaw doctor` را اجرا می‌کند و gateway را دوباره راه‌اندازی می‌کند. +سریع‌ترین راه برای به‌روزرسانی. نوع نصب شما را تشخیص می‌دهد (npm یا git)، آخرین نسخه را دریافت می‌کند، `openclaw doctor` را اجرا می‌کند، و Gateway را دوباره راه‌اندازی می‌کند. ```bash openclaw update ``` -برای تغییر کانال‌ها یا هدف‌گیری یک نسخه مشخص: +برای تغییر کانال‌ها یا هدف‌گرفتن یک نسخه مشخص: ```bash openclaw update --channel beta @@ -34,21 +34,17 @@ openclaw update --dry-run # preview without applying `openclaw update` گزینه `--verbose` را نمی‌پذیرد. برای عیب‌یابی به‌روزرسانی، از `--dry-run` برای پیش‌نمایش اقدام‌های برنامه‌ریزی‌شده، از `--json` برای نتایج ساختاریافته، یا از -`openclaw update status --json` برای بررسی کانال و وضعیت دسترس‌پذیری استفاده کنید. نصب‌کننده +`openclaw update status --json` برای بررسی وضعیت کانال و دسترس‌پذیری استفاده کنید. نصب‌کننده پرچم `--verbose` خودش را دارد، اما آن پرچم بخشی از `openclaw update` نیست. -`--channel beta` بتا را ترجیح می‌دهد، اما runtime وقتی -تگ بتا وجود نداشته باشد یا از آخرین انتشار پایدار قدیمی‌تر باشد، به stable/latest برمی‌گردد. اگر برای یک به‌روزرسانی موردی بسته، dist-tag خام npm beta را می‌خواهید، از `--tag beta` -استفاده کنید. +`--channel beta` بتا را ترجیح می‌دهد، اما runtime وقتی برچسب بتا وجود نداشته باشد یا از آخرین نسخه پایدار قدیمی‌تر باشد، به stable/latest برمی‌گردد. اگر dist-tag خام بتای npm را برای یک به‌روزرسانی موردی بسته می‌خواهید، از `--tag beta` استفاده کنید. برای معنای کانال‌ها، [کانال‌های توسعه](/fa/install/development-channels) را ببینید. ## جابه‌جایی بین نصب‌های npm و git -وقتی می‌خواهید نوع نصب را تغییر دهید، از کانال‌ها استفاده کنید. به‌روزرسان وضعیت، -پیکربندی، اعتبارنامه‌ها و workspace شما را در `~/.openclaw` نگه می‌دارد؛ فقط تغییر می‌دهد -که CLI و gateway از کدام نصب کد OpenClaw استفاده کنند. +وقتی می‌خواهید نوع نصب را تغییر دهید از کانال‌ها استفاده کنید. به‌روزرسان وضعیت، پیکربندی، credentials، و workspace شما را در `~/.openclaw` نگه می‌دارد؛ فقط این را تغییر می‌دهد که CLI و Gateway از کدام نصب کد OpenClaw استفاده کنند. ```bash # npm package install -> editable git checkout @@ -65,10 +61,7 @@ openclaw update --channel dev --dry-run openclaw update --channel stable --dry-run ``` -کانال `dev` وجود یک checkout از git را تضمین می‌کند، آن را می‌سازد و CLI سراسری را -از همان checkout نصب می‌کند. کانال‌های `stable` و `beta` از نصب‌های بسته‌ای استفاده می‌کنند. اگر -gateway از قبل نصب شده باشد، `openclaw update` فراداده سرویس را تازه‌سازی می‌کند -و مگر اینکه `--no-restart` را پاس دهید، آن را دوباره راه‌اندازی می‌کند. +کانال `dev` وجود یک checkout از git را تضمین می‌کند، آن را build می‌کند، و CLI سراسری را از همان checkout نصب می‌کند. کانال‌های `stable` و `beta` از نصب بسته‌ای استفاده می‌کنند. اگر Gateway از قبل نصب شده باشد، `openclaw update` فراداده سرویس را تازه‌سازی می‌کند و آن را دوباره راه‌اندازی می‌کند، مگر اینکه `--no-restart` را پاس دهید. ## جایگزین: اجرای دوباره نصب‌کننده @@ -76,37 +69,30 @@ gateway از قبل نصب شده باشد، `openclaw update` فراداده س curl -fsSL https://openclaw.ai/install.sh | bash ``` -برای رد کردن onboarding، `--no-onboard` را اضافه کنید. برای اجبار یک نوع نصب مشخص از طریق -نصب‌کننده، `--install-method git --no-onboard` یا +برای رد کردن onboarding، `--no-onboard` را اضافه کنید. برای اجبار یک نوع نصب مشخص از طریق نصب‌کننده، `--install-method git --no-onboard` یا `--install-method npm --no-onboard` را پاس دهید. -اگر `openclaw update` پس از مرحله نصب بسته npm شکست خورد، نصب‌کننده را -دوباره اجرا کنید. نصب‌کننده updater قدیمی را فراخوانی نمی‌کند؛ نصب بسته -سراسری را مستقیما اجرا می‌کند و می‌تواند یک نصب npm را که تا حدی به‌روز شده، بازیابی کند. +اگر `openclaw update` پس از مرحله نصب بسته npm شکست خورد، نصب‌کننده را دوباره اجرا کنید. نصب‌کننده updater قدیمی را فراخوانی نمی‌کند؛ نصب بسته سراسری را مستقیما اجرا می‌کند و می‌تواند یک نصب npm را که بخشی از آن به‌روزرسانی شده بازیابی کند. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm ``` -برای سنجاق کردن بازیابی به یک نسخه یا dist-tag مشخص، `--version` را اضافه کنید: +برای ثابت‌کردن بازیابی روی یک نسخه یا dist-tag مشخص، `--version` را اضافه کنید: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version ``` -## جایگزین: npm، pnpm یا bun دستی +## جایگزین: npm، pnpm، یا bun به‌صورت دستی ```bash npm i -g openclaw@latest ``` -وقتی `openclaw update` یک نصب سراسری npm را مدیریت می‌کند، ابتدا هدف را در -یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده را راستی‌آزمایی می‌کند، سپس -درخت بسته پاک را به پیشوند سراسری واقعی جابه‌جا می‌کند. این کار از هم‌پوشانی npm -یک بسته جدید روی فایل‌های کهنه بسته قدیمی جلوگیری می‌کند. اگر فرمان نصب شکست بخورد، -OpenClaw یک بار با `--omit=optional` دوباره تلاش می‌کند. این تلاش دوباره به میزبان‌هایی کمک می‌کند که در آن‌ها -وابستگی‌های اختیاری native نمی‌توانند کامپایل شوند، در حالی که اگر fallback هم شکست بخورد، -شکست اصلی همچنان قابل مشاهده می‌ماند. +برای نصب‌های تحت نظارت، `openclaw update` را ترجیح دهید، چون می‌تواند جابه‌جایی بسته را با سرویس Gateway در حال اجرا هماهنگ کند. اگر وقتی یک Gateway مدیریت‌شده در حال اجراست به‌صورت دستی به‌روزرسانی می‌کنید، بلافاصله پس از پایان کار مدیر بسته، Gateway را دوباره راه‌اندازی کنید تا فرایند قدیمی همچنان از فایل‌های بسته جایگزین‌شده سرویس‌دهی نکند. + +وقتی `openclaw update` یک نصب npm سراسری را مدیریت می‌کند، ابتدا هدف را در یک پیشوند موقت npm نصب می‌کند، موجودی `dist` بسته‌بندی‌شده را راستی‌آزمایی می‌کند، سپس درخت بسته پاک را به پیشوند سراسری واقعی منتقل می‌کند. این کار از قرار دادن بسته جدید توسط npm روی فایل‌های مانده از بسته قدیمی جلوگیری می‌کند. اگر فرمان نصب شکست بخورد، OpenClaw یک بار با `--omit=optional` دوباره تلاش می‌کند. این تلاش دوباره به میزبان‌هایی کمک می‌کند که وابستگی‌های اختیاری native در آن‌ها کامپایل نمی‌شوند، در حالی که اگر fallback هم شکست بخورد، شکست اصلی همچنان قابل مشاهده می‌ماند. ```bash pnpm add -g openclaw@latest @@ -120,13 +106,13 @@ bun add -g openclaw@latest - OpenClaw در runtime با نصب‌های سراسری بسته‌بندی‌شده مانند فقط‌خواندنی رفتار می‌کند، حتی وقتی دایرکتوری بسته سراسری برای کاربر فعلی قابل نوشتن باشد. نصب‌های بسته Plugin در ریشه‌های npm/git متعلق به OpenClaw زیر دایرکتوری پیکربندی کاربر قرار می‌گیرند، و راه‌اندازی Gateway درخت بسته OpenClaw را تغییر نمی‌دهد. + OpenClaw نصب‌های سراسری بسته‌بندی‌شده را در runtime فقط‌خواندنی در نظر می‌گیرد، حتی وقتی دایرکتوری بسته سراسری توسط کاربر فعلی قابل نوشتن باشد. نصب‌های بسته Plugin در ریشه‌های npm/git متعلق به OpenClaw زیر دایرکتوری پیکربندی کاربر قرار می‌گیرند، و راه‌اندازی Gateway درخت بسته OpenClaw را تغییر نمی‌دهد. - برخی تنظیمات npm در Linux بسته‌های سراسری را زیر دایرکتوری‌های متعلق به root مانند `/usr/lib/node_modules/openclaw` نصب می‌کنند. OpenClaw از این چیدمان پشتیبانی می‌کند، چون فرمان‌های نصب/به‌روزرسانی Plugin خارج از آن دایرکتوری بسته سراسری می‌نویسند. + برخی تنظیمات npm در Linux بسته‌های سراسری را زیر دایرکتوری‌های متعلق به root مانند `/usr/lib/node_modules/openclaw` نصب می‌کنند. OpenClaw از این چیدمان پشتیبانی می‌کند، چون فرمان‌های نصب/به‌روزرسانی Plugin بیرون از آن دایرکتوری بسته سراسری می‌نویسند. - به OpenClaw دسترسی نوشتن به ریشه‌های پیکربندی/وضعیتش بدهید تا نصب‌های صریح Plugin، به‌روزرسانی‌های Plugin و پاک‌سازی doctor بتوانند تغییرات خود را پایدار کنند: + به OpenClaw دسترسی نوشتن به ریشه‌های پیکربندی/وضعیت خودش بدهید تا نصب‌های صریح Plugin، به‌روزرسانی‌های Plugin، و پاک‌سازی doctor بتوانند تغییراتشان را پایدار کنند: ```ini ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp @@ -134,7 +120,7 @@ bun add -g openclaw@latest - پیش از به‌روزرسانی‌های بسته و نصب‌های صریح Plugin، OpenClaw تلاش می‌کند یک بررسی بهترین‌تلاشی فضای دیسک برای volume هدف انجام دهد. فضای کم یک هشدار همراه با مسیر بررسی‌شده تولید می‌کند، اما به‌روزرسانی را مسدود نمی‌کند، چون quotaهای فایل‌سیستم، snapshotها و volumeهای شبکه می‌توانند پس از بررسی تغییر کنند. نصب واقعی package-manager و راستی‌آزمایی پس از نصب همچنان مرجع نهایی هستند. + پیش از به‌روزرسانی بسته‌ها و نصب‌های صریح Plugin، OpenClaw تلاش می‌کند برای حجم هدف یک بررسی best-effort فضای دیسک انجام دهد. فضای کم یک هشدار با مسیر بررسی‌شده ایجاد می‌کند، اما به‌روزرسانی را مسدود نمی‌کند، چون سهمیه‌های فایل‌سیستم، snapshotها، و حجم‌های شبکه‌ای می‌توانند پس از بررسی تغییر کنند. نصب واقعی مدیر بسته و راستی‌آزمایی پس از نصب همچنان مرجع نهایی هستند. @@ -156,21 +142,16 @@ bun add -g openclaw@latest } ``` -| کانال | رفتار | +| کانال | رفتار | | -------- | ------------------------------------------------------------------------------------------------------------- | -| `stable` | `stableDelayHours` صبر می‌کند، سپس با jitter قطعی در سراسر `stableJitterHours` اعمال می‌کند (انتشار پخش‌شده). | -| `beta` | هر `betaCheckIntervalHours` بررسی می‌کند (پیش‌فرض: هر ساعت) و بلافاصله اعمال می‌کند. | -| `dev` | اعمال خودکار ندارد. از `openclaw update` به‌صورت دستی استفاده کنید. | +| `stable` | به اندازه `stableDelayHours` صبر می‌کند، سپس با jitter قطعی در سراسر `stableJitterHours` اعمال می‌کند (rollout پخش‌شده). | +| `beta` | هر `betaCheckIntervalHours` بررسی می‌کند (پیش‌فرض: هر ساعت) و بلافاصله اعمال می‌کند. | +| `dev` | اعمال خودکار ندارد. از `openclaw update` به‌صورت دستی استفاده کنید. | -Gateway همچنین هنگام راه‌اندازی یک راهنمای به‌روزرسانی ثبت می‌کند (با `update.checkOnStart: false` غیرفعال کنید). -برای downgrade یا بازیابی حادثه، `OPENCLAW_NO_AUTO_UPDATE=1` را در محیط gateway تنظیم کنید تا اعمال خودکار حتی وقتی `update.auto.enabled` پیکربندی شده باشد مسدود شود. راهنماهای به‌روزرسانی هنگام راه‌اندازی همچنان می‌توانند اجرا شوند، مگر اینکه `update.checkOnStart` نیز غیرفعال شده باشد. +Gateway همچنین هنگام startup یک راهنمای به‌روزرسانی در log می‌نویسد (با `update.checkOnStart: false` غیرفعال کنید). +برای downgrade یا بازیابی رخداد، `OPENCLAW_NO_AUTO_UPDATE=1` را در محیط Gateway تنظیم کنید تا اعمال خودکار حتی وقتی `update.auto.enabled` پیکربندی شده است مسدود شود. راهنماهای به‌روزرسانی هنگام startup همچنان می‌توانند اجرا شوند، مگر اینکه `update.checkOnStart` نیز غیرفعال شده باشد. -به‌روزرسانی‌های package-manager که از طریق handler زنده control-plane در Gateway درخواست می‌شوند -پس از جابه‌جایی بسته، یک راه‌اندازی مجدد به‌روزرسانی بدون تعویق و بدون cooldown را اجبار می‌کنند. این کار -از باقی ماندن یک پردازش قدیمی در حافظه آن‌قدر طولانی که chunkها را با lazy-load -از درخت بسته‌ای که قبلا جایگزین شده است بار کند، جلوگیری می‌کند. `openclaw update` در Shell -برای نصب‌های تحت نظارت همچنان مسیر ترجیحی است، چون می‌تواند سرویس را اطراف به‌روزرسانی متوقف و -دوباره راه‌اندازی کند. +به‌روزرسانی‌های مدیر بسته که از طریق handler زنده control-plane Gateway درخواست می‌شوند، پس از جابه‌جایی بسته یک restart به‌روزرسانی بدون تعویق و بدون cooldown را اجبار می‌کنند. این کار از باقی ماندن یک فرایند قدیمی در حافظه برای مدتی که بتواند chunkها را از درخت بسته‌ای که قبلا جایگزین شده lazy-load کند جلوگیری می‌کند. مسیر shell یعنی `openclaw update` همچنان برای نصب‌های تحت نظارت ترجیح داده می‌شود، چون می‌تواند سرویس را پیرامون به‌روزرسانی متوقف و دوباره راه‌اندازی کند. ## پس از به‌روزرسانی @@ -182,9 +163,9 @@ Gateway همچنین هنگام راه‌اندازی یک راهنمای به openclaw doctor ``` -پیکربندی را مهاجرت می‌دهد، سیاست‌های DM را audit می‌کند و سلامت gateway را بررسی می‌کند. جزئیات: [Doctor](/fa/gateway/doctor) +پیکربندی را migrate می‌کند، سیاست‌های DM را audit می‌کند، و سلامت Gateway را بررسی می‌کند. جزئیات: [Doctor](/fa/gateway/doctor) -### راه‌اندازی مجدد gateway +### راه‌اندازی دوباره Gateway ```bash openclaw gateway restart @@ -198,9 +179,9 @@ openclaw health -## بازگشت به نسخه قبلی +## بازگردانی -### سنجاق کردن یک نسخه (npm) +### ثابت‌کردن یک نسخه (npm) ```bash npm i -g openclaw@ @@ -212,7 +193,7 @@ openclaw gateway restart `npm view openclaw version` نسخه منتشرشده فعلی را نشان می‌دهد. -### سنجاق کردن یک commit (source) +### ثابت‌کردن یک commit (source) ```bash git fetch origin diff --git a/docs/fa/plugins/google-meet.md b/docs/fa/plugins/google-meet.md index 64fd3defd..18f48e67a 100644 --- a/docs/fa/plugins/google-meet.md +++ b/docs/fa/plugins/google-meet.md @@ -1,53 +1,55 @@ --- read_when: - - می‌خواهید یک عامل OpenClaw به تماس Google Meet بپیوندد + - می‌خواهید یک عامل OpenClaw به یک تماس Google Meet بپیوندد - می‌خواهید یک عامل OpenClaw یک تماس جدید Google Meet ایجاد کند - - شما در حال پیکربندی Chrome، Chrome node یا Twilio به‌عنوان انتقال‌دهندهٔ Google Meet هستید -summary: 'Google Meet Plugin: پیوستن به URLهای مشخص Meet از طریق Chrome یا Twilio با پیش‌فرض‌های صدای بلادرنگ' + - در حال پیکربندی Chrome، Chrome Node یا Twilio به‌عنوان ترابری Google Meet هستید +summary: 'Plugin Google Meet: پیوستن به URLهای صریح Meet از طریق Chrome یا Twilio با پیش‌فرض‌های پاسخ‌گویی عامل' title: Plugin Google Meet x-i18n: - generated_at: "2026-05-04T02:26:30Z" + generated_at: "2026-05-04T07:06:47Z" model: gpt-5.5 provider: openai - source_hash: 77ab70d27d47bcc037144c7c6cfad6f93f307355b6ebcf3ee75c85b96a24af2f + source_hash: 4268ad895bbf83d649b9571c0888c27eb982ad9710dfb408f22f7818cdc5dbcb source_path: plugins/google-meet.md workflow: 16 --- -پشتیبانی شرکت‌کننده Google Meet برای OpenClaw — این Plugin عمدا صریح طراحی شده است: +Google Meet از شرکت‌کنندگان برای OpenClaw پشتیبانی می‌کند — این Plugin عمداً صریح طراحی شده است: - فقط به یک URL صریح `https://meet.google.com/...` می‌پیوندد. -- می‌تواند از طریق Google Meet API یک فضای Meet جدید ایجاد کند، سپس به URL +- می‌تواند از طریق Google Meet API یک فضای Meet جدید بسازد، سپس به URL بازگردانده‌شده بپیوندد. -- صدای `realtime` حالت پیش‌فرض است. -- صدای بلادرنگ می‌تواند وقتی به استدلال عمیق‌تر یا ابزارها نیاز است، به عامل کامل OpenClaw - فراخوانی برگشتی انجام دهد. -- عامل‌ها رفتار پیوستن را با `mode` انتخاب می‌کنند: برای گوش‌دادن/پاسخ‌گویی زنده از `realtime` - استفاده کنید، یا برای پیوستن/کنترل مرورگر بدون پل صدای بلادرنگ از `transcribe` استفاده کنید. -- احراز هویت ابتدا به‌صورت OAuth شخصی Google یا یک نمایه Chrome ازپیش واردشده انجام می‌شود. -- هیچ اعلام رضایت خودکاری وجود ندارد. -- پشتانه صوتی پیش‌فرض Chrome، `BlackHole 2ch` است. -- Chrome می‌تواند محلی اجرا شود یا روی یک میزبان node جفت‌شده. -- Twilio یک شماره شماره‌گیری به‌همراه PIN یا توالی DTMF اختیاری را می‌پذیرد؛ - نمی‌تواند مستقیما یک URL Meet را شماره‌گیری کند. -- فرمان CLI برابر `googlemeet` است؛ `meet` برای گردش‌کارهای گسترده‌تر تله‌کنفرانس - عامل رزرو شده است. +- `agent` حالت پیش‌فرض پاسخ‌گویی گفتاری است: رونویسی بلادرنگ گوش می‌دهد، + عامل پیکربندی‌شده OpenClaw پاسخ می‌دهد، و TTS معمول OpenClaw داخل Meet صحبت می‌کند. +- `bidi` همچنان به‌عنوان حالت جایگزین مدل صدای بلادرنگ مستقیم در دسترس می‌ماند. +- عامل‌ها رفتار پیوستن را با `mode` انتخاب می‌کنند: از `agent` برای گوش‌دادن/پاسخ‌گویی + زنده، از `bidi` برای جایگزین صدای بلادرنگ مستقیم، یا از `transcribe` + برای پیوستن/کنترل مرورگر بدون پل پاسخ‌گویی گفتاری استفاده کنید. +- احراز هویت با OAuth شخصی Google یا یک نمایه Chrome که از قبل وارد شده است شروع می‌شود. +- اعلام رضایت خودکار وجود ندارد. +- پشتوانه صوتی پیش‌فرض Chrome برابر `BlackHole 2ch` است. +- Chrome می‌تواند محلی یا روی یک میزبان گره جفت‌شده اجرا شود. +- Twilio یک شماره تماس ورودی به‌همراه PIN اختیاری یا دنباله DTMF را می‌پذیرد؛ + نمی‌تواند مستقیماً با یک URL مربوط به Meet تماس بگیرد. +- فرمان CLI برابر `googlemeet` است؛ `meet` برای جریان‌های کاری گسترده‌تر + کنفرانس تلفنی عامل رزرو شده است. ## شروع سریع -وابستگی‌های صوتی محلی را نصب کنید و یک ارائه‌دهنده صدای بلادرنگ پشتانه را پیکربندی کنید. -OpenAI پیش‌فرض است؛ Google Gemini Live نیز با -`realtime.provider: "google"` کار می‌کند: +وابستگی‌های صوتی محلی را نصب کنید و یک ارائه‌دهنده رونویسی بلادرنگ به‌همراه +TTS معمول OpenClaw را پیکربندی کنید. OpenAI ارائه‌دهنده پیش‌فرض رونویسی است؛ +Google Gemini Live نیز به‌عنوان یک جایگزین صوتی جداگانه `bidi` با +`realtime.voiceProvider: "google"` کار می‌کند: ```bash brew install blackhole-2ch sox export OPENAI_API_KEY=sk-... -# or +# only needed when realtime.voiceProvider is "google" for bidi mode export GEMINI_API_KEY=... ``` -`blackhole-2ch` دستگاه صوتی مجازی `BlackHole 2ch` را نصب می‌کند. نصب‌کننده Homebrew -پیش از آنکه macOS دستگاه را در معرض استفاده قرار دهد به راه‌اندازی مجدد نیاز دارد: +`blackhole-2ch` دستگاه صوتی مجازی `BlackHole 2ch` را نصب می‌کند. نصب‌کننده +Homebrew پیش از آنکه macOS دستگاه را آشکار کند، به راه‌اندازی مجدد نیاز دارد: ```bash sudo reboot @@ -81,32 +83,33 @@ Plugin را فعال کنید: openclaw googlemeet setup ``` -خروجی راه‌اندازی برای خوانایی توسط عامل و آگاهی از حالت طراحی شده است. نمایه Chrome، -تثبیت node، و برای پیوستن‌های بلادرنگ Chrome، پل صوتی BlackHole/SoX و بررسی‌های -مقدمه بلادرنگ تأخیری را گزارش می‌کند. برای پیوستن‌های فقط مشاهده، همان انتقال را با -`--mode transcribe` بررسی کنید؛ آن حالت پیش‌نیازهای صوتی بلادرنگ را رد می‌کند -چون از طریق پل گوش نمی‌دهد یا از طریق آن صحبت نمی‌کند: +خروجی راه‌اندازی برای خواندن توسط عامل و آگاه از حالت طراحی شده است. این خروجی +نمایه Chrome، تثبیت گره، و برای پیوستن‌های بلادرنگ Chrome، پل صوتی +BlackHole/SoX و بررسی‌های معرفی بلادرنگِ با تأخیر را گزارش می‌کند. برای +پیوستن‌های فقط مشاهده، همان انتقال را با `--mode transcribe` بررسی کنید؛ +آن حالت پیش‌نیازهای صوتی بلادرنگ را رد می‌کند، چون از طریق پل گوش نمی‌دهد +یا صحبت نمی‌کند: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -وقتی واگذاری Twilio پیکربندی شده باشد، راه‌اندازی همچنین گزارش می‌دهد که آیا Plugin -`voice-call`، اعتبارنامه‌های Twilio، و در معرض‌گذاری Webhook عمومی آماده هستند یا نه. -هر بررسی `ok: false` را پیش از درخواست از عامل برای پیوستن، به‌عنوان مسدودکننده -برای انتقال و حالت بررسی‌شده در نظر بگیرید. برای اسکریپت‌ها یا خروجی قابل‌خواندن -برای ماشین، از `openclaw googlemeet setup --json` استفاده کنید. برای پیش‌پرواز یک -انتقال مشخص پیش از تلاش عامل، از `--transport chrome`، -`--transport chrome-node`، یا `--transport twilio` استفاده کنید. +وقتی تفویض Twilio پیکربندی شده باشد، راه‌اندازی همچنین گزارش می‌کند که آیا +Plugin `voice-call`، اعتبارنامه‌های Twilio، و دسترس‌پذیری عمومی Webhook آماده‌اند یا نه. +هر بررسی `ok: false` را پیش از درخواست از عامل برای پیوستن، برای انتقال و حالت +بررسی‌شده یک مانع در نظر بگیرید. برای اسکریپت‌ها یا خروجی قابل خواندن توسط ماشین +از `openclaw googlemeet setup --json` استفاده کنید. برای پیش‌بررسی یک انتقال مشخص +پیش از تلاش عامل، از `--transport chrome`، `--transport chrome-node`، یا +`--transport twilio` استفاده کنید. -برای Twilio، وقتی انتقال پیش‌فرض Chrome است، همیشه انتقال را صریحا پیش‌پرواز کنید: +برای Twilio، وقتی انتقال پیش‌فرض Chrome است، همیشه انتقال را صریحاً پیش‌بررسی کنید: ```bash openclaw googlemeet setup --transport twilio ``` -این کار سیم‌کشی مفقود `voice-call`، اعتبارنامه‌های Twilio، یا در معرض‌گذاری Webhook -غیرقابل‌دسترسی را پیش از تلاش عامل برای شماره‌گیری جلسه می‌گیرد. +این کار سیم‌کشی گمشده `voice-call`، اعتبارنامه‌های Twilio، یا دسترس‌پذیری +غیرقابل دسترس Webhook را پیش از تلاش عامل برای شماره‌گیری جلسه پیدا می‌کند. به یک جلسه بپیوندید: @@ -114,7 +117,7 @@ openclaw googlemeet setup --transport twilio openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -یا اجازه دهید عامل از طریق ابزار `google_meet` بپیوندد: +یا اجازه دهید یک عامل از طریق ابزار `google_meet` بپیوندد: ```json { @@ -125,37 +128,38 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -ابزار عامل‌محور `google_meet` روی میزبان‌های غیر macOS برای جریان‌های مصنوع، تقویم، -راه‌اندازی، رونویسی، Twilio، و `chrome-node` در دسترس می‌ماند. کنش‌های پاسخ‌گویی -محلی Chrome در آنجا مسدود می‌شوند چون مسیر صوتی Chrome بسته‌بندی‌شده در حال حاضر -به `BlackHole 2ch` در macOS وابسته است. در Linux، برای مشارکت پاسخ‌گویی Chrome از -`mode: "transcribe"`، شماره‌گیری Twilio، یا یک میزبان macOS `chrome-node` استفاده کنید. +ابزار روبه‌روی عامل `google_meet` روی میزبان‌های غیر macOS برای جریان‌های +مصنوع، تقویم، راه‌اندازی، رونویسی، Twilio، و `chrome-node` در دسترس می‌ماند. +اقدام‌های پاسخ‌گویی گفتاری Chrome محلی در آنجا مسدود می‌شوند، چون مسیر صوتی +Chrome همراه فعلاً به `BlackHole 2ch` در macOS وابسته است. روی Linux، برای +مشارکت پاسخ‌گویی گفتاری Chrome از `mode: "transcribe"`، تماس ورودی Twilio، +یا یک میزبان macOS `chrome-node` استفاده کنید. -یک جلسه جدید ایجاد کنید و به آن بپیوندید: +یک جلسه جدید بسازید و به آن بپیوندید: ```bash -openclaw googlemeet create --transport chrome-node --mode realtime +openclaw googlemeet create --transport chrome-node --mode agent ``` -برای اتاق‌های ایجادشده با API، وقتی می‌خواهید سیاست بدون درزدن اتاق به‌جای -ارث‌بری از پیش‌فرض‌های حساب Google صریح باشد، از Google Meet `SpaceConfig.accessType` -استفاده کنید: +برای اتاق‌هایی که با API ساخته می‌شوند، وقتی می‌خواهید سیاست بدون‌درزدن اتاق +به‌جای ارث‌بری از پیش‌فرض‌های حساب Google صریح باشد، از Google Meet +`SpaceConfig.accessType` استفاده کنید: ```bash -openclaw googlemeet create --access-type OPEN --transport chrome-node --mode realtime +openclaw googlemeet create --access-type OPEN --transport chrome-node --mode agent ``` -`OPEN` اجازه می‌دهد هر کسی با URL Meet بدون درزدن بپیوندد. `TRUSTED` اجازه می‌دهد -کاربران مورد اعتماد سازمان میزبان، کاربران خارجی دعوت‌شده، و کاربران شماره‌گیر -بدون درزدن بپیوندند. `RESTRICTED` ورود بدون درزدن را به دعوت‌شدگان محدود می‌کند. -این تنظیمات فقط برای مسیر ایجاد رسمی Google Meet API اعمال می‌شوند، بنابراین -اعتبارنامه‌های OAuth باید پیکربندی شده باشند. +`OPEN` اجازه می‌دهد هر کسی با URL مربوط به Meet بدون درزدن بپیوندد. `TRUSTED` +به کاربران مورد اعتماد سازمان میزبان، کاربران خارجی دعوت‌شده، و کاربران تماس ورودی +اجازه می‌دهد بدون درزدن بپیوندند. `RESTRICTED` ورود بدون‌درزدن را به دعوت‌شده‌ها +محدود می‌کند. این تنظیمات فقط بر مسیر رسمی ساخت با Google Meet API اعمال می‌شوند، +پس اعتبارنامه‌های OAuth باید پیکربندی شده باشند. -اگر پیش از در دسترس شدن این گزینه Google Meet را احراز هویت کرده‌اید، پس از افزودن -دامنه `meetings.space.settings` به صفحه رضایت Google OAuth خود، -`openclaw googlemeet auth login --json` را دوباره اجرا کنید. +اگر پیش از در دسترس بودن این گزینه Google Meet را احراز هویت کرده‌اید، پس از افزودن +دامنه `meetings.space.settings` به صفحه رضایت Google OAuth خود، دوباره +`openclaw googlemeet auth login --json` را اجرا کنید. -فقط URL را بدون پیوستن ایجاد کنید: +فقط URL را بدون پیوستن بسازید: ```bash openclaw googlemeet create --no-join @@ -163,83 +167,83 @@ openclaw googlemeet create --no-join `googlemeet create` دو مسیر دارد: -- ایجاد API: وقتی اعتبارنامه‌های Google Meet OAuth پیکربندی شده باشند استفاده می‌شود. این +- ساخت با API: وقتی اعتبارنامه‌های OAuth مربوط به Google Meet پیکربندی شده باشند استفاده می‌شود. این قطعی‌ترین مسیر است و به وضعیت UI مرورگر وابسته نیست. -- جایگزین مرورگر: وقتی اعتبارنامه‌های OAuth وجود ندارند استفاده می‌شود. OpenClaw از - node تثبیت‌شده Chrome استفاده می‌کند، `https://meet.google.com/new` را باز می‌کند، - منتظر می‌ماند تا Google به یک URL واقعی با کد جلسه هدایت کند، سپس آن URL را - برمی‌گرداند. این مسیر نیاز دارد نمایه Chrome مربوط به OpenClaw روی node از قبل - وارد Google شده باشد. - خودکارسازی مرورگر درخواست نخستین‌اجرای میکروفون خود Meet را مدیریت می‌کند؛ آن درخواست - به‌عنوان شکست ورود Google تلقی نمی‌شود. - جریان‌های پیوستن و ایجاد همچنین تلاش می‌کنند پیش از باز کردن مورد جدید، از یک زبانه - Meet موجود دوباره استفاده کنند. تطبیق، رشته‌های پرس‌وجوی بی‌ضرر URL مانند `authuser` - را نادیده می‌گیرد، بنابراین تلاش دوباره عامل باید به‌جای ایجاد زبانه دوم Chrome، - جلسه ازقبل‌باز را متمرکز کند. +- جایگزین مرورگر: وقتی اعتبارنامه‌های OAuth وجود نداشته باشند استفاده می‌شود. OpenClaw از گره + Chrome تثبیت‌شده استفاده می‌کند، `https://meet.google.com/new` را باز می‌کند، منتظر می‌ماند Google به + یک URL واقعی با کد جلسه هدایت کند، سپس آن URL را برمی‌گرداند. این مسیر نیاز دارد + نمایه Chrome مربوط به OpenClaw روی گره از قبل وارد Google شده باشد. + خودکارسازی مرورگر اعلان میکروفون اجرای نخست خود Meet را مدیریت می‌کند؛ آن اعلان + به‌عنوان شکست ورود Google در نظر گرفته نمی‌شود. + جریان‌های پیوستن و ساخت همچنین تلاش می‌کنند پیش از باز کردن یک زبانه جدید، از یک + زبانه موجود Meet دوباره استفاده کنند. تطبیق، رشته‌های پرس‌وجوی بی‌ضرر URL مانند `authuser` + را نادیده می‌گیرد، بنابراین تلاش دوباره عامل باید به‌جای ساخت یک زبانه دوم + Chrome، جلسه‌ای را که از قبل باز است در کانون قرار دهد. -خروجی فرمان/ابزار شامل یک فیلد `source` (`api` یا `browser`) است تا عامل‌ها بتوانند -توضیح دهند کدام مسیر استفاده شده است. `create` به‌طور پیش‌فرض به جلسه جدید می‌پیوندد و -`joined: true` به‌همراه نشست پیوستن را برمی‌گرداند. برای ضرب‌کردن فقط URL، در CLI از -`create --no-join` استفاده کنید یا `"join": false` را به ابزار پاس دهید. +خروجی فرمان/ابزار شامل یک فیلد `source` است (`api` یا `browser`) تا عامل‌ها +بتوانند توضیح دهند کدام مسیر استفاده شده است. `create` به‌طور پیش‌فرض به جلسه جدید +می‌پیوندد و `joined: true` به‌همراه نشست پیوستن را برمی‌گرداند. برای فقط ضرب‌کردن URL، +در CLI از `create --no-join` استفاده کنید یا `"join": false` را به ابزار بدهید. -یا به عامل بگویید: «یک Google Meet ایجاد کن، با صدای بلادرنگ به آن بپیوند، و پیوند را -برای من بفرست.» عامل باید `google_meet` را با `action: "create"` فراخوانی کند و -سپس `meetingUri` بازگردانده‌شده را به اشتراک بگذارد. +یا به یک عامل بگویید: «یک Google Meet بساز، با حالت پاسخ‌گویی گفتاری عامل به آن بپیوند، +و پیوند را برایم بفرست.» عامل باید `google_meet` را با +`action: "create"` فراخوانی کند و سپس `meetingUri` بازگردانده‌شده را به اشتراک بگذارد. ```json { "action": "create", "transport": "chrome-node", - "mode": "realtime" + "mode": "agent" } ``` برای پیوستن فقط مشاهده/کنترل مرورگر، `"mode": "transcribe"` را تنظیم کنید. این کار -پل صدای بلادرنگ دوطرفه را شروع نمی‌کند، به BlackHole یا SoX نیاز ندارد، و در جلسه -پاسخ صوتی نمی‌دهد. پیوستن‌های Chrome در این حالت همچنین از اعطای مجوز میکروفون/دوربین -OpenClaw و مسیر **Use -microphone** در Meet اجتناب می‌کنند. اگر Meet میان‌پرده انتخاب صدا را نشان دهد، -خودکارسازی مسیر بدون میکروفون را امتحان می‌کند و در غیر این صورت به‌جای باز کردن -میکروفون محلی، یک اقدام دستی گزارش می‌دهد. در حالت رونویسی، انتقال‌های مدیریت‌شده -Chrome همچنین یک ناظر زیرنویس Meet به‌صورت بهترین تلاش نصب می‌کنند. `googlemeet status --json` و -`googlemeet doctor` موارد `captioning`، `captionsEnabledAttempted`, -`transcriptLines`، `lastCaptionAt`، `lastCaptionSpeaker`، `lastCaptionText`, +پل صدای بلادرنگ دوطرفه را شروع نمی‌کند، به BlackHole یا SoX نیاز ندارد، +و در جلسه پاسخ گفتاری نمی‌دهد. پیوستن‌های Chrome در این حالت همچنین از اعطای +مجوز میکروفون/دوربین OpenClaw و مسیر **استفاده از میکروفون** در Meet پرهیز می‌کنند. +اگر Meet یک میان‌پرده انتخاب صدا نشان دهد، خودکارسازی مسیر بدون میکروفون را امتحان می‌کند +و در غیر این صورت به‌جای باز کردن میکروفون محلی، یک اقدام دستی را گزارش می‌کند. +در حالت رونویسی، انتقال‌های مدیریت‌شده Chrome همچنین یک مشاهده‌گر زیرنویس Meet +به‌صورت بهترین تلاش نصب می‌کنند. `googlemeet status --json` و +`googlemeet doctor` موارد `captioning`، `captionsEnabledAttempted`، +`transcriptLines`، `lastCaptionAt`، `lastCaptionSpeaker`، `lastCaptionText`، و یک دنباله کوتاه `recentTranscript` را نشان می‌دهند تا اپراتورها بتوانند بفهمند -آیا مرورگر به تماس پیوسته و آیا زیرنویس‌های Meet متن تولید می‌کنند یا نه. -وقتی به یک کاوش بله/خیر نیاز دارید، از `openclaw googlemeet test-listen --transport chrome-node` -استفاده کنید: در حالت رونویسی می‌پیوندد، منتظر حرکت تازه زیرنویس یا رونویسی می‌ماند، -و `listenVerified`، `listenTimedOut`، فیلدهای اقدام دستی، و آخرین سلامت زیرنویس را +مرورگر به تماس پیوسته است یا نه و آیا زیرنویس‌های Meet متن تولید می‌کنند یا نه. +وقتی به یک بررسی بله/خیر نیاز دارید، از `openclaw googlemeet test-listen --transport chrome-node` +استفاده کنید: این فرمان در حالت رونویسی می‌پیوندد، منتظر حرکت تازه زیرنویس یا رونویسی می‌ماند، +و `listenVerified`، `listenTimedOut`، فیلدهای اقدام دستی، و آخرین وضعیت سلامت زیرنویس را برمی‌گرداند. -در طول نشست‌های بلادرنگ، وضعیت `google_meet` سلامت مرورگر و پل صوتی مانند `inCall`, -`manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`، مهرهای زمانی آخرین ورودی/خروجی، -شمارنده‌های بایت، و وضعیت بسته‌شدن پل را شامل می‌شود. اگر یک درخواست امن صفحه Meet -ظاهر شود، خودکارسازی مرورگر وقتی بتواند آن را مدیریت می‌کند. ورود، پذیرش میزبان، و -درخواست‌های مجوز مرورگر/سیستم‌عامل به‌صورت اقدام دستی با دلیل و پیام برای انتقال توسط -عامل گزارش می‌شوند. نشست‌های مدیریت‌شده Chrome فقط پس از آن عبارت مقدمه یا آزمون را -منتشر می‌کنند که سلامت مرورگر `inCall: true` را گزارش کند؛ در غیر این صورت وضعیت -`speechReady: false` را گزارش می‌دهد و تلاش گفتار به‌جای وانمود کردن به اینکه عامل -در جلسه صحبت کرده است، مسدود می‌شود. +در طول نشست‌های بلادرنگ، وضعیت `google_meet` سلامت مرورگر و پل صوتی مانند +`inCall`، `manualActionRequired`، `providerConnected`، +`realtimeReady`، `audioInputActive`، `audioOutputActive`، آخرین مُهرهای زمانی +ورودی/خروجی، شمارنده‌های بایت، و وضعیت بسته‌شدن پل را شامل می‌شود. اگر یک اعلان +ایمن صفحه Meet ظاهر شود، خودکارسازی مرورگر تا جایی که بتواند آن را مدیریت می‌کند. +اعلان‌های ورود، پذیرش میزبان، و مجوز مرورگر/سیستم‌عامل به‌عنوان اقدام دستی با دلیل +و پیام برای انتقال توسط عامل گزارش می‌شوند. نشست‌های مدیریت‌شده Chrome فقط پس از آنکه +سلامت مرورگر `inCall: true` را گزارش کند، عبارت معرفی یا آزمون را منتشر می‌کنند؛ +در غیر این صورت وضعیت `speechReady: false` را گزارش می‌کند و تلاش گفتار به‌جای +وانمود کردن اینکه عامل داخل جلسه صحبت کرده است، مسدود می‌شود. -پیوستن‌های محلی Chrome از طریق نمایه مرورگر OpenClaw واردشده انجام می‌شوند. حالت بلادرنگ -برای مسیر میکروفون/بلندگو که OpenClaw استفاده می‌کند به `BlackHole 2ch` نیاز دارد. -برای صدای دوطرفه تمیز، از دستگاه‌های مجازی جداگانه یا یک گراف به سبک Loopback استفاده کنید؛ -یک دستگاه BlackHole برای نخستین آزمون دود کافی است اما می‌تواند اکو ایجاد کند. +پیوستن‌های Chrome محلی از طریق نمایه مرورگر OpenClaw که وارد شده است انجام می‌شوند. +حالت بلادرنگ برای مسیر میکروفون/بلندگوی مورد استفاده OpenClaw به `BlackHole 2ch` +نیاز دارد. برای صدای دوطرفه تمیز، از دستگاه‌های مجازی جداگانه یا یک گراف به سبک +Loopback استفاده کنید؛ یک دستگاه BlackHole برای نخستین آزمون دود کافی است اما ممکن +است اکو ایجاد کند. ### Gateway محلی + Chrome در Parallels -برای اینکه فقط VM مالک Chrome باشد، به Gateway کامل OpenClaw یا کلید API مدل داخل VM -macOS نیاز **ندارید**. Gateway و عامل را محلی اجرا کنید، سپس یک میزبان node در VM -اجرا کنید. Plugin بسته‌بندی‌شده را یک‌بار روی VM فعال کنید تا node فرمان Chrome را +فقط برای اینکه VM مالک Chrome باشد، به یک OpenClaw Gateway کامل یا کلید API مدل +داخل VM macOS نیاز ندارید. Gateway و عامل را محلی اجرا کنید، سپس یک میزبان گره +در VM اجرا کنید. Plugin همراه را یک‌بار روی VM فعال کنید تا گره فرمان Chrome را اعلان کند: چه چیزی کجا اجرا می‌شود: - میزبان Gateway: OpenClaw Gateway، فضای کاری عامل، کلیدهای مدل/API، ارائه‌دهنده - بلادرنگ، و پیکربندی Plugin Google Meet. -- VM macOS در Parallels: CLI/میزبان node OpenClaw، Google Chrome، SoX، BlackHole 2ch، - و یک نمایه Chrome واردشده به Google. + بلادرنگ، و پیکربندی Plugin مربوط به Google Meet. +- VM macOS در Parallels: OpenClaw CLI/میزبان گره، Google Chrome، SoX، BlackHole 2ch، + و یک نمایه Chrome که وارد Google شده است. - در VM لازم نیست: سرویس Gateway، پیکربندی عامل، کلید OpenAI/GPT، یا راه‌اندازی ارائه‌دهنده مدل. @@ -249,41 +253,41 @@ macOS نیاز **ندارید**. Gateway و عامل را محلی اجرا کن brew install blackhole-2ch sox ``` -پس از نصب BlackHole، VM را دوباره راه‌اندازی کنید تا macOS، `BlackHole 2ch` را -در معرض استفاده قرار دهد: +پس از نصب BlackHole، VM را راه‌اندازی مجدد کنید تا macOS دستگاه `BlackHole 2ch` +را آشکار کند: ```bash sudo reboot ``` -پس از راه‌اندازی مجدد، بررسی کنید که VM بتواند دستگاه صوتی و فرمان‌های SoX را ببیند: +پس از راه‌اندازی مجدد، بررسی کنید که VM می‌تواند دستگاه صوتی و فرمان‌های SoX را ببیند: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -OpenClaw را در VM نصب یا به‌روزرسانی کنید، سپس Plugin بسته‌بندی‌شده را آنجا فعال کنید: +OpenClaw را در VM نصب یا به‌روزرسانی کنید، سپس Plugin همراه را آنجا فعال کنید: ```bash openclaw plugins enable google-meet ``` -میزبان node را در VM شروع کنید: +میزبان گره را در VM شروع کنید: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -اگر `` یک IP شبکه LAN است و از TLS استفاده نمی‌کنید، node اتصال -WebSocket متنی ساده را رد می‌کند مگر اینکه برای آن شبکه خصوصی مورد اعتماد موافقت کنید: +اگر `` یک IP در LAN است و از TLS استفاده نمی‌کنید، گره WebSocket +متنی ساده را رد می‌کند مگر اینکه برای آن شبکه خصوصی مورد اعتماد اعلام موافقت کنید: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -هنگام نصب node به‌عنوان LaunchAgent از همان متغیر محیطی استفاده کنید: +هنگام نصب گره به‌عنوان LaunchAgent از همان متغیر محیطی استفاده کنید: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -292,24 +296,24 @@ openclaw node restart ``` `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` محیط فرایند است، نه یک تنظیم -`openclaw.json`. وقتی روی فرمان نصب وجود داشته باشد، `openclaw node install` آن را -در محیط LaunchAgent ذخیره می‌کند. +`openclaw.json`. وقتی `openclaw node install` این مقدار را در فرمان نصب حاضر ببیند، +آن را در محیط LaunchAgent ذخیره می‌کند. -node را از میزبان Gateway تأیید کنید: +گره را از میزبان Gateway تأیید کنید: ```bash openclaw devices list openclaw devices approve ``` -تأیید کنید که Gateway، node را می‌بیند و اینکه هم `googlemeet.chrome` و هم قابلیت +تأیید کنید Gateway گره را می‌بیند و گره هم `googlemeet.chrome` و هم قابلیت مرورگر/`browser.proxy` را اعلان می‌کند: ```bash openclaw nodes status ``` -Meet را روی میزبان Gateway از طریق آن node مسیریابی کنید: +Meet را از طریق آن گره روی میزبان Gateway مسیریابی کنید: ```json5 { @@ -339,118 +343,126 @@ Meet را روی میزبان Gateway از طریق آن node مسیریابی } ``` -اکنون به‌طور معمول از میزبان Gateway بپیوندید: +اکنون به‌صورت عادی از میزبان Gateway بپیوندید: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -یا از عامل بخواهید ابزار `google_meet` را با `transport: "chrome-node"` استفاده کند. +یا از عامل بخواهید از ابزار `google_meet` با `transport: "chrome-node"` استفاده کند. -برای یک آزمون دود تک‌فرمانی که یک نشست را ایجاد می‌کند یا دوباره استفاده می‌کند، یک -عبارت شناخته‌شده می‌گوید، و سلامت نشست را چاپ می‌کند: +برای یک آزمون دود تک‌فرمانی که یک نشست را می‌سازد یا دوباره استفاده می‌کند، یک عبارت +شناخته‌شده را می‌گوید، و سلامت نشست را چاپ می‌کند: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -هنگام پیوستن بی‌درنگ، اتوماسیون مرورگر OpenClaw نام مهمان را وارد می‌کند، روی -Join/Ask to join کلیک می‌کند، و وقتی اعلان Meet برای انتخاب اولیه «Use microphone» -نمایان شود، آن را می‌پذیرد. هنگام پیوستن فقط برای مشاهده یا ساخت جلسه فقط با مرورگر، -وقتی همان انتخاب در دسترس باشد، بدون میکروفون از همان اعلان عبور می‌کند. -اگر پروفایل مرورگر وارد حساب نشده باشد، Meet منتظر پذیرش میزبان باشد، -Chrome برای پیوستن بی‌درنگ به مجوز میکروفون/دوربین نیاز داشته باشد، یا Meet روی -اعلانی گیر کرده باشد که اتوماسیون نتوانسته آن را برطرف کند، نتیجه join/test-speech مقدار -`manualActionRequired: true` را همراه با `manualActionReason` و -`manualActionMessage` گزارش می‌کند. Agentها باید تلاش دوباره برای پیوستن را متوقف کنند، -همان پیام دقیق را همراه با `browserUrl`/`browserTitle` فعلی گزارش دهند، و فقط پس از -تکمیل اقدام دستی در مرورگر دوباره تلاش کنند. +هنگام پیوستن بلادرنگ، اتوماسیون مرورگر OpenClaw نام مهمان را پر می‌کند، روی +Join/Ask to join کلیک می‌کند، و وقتی اعلان نخستین اجرای Meet برای گزینهٔ +"Use microphone" ظاهر شود، آن را می‌پذیرد. هنگام پیوستن فقط برای مشاهده یا +ایجاد جلسه فقط با مرورگر، وقتی همان گزینه در دسترس باشد، بدون میکروفون از همان +اعلان عبور می‌کند. اگر نمایهٔ مرورگر وارد نشده باشد، Meet منتظر پذیرش میزبان +باشد، Chrome برای پیوستن بلادرنگ به مجوز میکروفون/دوربین نیاز داشته باشد، یا +Meet روی اعلانی گیر کرده باشد که اتوماسیون نتوانسته حل کند، نتیجهٔ +join/test-speech مقدار `manualActionRequired: true` را همراه با +`manualActionReason` و `manualActionMessage` گزارش می‌کند. عامل‌ها باید تلاش +دوباره برای پیوستن را متوقف کنند، همان پیام دقیق را به‌همراه `browserUrl`/ +`browserTitle` فعلی گزارش کنند، و فقط پس از کامل شدن اقدام دستی در مرورگر +دوباره تلاش کنند. -اگر `chromeNode.node` حذف شود، OpenClaw فقط زمانی به‌صورت خودکار انتخاب می‌کند که دقیقا یک -node متصل هر دو قابلیت `googlemeet.chrome` و کنترل مرورگر را اعلام کرده باشد. اگر -چند node دارای قابلیت متصل باشند، `chromeNode.node` را روی شناسه node، -نام نمایشی، یا IP راه دور تنظیم کنید. +اگر `chromeNode.node` حذف شده باشد، OpenClaw فقط وقتی به‌صورت خودکار انتخاب +می‌کند که دقیقاً یک گرهٔ متصل هم `googlemeet.chrome` و هم کنترل مرورگر را +اعلام کرده باشد. اگر چند گرهٔ توانمند متصل باشند، `chromeNode.node` را روی +شناسهٔ گره، نام نمایشی، یا IP راه‌دور تنظیم کنید. -بررسی‌های رایج خطا: +بررسی‌های رایج شکست: -- `Configured Google Meet node ... is not usable: offline`: node پین‌شده برای - Gateway شناخته‌شده است اما در دسترس نیست. Agentها باید آن node را به‌عنوان - وضعیت عیب‌یابی در نظر بگیرند، نه میزبان Chrome قابل استفاده، و به‌جای fallback به - transport دیگر، مانع راه‌اندازی را گزارش دهند مگر اینکه کاربر چنین چیزی خواسته باشد. -- `No connected Google Meet-capable node`: در VM دستور `openclaw node run` را اجرا کنید، - pairing را تأیید کنید، و مطمئن شوید `openclaw plugins enable google-meet` و - `openclaw plugins enable browser` در VM اجرا شده‌اند. همچنین تأیید کنید میزبان - Gateway هر دو فرمان node را با - `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` مجاز می‌داند. +- `Configured Google Meet node ... is not usable: offline`: گرهٔ پین‌شده برای + Gateway شناخته شده است اما در دسترس نیست. عامل‌ها باید با آن گره به‌عنوان + وضعیت عیب‌یابی رفتار کنند، نه میزبان Chrome قابل استفاده، و به‌جای برگشت به + انتقال دیگر، مانع راه‌اندازی را گزارش کنند مگر اینکه کاربر چنین چیزی خواسته + باشد. +- `No connected Google Meet-capable node`: در VM دستور `openclaw node run` را + اجرا کنید، جفت‌سازی را تأیید کنید، و مطمئن شوید `openclaw plugins enable google-meet` + و `openclaw plugins enable browser` در VM اجرا شده‌اند. همچنین تأیید کنید + میزبان Gateway هر دو فرمان گره را با + `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` مجاز + کرده است. - `BlackHole 2ch audio device not found`: روی میزبانی که بررسی می‌شود - `blackhole-2ch` را نصب کنید و پیش از استفاده از صدای Chrome محلی reboot کنید. -- `BlackHole 2ch audio device not found on the node`: در VM، `blackhole-2ch` - را نصب کنید و VM را reboot کنید. -- Chrome باز می‌شود اما نمی‌تواند بپیوندد: داخل VM وارد پروفایل مرورگر شوید، یا - برای پیوستن مهمان `chrome.guestName` را تنظیم نگه دارید. پیوستن خودکار مهمان از - اتوماسیون مرورگر OpenClaw از طریق proxy مرورگر node استفاده می‌کند؛ مطمئن شوید config - مرورگر node به پروفایلی اشاره می‌کند که می‌خواهید، برای نمونه - `browser.defaultProfile: "user"` یا یک پروفایل named existing-session. -- تب‌های تکراری Meet: گزینه `chrome.reuseExistingTab: true` را فعال نگه دارید. OpenClaw - پیش از باز کردن تب جدید، تب موجود برای همان URL Meet را فعال می‌کند، و - ساخت جلسه با مرورگر، پیش از باز کردن تب دیگر، یک تب در حال انجام - `https://meet.google.com/new` یا تب اعلان حساب Google را reuse می‌کند. -- بدون صدا: در Meet، میکروفون/بلندگو را از مسیر دستگاه صدای مجازی‌ای عبور دهید که - OpenClaw استفاده می‌کند؛ برای صدای duplex تمیز از دستگاه‌های مجازی جداگانه یا - routing شبیه Loopback استفاده کنید. + `blackhole-2ch` را نصب کنید و پیش از استفاده از صوت Chrome محلی بازراه‌اندازی + کنید. +- `BlackHole 2ch audio device not found on the node`: در VM مقدار + `blackhole-2ch` را نصب کنید و VM را بازراه‌اندازی کنید. +- Chrome باز می‌شود اما نمی‌تواند بپیوندد: داخل VM وارد نمایهٔ مرورگر شوید، یا + برای پیوستن مهمان `chrome.guestName` را تنظیم نگه دارید. پیوستن خودکار مهمان + از اتوماسیون مرورگر OpenClaw از طریق پراکسی مرورگر گره استفاده می‌کند؛ + مطمئن شوید پیکربندی مرورگر گره به نمایه‌ای اشاره می‌کند که می‌خواهید، برای + مثال `browser.defaultProfile: "user"` یا یک نمایهٔ نشست موجود با نام. +- تب‌های تکراری Meet: گزینهٔ `chrome.reuseExistingTab: true` را فعال بگذارید. + OpenClaw پیش از باز کردن تب جدید، تب موجود برای همان URL مربوط به Meet را + فعال می‌کند، و ایجاد جلسه در مرورگر پیش از باز کردن تب دیگر، از تب در حال + انجام `https://meet.google.com/new` یا اعلان حساب Google دوباره استفاده + می‌کند. +- نبود صدا: در Meet، میکروفون/بلندگو را از مسیر دستگاه صوتی مجازی مورد استفادهٔ + OpenClaw عبور دهید؛ برای صدای دوطرفهٔ تمیز از دستگاه‌های مجازی جداگانه یا + مسیریابی به سبک Loopback استفاده کنید. -## نکات نصب +## یادداشت‌های نصب -پیش‌فرض talk-back در Chrome از دو ابزار خارجی استفاده می‌کند: +پیش‌فرض پاسخ‌گویی صوتی Chrome از دو ابزار خارجی استفاده می‌کند: -- `sox`: ابزار صوتی خط فرمان. Plugin برای audio bridge پیش‌فرض PCM16 با نرخ 24 kHz - از فرمان‌های صریح دستگاه CoreAudio استفاده می‌کند. -- `blackhole-2ch`: درایور صوتی مجازی macOS. این ابزار دستگاه صوتی `BlackHole 2ch` - را ایجاد می‌کند که Chrome/Meet می‌توانند از آن route کنند. +- `sox`: ابزار صوتی خط فرمان. Plugin از فرمان‌های صریح دستگاه CoreAudio برای + پل صوتی پیش‌فرض 24 kHz PCM16 استفاده می‌کند. +- `blackhole-2ch`: درایور صوتی مجازی macOS. این ابزار دستگاه صوتی + `BlackHole 2ch` را ایجاد می‌کند که Chrome/Meet می‌تواند از طریق آن مسیریابی + شود. -OpenClaw هیچ‌کدام از این دو package را bundle یا بازتوزیع نمی‌کند. مستندات از کاربران می‌خواهند -آن‌ها را به‌عنوان وابستگی‌های میزبان از طریق Homebrew نصب کنند. SoX با مجوز -`LGPL-2.0-only AND GPL-2.0-only` منتشر شده است؛ BlackHole تحت GPL-3.0 است. اگر -installer یا applianceای می‌سازید که BlackHole را همراه با OpenClaw bundle می‌کند، شرایط -مجوزدهی upstream BlackHole را بررسی کنید یا از Existential Audio مجوز جداگانه بگیرید. +OpenClaw هیچ‌کدام از این بسته‌ها را همراه خود ارائه یا بازتوزیع نمی‌کند. مستندات +از کاربران می‌خواهد آن‌ها را به‌عنوان وابستگی‌های میزبان از طریق Homebrew نصب +کنند. SoX تحت مجوز `LGPL-2.0-only AND GPL-2.0-only` است؛ BlackHole تحت GPL-3.0 +است. اگر نصب‌کننده یا applianceای می‌سازید که BlackHole را همراه OpenClaw +بسته‌بندی می‌کند، شرایط مجوز بالادستی BlackHole را بررسی کنید یا از +Existential Audio مجوز جداگانه بگیرید. -## Transportها +## انتقال‌ها ### Chrome -transport مربوط به Chrome، URL Meet را از طریق کنترل مرورگر OpenClaw باز می‌کند و با -پروفایل مرورگر OpenClaw که وارد حساب شده است می‌پیوندد. در macOS، Plugin پیش از launch وجود -`BlackHole 2ch` را بررسی می‌کند. اگر پیکربندی شده باشد، پیش از باز کردن Chrome یک فرمان -سلامت audio bridge و فرمان startup را نیز اجرا می‌کند. وقتی Chrome/صدا روی میزبان -Gateway هستند از `chrome` استفاده کنید؛ وقتی Chrome/صدا روی node جفت‌شده‌ای مثل VM -macOS در Parallels هستند از `chrome-node` استفاده کنید. برای Chrome محلی، پروفایل را با -`browser.defaultProfile` انتخاب کنید؛ `chrome.browserProfile` به میزبان‌های -`chrome-node` پاس داده می‌شود. +انتقال Chrome، URL مربوط به Meet را از طریق کنترل مرورگر OpenClaw باز می‌کند و +با نمایهٔ مرورگر واردشدهٔ OpenClaw می‌پیوندد. روی macOS، Plugin پیش از اجرا +وجود `BlackHole 2ch` را بررسی می‌کند. اگر پیکربندی شده باشد، پیش از باز کردن +Chrome یک فرمان سلامت پل صوتی و فرمان راه‌اندازی را نیز اجرا می‌کند. وقتی +Chrome/صدا روی میزبان Gateway اجرا می‌شود از `chrome` استفاده کنید؛ وقتی +Chrome/صدا روی یک گرهٔ جفت‌شده مانند VM macOS در Parallels اجرا می‌شود از +`chrome-node` استفاده کنید. برای Chrome محلی، نمایه را با `browser.defaultProfile` +انتخاب کنید؛ `chrome.browserProfile` به میزبان‌های `chrome-node` پاس داده +می‌شود. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -صدای میکروفون و بلندگوی Chrome را از audio bridge محلی OpenClaw عبور دهید. اگر -`BlackHole 2ch` نصب نشده باشد، پیوستن به‌جای اینکه بی‌صدا و بدون مسیر صوتی انجام شود، -با خطای راه‌اندازی شکست می‌خورد. +صدای میکروفون و بلندگوی Chrome را از طریق پل صوتی محلی OpenClaw عبور دهید. اگر +`BlackHole 2ch` نصب نشده باشد، پیوستن به‌جای اینکه بی‌صدا و بدون مسیر صوتی +انجام شود، با خطای راه‌اندازی شکست می‌خورد. ### Twilio -transport مربوط به Twilio یک dial plan سخت‌گیرانه است که به Plugin تماس صوتی واگذار می‌شود. این -transport صفحه‌های Meet را برای شماره تلفن parse نمی‌کند. +انتقال Twilio یک طرح شماره‌گیری سخت‌گیرانه است که به Plugin تماس صوتی واگذار +می‌شود. این انتقال صفحه‌های Meet را برای شماره تلفن‌ها تحلیل نمی‌کند. -وقتی مشارکت از طریق Chrome در دسترس نیست یا fallback تماس تلفنی می‌خواهید از این استفاده کنید. -Google Meet باید برای جلسه شماره dial-in و PIN تلفنی ارائه کند؛ OpenClaw آن‌ها را از -صفحه Meet کشف نمی‌کند. +وقتی مشارکت با Chrome در دسترس نیست یا یک fallback شماره‌گیری تلفنی می‌خواهید +از این استفاده کنید. Google Meet باید برای جلسه شمارهٔ تماس تلفنی و PIN ارائه +کند؛ OpenClaw آن‌ها را از صفحهٔ Meet کشف نمی‌کند. -Plugin تماس صوتی را روی میزبان Gateway فعال کنید، نه روی node مربوط به Chrome: +Plugin تماس صوتی را روی میزبان Gateway فعال کنید، نه روی گرهٔ Chrome: ```json5 { plugins: { - allow: ["google-meet", "voice-call"], + allow: ["google-meet", "voice-call", "google"], entries: { "google-meet": { enabled: true, @@ -463,26 +475,48 @@ Plugin تماس صوتی را روی میزبان Gateway فعال کنید، ن enabled: true, config: { provider: "twilio", + inboundPolicy: "allowlist", + realtime: { + enabled: true, + provider: "google", + instructions: "Join this Google Meet as an OpenClaw agent. Be brief.", + toolPolicy: "safe-read-only", + providers: { + google: { + silenceDurationMs: 500, + startSensitivity: "high", + }, + }, + }, }, }, + google: { + enabled: true, + }, }, }, } ``` -اعتبارنامه‌های Twilio را از طریق environment یا config فراهم کنید. environment باعث می‌شود -secretها خارج از `openclaw.json` بمانند: +اعتبارنامه‌های Twilio را از طریق محیط یا پیکربندی ارائه کنید. محیط، رازها را +بیرون از `openclaw.json` نگه می‌دارد: ```bash export TWILIO_ACCOUNT_SID=AC... export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 +export GEMINI_API_KEY=... ``` -پس از فعال کردن `voice-call`، Gateway را restart یا reload کنید؛ تغییرات config مربوط به Plugin -تا زمانی که reload نشود در فرایند Gateway در حال اجرا ظاهر نمی‌شوند. +اگر ارائه‌دهندهٔ صدای بلادرنگ شما همین است، به‌جای آن از +`realtime.provider: "openai"` با Plugin ارائه‌دهندهٔ OpenAI و `OPENAI_API_KEY` +استفاده کنید. -سپس بررسی کنید: +پس از فعال کردن `voice-call`، Gateway را بازراه‌اندازی یا بارگذاری مجدد کنید؛ +تغییرات پیکربندی Plugin تا وقتی فرایند Gateway در حال اجرا بارگذاری مجدد نشود +در آن ظاهر نمی‌شود. + +سپس تأیید کنید: ```bash openclaw config validate @@ -490,9 +524,9 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -وقتی delegation مربوط به Twilio وصل باشد، `googlemeet setup` شامل بررسی‌های موفق +وقتی واگذاری Twilio وصل شده باشد، `googlemeet setup` شامل بررسی‌های موفق `twilio-voice-call-plugin`، `twilio-voice-call-credentials` و -`twilio-voice-call-webhook` خواهد بود. +`twilio-voice-call-webhook` می‌شود. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -501,7 +535,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -وقتی جلسه به sequence سفارشی نیاز دارد از `--dtmf-sequence` استفاده کنید: +وقتی جلسه به توالی سفارشی نیاز دارد، از `--dtmf-sequence` استفاده کنید: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -510,67 +544,70 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth و preflight +## OAuth و پیش‌پرواز -OAuth برای ساختن لینک Meet اختیاری است، چون `googlemeet create` می‌تواند به -اتوماسیون مرورگر fallback کند. وقتی ساخت از طریق API رسمی، resolution مربوط به space، -یا بررسی‌های preflight در Meet Media API را می‌خواهید، OAuth را پیکربندی کنید. +OAuth برای ایجاد لینک Meet اختیاری است، چون `googlemeet create` می‌تواند به +اتوماسیون مرورگر برگردد. وقتی ایجاد از طریق API رسمی، حل‌کردن space، یا +بررسی‌های پیش‌پرواز Meet Media API را می‌خواهید، OAuth را پیکربندی کنید. -دسترسی Google Meet API از OAuth کاربر استفاده می‌کند: یک Google Cloud OAuth client بسازید، -scopeهای لازم را درخواست کنید، یک حساب Google را authorize کنید، سپس refresh token حاصل را -در config مربوط به Plugin Google Meet ذخیره کنید یا متغیرهای محیطی -`OPENCLAW_GOOGLE_MEET_*` را فراهم کنید. +دسترسی Google Meet API از OAuth کاربر استفاده می‌کند: یک کلاینت OAuth در +Google Cloud ایجاد کنید، scopeهای لازم را درخواست کنید، یک حساب Google را +مجاز کنید، سپس refresh token حاصل را در پیکربندی Plugin مربوط به Google Meet +ذخیره کنید یا متغیرهای محیطی `OPENCLAW_GOOGLE_MEET_*` را ارائه کنید. -OAuth جایگزین مسیر پیوستن با Chrome نمی‌شود. transportهای Chrome و Chrome-node -هنوز هنگام استفاده از مشارکت مرورگری، از طریق پروفایل Chrome واردشده، BlackHole/SoX و -یک node متصل می‌پیوندند. OAuth فقط برای مسیر رسمی Google Meet API است: ساخت meeting -spaceها، resolve کردن spaceها، و اجرای بررسی‌های preflight در Meet Media API. +OAuth جایگزین مسیر پیوستن Chrome نمی‌شود. انتقال‌های Chrome و Chrome-node +هنوز هنگام استفاده از مشارکت مرورگر، از طریق نمایهٔ واردشدهٔ Chrome، +BlackHole/SoX، و یک گرهٔ متصل می‌پیوندند. OAuth فقط برای مسیر رسمی Google Meet +API است: ایجاد spaceهای جلسه، حل‌کردن spaceها، و اجرای بررسی‌های پیش‌پرواز +Meet Media API. -### ساخت اعتبارنامه‌های Google +### ایجاد اعتبارنامه‌های Google در Google Cloud Console: -1. یک پروژه Google Cloud بسازید یا انتخاب کنید. +1. یک پروژهٔ Google Cloud ایجاد یا انتخاب کنید. 2. **Google Meet REST API** را برای آن پروژه فعال کنید. -3. صفحه OAuth consent را پیکربندی کنید. - - **Internal** برای سازمان Google Workspace ساده‌ترین گزینه است. - - **External** برای راه‌اندازی‌های شخصی/آزمایشی کار می‌کند؛ تا زمانی که app در Testing است، - هر حساب Google را که قرار است app را authorize کند به‌عنوان test user اضافه کنید. +3. صفحهٔ رضایت OAuth را پیکربندی کنید. + - **Internal** برای یک سازمان Google Workspace ساده‌ترین گزینه است. + - **External** برای راه‌اندازی‌های شخصی/آزمایشی کار می‌کند؛ تا وقتی برنامه + در حالت Testing است، هر حساب Google را که قرار است برنامه را مجاز کند + به‌عنوان کاربر آزمایشی اضافه کنید. 4. scopeهایی را که OpenClaw درخواست می‌کند اضافه کنید: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.space.settings` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` -5. یک OAuth client ID بسازید. - - نوع application: **Web application**. - - URI مجاز redirect: +5. یک شناسهٔ کلاینت OAuth ایجاد کنید. + - نوع برنامه: **Web application**. + - URI مجاز تغییرمسیر: ```text http://localhost:8085/oauth2callback ``` -6. client ID و client secret را کپی کنید. +6. شناسهٔ کلاینت و secret کلاینت را کپی کنید. `meetings.space.created` برای `spaces.create` در Google Meet لازم است. -`meetings.space.readonly` به OpenClaw اجازه می‌دهد URLها/کدهای Meet را به spaceها resolve کند. -`meetings.space.settings` به OpenClaw اجازه می‌دهد هنگام ساخت room از طریق API، تنظیمات -`SpaceConfig` مانند `accessType` را پاس دهد. -`meetings.conference.media.readonly` برای preflight در Meet Media API و کار رسانه‌ای است؛ -Google ممکن است برای استفاده واقعی از Media API به ثبت‌نام Developer Preview نیاز داشته باشد. -اگر فقط به پیوستن‌های browser-based در Chrome نیاز دارید، OAuth را کاملا رد کنید. +`meetings.space.readonly` به OpenClaw اجازه می‌دهد URLها/کدهای Meet را به +spaceها حل کند. `meetings.space.settings` به OpenClaw اجازه می‌دهد هنگام ایجاد +اتاق از طریق API تنظیمات `SpaceConfig` مانند `accessType` را پاس دهد. +`meetings.conference.media.readonly` برای پیش‌پرواز Meet Media API و کار رسانه +است؛ Google ممکن است برای استفادهٔ واقعی از Media API به ثبت‌نام Developer +Preview نیاز داشته باشد. اگر فقط به پیوستن‌های Chrome مبتنی بر مرورگر نیاز +دارید، OAuth را کاملاً نادیده بگیرید. -### ساخت refresh token +### ساختن refresh token -`oauth.clientId` و در صورت نیاز `oauth.clientSecret` را پیکربندی کنید، یا آن‌ها را به‌عنوان -متغیرهای محیطی پاس دهید، سپس اجرا کنید: +`oauth.clientId` و در صورت نیاز `oauth.clientSecret` را پیکربندی کنید، یا آن‌ها +را به‌عنوان متغیرهای محیطی پاس دهید، سپس اجرا کنید: ```bash openclaw googlemeet auth login --json ``` -این فرمان یک بلوک config به نام `oauth` با refresh token چاپ می‌کند. از PKCE، -callback روی localhost در `http://localhost:8085/oauth2callback`، و flow دستی -copy/paste با `--manual` استفاده می‌کند. +این فرمان یک بلوک پیکربندی `oauth` با refresh token چاپ می‌کند. از PKCE، +callback محلی روی `http://localhost:8085/oauth2callback`، و جریان کپی/چسباندن +دستی با `--manual` استفاده می‌کند. نمونه‌ها: @@ -580,7 +617,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -وقتی مرورگر نمی‌تواند به callback محلی برسد از حالت دستی استفاده کنید: +وقتی مرورگر نمی‌تواند به callback محلی برسد، از حالت دستی استفاده کنید: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -603,7 +640,7 @@ openclaw googlemeet auth login --json --manual } ``` -object مربوط به `oauth` را زیر config Plugin مربوط به Google Meet ذخیره کنید: +شیء `oauth` را زیر پیکربندی Plugin مربوط به Google Meet ذخیره کنید: ```json5 { @@ -624,60 +661,70 @@ object مربوط به `oauth` را زیر config Plugin مربوط به Google } ``` -وقتی نمی‌خواهید refresh token در config باشد، متغیرهای محیطی را ترجیح دهید. -اگر هم مقدارهای config و هم مقدارهای environment حاضر باشند، Plugin ابتدا config را resolve می‌کند -و سپس به environment fallback می‌کند. +وقتی نمی‌خواهید refresh token در پیکربندی باشد، متغیرهای محیطی را ترجیح دهید. +اگر هم مقدارهای پیکربندی و هم مقدارهای محیطی حاضر باشند، Plugin ابتدا +پیکربندی را حل می‌کند و سپس به fallback محیطی برمی‌گردد. -OAuth consent شامل ساخت space در Meet، دسترسی خواندن space در Meet، و دسترسی خواندن رسانه -conference در Meet است. اگر پیش از وجود پشتیبانی ساخت جلسه authenticate کرده‌اید، -`openclaw googlemeet auth login --json` را دوباره اجرا کنید تا refresh token دارای scope -`meetings.space.created` باشد. +رضایت OAuth شامل ایجاد space در Meet، دسترسی خواندن به space در Meet، و +دسترسی خواندن رسانهٔ کنفرانس Meet است. اگر پیش از وجود پشتیبانی ایجاد جلسه +احراز هویت کرده‌اید، دوباره `openclaw googlemeet auth login --json` را اجرا +کنید تا refresh token دارای scope `meetings.space.created` باشد. ### تأیید OAuth با doctor -وقتی یک بررسی سلامت سریع و بدون secret می‌خواهید، OAuth doctor را اجرا کنید: +وقتی یک بررسی سلامت سریع و بدون راز می‌خواهید، doctor مربوط به OAuth را اجرا +کنید: ```bash openclaw googlemeet doctor --oauth --json ``` -این کار runtime مربوط به Chrome را load نمی‌کند و به node متصل Chrome نیاز ندارد. بررسی می‌کند که -config مربوط به OAuth وجود داشته باشد و refresh token بتواند access token صادر کند. گزارش JSON -فقط شامل فیلدهای وضعیت مانند `ok`، `configured`، `tokenSource`، `expiresAt` و پیام‌های check است؛ -access token، refresh token یا client secret را چاپ نمی‌کند. +این فرمان runtime مربوط به Chrome را بارگذاری نمی‌کند و به گرهٔ Chrome متصل +نیاز ندارد. بررسی می‌کند که پیکربندی OAuth وجود داشته باشد و refresh token +بتواند access token بسازد. گزارش JSON فقط فیلدهای وضعیت مانند `ok`، +`configured`، `tokenSource`، `expiresAt` و پیام‌های بررسی را شامل می‌شود؛ +access token، refresh token، یا secret کلاینت را چاپ نمی‌کند. نتایج رایج: | بررسی | معنی | | -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | `oauth.clientId` به‌علاوه `oauth.refreshToken`، یا یک access token کش‌شده، حاضر است. | -| `oauth-token` | access token کش‌شده هنوز معتبر است، یا refresh token یک access token جدید صادر کرده است. | -| `meet-spaces-get` | بررسی اختیاری `--meeting` یک space موجود Meet را resolve کرده است. | -| `meet-spaces-create` | بررسی اختیاری `--create-space` یک space جدید Meet ایجاد کرده است. | +| `oauth-config` | `oauth.clientId` به‌همراه `oauth.refreshToken`، یا یک نشانه دسترسی ذخیره‌شده، موجود است. | +| `oauth-token` | نشانه دسترسی ذخیره‌شده هنوز معتبر است، یا نشانه تازه‌سازی یک نشانه دسترسی جدید صادر کرده است. | +| `meet-spaces-get` | بررسی اختیاری `--meeting` یک فضای Meet موجود را پیدا کرد. | +| `meet-spaces-create` | بررسی اختیاری `--create-space` یک فضای Meet جدید ایجاد کرد. | -برای اثبات فعال بودن Google Meet API و scope مربوط به `spaces.create` نیز، بررسی create دارای -side effect را اجرا کنید: +برای اثبات فعال بودن Google Meet API و محدوده `spaces.create` نیز، بررسی +ایجاد دارای اثر جانبی را اجرا کنید: ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` یک URL موقت Meet ایجاد می‌کند. وقتی لازم است تأیید کنید که پروژه Google Cloud دارای Meet API فعال است و حساب مجاز scope‏ `meetings.space.created` را دارد، از آن استفاده کنید. +`--create-space` یک URL موقت Meet ایجاد می‌کند. زمانی از آن استفاده کنید که باید تأیید کنید +Google Cloud project دارای Meet API فعال است و حساب مجاز +محدوده `meetings.space.created` را دارد. -برای اثبات دسترسی خواندن به یک فضای جلسه موجود: +برای اثبات دسترسی خواندن برای یک فضای جلسه موجود: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` و `resolve-space` دسترسی خواندن به یک space موجود را که حساب Google مجاز می‌تواند به آن دسترسی داشته باشد اثبات می‌کنند. دریافت `403` از این بررسی‌ها معمولاً یعنی Google Meet REST API غیرفعال است، refresh token تأییدشده scope لازم را ندارد، یا حساب Google نمی‌تواند به آن space در Meet دسترسی داشته باشد. خطای refresh-token یعنی دوباره `openclaw googlemeet auth login ---json` را اجرا کنید و بلوک جدید `oauth` را ذخیره کنید. +`doctor --oauth --meeting` و `resolve-space` دسترسی خواندن به یک فضای موجود را +که حساب Google مجاز می‌تواند به آن دسترسی داشته باشد اثبات می‌کنند. یک `403` از این بررسی‌ها +معمولاً یعنی Google Meet REST API غیرفعال است، نشانه تازه‌سازی رضایت‌داده‌شده +محدوده لازم را ندارد، یا حساب Google نمی‌تواند به آن فضای Meet +دسترسی داشته باشد. خطای نشانه تازه‌سازی یعنی `openclaw googlemeet auth login +--json` را دوباره اجرا کنید و بلوک جدید `oauth` را ذخیره کنید. -برای fallback مرورگر، هیچ اعتبارنامه OAuth لازم نیست. در این حالت، احراز هویت Google از پروفایل Chrome واردشده در Node انتخاب‌شده می‌آید، نه از پیکربندی OpenClaw. +برای جایگزین مرورگر به هیچ اعتبارنامه OAuth نیازی نیست. در آن حالت، احراز هویت Google +از پروفایل Chrome واردشده در گره انتخاب‌شده می‌آید، نه از +پیکربندی OpenClaw. -این متغیرهای محیطی به‌عنوان fallback پذیرفته می‌شوند: +این متغیرهای محیطی به‌عنوان جایگزین پذیرفته می‌شوند: - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` یا `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` یا `GOOGLE_MEET_CLIENT_SECRET` @@ -688,19 +735,19 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` یا `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` یا `GOOGLE_MEET_PREVIEW_ACK` -یک URL‏ Meet، کد، یا `spaces/{id}` را از طریق `spaces.get` resolve کنید: +یک URL، کد، یا `spaces/{id}` مربوط به Meet را از طریق `spaces.get` حل کنید: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -پیش از کار رسانه‌ای، preflight را اجرا کنید: +پیش از کار رسانه‌ای، پیش‌بررسی را اجرا کنید: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -پس از اینکه Meet رکوردهای کنفرانس را ایجاد کرد، artifactهای جلسه و حضور را فهرست کنید: +پس از آنکه Meet رکوردهای کنفرانس را ایجاد کرد، مصنوعات جلسه و حضور را فهرست کنید: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -708,9 +755,12 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -با `--meeting`، `artifacts` و `attendance` به‌طور پیش‌فرض از آخرین رکورد کنفرانس استفاده می‌کنند. وقتی همه رکوردهای نگه‌داری‌شده برای آن جلسه را می‌خواهید، `--all-conference-records` را پاس دهید. +با `--meeting`، `artifacts` و `attendance` به‌طور پیش‌فرض از آخرین رکورد کنفرانس +استفاده می‌کنند. وقتی همه رکوردهای نگه‌داری‌شده برای آن جلسه را می‌خواهید، +`--all-conference-records` را ارسال کنید. -جست‌وجوی Calendar می‌تواند پیش از خواندن artifactهای Meet، URL جلسه را از Google Calendar resolve کند: +جست‌وجوی Calendar می‌تواند URL جلسه را پیش از خواندن مصنوعات Meet از Google Calendar +حل کند: ```bash openclaw googlemeet latest --today @@ -719,10 +769,14 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` در Calendar‏ `primary` امروز به‌دنبال رویداد Calendar دارای لینک Google Meet می‌گردد. برای جست‌وجوی متن رویدادهای مطابق از `--event `، و برای Calendar غیر primary از `--calendar ` استفاده کنید. جست‌وجوی Calendar به یک ورود OAuth تازه نیاز دارد که شامل scope فقط‌خواندنی رویدادهای Calendar باشد. -`calendar-events` رویدادهای Meet مطابق را پیش‌نمایش می‌کند و رویدادی را که `latest`، `artifacts`، `attendance`، یا `export` انتخاب خواهد کرد علامت می‌زند. +`--today` در تقویم `primary` امروز به‌دنبال یک رویداد Calendar با پیوند +Google Meet می‌گردد. برای جست‌وجوی متن رویدادهای منطبق از `--event ` و +برای یک تقویم غیر اصلی از `--calendar ` استفاده کنید. جست‌وجوی Calendar به ورود OAuth تازه‌ای نیاز دارد +که شامل محدوده فقط‌خواندنی رویدادهای Calendar باشد. +`calendar-events` رویدادهای Meet منطبق را پیش‌نمایش می‌کند و رویدادی را که +`latest`، `artifacts`، `attendance` یا `export` انتخاب خواهد کرد علامت می‌زند. -اگر از قبل id رکورد کنفرانس را می‌دانید، آن را مستقیماً نشانی‌دهی کنید: +اگر از قبل شناسه رکورد کنفرانس را می‌دانید، مستقیماً به آن آدرس‌دهی کنید: ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -730,15 +784,18 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -وقتی می‌خواهید اتاق را پس از تماس ببندید، کنفرانس فعال را برای یک space ایجادشده با API پایان دهید: +وقتی می‌خواهید پس از تماس اتاق را ببندید، یک کنفرانس فعال را برای فضایی که با API ایجاد شده است پایان دهید: ```bash openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -این دستور Google Meet‏ `spaces.endActiveConference` را فراخوانی می‌کند و برای spaceای که حساب مجاز می‌تواند مدیریت کند، به OAuth با scope‏ `meetings.space.created` نیاز دارد. -OpenClaw ورودی URL‏ Meet، کد جلسه، یا `spaces/{id}` را می‌پذیرد و پیش از پایان دادن به کنفرانس فعال، آن را به منبع space در API resolve می‌کند. -این دستور از `googlemeet leave` جداست: `leave` مشارکت محلی/نشست OpenClaw را متوقف می‌کند، در حالی که `end-active-conference` از Google Meet می‌خواهد کنفرانس فعال آن space را پایان دهد. +این کار Google Meet `spaces.endActiveConference` را فراخوانی می‌کند و به OAuth با +محدوده `meetings.space.created` برای فضایی نیاز دارد که حساب مجاز بتواند آن را مدیریت کند. +OpenClaw ورودی URL، کد جلسه، یا `spaces/{id}` مربوط به Meet را می‌پذیرد و پیش از پایان دادن به کنفرانس فعال، +آن را به منبع فضای API حل می‌کند. +این از `googlemeet leave` جداست: `leave` مشارکت محلی/نشستی OpenClaw را متوقف می‌کند، +در حالی که `end-active-conference` از Google Meet می‌خواهد کنفرانس فعال را برای فضا پایان دهد. یک گزارش خوانا بنویسید: @@ -755,13 +812,33 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` وقتی Google آن را برای جلسه ارائه کند، metadata رکورد کنفرانس به‌همراه metadata منابع participant، recording، transcript، transcript-entry ساخت‌یافته، و smart-note را برمی‌گرداند. برای رد کردن lookup ورودی‌ها در جلسه‌های بزرگ از `--no-transcript-entries` استفاده کنید. `attendance` شرکت‌کنندگان را به ردیف‌های participant-session با زمان‌های اولین/آخرین مشاهده، مدت کل نشست، flagهای دیرآمدن/زودتر ترک‌کردن، و منابع participant تکراری ادغام‌شده بر اساس کاربر واردشده یا نام نمایشی گسترش می‌دهد. برای جدا نگه داشتن منابع خام participant، `--no-merge-duplicates`، برای تنظیم تشخیص دیرآمدن `--late-after-minutes`، و برای تنظیم تشخیص زودتر ترک‌کردن `--early-before-minutes` را پاس دهید. +`artifacts` فراداده رکورد کنفرانس را به‌همراه فراداده منابع شرکت‌کننده، ضبط، +رونوشت، ورودی رونوشت ساختاریافته، و یادداشت هوشمند، وقتی Google آن را برای جلسه ارائه کند، +برمی‌گرداند. برای رد کردن جست‌وجوی ورودی در جلسات بزرگ از `--no-transcript-entries` استفاده کنید. +`attendance` شرکت‌کنندگان را به ردیف‌های نشست شرکت‌کننده با زمان‌های اولین/آخرین مشاهده، +مدت کل نشست، پرچم‌های دیررس/ترک زودهنگام، و منابع شرکت‌کننده تکراری ادغام‌شده بر اساس +کاربر واردشده یا نام نمایشی گسترش می‌دهد. برای جدا نگه‌داشتن منابع خام شرکت‌کننده +`--no-merge-duplicates`، برای تنظیم تشخیص دیررس `--late-after-minutes` و +برای تنظیم تشخیص ترک زودهنگام `--early-before-minutes` را ارسال کنید. -`export` پوشه‌ای شامل `summary.md`، `attendance.csv`، `transcript.md`، `artifacts.json`، `attendance.json`، و `manifest.json` می‌نویسد. -`manifest.json` ورودی انتخاب‌شده، گزینه‌های export، رکوردهای کنفرانس، فایل‌های خروجی، شمارش‌ها، منبع token، رویداد Calendar در صورت استفاده، و هرگونه هشدار بازیابی جزئی را ثبت می‌کند. برای نوشتن یک archive قابل‌حمل کنار پوشه نیز `--zip` را پاس دهید. برای export متن Google Docs مربوط به transcript و smart-note لینک‌شده از طریق Google Drive‏ `files.export`، `--include-doc-bodies` را پاس دهید؛ این کار به یک ورود OAuth تازه نیاز دارد که شامل scope فقط‌خواندنی Drive Meet باشد. بدون `--include-doc-bodies`، exportها فقط شامل metadata‏ Meet و ورودی‌های transcript ساخت‌یافته هستند. اگر Google یک شکست جزئی artifact برگرداند، مانند خطای فهرست smart-note، transcript-entry، یا document-body در Drive، summary و manifest به‌جای شکست دادن کل export، هشدار را نگه می‌دارند. -برای دریافت همان داده‌های artifact/attendance و چاپ JSON مربوط به manifest بدون ایجاد پوشه یا ZIP، از `--dry-run` استفاده کنید. این کار پیش از نوشتن یک export بزرگ یا وقتی agent فقط به شمارش‌ها، رکوردهای انتخاب‌شده، و هشدارها نیاز دارد مفید است. +`export` پوشه‌ای شامل `summary.md`، `attendance.csv`، +`transcript.md`، `artifacts.json`، `attendance.json` و `manifest.json` می‌نویسد. +`manifest.json` ورودی انتخاب‌شده، گزینه‌های خروجی، رکوردهای کنفرانس، +فایل‌های خروجی، شمارش‌ها، منبع نشانه، رویداد Calendar در صورت استفاده، و هرگونه +هشدار بازیابی جزئی را ثبت می‌کند. برای نوشتن یک آرشیو قابل‌حمل کنار پوشه نیز +`--zip` را ارسال کنید. برای خروجی گرفتن متن Google Docs رونوشت‌ها و +یادداشت‌های هوشمند پیوندشده از طریق Google Drive `files.export`، `--include-doc-bodies` را ارسال کنید؛ این به +ورود OAuth تازه‌ای نیاز دارد که شامل محدوده فقط‌خواندنی Drive Meet باشد. بدون +`--include-doc-bodies`، خروجی‌ها فقط شامل فراداده Meet و ورودی‌های رونوشت ساختاریافته هستند. +اگر Google یک شکست جزئی مصنوع برگرداند، مانند خطای فهرست‌کردن یادداشت هوشمند، +ورودی رونوشت، یا بدنه سند Drive، خلاصه و +manifest هشدار را به‌جای شکست دادن کل خروجی نگه می‌دارند. +برای واکشی همان داده‌های مصنوعات/حضور و چاپ JSON مربوط به +manifest بدون ایجاد پوشه یا ZIP از `--dry-run` استفاده کنید. این کار پیش از نوشتن +یک خروجی بزرگ یا وقتی یک عامل فقط به شمارش‌ها، رکوردهای انتخاب‌شده و +هشدارها نیاز دارد مفید است. -agentها همچنین می‌توانند همان bundle را از طریق ابزار `google_meet` ایجاد کنند: +عامل‌ها همچنین می‌توانند همان بسته را از طریق ابزار `google_meet` ایجاد کنند: ```json { @@ -773,20 +850,20 @@ agentها همچنین می‌توانند همان bundle را از طریق ا } ``` -برای بازگرداندن فقط manifest خروجی و رد کردن نوشتن فایل‌ها، `"dryRun": true` را تنظیم کنید. +برای برگرداندن فقط manifest خروجی و رد کردن نوشتن فایل‌ها، `"dryRun": true` را تنظیم کنید. -agentها همچنین می‌توانند یک اتاق مبتنی بر API با policy دسترسی صریح ایجاد کنند: +عامل‌ها همچنین می‌توانند یک اتاق مبتنی بر API با سیاست دسترسی صریح ایجاد کنند: ```json { "action": "create", "transport": "chrome-node", - "mode": "realtime", + "mode": "agent", "accessType": "OPEN" } ``` -و می‌توانند کنفرانس فعال یک اتاق شناخته‌شده را پایان دهند: +و می‌توانند کنفرانس فعال را برای یک اتاق شناخته‌شده پایان دهند: ```json { @@ -795,7 +872,7 @@ agentها همچنین می‌توانند یک اتاق مبتنی بر API ب } ``` -برای اعتبارسنجی listen-first، agentها باید پیش از ادعای مفید بودن جلسه از `test_listen` استفاده کنند: +برای اعتبارسنجی ابتدا-گوش‌دادن، عامل‌ها باید پیش از ادعای مفید بودن جلسه از `test_listen` استفاده کنند: ```json { @@ -806,7 +883,7 @@ agentها همچنین می‌توانند یک اتاق مبتنی بر API ب } ``` -live smoke محافظت‌شده را در برابر یک جلسه واقعی نگه‌داری‌شده اجرا کنید: +اسموک زنده محافظت‌شده را در برابر یک جلسه واقعی نگه‌داری‌شده اجرا کنید: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -814,38 +891,46 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -live listen-first browser probe را در برابر جلسه‌ای اجرا کنید که کسی در آن صحبت خواهد کرد و captionهای Meet در دسترس است: +کاوشگر مرورگر زنده ابتدا-گوش‌دادن را در برابر جلسه‌ای اجرا کنید که در آن کسی صحبت خواهد کرد +و زیرنویس‌های Meet در دسترس هستند: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -محیط live smoke: +محیط اسموک زنده: -- `OPENCLAW_LIVE_TEST=1` تست‌های live محافظت‌شده را فعال می‌کند. -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` به یک URL‏ Meet، کد، یا `spaces/{id}` نگه‌داری‌شده اشاره می‌کند. -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` یا `GOOGLE_MEET_CLIENT_ID` شناسه client‏ OAuth را فراهم می‌کند. -- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` یا `GOOGLE_MEET_REFRESH_TOKEN` refresh token را فراهم می‌کند. +- `OPENCLAW_LIVE_TEST=1` آزمون‌های زنده محافظت‌شده را فعال می‌کند. +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` به یک URL، کد، یا + `spaces/{id}` نگه‌داری‌شده Meet اشاره می‌کند. +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` یا `GOOGLE_MEET_CLIENT_ID` شناسه کلاینت OAuth را فراهم می‌کند. +- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` یا `GOOGLE_MEET_REFRESH_TOKEN` نشانه تازه‌سازی را فراهم می‌کند. - اختیاری: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`، - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN`، و - `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` از همان نام‌های fallback + `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` و + `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` از همان نام‌های جایگزین بدون پیشوند `OPENCLAW_` استفاده می‌کنند. -live smoke پایه artifact/attendance به +اسموک زنده پایه مصنوعات/حضور به `https://www.googleapis.com/auth/meetings.space.readonly` و -`https://www.googleapis.com/auth/meetings.conference.media.readonly` نیاز دارد. جست‌وجوی Calendar به `https://www.googleapis.com/auth/calendar.events.readonly` نیاز دارد. export متن document-body در Drive به +`https://www.googleapis.com/auth/meetings.conference.media.readonly` نیاز دارد. جست‌وجوی Calendar +به `https://www.googleapis.com/auth/calendar.events.readonly` نیاز دارد. خروجی گرفتن از +بدنه سند Drive به `https://www.googleapis.com/auth/drive.meet.readonly` نیاز دارد. -یک space تازه Meet ایجاد کنید: +یک فضای Meet تازه ایجاد کنید: ```bash openclaw googlemeet create ``` -این دستور `meeting uri` جدید، منبع، و نشست join را چاپ می‌کند. با اعتبارنامه‌های OAuth از Google Meet API رسمی استفاده می‌کند. بدون اعتبارنامه‌های OAuth از پروفایل مرورگر واردشده Node سنجاق‌شده Chrome به‌عنوان fallback استفاده می‌کند. agentها می‌توانند از ابزار `google_meet` با `action: "create"` برای ایجاد و join در یک مرحله استفاده کنند. برای ایجاد فقط URL، `"join": false` را پاس دهید. +فرمان `meeting uri` جدید، منبع، و نشست پیوستن را چاپ می‌کند. با اعتبارنامه‌های OAuth +از Google Meet API رسمی استفاده می‌کند. بدون اعتبارنامه‌های OAuth، +از پروفایل مرورگر واردشده گره Chrome سنجاق‌شده به‌عنوان جایگزین استفاده می‌کند. عامل‌ها می‌توانند +با `action: "create"` از ابزار `google_meet` برای ایجاد و پیوستن در یک +مرحله استفاده کنند. برای ایجاد فقط URL، `"join": false` را ارسال کنید. -نمونه خروجی JSON از fallback مرورگر: +نمونه خروجی JSON از جایگزین مرورگر: ```json { @@ -865,7 +950,9 @@ openclaw googlemeet create } ``` -اگر fallback مرورگر پیش از اینکه بتواند URL را ایجاد کند به مانع ورود Google یا مجوز Meet برخورد کند، متد Gateway یک پاسخ ناموفق برمی‌گرداند و ابزار `google_meet` به‌جای یک رشته ساده، جزئیات ساخت‌یافته برمی‌گرداند: +اگر جایگزین مرورگر پیش از آنکه بتواند URL را ایجاد کند به ورود Google یا مانع مجوز Meet برخورد کند، +متد Gateway پاسخی ناموفق برمی‌گرداند و ابزار +`google_meet` جزئیات ساختاریافته را به‌جای یک رشته ساده برمی‌گرداند: ```json { @@ -883,9 +970,11 @@ openclaw googlemeet create } ``` -وقتی agent مقدار `manualActionRequired: true` را می‌بیند، باید `manualActionMessage` به‌علاوه context مربوط به Node/زبانه مرورگر را گزارش کند و تا زمانی که operator مرحله مرورگر را کامل نکرده است، باز کردن زبانه‌های جدید Meet را متوقف کند. +وقتی یک عامل `manualActionRequired: true` را می‌بیند، باید +`manualActionMessage` را به‌همراه زمینه گره/زبانه مرورگر گزارش کند و تا زمانی که اپراتور مرحله مرورگر را کامل کند، +باز کردن زبانه‌های جدید Meet را متوقف کند. -نمونه خروجی JSON از create در API: +نمونه خروجی JSON از ایجاد API: ```json { @@ -906,14 +995,23 @@ openclaw googlemeet create } ``` -ایجاد Meet به‌طور پیش‌فرض join می‌کند. transport مربوط به Chrome یا Chrome-node همچنان برای join از طریق مرورگر به یک پروفایل Google Chrome واردشده نیاز دارد. اگر پروفایل خارج شده باشد، OpenClaw مقدار `manualActionRequired: true` یا یک خطای fallback مرورگر گزارش می‌کند و از operator می‌خواهد پیش از تلاش دوباره، ورود Google را کامل کند. +ایجاد یک Meet به‌صورت پیش‌فرض به جلسه می‌پیوندد. انتقال Chrome یا Chrome-node همچنان +برای پیوستن از طریق مرورگر به یک نمایه Google Chrome واردشده نیاز دارد. اگر +نمایه خارج شده باشد، OpenClaw مقدار `manualActionRequired: true` یا یک +خطای جایگزین مرورگر را گزارش می‌کند و از اپراتور می‌خواهد پیش از +تلاش دوباره، ورود به Google را کامل کند. -`preview.enrollmentAcknowledged: true` را فقط پس از تأیید اینکه پروژه Cloud، اصل OAuth، و شرکت‌کنندگان جلسه شما در Google Workspace Developer Preview Program برای APIهای رسانه‌ای Meet ثبت‌نام شده‌اند تنظیم کنید. +`preview.enrollmentAcknowledged: true` را فقط پس از تأیید این‌که پروژه Cloud، +اصل OAuth، و شرکت‌کنندگان جلسه شما در Google Workspace Developer Preview Program +برای APIهای رسانه Meet ثبت‌نام شده‌اند تنظیم کنید. ## پیکربندی -مسیر رایج agent در Chrome فقط به فعال بودن Plugin، BlackHole، SoX، یک کلید provider رونویسی realtime، و یک provider‏ TTS پیکربندی‌شده OpenClaw نیاز دارد. -OpenAI provider پیش‌فرض رونویسی است؛ برای استفاده از Google Gemini Live در حالت `bidi`، `realtime.provider: "google"` را تنظیم کنید: +مسیر رایج عامل Chrome فقط به فعال بودن Plugin، BlackHole، SoX، یک +کلید ارائه‌دهنده رونویسی بی‌درنگ، و یک ارائه‌دهنده TTS پیکربندی‌شده OpenClaw نیاز دارد. +OpenAI ارائه‌دهنده پیش‌فرض رونویسی است؛ برای استفاده از Google Gemini Live در حالت `bidi` +بدون تغییر ارائه‌دهنده پیش‌فرض رونویسی حالت عامل، `realtime.voiceProvider` را روی +`"google"` و `realtime.model` را تنظیم کنید: ```bash brew install blackhole-2ch sox @@ -940,33 +1038,58 @@ export GEMINI_API_KEY=... پیش‌فرض‌ها: - `defaultTransport: "chrome"` -- `defaultMode: "agent"` (`"realtime"` به‌عنوان نام مستعار سازگاری برای - `"agent"` پذیرفته می‌شود) +- `defaultMode: "agent"` (`"realtime"` فقط به‌عنوان یک نام مستعار سازگاری قدیمی + برای `"agent"` پذیرفته می‌شود؛ فراخوانی‌های جدید ابزار باید `"agent"` بگویند) - `chromeNode.node`: شناسه/نام/IP اختیاری Node برای `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: نامی که در صفحه مهمان Meet بدون ورود به حساب استفاده می‌شود -- `chrome.autoJoin: true`: پر کردن نام مهمان و کلیک روی Join Now به‌صورت بهترین تلاش از طریق خودکارسازی مرورگر OpenClaw روی `chrome-node` -- `chrome.reuseExistingTab: true`: فعال کردن تب Meet موجود به‌جای +- `chrome.guestName: "OpenClaw Agent"`: نامی که در صفحه مهمان خارج‌شده Meet + استفاده می‌شود +- `chrome.autoJoin: true`: تکمیل نام مهمان و کلیک روی Join Now به‌صورت بهترین‌تلاش + از طریق خودکارسازی مرورگر OpenClaw روی `chrome-node` +- `chrome.reuseExistingTab: true`: فعال‌سازی یک برگه موجود Meet به‌جای باز کردن موارد تکراری -- `chrome.waitForInCallMs: 20000`: انتظار برای اینکه تب Meet پیش از فعال شدن معرفی بلادرنگ، وضعیت درون‌تماس را گزارش کند -- `chrome.audioFormat: "pcm16-24khz"`: قالب صوتی جفت‌فرمان. فقط برای جفت‌فرمان‌های قدیمی/سفارشی که هنوز صدای تلفنی تولید می‌کنند از - `"g711-ulaw-8khz"` استفاده کنید. +- `chrome.waitForInCallMs: 20000`: انتظار برای این‌که برگه Meet پیش از + فعال شدن معرفی گفت‌وگوی برگشتی، وضعیت حضور در تماس را گزارش کند +- `chrome.audioFormat: "pcm16-24khz"`: قالب صوتی جفت‌فرمان. از + `"g711-ulaw-8khz"` فقط برای جفت‌فرمان‌های قدیمی/سفارشی استفاده کنید که هنوز + صوت تلفنی تولید می‌کنند. +- `chrome.audioBufferBytes: 4096`: بافر پردازش SoX برای فرمان‌های صوتی + جفت‌فرمان Chrome تولیدشده. این مقدار نصف بافر پیش‌فرض 8192 بایتی SoX است، + که تأخیر پیش‌فرض لوله را کاهش می‌دهد و در عین حال امکان افزایش آن را روی میزبان‌های شلوغ باقی می‌گذارد. + مقادیر کمتر از حداقل SoX به 17 بایت محدود می‌شوند. - `chrome.audioInputCommand`: فرمان SoX که از CoreAudio `BlackHole 2ch` - می‌خواند و صدا را در `chrome.audioFormat` می‌نویسد -- `chrome.audioOutputCommand`: فرمان SoX که صدا را در `chrome.audioFormat` - می‌خواند و در CoreAudio `BlackHole 2ch` می‌نویسد -- `chrome.bargeInInputCommand`: فرمان اختیاری میکروفون محلی که برای تشخیص ورود گفتار انسان در حین پخش دستیار، PCM مونو little-endian امضادار ۱۶ بیتی می‌نویسد. این مورد در حال حاضر برای پل جفت‌فرمان `chrome` میزبانی‌شده در Gateway اعمال می‌شود. -- `chrome.bargeInRmsThreshold: 650`: سطح RMS که در `chrome.bargeInInputCommand` به‌عنوان وقفه انسانی حساب می‌شود -- `chrome.bargeInPeakThreshold: 2500`: سطح پیک که در `chrome.bargeInInputCommand` به‌عنوان وقفه انسانی حساب می‌شود -- `chrome.bargeInCooldownMs: 900`: حداقل تأخیر بین پاک‌سازی‌های تکراری وقفه انسانی -- `mode: "agent"`: حالت پیش‌فرض پاسخ‌گویی صوتی. گفتار شرکت‌کننده توسط ارائه‌دهنده رونویسی بلادرنگ پیکربندی‌شده رونویسی می‌شود، به عامل OpenClaw پیکربندی‌شده در یک نشست زیرعامل برای هر جلسه ارسال می‌شود و از طریق زمان اجرای معمول TTS در OpenClaw به گفتار برگردانده می‌شود. -- `mode: "bidi"`: حالت جایگزین مستقیم مدل بلادرنگ دوطرفه. ارائه‌دهنده صدای بلادرنگ مستقیما به گفتار شرکت‌کننده پاسخ می‌دهد و ممکن است برای پاسخ‌های عمیق‌تر/پشتوانه‌دار با ابزار، `openclaw_agent_consult` را فراخوانی کند. -- `mode: "transcribe"`: حالت فقط مشاهده بدون پل پاسخ‌گویی صوتی. -- `realtime.provider: "openai"`: شناسه ارائه‌دهنده‌ای که حالت `agent` برای رونویسی بلادرنگ و حالت `bidi` برای صدای بلادرنگ استفاده می‌کند. + می‌خواند و صوت را در `chrome.audioFormat` می‌نویسد +- `chrome.audioOutputCommand`: فرمان SoX که صوت را در `chrome.audioFormat` + می‌خواند و به CoreAudio `BlackHole 2ch` می‌نویسد +- `chrome.bargeInInputCommand`: فرمان اختیاری میکروفون محلی که برای تشخیص ورود گفتار انسان + هنگام فعال بودن پخش دستیار، PCM مونو 16 بیتی little-endian علامت‌دار می‌نویسد. + این در حال حاضر برای پل جفت‌فرمان `chrome` میزبانی‌شده در Gateway اعمال می‌شود. +- `chrome.bargeInRmsThreshold: 650`: سطح RMS که در + `chrome.bargeInInputCommand` به‌عنوان وقفه انسانی شمرده می‌شود +- `chrome.bargeInPeakThreshold: 2500`: سطح اوج که در + `chrome.bargeInInputCommand` به‌عنوان وقفه انسانی شمرده می‌شود +- `chrome.bargeInCooldownMs: 900`: حداقل تأخیر بین پاک‌سازی‌های تکراری + وقفه انسانی +- `mode: "agent"`: حالت پیش‌فرض گفت‌وگوی برگشتی. گفتار شرکت‌کننده توسط + ارائه‌دهنده رونویسی بی‌درنگ پیکربندی‌شده رونویسی می‌شود، به عامل + پیکربندی‌شده OpenClaw در یک نشست زیرعامل برای هر جلسه فرستاده می‌شود، و از طریق + زمان‌اجرای عادی TTS OpenClaw بازگو می‌شود. +- `mode: "bidi"`: حالت جایگزین مدل بی‌درنگ دوسویه مستقیم. ارائه‌دهنده + صدای بی‌درنگ مستقیماً به گفتار شرکت‌کننده پاسخ می‌دهد و ممکن است برای + پاسخ‌های عمیق‌تر/پشتیبانی‌شده با ابزار `openclaw_agent_consult` را فراخوانی کند. +- `mode: "transcribe"`: حالت فقط مشاهده بدون پل گفت‌وگوی برگشتی. +- `realtime.provider: "openai"`: جایگزین سازگاری که وقتی فیلدهای ارائه‌دهنده + محدوده‌دار زیر تنظیم نشده‌اند استفاده می‌شود. +- `realtime.transcriptionProvider: "openai"`: شناسه ارائه‌دهنده‌ای که حالت `agent` + برای رونویسی بی‌درنگ استفاده می‌کند. +- `realtime.voiceProvider`: شناسه ارائه‌دهنده‌ای که حالت `bidi` برای صدای + بی‌درنگ مستقیم استفاده می‌کند. برای استفاده از Gemini Live در حالی که رونویسی + حالت عامل روی OpenAI باقی می‌ماند، این را روی `"google"` تنظیم کنید. - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: پاسخ‌های گفتاری کوتاه، همراه با `openclaw_agent_consult` برای پاسخ‌های عمیق‌تر -- `realtime.introMessage`: بررسی کوتاه گفتاری آمادگی هنگام اتصال پل بلادرنگ؛ برای ورود بی‌صدا آن را روی `""` بگذارید +- `realtime.introMessage`: بررسی آمادگی گفتاری کوتاه هنگام اتصال پل بی‌درنگ؛ + آن را روی `""` تنظیم کنید تا بی‌صدا بپیوندد - `realtime.agentId`: شناسه اختیاری عامل OpenClaw برای `openclaw_agent_consult`؛ مقدار پیش‌فرض `main` است @@ -1007,13 +1130,15 @@ export GEMINI_API_KEY=... }, defaultMode: "agent", realtime: { - provider: "google", + provider: "openai", + transcriptionProvider: "openai", + voiceProvider: "google", + model: "gemini-2.5-flash-native-audio-preview-12-2025", agentId: "jay", toolPolicy: "owner", introMessage: "Say exactly: I'm here.", providers: { google: { - model: "gemini-2.5-flash-native-audio-preview-12-2025", voice: "Kore", }, }, @@ -1021,6 +1146,50 @@ export GEMINI_API_KEY=... } ``` +ElevenLabs برای گوش دادن و صحبت کردن در حالت عامل: + +```json5 +{ + messages: { + tts: { + provider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "eleven_v3", + voiceId: "pMsXgVXv3BLzUgSXRplE", + }, + }, + }, + }, + plugins: { + entries: { + "google-meet": { + config: { + realtime: { + transcriptionProvider: "elevenlabs", + providers: { + elevenlabs: { + modelId: "scribe_v2_realtime", + audioFormat: "ulaw_8000", + sampleRate: 8000, + commitStrategy: "vad", + }, + }, + }, + }, + }, + }, + }, +} +``` + +صدای پایدار Meet از +`messages.tts.providers.elevenlabs.voiceId` می‌آید. پاسخ‌های عامل همچنین می‌توانند از +دستورهای ویژه هر پاسخ مانند `[[tts:voiceId=... model=eleven_v3]]` استفاده کنند، +وقتی بازنویسی‌های مدل TTS فعال باشند، اما پیکربندی پیش‌فرض قطعی برای جلسه‌ها است. +هنگام پیوستن، گزارش‌ها باید `transcriptionProvider=elevenlabs` را نشان دهند و هر +پاسخ گفتاری باید `provider=elevenlabs model=eleven_v3 voice=` را ثبت کند. + پیکربندی فقط Twilio: ```json5 @@ -1036,7 +1205,12 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` به‌صورت پیش‌فرض `true` است؛ با انتقال Twilio، تماس واقعی PSTN، DTMF و خوشامدگویی آغازین را به Plugin تماس صوتی واگذار می‌کند. تماس صوتی پیش از باز کردن جریان رسانه بلادرنگ، توالی DTMF را پخش می‌کند و سپس از متن معرفی ذخیره‌شده به‌عنوان خوشامدگویی اولیه بلادرنگ استفاده می‌کند. اگر `voice-call` فعال نباشد، Google Meet همچنان می‌تواند طرح شماره‌گیری را اعتبارسنجی و ثبت کند، اما نمی‌تواند تماس Twilio را برقرار کند. +مقدار پیش‌فرض `voiceCall.enabled` برابر `true` است؛ با انتقال Twilio، تماس +واقعی PSTN، DTMF، و خوشامدگویی آغازین را به Plugin تماس صوتی واگذار می‌کند. تماس صوتی +پیش از باز کردن جریان رسانه بی‌درنگ، توالی DTMF را پخش می‌کند، سپس از متن +آغازین ذخیره‌شده به‌عنوان خوشامدگویی بی‌درنگ اولیه استفاده می‌کند. اگر `voice-call` +فعال نباشد، Google Meet همچنان می‌تواند طرح شماره‌گیری را اعتبارسنجی و ثبت کند، +اما نمی‌تواند تماس Twilio را برقرار کند. ## ابزار @@ -1051,25 +1225,46 @@ export GEMINI_API_KEY=... } ``` -وقتی Chrome روی میزبان Gateway اجرا می‌شود از `transport: "chrome"` استفاده کنید. وقتی Chrome روی یک Node جفت‌شده مانند VM Parallels اجرا می‌شود از -`transport: "chrome-node"` استفاده کنید. در هر دو حالت، ارائه‌دهندگان مدل و `openclaw_agent_consult` روی میزبان Gateway اجرا می‌شوند، بنابراین اعتبارنامه‌های مدل همان‌جا باقی می‌مانند. با `mode: "agent"` پیش‌فرض، ارائه‌دهنده رونویسی بلادرنگ گوش دادن را انجام می‌دهد، عامل OpenClaw پیکربندی‌شده پاسخ را تولید می‌کند و TTS معمول OpenClaw آن را در Meet پخش می‌کند. وقتی می‌خواهید مدل صدای بلادرنگ مستقیما پاسخ دهد از +وقتی Chrome روی میزبان Gateway اجرا می‌شود از `transport: "chrome"` استفاده کنید. وقتی +Chrome روی یک Node جفت‌شده مانند VM Parallels اجرا می‌شود از +`transport: "chrome-node"` استفاده کنید. در هر دو حالت، ارائه‌دهندگان مدل و +`openclaw_agent_consult` روی میزبان Gateway اجرا می‌شوند، بنابراین اعتبارنامه‌های مدل همان‌جا می‌مانند. +با `mode: "agent"` پیش‌فرض، ارائه‌دهنده رونویسی بی‌درنگ گوش دادن را انجام می‌دهد، +عامل پیکربندی‌شده OpenClaw پاسخ را تولید می‌کند، و TTS عادی OpenClaw آن را در Meet +پخش می‌کند. وقتی می‌خواهید مدل صدای بی‌درنگ مستقیماً پاسخ دهد از `mode: "bidi"` استفاده کنید. -`mode: "realtime"` همچنان به‌عنوان نام مستعار سازگاری برای -`mode: "agent"` پذیرفته می‌شود. +`mode: "realtime"` خام همچنان به‌عنوان نام مستعار سازگاری قدیمی برای +`mode: "agent"` پذیرفته می‌شود، اما دیگر در شِمای ابزار عامل تبلیغ نمی‌شود. +گزارش‌های حالت عامل در زمان راه‌اندازی پل، ارائه‌دهنده/مدل رونویسی حل‌شده را +و پس از هر پاسخ ساخته‌شده، ارائه‌دهنده TTS، مدل، صدا، قالب خروجی، و نرخ نمونه‌برداری را شامل می‌شوند. -از `action: "status"` برای فهرست کردن نشست‌های فعال یا بررسی یک شناسه نشست استفاده کنید. از `action: "speak"` همراه با `sessionId` و `message` استفاده کنید تا عامل بلادرنگ فورا صحبت کند. از `action: "test_speech"` برای ایجاد یا استفاده مجدد از نشست، فعال کردن یک عبارت شناخته‌شده و برگرداندن سلامت `inCall` وقتی میزبان Chrome بتواند آن را گزارش کند استفاده کنید. `test_speech` همیشه `mode: "agent"` را اجباری می‌کند و اگر درخواست شود در -`mode: "transcribe"` اجرا شود شکست می‌خورد، چون نشست‌های فقط مشاهده عمدا نمی‌توانند گفتار منتشر کنند. نتیجه `speechOutputVerified` آن بر اساس افزایش بایت‌های خروجی صدای بلادرنگ در طول این تماس آزمایشی است، بنابراین نشست استفاده‌شده مجدد با صدای قدیمی‌تر به‌عنوان بررسی گفتار موفق تازه حساب نمی‌شود. از `action: "leave"` برای علامت‌گذاری پایان نشست استفاده کنید. +برای فهرست کردن نشست‌های فعال یا بررسی شناسه نشست از `action: "status"` استفاده کنید. از +`action: "speak"` همراه با `sessionId` و `message` استفاده کنید تا عامل بی‌درنگ +فوراً صحبت کند. برای ایجاد یا استفاده دوباره از نشست، فعال‌سازی یک عبارت شناخته‌شده، +و بازگرداندن سلامت `inCall` وقتی میزبان Chrome بتواند آن را گزارش کند، از +`action: "test_speech"` استفاده کنید. `test_speech` همیشه `mode: "agent"` را اجبار می‌کند +و اگر خواسته شود در `mode: "transcribe"` اجرا شود شکست می‌خورد، چون نشست‌های فقط مشاهده +عمداً نمی‌توانند گفتار تولید کنند. نتیجه `speechOutputVerified` آن بر پایه افزایش +بایت‌های خروجی صوت بی‌درنگ در طول این فراخوانی آزمایشی است، بنابراین یک نشست +استفاده‌شده دوباره با صوت قدیمی‌تر، به‌عنوان بررسی گفتار تازه و موفق شمرده نمی‌شود. +برای علامت‌گذاری پایان نشست از `action: "leave"` استفاده کنید. -`status` در صورت دسترس بودن، سلامت Chrome را شامل می‌شود: +وقتی در دسترس باشد، `status` سلامت Chrome را شامل می‌شود: - `inCall`: به نظر می‌رسد Chrome داخل تماس Meet است -- `micMuted`: وضعیت میکروفون Meet به‌صورت بهترین تلاش -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: نمایه مرورگر پیش از کار کردن گفتار به ورود دستی، پذیرش توسط میزبان Meet، مجوزها یا تعمیر کنترل مرورگر نیاز دارد -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: آیا گفتار Chrome مدیریت‌شده اکنون مجاز است یا نه. `speechReady: false` یعنی OpenClaw عبارت معرفی/آزمایش را به پل صوتی ارسال نکرد. -- `providerConnected` / `realtimeReady`: وضعیت پل صدای بلادرنگ -- `lastInputAt` / `lastOutputAt`: آخرین صدای دیده‌شده از پل یا ارسال‌شده به آن -- `audioOutputRouted` / `audioOutputDeviceLabel`: آیا خروجی رسانه تب Meet به‌صورت فعال به دستگاه BlackHole استفاده‌شده توسط پل هدایت شده است یا نه -- `lastSuppressedInputAt` / `suppressedInputBytes`: ورودی loopback که هنگام فعال بودن پخش دستیار نادیده گرفته شده است +- `micMuted`: وضعیت میکروفون Meet به‌صورت بهترین‌تلاش +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: نمایه + مرورگر پیش از کار کردن گفتار به ورود دستی، پذیرش توسط میزبان Meet، مجوزها، یا + تعمیر کنترل مرورگر نیاز دارد +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: این‌که آیا + گفتار مدیریت‌شده Chrome اکنون مجاز است. `speechReady: false` یعنی OpenClaw + عبارت آغازین/آزمایشی را به پل صوتی نفرستاده است. +- `providerConnected` / `realtimeReady`: وضعیت پل صدای بی‌درنگ +- `lastInputAt` / `lastOutputAt`: آخرین صوت دیده‌شده از پل یا فرستاده‌شده به آن +- `audioOutputRouted` / `audioOutputDeviceLabel`: این‌که آیا خروجی رسانه برگه Meet + به‌طور فعال به دستگاه BlackHole استفاده‌شده توسط پل هدایت شده است +- `lastSuppressedInputAt` / `suppressedInputBytes`: ورودی loopback که هنگام فعال بودن + پخش دستیار نادیده گرفته شده است ```json { @@ -1081,40 +1276,59 @@ export GEMINI_API_KEY=... ## حالت‌های عامل و Bidi -حالت `agent` در Chrome برای رفتار «عامل من در جلسه است» بهینه شده است. ارائه‌دهنده رونویسی بلادرنگ صدای جلسه را می‌شنود، رونویسی‌های نهایی شرکت‌کننده از طریق عامل OpenClaw پیکربندی‌شده هدایت می‌شوند و پاسخ از طریق زمان اجرای معمول TTS در OpenClaw گفته می‌شود. وقتی می‌خواهید مدل صدای بلادرنگ مستقیما پاسخ دهد، `mode: "bidi"` را تنظیم کنید. -قطعه‌های نزدیک رونویسی نهایی پیش از مشاوره با هم ادغام می‌شوند تا یک نوبت گفتاری چند پاسخ جزئی کهنه تولید نکند. ورودی بلادرنگ همچنین تا زمانی که صدای صف‌شده دستیار هنوز در حال پخش است سرکوب می‌شود، -و پژواک‌های اخیر رونویسی شبیه دستیار پیش از مشاوره عامل نادیده گرفته می‌شوند تا loopback مربوط به BlackHole باعث نشود عامل به گفتار خودش پاسخ دهد. +حالت `agent` در Chrome برای رفتار «عامل من در جلسه است» بهینه شده است. ارائه‌دهنده +رونویسی بی‌درنگ صدای جلسه را می‌شنود، رونوشت‌های نهایی شرکت‌کنندگان از طریق عامل +پیکربندی‌شده OpenClaw مسیریابی می‌شوند، و پاسخ از طریق زمان‌اجرای عادی TTS OpenClaw +گفته می‌شود. وقتی می‌خواهید مدل صدای بی‌درنگ مستقیماً پاسخ دهد، `mode: "bidi"` را تنظیم کنید. +قطعه‌های رونوشت نهایی نزدیک به هم پیش از مشورت ادغام می‌شوند تا یک نوبت گفتاری +چند پاسخ جزئی کهنه تولید نکند. ورودی بی‌درنگ همچنین هنگام پخش شدن صوت دستیار +در صف سرکوب می‌شود، +و پژواک‌های اخیر رونوشت شبیه دستیار پیش از مشورت عامل نادیده گرفته می‌شوند +تا loopback مربوط به BlackHole باعث نشود عامل به گفتار خودش پاسخ دهد. | حالت | چه کسی پاسخ را تعیین می‌کند | مسیر خروجی گفتار | زمان استفاده | | ------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------- | -| `agent` | عامل OpenClaw پیکربندی‌شده | زمان اجرای معمول TTS در OpenClaw | وقتی رفتار «عامل من در جلسه است» را می‌خواهید | -| `bidi` | مدل صدای بلادرنگ | پاسخ صوتی ارائه‌دهنده صدای بلادرنگ | وقتی حلقه مکالمه صوتی با کمترین تأخیر را می‌خواهید | +| `agent` | عامل پیکربندی‌شده OpenClaw | زمان‌اجرای عادی TTS OpenClaw | رفتار «عامل من در جلسه است» را می‌خواهید | +| `bidi` | مدل صدای بی‌درنگ | پاسخ صوتی ارائه‌دهنده صدای بی‌درنگ | کم‌تأخیرترین چرخه صدای مکالمه‌ای را می‌خواهید | -در حالت `bidi`، وقتی مدل بلادرنگ به استدلال عمیق‌تر، اطلاعات فعلی یا ابزارهای معمول OpenClaw نیاز دارد، می‌تواند `openclaw_agent_consult` را فراخوانی کند. +در حالت `bidi`، وقتی مدل بی‌درنگ به استدلال عمیق‌تر، اطلاعات فعلی، یا ابزارهای عادی OpenClaw +نیاز داشته باشد، می‌تواند `openclaw_agent_consult` را فراخوانی کند. -ابزار مشاوره در پشت صحنه عامل معمول OpenClaw را با زمینه رونویسی اخیر جلسه اجرا می‌کند و یک پاسخ گفتاری مختصر برمی‌گرداند. در حالت `agent`، OpenClaw آن پاسخ را مستقیما به زمان اجرای TTS ارسال می‌کند؛ در حالت `bidi`، مدل صدای بلادرنگ می‌تواند نتیجه مشاوره را دوباره در جلسه بگوید. این مورد از همان سازوکار مشترک مشاوره Voice Call استفاده می‌کند. +ابزار مشاوره، عامل معمولی OpenClaw را پشت صحنه با زمینهٔ رونوشت اخیر +جلسه اجرا می‌کند و یک پاسخ گفتاری کوتاه برمی‌گرداند. در حالت `agent`، +OpenClaw آن پاسخ را مستقیم به زمان‌اجرای TTS می‌فرستد؛ در حالت `bidi`، مدل +صدای بلادرنگ می‌تواند نتیجهٔ مشاوره را دوباره در جلسه بیان کند. این ابزار از +همان سازوکار مشاورهٔ مشترک تماس صوتی استفاده می‌کند. -به‌صورت پیش‌فرض، مشاوره‌ها روی عامل `main` اجرا می‌شوند. وقتی یک مسیر Meet باید با یک فضای کاری اختصاصی عامل OpenClaw، پیش‌فرض‌های مدل، سیاست ابزار، حافظه و تاریخچه نشست مشورت کند، `realtime.agentId` را تنظیم کنید. +به‌طور پیش‌فرض، مشاوره‌ها روی عامل `main` اجرا می‌شوند. وقتی یک مسیر Meet باید +با یک فضای کاری عامل OpenClaw اختصاصی، پیش‌فرض‌های مدل، سیاست ابزار، حافظه و +تاریخچهٔ نشست مشاوره کند، `realtime.agentId` را تنظیم کنید. -مشاوره‌های حالت عامل از کلید نشست `agent::subagent:google-meet:` برای هر جلسه استفاده می‌کنند تا پرسش‌های بعدی ضمن به‌ارث بردن سیاست معمول عامل از عامل پیکربندی‌شده، زمینه جلسه را حفظ کنند. +مشاوره‌های حالت عامل از کلید نشست جداگانهٔ هر جلسه +`agent::subagent:google-meet:` استفاده می‌کنند تا پرسش‌های +پیگیری، ضمن به ارث بردن سیاست معمول عامل از عامل پیکربندی‌شده، زمینهٔ جلسه را +حفظ کنند. `realtime.toolPolicy` اجرای مشاوره را کنترل می‌کند: -- `safe-read-only`: ابزار مشاوره را در دسترس قرار می‌دهد و عامل معمول را به +- `safe-read-only`: ابزار مشاوره را در دسترس قرار می‌دهد و عامل معمولی را به `read`، `web_search`، `web_fetch`، `x_search`، `memory_search` و `memory_get` محدود می‌کند. -- `owner`: ابزار مشاوره را در دسترس قرار می‌دهد و به عامل معمول اجازه می‌دهد از سیاست ابزار معمول عامل استفاده کند. +- `owner`: ابزار مشاوره را در دسترس قرار می‌دهد و اجازه می‌دهد عامل معمولی از + سیاست ابزار معمول عامل استفاده کند. - `none`: ابزار مشاوره را در اختیار مدل صدای بلادرنگ قرار نمی‌دهد. -کلید نشست مشاوره برای هر نشست Meet محدود شده است، بنابراین فراخوانی‌های مشاوره بعدی می‌توانند در همان جلسه از زمینه مشاوره قبلی دوباره استفاده کنند. +کلید نشست مشاوره برای هر نشست Meet محدود شده است، بنابراین فراخوانی‌های +مشاورهٔ پیگیری می‌توانند در همان جلسه از زمینهٔ مشاورهٔ قبلی دوباره استفاده +کنند. -برای اجبار یک بررسی آمادگی گفتاری پس از اینکه Chrome کاملا وارد تماس شد: +برای اجبار به بررسی آمادگی گفتاری پس از اینکه Chrome کاملا به تماس پیوست: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -برای آزمون کامل پیوستن و گفتار: +برای آزمون دود کامل پیوستن و صحبت کردن: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1122,7 +1336,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## چک‌لیست آزمایش زنده +## فهرست بررسی آزمون زنده پیش از سپردن جلسه به یک عامل بدون نظارت، از این توالی استفاده کنید: @@ -1137,13 +1351,16 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ وضعیت مورد انتظار Chrome-node: - `googlemeet setup` کاملا سبز است. -- وقتی Chrome-node انتقال پیش‌فرض است یا یک Node سنجاق شده است، `googlemeet setup` شامل `chrome-node-connected` می‌شود. -- `nodes status` نشان می‌دهد Node انتخاب‌شده متصل است. -- Node انتخاب‌شده هر دو قابلیت `googlemeet.chrome` و `browser.proxy` را اعلام می‌کند. -- تب Meet به تماس می‌پیوندد و `test-speech` سلامت Chrome را با +- وقتی Chrome-node انتقال پیش‌فرض است یا یک گره پین شده است، `googlemeet setup` + شامل `chrome-node-connected` می‌شود. +- `nodes status` نشان می‌دهد گره انتخاب‌شده متصل است. +- گره انتخاب‌شده هر دو قابلیت `googlemeet.chrome` و `browser.proxy` را اعلام + می‌کند. +- زبانهٔ Meet به تماس می‌پیوندد و `test-speech` سلامت Chrome را با `inCall: true` برمی‌گرداند. -برای یک میزبان Chrome راه‌دور مانند VM macOS در Parallels، این کوتاه‌ترین بررسی امن پس از به‌روزرسانی Gateway یا VM است: +برای یک میزبان Chrome دوردست مانند ماشین مجازی macOS در Parallels، این +کوتاه‌ترین بررسی امن پس از به‌روزرسانی Gateway یا ماشین مجازی است: ```bash openclaw googlemeet setup @@ -1154,9 +1371,12 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -این ثابت می‌کند که Plugin مربوط به Gateway بارگذاری شده است، Node مربوط به VM با توکن فعلی متصل است و پل صوتی Meet پیش از اینکه یک عامل تب جلسه واقعی را باز کند در دسترس است. +این ثابت می‌کند Plugin مربوط به Gateway بارگذاری شده، گره ماشین مجازی با توکن +فعلی متصل است، و پل صوتی Meet پیش از باز کردن یک زبانهٔ جلسهٔ واقعی توسط عامل +در دسترس است. -برای آزمون Twilio، از جلسه‌ای استفاده کنید که جزئیات شماره‌گیری تلفنی را نشان می‌دهد: +برای آزمون دود Twilio، از جلسه‌ای استفاده کنید که جزئیات شماره‌گیری تلفنی را +ارائه می‌دهد: ```bash openclaw googlemeet setup @@ -1168,38 +1388,41 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ وضعیت مورد انتظار Twilio: -- `googlemeet setup` بررسی‌های سبز `twilio-voice-call-plugin`، - `twilio-voice-call-credentials`، و `twilio-voice-call-webhook` را شامل می‌شود. -- `voicecall` پس از بارگذاری دوباره Gateway در CLI در دسترس است. -- نشست بازگردانده‌شده دارای `transport: "twilio"` و یک `twilio.voiceCallId` است. -- `openclaw logs --follow` نشان می‌دهد TwiML مربوط به DTMF پیش از TwiML بلادرنگ ارائه شده، سپس یک - پل بلادرنگ با خوشامدگویی اولیه در صف قرار گرفته است. -- `googlemeet leave ` تماس صوتی تفویض‌شده را قطع می‌کند. +- `googlemeet setup` شامل بررسی‌های سبز `twilio-voice-call-plugin`، + `twilio-voice-call-credentials` و `twilio-voice-call-webhook` است. +- پس از بارگذاری دوبارهٔ Gateway، `voicecall` در CLI در دسترس است. +- نشست برگشتی `transport: "twilio"` و یک `twilio.voiceCallId` دارد. +- `openclaw logs --follow` نشان می‌دهد TwiML مربوط به DTMF پیش از TwiML + بلادرنگ ارائه شده، سپس یک پل بلادرنگ با خوشامدگویی اولیه در صف قرار گرفته + است. +- `googlemeet leave ` تماس صوتی واگذارشده را قطع می‌کند. ## عیب‌یابی ### عامل نمی‌تواند ابزار Google Meet را ببیند -تأیید کنید Plugin در پیکربندی Gateway فعال است و Gateway را دوباره بارگذاری کنید: +تأیید کنید Plugin در پیکربندی Gateway فعال است و Gateway را دوباره بارگذاری +کنید: ```bash openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -اگر همین الان `plugins.entries.google-meet` را ویرایش کرده‌اید، Gateway را راه‌اندازی مجدد یا دوباره بارگذاری کنید. -عامل در حال اجرا فقط ابزارهای Plugin را می‌بیند که توسط فرایند فعلی Gateway -ثبت شده‌اند. +اگر به‌تازگی `plugins.entries.google-meet` را ویرایش کرده‌اید، Gateway را +بازراه‌اندازی یا دوباره بارگذاری کنید. عامل در حال اجرا فقط ابزارهای Plugin را +می‌بیند که توسط فرایند فعلی Gateway ثبت شده‌اند. -روی میزبان‌های Gateway غیر از macOS، ابزار روبه‌روی عامل `google_meet` همچنان قابل مشاهده می‌ماند، -اما اقدامات پاسخ صوتی Chrome محلی پیش از رسیدن به پل صوتی مسدود می‌شوند. -صدای پاسخ صوتی Chrome محلی در حال حاضر به `BlackHole 2ch` در macOS وابسته است، بنابراین -عامل‌های Linux باید به‌جای مسیر پیش‌فرض عامل Chrome محلی از `mode: "transcribe"`، تماس ورودی Twilio، یا یک میزبان -`chrome-node` مبتنی بر macOS استفاده کنند. +روی میزبان‌های Gateway غیر macOS، ابزار روبه‌عامل `google_meet` همچنان قابل +مشاهده می‌ماند، اما کنش‌های گفت‌وگوی برگشتی Chrome محلی پیش از رسیدن به پل +صوتی مسدود می‌شوند. صدای گفت‌وگوی برگشتی Chrome محلی در حال حاضر به +`BlackHole 2ch` در macOS وابسته است، بنابراین عامل‌های Linux باید به جای مسیر +عامل Chrome محلی پیش‌فرض، از `mode: "transcribe"`، شماره‌گیری Twilio، یا یک +میزبان `chrome-node` روی macOS استفاده کنند. -### هیچ Node سازگار با Google Meet متصل نیست +### هیچ گره متصلِ دارای قابلیت Google Meet وجود ندارد -روی میزبان Node، اجرا کنید: +روی میزبان گره، اجرا کنید: ```bash openclaw plugins enable google-meet @@ -1208,7 +1431,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -روی میزبان Gateway، Node را تأیید کنید و فرمان‌ها را بررسی کنید: +روی میزبان Gateway، گره را تأیید و فرمان‌ها را بررسی کنید: ```bash openclaw devices list @@ -1216,8 +1439,8 @@ openclaw devices approve openclaw nodes status ``` -Node باید متصل باشد و `googlemeet.chrome` به‌همراه `browser.proxy` را فهرست کند. -پیکربندی Gateway باید آن فرمان‌های Node را مجاز کند: +گره باید متصل باشد و `googlemeet.chrome` به‌علاوهٔ `browser.proxy` را فهرست +کند. پیکربندی Gateway باید اجازهٔ آن فرمان‌های گره را بدهد: ```json5 { @@ -1230,7 +1453,8 @@ Node باید متصل باشد و `googlemeet.chrome` به‌همراه `browse ``` اگر `googlemeet setup` در `chrome-node-connected` شکست خورد یا گزارش Gateway -`gateway token mismatch` را نشان داد، Node را با توکن فعلی Gateway دوباره نصب یا راه‌اندازی مجدد کنید. برای یک Gateway در LAN این معمولاً یعنی: +عبارت `gateway token mismatch` را نشان داد، گره را با توکن فعلی Gateway دوباره +نصب یا بازراه‌اندازی کنید. برای یک Gateway روی LAN، این معمولا یعنی: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1241,63 +1465,68 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -سپس سرویس Node را دوباره بارگذاری کنید و دوباره اجرا کنید: +سپس سرویس گره را دوباره بارگذاری کنید و دوباره اجرا کنید: ```bash openclaw googlemeet setup openclaw nodes status --connected ``` -### مرورگر باز می‌شود اما عامل نمی‌تواند وارد شود +### مرورگر باز می‌شود اما عامل نمی‌تواند بپیوندد -برای ورودهای فقط مشاهده، `googlemeet test-listen` را اجرا کنید، یا برای ورودهای بلادرنگ -`googlemeet test-speech` را اجرا کنید، سپس سلامت Chrome بازگردانده‌شده را بررسی کنید. اگر هرکدام از آزمون‌ها +برای پیوستن‌های فقط مشاهده، `googlemeet test-listen` را اجرا کنید، یا برای +پیوستن‌های بلادرنگ، `googlemeet test-speech` را اجرا کنید؛ سپس سلامت Chrome +برگشتی را بررسی کنید. اگر هر یک از این کاوش‌ها `manualActionRequired: true` را گزارش کرد، `manualActionMessage` را به اپراتور -نشان دهید و تا کامل شدن اقدام مرورگر از تلاش مجدد خودداری کنید. +نشان دهید و تا کامل شدن کنش مرورگر، تلاش دوباره را متوقف کنید. -اقدامات دستی رایج: +کنش‌های دستی رایج: -- به نمایه Chrome وارد شوید. +- به نمایهٔ Chrome وارد شوید. - مهمان را از حساب میزبان Meet بپذیرید. -- وقتی اعلان مجوز بومی Chrome ظاهر شد، مجوزهای میکروفون/دوربین Chrome را بدهید. -- گفت‌وگوی گیرکرده مجوز Meet را ببندید یا اصلاح کنید. +- وقتی درخواست مجوز بومی Chrome ظاهر شد، مجوزهای میکروفون/دوربین Chrome را + بدهید. +- یک گفت‌وگوی مجوز Meet گیرکرده را ببندید یا تعمیر کنید. -صرفاً به این دلیل که Meet نشان می‌دهد "Do you want people to -hear you in the meeting?"، «وارد نشده» گزارش نکنید. این صفحه میانی انتخاب صدا در Meet است؛ OpenClaw -در صورت امکان از طریق خودکارسازی مرورگر روی **Use microphone** کلیک می‌کند و منتظر -وضعیت واقعی جلسه می‌ماند. برای جایگزین مرورگر فقط-ایجاد، OpenClaw -ممکن است روی **Continue without microphone** کلیک کند، چون ایجاد URL به مسیر صدای بلادرنگ نیاز ندارد. +صرفا به این دلیل که Meet نشان می‌دهد «Do you want people to hear you in the +meeting?» گزارش «وارد نشده‌اید» ندهید. این میان‌پردهٔ انتخاب صوت Meet است؛ +OpenClaw وقتی در دسترس باشد، از طریق خودکارسازی مرورگر روی **Use microphone** +کلیک می‌کند و همچنان منتظر وضعیت واقعی جلسه می‌ماند. برای جایگزین مرورگر فقط +برای ایجاد، OpenClaw ممکن است روی **Continue without microphone** کلیک کند، +زیرا ایجاد URL به مسیر صوتی بلادرنگ نیاز ندارد. ### ایجاد جلسه شکست می‌خورد -`googlemeet create` ابتدا وقتی اعتبارنامه‌های OAuth پیکربندی شده باشند از endpoint -`spaces.create` در Google Meet API استفاده می‌کند. بدون اعتبارنامه‌های OAuth، به مرورگر Node ثابت‌شده Chrome برمی‌گردد. -تأیید کنید: +`googlemeet create` ابتدا وقتی اعتبارنامه‌های OAuth پیکربندی شده باشند از +نقطهٔ پایانی Google Meet API یعنی `spaces.create` استفاده می‌کند. بدون +اعتبارنامه‌های OAuth، به مرورگر گره Chrome پین‌شده برمی‌گردد. تأیید کنید: -- برای ایجاد از طریق API: `oauth.clientId` و `oauth.refreshToken` پیکربندی شده‌اند، - یا متغیرهای محیطی مطابق `OPENCLAW_GOOGLE_MEET_*` وجود دارند. -- برای ایجاد از طریق API: توکن تازه‌سازی پس از افزوده شدن پشتیبانی ایجاد صادر شده باشد. - توکن‌های قدیمی‌تر ممکن است scope مربوط به `meetings.space.created` را نداشته باشند؛ - `openclaw googlemeet auth login --json` را دوباره اجرا کنید و پیکربندی Plugin را به‌روزرسانی کنید. -- برای جایگزین مرورگر: `defaultTransport: "chrome-node"` و - `chromeNode.node` به یک Node متصل با `browser.proxy` و - `googlemeet.chrome` اشاره می‌کنند. -- برای جایگزین مرورگر: نمایه Chrome متعلق به OpenClaw روی آن Node به Google وارد شده است - و می‌تواند `https://meet.google.com/new` را باز کند. -- برای جایگزین مرورگر: تلاش‌های مجدد پیش از باز کردن زبانه جدید، از یک - `https://meet.google.com/new` موجود یا زبانه اعلان حساب Google استفاده می‌کنند. اگر عامل timeout شد، - به‌جای باز کردن دستی یک زبانه دیگر Meet، فراخوانی ابزار را دوباره تلاش کنید. -- برای جایگزین مرورگر: اگر ابزار `manualActionRequired: true` بازگرداند، از - `browser.nodeId`، `browser.targetId`، `browserUrl`، و - `manualActionMessage` بازگردانده‌شده برای راهنمایی اپراتور استفاده کنید. تا کامل شدن آن - اقدام، در حلقه تلاش مجدد نکنید. -- برای جایگزین مرورگر: اگر Meet نشان داد "Do you want people to hear you in the - meeting?"، زبانه را باز نگه دارید. OpenClaw باید از طریق خودکارسازی مرورگر روی **Use microphone** یا، برای - جایگزین فقط-ایجاد، روی **Continue without microphone** کلیک کند - و همچنان منتظر URL تولیدشده Meet بماند. اگر نتواند، خطا باید به - `meet-audio-choice-required` اشاره کند، نه `google-login-required`. +- برای ایجاد از طریق API: `oauth.clientId` و `oauth.refreshToken` پیکربندی + شده‌اند، یا متغیرهای محیطی مطابق `OPENCLAW_GOOGLE_MEET_*` وجود دارند. +- برای ایجاد از طریق API: توکن تازه‌سازی پس از اضافه شدن پشتیبانی ایجاد صادر + شده است. توکن‌های قدیمی‌تر ممکن است دامنهٔ `meetings.space.created` را + نداشته باشند؛ `openclaw googlemeet auth login --json` را دوباره اجرا کنید و + پیکربندی Plugin را به‌روزرسانی کنید. +- برای جایگزین مرورگر: `defaultTransport: "chrome-node"` و `chromeNode.node` به + گره متصلی اشاره می‌کنند که `browser.proxy` و `googlemeet.chrome` دارد. +- برای جایگزین مرورگر: نمایهٔ OpenClaw Chrome روی آن گره به Google وارد شده + است و می‌تواند `https://meet.google.com/new` را باز کند. +- برای جایگزین مرورگر: تلاش‌های دوباره پیش از باز کردن زبانهٔ جدید، از یک + زبانهٔ موجود `https://meet.google.com/new` یا درخواست حساب Google دوباره + استفاده می‌کنند. اگر مهلت عامل تمام شد، به جای باز کردن دستی یک زبانهٔ Meet + دیگر، فراخوانی ابزار را دوباره تلاش کنید. +- برای جایگزین مرورگر: اگر ابزار `manualActionRequired: true` را برگرداند، از + `browser.nodeId`، `browser.targetId`، `browserUrl` و + `manualActionMessage` برگشتی برای راهنمایی اپراتور استفاده کنید. تا کامل شدن + آن کنش، در یک حلقه دوباره تلاش نکنید. +- برای جایگزین مرورگر: اگر Meet نشان می‌دهد «Do you want people to hear you in + the meeting?» زبانه را باز نگه دارید. OpenClaw باید از طریق خودکارسازی مرورگر + روی **Use microphone** یا، برای جایگزین فقط ایجاد، روی **Continue without + microphone** کلیک کند و به انتظار برای URL ایجادشدهٔ Meet ادامه دهد. اگر + نتواند، خطا باید به `meet-audio-choice-required` اشاره کند، نه + `google-login-required`. -### عامل وارد می‌شود اما صحبت نمی‌کند +### عامل می‌پیوندد اما صحبت نمی‌کند مسیر بلادرنگ را بررسی کنید: @@ -1306,61 +1535,65 @@ openclaw googlemeet setup openclaw googlemeet doctor ``` -برای مسیر عادی STT -> عامل OpenClaw -> پاسخ صوتی TTS از `mode: "agent"` استفاده کنید، -یا برای جایگزین مستقیم صدای بلادرنگ از `mode: "bidi"` استفاده کنید. `mode: "transcribe"` -عمداً پل پاسخ صوتی را شروع نمی‌کند. برای اشکال‌زدایی فقط مشاهده، -پس از صحبت کردن شرکت‌کنندگان، `openclaw googlemeet status --json ` را اجرا کنید -و `captioning`، `transcriptLines`، و `lastCaptionText` را بررسی کنید. اگر `inCall` -true است اما `transcriptLines` روی `0` می‌ماند، ممکن است زیرنویس‌های Meet غیرفعال باشند، از زمان نصب مشاهده‌گر کسی -صحبت نکرده باشد، UI Meet تغییر کرده باشد، یا زیرنویس زنده برای زبان/حساب جلسه -در دسترس نباشد. +برای مسیر معمول گفت‌وگوی برگشتی STT -> عامل OpenClaw -> TTS از +`mode: "agent"` استفاده کنید، یا برای جایگزین صدای بلادرنگ مستقیم از +`mode: "bidi"` استفاده کنید. `mode: "transcribe"` عمدا پل گفت‌وگوی برگشتی را +شروع نمی‌کند. برای اشکال‌زدایی فقط مشاهده، پس از صحبت کردن شرکت‌کنندگان، +`openclaw googlemeet status --json ` را اجرا کنید و `captioning`، +`transcriptLines` و `lastCaptionText` را بررسی کنید. اگر `inCall` برابر true +است اما `transcriptLines` روی `0` می‌ماند، ممکن است زیرنویس‌های Meet غیرفعال +باشند، از زمان نصب مشاهده‌گر کسی صحبت نکرده باشد، رابط کاربری Meet تغییر کرده +باشد، یا زیرنویس زنده برای زبان/حساب جلسه در دسترس نباشد. -`googlemeet test-speech` همیشه مسیر بلادرنگ را بررسی می‌کند و گزارش می‌دهد که آیا -برای آن فراخوانی، بایت‌های خروجی پل مشاهده شده‌اند یا نه. اگر `speechOutputVerified` false و -`speechOutputTimedOut` true باشد، ارائه‌دهنده بلادرنگ ممکن است -گفتار را پذیرفته باشد اما OpenClaw ندیده باشد که بایت‌های خروجی جدید به پل صوتی Chrome -برسند. +`googlemeet test-speech` همیشه مسیر بلادرنگ را بررسی می‌کند و گزارش می‌دهد آیا +برای آن فراخوانی، بایت‌های خروجی پل مشاهده شده‌اند یا نه. اگر +`speechOutputVerified` برابر false و `speechOutputTimedOut` برابر true باشد، +ارائه‌دهندهٔ بلادرنگ ممکن است گفتار را پذیرفته باشد اما OpenClaw بایت‌های +خروجی تازه‌ای را ندیده که به پل صوتی Chrome برسند. همچنین بررسی کنید: -- یک کلید ارائه‌دهنده بلادرنگ روی میزبان Gateway در دسترس باشد، مانند +- یک کلید ارائه‌دهندهٔ بلادرنگ روی میزبان Gateway در دسترس است، مانند `OPENAI_API_KEY` یا `GEMINI_API_KEY`. -- `BlackHole 2ch` روی میزبان Chrome قابل مشاهده باشد. -- `sox` روی میزبان Chrome وجود داشته باشد. -- میکروفون و بلندگوی Meet از مسیر صدای مجازی استفاده‌شده توسط - OpenClaw عبور داده شده باشند. برای ورودهای بلادرنگ Chrome محلی، - `doctor` باید `meet output routed: yes` را نشان دهد. +- `BlackHole 2ch` روی میزبان Chrome قابل مشاهده است. +- `sox` روی میزبان Chrome وجود دارد. +- میکروفون و بلندگوی Meet از مسیر صوتی مجازی مورد استفادهٔ OpenClaw عبور داده + شده‌اند. برای پیوستن‌های بلادرنگ Chrome محلی، `doctor` باید + `meet output routed: yes` را نشان دهد. -`googlemeet doctor [session-id]` نشست، Node، وضعیت در تماس بودن، -دلیل اقدام دستی، اتصال ارائه‌دهنده بلادرنگ، `realtimeReady`، فعالیت -ورودی/خروجی صدا، آخرین timestampهای صدا، شمارنده‌های بایت، و URL مرورگر را چاپ می‌کند. -وقتی به JSON خام نیاز دارید از `googlemeet status [session-id] --json` استفاده کنید. وقتی +`googlemeet doctor [session-id]` نشست، گره، وضعیت داخل تماس، دلیل کنش دستی، +اتصال ارائه‌دهندهٔ بلادرنگ، `realtimeReady`، فعالیت ورودی/خروجی صوتی، آخرین +مهرهای زمانی صوت، شمارنده‌های بایت و URL مرورگر را چاپ می‌کند. وقتی به JSON +خام نیاز دارید از `googlemeet status [session-id] --json` استفاده کنید. وقتی باید تازه‌سازی OAuth مربوط به Google Meet را بدون افشای توکن‌ها بررسی کنید از -`googlemeet doctor --oauth` استفاده کنید؛ وقتی به اثبات Google Meet API نیز نیاز دارید -`--meeting` یا `--create-space` را اضافه کنید. +`googlemeet doctor --oauth` استفاده کنید؛ وقتی به اثبات Google Meet API هم +نیاز دارید، `--meeting` یا `--create-space` را اضافه کنید. -اگر عامل timeout شد و می‌توانید ببینید که یک زبانه Meet از قبل باز است، آن زبانه را -بدون باز کردن زبانه دیگر بررسی کنید: +اگر مهلت عامل تمام شده و می‌بینید که یک زبانهٔ Meet از قبل باز است، همان زبانه +را بدون باز کردن زبانه‌ای دیگر بررسی کنید: ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -اقدام ابزار معادل `recover_current_tab` است. این اقدام یک زبانه موجود Meet را برای انتقال انتخاب‌شده -در کانون قرار می‌دهد و بررسی می‌کند. با `chrome`، از کنترل مرورگر محلی از طریق Gateway استفاده می‌کند؛ با `chrome-node`، -از Node پیکربندی‌شده Chrome استفاده می‌کند. زبانه جدید باز نمی‌کند یا نشست جدید نمی‌سازد؛ -مسدودکننده فعلی را گزارش می‌دهد، مانند ورود، پذیرش، مجوزها، یا وضعیت انتخاب صدا. -فرمان CLI با Gateway پیکربندی‌شده صحبت می‌کند، پس Gateway باید در حال اجرا باشد؛ -`chrome-node` همچنین نیاز دارد Node مربوط به Chrome متصل باشد. +کنش ابزار معادل `recover_current_tab` است. این کنش یک زبانهٔ Meet موجود را برای +انتقال انتخاب‌شده متمرکز و بررسی می‌کند. با `chrome`، از کنترل مرورگر محلی از +طریق Gateway استفاده می‌کند؛ با `chrome-node`، از گره Chrome پیکربندی‌شده +استفاده می‌کند. زبانهٔ جدید باز نمی‌کند و نشست جدید نمی‌سازد؛ مانع فعلی را +گزارش می‌دهد، مانند وضعیت ورود، پذیرش، مجوزها یا انتخاب صوت. فرمان CLI با +Gateway پیکربندی‌شده صحبت می‌کند، بنابراین Gateway باید در حال اجرا باشد؛ +`chrome-node` همچنین نیاز دارد گره Chrome متصل باشد. ### بررسی‌های راه‌اندازی Twilio شکست می‌خورند -`twilio-voice-call-plugin` وقتی `voice-call` مجاز یا فعال نباشد شکست می‌خورد. -آن را به `plugins.allow` اضافه کنید، `plugins.entries.voice-call` را فعال کنید، و Gateway را دوباره بارگذاری کنید. +وقتی `voice-call` مجاز یا فعال نباشد، `twilio-voice-call-plugin` شکست می‌خورد. +آن را به `plugins.allow` اضافه کنید، `plugins.entries.voice-call` را فعال کنید +و Gateway را دوباره بارگذاری کنید. -`twilio-voice-call-credentials` وقتی backend مربوط به Twilio فاقد SID حساب، -توکن auth، یا شماره تماس‌گیرنده باشد شکست می‌خورد. این‌ها را روی میزبان Gateway تنظیم کنید: +وقتی پشتیبان Twilio شناسهٔ حساب، توکن احراز هویت یا شمارهٔ تماس‌گیرنده را +نداشته باشد، `twilio-voice-call-credentials` شکست می‌خورد. این‌ها را روی +میزبان Gateway تنظیم کنید: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1368,14 +1601,15 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`twilio-voice-call-webhook` وقتی `voice-call` در معرض Webhook عمومی نباشد، -یا وقتی `publicUrl` به loopback یا فضای شبکه خصوصی اشاره کند، شکست می‌خورد. -`plugins.entries.voice-call.config.publicUrl` را روی URL عمومی ارائه‌دهنده تنظیم کنید یا -یک tunnel/نمایانی Tailscale برای `voice-call` پیکربندی کنید. +وقتی `voice-call` در معرض Webhook عمومی نباشد، یا وقتی `publicUrl` به local loopback +یا فضای شبکهٔ خصوصی اشاره کند، `twilio-voice-call-webhook` شکست می‌خورد. +`plugins.entries.voice-call.config.publicUrl` را روی URL عمومی ارائه‌دهنده +تنظیم کنید یا یک تونل/نمایش Tailscale برای `voice-call` پیکربندی کنید. -URLهای loopback و خصوصی برای callbackهای carrier معتبر نیستند. از +URLهای loopback و خصوصی برای callbackهای اپراتور مخابراتی معتبر نیستند. از `localhost`، `127.0.0.1`، `0.0.0.0`، `10.x`، `172.16.x`-`172.31.x`، -`192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به‌عنوان `publicUrl` استفاده نکنید. +`192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به عنوان `publicUrl` +استفاده نکنید. برای یک URL عمومی پایدار: @@ -1396,7 +1630,7 @@ URLهای loopback و خصوصی برای callbackهای carrier معتبر نی } ``` -برای توسعه محلی، به‌جای URL میزبان خصوصی از tunnel یا نمایانی Tailscale استفاده کنید: +برای توسعهٔ محلی، به‌جای URL میزبان خصوصی، از تونل یا در معرض‌گذاری Tailscale استفاده کنید: ```json5 { @@ -1414,7 +1648,7 @@ URLهای loopback و خصوصی برای callbackهای carrier معتبر نی } ``` -سپس Gateway را راه‌اندازی مجدد یا دوباره بارگذاری کنید و اجرا کنید: +سپس Gateway را بازراه‌اندازی یا بازبارگذاری کنید و اجرا کنید: ```bash openclaw googlemeet setup --transport twilio @@ -1422,7 +1656,7 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` به‌طور پیش‌فرض فقط آمادگی را بررسی می‌کند. برای اجرای آزمایشی یک شماره مشخص: +`voicecall smoke` به‌صورت پیش‌فرض فقط آمادگی را بررسی می‌کند. برای اجرای آزمایشی یک شمارهٔ مشخص بدون برقراری تماس واقعی: ```bash openclaw voicecall smoke --to "+15555550123" @@ -1436,8 +1670,7 @@ openclaw voicecall smoke --to "+15555550123" --yes ### تماس Twilio شروع می‌شود اما هرگز وارد جلسه نمی‌شود -تأیید کنید رویداد Meet جزئیات تماس تلفنی ورودی را ارائه می‌کند. شماره دقیق تماس ورودی -و PIN یا یک توالی DTMF سفارشی را بدهید: +تأیید کنید که رویداد Meet جزئیات تماس تلفنی ورودی را ارائه می‌کند. شمارهٔ دقیق تماس ورودی و PIN یا یک توالی DTMF سفارشی را بدهید: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1446,56 +1679,40 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -اگر ارائه‌دهنده پیش از وارد کردن PIN به مکث نیاز دارد، از `w` ابتدایی یا ویرگول‌ها در -`--dtmf-sequence` استفاده کنید. +اگر ارائه‌دهنده پیش از وارد کردن PIN به مکث نیاز دارد، در `--dtmf-sequence` از `w` ابتدایی یا ویرگول استفاده کنید. -اگر تماس تلفنی ساخته شد اما فهرست شرکت‌کنندگان Meet هرگز شرکت‌کننده تماس ورودی را نشان نداد: +اگر تماس تلفنی ایجاد می‌شود اما فهرست اعضای Meet هرگز شرکت‌کنندهٔ تماس ورودی را نشان نمی‌دهد: -- `openclaw googlemeet doctor ` را اجرا کنید تا ID تماس Twilio تفویض‌شده، - اینکه DTMF در صف بوده یا نه، و اینکه خوشامدگویی آغازین درخواست شده یا نه را تأیید کنید. -- `openclaw voicecall status --call-id ` را اجرا کنید و تأیید کنید تماس همچنان - فعال است. -- `openclaw voicecall tail` را اجرا کنید و بررسی کنید Webhookهای Twilio به - Gateway می‌رسند. -- `openclaw logs --follow` را اجرا کنید و به‌دنبال توالی Twilio Meet بگردید: Google - Meet ورود را تفویض می‌کند، Voice Call مسیر تلفنی را شروع می‌کند، Google Meet - `voiceCall.dtmfDelayMs` صبر می‌کند، با `voicecall.dtmf` DTMF می‌فرستد، - `voiceCall.postDtmfSpeechDelayMs` صبر می‌کند، سپس با - `voicecall.speak` گفتار آغازین را درخواست می‌کند. -- `openclaw googlemeet setup --transport twilio` را دوباره اجرا کنید؛ بررسی سبز راه‌اندازی - لازم است اما ثابت نمی‌کند توالی PIN جلسه درست است. -- تأیید کنید شماره تماس ورودی به همان دعوت‌نامه و منطقه Meet مربوط به PIN تعلق دارد. -- اگر Meet کند پاسخ می‌دهد یا transcript تماس پس از ارسال DTMF همچنان - اعلان درخواست PIN را نشان می‌دهد، `voiceCall.dtmfDelayMs` را افزایش دهید. -- اگر شرکت‌کننده وارد شد اما خوشامدگویی را نمی‌شنوید، در - `openclaw logs --follow` درخواست پس از DTMF مربوط به `voicecall.speak` و - پخش TTS از طریق media-stream یا جایگزین Twilio `` را بررسی کنید. اگر transcript تماس - همچنان شامل "enter the meeting PIN" است، مسیر تلفنی هنوز وارد اتاق Meet نشده است، - پس شرکت‌کنندگان جلسه گفتار را نخواهند شنید. +- `openclaw googlemeet doctor ` را اجرا کنید تا شناسهٔ تماس Twilio واگذارشده، اینکه آیا DTMF در صف قرار گرفته است، و اینکه آیا پیام خوشامدگویی درخواستی ثبت شده است یا نه را تأیید کنید. +- `openclaw voicecall status --call-id ` را اجرا کنید و تأیید کنید که تماس هنوز فعال است. +- `openclaw voicecall tail` را اجرا کنید و بررسی کنید که Webhookهای Twilio به Gateway می‌رسند. +- `openclaw logs --follow` را اجرا کنید و دنبال توالی Twilio Meet بگردید: Google Meet پیوستن را واگذار می‌کند، Voice Call بخش تلفنی را شروع می‌کند، Google Meet به‌اندازهٔ `voiceCall.dtmfDelayMs` صبر می‌کند، DTMF را با `voicecall.dtmf` می‌فرستد، به‌اندازهٔ `voiceCall.postDtmfSpeechDelayMs` صبر می‌کند، سپس با `voicecall.speak` گفتار معرفی را درخواست می‌کند. +- `openclaw googlemeet setup --transport twilio` را دوباره اجرا کنید؛ بررسی راه‌اندازی سبز لازم است، اما درست بودن توالی PIN جلسه را ثابت نمی‌کند. +- تأیید کنید شمارهٔ تماس ورودی متعلق به همان دعوت‌نامه و منطقهٔ Meet مربوط به PIN است. +- اگر Meet کند پاسخ می‌دهد یا رونوشت تماس هنوز پس از ارسال DTMF درخواست PIN را نشان می‌دهد، `voiceCall.dtmfDelayMs` را افزایش دهید. +- اگر شرکت‌کننده وارد می‌شود اما پیام خوشامدگویی را نمی‌شنوید، در `openclaw logs --follow` درخواست `voicecall.speak` پس از DTMF و سپس پخش TTS جریان رسانه یا جایگزین `` در Twilio را بررسی کنید. اگر رونوشت تماس هنوز شامل "enter the meeting PIN" است، بخش تلفنی هنوز به اتاق Meet نپیوسته است، بنابراین شرکت‌کنندگان جلسه گفتار را نخواهند شنید. -اگر Webhookها نمی‌رسند، ابتدا Voice Call Plugin را عیب‌یابی کنید: ارائه‌دهنده باید به `plugins.entries.voice-call.config.publicUrl` یا تونل پیکربندی‌شده دسترسی داشته باشد. -[عیب‌یابی تماس صوتی](/fa/plugins/voice-call#troubleshooting) را ببینید. +اگر Webhookها نمی‌رسند، ابتدا Plugin تماس صوتی را اشکال‌زدایی کنید: ارائه‌دهنده باید بتواند به `plugins.entries.voice-call.config.publicUrl` یا تونل پیکربندی‌شده دسترسی پیدا کند. [عیب‌یابی تماس صوتی](/fa/plugins/voice-call#troubleshooting) را ببینید. ## یادداشت‌ها -API رسمی رسانه‌ای Google Meet دریافت‌محور است، بنابراین صحبت کردن در یک تماس Meet همچنان به یک مسیر شرکت‌کننده نیاز دارد. این Plugin این مرز را آشکار نگه می‌دارد: -Chrome مشارکت مرورگر و مسیریابی صوت محلی را مدیریت می‌کند؛ Twilio مشارکت شماره‌گیری تلفنی را مدیریت می‌کند. +API رسانهٔ رسمی Google Meet دریافت‌محور است، بنابراین صحبت کردن داخل تماس Meet همچنان به مسیر شرکت‌کننده نیاز دارد. این Plugin این مرز را شفاف نگه می‌دارد: Chrome مشارکت مرورگر و مسیریابی صوتی محلی را مدیریت می‌کند؛ Twilio مشارکت تماس ورودی تلفنی را مدیریت می‌کند. -حالت‌های پاسخ‌گویی صوتی Chrome به `BlackHole 2ch` به‌علاوه یکی از موارد زیر نیاز دارند: +حالت‌های پاسخ‌گویی Chrome به `BlackHole 2ch` به‌علاوهٔ یکی از این موارد نیاز دارند: -- `chrome.audioInputCommand` به‌همراه `chrome.audioOutputCommand`: OpenClaw مالک پل است و صوت را با `chrome.audioFormat` بین این دستورها و ارائه‌دهنده انتخاب‌شده لوله‌کشی می‌کند. حالت agent از رونویسی بی‌درنگ به‌همراه TTS معمولی استفاده می‌کند؛ حالت bidi از ارائه‌دهنده صدای بی‌درنگ استفاده می‌کند. مسیر پیش‌فرض Chrome برابر با PCM16 با نرخ 24 کیلوهرتز است؛ G.711 mu-law با نرخ 8 کیلوهرتز همچنان برای جفت‌دستورهای قدیمی در دسترس است. -- `chrome.audioBridgeCommand`: یک دستور پل خارجی مالک کل مسیر صوت محلی است و باید پس از راه‌اندازی یا اعتبارسنجی daemon خود خارج شود. این فقط برای `bidi` معتبر است، زیرا حالت `agent` برای TTS به دسترسی مستقیم جفت‌دستور نیاز دارد. +- `chrome.audioInputCommand` به‌علاوهٔ `chrome.audioOutputCommand`: OpenClaw مالک پل است و صدا را با `chrome.audioFormat` بین آن فرمان‌ها و ارائه‌دهندهٔ انتخاب‌شده لوله‌کشی می‌کند. حالت agent از رونویسی بلادرنگ به‌علاوهٔ TTS معمولی استفاده می‌کند؛ حالت bidi از ارائه‌دهندهٔ صدای بلادرنگ استفاده می‌کند. مسیر پیش‌فرض Chrome برابر با PCM16 با 24 kHz و `chrome.audioBufferBytes: 4096` است؛ G.711 mu-law با 8 kHz همچنان برای جفت‌فرمان‌های قدیمی در دسترس است. +- `chrome.audioBridgeCommand`: یک فرمان پل خارجی مالک کل مسیر صوتی محلی است و باید پس از شروع یا اعتبارسنجی daemon خود خارج شود. این فقط برای `bidi` معتبر است، چون حالت `agent` برای TTS به دسترسی مستقیم جفت‌فرمان نیاز دارد. -برای صوت دوطرفه تمیز، خروجی Meet و میکروفون Meet را از طریق دستگاه‌های مجازی جداگانه یا یک گراف دستگاه مجازی به سبک Loopback مسیریابی کنید. یک دستگاه BlackHole مشترک واحد می‌تواند صدای دیگر شرکت‌کنندگان را دوباره به تماس بازتاب دهد. +وقتی یک عامل ابزار `google_meet` را در حالت agent فراخوانی می‌کند، نشست مشاور جلسه پیش از پاسخ دادن به گفتار شرکت‌کننده، رونوشت فعلی فراخواننده را fork می‌کند. نشست Meet همچنان جدا می‌ماند (`agent::subagent:google-meet:`) تا پیگیری‌های جلسه مستقیماً رونوشت فراخواننده را تغییر ندهند. -با پل Chrome مبتنی بر جفت‌دستور، `chrome.bargeInInputCommand` می‌تواند به یک میکروفون محلی جداگانه گوش دهد و وقتی انسان شروع به صحبت می‌کند، پخش دستیار را پاک کند. این کار گفتار انسان را حتی وقتی ورودی local loopback مشترک BlackHole هنگام پخش دستیار موقتاً سرکوب شده است، جلوتر از خروجی دستیار نگه می‌دارد. -مانند `chrome.audioInputCommand` و `chrome.audioOutputCommand`، این یک دستور محلی پیکربندی‌شده توسط اپراتور است. از یک مسیر دستور یا فهرست آرگومان صریح و مورداعتماد استفاده کنید و آن را به اسکریپت‌های مکان‌های نامطمئن اشاره ندهید. +برای صدای دوسویهٔ تمیز، خروجی Meet و میکروفن Meet را از طریق دستگاه‌های مجازی جداگانه یا یک گراف دستگاه مجازی سبک Loopback مسیریابی کنید. یک دستگاه مشترک BlackHole می‌تواند صدای دیگر شرکت‌کنندگان را دوباره به تماس بازتاب دهد. -`googlemeet speak` پل صوتی پاسخ‌گویی فعال را برای یک نشست Chrome فعال می‌کند. `googlemeet leave` آن پل را متوقف می‌کند. برای نشست‌های Twilio که از طریق Voice Call Plugin واگذار شده‌اند، `leave` تماس صوتی زیربنایی را نیز قطع می‌کند. -وقتی می‌خواهید کنفرانس فعال Google Meet را نیز برای یک فضای مدیریت‌شده با API ببندید، از `googlemeet end-active-conference` استفاده کنید. +با پل Chrome مبتنی بر جفت‌فرمان، `chrome.bargeInInputCommand` می‌تواند به یک میکروفن محلی جداگانه گوش دهد و وقتی انسان شروع به صحبت می‌کند، پخش دستیار را پاک کند. این باعث می‌شود گفتار انسان حتی زمانی که ورودی مشترک BlackHole loopback هنگام پخش دستیار موقتاً سرکوب شده است، جلوتر از خروجی دستیار بماند. مانند `chrome.audioInputCommand` و `chrome.audioOutputCommand`، این یک فرمان محلی پیکربندی‌شده توسط اپراتور است. از مسیر فرمان یا فهرست آرگومان صریح و مورد اعتماد استفاده کنید و آن را به اسکریپت‌هایی از مکان‌های نامطمئن اشاره ندهید. + +`googlemeet speak` پل صوتی پاسخ‌گویی فعال را برای یک نشست Chrome فعال می‌کند. `googlemeet leave` آن پل را متوقف می‌کند. برای نشست‌های Twilio که از طریق Plugin تماس صوتی واگذار شده‌اند، `leave` تماس صوتی زیربنایی را هم قطع می‌کند. وقتی می‌خواهید کنفرانس فعال Google Meet را هم برای یک فضای مدیریت‌شده با API ببندید، از `googlemeet end-active-conference` استفاده کنید. ## مرتبط -- [Voice Call Plugin](/fa/plugins/voice-call) -- [حالت گفت‌وگو](/fa/nodes/talk) +- [Plugin تماس صوتی](/fa/plugins/voice-call) +- [حالت گفتگو](/fa/nodes/talk) - [ساخت Pluginها](/fa/plugins/building-plugins) diff --git a/docs/fa/plugins/voice-call.md b/docs/fa/plugins/voice-call.md index bd38091f3..2836cdb31 100644 --- a/docs/fa/plugins/voice-call.md +++ b/docs/fa/plugins/voice-call.md @@ -1,23 +1,23 @@ --- read_when: - - می‌خواهید از OpenClaw یک تماس صوتی خروجی برقرار کنید - - شما در حال پیکربندی یا توسعه Plugin تماس صوتی هستید - - به صدای بلادرنگ یا رونویسی جریانی در بستر تلفنی نیاز دارید + - می‌خواهید یک تماس صوتی خروجی از OpenClaw برقرار کنید + - در حال پیکربندی یا توسعهٔ Plugin تماس صوتی هستید + - به صدای بلادرنگ یا رونویسی جریانی در ارتباطات تلفنی نیاز دارید sidebarTitle: Voice call -summary: برقراری تماس‌های صوتی خروجی و پذیرش تماس‌های صوتی ورودی از طریق Twilio، Telnyx یا Plivo، با امکان اختیاری صدای بلادرنگ و رونویسی جریانی +summary: تماس‌های صوتی خروجی برقرار کنید و تماس‌های صوتی ورودی را از طریق Twilio، Telnyx یا Plivo بپذیرید، همراه با صدای بی‌درنگ و رونویسی جریانی اختیاری title: Plugin تماس صوتی x-i18n: - generated_at: "2026-05-02T22:24:09Z" + generated_at: "2026-05-04T07:06:59Z" model: gpt-5.5 provider: openai - source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a + source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857 source_path: plugins/voice-call.md workflow: 16 --- تماس‌های صوتی برای OpenClaw از طریق یک Plugin. از اعلان‌های خروجی، -گفت‌وگوهای چندمرحله‌ای، صدای بلادرنگ تمام‌دوطرفه، رونویسی -جریانی، و تماس‌های ورودی با سیاست‌های فهرست مجاز پشتیبانی می‌کند. +گفت‌وگوهای چندمرحله‌ای، صدای بلادرنگ تمام‌دوطرفه، رونویسی جریانی، +و تماس‌های ورودی با سیاست‌های فهرست مجاز پشتیبانی می‌کند. **ارائه‌دهندگان فعلی:** `twilio` (Programmable Voice + Media Streams)، `telnyx` (Call Control v2)، `plivo` (Voice API + XML transfer + GetInput @@ -25,22 +25,21 @@ speech)، `mock` (توسعه/بدون شبکه). Plugin تماس صوتی **داخل فرایند Gateway** اجرا می‌شود. اگر از یک -Gateway راه دور استفاده می‌کنید، Plugin را روی ماشینی که Gateway را اجرا -می‌کند نصب و پیکربندی کنید، سپس Gateway را بازراه‌اندازی کنید تا آن را -بارگذاری کند. +Gateway راه‌دور استفاده می‌کنید، Plugin را روی دستگاهی نصب و پیکربندی کنید +که Gateway را اجرا می‌کند، سپس Gateway را بازراه‌اندازی کنید تا آن را بارگذاری کند. ## شروع سریع - + - + ```bash openclaw plugins install @openclaw/voice-call ``` - + ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin openclaw plugins install "$PLUGIN_SRC" @@ -49,37 +48,37 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش - برای دنبال کردن برچسب انتشار رسمی فعلی، از بسته بدون نسخه استفاده کنید. - فقط زمانی یک نسخه دقیق را pin کنید که به نصب بازتولیدپذیر نیاز دارید. + برای دنبال‌کردن برچسب انتشار رسمی فعلی، از بستهٔ بدون نسخه استفاده کنید. فقط زمانی + نسخهٔ دقیق را پین کنید که به نصب بازتولیدپذیر نیاز دارید. - پس از آن Gateway را بازراه‌اندازی کنید تا Plugin بارگذاری شود. + سپس Gateway را بازراه‌اندازی کنید تا Plugin بارگذاری شود. - - پیکربندی را زیر `plugins.entries.voice-call.config` تنظیم کنید (برای شکل - کامل، [پیکربندی](#configuration) را در پایین ببینید). حداقل موارد لازم: - `provider`، اعتبارنامه‌های ارائه‌دهنده، `fromNumber`، و یک URL مربوط به - Webhook که به‌صورت عمومی قابل دسترسی باشد. + + پیکربندی را زیر `plugins.entries.voice-call.config` تنظیم کنید (برای شکل کامل، + [پیکربندی](#configuration) را در پایین ببینید). حداقل موارد لازم: + `provider`، اعتبارنامه‌های ارائه‌دهنده، `fromNumber`، و یک URL Webhook + که به‌صورت عمومی قابل دسترسی باشد. - + ```bash openclaw voicecall setup ``` - خروجی پیش‌فرض در لاگ‌های چت و ترمینال‌ها خواناست. فعال بودن - Plugin، اعتبارنامه‌های ارائه‌دهنده، در معرض دسترس بودن Webhook، و این را - بررسی می‌کند که فقط یک حالت صوتی (`streaming` یا `realtime`) فعال باشد. - برای اسکریپت‌ها از `--json` استفاده کنید. + خروجی پیش‌فرض در گزارش‌های چت و ترمینال‌ها خوانا است. فعال‌بودن + Plugin، اعتبارنامه‌های ارائه‌دهنده، در معرض‌بودن Webhook، و اینکه + فقط یک حالت صوتی (`streaming` یا `realtime`) فعال باشد را بررسی می‌کند. برای + اسکریپت‌ها از `--json` استفاده کنید. - + ```bash openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` - هر دو به‌صورت پیش‌فرض اجرای آزمایشی بدون اثر هستند. برای اینکه واقعا یک - تماس اعلان خروجی کوتاه برقرار شود، `--yes` را اضافه کنید: + هر دو به‌صورت پیش‌فرض اجرای خشک هستند. برای برقراری واقعی یک تماس اعلان خروجی + کوتاه، `--yes` را اضافه کنید: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -89,22 +88,21 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش -برای Twilio، Telnyx، و Plivo، راه‌اندازی باید به یک **URL عمومی Webhook** resolve شود. -اگر `publicUrl`، URL تونل، URL مربوط به Tailscale، یا fallback سرو، به loopback -یا فضای شبکه خصوصی resolve شود، راه‌اندازی به‌جای شروع ارائه‌دهنده‌ای که -نمی‌تواند Webhookهای اپراتور را دریافت کند، شکست می‌خورد. +برای Twilio، Telnyx، و Plivo، راه‌اندازی باید به یک **URL Webhook عمومی** برسد. +اگر `publicUrl`، URL تونل، URL Tailscale، یا جایگزین سرویس‌دهی +به loopback یا فضای شبکهٔ خصوصی resolve شود، راه‌اندازی به‌جای +شروع ارائه‌دهنده‌ای که نمی‌تواند Webhookهای حامل را دریافت کند، شکست می‌خورد. ## پیکربندی -اگر `enabled: true` باشد اما اعتبارنامه‌های ارائه‌دهنده انتخاب‌شده موجود -نباشد، شروع Gateway یک هشدار setup-incomplete همراه با کلیدهای مفقود لاگ -می‌کند و از شروع runtime صرف‌نظر می‌کند. فرمان‌ها، فراخوانی‌های RPC، و -ابزارهای agent همچنان هنگام استفاده، پیکربندی دقیق مفقود ارائه‌دهنده را -برمی‌گردانند. +اگر `enabled: true` باشد اما ارائه‌دهندهٔ انتخاب‌شده فاقد اعتبارنامه باشد، +شروع Gateway یک هشدار راه‌اندازی ناقص با کلیدهای مفقود ثبت می‌کند و +از شروع runtime صرف‌نظر می‌کند. فرمان‌ها، فراخوانی‌های RPC، و ابزارهای عامل همچنان +هنگام استفاده، پیکربندی دقیق مفقود ارائه‌دهنده را برمی‌گردانند. -اعتبارنامه‌های تماس صوتی SecretRefها را می‌پذیرند. `plugins.entries.voice-call.config.twilio.authToken`، `plugins.entries.voice-call.config.realtime.providers.*.apiKey`، `plugins.entries.voice-call.config.streaming.providers.*.apiKey`، و `plugins.entries.voice-call.config.tts.providers.*.apiKey` از طریق سطح استاندارد SecretRef resolve می‌شوند؛ [سطح اعتبارنامه SecretRef](/fa/reference/secretref-credential-surface) را ببینید. +اعتبارنامه‌های voice-call از SecretRefها پشتیبانی می‌کنند. `plugins.entries.voice-call.config.twilio.authToken`، `plugins.entries.voice-call.config.realtime.providers.*.apiKey`، `plugins.entries.voice-call.config.streaming.providers.*.apiKey`، و `plugins.entries.voice-call.config.tts.providers.*.apiKey` از طریق سطح استاندارد SecretRef resolve می‌شوند؛ [سطح اعتبارنامه SecretRef](/fa/reference/secretref-credential-surface) را ببینید. ```json5 @@ -177,31 +175,31 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش ``` - - - Twilio، Telnyx، و Plivo همگی به یک URL مربوط به Webhook نیاز دارند که **به‌صورت عمومی قابل دسترسی** باشد. - - `mock` یک ارائه‌دهنده توسعه محلی است (بدون فراخوانی شبکه). + + - Twilio، Telnyx، و Plivo همگی به یک URL Webhook **قابل دسترسی عمومی** نیاز دارند. + - `mock` یک ارائه‌دهندهٔ توسعهٔ محلی است (بدون فراخوانی شبکه). - Telnyx به `telnyx.publicKey` (یا `TELNYX_PUBLIC_KEY`) نیاز دارد مگر اینکه `skipSignatureVerification` برابر true باشد. - - `skipSignatureVerification` فقط برای تست محلی است. - - در سطح رایگان ngrok، `publicUrl` را روی URL دقیق ngrok تنظیم کنید؛ اعتبارسنجی امضا همیشه اعمال می‌شود. - - `tunnel.allowNgrokFreeTierLoopbackBypass: true` فقط زمانی به Twilio Webhookها با امضاهای نامعتبر اجازه می‌دهد که `tunnel.provider="ngrok"` و `serve.bind` برابر loopback باشد (عامل محلی ngrok). فقط برای توسعه محلی. - - URLهای سطح رایگان Ngrok ممکن است تغییر کنند یا رفتار میان‌صفحه اضافه کنند؛ اگر `publicUrl` جابه‌جا شود، امضاهای Twilio شکست می‌خورند. تولید: یک دامنه پایدار یا یک funnel در Tailscale را ترجیح دهید. + - `skipSignatureVerification` فقط برای آزمون محلی است. + - در سطح رایگان ngrok، `publicUrl` را روی URL دقیق ngrok تنظیم کنید؛ راستی‌آزمایی امضا همیشه اعمال می‌شود. + - `tunnel.allowNgrokFreeTierLoopbackBypass: true` به Webhookهای Twilio با امضاهای نامعتبر اجازه می‌دهد **فقط** وقتی `tunnel.provider="ngrok"` و `serve.bind` برابر loopback باشد (عامل محلی ngrok). فقط برای توسعهٔ محلی. + - URLهای سطح رایگان ngrok می‌توانند تغییر کنند یا رفتار میان‌برگه اضافه کنند؛ اگر `publicUrl` منحرف شود، امضاهای Twilio شکست می‌خورند. تولید: یک دامنهٔ پایدار یا funnel در Tailscale را ترجیح دهید. - - - `streaming.preStartTimeoutMs` سوکت‌هایی را می‌بندد که هرگز یک قاب `start` معتبر نمی‌فرستند. - - `streaming.maxPendingConnections` سقف کل سوکت‌های pre-start احرازنشده را تعیین می‌کند. - - `streaming.maxPendingConnectionsPerIp` سقف سوکت‌های pre-start احرازنشده را برای هر IP مبدأ تعیین می‌کند. - - `streaming.maxConnections` سقف کل سوکت‌های باز stream رسانه را تعیین می‌کند (در انتظار + فعال). + + - `streaming.preStartTimeoutMs` سوکت‌هایی را می‌بندد که هرگز یک فریم معتبر `start` ارسال نمی‌کنند. + - `streaming.maxPendingConnections` مجموع سوکت‌های پیش از شروعِ احرازنشده را محدود می‌کند. + - `streaming.maxPendingConnectionsPerIp` سوکت‌های پیش از شروعِ احرازنشده را به‌ازای هر IP مبدأ محدود می‌کند. + - `streaming.maxConnections` مجموع سوکت‌های باز جریان رسانه را محدود می‌کند (در انتظار + فعال). - - پیکربندی‌های قدیمی‌تر که از `provider: "log"`، `twilio.from`، یا کلیدهای - قدیمی `streaming.*` مربوط به OpenAI استفاده می‌کنند، با `openclaw doctor --fix` - بازنویسی می‌شوند. fallback زمان اجرا فعلا همچنان کلیدهای قدیمی voice-call را - می‌پذیرد، اما مسیر بازنویسی `openclaw doctor --fix` است و shim سازگاری + + پیکربندی‌های قدیمی‌تر که از `provider: "log"`، `twilio.from`، یا کلیدهای قدیمی + OpenAI در `streaming.*` استفاده می‌کنند، با `openclaw doctor --fix` بازنویسی می‌شوند. + جایگزین runtime فعلاً همچنان کلیدهای قدیمی voice-call را می‌پذیرد، اما + مسیر بازنویسی `openclaw doctor --fix` است و shim سازگاری موقتی است. - کلیدهای جریانی مهاجرت‌شده خودکار: + کلیدهای streaming که به‌صورت خودکار مهاجرت می‌شوند: - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -212,53 +210,56 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش -## دامنه جلسه +## دامنهٔ نشست -به‌صورت پیش‌فرض، تماس صوتی از `sessionScope: "per-phone"` استفاده می‌کند تا -تماس‌های تکراری از همان تماس‌گیرنده حافظه گفت‌وگو را حفظ کنند. وقتی هر تماس -اپراتور باید با زمینه تازه شروع شود، `sessionScope: "per-call"` را تنظیم کنید؛ -برای مثال جریان‌های پذیرش، رزرو، IVR، یا پل Google Meet که در آن‌ها همان -شماره تلفن ممکن است نماینده جلسه‌های متفاوت باشد. +به‌صورت پیش‌فرض، Voice Call از `sessionScope: "per-phone"` استفاده می‌کند تا تماس‌های تکراری از +همان تماس‌گیرنده حافظهٔ گفت‌وگو را حفظ کنند. وقتی هر تماس حامل باید با زمینهٔ تازه شروع شود، +برای نمونه جریان‌های پذیرش، رزرو، IVR، یا پل Google Meet که در آن همان شمارهٔ تلفن ممکن است +نمایندهٔ جلسه‌های متفاوت باشد، `sessionScope: "per-call"` را تنظیم کنید. ## گفت‌وگوهای صوتی بلادرنگ -`realtime` یک ارائه‌دهنده صدای بلادرنگ تمام‌دوطرفه را برای صدای تماس زنده -انتخاب می‌کند. این از `streaming` جداست؛ `streaming` فقط صدا را به -ارائه‌دهندگان رونویسی بلادرنگ می‌فرستد. +`realtime` یک ارائه‌دهندهٔ صوتی بلادرنگ تمام‌دوطرفه را برای صدای تماس زنده +انتخاب می‌کند. این با `streaming` جدا است، که فقط صدا را به +ارائه‌دهندگان رونویسی بلادرنگ ارسال می‌کند. `realtime.enabled` نمی‌تواند با `streaming.enabled` ترکیب شود. برای هر تماس یک حالت صوتی انتخاب کنید. -رفتار فعلی runtime: +رفتار runtime فعلی: - `realtime.enabled` برای Twilio Media Streams پشتیبانی می‌شود. -- `realtime.provider` اختیاری است. اگر تنظیم نشود، Voice Call از اولین ارائه‌دهنده ثبت‌شده صدای بلادرنگ استفاده می‌کند. -- ارائه‌دهندگان همراه صدای بلادرنگ: Google Gemini Live (`google`) و OpenAI (`openai`)، که توسط Pluginهای ارائه‌دهنده خودشان ثبت می‌شوند. -- پیکربندی خام تحت مالکیت ارائه‌دهنده زیر `realtime.providers.` قرار می‌گیرد. -- Voice Call به‌صورت پیش‌فرض ابزار بلادرنگ مشترک `openclaw_agent_consult` را ارائه می‌کند. مدل بلادرنگ وقتی تماس‌گیرنده استدلال عمیق‌تر، اطلاعات فعلی، یا ابزارهای عادی OpenClaw را می‌خواهد، می‌تواند آن را فراخوانی کند. -- `realtime.fastContext.enabled` به‌صورت پیش‌فرض خاموش است. وقتی فعال باشد، Voice Call ابتدا حافظه/زمینه جلسه indexشده را برای پرسش consult جست‌وجو می‌کند و پیش از fallback به agent کامل consult فقط در صورتی که `realtime.fastContext.fallbackToConsult` برابر true باشد، آن قطعه‌ها را در بازه `realtime.fastContext.timeoutMs` به مدل بلادرنگ برمی‌گرداند. -- اگر `realtime.provider` به یک ارائه‌دهنده ثبت‌نشده اشاره کند، یا اصلا هیچ ارائه‌دهنده صدای بلادرنگی ثبت نشده باشد، Voice Call به‌جای شکست دادن کل Plugin، یک هشدار لاگ می‌کند و از رسانه بلادرنگ صرف‌نظر می‌کند. -- کلیدهای جلسه consult در صورت وجود از جلسه تماس ذخیره‌شده دوباره استفاده می‌کنند، سپس به `sessionScope` پیکربندی‌شده fallback می‌کنند (`per-phone` به‌صورت پیش‌فرض، یا `per-call` برای تماس‌های ایزوله). +- `realtime.provider` اختیاری است. اگر تنظیم نشود، Voice Call از نخستین ارائه‌دهندهٔ صوتی بلادرنگ ثبت‌شده استفاده می‌کند. +- ارائه‌دهندگان صوتی بلادرنگ همراه: Google Gemini Live (`google`) و OpenAI (`openai`)، که توسط Pluginهای ارائه‌دهندهٔ خود ثبت می‌شوند. +- پیکربندی خام متعلق به ارائه‌دهنده زیر `realtime.providers.` قرار دارد. +- Voice Call ابزار بلادرنگ مشترک `openclaw_agent_consult` را به‌صورت پیش‌فرض در معرض می‌گذارد. مدل بلادرنگ می‌تواند وقتی تماس‌گیرنده استدلال عمیق‌تر، اطلاعات فعلی، یا ابزارهای عادی OpenClaw را می‌خواهد، آن را فراخوانی کند. +- `realtime.fastContext.enabled` به‌صورت پیش‌فرض خاموش است. وقتی فعال باشد، Voice Call ابتدا حافظهٔ ایندکس‌شده/زمینهٔ نشست را برای پرسش مشاوره جست‌وجو می‌کند و این قطعه‌ها را ظرف `realtime.fastContext.timeoutMs` به مدل بلادرنگ برمی‌گرداند، پیش از آنکه فقط در صورت true بودن `realtime.fastContext.fallbackToConsult` به عامل کامل مشاوره fallback کند. +- اگر `realtime.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهندهٔ صوتی بلادرنگی اصلاً ثبت نشده باشد، Voice Call یک هشدار ثبت می‌کند و به‌جای شکست‌دادن کل Plugin، از رسانهٔ بلادرنگ صرف‌نظر می‌کند. +- کلیدهای نشست مشاوره وقتی موجود باشند از نشست تماس ذخیره‌شده دوباره استفاده می‌کنند، سپس به `sessionScope` پیکربندی‌شده fallback می‌کنند (`per-phone` به‌صورت پیش‌فرض، یا `per-call` برای تماس‌های ایزوله). ### سیاست ابزار -`realtime.toolPolicy` اجرای consult را کنترل می‌کند: +`realtime.toolPolicy` اجرای مشاوره را کنترل می‌کند: | سیاست | رفتار | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `safe-read-only` | ابزار consult را ارائه می‌کند و agent عادی را به `read`، `web_search`، `web_fetch`، `x_search`، `memory_search`، و `memory_get` محدود می‌کند. | -| `owner` | ابزار consult را ارائه می‌کند و به agent عادی اجازه می‌دهد از سیاست ابزار عادی agent استفاده کند. | -| `none` | ابزار consult را ارائه نمی‌کند. `realtime.tools` سفارشی همچنان به ارائه‌دهنده بلادرنگ منتقل می‌شود. | +| `safe-read-only` | ابزار مشاوره را در معرض بگذار و عامل عادی را به `read`، `web_search`، `web_fetch`، `x_search`، `memory_search`، و `memory_get` محدود کن. | +| `owner` | ابزار مشاوره را در معرض بگذار و به عامل عادی اجازه بده از سیاست ابزار عادی عامل استفاده کند. | +| `none` | ابزار مشاوره را در معرض نگذار. `realtime.tools` سفارشی همچنان به ارائه‌دهندهٔ بلادرنگ عبور داده می‌شوند. | -### نمونه‌های ارائه‌دهنده بلادرنگ +### نمونه‌های ارائه‌دهندهٔ بلادرنگ پیش‌فرض‌ها: کلید API از `realtime.providers.google.apiKey`، `GEMINI_API_KEY`، یا `GOOGLE_GENERATIVE_AI_API_KEY`؛ مدل `gemini-2.5-flash-native-audio-preview-12-2025`؛ صدا `Kore`. + `sessionResumption` و `contextWindowCompression` برای تماس‌های طولانی‌تر و + قابل اتصال مجدد به‌صورت پیش‌فرض روشن هستند. برای تنظیم نوبت‌گیری سریع‌تر روی صدای تلفنی از + `silenceDurationMs`، `startSensitivity`، و + `endSensitivity` استفاده کنید. ```json5 { @@ -279,6 +280,8 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش apiKey: "${GEMINI_API_KEY}", model: "gemini-2.5-flash-native-audio-preview-12-2025", voice: "Kore", + silenceDurationMs: 500, + startSensitivity: "high", }, }, }, @@ -313,26 +316,27 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش -برای گزینه‌های صدای بلادرنگ ویژه هر ارائه‌دهنده، [ارائه‌دهنده Google](/fa/providers/google) و -[ارائه‌دهنده OpenAI](/fa/providers/openai) را ببینید. +به [ارائه‌دهنده Google](/fa/providers/google) و +[ارائه‌دهنده OpenAI](/fa/providers/openai) برای گزینه‌های صدای بی‌درنگ +ویژه ارائه‌دهنده مراجعه کنید. ## رونویسی جریانی -`streaming` یک ارائه‌دهنده رونویسی بلادرنگ را برای صدای تماس زنده انتخاب می‌کند. +`streaming` یک ارائه‌دهنده رونویسی بی‌درنگ را برای صدای زنده تماس انتخاب می‌کند. -رفتار فعلی runtime: +رفتار فعلی در زمان اجرا: -- `streaming.provider` اختیاری است. اگر تنظیم نشده باشد، تماس صوتی از اولین ارائه‌دهنده رونویسی بلادرنگ ثبت‌شده استفاده می‌کند. -- ارائه‌دهندگان رونویسی بلادرنگ همراه: Deepgram (`deepgram`)، ElevenLabs (`elevenlabs`)، Mistral (`mistral`)، OpenAI (`openai`) و xAI (`xai`) که توسط Pluginهای ارائه‌دهنده خود ثبت می‌شوند. -- پیکربندی خام متعلق به ارائه‌دهنده زیر `streaming.providers.` قرار می‌گیرد. -- پس از اینکه Twilio پیام `start` یک استریم پذیرفته‌شده را می‌فرستد، تماس صوتی بلافاصله استریم را ثبت می‌کند، رسانه ورودی را تا زمان اتصال ارائه‌دهنده از طریق ارائه‌دهنده رونویسی در صف قرار می‌دهد و سلام اولیه را فقط پس از آماده‌شدن رونویسی بلادرنگ شروع می‌کند. -- اگر `streaming.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهنده‌ای ثبت نشده باشد، تماس صوتی یک هشدار ثبت می‌کند و به‌جای ناموفق‌کردن کل Plugin، استریم رسانه را رد می‌کند. +- `streaming.provider` اختیاری است. اگر تنظیم نشده باشد، Voice Call از نخستین ارائه‌دهنده رونویسی بی‌درنگ ثبت‌شده استفاده می‌کند. +- ارائه‌دهندگان رونویسی بی‌درنگ همراه: Deepgram (`deepgram`)، ElevenLabs (`elevenlabs`)، Mistral (`mistral`)، OpenAI (`openai`) و xAI (`xai`) که توسط Pluginهای ارائه‌دهنده خودشان ثبت می‌شوند. +- پیکربندی خامِ تحت مالکیت ارائه‌دهنده زیر `streaming.providers.` قرار دارد. +- پس از اینکه Twilio پیام `start` جریان پذیرفته‌شده را می‌فرستد، Voice Call جریان را بی‌درنگ ثبت می‌کند، رسانه ورودی را تا زمان اتصال ارائه‌دهنده از طریق ارائه‌دهنده رونویسی در صف می‌گذارد، و خوشامدگویی اولیه را فقط پس از آماده شدن رونویسی بی‌درنگ شروع می‌کند. +- اگر `streaming.provider` به ارائه‌دهنده‌ای ثبت‌نشده اشاره کند، یا هیچ ارائه‌دهنده‌ای ثبت نشده باشد، Voice Call یک هشدار ثبت می‌کند و به‌جای شکست دادن کل Plugin، پخش جریانی رسانه را رد می‌کند. -### نمونه‌های ارائه‌دهنده استریم +### نمونه‌های ارائه‌دهنده جریانی - پیش‌فرض‌ها: کلید API `streaming.providers.openai.apiKey` یا + پیش‌فرض‌ها: کلید API در `streaming.providers.openai.apiKey` یا `OPENAI_API_KEY`؛ مدل `gpt-4o-transcribe`؛ `silenceDurationMs: 800`؛ `vadThreshold: 0.5`. @@ -364,7 +368,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش - پیش‌فرض‌ها: کلید API `streaming.providers.xai.apiKey` یا `XAI_API_KEY`؛ + پیش‌فرض‌ها: کلید API در `streaming.providers.xai.apiKey` یا `XAI_API_KEY`؛ نقطه پایانی `wss://api.x.ai/v1/stt`؛ کدگذاری `mulaw`؛ نرخ نمونه‌برداری `8000`؛ `endpointingMs: 800`؛ `interimResults: true`. @@ -398,9 +402,9 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش ## TTS برای تماس‌ها -تماس صوتی از پیکربندی هسته `messages.tts` برای استریم گفتار در تماس‌ها -استفاده می‌کند. می‌توانید آن را در پیکربندی Plugin با **همان ساختار** بازنویسی کنید — -این پیکربندی با `messages.tts` به‌صورت عمیق ادغام می‌شود. +Voice Call از پیکربندی هسته‌ای `messages.tts` برای گفتار جریانی +در تماس‌ها استفاده می‌کند. می‌توانید آن را در پیکربندی Plugin با +**همان شکل** بازنویسی کنید — این پیکربندی با `messages.tts` به‌صورت عمیق ادغام می‌شود. ```json5 { @@ -418,21 +422,21 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش **گفتار Microsoft برای تماس‌های صوتی نادیده گرفته می‌شود.** صدای تلفنی به PCM نیاز دارد؛ -انتقال فعلی Microsoft خروجی PCM تلفنی را در دسترس نمی‌گذارد. +انتقال فعلی Microsoft خروجی PCM تلفنی را ارائه نمی‌کند. نکات رفتاری: -- کلیدهای قدیمی `tts.` داخل پیکربندی Plugin (`openai`، `elevenlabs`، `microsoft`، `edge`) توسط `openclaw doctor --fix` ترمیم می‌شوند؛ پیکربندی ثبت‌شده باید از `tts.providers.` استفاده کند. -- وقتی استریم رسانه Twilio فعال باشد، TTS هسته استفاده می‌شود؛ در غیر این صورت تماس‌ها به صداهای بومی ارائه‌دهنده برمی‌گردند. -- اگر یک استریم رسانه Twilio از قبل فعال باشد، تماس صوتی به TwiML `` برنمی‌گردد. اگر TTS تلفنی در آن وضعیت در دسترس نباشد، درخواست پخش به‌جای ترکیب دو مسیر پخش ناموفق می‌شود. -- وقتی TTS تلفنی به یک ارائه‌دهنده ثانویه برمی‌گردد، تماس صوتی برای اشکال‌زدایی هشداری همراه با زنجیره ارائه‌دهنده (`from`، `to`، `attempts`) ثبت می‌کند. -- وقتی ورود هم‌زمان Twilio یا برچیدن استریم صف معلق TTS را پاک می‌کند، درخواست‌های پخش صف‌شده به نتیجه می‌رسند به‌جای اینکه تماس‌گیرندگان را در انتظار تکمیل پخش معلق نگه دارند. +- کلیدهای قدیمی `tts.` داخل پیکربندی Plugin (`openai`، `elevenlabs`، `microsoft`، `edge`) توسط `openclaw doctor --fix` ترمیم می‌شوند؛ پیکربندی commit‌شده باید از `tts.providers.` استفاده کند. +- وقتی پخش جریانی رسانه Twilio فعال باشد، از TTS هسته استفاده می‌شود؛ در غیر این صورت تماس‌ها به صداهای بومی ارائه‌دهنده برمی‌گردند. +- اگر یک جریان رسانه Twilio از قبل فعال باشد، Voice Call به TwiML `` برنمی‌گردد. اگر TTS تلفنی در آن وضعیت در دسترس نباشد، درخواست پخش به‌جای ترکیب دو مسیر پخش شکست می‌خورد. +- وقتی TTS تلفنی به یک ارائه‌دهنده ثانویه برمی‌گردد، Voice Call برای اشکال‌زدایی هشداری با زنجیره ارائه‌دهنده (`from`، `to`، `attempts`) ثبت می‌کند. +- وقتی ورود ناگهانی Twilio یا برچیدن جریان، صف TTS معلق را پاک می‌کند، درخواست‌های پخش صف‌شده به نتیجه می‌رسند و تماس‌گیرندگان در انتظار تکمیل پخش معلق نمی‌مانند. ### نمونه‌های TTS - + ```json5 { messages: { @@ -446,7 +450,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش } ``` - + ```json5 { plugins: { @@ -470,7 +474,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش } ``` - + ```json5 { plugins: { @@ -496,7 +500,7 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش ## تماس‌های ورودی -خط‌مشی ورودی به‌طور پیش‌فرض `disabled` است. برای فعال‌کردن تماس‌های ورودی، تنظیم کنید: +سیاست ورودی به‌صورت پیش‌فرض `disabled` است. برای فعال کردن تماس‌های ورودی، تنظیم کنید: ```json5 { @@ -507,31 +511,29 @@ Gateway راه دور استفاده می‌کنید، Plugin را روی ماش ``` -`inboundPolicy: "allowlist"` یک غربال‌گری شناسه تماس‌گیرنده با اطمینان پایین است. +`inboundPolicy: "allowlist"` یک غربالگری کم‌اطمینان شناسه تماس‌گیرنده است. این Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده را نرمال‌سازی می‌کند و آن را با -`allowFrom` مقایسه می‌کند. تأیید Webhook تحویل ارائه‌دهنده و -یکپارچگی payload را احراز می‌کند، اما مالکیت شماره تماس‌گیرنده PSTN/VoIP را -**ثابت نمی‌کند**. با `allowFrom` به‌عنوان فیلتر شناسه تماس‌گیرنده رفتار کنید، نه هویت -قوی تماس‌گیرنده. +`allowFrom` مقایسه می‌کند. راستی‌آزمایی Webhook تحویل ارائه‌دهنده و +یکپارچگی بار داده را احراز می‌کند، اما مالکیت شماره تماس‌گیرنده PSTN/VoIP را +**اثبات نمی‌کند**. با `allowFrom` به‌عنوان فیلتر شناسه تماس‌گیرنده برخورد کنید، نه هویت قوی تماس‌گیرنده. -پاسخ‌های خودکار از سامانه عامل استفاده می‌کنند. با `responseModel`، +پاسخ‌های خودکار از سیستم عامل استفاده می‌کنند. با `responseModel`، `responseSystemPrompt` و `responseTimeoutMs` تنظیم کنید. -### مسیریابی برای هر شماره +### مسیریابی بر اساس شماره -وقتی یک Plugin تماس صوتی تماس‌های چند شماره تلفن را دریافت می‌کند و هر شماره -باید مانند یک خط متفاوت رفتار کند، از `numbers` استفاده کنید. برای مثال، یک -شماره می‌تواند از یک دستیار شخصی غیررسمی استفاده کند در حالی که شماره‌ای دیگر از یک شخصیت -کاری، یک عامل پاسخ متفاوت و یک صدای TTS متفاوت استفاده می‌کند. +وقتی یک Plugin از نوع Voice Call برای چند شماره تلفن تماس دریافت می‌کند و هر شماره باید مثل یک خط متفاوت رفتار کند، از `numbers` استفاده کنید. برای نمونه، یک +شماره می‌تواند از یک دستیار شخصی خودمانی استفاده کند، در حالی که شماره‌ای دیگر از یک +شخصیت تجاری، عامل پاسخ متفاوت، و صدای TTS متفاوت استفاده می‌کند. -مسیرها از شماره `To` شماره‌گیری‌شده و ارائه‌شده توسط ارائه‌دهنده انتخاب می‌شوند. کلیدها باید -شماره‌های E.164 باشند. وقتی تماسی وارد می‌شود، تماس صوتی مسیر مطابق را یک‌بار حل می‌کند، -مسیر مطابق را در رکورد تماس ذخیره می‌کند و همان پیکربندی مؤثر را برای -سلام، مسیر پاسخ خودکار کلاسیک، مسیر مشاوره بلادرنگ و پخش TTS -بازاستفاده می‌کند. اگر هیچ مسیری مطابق نباشد، پیکربندی سراسری تماس صوتی استفاده می‌شود. +مسیرها از شماره `To` شماره‌گیری‌شده ارائه‌شده توسط ارائه‌دهنده انتخاب می‌شوند. کلیدها باید +شماره‌های E.164 باشند. وقتی تماسی می‌رسد، Voice Call مسیر مطابق را یک بار حل می‌کند، +مسیر مطابق را روی رکورد تماس ذخیره می‌کند، و همان پیکربندی مؤثر را +برای خوشامدگویی، مسیر کلاسیک پاسخ خودکار، مسیر مشاوره بی‌درنگ، و پخش +TTS دوباره استفاده می‌کند. اگر هیچ مسیری مطابق نباشد، از پیکربندی سراسری Voice Call استفاده می‌شود. تماس‌های خروجی از `numbers` استفاده نمی‌کنند؛ هنگام شروع تماس، مقصد خروجی، پیام و -نشست را صریحاً ارسال کنید. +نشست را به‌صراحت پاس دهید. بازنویسی‌های مسیر در حال حاضر پشتیبانی می‌کنند از: @@ -542,7 +544,7 @@ Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده ر - `responseSystemPrompt` - `responseTimeoutMs` -مقدار مسیر `tts` روی پیکربندی سراسری `tts` تماس صوتی به‌صورت عمیق ادغام می‌شود، بنابراین +مقدار مسیر `tts` روی پیکربندی سراسری `tts` در Voice Call به‌صورت عمیق ادغام می‌شود، بنابراین معمولاً می‌توانید فقط صدای ارائه‌دهنده را بازنویسی کنید: ```json5 @@ -571,51 +573,51 @@ Plugin مقدار `From` ارائه‌شده توسط ارائه‌دهنده ر ### قرارداد خروجی گفتاری -برای پاسخ‌های خودکار، تماس صوتی یک قرارداد سخت‌گیرانه خروجی گفتاری را به -پرامپت سیستم اضافه می‌کند: +برای پاسخ‌های خودکار، Voice Call یک قرارداد سخت‌گیرانه خروجی گفتاری را به +اعلان سیستم اضافه می‌کند: ```text {"spoken":"..."} ``` -تماس صوتی متن گفتار را به‌صورت تدافعی استخراج می‌کند: +Voice Call متن گفتار را دفاعی استخراج می‌کند: -- payloadهایی را که به‌عنوان محتوای استدلال/خطا علامت‌گذاری شده‌اند نادیده می‌گیرد. -- JSON مستقیم، JSON حصارگذاری‌شده یا کلیدهای درون‌خطی `"spoken"` را تجزیه می‌کند. -- به متن ساده برمی‌گردد و پاراگراف‌های آغازین محتملِ برنامه‌ریزی/فرا را حذف می‌کند. +- بارهای داده‌ای را که به‌عنوان محتوای استدلال/خطا علامت‌گذاری شده‌اند نادیده می‌گیرد. +- JSON مستقیم، JSON حصارشده، یا کلیدهای درون‌خطی `"spoken"` را تجزیه می‌کند. +- به متن ساده برمی‌گردد و پاراگراف‌های ابتدایی احتمالی برنامه‌ریزی/فراداده را حذف می‌کند. این کار پخش گفتاری را روی متن روبه‌روی تماس‌گیرنده متمرکز نگه می‌دارد و از نشت متن برنامه‌ریزی به صدا جلوگیری می‌کند. ### رفتار شروع مکالمه -برای تماس‌های خروجی `conversation`، مدیریت پیام اول به وضعیت پخش زنده -وابسته است: +برای تماس‌های خروجی `conversation`، مدیریت پیام نخست به وضعیت زنده +پخش گره خورده است: -- پاک‌سازی صف ورود هم‌زمان و پاسخ خودکار فقط زمانی سرکوب می‌شوند که سلام اولیه فعالانه در حال صحبت باشد. -- اگر پخش اولیه ناموفق شود، تماس به `listening` برمی‌گردد و پیام اولیه برای تلاش دوباره در صف می‌ماند. -- پخش اولیه برای استریم Twilio هنگام اتصال استریم و بدون تأخیر اضافی شروع می‌شود. -- ورود هم‌زمان پخش فعال را لغو می‌کند و ورودی‌های Twilio TTS صف‌شده اما هنوز پخش‌نشده را پاک می‌کند. ورودی‌های پاک‌شده به‌عنوان ردشده resolve می‌شوند، بنابراین منطق پاسخ بعدی می‌تواند بدون انتظار برای صدایی که هرگز پخش نخواهد شد ادامه دهد. -- مکالمات صوتی بلادرنگ از نوبت آغازین خود استریم بلادرنگ استفاده می‌کنند. تماس صوتی برای آن پیام اولیه، به‌روزرسانی قدیمی TwiML `` ارسال **نمی‌کند**، بنابراین نشست‌های خروجی `` متصل باقی می‌مانند. +- پاک‌سازی صف ورود ناگهانی و پاسخ خودکار فقط زمانی سرکوب می‌شوند که خوشامدگویی اولیه به‌صورت فعال در حال پخش باشد. +- اگر پخش اولیه شکست بخورد، تماس به `listening` برمی‌گردد و پیام اولیه برای تلاش دوباره در صف می‌ماند. +- پخش اولیه برای جریان Twilio بدون تأخیر اضافه هنگام اتصال جریان شروع می‌شود. +- ورود ناگهانی پخش فعال را لغو می‌کند و ورودی‌های TTS در Twilio را که صف شده‌اند اما هنوز پخش نشده‌اند پاک می‌کند. ورودی‌های پاک‌شده به‌عنوان ردشده حل می‌شوند، بنابراین منطق پاسخ بعدی می‌تواند بدون انتظار برای صدایی که هرگز پخش نخواهد شد ادامه پیدا کند. +- مکالمه‌های صوتی بی‌درنگ از نوبت آغازین خودِ جریان بی‌درنگ استفاده می‌کنند. Voice Call برای آن پیام اولیه یک به‌روزرسانی قدیمی TwiML با `` ارسال **نمی‌کند**، بنابراین نشست‌های خروجی `` متصل باقی می‌مانند. -### مهلت قطع اتصال استریم Twilio +### مهلت قطع اتصال جریان Twilio -وقتی یک استریم رسانه Twilio قطع می‌شود، تماس صوتی پیش از -پایان خودکار تماس **2000 ms** منتظر می‌ماند: +وقتی جریان رسانه Twilio قطع می‌شود، Voice Call پیش از +پایان‌دهی خودکار تماس **2000 ms** صبر می‌کند: -- اگر استریم در آن بازه دوباره وصل شود، پایان خودکار لغو می‌شود. -- اگر پس از دوره مهلت هیچ استریمی دوباره ثبت نشود، تماس پایان داده می‌شود تا از گیرکردن تماس‌های فعال جلوگیری شود. +- اگر جریان در طول آن بازه دوباره متصل شود، پایان خودکار لغو می‌شود. +- اگر پس از دوره مهلت هیچ جریانی دوباره ثبت نشود، تماس پایان می‌یابد تا از تماس‌های فعال گیرکرده جلوگیری شود. -## پاک‌کننده تماس کهنه +## پاک‌سازی تماس‌های کهنه -از `staleCallReaperSeconds` برای پایان‌دادن به تماس‌هایی استفاده کنید که هرگز یک -Webhook پایانی دریافت نمی‌کنند (برای مثال، تماس‌های حالت اعلان که هرگز کامل نمی‌شوند). مقدار پیش‌فرض +از `staleCallReaperSeconds` برای پایان دادن به تماس‌هایی استفاده کنید که هرگز Webhook پایانی +دریافت نمی‌کنند (برای مثال، تماس‌های حالت اعلان که هرگز کامل نمی‌شوند). مقدار پیش‌فرض `0` است (غیرفعال). بازه‌های پیشنهادی: - **تولید:** `120` تا `300` ثانیه برای جریان‌های سبک اعلان. -- این مقدار را **بالاتر از `maxDurationSeconds`** نگه دارید تا تماس‌های عادی بتوانند تمام شوند. نقطه شروع خوب `maxDurationSeconds + 30–60` ثانیه است. +- این مقدار را **بالاتر از `maxDurationSeconds`** نگه دارید تا تماس‌های عادی بتوانند تمام شوند. نقطه شروع مناسب `maxDurationSeconds + 30–60` ثانیه است. ```json5 { @@ -634,28 +636,28 @@ Webhook پایانی دریافت نمی‌کنند (برای مثال، تما ## امنیت Webhook -وقتی یک پراکسی یا تونل جلوی Gateway قرار دارد، Plugin -نشانی URL عمومی را برای تأیید امضا بازسازی می‌کند. این گزینه‌ها -کنترل می‌کنند کدام سربرگ‌های فورواردشده قابل اعتماد باشند: +وقتی یک پروکسی یا تونل جلوی Gateway قرار می‌گیرد، این Plugin +URL عمومی را برای راستی‌آزمایی امضا بازسازی می‌کند. این گزینه‌ها +کنترل می‌کنند که کدام سرآیندهای فورواردشده قابل اعتماد هستند: - میزبان‌های allowlist از سربرگ‌های فورواردینگ. + میزبان‌های فهرست مجاز از سرآیندهای فوروارد را مجاز کنید. - اعتماد به سربرگ‌های فورواردشده بدون allowlist. + به سرآیندهای فورواردشده بدون فهرست مجاز اعتماد کنید. - فقط زمانی به سربرگ‌های فورواردشده اعتماد کنید که IP راه‌دور درخواست با فهرست مطابق باشد. + فقط وقتی IP راه‌دور درخواست با فهرست مطابق باشد به سرآیندهای فورواردشده اعتماد کنید. محافظت‌های اضافی: -- **محافظت در برابر بازپخش** Webhook برای Twilio و Plivo فعال است. درخواست‌های معتبر Webhook که بازپخش شده‌اند تأیید می‌شوند اما برای اثرات جانبی رد می‌شوند. -- نوبت‌های مکالمه Twilio در callbackهای `` شامل یک توکن برای هر نوبت هستند، بنابراین callbackهای گفتار کهنه/بازپخش‌شده نمی‌توانند یک نوبت transcript معلق جدیدتر را برآورده کنند. -- درخواست‌های Webhook احرازنشده، زمانی که سربرگ‌های امضای الزامی ارائه‌دهنده وجود نداشته باشند، پیش از خواندن بدنه رد می‌شوند. -- Webhook تماس صوتی از پروفایل مشترک بدنه پیش‌از‌احراز (64 KB / 5 ثانیه) به‌همراه سقف درحال‌پرواز برای هر IP پیش از تأیید امضا استفاده می‌کند. +- **محافظت در برابر بازپخش** Webhook برای Twilio و Plivo فعال است. درخواست‌های Webhook معتبرِ بازپخش‌شده تأیید می‌شوند اما برای اثرات جانبی رد می‌شوند. +- نوبت‌های مکالمه Twilio شامل یک توکن ویژه هر نوبت در callbackهای `` هستند، بنابراین callbackهای گفتار کهنه/بازپخش‌شده نمی‌توانند یک نوبت رونوشت معلق جدیدتر را برآورده کنند. +- درخواست‌های Webhook احرازنشده وقتی سرآیندهای امضای موردنیاز ارائه‌دهنده وجود نداشته باشند، پیش از خواندن بدنه رد می‌شوند. +- Webhook مربوط به voice-call از پروفایل بدنه پیشااحراز مشترک (64 KB / 5 ثانیه) به‌همراه سقف درحال‌انجام بر اساس هر IP پیش از راستی‌آزمایی امضا استفاده می‌کند. -نمونه با یک میزبان عمومی پایدار: +نمونه با میزبان عمومی پایدار: ```json5 { @@ -689,17 +691,11 @@ openclaw voicecall latency # summarize turn latency from lo openclaw voicecall expose --mode funnel ``` -وقتی Gateway از قبل در حال اجراست، فرمان‌های عملیاتی `voicecall` به -runtime تماس صوتی متعلق به Gateway واگذار می‌شوند تا CLI یک سرور -Webhook دوم را bind نکند. اگر هیچ Gatewayی در دسترس نباشد، فرمان‌ها به یک -runtime مستقل CLI برمی‌گردند. +وقتی Gateway از قبل در حال اجراست، فرمان‌های عملیاتی `voicecall` به runtime تماس صوتی تحت مالکیت Gateway واگذار می‌شوند تا CLI یک سرور webhook دوم را bind نکند. اگر هیچ Gatewayای در دسترس نباشد، فرمان‌ها به runtime مستقل CLI برمی‌گردند. -`latency`، `calls.jsonl` را از مسیر پیش‌فرض ذخیره‌سازی تماس صوتی می‌خواند. -از `--file ` برای اشاره به یک گزارش متفاوت و از `--last ` برای محدود کردن -تحلیل به آخرین N رکورد استفاده کنید (پیش‌فرض 200). خروجی شامل p50/p90/p99 -برای تأخیر نوبت و زمان‌های انتظار شنیدن است. +`latency` فایل `calls.jsonl` را از مسیر پیش‌فرض ذخیره‌سازی تماس صوتی می‌خواند. از `--file ` برای اشاره به یک log دیگر و از `--last ` برای محدود کردن تحلیل به آخرین N رکورد استفاده کنید (پیش‌فرض 200). خروجی شامل p50/p90/p99 برای تأخیر نوبت و زمان‌های انتظار برای گوش‌دادن است. -## ابزار عامل +## ابزار agent نام ابزار: `voice_call`. @@ -712,11 +708,11 @@ runtime مستقل CLI برمی‌گردند. | `end_call` | `callId` | | `get_status` | `callId` | -این مخزن یک سند skill متناظر را در `skills/voice-call/SKILL.md` ارائه می‌کند. +این repo یک سند skill متناظر را در `skills/voice-call/SKILL.md` ارائه می‌کند. -## RPC Gateway +## RPC مربوط به Gateway -| روش | آرگومان‌ها | +| متد | آرگومان‌ها | | -------------------- | ------------------------------------------ | | `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` | | `voicecall.continue` | `callId`, `message` | @@ -725,13 +721,11 @@ runtime مستقل CLI برمی‌گردند. | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` فقط با `mode: "conversation"` معتبر است. تماس‌های حالت اعلان -اگر پس از اتصال به ارقام نیاز دارند، باید بعد از ایجاد تماس از `voicecall.dtmf` -استفاده کنند. +`dtmfSequence` فقط با `mode: "conversation"` معتبر است. تماس‌های حالت notify، اگر پس از برقراری اتصال به رقم‌ها نیاز دارند، باید بعد از اینکه تماس ایجاد شد از `voicecall.dtmf` استفاده کنند. ## عیب‌یابی -### راه‌اندازی در مواجهه با Webhook ناموفق می‌شود +### راه‌اندازی در معرض‌گذاری webhook ناموفق است راه‌اندازی را از همان محیطی اجرا کنید که Gateway را اجرا می‌کند: @@ -740,20 +734,11 @@ openclaw voicecall setup openclaw voicecall setup --json ``` -برای `twilio`، `telnyx` و `plivo`، `webhook-exposure` باید سبز باشد. یک -`publicUrl` پیکربندی‌شده همچنان وقتی به فضای شبکه محلی یا خصوصی اشاره کند -ناموفق می‌شود، چون اپراتور نمی‌تواند به آن نشانی‌ها بازتماس انجام دهد. از -`localhost`، `127.0.0.1`، `0.0.0.0`، `10.x`، `172.16.x`-`172.31.x`، -`192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به عنوان `publicUrl` -استفاده نکنید. +برای `twilio`، `telnyx`، و `plivo`، `webhook-exposure` باید سبز باشد. یک `publicUrl` پیکربندی‌شده همچنان وقتی به فضای شبکه محلی یا خصوصی اشاره کند شکست می‌خورد، چون carrier نمی‌تواند به آن آدرس‌ها callback کند. از `localhost`، `127.0.0.1`، `0.0.0.0`، `10.x`، `172.16.x`-`172.31.x`، `192.168.x`، `169.254.x`، `fc00::/7`، یا `fd00::/8` به‌عنوان `publicUrl` استفاده نکنید. -تماس‌های خروجی حالت اعلان Twilio، TwiML اولیه `` خود را مستقیماً در -درخواست ایجاد تماس ارسال می‌کنند، بنابراین نخستین پیام گفتاری به دریافت TwiML -Webhook توسط Twilio وابسته نیست. Webhook عمومی همچنان برای callbackهای وضعیت، -تماس‌های مکالمه، DTMF پیش از اتصال، جریان‌های بلادرنگ و کنترل تماس پس از اتصال -لازم است. +تماس‌های outbound در حالت notify برای Twilio، TwiML اولیه‌ی `` خود را مستقیماً در درخواست create-call ارسال می‌کنند، بنابراین نخستین پیام گفتاری به دریافت TwiML مربوط به webhook توسط Twilio وابسته نیست. یک webhook عمومی همچنان برای callbackهای وضعیت، تماس‌های مکالمه، DTMF پیش از اتصال، streamهای realtime، و کنترل تماس پس از اتصال لازم است. -از یک مسیر مواجهه عمومی استفاده کنید: +از یک مسیر در معرض‌گذاری عمومی استفاده کنید: ```json5 { @@ -773,38 +758,34 @@ Webhook توسط Twilio وابسته نیست. Webhook عمومی همچنان } ``` -پس از تغییر پیکربندی، Gateway را بازراه‌اندازی یا بازبارگذاری کنید، سپس اجرا کنید: +پس از تغییر config، Gateway را restart یا reload کنید، سپس اجرا کنید: ```bash openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` یک اجرای آزمایشی خشک است مگر اینکه `--yes` را بدهید. +`voicecall smoke` یک dry run است مگر اینکه `--yes` را پاس بدهید. -### اعتبارنامه‌های ارائه‌دهنده ناموفق می‌شوند +### credentialهای provider ناموفق هستند -ارائه‌دهنده انتخاب‌شده و فیلدهای اعتبارنامه لازم را بررسی کنید: +provider انتخاب‌شده و fieldهای credential لازم را بررسی کنید: -- Twilio: `twilio.accountSid`، `twilio.authToken` و `fromNumber`، یا - `TWILIO_ACCOUNT_SID`، `TWILIO_AUTH_TOKEN` و `TWILIO_FROM_NUMBER`. -- Telnyx: `telnyx.apiKey`، `telnyx.connectionId`، `telnyx.publicKey` و - `fromNumber`. -- Plivo: `plivo.authId`، `plivo.authToken` و `fromNumber`. +- Twilio: `twilio.accountSid`، `twilio.authToken`، و `fromNumber`، یا `TWILIO_ACCOUNT_SID`، `TWILIO_AUTH_TOKEN`، و `TWILIO_FROM_NUMBER`. +- Telnyx: `telnyx.apiKey`، `telnyx.connectionId`، `telnyx.publicKey`، و `fromNumber`. +- Plivo: `plivo.authId`، `plivo.authToken`، و `fromNumber`. -اعتبارنامه‌ها باید روی میزبان Gateway وجود داشته باشند. ویرایش یک پروفایل پوسته -محلی تا زمانی که Gateway محیط خود را بازراه‌اندازی یا بازبارگذاری نکند، روی -Gateway در حال اجرا اثر نمی‌گذارد. +credentialها باید روی میزبان Gateway وجود داشته باشند. ویرایش یک shell profile محلی تا زمانی که Gateway دوباره راه‌اندازی یا محیطش reload نشود، روی Gatewayای که از قبل در حال اجراست اثری ندارد. -### تماس‌ها شروع می‌شوند اما Webhookهای ارائه‌دهنده نمی‌رسند +### تماس‌ها شروع می‌شوند اما webhookهای provider نمی‌رسند -تأیید کنید کنسول ارائه‌دهنده دقیقاً به URL عمومی Webhook اشاره می‌کند: +تأیید کنید console مربوط به provider به URL دقیق webhook عمومی اشاره می‌کند: ```text https://voice.example.com/voice/webhook ``` -سپس وضعیت زمان اجرا را بررسی کنید: +سپس وضعیت runtime را بررسی کنید: ```bash openclaw voicecall status --call-id @@ -815,80 +796,64 @@ openclaw logs --follow علت‌های رایج: - `publicUrl` به مسیری متفاوت از `serve.path` اشاره می‌کند. -- URL تونل پس از شروع Gateway تغییر کرده است. -- یک پراکسی درخواست را ارسال می‌کند اما سرآیندهای host/proto را حذف یا بازنویسی می‌کند. -- دیوار آتش یا DNS نام میزبان عمومی را به جایی غیر از Gateway مسیریابی می‌کند. -- Gateway بدون فعال بودن Plugin تماس صوتی بازراه‌اندازی شده است. +- URL مربوط به tunnel پس از شروع Gateway تغییر کرده است. +- یک proxy درخواست را forward می‌کند اما headerهای host/proto را حذف یا بازنویسی می‌کند. +- firewall یا DNS نام میزبان عمومی را به جایی غیر از Gateway route می‌کند. +- Gateway بدون فعال بودن Plugin تماس صوتی restart شده است. -وقتی یک پراکسی معکوس یا تونل جلوی Gateway قرار دارد، `webhookSecurity.allowedHosts` -را روی نام میزبان عمومی تنظیم کنید، یا برای نشانی شناخته‌شده پراکسی از -`webhookSecurity.trustedProxyIPs` استفاده کنید. فقط زمانی از -`webhookSecurity.trustForwardingHeaders` استفاده کنید که مرز پراکسی تحت کنترل -شماست. +وقتی یک reverse proxy یا tunnel جلوی Gateway قرار دارد، `webhookSecurity.allowedHosts` را روی hostname عمومی تنظیم کنید، یا برای یک آدرس proxy شناخته‌شده از `webhookSecurity.trustedProxyIPs` استفاده کنید. فقط زمانی از `webhookSecurity.trustForwardingHeaders` استفاده کنید که مرز proxy تحت کنترل شماست. -### راستی‌آزمایی امضا ناموفق می‌شود +### اعتبارسنجی امضا ناموفق است -امضاهای ارائه‌دهنده در برابر URL عمومی‌ای بررسی می‌شوند که OpenClaw از درخواست -ورودی بازسازی می‌کند. اگر امضاها ناموفق شوند: +امضاهای provider در برابر URL عمومی‌ای بررسی می‌شوند که OpenClaw از درخواست ورودی بازسازی می‌کند. اگر امضاها ناموفق باشند: -- تأیید کنید URL Webhook ارائه‌دهنده دقیقاً با `publicUrl` مطابق است، از جمله - scheme، host و path. -- برای URLهای سطح رایگان ngrok، وقتی نام میزبان تونل تغییر می‌کند `publicUrl` را به‌روزرسانی کنید. -- مطمئن شوید پراکسی سرآیندهای اصلی host و proto را حفظ می‌کند، یا - `webhookSecurity.allowedHosts` را پیکربندی کنید. -- خارج از آزمون محلی، `skipSignatureVerification` را فعال نکنید. +- تأیید کنید URL مربوط به webhook provider دقیقاً با `publicUrl` مطابقت دارد، شامل scheme، host، و path. +- برای URLهای سطح رایگان ngrok، وقتی hostname مربوط به tunnel تغییر می‌کند `publicUrl` را به‌روزرسانی کنید. +- مطمئن شوید proxy headerهای host و proto اصلی را حفظ می‌کند، یا `webhookSecurity.allowedHosts` را پیکربندی کنید. +- خارج از تست محلی، `skipSignatureVerification` را فعال نکنید. -### اتصال‌های Google Meet با Twilio ناموفق می‌شوند +### اتصال‌های Google Meet با Twilio ناموفق هستند -Google Meet از این Plugin برای اتصال‌های شماره‌گیری ورودی Twilio استفاده می‌کند. ابتدا Voice Call را تأیید کنید: +Google Meet از این Plugin برای اتصال‌های dial-in با Twilio استفاده می‌کند. ابتدا Voice Call را تأیید کنید: ```bash openclaw voicecall setup openclaw voicecall smoke --to "+15555550123" ``` -سپس انتقال Google Meet را صراحتاً تأیید کنید: +سپس transport مربوط به Google Meet را صراحتاً تأیید کنید: ```bash openclaw googlemeet setup --transport twilio ``` -اگر Voice Call سبز است اما شرکت‌کننده Meet هرگز وصل نمی‌شود، شماره شماره‌گیری -ورودی Meet، PIN و `--dtmf-sequence` را بررسی کنید. تماس تلفنی می‌تواند سالم باشد -در حالی که جلسه یک دنباله DTMF نادرست را رد یا نادیده می‌گیرد. +اگر Voice Call سبز است اما شرکت‌کننده‌ی Meet هرگز ملحق نمی‌شود، شماره dial-in، PIN، و `--dtmf-sequence` مربوط به Meet را بررسی کنید. تماس تلفنی می‌تواند سالم باشد در حالی که meeting یک توالی DTMF نادرست را رد یا نادیده می‌گیرد. -Google Meet دنباله DTMF و متن مقدمه Meet را به `voicecall.start` می‌فرستد. -برای تماس‌های Twilio، Voice Call ابتدا TwiML مربوط به DTMF را سرو می‌کند، سپس -به Webhook برمی‌گرداند، و بعد جریان رسانه بلادرنگ را باز می‌کند تا مقدمه -ذخیره‌شده پس از پیوستن شرکت‌کننده تلفنی به جلسه تولید شود. +Google Meet توالی DTMF مربوط به Meet و متن intro را به `voicecall.start` پاس می‌دهد. برای تماس‌های Twilio، Voice Call ابتدا TwiML مربوط به DTMF را serve می‌کند، دوباره به webhook redirect می‌کند، سپس stream رسانه‌ی realtime را باز می‌کند تا intro ذخیره‌شده پس از ملحق شدن شرکت‌کننده‌ی تلفنی به meeting تولید شود. -برای ردگیری زنده مرحله از `openclaw logs --follow` استفاده کنید. یک اتصال سالم -Twilio Meet این ترتیب را ثبت می‌کند: +برای trace زنده‌ی phase از `openclaw logs --follow` استفاده کنید. یک اتصال سالم Twilio Meet این ترتیب را log می‌کند: - Google Meet اتصال Twilio را به Voice Call واگذار می‌کند. -- Voice Call، TwiML مربوط به DTMF پیش از اتصال را ذخیره می‌کند. -- TwiML اولیه Twilio پیش از پردازش بلادرنگ مصرف و سرو می‌شود. -- Voice Call، TwiML بلادرنگ را برای تماس Twilio سرو می‌کند. -- پل بلادرنگ با سلام اولیه در صف شروع می‌شود. +- Voice Call توالی DTMF TwiML پیش از اتصال را ذخیره می‌کند. +- TwiML اولیه‌ی Twilio مصرف و پیش از پردازش realtime serve می‌شود. +- Voice Call برای تماس Twilio، TwiML مربوط به realtime را serve می‌کند. +- bridge مربوط به realtime با greeting اولیه در queue شروع می‌شود. -`openclaw voicecall tail` همچنان رکوردهای تماس پایدارشده را نشان می‌دهد؛ برای -وضعیت تماس و رونوشت‌ها مفید است، اما هر گذار Webhook/بلادرنگ در آن ظاهر نمی‌شود. +`openclaw voicecall tail` همچنان رکوردهای تماس پایدارشده را نشان می‌دهد؛ برای وضعیت تماس و transcriptها مفید است، اما هر گذار webhook/realtime در آن ظاهر نمی‌شود. -### تماس بلادرنگ گفتار ندارد +### تماس realtime گفتار ندارد -تأیید کنید فقط یک حالت صوتی فعال است. `realtime.enabled` و -`streaming.enabled` نمی‌توانند هر دو true باشند. +تأیید کنید فقط یک حالت audio فعال است. `realtime.enabled` و `streaming.enabled` نمی‌توانند هر دو true باشند. -برای تماس‌های بلادرنگ Twilio، این موارد را نیز تأیید کنید: +برای تماس‌های realtime Twilio، همچنین بررسی کنید: -- یک Plugin ارائه‌دهنده بلادرنگ بارگذاری و ثبت شده است. -- `realtime.provider` تنظیم نشده یا نام یک ارائه‌دهنده ثبت‌شده را دارد. -- کلید API ارائه‌دهنده برای فرایند Gateway در دسترس است. -- `openclaw logs --follow` نشان می‌دهد TwiML بلادرنگ سرو شده، پل بلادرنگ - شروع شده، و سلام اولیه در صف قرار گرفته است. +- یک Plugin مربوط به provider realtime load و register شده است. +- `realtime.provider` unset است یا نام یک provider ثبت‌شده را دارد. +- کلید API مربوط به provider در دسترس فرایند Gateway است. +- `openclaw logs --follow` نشان می‌دهد TwiML مربوط به realtime serve شده، bridge مربوط به realtime شروع شده، و greeting اولیه در queue قرار گرفته است. ## مرتبط - [حالت گفت‌وگو](/fa/nodes/talk) -- [متن به گفتار](/fa/tools/tts) -- [بیدارسازی صوتی](/fa/nodes/voicewake) +- [تبدیل متن به گفتار](/fa/tools/tts) +- [بیدارباش صوتی](/fa/nodes/voicewake) diff --git a/docs/fa/providers/elevenlabs.md b/docs/fa/providers/elevenlabs.md index dde00dc07..87f3b70b1 100644 --- a/docs/fa/providers/elevenlabs.md +++ b/docs/fa/providers/elevenlabs.md @@ -1,27 +1,27 @@ --- read_when: - می‌خواهید تبدیل متن به گفتار ElevenLabs را در OpenClaw داشته باشید - - به تبدیل گفتار به متن ElevenLabs Scribe برای پیوست‌های صوتی نیاز دارید - - شما رونویسی بلادرنگ ElevenLabs را برای تماس صوتی می‌خواهید -summary: از گفتار ElevenLabs، STT Scribe و رونویسی بلادرنگ با OpenClaw استفاده کنید + - برای پیوست‌های صوتی، تبدیل گفتار به متن ElevenLabs Scribe را می‌خواهید + - شما رونویسی بی‌درنگ ElevenLabs را برای تماس صوتی یا Google Meet می‌خواهید +summary: از گفتار ElevenLabs، Scribe STT و رونویسی بلادرنگ با OpenClaw استفاده کنید title: ElevenLabs x-i18n: - generated_at: "2026-04-29T23:24:53Z" + generated_at: "2026-05-04T07:06:58Z" model: gpt-5.5 provider: openai - source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a + source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b source_path: providers/elevenlabs.md workflow: 16 --- OpenClaw از ElevenLabs برای تبدیل متن به گفتار، تبدیل گفتار به متن دسته‌ای با Scribe -v2، و STT جریانی Voice Call با Scribe v2 Realtime استفاده می‌کند. +v2، و STT جریانی با Scribe v2 Realtime استفاده می‌کند. -| قابلیت | سطح OpenClaw | پیش‌فرض | -| ------------------------ | --------------------------------------------- | ------------------------ | -| تبدیل متن به گفتار | `messages.tts` / `talk` | `eleven_multilingual_v2` | -| تبدیل گفتار به متن دسته‌ای | `tools.media.audio` | `scribe_v2` | -| تبدیل گفتار به متن جریانی | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` | +| قابلیت | سطح OpenClaw | پیش‌فرض | +| ---------------------- | -------------------------------------------------------------------- | ----------------------- | +| تبدیل متن به گفتار | `messages.tts` / `talk` | `eleven_multilingual_v2` | +| تبدیل گفتار به متن دسته‌ای | `tools.media.audio` | `scribe_v2` | +| تبدیل گفتار به متن جریانی | پخش جریانی Voice Call یا Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` | ## احراز هویت @@ -70,22 +70,23 @@ export ELEVENLABS_API_KEY="..." } ``` -OpenClaw صدای multipart را به `/v1/speech-to-text` در ElevenLabs با -`model_id: "scribe_v2"` ارسال می‌کند. در صورت وجود، راهنمایی‌های زبان به `language_code` نگاشت می‌شوند. +OpenClaw صدای چندبخشی را با `model_id: "scribe_v2"` به +`/v1/speech-to-text` در ElevenLabs ارسال می‌کند. در صورت وجود، راهنمایی‌های زبان به +`language_code` نگاشت می‌شوند. -## STT جریانی Voice Call +## STT جریانی -Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی جریانی Voice Call -ثبت می‌کند. +Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی جریانی در حالت عامل Voice Call و +Google Meet ثبت می‌کند. -| تنظیم | مسیر پیکربندی | پیش‌فرض | -| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | -| کلید API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | به `ELEVENLABS_API_KEY` / `XI_API_KEY` بازمی‌گردد | -| مدل | `...elevenlabs.modelId` | `scribe_v2_realtime` | -| قالب صوتی | `...elevenlabs.audioFormat` | `ulaw_8000` | -| نرخ نمونه‌برداری | `...elevenlabs.sampleRate` | `8000` | -| راهبرد commit | `...elevenlabs.commitStrategy` | `vad` | -| زبان | `...elevenlabs.languageCode` | (تنظیم‌نشده) | +| تنظیم | مسیر پیکربندی | پیش‌فرض | +| --------------- | ----------------------------------------------------------------------- | -------------------------------------------------- | +| کلید API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | به `ELEVENLABS_API_KEY` / `XI_API_KEY` بازمی‌گردد | +| مدل | `...elevenlabs.modelId` | `scribe_v2_realtime` | +| قالب صوتی | `...elevenlabs.audioFormat` | `ulaw_8000` | +| نرخ نمونه‌برداری | `...elevenlabs.sampleRate` | `8000` | +| راهبرد ثبت | `...elevenlabs.commitStrategy` | `vad` | +| زبان | `...elevenlabs.languageCode` | (تنظیم‌نشده) | ```json5 { @@ -113,12 +114,18 @@ Plugin همراه `elevenlabs`، Scribe v2 Realtime را برای رونویسی ``` -Voice Call رسانه Twilio را به‌صورت G.711 u-law با فرکانس ۸ kHz دریافت می‌کند. provider بلادرنگ ElevenLabs -به‌صورت پیش‌فرض از `ulaw_8000` استفاده می‌کند، بنابراین فریم‌های تلفنی می‌توانند بدون -تبدیل کدگذاری ارسال شوند. +Voice Call رسانه Twilio را به‌صورت G.711 u-law با نرخ ۸ kHz دریافت می‌کند. ارائه‌دهنده بلادرنگ ElevenLabs +به‌طور پیش‌فرض از `ulaw_8000` استفاده می‌کند، بنابراین فریم‌های تلفنی می‌توانند بدون +تبدیل کدینگ بازفرستاده شوند. +برای حالت عامل Google Meet، مقدار +`plugins.entries.google-meet.config.realtime.transcriptionProvider` را روی +`"elevenlabs"` تنظیم کنید و همان بلوک ارائه‌دهنده را زیر +`plugins.entries.google-meet.config.realtime.providers.elevenlabs` پیکربندی کنید. + ## مرتبط - [تبدیل متن به گفتار](/fa/tools/tts) +- [Google Meet](/fa/plugins/google-meet) - [انتخاب مدل](/fa/concepts/model-providers) diff --git a/docs/fa/providers/google.md b/docs/fa/providers/google.md index e31042022..f74b96aa2 100644 --- a/docs/fa/providers/google.md +++ b/docs/fa/providers/google.md @@ -2,28 +2,28 @@ read_when: - می‌خواهید از مدل‌های Google Gemini با OpenClaw استفاده کنید - به کلید API یا جریان احراز هویت OAuth نیاز دارید -summary: راه‌اندازی Google Gemini (کلید API + OAuth، تولید تصویر، درک رسانه، TTS، جست‌وجوی وب) +summary: راه‌اندازی Google Gemini (کلید API + OAuth، تولید تصویر، درک رسانه، TTS، جستجوی وب) title: Google (Gemini) x-i18n: - generated_at: "2026-05-02T11:59:14Z" + generated_at: "2026-05-04T07:07:27Z" model: gpt-5.5 provider: openai - source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7 + source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908 source_path: providers/google.md workflow: 16 --- -Plugin Google از طریق Google AI Studio به مدل‌های Gemini دسترسی می‌دهد، به‌علاوه -تولید تصویر، فهم رسانه (تصویر/صوت/ویدیو)، تبدیل متن به گفتار، و جست‌وجوی وب از طریق +Plugin Google دسترسی به مدل‌های Gemini را از طریق Google AI Studio فراهم می‌کند، به‌همراه +تولید تصویر، درک رسانه (تصویر/صدا/ویدیو)، تبدیل متن به گفتار، و جست‌وجوی وب از طریق Gemini Grounding. - ارائه‌دهنده: `google` - احراز هویت: `GEMINI_API_KEY` یا `GOOGLE_API_KEY` - API: Google Gemini API -- گزینه زمان اجرا: `agents.defaults.agentRuntime.id: "google-gemini-cli"` - از OAuth مربوط به Gemini CLI دوباره استفاده می‌کند و در عین حال ارجاع‌های مدل را به‌صورت متعارف `google/*` نگه می‌دارد. +- گزینهٔ زمان اجرا: `agents.defaults.agentRuntime.id: "google-gemini-cli"` + ضمن نگه‌داشتن ارجاع‌های مدل به‌شکل رسمی `google/*`، OAuth متعلق به Gemini CLI را دوباره استفاده می‌کند. -## شروع به کار +## شروع کار روش احراز هویت دلخواه خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید. @@ -57,7 +57,7 @@ Gemini Grounding. } ``` - + ```bash openclaw models list --provider google ``` @@ -71,16 +71,16 @@ Gemini Grounding. - **بهترین گزینه برای:** استفاده دوباره از ورود موجود Gemini CLI از طریق PKCE OAuth به‌جای یک کلید API جداگانه. + **بهترین گزینه برای:** استفادهٔ دوباره از ورود موجود Gemini CLI از طریق PKCE OAuth به‌جای یک کلید API جداگانه. - ارائه‌دهنده `google-gemini-cli` یک یکپارچه‌سازی غیررسمی است. برخی کاربران - هنگام استفاده از OAuth به این روش، محدودیت‌های حساب گزارش کرده‌اند. با مسئولیت خودتان استفاده کنید. + ارائه‌دهندهٔ `google-gemini-cli` یک یکپارچه‌سازی غیررسمی است. برخی کاربران + هنگام استفاده از OAuth به این روش، محدودیت‌های حساب را گزارش کرده‌اند. با مسئولیت خودتان استفاده کنید. - فرمان محلی `gemini` باید در `PATH` در دسترس باشد. + دستور محلی `gemini` باید روی `PATH` در دسترس باشد. ```bash # Homebrew @@ -98,7 +98,7 @@ Gemini Grounding. openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google ``` @@ -109,7 +109,7 @@ Gemini Grounding. - زمان اجرا: `google-gemini-cli` - نام مستعار: `gemini-cli` - شناسه مدل Gemini API برای Gemini 3.1 Pro برابر با `gemini-3.1-pro-preview` است. OpenClaw شکل کوتاه‌تر `google/gemini-3.1-pro` را به‌عنوان نام مستعار کاربردی می‌پذیرد و پیش از فراخوانی‌های ارائه‌دهنده آن را عادی‌سازی می‌کند. + شناسهٔ مدل Gemini API برای Gemini 3.1 Pro برابر `gemini-3.1-pro-preview` است. OpenClaw نام کوتاه‌تر `google/gemini-3.1-pro` را به‌عنوان یک نام مستعار راحت می‌پذیرد و پیش از فراخوانی‌های ارائه‌دهنده آن را عادی‌سازی می‌کند. **متغیرهای محیطی:** @@ -119,17 +119,17 @@ Gemini Grounding. (یا گونه‌های `GEMINI_CLI_*`.) - اگر درخواست‌های Gemini CLI OAuth پس از ورود شکست خوردند، `GOOGLE_CLOUD_PROJECT` یا + اگر درخواست‌های OAuth در Gemini CLI پس از ورود ناموفق شدند، `GOOGLE_CLOUD_PROJECT` یا `GOOGLE_CLOUD_PROJECT_ID` را روی میزبان Gateway تنظیم کنید و دوباره تلاش کنید. - اگر ورود پیش از شروع جریان مرورگر شکست می‌خورد، مطمئن شوید فرمان محلی `gemini` - نصب شده و در `PATH` قرار دارد. + اگر ورود قبل از شروع جریان مرورگر ناموفق شد، مطمئن شوید دستور محلی `gemini` + نصب شده و روی `PATH` قرار دارد. ارجاع‌های مدل `google-gemini-cli/*` نام‌های مستعار سازگاری قدیمی هستند. پیکربندی‌های - جدید وقتی اجرای محلی Gemini CLI را می‌خواهند، باید از ارجاع‌های مدل `google/*` به‌همراه زمان اجرای `google-gemini-cli` + جدید باید وقتی اجرای محلی Gemini CLI را می‌خواهند، از ارجاع‌های مدل `google/*` به‌همراه زمان اجرای `google-gemini-cli` استفاده کنند. @@ -137,25 +137,25 @@ Gemini Grounding. ## قابلیت‌ها -| قابلیت | پشتیبانی‌شده | +| قابلیت | پشتیبانی‌شده | | ---------------------- | ----------------------------- | -| تکمیل‌های چت | بله | -| تولید تصویر | بله | -| تولید موسیقی | بله | -| تبدیل متن به گفتار | بله | -| صدای بی‌درنگ | بله (Google Live API) | -| فهم تصویر | بله | -| رونویسی صوت | بله | -| فهم ویدیو | بله | -| جست‌وجوی وب (Grounding) | بله | -| تفکر/استدلال | بله (Gemini 2.5+ / Gemini 3+) | -| مدل‌های Gemma 4 | بله | +| تکمیل‌های چت | بله | +| تولید تصویر | بله | +| تولید موسیقی | بله | +| تبدیل متن به گفتار | بله | +| صدای بلادرنگ | بله (Google Live API) | +| درک تصویر | بله | +| رونویسی صدا | بله | +| درک ویدیو | بله | +| جست‌وجوی وب (Grounding) | بله | +| فکر کردن/استدلال | بله (Gemini 2.5+ / Gemini 3+) | +| مدل‌های Gemma 4 | بله | ## جست‌وجوی وب -ارائه‌دهنده جست‌وجوی وب همراه `gemini` از Gemini Google Search grounding استفاده می‌کند. +ارائه‌دهندهٔ جست‌وجوی وب همراه `gemini` از grounding جست‌وجوی Google در Gemini استفاده می‌کند. یک کلید جست‌وجوی اختصاصی را زیر `plugins.entries.google.config.webSearch` پیکربندی کنید، -یا بگذارید پس از `GEMINI_API_KEY` از `models.providers.google.apiKey` دوباره استفاده کند: +یا اجازه دهید پس از `GEMINI_API_KEY`، از `models.providers.google.apiKey` دوباره استفاده کند: ```json5 { @@ -175,38 +175,38 @@ Gemini Grounding. } ``` -اولویت اعتبارنامه‌ها ابتدا `webSearch.apiKey`، سپس `GEMINI_API_KEY`، +اولویت اعتبارنامه‌ها ابتدا `webSearch.apiKey` اختصاصی، سپس `GEMINI_API_KEY`، و سپس `models.providers.google.apiKey` است. `webSearch.baseUrl` اختیاری است و -برای پراکسی‌های اپراتور یا نقاط پایانی سازگار با Gemini API وجود دارد؛ وقتی حذف شود، -جست‌وجوی وب Gemini از `models.providers.google.baseUrl` دوباره استفاده می‌کند. برای رفتار ابزار اختصاصی ارائه‌دهنده، به -[جست‌وجوی Gemini](/fa/tools/gemini-search) مراجعه کنید. +برای پراکسی‌های اپراتور یا endpointهای سازگار Gemini API وجود دارد؛ وقتی حذف شود، +جست‌وجوی وب Gemini دوباره از `models.providers.google.baseUrl` استفاده می‌کند. برای رفتار ابزار ویژهٔ ارائه‌دهنده، +[جست‌وجوی Gemini](/fa/tools/gemini-search) را ببینید. مدل‌های Gemini 3 به‌جای `thinkingBudget` از `thinkingLevel` استفاده می‌کنند. OpenClaw کنترل‌های استدلال -Gemini 3، Gemini 3.1، و نام مستعار `gemini-*-latest` را به -`thinkingLevel` نگاشت می‌کند تا اجراهای پیش‌فرض/کم‌تاخیر مقدارهای غیرفعال‌شده +نام‌های مستعار Gemini 3، Gemini 3.1، و `gemini-*-latest` را به +`thinkingLevel` نگاشت می‌کند تا اجراهای پیش‌فرض/کم‌تأخیر مقادیر غیرفعال `thinkingBudget` را ارسال نکنند. -`/think adaptive` به‌جای انتخاب یک سطح ثابت OpenClaw، معناشناسی تفکر پویای Google را حفظ می‌کند. Gemini 3 و Gemini 3.1 یک `thinkingLevel` ثابت را حذف می‌کنند تا +`/think adaptive` به‌جای انتخاب یک سطح ثابت OpenClaw، معناشناسی فکر کردن پویای Google را حفظ می‌کند. Gemini 3 و Gemini 3.1 یک `thinkingLevel` ثابت را حذف می‌کنند تا Google بتواند سطح را انتخاب کند؛ Gemini 2.5 sentinel پویای Google یعنی `thinkingBudget: -1` را ارسال می‌کند. -مدل‌های Gemma 4 (برای مثال `gemma-4-26b-a4b-it`) از حالت تفکر پشتیبانی می‌کنند. OpenClaw -`thinkingBudget` را برای Gemma 4 به یک `thinkingLevel` پشتیبانی‌شده Google بازنویسی می‌کند. -تنظیم تفکر روی `off` به‌جای نگاشت به `MINIMAL`، غیرفعال بودن تفکر را حفظ می‌کند. +مدل‌های Gemma 4 (برای مثال `gemma-4-26b-a4b-it`) از حالت فکر کردن پشتیبانی می‌کنند. OpenClaw +برای Gemma 4، `thinkingBudget` را به یک `thinkingLevel` پشتیبانی‌شدهٔ Google بازنویسی می‌کند. +تنظیم فکر کردن روی `off` به‌جای نگاشت به `MINIMAL`، غیرفعال بودن فکر کردن را حفظ می‌کند. ## تولید تصویر -ارائه‌دهنده تولید تصویر همراه `google` به‌صورت پیش‌فرض از +ارائه‌دهندهٔ تولید تصویر همراه `google` به‌صورت پیش‌فرض از `google/gemini-3.1-flash-image-preview` استفاده می‌کند. -- همچنین از `google/gemini-3-pro-image-preview` پشتیبانی می‌کند +- از `google/gemini-3-pro-image-preview` نیز پشتیبانی می‌کند - تولید: تا ۴ تصویر در هر درخواست - حالت ویرایش: فعال، تا ۵ تصویر ورودی - کنترل‌های هندسه: `size`، `aspectRatio`، و `resolution` -برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض تصویر: +برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض تصویر: ```json5 { @@ -221,7 +221,7 @@ Google بتواند سطح را انتخاب کند؛ Gemini 2.5 sentinel پوی ``` -برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید تصویر](/fa/tools/image-generation) مراجعه کنید. +برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید تصویر](/fa/tools/image-generation) را ببینید. ## تولید ویدیو @@ -230,11 +230,11 @@ Plugin همراه `google` تولید ویدیو را نیز از طریق اب `video_generate` ثبت می‌کند. - مدل ویدیوی پیش‌فرض: `google/veo-3.1-fast-generate-preview` -- حالت‌ها: جریان‌های متن به ویدیو، تصویر به ویدیو، و مرجع تک‌ویدیویی +- حالت‌ها: جریان‌های متن به ویدیو، تصویر به ویدیو، و ارجاع تک‌ویدیو - از `aspectRatio`، `resolution`، و `audio` پشتیبانی می‌کند -- محدودیت مدت فعلی: **۴ تا ۸ ثانیه** +- محدودیت مدت‌زمان فعلی: **۴ تا ۸ ثانیه** -برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض ویدیو: +برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض ویدیو: ```json5 { @@ -249,7 +249,7 @@ Plugin همراه `google` تولید ویدیو را نیز از طریق اب ``` -برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید ویدیو](/fa/tools/video-generation) مراجعه کنید. +برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید ویدیو](/fa/tools/video-generation) را ببینید. ## تولید موسیقی @@ -258,13 +258,13 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا `music_generate` ثبت می‌کند. - مدل موسیقی پیش‌فرض: `google/lyria-3-clip-preview` -- همچنین از `google/lyria-3-pro-preview` پشتیبانی می‌کند +- از `google/lyria-3-pro-preview` نیز پشتیبانی می‌کند - کنترل‌های prompt: `lyrics` و `instrumental` -- قالب خروجی: به‌صورت پیش‌فرض `mp3`، به‌علاوه `wav` در `google/lyria-3-pro-preview` +- قالب خروجی: به‌صورت پیش‌فرض `mp3`، به‌علاوهٔ `wav` روی `google/lyria-3-pro-preview` - ورودی‌های مرجع: تا ۱۰ تصویر -- اجراهای مبتنی بر نشست از طریق جریان مشترک کار/وضعیت جدا می‌شوند، از جمله `action: "status"` +- اجراهای متکی به جلسه از طریق جریان مشترک task/status جدا می‌شوند، شامل `action: "status"` -برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض موسیقی: +برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض موسیقی: ```json5 { @@ -279,20 +279,20 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا ``` -برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، به [تولید موسیقی](/fa/tools/music-generation) مراجعه کنید. +برای پارامترهای مشترک ابزار، انتخاب ارائه‌دهنده، و رفتار failover، [تولید موسیقی](/fa/tools/music-generation) را ببینید. ## تبدیل متن به گفتار -ارائه‌دهنده گفتار همراه `google` از مسیر TTS مربوط به Gemini API با +ارائه‌دهندهٔ گفتار همراه `google` از مسیر TTS در Gemini API با `gemini-3.1-flash-tts-preview` استفاده می‌کند. - صدای پیش‌فرض: `Kore` - احراز هویت: `messages.tts.providers.google.apiKey`، `models.providers.google.apiKey`، `GEMINI_API_KEY`، یا `GOOGLE_API_KEY` -- خروجی: WAV برای پیوست‌های معمول TTS، Opus برای مقصدهای یادداشت صوتی، PCM برای Talk/تلفنی -- خروجی یادداشت صوتی: PCM Google به‌صورت WAV بسته‌بندی می‌شود و با `ffmpeg` به Opus با فرکانس ۴۸ kHz تبدیل می‌شود +- خروجی: WAV برای پیوست‌های معمول TTS، Opus برای مقصدهای یادداشت صوتی، PCM برای Talk/تلفن +- خروجی یادداشت صوتی: PCM متعلق به Google به‌صورت WAV بسته‌بندی می‌شود و با `ffmpeg` به Opus با نرخ ۴۸ kHz تبدیل می‌شود -برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض TTS: +برای استفاده از Google به‌عنوان ارائه‌دهندهٔ پیش‌فرض TTS: ```json5 { @@ -312,13 +312,11 @@ Plugin همراه `google` تولید موسیقی را نیز از طریق ا } ``` -Gemini API TTS برای کنترل سبک از prompt به زبان طبیعی استفاده می‌کند. `audioProfile` را تنظیم کنید -تا پیش از متن گفتاری، یک prompt سبک قابل استفاده مجدد اضافه شود. وقتی متن prompt شما به یک گوینده نام‌دار اشاره می‌کند، -`speakerName` را تنظیم کنید. +TTS در Gemini API برای کنترل سبک از prompt زبان طبیعی استفاده می‌کند. `audioProfile` را تنظیم کنید تا یک prompt سبک قابل‌استفادهٔ دوباره پیش از متن گفتاری اضافه شود. وقتی متن prompt شما به یک گویندهٔ نام‌دار اشاره دارد، `speakerName` را تنظیم کنید. -Gemini API TTS همچنین تگ‌های صوتی بیانی در براکت مربع را در متن می‌پذیرد، -مانند `[whispers]` یا `[laughs]`. برای اینکه تگ‌ها در پاسخ چت قابل مشاهده نباشند -اما به TTS ارسال شوند، آن‌ها را داخل یک بلوک `[[tts:text]]...[[/tts:text]]` +TTS در Gemini API همچنین برچسب‌های صوتی بیانی داخل کروشه را در متن می‌پذیرد، +مانند `[whispers]` یا `[laughs]`. برای دور نگه داشتن برچسب‌ها از پاسخ چت قابل‌مشاهده +درحالی‌که آن‌ها را به TTS ارسال می‌کنید، آن‌ها را داخل یک بلوک `[[tts:text]]...[[/tts:text]]` قرار دهید: ```text @@ -328,27 +326,29 @@ Here is the clean reply text. ``` -یک کلید API متعلق به Google Cloud Console که به Gemini API محدود شده باشد برای این -ارائه‌دهنده معتبر است. این مسیر جداگانه Cloud Text-to-Speech API نیست. +یک کلید API در Google Cloud Console که به Gemini API محدود شده باشد، برای این +ارائه‌دهنده معتبر است. این مسیر جداگانهٔ Cloud Text-to-Speech API نیست. -## صدای بی‌درنگ +## صدای بلادرنگ -Plugin همراه `google` یک ارائه‌دهنده صدای بی‌درنگ مبتنی بر -Gemini Live API را برای پل‌های صوتی backend مانند Voice Call و Google Meet ثبت می‌کند. +Plugin همراه `google` یک ارائه‌دهندهٔ صدای بلادرنگ را ثبت می‌کند که با +Gemini Live API برای پل‌های صوتی backend مانند Voice Call و Google Meet پشتیبانی می‌شود. -| تنظیمات | مسیر پیکربندی | پیش‌فرض | +| تنظیم | مسیر پیکربندی | پیش‌فرض | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| مدل | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | -| صدا | `...google.voice` | `Kore` | -| دما | `...google.temperature` | (تنظیم‌نشده) | +| مدل | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | +| صدا | `...google.voice` | `Kore` | +| دما | `...google.temperature` | (تنظیم‌نشده) | | حساسیت شروع VAD | `...google.startSensitivity` | (تنظیم‌نشده) | | حساسیت پایان VAD | `...google.endSensitivity` | (تنظیم‌نشده) | -| مدت سکوت | `...google.silenceDurationMs` | (تنظیم‌نشده) | +| مدت سکوت | `...google.silenceDurationMs` | (تنظیم‌نشده) | | مدیریت فعالیت | `...google.activityHandling` | پیش‌فرض Google، `start-of-activity-interrupts` | -| پوشش نوبت | `...google.turnCoverage` | پیش‌فرض Google، `only-activity` | +| پوشش نوبت | `...google.turnCoverage` | پیش‌فرض Google، `only-activity` | | غیرفعال‌سازی VAD خودکار | `...google.automaticActivityDetectionDisabled` | `false` | -| کلید API | `...google.apiKey` | به `models.providers.google.apiKey`، `GEMINI_API_KEY` یا `GOOGLE_API_KEY` برمی‌گردد | +| ازسرگیری نشست | `...google.sessionResumption` | `true` | +| فشرده‌سازی زمینه | `...google.contextWindowCompression` | `true` | +| کلید API | `...google.apiKey` | به `models.providers.google.apiKey`، `GEMINI_API_KEY`، یا `GOOGLE_API_KEY` بازمی‌گردد | نمونه پیکربندی بلادرنگ تماس صوتی: @@ -380,38 +380,38 @@ Gemini Live API را برای پل‌های صوتی backend مانند Voice Ca Google Live API از صدای دوسویه و فراخوانی تابع از طریق WebSocket استفاده می‌کند. -OpenClaw صدای پل تلفنی/Meet را با جریان PCM Live API متعلق به Gemini سازگار می‌کند و -فراخوانی‌های ابزار را روی قرارداد صدای بلادرنگ مشترک نگه می‌دارد. `temperature` را -تنظیم‌نشده بگذارید، مگر اینکه به تغییرات نمونه‌گیری نیاز داشته باشید؛ OpenClaw مقدارهای غیرمثبت را حذف می‌کند +OpenClaw صدای پل تلفنی/Meet را با جریان PCM Live API در Gemini سازگار می‌کند و +فراخوانی‌های ابزار را روی قرارداد مشترک صدای بلادرنگ نگه می‌دارد. `temperature` را +تنظیم‌نشده بگذارید مگر اینکه به تغییرات نمونه‌گیری نیاز داشته باشید؛ OpenClaw مقدارهای غیرمثبت را حذف می‌کند، چون Google Live می‌تواند برای `temperature: 0` رونوشت‌ها را بدون صدا برگرداند. رونویسی Gemini API بدون `languageCodes` فعال می‌شود؛ SDK فعلی Google راهنمایی‌های کد زبان را در این مسیر API رد می‌کند. -Control UI Talk از نشست‌های مرورگر Google Live با توکن‌های محدودشده یک‌بارمصرف -پشتیبانی می‌کند. ارائه‌دهندگان صدای بلادرنگ فقط‌پشتیبان نیز می‌توانند از طریق انتقال رله عمومی -Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد. +Control UI Talk از نشست‌های مرورگر Google Live با توکن‌های محدود و یک‌بارمصرف +پشتیبانی می‌کند. ارائه‌دهندگان صدای بلادرنگ فقط-بک‌اند همچنین می‌توانند از طریق +انتقال relay عمومی Gateway اجرا شوند که اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد. -برای راستی‌آزمایی زنده توسط نگه‌دارنده، اجرا کنید: +برای راستی‌آزمایی زنده نگه‌دارنده، اجرا کنید: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`. -شاخه Google همان شکل توکن محدودشده Live API را که Control UI Talk استفاده می‌کند صادر می‌کند، -نقطه پایانی WebSocket مرورگر را باز می‌کند، بار اولیه راه‌اندازی را می‌فرستد، +بخش Google همان شکل توکن محدود Live API را صادر می‌کند که Control +UI Talk از آن استفاده می‌کند، نقطه پایانی WebSocket مرورگر را باز می‌کند، محموله راه‌اندازی اولیه را می‌فرستد، و منتظر `setupComplete` می‌ماند. ## پیکربندی پیشرفته - + برای اجراهای مستقیم Gemini API (`api: "google-generative-ai"`)، OpenClaw - یک هندل پیکربندی‌شده `cachedContent` را به درخواست‌های Gemini منتقل می‌کند. + شناسه `cachedContent` پیکربندی‌شده را به درخواست‌های Gemini عبور می‌دهد. - - پارامترهای هر مدل یا سراسری را با یکی از + - پارامترهای سراسری یا مخصوص هر مدل را با `cachedContent` یا `cached_content` قدیمی پیکربندی کنید - - اگر هر دو وجود داشته باشند، `cachedContent` برنده است + - اگر هر دو حاضر باشند، `cachedContent` اولویت دارد - مقدار نمونه: `cachedContents/prebuilt-context` - - مصرف اصابت کش Gemini از + - مصرف cache-hit در Gemini از `cachedContentTokenCount` بالادستی به `cacheRead` در OpenClaw نرمال‌سازی می‌شود ```json5 @@ -432,19 +432,19 @@ Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌ده - - هنگام استفاده از ارائه‌دهنده OAuth متعلق به `google-gemini-cli`، OpenClaw + + هنگام استفاده از ارائه‌دهنده OAuth به نام `google-gemini-cli`، OpenClaw خروجی JSON در CLI را به شکل زیر نرمال‌سازی می‌کند: - متن پاسخ از فیلد `response` در JSON خروجی CLI می‌آید. - - وقتی CLI مقدار `usage` را خالی بگذارد، مصرف به `stats` برمی‌گردد. + - وقتی CLI مقدار `usage` را خالی می‌گذارد، مصرف به `stats` بازمی‌گردد. - `stats.cached` به `cacheRead` در OpenClaw نرمال‌سازی می‌شود. - - اگر `stats.input` وجود نداشته باشد، OpenClaw توکن‌های ورودی را از - `stats.input_tokens - stats.cached` به دست می‌آورد. + - اگر `stats.input` موجود نباشد، OpenClaw توکن‌های ورودی را از + `stats.input_tokens - stats.cached` استخراج می‌کند. - + اگر Gateway به‌صورت daemon اجرا می‌شود (launchd/systemd)، مطمئن شوید `GEMINI_API_KEY` برای آن فرایند در دسترس است (برای مثال، در `~/.openclaw/.env` یا از طریق `env.shellEnv`). @@ -454,16 +454,16 @@ Gateway اجرا شوند، که اعتبارنامه‌های ارائه‌ده ## مرتبط - + انتخاب ارائه‌دهندگان، ارجاع‌های مدل، و رفتار failover. - + پارامترهای ابزار تصویر مشترک و انتخاب ارائه‌دهنده. - - پارامترهای ابزار ویدئوی مشترک و انتخاب ارائه‌دهنده. + + پارامترهای ابزار ویدیوی مشترک و انتخاب ارائه‌دهنده. - + پارامترهای ابزار موسیقی مشترک و انتخاب ارائه‌دهنده. diff --git a/docs/fa/reference/RELEASING.md b/docs/fa/reference/RELEASING.md index 836b1baa3..64b46fd51 100644 --- a/docs/fa/reference/RELEASING.md +++ b/docs/fa/reference/RELEASING.md @@ -1,190 +1,173 @@ --- read_when: - - در حال جست‌وجوی تعاریف کانال انتشار عمومی + - در حال جست‌وجوی تعاریف کانال‌های انتشار عمومی - اجرای اعتبارسنجی انتشار یا پذیرش بسته - - در جست‌وجوی نام‌گذاری نسخه‌ها و چرخه انتشار -summary: مسیرهای انتشار، چک‌لیست اپراتور، محیط‌های اعتبارسنجی، نام‌گذاری نسخه‌ها و چرخه زمانی + - در حال جست‌وجوی نام‌گذاری نسخه‌ها و آهنگ انتشار +summary: مسیرهای انتشار، فهرست بررسی اپراتور، محیط‌های اعتبارسنجی، نام‌گذاری نسخه، و آهنگ انتشار title: سیاست انتشار x-i18n: - generated_at: "2026-05-03T21:38:42Z" + generated_at: "2026-05-04T07:07:47Z" model: gpt-5.5 provider: openai - source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba + source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6 source_path: reference/RELEASING.md workflow: 16 --- OpenClaw سه مسیر انتشار عمومی دارد: -- stable: انتشارهای برچسب‌خورده‌ای که به‌صورت پیش‌فرض در npm `beta` منتشر می‌شوند، یا وقتی صریحا درخواست شود در npm `latest` -- beta: برچسب‌های پیش‌انتشار که در npm `beta` منتشر می‌شوند -- dev: سرِ متحرک `main` +- stable: انتشارهای برچسب‌خورده‌ای که به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند، یا وقتی صریحاً درخواست شود در npm با `latest` منتشر می‌شوند +- beta: برچسب‌های پیش‌انتشار که در npm با `beta` منتشر می‌شوند +- dev: سرِ در حال حرکتِ `main` ## نام‌گذاری نسخه -- نسخه انتشار پایدار: `YYYY.M.D` +- نسخهٔ انتشار پایدار: `YYYY.M.D` - برچسب Git: `vYYYY.M.D` -- نسخه انتشار اصلاحی پایدار: `YYYY.M.D-N` +- نسخهٔ انتشار اصلاحی پایدار: `YYYY.M.D-N` - برچسب Git: `vYYYY.M.D-N` -- نسخه پیش‌انتشار بتا: `YYYY.M.D-beta.N` +- نسخهٔ پیش‌انتشار بتا: `YYYY.M.D-beta.N` - برچسب Git: `vYYYY.M.D-beta.N` -- ماه یا روز را با صفر ابتدایی ننویسید +- ماه یا روز را با صفر پر نکنید - `latest` یعنی انتشار پایدار فعلی npm که ترویج شده است - `beta` یعنی هدف نصب بتای فعلی -- انتشارهای پایدار و اصلاحی پایدار به‌صورت پیش‌فرض در npm `beta` منتشر می‌شوند؛ گردانندگان انتشار می‌توانند صریحا `latest` را هدف بگیرند، یا بعدا یک ساخت بتای بررسی‌شده را ترویج کنند -- هر انتشار پایدار OpenClaw بسته npm و برنامه macOS را با هم ارائه می‌کند؛ - انتشارهای بتا معمولا ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر می‌کنند، و - ساخت/امضا/محضری‌سازی برنامه Mac برای پایدار نگه داشته می‌شود مگر اینکه صریحا درخواست شود +- انتشارهای پایدار و اصلاحی پایدار به‌صورت پیش‌فرض در npm با `beta` منتشر می‌شوند؛ متصدیان انتشار می‌توانند صریحاً `latest` را هدف بگیرند، یا بعداً یک ساخت بتای بررسی‌شده را ترویج کنند +- هر انتشار پایدار OpenClaw بستهٔ npm و برنامهٔ macOS را با هم عرضه می‌کند؛ + انتشارهای بتا معمولاً ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر می‌کنند، و + ساخت/امضا/محضری‌سازی برنامهٔ mac برای نسخهٔ پایدار نگه داشته می‌شود مگر آنکه صریحاً درخواست شود -## آهنگ انتشار +## چرخهٔ انتشار - انتشارها ابتدا از بتا عبور می‌کنند - پایدار فقط پس از اعتبارسنجی آخرین بتا دنبال می‌شود -- نگه‌دارندگان معمولا انتشارها را از شاخه `release/YYYY.M.D` که - از `main` فعلی ساخته شده است انجام می‌دهند، تا اعتبارسنجی انتشار و اصلاحات مانع - توسعه جدید روی `main` نشود +- نگه‌دارندگان معمولاً انتشارها را از شاخهٔ `release/YYYY.M.D` که از + `main` فعلی ساخته شده است جدا می‌کنند، تا اعتبارسنجی انتشار و رفع اشکال‌ها + توسعهٔ جدید روی `main` را مسدود نکند - اگر یک برچسب بتا push یا منتشر شده باشد و به اصلاح نیاز داشته باشد، نگه‌دارندگان - به‌جای حذف یا بازآفرینی برچسب بتای قدیمی، برچسب `-beta.N` بعدی را می‌سازند -- رویه تفصیلی انتشار، تاییدیه‌ها، گواهی‌ها و یادداشت‌های بازیابی - فقط مخصوص نگه‌دارندگان است + به‌جای حذف یا بازسازی برچسب بتای قدیمی، برچسب `-beta.N` بعدی را جدا می‌کنند +- رویهٔ تفصیلی انتشار، تأییدها، اعتبارنامه‌ها، و یادداشت‌های بازیابی + فقط مخصوص نگه‌داران است -## چک‌لیست گرداننده انتشار +## چک‌لیست متصدی انتشار -این چک‌لیست شکل عمومی جریان انتشار است. گواهی‌های خصوصی، -امضا، محضری‌سازی، بازیابی dist-tag، و جزئیات بازگردانی اضطراری در -راهنمای اجرای انتشار مخصوص نگه‌دارندگان باقی می‌ماند. +این چک‌لیست شکل عمومی جریان انتشار است. اعتبارنامه‌های خصوصی، +امضا، محضری‌سازی، بازیابی dist-tag، و جزئیات rollback اضطراری در +دستورالعمل اجرایی انتشارِ فقط مخصوص نگه‌داران باقی می‌ماند. -1. از `main` فعلی شروع کنید: آخرین تغییرات را pull کنید، تایید کنید commit هدف push شده است، - و تایید کنید CI فعلی `main` به‌اندازه کافی سبز است که بتوان از آن شاخه ساخت. -2. بخش بالایی `CHANGELOG.md` را از تاریخچه واقعی commitها با - `/changelog` بازنویسی کنید، ورودی‌ها را کاربرمحور نگه دارید، آن را commit کنید، push کنید، و پیش از شاخه‌سازی - یک بار دیگر rebase/pull کنید. +1. از `main` فعلی شروع کنید: آخرین تغییرات را pull کنید، تأیید کنید commit هدف push شده است، + و تأیید کنید CI فعلی `main` به‌اندازهٔ کافی سبز است که بتوان از آن شاخه ساخت. +2. بخش بالایی `CHANGELOG.md` را از تاریخچهٔ واقعی commit با + `/changelog` بازنویسی کنید، ورودی‌ها را کاربرمحور نگه دارید، آن را commit و push کنید، و + پیش از ساخت شاخه یک بار دیگر rebase/pull کنید. 3. رکوردهای سازگاری انتشار را در `src/plugins/compat/registry.ts` و - `src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضی‌شده را - فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا - عمدا نگه داشته شده است. + `src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضی‌شده را فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا + عمداً حفظ شده است. 4. `release/YYYY.M.D` را از `main` فعلی بسازید؛ کار عادی انتشار را - مستقیما روی `main` انجام ندهید. -5. همه محل‌های نسخه لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بسته‌های Plugin قابل انتشار نسخه انتشار - و فراداده سازگاری مشترک داشته باشند، سپس پیش‌پرواز قطعی محلی را اجرا کنید: + مستقیماً روی `main` انجام ندهید. +5. همهٔ محل‌های نسخهٔ لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بسته‌های Plugin قابل انتشار نسخهٔ انتشار + و فرادادهٔ سازگاری مشترک داشته باشند، سپس پیش‌بررسی قطعی محلی را اجرا کنید: `pnpm check:test-types`، `pnpm check:architecture`، `pnpm build && pnpm ui:build`، `pnpm plugins:sync:check`، و `pnpm release:check`. 6. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید. پیش از وجود برچسب، - یک SHA کامل ۴۰کاراکتری شاخه انتشار برای پیش‌پرواز صرفا اعتبارسنجی + یک SHA کامل ۴۰ نویسه‌ای از شاخهٔ انتشار برای پیش‌بررسی صرفاً اعتبارسنجی مجاز است. `preflight_run_id` موفق را ذخیره کنید. -7. همه آزمون‌های پیش از انتشار را با `Full Release Validation` برای - شاخه انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطه ورود دستی - برای چهار جعبه آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package. -8. اگر اعتبارسنجی شکست خورد، روی شاخه انتشار اصلاح کنید و کوچک‌ترین - فایل، مسیر، job گردش‌کار، پروفایل بسته، ارائه‌دهنده، یا allowlist مدل شکست‌خورده را - که اصلاح را اثبات می‌کند دوباره اجرا کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییریافته +7. همهٔ آزمون‌های پیش از انتشار را با `Full Release Validation` برای + شاخهٔ انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطهٔ ورود دستی + برای چهار جعبهٔ آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package. +8. اگر اعتبارسنجی شکست خورد، روی شاخهٔ انتشار اصلاح کنید و کوچک‌ترین + فایل، مسیر، job گردش‌کار، پروفایل بسته، provider، یا allowlist مدل شکست‌خورده‌ای را که + اصلاح را اثبات می‌کند دوباره اجرا کنید. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییرکرده شواهد قبلی را کهنه کند. 9. برای بتا، `vYYYY.M.D-beta.N` را برچسب بزنید، سپس `OpenClaw Release Publish` را از - شاخه منطبق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تایید می‌کند، - ابتدا همه بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، همان - مجموعه را در مرحله دوم به‌صورت tarballهای npm-pack مربوط به ClawPack در ClawHub منتشر می‌کند، و سپس - artifact آماده پیش‌پرواز npm مربوط به OpenClaw را با dist-tag منطبق ترویج می‌کند. پس از - انتشار، پذیرش بسته پس از انتشار را - در برابر بسته منتشرشده `openclaw@YYYY.M.D-beta.N` یا + شاخهٔ منطبق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تأیید می‌کند، + ابتدا همهٔ بسته‌های Plugin قابل انتشار را در npm منتشر می‌کند، سپس همان + مجموعه را به‌عنوان tarballهای ClawPack npm-pack در ClawHub منتشر می‌کند، و بعد + مصنوع پیش‌بررسی npm آمادهٔ OpenClaw را با dist-tag منطبق ترویج می‌کند. پس از + انتشار، پذیرش بستهٔ پس از انتشار را در برابر بستهٔ منتشرشدهٔ + `openclaw@YYYY.M.D-beta.N` یا `openclaw@beta` اجرا کنید. اگر یک پیش‌انتشار push یا منتشرشده به اصلاح نیاز داشت، - شماره پیش‌انتشار منطبق بعدی را بسازید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید. -10. برای پایدار، فقط پس از آن ادامه دهید که بتا یا کاندیدای انتشار بررسی‌شده - شواهد اعتبارسنجی لازم را داشته باشد. انتشار npm پایدار نیز از طریق - `OpenClaw Release Publish` انجام می‌شود و با استفاده از - `preflight_run_id` از artifact موفق پیش‌پرواز دوباره استفاده می‌کند؛ آمادگی انتشار پایدار macOS همچنین به + شمارهٔ پیش‌انتشار منطبق بعدی را جدا کنید؛ پیش‌انتشار قدیمی را حذف یا بازنویسی نکنید. +10. برای پایدار، فقط پس از آن ادامه دهید که بتا یا نامزد انتشار بررسی‌شده + شواهد اعتبارسنجی لازم را داشته باشد. انتشار پایدار npm نیز از طریق + `OpenClaw Release Publish` انجام می‌شود، با استفادهٔ دوباره از مصنوع پیش‌بررسی موفق از طریق + `preflight_run_id`؛ آمادگی انتشار پایدار macOS همچنین به `.zip`، `.dmg`، `.dSYM.zip` بسته‌بندی‌شده، و `appcast.xml` به‌روزشده روی `main` نیاز دارد. -11. پس از انتشار، تاییدکننده پس از انتشار npm، آزمون اختیاری E2E مستقل - Telegram منتشرشده از npm وقتی به اثبات کانال پس از انتشار نیاز دارید، - ترویج dist-tag در صورت نیاز، یادداشت‌های انتشار/پیش‌انتشار GitHub از بخش - کامل و منطبق `CHANGELOG.md`، و گام‌های اعلام انتشار - را اجرا کنید. +11. پس از انتشار، تأییدگر پس از انتشار npm، E2E اختیاری Telegram برای + npm منتشرشدهٔ مستقل وقتی به اثبات کانال پس از انتشار نیاز دارید، + ترویج dist-tag در صورت نیاز، یادداشت‌های انتشار/پیش‌انتشار GitHub از + بخش کامل و منطبق `CHANGELOG.md`، و گام‌های اعلام انتشار را اجرا کنید. -## پیش‌پرواز انتشار +## پیش‌بررسی انتشار -- پیش از پیش‌پرواز انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript آزمون‌ها بیرون از دروازه سریع‌تر محلی `pnpm check` نیز پوشش داده شود -- پیش از پیش‌پرواز انتشار، `pnpm check:architecture` را اجرا کنید تا بررسی‌های گسترده‌تر چرخه import و مرزهای معماری بیرون از دروازه سریع‌تر محلی سبز باشند -- پیش از `pnpm release:check`، `pnpm build && pnpm ui:build` را اجرا کنید تا آرتیفکت‌های انتشار مورد انتظار `dist/*` و بسته Control UI برای مرحله اعتبارسنجی بسته‌بندی وجود داشته باشند -- پس از افزایش نسخه ریشه و پیش از برچسب‌گذاری، `pnpm plugins:sync` را اجرا کنید. این دستور نسخه‌های بسته‌های Plugin قابل انتشار، فراداده سازگاری peer/API مربوط به OpenClaw، فراداده ساخت، و stubهای changelog مربوط به Plugin را به‌روزرسانی می‌کند تا با نسخه انتشار هسته هماهنگ شوند. `pnpm plugins:sync:check` نگهبان انتشار غیرتغییردهنده است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد. -- پیش از تأیید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه test boxهای پیش از انتشار از یک entrypoint آغاز شوند. این workflow یک شاخه، برچسب، یا SHA کامل commit را می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعه‌های مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E بسته را در برابر آرتیفکت `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، زمانی `npm_telegram_package_spec` را ارائه کنید که همان Telegram E2E باید بسته npm منتشرشده را نیز اثبات کند. پس از انتشار، زمانی `package_acceptance_package_spec` را ارائه کنید که Package Acceptance باید ماتریس package/update خود را به‌جای آرتیفکت ساخته‌شده از SHA، در برابر بسته npm ارسال‌شده اجرا کند. زمانی `evidence_package_spec` را ارائه کنید که گزارش private evidence باید بدون اجبار Telegram E2E اثبات کند که اعتبارسنجی با یک بسته npm منتشرشده مطابقت دارد. مثال: +- پیش از بررسی مقدماتی انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript تست‌ها خارج از gate سریع‌تر محلی `pnpm check` همچنان پوشش داده شود +- پیش از بررسی مقدماتی انتشار، `pnpm check:architecture` را اجرا کنید تا بررسی‌های گسترده‌تر چرخه‌های import و مرزهای معماری خارج از gate سریع‌تر محلی سبز باشند +- پیش از `pnpm release:check`، `pnpm build && pnpm ui:build` را اجرا کنید تا artifactهای انتشار مورد انتظار `dist/*` و bundle رابط کاربری کنترل برای مرحله اعتبارسنجی pack موجود باشند +- پس از افزایش نسخه ریشه و پیش از tag زدن، `pnpm plugins:sync` را اجرا کنید. این دستور نسخه‌های packageهای Plugin قابل انتشار، فراداده سازگاری peer/API مربوط به OpenClaw، فراداده build، و stubهای changelog Plugin را به‌روزرسانی می‌کند تا با نسخه انتشار core هم‌خوان شوند. `pnpm plugins:sync:check` نگهبان غیرتغییردهنده انتشار است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست می‌خورد. +- پیش از تأیید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه test boxهای پیش از انتشار از یک entrypoint آغاز شوند. این workflow یک branch، tag، یا commit SHA کامل می‌پذیرد، `CI` دستی را dispatch می‌کند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، suiteهای مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch می‌کند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E package را روی artifact `release-package-under-test` از release checks اجرا می‌کند. پس از انتشار، وقتی همان Telegram E2E باید package منتشرشده npm را هم اثبات کند، `npm_telegram_package_spec` را ارائه کنید. پس از انتشار، وقتی Package Acceptance باید matrix package/update خود را به‌جای artifact ساخته‌شده از SHA روی package ارسال‌شده npm اجرا کند، `package_acceptance_package_spec` را ارائه کنید. وقتی گزارش evidence خصوصی باید بدون اجبار Telegram E2E اثبات کند که اعتبارسنجی با یک package منتشرشده npm مطابقت دارد، `evidence_package_spec` را ارائه کنید. مثال: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- workflow دستی `Package Acceptance` را زمانی اجرا کنید که می‌خواهید در حین ادامه کار انتشار، اثبات side-channel برای یک نامزد بسته داشته باشید. از `source=npm` برای `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار استفاده کنید؛ از `source=ref` برای بسته‌بندی یک شاخه/برچسب/SHA مطمئن `package_ref` با harness فعلی `workflow_ref` استفاده کنید؛ از `source=url` برای یک tarball HTTPS با SHA-256 الزامی استفاده کنید؛ یا از `source=artifact` برای tarballی که توسط اجرای دیگری از GitHub Actions آپلود شده است استفاده کنید. این workflow نامزد را به `package-under-test` resolve می‌کند، scheduler انتشار Docker E2E را در برابر همان tarball دوباره استفاده می‌کند، و می‌تواند QA مربوط به Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` در برابر همان tarball اجرا کند. وقتی laneهای انتخاب‌شده Docker شامل `published-upgrade-survivor` باشند، آرتیفکت بسته همان نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند. +- وقتی می‌خواهید در حالی که کار انتشار ادامه دارد برای یک candidate package اثبات جانبی بگیرید، workflow دستی `Package Acceptance` را اجرا کنید. برای `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق از `source=npm` استفاده کنید؛ برای pack کردن یک branch/tag/SHA قابل اعتماد `package_ref` با harness فعلی `workflow_ref` از `source=ref` استفاده کنید؛ برای یک tarball HTTPS با SHA-256 الزامی از `source=url` استفاده کنید؛ یا برای tarball آپلودشده توسط اجرای دیگری از GitHub Actions از `source=artifact` استفاده کنید. این workflow candidate را به `package-under-test` resolve می‌کند، scheduler انتشار Docker E2E را روی آن tarball بازاستفاده می‌کند، و می‌تواند QA Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` روی همان tarball اجرا کند. وقتی laneهای Docker انتخاب‌شده شامل `published-upgrade-survivor` باشند، artifact package همان candidate است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب می‌کند. مثال: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - پروفایل‌های رایج: - - `smoke`: laneهای نصب/channel/agent، شبکه Gateway، و بارگذاری مجدد config - - `package`: laneهای package/update/plugin بومی آرتیفکت بدون OpenWebUI یا ClawHub زنده - - `product`: پروفایل package به‌همراه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI + profileهای رایج: + - `smoke`: laneهای install/channel/agent، شبکه Gateway، و reload پیکربندی + - `package`: laneهای package/update/plugin بومی artifact بدون OpenWebUI یا ClawHub زنده + - `product`: profile package به‌علاوه channelهای MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI - `full`: بخش‌های مسیر انتشار Docker با OpenWebUI - - `custom`: انتخاب دقیق `docker_lanes` برای یک اجرای مجدد متمرکز -- زمانی workflow دستی `CI` را مستقیم اجرا کنید که فقط به پوشش کامل CI عادی برای نامزد انتشار نیاز دارید. dispatchهای دستی CI از scoping تغییرات عبور می‌کنند و shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n مربوط به Control UI را اجباری اجرا می‌کنند. + - `custom`: انتخاب دقیق `docker_lanes` برای rerun متمرکز +- وقتی فقط به پوشش کامل CI عادی برای candidate انتشار نیاز دارید، workflow دستی `CI` را مستقیم اجرا کنید. dispatchهای CI دستی scoping بر اساس تغییرات را دور می‌زنند و shardهای Linux Node، shardهای bundled-plugin، contractهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n رابط کاربری کنترل را اجباری می‌کنند. مثال: `gh workflow run ci.yml --ref release/YYYY.M.D` -- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک گیرنده محلی OTLP/HTTP تمرین می‌دهد و نام‌های span مربوط به trace خروجی، attributeهای محدودشده، و redaction محتوا/شناسه را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر بررسی می‌کند. -- پیش از هر انتشار برچسب‌دار، `pnpm release:check` را اجرا کنید -- پس از وجود داشتن برچسب، `OpenClaw Release Publish` را برای توالی انتشار تغییردهنده اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید، یا زمانی که یک برچسب قابل دسترسی از main را منتشر می‌کنید از `main` dispatch کنید، برچسب انتشار و `preflight_run_id` موفق npm مربوط به OpenClaw را بدهید، و scope پیش‌فرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً یک ترمیم متمرکز را اجرا می‌کنید. این workflow انتشار npm مربوط به Plugin، انتشار Plugin در ClawHub، و انتشار npm مربوط به OpenClaw را به‌صورت ترتیبی انجام می‌دهد تا بسته هسته پیش از Pluginهای externalized خود منتشر نشود. -- بررسی‌های انتشار اکنون در یک workflow دستی جداگانه اجرا می‌شوند: +- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک receiver محلی OTLP/HTTP اجرا می‌کند و نام spanهای trace صادرشده، attributeهای محدود، و redact شدن content/identifier را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر بررسی می‌کند. +- پیش از هر انتشار tagشده، `pnpm release:check` را اجرا کنید +- پس از وجود tag، برای دنباله انتشار تغییردهنده `OpenClaw Release Publish` را اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید (یا هنگام انتشار tag قابل دسترسی از main، از `main`)، tag انتشار و `preflight_run_id` موفق OpenClaw npm را پاس بدهید، و scope پیش‌فرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً تعمیر متمرکز اجرا می‌کنید. این workflow انتشار npm مربوط به Plugin، انتشار Plugin در ClawHub، و انتشار OpenClaw در npm را سریالی می‌کند تا package core پیش از Pluginهای externalized خود منتشر نشود. +- اکنون release checks در یک workflow دستی جداگانه اجرا می‌شوند: `OpenClaw Release Checks` -- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock مربوط به QA Lab به‌همراه پروفایل live سریع Matrix و lane QA مربوط به Telegram را اجرا می‌کند. laneهای live از محیط `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از اجاره credential مربوط به Convex CI استفاده می‌کند. زمانی workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید که می‌خواهید موجودی کامل transport، media، و E2EE مربوط به Matrix به‌صورت موازی اجرا شود. -- اعتبارسنجی runtime نصب و ارتقا در سیستم‌عامل‌های مختلف بخشی از workflow عمومی `OpenClaw Release Checks` و `Full Release Validation` است که workflow reusable زیر را مستقیم فراخوانی می‌کنند: - `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- این جداسازی عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی، و متمرکز بر آرتیفکت نگه می‌دارد، در حالی که بررسی‌های live کندتر در lane خودشان می‌مانند تا انتشار را متوقف یا مسدود نکنند -- بررسی‌های انتشار دارای secret باید از طریق `Full Release Validation` یا از ref workflow مربوط به `main`/release dispatch شوند تا منطق workflow و secretها کنترل‌شده بمانند -- `OpenClaw Release Checks` یک شاخه، برچسب، یا SHA کامل commit را می‌پذیرد، به شرطی که commit resolveشده از یک شاخه OpenClaw یا برچسب انتشار قابل دسترسی باشد -- پیش‌پرواز فقط‌اعتبارسنجی `OpenClaw NPM Release` نیز SHA کامل ۴۰ کاراکتری commit شاخه workflow فعلی را بدون نیاز به برچسب pushشده می‌پذیرد -- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به انتشار واقعی ارتقا داده شود -- در حالت SHA، workflow فقط برای بررسی فراداده بسته `v` را می‌سازد؛ انتشار واقعی همچنان به یک برچسب انتشار واقعی نیاز دارد +- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane برابری mock در QA Lab به‌علاوه profile سریع Matrix زنده و lane QA Telegram را اجرا می‌کند. laneهای زنده از environment `qa-live-shared` استفاده می‌کنند؛ Telegram همچنین از leaseهای credential مربوط به Convex CI استفاده می‌کند. وقتی inventory کامل transport، media، و E2EE مربوط به Matrix را به‌صورت موازی می‌خواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید. +- اعتبارسنجی runtime نصب و upgrade میان سیستم‌عامل‌ها بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است، که workflow قابل بازاستفاده `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی می‌کنند +- این تفکیک عمدی است: مسیر واقعی انتشار npm را کوتاه، قطعی، و متمرکز بر artifact نگه دارید، در حالی که بررسی‌های زنده کندتر در lane خودشان باقی می‌مانند تا انتشار را متوقف یا block نکنند +- release checkهایی که secret دارند باید از طریق `Full Release Validation` یا از workflow ref مربوط به `main`/release dispatch شوند تا logic workflow و secretها کنترل‌شده بمانند +- `OpenClaw Release Checks` یک branch، tag، یا commit SHA کامل را می‌پذیرد تا زمانی که commit resolveشده از یک branch یا tag انتشار OpenClaw قابل دسترسی باشد +- بررسی مقدماتی فقط-اعتبارسنجی `OpenClaw NPM Release` نیز commit SHA کامل ۴۰ کاراکتری branch workflow فعلی را بدون نیاز به tag pushشده می‌پذیرد +- آن مسیر SHA فقط برای اعتبارسنجی است و نمی‌تواند به یک انتشار واقعی promote شود +- در حالت SHA، workflow فقط برای بررسی فراداده package مقدار `v` را synthesize می‌کند؛ انتشار واقعی همچنان به tag واقعی انتشار نیاز دارد - هر دو workflow مسیر واقعی انتشار و promotion را روی runnerهای GitHub-hosted نگه می‌دارند، در حالی که مسیر اعتبارسنجی غیرتغییردهنده می‌تواند از runnerهای بزرگ‌تر Blacksmith Linux استفاده کند -- آن workflow دستور - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - را با استفاده از secretهای workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا می‌کند -- پیش‌پرواز انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند -- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` را اجرا کنید - (یا برچسب beta/correction متناظر را) -- پس از انتشار npm، دستور - `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - را اجرا کنید - (یا نسخه beta/correction متناظر را) تا مسیر نصب registry منتشرشده در یک prefix موقت تازه بررسی شود -- پس از انتشار beta، دستور `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - را اجرا کنید تا onboarding بسته نصب‌شده، راه‌اندازی Telegram، و Telegram E2E واقعی در برابر بسته npm منتشرشده با استفاده از pool مشترک credential اجاره‌ای Telegram بررسی شود. maintainerها برای اجراهای موردی محلی می‌توانند متغیرهای Convex را حذف کنند و سه credential محیطی `OPENCLAW_QA_TELEGRAM_*` را مستقیم بدهند. -- maintainerها می‌توانند همین بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود. -- اتوماسیون انتشار maintainer اکنون از preflight-then-promote استفاده می‌کند: - - انتشار واقعی npm باید یک `preflight_run_id` موفق npm داشته باشد - - انتشار واقعی npm باید از همان شاخه `main` یا `release/YYYY.M.D` dispatch شود که اجرای پیش‌پرواز موفق از آن بوده است - - انتشارهای پایدار npm به‌طور پیش‌فرض روی `beta` هستند - - انتشار پایدار npm می‌تواند از طریق ورودی workflow به‌صورت صریح `latest` را هدف بگیرد - - تغییر npm dist-tag مبتنی بر token اکنون برای امنیت در - `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - قرار دارد، چون `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالی که repo عمومی انتشار فقط OIDC را نگه می‌دارد - - `macOS Release` عمومی فقط‌اعتبارسنجی است؛ وقتی یک برچسب فقط روی شاخه release وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید - - انتشار واقعی خصوصی mac باید `preflight_run_id` و `validate_run_id` موفق خصوصی mac را داشته باشد - - مسیرهای واقعی انتشار، آرتیفکت‌های آماده‌شده را promote می‌کنند به‌جای اینکه دوباره آن‌ها را build کنند -- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار مسیر ارتقای temp-prefix یکسان را از `YYYY.M.D` به `YYYY.M.D-N` نیز بررسی می‌کند تا correctionهای انتشار نتوانند بی‌صدا نصب‌های global قدیمی‌تر را روی payload پایدار پایه باقی بگذارند -- پیش‌پرواز انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball شامل هر دو payload یعنی `dist/control-ui/index.html` و `dist/control-ui/assets/` غیرخالی باشد، تا دوباره یک dashboard مرورگر خالی ارسال نکنیم -- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای Plugin منتشرشده و فراداده package در layout نصب‌شده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند در verifier پس از انتشار شکست می‌خورد و نمی‌تواند به `latest` promote شود. -- `pnpm test:install:smoke` همچنین بودجه `unpackedSize` مربوط به npm pack را روی tarball به‌روزرسانی نامزد enforce می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، pack bloat تصادفی را می‌گیرد -- اگر کار انتشار به برنامه‌ریزی CI، manifestهای زمان‌بندی extension، یا ماتریس‌های آزمون extension دست زده است، پیش از تأیید خروجی‌های ماتریس `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره تولید و بازبینی کنید تا release notes یک layout قدیمی CI را توصیف نکند -- آمادگی انتشار پایدار macOS همچنین شامل سطح‌های updater است: - - انتشار GitHub باید در نهایت `.zip`، `.dmg`، و `.dSYM.zip` بسته‌بندی‌شده را داشته باشد - - پس از انتشار، `appcast.xml` روی `main` باید به zip پایدار جدید اشاره کند - - اپ بسته‌بندی‌شده باید bundle id غیرdebug، URL غیرخالی Sparkle feed، و `CFBundleVersion` برابر یا بالاتر از کف canonical build مربوط به Sparkle برای آن نسخه انتشار را حفظ کند +- آن workflow دستور `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` را با استفاده از هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا می‌کند +- بررسی مقدماتی انتشار npm دیگر منتظر lane جداگانه release checks نمی‌ماند +- پیش از تأیید، `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` را اجرا کنید (یا tag متناظر beta/correction) +- پس از انتشار npm، برای بررسی مسیر نصب registry منتشرشده در یک temp prefix تازه، `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` را اجرا کنید (یا نسخه متناظر beta/correction) +- پس از انتشار beta، برای بررسی onboarding package نصب‌شده، راه‌اندازی Telegram، و Telegram E2E واقعی روی package منتشرشده npm با استفاده از pool مشترک credentialهای اجاره‌ای Telegram، `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` را اجرا کنید. اجرای موردی محلی توسط maintainer می‌تواند vars مربوط به Convex را حذف کند و سه credential env یعنی `OPENCLAW_QA_TELEGRAM_*` را مستقیم پاس بدهد. +- برای اجرای smoke کامل beta پس از انتشار از ماشین maintainer، از `pnpm release:beta-smoke -- --beta betaN` استفاده کنید. helper اعتبارسنجی Parallels برای npm update/fresh-target را اجرا می‌کند، `NPM Telegram Beta E2E` را dispatch می‌کند، اجرای دقیق workflow را poll می‌کند، artifact را دانلود می‌کند، و گزارش Telegram را چاپ می‌کند. +- maintainers می‌توانند همان بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمی‌شود. +- automation انتشار maintainer اکنون از preflight-then-promote استفاده می‌کند: + - انتشار واقعی npm باید از یک `preflight_run_id` موفق npm عبور کند + - انتشار واقعی npm باید از همان branch `main` یا `release/YYYY.M.D` اجرا شود که preflight موفق از آن اجرا شده است + - انتشارهای stable npm به‌طور پیش‌فرض روی `beta` قرار می‌گیرند + - انتشار stable npm می‌تواند از طریق ورودی workflow صراحتاً `latest` را هدف بگیرد + - تغییر token-based در dist-tagهای npm اکنون برای امنیت در `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` قرار دارد، زیرا `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالی که repo عمومی انتشار فقط با OIDC را نگه می‌دارد + - `macOS Release` عمومی فقط اعتبارسنجی است؛ وقتی یک tag فقط روی branch انتشار وجود دارد اما workflow از `main` dispatch می‌شود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید + - انتشار واقعی private mac باید از `preflight_run_id` و `validate_run_id` موفق private mac عبور کند + - مسیرهای واقعی انتشار artifactهای آماده‌شده را promote می‌کنند به‌جای اینکه دوباره آن‌ها را rebuild کنند +- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر upgrade با temp-prefix از `YYYY.M.D` به `YYYY.M.D-N` را بررسی می‌کند تا correctionهای انتشار نتوانند بی‌سروصدا نصب‌های global قدیمی‌تر را روی payload پایدار پایه باقی بگذارند +- بررسی مقدماتی انتشار npm به‌صورت fail-closed شکست می‌خورد مگر اینکه tarball هم `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` را شامل شود تا دوباره dashboard مرورگر خالی ارسال نکنیم +- اعتبارسنجی پس از انتشار همچنین بررسی می‌کند که entrypointهای Plugin منتشرشده و فراداده package در layout نصب‌شده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند، verifier پس از انتشار را fail می‌کند و نمی‌تواند به `latest` promote شود. +- `pnpm test:install:smoke` همچنین budget مربوط به `unpackedSize` در npm pack را روی tarball candidate update اعمال می‌کند، بنابراین installer e2e پیش از مسیر انتشار release، افزایش ناخواسته حجم pack را می‌گیرد +- اگر کار انتشار به برنامه‌ریزی CI، manifestهای زمان‌بندی extension، یا matrixهای تست extension دست زده است، پیش از تأیید، outputهای matrix مربوط به `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره generate و review کنید تا release notes layout کهنه CI را توصیف نکند +- آمادگی انتشار stable macOS همچنین شامل سطوح updater است: + - GitHub release باید در نهایت شامل `.zip`، `.dmg`، و `.dSYM.zip` packageشده باشد + - `appcast.xml` روی `main` باید پس از انتشار به zip پایدار جدید اشاره کند + - app بسته‌بندی‌شده باید bundle id غیر-debug، URL feed غیرخالی Sparkle، و `CFBundleVersion` در حداقل کف build canonical Sparkle یا بالاتر برای آن نسخه انتشار را حفظ کند -## جعبه‌های آزمون انتشار +## test boxهای انتشار -`Full Release Validation` روشی است که operatorها با آن همه آزمون‌های پیش از انتشار را از -یک entrypoint آغاز می‌کنند. برای اثبات commit پین‌شده روی شاخه‌ای که سریع تغییر می‌کند، از -helper استفاده کنید تا هر workflow فرزند از یک شاخه موقت ثابت‌شده روی SHA هدف اجرا شود: +`Full Release Validation` روشی است که operatorها با آن همه تست‌های پیش از انتشار را از یک entrypoint آغاز می‌کنند. برای اثبات commit pinشده روی branch پرتحرک، از helper استفاده کنید تا هر workflow فرزند از یک branch موقت ثابت‌شده روی SHA هدف اجرا شود: ```bash pnpm ci:full-release --sha ``` -این helper شاخه `release-ci/-...` را push می‌کند، `Full Release Validation` -را از آن شاخه با `ref=` dispatch می‌کند، بررسی می‌کند که `headSha` -هر workflow فرزند با هدف مطابقت داشته باشد، سپس شاخه موقت را حذف می‌کند. این کار از اثبات تصادفی -اجرای فرزند جدیدتر `main` جلوگیری می‌کند. +helper مقدار `release-ci/-...` را push می‌کند، `Full Release Validation` را از آن branch با `ref=` dispatch می‌کند، بررسی می‌کند که `headSha` هر workflow فرزند با هدف مطابقت داشته باشد، سپس branch موقت را حذف می‌کند. این کار از اثبات تصادفی یک اجرای فرزند جدیدتر روی `main` جلوگیری می‌کند. -برای اعتبارسنجی شاخه یا برچسب انتشار، آن را از ref workflow مطمئن `main` اجرا کنید -و شاخه یا برچسب انتشار را به‌عنوان `ref` بدهید: +برای اعتبارسنجی branch یا tag انتشار، آن را از workflow ref قابل اعتماد `main` اجرا کنید و branch یا tag انتشار را به‌عنوان `ref` پاس بدهید: ```bash gh workflow run full-release-validation.yml \ @@ -196,45 +179,47 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -گردش‌کار ref هدف را resolve می‌کند، `CI` دستی را با -`target_ref=` dispatch می‌کند، `OpenClaw Release Checks` را dispatch می‌کند، artifact والد -`release-package-under-test` را برای بررسی‌های ناظر به package آماده می‌کند، و -E2E مستقل Telegram برای package را وقتی `release_profile=full` با -`rerun_group=all` باشد یا وقتی `npm_telegram_package_spec` تنظیم شده باشد dispatch می‌کند. سپس `OpenClaw Release -Checks` به install smoke، بررسی‌های انتشار میان‌سیستم‌عاملی، پوشش live/E2E Docker -در مسیر انتشار، Package Acceptance با QA برای package Telegram، هم‌ارزی QA Lab، -Matrix زنده، و Telegram زنده fan out می‌شود. اجرای کامل فقط وقتی قابل قبول است که -خلاصه `Full Release Validation` -، `normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all، +گردش‌کار، ref هدف را resolve می‌کند، `CI` دستی را با +`target_ref=` dispatch می‌کند، `OpenClaw Release Checks` را dispatch می‌کند، یک +artifact والد `release-package-under-test` را برای بررسی‌های مرتبط با بسته آماده می‌کند، و +وقتی `release_profile=full` با `rerun_group=all` باشد یا وقتی +`npm_telegram_package_spec` تنظیم شده باشد، E2E مستقل بسته Telegram را dispatch می‌کند. سپس `OpenClaw Release +Checks` بررسی‌های install smoke، بررسی‌های انتشار cross-OS، پوشش مسیر انتشار live/E2E Docker، +Package Acceptance با QA بسته Telegram، برابری QA Lab، +Matrix زنده، و Telegram زنده را fan out می‌کند. یک اجرای کامل فقط زمانی قابل قبول است که +خلاصه‌ی `Full Release Validation` +`normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all، فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all، مگر اینکه -`npm_telegram_package_spec` منتشرشده ارائه شده باشد، skip می‌شود. خلاصه نهایی -verifier شامل جدول‌های کندترین job برای هر اجرای فرزند است، تا release manager -بتواند مسیر بحرانی فعلی را بدون دانلود logها ببیند. -برای ماتریس کامل stage، نام دقیق jobهای workflow، تفاوت‌های profile پایدار در برابر کامل، +یک `npm_telegram_package_spec` منتشرشده ارائه شده باشد، skip می‌شود. خلاصه‌ی نهایی +verifier شامل جدول‌های کندترین job برای هر اجرای فرزند است، تا مدیر انتشار بتواند +مسیر بحرانی فعلی را بدون دانلود logها ببیند. +برای matrix کامل مرحله‌ها، نام دقیق jobهای workflow، تفاوت‌های پروفایل stable در برابر full، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید. -گردش‌کارهای فرزند از ref مورد اعتمادی dispatch می‌شوند که `Full Release -Validation` را اجرا می‌کند، معمولا `--ref main`، حتی وقتی ref هدف به branch یا tag -انتشار قدیمی‌تری اشاره کند. ورودی جداگانه‌ای برای workflow-ref مربوط به Full Release Validation +workflowهای فرزند از ref مورد اعتماد که `Full Release +Validation` را اجرا می‌کند dispatch می‌شوند، معمولاً `--ref main`، حتی وقتی target `ref` به یک +شاخه یا tag انتشار قدیمی‌تر اشاره کند. ورودی جداگانه‌ای برای workflow-ref در Full Release Validation وجود ندارد؛ harness مورد اعتماد را با انتخاب ref اجرای workflow انتخاب کنید. -برای proof دقیق commit روی `main` متحرک از `--ref main -f ref=` استفاده نکنید؛ -SHAهای خام commit نمی‌توانند workflow dispatch ref باشند، بنابراین از -`pnpm ci:full-release --sha ` برای ایجاد branch موقت pinned استفاده کنید. +برای اثبات commit دقیق روی `main` متحرک از `--ref main -f ref=` استفاده نکنید؛ +SHAهای خام commit نمی‌توانند refهای workflow dispatch باشند، پس از +`pnpm ci:full-release --sha ` برای ساخت شاخه‌ی موقت pinned استفاده کنید. -برای انتخاب گستره live/provider از `release_profile` استفاده کنید: +برای انتخاب گستره‌ی live/provider از `release_profile` استفاده کنید: -- `minimum`: سریع‌ترین مسیر live و Docker حیاتی برای انتشار، مربوط به OpenAI/core -- `stable`: minimum به‌علاوه پوشش provider/backend پایدار برای تأیید انتشار -- `full`: stable به‌علاوه پوشش گسترده advisory provider/media +- `minimum`: سریع‌ترین مسیر live و Docker حیاتی برای انتشار OpenAI/core +- `stable`: minimum به‌علاوه‌ی پوشش provider/backend پایدار برای تأیید انتشار +- `full`: stable به‌علاوه‌ی پوشش گسترده‌ی advisory provider/media -`OpenClaw Release Checks` از workflow ref مورد اعتماد استفاده می‌کند تا ref هدف را -یک‌بار به‌صورت `release-package-under-test` resolve کند و از همان artifact هم در -بررسی‌های Docker مسیر انتشار و هم در Package Acceptance دوباره استفاده می‌کند. این کار همه boxهای ناظر به package را روی همان byteها نگه می‌دارد و از buildهای تکراری package جلوگیری می‌کند. -install smoke میان‌سیستم‌عاملی OpenAI وقتی متغیر repo/org تنظیم شده باشد از -`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، زیرا این lane -در حال اثبات نصب package، onboarding، راه‌اندازی Gateway، و یک نوبت agent زنده است -نه benchmark کردن کندترین model پیش‌فرض. ماتریس گسترده‌تر provider زنده همچنان محل پوشش model-specific است. +`OpenClaw Release Checks` از ref مورد اعتماد workflow استفاده می‌کند تا ref هدف را +یک‌بار به‌عنوان `release-package-under-test` resolve کند و همان artifact را هم در +بررسی‌های Docker مسیر انتشار و هم در Package Acceptance دوباره به کار ببرد. این کار همه‌ی +boxهای مرتبط با بسته را روی byteهای یکسان نگه می‌دارد و از ساخت‌های تکراری بسته جلوگیری می‌کند. +install smoke مربوط به cross-OS OpenAI وقتی متغیر repo/org تنظیم شده باشد از +`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده می‌کند، وگرنه از `openai/gpt-5.4`، چون این lane در حال +اثبات نصب بسته، onboarding، راه‌اندازی Gateway، و یک نوبت agent زنده است +نه benchmark کردن کندترین مدل پیش‌فرض. matrix گسترده‌تر provider زنده همچنان محل +پوشش اختصاصی مدل‌ها باقی می‌ماند. -بسته به stage انتشار از این variantها استفاده کنید: +بسته به مرحله‌ی انتشار از این variantها استفاده کنید: ```bash # Validate an unpublished release candidate branch. @@ -264,39 +249,41 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -از umbrella کامل به‌عنوان نخستین rerun پس از یک اصلاح متمرکز استفاده نکنید. اگر یک box -fail شد، برای proof بعدی از workflow فرزند fail‌شده، job، lane Docker، profile package، provider model، یا lane QA استفاده کنید. umbrella کامل را فقط وقتی دوباره اجرا کنید که -اصلاح، orchestration مشترک انتشار را تغییر داده باشد یا شواهد all-box قبلی را stale کرده باشد. -verifier نهایی umbrella شناسه‌های ضبط‌شده اجرای workflow فرزند را دوباره بررسی می‌کند، بنابراین پس از rerun موفق یک workflow فرزند، فقط job والد fail‌شده +پس از یک fix متمرکز، از umbrella کامل به‌عنوان اولین rerun استفاده نکنید. اگر یک box +fail شود، برای اثبات بعدی از workflow فرزند fail‌شده، job، Docker lane، پروفایل بسته، provider مدل، +یا QA lane استفاده کنید. umbrella کامل را فقط وقتی دوباره اجرا کنید که +fix، orchestration مشترک انتشار را تغییر داده باشد یا شواهد قبلی همه‌ی boxها را +کهنه کرده باشد. verifier نهایی umbrella دوباره idهای ثبت‌شده‌ی اجرای workflow فرزند +را بررسی می‌کند، پس بعد از اینکه یک workflow فرزند با موفقیت rerun شد، فقط job والد fail‌شده‌ی `Verify full validation` را rerun کنید. -برای بازیابی محدود، `rerun_group` را به umbrella پاس بدهید. `all` اجرای واقعی -release-candidate است، `ci` فقط فرزند CI عادی را اجرا می‌کند، `plugin-prerelease` -فقط فرزند Plugin مخصوص انتشار را اجرا می‌کند، `release-checks` همه boxهای انتشار را اجرا می‌کند، -و گروه‌های انتشار باریک‌تر عبارت‌اند از `install-smoke`، `cross-os`، +برای بازیابی bounded، `rerun_group` را به umbrella پاس دهید. `all` اجرای واقعی +release-candidate است، `ci` فقط فرزند CI معمولی را اجرا می‌کند، `plugin-prerelease` +فقط فرزند مخصوص انتشار Plugin را اجرا می‌کند، `release-checks` همه‌ی boxهای انتشار +را اجرا می‌کند، و گروه‌های محدودتر انتشار عبارت‌اند از `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، و `npm-telegram`. rerunهای متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارند؛ اجراهای full/all -با `release_profile=full` از artifact package مربوط به release-checks استفاده می‌کنند. +با `release_profile=full` از artifact بسته‌ی release-checks استفاده می‌کنند. ### Vitest -box مربوط به Vitest همان workflow فرزند `CI` دستی است. CI دستی عمدا -scoping مبتنی بر changed را دور می‌زند و graph تست عادی را برای release candidate اجباری می‌کند: -shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22، +box مربوط به Vitest همان workflow فرزند `CI` دستی است. CI دستی عمداً +scoping تغییرات را دور می‌زند و graph معمول test را برای release candidate اجبار می‌کند: +shardهای Linux Node، shardهای Pluginهای bundled، contractهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسی‌های docs، Skills پایتون، Windows، -macOS، Android، و i18n مربوط به Control UI. +macOS، Android، و Control UI i18n. -از این box برای پاسخ به این پرسش استفاده کنید: «آیا source tree کل test suite عادی را پاس کرده است؟» -این همان اعتبارسنجی product در مسیر انتشار نیست. شواهدی که باید نگه دارید: +از این box برای پاسخ به این پرسش استفاده کنید: «آیا source tree کل test suite معمول را پاس کرده است؟» +این با اعتبارسنجی محصول در مسیر انتشار یکسان نیست. شواهدی که باید نگه دارید: -- خلاصه `Full Release Validation` که URL اجرای dispatch‌شده `CI` را نشان می‌دهد -- اجرای سبز `CI` روی SHA دقیق هدف +- خلاصه‌ی `Full Release Validation` که URL اجرای `CI` dispatch‌شده را نشان می‌دهد +- اجرای `CI` سبز روی SHA دقیق هدف - نام shardهای fail‌شده یا کند از jobهای CI هنگام بررسی regressionها -- artifactهای timing مربوط به Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی - یک اجرا به تحلیل performance نیاز دارد +- artifactهای timing Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی + یک اجرا به تحلیل کارایی نیاز دارد -CI دستی را فقط وقتی مستقیم اجرا کنید که انتشار به CI عادی deterministic نیاز دارد اما -به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز ندارد: +CI دستی را مستقیماً فقط وقتی اجرا کنید که انتشار به CI معمول deterministic نیاز داشته باشد اما +به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز نداشته باشد: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -304,16 +291,16 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -box مربوط به Docker در `OpenClaw Release Checks` از طریق -`openclaw-live-and-e2e-checks-reusable.yml`، به‌علاوه workflow -`install-smoke` در حالت release قرار دارد. این box release candidate را از طریق محیط‌های packaged -Docker اعتبارسنجی می‌کند، نه فقط تست‌های سطح source. +box مربوط به Docker درون `OpenClaw Release Checks` از طریق +`openclaw-live-and-e2e-checks-reusable.yml`، به‌علاوه‌ی workflow +`install-smoke` در حالت release قرار دارد. این box، release candidate را از طریق محیط‌های +Docker بسته‌بندی‌شده اعتبارسنجی می‌کند، نه فقط testهای سطح source. پوشش Docker انتشار شامل موارد زیر است: - install smoke کامل با فعال بودن smoke نصب global کند Bun -- آماده‌سازی/استفاده مجدد از image smoke برای Dockerfile ریشه بر اساس SHA هدف، با jobهای smoke مربوط به QR، - root/gateway، و installer/Bun که به‌صورت shardهای install-smoke جداگانه اجرا می‌شوند +- آماده‌سازی/استفاده‌ی دوباره از image smoke ریشه‌ی Dockerfile براساس SHA هدف، با jobهای QR، + root/gateway، و installer/Bun smoke که به‌عنوان shardهای جداگانه‌ی install-smoke اجرا می‌شوند - laneهای E2E repository - chunkهای Docker مسیر انتشار: `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، @@ -322,75 +309,88 @@ Docker اعتبارسنجی می‌کند، نه فقط تست‌های سطح s `plugins-runtime-install-c`، `plugins-runtime-install-d`، `plugins-runtime-install-e`، `plugins-runtime-install-f`، `plugins-runtime-install-g`، و `plugins-runtime-install-h` -- پوشش OpenWebUI داخل chunk `plugins-runtime-services` در صورت درخواست -- laneهای split نصب/حذف نصب bundled Plugin +- پوشش OpenWebUI داخل chunk `plugins-runtime-services` وقتی درخواست شده باشد +- laneهای جداشده‌ی نصب/حذف Plugin bundled `bundled-plugin-install-uninstall-0` تا `bundled-plugin-install-uninstall-23` -- suiteهای provider live/E2E و پوشش model زنده Docker وقتی release checks - شامل suiteهای live باشد +- suiteهای provider زنده/E2E و پوشش مدل زنده‌ی Docker وقتی release checks + شامل suiteهای live باشند -پیش از rerun از artifactهای Docker استفاده کنید. scheduler مسیر انتشار، +پیش از rerun از artifactهای Docker استفاده کنید. scheduler مسیر انتشار `.artifacts/docker-tests/` را با logهای lane، `summary.json`، `failures.json`, timingهای phase، JSON طرح scheduler، و دستورهای rerun upload می‌کند. برای بازیابی متمرکز، -به‌جای rerun کردن همه chunkهای انتشار، از `docker_lanes=` روی workflow قابل استفاده مجدد live/E2E استفاده کنید. دستورهای rerun تولیدشده در صورت موجود بودن شامل -`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده Docker هستند، تا یک +به‌جای rerun کردن همه‌ی chunkهای انتشار، روی workflow live/E2E قابل استفاده‌مجدد از +`docker_lanes=` استفاده کنید. دستورهای rerun تولیدشده وقتی موجود باشند شامل +`package_artifact_run_id` قبلی و ورودی‌های image آماده‌شده‌ی Docker هستند، تا یک lane fail‌شده بتواند از همان tarball و imageهای GHCR دوباره استفاده کند. ### QA Lab -box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate رفتار agentic -و سطح channel برای انتشار است، جدا از Vitest و مکانیک package در Docker. +box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate انتشار مربوط به +رفتار agentic و سطح channel است، جدا از Vitest و سازوکارهای package Docker. پوشش QA Lab انتشار شامل موارد زیر است: -- lane هم‌ارزی mock که lane کاندیدای OpenAI را با baseline مربوط به Opus 4.6 - با استفاده از pack هم‌ارزی agentic مقایسه می‌کند -- profile سریع QA برای Matrix زنده با استفاده از محیط `qa-live-shared` -- lane QA برای Telegram زنده با استفاده از leaseهای credential مربوط به Convex CI -- `pnpm qa:otel:smoke` وقتی telemetry انتشار به proof محلی صریح نیاز دارد +- lane برابری mock که lane candidate OpenAI را با baseline Opus 4.6 + با استفاده از agentic parity pack مقایسه می‌کند +- پروفایل سریع QA زنده‌ی Matrix با استفاده از محیط `qa-live-shared` +- lane QA زنده‌ی Telegram با استفاده از leaseهای credential مربوط به Convex CI +- `pnpm qa:otel:smoke` وقتی telemetry انتشار به اثبات محلی صریح نیاز داشته باشد از این box برای پاسخ به این پرسش استفاده کنید: «آیا انتشار در سناریوهای QA و -flowهای channel زنده درست رفتار می‌کند؟» هنگام تأیید انتشار، URLهای artifact مربوط به laneهای parity، Matrix، و Telegram را نگه دارید. پوشش کامل Matrix همچنان به‌صورت اجرای دستی sharded QA-Lab در دسترس است، نه lane پیش‌فرض حیاتی برای انتشار. +flowهای channel زنده درست رفتار می‌کند؟» هنگام تأیید انتشار، URLهای artifact برای laneهای برابری، +Matrix، و Telegram را نگه دارید. پوشش کامل Matrix همچنان به‌عنوان اجرای دستی sharded QA-Lab +در دسترس است، نه lane حیاتی پیش‌فرض برای انتشار. ### Package -box مربوط به Package، gate محصول قابل نصب است. پشتوانه آن +box مربوط به Package همان gate محصول قابل‌نصب است. این box با `Package Acceptance` و resolver -`scripts/resolve-openclaw-package-candidate.mjs` است. resolver یک candidate را به tarball -`package-under-test` که توسط Docker E2E مصرف می‌شود normalize می‌کند، inventory package را اعتبارسنجی می‌کند، -نسخه package و SHA-256 را ثبت می‌کند، و ref مربوط به workflow harness را از ref منبع package جدا نگه می‌دارد. +`scripts/resolve-openclaw-package-candidate.mjs` پشتیبانی می‌شود. resolver یک +candidate را به tarball `package-under-test` مصرف‌شده توسط Docker E2E normalize می‌کند، +inventory بسته را اعتبارسنجی می‌کند، نسخه‌ی بسته و SHA-256 را ثبت می‌کند، و ref +harness workflow را از ref source بسته جدا نگه می‌دارد. -منابع candidate پشتیبانی‌شده: +sourceهای candidate پشتیبانی‌شده: -- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار OpenClaw -- `source=ref`: pack کردن branch، tag، یا SHA کامل commit مربوط به `package_ref` مورد اعتماد - با harness انتخاب‌شده `workflow_ref` -- `source=url`: دانلود یک `.tgz` مبتنی بر HTTPS با `package_sha256` الزامی -- `source=artifact`: استفاده مجدد از یک `.tgz` که توسط اجرای دیگری از GitHub Actions upload شده است +- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخه‌ی دقیق انتشار OpenClaw +- `source=ref`: بسته‌بندی یک شاخه، tag، یا SHA کامل commit مربوط به `package_ref` مورد اعتماد + با harness انتخاب‌شده‌ی `workflow_ref` +- `source=url`: دانلود یک `.tgz` از HTTPS با `package_sha256` الزامی +- `source=artifact`: استفاده‌ی دوباره از یک `.tgz` uploadشده توسط اجرای دیگری از GitHub Actions -`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`، -artifact آماده‌شده package انتشار، `suite_profile=custom`, -`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, -`published_upgrade_survivor_baselines=all-since-2026.4.23`, +`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`، artifact +بسته‌ی آماده‌شده‌ی انتشار، `suite_profile=custom`، +`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`، +`published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues`، و -`telegram_mode=mock-openai` اجرا می‌کند. Package Acceptance مهاجرت، update، پاک‌سازی dependencyهای stale Plugin، fixtureهای offline Plugin، update Plugin، و QA برای package Telegram را در برابر همان tarball resolve‌شده نگه می‌دارد. ماتریس upgrade هر baseline پایدار منتشرشده در npm از `2026.4.23` تا `latest` را پوشش می‌دهد؛ برای candidateای که قبلا shipped شده است از Package Acceptance با `source=npm` استفاده کنید، یا -برای tarball محلی npm با پشتوانه SHA پیش از publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین GitHub-native -برای بیشتر پوشش package/update است که قبلا به Parallels نیاز داشت. -بررسی‌های انتشار cross-OS همچنان برای رفتارهای onboarding، installer، و platform خاص OS مهم هستند، اما اعتبارسنجی product مربوط به package/update باید Package Acceptance را ترجیح دهد. +`telegram_mode=mock-openai` اجرا می‌کند. Package Acceptance، migration، update، پاک‌سازی +وابستگی stale Plugin، fixtureهای Plugin offline، update Plugin، و QA بسته Telegram +را در برابر همان tarball resolve‌شده نگه می‌دارد. matrix upgrade هر baseline پایدار منتشرشده در npm را از `2026.4.23` تا `latest` پوشش می‌دهد؛ برای یک candidate که قبلاً منتشر شده است از +Package Acceptance با `source=npm` استفاده کنید، یا برای یک tarball محلی npm مبتنی بر SHA پیش از +publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین native در GitHub +برای بیشتر پوشش package/update است که قبلاً به Parallels نیاز داشت. +بررسی‌های انتشار cross-OS همچنان برای onboarding، installer، و رفتار platform خاص OS مهم‌اند، +اما اعتبارسنجی محصول package/update باید Package Acceptance را ترجیح دهد. -چک‌لیست canonical برای اعتبارسنجی update و Plugin، [تست updateها و Pluginها](/fa/help/testing-updates-plugins) است. هنگام تصمیم‌گیری درباره اینکه کدام lane محلی، Docker، Package Acceptance، یا release-check یک تغییر نصب/update Plugin، پاک‌سازی doctor، یا مهاجرت package منتشرشده را اثبات می‌کند، از آن استفاده کنید. -مهاجرت exhaustive published update از هر package پایدار `2026.4.23+` یک workflow دستی جداگانه `Update Migration` است، نه بخشی از Full Release CI. +checklist canonical برای اعتبارسنجی update و Plugin این است: +[آزمایش updateها و Pluginها](/fa/help/testing-updates-plugins). هنگام تصمیم‌گیری درباره‌ی اینکه +کدام lane محلی، Docker، Package Acceptance، یا release-check یک تغییر نصب/update Plugin، +پاک‌سازی doctor، یا migration بسته‌ی منتشرشده را اثبات می‌کند، از آن استفاده کنید. +migration کامل update منتشرشده از هر بسته‌ی پایدار `2026.4.23+` +یک workflow دستی جداگانه‌ی `Update Migration` است، نه بخشی از Full Release CI. -leniency قدیمی package-acceptance عمدا زمان‌بندی محدود دارد. packageها تا -`2026.4.25` می‌توانند برای gapهای metadata که قبلا در npm منتشر شده‌اند از مسیر سازگاری استفاده کنند: -entryهای خصوصی inventory مربوط به QA که در tarball نیستند، نبود -`gateway install --wrapper`، نبود patch fileها در fixture git مشتق‌شده از tarball، -نبود `update.channel` persisted، محل‌های legacy برای install-record مربوط به Plugin، -نبود persistence برای marketplace install-record، و مهاجرت metadata پیکربندی طی `plugins update`. package منتشرشده `2026.4.26` ممکن است -برای فایل‌های stamp مربوط به metadata build محلی که قبلا shipped شده‌اند warning بدهد. packageهای بعدی -باید قراردادهای package مدرن را برآورده کنند؛ همان gapها در اعتبارسنجی انتشار fail می‌شوند. +leniency قدیمی package-acceptance عمداً time boxed است. بسته‌ها تا +`2026.4.25` می‌توانند برای gapهای metadata که قبلاً در npm منتشر شده‌اند +از مسیر compatibility استفاده کنند: entryهای private QA inventory که در tarball وجود ندارند، +نبود `gateway install --wrapper`، نبود patch fileها در fixture git مشتق‌شده از tarball، +نبود `update.channel` persisted، محل‌های قدیمی install-record مربوط به Plugin، +نبود persistence برای install-record marketplace، و migration metadata config +در طول `plugins update`. بسته‌ی منتشرشده‌ی `2026.4.26` ممکن است برای فایل‌های stamp +metadata ساخت محلی که قبلاً ship شده‌اند warning بدهد. بسته‌های بعدی باید +contractهای مدرن package را برآورده کنند؛ همان gapها باعث fail شدن اعتبارسنجی انتشار می‌شوند. -وقتی پرسش انتشار درباره یک package واقعا قابل نصب است، از profileهای گسترده‌تر Package Acceptance استفاده کنید: +وقتی پرسش انتشار درباره‌ی یک بسته‌ی واقعاً قابل‌نصب است، از پروفایل‌های گسترده‌تر Package Acceptance استفاده کنید: ```bash gh workflow run package-acceptance.yml \ @@ -402,34 +402,33 @@ gh workflow run package-acceptance.yml \ -f published_upgrade_survivor_baseline=openclaw@2026.4.26 ``` -profileهای رایج package: +پروفایل‌های رایج package: -- `smoke`: مسیرهای سریع نصب بسته/کانال/agent، شبکهٔ Gateway، و بارگذاری دوبارهٔ پیکربندی -- `package`: قراردادهای نصب/به‌روزرسانی/بستهٔ Plugin بدون ClawHub زنده؛ این پیش‌فرض بررسی انتشار است -- `product`: `package` به‌همراه کانال‌های MCP، پاک‌سازی cron/subagent، جست‌وجوی وب OpenAI، و OpenWebUI +- `smoke`: مسیرهای سریع نصب package/channel/agent، شبکه Gateway، و بارگذاری دوباره config +- `package`: قراردادهای نصب/به‌روزرسانی/Plugin package بدون ClawHub زنده؛ این پیش‌فرض release-check است +- `product`: `package` به‌همراه channelهای MCP، پاک‌سازی Cron/زیرعامل، جست‌وجوی وب OpenAI، و OpenWebUI - `full`: بخش‌های مسیر انتشار Docker با OpenWebUI -- `custom`: فهرست دقیق `docker_lanes` برای اجرای دوبارهٔ متمرکز +- `custom`: فهرست دقیق `docker_lanes` برای اجرای دوباره متمرکز -برای اثبات Telegram نامزد بسته، `telegram_mode=mock-openai` یا -`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. این گردش‌کار فایل tarball حل‌شدهٔ -`package-under-test` را به مسیر Telegram می‌دهد؛ گردش‌کار مستقل -Telegram همچنان برای بررسی‌های پس از انتشار، یک مشخصات npm منتشرشده را می‌پذیرد. +برای اثبات Telegram نامزد package، `telegram_mode=mock-openai` یا +`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. workflow، فایل tarball حل‌شده +`package-under-test` را به مسیر Telegram می‌دهد؛ workflow مستقل +Telegram همچنان یک مشخصه منتشرشده npm را برای بررسی‌های پس از انتشار می‌پذیرد. -## خودکارسازی انتشار نسخه +## خودکارسازی انتشار release -`OpenClaw Release Publish` نقطهٔ ورود عادی انتشار تغییردهنده است. این گردش‌کار، -گردش‌کارهای ناشر معتمد را به ترتیبی که انتشار نیاز دارد هماهنگ می‌کند: +`OpenClaw Release Publish` نقطه ورود معمول انتشار تغییردهنده است. این workflowهای trusted-publisher را به ترتیبی که release نیاز دارد هماهنگ می‌کند: -1. tag انتشار را check out کنید و SHA کامیت آن را حل کنید. -2. تأیید کنید که tag از `main` یا `release/*` قابل دسترسی است. -3. `pnpm plugins:sync:check` را اجرا کنید. +1. تگ release را check out می‌کند و commit SHA آن را حل می‌کند. +2. بررسی می‌کند که تگ از `main` یا `release/*` قابل دسترسی باشد. +3. `pnpm plugins:sync:check` را اجرا می‌کند. 4. `Plugin NPM Release` را با `publish_scope=all-publishable` و - `ref=` dispatch کنید. -5. `Plugin ClawHub Release` را با همان دامنه و SHA dispatch کنید. -6. `OpenClaw NPM Release` را با tag انتشار، dist-tag در npm، و - `preflight_run_id` ذخیره‌شده dispatch کنید. + `ref=` dispatch می‌کند. +5. `Plugin ClawHub Release` را با همان scope و SHA dispatch می‌کند. +6. `OpenClaw NPM Release` را با تگ release، dist-tag مربوط به npm، و + `preflight_run_id` ذخیره‌شده dispatch می‌کند. -نمونهٔ انتشار Beta: +نمونه انتشار beta: ```bash gh workflow run openclaw-release-publish.yml \ @@ -439,7 +438,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -انتشار Stable به dist-tag پیش‌فرض beta: +انتشار پایدار به dist-tag پیش‌فرض beta: ```bash gh workflow run openclaw-release-publish.yml \ @@ -449,7 +448,7 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -ارتقای Stable مستقیماً به `latest` صریح است: +ارتقای پایدار مستقیما به `latest` صریح است: ```bash gh workflow run openclaw-release-publish.yml \ @@ -459,76 +458,68 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=latest ``` -از گردش‌کارهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release` -فقط برای کارهای تعمیر یا انتشار دوبارهٔ متمرکز استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده، +از workflowهای سطح پایین‌تر `Plugin NPM Release` و `Plugin ClawHub Release` فقط برای کار تعمیر یا بازنشر متمرکز استفاده کنید. برای تعمیر یک Plugin انتخاب‌شده، `plugin_publish_scope=selected` و `plugins=@openclaw/name` را به -`OpenClaw Release Publish` بدهید، یا هنگامی که بستهٔ -OpenClaw نباید منتشر شود، گردش‌کار فرزند را مستقیماً dispatch کنید. +`OpenClaw Release Publish` بدهید، یا وقتی package مربوط به OpenClaw نباید منتشر شود، workflow فرزند را مستقیما dispatch کنید. -## ورودی‌های گردش‌کار NPM +## ورودی‌های workflow مربوط به NPM -`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: +`OpenClaw NPM Release` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: -- `tag`: tag انتشار الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا - `v2026.4.2-beta.1`؛ هنگامی که `preflight_only=true` است، می‌تواند SHA کامل ۴۰نویسه‌ای کامیت شاخهٔ گردش‌کار فعلی برای preflight فقط اعتبارسنجی نیز باشد -- `preflight_only`: `true` برای فقط اعتبارسنجی/ساخت/بسته، `false` برای مسیر انتشار واقعی -- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا گردش‌کار از tarball آماده‌شدهٔ اجرای موفق preflight دوباره استفاده کند -- `npm_dist_tag`: tag هدف npm برای مسیر انتشار؛ مقدار پیش‌فرض `beta` است +- `tag`: تگ release الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا + `v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، برای preflight فقط اعتبارسنجی می‌تواند SHA کامل ۴۰ کاراکتری commit فعلی شاخه workflow هم باشد +- `preflight_only`: مقدار `true` فقط برای اعتبارسنجی/ساخت/package، و `false` برای مسیر انتشار واقعی +- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا workflow از tarball آماده‌شده اجرای preflight موفق دوباره استفاده کند +- `npm_dist_tag`: تگ هدف npm برای مسیر انتشار؛ پیش‌فرض آن `beta` است -`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: +`OpenClaw Release Publish` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: -- `tag`: tag انتشار الزامی؛ باید از قبل وجود داشته باشد -- `preflight_run_id`: شناسهٔ اجرای موفق preflight از `OpenClaw NPM Release`؛ - هنگامی که `publish_openclaw_npm=true` است الزامی است -- `npm_dist_tag`: tag هدف npm برای بستهٔ OpenClaw -- `plugin_publish_scope`: مقدار پیش‌فرض `all-publishable` است؛ فقط - برای کار تعمیر متمرکز از `selected` استفاده کنید -- `plugins`: نام‌های بستهٔ `@openclaw/*` جداشده با کاما هنگامی که - `plugin_publish_scope=selected` است -- `publish_openclaw_npm`: مقدار پیش‌فرض `true` است؛ فقط هنگامی آن را `false` تنظیم کنید که از گردش‌کار به‌عنوان هماهنگ‌کنندهٔ تعمیر فقط Plugin استفاده می‌کنید +- `tag`: تگ release الزامی؛ باید از قبل وجود داشته باشد +- `preflight_run_id`: شناسه اجرای preflight موفق `OpenClaw NPM Release`؛ + وقتی `publish_openclaw_npm=true` باشد الزامی است +- `npm_dist_tag`: تگ هدف npm برای package مربوط به OpenClaw +- `plugin_publish_scope`: پیش‌فرض آن `all-publishable` است؛ فقط برای کار تعمیر متمرکز از `selected` استفاده کنید +- `plugins`: نام‌های package با جداکننده ویرگول از نوع `@openclaw/*` وقتی + `plugin_publish_scope=selected` باشد +- `publish_openclaw_npm`: پیش‌فرض آن `true` است؛ فقط وقتی workflow را به‌عنوان هماهنگ‌کننده تعمیر صرفا Plugin استفاده می‌کنید، آن را `false` تنظیم کنید -`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط اپراتور را می‌پذیرد: +`OpenClaw Release Checks` این ورودی‌های کنترل‌شده توسط operator را می‌پذیرد: -- `ref`: شاخه، tag، یا SHA کامل کامیت برای اعتبارسنجی. بررسی‌های دارای secret نیاز دارند کامیت حل‌شده از یک شاخهٔ OpenClaw یا tag انتشار قابل دسترسی باشد. +- `ref`: شاخه، تگ، یا SHA کامل commit برای اعتبارسنجی. بررسی‌های دارای secret نیاز دارند commit حل‌شده از یک شاخه OpenClaw یا تگ release قابل دسترسی باشد. قواعد: -- tagهای Stable و اصلاحی می‌توانند به `beta` یا `latest` منتشر شوند -- tagهای پیش‌انتشار Beta فقط می‌توانند به `beta` منتشر شوند -- برای `OpenClaw NPM Release`، ورودی SHA کامل کامیت فقط هنگامی مجاز است که +- تگ‌های پایدار و اصلاحی می‌توانند در `beta` یا `latest` منتشر شوند +- تگ‌های پیش‌انتشار beta فقط می‌توانند در `beta` منتشر شوند +- برای `OpenClaw NPM Release`، ورودی SHA کامل commit فقط وقتی مجاز است که `preflight_only=true` باشد - `OpenClaw Release Checks` و `Full Release Validation` همیشه فقط اعتبارسنجی هستند -- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که هنگام preflight استفاده شده است؛ - گردش‌کار پیش از ادامهٔ انتشار آن metadata را تأیید می‌کند +- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که در preflight استفاده شده است؛ workflow پیش از ادامه انتشار، آن metadata را بررسی می‌کند -## توالی انتشار Stable در npm +## توالی release پایدار npm -هنگام ساخت یک انتشار Stable در npm: +هنگام ایجاد یک release پایدار npm: 1. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید - - پیش از وجود tag، می‌توانید از SHA کامل کامیت شاخهٔ گردش‌کار فعلی برای اجرای آزمایشی فقط اعتبارسنجی گردش‌کار preflight استفاده کنید -2. برای جریان عادی beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط هنگامی `latest` را انتخاب کنید که عمداً انتشار مستقیم Stable می‌خواهید -3. هنگامی که پوشش عادی CI به‌همراه prompt cache زنده، Docker، QA Lab، - Matrix، و Telegram را از یک گردش‌کار دستی می‌خواهید، `Full Release Validation` را روی شاخهٔ انتشار، tag انتشار، یا SHA کامل کامیت اجرا کنید -4. اگر عمداً فقط به گراف آزمون عادی قطعی نیاز دارید، به‌جای آن گردش‌کار دستی `CI` را روی ref انتشار اجرا کنید + - پیش از وجود تگ، می‌توانید از SHA کامل commit فعلی شاخه workflow برای اجرای آزمایشی فقط اعتبارسنجی workflow مربوط به preflight استفاده کنید +2. برای جریان عادی beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی عمدا انتشار پایدار مستقیم می‌خواهید `latest` را انتخاب کنید +3. وقتی می‌خواهید CI عادی به‌همراه پوشش live prompt cache، Docker، QA Lab، + Matrix، و Telegram را از یک workflow دستی داشته باشید، `Full Release Validation` را روی شاخه release، تگ release، یا SHA کامل commit اجرا کنید +4. اگر عمدا فقط به گراف تست عادی قطعی نیاز دارید، به‌جای آن workflow دستی `CI` را روی ref مربوط به release اجرا کنید 5. `preflight_run_id` موفق را ذخیره کنید 6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`، - و `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را پیش از ارتقای بستهٔ npm مربوط به OpenClaw در npm و ClawHub منتشر می‌کند -7. اگر انتشار روی `beta` قرار گرفت، از گردش‌کار خصوصی + و `preflight_run_id` ذخیره‌شده اجرا کنید؛ این کار Pluginهای externalized را پیش از ارتقای package npm مربوط به OpenClaw در npm و ClawHub منتشر می‌کند +7. اگر release روی `beta` فرود آمد، از workflow خصوصی `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - برای ارتقای آن نسخهٔ Stable از `beta` به `latest` استفاده کنید -8. اگر انتشار عمداً مستقیماً روی `latest` منتشر شد و `beta` - باید فوراً همان ساخت Stable را دنبال کند، از همان گردش‌کار خصوصی استفاده کنید تا هر دو dist-tag را به نسخهٔ Stable اشاره دهید، یا اجازه دهید همگام‌سازی خودترمیمی زمان‌بندی‌شدهٔ آن بعداً `beta` را جابه‌جا کند + برای ارتقای آن نسخه پایدار از `beta` به `latest` استفاده کنید +8. اگر release عمدا مستقیما روی `latest` منتشر شد و `beta` باید بلافاصله همان build پایدار را دنبال کند، از همان workflow خصوصی استفاده کنید تا هر دو dist-tag را به نسخه پایدار اشاره دهد، یا اجازه دهید همگام‌سازی خودترمیم زمان‌بندی‌شده آن بعدا `beta` را جابه‌جا کند -جهش dist-tag به‌دلایل امنیتی در مخزن خصوصی قرار دارد، چون همچنان به -`NPM_TOKEN` نیاز دارد، در حالی که مخزن عمومی انتشار فقط OIDC را نگه می‌دارد. +تغییر dist-tag به دلایل امنیتی در repo خصوصی قرار دارد، چون همچنان به +`NPM_TOKEN` نیاز دارد، در حالی که repo عمومی انتشار فقط با OIDC را حفظ می‌کند. -این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای beta-first را مستند و برای اپراتور قابل مشاهده نگه می‌دارد. +این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای beta-first را مستند و برای operator قابل مشاهده نگه می‌دارد. -اگر یک maintainer ناچار است به احراز هویت محلی npm برگردد، هر فرمان 1Password -CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کند. `op` را -مستقیماً از پوستهٔ اصلی agent فراخوانی نکنید؛ نگه‌داشتن آن داخل tmux باعث می‌شود promptها، -هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان جلوگیری شود. +اگر یک maintainer ناچار شود به احراز هویت محلی npm برگردد، هر دستور CLI مربوط به 1Password (`op`) را فقط داخل یک نشست tmux اختصاصی اجرا کنید. `op` را مستقیما از shell اصلی agent فراخوانی نکنید؛ نگه داشتن آن داخل tmux باعث می‌شود promptها، هشدارها، و مدیریت OTP قابل مشاهده باشند و از هشدارهای تکراری میزبان جلوگیری می‌کند. ## ارجاع‌های عمومی @@ -542,10 +533,10 @@ CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کن - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -maintainerها برای runbook واقعی از مستندات انتشار خصوصی در +maintainerها برای runbook واقعی از مستندات خصوصی release در [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) استفاده می‌کنند. ## مرتبط -- [کانال‌های انتشار](/fa/install/development-channels) +- [کانال‌های release](/fa/install/development-channels) diff --git a/docs/fa/security/network-proxy.md b/docs/fa/security/network-proxy.md index 8c59e74e0..c63111248 100644 --- a/docs/fa/security/network-proxy.md +++ b/docs/fa/security/network-proxy.md @@ -1,40 +1,40 @@ --- read_when: - - می‌خواهید در برابر حملات SSRF و بازاتصال DNS دفاع در عمق داشته باشید - - پیکربندی یک پروکسی فوروارد خارجی برای ترافیک زمان اجرای OpenClaw -summary: نحوهٔ مسیریابی ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق یک پروکسی فیلترکنندهٔ مدیریت‌شده توسط اپراتور + - شما به دفاع در عمق در برابر حملات SSRF و بازپیوند DNS نیاز دارید + - پیکربندی یک پروکسی رو به جلو خارجی برای ترافیک زمان اجرای OpenClaw +summary: نحوهٔ هدایت ترافیک HTTP و WebSocket زمان اجرای OpenClaw از طریق یک پروکسی فیلترکنندهٔ تحت مدیریت اپراتور title: پروکسی شبکه x-i18n: - generated_at: "2026-05-04T02:27:21Z" + generated_at: "2026-05-04T07:07:45Z" model: gpt-5.5 provider: openai - source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9 + source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0 source_path: security/network-proxy.md workflow: 16 --- -# پراکسی شبکه +# پروکسی شبکه -OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پراکسی رو‌به‌جلو که توسط اپراتور مدیریت می‌شود مسیریابی کند. این یک دفاع در عمق اختیاری برای استقرارهایی است که کنترل مرکزی خروجی شبکه، محافظت قوی‌تر در برابر SSRF، و قابلیت ممیزی بهتر شبکه می‌خواهند. +OpenClaw می‌تواند ترافیک HTTP و WebSocket زمان اجرا را از طریق یک پروکسی ارسالِ مدیریت‌شده توسط اپراتور مسیریابی کند. این یک دفاع اختیاریِ چندلایه برای استقرارهایی است که کنترل مرکزی خروجی، حفاظت قوی‌تر در برابر SSRF، و قابلیت ممیزی بهتر شبکه می‌خواهند. -OpenClaw هیچ پراکسی‌ای را همراه خود ارائه، دانلود، راه‌اندازی، پیکربندی، یا تأیید نمی‌کند. شما فناوری پراکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های معمول HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند. +OpenClaw هیچ پروکسی‌ای را همراه خود ارائه، دانلود، راه‌اندازی، پیکربندی یا تأیید نمی‌کند. شما فناوری پروکسی متناسب با محیط خود را اجرا می‌کنید، و OpenClaw کلاینت‌های معمول HTTP و WebSocket محلیِ فرایند را از طریق آن مسیریابی می‌کند. -## چرا از پراکسی استفاده کنیم؟ +## چرا از پروکسی استفاده کنیم؟ -پراکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این حتی خارج از سخت‌سازی SSRF هم می‌تواند مفید باشد: +پروکسی به اپراتورها یک نقطه کنترل شبکه برای ترافیک خروجی HTTP و WebSocket می‌دهد. این موضوع حتی خارج از سخت‌سازی SSRF هم می‌تواند مفید باشد: -- سیاست مرکزی: به‌جای اتکا به اینکه هر محل فراخوانی HTTP در برنامه قوانین شبکه را درست اعمال کند، یک سیاست خروجی واحد نگه دارید. -- بررسی‌های زمان اتصال: مقصد را پس از حل DNS و بلافاصله پیش از آنکه پراکسی اتصال بالادستی را باز کند ارزیابی کنید. +- سیاست مرکزی: به‌جای تکیه بر اینکه هر محل فراخوانی HTTP در برنامه قواعد شبکه را درست اعمال کند، یک سیاست خروجی واحد را نگه‌داری کنید. +- بررسی‌های زمان اتصال: مقصد را پس از حل DNS و درست پیش از اینکه پروکسی اتصال بالادستی را باز کند ارزیابی کنید. - دفاع در برابر DNS rebinding: فاصله بین بررسی DNS در سطح برنامه و اتصال خروجی واقعی را کاهش دهید. -- پوشش گسترده‌تر JavaScript: کلاینت‌های معمول `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch و کلاینت‌های مشابه را از همان مسیر عبور دهید. +- پوشش گسترده‌تر JavaScript: کلاینت‌های معمول `fetch`، `node:http`، `node:https`، WebSocket، axios، got، node-fetch، و کلاینت‌های مشابه را از همان مسیر عبور دهید. - قابلیت ممیزی: مقصدهای مجاز و ردشده را در مرز خروجی ثبت کنید. -- کنترل عملیاتی: قوانین مقصد، جداسازی شبکه، محدودیت نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید. +- کنترل عملیاتی: قواعد مقصد، جداسازی شبکه، محدودیت‌های نرخ، یا فهرست‌های مجاز خروجی را بدون بازسازی OpenClaw اعمال کنید. -مسیریابی پراکسی یک محافظ در سطح فرایند برای خروجی معمول HTTP و WebSocket است. این به اپراتورها یک مسیر fail-closed برای مسیریابی کلاینت‌های HTTP پشتیبانی‌شده JavaScript از طریق پراکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پراکسی را تأیید کند. +مسیریابی پروکسی یک حفاظ در سطح فرایند برای خروجی معمول HTTP و WebSocket است. این قابلیت به اپراتورها یک مسیر fail-closed برای مسیریابی کلاینت‌های HTTP پشتیبانی‌شده JavaScript از طریق پروکسی فیلترکننده خودشان می‌دهد، اما یک سندباکس شبکه در سطح سیستم‌عامل نیست و باعث نمی‌شود OpenClaw سیاست مقصد پروکسی را تأیید کند. ## OpenClaw چگونه ترافیک را مسیریابی می‌کند -وقتی `proxy.enabled=true` باشد و یک URL پراکسی پیکربندی شده باشد، فرایندهای محافظت‌شده زمان اجرا مانند `openclaw gateway run`، `openclaw node run`، و `openclaw agent --local` خروجی معمول HTTP و WebSocket را از طریق پراکسی پیکربندی‌شده مسیریابی می‌کنند: +وقتی `proxy.enabled=true` و یک URL پروکسی پیکربندی شده باشد، فرایندهای محافظت‌شده زمان اجرا مانند `openclaw gateway run`، `openclaw node run`، و `openclaw agent --local` خروجی معمول HTTP و WebSocket را از طریق پروکسی پیکربندی‌شده مسیریابی می‌کنند: ```text OpenClaw process @@ -43,27 +43,27 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -قرارداد عمومی، رفتار مسیریابی است، نه hookهای داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket سطح کنترل OpenClaw Gateway وقتی URL Gateway از `localhost` یا یک IP loopback لفظی مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، برای ترافیک RPC مربوط به Gateway در local loopback از یک مسیر مستقیم محدود استفاده می‌کنند. این مسیر سطح کنترل باید بتواند به Gatewayهای loopback دسترسی داشته باشد، حتی وقتی پراکسی اپراتور مقصدهای loopback را مسدود می‌کند. درخواست‌های معمول HTTP و WebSocket زمان اجرا همچنان از پراکسی پیکربندی‌شده استفاده می‌کنند. +قرارداد عمومی، رفتار مسیریابی است، نه هوک‌های داخلی Node که برای پیاده‌سازی آن استفاده می‌شوند. کلاینت‌های WebSocket صفحه کنترل OpenClaw Gateway برای ترافیک RPC مربوط به local loopback Gateway، وقتی URL Gateway از `localhost` یا یک IP لوپ‌بک صریح مانند `127.0.0.1` یا `[::1]` استفاده می‌کند، از یک مسیر مستقیم محدود استفاده می‌کنند. آن مسیر صفحه کنترل باید بتواند به Gatewayهای لوپ‌بک برسد، حتی زمانی که پروکسی اپراتور مقصدهای لوپ‌بک را مسدود می‌کند. درخواست‌های معمول HTTP و WebSocket زمان اجرا همچنان از پروکسی پیکربندی‌شده استفاده می‌کنند. -در داخل، OpenClaw برای این قابلیت از دو hook مسیریابی در سطح فرایند استفاده می‌کند: +در داخل، OpenClaw برای این قابلیت از دو هوک مسیریابی در سطح فرایند استفاده می‌کند: -- مسیریابی dispatcher در Undici شامل `fetch`، کلاینت‌های مبتنی بر undici، و transportهایی می‌شود که dispatcher undici خودشان را فراهم می‌کنند. -- مسیریابی `global-agent` شامل فراخوان‌های هسته Node برای `node:http` و `node:https` می‌شود، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get`، و `https.get` ساخته شده‌اند. حالت پراکسی مدیریت‌شده آن global agent را اجباری می‌کند تا عامل‌های HTTP صریح Node تصادفاً پراکسی اپراتور را دور نزنند. +- مسیریابی dispatcher در Undici شامل `fetch`، کلاینت‌های مبتنی بر undici، و انتقال‌هایی می‌شود که dispatcher اختصاصی undici خود را ارائه می‌کنند. +- مسیریابی `global-agent` فراخوان‌های هسته Node یعنی `node:http` و `node:https` را پوشش می‌دهد، از جمله بسیاری از کتابخانه‌هایی که روی `http.request`، `https.request`، `http.get`، و `https.get` ساخته شده‌اند. حالت پروکسی مدیریت‌شده آن عامل سراسری را اجبار می‌کند تا عامل‌های صریح HTTP در Node به‌طور تصادفی پروکسی اپراتور را دور نزنند. -برخی Pluginها transportهای سفارشی خودشان را دارند که حتی وقتی مسیریابی در سطح فرایند وجود دارد، به سیم‌کشی صریح پراکسی نیاز دارند. برای مثال، transport مربوط به Bot API در Telegram از dispatcher اختصاصی HTTP/1 undici خودش استفاده می‌کند و بنابراین env پراکسی فرایند به‌علاوه fallback مدیریت‌شده `OPENCLAW_PROXY_URL` را در آن مسیر transport مالک‌محور رعایت می‌کند. +برخی Pluginها انتقال‌های سفارشی خود را دارند که حتی با وجود مسیریابی در سطح فرایند، به سیم‌کشی صریح پروکسی نیاز دارند. برای مثال، انتقال Bot API در Telegram از dispatcher اختصاصی HTTP/1 در undici استفاده می‌کند و بنابراین env پروکسی فرایند به‌همراه جایگزین مدیریت‌شده `OPENCLAW_PROXY_URL` را در آن مسیر انتقال مالک‌محور رعایت می‌کند. -خود URL پراکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پراکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک listener ساده HTTP برای پراکسی رو‌به‌جلو مانند `http://127.0.0.1:3128` را دارد. +خود URL پروکسی باید از `http://` استفاده کند. مقصدهای HTTPS همچنان از طریق پروکسی با HTTP `CONNECT` پشتیبانی می‌شوند؛ این فقط یعنی OpenClaw انتظار یک شنونده پروکسی ارسال HTTP ساده مانند `http://127.0.0.1:3128` را دارد. -وقتی پراکسی فعال است، OpenClaw مقدارهای `no_proxy`، `NO_PROXY`، و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، بنابراین باقی‌ماندن `localhost` یا `127.0.0.1` در آن‌ها باعث می‌شود مقصدهای پرریسک SSRF از پراکسی فیلترکننده عبور نکنند. +وقتی پروکسی فعال است، OpenClaw مقادیر `no_proxy`، `NO_PROXY`، و `GLOBAL_AGENT_NO_PROXY` را پاک می‌کند. این فهرست‌های دورزدن مبتنی بر مقصد هستند، بنابراین باقی گذاشتن `localhost` یا `127.0.0.1` در آن‌ها باعث می‌شود هدف‌های پرخطر SSRF از پروکسی فیلترکننده عبور نکنند. -هنگام خاموش شدن، OpenClaw محیط قبلی پراکسی را بازیابی می‌کند و وضعیت مسیریابی کش‌شده فرایند را بازنشانی می‌کند. +در زمان خاموشی، OpenClaw محیط پروکسی قبلی را بازیابی می‌کند و وضعیت مسیریابی فرایندِ کش‌شده را بازنشانی می‌کند. -## اصطلاحات مرتبط با پراکسی +## اصطلاحات مرتبط با پروکسی -- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پراکسی رو‌به‌جلو خروجی برای خروجی زمان اجرای OpenClaw. این صفحه آن قابلیت را مستند می‌کند. -- `gateway.auth.mode: "trusted-proxy"`: احراز هویت پراکسی معکوس ورودیِ آگاه از هویت برای دسترسی Gateway. [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید. -- `openclaw proxy`: پراکسی اشکال‌زدایی محلی و بازرس capture برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید. -- تنظیمات پراکسی ویژه کانال یا ارائه‌دهنده: overrideهای مالک‌محور برای یک transport خاص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجرا است، پراکسی شبکه مدیریت‌شده را ترجیح دهید. +- `proxy.enabled` / `proxy.proxyUrl`: مسیریابی پروکسی ارسال خروجی برای خروجی زمان اجرای OpenClaw. این صفحه همین قابلیت را مستند می‌کند. +- `gateway.auth.mode: "trusted-proxy"`: احراز هویت پروکسی معکوسِ آگاه از هویت برای دسترسی به Gateway. [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید. +- `openclaw proxy`: پروکسی اشکال‌زدایی محلی و بازرس ثبت ترافیک برای توسعه و پشتیبانی. [openclaw proxy](/fa/cli/proxy) را ببینید. +- تنظیمات پروکسی مخصوص کانال یا ارائه‌دهنده: بازنویسی‌های مالک‌محور برای یک انتقال مشخص. وقتی هدف کنترل مرکزی خروجی در سراسر زمان اجرا است، پروکسی شبکه مدیریت‌شده را ترجیح دهید. ## پیکربندی @@ -73,7 +73,7 @@ proxy: proxyUrl: http://127.0.0.1:3128 ``` -همچنین می‌توانید URL را از طریق محیط ارائه کنید، در حالی که `proxy.enabled=true` را در پیکربندی نگه می‌دارید: +همچنین می‌توانید URL را از طریق محیط ارائه کنید، درحالی‌که `proxy.enabled=true` را در پیکربندی نگه می‌دارید: ```bash OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run @@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run `proxy.proxyUrl` بر `OPENCLAW_PROXY_URL` اولویت دارد. -اگر `enabled=true` باشد اما هیچ URL پراکسی معتبری پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، در شروع اجرا شکست می‌خورند. +اگر `enabled=true` باشد اما هیچ URL معتبر پروکسی پیکربندی نشده باشد، فرمان‌های محافظت‌شده به‌جای بازگشت به دسترسی مستقیم شبکه، در شروع به‌کار شکست می‌خورند. برای سرویس‌های Gateway مدیریت‌شده که با `openclaw gateway start` شروع می‌شوند، بهتر است URL را در پیکربندی ذخیره کنید: @@ -92,63 +92,63 @@ openclaw gateway install --force openclaw gateway start ``` -fallback محیط برای اجراهای foreground مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env`، قرار دهید و سپس سرویس را دوباره نصب کنید تا launchd، systemd، یا Scheduled Tasks، gateway را با آن مقدار شروع کند. +جایگزین محیطی برای اجراهای پیش‌زمینه مناسب‌تر است. اگر از آن با یک سرویس نصب‌شده استفاده می‌کنید، `OPENCLAW_PROXY_URL` را در محیط پایدار سرویس، مانند `$OPENCLAW_STATE_DIR/.env` یا `~/.openclaw/.env` قرار دهید، سپس سرویس را دوباره نصب کنید تا launchd، systemd، یا Scheduled Tasks، Gateway را با آن مقدار شروع کند. -برای فرمان‌های `openclaw --container ...`، OpenClaw وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد آن را به CLI فرزند هدف‌گیری‌شده برای کانتینر ارسال می‌کند. URL باید از داخل کانتینر قابل دسترسی باشد؛ `127.0.0.1` به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw برای فرمان‌های هدف‌گیری‌شده به کانتینر، URLهای پراکسی loopback را رد می‌کند مگر اینکه آن بررسی ایمنی را صریحاً override کنید. +برای فرمان‌های `openclaw --container ...`، وقتی `OPENCLAW_PROXY_URL` تنظیم شده باشد، OpenClaw آن را به CLI فرزند هدف‌گیری‌شده برای کانتینر ارسال می‌کند. URL باید از داخل کانتینر قابل دسترسی باشد؛ `127.0.0.1` به خود کانتینر اشاره می‌کند، نه میزبان. OpenClaw برای فرمان‌های هدف‌گیری‌شده برای کانتینر، URLهای پروکسی لوپ‌بک را رد می‌کند، مگر اینکه آن بررسی ایمنی را به‌صورت صریح بازنویسی کنید. -## الزامات پراکسی +## الزامات پروکسی -سیاست پراکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پراکسی مقصدهای درست را مسدود می‌کند. +سیاست پروکسی مرز امنیتی است. OpenClaw نمی‌تواند تأیید کند که پروکسی هدف‌های درست را مسدود می‌کند. -پراکسی را طوری پیکربندی کنید که: +پروکسی را طوری پیکربندی کنید که: -- فقط به loopback یا یک interface خصوصی و مورد اعتماد bind شود. +- فقط به لوپ‌بک یا یک رابط خصوصی مورد اعتماد bind شود. - دسترسی را محدود کند تا فقط فرایند، میزبان، کانتینر، یا حساب سرویس OpenClaw بتواند از آن استفاده کند. - مقصدها را خودش resolve کند و IPهای مقصد را پس از حل DNS مسدود کند. -- سیاست را هنگام اتصال، هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT`، اعمال کند. -- دورزدن‌های مبتنی بر مقصد را برای محدوده‌های loopback، خصوصی، link-local، metadata، multicast، reserved، یا documentation رد کند. -- از فهرست‌های مجاز hostname پرهیز کند مگر اینکه به مسیر حل DNS کاملاً اعتماد دارید. -- مقصد، تصمیم، وضعیت، و دلیل را بدون ثبت بدنه‌های درخواست، headerهای authorization، cookieها، یا سایر secretها ثبت کند. -- سیاست پراکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند. +- سیاست را در زمان اتصال، هم برای درخواست‌های HTTP ساده و هم برای تونل‌های HTTPS `CONNECT` اعمال کند. +- دورزدن‌های مبتنی بر مقصد را برای محدوده‌های لوپ‌بک، خصوصی، link-local، metadata، multicast، reserved، یا documentation رد کند. +- از فهرست‌های مجاز نام میزبان پرهیز کند، مگر اینکه مسیر حل DNS را کاملاً قابل اعتماد بدانید. +- مقصد، تصمیم، وضعیت، و دلیل را بدون ثبت بدنه درخواست‌ها، سرآیندهای مجوز، کوکی‌ها، یا سایر اسرار ثبت کند. +- سیاست پروکسی را تحت کنترل نسخه نگه دارد و تغییرات را مانند پیکربندی حساس امنیتی بازبینی کند. ## مقصدهای مسدودشده پیشنهادی -از این denylist به‌عنوان نقطه شروع برای هر پراکسی رو‌به‌جلو، firewall، یا سیاست خروجی استفاده کنید. +از این فهرست انکار به‌عنوان نقطه شروع برای هر پروکسی ارسال، فایروال، یا سیاست خروجی استفاده کنید. -منطق classifier سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. hookهای parity مرتبط عبارت‌اند از `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX`، و مدیریت sentinel تعبیه‌شده IPv4 برای NAT64، 6to4، Teredo، ISATAP، و فرم‌های IPv4-mapped. این فایل‌ها هنگام نگهداری یک سیاست پراکسی خارجی مرجع‌های مفیدی هستند، اما OpenClaw آن قوانین را به‌صورت خودکار در پراکسی شما صادر یا اعمال نمی‌کند. +منطق طبقه‌بندی در سطح برنامه OpenClaw در `src/infra/net/ssrf.ts` و `src/shared/net/ip.ts` قرار دارد. هوک‌های هم‌ارزی مرتبط `BLOCKED_HOSTNAMES`، `BLOCKED_IPV4_SPECIAL_USE_RANGES`، `BLOCKED_IPV6_SPECIAL_USE_RANGES`، `RFC2544_BENCHMARK_PREFIX`، و مدیریت sentinel داخلی IPv4 برای NAT64، 6to4، Teredo، ISATAP، و فرم‌های نگاشت‌شده به IPv4 هستند. این فایل‌ها هنگام نگه‌داری سیاست پروکسی خارجی منابع مفیدی هستند، اما OpenClaw آن قواعد را به‌طور خودکار در پروکسی شما صادر یا اعمال نمی‌کند. -| محدوده یا میزبان | دلیل مسدود کردن | +| محدوده یا میزبان | دلیل مسدودسازی | | ------------------------------------------------------------------------------------ | ---------------------------------------------------- | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | -| `::1/128` | IPv6 loopback | -| `0.0.0.0/8`, `::/128` | آدرس‌های نامشخص و این-شبکه | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبکه‌های خصوصی RFC1918 | -| `169.254.0.0/16`, `fe80::/10` | آدرس‌های link-local و مسیرهای رایج metadata ابری | -| `169.254.169.254`, `metadata.google.internal` | سرویس‌های metadata ابری | -| `100.64.0.0/10` | فضای آدرس مشترک NAT در سطح carrier | -| `198.18.0.0/15`, `2001:2::/48` | محدوده‌های benchmarking | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | محدوده‌های special-use و documentation | -| `224.0.0.0/4`, `ff00::/8` | Multicast | -| `240.0.0.0/4` | IPv4 رزرو‌شده | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | لوپ‌بک IPv4 | +| `::1/128` | لوپ‌بک IPv6 | +| `0.0.0.0/8`, `::/128` | نشانی‌های نامشخص و این-شبکه | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | شبکه‌های خصوصی RFC1918 | +| `169.254.0.0/16`, `fe80::/10` | نشانی‌های Link-local و مسیرهای رایج metadata ابری | +| `169.254.169.254`, `metadata.google.internal` | سرویس‌های metadata ابری | +| `100.64.0.0/10` | فضای نشانی مشترک NAT در سطح حامل | +| `198.18.0.0/15`, `2001:2::/48` | محدوده‌های بنچمارک | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | محدوده‌های استفاده ویژه و مستندسازی | +| `224.0.0.0/4`, `ff00::/8` | Multicast | +| `240.0.0.0/4` | IPv4 رزروشده | | `fc00::/7`, `fec0::/10` | محدوده‌های محلی/خصوصی IPv6 | -| `100::/64`, `2001:20::/28` | محدوده‌های IPv6 discard و ORCHIDv2 | -| `64:ff9b::/96`, `64:ff9b:1::/48` | پیشوندهای NAT64 با IPv4 تعبیه‌شده | -| `2002::/16`, `2001::/32` | 6to4 و Teredo با IPv4 تعبیه‌شده | -| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv4-mapped | +| `100::/64`, `2001:20::/28` | محدوده‌های discard و ORCHIDv2 در IPv6 | +| `64:ff9b::/96`, `64:ff9b:1::/48` | پیشوندهای NAT64 با IPv4 جاسازی‌شده | +| `2002::/16`, `2001::/32` | 6to4 و Teredo با IPv4 جاسازی‌شده | +| `::/96`, `::ffff:0:0/96` | IPv6 سازگار با IPv4 و IPv6 نگاشت‌شده به IPv4 | -اگر ارائه‌دهنده ابر یا پلتفرم شبکه شما میزبان‌های metadata یا محدوده‌های رزروشده بیشتری را مستند کرده است، آن‌ها را هم اضافه کنید. +اگر ارائه‌دهنده ابر یا پلتفرم شبکه شما میزبان‌های metadata یا محدوده‌های رزروشده بیشتری را مستند کرده است، آن‌ها را نیز اضافه کنید. ## اعتبارسنجی -پراکسی را از همان میزبان، کانتینر، یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید: +پروکسی را از همان میزبان، کانتینر، یا حساب سرویسی که OpenClaw را اجرا می‌کند اعتبارسنجی کنید: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -به‌صورت پیش‌فرض، وقتی مقصدهای سفارشی ارائه نشده باشند، فرمان بررسی می‌کند که `https://example.com/` موفق شود و یک canary موقت loopback را شروع می‌کند که پراکسی نباید به آن برسد. بررسی ردشده پیش‌فرض وقتی موفق است که پراکسی یک پاسخ denial غیر-2xx برگرداند یا canary را با شکست transport مسدود کند؛ اگر پاسخ موفق به canary برسد، شکست می‌خورد. اگر هیچ پراکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. برای آزمودن انتظارهای ویژه استقرار از `--allowed-url` و `--denied-url` استفاده کنید. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پراکسی قابل دسترسی بوده است، و هر خطای transport به‌عنوان نامشخص گزارش می‌شود چون OpenClaw نمی‌تواند ثابت کند پراکسی یک origin قابل دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود. +به‌طور پیش‌فرض، وقتی مقصدهای سفارشی ارائه نشده باشند، فرمان بررسی می‌کند که `https://example.com/` موفق شود و یک قناری موقت لوپ‌بک را شروع می‌کند که پروکسی نباید به آن برسد. بررسی ردشده پیش‌فرض زمانی قبول می‌شود که پروکسی یک پاسخ رد غیر 2xx برگرداند یا قناری را با شکست انتقال مسدود کند؛ اگر یک پاسخ موفق به قناری برسد، شکست می‌خورد. اگر هیچ پروکسی‌ای فعال و پیکربندی نشده باشد، اعتبارسنجی یک مشکل پیکربندی را گزارش می‌کند؛ برای یک preflight یک‌باره پیش از تغییر پیکربندی از `--proxy-url` استفاده کنید. برای آزمون انتظارهای مخصوص استقرار از `--allowed-url` و `--denied-url` استفاده کنید. مقصدهای ردشده سفارشی fail-closed هستند: هر پاسخ HTTP یعنی مقصد از طریق پروکسی قابل دسترسی بوده است، و هر خطای انتقال به‌عنوان نامشخص گزارش می‌شود، چون OpenClaw نمی‌تواند ثابت کند که پروکسی یک origin قابل دسترسی را مسدود کرده است. در صورت شکست اعتبارسنجی، فرمان با کد 1 خارج می‌شود. -برای automation از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پراکسی، هرگونه خطای پیکربندی، و بررسی هر مقصد است. credentialهای URL پراکسی در خروجی متنی و JSON پنهان می‌شوند: +برای خودکارسازی از `--json` استفاده کنید. خروجی JSON شامل نتیجه کلی، منبع مؤثر پیکربندی پروکسی، هر خطای پیکربندی، و هر بررسی مقصد است. اعتبارنامه‌های URL پروکسی در خروجی متنی و JSON پنهان‌سازی می‌شوند: ```json { @@ -170,7 +170,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128 } ``` -می‌توانید به‌صورت دستی نیز با `curl` اعتبارسنجی کنید: +همچنین می‌توانید با `curl` به‌صورت دستی اعتبارسنجی کنید: ```bash curl -x http://127.0.0.1:3128 https://example.com/ @@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -درخواست عمومی باید موفق شود. درخواست‌های لوپ‌بک و فراداده باید توسط پراکسی مسدود شوند. برای `openclaw proxy validate`، قناری لوپ‌بک داخلی می‌تواند رد شدن توسط پراکسی را از مبدا قابل دسترس تشخیص دهد. بررسی‌های سفارشی `--denied-url` این قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را به‌عنوان شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پراکسی شما سیگنال رد ویژه استقرار را ارائه دهد که بتوانید جداگانه آن را راستی‌آزمایی کنید. +درخواست عمومی باید موفق شود. درخواست‌های لوپ‌بک و فراداده باید توسط پروکسی مسدود شوند. برای `openclaw proxy validate`، قناری داخلی لوپ‌بک می‌تواند رد شدن توسط پروکسی را از یک مبدا قابل دسترسی تشخیص دهد. بررسی‌های سفارشی `--denied-url` آن قناری را ندارند، بنابراین هم پاسخ‌های HTTP و هم شکست‌های مبهم انتقال را شکست اعتبارسنجی در نظر بگیرید، مگر اینکه پروکسی شما سیگنال رد مخصوص استقراری را آشکار کند که بتوانید جداگانه آن را تأیید کنید. -سپس مسیریابی پراکسی OpenClaw را فعال کنید: +سپس مسیریابی پروکسی OpenClaw را فعال کنید: ```bash openclaw config set proxy.enabled true @@ -198,10 +198,11 @@ proxy: ## محدودیت‌ها -- پراکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتی محلیِ فرایند بهبود می‌دهد، اما یک محیط ایزوله شبکه‌ای در سطح سیستم‌عامل نیست. -- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی و فرایندهای فرزند ممکن است از مسیریابی پراکسی در سطح Node عبور کنند، مگر اینکه متغیرهای محیطی پراکسی را به ارث ببرند و رعایت کنند. -- IRC یک کانال خام TCP/TLS خارج از مسیریابی پراکسی پیش‌روی مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از طریق آن پراکسی پیش‌رو عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروج مستقیم IRC صراحتا تایید شده باشد. -- رابط‌های وب محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پراکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw برای آن‌ها یک میان‌بر عمومی شبکه محلی ارائه نمی‌کند. -- میان‌بر پراکسی برای صفحه کنترل Gateway عمدا به `localhost` و نشانی‌های URL با IP لوپ‌بک صریح محدود است. برای اتصال‌های مستقیم محلی به صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789` یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمول مبتنی بر نام میزبان مسیریابی می‌شوند. -- OpenClaw سیاست پراکسی شما را بازرسی، آزمایش یا گواهی نمی‌کند. -- تغییرات سیاست پراکسی را به‌عنوان تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید. +- پروکسی پوشش را برای کلاینت‌های HTTP و WebSocket جاوااسکریپتِ محلیِ پردازه بهبود می‌دهد، اما سندباکس شبکه در سطح سیستم‌عامل نیست. +- سوکت‌های خام `net`، `tls` و `http2`، افزونه‌های بومی و پردازه‌های فرزند ممکن است مسیریابی پروکسی در سطح Node را دور بزنند، مگر اینکه متغیرهای محیطی پروکسی را به ارث ببرند و رعایت کنند. +- IRC یک کانال TCP/TLS خام خارج از مسیریابی پروکسی روبه‌جلوی مدیریت‌شده توسط اپراتور است. در استقرارهایی که نیاز دارند همه خروجی‌ها از طریق آن پروکسی روبه‌جلو عبور کنند، `channels.irc.enabled=false` را تنظیم کنید، مگر اینکه خروجی مستقیم IRC صراحتاً تأیید شده باشد. +- پروکسی اشکال‌زدایی محلی ابزار تشخیصی است و ارسال مستقیم بالادستی آن برای درخواست‌های پروکسی و تونل‌های CONNECT به‌طور پیش‌فرض هنگامی که حالت پروکسی مدیریت‌شده فعال است غیرفعال می‌شود؛ ارسال مستقیم را فقط برای تشخیص‌های محلی تأییدشده فعال کنید. +- WebUIهای محلی کاربر و سرورهای مدل محلی باید در صورت نیاز در سیاست پروکسی اپراتور در فهرست مجاز قرار گیرند؛ OpenClaw یک دورزدن عمومی شبکه محلی برای آن‌ها ارائه نمی‌کند. +- دورزدن پروکسی صفحه کنترل Gateway عمداً به URLهای `localhost` و IPهای لفظی لوپ‌بک محدود شده است. برای اتصال‌های مستقیم محلی صفحه کنترل Gateway از `ws://127.0.0.1:18789`، `ws://[::1]:18789` یا `ws://localhost:18789` استفاده کنید؛ نام‌های میزبان دیگر مانند ترافیک معمولی مبتنی بر نام میزبان مسیریابی می‌شوند. +- OpenClaw سیاست پروکسی شما را بازرسی، آزمایش یا گواهی نمی‌کند. +- تغییرات سیاست پروکسی را تغییرات عملیاتی حساس از نظر امنیتی در نظر بگیرید. diff --git a/docs/fa/tools/subagents.md b/docs/fa/tools/subagents.md index 7c327639a..7207e9b4c 100644 --- a/docs/fa/tools/subagents.md +++ b/docs/fa/tools/subagents.md @@ -1,40 +1,47 @@ --- read_when: - - می‌خواهید کار پس‌زمینه یا موازی را از طریق عامل انجام دهید - - شما در حال تغییر sessions_spawn یا خط‌مشی ابزار زیردستیار هستید - - شما در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیرعامل وابسته به رشتهٔ گفتگو هستید + - می‌خواهید کار پس‌زمینه یا موازی از طریق عامل انجام شود + - شما در حال تغییر خط‌مشی sessions_spawn یا ابزار زیرعامل هستید + - در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیردستیارِ وابسته به رشته هستید sidebarTitle: Sub-agents -summary: اجراهای ایزولهٔ عامل در پس‌زمینه را راه‌اندازی کنید که نتایج را به گفت‌وگوی درخواست‌دهنده اعلام می‌کنند -title: عامل‌های فرعی +summary: اجراهای ایزولهٔ عامل در پس‌زمینه را راه‌اندازی کنید که نتایج را به چت درخواست‌کننده اعلام می‌کنند +title: زیرعامل‌ها x-i18n: - generated_at: "2026-05-04T02:28:54Z" + generated_at: "2026-05-04T07:08:28Z" model: gpt-5.5 provider: openai - source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37 + source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8 source_path: tools/subagents.md workflow: 16 --- -زیرعامل‌ها اجراهای پس‌زمینهٔ عامل هستند که از یک اجرای عامل موجود ایجاد می‌شوند. +زیرعامل‌ها اجرای عامل‌های پس‌زمینه هستند که از یک اجرای عامل موجود ایجاد می‌شوند. آن‌ها در نشست خودشان (`agent::subagent:`) اجرا می‌شوند و، -پس از پایان، نتیجهٔ خود را به کانال گفت‌وگوی درخواست‌کننده **اعلام** می‌کنند. +پس از پایان، نتیجه خود را در کانال چت درخواست‌کننده **اعلام** می‌کنند. هر اجرای زیرعامل به‌عنوان یک -[وظیفهٔ پس‌زمینه](/fa/automation/tasks) پیگیری می‌شود. +[کار پس‌زمینه](/fa/automation/tasks) ردیابی می‌شود. اهداف اصلی: -- موازی‌سازی کارهای «پژوهش / وظیفهٔ طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی. -- جدا نگه داشتن پیش‌فرض زیرعامل‌ها (جداسازی نشست + sandboxing اختیاری). -- دشوار کردن سوءاستفاده از سطح ابزار: زیرعامل‌ها به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند. -- پشتیبانی از عمق تودرتوی قابل‌پیکربندی برای الگوهای orchestrator. +- موازی‌سازی کارهای «پژوهش / وظیفه طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی. +- ایزوله نگه داشتن زیرعامل‌ها به‌صورت پیش‌فرض (جداسازی نشست + sandboxing اختیاری). +- سخت کردن سطح ابزار برای سوءاستفاده: زیرعامل‌ها به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند. +- پشتیبانی از عمق تودرتوی قابل پیکربندی برای الگوهای هماهنگ‌کننده. -**یادداشت هزینه:** هر زیرعامل به‌صورت پیش‌فرض context و مصرف token خودش را دارد. برای وظایف سنگین یا تکراری، یک مدل ارزان‌تر برای زیرعامل‌ها تنظیم کنید و عامل اصلی خود را روی مدلی باکیفیت‌تر نگه دارید. از طریق `agents.defaults.subagents.model` یا overrideهای هر عامل پیکربندی کنید. وقتی یک فرزند واقعاً به transcript فعلی درخواست‌کننده نیاز دارد، عامل می‌تواند برای همان یک spawn مقدار `context: "fork"` را درخواست کند. نشست‌های subagent وابسته به thread به‌صورت پیش‌فرض `context: "fork"` دارند، چون مکالمهٔ فعلی را به یک thread پیگیری منشعب می‌کنند. +**نکته هزینه:** هر زیرعامل به‌صورت پیش‌فرض context و مصرف توکن خودش را دارد. +برای وظایف سنگین یا تکراری، یک مدل ارزان‌تر برای زیرعامل‌ها تنظیم کنید +و عامل اصلی خود را روی یک مدل باکیفیت‌تر نگه دارید. از طریق +`agents.defaults.subagents.model` یا بازنویسی‌های هر عامل پیکربندی کنید. وقتی یک فرزند + واقعاً به رونوشت فعلی درخواست‌کننده نیاز دارد، عامل می‌تواند برای همان یک ایجاد + `context: "fork"` را درخواست کند. نشست‌های زیرعامل وابسته به thread به‌صورت پیش‌فرض + `context: "fork"` هستند، زیرا گفت‌وگوی فعلی را به یک thread پیگیری منشعب می‌کنند. -## فرمان Slash +## دستور Slash -از `/subagents` برای بررسی یا کنترل اجراهای زیرعامل برای **نشست فعلی** استفاده کنید: +از `/subagents` برای بررسی یا کنترل اجراهای زیرعامل برای **نشست فعلی** +استفاده کنید: ```text /subagents list @@ -46,15 +53,15 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -برای هدایت اجرای فعال نشست درخواست‌کنندهٔ فعلی، از [`/steer `](/fa/tools/steer) در سطح بالا استفاده کنید. وقتی هدف یک اجرای فرزند است، از `/subagents steer ` استفاده کنید. +از [`/steer `](/fa/tools/steer) سطح بالا برای هدایت اجرای فعال نشست درخواست‌کننده فعلی استفاده کنید. وقتی هدف یک اجرای فرزند است، از `/subagents steer ` استفاده کنید. -`/subagents info` فرادادهٔ اجرا را نشان می‌دهد (وضعیت، timestampها، شناسهٔ نشست، -مسیر transcript، پاک‌سازی). برای یک نمای یادآوری محدود و فیلترشده از نظر ایمنی، از `sessions_history` استفاده کنید؛ وقتی به transcript کامل خام نیاز دارید، مسیر transcript را روی دیسک بررسی کنید. +`/subagents info` فراداده اجرا را نشان می‌دهد (وضعیت، timestampها، شناسه نشست، +مسیر رونوشت، پاک‌سازی). برای نمای یادآوری محدود و فیلترشده از نظر ایمنی از `sessions_history` استفاده کنید؛ وقتی به رونوشت خام کامل نیاز دارید، مسیر رونوشت را روی دیسک بررسی کنید. ### کنترل‌های اتصال thread -این فرمان‌ها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند. -بخش [کانال‌های پشتیبان thread](#thread-supporting-channels) را در پایین ببینید. +این دستورها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند. +در ادامه [کانال‌های پشتیبان thread](#thread-supporting-channels) را ببینید. ```text /focus @@ -64,71 +71,80 @@ x-i18n: /session max-age ``` -### رفتار spawn +### رفتار ایجاد -`/subagents spawn` یک زیرعامل پس‌زمینه را به‌عنوان فرمان کاربر (نه relay داخلی) شروع می‌کند و پس از پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به گفت‌وگوی درخواست‌کننده می‌فرستد. +`/subagents spawn` یک زیرعامل پس‌زمینه را به‌عنوان دستور کاربر (نه یک +بازرسانی داخلی) شروع می‌کند و پس از پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به +چت درخواست‌کننده می‌فرستد. - - - فرمان spawn غیرمسدودکننده است؛ فوراً یک شناسهٔ اجرا برمی‌گرداند. - - پس از تکمیل، زیرعامل یک پیام خلاصه/نتیجه را به کانال گفت‌وگوی درخواست‌کننده اعلام می‌کند. - - تکمیل push-based است. پس از spawn شدن، فقط برای انتظار تا پایان آن، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه poll نکنید؛ وضعیت را فقط هنگام نیاز برای اشکال‌زدایی یا مداخله بررسی کنید. - - پس از تکمیل، OpenClaw به‌صورت best-effort برگه‌ها/فرآیندهای مرورگری را که توسط آن نشست زیرعامل باز شده‌اند، پیش از ادامهٔ جریان پاک‌سازی اعلام، می‌بندد. + + - دستور ایجاد غیرمسدودکننده است؛ بلافاصله یک شناسه اجرا برمی‌گرداند. + - هنگام تکمیل، زیرعامل یک پیام خلاصه/نتیجه را به کانال چت درخواست‌کننده اعلام می‌کند. + - تکمیل مبتنی بر push است. پس از ایجاد، فقط برای انتظار تا پایان، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه polling نکنید؛ وضعیت را فقط هنگام نیاز برای اشکال‌زدایی یا مداخله بررسی کنید. + - هنگام تکمیل، OpenClaw تا حد امکان tabها/فرایندهای مرورگر را که توسط آن نشست زیرعامل باز شده‌اند، پیش از ادامه جریان پاک‌سازی اعلام می‌بندد. - + - OpenClaw ابتدا تحویل مستقیم `agent` را با یک کلید idempotency پایدار امتحان می‌کند. - - اگر تحویل مستقیم شکست بخورد، به مسیریابی صف fallback می‌کند. - - اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با backoff نمایی کوتاه، پیش از انصراف نهایی، دوباره امتحان می‌شود. - - تحویل تکمیل، مسیر حل‌شدهٔ درخواست‌کننده را نگه می‌دارد: مسیرهای تکمیل وابسته به thread یا وابسته به مکالمه، وقتی در دسترس باشند، اولویت دارند؛ اگر مبدأ تکمیل فقط یک کانال ارائه کند، OpenClaw هدف/حساب گم‌شده را از مسیر حل‌شدهٔ نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند. + - اگر نوبت تکمیل عامل درخواست‌کننده شکست بخورد، خروجی قابل‌مشاهده تولید نکند، یا یک پیشوند آشکارا ناقص از نتیجه فرزند ثبت‌شده برگرداند، OpenClaw به تحویل مستقیم تکمیل از نتیجه فرزند ثبت‌شده بازمی‌گردد. + - اگر تحویل مستقیم قابل استفاده نباشد، به مسیریابی صف بازمی‌گردد. + - اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با یک backoff نمایی کوتاه پیش از صرف‌نظر نهایی دوباره تلاش می‌شود. + - تحویل تکمیل مسیر حل‌شده درخواست‌کننده را نگه می‌دارد: مسیرهای تکمیل وابسته به thread یا وابسته به گفت‌وگو، وقتی در دسترس باشند، برنده می‌شوند؛ اگر مبدأ تکمیل فقط یک کانال ارائه کند، OpenClaw هدف/حساب گم‌شده را از مسیر حل‌شده نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند. - - تحویل تکمیل به نشست درخواست‌کننده، context داخلی تولیدشده در runtime است (نه متن نوشته‌شده توسط کاربر) و شامل موارد زیر است: + + واگذاری تکمیل به نشست درخواست‌کننده context داخلی تولیدشده در زمان اجرا است + (نه متن نوشته‌شده توسط کاربر) و شامل موارد زیر است: - - `Result` — آخرین متن پاسخ قابل‌مشاهدهٔ `assistant`، وگرنه آخرین متن پاک‌سازی‌شدهٔ tool/toolResult. اجراهای نهاییِ شکست‌خورده از متن پاسخ captureشده دوباره استفاده نمی‌کنند. + - `Result` — آخرین متن پاسخ قابل‌مشاهده `assistant`، وگرنه آخرین متن ابزار/toolResult پاک‌سازی‌شده. اجراهای ناموفق پایانی از متن پاسخ ثبت‌شده دوباره استفاده نمی‌کنند. - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`. - - آمار فشردهٔ runtime/token. - - دستور تحویل که به عامل درخواست‌کننده می‌گوید با صدای عادی assistant بازنویسی کند (نه اینکه فرادادهٔ داخلی خام را forward کند). + - آمار فشرده زمان اجرا/توکن. + - یک دستور تحویل که به عامل درخواست‌کننده می‌گوید با صدای عادی دستیار بازنویسی کند (نه اینکه فراداده خام داخلی را ارسال کند). - - - `--model` و `--thinking` پیش‌فرض‌ها را برای همان اجرای مشخص override می‌کنند. - - از `info`/`log` برای بررسی جزئیات و خروجی پس از تکمیل استفاده کنید. + + - `--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 را تبلیغ می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل به عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل گفت‌وگو/thread مربوط به Codex باید `/codex ...` را به ACP ترجیح دهد، مگر اینکه کاربر صریحاً ACP/acpx را درخواست کند. - - OpenClaw مقدار `runtime: "acp"` را پنهان می‌کند تا وقتی ACP فعال باشد، درخواست‌کننده sandboxed نباشد، و یک Plugin پشتیبان مانند `acpx` بارگذاری شده باشد. `runtime: "acp"` انتظار یک شناسهٔ harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای عامل‌های عادی پیکربندی OpenClaw از `agents_list`، از runtime پیش‌فرض زیرعامل استفاده کنید. + - برای نشست‌های harness ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن runtime را اعلام می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل‌به‌عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل چت/thread Codex باید `/codex ...` را به ACP ترجیح دهد، مگر اینکه کاربر صراحتاً ACP/acpx را بخواهد. + - OpenClaw تا زمانی که ACP فعال نشده، درخواست‌کننده sandbox نشده، و یک Plugin backend مانند `acpx` بارگذاری نشده باشد، `runtime: "acp"` را پنهان می‌کند. `runtime: "acp"` انتظار یک شناسه harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` را دارد؛ برای عامل‌های پیکربندی عادی OpenClaw از `agents_list`، از runtime پیش‌فرض زیرعامل استفاده کنید. ## حالت‌های context -زیرعامل‌های native جدا شروع می‌شوند، مگر اینکه فراخواننده صریحاً درخواست fork کردن transcript فعلی را بدهد. +زیرعامل‌های بومی به‌صورت ایزوله شروع می‌شوند، مگر اینکه فراخواننده صراحتاً درخواست کند +رونوشت فعلی fork شود. | حالت | زمان استفاده | رفتار | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان در متن وظیفه مختصر توضیح داد | یک transcript فرزند پاک می‌سازد. این حالت پیش‌فرض است و مصرف token را پایین‌تر نگه می‌دارد. | -| `fork` | کاری که به مکالمهٔ فعلی، نتایج ابزارهای قبلی، یا دستورالعمل‌های ظریف موجود در transcript درخواست‌کننده وابسته است | transcript درخواست‌کننده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. | +| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان آن را در متن وظیفه خلاصه کرد | یک رونوشت فرزند پاک ایجاد می‌کند. این پیش‌فرض است و مصرف توکن را پایین‌تر نگه می‌دارد. | +| `fork` | کاری که به گفت‌وگوی فعلی، نتایج قبلی ابزار، یا دستورهای ظریف موجود در رونوشت درخواست‌کننده وابسته است | رونوشت درخواست‌کننده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. | -از `fork` با احتیاط استفاده کنید. این حالت برای واگذاری context-sensitive است، نه جایگزینی برای نوشتن یک task prompt روشن. +از `fork` با صرفه‌جویی استفاده کنید. این برای واگذاری حساس به context است، نه +جایگزینی برای نوشتن یک prompt وظیفه روشن. ## ابزار: `sessions_spawn` یک اجرای زیرعامل را با `deliver: false` روی lane سراسری `subagent` شروع می‌کند، -سپس یک مرحلهٔ اعلام اجرا می‌کند و پاسخ اعلام را به کانال گفت‌وگوی درخواست‌کننده post می‌کند. +سپس یک گام اعلام را اجرا می‌کند و پاسخ اعلام را به کانال چت درخواست‌کننده +ارسال می‌کند. دسترس‌پذیری به سیاست ابزار مؤثر فراخواننده بستگی دارد. پروفایل‌های `coding` و `full` به‌صورت پیش‌فرض `sessions_spawn` را ارائه می‌کنند. پروفایل `messaging` -این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند، `tools.alsoAllow: ["sessions_spawn", "sessions_yield", +این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند، +`tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` را اضافه کنید یا از `tools.profile: "coding"` استفاده کنید. -سیاست‌های allow/deny مربوط به کانال/گروه، provider، sandbox، و هر عامل، همچنان می‌توانند ابزار را پس از مرحلهٔ پروفایل حذف کنند. برای تأیید فهرست ابزار مؤثر، از همان نشست `/tools` را اجرا کنید. +سیاست‌های کانال/گروه، provider، sandbox و allow/deny هر عامل همچنان می‌توانند +ابزار را پس از مرحله پروفایل حذف کنند. از همان نشست، برای تأیید فهرست مؤثر ابزارها از `/tools` استفاده کنید. **پیش‌فرض‌ها:** -- **مدل:** از فراخواننده به ارث می‌برد، مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` برای هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.model` همچنان اولویت دارد. -- **Thinking:** از فراخواننده به ارث می‌برد، مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` برای هر عامل) را تنظیم کنید؛ مقدار صریح `sessions_spawn.thinking` همچنان اولویت دارد. -- **مهلت اجرای run:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw در صورت تنظیم بودن از `agents.defaults.subagents.runTimeoutSeconds` استفاده می‌کند؛ در غیر این صورت به `0` fallback می‌کند (بدون timeout). +- **مدل:** از فراخواننده ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.model` (یا `agents.list[].subagents.model` هر عامل) را تنظیم کنید؛ یک `sessions_spawn.model` صریح همچنان اولویت دارد. +- **Thinking:** از فراخواننده ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.thinking` (یا `agents.list[].subagents.thinking` هر عامل) را تنظیم کنید؛ یک `sessions_spawn.thinking` صریح همچنان اولویت دارد. +- **مهلت اجرای اجرا:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw وقتی `agents.defaults.subagents.runTimeoutSeconds` تنظیم شده باشد از آن استفاده می‌کند؛ در غیر این صورت به `0` (بدون مهلت) بازمی‌گردد. ### پارامترهای ابزار @@ -136,58 +152,60 @@ x-i18n: شرح وظیفه برای زیرعامل. - برچسب اختیاری و خوانا برای انسان. + برچسب اختیاری قابل خواندن برای انسان. - وقتی `subagents.allowAgents` اجازه بدهد، زیر یک شناسهٔ عامل دیگر spawn کنید. + وقتی توسط `subagents.allowAgents` مجاز باشد، زیر یک شناسه عامل دیگر ایجاد کنید. - `acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صریحاً درخواست شده باشد) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است. + `acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صراحتاً درخواست شده) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است. - فقط ACP. وقتی `runtime: "acp"` باشد، یک نشست harness موجود ACP را از سر می‌گیرد؛ برای spawnهای زیرعامل native نادیده گرفته می‌شود. + فقط ACP. وقتی `runtime: "acp"` است یک نشست harness ACP موجود را از سر می‌گیرد؛ برای ایجادهای زیرعامل بومی نادیده گرفته می‌شود. - فقط ACP. وقتی `runtime: "acp"` باشد، خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای spawnهای زیرعامل native حذف کنید. + فقط ACP. وقتی `runtime: "acp"` است خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای ایجادهای زیرعامل بومی حذف کنید. - مدل زیرعامل را override کنید. مقدارهای نامعتبر رد می‌شوند و زیرعامل با مدل پیش‌فرض اجرا می‌شود و در نتیجهٔ ابزار یک هشدار می‌آید. + مدل زیرعامل را بازنویسی کنید. مقدارهای نامعتبر رد می‌شوند و زیرعامل روی مدل پیش‌فرض با یک هشدار در نتیجه ابزار اجرا می‌شود. - سطح thinking را برای اجرای زیرعامل override کنید. + سطح thinking را برای اجرای زیرعامل بازنویسی کنید. - وقتی تنظیم شده باشد، به‌صورت پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه abort می‌شود. + وقتی تنظیم شده باشد به‌صورت پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، وگرنه `0`. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه لغو می‌شود. وقتی `true` باشد، اتصال thread کانال را برای این نشست زیرعامل درخواست می‌کند. - اگر `thread: true` باشد و `mode` حذف شده باشد، پیش‌فرض `session` می‌شود. `mode: "session"` به `thread: true` نیاز دارد. + اگر `thread: true` باشد و `mode` حذف شود، پیش‌فرض به `session` تبدیل می‌شود. `mode: "session"` به `thread: true` نیاز دارد. - `"delete"` بلافاصله پس از اعلام archive می‌کند (هنوز transcript را از طریق rename نگه می‌دارد). + `"delete"` بلافاصله پس از اعلام archive می‌کند (همچنان رونوشت را از طریق rename نگه می‌دارد). - `require` مگر اینکه runtime فرزند هدف sandboxed باشد، spawn را رد می‌کند. + `require` ایجاد را رد می‌کند، مگر اینکه runtime فرزند هدف sandbox شده باشد. - `fork` transcript فعلی درخواست‌کننده را به نشست فرزند منشعب می‌کند. فقط زیرعامل‌های native. spawnهای وابسته به thread به‌صورت پیش‌فرض `fork` هستند؛ spawnهای غیر thread به‌صورت پیش‌فرض `isolated` هستند. + `fork` رونوشت فعلی درخواست‌کننده را به نشست فرزند منشعب می‌کند. فقط زیرعامل‌های بومی. ایجادهای وابسته به thread به‌صورت پیش‌فرض `fork` هستند؛ ایجادهای غیر thread به‌صورت پیش‌فرض `isolated` هستند. -`sessions_spawn` پارامترهای تحویل کانال (`target`, -`channel`, `to`, `threadId`, `replyTo`, `transport`) را نمی‌پذیرد. برای تحویل، از -`message`/`sessions_send` از اجرای spawnشده استفاده کنید. +`sessions_spawn` پارامترهای تحویل کانال (`target`، +`channel`، `to`، `threadId`، `replyTo`، `transport`) را نمی‌پذیرد. برای تحویل، از +`message`/`sessions_send` از اجرای ایجادشده استفاده کنید. ## نشست‌های وابسته به thread -وقتی اتصال‌های thread برای یک کانال فعال باشند، یک زیرعامل می‌تواند به یک thread متصل بماند تا پیام‌های پیگیری کاربر در آن thread همچنان به همان نشست زیرعامل route شوند. +وقتی اتصال‌های thread برای یک کانال فعال هستند، یک زیرعامل می‌تواند به یک thread متصل بماند +تا پیام‌های پیگیری کاربر در آن thread همچنان به همان نشست زیرعامل مسیریابی شوند. ### کانال‌های پشتیبان thread -**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از نشست‌های subagent وابسته به thread پایدار (`sessions_spawn` با +**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از +نشست‌های زیرعامل پایدار وابسته به thread (`sessions_spawn` با `thread: true`)، کنترل‌های دستی thread (`/focus`، `/unfocus`، `/agents`، `/session idle`، `/session max-age`) و کلیدهای adapter `channels.discord.threadBindings.enabled`, @@ -199,77 +217,78 @@ x-i18n: - `sessions_spawn` با `thread: true` (و در صورت تمایل `mode: "session"`). + `sessions_spawn` با `thread: true` (و در صورت نیاز `mode: "session"`). - - OpenClaw یک thread را به آن هدف نشست در کانال فعال ایجاد یا متصل می‌کند. + + OpenClaw یک رشته را برای هدف آن نشست در کانال فعال ایجاد می‌کند یا به آن متصل می‌کند. - - پاسخ‌ها و پیام‌های پیگیری در آن thread به نشست متصل route می‌شوند. + + پاسخ‌ها و پیام‌های پیگیری در آن رشته به نشست متصل‌شده مسیریابی می‌شوند. - - از `/session idle` برای بررسی/به‌روزرسانی auto-unfocus هنگام عدم فعالیت و + + از `/session idle` برای بررسی/به‌روزرسانی خروج خودکار از فوکوس بر اثر عدم فعالیت و از `/session max-age` برای کنترل سقف سخت استفاده کنید. - - برای جدا کردن دستی، از `/unfocus` استفاده کنید. + + از `/unfocus` برای جدا کردن دستی استفاده کنید. ### کنترل‌های دستی -| دستور | اثر | -| ------------------ | --------------------------------------------------------------------- | -| `/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) در بالا را ببینید. +- **پیش‌فرض سراسری:** `session.threadBindings.enabled`، `session.threadBindings.idleHours`، `session.threadBindings.maxAgeHours`. +- **بازنویسی کانال و کلیدهای اتصال خودکار هنگام ایجاد** به آداپتر وابسته‌اند. به [کانال‌های پشتیبان رشته](#thread-supporting-channels) در بالا مراجعه کنید. -برای جزئیات فعلی آداپتور، [مرجع پیکربندی](/fa/gateway/configuration-reference) و -[دستورهای اسلش](/fa/tools/slash-commands) را ببینید. +برای جزئیات فعلی آداپتر، [مرجع پیکربندی](/fa/gateway/configuration-reference) و +[فرمان‌های اسلش](/fa/tools/slash-commands) را ببینید. ### فهرست مجاز - فهرست شناسه‌های عامل که می‌توانند از طریق `agentId` صریح هدف قرار بگیرند (`["*"]` هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌دهنده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌دهنده خودش را با `agentId` ایجاد کند، شناسهٔ درخواست‌دهنده را در فهرست وارد کنید. + فهرست شناسه‌های عامل که می‌توانند از طریق `agentId` صریح هدف قرار بگیرند (`["*"]` هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌کننده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌کننده بتواند خودش را با `agentId` ایجاد کند، شناسه درخواست‌کننده را در فهرست قرار دهید. - فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌دهنده `subagents.allowAgents` خودش را تنظیم نکرده باشد استفاده می‌شود. + فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌کننده `subagents.allowAgents` اختصاصی خود را تنظیم نکرده باشد استفاده می‌شود. فراخوانی‌های `sessions_spawn` را که `agentId` را حذف می‌کنند مسدود می‌کند (انتخاب صریح پروفایل را اجباری می‌کند). بازنویسی برای هر عامل: `agents.list[].subagents.requireAgentId`. -اگر نشست درخواست‌دهنده sandbox شده باشد، `sessions_spawn` هدف‌هایی را که -بدون sandbox اجرا می‌شوند رد می‌کند. +اگر نشست درخواست‌کننده در سندباکس باشد، `sessions_spawn` هدف‌هایی را رد می‌کند +که بدون سندباکس اجرا شوند. ### کشف از `agents_list` استفاده کنید تا ببینید کدام شناسه‌های عامل در حال حاضر برای -`sessions_spawn` مجاز هستند. پاسخ شامل مدل مؤثر هر عامل فهرست‌شده و فرادادهٔ -اجرای تعبیه‌شده است تا فراخواننده‌ها بتوانند Pi، سرور برنامهٔ Codex -و سایر اجراهای بومی پیکربندی‌شده را از هم تشخیص دهند. +`sessions_spawn` مجاز هستند. پاسخ، مدل مؤثر هر عامل فهرست‌شده و فراداده +اجرای جاسازی‌شده را شامل می‌شود تا فراخواننده‌ها بتوانند Pi، سرور برنامه Codex +و اجراهای بومی پیکربندی‌شده دیگر را از هم تشخیص دهند. ### بایگانی خودکار -- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌طور خودکار بایگانی می‌شوند (پیش‌فرض `60`). -- بایگانی از `sessions.delete` استفاده می‌کند و متن نشست را به `*.deleted.` تغییر نام می‌دهد (در همان پوشه). -- `cleanup: "delete"` بلافاصله پس از اعلان بایگانی می‌کند (همچنان متن نشست را از طریق تغییر نام نگه می‌دارد). -- بایگانی خودکار با بهترین تلاش انجام می‌شود؛ اگر Gateway دوباره راه‌اندازی شود، تایمرهای معلق از دست می‌روند. +- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌صورت خودکار بایگانی می‌شوند (پیش‌فرض `60`). +- بایگانی از `sessions.delete` استفاده می‌کند و رونوشت را به `*.deleted.` تغییر نام می‌دهد (در همان پوشه). +- `cleanup: "delete"` بلافاصله پس از اعلام، بایگانی می‌کند (همچنان رونوشت را از طریق تغییر نام نگه می‌دارد). +- بایگانی خودکار به‌صورت بهترین تلاش انجام می‌شود؛ اگر Gateway راه‌اندازی مجدد شود، تایمرهای معلق از دست می‌روند. - `runTimeoutSeconds` بایگانی خودکار انجام نمی‌دهد؛ فقط اجرا را متوقف می‌کند. نشست تا زمان بایگانی خودکار باقی می‌ماند. - بایگانی خودکار به‌طور یکسان برای نشست‌های عمق ۱ و عمق ۲ اعمال می‌شود. -- پاک‌سازی مرورگر از پاک‌سازی بایگانی جداست: تب‌ها/فرایندهای مرورگر ردیابی‌شده هنگام پایان اجرا با بهترین تلاش بسته می‌شوند، حتی اگر رکورد متن نشست/نشست نگه داشته شود. +- پاک‌سازی مرورگر از پاک‌سازی بایگانی جداست: برگه‌ها/فرایندهای مرورگرِ ردیابی‌شده هنگام پایان اجرا با بهترین تلاش بسته می‌شوند، حتی اگر رونوشت/رکورد نشست نگه داشته شود. ## زیرعامل‌های تودرتو به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند -(`maxSpawnDepth: 1`). برای فعال‌کردن یک سطح تودرتویی، `maxSpawnDepth: 2` را تنظیم کنید — **الگوی هماهنگ‌کننده**: اصلی → زیرعامل هماهنگ‌کننده → +(`maxSpawnDepth: 1`). برای فعال کردن یک سطح تودرتویی، `maxSpawnDepth: 2` +را تنظیم کنید — **الگوی هماهنگ‌کننده**: عامل اصلی → زیرعامل هماهنگ‌کننده → زیر-زیرعامل‌های کارگر. ```json5 @@ -289,151 +308,152 @@ x-i18n: ### سطح‌های عمق -| عمق | شکل کلید نشست | نقش | می‌تواند ایجاد کند؟ | -| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | عامل اصلی | همیشه | -| 1 | `agent::subagent:` | زیرعامل (هماهنگ‌کننده وقتی عمق ۲ مجاز باشد) | فقط اگر `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | زیر-زیرعامل (کارگر برگ) | هرگز | +| عمق | شکل کلید نشست | نقش | می‌تواند ایجاد کند؟ | +| --- | ------------------------------------------ | --------------------------------------------- | ----------------------------- | +| 0 | `agent::main` | عامل اصلی | همیشه | +| 1 | `agent::subagent:` | زیرعامل (هماهنگ‌کننده وقتی عمق ۲ مجاز باشد) | فقط اگر `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | زیر-زیرعامل (کارگر برگ) | هرگز | -### زنجیرهٔ اعلان +### زنجیره اعلام -نتایج در زنجیره به بالا جریان می‌یابند: +نتایج در زنجیره به بالا برمی‌گردند: -1. کارگر عمق ۲ پایان می‌یابد → به والد خود (هماهنگ‌کنندهٔ عمق ۱) اعلان می‌کند. -2. هماهنگ‌کنندهٔ عمق ۱ اعلان را دریافت می‌کند، نتایج را ترکیب می‌کند، پایان می‌یابد → به اصلی اعلان می‌کند. -3. عامل اصلی اعلان را دریافت می‌کند و به کاربر تحویل می‌دهد. +1. کارگر عمق ۲ تمام می‌کند → به والد خود اعلام می‌کند (هماهنگ‌کننده عمق ۱). +2. هماهنگ‌کننده عمق ۱ اعلام را دریافت می‌کند، نتایج را ترکیب می‌کند، تمام می‌کند → به اصلی اعلام می‌کند. +3. عامل اصلی اعلام را دریافت می‌کند و به کاربر تحویل می‌دهد. -هر سطح فقط اعلان‌های فرزندان مستقیم خود را می‌بیند. +هر سطح فقط اعلام‌های فرزندان مستقیم خود را می‌بیند. -**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی حول `sessions_list`، -`sessions_history`، `/subagents list` یا دستورهای خواب `exec`، منتظر رویدادهای تکمیل بمانید. +**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی پیرامون `sessions_list`، +`sessions_history`، `/subagents list` یا فرمان‌های خواب `exec`، منتظر رویدادهای تکمیل بمانید. `sessions_list` و `/subagents list` رابطه‌های نشست فرزند را -متمرکز بر کار زنده نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته -برای یک پنجرهٔ کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزندِ فقط-ذخیرهٔ کهنه -پس از پنجرهٔ تازگی‌شان نادیده گرفته می‌شوند. این کار مانع می‌شود فرادادهٔ قدیمی `spawnedBy` / -`parentSessionKey` پس از راه‌اندازی دوباره، فرزندان شبحی را دوباره زنده کند. -اگر رویداد تکمیل فرزند پس از اینکه پاسخ نهایی را فرستاده‌اید برسد، -پیگیری درست همان توکن خاموش دقیق +بر کار زنده متمرکز نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته +برای یک بازه کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزندِ فقط ذخیره‌شده و کهنه +پس از پنجره تازگی خود نادیده گرفته می‌شوند. این کار از زنده شدن دوباره فرزندان شبح‌گونه بر اثر فراداده قدیمی `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` +هر نشست عامل (در هر عمقی) می‌تواند هم‌زمان حداکثر `maxChildrenPerAgent` فرزند فعال داشته باشد (پیش‌فرض `5`). این کار از گسترش مهارنشده -از سوی یک هماهنگ‌کنندهٔ واحد جلوگیری می‌کند. +از یک هماهنگ‌کننده واحد جلوگیری می‌کند. ### توقف آبشاری -توقف یک هماهنگ‌کنندهٔ عمق ۱ به‌طور خودکار همهٔ فرزندان عمق ۲ آن را متوقف می‌کند: +متوقف کردن یک هماهنگ‌کننده عمق ۱ به‌صورت خودکار همه فرزندان عمق ۲ آن را +متوقف می‌کند: -- `/stop` در گفت‌وگوی اصلی همهٔ عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها آبشار می‌شود. -- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و به فرزندان آن آبشار می‌شود. -- `/subagents kill all` همهٔ زیرعامل‌های درخواست‌دهنده را متوقف می‌کند و آبشار می‌شود. +- `/stop` در گفت‌وگوی اصلی همه عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها سرایت می‌کند. +- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و به فرزندان آن سرایت می‌کند. +- `/subagents kill all` همه زیرعامل‌های درخواست‌کننده را متوقف می‌کند و سرایت می‌کند. ## احراز هویت -احراز هویت زیرعامل بر اساس **شناسهٔ عامل** حل می‌شود، نه بر اساس نوع نشست: +احراز هویت زیرعامل بر اساس **شناسه عامل** حل می‌شود، نه بر اساس نوع نشست: - کلید نشست زیرعامل `agent::subagent:` است. -- ذخیرهٔ احراز هویت از `agentDir` آن عامل بارگذاری می‌شود. -- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **جایگزین** ادغام می‌شوند؛ پروفایل‌های عامل در تعارض‌ها پروفایل‌های اصلی را بازنویسی می‌کنند. +- ذخیره‌گاه احراز هویت از `agentDir` آن عامل بارگذاری می‌شود. +- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **پشتیبان** ادغام می‌شوند؛ پروفایل‌های عامل در تعارض‌ها بر پروفایل‌های اصلی اولویت دارند. ادغام افزایشی است، بنابراین پروفایل‌های اصلی همیشه به‌عنوان -جایگزین در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود. +پشتیبان در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود. -## اعلان +## اعلام -زیرعامل‌ها از طریق یک گام اعلان گزارش می‌دهند: +زیرعامل‌ها از طریق یک گام اعلام گزارش می‌دهند: -- گام اعلان داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌دهنده). +- گام اعلام داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌کننده). - اگر زیرعامل دقیقاً `ANNOUNCE_SKIP` پاسخ دهد، چیزی ارسال نمی‌شود. -- اگر آخرین متن دستیار همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلان حتی اگر پیشرفت قابل مشاهدهٔ قبلی وجود داشته باشد سرکوب می‌شود. +- اگر آخرین متن دستیار همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلام حتی اگر پیشرفت قابل مشاهده قبلی وجود داشته باشد سرکوب می‌شود. -تحویل به عمق درخواست‌دهنده وابسته است: +تحویل به عمق درخواست‌کننده بستگی دارد: -- نشست‌های درخواست‌دهندهٔ سطح بالا از یک فراخوانی پیگیری `agent` با تحویل خارجی (`deliver=true`) استفاده می‌کنند. -- نشست‌های زیرعامل درخواست‌دهندهٔ تودرتو یک تزریق پیگیری داخلی (`deliver=false`) دریافت می‌کنند تا هماهنگ‌کننده بتواند نتایج فرزند را در همان نشست ترکیب کند. -- اگر نشست زیرعامل درخواست‌دهندهٔ تودرتو از بین رفته باشد، OpenClaw در صورت وجود، به درخواست‌دهندهٔ آن نشست برمی‌گردد. +- نشست‌های درخواست‌کننده سطح بالا از یک فراخوانی پیگیری `agent` با تحویل بیرونی (`deliver=true`) استفاده می‌کنند. +- نشست‌های زیرعامل درخواست‌کننده تودرتو یک تزریق پیگیری داخلی دریافت می‌کنند (`deliver=false`) تا هماهنگ‌کننده بتواند نتایج فرزند را درون نشست ترکیب کند. +- اگر نشست زیرعامل درخواست‌کننده تودرتو از بین رفته باشد، OpenClaw در صورت وجود به درخواست‌کننده آن نشست برمی‌گردد. -برای نشست‌های درخواست‌دهندهٔ سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا -هر مسیر گفت‌وگو/رشتهٔ مقید و بازنویسی hook را حل می‌کند، سپس -فیلدهای هدف کانالِ جاافتاده را از مسیر ذخیره‌شدهٔ نشست درخواست‌دهنده پر می‌کند. -این کار تکمیل‌ها را در گفت‌وگو/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل +برای نشست‌های درخواست‌کننده سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا +هر مسیر گفت‌وگو/رشته متصل و بازنویسی قلاب را حل می‌کند، سپس +فیلدهای هدف-کانالِ گم‌شده را از مسیر ذخیره‌شده نشست درخواست‌کننده پر می‌کند. +این کار تکمیل‌ها را روی گفت‌وگو/موضوع درست نگه می‌دارد، حتی وقتی مبدأ تکمیل فقط کانال را شناسایی می‌کند. -تجمیع تکمیل فرزند هنگام ساخت یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌دهنده -محدود می‌شود و از نشت خروجی‌های فرزندِ اجرای قبلی کهنه -به اعلان فعلی جلوگیری می‌کند. پاسخ‌های اعلان در صورت وجود در آداپتورهای کانال، -مسیر‌یابی رشته/موضوع را حفظ می‌کنند. +تجمیع تکمیل فرزند هنگام ساختن یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌کننده +محدود می‌شود و از نشت خروجی‌های فرزندِ اجرای قبلیِ کهنه +به اعلام فعلی جلوگیری می‌کند. پاسخ‌های اعلام، وقتی در آداپترهای کانال در دسترس باشند، +مسیریابی رشته/موضوع را حفظ می‌کنند. -### زمینهٔ اعلان +### زمینه اعلام -زمینهٔ اعلان به یک بلوک رویداد داخلی پایدار عادی‌سازی می‌شود: +زمینه اعلام به یک بلوک رویداد داخلی پایدار نرمال‌سازی می‌شود: | فیلد | منبع | -| -------------- | ------------------------------------------------------------------------------------------------------------- | -| منبع | `subagent` یا `cron` | -| شناسه‌های نشست | کلید/شناسهٔ نشست فرزند | -| نوع | نوع اعلان + برچسب وظیفه | -| وضعیت | برگرفته از نتیجهٔ زمان اجرا (`success`، `error`، `timeout` یا `unknown`) — **نه** استنباط‌شده از متن مدل | -| محتوای نتیجه | آخرین متن قابل مشاهدهٔ دستیار، در غیر این صورت آخرین متن پاک‌سازی‌شدهٔ ابزار/toolResult | -| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ دهد و چه زمانی خاموش بماند | +| ------------- | ----------------------------------------------------------------------------------------------------------- | +| منبع | `subagent` یا `cron` | +| شناسه‌های نشست | کلید/شناسه نشست فرزند | +| نوع | نوع اعلام + برچسب کار | +| وضعیت | مشتق‌شده از نتیجه اجرا (`success`، `error`، `timeout` یا `unknown`) — **نه** استنتاج‌شده از متن مدل | +| محتوای نتیجه | آخرین متن قابل مشاهده دستیار، در غیر این صورت آخرین متن ابزار/نتیجه‌ابزار پاک‌سازی‌شده | +| پیگیری | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ داده شود و چه زمانی خاموش بماند | -اجراهای شکست‌خوردهٔ پایانی وضعیت شکست را بدون بازپخش متن پاسخ -گرفته‌شده گزارش می‌کنند. هنگام timeout، اگر فرزند فقط تا فراخوانی‌های ابزار پیش رفته باشد، -اعلان می‌تواند آن تاریخچه را به‌جای بازپخش خروجی خام ابزار، -به یک خلاصهٔ کوتاه از پیشرفت جزئی فشرده کند. +اجراهای ناموفق پایانی، وضعیت شکست را بدون بازپخش متن پاسخ +ثبت‌شده گزارش می‌کنند. در زمان پایان مهلت، اگر فرزند فقط تا فراخوانی ابزارها پیش رفته باشد، اعلام +می‌تواند به‌جای بازپخش خروجی خام ابزار، آن تاریخچه را به یک خلاصه کوتاه از پیشرفت جزئی +فرو بکاهد. ### خط آمار -بار اعلان‌ها در پایان یک خط آمار دارد (حتی وقتی پیچیده شده باشد): +بارهای اعلام یک خط آمار در پایان دارند (حتی وقتی بسته‌بندی شده باشند): -- زمان اجرا (برای مثال `runtime 5m12s`). +- زمان اجرا (مثلاً `runtime 5m12s`). - مصرف توکن (ورودی/خروجی/کل). -- هزینهٔ تخمینی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`). -- `sessionKey`، `sessionId` و مسیر متن نشست تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` واکشی کند یا فایل روی دیسک را بررسی کند. +- هزینه برآوردی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`). +- `sessionKey`، `sessionId` و مسیر رونوشت تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` بگیرد یا فایل روی دیسک را بررسی کند. -فرادادهٔ داخلی فقط برای هماهنگ‌سازی است؛ پاسخ‌های کاربرنما +فراداده داخلی فقط برای هماهنگ‌سازی در نظر گرفته شده است؛ پاسخ‌های کاربرمحور باید با صدای عادی دستیار بازنویسی شوند. ### چرا `sessions_history` ترجیح داده می‌شود `sessions_history` مسیر هماهنگ‌سازی امن‌تری است: -- یادآوری دستیار ابتدا عادی‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ داربست `` / `` حذف می‌شود؛ بلوک‌های بار XML فراخوانی ابزار در متن ساده (``، ``، ``، ``) حذف می‌شوند، از جمله بارهای کوتاه‌شده‌ای که هرگز تمیز بسته نمی‌شوند؛ داربست تنزل‌یافتهٔ فراخوانی/نتیجهٔ ابزار و نشانگرهای زمینهٔ تاریخی حذف می‌شوند؛ توکن‌های کنترل مدلِ نشت‌کرده (`<|assistant|>`، سایر ASCII `<|...|>`، تمام‌عرض `<｜...｜>`) حذف می‌شوند؛ XML فراخوانی ابزار MiniMax ناقص حذف می‌شود. -- متن‌های شبیه اعتبارنامه/توکن پوشانده می‌شوند. +- یادآوری دستیار ابتدا نرمال‌سازی می‌شود: برچسب‌های تفکر حذف می‌شوند؛ چارچوب‌های `` / `` حذف می‌شوند؛ بلوک‌های بار XML فراخوانی ابزار در متن ساده (``، ``، ``، ``) حذف می‌شوند، شامل بارهای کوتاه‌شده‌ای که هرگز تمیز بسته نمی‌شوند؛ چارچوب‌های تنزل‌یافته فراخوانی/نتیجه ابزار و نشانگرهای زمینه تاریخی حذف می‌شوند؛ توکن‌های کنترلی نشت‌کرده مدل (`<|assistant|>`، سایر `<|...|>`های ASCII، `<｜...｜>` تمام‌عرض) حذف می‌شوند؛ XML فراخوانی ابزار بدشکل MiniMax حذف می‌شود. +- متن‌هایی شبیه اعتبارنامه/توکن ویرایش می‌شوند. - بلوک‌های طولانی می‌توانند کوتاه شوند. - تاریخچه‌های بسیار بزرگ می‌توانند ردیف‌های قدیمی‌تر را حذف کنند یا یک ردیف بیش‌ازحد بزرگ را با `[sessions_history omitted: message too large]` جایگزین کنند. -- بررسی متن نشست خام روی دیسک گزینهٔ جایگزین است وقتی به متن نشست کاملِ بایت‌به‌بایت نیاز دارید. +- بررسی رونوشت خام روی دیسک، گزینه پشتیبان وقتی است که به رونوشت کامل و بایت‌به‌بایت نیاز دارید. ## سیاست ابزار -زیرعامل‌ها ابتدا از همان پروفایل و خط لولهٔ سیاست ابزار والد یا -عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت زیرعامل را اعمال می‌کند. +عامل‌های فرعی ابتدا از همان پروفایل و خط لولهٔ سیاست ابزارِ عامل والد یا +عامل هدف استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت عامل فرعی را +اعمال می‌کند. -بدون `tools.profile` محدودکننده، زیرعامل‌ها **همهٔ ابزارها به‌جز -ابزارهای نشست** و ابزارهای سیستم را دریافت می‌کنند: +بدون `tools.profile` محدودکننده، عامل‌های فرعی **همهٔ ابزارها به‌جز +ابزارهای جلسه** و ابزارهای سامانه را دریافت می‌کنند: - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -`sessions_history` در اینجا نیز یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند — -ریزگردان خام متن نشست نیست. +`sessions_history` اینجا نیز یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند؛ +یک dump خام از transcript نیست. -وقتی `maxSpawnDepth >= 2` باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر این -`sessions_spawn`، `subagents`، `sessions_list` و -`sessions_history` را دریافت می‌کنند تا بتوانند فرزندانشان را مدیریت کنند. +وقتی `maxSpawnDepth >= 2` باشد، عامل‌های فرعیِ هماهنگ‌کننده در عمق ۱ علاوه بر آن +`sessions_spawn`، `subagents`، `sessions_list`، و +`sessions_history` را دریافت می‌کنند تا بتوانند فرزندان خود را مدیریت کنند. ### بازنویسی از طریق پیکربندی @@ -459,7 +479,12 @@ x-i18n: } ``` -`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` را شامل نمی‌شود. برای اینکه +عامل‌های فرعیِ دارای پروفایل کدنویسی بتوانند از خودکارسازی مرورگر استفاده کنند، +مرورگر را در مرحلهٔ پروفایل اضافه کنید: ```json5 { @@ -470,44 +495,65 @@ x-i18n: } ``` -وقتی فقط یک عامل باید اتوماسیون مرورگر داشته باشد، از `agents.list[].tools.alsoAllow: ["browser"]` برای همان عامل استفاده کنید. +وقتی فقط یک عامل باید خودکارسازی مرورگر داشته باشد، از +`agents.list[].tools.alsoAllow: ["browser"]` برای همان عامل استفاده کنید. ## هم‌زمانی -زیرعامل‌ها از یک صف اختصاصی درون‌فرایندی استفاده می‌کنند: +عامل‌های فرعی از یک مسیر صف اختصاصی درون‌فرآیندی استفاده می‌کنند: - **نام مسیر:** `subagent` - **هم‌زمانی:** `agents.defaults.subagents.maxConcurrent` (پیش‌فرض `8`) ## زنده‌بودن و بازیابی -OpenClaw نبود `endedAt` را اثبات دائمی زنده‌بودن یک زیرعامل در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجره اجرای کهنه قدیمی‌تر هستند، دیگر در `/subagents list`، خلاصه‌های وضعیت، گیت‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر نشست به‌عنوان فعال/در انتظار شمارش نمی‌شوند. +OpenClaw نبودِ `endedAt` را مدرک دائمی برای زنده بودن یک +عامل فرعی در نظر نمی‌گیرد. اجراهای پایان‌نیافته‌ای که از پنجرهٔ اجرای کهنه +قدیمی‌تر باشند، دیگر در `/subagents list`، خلاصه‌های وضعیت، +دروازه‌گذاری تکمیل فرزندان، و بررسی‌های هم‌زمانی هر جلسه به‌عنوان فعال/در انتظار +شمرده نمی‌شوند. -پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شده پایان‌نیافته و کهنه حذف می‌شوند، مگر اینکه نشست فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. این نشست‌های فرزندی که بر اثر راه‌اندازی مجدد قطع شده‌اند، از طریق جریان بازیابی یتیم زیرعامل همچنان قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر قطع‌شده، یک پیام ازسرگیری مصنوعی ارسال می‌کند. +پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شدهٔ پایان‌نیافتهٔ کهنه حذف می‌شوند مگر اینکه +جلسهٔ فرزند آن‌ها با `abortedLastRun: true` علامت‌گذاری شده باشد. آن +جلسه‌های فرزندِ قطع‌شده در راه‌اندازی مجدد، همچنان از طریق جریان بازیابی یتیمِ عامل فرعی +قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر قطع‌شده، +یک پیام resume مصنوعی ارسال می‌کند. -بازیابی خودکار پس از راه‌اندازی مجدد برای هر نشست فرزند محدود است. اگر همان فرزند زیرعامل بارها در پنجره سریع گیرکردن دوباره برای بازیابی یتیم پذیرفته شود، OpenClaw یک سنگ‌نشان بازیابی روی آن نشست ثبت می‌کند و در راه‌اندازی‌های مجدد بعدی از ازسرگیری خودکار آن جلوگیری می‌کند. برای همگام‌سازی رکورد وظیفه، `openclaw tasks maintenance --apply` را اجرا کنید، یا برای پاک کردن پرچم‌های بازیابی قطع‌شده کهنه روی نشست‌های دارای سنگ‌نشان، `openclaw doctor --fix` را اجرا کنید. +بازیابی خودکار پس از راه‌اندازی مجدد برای هر جلسهٔ فرزند محدود است. اگر همان +فرزندِ عامل فرعی در بازهٔ گیرکردن دوبارهٔ سریع، بارها برای بازیابی یتیم پذیرفته شود، +OpenClaw یک tombstone بازیابی را روی آن جلسه ماندگار می‌کند و +در راه‌اندازی‌های مجدد بعدی، ادامهٔ خودکار آن را متوقف می‌کند. برای سازگار کردن رکورد task، +`openclaw tasks maintenance --apply` را اجرا کنید، یا برای پاک کردن پرچم‌های کهنهٔ بازیابیِ قطع‌شده +روی جلسه‌های tombstone‌شده، `openclaw doctor --fix` را اجرا کنید. -اگر ایجاد زیرعامل با خطای Gateway `PAIRING_REQUIRED` / `scope-upgrade` شکست خورد، پیش از ویرایش وضعیت جفت‌سازی، فراخوان RPC را بررسی کنید. هماهنگی داخلی `sessions_spawn` باید از طریق احراز هویت مستقیم local loopback با توکن/گذرواژه مشترک، با `client.id: "gateway-client"` و `client.mode: "backend"` متصل شود؛ این مسیر به خط مبنای دامنه دستگاه جفت‌شده CLI وابسته نیست. فراخوان‌های راه دور، `deviceIdentity` صریح، مسیرهای صریح توکن دستگاه، و کلاینت‌های مرورگر/Node همچنان برای ارتقای دامنه به تأیید عادی دستگاه نیاز دارند. +اگر ایجاد عامل فرعی با Gateway `PAIRING_REQUIRED` / +`scope-upgrade` شکست خورد، پیش از ویرایش وضعیت pairing، فراخوان RPC را بررسی کنید. +هماهنگی داخلی `sessions_spawn` باید به‌صورت +`client.id: "gateway-client"` با `client.mode: "backend"` از طریق +auth مستقیم با shared-token/password روی local loopback وصل شود؛ آن مسیر به +خط پایهٔ scope دستگاه paired شدهٔ CLI وابسته نیست. فراخوان‌های remote، `deviceIdentity` +صریح، مسیرهای صریح device-token، و کلاینت‌های browser/node همچنان برای ارتقای scope +به تأیید عادی دستگاه نیاز دارند. -## توقف +## متوقف کردن -- ارسال `/stop` در گفت‌وگوی درخواست‌دهنده، نشست درخواست‌دهنده را قطع می‌کند و هر اجرای فعال زیرعامل را که از آن ایجاد شده باشد متوقف می‌کند و این توقف به فرزندان تودرتو نیز سرایت می‌کند. -- `/subagents kill ` یک زیرعامل مشخص را متوقف می‌کند و این توقف به فرزندان آن نیز سرایت می‌کند. +- ارسال `/stop` در گفت‌وگوی درخواست‌کننده، جلسهٔ درخواست‌کننده را قطع می‌کند و هر اجرای فعال عامل فرعیِ ایجادشده از آن را متوقف می‌کند و این توقف به فرزندان تودرتو نیز آبشاری اعمال می‌شود. +- `/subagents kill ` یک عامل فرعی مشخص را متوقف می‌کند و این توقف به فرزندان آن نیز آبشاری اعمال می‌شود. ## محدودیت‌ها -- اعلام زیرعامل **در حد بهترین تلاش** است. اگر Gateway دوباره راه‌اندازی شود، کارهای در انتظار «اعلام بازگشتی» از دست می‌روند. -- زیرعامل‌ها همچنان منابع همان فرایند Gateway را به‌اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک شیر ایمنی در نظر بگیرید. -- `sessions_spawn` همیشه غیرمسدودکننده است: بلافاصله `{ status: "accepted", runId, childSessionKey }` را برمی‌گرداند. -- زمینه زیرعامل فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`). -- بیشینه عمق تودرتوسازی 5 است (بازه `maxSpawnDepth`: 1 تا 5). عمق 2 برای بیشتر موارد استفاده توصیه می‌شود. -- `maxChildrenPerAgent` تعداد فرزندان فعال برای هر نشست را محدود می‌کند (پیش‌فرض `5`، بازه `1–20`). +- اعلام عامل فرعی **بهترین تلاش** است. اگر Gateway دوباره راه‌اندازی شود، کارهای در انتظار «اعلام برگشتی» از دست می‌روند. +- عامل‌های فرعی همچنان همان منابع فرآیند Gateway را به اشتراک می‌گذارند؛ `maxConcurrent` را به‌عنوان یک شیر اطمینان در نظر بگیرید. +- `sessions_spawn` همیشه non-blocking است: بلافاصله `{ status: "accepted", runId, childSessionKey }` را برمی‌گرداند. +- زمینهٔ عامل فرعی فقط `AGENTS.md` + `TOOLS.md` را تزریق می‌کند (بدون `SOUL.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، یا `BOOTSTRAP.md`). +- بیشینهٔ عمق تودرتویی ۵ است (بازهٔ `maxSpawnDepth`: ۱–۵). عمق ۲ برای بیشتر موارد استفاده توصیه می‌شود. +- `maxChildrenPerAgent` تعداد فرزندان فعال برای هر جلسه را محدود می‌کند (پیش‌فرض `5`، بازهٔ `1–20`). ## مرتبط - [عامل‌های ACP](/fa/tools/acp-agents) - [ارسال عامل](/fa/tools/agent-send) -- [وظیفه‌های پس‌زمینه](/fa/automation/tasks) -- [ابزارهای سندباکس چندعاملی](/fa/tools/multi-agent-sandbox-tools) +- [taskهای پس‌زمینه](/fa/automation/tasks) +- [ابزارهای sandbox چندعاملی](/fa/tools/multi-agent-sandbox-tools) diff --git a/docs/fa/web/control-ui.md b/docs/fa/web/control-ui.md index f0318b1ff..ead8b0519 100644 --- a/docs/fa/web/control-ui.md +++ b/docs/fa/web/control-ui.md @@ -1,239 +1,239 @@ --- read_when: - - می‌خواهید Gateway را از طریق یک مرورگر مدیریت کنید + - می‌خواهید Gateway را از طریق مرورگر مدیریت کنید - دسترسی به Tailnet را بدون تونل‌های SSH می‌خواهید sidebarTitle: Control UI -summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (چت، گره‌ها، پیکربندی) +summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (گفتگو، گره‌ها، پیکربندی) title: رابط کاربری کنترل x-i18n: - generated_at: "2026-05-04T02:29:06Z" + generated_at: "2026-05-04T07:08:30Z" model: gpt-5.5 provider: openai - source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e + source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5 source_path: web/control-ui.md workflow: 16 --- -رابط کاربری کنترل یک برنامه تک‌صفحه‌ای کوچک **Vite + Lit** است که توسط Gateway ارائه می‌شود: +رابط کاربری کنترل یک برنامه تک‌صفحه‌ای کوچک با **Vite + Lit** است که توسط Gateway ارائه می‌شود: - پیش‌فرض: `http://:18789/` - پیشوند اختیاری: `gateway.controlUi.basePath` را تنظیم کنید (مثلاً `/openclaw`) -این رابط **مستقیماً با Gateway WebSocket** روی همان پورت ارتباط برقرار می‌کند. +این برنامه **مستقیماً با Gateway WebSocket** روی همان پورت ارتباط برقرار می‌کند. ## باز کردن سریع (محلی) -اگر Gateway روی همان رایانه در حال اجرا است، باز کنید: +اگر Gateway روی همان رایانه در حال اجراست، باز کنید: - [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (یا [http://localhost:18789/](http://localhost:18789/)) اگر صفحه بارگذاری نشد، ابتدا Gateway را راه‌اندازی کنید: `openclaw gateway`. -احراز هویت هنگام دست‌دهی WebSocket از طریق موارد زیر ارائه می‌شود: +احراز هویت هنگام دست‌دهی WebSocket از این طریق ارائه می‌شود: - `connect.params.auth.token` - `connect.params.auth.password` -- سرآیندهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` باشد -- سرآیندهای هویت پراکسی مورد اعتماد وقتی `gateway.auth.mode: "trusted-proxy"` باشد +- هدرهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` باشد +- هدرهای هویت پراکسی مورد اعتماد وقتی `gateway.auth.mode: "trusted-proxy"` باشد -پنل تنظیمات داشبورد یک توکن را برای نشست زبانه فعلی مرورگر و نشانی Gateway انتخاب‌شده نگه می‌دارد؛ گذرواژه‌ها ذخیره نمی‌شوند. راه‌اندازی اولیه معمولاً در اولین اتصال، یک توکن Gateway برای احراز هویت با راز مشترک تولید می‌کند، اما احراز هویت با گذرواژه هم وقتی `gateway.auth.mode` برابر `"password"` باشد کار می‌کند. +پنل تنظیمات داشبورد یک توکن را برای نشست تب فعلی مرورگر و URL انتخاب‌شده Gateway نگه می‌دارد؛ گذرواژه‌ها ذخیره نمی‌شوند. راه‌اندازی اولیه معمولاً در اولین اتصال، یک توکن Gateway برای احراز هویت با راز مشترک تولید می‌کند، اما احراز هویت با گذرواژه نیز وقتی `gateway.auth.mode` برابر `"password"` باشد کار می‌کند. -## جفت‌سازی دستگاه (اتصال نخست) +## جفت‌سازی دستگاه (اولین اتصال) -وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل می‌شوید، Gateway معمولاً به **تأیید جفت‌سازی یک‌باره** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است. +وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل می‌شوید، Gateway معمولاً به **تأیید یک‌باره جفت‌سازی** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است. -**چیزی که می‌بینید:** "disconnected (1008): pairing required" +**چیزی که خواهید دید:** "disconnected (1008): pairing required" - + ```bash openclaw devices list ``` - + ```bash openclaw devices approve ``` -اگر مرورگر با جزئیات احراز هویت تغییرکرده دوباره جفت‌سازی را تلاش کند (نقش/دامنه‌ها/کلید عمومی)، درخواست در انتظار قبلی جایگزین می‌شود و یک `requestId` جدید ساخته می‌شود. پیش از تأیید دوباره `openclaw devices list` را اجرا کنید. +اگر مرورگر جفت‌سازی را با جزئیات احراز هویت تغییرکرده (نقش/دامنه‌ها/کلید عمومی) دوباره امتحان کند، درخواست معلق قبلی جایگزین می‌شود و یک `requestId` جدید ایجاد می‌شود. پیش از تأیید، دوباره `openclaw devices list` را اجرا کنید. -اگر مرورگر از قبل جفت شده باشد و شما دسترسی آن را از خواندن به نوشتن/مدیریت تغییر دهید، این به‌عنوان ارتقای تأیید در نظر گرفته می‌شود، نه اتصال مجدد بی‌صدا. OpenClaw تأیید قبلی را فعال نگه می‌دارد، اتصال مجدد گسترده‌تر را مسدود می‌کند و از شما می‌خواهد مجموعه دامنه جدید را صریحاً تأیید کنید. +اگر مرورگر از قبل جفت شده باشد و آن را از دسترسی خواندن به دسترسی نوشتن/مدیر تغییر دهید، این کار به‌عنوان ارتقای تأیید در نظر گرفته می‌شود، نه اتصال مجدد بی‌صدا. OpenClaw تأیید قبلی را فعال نگه می‌دارد، اتصال مجدد با دامنه گسترده‌تر را مسدود می‌کند و از شما می‌خواهد مجموعه دامنه جدید را صریحاً تأیید کنید. -پس از تأیید، دستگاه به خاطر سپرده می‌شود و دیگر به تأیید دوباره نیاز ندارد مگر اینکه آن را با `openclaw devices revoke --device --role ` لغو کنید. برای چرخش توکن و لغو، [CLI دستگاه‌ها](/fa/cli/devices) را ببینید. +پس از تأیید، دستگاه به خاطر سپرده می‌شود و تا زمانی که آن را با `openclaw devices revoke --device --role ` لغو نکنید، به تأیید دوباره نیاز ندارد. برای چرخش و لغو توکن، [CLI دستگاه‌ها](/fa/cli/devices) را ببینید. -- اتصال‌های مستقیم مرورگر از طریق local loopback (`127.0.0.1` / `localhost`) به‌طور خودکار تأیید می‌شوند. -- وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود، و مرورگر هویت دستگاه خود را ارائه کند، Tailscale Serve می‌تواند رفت‌وبرگشت جفت‌سازی را برای نشست‌های اپراتور رابط کاربری کنترل رد کند. +- اتصال‌های مستقیم مرورگر با local loopback (`127.0.0.1` / `localhost`) به‌طور خودکار تأیید می‌شوند. +- Tailscale Serve می‌تواند رفت‌وبرگشت جفت‌سازی را برای نشست‌های اپراتور رابط کاربری کنترل رد کند، وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود و مرورگر هویت دستگاه خود را ارائه کند. - اتصال‌های مستقیم Tailnet، اتصال‌های مرورگر در LAN، و پروفایل‌های مرورگر بدون هویت دستگاه همچنان به تأیید صریح نیاز دارند. -- هر پروفایل مرورگر یک شناسه دستگاه یکتا تولید می‌کند، بنابراین تغییر مرورگر یا پاک کردن داده‌های مرورگر به جفت‌سازی دوباره نیاز خواهد داشت. +- هر پروفایل مرورگر یک شناسه دستگاه یکتا تولید می‌کند، بنابراین تغییر مرورگر یا پاک کردن داده‌های مرورگر نیازمند جفت‌سازی دوباره خواهد بود. ## هویت شخصی (محلی مرورگر) -رابط کاربری کنترل از یک هویت شخصی به‌ازای هر مرورگر پشتیبانی می‌کند (نام نمایشی و آواتار) که برای انتساب در نشست‌های مشترک به پیام‌های خروجی پیوست می‌شود. این هویت در فضای ذخیره‌سازی مرورگر قرار دارد، به پروفایل مرورگر فعلی محدود است، و به دستگاه‌های دیگر همگام‌سازی نمی‌شود یا فراتر از فراداده معمول نویسندگی رونوشت برای پیام‌هایی که واقعاً ارسال می‌کنید، در سمت سرور ماندگار نمی‌شود. پاک کردن داده‌های سایت یا تغییر مرورگر آن را دوباره خالی می‌کند. +رابط کاربری کنترل از یک هویت شخصی برای هر مرورگر پشتیبانی می‌کند (نام نمایشی و آواتار) که برای انتساب در نشست‌های مشترک به پیام‌های خروجی پیوست می‌شود. این هویت در فضای ذخیره‌سازی مرورگر قرار دارد، به پروفایل مرورگر فعلی محدود است، و فراتر از فراداده معمول نویسندگی رونوشت پیام‌هایی که واقعاً ارسال می‌کنید، با دستگاه‌های دیگر همگام‌سازی یا در سمت سرور ماندگار نمی‌شود. پاک کردن داده‌های سایت یا تغییر مرورگر آن را به حالت خالی بازمی‌گرداند. -همین الگوی محلی مرورگر برای بازنویسی آواتار دستیار هم اعمال می‌شود. آواتارهای بارگذاری‌شده دستیار فقط در مرورگر محلی روی هویت حل‌شده توسط Gateway قرار می‌گیرند و هرگز از مسیر `config.patch` رفت‌وبرگشت نمی‌کنند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینت‌های غیر UI که مستقیماً این فیلد را می‌نویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی). +همین الگوی محلی مرورگر برای جایگزینی آواتار دستیار نیز اعمال می‌شود. آواتارهای بارگذاری‌شده دستیار فقط در مرورگر محلی روی هویت حل‌شده توسط Gateway قرار می‌گیرند و هرگز از طریق `config.patch` رفت‌وبرگشت نمی‌شوند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینت‌های غیر UI که فیلد را مستقیماً می‌نویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی). ## نقطه پایانی پیکربندی زمان اجرا -رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت می‌کند. آن نقطه پایانی با همان احراز هویت Gateway مانند بقیه سطح HTTP محافظت می‌شود: مرورگرهای احراز هویت‌نشده نمی‌توانند آن را دریافت کنند، و دریافت موفق به یک توکن/گذرواژه معتبر Gateway از قبل موجود، هویت Tailscale Serve، یا هویت پراکسی مورد اعتماد نیاز دارد. +رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت می‌کند. این نقطه پایانی با همان احراز هویت Gateway که برای بقیه سطح HTTP استفاده می‌شود محافظت می‌شود: مرورگرهای احراز هویت‌نشده نمی‌توانند آن را دریافت کنند، و دریافت موفق به یکی از این موارد نیاز دارد: توکن/گذرواژه Gateway که از قبل معتبر است، هویت Tailscale Serve، یا هویت پراکسی مورد اعتماد. ## پشتیبانی زبان -رابط کاربری کنترل می‌تواند در اولین بارگذاری بر اساس زبان مرورگر شما خود را بومی‌سازی کند. برای بازنویسی آن در آینده، **Overview -> Gateway Access -> Language** را باز کنید. انتخابگر زبان در کارت Gateway Access قرار دارد، نه زیر Appearance. +رابط کاربری کنترل می‌تواند در اولین بارگذاری بر اساس زبان مرورگر شما محلی‌سازی شود. برای بازنویسی آن در آینده، **Overview -> Gateway Access -> Language** را باز کنید. انتخابگر زبان در کارت Gateway Access قرار دارد، نه زیر Appearance. - زبان‌های پشتیبانی‌شده: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` - ترجمه‌های غیرانگلیسی در مرورگر به‌صورت تنبل بارگذاری می‌شوند. - زبان انتخاب‌شده در فضای ذخیره‌سازی مرورگر ذخیره می‌شود و در بازدیدهای آینده دوباره استفاده می‌شود. -- کلیدهای ترجمه موجودنباشد به انگلیسی برمی‌گردند. +- کلیدهای ترجمه گمشده به انگلیسی بازمی‌گردند. -ترجمه‌های مستندات برای همان مجموعه زبان‌های غیرانگلیسی تولید می‌شوند، اما انتخابگر زبان داخلی سایت مستندات Mintlify به کدهای زبانی محدود است که Mintlify می‌پذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید می‌شوند؛ ممکن است تا زمانی که Mintlify از این کدها پشتیبانی نکند در آن انتخابگر ظاهر نشوند. +ترجمه‌های مستندات برای همان مجموعه زبان‌های غیرانگلیسی تولید می‌شوند، اما انتخابگر زبان داخلی سایت مستندات در Mintlify به کدهای زبانی محدود است که Mintlify می‌پذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید می‌شوند؛ ممکن است تا زمانی که Mintlify از این کدها پشتیبانی کند در آن انتخابگر ظاهر نشوند. -## تم‌های ظاهری +## تم‌های ظاهر -پنل Appearance تم‌های داخلی Claw، Knot و Dash را به‌همراه یک جایگاه واردسازی tweakcn محلی مرورگر نگه می‌دارد. برای وارد کردن یک تم، [تم‌های tweakcn](https://tweakcn.com/themes) را باز کنید، یک تم انتخاب کنید یا بسازید، روی **Share** کلیک کنید و پیوند تم کپی‌شده را در Appearance بچسبانید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/`، شناسه‌های خام تم، و نام‌های تم پیش‌فرض مانند `amethyst-haze` را می‌پذیرد. +پنل Appearance تم‌های داخلی Claw، Knot و Dash، به‌علاوه یک جایگاه واردسازی tweakcn محلی مرورگر را نگه می‌دارد. برای وارد کردن یک تم، [ویرایشگر tweakcn](https://tweakcn.com/editor/theme) را باز کنید، یک تم را انتخاب یا ایجاد کنید، روی **Share** کلیک کنید، و پیوند تم کپی‌شده را در Appearance جای‌گذاری کنید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/`، شناسه‌های خام تم، و نام‌های تم پیش‌فرض مانند `amethyst-haze` را می‌پذیرد. -تم‌های واردشده فقط در پروفایل مرورگر فعلی ذخیره می‌شوند. آن‌ها در پیکربندی Gateway نوشته نمی‌شوند و بین دستگاه‌ها همگام‌سازی نمی‌شوند. جایگزین کردن تم واردشده همان یک جایگاه محلی را به‌روزرسانی می‌کند؛ پاک کردن آن اگر تم واردشده انتخاب شده باشد، تم فعال را به Claw برمی‌گرداند. +تم‌های واردشده فقط در پروفایل مرورگر فعلی ذخیره می‌شوند. آن‌ها در پیکربندی Gateway نوشته نمی‌شوند و بین دستگاه‌ها همگام‌سازی نمی‌شوند. جایگزین کردن تم واردشده همان یک جایگاه محلی را به‌روزرسانی می‌کند؛ پاک کردن آن، اگر تم واردشده انتخاب شده باشد، تم فعال را به Claw برمی‌گرداند. ## کارهایی که می‌تواند انجام دهد (امروز) - - - گفت‌وگو با مدل از طریق Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - گفت‌وگو از طریق نشست‌های بی‌درنگ مرورگر. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن محدود یک‌بارمصرف مرورگر روی WebSocket استفاده می‌کند، و Pluginهای صوتی بی‌درنگ فقط بک‌اند از انتقال رله Gateway استفاده می‌کنند. رله اطلاعات اعتبار ارائه‌دهنده را روی Gateway نگه می‌دارد، در حالی که مرورگر PCM میکروفون را از طریق RPCهای `talk.realtime.relay*` پخش می‌کند و فراخوانی‌های ابزار `openclaw_agent_consult` را از طریق `chat.send` به مدل OpenClaw بزرگ‌تر پیکربندی‌شده برمی‌گرداند. - - پخش فراخوانی‌های ابزار + کارت‌های خروجی زنده ابزار در چت (رویدادهای عامل). + + - از طریق Gateway WS با مدل چت کنید (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). + - از طریق نشست‌های بی‌درنگ مرورگر صحبت کنید. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن مرورگر یک‌بارمصرف محدود روی WebSocket استفاده می‌کند، و Pluginهای صوتی بی‌درنگ فقط-بک‌اند از انتقال رله Gateway استفاده می‌کنند. رله اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد، در حالی که مرورگر PCM میکروفن را از طریق RPCهای `talk.realtime.relay*` پخش می‌کند و فراخوانی‌های ابزار `openclaw_agent_consult` را برای مدل بزرگ‌تر پیکربندی‌شده OpenClaw از طریق `chat.send` برمی‌گرداند. + - فراخوانی‌های ابزار + کارت‌های خروجی زنده ابزار را در Chat پخش کنید (رویدادهای عامل). - - - کانال‌ها: داخلی به‌علاوه وضعیت کانال‌های Plugin بسته‌بندی‌شده/خارجی، ورود QR، و پیکربندی به‌ازای هر کانال (`channels.status`, `web.login.*`, `config.patch`). - - نمونه‌ها: فهرست حضور + تازه‌سازی (`system-presence`). - - نشست‌ها: فهرست + بازنویسی‌های مدل/تفکر/سریع/پرحرف/ردیابی/استدلال به‌ازای هر نشست (`sessions.list`, `sessions.patch`). - - رویاها: وضعیت dreaming، کلید فعال/غیرفعال، و خواننده دفترچه Dream (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + + - کانال‌ها: داخلی به‌علاوه وضعیت کانال‌های Plugin بسته‌بندی‌شده/خارجی، ورود QR، و پیکربندی برای هر کانال (`channels.status`, `web.login.*`, `config.patch`). + - نمونه‌ها: فهرست حضور + بازخوانی (`system-presence`). + - نشست‌ها: فهرست + بازنویسی‌های مدل/تفکر/سریع/پرحرف/ردیابی/استدلال برای هر نشست (`sessions.list`, `sessions.patch`). + - رویاها: وضعیت Dreaming، کلید فعال/غیرفعال، و خواننده دفترچه رویا (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - - کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال‌سازی/غیرفعال‌سازی + تاریخچه اجرا (`cron.*`). + + - کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال/غیرفعال + تاریخچه اجرا (`cron.*`). - Skills: وضعیت، فعال/غیرفعال، نصب، به‌روزرسانی‌های کلید API (`skills.*`). - - Nodeها: فهرست + قابلیت‌ها (`node.list`). - - تأییدهای اجرا: ویرایش فهرست‌های مجاز Gateway یا Node + سیاست درخواست برای `exec host=gateway/node` (`exec.approvals.*`). + - گره‌ها: فهرست + قابلیت‌ها (`node.list`). + - تأییدهای اجرا: ویرایش فهرست‌های مجاز Gateway یا گره + سیاست پرسش برای `exec host=gateway/node` (`exec.approvals.*`). - + - مشاهده/ویرایش `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - اعمال + راه‌اندازی مجدد همراه با اعتبارسنجی (`config.apply`) و بیدار کردن آخرین نشست فعال. - - نوشتن‌ها شامل یک محافظ هش پایه برای جلوگیری از بازنویسی و از بین بردن ویرایش‌های هم‌زمان است. - - نوشتن‌ها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، تفکیک SecretRefهای فعال را برای ارجاع‌های موجود در بار پیکربندی ارسالی بررسی می‌کنند؛ ارجاع‌های فعال ارسالی که قابل تفکیک نباشند پیش از نوشتن رد می‌شوند. - - رندر طرح‌واره + فرم (`config.schema` / `config.schema.lookup`، شامل `title` / `description` فیلد، راهنمایی‌های UI منطبق، خلاصه‌های فرزند بلافاصله، فراداده مستندات روی گره‌های شیء تو‌در‌تو/وایلدکارت/آرایه/ترکیب، به‌علاوه طرح‌واره‌های Plugin + کانال در صورت موجود بودن)؛ ویرایشگر Raw JSON فقط وقتی در دسترس است که عکس‌برداری یک رفت‌وبرگشت خام امن داشته باشد. - - اگر یک عکس‌برداری نتواند متن خام را با ایمنی رفت‌وبرگشت کند، رابط کاربری کنترل حالت Form را اجباری می‌کند و حالت Raw را برای آن عکس‌برداری غیرفعال می‌کند. - - گزینه "Reset to saved" در ویرایشگر Raw JSON شکل نوشته‌شده خام را حفظ می‌کند (قالب‌بندی، نظرها، چیدمان `$include`) به‌جای اینکه یک عکس‌برداری تخت‌شده را دوباره رندر کند، بنابراین ویرایش‌های خارجی وقتی عکس‌برداری بتواند با ایمنی رفت‌وبرگشت کند پس از بازنشانی باقی می‌مانند. - - مقدارهای شیء ساختاریافته SecretRef در ورودی‌های متنی فرم فقط‌خواندنی رندر می‌شوند تا از خراب‌شدن تصادفی شیء به رشته جلوگیری شود. + - نوشتن‌ها شامل محافظ هش پایه برای جلوگیری از بازنویسی ناخواسته ویرایش‌های هم‌زمان هستند. + - نوشتن‌ها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، حل SecretRef فعال را برای ارجاع‌های موجود در بار پیکربندی ارسال‌شده بررسی می‌کنند؛ ارجاع‌های فعال ارسال‌شده که حل‌نشده باشند پیش از نوشتن رد می‌شوند. + - طرح‌واره + رندر فرم (`config.schema` / `config.schema.lookup`، شامل فیلد `title` / `description`، راهنمایی‌های UI منطبق، خلاصه‌های فرزند مستقیم، فراداده مستندات روی گره‌های تو در توی شیء/وایلدکارت/آرایه/ترکیب، به‌علاوه طرح‌واره‌های Plugin + کانال وقتی در دسترس باشند)؛ ویرایشگر JSON خام فقط وقتی در دسترس است که نماگرفت یک رفت‌وبرگشت خام ایمن داشته باشد. + - اگر یک نماگرفت نتواند متن خام را به‌طور ایمن رفت‌وبرگشت کند، رابط کاربری کنترل حالت Form را اجباری می‌کند و حالت Raw را برای آن نماگرفت غیرفعال می‌کند. + - گزینه "Reset to saved" در ویرایشگر JSON خام، شکل نوشته‌شده خام را حفظ می‌کند (قالب‌بندی، دیدگاه‌ها، چیدمان `$include`) به‌جای اینکه یک نماگرفت تخت‌شده را دوباره رندر کند، بنابراین وقتی نماگرفت بتواند به‌طور ایمن رفت‌وبرگشت کند، ویرایش‌های خارجی پس از بازنشانی باقی می‌مانند. + - مقادیر شیء ساختاریافته SecretRef در ورودی‌های متنی فرم فقط-خواندنی رندر می‌شوند تا از خراب شدن تصادفی شیء به رشته جلوگیری شود. - - - اشکال‌زدایی: عکس‌برداری‌های وضعیت/سلامت/مدل‌ها + گزارش رویداد + فراخوانی‌های دستی RPC (`status`, `health`, `models.list`). - - گزارش‌ها: دنبال‌کردن زنده گزارش‌های فایل Gateway همراه با فیلتر/صدور (`logs.tail`). - - به‌روزرسانی: اجرای به‌روزرسانی بسته/git + راه‌اندازی مجدد (`update.run`) همراه با گزارش راه‌اندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال مجدد برای تأیید نسخه Gateway در حال اجرا. + + - اشکال‌زدایی: نماگرفت‌های وضعیت/سلامت/مدل‌ها + گزارش رویداد + فراخوانی‌های دستی RPC (`status`, `health`, `models.list`). + - گزارش‌ها: دنبال‌کردن زنده گزارش‌های فایل Gateway با فیلتر/خروجی‌گیری (`logs.tail`). + - به‌روزرسانی: اجرای به‌روزرسانی بسته/git + راه‌اندازی مجدد (`update.run`) همراه با گزارش راه‌اندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال دوباره برای تأیید نسخه Gateway در حال اجرا. - - - برای کارهای ایزوله، تحویل به‌طور پیش‌فرض اعلام خلاصه است. اگر اجراهای فقط داخلی می‌خواهید می‌توانید آن را به none تغییر دهید. - - وقتی announce انتخاب شده باشد، فیلدهای کانال/هدف ظاهر می‌شوند. - - حالت Webhook از `delivery.mode = "webhook"` استفاده می‌کند و `delivery.to` روی یک URL معتبر HTTP(S) Webhook تنظیم می‌شود. - - برای کارهای نشست اصلی، حالت‌های تحویل webhook و none در دسترس هستند. - - کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینه‌های exact/stagger برای cron، بازنویسی‌های مدل/تفکر عامل، و کلیدهای تحویل best-effort هستند. - - اعتبارسنجی فرم به‌صورت درون‌خطی همراه با خطاهای سطح فیلد است؛ مقدارهای نامعتبر دکمه ذخیره را تا زمان اصلاح غیرفعال می‌کنند. - - `cron.webhookToken` را تنظیم کنید تا یک توکن bearer اختصاصی ارسال شود؛ اگر حذف شود Webhook بدون سرآیند احراز هویت ارسال می‌شود. - - جایگزین منسوخ: کارهای قدیمی ذخیره‌شده با `notify: true` همچنان تا زمان مهاجرت می‌توانند از `cron.webhook` استفاده کنند. + + - برای کارهای ایزوله، تحویل به‌طور پیش‌فرض روی اعلام خلاصه است. اگر اجراهای فقط داخلی می‌خواهید، می‌توانید آن را به هیچ تغییر دهید. + - وقتی اعلام انتخاب شود، فیلدهای کانال/هدف ظاهر می‌شوند. + - حالت Webhook از `delivery.mode = "webhook"` با `delivery.to` تنظیم‌شده روی یک URL معتبر Webhook با HTTP(S) استفاده می‌کند. + - برای کارهای نشست اصلی، حالت‌های تحویل Webhook و هیچ در دسترس هستند. + - کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینه‌های دقیق/پراکنده Cron، بازنویسی‌های مدل/تفکر عامل، و کلیدهای تحویل با بهترین تلاش هستند. + - اعتبارسنجی فرم به‌صورت درون‌خطی با خطاهای سطح فیلد انجام می‌شود؛ مقادیر نامعتبر تا زمان اصلاح، دکمه ذخیره را غیرفعال می‌کنند. + - برای ارسال یک توکن حامل اختصاصی، `cron.webhookToken` را تنظیم کنید؛ اگر حذف شود، Webhook بدون هدر احراز هویت ارسال می‌شود. + - جایگزین منسوخ: کارهای قدیمی ذخیره‌شده با `notify: true` همچنان می‌توانند تا زمان مهاجرت از `cron.webhook` استفاده کنند. -## رفتار چت +## رفتار Chat - - `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تأیید می‌کند و پاسخ از طریق رویدادهای `chat` پخش می‌شود. - - بارگذاری‌های چت تصویرها و فایل‌های غیر ویدیویی را می‌پذیرد. تصویرها مسیر تصویر بومی را حفظ می‌کنند؛ فایل‌های دیگر به‌عنوان رسانه مدیریت‌شده ذخیره می‌شوند و در تاریخچه به‌صورت لینک‌های پیوست نمایش داده می‌شوند. - - ارسال دوباره با همان `idempotencyKey` هنگام اجرا `{ status: "in_flight" }` و پس از تکمیل `{ status: "ok" }` را برمی‌گرداند. - - پاسخ‌های `chat.history` برای ایمنی UI از نظر اندازه محدود می‌شوند. وقتی ورودی‌های رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوک‌های فراداده سنگین را حذف کند، و پیام‌های بیش از حد بزرگ را با یک جای‌نگهدار (`[chat.history omitted: message too large]`) جایگزین کند. - - تصویرهای دستیار/تولیدشده به‌صورت ارجاع‌های رسانه مدیریت‌شده پایدار می‌شوند و از طریق URLهای رسانه احرازهویت‌شده Gateway دوباره ارائه می‌شوند، بنابراین بارگذاری‌های مجدد به ماندن بارهای تصویر base64 خام در پاسخ تاریخچه چت وابسته نیستند. - - `chat.history` همچنین برچسب‌های دستور درون‌خطی فقط‌نمایشی را از متن قابل‌مشاهده دستیار حذف می‌کند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، بارهای XML فراخوانی ابزار به‌صورت متن ساده (شامل `...`، `...`، `...`، `...`، و بلوک‌های فراخوانی ابزار کوتاه‌شده)، و توکن‌های کنترل مدل ASCII/تمام‌عرض نشت‌کرده را حذف می‌کند، و ورودی‌های دستیار را که کل متن قابل‌مشاهده آن‌ها فقط توکن خاموش دقیق `NO_REPLY` / `no_reply` است کنار می‌گذارد. - - هنگام یک ارسال فعال و تازه‌سازی نهایی تاریخچه، اگر `chat.history` برای مدت کوتاهی یک اسنپ‌شات قدیمی‌تر برگرداند، نمای چت پیام‌های خوش‌بینانه محلی کاربر/دستیار را قابل‌مشاهده نگه می‌دارد؛ رونوشت مرجع پس از همگام شدن تاریخچه Gateway آن پیام‌های محلی را جایگزین می‌کند. - - رویدادهای زنده `chat` وضعیت تحویل هستند، در حالی که `chat.history` از رونوشت پایدار نشست دوباره ساخته می‌شود. پس از رویدادهای نهایی ابزار، Control UI تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنباله خوش‌بینانه کوچک را ادغام می‌کند؛ مرز رونوشت در [WebChat](/fa/web/webchat) مستند شده است. + - `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تأیید می‌کند و پاسخ از طریق رویدادهای `chat` جریان می‌یابد. + - بارگذاری‌های چت تصویرها را همراه با فایل‌های غیر ویدیویی می‌پذیرند. تصویرها مسیر تصویر بومی را حفظ می‌کنند؛ فایل‌های دیگر به‌عنوان رسانهٔ مدیریت‌شده ذخیره می‌شوند و در تاریخچه به‌صورت لینک‌های پیوست نمایش داده می‌شوند. + - ارسال دوباره با همان `idempotencyKey` در زمان اجرا `{ status: "in_flight" }` و پس از تکمیل `{ status: "ok" }` را برمی‌گرداند. + - پاسخ‌های `chat.history` برای ایمنی UI از نظر اندازه محدود هستند. وقتی ورودی‌های رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوک‌های فرادادهٔ سنگین را حذف کند، و پیام‌های بیش‌ازحد بزرگ را با یک جانگهدار (`[chat.history omitted: message too large]`) جایگزین کند. + - تصویرهای دستیار/تولیدشده به‌صورت ارجاع‌های رسانهٔ مدیریت‌شده پایدار می‌شوند و از طریق URLهای رسانهٔ احرازهویت‌شدهٔ Gateway دوباره ارائه می‌شوند، بنابراین بارگذاری‌های مجدد به باقی‌ماندن payloadهای خام تصویر base64 در پاسخ تاریخچهٔ چت وابسته نیستند. + - `chat.history` همچنین برچسب‌های دستور درون‌خطیِ صرفاً نمایشی را از متن قابل‌مشاهدهٔ دستیار حذف می‌کند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، payloadهای XML فراخوانی ابزار در متن ساده (از جمله `...`، `...`، `...`، `...`، و بلوک‌های کوتاه‌شدهٔ فراخوانی ابزار)، و توکن‌های کنترل مدل ASCII/تمام‌عرضِ نشت‌کرده را حذف می‌کند، و ورودی‌های دستیار را که کل متن قابل‌مشاهدهٔ آن‌ها فقط توکن سکوت دقیق `NO_REPLY` / `no_reply` است کنار می‌گذارد. + - در طول یک ارسال فعال و تازه‌سازی نهایی تاریخچه، اگر `chat.history` برای لحظه‌ای یک snapshot قدیمی‌تر برگرداند، نمای چت پیام‌های خوش‌بینانهٔ محلی کاربر/دستیار را قابل‌مشاهده نگه می‌دارد؛ وقتی تاریخچهٔ Gateway به‌روز شد، رونوشت رسمی جای آن پیام‌های محلی را می‌گیرد. + - رویدادهای زندهٔ `chat` وضعیت تحویل هستند، در حالی که `chat.history` از رونوشت پایدار نشست بازسازی می‌شود. پس از رویدادهای نهایی ابزار، Control UI تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنبالهٔ خوش‌بینانهٔ کوچک را ادغام می‌کند؛ مرز رونوشت در [WebChat](/fa/web/webchat) مستند شده است. - `chat.inject` یک یادداشت دستیار را به رونوشت نشست اضافه می‌کند و یک رویداد `chat` را برای به‌روزرسانی‌های فقط UI پخش می‌کند (بدون اجرای عامل، بدون تحویل کانال). - - انتخابگرهای مدل و تفکر در سرآیند چت، نشست فعال را بلافاصله از طریق `sessions.patch` وصله می‌کنند؛ آن‌ها بازنویسی‌های پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت. - - تایپ `/new` در Control UI همان نشست داشبورد تازه New Chat را ایجاد می‌کند و به آن جابه‌جا می‌شود. تایپ `/reset` بازنشانی صریح درجا Gateway را برای نشست فعلی نگه می‌دارد. - - انتخابگر مدل چت نمای مدل پیکربندی‌شده Gateway را درخواست می‌کند. اگر `agents.defaults.models` وجود داشته باشد، همان فهرست مجاز انتخابگر را هدایت می‌کند. در غیر این صورت انتخابگر ورودی‌های صریح `models.providers.*.models` را به‌همراه ارائه‌دهندگانی که احراز هویت قابل‌استفاده دارند نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی `models.list` با `view: "all"` همچنان در دسترس می‌ماند. - - وقتی گزارش‌های استفاده نشست تازه Gateway فشار بالای زمینه را نشان دهند، ناحیه نوشتن چت یک اعلان زمینه نشان می‌دهد و، در سطح‌های پیشنهادی Compaction، یک دکمه فشرده که مسیر عادی Compaction نشست را اجرا می‌کند. اسنپ‌شات‌های توکن کهنه تا زمانی که Gateway دوباره استفاده تازه را گزارش کند پنهان می‌شوند. + - انتخابگرهای مدل و تفکر در سربرگ چت، نشست فعال را بلافاصله از طریق `sessions.patch` وصله می‌کنند؛ آن‌ها overrideهای پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت. + - تایپ `/new` در Control UI همان نشست تازهٔ داشبورد را مثل New Chat ایجاد کرده و به آن جابه‌جا می‌شود. تایپ `/reset` ریست صریح درجا برای نشست فعلی Gateway را حفظ می‌کند. + - انتخابگر مدل چت نمای مدل پیکربندی‌شدهٔ Gateway را درخواست می‌کند. اگر `agents.defaults.models` وجود داشته باشد، همان allowlist انتخابگر را هدایت می‌کند. در غیر این صورت انتخابگر ورودی‌های صریح `models.providers.*.models` را به‌همراه providerهایی که auth قابل‌استفاده دارند نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی `models.list` با `view: "all"` در دسترس می‌ماند. + - وقتی گزارش‌های تازهٔ مصرف نشست Gateway فشار بالای context را نشان دهند، ناحیهٔ composer چت یک اعلان context نشان می‌دهد و در سطح‌های پیشنهادی Compaction، دکمه‌ای فشرده که مسیر معمول Compaction نشست را اجرا می‌کند. snapshotهای قدیمی توکن تا زمانی که Gateway دوباره مصرف تازه را گزارش کند پنهان می‌شوند. - - حالت گفت‌وگو از یک ارائه‌دهنده صوتی بی‌درنگ ثبت‌شده استفاده می‌کند. OpenAI را با `talk.provider: "openai"` به‌همراه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` به‌همراه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی ارائه‌دهنده بی‌درنگ Voice Call همچنان می‌تواند به‌عنوان جایگزین دوباره استفاده شود. مرورگر هرگز یک کلید API استاندارد ارائه‌دهنده را دریافت نمی‌کند. OpenAI یک راز کلاینت Realtime موقت برای WebRTC دریافت می‌کند. Google Live یک توکن احراز هویت Live API محدود و یک‌بارمصرف برای یک نشست WebSocket مرورگر دریافت می‌کند که دستورالعمل‌ها و اعلان‌های ابزار توسط Gateway در توکن قفل شده‌اند. ارائه‌دهندگانی که فقط یک پل بی‌درنگ بک‌اند ارائه می‌کنند از طریق انتقال رله Gateway اجرا می‌شوند، بنابراین اعتبارنامه‌ها و سوکت‌های فروشنده سمت سرور می‌مانند در حالی که صدای مرورگر از طریق RPCهای احرازهویت‌شده Gateway جابه‌جا می‌شود. پرامپت نشست Realtime توسط Gateway مونتاژ می‌شود؛ `talk.realtime.session` بازنویسی دستورالعمل ارائه‌شده توسط فراخواننده را نمی‌پذیرد. + + حالت گفت‌وگو از یک provider صدای بلادرنگ ثبت‌شده استفاده می‌کند. OpenAI را با `talk.provider: "openai"` به‌همراه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` به‌همراه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی provider بلادرنگ Voice Call همچنان می‌تواند به‌عنوان fallback دوباره استفاده شود. مرورگر هرگز یک کلید API استاندارد provider دریافت نمی‌کند. OpenAI یک secret موقت Realtime client برای WebRTC دریافت می‌کند. Google Live یک توکن auth محدود و یک‌بارمصرف Live API برای نشست WebSocket مرورگر دریافت می‌کند، با دستورالعمل‌ها و اعلان‌های ابزار که توسط Gateway داخل توکن قفل شده‌اند. providerهایی که فقط یک پل بلادرنگ backend ارائه می‌کنند از طریق انتقال relay در Gateway اجرا می‌شوند، بنابراین credentialها و socketهای فروشنده سمت سرور می‌مانند، در حالی که صدای مرورگر از طریق RPCهای احرازهویت‌شدهٔ Gateway جابه‌جا می‌شود. prompt نشست Realtime توسط Gateway مونتاژ می‌شود؛ `talk.realtime.session` overrideهای دستورالعملِ ارائه‌شده توسط caller را نمی‌پذیرد. - در سازنده چت، کنترل گفت‌وگو دکمه موج‌ها کنار دکمه دیکته میکروفون است. وقتی گفت‌وگو شروع می‌شود، ردیف وضعیت سازنده ابتدا `Connecting Talk...` را نشان می‌دهد، سپس وقتی صدا متصل است `Talk live`، یا وقتی یک فراخوانی ابزار بی‌درنگ از طریق `chat.send` در حال مشورت با مدل بزرگ‌تر پیکربندی‌شده است `Asking OpenClaw...` را نشان می‌دهد. + در composer چت، کنترل Talk دکمهٔ موج‌ها کنار دکمهٔ دیکتهٔ میکروفون است. وقتی Talk شروع می‌شود، ردیف وضعیت composer ابتدا `Connecting Talk...`، سپس هنگام اتصال صدا `Talk live`، یا هنگام مشورت یک فراخوانی ابزار بلادرنگ با مدل بزرگ‌تر پیکربندی‌شده از طریق `chat.send`، `Asking OpenClaw...` را نشان می‌دهد. - دودآزمون زنده نگه‌دارنده: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مرورگر WebRTC برای OpenAI، راه‌اندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر رله Gateway با رسانه میکروفون جعلی را راستی‌آزمایی می‌کند. فرمان فقط وضعیت ارائه‌دهنده را چاپ می‌کند و رازها را ثبت نمی‌کند. + smoke زندهٔ maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مربوط به WebRTC مرورگر OpenAI، راه‌اندازی WebSocket مرورگر Google Live با توکن محدود، و adapter مرورگر relay Gateway با رسانهٔ میکروفون جعلی را تأیید می‌کند. این دستور فقط وضعیت provider را چاپ می‌کند و secretها را log نمی‌کند. - روی **توقف** کلیک کنید (`chat.abort` را فراخوانی می‌کند). - - وقتی یک اجرا فعال است، پیگیری‌های عادی در صف قرار می‌گیرند. روی **هدایت** در یک پیام صف‌شده کلیک کنید تا آن پیگیری در نوبت در حال اجرا تزریق شود. - - برای لغو خارج از باند، `/stop` را تایپ کنید (یا عبارت‌های مستقل لغو مانند `stop`، `stop action`، `stop run`، `stop openclaw`، `please stop`). - - `chat.abort` از `{ sessionKey }` (بدون `runId`) پشتیبانی می‌کند تا همه اجراهای فعال آن نشست را لغو کند. + - وقتی یک اجرا فعال است، follow-upهای عادی در صف قرار می‌گیرند. روی **Steer** در یک پیام صف‌شده کلیک کنید تا آن follow-up به نوبت در حال اجرا تزریق شود. + - برای لغو خارج از باند، `/stop` را تایپ کنید (یا عبارت‌های لغو مستقل مثل `stop`، `stop action`، `stop run`، `stop openclaw`، `please stop`). + - `chat.abort` از `{ sessionKey }` (بدون `runId`) برای لغو همهٔ اجراهای فعال آن نشست پشتیبانی می‌کند. - + - وقتی یک اجرا لغو می‌شود، متن جزئی دستیار همچنان می‌تواند در UI نشان داده شود. - - Gateway وقتی خروجی بافرشده وجود داشته باشد، متن جزئی دستیار لغوشده را در تاریخچه رونوشت پایدار می‌کند. - - ورودی‌های پایدارشده شامل فراداده لغو هستند تا مصرف‌کنندگان رونوشت بتوانند بخش‌های جزئی لغو را از خروجی تکمیل عادی تشخیص دهند. + - Gateway متن جزئی لغوشدهٔ دستیار را وقتی خروجی bufferشده وجود داشته باشد در تاریخچهٔ رونوشت پایدار می‌کند. + - ورودی‌های پایدارشده شامل فرادادهٔ لغو هستند تا مصرف‌کنندگان رونوشت بتوانند جزئیات لغوشده را از خروجی تکمیل عادی تشخیص دهند. ## نصب PWA و Web Push -Control UI یک `manifest.webmanifest` و یک service worker ارائه می‌کند، بنابراین مرورگرهای مدرن می‌توانند آن را به‌عنوان یک PWA مستقل نصب کنند. Web Push به Gateway امکان می‌دهد PWA نصب‌شده را حتی وقتی تب یا پنجره مرورگر باز نیست، با اعلان‌ها بیدار کند. +Control UI یک `manifest.webmanifest` و یک service worker عرضه می‌کند، بنابراین مرورگرهای مدرن می‌توانند آن را به‌عنوان یک PWA مستقل نصب کنند. Web Push به Gateway اجازه می‌دهد حتی وقتی تب یا پنجرهٔ مرورگر باز نیست، PWA نصب‌شده را با اعلان‌ها بیدار کند. -| سطح | کاری که انجام می‌دهد | +| سطح | کاری که انجام می‌دهد | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | مانیفست PWA. مرورگرها وقتی قابل دسترسی شود، «نصب برنامه» را پیشنهاد می‌کنند. | +| `ui/public/manifest.webmanifest` | manifest مربوط به PWA. مرورگرها پس از قابل‌دسترس شدن آن، «Install app» را پیشنهاد می‌کنند. | | `ui/public/sw.js` | service worker که رویدادهای `push` و کلیک‌های اعلان را مدیریت می‌کند. | -| `push/vapid-keys.json` (در دایرکتوری وضعیت OpenClaw) | جفت‌کلید VAPID خودکار تولیدشده که برای امضای بارهای Web Push استفاده می‌شود. | -| `push/web-push-subscriptions.json` | endpointهای اشتراک مرورگر پایدارشده. | +| `push/vapid-keys.json` (زیر دایرکتوری state مربوط به OpenClaw) | جفت‌کلید VAPID تولیدشده به‌صورت خودکار که برای امضای payloadهای Web Push استفاده می‌شود. | +| `push/web-push-subscriptions.json` | endpointهای اشتراک مرورگرِ پایدارشده. | -وقتی می‌خواهید کلیدها را ثابت نگه دارید (برای استقرارهای چندمیزبانه، چرخش رازها، یا آزمایش‌ها)، جفت‌کلید VAPID را از طریق متغیرهای محیطی روی فرایند Gateway بازنویسی کنید: +وقتی می‌خواهید کلیدها را ثابت کنید (برای استقرارهای چندمیزبانه، چرخش secretها، یا تست‌ها)، جفت‌کلید VAPID را از طریق env varها روی پردازش Gateway override کنید: - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` -- `OPENCLAW_VAPID_SUBJECT` (پیش‌فرض `mailto:openclaw@localhost`) +- `OPENCLAW_VAPID_SUBJECT` (پیش‌فرض `mailto:openclaw@localhost` است) -Control UI از این روش‌های Gateway محدودشده با دامنه برای ثبت و آزمایش اشتراک‌های مرورگر استفاده می‌کند: +Control UI از این متدهای Gateway محدودشده با scope برای ثبت و تست اشتراک‌های مرورگر استفاده می‌کند: - `push.web.vapidPublicKey` — کلید عمومی VAPID فعال را دریافت می‌کند. - `push.web.subscribe` — یک `endpoint` را به‌همراه `keys.p256dh`/`keys.auth` ثبت می‌کند. - `push.web.unsubscribe` — یک endpoint ثبت‌شده را حذف می‌کند. -- `push.web.test` — یک اعلان آزمایشی به اشتراک فراخواننده می‌فرستد. +- `push.web.test` — یک اعلان تستی به اشتراک caller می‌فرستد. -Web Push مستقل از مسیر رله APNS در iOS است (برای push پشتیبانی‌شده با رله، [پیکربندی](/fa/gateway/configuration) را ببینید) و از روش موجود `push.test` که جفت‌سازی موبایل بومی را هدف می‌گیرد نیز مستقل است. +Web Push مستقل از مسیر relay مربوط به iOS APNS است (برای push مبتنی بر relay، [پیکربندی](/fa/gateway/configuration) را ببینید) و همچنین مستقل از متد موجود `push.test` است، که pairing موبایل بومی را هدف می‌گیرد. -## جاسازی‌های میزبانی‌شده +## embedهای میزبانی‌شده -پیام‌های دستیار می‌توانند محتوای وب میزبانی‌شده را به‌صورت درون‌خطی با shortcode `[embed ...]` رندر کنند. سیاست sandbox iframe با `gateway.controlUi.embedSandbox` کنترل می‌شود: +پیام‌های دستیار می‌توانند محتوای وب میزبانی‌شده را به‌صورت درون‌خطی با shortcode `[embed ...]` رندر کنند. سیاست sandbox مربوط به iframe توسط `gateway.controlUi.embedSandbox` کنترل می‌شود: - اجرای اسکریپت را داخل جاسازی‌های میزبانی‌شده غیرفعال می‌کند. + اجرای script را داخل embedهای میزبانی‌شده غیرفعال می‌کند. - - جاسازی‌های تعاملی را مجاز می‌کند و در عین حال جداسازی مبدا را حفظ می‌کند؛ این پیش‌فرض است و معمولاً برای بازی‌ها/ویجت‌های مرورگری خودبسنده کافی است. + + embedهای تعاملی را مجاز می‌کند و در عین حال جداسازی origin را حفظ می‌کند؛ این پیش‌فرض است و معمولاً برای بازی‌ها/widgetهای مرورگرِ خودبسنده کافی است. - برای سندهای هم‌سایتی که عمداً به امتیازهای قوی‌تر نیاز دارند، `allow-same-origin` را علاوه بر `allow-scripts` اضافه می‌کند. + برای سندهای همان‌سایت که عمداً به privilegeهای قوی‌تر نیاز دارند، `allow-same-origin` را روی `allow-scripts` اضافه می‌کند. @@ -250,14 +250,14 @@ Web Push مستقل از مسیر رله APNS در iOS است (برای push پ ``` -از `trusted` فقط زمانی استفاده کنید که سند جاسازی‌شده واقعاً به رفتار هم‌مبدا نیاز دارد. برای بیشتر بازی‌ها و canvasهای تعاملی تولیدشده توسط عامل، `scripts` گزینه امن‌تری است. +از `trusted` فقط زمانی استفاده کنید که سند embedشده واقعاً به رفتار same-origin نیاز داشته باشد. برای بیشتر بازی‌ها و canvasهای تعاملی تولیدشده توسط عامل، `scripts` گزینهٔ امن‌تری است. -URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فرض مسدود می‌مانند. اگر عمداً می‌خواهید `[embed url="https://..."]` صفحه‌های شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید. +URLهای embed خارجی مطلق `http(s)` به‌صورت پیش‌فرض مسدود می‌مانند. اگر عمداً می‌خواهید `[embed url="https://..."]` صفحه‌های شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید. -## پهنای پیام چت +## عرض پیام چت -پیام‌های چت گروه‌بندی‌شده از یک حداکثر پهنای پیش‌فرض خوانا استفاده می‌کنند. استقرارهای نمایشگر عریض می‌توانند بدون وصله کردن CSS همراه، آن را با تنظیم `gateway.controlUi.chatMessageMaxWidth` بازنویسی کنند: +پیام‌های چت گروه‌بندی‌شده از یک max-width پیش‌فرض خوانا استفاده می‌کنند. استقرارهای مانیتور عریض می‌توانند بدون وصله‌کردن CSS باندل‌شده، با تنظیم `gateway.controlUi.chatMessageMaxWidth` آن را override کنند: ```json5 { @@ -269,13 +269,13 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر } ``` -مقدار پیش از رسیدن به مرورگر اعتبارسنجی می‌شود. مقدارهای پشتیبانی‌شده شامل طول‌ها و درصدهای ساده مانند `960px` یا `82%`، به‌علاوه عبارت‌های پهنای محدودشده `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` است. +مقدار پیش از رسیدن به مرورگر اعتبارسنجی می‌شود. مقدارهای پشتیبانی‌شده شامل طول‌ها و درصدهای ساده مانند `960px` یا `82%`، به‌علاوهٔ عبارت‌های عرض محدودشدهٔ `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` هستند. -## دسترسی Tailnet (توصیه‌شده) +## دسترسی tailnet (پیشنهادی) - Gateway را روی loopback نگه دارید و اجازه دهید Tailscale Serve آن را با HTTPS پروکسی کند: + Gateway را روی local loopback نگه دارید و بگذارید Tailscale Serve آن را با HTTPS proxy کند: ```bash openclaw gateway --tailscale serve @@ -283,48 +283,48 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر باز کنید: - - `https:///` (یا `gateway.controlUi.basePath` پیکربندی‌شده شما) + - `https:///` (یا `gateway.controlUi.basePath` پیکربندی‌شدهٔ شما) - به‌طور پیش‌فرض، درخواست‌های Control UI/WebSocket Serve می‌توانند از طریق سرآیندهای هویت Tailscale (`tailscale-user-login`) احراز هویت کنند وقتی `gateway.auth.allowTailscale` برابر `true` باشد. OpenClaw هویت را با resolve کردن نشانی `x-forwarded-for` با `tailscale whois` و تطبیق آن با سرآیند راستی‌آزمایی می‌کند، و فقط وقتی این‌ها را می‌پذیرد که درخواست با سرآیندهای `x-forwarded-*` متعلق به Tailscale به loopback برسد. برای نشست‌های اپراتور Control UI با هویت دستگاه مرورگر، این مسیر Serve راستی‌آزمایی‌شده همچنین رفت‌وبرگشت جفت‌سازی دستگاه را رد می‌کند؛ مرورگرهای بدون دستگاه و اتصال‌های با نقش node همچنان بررسی‌های عادی دستگاه را دنبال می‌کنند. اگر می‌خواهید حتی برای ترافیک Serve هم اعتبارنامه‌های صریح راز مشترک را الزامی کنید، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید. + به‌صورت پیش‌فرض، درخواست‌های Control UI/WebSocket Serve می‌توانند وقتی `gateway.auth.allowTailscale` برابر `true` است از طریق headerهای هویت Tailscale (`tailscale-user-login`) احراز هویت کنند. OpenClaw هویت را با resolve کردن نشانی `x-forwarded-for` از طریق `tailscale whois` و تطبیق آن با header تأیید می‌کند، و فقط وقتی این‌ها را می‌پذیرد که درخواست با headerهای `x-forwarded-*` مربوط به Tailscale به local loopback برسد. برای نشست‌های operator در Control UI با هویت دستگاه مرورگر، این مسیر Serve تأییدشده همچنین رفت‌وبرگشت device-pairing را رد می‌کند؛ مرورگرهای بدون دستگاه و اتصال‌های با نقش node همچنان بررسی‌های معمول دستگاه را دنبال می‌کنند. اگر می‌خواهید حتی برای ترافیک Serve هم credentialهای shared-secret صریح لازم باشد، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید. - برای آن مسیر ناهمگام هویت Serve، تلاش‌های احراز هویت ناموفق برای همان IP کلاینت و دامنه احراز هویت، پیش از نوشتن‌های محدودسازی نرخ به‌صورت ترتیبی انجام می‌شوند. بنابراین تلاش‌های بد هم‌زمان از همان مرورگر می‌توانند روی درخواست دوم به‌جای دو عدم‌تطابق ساده که موازی رقابت کنند، `retry later` را نشان دهند. + برای آن مسیر async هویت Serve، تلاش‌های auth ناموفق برای همان IP کلاینت و scope احراز هویت پیش از نوشتن rate-limit سریال می‌شوند. بنابراین retryهای بد همزمان از همان مرورگر می‌توانند روی درخواست دوم به‌جای دو mismatch ساده که موازی رقابت می‌کنند، `retry later` را نشان دهند. - احراز هویت Serve بدون توکن فرض می‌کند میزبان gateway مورد اعتماد است. اگر کد محلی غیرقابل‌اعتماد ممکن است روی آن میزبان اجرا شود، احراز هویت token/password را الزامی کنید. + احراز هویت Serve بدون token فرض می‌کند میزبان gateway مورد اعتماد است. اگر کد محلی نامطمئن ممکن است روی آن میزبان اجرا شود، auth مبتنی بر token/password را الزامی کنید. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` سپس باز کنید: - - `http://:18789/` (یا `gateway.controlUi.basePath` پیکربندی‌شده شما) + - `http://:18789/` (یا `gateway.controlUi.basePath` پیکربندی‌شدهٔ شما) - راز مشترک متناظر را در تنظیمات UI جای‌گذاری کنید (به‌صورت `connect.params.auth.token` یا `connect.params.auth.password` ارسال می‌شود). + shared secret مطابق را در تنظیمات UI بچسبانید (به‌صورت `connect.params.auth.token` یا `connect.params.auth.password` ارسال می‌شود). ## HTTP ناامن -اگر داشبورد را از طریق HTTP ساده (`http://` یا `http://`) باز کنید، مرورگر در یک **زمینه ناامن** اجرا می‌شود و WebCrypto را مسدود می‌کند. به‌طور پیش‌فرض، OpenClaw اتصال‌های Control UI بدون هویت دستگاه را **مسدود** می‌کند. +اگر داشبورد را از طریق HTTP ساده باز کنید (`http://` یا `http://`)، مرورگر در یک **context غیرامن** اجرا می‌شود و WebCrypto را مسدود می‌کند. به‌صورت پیش‌فرض، OpenClaw اتصال‌های Control UI بدون هویت دستگاه را **مسدود** می‌کند. استثناهای مستندشده: - سازگاری HTTP ناامن فقط برای localhost با `gateway.controlUi.allowInsecureAuth=true` -- احراز هویت موفق اپراتور Control UI از طریق `gateway.auth.mode: "trusted-proxy"` -- حالت اضطراری `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- auth موفق operator در Control UI از طریق `gateway.auth.mode: "trusted-proxy"` +- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**راهکار پیشنهادی:** از HTTPS (Tailscale Serve) استفاده کنید یا رابط کاربری را به‌صورت محلی باز کنید: +**راه‌حل پیشنهادی:** از HTTPS (Tailscale Serve) استفاده کنید یا رابط کاربری را به‌صورت محلی باز کنید: - `https:///` (Serve) -- `http://127.0.0.1:18789/` (روی میزبان Gateway) +- `http://127.0.0.1:18789/` (روی میزبان gateway) - + ```json5 { gateway: { @@ -335,14 +335,14 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر } ``` - `allowInsecureAuth` فقط یک گزینهٔ سازگاری محلی است: + `allowInsecureAuth` فقط یک کلید سازگاری محلی است: - به نشست‌های localhost رابط کاربری کنترل اجازه می‌دهد در زمینه‌های HTTP غیرامن، بدون هویت دستگاه ادامه پیدا کنند. - بررسی‌های جفت‌سازی را دور نمی‌زند. - - الزامات هویت دستگاه راه دور (غیر از localhost) را کاهش نمی‌دهد. + - الزامات هویت دستگاه از راه دور (غیر از localhost) را آسان‌تر نمی‌کند. - + ```json5 { gateway: { @@ -354,42 +354,52 @@ URLهای جاسازی خارجی مطلق `http(s)` به‌طور پیش‌فر ``` - `dangerouslyDisableDeviceAuth` بررسی‌های هویت دستگاه در رابط کاربری کنترل را غیرفعال می‌کند و یک کاهش شدید امنیتی است. پس از استفادهٔ اضطراری، سریعاً آن را برگردانید. + `dangerouslyDisableDeviceAuth` بررسی‌های هویت دستگاه رابط کاربری کنترل را غیرفعال می‌کند و یک کاهش امنیتی شدید است. پس از استفاده اضطراری، سریع آن را برگردانید. - - - احراز هویت موفق trusted-proxy می‌تواند نشست‌های رابط کاربری کنترل **اپراتور** را بدون هویت دستگاه بپذیرد. - - این مورد به نشست‌های رابط کاربری کنترل با نقش node گسترش پیدا نمی‌کند. - - reverse proxyهای loopback روی همان میزبان همچنان احراز هویت trusted-proxy را برآورده نمی‌کنند؛ [احراز هویت پراکسی معتمد](/fa/gateway/trusted-proxy-auth) را ببینید. + + - احراز هویت موفق پروکسی مورد اعتماد می‌تواند نشست‌های رابط کاربری کنترل **اپراتور** را بدون هویت دستگاه بپذیرد. + - این موضوع به نشست‌های رابط کاربری کنترل با نقش node گسترش پیدا نمی‌کند. + - پروکسی‌های معکوس loopback روی همان میزبان همچنان احراز هویت پروکسی مورد اعتماد را برآورده نمی‌کنند؛ [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید. -برای راهنمایی تنظیم HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید. +برای راهنمایی راه‌اندازی HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید. ## سیاست امنیت محتوا -رابط کاربری کنترل با یک سیاست سخت‌گیرانهٔ `img-src` عرضه می‌شود: فقط دارایی‌های **هم‌مبدأ**، URLهای `data:` و URLهای `blob:` تولیدشده به‌صورت محلی مجاز هستند. URLهای تصویر راه دور `http(s)` و URLهای نسبیِ پروتکل توسط مرورگر رد می‌شوند و هیچ واکشی شبکه‌ای صادر نمی‌کنند. +رابط کاربری کنترل با سیاست سخت‌گیرانه `img-src` ارائه می‌شود: فقط دارایی‌های **هم‌مبدا**، URLهای `data:` و URLهای `blob:` تولیدشده به‌صورت محلی مجاز هستند. URLهای تصویر از راه دور `http(s)` و نسبی به پروتکل توسط مرورگر رد می‌شوند و درخواست شبکه‌ای ارسال نمی‌کنند. -معنای عملی این موضوع: +معنای عملی این رفتار: -- آواتارها و تصویرهایی که تحت مسیرهای نسبی ارائه می‌شوند (برای مثال `/avatars/`) همچنان رندر می‌شوند، از جمله مسیرهای آواتار احراز هویت‌شده که رابط کاربری آن‌ها را واکشی و به URLهای محلی `blob:` تبدیل می‌کند. -- URLهای درون‌خطی `data:image/...` همچنان رندر می‌شوند (برای payloadهای داخل پروتکل مفید است). -- URLهای محلی `blob:` که توسط رابط کاربری کنترل ساخته می‌شوند همچنان رندر می‌شوند. -- URLهای آواتار راه دور که توسط فرادادهٔ کانال منتشر می‌شوند، در helperهای آواتار رابط کاربری کنترل حذف و با لوگو/نشان داخلی جایگزین می‌شوند؛ بنابراین یک کانال compromiseشده یا مخرب نمی‌تواند مرورگر اپراتور را مجبور به واکشی دلخواه تصویر راه دور کند. +- آواتارها و تصویرهایی که زیر مسیرهای نسبی ارائه می‌شوند (برای مثال `/avatars/`) همچنان نمایش داده می‌شوند، از جمله مسیرهای آواتار احرازشده که رابط کاربری آن‌ها را دریافت می‌کند و به URLهای محلی `blob:` تبدیل می‌کند. +- URLهای درون‌خطی `data:image/...` همچنان نمایش داده می‌شوند (برای payloadهای درون پروتکل مفید است). +- URLهای محلی `blob:` که توسط رابط کاربری کنترل ساخته شده‌اند همچنان نمایش داده می‌شوند. +- URLهای آواتار از راه دور که توسط فراداده کانال صادر می‌شوند در helperهای آواتار رابط کاربری کنترل حذف و با لوگو/نشان داخلی جایگزین می‌شوند، بنابراین یک کانال به‌خطر‌افتاده یا مخرب نمی‌تواند مرورگر اپراتور را مجبور به دریافت تصویر دلخواه از راه دور کند. برای دریافت این رفتار لازم نیست چیزی را تغییر دهید — همیشه فعال است و قابل پیکربندی نیست. ## احراز هویت مسیر آواتار -وقتی احراز هویت Gateway پیکربندی شده باشد، endpoint آواتار رابط کاربری کنترل همان token Gateway را مثل بقیهٔ API لازم دارد: +وقتی احراز هویت Gateway پیکربندی شده باشد، endpoint آواتار رابط کاربری کنترل به همان توکن Gateway نیاز دارد که بقیه API استفاده می‌کند: -- `GET /avatar/` تصویر آواتار را فقط به فراخوان‌های احراز هویت‌شده برمی‌گرداند. `GET /avatar/?meta=1` فرادادهٔ آواتار را تحت همان قاعده برمی‌گرداند. -- درخواست‌های احراز هویت‌نشده به هرکدام از مسیرها رد می‌شوند (همسو با مسیر هم‌ردهٔ assistant-media). این کار از نشت هویت agent از مسیر آواتار روی میزبان‌هایی که در غیر این صورت محافظت شده‌اند جلوگیری می‌کند. -- خود رابط کاربری کنترل هنگام واکشی آواتارها token Gateway را به‌صورت header bearer ارسال می‌کند و از URLهای blob احراز هویت‌شده استفاده می‌کند تا تصویر همچنان در داشبوردها رندر شود. +- `GET /avatar/` تصویر آواتار را فقط به فراخواننده‌های احرازشده برمی‌گرداند. `GET /avatar/?meta=1` فراداده آواتار را با همان قاعده برمی‌گرداند. +- درخواست‌های احرازنشده به هرکدام از مسیرها رد می‌شوند (مطابق مسیر هم‌سطح assistant-media). این کار مانع می‌شود مسیر آواتار، هویت agent را روی میزبان‌هایی که در غیر این صورت محافظت شده‌اند، افشا کند. +- خود رابط کاربری کنترل هنگام دریافت آواتارها، توکن Gateway را به‌عنوان هدر bearer ارسال می‌کند و از URLهای blob احرازشده استفاده می‌کند تا تصویر همچنان در داشبوردها نمایش داده شود. -اگر احراز هویت Gateway را غیرفعال کنید (روی میزبان‌های اشتراکی توصیه نمی‌شود)، مسیر آواتار نیز همانند بقیهٔ Gateway بدون احراز هویت می‌شود. +اگر احراز هویت Gateway را غیرفعال کنید (روی میزبان‌های مشترک توصیه نمی‌شود)، مسیر آواتار نیز مطابق بقیه Gateway بدون احراز هویت می‌شود. + +## احراز هویت مسیر رسانه assistant + +وقتی احراز هویت Gateway پیکربندی شده باشد، پیش‌نمایش‌های رسانه محلی assistant از یک مسیر دومرحله‌ای استفاده می‌کنند: + +- `GET /__openclaw__/assistant-media?meta=1&source=` به احراز هویت عادی اپراتور رابط کاربری کنترل نیاز دارد. مرورگر هنگام بررسی دسترس‌پذیری، توکن Gateway را به‌عنوان هدر bearer ارسال می‌کند. +- پاسخ‌های فراداده موفق شامل یک `mediaTicket` کوتاه‌عمر هستند که فقط به همان مسیر منبع دقیق محدود شده است. +- URLهای تصویر، صدا، ویدئو و سند که در مرورگر نمایش داده می‌شوند، به‌جای توکن یا گذرواژه فعال Gateway از `mediaTicket=` استفاده می‌کنند. ticket به‌سرعت منقضی می‌شود و نمی‌تواند منبع دیگری را مجاز کند. + +این کار نمایش عادی رسانه را با عناصر رسانه بومی مرورگر سازگار نگه می‌دارد، بدون اینکه اعتبارنامه‌های قابل‌استفاده مجدد Gateway را در URLهای قابل‌مشاهده رسانه قرار دهد. ## ساخت رابط کاربری @@ -399,36 +409,36 @@ Gateway فایل‌های ایستا را از `dist/control-ui` ارائه می pnpm ui:build ``` -base مطلق اختیاری (وقتی URLهای ثابت دارایی می‌خواهید): +مبنای مطلق اختیاری (وقتی URLهای ثابت دارایی می‌خواهید): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` -برای توسعهٔ محلی (dev server جداگانه): +برای توسعه محلی (سرور توسعه جداگانه): ```bash pnpm ui:dev ``` -سپس رابط کاربری را به URL مربوط به Gateway WS خودتان اشاره دهید (مثلاً `ws://127.0.0.1:18789`). +سپس رابط کاربری را به URL WS مربوط به Gateway خود اشاره دهید (مثلاً `ws://127.0.0.1:18789`). -## اشکال‌زدایی/آزمایش: dev server + Gateway راه دور +## اشکال‌زدایی/آزمایش: سرور توسعه + Gateway راه دور -رابط کاربری کنترل فایل‌های ایستا است؛ هدف WebSocket قابل پیکربندی است و می‌تواند با مبدأ HTTP متفاوت باشد. این زمانی مفید است که dev server مربوط به Vite را به‌صورت محلی می‌خواهید اما Gateway جای دیگری اجرا می‌شود. +رابط کاربری کنترل فایل‌های ایستا است؛ هدف WebSocket قابل پیکربندی است و می‌تواند با مبدا HTTP متفاوت باشد. این برای زمانی مفید است که سرور توسعه Vite را به‌صورت محلی می‌خواهید اما Gateway جای دیگری اجرا می‌شود. - + ```bash pnpm ui:dev ``` - + ```text http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - احراز هویت یک‌بارهٔ اختیاری (در صورت نیاز): + احراز هویت یک‌باره اختیاری (در صورت نیاز): ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= @@ -438,18 +448,18 @@ pnpm ui:dev - + - `gatewayUrl` پس از بارگذاری در localStorage ذخیره و از URL حذف می‌شود. - - اگر یک endpoint کامل `ws://` یا `wss://` را از طریق `gatewayUrl` ارسال می‌کنید، مقدار `gatewayUrl` را URL-encode کنید تا مرورگر query string را درست parse کند. - - هر زمان ممکن است، `token` باید از طریق fragment URL (`#token=...`) ارسال شود. fragmentها به سرور ارسال نمی‌شوند و این کار از نشت در request-log و Referer جلوگیری می‌کند. پارامترهای query قدیمی `?token=` همچنان برای سازگاری یک‌بار import می‌شوند، اما فقط به‌عنوان fallback، و بلافاصله پس از bootstrap حذف می‌شوند. + - اگر یک endpoint کامل `ws://` یا `wss://` را از طریق `gatewayUrl` ارسال می‌کنید، مقدار `gatewayUrl` را URL-encode کنید تا مرورگر رشته query را درست تجزیه کند. + - هر زمان ممکن است، `token` باید از طریق fragment URL (`#token=...`) ارسال شود. fragmentها به سرور فرستاده نمی‌شوند و این از نشت در لاگ درخواست و Referer جلوگیری می‌کند. پارامترهای query قدیمی `?token=` همچنان برای سازگاری یک‌بار وارد می‌شوند، اما فقط به‌عنوان fallback، و بلافاصله پس از bootstrap حذف می‌شوند. - `password` فقط در حافظه نگه داشته می‌شود. - - وقتی `gatewayUrl` تنظیم شده باشد، رابط کاربری به credentialهای config یا environment fallback نمی‌کند. `token` (یا `password`) را صریحاً ارائه کنید. نبود credentialهای صریح یک خطا است. - - وقتی Gateway پشت TLS است (Tailscale Serve، پراکسی HTTPS، و غیره)، از `wss://` استفاده کنید. - - `gatewayUrl` فقط در یک پنجرهٔ سطح بالا پذیرفته می‌شود (نه embedded) تا از clickjacking جلوگیری شود. - - استقرارهای غیر loopback رابط کاربری کنترل باید `gateway.controlUi.allowedOrigins` را صریحاً تنظیم کنند (originهای کامل). این شامل setupهای dev راه دور هم می‌شود. - - راه‌اندازی Gateway ممکن است originهای محلی مانند `http://localhost:` و `http://127.0.0.1:` را از bind و port مؤثر زمان اجرا seed کند، اما originهای مرورگر راه دور همچنان به entryهای صریح نیاز دارند. - - از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید مگر برای آزمایش محلی کاملاً کنترل‌شده. این یعنی اجازه دادن به هر origin مرورگر، نه «مطابقت با هر میزبانی که استفاده می‌کنم.» - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت fallback مبدأ بر اساس Host-header را فعال می‌کند، اما این یک حالت امنیتی خطرناک است. + - وقتی `gatewayUrl` تنظیم شده باشد، رابط کاربری به اعتبارنامه‌های پیکربندی یا محیط fallback نمی‌کند. `token` (یا `password`) را صریح ارائه کنید. نبود اعتبارنامه صریح یک خطا است. + - وقتی Gateway پشت TLS است (Tailscale Serve، پروکسی HTTPS و غیره)، از `wss://` استفاده کنید. + - `gatewayUrl` فقط در یک پنجره سطح بالا پذیرفته می‌شود (نه به‌صورت embedded) تا از clickjacking جلوگیری شود. + - استقرارهای رابط کاربری کنترل غیر loopback باید `gateway.controlUi.allowedOrigins` را به‌صورت صریح تنظیم کنند (originهای کامل). این شامل راه‌اندازی‌های توسعه از راه دور هم می‌شود. + - راه‌اندازی Gateway ممکن است originهای محلی مانند `http://localhost:` و `http://127.0.0.1:` را از bind و پورت موثر runtime seed کند، اما originهای مرورگر راه دور همچنان به ورودی‌های صریح نیاز دارند. + - جز برای آزمایش محلی کاملاً کنترل‌شده، از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید. این یعنی اجازه دادن به هر origin مرورگر، نه «مطابقت با هر میزبانی که استفاده می‌کنم». + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت fallback مبدا بر اساس هدر Host را فعال می‌کند، اما این یک حالت امنیتی خطرناک است. @@ -466,11 +476,11 @@ pnpm ui:dev } ``` -جزئیات setup دسترسی راه دور: [دسترسی راه دور](/fa/gateway/remote). +جزئیات راه‌اندازی دسترسی از راه دور: [دسترسی از راه دور](/fa/gateway/remote). ## مرتبط -- [داشبورد](/fa/web/dashboard) — داشبورد Gateway -- [بررسی‌های سلامت](/fa/gateway/health) — پایش سلامت Gateway -- [TUI](/fa/web/tui) — رابط کاربری ترمینال +- [داشبورد](/fa/web/dashboard) — داشبورد gateway +- [بررسی‌های سلامت](/fa/gateway/health) — پایش سلامت gateway +- [TUI](/fa/web/tui) — رابط کاربری terminal - [WebChat](/fa/web/webchat) — رابط چت مبتنی بر مرورگر